nxus-qbd 0.8.0 → 1.0.0

package/dist/transport.js

@@ -4,11 +4,25 @@
  * Handles authentication, base URL resolution, JSON serialization,
  * and error mapping for all SDK requests.
  */
-import { NxusApiError } from './helpers/errors';
+import { NxusApiError } from "./helpers/errors.js";
 export const DEFAULT_TIMEOUT_MS = 100_000;
 export const DEFAULT_MAX_RETRIES = 2;
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_DELAY_MS = 8_000;
+/**
+ * Ceiling on how long a server-supplied `Retry-After` will be honoured.
+ *
+ * Separate from RETRY_MAX_DELAY_MS, which bounds our own exponential backoff.
+ * Clamping the server's value to the backoff cap was actively harmful: on
+ * `Retry-After: 60` the SDK slept 8s, retried into a window still in force,
+ * and repeated until the budget was gone — every attempt guaranteed to fail.
+ *
+ * Beyond this ceiling the SDK does not sleep and does not spend an attempt; it
+ * returns the error with `retryAfter` intact so the caller can schedule the
+ * wait itself. Blocking a process for an unbounded server value is not the
+ * SDK's decision to make.
+ */
+const RETRY_AFTER_MAX_MS = 60_000;
 // 409 is intentionally omitted: the backend overloads it for both retryable
 // lock contention (`ObjectInUse`, `LockFailed`) and terminal business-rule
 // violations (`OutdatedEditSequence`, `NameNotUnique`, `TimeCreationMismatch`).
@@ -16,13 +30,13 @@ const RETRY_MAX_DELAY_MS = 8_000;
 // attempts on errors that need client-side action. Servers that emit the
 // header (`x-should-retry: true`) override this fallback and opt 409s in.
 const RETRYABLE_STATUSES = new Set([408, 429]);
