@providerkit/core 0.1.0 → 0.3.0

package/dist/providers/responses.d.ts

@@ -0,0 +1,38 @@
+import type { ChatMessage, Effort, Provider } from "../types.ts";
+export interface ResponsesConfig {
+    apiKey: string;
+    model: string;
+    /** Any endpoint speaking the Responses format. Defaults to OpenAI itself. */
+    baseUrl?: string;
+    /** Names the provider in errors and logs. */
+    id?: string;
+    effort?: Effort;
+    maxTokens?: number;
+    fetchImpl?: typeof fetch;
+    /** Extra request headers — where a subscription backend's account id goes
+     *  (`ChatGPT-Account-Id`), which those backends reject the request without. */
+    headers?: Record<string, string>;
+    /**
+     * Where this backend serves the endpoint, when it is not `/v1/responses`.
+     * The ChatGPT subscription surface serves it at `/backend-api/codex/responses`
+     * with no version segment, so that backend needs
+     * `{ baseUrl: "https://chatgpt.com/backend-api/codex", path: "/responses" }`.
+     * Without the override the POST 404s, and a 404 classifies as "model" — the
+     * user is told the model id does not exist when the path was the problem.
+     */
+    path?: string;
+}
+/**
+ * Flatten a history into `instructions` plus the input item list.
+ *
+ * This shape has no system ROLE — the system prompt is a top-level
+ * `instructions` string, and everything else is items. One assistant turn can
+ * become several items (its text, then one `function_call` per tool it asked
+ * for), which is why a message maps to a list rather than to one item.
+ */
+export declare function toResponsesInput(messages: readonly ChatMessage[]): {
+    instructions?: string;
+    input: unknown[];
+};
+export declare function createResponsesProvider(config: ResponsesConfig): Provider;
+//# sourceMappingURL=responses.d.ts.map

package/dist/providers/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/providers/responses.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,WAAW,EAEX,MAAM,EAGN,QAAQ,EAIT,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;mFAC+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAiDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB,CAuDA;AA2DD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,CAuOzE"}

package/dist/providers/responses.js

