@usequeek/app-sdk 0.6.2 → 0.7.0

package/dist/app-auth.d.ts

@@ -72,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;
@@ -156,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

@@ -97,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;
@@ -234,4 +234,3 @@ export function signAppJwt(options) {
     }
     return `${signingInput}.${signature.toString("base64url")}`;
 }
-//# sourceMappingURL=app-auth.js.map

package/dist/auth-fetch.d.ts

@@ -85,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

@@ -61,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();
@@ -68,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;
@@ -258,4 +270,3 @@ export function installAuthFetch(options) {
         },
     };
 }
-//# sourceMappingURL=auth-fetch.js.map

package/dist/background.d.ts

@@ -15,6 +15,14 @@ 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;
@@ -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,5 +1,5 @@
 /**
- * Plain-browser entry for `@usequeek/app-sdk`: the embedded-app bridge plus
+ * 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,
@@ -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,5 +1,5 @@
 /**
- * Plain-browser entry for `@usequeek/app-sdk`: the embedded-app bridge plus
+ * 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,
@@ -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

@@ -23,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
@@ -92,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 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;
@@ -122,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;
@@ -135,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
@@ -147,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). */
@@ -158,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>;