@ziffer-io/client 0.1.1 → 0.2.1

package/dist/client.js

@@ -43,7 +43,30 @@
  * - A poll that outlives its deadline throws {@link WaitTimeout}. A timeout
  *   is "no answer yet", never "the answer was no" (ingress-low's rule for
  *   its own dependency, one layer out).
+ * - A call that was still retrying when the caller's deadline arrived throws
+ *   {@link DeadlineExceeded}, carrying the last failure's name and status.
+ *   Inside {@link ZifferClient.wait} it is caught and re-thrown as
+ *   {@link WaitTimeout} with that `DeadlineExceeded` as its `cause`: `wait`
+ *   has ONE name for "no answer yet" and a caller already catches it.
+ *
+ * # Timeouts and retries
+ *
+ * Every round trip carries an abort signal set to {@link REQUEST_TIMEOUT_MS}.
+ * **That timeout covers ONE ROUND TRIP** — the send and the reading of the
+ * answer's body — and is not a budget for the call: a call that retries may
+ * take several times as long and is not wrong for doing so. Waiting for a
+ * human to approve is not a round trip at all; that is {@link
+ * ZifferClient.wait}, which polls, and each poll is its own round trip under
+ * its own timeout.
+ *
+ * There is ONE request path and the retry loop is inside it, so `propose`,
+ * `decision` and every poll of `wait` retry under exactly the same rules
+ * (`retry.ts` holds them, `retry.test.ts` replays the corpus both SDKs share).
+ * The bytes are serialised once, above the loop, and the same bytes are
+ * resent: the gateway keys a pending hold on the hash of what it received, so
+ * identical bytes land on the same hold instead of opening a second one.
  */
