@usequeek/app-sdk 0.4.0

package/dist/tokens.d.ts

@@ -0,0 +1,162 @@
+import { type AppCredential } from "./app-auth.js";
+import { QueekApiError, type QueekClient } from "./client.js";
+import { type Logger } from "./logger.js";
+import type { InstallationStore } from "./store.js";
+/**
+ * Installation tokens (S1, SDK 0.2.0): the app holds ONE asymmetric app
+ * credential and mints short-lived installation tokens from Queek on
+ * demand, cached (encrypted) in its own database to near-expiry.
+ *
+ * - `acquireToken(installationId)`: cached-valid token (expiry more than 5
+ *   minutes away) → else sign an app JWT → `POST access_tokens` → persist
+ *   (encrypted, expires_at, kid) → return. Every Queek API call in the
+ *   installation client goes through it.
+ * - A merchant-API token refusal → drop it, re-mint once, retry once; a
+ *   second refusal propagates. Token refusal = any 401, or a 403 with
+ *   `api_key_revoked` / `api_key_expired` / `invalid_client_key` (rev 7).
+ *   A merchant 403 `app_token_revoked` is the app-wide kill switch (drop
+ *   all + halt, no mint); any other merchant 403 (scope, plan, mode)
+ *   propagates untouched. (If the re-mint itself hits `invalid_client` /
+ *   kill-switch / gone, the mint path below applies those rules.)
+ * - Concurrent callers in one process share ONE in-flight mint per
+ *   installation (single-flight). Across containers two mints are harmless
+ *   by design: Queek keeps coexisting tokens valid (K=2 slots) and the
+ *   last write wins the shared cache row; a residual race self-heals via
+ *   re-mint on 401.
+ * - Error handling exactly per the wire contract: 401 `invalid_client`
+ *   halts minting app-wide (loud log, no retry loop); 403 kill-switch
+ *   drops ALL cached tokens and halts; 404 `app_installation_gone` purges
+ *   the installation; 409 `app_installation_pending` retries later with
+ *   backoff — NEVER purges, NEVER halts (the persisted pending mark keeps
+ *   the row through restarts and resync's purge-absent step); 429 honors
+ *   `Retry-After` +
+ *   jitter with bounded retries; 5xx/network bounded exponential backoff.
+ */
+/** Path of the app-credential API below the store host. */
+export declare const APP_API_PATH = "/api/v1/apps";
+/** Minimal surface the installation client needs (stubs stay one-liners). */
+export interface AppTokens {
+    acquireToken(installationId: string): Promise<string>;
+    dropCachedToken(installationId: string): Promise<void>;
+    /**
+     * Kill-switch path: forget EVERY cached token for the app and halt
+     * minting (loud log inside). Called on a merchant 403 `app_token_revoked`.
+     */
+    revokeAppAccess(): Promise<void>;
+}
+export interface TokenProviderOptions {
+    credential: AppCredential;
+    store: InstallationStore;
+    fetchImpl?: typeof fetch;
+    /** Sent as User-Agent on app-API calls. Defaults to `queek-app/1.0`. */
+    userAgent?: string;
+    /** Extra allowed `apiBase` hosts (test/local backends). */
+    allowedApiHosts?: string[];
+    /** Loud halt/drop logs go here. Defaults to a `queek-app-tokens` logger (stderr on warn+). */
+    logger?: Logger;
+    /** Injectable clock (ms since epoch). Defaults to `Date.now`. */
+    nowMs?: () => number;
+    /** Injectable sleep for tests. Defaults to a real setTimeout sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable uniform [0,1) for jitter. Defaults to `Math.random`. */
+    random?: () => number;
+}
+/**
+ * Validate the handoff `apiBase` (https + allowlist, same rules as the
+ * merchant client) and normalize it to the app-API base
+ * (`<origin>/api/v1/apps`). Throws `InvalidApiBaseError` before any fetch.
+ */
+export declare function resolveAppApiBase(raw: string, allowedApiHosts?: string[]): string;
+export declare function mintPath(installationId: string): string;
+export declare class AppTokenProvider implements AppTokens {
+    private readonly credential;
+    private readonly store;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly allowedApiHosts;
+    private readonly logger;
+    private readonly nowMs;
+    private readonly sleep;
+    private readonly random;
+    private readonly inflight;
+    private halted;
+    constructor(options: TokenProviderOptions);
+    /** True while minting is halted app-wide (`invalid_client` or kill switch). */
+    isHalted(): boolean;
+    /**
+     * Clear a halt (e.g. the key was fixed / the app re-enabled). A process
+     * restart clears it too — the halt is in-process only.
+     */
+    resumeMinting(): void;
+    acquireToken(installationId: string): Promise<string>;
+    private acquireUnshared;
+    private isFresh;
+    dropCachedToken(installationId: string): Promise<void>;
+    /** Kill-switch path (also used by ops): forget every cached token, keep the rows. */
+    dropAllCachedTokens(): Promise<void>;
+    /**
+     * Persist the 409 `app_installation_pending` mark for this installation
+     * (store column — survives restarts, B2 review r2). Resync's purge-absent
+     * step keeps marked rows (the list covers active installations only).
+     * Called by the mint path and by `resyncFromQueek`; idempotent, and a
+     * no-op when the row is already gone.
+     */
+    markInstallationPending(installationId: string): Promise<void>;
+    /**
+     * Clear the persisted pending mark: the installation answered active
+     * again (mint success, resync 202/redelivery).
+     */
+    clearInstallationPending(installationId: string): Promise<void>;
+    /**
+     * True when the row carries the persisted pending mark. Consulted by
+     * resync's purge-absent step; false when the row is missing.
+     */
+    isKnownPending(installationId: string): Promise<boolean>;
+    /**
+     * Kill-switch path from any surface (mint 403, merchant 403, ops):
+     * forget EVERY cached token for the app and halt minting, loudly.
+     * Clears on process restart or `resumeMinting()`.
+     */
+    revokeAppAccess(): Promise<void>;
+    /** Sign a fresh app JWT (exposed for the app-API calls in `resync.ts`). */
+    signJwt(nowSeconds?: number): string;
+    /**
+     * Map an app-endpoint failure to its contract behavior. ALWAYS throws:
+     * the halted error, or the original `QueekApiError` after performing the
+     * side effect (drop-all / purge). `installationPid` is log-only.
+     */
+    handleAppEndpointError(error: QueekApiError, installation: {
+        id: string;
+        pid: string;
+    }): Promise<never>;
+    private mintWithRetry;
+    private jittered;
+    private mintOnce;
+}
+/** Create a provider in one call (thin wrapper over `new AppTokenProvider`). */
+export declare function createAppTokenProvider(options: TokenProviderOptions): AppTokenProvider;
+export interface InstallationClientOptions {
+    installationId: string;
+    /** Handoff `api_base` (bare store host or full merchant base). Validated at construction. */
+    apiBase: string;
+    tokens: AppTokens;
+    fetchImpl?: typeof fetch;
+    /** Sent as User-Agent. Defaults to `queek-app/1.0`. */
+    userAgent?: string;
+    /** Extra allowed `apiBase` hosts (test/local backends). */
+    allowedApiHosts?: string[];
+}
+/**
+ * A `QueekClient` whose every call goes through `acquireToken()`: the
+ * installation token is resolved per request (usually a cache hit — the
+ * store IS the cache, one shared row per installation), sent as
+ * `X-Client-Key`, and on a merchant-API token refusal (any 401, or 403
+ * `api_key_revoked` / `api_key_expired` / `invalid_client_key`) it is
+ * dropped, re-minted once, and the call retried once; a second refusal
+ * propagates to the caller. A merchant 403 `app_token_revoked` drops all
+ * cached tokens and halts minting; any other 403 propagates without a
+ * mint. 429/network retries (`requestWithRetry`) reuse one idempotency key
+ * exactly like the static client.
+ */
+export declare function createInstallationClient(options: InstallationClientOptions): QueekClient;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

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

