@usequeek/app-sdk 0.6.2 → 0.7.0

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";
@@ -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" &&
@@ -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 } };
@@ -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

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