-const REDACTED = '[REDACTED]';
+const REDACTED = "[REDACTED]";
 const SENSITIVE_HEADER_NAMES = new Set([
-    'authorization',
-    'proxy-authorization',
-    'x-api-key',
-    'cookie',
-    'set-cookie',
+    "authorization",
+    "proxy-authorization",
+    "x-api-key",
+    "cookie",
+    "set-cookie",
 ]);
 function redactHeaders(headers) {
     const out = {};
@@ -34,12 +48,43 @@ function redactHeaders(headers) {
 function defaultLogger() {
     // Bind to console so callers can swap the logger without losing context.
     return {
-        debug: (m, c) => console.debug(`[nxus-qbd] ${m}`, c ?? ''),
-        info: (m, c) => console.info(`[nxus-qbd] ${m}`, c ?? ''),
-        warn: (m, c) => console.warn(`[nxus-qbd] ${m}`, c ?? ''),
-        error: (m, c) => console.error(`[nxus-qbd] ${m}`, c ?? ''),
+        debug: (m, c) => console.debug(`[nxus-qbd] ${m}`, c ?? ""),
+        info: (m, c) => console.info(`[nxus-qbd] ${m}`, c ?? ""),
+        warn: (m, c) => console.warn(`[nxus-qbd] ${m}`, c ?? ""),
+        error: (m, c) => console.error(`[nxus-qbd] ${m}`, c ?? ""),
     };
 }
+function hasHeader(headers, name) {
+    return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());
+}
+function setHeader(headers, name, value) {
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === name.toLowerCase() && key !== name) {
+            delete headers[key];
+        }
+    }
+    headers[name] = value;
+}
+/** Resolve case-insensitive duplicates after all header sources are merged. */
+function canonicalizeHeader(headers, canonicalName) {
+    const matching = Object.entries(headers).filter(([name]) => name.toLowerCase() === canonicalName.toLowerCase());
+    const value = matching.at(-1)?.[1];
+    if (value !== undefined) {
+        setHeader(headers, canonicalName, value);
+    }
+}
+const RETRY_IDEMPOTENT_CREATE_TIMEOUT = Symbol("retryIdempotentCreateTimeout");
+/** @internal Marks only SDK-owned generic Create options as timeout-retryable. */
+export function enableIdempotentCreateTimeoutRetry(options) {
+    Object.defineProperty(options, RETRY_IDEMPOTENT_CREATE_TIMEOUT, {
+        value: true,
+    });
+    return options;
+}
+function retriesIdempotentCreateTimeout(options) {
+    return Boolean(options &&
+        options[RETRY_IDEMPOTENT_CREATE_TIMEOUT]);
+}
 function normalizeErrorPayload(errorBody, response) {
     if (errorBody == null) {
         return {
@@ -47,28 +92,108 @@ function normalizeErrorPayload(errorBody, response) {
             message: response.statusText,
         };
     }
-    if (typeof errorBody !== 'object') {
+    if (typeof errorBody !== "object") {
         return errorBody;
     }
-    const normalized = { ...errorBody };
+    const source = errorBody;
+    const nestedEnvelope = asRecord(source.nxusApiError) ?? asRecord(source.qbdApiError);
+    const normalized = {
+        ...(nestedEnvelope ?? source),
+    };
+    if (nestedEnvelope) {
+        if (normalized.requestId == null && source.requestId != null) {
+            normalized.requestId = source.requestId;
+        }
+        if (normalized.status == null && source.status != null) {
+            normalized.status = source.status;
+        }
+        if (normalized.statusCode == null && source.statusCode != null) {
+            normalized.statusCode = source.statusCode;
+        }
+        if (normalized.retryAfter == null && source.retryAfter != null) {
+            normalized.retryAfter = source.retryAfter;
+        }
+        if (normalized.restriction == null && source.restriction != null) {
+            normalized.restriction = source.restriction;
+        }
+        if (normalized.billing == null && source.billing != null) {
+            normalized.billing = source.billing;
+        }
+        if (normalized.lifecycleState == null && source.lifecycleState != null) {
+            normalized.lifecycleState = source.lifecycleState;
+        }
+        if (normalized.restrictionReason == null &&
+            source.restrictionReason != null) {
+            normalized.restrictionReason = source.restrictionReason;
+        }
+        if (normalized.restrictionCode == null && source.restrictionCode != null) {
+            normalized.restrictionCode = source.restrictionCode;
+        }
+        if (normalized.requiresPayment == null && source.requiresPayment != null) {
+            normalized.requiresPayment = source.requiresPayment;
+        }
+        if (normalized.checkoutUrl == null && source.checkoutUrl != null) {
+            normalized.checkoutUrl = source.checkoutUrl;
+        }
+    }
     if (normalized.status == null) {
         normalized.status = response.status;
     }
-    const nestedError = normalized.error;
-    if (nestedError && typeof nestedError === 'object') {
+    if (normalized.httpStatusCode == null) {
+        normalized.httpStatusCode = response.status;
+    }
+    if (normalized.retryAfter == null) {
+        const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+        if (retryAfterMs != null) {
+            normalized.retryAfter = retryAfterMs / 1_000;
+        }
+    }
+    // Bodies that carry no request id still get one from the header, so
+    // `err.requestId` is usable for support regardless of the error shape.
+    if (normalized.requestId == null) {
+        const headerRequestId = response.headers.get("x-request-id");
+        if (headerRequestId) {
+            normalized.requestId = headerRequestId;
+        }
+    }
+    const normalizedError = normalized.error;
+    if (normalizedError && typeof normalizedError === "object") {
         normalized.error = {
-            ...nestedError,
-            httpStatusCode: nestedError.httpStatusCode ?? response.status,
+            ...normalizedError,
+            httpStatusCode: normalizedError.httpStatusCode ??
+                response.status,
         };
     }
     return normalized;
 }
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : undefined;
+}
+function extractLogicalErrorPayload(body) {
+    const record = asRecord(body);
+    if (!record) {
+        return undefined;
+    }
+    if (record.success === false) {
+        return body;
+    }
+    if (asRecord(record.nxusApiError) || asRecord(record.qbdApiError)) {
+        return body;
+    }
+    if (String(record.status).toLowerCase() === "failed") {
+        return body;
+    }
+    return undefined;
+}
 // ---------------------------------------------------------------------------
 // Transport
 // ---------------------------------------------------------------------------
 export class NxusHttpTransport {
     baseUrl;
     apiKey;
+    defaultConnectionId;
     defaultHeaders;
     defaultTimeout;
     defaultServerTimeoutSeconds;
@@ -81,8 +206,9 @@ export class NxusHttpTransport {
     dispatcherPromise;
     constructor(options) {
         // Ensure trailing slash for consistent URL joining
-        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
         this.apiKey = options.apiKey;
+        this.defaultConnectionId = options.connectionId;
         this.defaultHeaders = options.headers ?? {};
         this.defaultTimeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
         this.defaultServerTimeoutSeconds = options.serverTimeoutSeconds;
@@ -93,35 +219,76 @@ export class NxusHttpTransport {
         this.fetchOptions = options.fetchOptions ?? {};
     }
     async get(path, query, options) {
-        const url = this.buildUrl(path, query);
-        return this.request(url, { method: 'GET' }, options);
+        return (await this.sendGet(path, query, options)).body;
     }
     async post(path, body, options) {
+        return (await this.sendPost(path, body, options)).body;
+    }
+    async delete(path, options) {
+        return (await this.sendDelete(path, options)).body;
+    }
+    /** @internal */
+    async deleteWithBody(path, body, options) {
+        return (await this.sendDeleteWithBody(path, body, options)).body;
+    }
+    /**
+     * Snapshot-returning counterparts of `get`/`post`/`delete`.
+     *
+     * These are the real implementations; the three above are thin wrappers that
+     * discard the metadata. Both paths therefore share one retry loop, one error
+     * translation, and one parse — metadata-aware calls cannot drift from plain
+     * ones.
+     *
+     * @internal
+     */
+    async sendGet(path, query, options) {
+        const url = this.buildUrl(path, query);
+        return this.request(url, { method: "GET" }, options);
+    }
+    /** @internal */
+    async sendPost(path, body, options) {
         const url = this.buildUrl(path);
         return this.request(url, {
-            method: 'POST',
+            method: "POST",
             body: body != null ? JSON.stringify(body) : undefined,
         }, options);
     }
-    async delete(path, options) {
+    /** @internal */
+    async sendDelete(path, options) {
         const url = this.buildUrl(path);
-        return this.request(url, { method: 'DELETE' }, options);
+        return this.request(url, { method: "DELETE" }, options);
+    }
+    /** @internal */
+    async sendDeleteWithBody(path, body, options) {
+        const url = this.buildUrl(path);
+        return this.request(url, {
+            method: "DELETE",
+            body: JSON.stringify(body),
+        }, options);
     }
     /**
      * Issue a raw HTTP request and return the unparsed `Response`.
      *
-     * Use this when you need direct access to status, headers, or the response
-     * body as a stream/blob/text. Bypasses JSON parsing and the typed error
-     * mapping, but still applies authentication, the default headers, the
-     * timeout, and retries. Non-2xx responses are returned, not thrown — the
-     * caller is responsible for `response.ok` handling.
+     * Gives direct access to status, headers, and the response body as a
+     * stream/blob/text. Bypasses JSON parsing and the typed error mapping, but
+     * still applies authentication, the default headers, the timeout, and
+     * retries. Non-2xx responses are returned, not thrown — the caller is
+     * responsible for `response.ok` handling.
+     *
+     * **SDK-internal.** `NxusClient.transport` is private, so this is not
+     * reachable from consumer code. The previous `@example` here showed
+     * `client.transport.raw(...)`, which does not compile. Consumers needing
+     * status/headers/request-id should not reach for the transport — that is
+     * what the planned public response wrapper is for.
      *
      * @example
      * ```ts
-     * const res = await client.transport.raw('/api/v1/vendors', { method: 'GET' });
-     * console.log(res.status, res.headers.get('x-request-id'));
-     * const blob = await res.blob();
+     * // Internal use only — see resources/custom-fields.ts `deleteWithBody`,
+     * // which needs a JSON body on DELETE and maps non-2xx onto NxusApiError.
+     * const res = await this.transport.raw(path, { method: 'DELETE', body });
      * ```
+     *
+     * @internal
      */
     async raw(path, init = {}, options) {
         const { query, ...rest } = init;
@@ -132,10 +299,10 @@ export class NxusHttpTransport {
     // Internal
     // -------------------------------------------------------------------------
     buildUrl(path, query) {
-        const url = new URL(path, this.baseUrl + '/');
+        const url = new URL(path, this.baseUrl + "/");
         // The URL constructor resolves relative to base — if path starts with /
         // we need to set it directly
-        if (path.startsWith('/')) {
+        if (path.startsWith("/")) {
             url.pathname = path;
         }
         if (query) {
@@ -164,11 +331,17 @@ export class NxusHttpTransport {
         const timeout = options?.timeout ?? this.defaultTimeout;
         const maxRetries = Math.max(0, options?.maxRetries ?? this.defaultMaxRetries);
         const verbose = options?.verbose ?? this.verbose;
-        const extraFetchOptions = { ...this.fetchOptions, ...(options?.fetchOptions ?? {}) };
+        const extraFetchOptions = {
+            ...this.fetchOptions,
+            ...(options?.fetchOptions ?? {}),
+        };
+        // Read here as well as inside the attempt, so a cancellation lands during
+        // the backoff wait rather than only at the next dispatch.
+        const { callerSignal } = extractCallerSignal(extraFetchOptions);
         let attempt = 0;
         while (true) {
             if (verbose) {
-                this.logger.debug('request', {
+                this.logger.debug("request", {
                     method: init.method,
                     url,
                     headers: redactHeaders(headers),
@@ -176,20 +349,26 @@ export class NxusHttpTransport {
                     maxRetries,
                 });
             }
-            const outcome = await this.attempt(url, init, headers, timeout, extraFetchOptions);
+            const outcome = await this.attempt(url, init, headers, timeout, extraFetchOptions, options?.includeRawBody ?? false);
             if (verbose) {
                 this.logOutcome(outcome, { method: init.method, url, attempt });
             }
-            if (outcome.kind === 'success') {
+            if (outcome.kind === "success") {
                 return outcome.value;
             }
+            // Rethrow the caller's own abort reason rather than wrapping it. A
+            // consumer racing an AbortController checks `err.name === "AbortError"`;
+            // an NxusApiError here would read as a request failure instead.
+            if (outcome.kind === "canceled") {
+                throw outcome.reason;
+            }
             if (attempt >= maxRetries ||
-                !shouldRetry(outcome)) {
+                !shouldRetry(outcome, retriesIdempotentCreateTimeout(options))) {
                 throw outcome.error;
             }
             const delayMs = computeRetryDelay(attempt, outcome);
             if (verbose) {
-                this.logger.debug('retry-scheduled', {
+                this.logger.debug("retry-scheduled", {
                     url,
                     attempt: attempt + 1,
                     delayMs,
@@ -197,7 +376,7 @@ export class NxusHttpTransport {
             }
             attempt += 1;
             if (delayMs > 0) {
-                await sleep(delayMs);
+                await sleep(delayMs, callerSignal);
             }
         }
     }
@@ -206,12 +385,18 @@ export class NxusHttpTransport {
         const timeout = options?.timeout ?? this.defaultTimeout;
         const maxRetries = Math.max(0, options?.maxRetries ?? this.defaultMaxRetries);
         const verbose = options?.verbose ?? this.verbose;
-        const extraFetchOptions = { ...this.fetchOptions, ...(options?.fetchOptions ?? {}) };
+        const extraFetchOptions = {
+            ...this.fetchOptions,
+            ...(options?.fetchOptions ?? {}),
+        };
+        // Read here as well as inside the attempt, so a cancellation lands during
+        // the backoff wait rather than only at the next dispatch.
+        const { callerSignal } = extractCallerSignal(extraFetchOptions);
         let attempt = 0;
         while (true) {
             if (verbose) {
-                this.logger.debug('request', {
-                    method: init.method ?? 'GET',
+                this.logger.debug("request", {
+                    method: init.method ?? "GET",
                     url,
                     headers: redactHeaders(headers),
                     attempt,
@@ -221,22 +406,30 @@ export class NxusHttpTransport {
             }
             const outcome = await this.attemptRaw(url, init, headers, timeout, extraFetchOptions);
             if (verbose) {
-                this.logRawOutcome(outcome, { method: init.method ?? 'GET', url, attempt });
+                this.logRawOutcome(outcome, {
+                    method: init.method ?? "GET",
+                    url,
+                    attempt,
+                });
             }
-            if (outcome.kind === 'response') {
+            if (outcome.kind === "response") {
                 return outcome.response;
             }
-            if (attempt >= maxRetries || !shouldRetry(outcome)) {
+            if (outcome.kind === "canceled") {
+                throw outcome.reason;
+            }
+            if (attempt >= maxRetries ||
+                !shouldRetry(outcome, retriesIdempotentCreateTimeout(options))) {
                 // Non-2xx that we won't retry: return the Response so the caller can
                 // inspect status/headers/body, matching the documented contract.
-                if (outcome.kind === 'http-error') {
+                if (outcome.kind === "http-error") {
                     return outcome.response;
                 }
                 throw outcome.error;
             }
             const delayMs = computeRetryDelay(attempt, outcome);
             if (verbose) {
-                this.logger.debug('retry-scheduled', {
+                this.logger.debug("retry-scheduled", {
                     url,
                     attempt: attempt + 1,
                     delayMs,
@@ -244,24 +437,32 @@ export class NxusHttpTransport {
             }
             attempt += 1;
             if (delayMs > 0) {
-                await sleep(delayMs);
+                await sleep(delayMs, callerSignal);
             }
         }
     }
     buildHeaders(options) {
         const headers = {
-            'Content-Type': 'application/json',
+            "Content-Type": "application/json",
             Authorization: `Bearer ${this.apiKey}`,
             ...this.defaultHeaders,
             ...options?.headers,
         };
-        if (options?.connectionId) {
-            headers['X-Connection-Id'] = options.connectionId;
+        if (options?.connectionId !== undefined) {
+            setHeader(headers, "X-Connection-Id", options.connectionId);
         }
-        const serverTimeoutSeconds = options?.serverTimeoutSeconds ?? this.defaultServerTimeoutSeconds;
-        if (serverTimeoutSeconds != null && !('X-Nxus-Timeout-Seconds' in headers)) {
-            headers['X-Nxus-Timeout-Seconds'] = String(serverTimeoutSeconds);
+        else if (this.defaultConnectionId != null &&
+            !hasHeader(headers, "X-Connection-Id")) {
+            setHeader(headers, "X-Connection-Id", this.defaultConnectionId);
         }
+        if (options?.serverTimeoutSeconds !== undefined) {
+            setHeader(headers, "X-Nxus-Timeout-Seconds", String(options.serverTimeoutSeconds));
+        }
+        else if (this.defaultServerTimeoutSeconds != null &&
+            !hasHeader(headers, "X-Nxus-Timeout-Seconds")) {
+            setHeader(headers, "X-Nxus-Timeout-Seconds", String(this.defaultServerTimeoutSeconds));
+        }
+        canonicalizeHeader(headers, "Idempotency-Key");
         return headers;
     }
     async resolveDispatcher() {
@@ -274,15 +475,16 @@ export class NxusHttpTransport {
                 // handling without throwing.
                 try {
                     // @ts-expect-error - undici is an optional runtime peer
-                    const mod = await import('undici');
-                    const Agent = mod.ProxyAgent;
+                    const mod = await import("undici");
+                    const Agent = mod
+                        .ProxyAgent;
                     if (!Agent)
                         return undefined;
                     return new Agent(this.proxyUrl);
                 }
                 catch (err) {
                     if (this.verbose) {
-                        this.logger.warn('proxy-agent-unavailable', {
+                        this.logger.warn("proxy-agent-unavailable", {
                             proxy: this.proxyUrl,
                             reason: err instanceof Error ? err.message : String(err),
                         });
@@ -294,6 +496,11 @@ export class NxusHttpTransport {
         return this.dispatcherPromise;
     }
     async resolveFetchInit(init, headers, signal, extraFetchOptions) {
+        // `signal` is placed last on purpose, and `extraFetchOptions` must already
+        // have had the caller's own signal removed by extractCallerSignal — the
+        // combined signal passed in here is what represents both. Leaving a raw
+        // caller signal in extraFetchOptions would let this spread drop the
+        // timeout instead, which is the same bug in the other direction.
         const merged = {
             ...extraFetchOptions,
             ...init,
@@ -315,22 +522,25 @@ export class NxusHttpTransport {
     }
     logOutcome(outcome, ctx) {
         switch (outcome.kind) {
-            case 'success':
-                this.logger.debug('response', { ...ctx, ok: true });
+            case "success":
+                this.logger.debug("response", { ...ctx, ok: true });
                 return;
-            case 'http-error':
-                this.logger.warn('response', {
+            case "http-error":
+                this.logger.warn("response", {
                     ...ctx,
                     status: outcome.status,
                     retryAfter: outcome.retryAfter,
                     shouldRetry: outcome.shouldRetry,
                 });
                 return;
-            case 'timeout':
-                this.logger.warn('timeout', ctx);
+            case "timeout":
+                this.logger.warn("timeout", ctx);
                 return;
-            case 'network-error':
-                this.logger.warn('network-error', {
+            case "canceled":
+                this.logger.debug("canceled", ctx);
+                return;
+            case "network-error":
+                this.logger.warn("network-error", {
                     ...ctx,
                     reason: outcome.error.message,
                 });
@@ -339,15 +549,15 @@ export class NxusHttpTransport {
     }
     logRawOutcome(outcome, ctx) {
         switch (outcome.kind) {
-            case 'response':
-                this.logger.debug('response', {
+            case "response":
+                this.logger.debug("response", {
                     ...ctx,
                     status: outcome.response.status,
                     raw: true,
                 });
                 return;
-            case 'http-error':
-                this.logger.warn('response', {
+            case "http-error":
+                this.logger.warn("response", {
                     ...ctx,
                     status: outcome.status,
                     retryAfter: outcome.retryAfter,
@@ -355,22 +565,33 @@ export class NxusHttpTransport {
                     raw: true,
                 });
                 return;
-            case 'timeout':
-                this.logger.warn('timeout', ctx);
+            case "timeout":
+                this.logger.warn("timeout", ctx);
+                return;
+            case "canceled":
+                this.logger.debug("canceled", ctx);
                 return;
-            case 'network-error':
-                this.logger.warn('network-error', {
+            case "network-error":
+                this.logger.warn("network-error", {
                     ...ctx,
                     reason: outcome.error.message,
                 });
                 return;
         }
     }
-    async attempt(url, init, headers, timeout, extraFetchOptions) {
+    async attempt(url, init, headers, timeout, extraFetchOptions, includeRawBody = false) {
+        const { callerSignal, rest } = extractCallerSignal(extraFetchOptions);
+        // Bail before dispatching. A caller who aborted before the call was made
+        // still had the request sent and the response returned, because the
+        // caller's signal never reached fetch at all.
+        if (callerSignal?.aborted) {
+            return { kind: "canceled", reason: callerSignal.reason };
+        }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeout);
+        const composed = combineAbortSignals(callerSignal, controller.signal);
         try {
-            const fetchInit = await this.resolveFetchInit(init, headers, controller.signal, extraFetchOptions);
+            const fetchInit = await this.resolveFetchInit(init, headers, composed.signal, rest);
             const response = await fetch(url, fetchInit);
             if (!response.ok) {
                 let errorBody;
@@ -385,42 +606,78 @@ export class NxusHttpTransport {
                 // body's `error.retryAfter` (seconds, integer) when the header is
                 // missing. This keeps behavior correct against proxies that strip
                 // hop-by-hop headers but preserve the body.
-                const retryAfter = parseRetryAfter(response.headers.get('retry-after')) ??
+                const retryAfter = parseRetryAfter(response.headers.get("retry-after")) ??
                     parseBodyRetryAfter(errorBody);
                 return {
-                    kind: 'http-error',
+                    kind: "http-error",
                     status: response.status,
                     retryAfter,
-                    shouldRetry: parseShouldRetry(response.headers.get('x-should-retry')),
+                    shouldRetry: parseShouldRetry(response.headers.get("x-should-retry")),
                     error,
                 };
             }
             // 204 No Content
             if (response.status === 204) {
-                return { kind: 'success', value: undefined };
+                return {
+                    kind: "success",
+                    value: snapshot(response, undefined, undefined, includeRawBody),
+                };
             }
             const text = await response.text();
             if (!text) {
-                return { kind: 'success', value: undefined };
+                return {
+                    kind: "success",
+                    value: snapshot(response, undefined, "", includeRawBody),
+                };
+            }
+            const parsed = JSON.parse(text);
+            const logicalErrorPayload = extractLogicalErrorPayload(parsed);
+            if (logicalErrorPayload !== undefined) {
+                const normalizedError = normalizeErrorPayload(logicalErrorPayload, response);
+                return {
+                    kind: "http-error",
+                    status: typeof asRecord(normalizedError)?.status === "number"
+                        ? asRecord(normalizedError)?.status
+                        : response.status,
+                    retryAfter: parseBodyRetryAfter(normalizedError),
+                    shouldRetry: parseShouldRetry(response.headers.get("x-should-retry")),
+                    error: NxusApiError.from(normalizedError),
+                };
             }
-            return { kind: 'success', value: JSON.parse(text) };
+            return {
+                kind: "success",
+                value: snapshot(response, parsed, text, includeRawBody),
+            };
         }
         catch (error) {
-            if (error instanceof DOMException && error.name === 'AbortError') {
+            // The caller's signal is checked FIRST, and independently of what was
+            // thrown. fetch rejects with the signal's abort reason verbatim, and
+            // `controller.abort(new Error("deployment shutdown"))` produces a plain
+            // Error whose name is "Error" — so keying off the thrown value's name
+            // classified a real cancellation as a network failure and retried it.
+            // Whether the caller aborted is a fact about the signal, not about the
+            // shape of the rejection.
+            if (callerSignal?.aborted) {
+                return { kind: "canceled", reason: callerSignal.reason };
+            }
+            if (isAbortError(error)) {
+                // Not the caller, so this is our own timeout controller firing. The
+                // two mean opposite things: a timeout leaves the outcome unknown and
+                // may deserve a retry, a cancellation is an instruction to stop.
                 return {
-                    kind: 'timeout',
+                    kind: "timeout",
                     error: new NxusApiError({
                         message: `Request timed out after ${timeout}ms`,
-                        userMessage: 'The request timed out. Please try again.',
+                        userMessage: "The request timed out. Please try again.",
                         status: 0,
                     }),
                 };
             }
             return {
-                kind: 'network-error',
+                kind: "network-error",
                 error: new NxusApiError({
-                    message: error instanceof Error ? error.message : 'Network request failed',
-                    userMessage: 'A network error occurred. Please check your connection and try again.',
+                    message: error instanceof Error ? error.message : "Network request failed",
+                    userMessage: "A network error occurred. Please check your connection and try again.",
                     status: 0,
                     raw: error,
                 }),
@@ -428,44 +685,54 @@ export class NxusHttpTransport {
         }
         finally {
             clearTimeout(timer);
+            composed.dispose();
         }
     }
     async attemptRaw(url, init, headers, timeout, extraFetchOptions) {
+        const { callerSignal, rest } = extractCallerSignal(extraFetchOptions);
+        if (callerSignal?.aborted) {
+            return { kind: "canceled", reason: callerSignal.reason };
+        }
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeout);
+        const composed = combineAbortSignals(callerSignal, controller.signal);
         try {
-            const fetchInit = await this.resolveFetchInit(init, headers, controller.signal, extraFetchOptions);
+            const fetchInit = await this.resolveFetchInit(init, headers, composed.signal, rest);
             const response = await fetch(url, fetchInit);
             if (!response.ok) {
                 // Classify retryable failures by status + headers only — never read
                 // the body, since the caller owns the stream.
-                const retryAfter = parseRetryAfter(response.headers.get('retry-after')) ?? undefined;
+                const retryAfter = parseRetryAfter(response.headers.get("retry-after")) ?? undefined;
                 return {
-                    kind: 'http-error',
+                    kind: "http-error",
                     status: response.status,
                     retryAfter,
-                    shouldRetry: parseShouldRetry(response.headers.get('x-should-retry')),
+                    shouldRetry: parseShouldRetry(response.headers.get("x-should-retry")),
                     response,
                 };
             }
-            return { kind: 'response', response };
+            return { kind: "response", response };
         }
         catch (error) {
-            if (error instanceof DOMException && error.name === 'AbortError') {
+            // Checked first and independently of the thrown value — see attempt().
+            if (callerSignal?.aborted) {
+                return { kind: "canceled", reason: callerSignal.reason };
+            }
+            if (isAbortError(error)) {
                 return {
-                    kind: 'timeout',
+                    kind: "timeout",
                     error: new NxusApiError({
                         message: `Request timed out after ${timeout}ms`,
-                        userMessage: 'The request timed out. Please try again.',
+                        userMessage: "The request timed out. Please try again.",
                         status: 0,
                     }),
                 };
             }
             return {
-                kind: 'network-error',
+                kind: "network-error",
                 error: new NxusApiError({
-                    message: error instanceof Error ? error.message : 'Network request failed',
-                    userMessage: 'A network error occurred. Please check your connection and try again.',
+                    message: error instanceof Error ? error.message : "Network request failed",
+                    userMessage: "A network error occurred. Please check your connection and try again.",
                     status: 0,
                     raw: error,
                 }),
@@ -473,15 +740,59 @@ export class NxusHttpTransport {
         }
         finally {
             clearTimeout(timer);
+            composed.dispose();
         }
     }
 }
-function shouldRetry(outcome) {
-    if (outcome.kind === 'network-error')
-        return true;
-    if (outcome.kind === 'timeout')
+/**
+ * Copy everything worth keeping out of a response before it is released.
+ *
+ * The body is already read by the time this is called, so nothing downstream
+ * can touch a consumed stream. `rawBody` is retained only on request — holding
+ * the undecoded text of every response would keep a second full copy of every
+ * payload alive.
+ */
+function snapshot(response, body, text, includeRawBody) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    const bodyRequestId = body != null && typeof body === "object"
+        ? body.requestId
+        : undefined;
+    return {
+        body,
+        status: response.status,
+        headers: Object.freeze(headers),
+        requestId: (typeof bodyRequestId === "string" ? bodyRequestId : undefined) ??
+            headers["x-request-id"],
+        rawBody: includeRawBody ? text : undefined,
+    };
+}
+function shouldRetry(outcome, retryTimeout = false) {
+    // The caller asked us to stop. Retrying would be the opposite of that, and
+    // for a Create it would resubmit work the caller is trying to abandon.
+    if (outcome.kind === "canceled")
         return false;
-    if (outcome.kind === 'http-error') {
+    if (outcome.kind === "network-error")
+        return true;
+    if (outcome.kind === "timeout")
+        return retryTimeout;
+    if (outcome.kind === "http-error") {
+        // A wait longer than we are willing to block for. Returning false here
+        // rather than retrying early is the point: an early retry cannot succeed
+        // inside a window the server just told us is still open, and it consumes
+        // an attempt to learn that. The caller gets the error with `retryAfter`
+        // on it and can schedule the real wait.
+        //
+        // Checked before `x-should-retry` on purpose. The two answer different
+        // questions — whether to retry, and when — and a server sending
+        // `x-should-retry: true` with `Retry-After: 300` is asking for a retry in
+        // five minutes, not for this process to block for five minutes. Nothing
+        // is lost: both facts reach the caller on the error.
+        if (outcome.retryAfter != null && outcome.retryAfter > RETRY_AFTER_MAX_MS) {
+            return false;
+        }
         if (outcome.shouldRetry != null)
             return outcome.shouldRetry;
         if (RETRYABLE_STATUSES.has(outcome.status))
@@ -493,8 +804,10 @@ function shouldRetry(outcome) {
     return false;
 }
 function computeRetryDelay(attempt, outcome) {
-    if (outcome.kind === 'http-error' && outcome.retryAfter != null) {
-        return Math.min(outcome.retryAfter, RETRY_MAX_DELAY_MS);
+    if (outcome.kind === "http-error" && outcome.retryAfter != null) {
+        // Honoured in full. shouldRetry() has already refused anything above
+        // RETRY_AFTER_MAX_MS, so this cannot exceed the ceiling.
+        return outcome.retryAfter;
     }
     const exponential = Math.min(RETRY_BASE_DELAY_MS * 2 ** attempt, RETRY_MAX_DELAY_MS);
     const jitter = Math.random() * exponential * 0.5;
@@ -515,16 +828,18 @@ function parseRetryAfter(value) {
     return undefined;
 }
 function parseBodyRetryAfter(body) {
-    if (body == null || typeof body !== 'object')
+    if (body == null || typeof body !== "object")
         return undefined;
     const root = body;
     // Shape per backend contract: `{ error: { retryAfter: <seconds> } }`.
     // Tolerate top-level `retryAfter` for older payloads / future flattening.
-    const errorObj = root.error && typeof root.error === 'object'
+    const errorObj = root.error && typeof root.error === "object"
         ? root.error
         : undefined;
     const candidate = errorObj?.retryAfter ?? root.retryAfter;
-    if (typeof candidate !== 'number' || !Number.isFinite(candidate) || candidate < 0) {
+    if (typeof candidate !== "number" ||
+        !Number.isFinite(candidate) ||
+        candidate < 0) {
         return undefined;
     }
     return candidate * 1000;
@@ -533,13 +848,107 @@ function parseShouldRetry(value) {
     if (!value)
         return undefined;
     const normalized = value.trim().toLowerCase();
-    if (['1', 'true', 'yes'].includes(normalized))
+    if (["1", "true", "yes"].includes(normalized))
         return true;
-    if (['0', 'false', 'no'].includes(normalized))
+    if (["0", "false", "no"].includes(normalized))
         return false;
     return undefined;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Sleep that a caller can interrupt.
+ *
+ * Retry backoff can be seconds long. Without the signal, a caller cancelling
+ * mid-backoff would still wait out the delay and then issue another request.
+ */
+/**
+ * Abort detection that survives a cross-realm boundary.
+ *
+ * `instanceof DOMException` is false for an abort raised in another realm
+ * (undici's fetch, a worker, a polyfilled test double), and a miss there gets
+ * reported as a network error and retried — the opposite of what a cancelling
+ * caller asked for.
+ */
+function isAbortError(error) {
+    if (error instanceof DOMException && error.name === "AbortError")
+        return true;
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "AbortError");
+}
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    if (signal.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Read a caller-supplied `signal` out of per-request `fetchOptions`.
+ *
+ * Returned separately from the rest of the options so the SDK's timeout signal
+ * cannot silently overwrite it, which is exactly what used to happen.
+ */
+function extractCallerSignal(extraFetchOptions) {
+    const { signal, ...rest } = extraFetchOptions;
+    return {
+        callerSignal: signal instanceof AbortSignal ? signal : undefined,
+        rest,
+    };
+}
+/**
+ * One signal that aborts when either the caller or the timeout does, plus the
+ * cleanup that detaches whatever it attached.
+ *
+ * `AbortSignal.any` landed in Node 20.3; the package supports Node 18, so the
+ * manual path is not dead code.
+ *
+ * The caller's signal usually outlives the request — one controller cancels a
+ * whole batch — so the fallback's listeners MUST be removed when the request
+ * finishes, not only when an abort fires. `{ once: true }` covers the abort
+ * case and nothing else: twelve successful requests sharing one caller signal
+ * left twelve listeners attached, each retaining a controller and its closure.
+ * Hence the returned `dispose`, which every attempt calls from its finally.
+ */
+function combineAbortSignals(callerSignal, timeoutSignal) {
+    if (!callerSignal)
+        return { signal: timeoutSignal, dispose: () => { } };
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === "function") {
+        // Native composition detaches itself once the composed signal is
+        // unreachable; there is nothing for us to clean up.
+        return { signal: anyFn([callerSignal, timeoutSignal]), dispose: () => { } };
+    }
+    const controller = new AbortController();
+    const attached = [];
+    for (const source of [callerSignal, timeoutSignal]) {
+        if (source.aborted) {
+            controller.abort(source.reason);
+            break;
+        }
+        const forward = () => controller.abort(source.reason);
+        source.addEventListener("abort", forward, { once: true });
+        attached.push([source, forward]);
+    }
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            for (const [source, forward] of attached) {
+                source.removeEventListener("abort", forward);
+            }
+            attached.length = 0;
+        },
+    };
 }
 //# sourceMappingURL=transport.js.map