package/dist/tokens.js

@@ -0,0 +1,411 @@
+import { APP_TOKEN_REVOKED_CODE, AppMintHaltedError, INVALID_CLIENT_CODE, isAppTokenRevoked, isInstallationGone, isInstallationPending, isTokenRefusal, MAX_MINT_ATTEMPTS, MINT_BACKOFF_BASE_MS, MINT_BACKOFF_MAX_MS, RETRY_JITTER_MAX_MS, signAppJwt, TOKEN_VALIDITY_SKEW_SECONDS, UnknownInstallationError, } from "./app-auth.js";
+import { createQueekClient, MERCHANT_API_PATH, QueekApiError, queekApiErrorFromResponse, resolveApiBase, } from "./client.js";
+import { createLogger } from "./logger.js";
+/**
+ * Installation tokens (S1, SDK 0.2.0): the app holds ONE asymmetric app
+ * credential and mints short-lived installation tokens from Queek on
+ * demand, cached (encrypted) in its own database to near-expiry.
+ *
+ * - `acquireToken(installationId)`: cached-valid token (expiry more than 5
+ *   minutes away) → else sign an app JWT → `POST access_tokens` → persist
+ *   (encrypted, expires_at, kid) → return. Every Queek API call in the
+ *   installation client goes through it.
+ * - A merchant-API token refusal → drop it, re-mint once, retry once; a
+ *   second refusal propagates. Token refusal = any 401, or a 403 with
+ *   `api_key_revoked` / `api_key_expired` / `invalid_client_key` (rev 7).
+ *   A merchant 403 `app_token_revoked` is the app-wide kill switch (drop
+ *   all + halt, no mint); any other merchant 403 (scope, plan, mode)
+ *   propagates untouched. (If the re-mint itself hits `invalid_client` /
+ *   kill-switch / gone, the mint path below applies those rules.)
+ * - Concurrent callers in one process share ONE in-flight mint per
+ *   installation (single-flight). Across containers two mints are harmless
+ *   by design: Queek keeps coexisting tokens valid (K=2 slots) and the
+ *   last write wins the shared cache row; a residual race self-heals via
+ *   re-mint on 401.
+ * - Error handling exactly per the wire contract: 401 `invalid_client`
+ *   halts minting app-wide (loud log, no retry loop); 403 kill-switch
+ *   drops ALL cached tokens and halts; 404 `app_installation_gone` purges
+ *   the installation; 409 `app_installation_pending` retries later with
+ *   backoff — NEVER purges, NEVER halts (the persisted pending mark keeps
+ *   the row through restarts and resync's purge-absent step); 429 honors
+ *   `Retry-After` +
+ *   jitter with bounded retries; 5xx/network bounded exponential backoff.
+ */
+/** Path of the app-credential API below the store host. */
+export const APP_API_PATH = "/api/v1/apps";
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Validate the handoff `apiBase` (https + allowlist, same rules as the
+ * merchant client) and normalize it to the app-API base
+ * (`<origin>/api/v1/apps`). Throws `InvalidApiBaseError` before any fetch.
+ */
+export function resolveAppApiBase(raw, allowedApiHosts = []) {
+    const merchant = resolveApiBase(raw, allowedApiHosts);
+    return `${merchant.slice(0, merchant.length - MERCHANT_API_PATH.length)}${APP_API_PATH}`;
+}
+export function mintPath(installationId) {
+    return `/installations/${encodeURIComponent(installationId)}/access_tokens`;
+}
+export class AppTokenProvider {
+    credential;
+    store;
+    fetchImpl;
+    userAgent;
+    allowedApiHosts;
+    logger;
+    nowMs;
+    sleep;
+    random;
+    inflight = new Map();
+    halted = null;
+    constructor(options) {
+        this.credential = options.credential;
+        this.store = options.store;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.userAgent = options.userAgent ?? "queek-app/1.0";
+        this.allowedApiHosts = options.allowedApiHosts ?? [];
+        this.logger = options.logger ?? createLogger({ service: "queek-app-tokens" });
+        this.nowMs = options.nowMs ?? Date.now;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.random = options.random ?? Math.random;
+    }
+    /** True while minting is halted app-wide (`invalid_client` or kill switch). */
+    isHalted() {
+        return this.halted !== null;
+    }
+    /**
+     * Clear a halt (e.g. the key was fixed / the app re-enabled). A process
+     * restart clears it too — the halt is in-process only.
+     */
+    resumeMinting() {
+        this.halted = null;
+    }
+    async acquireToken(installationId) {
+        const shared = this.inflight.get(installationId);
+        if (shared)
+            return shared;
+        const attempt = this.acquireUnshared(installationId);
+        this.inflight.set(installationId, attempt);
+        try {
+            return await attempt;
+        }
+        finally {
+            this.inflight.delete(installationId);
+        }
+    }
+    async acquireUnshared(installationId) {
+        const row = await this.store.getInstallation(installationId);
+        if (!row)
+            throw new UnknownInstallationError(installationId);
+        // Cache serves even while halted: a bad app key (or a kill switch)
+        // stops MINTING, but tokens minted before it stay usable on the
+        // merchant API until they expire.
+        if (row.token !== null && row.tokenExpiresAt !== null && this.isFresh(row.tokenExpiresAt)) {
+            return row.token;
+        }
+        if (this.halted)
+            throw this.halted;
+        const minted = await this.mintWithRetry(row.apiBase, installationId, row.installationPid);
+        // A successful mint proves the installation is active again: persist
+        // the fresh token and clear the pending mark in the same write.
+        await this.store.saveInstallation({
+            ...row,
+            token: minted.token,
+            tokenExpiresAt: minted.expiresAt,
+            tokenKid: minted.kid,
+            pending: false,
+            updatedAt: new Date(this.nowMs()).toISOString(),
+        });
+        return minted.token;
+    }
+    isFresh(expiresAtIso) {
+        const expiresMs = Date.parse(expiresAtIso);
+        if (Number.isNaN(expiresMs))
+            return false;
+        return expiresMs - this.nowMs() > TOKEN_VALIDITY_SKEW_SECONDS * 1000;
+    }
+    async dropCachedToken(installationId) {
+        await this.store.clearCachedToken(installationId);
+    }
+    /** Kill-switch path (also used by ops): forget every cached token, keep the rows. */
+    async dropAllCachedTokens() {
+        await this.store.clearAllCachedTokens();
+    }
+    /**
+     * Persist the 409 `app_installation_pending` mark for this installation
+     * (store column — survives restarts, B2 review r2). Resync's purge-absent
+     * step keeps marked rows (the list covers active installations only).
+     * Called by the mint path and by `resyncFromQueek`; idempotent, and a
+     * no-op when the row is already gone.
+     */
+    async markInstallationPending(installationId) {
+        await this.store.markInstallationPending(installationId);
+    }
+    /**
+     * Clear the persisted pending mark: the installation answered active
+     * again (mint success, resync 202/redelivery).
+     */
+    async clearInstallationPending(installationId) {
+        await this.store.clearInstallationPending(installationId);
+    }
+    /**
+     * True when the row carries the persisted pending mark. Consulted by
+     * resync's purge-absent step; false when the row is missing.
+     */
+    async isKnownPending(installationId) {
+        return this.store.isKnownPending(installationId);
+    }
+    /**
+     * Kill-switch path from any surface (mint 403, merchant 403, ops):
+     * forget EVERY cached token for the app and halt minting, loudly.
+     * Clears on process restart or `resumeMinting()`.
+     */
+    async revokeAppAccess() {
+        await this.store.clearAllCachedTokens();
+        this.halted = new AppMintHaltedError(APP_TOKEN_REVOKED_CODE, "Queek revoked this app's access (kill switch or disabled app). " +
+            "All cached tokens dropped. Re-enable the app, then restart (or resumeMinting).");
+        this.logger.error("queek app minting halted: access revoked (kill switch / disabled)", {
+            code: APP_TOKEN_REVOKED_CODE,
+        });
+    }
+    /** Sign a fresh app JWT (exposed for the app-API calls in `resync.ts`). */
+    signJwt(nowSeconds) {
+        return signAppJwt({ credential: this.credential, nowSeconds });
+    }
+    /**
+     * Map an app-endpoint failure to its contract behavior. ALWAYS throws:
+     * the halted error, or the original `QueekApiError` after performing the
+     * side effect (drop-all / purge). `installationPid` is log-only.
+     */
+    async handleAppEndpointError(error, installation) {
+        if (error.status === 401) {
+            // The wire contract defines 401 on app endpoints as `invalid_client`
+            // (bad/expired JWT, unknown kid): fatal for the app regardless of the
+            // exact code string — retry-looping a refused identity is never right.
+            this.halted = new AppMintHaltedError(INVALID_CLIENT_CODE, `Queek refused the app credential (status 401, code ${JSON.stringify(error.code)}). ` +
+                `Fix APP_PRIVATE_KEY/APP_KEY_ID or re-register, then restart (or resumeMinting).`);
+            this.logger.error("queek app minting halted: invalid_client", {
+                installation: installation.pid,
+                code: error.code,
+            });
+            throw this.halted;
+        }
+        if (error.status === 403 && isAppTokenRevoked(error.code)) {
+            await this.revokeAppAccess();
+            throw this.halted;
+        }
+        if (error.status === 404 && isInstallationGone(error.code)) {
+            // The row's deletion drops its pending mark with it — a gone
+            // installation is never "pending".
+            await this.store.deleteInstallation(installation.id);
+            this.logger.warn("queek installation gone server-side; purged locally", {
+                installation: installation.pid,
+            });
+        }
+        // NOTE: 409 `app_installation_pending` never reaches here as a purge
+        // or halt — the mint loop retries it with backoff below, and resync
+        // handles it per installation. A pending row is marked, never deleted.
+        throw error;
+    }
+    async mintWithRetry(apiBase, installationId, installationPid) {
+        const appBase = resolveAppApiBase(apiBase, this.allowedApiHosts);
+        let lastError;
+        for (let attempt = 0; attempt < MAX_MINT_ATTEMPTS; attempt++) {
+            try {
+                return await this.mintOnce(appBase, installationId, installationPid);
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof QueekApiError))
+                    throw error;
+                // Contract-mapped failures throw their final error from inside
+                // `handleAppEndpointError` (halt/drop/purge already performed).
+                if (error.status === 401 || error.status === 404 || error.status === 403) {
+                    await this.handleAppEndpointError(error, { id: installationId, pid: installationPid });
+                }
+                if (error.status === 409 && isInstallationPending(error.code)) {
+                    // Pending installation (rev 8, mark persisted per B2 review
+                    // r2): retry later with backoff — NEVER purge, NEVER halt. The
+                    // persisted mark keeps the row through restarts and resync's
+                    // purge-absent step (the list covers active rows only). After
+                    // the bounded budget the 409 propagates to the caller, which
+                    // retries later; the mark clears on mint success (same write)
+                    // or with the row on 404-gone purge.
+                    await this.markInstallationPending(installationId);
+                    this.logger.warn("queek installation pending; mint retry later with backoff", {
+                        installation: installationPid,
+                        code: error.code,
+                    });
+                    if (attempt === MAX_MINT_ATTEMPTS - 1)
+                        throw error;
+                    const backoff = Math.min(MINT_BACKOFF_MAX_MS, MINT_BACKOFF_BASE_MS * 2 ** attempt);
+                    await this.sleep(this.jittered(backoff));
+                    continue;
+                }
+                if (attempt === MAX_MINT_ATTEMPTS - 1)
+                    throw error;
+                if (error.status === 429) {
+                    await this.sleep(this.jittered(error.retryAfterMs ?? MINT_BACKOFF_BASE_MS));
+                    continue;
+                }
+                if (error.status >= 500 || error.code === "network_error") {
+                    const backoff = Math.min(MINT_BACKOFF_MAX_MS, MINT_BACKOFF_BASE_MS * 2 ** attempt);
+                    await this.sleep(this.jittered(backoff));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError;
+    }
+    jittered(baseMs) {
+        return baseMs + Math.floor(this.random() * RETRY_JITTER_MAX_MS);
+    }
+    async mintOnce(appBase, installationId, installationPid) {
+        // Signed per attempt (never reused past its ≤10-min window, never logged).
+        const jwt = signAppJwt({ credential: this.credential });
+        const url = `${appBase}${mintPath(installationId)}`;
+        const headers = new Headers();
+        headers.set("Authorization", `Bearer ${jwt}`);
+        headers.set("Accept", "application/json");
+        headers.set("User-Agent", this.userAgent);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: "POST", headers });
+        }
+        catch (cause) {
+            throw new QueekApiError({
+                status: 0,
+                code: "network_error",
+                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
+            });
+        }
+        const text = await response.text();
+        const parsed = text === "" ? null : tryParseJson(text);
+        if (!response.ok) {
+            throw queekApiErrorFromResponse(response.status, parsed, response.headers);
+        }
+        if (response.status !== 201) {
+            throw new Error(`Unexpected mint status ${response.status} for installation ${installationPid} (expected 201).`);
+        }
+        return parseMintBody(parsed, installationPid, this.credential.keyId);
+    }
+}
+function parseMintBody(body, installationPid, kid) {
+    const record = (typeof body === "object" && body !== null ? body : {});
+    const token = typeof record.token === "string" && record.token !== "" ? record.token : null;
+    const expiresAt = typeof record.expires_at === "string" ? record.expires_at : null;
+    if (token === null || expiresAt === null || Number.isNaN(Date.parse(expiresAt))) {
+        throw new Error(`Malformed mint response for installation ${installationPid}: expected {token, expires_at}.`);
+    }
+    return { token, expiresAt, kid };
+}
+/** Create a provider in one call (thin wrapper over `new AppTokenProvider`). */
+export function createAppTokenProvider(options) {
+    return new AppTokenProvider(options);
+}
+/**
+ * A `QueekClient` whose every call goes through `acquireToken()`: the
+ * installation token is resolved per request (usually a cache hit — the
+ * store IS the cache, one shared row per installation), sent as
+ * `X-Client-Key`, and on a merchant-API token refusal (any 401, or 403
+ * `api_key_revoked` / `api_key_expired` / `invalid_client_key`) it is
+ * dropped, re-minted once, and the call retried once; a second refusal
+ * propagates to the caller. A merchant 403 `app_token_revoked` drops all
+ * cached tokens and halts minting; any other 403 propagates without a
+ * mint. 429/network retries (`requestWithRetry`) reuse one idempotency key
+ * exactly like the static client.
+ */
+export function createInstallationClient(options) {
+    // Validated here, once, before any fetch — same rules as the static client.
+    const probe = resolveApiBase(options.apiBase, options.allowedApiHosts ?? []);
+    void probe;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const userAgent = options.userAgent ?? "queek-app/1.0";
+    const allowedApiHosts = options.allowedApiHosts ?? [];
+    let cached = null;
+    async function clientForToken(token) {
+        if (!cached || cached.token !== token) {
+            cached = {
+                token,
+                client: createQueekClient({
+                    apiBase: options.apiBase,
+                    apiKey: token,
+                    fetchImpl,
+                    userAgent,
+                    allowedApiHosts,
+                }),
+            };
+        }
+        return cached.client;
+    }
+    async function request(method, path, requestOptions = {}) {
+        const token = await options.tokens.acquireToken(options.installationId);
+        try {
+            return await (await clientForToken(token)).request(method, path, requestOptions);
+        }
+        catch (error) {
+            if (!(error instanceof QueekApiError))
+                throw error;
+            // Kill switch / disabled app, observed on the merchant path: drop
+            // every cached token and halt minting, then propagate this refusal
+            // (no mint — the app is revoked, not the token).
+            if (error.status === 403 && isAppTokenRevoked(error.code)) {
+                await options.tokens.revokeAppAccess();
+                throw error;
+            }
+            // Token refusals ONLY (rev 7): any 401, or a 403 carrying a
+            // revoked/expired-key code. Every other 403 (scope, plan, mode)
+            // propagates to the caller without burning a mint.
+            if (!isTokenRefusal(error.status, error.code))
+                throw error;
+            // Dead token: drop it, re-mint once, retry once. The re-mint runs
+            // the full contract error mapping (halt/purge on
+            // invalid_client/kill-switch/gone); a second merchant refusal
+            // propagates to the caller.
+            await options.tokens.dropCachedToken(options.installationId);
+            const fresh = await options.tokens.acquireToken(options.installationId);
+            return (await clientForToken(fresh)).request(method, path, requestOptions);
+        }
+    }
+    async function requestWithRetry(method, path, retryOptions = {}) {
+        const maxAttempts = Math.max(1, Math.floor(retryOptions.maxAttempts ?? 3));
+        const baseDelayMs = retryOptions.baseDelayMs ?? 250;
+        const maxDelayMs = retryOptions.maxDelayMs ?? 5000;
+        const sleep = retryOptions.sleep ?? defaultSleep;
+        const idempotencyKey = retryOptions.idempotencyKey;
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                return await request(method, path, { ...retryOptions, idempotencyKey });
+            }
+            catch (error) {
+                lastError = error;
+                const retryable = error instanceof QueekApiError && (error.isRateLimited || error.code === "network_error");
+                if (!retryable || attempt === maxAttempts - 1)
+                    throw error;
+                const delay = error instanceof QueekApiError && error.isRateLimited && error.retryAfterMs !== undefined
+                    ? error.retryAfterMs
+                    : Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+                await sleep(delay);
+            }
+        }
+        throw lastError;
+    }
+    return {
+        getStore: (signal) => request("GET", "/store", { signal }),
+        request,
+        requestWithRetry,
+    };
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 500) };
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/dist/webhooks.d.ts

