@usequeek/app-sdk 0.6.1 → 0.7.0

package/dist/app-auth.d.ts

@@ -1,21 +1,19 @@
 /**
- * The app credential (S1, SDK 0.2.0): ONE asymmetric RS256 key per app.
- * Queek holds the PUBLIC keys (`apps.public_keys`, kid-capped); the app
- * holds the PRIVATE key in `APP_PRIVATE_KEY` and signs short-lived app
- * JWTs that mint per-installation tokens (`acquireToken()`).
+ * The app credential: ONE asymmetric RS256 key per app. Queek holds the
+ * PUBLIC keys (kid-capped); the app holds the PRIVATE key in
+ * `APP_PRIVATE_KEY` and signs short-lived app JWTs that mint
+ * per-installation tokens (`acquireToken()`).
  *
- * Wire contract (BINDING for B2 and S1): every call under `/api/v1/apps`
- * carries `Authorization: Bearer <app JWT>` (RS256, header `kid`, claims
- * `iss` = app slug, `iat`, `exp`, `exp − iat` ≤ 600 s). `node:crypto` only
- * — no new dependency. The JWT and the private key are NEVER logged (the
+ * Every call under `/api/v1/apps` carries `Authorization: Bearer <app JWT>`
+ * (RS256, header `kid`, claims `iss` = app slug, `iat`, `exp`,
+ * `exp − iat` ≤ 600 s). `node:crypto` only — no new dependency. The JWT and the private key are NEVER logged (the
  * logger redacts `Bearer …` values; signers below never emit them).
  */
 /** 401 on an app-credential call: bad/expired JWT or unknown kid. Fatal for the app. */
 export declare const INVALID_CLIENT_CODE = "invalid_client";
 /**
  * 403 on an app-credential call: the app is disabled or its token epoch was
- * bumped by `app:revoke-tokens` (kill switch). Confirmed against B1
- * (`ApiError::APP_TOKEN_REVOKED`, returned in both cases); matched in
+ * bumped (kill switch, returned in both cases); matched in
  * exactly one place (`isAppTokenRevoked`).
  */
 export declare const APP_TOKEN_REVOKED_CODE = "app_token_revoked";
@@ -55,10 +53,10 @@ export declare function isInstallationPending(code: string | undefined): boolean
 /** True when a resync 429 code is the per-installation rotation cooldown (skip, recorded). */
 export declare function isResyncCooldown(code: string | undefined): boolean;
 /**
- * Merchant-API token-refusal codes (rev 7): a token in one of these states
+ * Merchant-API token-refusal codes: a token in one of these states
  * is dead — drop it, re-mint once, retry once. `api_key_revoked` covers the
- * uninstalled store, the removed kid, and the replaced K-slot; the re-mint
- * then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
+ * uninstalled store, the removed kid, and a token replaced by a newer one;
+ * the re-mint then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
  * (halt) where applicable. Every OTHER merchant 403 (plan, mode)
  * propagates to the caller without a mint.
  */
@@ -74,7 +72,7 @@ export declare const INVALID_CLIENT_KEY_CODE = "invalid_client_key";
 export declare function isTokenRefusal(status: number, code: string | undefined): boolean;
 /** True when a merchant-API 403 means the cached token predates a grant change. */
 export declare function isInsufficientScope(status: number, code: string | undefined): boolean;
-/** App-JWT `iat` is backdated this far (clock skew, GitHub's recommendation). */
+/** App-JWT `iat` is backdated this far, so a small clock skew between the app and Queek cannot make a fresh token look not-yet-valid. */
 export declare const APP_JWT_SKEW_SECONDS = 60;
 /** App-JWT lifetime: `exp = iat + 540`, so `exp − iat` (540 s) stays ≤ the 600 s wire bound. */
 export declare const APP_JWT_TTL_SECONDS = 540;