+import { DeadlineExceeded, newCall, parseRetryAfterSeconds, REQUEST_TIMEOUT_MS, RETRY_AFTER_HEADER, RetryPolicy, } from './retry.js';
 // ---------------------------------------------------------------- key expiry
 /**
  * The header every SUCCESSFUL answer carries (ACP-256 §5): the instant the key
@@ -98,6 +121,39 @@ function noteKeyExpiry(value) {
             "(tools/mint-api-key.py --rotate <this key's key_hash>), deploy it, then have this one revoked");
     }
 }
+const REFUSAL_CATEGORIES = [
+    'PolicyRefused',
+    'PolicyBasisMoved',
+    'RateBounded',
+    'ProposalMalformed',
+];
+function isRefusalCategory(v) {
+    return REFUSAL_CATEGORIES.some((c) => c === v);
+}
+/**
+ * The two optional members ACP-402 added to a decision and to a list item,
+ * read once: `refusal_category` (RF-4) and `held_until` (DR-15/DR-16: the
+ * action is held and no receipt is readable until it releases). An absent
+ * member is ABSENT, never `null`.
+ */
+function refusalAndHold(raw, where) {
+    let out = {};
+    if ('refusal_category' in raw) {
+        const category = raw['refusal_category'];
+        if (!isRefusalCategory(category)) {
+            throw new ResponseMalformed(`${where} refusal_category is not one of RF-4's four`);
+        }
+        out = { ...out, refusal_category: category };
+    }
+    if ('held_until' in raw) {
+        const heldUntil = raw['held_until'];
+        if (typeof heldUntil !== 'string') {
+            throw new ResponseMalformed(`${where} held_until is not a string`);
+        }
+        out = { ...out, held_until: heldUntil };
+    }
+    return out;
+}
 // ------------------------------------------------------------ error surface
 /** §1 names, exported so callers and tests never retype the strings. The set
  * is OPEN — the gateway may name more; {@link ApiRefusal} carries any name
@@ -107,6 +163,22 @@ export const ERROR_TENANT_MISMATCH = 'TenantMismatch';
 export const ERROR_PROPOSAL_MALFORMED = 'ProposalMalformed';
 export const ERROR_DECISION_UNKNOWN = 'DecisionUnknown';
 export const ERROR_ADMISSION_UNAVAILABLE = 'AdmissionUnavailable';
+/** ACP-356. ONE name for every way the list's query string is not a legal
+ * one — which parameter, and why, is deliberately not said. */
+export const ERROR_LIST_QUERY_MALFORMED = 'ListQueryMalformed';
+/** ACP-392. `POST /v1/feedback`'s four, in the gateway's own spelling
+ * (`services/gateway/src/gateway.rs::error_name`). They are exported for the
+ * same reason the five above are: a caller branching on a refusal should
+ * import the string rather than type it. */
+export const ERROR_FEEDBACK_MALFORMED = 'FeedbackMalformed';
+export const ERROR_FEEDBACK_TOO_LARGE = 'FeedbackTooLarge';
+export const ERROR_FEEDBACK_RATE_LIMITED = 'FeedbackRateLimited';
+export const ERROR_FEEDBACK_UNAVAILABLE = 'FeedbackUnavailable';
+/** ACP-422. This key's quota on `propose`, `decision`, `list` and `whoami` is
+ * spent: 429 with `Retry-After`, which the retry policy already obeys
+ * (ACP-355). A different name from {@link ERROR_FEEDBACK_RATE_LIMITED}
+ * because it is a different allowance. */
+export const ERROR_RATE_LIMITED = 'RateLimited';
 /**
  * The gateway answered, and the answer was a named refusal. `error` is the
  * gateway's name, verbatim — the machine-readable half, as `Refusal.clause`
@@ -138,11 +210,19 @@ export class ResponseMalformed extends Error {
     }
 }
 /** The deadline passed with the decision still `pending`. Not a refusal and
- * not an answer — the decision may still decide; the id remains fetchable. */
+ * not an answer — the decision may still decide; the id remains fetchable.
+ *
+ * `options.cause` is how the reason survives the rename. A poll that ran out
+ * of retry budget produced a {@link DeadlineExceeded} naming the last failure
+ * and its status; `wait` reports the event under the name its caller catches
+ * and hands the original through as `cause`, so nothing the caller could have
+ * learned from the poll is thrown away to keep one name at the surface. A
+ * rename that dropped the reason would make "no answer yet" indistinguishable
+ * from "the gateway was shedding for thirty seconds". */
 export class WaitTimeout extends Error {
     decisionId;
-    constructor(decisionId, timeoutMs) {
-        super(`decision ${decisionId} still pending after ${timeoutMs}ms`);
+    constructor(decisionId, timeoutMs, options) {
+        super(`decision ${decisionId} still pending after ${timeoutMs}ms`, options);
         this.name = 'WaitTimeout';
         this.decisionId = decisionId;
     }
@@ -166,6 +246,23 @@ function isRecord(v) {
  * is NEVER in the POST response — one place serves receipts — and a client
  * that tolerated one there would quietly stand up a second serving place.
  */
+/** The feedback answer, narrowed with no cast (ACP-392). A 200 whose body is
+ * not this shape is NOT reported as stored: "the gateway answered something"
+ * and "your message is on a disk an operator reads" are different facts, and
+ * only the second is what the caller asked for. */
+function feedbackFromBody(body) {
+    if (!isRecord(body)) {
+        throw new ResponseMalformed('feedback response is not a JSON object');
+    }
+    if (body['stored'] !== true) {
+        throw new ResponseMalformed('feedback response does not say the message was stored');
+    }
+    const tenant = body['tenant'];
+    if (typeof tenant !== 'string' || tenant.length === 0) {
+        throw new ResponseMalformed('feedback response names no tenant');
+    }
+    return { stored: true, tenant };
+}
 function decisionFromBody(body, receiptAllowed) {
     if (!isRecord(body)) {
         throw new ResponseMalformed('decision response is not a JSON object');
@@ -189,15 +286,7 @@ function decisionFromBody(body, receiptAllowed) {
         }
         decision = { ...decision, outcome };
     }
-    if ('clause' in body) {
-        const clause = body['clause'];
-        if (typeof clause !== 'string') {
-            // Includes null: an absent clause is spelled ABSENT (§1's parity with
-            // ingress-low) — accepting null here would admit the second encoding.
-            throw new ResponseMalformed('decision clause is not a string');
-        }
-        decision = { ...decision, clause };
-    }
+    decision = { ...decision, ...refusalAndHold(body, 'decision') };
     if ('receipt' in body) {
         if (!receiptAllowed) {
             throw new ResponseMalformed('receipt in a POST response: one place serves receipts (GET)');
@@ -206,6 +295,120 @@ function decisionFromBody(body, receiptAllowed) {
     }
     return decision;
 }
+/**
+ * Narrow the `GET /v1/whoami` body, refusing by name on any departure.
+ *
+ * BOTH MEMBERS ARE REQUIRED. There is no optional half of an identity, and a
+ * tolerated missing `key_expires_at` would surface as `undefined` in whatever
+ * a caller prints — which reads as "no expiry" and is the one wrong reading of
+ * a credential that ends.
+ */
+function identityFromBody(body) {
+    if (!isRecord(body)) {
+        throw new ResponseMalformed('whoami response is not a JSON object');
+    }
+    const tenant = body['tenant_id'];
+    if (typeof tenant !== 'string' || tenant.length === 0) {
+        throw new ResponseMalformed('whoami response carries no tenant_id');
+    }
+    const expires = body['key_expires_at'];
+    if (typeof expires !== 'string' || expires.length === 0) {
+        throw new ResponseMalformed('whoami response carries no key_expires_at');
+    }
+    return { tenant_id: tenant, key_expires_at: expires };
+}
+function isReceiptPresence(v) {
+    return v === 'attached' || v === 'absent';
+}
+/**
+ * Narrow one list body, refusing by name on any departure — never repairing
+ * one. `next_cursor` must be PRESENT: `null` is the end, an absent member is a
+ * server that did not say, and a client that read the two as one would stop
+ * paging early and report a customer's list as shorter than it is.
+ */
+function pageFromBody(body) {
+    if (!isRecord(body)) {
+        throw new ResponseMalformed('list response is not a JSON object');
+    }
+    const rawItems = body['items'];
+    if (!Array.isArray(rawItems)) {
+        throw new ResponseMalformed('list response carries no items array');
+    }
+    if (!('next_cursor' in body)) {
+        throw new ResponseMalformed('list response carries no next_cursor: null is the end, absent is silence');
+    }
+    const rawCursor = body['next_cursor'];
+    if (rawCursor !== null && typeof rawCursor !== 'string') {
+        throw new ResponseMalformed('next_cursor is neither a string nor null');
+    }
+    const items = rawItems.map((raw) => {
+        if (!isRecord(raw)) {
+            throw new ResponseMalformed('list item is not a JSON object');
+        }
+        const id = raw['decision_id'];
+        const status = raw['status'];
+        const receipt = raw['receipt'];
+        const createdAt = raw['created_at'];
+        const waiting = raw['waiting'];
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new ResponseMalformed('list item carries no decision_id');
+        }
+        if (!isStatus(status)) {
+            throw new ResponseMalformed('list item status is not "pending" or "decided"');
+        }
+        if (!isReceiptPresence(receipt)) {
+            throw new ResponseMalformed('list item receipt is not "attached" or "absent"');
+        }
+        if (typeof createdAt !== 'string') {
+            throw new ResponseMalformed('list item created_at is not a string');
+        }
+        if (typeof waiting !== 'boolean') {
+            throw new ResponseMalformed('list item waiting is not a boolean');
+        }
+        let item = {
+            decision_id: id,
+            status,
+            receipt,
+            created_at: createdAt,
+            waiting,
+        };
+        if ('outcome' in raw) {
+            const outcome = raw['outcome'];
+            if (!isOutcome(outcome)) {
+                throw new ResponseMalformed('list item outcome is not ALLOW, ATTEST or DENY');
+            }
+            item = { ...item, outcome };
+        }
+        if ('expires_at' in raw) {
+            const expiresAt = raw['expires_at'];
+            if (typeof expiresAt !== 'string') {
+                // Includes null: an absent window is spelled ABSENT.
+                throw new ResponseMalformed('list item expires_at is not a string');
+            }
+            item = { ...item, expires_at: expiresAt };
+        }
+        return { ...item, ...refusalAndHold(raw, 'list item') };
+    });
+    return { items, next_cursor: rawCursor };
+}
+/** The global `fetch`, behind {@link FetchLike}. Not `globalThis.fetch`
+ * captured at module load: a test that replaces the global would then be
+ * replacing something this module already copied. */
+const globalFetch = (url, init) => fetch(url, init);
+/** The real sleep. */
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Whatever `fetch` (or the body stream) threw, as an `Error`. A thrown
+ * non-Error is wrapped rather than re-thrown as-is, because {@link
+ * DeadlineExceeded} reports the last failure's NAME and a thrown string has
+ * none — the operator would be told the deadline passed and nothing else.
+ */
+function transportError(thrown, method, path) {
+    if (thrown instanceof Error) {
+        return thrown;
+    }
+    return new Error(`${method} ${path} failed with a non-Error: ${String(thrown)}`);
+}
 /**
  * The client. One instance per (gateway, key); the KEY determines the tenant
  * server-side (§1), so there is nothing tenant-shaped to configure here —
@@ -214,7 +417,15 @@ function decisionFromBody(body, receiptAllowed) {
 export class ZifferClient {
     baseUrl;
     apiKey;
-    constructor(baseUrl, apiKey) {
+    timeoutMs;
+    fetchImpl;
+    now;
+    sleep;
+    random;
+    /** R6/R9: per CLIENT INSTANCE, as the rules say. Two clients do not share a
+     * retry budget, and one client's `propose` and `wait` do. */
+    retry;
+    constructor(baseUrl, apiKey, options) {
         if (baseUrl.length === 0) {
             throw new TypeError('ZifferClient: baseUrl is empty');
         }
@@ -224,28 +435,102 @@ export class ZifferClient {
             // whose log line points at the wrong component.
             throw new TypeError('ZifferClient: apiKey is empty');
         }
+        const timeoutMs = options?.timeoutMs ?? REQUEST_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new TypeError('ZifferClient: timeoutMs must be a positive number of milliseconds');
+        }
         this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
         this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+        this.fetchImpl = options?.fetch ?? globalFetch;
+        this.now = options?.now ?? Date.now;
+        this.sleep = options?.sleep ?? realSleep;
+        this.random = options?.random ?? Math.random;
+        this.retry = new RetryPolicy(options?.retryBucketInitial);
+    }
+    /**
+     * R9. The two retry counters and the bucket gauge, as a plain object taken
+     * at this instant. Cumulative over the client's life — a caller that wants
+     * a delta over one call reads it before and after.
+     */
+    get retryCounters() {
+        return this.retry.counters;
     }
     /**
      * POST /v1/proposals. The proposal is serialised as given — the caller's
      * values, no edits — and the answer never carries a receipt (§1): fetch it
      * with {@link decision} once decided.
+     *
+     * `opts.deadlineMs` bounds the RETRYING, not the round trip (R5).
+     */
+    async propose(proposal, opts) {
+        // R7: serialised ONCE, here, above the retry loop. `request` resends these
+        // same bytes on every attempt, so a resend lands on the hold the gateway
+        // already keyed on their hash rather than opening a second one. Moving
+        // this inside the loop is the defect, not a tidier place for it.
+        const body = JSON.stringify(proposal);
+        const parsed = await this.request('POST', '/v1/proposals', body, this.deadlineAt(opts?.deadlineMs));
+        return decisionFromBody(parsed, false);
+    }
+    /**
+     * POST /v1/feedback — tell ZIFFER what our documentation did not answer
+     * (ACP-392).
+     *
+     * THE TEXT LEAVES THE MACHINE. It is stored under the tenant this API key
+     * carries and read by an operator; nothing is filtered on the way, so
+     * anything put in `question` or `context` is anything an operator will
+     * read. The gateway refuses a member this shape does not define, which is
+     * what stops the object growing a field that carries more than a sentence.
+     *
+     * # ONE round trip and NO retry, unlike every other call on this client
+     *
+     * `request` retries a 429 and honours its `Retry-After`, which is right for
+     * work: a proposal that was refused for backpressure still has to happen.
+     * This is not work. A rate-limited feedback message is a message that will
+     * not be stored, and riding out a 60-second bucket would block the coding
+     * agent that called it for a minute to deliver a sentence. So the failure
+     * is raised as it arrives — [`ApiRefusal`] with the gateway's own name —
+     * and the caller decides.
      */
-    async propose(proposal) {
-        const body = await this.request('POST', '/v1/proposals', JSON.stringify(proposal));
-        return decisionFromBody(body, false);
+    async feedback(message) {
+        if (message.tool.length === 0 || message.question.length === 0) {
+            // Refused here rather than sent, `apiKey`'s rule in the constructor: an
+            // empty question is a caller bug, and mailing it converts a local
+            // defect into a remote 400.
+            throw new TypeError('ZifferClient.feedback: tool and question must both be non-empty');
+        }
+        const body = {
+            tool: message.tool,
+            question: message.question,
+        };
+        // Absent means ABSENT, never present-and-undefined: `JSON.stringify`
+        // would drop an undefined member anyway, and relying on that would make
+        // the wire shape depend on a serialiser's behaviour rather than on this
+        // object.
+        if (message.context !== undefined) {
+            body['context'] = message.context;
+        }
+        const trip = await this.roundTrip('POST', '/v1/feedback', JSON.stringify(body));
+        if (trip.kind !== 'ok') {
+            throw trip.error;
+        }
+        return feedbackFromBody(trip.value);
     }
     /**
      * GET /v1/decisions/{id}. `receipt` is present iff a signed receipt
      * exists; hand it to `verifyReceipt` with your OWN copy of the proposal
      * bytes — the id proves nothing (T), the recomputed hash is the binding.
      */
-    async decision(id) {
+    async decision(id, opts) {
         if (id.length === 0) {
             throw new TypeError('ZifferClient.decision: id is empty');
         }
-        const body = await this.request('GET', `/v1/decisions/${encodeURIComponent(id)}`, null);
+        return this.fetchDecision(id, this.deadlineAt(opts?.deadlineMs));
+    }
+    /** {@link decision}, with the deadline already resolved to an instant —
+     * which is what {@link wait} has and a caller does not. */
+    async fetchDecision(id, deadlineAtMs) {
+        const body = await this.request('GET', `/v1/decisions/${encodeURIComponent(id)}`, null, deadlineAtMs);
         const d = decisionFromBody(body, true);
         if (d.decision_id !== id) {
             // The id is a locator, but an answer ABOUT A DIFFERENT LOCATOR is not
@@ -255,11 +540,59 @@ export class ZifferClient {
         }
         return d;
     }
+    /**
+     * GET /v1/whoami — which customer this key is bound to, and when it ends.
+     *
+     * The one call that asks about the CREDENTIAL rather than about a decision.
+     * It sends no body and takes no argument: there is nothing to name, because
+     * the key is the question. A dead key — expired, revoked or never minted —
+     * is one `ApiRefusal` (`ApiKeyUnknown`, 401) and the three cannot be told
+     * apart, which is deliberate at the gateway and is not this client's to
+     * undo.
+     */
+    async whoami(opts) {
+        const body = await this.request('GET', '/v1/whoami', null, this.deadlineAt(opts?.deadlineMs));
+        return identityFromBody(body);
+    }
+    /**
+     * GET /v1/decisions — what ZIFFER holds and decided for THIS key.
+     *
+     * Every request waiting for approval (with when its hold ends) and every
+     * decision in the window, newest first. The tenant is the API key's and
+     * cannot be named any other way: there is no parameter for it and the
+     * gateway refuses one by name.
+     *
+     * Every bad parameter is one refusal, `ListQueryMalformed` (400). The API
+     * does not say which one, for the same reason an item carries no clause.
+     */
+    async list(opts) {
+        const params = new URLSearchParams();
+        if (opts?.since !== undefined) {
+            params.set('since', opts.since);
+        }
+        if (opts?.limit !== undefined) {
+            params.set('limit', String(opts.limit));
+        }
+        if (opts?.cursor !== undefined) {
+            params.set('cursor', opts.cursor);
+        }
+        const query = params.toString();
+        const body = await this.request('GET', query.length === 0 ? '/v1/decisions' : `/v1/decisions?${query}`, null, this.deadlineAt(opts?.deadlineMs));
+        return pageFromBody(body);
+    }
     /**
      * Poll {@link decision} until `decided` or the deadline. A `WaitTimeout`
      * is "no answer yet", never a verdict; every named refusal (404 included)
      * propagates immediately — retrying `DecisionUnknown` would be the client
      * deciding the server was wrong.
+     *
+     * A poll that runs out of budget surfaces as `WaitTimeout` too, and NOT as
+     * the `DeadlineExceeded` the request path raised. Both mean "the wait's own
+     * deadline arrived with the decision still pending"; which of the two a
+     * caller saw depended on whether the last poll happened to be mid-retry,
+     * which is a detail of the gateway's load and not of this API. The
+     * `DeadlineExceeded` rides along as `cause`, so the last failure's name and
+     * status are still there for whoever wants them.
      */
     async wait(id, opts) {
         const timeoutMs = opts?.timeoutMs ?? 30_000;
@@ -267,57 +600,167 @@ export class ZifferClient {
         if (timeoutMs <= 0 || intervalMs <= 0) {
             throw new TypeError('ZifferClient.wait: timeoutMs and intervalMs must be positive');
         }
-        const deadline = Date.now() + timeoutMs;
+        const deadline = this.now() + timeoutMs;
         for (;;) {
-            const d = await this.decision(id);
+            // R8: each poll is a request like any other, so R1..R6 hold per poll —
+            // including R5, under this wait's OWN deadline. Without that a gateway
+            // answering `Retry-After: 3600` on one poll would park a 30-second wait
+            // for an hour, and the caller's timeout would have meant nothing.
+            let d;
+            try {
+                d = await this.fetchDecision(id, deadline);
+            }
+            catch (thrown) {
+                if (thrown instanceof DeadlineExceeded) {
+                    // The deadline the poll hit IS this wait's deadline — it is the only
+                    // one `fetchDecision` was given above. So this is the event the loop
+                    // below already throws `WaitTimeout` for, reached one branch earlier,
+                    // and giving it a second name would make a caller catch two.
+                    throw new WaitTimeout(id, timeoutMs, { cause: thrown });
+                }
+                throw thrown;
+            }
             if (d.status === 'decided') {
                 return d;
             }
-            if (Date.now() + intervalMs > deadline) {
+            if (this.now() + intervalMs > deadline) {
                 throw new WaitTimeout(id, timeoutMs);
             }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            await this.sleep(intervalMs);
+        }
+    }
+    /** R5: the caller's duration becomes an instant on this client's clock,
+     * once, at the start of the call. `undefined` in, `undefined` out — no
+     * deadline means no check, not a check against infinity. */
+    deadlineAt(deadlineMs) {
+        if (deadlineMs === undefined) {
+            return undefined;
+        }
+        if (!Number.isFinite(deadlineMs) || deadlineMs < 0) {
+            throw new TypeError('ZifferClient: deadlineMs must be a non-negative number of milliseconds');
+        }
+        return this.now() + deadlineMs;
+    }
+    /**
+     * THE request path: one loop, R1..R6, for every call this client makes.
+     *
+     * `body` arrives already serialised and is resent unchanged (R7). The loop
+     * owns nothing about the rules themselves — `retry.ts` decides, this
+     * sleeps, sends again, or throws what the last attempt produced.
+     */
+    async request(method, path, body, deadlineAtMs) {
+        const call = newCall();
+        for (;;) {
+            call.attempts += 1;
+            const trip = await this.roundTrip(method, path, body);
+            if (trip.kind === 'ok') {
+                return trip.value;
+            }
+            const step = this.retry.decide(trip.status, trip.retryAfterS, call, this.now(), deadlineAtMs, this.random);
+            if (step.kind === 'stop') {
+                // Nothing invented: the failure this attempt already produced, as it is.
+                throw trip.error;
+            }
+            if (step.kind === 'deadline') {
+                throw new DeadlineExceeded(trip.error.name, trip.status);
+            }
+            await this.sleep(step.ms);
         }
     }
     /**
-     * One request, one parse, one narrowing. 2xx returns the parsed body for
-     * the caller's guard; anything else must be §1's `{"error": name}` and
-     * throws {@link ApiRefusal} with the name verbatim. A non-JSON or unnamed
-     * error body throws {@link ResponseMalformed} — an intermediary's HTML 502
-     * is not the gateway's answer and is never dressed up as one.
+     * ONE round trip: one request, one parse, one narrowing. 2xx returns the
+     * parsed body for the caller's guard; anything else must be §1's
+     * `{"error": name}` and yields {@link ApiRefusal} with the name verbatim. A
+     * non-JSON or unnamed error body yields {@link ResponseMalformed} — an
+     * intermediary's HTML 502 is not the gateway's answer and is never dressed
+     * up as one, though it IS retried, because 502 is retryable whoever wrote it.
+     *
+     * Nothing is thrown from here: the failure is RETURNED, because whether it
+     * becomes the caller's error is the retry loop's question and not this
+     * method's.
      */
-    async request(method, path, body) {
+    async roundTrip(method, path, body) {
         const headers = {
             authorization: `Bearer ${this.apiKey}`,
         };
         if (body !== null) {
             headers['content-type'] = 'application/json';
         }
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method,
-            headers,
-            ...(body !== null ? { body } : {}),
-        });
-        const text = await res.text();
+        // R8: the signal covers the send AND the reading of the body — one round
+        // trip, not one call.
+        //
+        // An AbortController with a timer this method owns, and NOT
+        // `AbortSignal.timeout`: that helper's timer is held weakly, so a signal
+        // nothing else strongly references can be collected and the abort then
+        // never fires — a timeout that silently is not one. It was observed here,
+        // once in about fifteen runs of this package's own suite, which is exactly
+        // the shape of defect that reaches a customer as "the SDK hung". The timer
+        // below is cleared on every path.
+        const controller = new AbortController();
+        const timedOut = new Error(`${method} ${path} did not answer within ${this.timeoutMs}ms`);
+        timedOut.name = 'TimeoutError';
+        const timer = setTimeout(() => controller.abort(timedOut), this.timeoutMs);
+        let res;
+        let text;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(body !== null ? { body } : {}),
+                signal: controller.signal,
+            });
+            text = await res.text();
+        }
+        catch (thrown) {
+            // R1: no HTTP answer at all — refused, DNS, or the round trip outlived
+            // its timeout. Status 0, and retryable.
+            return {
+                kind: 'failed',
+                status: 0,
+                retryAfterS: null,
+                error: transportError(thrown, method, path),
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const status = res.status;
+        const retryAfterS = parseRetryAfterSeconds(res.headers.get(RETRY_AFTER_HEADER));
+        if (res.ok) {
+            // R6: a successful call adds a token. Counted here, on the STATUS, and
+            // not after the parse: R6 is about the call the gateway answered, and a
+            // 2xx whose body this client then refuses was still a call that worked.
+            this.retry.refill();
+            // Only here, on a 2xx (see API_KEY_EXPIRES_HEADER).
+            noteKeyExpiry(res.headers.get(API_KEY_EXPIRES_HEADER));
+        }
         let parsed;
         try {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new ResponseMalformed(`HTTP ${res.status} with a non-JSON body from ${method} ${path}`);
+            return {
+                kind: 'failed',
+                status,
+                retryAfterS,
+                error: new ResponseMalformed(`HTTP ${status} with a non-JSON body from ${method} ${path}`),
+            };
         }
         if (res.ok) {
-            // Only here, on a 2xx (see API_KEY_EXPIRES_HEADER).
-            noteKeyExpiry(res.headers.get(API_KEY_EXPIRES_HEADER));
-            return parsed;
+            return { kind: 'ok', value: parsed };
         }
         if (isRecord(parsed)) {
             const name = parsed['error'];
             if (typeof name === 'string' && name.length > 0) {
-                throw new ApiRefusal(res.status, name);
+                return { kind: 'failed', status, retryAfterS, error: new ApiRefusal(status, name) };
             }
         }
-        throw new ResponseMalformed(`HTTP ${res.status} from ${method} ${path} names no error`);
+        return {
+            kind: 'failed',
+            status,
+            retryAfterS,
+            error: new ResponseMalformed(`HTTP ${status} from ${method} ${path} names no error`),
+        };
     }
 }
 //# sourceMappingURL=client.js.map