@usequeek/app-sdk 0.6.1 → 0.7.0

package/dist/client.js

@@ -24,7 +24,7 @@ function parseHostList(raw, varName) {
     });
 }
 /**
- * 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.
  */
@@ -35,7 +35,7 @@ export function apiHostsFromEnv(env = process.env) {
     return parseHostList(raw, ENV_HOSTS_VAR);
 }
 /**
- * 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.
@@ -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

@@ -1,15 +1,14 @@
 import type { QueekClient } from "./client.js";
 import type { components } from "./merchant-schema.js";
 /**
- * Installation-bound app writes (S3a): the setup notice, merchant alerts,
+ * Installation-bound app writes: the setup notice, merchant alerts,
  * collected definitions and record submits. Every helper takes a
- * `QueekClient` built from the installation's own key — the backend
- * resolves the installation from that key, never from the body — and
- * returns the decoded `data` payload of the success envelope.
+ * `QueekClient` built from the installation's own key — Queek resolves
+ * the installation from that key, never from the body — and returns the
+ * decoded `data` payload of the success envelope.
  *
- * Contracts: config/vendor_api_keys.php (Apps group + Forms proof path)
- * at queek_backend@c1fa1c31; request shapes below are the generated
- * `components` schemas from the same backend's merchant export.
+ * Request shapes below are the generated `components` schemas of the
+ * Merchant API spec (https://api.usequeek.com/docs/merchant.json).
  */
 type Schemas = components["schemas"];
 export interface SuccessEnvelope<T> {
@@ -66,9 +65,9 @@ export interface CollectedDefinitionUpdate {
 }
 /**
  * A collected definition as the Merchant API returns it: the generated
- * MetaobjectDefinitionResource (typed since bf7329af) with the create
- * endpoint's field vocabulary for `fields` (the generated `unknown[]`
- * carries no field shape).
+ * MetaobjectDefinitionResource with the create endpoint's field
+ * vocabulary for `fields` (the generated `unknown[]` carries no field
+ * shape).
  */
 export type CollectedDefinition = Omit<Schemas["MetaobjectDefinitionResource"], "fields"> & {
     fields: CollectedField[];
@@ -88,10 +87,10 @@ export declare const collectedDefinitions: {
 /**
  * POST records — one record under the installation's own type.
  *
- * `values` is a `{field_key: value}` object (spec-correct since
- * bf7329af: object + additionalProperties; the writer validates pairs). A
- * fresh Idempotency-Key is generated per call unless the caller passes
- * one — no two submits ever share a key.
+ * `values` is a `{field_key: value}` object (an object with
+ * additionalProperties in the spec; Queek validates the pairs). A fresh
+ * Idempotency-Key is generated per call unless the caller passes one — no
+ * two submits ever share a key.
  */
 export declare function createRecord(client: QueekClient, submit: {
     definition: string;
@@ -100,4 +99,3 @@ export declare function createRecord(client: QueekClient, submit: {
     idempotencyKey?: string;
 }): Promise<unknown>;
 export {};
-//# sourceMappingURL=collected.d.ts.map

package/dist/collected.js

@@ -44,10 +44,10 @@ export const collectedDefinitions = {
 /**
  * POST records — one record under the installation's own type.
  *
- * `values` is a `{field_key: value}` object (spec-correct since
- * bf7329af: object + additionalProperties; the writer validates pairs). A
- * fresh Idempotency-Key is generated per call unless the caller passes
- * one — no two submits ever share a key.
+ * `values` is a `{field_key: value}` object (an object with
+ * additionalProperties in the spec; Queek validates the pairs). A fresh
+ * Idempotency-Key is generated per call unless the caller passes one — no
+ * two submits ever share a key.
  */
 export async function createRecord(client, submit, options = {}) {
     const response = await client.request("POST", "/records", {
@@ -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

@@ -1,7 +1,7 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 /**
- * AES-256-GCM envelope encryption for secrets at rest (installation api_key
- * and webhook_secret). One random 96-bit IV per value; the stored string is
+ * AES-256-GCM envelope encryption for secrets at rest (installation tokens,
+ * webhook/proxy/embed secrets and settings). One random 96-bit IV per value; the stored string is
  * `v1.<base64 iv>.<base64 ciphertext+tag>`.
  *
  * The 32-byte data key comes from the environment (`APP_ENCRYPTION_KEY`, base64
@@ -11,9 +11,18 @@ 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.");
+        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).");
     }
     const value = raw.trim();
     const candidates = [];
@@ -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

@@ -9,14 +9,10 @@
  * standard onto this core; `@usequeek/app-sdk/hono` adapts Hono onto
  * layer 2.
  *
- * The raw-body rule (Stripe's model:
- * `stripe.webhooks.constructEvent(rawBody, sigHeader, secret)` —
- * https://docs.stripe.com/webhooks: "Stripe requires the raw body of the
- * request to perform signature verification… Any manipulation to the raw
- * body of the request causes the verification to fail"): `rawBody` must be
- * the exact bytes Queek signed. Never pass a parsed-then-restringified
- * body — JSON re-serialization changes bytes (spacing, key order) and the
- * signature will not verify.
+ * 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.
  */
 /** Headers as any framework holds them: a `Headers` instance, or a plain object (Express-style: lowercased keys, array values allowed). */
 export type CoreHeaders = Record<string, string | string[] | undefined> | Headers;
@@ -43,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,23 +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 (Stripe's model:
- * `stripe.webhooks.constructEvent(rawBody, sigHeader, secret)` —
- * https://docs.stripe.com/webhooks: "Stripe requires the raw body of the
- * request to perform signature verification… Any manipulation to the raw
- * body of the request causes the verification to fail"): `rawBody` must be
- * the exact bytes Queek signed. 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) {
@@ -39,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

@@ -1,14 +1,14 @@
 /**
- * Framed-page bridge client, v1 (U2): the browser-safe half of the
- * dashboard bridge. Carries NO secret and performs NO verification — it only
- * shapes and addresses messages. The dashboard (queek-merchant) enforces
- * origin+source binding and mints tokens; the app backend verifies them via
- * `./server` (`verifySessionToken`).
+ * Framed-page bridge client, v1: the browser-safe half of the dashboard
+ * bridge. Carries NO secret and performs NO verification — it only shapes
+ * and addresses messages. The dashboard enforces origin+source binding and
+ * mints tokens; the app's server verifies them via `./server`
+ * (`verifySessionToken`).
  *
- * Byte-compatible with today's protocol (`ready`/`token`/`resize`/
- * `resize-ack`/`ack`, sources `queek-app`/`queek-merchant`, exact-origin
- * postMessage): v1 only ADDS optional fields and new message types, and both
- * directions ignore unknown types.
+ * Compatible with the v0 protocol (`ready`/`token`/`resize`/`resize-ack`/
+ * `ack`, sources `queek-app`/`queek-merchant`, exact-origin postMessage):
+ * v1 only ADDS optional fields and new message types, and both directions
+ * ignore unknown types.
  *
  * DOM-free by design (structural minimal types): the app passes its own
  * window/parent in, so this module needs no DOM lib and stays import-safe
@@ -240,7 +240,7 @@ export declare function sendReady(dashboardOrigin: string, target?: EmbedPostTar
  * (via `sendBridgeMessage`) clamps and drops non-finite asks.
  */
 export declare function sendResize(dashboardOrigin: string, target: EmbedPostTarget | undefined, height: number): void;
-/** Delivery confirmation with no state — accepted and ignored by decision. */
+/** Delivery confirmation carrying no state (accepted, no further effect). */
 export declare function sendAck(dashboardOrigin: string, target?: EmbedPostTarget): void;
 /**
  * Drive the dashboard title bar (heading + up to 5 secondary actions).
@@ -257,7 +257,7 @@ export declare function sendToast(dashboardOrigin: string, target: EmbedPostTarg
 }): void;
 /** Show (dirty) or hide (clean) the dashboard save bar. Bad states are dropped downstream. */
 export declare function sendSaveBar(dashboardOrigin: string, target: EmbedPostTarget | undefined, state: SaveBarState): void;
-/** Report an in-app move so the dashboard can mirror it in its URL (U2b). */
+/** Report an in-app move so the dashboard can mirror it in its URL. */
 export declare function sendNavigated(dashboardOrigin: string, target: EmbedPostTarget | undefined, path: string): void;
 /**
  * Ask the dashboard to open a dashboard path or https URL (sandbox-safe).
@@ -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