@@ -112,7 +110,7 @@ export declare class UnknownInstallationError extends Error {
     constructor(installationId: string);
 }
 export interface AppCredential {
-    /** `iss`: the app slug (as registered with `app:register`). */
+    /** `iss`: the app slug (as registered on the Queek Developer page). */
     appSlug: string;
     /** `kid`: which of the app's public keys Queek verifies against (`APP_KEY_ID`). */
     keyId: string;
@@ -128,7 +126,8 @@ export interface AppCredentialOptions {
 /**
  * Accepted `APP_PRIVATE_KEY` forms (env files are one line per variable):
  * raw PEM text, one-line PEM with literal `\n` escapes, or base64 of the
- * full PEM text (one line, no wrapping — what the Developer page shows).
+ * full PEM text (one line, no wrapping — the form `queek app dev` writes to
+ * `.queek/.env.local`; a server-generated key is shown once, never again).
  */
 export declare const APP_PRIVATE_KEY_FORMS = "raw PEM text, one-line PEM with literal \\n escapes, or base64 of the PEM text";
 /**
@@ -157,4 +156,3 @@ export interface SignAppJwtOptions {
  * compact JWT; NEVER logs it or the private key.
  */
 export declare function signAppJwt(options: SignAppJwtOptions): string;
-//# sourceMappingURL=app-auth.d.ts.map

package/dist/app-auth.js

@@ -1,27 +1,24 @@
 import { createPrivateKey, createSign } from "node:crypto";
 /**
- * The app credential (S1, SDK 0.2.0): ONE asymmetric RS256 key per app.
- * Queek holds the PUBLIC keys (`apps.public_keys`, kid-capped); the app
- * holds the PRIVATE key in `APP_PRIVATE_KEY` and signs short-lived app
- * JWTs that mint per-installation tokens (`acquireToken()`).
+ * The app credential: ONE asymmetric RS256 key per app. Queek holds the
+ * PUBLIC keys (kid-capped); the app holds the PRIVATE key in
+ * `APP_PRIVATE_KEY` and signs short-lived app JWTs that mint
+ * per-installation tokens (`acquireToken()`).
  *
- * Wire contract (BINDING for B2 and S1): every call under `/api/v1/apps`
- * carries `Authorization: Bearer <app JWT>` (RS256, header `kid`, claims
- * `iss` = app slug, `iat`, `exp`, `exp − iat` ≤ 600 s). `node:crypto` only
- * — no new dependency. The JWT and the private key are NEVER logged (the
+ * Every call under `/api/v1/apps` carries `Authorization: Bearer <app JWT>`
+ * (RS256, header `kid`, claims `iss` = app slug, `iat`, `exp`,
+ * `exp − iat` ≤ 600 s). `node:crypto` only — no new dependency. The JWT and the private key are NEVER logged (the
  * logger redacts `Bearer …` values; signers below never emit them).
  */
 // ---------------------------------------------------------------------------
-// Wire-contract error codes. Each code the SDK reacts to lives in EXACTLY
-// one constant here, so a backend rename is a one-line change the parallel
-// B1/B2 build must confirm.
+// Error codes on the wire. Each code the SDK reacts to lives in EXACTLY
+// one constant here, so a rename on Queek's side is a one-line change.
 // ---------------------------------------------------------------------------
 /** 401 on an app-credential call: bad/expired JWT or unknown kid. Fatal for the app. */
 export const INVALID_CLIENT_CODE = "invalid_client";
 /**
  * 403 on an app-credential call: the app is disabled or its token epoch was
- * bumped by `app:revoke-tokens` (kill switch). Confirmed against B1
- * (`ApiError::APP_TOKEN_REVOKED`, returned in both cases); matched in
+ * bumped (kill switch, returned in both cases); matched in
  * exactly one place (`isAppTokenRevoked`).
  */
 export const APP_TOKEN_REVOKED_CODE = "app_token_revoked";
@@ -71,10 +68,10 @@ export function isResyncCooldown(code) {
     return code === RESYNC_COOLDOWN_CODE;
 }
 /**
- * Merchant-API token-refusal codes (rev 7): a token in one of these states
+ * Merchant-API token-refusal codes: a token in one of these states
  * is dead — drop it, re-mint once, retry once. `api_key_revoked` covers the
- * uninstalled store, the removed kid, and the replaced K-slot; the re-mint
- * then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
+ * uninstalled store, the removed kid, and a token replaced by a newer one;
+ * the re-mint then answers 404 `app_installation_gone` (purge) or 401 `invalid_client`
  * (halt) where applicable. Every OTHER merchant 403 (plan, mode)
  * propagates to the caller without a mint.
  */
@@ -100,7 +97,7 @@ export function isInsufficientScope(status, code) {
 // ---------------------------------------------------------------------------
 // Timing bounds (all in the open, all injectable in tests).
 // ---------------------------------------------------------------------------
-/** App-JWT `iat` is backdated this far (clock skew, GitHub's recommendation). */
+/** App-JWT `iat` is backdated this far, so a small clock skew between the app and Queek cannot make a fresh token look not-yet-valid. */
 export const APP_JWT_SKEW_SECONDS = 60;
 /** App-JWT lifetime: `exp = iat + 540`, so `exp − iat` (540 s) stays ≤ the 600 s wire bound. */
 export const APP_JWT_TTL_SECONDS = 540;
@@ -146,14 +143,15 @@ export class AppMintHaltedError extends Error {
 export class UnknownInstallationError extends Error {
     code = "unknown_installation";
     constructor(installationId) {
-        super(`Unknown installation ${installationId}: no local row (resync or reinstall first).`);
+        super(`Unknown installation ${installationId}: no local row. Recover with resyncFromQueek() (lists the app's active installations from Queek) or reinstall the app on the store.`);
         this.name = "UnknownInstallationError";
     }
 }
 /**
  * Accepted `APP_PRIVATE_KEY` forms (env files are one line per variable):
  * raw PEM text, one-line PEM with literal `\n` escapes, or base64 of the
- * full PEM text (one line, no wrapping — what the Developer page shows).
+ * full PEM text (one line, no wrapping — the form `queek app dev` writes to
+ * `.queek/.env.local`; a server-generated key is shown once, never again).
  */
 export const APP_PRIVATE_KEY_FORMS = "raw PEM text, one-line PEM with literal \\n escapes, or base64 of the PEM text";
 /**
@@ -183,15 +181,15 @@ export function loadAppCredential(options = {}) {
     const env = options.env ?? process.env;
     const appSlug = (options.appSlug ?? env.APP_SLUG ?? "").trim();
     if (appSlug === "") {
-        throw new InvalidAppCredentialError("Missing app slug for `iss`: pass appSlug or set APP_SLUG to the slug registered with Queek.");
+        throw new InvalidAppCredentialError("Missing app slug for `iss`: pass appSlug or set APP_SLUG to the slug from the Queek Developer page (register the app there, or run `queek app dev` — it writes .queek/.env.local).");
     }
     const keyId = (options.keyId ?? env.APP_KEY_ID ?? "").trim();
     if (keyId === "") {
-        throw new InvalidAppCredentialError("Missing APP_KEY_ID: set it to the kid registered with Queek (`php artisan app:register --public-key=…`).");
+        throw new InvalidAppCredentialError("Missing APP_KEY_ID: set it to the key id shown on the Queek Developer page for this app (`queek app dev` writes it to .queek/.env.local on first run).");
     }
     const privateKeyInput = (options.privateKeyPem ?? env.APP_PRIVATE_KEY ?? "").trim();
     if (privateKeyInput === "") {
-        throw new InvalidAppCredentialError(`Missing APP_PRIVATE_KEY: set it to base64 of the app's RSA private key PEM (one line). Accepted forms: ${APP_PRIVATE_KEY_FORMS}.`);
+        throw new InvalidAppCredentialError(`Missing APP_PRIVATE_KEY: set it to the app's RSA private key — your offline-generated file, or the server-generated key (shown once on the Developer page; \`queek app dev\` stores it in .queek/.env.local). If lost, generate a new key. Accepted forms: ${APP_PRIVATE_KEY_FORMS}.`);
     }
     const privateKeyPem = decodePrivateKeyInput(privateKeyInput);
     try {
@@ -236,4 +234,3 @@ export function signAppJwt(options) {
     }
     return `${signingInput}.${signature.toString("base64url")}`;
 }
-//# sourceMappingURL=app-auth.js.map

package/dist/auth-fetch.d.ts

@@ -1,6 +1,5 @@
 /**
- * Same-origin session carriage for embedded apps (U-validation "Auth
- * carriage"): `installAuthFetch()` reads the dashboard token from the
+ * Same-origin session carriage for embedded apps: `installAuthFetch()` reads the dashboard token from the
  * first-load URL (`?queek_token=`, stripped immediately), exchanges it
  * ONCE for the app's own session, and attaches
  * `Authorization: Bearer <session>` to every same-origin fetch. A 401
@@ -25,8 +24,7 @@ import { type EmbedEventTarget, type EmbedPostTarget } from "./frame.js";
  * frame src contract (the ONLY token that may ride a URL, namespaced so it
  * cannot collide with an app's own `token` param). The token is the same
  * type the bridge `ready→token` flow returns on refresh — first load and
- * refresh differ only in transport (URL param vs postMessage), exactly
- * Shopify's `id_token`.
+ * refresh differ only in transport (URL param vs postMessage).
  */
 export declare const LAUNCH_TOKEN_PARAM = "queek_token";
 /** How long to wait for the dashboard's token reply after a `ready`. */
@@ -87,5 +85,16 @@ export declare function readLaunchToken(href: string, param?: string): string |
  * present.
  */
 export declare function stripLaunchToken(href: string, param?: string): string | null;
+/**
+ * Install same-origin session carriage for an embedded page. Reads and strips
+ * the first-load token, exchanges it once, and returns a `fetch` that adds
+ * `Authorization: Bearer <session>` to same-origin requests.
+ *
+ * @example
+ * const auth = installAuthFetch({
+ *   dashboardOrigin: "https://dashboard.usequeek.com",
+ *   exchange: async (token) => (await fetch("/api/session", { method: "POST", body: token })).text(),
+ * });
+ * const response = await auth.fetch("/api/orders");
+ */
 export declare function installAuthFetch(options: AuthFetchOptions): InstalledAuth;
-//# sourceMappingURL=auth-fetch.d.ts.map

package/dist/auth-fetch.js

@@ -1,6 +1,5 @@
 /**
- * Same-origin session carriage for embedded apps (U-validation "Auth
- * carriage"): `installAuthFetch()` reads the dashboard token from the
+ * Same-origin session carriage for embedded apps: `installAuthFetch()` reads the dashboard token from the
  * first-load URL (`?queek_token=`, stripped immediately), exchanges it
  * ONCE for the app's own session, and attaches
  * `Authorization: Bearer <session>` to every same-origin fetch. A 401
@@ -25,8 +24,7 @@ import { listenToDashboard, sendReady } from "./frame.js";
  * frame src contract (the ONLY token that may ride a URL, namespaced so it
  * cannot collide with an app's own `token` param). The token is the same
  * type the bridge `ready→token` flow returns on refresh — first load and
- * refresh differ only in transport (URL param vs postMessage), exactly
- * Shopify's `id_token`.
+ * refresh differ only in transport (URL param vs postMessage).
  */
 export const LAUNCH_TOKEN_PARAM = "queek_token";
 /** How long to wait for the dashboard's token reply after a `ready`. */
@@ -63,6 +61,18 @@ export function stripLaunchToken(href, param = LAUNCH_TOKEN_PARAM) {
         return null;
     }
 }
+/**
+ * Install same-origin session carriage for an embedded page. Reads and strips
+ * the first-load token, exchanges it once, and returns a `fetch` that adds
+ * `Authorization: Bearer <session>` to same-origin requests.
+ *
+ * @example
+ * const auth = installAuthFetch({
+ *   dashboardOrigin: "https://dashboard.usequeek.com",
+ *   exchange: async (token) => (await fetch("/api/session", { method: "POST", body: token })).text(),
+ * });
+ * const response = await auth.fetch("/api/orders");
+ */
 export function installAuthFetch(options) {
     const param = options.param ?? LAUNCH_TOKEN_PARAM;
     const win = globalWindow();
@@ -70,7 +80,7 @@ export function installAuthFetch(options) {
     const replaceUrl = options.replaceUrl ?? ((url) => win?.history.replaceState(null, "", url));
     const fetchImpl = options.fetchImpl ?? globalThis.fetch ?? null;
     if (fetchImpl === null) {
-        throw new Error("installAuthFetch needs a fetch implementation");
+        throw new Error("installAuthFetch needs a fetch implementation: pass `fetchImpl`, or run where a global `fetch` exists.");
     }
     const fetchFn = fetchImpl;
     const listenTarget = options.listenTarget ?? win ?? undefined;
@@ -260,4 +270,3 @@ export function installAuthFetch(options) {
         },
     };
 }
-//# sourceMappingURL=auth-fetch.js.map

package/dist/background.d.ts

@@ -15,11 +15,19 @@ export interface DetachOptions {
     label: string;
     onError: (error: unknown) => void;
 }
+/**
+ * Run a promise in the background without leaving it unhandled: a rejection
+ * goes to `options.onError` with the `label`, never to an unhandled-rejection
+ * crash. Use it to answer a delivery fast and finish the work after.
+ *
+ * @example
+ * detach(syncCatalogue(installationId), { label: "catalogue sync", onError: (e) => logger.error("sync failed", { e: String(e) }) });
+ */
 export declare function detach(promise: Promise<unknown>, options: DetachOptions): void;
 /** How many background tasks are currently running (health/debug only). */
 export declare function backgroundTaskCount(): number;
 /**
- * Jittered per-installation catch-up for one container (S1, SDK 0.2.0):
+ * Jittered per-installation catch-up for one container:
  * iterate every stored installation and run `forInstallation` (a token
  * proof-call, a resync batch, an inbox poll — whatever the app needs
  * hourly), with:
@@ -64,5 +72,5 @@ export interface CatchupOptions {
     /** Injectable uniform [0,1) for jitter. Defaults to `Math.random`. */
     random?: () => number;
 }
+/** Run `forInstallation` for every stored installation on a jittered schedule. See the notes above for the guarantees. */
 export declare function runInstallationCatchup(options: CatchupOptions): Promise<CatchupResult>;
-//# sourceMappingURL=background.d.ts.map

package/dist/background.js

@@ -12,6 +12,14 @@
  * when replicas or an outbound queue need shared state.
  */
 const inFlight = new Set();
+/**
+ * Run a promise in the background without leaving it unhandled: a rejection
+ * goes to `options.onError` with the `label`, never to an unhandled-rejection
+ * crash. Use it to answer a delivery fast and finish the work after.
+ *
+ * @example
+ * detach(syncCatalogue(installationId), { label: "catalogue sync", onError: (e) => logger.error("sync failed", { e: String(e) }) });
+ */
 export function detach(promise, options) {
     inFlight.add(promise);
     promise
@@ -29,6 +37,7 @@ export function backgroundTaskCount() {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Run `forInstallation` for every stored installation on a jittered schedule. See the notes above for the guarantees. */
 export async function runInstallationCatchup(options) {
     const sleep = options.sleep ?? defaultSleep;
     const random = options.random ?? Math.random;
@@ -75,4 +84,3 @@ export async function runInstallationCatchup(options) {
     await Promise.all(Array.from({ length: Math.min(concurrency, resolved.length) }, () => worker()));
     return result;
 }
-//# sourceMappingURL=background.js.map

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
 /**
- * Plain-browser entry for `@usequeek/app-sdk` (Booking fix): the embedded-app
- * bridge plus `installAuthFetch`, with ZERO Node-only modules.
+ * Plain-browser entry for `@usequeek/app-sdk`: the embedded-page bridge plus
+ * `installAuthFetch`, with ZERO Node-only modules.
  *
  * Import from `@usequeek/app-sdk/browser` in any browser bundle (Vite,
  * Rollup, esbuild, …). Importing the same helpers from the MAIN entry pulls
@@ -22,4 +22,3 @@
 export { type AuthFetchOptions, BRIDGE_TOKEN_TIMEOUT_MS, type InstalledAuth, installAuthFetch, LAUNCH_TOKEN_PARAM, readLaunchToken, stripLaunchToken, } from "./auth-fetch.js";
 export { APP_SOURCE, type AppInboundMessage, type AppOutboundMessage, BRIDGE_VERSION, type BridgeTheme, DASHBOARD_SOURCE, type EmbedEvent, type EmbedEventTarget, type EmbedPostTarget, type FrameBridgeOptions, listenToDashboard, type PickResourceRequest, type ReadyOptions, type ResourceItem, type SaveBarAction, type SaveBarState, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, type ThemeMode, type TitleActionDef, } from "./frame.js";
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, syncThemeUrl, THEME_PARAM, THEME_STORAGE_KEY, type ThemeDocument, type ThemeDocumentElement, type ThemeListenerOptions, type ThemeStorage, type ThemeUrlOptions, themeBootstrapScript, } from "./theme.js";
-//# sourceMappingURL=browser.d.ts.map

package/dist/browser.js

@@ -1,6 +1,6 @@
 /**
- * Plain-browser entry for `@usequeek/app-sdk` (Booking fix): the embedded-app
- * bridge plus `installAuthFetch`, with ZERO Node-only modules.
+ * Plain-browser entry for `@usequeek/app-sdk`: the embedded-page bridge plus
+ * `installAuthFetch`, with ZERO Node-only modules.
  *
  * Import from `@usequeek/app-sdk/browser` in any browser bundle (Vite,
  * Rollup, esbuild, …). Importing the same helpers from the MAIN entry pulls
@@ -24,4 +24,3 @@ export { APP_SOURCE, BRIDGE_VERSION, DASHBOARD_SOURCE, listenToDashboard, sendNa
 // NOTE: ThemeMode comes from ./frame.js only — theme.js merely re-exports
 // it, so listing it here too would be ambiguous.
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, syncThemeUrl, THEME_PARAM, THEME_STORAGE_KEY, themeBootstrapScript, } from "./theme.js";
-//# sourceMappingURL=browser.js.map

package/dist/client.d.ts

@@ -2,12 +2,11 @@ import type { paths } from "./merchant-schema.js";
 /**
  * Typed fetch client over Queek's public Merchant API.
  *
- * - Base URL comes from the install handoff (`api_base`). The backend sends
- *   the BARE store host (`AppInstallService::installPayload()` passes
- *   `rtrim(config('app.url'))` verbatim, e.g. `https://api.usequeek.com`);
- *   the client appends `/api/v1/merchant` when it is absent, so a bare host
- *   and a full merchant base both work. Never hardcoded otherwise, so test
- *   stores ride their own host.
+ * - Base URL comes from the install handoff (`api_base`). Queek sends the
+ *   BARE store host (e.g. `https://api.usequeek.com`); the client appends
+ *   `/api/v1/merchant` when it is absent, so a bare host and a full
+ *   merchant base both work. Never hardcoded otherwise, so test stores ride
+ *   their own host.
  * - `apiBase` is validated at construction — https only, no credentials,
  *   host on the allowlist — and throws BEFORE any fetch, so a
  *   signed-but-stale or attacker-influenced handoff can never point
@@ -24,7 +23,12 @@ import type { paths } from "./merchant-schema.js";
  *   is additive, so both are read). Switch on `code`, never on `message`.
  * - 429s expose `retryAfterMs` parsed from `Retry-After` (seconds or
  *   HTTP-date). Plain `request()` never retries; `requestWithRetry()`
- *   retries 429s and network errors with the SAME idempotency key.
+ *   retries 429s, 502/503/504, timeouts and network errors with jittered
+ *   exponential backoff and the SAME idempotency key on every attempt.
+ * - Every request has a timeout (`timeoutMs`, default 30 s) and accepts an
+ *   `AbortSignal`. Failures that never produced an HTTP answer are thrown as
+ *   `QueekApiError` with status 0 and the code `network_error`,
+ *   `request_timeout` or `request_aborted`, and the original error as `cause`.
  *
  * Typed surface: `getStore()` is typed from the app's Merchant API
  * paths. Pass the app's own codegen output as the type argument
@@ -72,13 +76,13 @@ export declare class InvalidApiBaseError extends Error {
     constructor(message: string);
 }
 /**
- * Extra allowed `apiBase` hosts for test/local backends, from
+ * Extra allowed `apiBase` hosts for test and local setups, from
  * `QUEEK_API_HOSTS` (comma-separated bare hostnames). Parsed strictly: any
  * entry that is not a bare hostname throws — nothing is silently skipped.
  */
 export declare function apiHostsFromEnv(env?: NodeJS.ProcessEnv): string[];
 /**
- * DEV-ONLY extra allowed hosts (e.g. an HTTPS tunnel to a local backend),
+ * DEV-ONLY extra allowed hosts (e.g. an HTTPS tunnel to a local Queek API),
  * from `QUEEK_DEV_API_HOSTS`. REFUSED when NODE_ENV=production: a dev
  * tunnel host must never be allowlisted in production, even by accident.
  * Throws at client construction, before any fetch.
@@ -93,26 +97,40 @@ export declare function devApiHostsFromEnv(env?: NodeJS.ProcessEnv): string[];
  * QUEEK_DEV_API_HOSTS`.
  */
 export declare function resolveApiBase(raw: string, allowedApiHosts?: string[]): string;
+/** Default time a single HTTP attempt may take before it fails with `request_timeout`. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Default ceiling for honouring a 429 `Retry-After` inside `requestWithRetry()`. */
+export declare const DEFAULT_MAX_RETRY_AFTER_MS = 30000;
 export interface QueekClientOptions {
     /** Handoff `api_base` (bare store host or full merchant base). Validated at construction. */
     apiBase: string;
+    /** The installation credential, sent as `X-Client-Key`. Never logged and never put in an error message. */
     apiKey: string;
     fetchImpl?: typeof fetch;
+    /** Time one attempt may take, in ms (default 30000). `0` disables the client timeout. */
+    timeoutMs?: number;
     /** Sent as User-Agent. Defaults to `queek-app/1.0`. */
     userAgent?: string;
-    /** Extra allowed `apiBase` hosts (test/local backends). Production default always applies. */
+    /** Extra allowed `apiBase` hosts (test/local API hosts). Production default always applies. */
     allowedApiHosts?: string[];
 }
 export interface RequestOptions {
+    /** Query string values. `undefined` entries are skipped; everything else is URL-encoded for you. */
     query?: Record<string, string | number | boolean | undefined>;
+    /** JSON-serialisable request body. */
     body?: unknown;
     /** Write idempotency (POST/PUT/PATCH/DELETE). Generated when omitted. */
     idempotencyKey?: string;
+    /** Correlation id sent as `X-Request-Id` (8 to 128 characters of `A-Za-z0-9_.:-`). Generated when omitted. */
     requestId?: string;
+    /** Aborts the call. An aborted call fails with code `request_aborted` and is never retried. */
     signal?: AbortSignal;
+    /** Overrides the client's per-attempt timeout for this call, in ms. `0` disables it. */
+    timeoutMs?: number;
 }
 /** True for HTTP methods that carry an `Idempotency-Key` (POST/PUT/PATCH/DELETE). */
 export declare function isWriteMethod(method: string): boolean;
+/** A fresh `Idempotency-Key` value (a random UUID). */
 export declare function newIdempotencyKey(): string;
 export interface QueekErrorDetails {
     status: number;
@@ -123,7 +141,31 @@ export interface QueekErrorDetails {
     docUrl?: string;
     requestId?: string;
     retryAfterMs?: number;
+    /** The underlying error, when this one wraps another (a failed `fetch`, for example). */
+    cause?: unknown;
 }
+/**
+ * The one error every Queek HTTP call throws. Switch on `code`, never on
+ * `message`.
+ *
+ * Codes that come from Queek are the API's own (`validation_failed`,
+ * `insufficient_scope`, `too_many_requests`, ...). Codes the SDK raises when
+ * no usable HTTP answer arrived (`status` is 0 for the first three):
+ * `network_error`, `request_timeout`, `request_aborted`, and
+ * `invalid_response` (an HTTP success whose body was not JSON).
+ *
+ * `requestId` matches the `X-Request-Id` response header: quote it to Queek
+ * support.
+ *
+ * @example
+ * try {
+ *   await client.request("POST", "/orders", { body });
+ * } catch (error) {
+ *   if (error instanceof QueekApiError && error.code === "validation_failed") {
+ *     console.error(error.field, error.errors, error.requestId);
+ *   }
+ * }
+ */
 export declare class QueekApiError extends Error {
     readonly status: number;
     readonly code: string;
@@ -136,7 +178,26 @@ export declare class QueekApiError extends Error {
     constructor(details: QueekErrorDetails);
     get isRateLimited(): boolean;
     get isAuthFailure(): boolean;
+    /**
+     * True when sending the same call again can succeed without any change:
+     * rate limits, gateway failures (502, 503, 504), timeouts and network
+     * errors. `requestWithRetry()` retries exactly these. A caller abort is
+     * never retryable.
+     */
+    get isRetryable(): boolean;
 }
+/**
+ * The error for a call that never produced an HTTP answer. A caller abort is
+ * `request_aborted`, the client timeout is `request_timeout`, everything else
+ * (DNS, refused or reset connection, TLS) is `network_error`. The original
+ * error stays on `cause`.
+ */
+export declare function transportError(cause: unknown, signal?: AbortSignal): QueekApiError;
+/**
+ * Combine a caller signal with the per-attempt timeout. Returns the caller
+ * signal untouched when `timeoutMs` is 0 or negative.
+ */
+export declare function requestSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal | undefined;
 /**
  * Build a `QueekApiError` from a status + parsed body + headers. Shared
  * with the installation-token mint path (`tokens.ts`), so the merchant and
@@ -148,10 +209,17 @@ export interface RetryOptions {
     maxAttempts?: number;
     /** Base backoff between attempts in ms (default 250); doubles per attempt. */
     baseDelayMs?: number;
-    /** Backoff ceiling in ms (default 5000). A 429 `Retry-After` can exceed it. */
+    /** Backoff ceiling in ms (default 5000). */
     maxDelayMs?: number;
+    /**
+     * Longest `Retry-After` the call will wait out, in ms (default 30000). A
+     * 429 that asks for more is thrown at once instead of holding the caller.
+     */
+    maxRetryAfterMs?: number;
     /** Injectable clock for tests. Defaults to a real setTimeout sleep. */
     sleep?: (ms: number) => Promise<void>;
+    /** Injectable randomness for the backoff jitter, in [0, 1). Defaults to `Math.random`. */
+    random?: () => number;
 }
 export interface QueekClient<TPaths = paths> {
     /** `GET /store` — the handed-off key proving itself. Typed from the app's paths (`TPaths`, default: bundled shim). */
@@ -159,12 +227,66 @@ export interface QueekClient<TPaths = paths> {
     /** Generic typed escape hatch: `request<T>("GET", "/orders", { query })`. Never retries. */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     /**
-     * `request()` with bounded retries on 429s and network errors. The SAME
-     * idempotency key is reused across attempts (generated once when the
-     * caller does not supply one), so a retry can never duplicate a write;
-     * a 429 `Retry-After` is honoured over the backoff schedule.
+     * `request()` with bounded retries on 429s, 502/503/504, timeouts and
+     * network errors, with jittered exponential backoff. The SAME idempotency
+     * key is reused across attempts (generated once when the caller does not
+     * supply one), so a retry can never duplicate a write; a 429
+     * `Retry-After` is honoured over the backoff schedule. A caller abort is
+     * never retried.
      */
     requestWithRetry<T>(method: string, path: string, options?: RequestOptions & RetryOptions): Promise<T>;
 }
+/**
+ * The retry loop both clients share. `run` receives the idempotency key to
+ * send (generated ONCE for writes when the caller gave none), so every
+ * attempt of one write carries the same key.
+ */
+export declare function runWithRetry<T>(method: string, options: RetryOptions & {
+    idempotencyKey?: string;
+}, run: (idempotencyKey: string | undefined) => Promise<T>): Promise<T>;
+/**
+ * Create a client for the Merchant API with one static installation key.
+ * Most apps want `createInstallationClient()` instead, which mints and
+ * refreshes the key for you.
+ *
+ * @example
+ * const client = createQueekClient({ apiBase: install.api_base, apiKey: process.env.QUEEK_KEY ?? "" });
+ * const store = await client.getStore();
+ */
 export declare function createQueekClient<TPaths = paths>(clientOptions: QueekClientOptions): QueekClient<ResolvedPaths<TPaths>>;
-//# sourceMappingURL=client.d.ts.map
+/**
+ * Parse a non-JSON-safe error body: JSON when it parses, otherwise the first
+ * 500 characters as the error `message`.
+ */
+export declare function tryParseJson(text: string): unknown;
+/**
+ * Parse an HTTP success body. An empty body is `null`; a body that is not
+ * JSON is an `invalid_response` error, never a silently mistyped value.
+ */
+export declare function parseSuccessBody<T>(response: Response, text: string): T;
+/** One page of a cursor-paginated Merchant API list. */
+export interface CursorPage<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string | null;
+}
+export interface PaginateOptions {
+    /** Extra query parameters (filters, sort). `limit` and `starting_after` are managed for you. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Rows per page. Each endpoint documents its own maximum. */
+    limit?: number;
+    signal?: AbortSignal;
+    /** Retry tuning for each page fetch. */
+    retry?: RetryOptions;
+}
+/**
+ * Iterate every row of a cursor-paginated list (`data`, `has_more`,
+ * `next_cursor`, driven by `starting_after`), fetching one page at a time
+ * with `requestWithRetry()`. Stops when `has_more` is false.
+ *
+ * @example
+ * for await (const order of paginate<{ p_id: string }>(client, "/orders", { limit: 50 })) {
+ *   console.log(order.p_id);
+ * }
+ */
+export declare function paginate<T>(client: Pick<QueekClient<unknown>, "requestWithRetry">, path: string, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;