@@ -0,0 +1,341 @@
+// Responses-shape adapter — SSE from POST /v1/responses.
+//
+// OpenAI's second wire format, and the only one some backends expose: the
+// ChatGPT subscription surface (chatgpt.com/backend-api/codex) has no
+// chat/completions endpoint at all. It is not chat/completions with a new path
+// — the input is an ITEM LIST rather than a message list, the stream is
+// event-typed rather than choice-delta'd, and the terminal event carries the
+// usage record instead of a trailing usage-only frame.
+//
+// The event names arrive on the SSE `event:` line and are repeated inside each
+// payload's own `type`. The transport yields only `data:` payloads, so this
+// adapter reads `type` — which is what survives, and what gateways agree on.
+import { streamError } from "../errors.js";
+import { streamSse, apiUrl } from "../transport.js";
+import { toDataUri } from "../types.js";
+const DEFAULT_BASE_URL = "https://api.openai.com";
+const DEFAULT_PATH = "/v1/responses";
+/**
+ * `response.incomplete` means the turn was cut short, and the seam has one word
+ * for that: "length". `content_filter` is the only other reason this shape
+ * documents; anything new stays on "length" rather than reporting a clean stop,
+ * because a caller that believes a truncated answer finished will act on it.
+ */
+function mapIncompleteReason(reason) {
+    return reason === "content_filter" ? "content_filter" : "length";
+}
+function partsToResponses(content) {
+    if (typeof content === "string")
+        return [{ type: "input_text", text: content }];
+    return content.map((part) => part.type === "text"
+        ? { type: "input_text", text: part.text }
+        : { type: "input_image", image_url: toDataUri(part) });
+}
+/** A tool result is a bare string unless it carried images — then the content-
+ *  array form, the only way to hand this shape a screenshot back. */
+function toolOutput(content, images) {
+    if (images.length === 0)
+        return content;
+    const parts = [];
+    if (content)
+        parts.push({ type: "input_text", text: content });
+    for (const image of images)
+        parts.push({ type: "input_image", image_url: toDataUri(image) });
+    return parts;
+}
+/**
+ * Flatten a history into `instructions` plus the input item list.
+ *
+ * This shape has no system ROLE — the system prompt is a top-level
+ * `instructions` string, and everything else is items. One assistant turn can
+ * become several items (its text, then one `function_call` per tool it asked
+ * for), which is why a message maps to a list rather than to one item.
+ */
+export function toResponsesInput(messages) {
+    const instructions = messages
+        .filter((message) => message.role === "system")
+        .map((message) => message.content)
+        .join("\n\n");
+    const input = [];
+    for (const message of messages) {
+        switch (message.role) {
+            case "system":
+                break; // lifted into `instructions` above
+            case "user":
+                input.push({ type: "message", role: "user", content: partsToResponses(message.content) });
+                break;
+            case "tool":
+                input.push({
+                    // `call_id` — the id the model coined for the CALL, not the `fc_…` id
+                    // of the output item that carried it. Sending the wrong one is a 400
+                    // reading "No tool output found for function call", one turn later.
+                    type: "function_call_output",
+                    call_id: message.toolCallId,
+                    output: toolOutput(message.content, message.images ?? []),
+                });
+                break;
+            case "assistant": {
+                // Reasoning is deliberately NOT replayed. This shape wants the ORIGINAL
+                // reasoning item back — its `rs_…` id, and under `store: false` its
+                // `encrypted_content` blob — and the seam carries neither, only the
+                // plain summary text a caller renders. A synthesized reasoning item is
+                // rejected; omitting it costs only the model re-deriving its own chain
+                // of thought, which is what every stateless caller already lives with.
+                if (message.content) {
+                    input.push({
+                        type: "message",
+                        role: "assistant",
+                        content: [{ type: "output_text", text: message.content }],
+                    });
+                }
+                for (const call of message.toolCalls ?? []) {
+                    input.push({
+                        type: "function_call",
+                        call_id: call.id,
+                        name: call.name,
+                        arguments: call.arguments,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return { ...(instructions ? { instructions } : {}), input };
+}
+function usageChunk(usage) {
+    return {
+        type: "usage",
+        usage: {
+            inputTokens: usage.input_tokens ?? 0,
+            // Already a SUBSET of input_tokens on this shape, as on chat/completions
+            // — and the only signal that its automatic prefix caching is working.
+            cachedInputTokens: usage.input_tokens_details?.cached_tokens ?? 0,
+            // Reasoning tokens are billed INSIDE output_tokens, not beside them.
+            outputTokens: usage.output_tokens ?? 0,
+        },
+    };
+}
+export function createResponsesProvider(config) {
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    const id = config.id ?? "openai-responses";
+    return {
+        id,
+        model: config.model,
+        async *createStream(messages, tools, opts = {}) {
+            const effort = opts.effort ?? config.effort;
+            const { instructions, input } = toResponsesInput(messages);
+            const request = {
+                model: opts.model ?? config.model,
+                input,
+                stream: true,
+                // The caller's history is the entire state of a run. Server-side
+                // storage adds a retention surface nobody asked for, and is refused
+                // outright on zero-data-retention accounts.
+                store: false,
+            };
+            if (instructions)
+                request.instructions = instructions;
+            const maxTokens = opts.maxTokens ?? config.maxTokens;
+            if (maxTokens !== undefined)
+                request.max_output_tokens = maxTokens;
+            if (opts.temperature !== undefined)
+                request.temperature = opts.temperature;
+            if (effort && effort !== "none") {
+                // `summary` is what switches the reasoning stream ON. Without it this
+                // shape emits no reasoning_summary_text events at all, and a caller
+                // rendering a thinking pane silently gets nothing while the tokens are
+                // billed either way.
+                request.reasoning = { effort, summary: "auto" };
+            }
+            if (tools.length > 0) {
+                // Flat here — no nested `function` envelope, unlike chat/completions.
+                request.tools = tools.map((tool) => ({
+                    type: "function",
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.inputSchema,
+                }));
+            }
+            if (opts.toolChoice && opts.toolChoice !== "auto") {
+                request.tool_choice =
+                    typeof opts.toolChoice === "string"
+                        ? opts.toolChoice
+                        : { type: "function", name: opts.toolChoice.name };
+            }
+            if (opts.json) {
+                // The schema rides in `text.format`, not `response_format`.
+                request.text = {
+                    format: {
+                        type: "json_schema",
+                        name: opts.json.name,
+                        schema: opts.json.schema,
+                        strict: true,
+                    },
+                };
+            }
+            // Tool calls arrive as an item skeleton plus argument deltas; keyed by the
+            // output item id so parallel calls never cross wires. The seam's index is
+            // ours to assign — `output_index` counts reasoning and message items too.
+            const pending = new Map();
+            let nextIndex = 0;
+            // This shape never states a stop reason on a clean finish, so it is
+            // inferred from whether the turn produced a function call.
+            let sawToolCall = false;
+            for await (const data of streamSse({
+                url: apiUrl(baseUrl, config.path ?? DEFAULT_PATH),
+                headers: { authorization: `Bearer ${config.apiKey}`, ...config.headers },
+                body: request,
+                provider: id,
+                ...(opts.signal ? { signal: opts.signal } : {}),
+                ...(config.fetchImpl ? { fetchImpl: config.fetchImpl } : {}),
+            })) {
+                let event;
+                try {
+                    event = JSON.parse(data);
+                }
+                catch {
+                    continue; // a keep-alive or a frame we do not model
+                }
+                switch (event.type) {
+                    case "response.output_text.delta":
+                        if (event.delta)
+                            yield { type: "delta", content: event.delta };
+                        break;
+                    // Two names for the same stream: `reasoning_summary_text` is the
+                    // redacted summary the API returns, `reasoning_text` the raw trace
+                    // the ChatGPT backend streams. A caller wants whichever it gets.
+                    case "response.reasoning_summary_text.delta":
+                    case "response.reasoning_text.delta":
+                        if (event.delta)
+                            yield { type: "delta", reasoning: event.delta };
+                        break;
+                    case "response.output_item.added": {
+                        const item = event.item;
+                        if (item?.type !== "function_call" || !item.id)
+                            break;
+                        sawToolCall = true;
+                        const index = nextIndex++;
+                        // Normally empty here, but a backend that already has the whole
+                        // call sends it in the skeleton.
+                        const seeded = item.arguments ?? "";
+                        pending.set(item.id, {
+                            index,
+                            id: item.call_id ?? "",
+                            name: item.name ?? "",
+                            streamed: seeded,
+                        });
+                        // Only the fields the skeleton actually states. An empty `id` here
+                        // is not "unknown", it is a wrong answer: a consumer takes the last
+                        // stated value, so `""` written into the slot survives the real
+                        // `call_id` arriving on `.done`.
+                        yield {
+                            type: "delta",
+                            toolCalls: [
+                                {
+                                    index,
+                                    ...(item.call_id ? { id: item.call_id } : {}),
+                                    ...(item.name ? { name: item.name } : {}),
+                                    ...(seeded ? { arguments: seeded } : {}),
+                                },
+                            ],
+                        };
+                        break;
+                    }
+                    case "response.function_call_arguments.delta": {
+                        const call = event.item_id ? pending.get(event.item_id) : undefined;
+                        if (!call || !event.delta)
+                            break;
+                        call.streamed += event.delta;
+                        yield { type: "delta", toolCalls: [{ index: call.index, arguments: event.delta }] };
+                        break;
+                    }
+                    case "response.output_item.done": {
+                        const item = event.item;
+                        if (item?.type !== "function_call")
+                            break;
+                        const known = item.id ? pending.get(item.id) : undefined;
+                        if (item.id)
+                            pending.delete(item.id);
+                        const snapshot = item.arguments ?? "";
+                        if (!known) {
+                            // A backend that emits neither the skeleton nor the deltas — the
+                            // whole call arrives here or not at all. Without a `call_id`
+                            // there is nothing to answer it with: the caller's
+                            // `function_call_output` would quote `""` and take a 400 reading
+                            // "No tool output found for function call" one turn later, so the
+                            // call is dropped rather than handed over unrunnable. Dropping is
+                            // only possible here, where nothing has been streamed for it yet.
+                            if (!item.call_id)
+                                break;
+                            sawToolCall = true;
+                            yield {
+                                type: "delta",
+                                toolCalls: [
+                                    {
+                                        index: nextIndex++,
+                                        id: item.call_id,
+                                        ...(item.name ? { name: item.name } : {}),
+                                        arguments: snapshot,
+                                    },
+                                ],
+                            };
+                            break;
+                        }
+                        // The snapshot is authoritative, but the fragments already went
+                        // out: re-emitting it whole concatenates the JSON with itself and
+                        // every argument parse fails. Send only what the deltas missed —
+                        // which is all of it when they never came.
+                        const tail = snapshot.length > known.streamed.length && snapshot.startsWith(known.streamed)
+                            ? snapshot.slice(known.streamed.length)
+                            : "";
+                        // `.done` restates the identity, and on a backend that leaves it
+                        // out of the skeleton this is the only frame that carries it. It
+                        // rides last so it WINS: the alternative is a caller assembling a
+                        // nameless call it has no tool to dispatch, quoting an empty
+                        // `call_id` back on the turn after.
+                        const restated = {
+                            ...(item.call_id && item.call_id !== known.id ? { id: item.call_id } : {}),
+                            ...(item.name && item.name !== known.name ? { name: item.name } : {}),
+                            ...(tail ? { arguments: tail } : {}),
+                        };
+                        if (Object.keys(restated).length > 0) {
+                            yield { type: "delta", toolCalls: [{ index: known.index, ...restated }] };
+                        }
+                        break;
+                    }
+                    case "response.completed": {
+                        const usage = event.response?.usage;
+                        if (usage)
+                            yield usageChunk(usage);
+                        yield { type: "finish", finishReason: sawToolCall ? "tool_calls" : "stop" };
+                        return;
+                    }
+                    case "response.incomplete": {
+                        // A turn that ran out of output tokens still billed for its input,
+                        // and this event carries usage in the same shape as `completed`.
+                        const usage = event.response?.usage;
+                        if (usage)
+                            yield usageChunk(usage);
+                        yield {
+                            type: "finish",
+                            finishReason: mapIncompleteReason(event.response?.incomplete_details?.reason),
+                        };
+                        return;
+                    }
+                    // The two ways this shape reports a failure after its headers went
+                    // out: a terminal `response.failed`, or a bare error frame from a
+                    // gateway in front of it.
+                    case "response.failed":
+                        throw streamError(id, event.response?.error);
+                    case "error":
+                    case "response.error":
+                        throw streamError(id, event.error ?? { message: event.message, code: event.code });
+                }
+            }
+            // The stream closed without a terminal event. Nothing is lost but the
+            // finish reason and the usage record — every delta, tool-call fragment
+            // included, was already yielded as it arrived.
+        },
+    };
+}
+//# sourceMappingURL=responses.js.map

package/dist/providers/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../../src/providers/responses.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,29 @@
+/** Which subscription window bound. Only Anthropic's unified headers name one
+ *  outright; the codex body shape has it inferred from the wait. */
+export type RateLimitWindow = "5h" | "weekly" | "monthly";
+export interface RateLimitReset {
+    /** Absolute time the binding window resets, when any header disclosed it. */
+    resetAtMs?: number;
+    /** Server-requested wait (`retry-after`) — what a retry policy honours. */
+    retryAfterMs?: number;
+    /** Which subscription window bound, when it could be named at all. */
+    window?: RateLimitWindow;
+}
+/**
+ * Parse the rate-limit headers off a (usually 429) response.
+ *
+ * Anthropic's `anthropic-ratelimit-unified-*` pair rides on every OAuth
+ * response, so both windows are always reported and only one of them is the
+ * reason for this 429. API-key accounts get the `anthropic-ratelimit-*-reset`
+ * RFC 3339 timestamps instead. Everything is optional — an unrecognized shape
+ * yields an empty result, and the caller falls back to its generic message.
+ */
+export declare function parseRateLimitReset(headers: Headers, now?: number): RateLimitReset;
+/**
+ * ChatGPT's codex backend puts the reset IN THE 429 BODY, not the headers:
+ * `{"error":{"type":"usage_limit_reached","resets_at":1788801754,"resets_in_seconds":2501465}}`.
+ * The window name is inferred from the wait itself, and only past the floor
+ * above — a sub-minute retry is a throttle, not a subscription window.
+ */
+export declare function parseUsageLimitBody(bodyText: string, now?: number): RateLimitReset;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AA2BA;oEACoE;AACpE,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AA8DD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,cAAc,CA+CtF;AAsBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,cAAc,CAgCtF"}

package/dist/rate-limit.js

@@ -0,0 +1,194 @@
+// Rate-limit headers, read for the one thing a 429 never says in its body: WHEN.
+//
+// A 429 discloses that a limit was hit, never which limit. A per-minute
+// throttle and a Claude OAuth subscription window (5-hour, or weekly) arrive
+// as the same status with the same wording, and the second one resets in DAYS.
+// Only the headers tell them apart. Without them a caller can say nothing
+// better than "try again in a moment", which is a lie for the multi-day case.
+//
+// Parsing only. Rendering `resetAtMs` as "in 4 hours (6:47 PM)" belongs to the
+// caller: relative-time wording is locale work, and a library that ships it
+// either drags in an i18n dependency or hardcodes English.
+//
+// The overlap with `retryAfterFromHeaders` in transport.ts is deliberate, and
+// the two are not interchangeable. That one answers the retry policy's
+// question — one number, how long to sleep — so it treats `Retry-After` as
+// authoritative whenever it is present, and falls back to any vendor reset
+// header it can find. This one answers the user-facing question, where the
+// unified window's reset OUTRANKS `Retry-After`: Anthropic sends
+// `retry-after: 60` beside a weekly window that lifts in three days, and 60
+// seconds is the correct sleep and the wrong horizon. Delegating here would
+// also fill `retryAfterMs` — documented as what the SERVER asked for — with a
+// vendor reset header on every response that carries no `Retry-After` at all.
+// What must NOT differ is which headers the two can date: the fallback list
+// below is transport's list, because a header only one of them reads is a 429
+// whose `ProviderError.retryAfterMs` knows the wait is three days while the
+// user-facing answer is empty.
+const RETRY_AFTER = "retry-after";
+const UNIFIED_5H = "anthropic-ratelimit-unified-5h-";
+const UNIFIED_7D = "anthropic-ratelimit-unified-7d-";
+/** Reset headers that name a time rather than a window, in the order
+ *  transport.ts reads them and kept in step with that list. The singular
+ *  `anthropic-ratelimit-unified-reset` rides on OAuth responses that carry no
+ *  5h/7d pair, and the `x-ratelimit-*` spellings are what every non-Anthropic
+ *  provider and gateway sends. */
+const RESET_HEADERS = [
+    "anthropic-ratelimit-unified-reset",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-reset",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    "x-ratelimit-reset",
+];
+/** Seconds since 1970 passed a billion in 2001, so a bare integer above this is
+ *  a timestamp and anything below it is a countdown. Vendors disagree on which
+ *  they send under the same header name, so magnitude decides. */
+const EPOCH_SECONDS_FLOOR = 1_000_000_000;
+/** A non-negative finite number, or nothing. The null guard carries weight:
+ *  `Number("")` is 0, so an absent header would otherwise read as a real zero. */
+function numeric(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function unixSecondsToMs(value) {
+    const n = numeric(value);
+    return n === undefined ? undefined : n * 1000;
+}
+/** Absolute reset time from a header that spells it either way: epoch seconds
+ *  (the unified reset, most gateways) or an RFC 3339 / HTTP-date string (the
+ *  API-key reset headers). The digit test runs first because `Date.parse("120")`
+ *  is not a rejection — it is the year 120, two millennia in the past. */
+function resetHeaderMs(value, now) {
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value)) {
+        const seconds = Number(value);
+        return seconds > EPOCH_SECONDS_FLOOR ? seconds * 1000 : now + seconds * 1000;
+    }
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : at;
+}
+/** `retry-after` is delay-seconds, but RFC 9110 also allows an absolute date,
+ *  and both forms occur across the providers this package speaks to. */
+function parseRetryAfter(value, now) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (Number.isFinite(n) && n >= 0)
+        return n * 1000;
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+/**
+ * Parse the rate-limit headers off a (usually 429) response.
+ *
+ * Anthropic's `anthropic-ratelimit-unified-*` pair rides on every OAuth
+ * response, so both windows are always reported and only one of them is the
+ * reason for this 429. API-key accounts get the `anthropic-ratelimit-*-reset`
+ * RFC 3339 timestamps instead. Everything is optional — an unrecognized shape
+ * yields an empty result, and the caller falls back to its generic message.
+ */
+export function parseRateLimitReset(headers, now = Date.now()) {
+    const result = {};
+    const after = parseRetryAfter(headers.get(RETRY_AFTER), now);
+    if (after !== undefined) {
+        result.retryAfterMs = after;
+        result.resetAtMs = now + after;
+    }
+    // The window with the higher utilization is the one a "would exceed your
+    // rate limit" 429 is about. A reset already in the past belongs to a window
+    // that rolled over between the response and this parse — naming it would put
+    // a past time in front of the user — so it drops out here.
+    const windows = [
+        {
+            window: "5h",
+            utilization: numeric(headers.get(`${UNIFIED_5H}utilization`)),
+            reset: unixSecondsToMs(headers.get(`${UNIFIED_5H}reset`)),
+        },
+        {
+            window: "weekly",
+            utilization: numeric(headers.get(`${UNIFIED_7D}utilization`)),
+            reset: unixSecondsToMs(headers.get(`${UNIFIED_7D}reset`)),
+        },
+    ].filter((w) => w.utilization !== undefined && w.reset !== undefined && w.reset > now);
+    const binding = windows.sort((a, b) => (b.utilization ?? 0) - (a.utilization ?? 0))[0];
+    if (binding) {
+        result.window = binding.window;
+        // The window's own reset outranks retry-after: it names the real horizon,
+        // where retry-after names the next polite attempt.
+        if (binding.reset !== undefined)
+            result.resetAtMs = binding.reset;
+    }
+    // No window named the horizon, so take the first reset header that dates the
+    // future. These stay below `retry-after`, which is the server speaking about
+    // this request; they only fill a silence.
+    if (result.resetAtMs === undefined) {
+        for (const name of RESET_HEADERS) {
+            const at = resetHeaderMs(headers.get(name), now);
+            if (at !== undefined && at > now) {
+                result.resetAtMs = at;
+                break;
+            }
+        }
+    }
+    return result;
+}
+/** Under ten minutes the wait is a per-minute throttle whatever the body calls
+ *  it, and calling a 40-second retry a "5-hour window" would be its own lie. */
+const WINDOW_FLOOR_MS = 10 * 60_000;
+/** Bucket edges, padded: a window's reset lands wherever inside it the first
+ *  request fell, so a 5-hour window routinely reports four hours and change. */
+const FIVE_HOUR_MAX_MS = 5.5 * 3_600_000;
+const WEEKLY_MAX_MS = 7.5 * 86_400_000;
+/** A finite number off a JSON field, the string form a relay may stringify it
+ *  into included. Bare `Number()` is the trap `numeric()` guards against one
+ *  layer up: `Number(null)`, `Number("")`, `Number([])` and `Number(false)` are
+ *  all 0, and 0 is finite and non-negative, so a relay that nulls out
+ *  `resets_in_seconds` beside a real `resets_at` would win the branch below and
+ *  report a three-day lockout as "retry now". */
+function jsonSeconds(value) {
+    const usable = typeof value === "number" || (typeof value === "string" && value.trim() !== "");
+    const n = usable ? Number(value) : NaN;
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * ChatGPT's codex backend puts the reset IN THE 429 BODY, not the headers:
+ * `{"error":{"type":"usage_limit_reached","resets_at":1788801754,"resets_in_seconds":2501465}}`.
+ * The window name is inferred from the wait itself, and only past the floor
+ * above — a sub-minute retry is a throttle, not a subscription window.
+ */
+export function parseUsageLimitBody(bodyText, now = Date.now()) {
+    let body;
+    try {
+        body = JSON.parse(bodyText);
+    }
+    catch {
+        return {};
+    }
+    if (typeof body !== "object" || body === null)
+        return {};
+    // The fields sit under `error` on the documented shape and at the top level
+    // on some gateway relays of it. Both are read rather than guessed between.
+    const source = body.error;
+    const error = typeof source === "object" && source !== null
+        ? source
+        : body;
+    const inSeconds = jsonSeconds(error.resets_in_seconds);
+    const atSeconds = jsonSeconds(error.resets_at);
+    const waitMs = inSeconds !== undefined && inSeconds >= 0
+        ? inSeconds * 1000
+        : atSeconds !== undefined && atSeconds > 0
+            ? Math.max(0, atSeconds * 1000 - now)
+            : undefined;
+    if (waitMs === undefined)
+        return {};
+    const result = { retryAfterMs: waitMs, resetAtMs: now + waitMs };
+    if (waitMs > WINDOW_FLOOR_MS) {
+        result.window =
+            waitMs <= FIVE_HOUR_MAX_MS ? "5h" : waitMs <= WEEKLY_MAX_MS ? "weekly" : "monthly";
+    }
+    return result;
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}