@usequeek/app-sdk 0.6.2 → 0.7.0

package/dist/client.js

@@ -88,11 +88,16 @@ export function resolveApiBase(raw, allowedApiHosts = []) {
     const merchantPath = path.endsWith(MERCHANT_API_PATH) ? path : `${path}${MERCHANT_API_PATH}`;
     return `https://${host}${url.port !== "" ? `:${url.port}` : ""}${merchantPath}`;
 }
+/** Default time a single HTTP attempt may take before it fails with `request_timeout`. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+/** Default ceiling for honouring a 429 `Retry-After` inside `requestWithRetry()`. */
+export const DEFAULT_MAX_RETRY_AFTER_MS = 30_000;
 const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 /** True for HTTP methods that carry an `Idempotency-Key` (POST/PUT/PATCH/DELETE). */
 export function isWriteMethod(method) {
     return WRITE_METHODS.has(method.toUpperCase());
 }
+/** A fresh `Idempotency-Key` value (a random UUID). */
 export function newIdempotencyKey() {
     return randomUUID();
 }
@@ -110,6 +115,28 @@ function parseRetryAfterMs(value) {
     }
     return null;
 }
+/**
+ * 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 class QueekApiError extends Error {
     status;
     code;
@@ -120,7 +147,7 @@ export class QueekApiError extends Error {
     /** Set on 429s (and only there): how long to wait before retrying. */
     retryAfterMs;
     constructor(details) {
-        super(details.message);
+        super(details.message, details.cause === undefined ? undefined : { cause: details.cause });
         this.name = "QueekApiError";
         this.status = details.status;
         this.code = details.code;
@@ -136,6 +163,62 @@ export class QueekApiError extends Error {
     get isAuthFailure() {
         return this.status === 401 || this.status === 403;
     }
+    /**
+     * 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() {
+        return (this.status === 429 ||
+            this.status === 502 ||
+            this.status === 503 ||
+            this.status === 504 ||
+            this.code === "network_error" ||
+            this.code === "request_timeout");
+    }
+}
+/**
+ * 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 function transportError(cause, signal) {
+    const name = cause instanceof Error ? cause.name : "";
+    const reason = cause instanceof Error && cause.message !== "" ? ` (${cause.message})` : "";
+    if (name === "TimeoutError") {
+        return new QueekApiError({
+            status: 0,
+            code: "request_timeout",
+            message: "Queek did not answer before the request timeout. Retry, raise `timeoutMs`, or use requestWithRetry().",
+            cause,
+        });
+    }
+    if (signal?.aborted === true) {
+        return new QueekApiError({
+            status: 0,
+            code: "request_aborted",
+            message: "The request was aborted by its AbortSignal before Queek answered.",
+            cause,
+        });
+    }
+    return new QueekApiError({
+        status: 0,
+        code: "network_error",
+        message: `Could not reach Queek${reason}. Check the network connection and the api_base host, then retry; requestWithRetry() does this for you.`,
+        cause,
+    });
+}
+/**
+ * Combine a caller signal with the per-attempt timeout. Returns the caller
+ * signal untouched when `timeoutMs` is 0 or negative.
+ */
+export function requestSignal(signal, timeoutMs) {
+    if (!(timeoutMs > 0))
+        return signal;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
 }
 /**
  * Build a `QueekApiError` from a status + parsed body + headers. Shared
@@ -153,7 +236,8 @@ export function queekApiErrorFromResponse(status, body, headers) {
         return undefined;
     };
     const code = firstString(envelope.code, record.error_code) ?? (status === 429 ? "too_many_requests" : "server_error");
-    const message = firstString(envelope.message, record.message) ?? `Queek API error ${status}`;
+    const message = firstString(envelope.message, record.message) ??
+        `Queek answered HTTP ${status} without an error message. Retry, and quote the request id if it persists.`;
     const details = {
         status,
         code,
@@ -181,14 +265,56 @@ export function queekApiErrorFromResponse(status, body, headers) {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function isRetryable(error) {
-    return error instanceof QueekApiError && (error.isRateLimited || error.code === "network_error");
+/**
+ * Milliseconds to wait before the next attempt, or `null` when the error
+ * must be thrown instead of retried (not retryable, or a `Retry-After`
+ * longer than `maxRetryAfterMs`). Backoff is exponential with equal jitter
+ * (half fixed, half random) so many clients do not retry in lockstep.
+ */
+function retryDelayMs(error, attempt, options) {
+    if (!error.isRetryable)
+        return null;
+    if (error.isRateLimited && error.retryAfterMs !== undefined) {
+        return error.retryAfterMs <= (options.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS)
+            ? error.retryAfterMs
+            : null;
+    }
+    const ceiling = Math.min(options.maxDelayMs ?? 5000, (options.baseDelayMs ?? 250) * 2 ** attempt);
+    const random = options.random ?? Math.random;
+    return Math.floor(ceiling / 2 + (random() * ceiling) / 2);
 }
-function retryDelayMs(error, attempt, baseDelayMs, maxDelayMs) {
-    if (error.isRateLimited && error.retryAfterMs !== undefined)
-        return error.retryAfterMs;
-    return Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+/**
+ * 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 async function runWithRetry(method, options, run) {
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+    const sleep = options.sleep ?? defaultSleep;
+    const idempotencyKey = options.idempotencyKey ?? (isWriteMethod(method) ? newIdempotencyKey() : undefined);
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await run(idempotencyKey);
+        }
+        catch (error) {
+            if (!(error instanceof QueekApiError) || attempt >= maxAttempts - 1)
+                throw error;
+            const delay = retryDelayMs(error, attempt, options);
+            if (delay === null)
+                throw error;
+            await sleep(delay);
+        }
+    }
 }
+/**
+ * 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 function createQueekClient(clientOptions) {
     const base = resolveApiBase(clientOptions.apiBase, clientOptions.allowedApiHosts ?? []);
     const fetchImpl = clientOptions.fetchImpl ?? fetch;
@@ -215,46 +341,23 @@ export function createQueekClient(clientOptions) {
         if (isWriteMethod(upper)) {
             headers.set("Idempotency-Key", options.idempotencyKey ?? newIdempotencyKey());
         }
+        const signal = requestSignal(options.signal, options.timeoutMs ?? clientOptions.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
         let response;
+        let text;
         try {
-            response = await fetchImpl(url.toString(), { method: upper, headers, body, signal: options.signal });
+            response = await fetchImpl(url.toString(), { method: upper, headers, body, signal });
+            text = await response.text();
         }
         catch (cause) {
-            throw new QueekApiError({
-                status: 0,
-                code: "network_error",
-                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
-            });
+            throw transportError(cause, options.signal);
         }
-        const text = await response.text();
-        const parsed = text === "" ? null : tryParseJson(text);
         if (!response.ok) {
-            throw queekApiErrorFromResponse(response.status, parsed, response.headers);
+            throw queekApiErrorFromResponse(response.status, text === "" ? null : tryParseJson(text), response.headers);
         }
-        return parsed;
+        return parseSuccessBody(response, text);
     }
     async function requestWithRetry(method, path, options = {}) {
-        const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
-        const baseDelayMs = options.baseDelayMs ?? 250;
-        const maxDelayMs = options.maxDelayMs ?? 5000;
-        const sleep = options.sleep ?? defaultSleep;
-        // One key for every attempt: Queek replays same-key+same-body writes
-        // instead of duplicating them, so retrying a write is safe.
-        const idempotencyKey = options.idempotencyKey ?? (isWriteMethod(method) ? newIdempotencyKey() : undefined);
-        let lastError;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            try {
-                return await request(method, path, { ...options, idempotencyKey });
-            }
-            catch (error) {
-                lastError = error;
-                const retryable = error instanceof QueekApiError && isRetryable(error);
-                if (!retryable || attempt === maxAttempts - 1)
-                    throw error;
-                await sleep(retryDelayMs(error, attempt, baseDelayMs, maxDelayMs));
-            }
-        }
-        throw lastError;
+        return runWithRetry(method, options, (idempotencyKey) => request(method, path, { ...options, idempotencyKey }));
     }
     return {
         getStore: (signal) => request("GET", "/store", { signal }),
@@ -262,7 +365,11 @@ export function createQueekClient(clientOptions) {
         requestWithRetry,
     };
 }
-function tryParseJson(text) {
+/**
+ * Parse a non-JSON-safe error body: JSON when it parses, otherwise the first
+ * 500 characters as the error `message`.
+ */
+export function tryParseJson(text) {
     try {
         return JSON.parse(text);
     }
@@ -270,4 +377,54 @@ function tryParseJson(text) {
         return { message: text.slice(0, 500) };
     }
 }
-//# sourceMappingURL=client.js.map
+/**
+ * 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 function parseSuccessBody(response, text) {
+    if (text === "")
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new QueekApiError({
+            status: response.status,
+            code: "invalid_response",
+            message: `Queek answered HTTP ${response.status} with a body that is not JSON. Retry; if it persists, quote the request id to Queek support.`,
+            requestId: response.headers.get("x-request-id") ?? undefined,
+            cause,
+        });
+    }
+}
+/**
+ * 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 async function* paginate(client, path, options = {}) {
+    let cursor;
+    while (true) {
+        const page = await client.requestWithRetry("GET", path, {
+            ...options.retry,
+            query: { ...options.query, limit: options.limit, starting_after: cursor },
+            signal: options.signal,
+        });
+        yield* page.data;
+        if (!page.has_more)
+            return;
+        if (typeof page.next_cursor !== "string" || page.next_cursor === "" || page.next_cursor === cursor) {
+            throw new QueekApiError({
+                status: 200,
+                code: "invalid_response",
+                message: `Queek reported more rows for ${path} but sent no new next_cursor, so paging stopped. Retry; if it persists, quote the request id to Queek support.`,
+            });
+        }
+        cursor = page.next_cursor;
+    }
+}

package/dist/collected.d.ts

@@ -99,4 +99,3 @@ export declare function createRecord(client: QueekClient, submit: {
     idempotencyKey?: string;
 }): Promise<unknown>;
 export {};
-//# sourceMappingURL=collected.d.ts.map

package/dist/collected.js

@@ -56,4 +56,3 @@ export async function createRecord(client, submit, options = {}) {
     });
     return response.data;
 }
-//# sourceMappingURL=collected.js.map

package/dist/crypto.d.ts

@@ -1,6 +1,16 @@
+/**
+ * Parse `APP_ENCRYPTION_KEY` (base64 or hex of 32 bytes, or a raw 32-character
+ * string) into the AES-256 key. Prefer random bytes: a raw string key is only
+ * as strong as the text you chose. Throws with a fix when the value is
+ * missing or the wrong length.
+ *
+ * @example
+ * const key = parseStoreKey(process.env.APP_ENCRYPTION_KEY);
+ */
 export declare function parseStoreKey(raw: string | undefined): Buffer;
 /** Non-secret fingerprint for logs (first 4 bytes, hex). Reveals nothing usable. */
 export declare function storeKeyFingerprint(key: Buffer): string;
+/** Encrypt `plaintext` with AES-256-GCM into a `v1.<iv>.<ciphertext+tag>` envelope. */
 export declare function encryptSecret(plaintext: string, key: Buffer): string;
+/** Decrypt an envelope made by {@link encryptSecret}. Throws a plain `Error` (with `cause`) on a wrong key or altered value. */
 export declare function decryptSecret(envelope: string, key: Buffer): string;
-//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.js

@@ -11,6 +11,15 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
  */
 const ENVELOPE_VERSION = "v1";
 const IV_BYTES = 12;
+/**
+ * Parse `APP_ENCRYPTION_KEY` (base64 or hex of 32 bytes, or a raw 32-character
+ * string) into the AES-256 key. Prefer random bytes: a raw string key is only
+ * as strong as the text you chose. Throws with a fix when the value is
+ * missing or the wrong length.
+ *
+ * @example
+ * const key = parseStoreKey(process.env.APP_ENCRYPTION_KEY);
+ */
 export function parseStoreKey(raw) {
     if (!raw || raw.trim() === "") {
         throw new Error("Missing store encryption key: set APP_ENCRYPTION_KEY to base64 or hex of 32 random bytes (`queek app dev` mints one into .queek/.env.local on first run; otherwise generate with node -e \"console.log(require('node:crypto').randomBytes(32).toString('base64'))\" and keep it in your secrets manager — key + DB loss = working data lost).");
@@ -38,7 +47,7 @@ export function parseStoreKey(raw) {
     candidates.push(Buffer.from(value, "utf8"));
     const key = candidates.find((candidate) => candidate.length === 32);
     if (!key) {
-        throw new Error("Invalid APP_ENCRYPTION_KEY: must decode to exactly 32 bytes (base64 or hex).");
+        throw new Error("Invalid APP_ENCRYPTION_KEY: it must decode to exactly 32 bytes (base64 or hex). Generate one with `node -e \"console.log(require('node:crypto').randomBytes(32).toString('base64'))\"`.");
     }
     return key;
 }
@@ -46,31 +55,37 @@ export function parseStoreKey(raw) {
 export function storeKeyFingerprint(key) {
     return key.subarray(0, 4).toString("hex");
 }
+/** Encrypt `plaintext` with AES-256-GCM into a `v1.<iv>.<ciphertext+tag>` envelope. */
 export function encryptSecret(plaintext, key) {
     if (key.length !== 32)
-        throw new Error("Encryption key must be 32 bytes.");
+        throw new Error(`Encryption key must be exactly 32 bytes, got ${key.length}. Build it with parseStoreKey().`);
     const iv = randomBytes(IV_BYTES);
     const cipher = createCipheriv("aes-256-gcm", key, iv);
     const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const tag = cipher.getAuthTag();
     return [ENVELOPE_VERSION, iv.toString("base64"), Buffer.concat([ciphertext, tag]).toString("base64")].join(".");
 }
+/** Decrypt an envelope made by {@link encryptSecret}. Throws a plain `Error` (with `cause`) on a wrong key or altered value. */
 export function decryptSecret(envelope, key) {
     if (key.length !== 32)
-        throw new Error("Encryption key must be 32 bytes.");
+        throw new Error(`Encryption key must be exactly 32 bytes, got ${key.length}. Build it with parseStoreKey().`);
     const parts = envelope.split(".");
     if (parts.length !== 3 || parts[0] !== ENVELOPE_VERSION) {
-        throw new Error("Unrecognized secret envelope (expected v1.<iv>.<ciphertext>).");
+        throw new Error("Unrecognized secret envelope: expected `v1.<iv>.<ciphertext>`. The stored value was not written by this SDK or was truncated.");
     }
     const iv = Buffer.from(parts[1], "base64");
     const raw = Buffer.from(parts[2], "base64");
     if (iv.length !== IV_BYTES || raw.length < 17) {
-        throw new Error("Corrupt secret envelope.");
+        throw new Error("Corrupt secret envelope: the IV or ciphertext has the wrong length. Restore the row from a backup.");
     }
     const tag = raw.subarray(raw.length - 16);
     const ciphertext = raw.subarray(0, raw.length - 16);
     const decipher = createDecipheriv("aes-256-gcm", key, iv);
     decipher.setAuthTag(tag);
-    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    try {
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    }
+    catch (cause) {
+        throw new Error("Could not decrypt a stored secret: it was written with a different APP_ENCRYPTION_KEY, or the value was changed. Restore the original key; without it the secret cannot be recovered.", { cause });
+    }
 }
-//# sourceMappingURL=crypto.js.map

package/dist/delivery.d.ts

@@ -39,6 +39,23 @@ export interface DeliveryResult {
 export declare function readHeader(headers: CoreHeaders, name: string): string | undefined;
 /** Decode untouched body bytes to the exact string Queek signed. */
 export declare function decodeBody(rawBody: Uint8Array | Buffer | string): string;
+/** Where a callback failed, passed to `onError`. */
+export interface DeliveryFailure {
+    /** `install`, `uninstall`, `settings`, `scopes_update` or `webhook`. */
+    stage: string;
+    /** The `webhook-id` header of the delivery that failed. */
+    eventId: string;
+    /** The topic, for webhook deliveries. */
+    topic?: string;
+}
+/** Receives the error a callback threw. The delivery still answers 500 so Queek retries. */
+export type DeliveryErrorHandler = (error: unknown, failure: DeliveryFailure) => void;
+/**
+ * Surface the error a callback threw, so a 500 is never a mystery. Calls the
+ * app's `onError` when given, otherwise logs the error name and message
+ * (secrets redacted) to stderr. A throwing `onError` cannot change the
+ * response.
+ */
+export declare function reportDeliveryFailure(onError: DeliveryErrorHandler | undefined, error: unknown, failure: DeliveryFailure): void;
 /** Build the layer-2 `Response` from a layer-1 result. */
 export declare function toResponse(result: DeliveryResult): Response;
-//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.js

@@ -1,19 +1,4 @@
-/**
- * Shared plumbing for the framework-free delivery core (layer 1).
- *
- * Layer 1 functions take plain data — untouched body bytes plus headers —
- * and return plain `{ status, body }` results. They reference zero
- * request/response types (no `Request`, no framework), so any framework
- * that can hand over the raw body bytes can use them. Layer 2
- * (`handleInstallRequest` / `handleWebhookRequest`) adapts the Web
- * standard onto this core; `@usequeek/app-sdk/hono` adapts Hono onto
- * layer 2.
- *
- * The raw-body rule: `rawBody` must be the exact bytes Queek signed (the
- * Standard Webhooks signature covers `{id}.{timestamp}.{body}`). Never pass
- * a parsed-then-restringified body — JSON re-serialization changes bytes
- * (spacing, key order) and the signature will not verify.
- */
+import { createLogger } from "./logger.js";
 /** Case-insensitive header lookup across `Headers` and plain (possibly lowercased, possibly array-valued) objects. */
 export function readHeader(headers, name) {
     if (headers instanceof Headers) {
@@ -35,8 +20,32 @@ export function decodeBody(rawBody) {
         return rawBody;
     return new TextDecoder("utf-8").decode(rawBody);
 }
+let defaultLogger = null;
+/**
+ * Surface the error a callback threw, so a 500 is never a mystery. Calls the
+ * app's `onError` when given, otherwise logs the error name and message
+ * (secrets redacted) to stderr. A throwing `onError` cannot change the
+ * response.
+ */
+export function reportDeliveryFailure(onError, error, failure) {
+    try {
+        if (onError) {
+            onError(error, failure);
+            return;
+        }
+        defaultLogger ??= createLogger({ service: "queek-app-sdk" });
+        defaultLogger.error("queek delivery callback failed; answering 500 so Queek retries", {
+            stage: failure.stage,
+            event_id: failure.eventId,
+            topic: failure.topic,
+            error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+        });
+    }
+    catch {
+        // Reporting must never change the HTTP answer.
+    }
+}
 /** Build the layer-2 `Response` from a layer-1 result. */
 export function toResponse(result) {
     return Response.json(result.body, { status: result.status, headers: result.headers });
 }
-//# sourceMappingURL=delivery.js.map

package/dist/frame.d.ts

@@ -284,4 +284,3 @@ export declare function listenToDashboard(options: FrameBridgeOptions): () => vo
  * blocked open target, non-product pick) — `sendBridgeMessage` skips null.
  */
 export declare function clipOutbound(message: AppOutboundMessage): AppOutboundMessage | null;
-//# sourceMappingURL=frame.d.ts.map

package/dist/frame.js

@@ -728,4 +728,3 @@ export function clipOutbound(message) {
         }
     }
 }
-//# sourceMappingURL=frame.js.map

package/dist/handoff.d.ts

@@ -137,4 +137,3 @@ export interface ScopesUpdateData {
 }
 export type ScopesUpdateEnvelope = HandoffEnvelope<typeof SCOPES_UPDATE_EVENT, ScopesUpdateData>;
 export type HandoffEnvelopeAny = InstallEnvelope | UninstallEnvelope | SettingsEnvelope | ResyncEnvelope | ScopesUpdateEnvelope;
-//# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.js

@@ -27,4 +27,3 @@ export const UNINSTALL_EVENT = "app/uninstalled";
 export const SETTINGS_EVENT = "app/settings_updated";
 export const RESYNC_EVENT = "app/resync";
 export const SCOPES_UPDATE_EVENT = "app/scopes_update";
-//# sourceMappingURL=handoff.js.map

package/dist/hono.d.ts

@@ -29,4 +29,3 @@ export declare function createWebhookHandler(options: WebhookHandlerOptions): Ho
 export declare function createProxyHandler(options: ProxyRequestOptions & {
     onVerified: ProxyResponder;
 }): Hono;
-//# sourceMappingURL=hono.d.ts.map

package/dist/hono.js

@@ -39,4 +39,3 @@ export function createProxyHandler(options) {
     app.get("*", (c) => handleProxyRequest(c.req.raw, requestOptions, onVerified));
     return app;
 }
-//# sourceMappingURL=hono.js.map

package/dist/index.d.ts

@@ -11,7 +11,7 @@
 export { API_KEY_EXPIRED_CODE, API_KEY_REVOKED_CODE, APP_INSTALLATION_GONE_CODE, APP_INSTALLATION_PENDING_CODE, APP_JWT_SKEW_SECONDS, APP_JWT_TTL_SECONDS, APP_PRIVATE_KEY_FORMS, APP_TOKEN_REVOKED_CODE, type AppCredential, AppMintHaltedError, decodePrivateKeyInput, INSUFFICIENT_SCOPE_CODE, INVALID_CLIENT_CODE, INVALID_CLIENT_KEY_CODE, InvalidAppCredentialError, isAppTokenRevoked, isInstallationGone, isInstallationPending, isInsufficientScope, isInvalidClient, isResyncCooldown, isTokenRefusal, loadAppCredential, MAX_MINT_ATTEMPTS, MINT_BACKOFF_BASE_MS, MINT_BACKOFF_MAX_MS, RESYNC_COOLDOWN_CODE, RETRY_JITTER_MAX_MS, type SignAppJwtOptions, signAppJwt, TOKEN_VALIDITY_SKEW_SECONDS, TOO_MANY_REQUESTS_CODE, UnknownInstallationError, } from "./app-auth.js";
 export { type AuthFetchOptions, BRIDGE_TOKEN_TIMEOUT_MS, type InstalledAuth, installAuthFetch, LAUNCH_TOKEN_PARAM, readLaunchToken, stripLaunchToken, } from "./auth-fetch.js";
 export { backgroundTaskCount, type CatchupFailure, type CatchupInstallation, type CatchupOptions, type CatchupResult, type DetachOptions, detach, runInstallationCatchup, } from "./background.js";
-export { apiHostsFromEnv, createQueekClient, DEFAULT_API_HOSTS, devApiHostsFromEnv, InvalidApiBaseError, isWriteMethod, MERCHANT_API_PATH, type MerchantPaths, newIdempotencyKey, type OperationResponse, QueekApiError, type QueekClient, type QueekClientOptions, type QueekErrorDetails, queekApiErrorFromResponse, type RequestOptions, type ResolvedPaths, type RetryOptions, resolveApiBase, type StoreProfile, } from "./client.js";
+export { apiHostsFromEnv, type CursorPage, createQueekClient, DEFAULT_API_HOSTS, DEFAULT_MAX_RETRY_AFTER_MS, DEFAULT_REQUEST_TIMEOUT_MS, devApiHostsFromEnv, InvalidApiBaseError, isWriteMethod, MERCHANT_API_PATH, type MerchantPaths, newIdempotencyKey, type OperationResponse, type PaginateOptions, paginate, QueekApiError, type QueekClient, type QueekClientOptions, type QueekErrorDetails, queekApiErrorFromResponse, type RequestOptions, type ResolvedPaths, type RetryOptions, resolveApiBase, type StoreProfile, } from "./client.js";
 export { type AlertBody, type AlertSeverity, type CollectedDefinition, type CollectedDefinitionCreate, type CollectedDefinitionUpdate, type CollectedField, collectedDefinitions, createRecord, type MerchantAlert, type SetupNotice, type SetupNoticeBody, type SetupNoticeItem, type SetupNoticeStatus, type SuccessEnvelope, sendAlert, setSetupNotice, } from "./collected.js";
 export { decryptSecret, encryptSecret, parseStoreKey, storeKeyFingerprint, } from "./crypto.js";
 export { type CoreDelivery, type CoreHeaders, type DeliveryResult, decodeBody, type InstallDelivery, readHeader, } from "./delivery.js";
@@ -27,4 +27,3 @@ export { createInstallationStore, createPostgresPool, defaultClearCachedTokenIfM
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, THEME_PARAM, THEME_STORAGE_KEY, type ThemeDocument, type ThemeDocumentElement, type ThemeListenerOptions, type ThemeStorage, themeBootstrapScript, } from "./theme.js";
 export { APP_API_PATH, AppTokenProvider, type AppTokens, createAppTokenProvider, createInstallationClient, type InstallationClientOptions, mintPath, resolveAppApiBase, type TokenProviderOptions, } from "./tokens.js";
 export { handleWebhookDelivery, handleWebhookRequest, QUEEK_TOPIC_HEADER, type QueekWebhookEnvelope, type SecretResolution, type WebhookHandlerContext, type WebhookHandlerFn, type WebhookHandlerOptions, } from "./webhooks.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,7 +11,7 @@
 export { API_KEY_EXPIRED_CODE, API_KEY_REVOKED_CODE, APP_INSTALLATION_GONE_CODE, APP_INSTALLATION_PENDING_CODE, APP_JWT_SKEW_SECONDS, APP_JWT_TTL_SECONDS, APP_PRIVATE_KEY_FORMS, APP_TOKEN_REVOKED_CODE, AppMintHaltedError, decodePrivateKeyInput, INSUFFICIENT_SCOPE_CODE, INVALID_CLIENT_CODE, INVALID_CLIENT_KEY_CODE, InvalidAppCredentialError, isAppTokenRevoked, isInstallationGone, isInstallationPending, isInsufficientScope, isInvalidClient, isResyncCooldown, isTokenRefusal, loadAppCredential, MAX_MINT_ATTEMPTS, MINT_BACKOFF_BASE_MS, MINT_BACKOFF_MAX_MS, RESYNC_COOLDOWN_CODE, RETRY_JITTER_MAX_MS, signAppJwt, TOKEN_VALIDITY_SKEW_SECONDS, TOO_MANY_REQUESTS_CODE, UnknownInstallationError, } from "./app-auth.js";
 export { BRIDGE_TOKEN_TIMEOUT_MS, installAuthFetch, LAUNCH_TOKEN_PARAM, readLaunchToken, stripLaunchToken, } from "./auth-fetch.js";
 export { backgroundTaskCount, detach, runInstallationCatchup, } from "./background.js";
-export { apiHostsFromEnv, createQueekClient, DEFAULT_API_HOSTS, devApiHostsFromEnv, InvalidApiBaseError, isWriteMethod, MERCHANT_API_PATH, newIdempotencyKey, QueekApiError, queekApiErrorFromResponse, resolveApiBase, } from "./client.js";
+export { apiHostsFromEnv, createQueekClient, DEFAULT_API_HOSTS, DEFAULT_MAX_RETRY_AFTER_MS, DEFAULT_REQUEST_TIMEOUT_MS, devApiHostsFromEnv, InvalidApiBaseError, isWriteMethod, MERCHANT_API_PATH, newIdempotencyKey, paginate, QueekApiError, queekApiErrorFromResponse, resolveApiBase, } from "./client.js";
 export { collectedDefinitions, createRecord, sendAlert, setSetupNotice, } from "./collected.js";
 export { decryptSecret, encryptSecret, parseStoreKey, storeKeyFingerprint, } from "./crypto.js";
 export { decodeBody, readHeader, } from "./delivery.js";
@@ -27,4 +27,3 @@ export { createInstallationStore, createPostgresPool, defaultClearCachedTokenIfM
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, THEME_PARAM, THEME_STORAGE_KEY, themeBootstrapScript, } from "./theme.js";
 export { APP_API_PATH, AppTokenProvider, createAppTokenProvider, createInstallationClient, mintPath, resolveAppApiBase, } from "./tokens.js";
 export { handleWebhookDelivery, handleWebhookRequest, QUEEK_TOPIC_HEADER, } from "./webhooks.js";
-//# sourceMappingURL=index.js.map

package/dist/install-handlers.d.ts

@@ -1,4 +1,4 @@
-import { type DeliveryResult, type InstallDelivery } from "./delivery.js";
+import { type DeliveryErrorHandler, type DeliveryResult, type InstallDelivery } from "./delivery.js";
 import { type InstallData, type InstallEnvelope, type ScopesUpdateEnvelope, type SettingsEnvelope, type UninstallEnvelope } from "./handoff.js";
 import type { InstallationRecord, InstallationStore } from "./store.js";
 /**
@@ -49,12 +49,18 @@ export interface InstallCallbacks {
     /** Defaults to refreshing the cached grant (dropping the cached token when it moved). */
     onScopesUpdate?: (envelope: ScopesUpdateEnvelope) => Promise<void>;
 }
+/** Options for the install handoff handlers. `appSecret` and `store` are required; every callback has a safe default. */
 export interface InstallHandlerOptions extends InstallCallbacks {
     /** The app signing secret (`whsec_…`) from Queek registration. */
     appSecret: string;
     store: InstallationStore;
     nowSeconds?: number;
     maxSkewSeconds?: number;
+    /**
+     * Called with the error a callback or store write threw, before the 500
+     * goes back. Without it the error is logged to stderr (secrets redacted).
+     */
+    onError?: DeliveryErrorHandler;
 }
 /**
  * Build the storable installation record from install `data`. Timestamps
@@ -93,12 +99,26 @@ export declare function saveResyncedInstallation(existing: InstallationRecord, d
  * `uninstall`, or `settings`, taken from the input path's last segment)
  * from plain data — no `Request`, no framework. Same options, same
  * behaviour, same errors/status codes at every layer.
+ *
+ * Answers 401 for a missing header, stale timestamp or bad signature, 400
+ * for a body that is not the expected envelope, 409 for a repeated
+ * `webhook-id`, 404 for an unknown route, and 500 when your callback or the
+ * store write throws (Queek then retries).
+ *
+ * @example
+ * const result = await handleInstallDelivery(
+ *   { rawBody, headers, method: "POST", path: "/queek/install" },
+ *   { appSecret: process.env.APP_SIGNING_SECRET ?? "", store },
+ * );
+ * // reply with result.status and result.body
  */
 export declare function handleInstallDelivery(input: InstallDelivery, options: InstallHandlerOptions): Promise<DeliveryResult>;
 /**
  * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads
  * `await request.arrayBuffer()` + headers, calls the core, builds the
  * `Response`.
+ *
+ * @example
+ * export const POST = (request: Request) => handleInstallRequest(request, { appSecret, store });
  */
 export declare function handleInstallRequest(request: Request, options: InstallHandlerOptions): Promise<Response>;
-//# sourceMappingURL=install-handlers.d.ts.map