@usequeek/app-sdk 0.8.0 → 0.8.1

package/README.md

@@ -72,7 +72,7 @@ export const installRoute = (request: Request) => handleInstallRequest(request,
 export const webhookRoute = (request: Request) => handleWebhookRequest(request, webhookOptions);
 ```
 
-In Next.js App Router, export `installRoute` as `POST` from `app/api/install/route.ts` (and again from `uninstall/route.ts` and `settings/route.ts`), and `webhookRoute` as `POST` from `app/api/webhooks/route.ts`.
+In Next.js App Router, export `installRoute` as `POST`, `GET` and `HEAD` from `app/api/install/route.ts` (and again from `uninstall/route.ts` and `settings/route.ts`), and `webhookRoute` as `POST`, `GET` and `HEAD` from `app/api/webhooks/route.ts`. The `GET` and `HEAD` exports answer the review probe below.
 
 ## Which entry do I import?
 
@@ -101,6 +101,10 @@ The handlers come in three layers that behave identically:
 2. `handleInstallRequest(request, options)` and `handleWebhookRequest(request, options)` adapt a Web `Request` to a `Response`.
 3. `createInstallHandlers`, `createWebhookHandler`, `createProxyHandler` and `createAiToolHandler` from `@usequeek/app-sdk/hono`.
 
+### The review probe
+
+Queek's app review checks that your install, uninstall and webhook URLs answer, and that the install URL verifies signatures. It sends `GET` requests: one unsigned (any 2xx passes), and on the install URL one signed with your app secret (must be 2xx) and one signed with a wrong secret (must be 4xx). The handlers above answer `GET` and `HEAD` on the install, uninstall, settings and webhook routes for you: unsigned gets 200 `{"ok":true}`, a signed probe is verified like a delivery over the empty body (200 if valid, 401 if not), and none of it runs your callbacks or touches the store. If you mount the handlers yourself, route `GET` and `HEAD` to the same function as `POST`. The Hono helpers already do.
+
 ### Status codes
 
 | Route | Status | Meaning |
@@ -109,7 +113,7 @@ The handlers come in three layers that behave identically:
 | | 400 | The body is not the expected envelope or payload. |
 | | 401 | Missing signature header, stale timestamp, or bad signature. |
 | | 404 | Unknown route or unknown installation. |
-| | 405 | Not a `POST`. |
+| | 405 | Not a `POST`, `GET` or `HEAD`. |
 | | 409 | This `webhook-id` was already claimed. |
 | | 500 | Your callback or the store write threw. The claim is released, so Queek's retry can land. |
 | Topic webhook | 200 | Handled, a repeat (`deduped: true`), or a topic with no handler (`unhandled: true`). |

package/dist/delivery.d.ts

@@ -22,6 +22,11 @@ export interface CoreDelivery {
     rawBody: Uint8Array | Buffer | string;
     headers: CoreHeaders;
 }
+/** Layer-1 input for the topic webhook receiver. `GET` and `HEAD` are the review probe; any other method is a delivery. */
+export interface WebhookDelivery extends CoreDelivery {
+    /** Defaults to `"POST"`. */
+    method?: string;
+}
 /** Layer-1 input for the install handoff, which genuinely needs routing. */
 export interface InstallDelivery extends CoreDelivery {
     /** Defaults to `"POST"`. Anything else answers 405. */
@@ -57,5 +62,18 @@ export type DeliveryErrorHandler = (error: unknown, failure: DeliveryFailure) =>
  * 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;
+/** Build the layer-2 `Response` from a layer-1 result. A `HEAD` request gets the same status and headers with no body. */
+export declare function toResponse(result: DeliveryResult, method?: string): Response;
+/** True for the methods of the review probe (`GET`, `HEAD`). */
+export declare function isProbeMethod(method: string | undefined): boolean;
+/**
+ * True when a probe carries no signature, the plain "is anything listening"
+ * check: it answers 200 without touching storage or any callback. A probe
+ * with a `webhook-signature` header is verified like a delivery.
+ */
+export declare function isUnsignedProbe(headers: CoreHeaders): boolean;
+/**
+ * The answer to a review probe: never cached, and never the result of an
+ * app callback. `error` is set for a refused (401) probe.
+ */
+export declare function probeResult(status: 200 | 401, error?: string): DeliveryResult;

package/dist/delivery.js

@@ -1,4 +1,5 @@
 import { createLogger } from "./logger.js";
+import { WEBHOOK_SIGNATURE_HEADER } from "./signatures.js";
 /** Case-insensitive header lookup across `Headers` and plain (possibly lowercased, possibly array-valued) objects. */
 export function readHeader(headers, name) {
     if (headers instanceof Headers) {
@@ -45,7 +46,34 @@ export function reportDeliveryFailure(onError, error, failure) {
         // 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 });
+/** Build the layer-2 `Response` from a layer-1 result. A `HEAD` request gets the same status and headers with no body. */
+export function toResponse(result, method) {
+    const response = Response.json(result.body, { status: result.status, headers: result.headers });
+    if (method?.toUpperCase() !== "HEAD")
+        return response;
+    return new Response(null, { status: response.status, headers: response.headers });
+}
+/** True for the methods of the review probe (`GET`, `HEAD`). */
+export function isProbeMethod(method) {
+    const upper = (method ?? "POST").toUpperCase();
+    return upper === "GET" || upper === "HEAD";
+}
+/**
+ * True when a probe carries no signature, the plain "is anything listening"
+ * check: it answers 200 without touching storage or any callback. A probe
+ * with a `webhook-signature` header is verified like a delivery.
+ */
+export function isUnsignedProbe(headers) {
+    return !readHeader(headers, WEBHOOK_SIGNATURE_HEADER);
+}
+/**
+ * The answer to a review probe: never cached, and never the result of an
+ * app callback. `error` is set for a refused (401) probe.
+ */
+export function probeResult(status, error) {
+    return {
+        status,
+        body: status === 200 ? { ok: true } : { ok: false, error },
+        headers: { "Cache-Control": "no-store" },
+    };
 }

package/dist/hono.d.ts

@@ -14,9 +14,12 @@ import { type WebhookHandlerOptions } from "./webhooks.js";
 export type { InstallCallbacks, InstallHandlerOptions } from "./install-handlers.js";
 export type { AiToolRequestOptions, ProxyRequestOptions, ProxyResponder } from "./proxy.js";
 export type { QueekWebhookEnvelope, SecretResolution, WebhookHandlerContext, WebhookHandlerFn, WebhookHandlerOptions, } from "./webhooks.js";
-/** Mount the signed install/uninstall/settings handoff (`POST /install`, `POST /uninstall`, `POST /settings`). */
+/**
+ * Mount the signed install/uninstall/settings handoff (`POST /install`, `POST /uninstall`, `POST /settings`).
+ * `GET` and `HEAD` on the same paths answer Queek's app-review probe (no callback runs).
+ */
 export declare function createInstallHandlers(options: InstallHandlerOptions): Hono;
-/** Mount the signed topic-delivery receiver (`POST /`). */
+/** Mount the signed topic-delivery receiver (`POST /`). `GET` and `HEAD` answer Queek's app-review probe. */
 export declare function createWebhookHandler(options: WebhookHandlerOptions): Hono;
 /**
  * Mount the signed app-proxy reader (`GET` only, proxy reads are

package/dist/hono.js

@@ -11,18 +11,26 @@ import { Hono } from "hono";
 import { handleInstallRequest } from "./install-handlers.js";
 import { handleAiToolRequest, handleProxyRequest, } from "./proxy.js";
 import { handleWebhookRequest } from "./webhooks.js";
-/** Mount the signed install/uninstall/settings handoff (`POST /install`, `POST /uninstall`, `POST /settings`). */
+/**
+ * Mount the signed install/uninstall/settings handoff (`POST /install`, `POST /uninstall`, `POST /settings`).
+ * `GET` and `HEAD` on the same paths answer Queek's app-review probe (no callback runs).
+ */
 export function createInstallHandlers(options) {
     const app = new Hono();
     app.post("/install", (c) => handleInstallRequest(c.req.raw, options));
     app.post("/uninstall", (c) => handleInstallRequest(c.req.raw, options));
     app.post("/settings", (c) => handleInstallRequest(c.req.raw, options));
+    // Hono answers HEAD from the GET route; layer 2 handles both methods.
+    app.get("/install", (c) => handleInstallRequest(c.req.raw, options));
+    app.get("/uninstall", (c) => handleInstallRequest(c.req.raw, options));
+    app.get("/settings", (c) => handleInstallRequest(c.req.raw, options));
     return app;
 }
-/** Mount the signed topic-delivery receiver (`POST /`). */
+/** Mount the signed topic-delivery receiver (`POST /`). `GET` and `HEAD` answer Queek's app-review probe. */
 export function createWebhookHandler(options) {
     const app = new Hono();
     app.post("/", (c) => handleWebhookRequest(c.req.raw, options));
+    app.get("/", (c) => handleWebhookRequest(c.req.raw, options));
     return app;
 }
 /**

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { backgroundTaskCount, type CatchupFailure, type CatchupInstallation, typ
 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";
+export { type CoreDelivery, type CoreHeaders, type DeliveryResult, decodeBody, type InstallDelivery, readHeader, type WebhookDelivery, } from "./delivery.js";
 export { type AiAction, type AiActionValue, APP_SOURCE, type AppInboundMessage, type AppOutboundMessage, BRIDGE_VERSION, type BridgeTheme, buildReadyMessage, capText, clipOutbound, DASHBOARD_SOURCE, type EmbedEvent, type EmbedEventTarget, type EmbedPostTarget, type FrameBridgeOptions, isAllowedImageUrl, isAllowedOpenTarget, listenToDashboard, MAX_ACTION_ID_LENGTH, MAX_CAPABILITIES, MAX_CAPABILITY_LENGTH, MAX_FILTER_LENGTH, MAX_HEADING_LENGTH, MAX_IMAGE_URL_LENGTH, MAX_LABEL_LENGTH, MAX_LOCALE_LENGTH, MAX_PATH_LENGTH, MAX_PICKED_ITEMS, MAX_REQUEST_ID_LENGTH, MAX_RESIZE_HEIGHT, MAX_RESOURCE_TITLE_LENGTH, MAX_SDK_VERSION_LENGTH, MAX_SECONDARY_ACTIONS, MAX_SELECTION_ID_LENGTH, MAX_SELECTION_IDS, MAX_TARGET_LENGTH, MAX_TOAST_DURATION_MS, MAX_TOAST_LENGTH, onAiAction, type PickResourceRequest, parseInboundMessage, parseOutboundMessage, type ReadyOptions, type ResourceItem, type SaveBarAction, type SaveBarState, sendAck, sendBridgeMessage, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, sendToast, type ThemeMode, type TitleActionDef, type TitleActionTone, type ToastTone, } from "./frame.js";
 export { type HandoffEnvelope, type HandoffEnvelopeAny, type HandoffInstallationRef, type HandoffPidRef, type HandoffStore, INSTALL_EVENT, type InstallData, type InstallEnvelope, RESYNC_EVENT, type ResyncEnvelope, SCOPES_UPDATE_EVENT, type ScopesUpdateData, type ScopesUpdateEnvelope, SETTINGS_EVENT, type SettingsData, type SettingsEnvelope, UNINSTALL_EVENT, type UninstallData, type UninstallEnvelope, } from "./handoff.js";
 export { buildInstallationRecord, handleInstallDelivery, handleInstallRequest, type InstallCallbacks, type InstallHandlerOptions, installationScopesEqual, saveResyncedInstallation, saveScopesUpdateInstallation, } from "./install-handlers.js";

package/dist/install-handlers.d.ts

@@ -105,6 +105,11 @@ export declare function saveResyncedInstallation(existing: InstallationRecord, d
  * `webhook-id`, 404 for an unknown route, and 500 when your callback or the
  * store write throws (Queek then retries).
  *
+ * `GET` and `HEAD` on a route are the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no callback; with a signature (over the
+ * empty body) 200 when it verifies and 401 when not. Any other method
+ * answers 405.
+ *
  * @example
  * const result = await handleInstallDelivery(
  *   { rawBody, headers, method: "POST", path: "/queek/install" },

package/dist/install-handlers.js

@@ -1,4 +1,4 @@
-import { decodeBody, readHeader, reportDeliveryFailure, toResponse, } from "./delivery.js";
+import { decodeBody, isProbeMethod, isUnsignedProbe, probeResult, 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";
@@ -112,6 +112,11 @@ export function saveResyncedInstallation(existing, data, nowIso = new Date().toI
  * `webhook-id`, 404 for an unknown route, and 500 when your callback or the
  * store write throws (Queek then retries).
  *
+ * `GET` and `HEAD` on a route are the review probe: 200 `{ ok: true }` with
+ * `Cache-Control: no-store` and no callback; with a signature (over the
+ * empty body) 200 when it verifies and 401 when not. Any other method
+ * answers 405.
+ *
  * @example
  * const result = await handleInstallDelivery(
  *   { rawBody, headers, method: "POST", path: "/queek/install" },
@@ -120,10 +125,13 @@ export function saveResyncedInstallation(existing, data, nowIso = new Date().toI
  * // reply with result.status and result.body
  */
 export async function handleInstallDelivery(input, options) {
+    const route = trailingSegment(input.path ?? "");
+    if (isProbeMethod(input.method)) {
+        return ROUTES.has(route) ? probeDelivery(input.headers, options) : UNKNOWN_ROUTE;
+    }
     if ((input.method ?? "POST").toUpperCase() !== "POST") {
         return { status: 405, body: { ok: false, error: "method_not_allowed" } };
     }
-    const route = trailingSegment(input.path ?? "");
     const rawBody = decodeBody(input.rawBody);
     if (route === "install")
         return installDelivery(rawBody, input.headers, options);
@@ -131,7 +139,21 @@ export async function handleInstallDelivery(input, options) {
         return uninstallDelivery(rawBody, input.headers, options);
     if (route === "settings")
         return settingsDelivery(rawBody, input.headers, options);
-    return { status: 404, body: { ok: false, error: "unknown_route" } };
+    return UNKNOWN_ROUTE;
+}
+const ROUTES = new Set(["install", "uninstall", "settings"]);
+const UNKNOWN_ROUTE = { status: 404, body: { ok: false, error: "unknown_route" } };
+/**
+ * The review probe (`GET` / `HEAD` on a handoff route): answers 200 without
+ * running a callback or touching the store. A probe that carries a
+ * signature goes through the SAME `guard` as a delivery, over the empty
+ * body: 200 when it verifies, 401 when not. A valid probe claims nothing.
+ */
+async function probeDelivery(headers, options) {
+    if (isUnsignedProbe(headers))
+        return probeResult(200);
+    const checked = await guard(options, headers, "");
+    return checked.ok ? probeResult(200) : probeResult(401, checked.reason);
 }
 /** Last path segment of a pathname or full URL (query/fragment stripped, trailing slashes ignored). */
 function trailingSegment(path) {
@@ -154,7 +176,7 @@ export async function handleInstallRequest(request, options) {
         headers: request.headers,
         method: request.method,
         path: new URL(request.url).pathname,
-    }, options));
+    }, options), request.method);
 }
 async function guard(options, headers, rawBody) {
     const id = readHeader(headers, WEBHOOK_ID_HEADER);