@usequeek/app-sdk 0.6.1 → 0.7.0

package/dist/frame.js

@@ -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
@@ -449,7 +449,7 @@ export function sendReady(dashboardOrigin, target, options) {
 export function sendResize(dashboardOrigin, target, height) {
     sendBridgeMessage(dashboardOrigin, target, { source: APP_SOURCE, type: "resize", height });
 }
-/** Delivery confirmation with no state — accepted and ignored by decision. */
+/** Delivery confirmation carrying no state (accepted, no further effect). */
 export function sendAck(dashboardOrigin, target) {
     sendBridgeMessage(dashboardOrigin, target, { source: APP_SOURCE, type: "ack" });
 }
@@ -483,7 +483,7 @@ export function sendToast(dashboardOrigin, target, message, options) {
 export function sendSaveBar(dashboardOrigin, target, state) {
     sendBridgeMessage(dashboardOrigin, target, { source: APP_SOURCE, type: "save-bar", state });
 }
-/** 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 function sendNavigated(dashboardOrigin, target, path) {
     sendBridgeMessage(dashboardOrigin, target, { source: APP_SOURCE, type: "navigated", path });
 }
@@ -728,4 +728,3 @@ export function clipOutbound(message) {
         }
     }
 }
-//# sourceMappingURL=frame.js.map

package/dist/handoff.d.ts

@@ -1,26 +1,26 @@
 /**
  * Typed payloads for Queek's server-to-server install handoff.
  *
- * Source of truth: queek_backend `App\Services\Apps\AppInstallService`
- * (`installPayload()`, `uninstallPayload()`, `settingsPayload()`,
- * `handoffBody()`). The signed body envelope is:
+ * The signed body envelope is:
  *
  *   { id, type, api_version: "v1", created_at, data }
  *
  * `type` is `app/installed` | `app/uninstalled` | `app/settings_updated`
- * | `app/resync` | `app/scopes_update`. The handoff POST carries the Standard Webhooks headers
- * (`webhook-id`, `webhook-timestamp`, `webhook-signature`) signed with the
- * APP's signing secret (`whsec_…`, minted once at `app:register`), NOT the
+ * | `app/resync` | `app/scopes_update`. The handoff POST carries the
+ * Standard Webhooks headers (`webhook-id`, `webhook-timestamp`,
+ * `webhook-signature`) signed with the APP's signing secret (`whsec_…`,
+ * minted when the app is registered on the Queek Developer page), NOT the
  * per-installation webhook secret. The per-installation `webhook_secret`
  * arrives INSIDE the install payload (`data.webhook_secret`) — once — so
  * the app can verify the topic events it is about to receive.
  *
- * `app/resync` is the installation resync handoff (backend
- * `AppInstallService::resyncPayload()`, delivered to the app's
- * `settings_url` falling back to `install_url`): the install-shaped data
+ * `app/resync` is the installation resync handoff (delivered to the app's
+ * `settings_url`, falling back to `install_url`): the install-shaped data
  * plus the resync-only `secret_rotated` flag, over the same signed channel
  * with the same verification rules. Both the `/install` and `/settings`
  * handlers accept it.
+ *
+ * See https://docs.usequeek.com/docs/apps/sdk
  */
 export declare const INSTALL_EVENT = "app/installed";
 export declare const UNINSTALL_EVENT = "app/uninstalled";
@@ -43,45 +43,43 @@ export interface InstallData {
     /** The Merchant API base for this store (e.g. https://api.usequeek.com/api/v1/merchant). */
     api_base: string;
     /**
-     * No store-callable credential crosses the handoff any more (S1, SDK
-     * 0.2.0): the app mints short-lived installation tokens with its
-     * asymmetric app key (`acquireToken()`) and caches them encrypted in its
-     * own database. The same envelope redelivers `webhook_secret` + the
-     * non-secret settings snapshot on resync.
+     * No store-callable credential crosses the handoff: the app mints
+     * short-lived installation tokens with its asymmetric app key
+     * (`acquireToken()`) and caches them encrypted in its own database. The
+     * same envelope redelivers `webhook_secret` + the non-secret settings
+     * snapshot on resync.
      */
     scopes: string[];
     settings: Record<string, unknown>;
     /** The installation endpoint's `whsec_…` secret, handed over ONCE per rotation. */
     webhook_secret: string | null;
     /**
-     * The installation's `whsec_…` proxy secret (backend `proxy_secret`),
-     * handed over ONCE per install/resync over the signed channel. The
-     * booking app signs slot-claims with it; core verifies the HMAC
-     * against the same installation secret. Null for apps without a
-     * proxy — the key's absence is the signal. Source of truth:
-     * queek_backend `App\Services\Apps\AppInstallService::installPayload()`.
+     * The installation's `whsec_…` proxy secret, handed over ONCE per
+     * install/resync over the signed channel. Queek signs storefront proxy
+     * reads with it (see `proxy.ts`), and an app can sign claims back to
+     * Queek with it (for example slot-claims); Queek verifies the HMAC
+     * against the same installation secret. Null for apps without a proxy —
+     * the key's absence is the signal.
      */
     proxy_secret: string | null;
     /**
-     * The installation's `embsec_…` embed secret (backend `embed_secret`),
-     * handed over on install/resync: the HS256 key of the dashboard session
-     * tokens its embedded merchant page receives (verify with
-     * `@usequeek/app-sdk/server` `verifySessionToken`). Null for apps
-     * without a merchant page.
+     * The installation's `embsec_…` embed secret, handed over on
+     * install/resync: the HS256 key of the dashboard session tokens its
+     * embedded merchant page receives (verify with `@usequeek/app-sdk/server`
+     * `verifySessionToken`). Null for apps without a merchant page.
      */
     embed_secret?: string | null;
     /**
      * The app's own id, exactly as the session token signs it (`app_id`
-     * claim) — the verifier binds it. Source of truth: queek_backend
-     * `AppInstallService::installPayload()` / `resyncPayload()`.
+     * claim) — the verifier binds it.
      */
     app_id?: string | null;
     webhook_url: string | null;
     webhook_topics: string[];
     /**
-     * Resync-only (backend `resyncPayload()`): whether the delivery rotated
-     * the endpoint secret (`webhook_secret` holds the new secret when true,
-     * null when the installation has no webhook endpoint). Absent on install.
+     * Resync-only: whether the delivery rotated the endpoint secret
+     * (`webhook_secret` holds the new secret when true, null when the
+     * installation has no webhook endpoint). Absent on install.
      */
     secret_rotated?: boolean | null;
 }
@@ -111,20 +109,19 @@ export type SettingsEnvelope = HandoffEnvelope<typeof SETTINGS_EVENT, SettingsDa
  */
 export type ResyncEnvelope = HandoffEnvelope<typeof RESYNC_EVENT, InstallData>;
 /**
- * The installation `p_id` the backend addresses a handoff to. The
- * scopes_update handoff carries ONLY the `p_id` (never the UUID — the
- * backend `p_id` rule), so `id` is optional here: present on
- * install-shaped payloads, absent on `app/scopes_update`.
+ * The installation `p_id` Queek addresses a handoff to. The
+ * scopes_update handoff carries ONLY the `p_id` (never the UUID), so `id`
+ * is optional here: present on install-shaped payloads, absent on
+ * `app/scopes_update`.
  */
 export interface HandoffPidRef {
-    /** String on the wire (the backend casts); the SDK normalises via `normalisePid`, so a JSON integer still matches. */
+    /** A string on the wire; the SDK normalises via `normalisePid`, so a JSON integer still matches. */
     p_id: string | number;
     id?: string;
 }
 /**
- * The grant-change handoff (backend
- * `AppInstallService::scopesUpdatePayload()`, queued per grant change over
- * the same signed channel): the installation `p_id` + the EFFECTIVE grant
+ * The grant-change handoff (sent per grant change over the same signed
+ * channel): the installation `p_id` + the EFFECTIVE grant
  * (grant ∩ tracked manifest — what the installation's tokens now carry,
  * byte for byte). Carries no settings and no secrets: the app refreshes
  * its cached grant from `scopes` and drops its cached token when the
@@ -140,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

@@ -1,30 +1,29 @@
 /**
  * Typed payloads for Queek's server-to-server install handoff.
  *
- * Source of truth: queek_backend `App\Services\Apps\AppInstallService`
- * (`installPayload()`, `uninstallPayload()`, `settingsPayload()`,
- * `handoffBody()`). The signed body envelope is:
+ * The signed body envelope is:
  *
  *   { id, type, api_version: "v1", created_at, data }
  *
  * `type` is `app/installed` | `app/uninstalled` | `app/settings_updated`
- * | `app/resync` | `app/scopes_update`. The handoff POST carries the Standard Webhooks headers
- * (`webhook-id`, `webhook-timestamp`, `webhook-signature`) signed with the
- * APP's signing secret (`whsec_…`, minted once at `app:register`), NOT the
+ * | `app/resync` | `app/scopes_update`. The handoff POST carries the
+ * Standard Webhooks headers (`webhook-id`, `webhook-timestamp`,
+ * `webhook-signature`) signed with the APP's signing secret (`whsec_…`,
+ * minted when the app is registered on the Queek Developer page), NOT the
  * per-installation webhook secret. The per-installation `webhook_secret`
  * arrives INSIDE the install payload (`data.webhook_secret`) — once — so
  * the app can verify the topic events it is about to receive.
  *
- * `app/resync` is the installation resync handoff (backend
- * `AppInstallService::resyncPayload()`, delivered to the app's
- * `settings_url` falling back to `install_url`): the install-shaped data
+ * `app/resync` is the installation resync handoff (delivered to the app's
+ * `settings_url`, falling back to `install_url`): the install-shaped data
  * plus the resync-only `secret_rotated` flag, over the same signed channel
  * with the same verification rules. Both the `/install` and `/settings`
  * handlers accept it.
+ *
+ * See https://docs.usequeek.com/docs/apps/sdk
  */
 export const INSTALL_EVENT = "app/installed";
 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

@@ -19,14 +19,13 @@ export declare function createInstallHandlers(options: InstallHandlerOptions): H
 /** Mount the signed topic-delivery receiver (`POST /`). */
 export declare function createWebhookHandler(options: WebhookHandlerOptions): Hono;
 /**
- * Mount the signed app-proxy reader (`GET`, phase 1 is read-only by binding
- * rule) — a thin wrapper built ONLY on the layer-2 Web-standard handler
+ * Mount the signed app-proxy reader (`GET` only, proxy reads are
+ * read-only) — a thin wrapper built ONLY on the layer-2 Web-standard handler
  * (`handleProxyRequest` in the root entry). Mount it where the proxy lives
  * (`app.route("/proxy", createProxyHandler(...))`); `options.path` stays
- * the Queek-side canonical path (`/apps/<subpath>/<rest>`) the backend
+ * the Queek-side canonical path (`/apps/<subpath>/<rest>`) Queek
  * signed, and `onVerified` owns the shopper-facing body.
  */
 export declare function createProxyHandler(options: ProxyRequestOptions & {
     onVerified: ProxyResponder;
 }): Hono;
-//# sourceMappingURL=hono.d.ts.map

package/dist/hono.js

@@ -26,11 +26,11 @@ export function createWebhookHandler(options) {
     return app;
 }
 /**
- * Mount the signed app-proxy reader (`GET`, phase 1 is read-only by binding
- * rule) — a thin wrapper built ONLY on the layer-2 Web-standard handler
+ * Mount the signed app-proxy reader (`GET` only, proxy reads are
+ * read-only) — a thin wrapper built ONLY on the layer-2 Web-standard handler
  * (`handleProxyRequest` in the root entry). Mount it where the proxy lives
  * (`app.route("/proxy", createProxyHandler(...))`); `options.path` stays
- * the Queek-side canonical path (`/apps/<subpath>/<rest>`) the backend
+ * the Queek-side canonical path (`/apps/<subpath>/<rest>`) Queek
  * signed, and `onVerified` owns the shopper-facing body.
  */
 export function createProxyHandler(options) {
@@ -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,10 +1,9 @@
-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";
 /**
  * Framework-agnostic handlers for Queek's signed server-to-server handoff
- * (`AppInstallService::deliver()` in queek_backend) in three thin layers:
- * layer 1 `handleInstallDelivery(input, options)` takes plain data
+ * in three thin layers: layer 1 `handleInstallDelivery(input, options)` takes plain data
  * (untouched body bytes + headers, plus method/path for routing) and
  * returns a plain `{ status, body }` result — zero request/response types,
  * so whatever request object each framework supports works; layer 2
@@ -13,12 +12,12 @@ import type { InstallationRecord, InstallationStore } from "./store.js";
  *
  * Every handoff — install, uninstall, settings, resync — carries the
  * Standard Webhooks headers signed with the APP signing secret (`whsec_…`,
- * minted once at `app:register`). The app answers 2xx only after the
- * installation is durably stored; anything else makes Queek revoke the
- * just-minted key and mark the install failed (retry = a fresh install).
+ * minted when the app is registered on the Queek Developer page). The app
+ * answers 2xx only after the installation is durably stored; anything else
+ * makes Queek revoke the just-minted key and mark the install failed
+ * (retry = a fresh install).
  *
- * The resync handoff (`type: app/resync`, backend
- * `AppInstallService::resyncPayload()`) redelivers the install-shaped data
+ * The resync handoff (`type: app/resync`) redelivers the install-shaped data
  * — rotated `webhook_secret`, non-secret settings, and recovery copies of
  * `proxy_secret` / `embed_secret` / `app_id` — to the app's `settings_url`,
  * falling back to `install_url`. Both `install` and `settings` accept it
@@ -50,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
@@ -94,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

package/dist/install-handlers.js

@@ -1,4 +1,4 @@
-import { decodeBody, readHeader, toResponse, } from "./delivery.js";
+import { decodeBody, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
 import { INSTALL_EVENT, RESYNC_EVENT, SCOPES_UPDATE_EVENT, SETTINGS_EVENT, UNINSTALL_EVENT, } from "./handoff.js";
 import { MAX_TIMESTAMP_SKEW_SECONDS, verifyQueekSignatureDetailed, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.js";
 import { normaliseNullablePid, normalisePid } from "./store.js";
@@ -14,8 +14,8 @@ export function buildInstallationRecord(data, nowIso = new Date().toISOString())
 function installationRecordFromInstall(data, nowIso) {
     return {
         installationId: data.installation.id,
-        // The installation p_id arrives as a string on the wire (the backend
-        // casts). `normalisePid` stays as tolerance: a JSON integer would reach
+        // The installation p_id arrives as a string on the wire.
+        // `normalisePid` stays as tolerance: a JSON integer would reach
         // here as a JS number, which `node:sqlite` would store as `"1021.0"`
         // in the TEXT column — never equal to the proxy `kid` — so non-string
         // forms still normalise to integer strings.
@@ -24,7 +24,7 @@ function installationRecordFromInstall(data, nowIso) {
         storePid: normaliseNullablePid(data.store.p_id),
         storeName: data.store.name,
         apiBase: data.api_base,
-        // No credential crosses the handoff (S1): a fresh row caches no token
+        // No credential crosses the handoff: a fresh row caches no token
         // (the first call mints one); see `saveResyncedInstallation` for the
         // existing-row path, which keeps the cached token unless the grant
         // changed.
@@ -106,6 +106,18 @@ export function saveResyncedInstallation(existing, data, nowIso = new Date().toI
  * `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 async function handleInstallDelivery(input, options) {
     if ((input.method ?? "POST").toUpperCase() !== "POST") {
@@ -132,6 +144,9 @@ function trailingSegment(path) {
  * 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 async function handleInstallRequest(request, options) {
     return toResponse(await handleInstallDelivery({
@@ -169,6 +184,11 @@ function parseEnvelope(rawBody) {
         return null;
     }
 }
+function hasInstallationId(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        typeof data.installation?.id === "string");
+}
 function isInstallPayload(data) {
     return (!!data &&
         typeof data === "object" &&
@@ -196,14 +216,14 @@ function isScopesUpdatePayload(data) {
 }
 /**
  * Default grant-change apply: find the row by the handoff `p_id` (the
- * scopes_update payload carries no UUID — the backend `p_id` rule) and
+ * scopes_update payload carries no UUID) and
  * refresh its cached grant, dropping the cached token when the grant
  * moved. Unknown `p_id` answers 404 (released, like the settings path).
  */
 async function applyScopesUpdate(store, data) {
-    // The installation p_id arrives as a string on the wire (the backend
-    // casts) — normalise before comparing anyway, exactly like the install
-    // mapping does, so a non-conforming integer form still matches.
+    // The installation p_id arrives as a string on the wire — normalise
+    // before comparing anyway, exactly like the install mapping does, so a
+    // non-conforming integer form still matches.
     const pid = normalisePid(data.installation.p_id);
     const rows = await store.listInstallations();
     const existing = rows.find((row) => row.installationPid === pid) ?? null;
@@ -243,8 +263,9 @@ async function scopesDelivery(rawBody, headers, options) {
             }
         }
     }
-    catch {
+    catch (error) {
         await options.store.releaseWebhookId(checked.id);
+        reportDeliveryFailure(options.onError, error, { stage: "scopes_update", eventId: checked.id });
         return { status: 500, body: { ok: false, error: "scopes_update_failed" } };
     }
     return { status: 200, body: { ok: true } };
@@ -256,8 +277,8 @@ async function installDelivery(rawBody, headers, options) {
     const envelope = parseEnvelope(rawBody);
     if (!envelope)
         return { status: 400, body: { ok: false, error: "invalid_envelope" } };
-    // The grant-change handoff (`type: app/scopes_update`, backend
-    // `scopesUpdatePayload()`) is delivered to the settings URL first,
+    // The grant-change handoff (`type: app/scopes_update`) is delivered to
+    // the settings URL first,
     // falling back to the install URL — both routes accept it with the same
     // verification, claim, and callback-failure rules as every handoff.
     if (envelope.type === SCOPES_UPDATE_EVENT) {
@@ -265,8 +286,8 @@ async function installDelivery(rawBody, headers, options) {
     }
     // The platform resync handoff redelivers the install-shaped data under
     // `type: app/resync` (same signed channel, same verification): it lands
-    // here as well as on `settings` (the backend aims at `settings_url`
-    // first, falling back to `install_url`).
+    // here as well as on `settings` (Queek aims at `settings_url` first,
+    // falling back to `install_url`).
     if (envelope.type !== INSTALL_EVENT && envelope.type !== RESYNC_EVENT) {
         return { status: 400, body: { ok: false, error: "unexpected event type" } };
     }
@@ -291,10 +312,11 @@ async function installDelivery(rawBody, headers, options) {
             await applyResync(options.store, envelope.data);
         }
     }
-    catch {
+    catch (error) {
         // Non-2xx on purpose: Queek revokes the key and the merchant retries
         // as a fresh install. The claim is released so the retry can land.
         await options.store.releaseWebhookId(checked.id);
+        reportDeliveryFailure(options.onError, error, { stage: "install", eventId: checked.id });
         return { status: 500, body: { ok: false, error: "install_failed" } };
     }
     return { status: 200, body: { ok: true } };
@@ -309,6 +331,9 @@ async function uninstallDelivery(rawBody, headers, options) {
     if (envelope.type !== UNINSTALL_EVENT) {
         return { status: 400, body: { ok: false, error: "unexpected event type" } };
     }
+    if (!hasInstallationId(envelope.data)) {
+        return { status: 400, body: { ok: false, error: "invalid uninstall payload" } };
+    }
     if (!(await options.store.claimWebhookId(checked.id))) {
         return { status: 409, body: { ok: false, error: "duplicate delivery" } };
     }
@@ -320,8 +345,9 @@ async function uninstallDelivery(rawBody, headers, options) {
             await options.store.deleteInstallation(envelope.data.installation.id);
         }
     }
-    catch {
+    catch (error) {
         await options.store.releaseWebhookId(checked.id);
+        reportDeliveryFailure(options.onError, error, { stage: "uninstall", eventId: checked.id });
         return { status: 500, body: { ok: false, error: "uninstall_failed" } };
     }
     return { status: 200, body: { ok: true } };
@@ -355,12 +381,16 @@ async function settingsDelivery(rawBody, headers, options) {
         try {
             await applyResync(options.store, envelope.data);
         }
-        catch {
+        catch (error) {
             await options.store.releaseWebhookId(checked.id);
+            reportDeliveryFailure(options.onError, error, { stage: "settings", eventId: checked.id });
             return { status: 500, body: { ok: false, error: "settings_failed" } };
         }
         return { status: 200, body: { ok: true } };
     }
+    if (!hasInstallationId(envelope.data)) {
+        return { status: 400, body: { ok: false, error: "invalid settings payload" } };
+    }
     if (!(await options.store.claimWebhookId(checked.id))) {
         return { status: 409, body: { ok: false, error: "duplicate delivery" } };
     }
@@ -382,10 +412,10 @@ async function settingsDelivery(rawBody, headers, options) {
             });
         }
     }
-    catch {
+    catch (error) {
         await options.store.releaseWebhookId(checked.id);
+        reportDeliveryFailure(options.onError, error, { stage: "settings", eventId: checked.id });
         return { status: 500, body: { ok: false, error: "settings_failed" } };
     }
     return { status: 200, body: { ok: true } };
 }
-//# sourceMappingURL=install-handlers.js.map

package/dist/logger.d.ts

@@ -23,5 +23,11 @@ export interface Logger {
     warn(message: string, fields?: LogFields): void;
     error(message: string, fields?: LogFields): void;
 }
+/**
+ * A JSON-lines logger with secret redaction built in.
+ *
+ * @example
+ * const logger = createLogger({ service: "my-app" });
+ * logger.info("order synced", { order: "ord_123" });
+ */
 export declare function createLogger(options: LoggerOptions): Logger;
-//# sourceMappingURL=logger.d.ts.map

package/dist/logger.js

@@ -12,7 +12,7 @@
 const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
 const SENSITIVE_KEY_RE = /key|secret|token|passwd|password|auth|credential|session/i;
 // Long opaque values Queek and friends mint: sk_live_/sk_test_, pk_*, whsec_*, Bearer …
-// — plus the S1 app credential shapes, which must NEVER reach logs: a whole PEM
+// — plus the app credential shapes, which must NEVER reach logs: a whole PEM
 // private-key block and a bare RS256 JWT (eyJ….….…, with or without a Bearer prefix).
 const SECRET_VALUE_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----|\b(eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|sk_(live|test)_[A-Za-z0-9_-]+|pk_(live|test)_[A-Za-z0-9_-]+|whsec_[A-Za-z0-9+/=_-]+|Bearer\s+[A-Za-z0-9._~+/-]+=*)\b/g;
 export const REDACTED = "[redacted]";
@@ -40,6 +40,13 @@ function redactUnknown(value, depth) {
     }
     return value;
 }
+/**
+ * A JSON-lines logger with secret redaction built in.
+ *
+ * @example
+ * const logger = createLogger({ service: "my-app" });
+ * logger.info("order synced", { order: "ord_123" });
+ */
 export function createLogger(options) {
     const threshold = LEVELS[options.level ?? process.env.LOG_LEVEL ?? "info"] ?? 1;
     const sink = options.sink ??
@@ -72,4 +79,3 @@ export function createLogger(options) {
         error: (message, fields) => emit("error", message, fields),
     };
 }
-//# sourceMappingURL=logger.js.map