Method requestWithMeta

src/lib/http.ts:407–610

(
    method: string,
    path: string,
    options: RequestOptions = {},
  )

  }

  async requestWithMeta<T>(
    method: string,
    path: string,
    options: RequestOptions = {},
  ): Promise<RequestResult<T>> {
    if (!this.apiKey) throw ApiError.authRequired();

    const url = buildUrl(this.baseUrl, path, options.query);
    const requestId = options.requestId ?? newRequestId();

    let attempt = 0;
    while (true) {
      attempt += 1;
      this.debug({ kind: 'request', method, url, attempt, requestId });
      const startedAt = Date.now();
      let response: Response;

      // Compose the per-request timeout signal with any caller-supplied signal.
      // The fetch aborts on whichever fires first. This ensures every one-shot
      // request (test create/update/delete/list/get, auth whoami, code put/get,
      // plan put) has a client-side deadline even when the caller supplies no
      // signal. The polling path supplies its own deadline-aware signal per
      // iteration — this timeout (120s default) is safely larger than any single
      // long-poll window (<=25s via ?waitSeconds), so it never bites polling.
      const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
      const effectiveSignal =
        options.signal != null ? AbortSignal.any([timeoutSignal, options.signal]) : timeoutSignal;

      try {
        response = await this.fetchImpl(url, {
          method,
          headers: this.buildHeaders(requestId, options),
          body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
          signal: effectiveSignal,
        });
      } catch (err) {
        // Distinguish a client-side request timeout from a caller-supplied abort.
        //
        // Node 22 `AbortSignal.timeout()` throws a `DOMException` with
        // `name === 'TimeoutError'` (not 'AbortError') when the signal fires.
        // A caller-supplied abort sets `name === 'AbortError'`.
        // We treat both abort variants together: if the timeout signal fired and
        // the caller hadn't already aborted, surface a clear RequestTimeoutError.
        // A timeout/abort during the fetch itself: classify it (RequestTimeoutError
        // when our deadline fired; otherwise rethrow the caller's abort unmodified).
        this.rethrowIfAbort(err, timeoutSignal, options.signal, requestId);
        // If a RequestTimeoutError already propagated from somewhere (e.g. from a
        // nested call or from a test-injected fetchImpl), pass it through unchanged
        // rather than re-wrapping it as a TransportError.
        if (err instanceof RequestTimeoutError) throw err;
        const message = err instanceof Error ? err.message : String(err);
        this.debug({
          kind: 'error',
          method,
          url,
          attempt,
          requestId,
          errorCode: 'TRANSPORT',