@chrischall/mcp-utils 0.6.0 → 0.8.0

package/dist/http/index.d.ts

@@ -16,12 +16,20 @@
  *  - {@link createApiClient} never embeds the token in a thrown message; a 401
  *    yields a fixed "unauthorized" string, not the credential.
  */
-/** Retry policy for transient (HTTP 429) responses. */
+export * from './throttle.js';
+/** Retry policy for transient responses (HTTP 429 by default). */
 export interface RetryPolicy {
     /** Number of retries after the initial attempt. The fleet default is 1. */
     count: number;
     /** Delay before each retry, in milliseconds. The fleet default is 2000. */
     delayMs: number;
+    /**
+     * Statuses that trigger a retry. Defaults to `[429]` — the historical
+     * fleet-wide behavior. Add transient 5xx codes (e.g. `[429, 500, 502, 503,
+     * 504]`) for upstreams that flake; an exhausted non-429 retried status
+     * surfaces through the normal non-2xx path (an {@link ApiError}).
+     */
+    statuses?: number[];
 }
 /** Options for {@link createApiClient}. */
 /**
@@ -46,6 +54,16 @@ export interface ApiClientOptions {
      * Optional when {@link ApiClientOptions.tokenManager} is provided.
      */
     getToken?: () => string | undefined | Promise<string | undefined>;
+    /**
+     * Send the token in this named request header instead of
+     * `Authorization: Bearer <token>`. The raw token is sent verbatim — no
+     * `Bearer ` prefix (e.g. `tokenHeader: 'x-goog-api-key'` /
+     * `'x-auth-token'` / `'x-api-key'`). Unset keeps the default
+     * `Authorization: Bearer` behavior. Applies to both
+     * {@link ApiClientOptions.getToken} and
+     * {@link ApiClientOptions.tokenManager} tokens.
+     */
+    tokenHeader?: string;
     /**
      * A reactive token source (e.g. `TokenManager`). When set, every request is
      * routed through {@link ReactiveTokenSource.withAuth} — proactive refresh +
@@ -130,6 +148,35 @@ export declare class RequestTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(service: string, timeoutMs: number);
 }
+/**
+ * Thrown by {@link ApiClient.fetchJson} / {@link ApiClient.fetchHtml} for a
+ * non-2xx response that isn't a 401/429 (those map to
+ * {@link UnauthorizedError} / {@link RateLimitedError}). The message is exactly
+ * the redacted, truncated {@link formatApiError} string the client has always
+ * thrown — this class only adds the `status` so callers can branch
+ * (`err instanceof ApiError && err.status === 404`) instead of regexing the
+ * message.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * A status-carrying HTTP error consumers can `throw new` directly — the
+ * directly-constructible parallel to {@link ApiError} (which is only thrown
+ * *inside* {@link createApiClient}). Extends {@link ApiError} so the same
+ * `err instanceof ApiError && err.status === 404` branch works for both, while
+ * its own name/`instanceof UpstreamHttpError` distinguishes the manual throws.
+ *
+ * Consolidates opentable's local `HttpError` and musescore's
+ * `MusescoreHttpError` — structural twins (status-carrying, thrown from a
+ * transport/bridge code path that doesn't go through `createApiClient`, used to
+ * branch on a 404 fallback). Repos that DO route through `createApiClient`
+ * already get {@link ApiError} for free and don't need this.
+ */
+export declare class UpstreamHttpError extends ApiError {
+    constructor(status: number, message: string);
+}
 /**
  * Build a bearer-auth fetch client with one-shot 429 retry, 401 mapping, 204 /
  * empty-body handling, and redacted error formatting.
@@ -198,15 +245,19 @@ export interface ParsedLinkHeader {
  * Consolidates canvas's pagination Link parser.
  */
 export declare function parseLinkHeader(header: string | null | undefined): ParsedLinkHeader;