@@ -0,0 +1,60 @@
+import { Hono } from "hono";
+import type { InstallationRecord, InstallationStore } from "./store.js";
+/**
+ * Receiver for Queek topic deliveries (`DeliverWebhookJob` in
+ * queek_backend, one signed POST per installation endpoint).
+ *
+ * Delivery envelope: `{ id, topic, api_version: "v1", created_at, data }`
+ * with `X-Queek-Topic` echoing `topic`. Verification uses the
+ * PER-INSTALLATION endpoint secret handed over once inside the install
+ * payload (`data.webhook_secret`) — never the app signing secret.
+ *
+ * Secret lookup: topic payloads are resource renders with no guaranteed
+ * installation/vendor id, so the default resolver identifies the
+ * installation by trying each stored installation secret against the
+ * signature (the signature itself names the sender; HMACs are microseconds,
+ * installations per app are few). Apps that carry their own routing hint
+ * may pass `resolveSecret` instead.
+ *
+ * Dedupe: Queek retries a delivery for ~4h until it sees 2xx, so every
+ * `webhook-id` is processed AT MOST once — the header id is claimed
+ * atomically up front (exactly one concurrent same-id delivery runs the
+ * handler) and a repeat answers 200 WITHOUT re-running it. A throwing
+ * handler releases the claim and answers 500 so the retry can land.
+ * Unknown topics answer 200 too (a topic the app no longer handles must
+ * not wedge Queek's retry queue); only auth and malformed bodies are
+ * non-2xx.
+ */
+export declare const QUEEK_TOPIC_HEADER = "X-Queek-Topic";
+export interface QueekWebhookEnvelope<TData = unknown> {
+    id: string;
+    topic: string;
+    api_version: "v1";
+    created_at: string;
+    data: TData;
+}
+export interface WebhookHandlerContext {
+    installation: InstallationRecord;
+    topic: string;
+    eventId: string;
+}
+export type WebhookHandlerFn<TData = unknown> = (envelope: QueekWebhookEnvelope<TData>, context: WebhookHandlerContext) => Promise<void>;
+export interface SecretResolution {
+    installationId: string;
+    secret: string;
+}
+export interface WebhookHandlerOptions {
+    store: InstallationStore;
+    /** `topic → handler`, e.g. `{ "orders/updated": onOrderUpdated }`. */
+    handlers: Record<string, WebhookHandlerFn>;
+    /** Override the default try-each-secret resolution. */
+    resolveSecret?: (envelope: QueekWebhookEnvelope | null, rawBody: string, headers: {
+        id: string;
+        timestamp: string;
+        signatureHeader: string;
+    }) => Promise<SecretResolution | null>;
+    nowSeconds?: number;
+    maxSkewSeconds?: number;
+}
+export declare function createWebhookHandler(options: WebhookHandlerOptions): Hono;
+//# sourceMappingURL=webhooks.d.ts.map