-/** A parsed Set-Cookie jar: deduplicated name→value plus a ready `Cookie` header. */
-export interface CookieJar {
+/**
+ * A parsed Set-Cookie jar: deduplicated name→value plus a ready `Cookie`
+ * header. (Renamed from `CookieJar` to free that name for the stateful
+ * {@link CookieJar} class; no fleet consumer imported the type.)
+ */
+export interface ParsedCookieJar {
     /** Surviving cookies, name → value (last value wins, deletions removed). */
     cookies: Record<string, string>;
     /** Pre-joined `name=value; name2=value2` string for the `Cookie` request header. */
     cookieHeader: string;
 }
 /**
- * Parse `Set-Cookie` headers into a deduplicated {@link CookieJar}.
+ * Parse `Set-Cookie` headers into a deduplicated {@link ParsedCookieJar}.
  *
  * Login responses commonly send deletion markers (`Max-Age=0` or an epoch
  * `Expires`) alongside real cookies; forwarding both the delete and set form of
@@ -221,7 +272,62 @@ export interface CookieJar {
  *
  * Consolidates the IC/signupgenius cookie-jar logic.
  */
-export declare function parseCookieJar(setCookieHeaders: string[] | string | null | undefined): CookieJar;
+export declare function parseCookieJar(setCookieHeaders: string[] | string | null | undefined): ParsedCookieJar;
+/**
+ * Parse a *request* `Cookie:` header (`name=value; name2=value2`) into a
+ * name→value map. This is the inbound counterpart to {@link parseCookieJar},
+ * which parses *response* `Set-Cookie` headers (with their attributes and
+ * deletion semantics) — a `Cookie` header has no attributes, just pairs.
+ *
+ * Semantics (matching creditkarma's hand-rolled `extractCookieValue` ×3):
+ *  - splits on `;`, then on the FIRST `=` only, so a value containing `=`
+ *    (e.g. base64 padding `ab==`, or `x=y=z`) is preserved verbatim,
+ *  - trims surrounding whitespace from both name and value,
+ *  - skips fragments with no `=` (bare attributes) or an empty name (`=v`),
+ *  - keeps an empty value when the name is present (`a=` → `{ a: '' }`),
+ *  - on a duplicate name, the last value wins.
+ *
+ * A missing / empty / whitespace-only header yields `{}`.
+ *
+ * Consolidates creditkarma's `extractCookieValue` (single-name lookup ×3) and
+ * the cookie-header pattern-matching in two other repos: `extractCookieValue(h,
+ * name)` is `parseCookieHeader(h)[name] ?? null`.
+ */
+export declare function parseCookieHeader(header: string): Record<string, string>;
+/**
+ * Anything {@link CookieJar.absorb} can read `Set-Cookie`s from: the array from
+ * `Headers.getSetCookie()`, a single (possibly comma-joined) header string, or
+ * a `Headers`-like object (prefers `getSetCookie()`, falls back to splitting
+ * `get('set-cookie')` safely around `Expires` commas).
+ */
+export type SetCookieSource = string[] | string | null | undefined | {
+    getSetCookie?: () => string[];
+    get(name: string): string | null;
+};
+/**
+ * Stateful cookie jar for multi-step session logins (login page → CSRF prime →
+ * credential POST → API calls), built on the {@link parseCookieJar} semantics.
+ *
+ * Consolidates the five drifted hand-rolled jars across
+ * artsonia/canvas-parent/evite/signupgenius/skylight:
+ *  - `absorb` merges each response's `Set-Cookie`s into the jar — later values
+ *    override earlier ones by name, and deletion markers (`Max-Age <= 0` or a
+ *    pre-2000 `Expires`, both comma- and dash-format epochs) **remove** the
+ *    name from the jar,
+ *  - empty-value non-deletion cookies are ignored (an existing value survives),
+ *  - `header()` renders the `Cookie` request-header value in insertion order.
+ */
+export declare class CookieJar {
+    private readonly jar;
+    /** Merge `Set-Cookie`s into the jar (later wins; deletion markers remove). */
+    absorb(setCookies: SetCookieSource): void;
+    /** The current value of a cookie, or `undefined` when absent/deleted. */
+    get(name: string): string | undefined;
+    /** Render the `Cookie` request-header value: `name=value; name2=value2`. */
+    header(): string;
+    /** Number of cookies currently in the jar. */
+    get size(): number;
+}
 /**
  * Decode a JWT's `exp` claim (seconds since epoch). Throws when the structure is
  * invalid or `exp` is missing/non-numeric — the strict variant zola uses for the
@@ -235,6 +341,17 @@ export declare function decodeJwtExp(token: string): number;
  * header.
  */
 export declare function decodeJwtSessionId(token: string): string | null;
+/**
+ * Generic single-claim extractor for a JWT payload. Returns the raw claim
+ * value (`unknown` — cast or narrow at the call site), or `undefined` for an
+ * undecodable token or an absent claim. Never throws.
+ *
+ * Generalizes the hand-rolled per-claim readers across the fleet (e.g.
+ * creditkarma's `extractGlidFromJwt`): `decodeJwtClaim(token, 'glid')` instead
+ * of a bespoke decode + payload-field pluck. Reuses the same base64url payload
+ * decode as {@link decodeJwtExp} / {@link decodeJwtSessionId}.
+ */
+export declare function decodeJwtClaim(token: string, claim: string): unknown;
 /** Result of {@link validateJwtExpiry}. */
 export interface JwtExpiryStatus {
     /** True when the token is past its `exp` (or undecodable / lacks `exp`). */
@@ -254,4 +371,61 @@ export interface JwtExpiryStatus {
  * reporting `expired: false`, so callers can refresh proactively.
  */
 export declare function validateJwtExpiry(token: string, nowMs?: number): JwtExpiryStatus;
+/** Options for {@link runBoundedBatch}. */
+export interface RunBoundedBatchOptions<T, R> {
+    /**
+     * Overall hard deadline for the WHOLE batch, in milliseconds. When it fires,
+     * any item that hasn't settled is filled by {@link onTimeout} and the batch
+     * returns immediately — unsettled workers are abandoned (left to settle in
+     * the background, never awaited), so a permanently-hung item can't wedge the
+     * call past this bound.
+     */
+    deadlineMs: number;
+    /**
+     * Backfill for an item the deadline cut off before it settled. Receives the
+     * original `item` and its `index` so the placeholder stays identifiable and
+     * re-runnable (the zillow `pending`-row pattern). Called only for unsettled
+     * slots.
+     */
+    onTimeout: (item: T, index: number) => R;
+    /**
+     * Backfill for an item whose `worker` REJECTED (threw). A worker error is
+     * isolated to its own slot — it never rejects the batch or cascades onto
+     * other items. Defaults to `onTimeout(item, index)` (a rejected worker is
+     * treated like a timeout) so a caller that doesn't care needn't distinguish;
+     * supply `onError` to tell a genuine failure apart from a deadline cutoff.
+     */
+    onError?: (item: T, index: number, err: unknown) => R;
+    /**
+     * Max workers in flight at once. Defaults to unbounded (all items started
+     * immediately). Use it to bound fan-out against a rate-limited upstream.
+     */
+    concurrency?: number;
+    /**
+     * Injectable timer (for tests). Defaults to `setTimeout`. Must invoke `cb`
+     * after roughly `ms`, returning a handle passed to {@link clearTimer}.
+     */
+    setTimer?: (ms: number, cb: () => void) => unknown;
+    /** Injectable clear paired with {@link setTimer}. Defaults to `clearTimeout`. */
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Run `worker` over `items` with an overall hard deadline and a per-item
+ * timeout-backfill, returning a full-length, input-ordered array with exactly
+ * one result per item.
+ *
+ * Each item gets an index-addressable slot. Work is raced against `deadlineMs`;
+ * when the deadline fires first, every still-unsettled slot is filled by
+ * `onTimeout(item, index)` and the batch resolves immediately — the in-flight
+ * workers are abandoned (and signalled via their `AbortSignal`) rather than
+ * awaited, so a single hung row can't keep the whole call (and the MCP request
+ * deadline behind it) pinned open. When everything settles before the deadline,
+ * the timer is cleared and every slot holds its real result.
+ *
+ * Generalises zillow's bulk-tool `runWithDeadline` (`zillow_bulk_get` /
+ * `zillow_resolve_addresses`, issues #98/#78): the slot-array + overall-deadline
+ * + `pending`-backfill shape, now with the worker + concurrency folded in and an
+ * injectable timer for deterministic tests.
+ */
+export declare function runBoundedBatch<T, R>(items: T[], worker: (item: T, signal?: AbortSignal) => Promise<R>, opts: RunBoundedBatchOptions<T, R>): Promise<R[]>;
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

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

package/dist/http/index.js

@@ -17,6 +17,7 @@
  *    yields a fixed "unauthorized" string, not the credential.
  */
 import { truncateErrorMessage } from '../errors/index.js';
+export * from './throttle.js';
 const DEFAULT_RETRY = { count: 1, delayMs: 2000 };
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Thrown for an upstream 401. Carries the status so callers can trigger a re-auth. */
@@ -47,6 +48,44 @@ export class RequestTimeoutError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * Thrown by {@link ApiClient.fetchJson} / {@link ApiClient.fetchHtml} for a
+ * non-2xx response that isn't a 401/429 (those map to
+ * {@link UnauthorizedError} / {@link RateLimitedError}). The message is exactly
+ * the redacted, truncated {@link formatApiError} string the client has always
+ * thrown — this class only adds the `status` so callers can branch
+ * (`err instanceof ApiError && err.status === 404`) instead of regexing the
+ * message.
+ */
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * A status-carrying HTTP error consumers can `throw new` directly — the
+ * directly-constructible parallel to {@link ApiError} (which is only thrown
+ * *inside* {@link createApiClient}). Extends {@link ApiError} so the same
+ * `err instanceof ApiError && err.status === 404` branch works for both, while
+ * its own name/`instanceof UpstreamHttpError` distinguishes the manual throws.
+ *
+ * Consolidates opentable's local `HttpError` and musescore's
+ * `MusescoreHttpError` — structural twins (status-carrying, thrown from a
+ * transport/bridge code path that doesn't go through `createApiClient`, used to
+ * branch on a 404 fallback). Repos that DO route through `createApiClient`
+ * already get {@link ApiError} for free and don't need this.
+ */
+export class UpstreamHttpError extends ApiError {
+    constructor(status, message) {
+        super(status, message);
+        this.name = 'UpstreamHttpError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 function hostOf(baseUrl) {
     try {
         return new URL(baseUrl).host;
@@ -74,7 +113,11 @@ export function createApiClient(opts) {
     const sleep = opts.sleep ?? defaultSleep;
     const unauthorized = () => (opts.onUnauthorized ? opts.onUnauthorized() : new UnauthorizedError(service));
     const rateLimited = () => (opts.onRateLimited ? opts.onRateLimited() : new RateLimitedError(service));
+    const retryStatuses = retry.statuses ?? [429];
     const timeoutMs = opts.timeout;
+    // Default: `Authorization: Bearer <token>`. With `tokenHeader`, the raw
+    // token goes in that named header instead (no `Bearer ` prefix).
+    const authHeader = (token) => !token ? {} : opts.tokenHeader ? { [opts.tokenHeader]: token } : { Authorization: `Bearer ${token}` };
     // Bound `run` with an AbortController when a timeout is configured, mapping the
     // abort to a RequestTimeoutError. No timeout → run as-is (no signal).
     function withTimeout(run) {
@@ -106,7 +149,7 @@ export function createApiClient(opts) {
                 Accept: 'application/json',
                 ...(hasJsonBody ? { 'Content-Type': 'application/json' } : {}),
                 ...opts.baseHeaders,
-                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                ...authHeader(token || undefined),
                 ...opt.headers,
             },
             ...(signal ? { signal } : {}),
@@ -122,7 +165,7 @@ export function createApiClient(opts) {
         // attempt 0 is the initial request; up to `retry.count` further attempts on 429.
         for (;;) {
             const res = await once();
-            if (res.status === 429 && attempt < retry.count) {
+            if (retryStatuses.includes(res.status) && attempt < retry.count) {
                 attempt += 1;
                 await sleep(retry.delayMs);
                 continue;
@@ -140,7 +183,7 @@ export function createApiClient(opts) {
             return undefined;
         const text = await res.text();
         if (!res.ok) {
-            throw new Error(formatApiError(res.status, method, path, text, { service }));
+            throw new ApiError(res.status, formatApiError(res.status, method, path, text, { service }));
         }
         if (text.length === 0)
             return undefined;
@@ -155,7 +198,7 @@ export function createApiClient(opts) {
             throw rateLimited();
         const text = await res.text();
         if (!res.ok) {
-            throw new Error(formatApiError(res.status, method, path, text, { service }));
+            throw new ApiError(res.status, formatApiError(res.status, method, path, text, { service }));
         }
         return text;
     }
@@ -247,10 +290,41 @@ export function parseLinkHeader(header) {
     }
     return out;
 }
-const MAX_AGE_ZERO_RE = /(?:^|;)\s*Max-Age\s*=\s*0\s*(?:;|$)/i;
-const EXPIRES_EPOCH_RE = /(?:^|;)\s*Expires\s*=\s*Thu,\s*01\s*Jan\s*1970/i;
+const MAX_AGE_RE = /(?:^|;)\s*Max-Age\s*=\s*(-?\d+)\s*(?:;|$)/i;
+const EXPIRES_RE = /(?:^|;)\s*Expires\s*=\s*([^;]+)/i;
+/** `Expires` dates before this year are treated as deletion markers. Fixed (not
+ * `Date.now()`-relative) so parsing stays deterministic; real session cookies
+ * are never legitimately set to expire in the previous millennium. */
+const EXPIRES_DELETION_YEAR = 2000;
+/**
+ * True when a `Set-Cookie` entry is a deletion marker: `Max-Age <= 0`
+ * (including the common `Max-Age=-1`), or — when no `Max-Age` is present
+ * (RFC 6265 §5.3: `Max-Age` outranks `Expires`) — an `Expires` date that
+ * parses to before {@link EXPIRES_DELETION_YEAR}. Both RFC 1123
+ * (`Thu, 01 Jan 1970`) and the legacy dash format (`Thu, 01-Jan-1970`) parse.
+ */
+function isDeletionCookie(entry) {
+    const maxAge = MAX_AGE_RE.exec(entry);
+    if (maxAge)
+        return Number(maxAge[1]) <= 0;
+    const expires = EXPIRES_RE.exec(entry);
+    if (expires && expires[1]) {
+        const when = new Date(expires[1].trim());
+        if (!Number.isNaN(when.getTime()))
+            return when.getUTCFullYear() < EXPIRES_DELETION_YEAR;
+    }
+    return false;
+}
+/** Parse the leading `name=value` pair of a `Set-Cookie` entry (attrs ignored). */
+function parseNameValue(entry) {
+    const nameValue = (entry.split(';')[0] ?? '').trim();
+    const eqIdx = nameValue.indexOf('=');
+    if (eqIdx < 1)
+        return null;
+    return { name: nameValue.slice(0, eqIdx).trim(), value: nameValue.slice(eqIdx + 1).trim() };
+}
 /**
- * Parse `Set-Cookie` headers into a deduplicated {@link CookieJar}.
+ * Parse `Set-Cookie` headers into a deduplicated {@link ParsedCookieJar}.
  *
  * Login responses commonly send deletion markers (`Max-Age=0` or an epoch
  * `Expires`) alongside real cookies; forwarding both the delete and set form of
@@ -266,24 +340,15 @@ const EXPIRES_EPOCH_RE = /(?:^|;)\s*Expires\s*=\s*Thu,\s*01\s*Jan\s*1970/i;
  * Consolidates the IC/signupgenius cookie-jar logic.
  */
 export function parseCookieJar(setCookieHeaders) {
-    const entries = setCookieHeaders == null
-        ? []
-        : Array.isArray(setCookieHeaders)
-            ? setCookieHeaders
-            : splitSetCookie(setCookieHeaders);
+    const entries = setCookieEntries(setCookieHeaders);
     const jar = new Map();
     for (const entry of entries) {
-        if (MAX_AGE_ZERO_RE.test(entry) || EXPIRES_EPOCH_RE.test(entry))
+        if (isDeletionCookie(entry))
             continue;
-        const nameValue = (entry.split(';')[0] ?? '').trim();
-        const eqIdx = nameValue.indexOf('=');
-        if (eqIdx < 1)
+        const pair = parseNameValue(entry);
+        if (!pair || !pair.value)
             continue;
-        const name = nameValue.slice(0, eqIdx).trim();
-        const value = nameValue.slice(eqIdx + 1).trim();
-        if (!value)
-            continue;
-        jar.set(name, value);
+        jar.set(pair.name, pair.value);
     }
     const cookies = {};
     for (const [k, v] of jar)
@@ -291,6 +356,100 @@ export function parseCookieJar(setCookieHeaders) {
     const cookieHeader = [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
     return { cookies, cookieHeader };
 }
+// ---------------------------------------------------------------------------
+// parseCookieHeader
+// ---------------------------------------------------------------------------
+/**
+ * Parse a *request* `Cookie:` header (`name=value; name2=value2`) into a
+ * name→value map. This is the inbound counterpart to {@link parseCookieJar},
+ * which parses *response* `Set-Cookie` headers (with their attributes and
+ * deletion semantics) — a `Cookie` header has no attributes, just pairs.
+ *
+ * Semantics (matching creditkarma's hand-rolled `extractCookieValue` ×3):
+ *  - splits on `;`, then on the FIRST `=` only, so a value containing `=`
+ *    (e.g. base64 padding `ab==`, or `x=y=z`) is preserved verbatim,
+ *  - trims surrounding whitespace from both name and value,
+ *  - skips fragments with no `=` (bare attributes) or an empty name (`=v`),
+ *  - keeps an empty value when the name is present (`a=` → `{ a: '' }`),
+ *  - on a duplicate name, the last value wins.
+ *
+ * A missing / empty / whitespace-only header yields `{}`.
+ *
+ * Consolidates creditkarma's `extractCookieValue` (single-name lookup ×3) and
+ * the cookie-header pattern-matching in two other repos: `extractCookieValue(h,
+ * name)` is `parseCookieHeader(h)[name] ?? null`.
+ */
+export function parseCookieHeader(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(';')) {
+        const eqIdx = part.indexOf('=');
+        if (eqIdx < 0)
+            continue; // bare attribute fragment, no `=`
+        const name = part.slice(0, eqIdx).trim();
+        if (name === '')
+            continue; // missing name (leading `=`)
+        out[name] = part.slice(eqIdx + 1).trim();
+    }
+    return out;
+}
+/** Normalize a {@link SetCookieSource} to individual `Set-Cookie` strings. */
+function setCookieEntries(source) {
+    if (source == null)
+        return [];
+    if (Array.isArray(source))
+        return source;
+    if (typeof source === 'string')
+        return splitSetCookie(source);
+    if (typeof source.getSetCookie === 'function')
+        return source.getSetCookie();
+    const joined = source.get('set-cookie');
+    return joined ? splitSetCookie(joined) : [];
+}
+/**
+ * Stateful cookie jar for multi-step session logins (login page → CSRF prime →
+ * credential POST → API calls), built on the {@link parseCookieJar} semantics.
+ *
+ * Consolidates the five drifted hand-rolled jars across
+ * artsonia/canvas-parent/evite/signupgenius/skylight:
+ *  - `absorb` merges each response's `Set-Cookie`s into the jar — later values
+ *    override earlier ones by name, and deletion markers (`Max-Age <= 0` or a
+ *    pre-2000 `Expires`, both comma- and dash-format epochs) **remove** the
+ *    name from the jar,
+ *  - empty-value non-deletion cookies are ignored (an existing value survives),
+ *  - `header()` renders the `Cookie` request-header value in insertion order.
+ */
+export class CookieJar {
+    jar = new Map();
+    /** Merge `Set-Cookie`s into the jar (later wins; deletion markers remove). */
+    absorb(setCookies) {
+        for (const entry of setCookieEntries(setCookies)) {
+            const pair = parseNameValue(entry);
+            if (!pair)
+                continue;
+            if (isDeletionCookie(entry)) {
+                this.jar.delete(pair.name);
+                continue;
+            }
+            if (!pair.value)
+                continue;
+            this.jar.set(pair.name, pair.value);
+        }
+    }
+    /** The current value of a cookie, or `undefined` when absent/deleted. */
+    get(name) {
+        return this.jar.get(name);
+    }
+    /** Render the `Cookie` request-header value: `name=value; name2=value2`. */
+    header() {
+        return [...this.jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+    /** Number of cookies currently in the jar. */
+    get size() {
+        return this.jar.size;
+    }
+}
 /** Best-effort split of a single joined `set-cookie` string (no `getSetCookie()`). */
 function splitSetCookie(header) {
     // Split on commas that are NOT part of an Expires date ("Thu, 01 Jan ...").
@@ -349,6 +508,22 @@ export function decodeJwtSessionId(token) {
     const sid = payload['session_id'] ?? payload['sid'];
     return typeof sid === 'string' ? sid : null;
 }
+/**
+ * Generic single-claim extractor for a JWT payload. Returns the raw claim
+ * value (`unknown` — cast or narrow at the call site), or `undefined` for an
+ * undecodable token or an absent claim. Never throws.
+ *
+ * Generalizes the hand-rolled per-claim readers across the fleet (e.g.
+ * creditkarma's `extractGlidFromJwt`): `decodeJwtClaim(token, 'glid')` instead
+ * of a bespoke decode + payload-field pluck. Reuses the same base64url payload
+ * decode as {@link decodeJwtExp} / {@link decodeJwtSessionId}.
+ */
+export function decodeJwtClaim(token, claim) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return undefined;
+    return payload[claim];
+}
 /** Tokens within this many seconds of `exp` are flagged as near-expiry. */
 const NEAR_EXPIRY_SKEW_SEC = 300;
 /**
@@ -380,4 +555,88 @@ export function validateJwtExpiry(token, nowMs = Date.now()) {
     }
     return { expired: false, expiresIn };
 }
+/**
+ * Run `worker` over `items` with an overall hard deadline and a per-item
+ * timeout-backfill, returning a full-length, input-ordered array with exactly
+ * one result per item.
+ *
+ * Each item gets an index-addressable slot. Work is raced against `deadlineMs`;
+ * when the deadline fires first, every still-unsettled slot is filled by
+ * `onTimeout(item, index)` and the batch resolves immediately — the in-flight
+ * workers are abandoned (and signalled via their `AbortSignal`) rather than
+ * awaited, so a single hung row can't keep the whole call (and the MCP request
+ * deadline behind it) pinned open. When everything settles before the deadline,
+ * the timer is cleared and every slot holds its real result.
+ *
+ * Generalises zillow's bulk-tool `runWithDeadline` (`zillow_bulk_get` /
+ * `zillow_resolve_addresses`, issues #98/#78): the slot-array + overall-deadline
+ * + `pending`-backfill shape, now with the worker + concurrency folded in and an
+ * injectable timer for deterministic tests.
+ */
+export function runBoundedBatch(items, worker, opts) {
+    const slots = Array.from({ length: items.length });
+    const settled = new Array(items.length).fill(false);
+    // An item whose worker threw: backfilled via onError (default onTimeout) at
+    // finish, distinct from a slot the deadline simply never reached.
+    const errored = new Array(items.length).fill(false);
+    const errorVals = new Array(items.length);
+    // Nothing to do — never arm a timer for an empty batch.
+    if (items.length === 0)
+        return Promise.resolve([]);
+    const setTimer = opts.setTimer ?? ((ms, cb) => setTimeout(cb, ms));
+    const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+    const controller = new AbortController();
+    // Bounded fan-out: a pool of `limit` runners pulling the next index off a
+    // shared cursor. limit >= items.length (or unset) means "all at once".
+    const limit = opts.concurrency && opts.concurrency > 0
+        ? Math.min(opts.concurrency, items.length)
+        : items.length;
+    const runAll = async () => {
+        let cursor = 0;
+        const runner = async () => {
+            for (;;) {
+                const index = cursor;
+                cursor += 1;
+                if (index >= items.length)
+                    return;
+                // Isolate a worker rejection to its own slot: record it and continue
+                // pulling the next item, so one bad row neither rejects the batch nor
+                // strands the items this runner hasn't reached yet.
+                try {
+                    slots[index] = await worker(items[index], controller.signal);
+                    settled[index] = true;
+                }
+                catch (err) {
+                    errored[index] = true;
+                    errorVals[index] = err;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: limit }, () => runner()));
+    };
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimer(handle);
+            // Signal abandoned workers so a cooperative worker can stop early.
+            if (!controller.signal.aborted)
+                controller.abort();
+            const onError = opts.onError ?? ((item, index) => opts.onTimeout(item, index));
+            resolve(items.map((item, index) => {
+                if (settled[index])
+                    return slots[index];
+                if (errored[index])
+                    return onError(item, index, errorVals[index]);
+                return opts.onTimeout(item, index);
+            }));
+        };
+        const handle = setTimer(opts.deadlineMs, finish);
+        // Abandon (never await) the fan-out on the deadline path; on full settle,
+        // finish() clears the timer and returns the real results.
+        void runAll().then(finish, finish);
+    });
+}
 //# sourceMappingURL=index.js.map