@usequeek/app-sdk 0.7.2 → 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?
 
@@ -99,7 +99,11 @@ The handlers come in three layers that behave identically:
 
 1. `handleInstallDelivery(input, options)` and `handleWebhookDelivery(input, options)` take raw body bytes plus headers and return `{ status, body }`. They use no request or response types, so any framework works.
 2. `handleInstallRequest(request, options)` and `handleWebhookRequest(request, options)` adapt a Web `Request` to a `Response`.
-3. `createInstallHandlers`, `createWebhookHandler` and `createProxyHandler` from `@usequeek/app-sdk/hono`.
+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
 
@@ -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`). |
@@ -429,6 +433,73 @@ export async function GET(request: Request) {
 
 The canonical string is `path`, `shop`, `ts` and the sorted, percent-encoded query pairs (without `sig`), joined with newlines. The signature is a hex HMAC-SHA256 keyed with the full `whsec_…` string, with no base64 decode. `kid` selects the installation, timestamps may skew by 5 minutes, each `jti` is single-use, and only `GET` is served. With Hono, mount `createProxyHandler({ store, path, onVerified })`.
 
+Queek also signs a `surface` on every proxy call: `storefront` (a shopper), `dashboard` (your merchant page) or `ai` (Queek AI). Only Queek sets it, and it is covered by the signature, so a shopper cannot choose it. A handler that serves merchant data must pass `expectedSurface: "dashboard"`, which answers 403 `surface_mismatch` for a genuine call signed for another surface. `handleProxyRequest` never hands a `surface=ai` call to your responder.
+
+## Queek AI tools and actions
+
+Declare an `ai` section (`ManifestAi`) in your manifest and Queek AI, the assistant in the merchant dashboard, can use your app in two small ways. It needs no scope. The merchant approves it with the install, and again when you add or change a tool or action.
+
+```toml
+[ai]
+summary = "Takes bookings for services."
+
+[[ai.tools]]
+key = "upcoming_bookings"
+description = "Upcoming bookings, soonest first."
+
+[[ai.tools.inputs]]
+key = "days"
+type = "integer"
+label = "Days ahead"
+min = 1
+max = 30
+
+[ai.tools.output]
+list = true
+
+[[ai.tools.output.fields]]
+key = "date"
+type = "date"
+
+[[ai.actions]]
+key = "add_date_exception"
+description = "Open the Hours page with a date filled in."
+page = "/admin/hours"
+
+[[ai.actions.inputs]]
+key = "date"
+type = "date"
+label = "Date"
+required = true
+```
+
+Tools read. Queek calls your proxy as a signed `GET ai/{key}` with `surface=ai` and the tool's inputs. Serve them with `handleAiToolRequest(request, tool, { subpath, secrets, tools })`, or mount `createAiToolHandler({ subpath, secrets, tools })` from `@usequeek/app-sdk/hono` at the `ai` segment of your proxy. `secrets(kid)` returns the proxy secrets of that installation, current first:
+
+```ts
+import { createAiToolHandler } from "@usequeek/app-sdk/hono";
+
+app.route(
+  "/proxy/ai",
+  createAiToolHandler({
+    subpath: "booking", // the manifest extensions.proxy.subpath
+    secrets: async (kid) => proxySecretsFor(kid),
+    tools: { upcoming_bookings: async (call) => ({ rows: await upcoming(call.kid, call.params.days) }) },
+  }),
+);
+```
+
+A `surface=ai` call is served only by a declared tool handler (403 otherwise), and a storefront or dashboard call at that path is refused. Answer an object, never a bare array: `{ rows: [...] }` for a list tool (`output.list: true`), the declared fields object otherwise. A handler that answers anything else gets a 500. Return only the declared output fields, because Queek drops the rest. Tool inputs are structured, with no free text. `call.actorRole` is the member's role, never a user id. Pass `replayStore` (your installation store) to make each call single-use: the `jti` is claimed like the storefront proxy does, and a replay answers 401. Without it a captured call can be replayed for 5 minutes, which for a read-only tool repeats only the read.
+
+Actions never write. Queek AI only opens your `page` (a path under your merchant page) with the values filled in, and shows "Opened by Queek AI, check these values before saving" above it. Receive the values with `onAiAction`, stage them in your form, show them editable, and write nothing until the merchant presses your own Save:
+
+```ts
+import { onAiAction } from "@usequeek/app-sdk/browser";
+
+onAiAction(({ action, values }) => stage(action, values), { dashboardOrigin });
+```
+
+`MANIFEST_AI_RESERVED_INPUT_KEYS` lists the input names Queek signs or owns (`sig`, `ts`, `surface`, `order_id` and more), and `isReservedAiInputKey` checks one. A manifest that declares an input with such a name, or any `logged_in_customer_` name, is refused. A setting can opt in to being changed by Queek AI with `ai_editable: true` (`ManifestSetting`, `aiEditableSettingKeys`). A `secret` never can, and each change still needs the merchant's confirmation.
+
 ## Scopes
 
 Apps declare required scopes (granted at install) and optional scopes (requested later, revocable).
@@ -469,7 +540,8 @@ Every export has JSDoc in its type definitions. By module:
 | `install-handlers` | `handleInstallDelivery`, `handleInstallRequest`, `saveResyncedInstallation` |
 | `webhooks` | `handleWebhookDelivery`, `handleWebhookRequest` |
 | `signatures` | `verifyQueekSignature`, `verifyQueekSignatureDetailed`, `signQueekPayload` |
-| `proxy` | `verifyProxyQuery`, `verifyProxyDelivery`, `handleProxyRequest` |
+| `proxy` | `verifyProxyQuery`, `verifyProxyDelivery`, `handleProxyRequest`, `handleAiToolRequest` |
+| `manifest` | `ManifestSetting`, `ManifestAi` and its parts, `aiEditableSettingKeys`, `isReservedAiInputKey` |
 | `store` | `SqliteInstallationStore`, `PostgresInstallationStore`, `createInstallationStore` |
 | `resync`, `background` | `resyncFromQueek`, `runInstallationCatchup`, `detach` |
 | `scopes` | `createInstallationScopesClient`, `AppScopeRequiredError` |

package/dist/browser.d.ts

@@ -20,5 +20,5 @@
  * `react` dependency, so this entry can never silently regress.
  */
 export { type AuthFetchOptions, BRIDGE_TOKEN_TIMEOUT_MS, type InstalledAuth, installAuthFetch, LAUNCH_TOKEN_PARAM, readLaunchToken, stripLaunchToken, } from "./auth-fetch.js";
-export { APP_SOURCE, type AppInboundMessage, type AppOutboundMessage, BRIDGE_VERSION, type BridgeTheme, DASHBOARD_SOURCE, type EmbedEvent, type EmbedEventTarget, type EmbedPostTarget, type FrameBridgeOptions, listenToDashboard, type PickResourceRequest, type ReadyOptions, type ResourceItem, type SaveBarAction, type SaveBarState, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, type ThemeMode, type TitleActionDef, } from "./frame.js";
+export { type AiAction, type AiActionValue, APP_SOURCE, type AppInboundMessage, type AppOutboundMessage, BRIDGE_VERSION, type BridgeTheme, DASHBOARD_SOURCE, type EmbedEvent, type EmbedEventTarget, type EmbedPostTarget, type FrameBridgeOptions, listenToDashboard, onAiAction, type PickResourceRequest, type ReadyOptions, type ResourceItem, type SaveBarAction, type SaveBarState, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, type ThemeMode, type TitleActionDef, } from "./frame.js";
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, syncThemeUrl, THEME_PARAM, THEME_STORAGE_KEY, type ThemeDocument, type ThemeDocumentElement, type ThemeListenerOptions, type ThemeStorage, type ThemeUrlOptions, themeBootstrapScript, } from "./theme.js";

package/dist/browser.js

@@ -20,7 +20,7 @@
  * `react` dependency, so this entry can never silently regress.
  */
 export { BRIDGE_TOKEN_TIMEOUT_MS, installAuthFetch, LAUNCH_TOKEN_PARAM, readLaunchToken, stripLaunchToken, } from "./auth-fetch.js";
-export { APP_SOURCE, BRIDGE_VERSION, DASHBOARD_SOURCE, listenToDashboard, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, } from "./frame.js";
+export { APP_SOURCE, BRIDGE_VERSION, DASHBOARD_SOURCE, listenToDashboard, onAiAction, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, } from "./frame.js";
 // NOTE: ThemeMode comes from ./frame.js only — theme.js merely re-exports
 // it, so listing it here too would be ambiguous.
 export { applyTheme, getThemeModeFromUrl, installThemeListener, rememberThemeMode, syncThemeUrl, THEME_PARAM, THEME_STORAGE_KEY, themeBootstrapScript, } from "./theme.js";

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/frame.d.ts

@@ -121,6 +121,16 @@ export type AppOutboundMessage = {
     selectionIds?: string[];
     requestId?: string;
 };
+/** A value Queek AI filled into an action input: the declared types only, never an object. */
+export type AiActionValue = string | number | boolean;
+/**
+ * Queek AI opened one of the app's declared `ai.actions` and sent its values. The values are a SUGGESTION: stage them
+ * in the form, show them editable, and write nothing until the merchant presses the app's own Save.
+ */
+export interface AiAction {
+    action: string;
+    values: Record<string, AiActionValue>;
+}
 export type AppInboundMessage = {
     source: typeof DASHBOARD_SOURCE;
     type: "token";
@@ -156,7 +166,10 @@ export type AppInboundMessage = {
     source: typeof DASHBOARD_SOURCE;
     type: "resource-pick-cancelled";
     requestId?: string;
-};
+} | ({
+    source: typeof DASHBOARD_SOURCE;
+    type: "ai-action";
+} & AiAction);
 export interface EmbedEvent {
     origin: string;
     data: unknown;
@@ -188,6 +201,7 @@ export interface FrameBridgeOptions {
     onNavigate?: (path: string) => void;
     onResourcePicked?: (items: ResourceItem[], requestId?: string) => void;
     onResourcePickCancelled?: (requestId?: string) => void;
+    onAiAction?: (action: AiAction) => void;
 }
 export interface ReadyOptions {
     capabilities?: string[];
@@ -276,6 +290,14 @@ export declare function sendPickResource(dashboardOrigin: string, target: EmbedP
  * Never touches any secret.
  */
 export declare function listenToDashboard(options: FrameBridgeOptions): () => void;
+/**
+ * Receive the action Queek AI opened this page for, from the exact dashboard origin only (the same gate as the token).
+ * Like `installAuthFetch`, it listens on the global window and accepts only messages from the embedding parent
+ * window; pass `target` / `expectSource` to override (`expectSource: null` turns the source check off).
+ * Stage `values` in your form and show them editable; NEVER save on load, only the merchant's own Save writes.
+ * Returns an unsubscribe function.
+ */
+export declare function onAiAction(handler: (action: AiAction) => void, options: Pick<FrameBridgeOptions, "dashboardOrigin" | "target" | "expectSource">): () => void;
 /**
  * The single choke point for everything the app posts: caps every string,
  * allow-lists every enum, clamps every number, re-gates `open` targets

package/dist/frame.js

@@ -64,6 +64,39 @@ function reqText(value, max) {
     }
     return capText(value, max);
 }
+const AI_KEY = /^[a-z][a-z0-9_]{0,39}$/;
+const MAX_AI_ACTION_VALUES = 8;
+const MAX_AI_TEXT_LENGTH = 500;
+/** One `ai-action` message: a declared key, and up to 8 scalar values (a `null` is an unset input and is dropped). */
+function parseAiAction(data) {
+    const { action, values } = data;
+    if (typeof action !== "string" || !AI_KEY.test(action)) {
+        return null;
+    }
+    if (!isRecord(values) || Array.isArray(values)) {
+        return null;
+    }
+    const entries = Object.entries(values).filter(([, value]) => value !== null);
+    if (entries.length > MAX_AI_ACTION_VALUES) {
+        return null;
+    }
+    const clean = {};
+    for (const [key, value] of entries) {
+        if (!AI_KEY.test(key)) {
+            return null;
+        }
+        if (typeof value === "string") {
+            clean[key] = capText(value, MAX_AI_TEXT_LENGTH);
+        }
+        else if (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) {
+            clean[key] = value;
+        }
+        else {
+            return null;
+        }
+    }
+    return { action, values: clean };
+}
 function isThemeMode(value) {
     return value === "light" || value === "dark";
 }
@@ -283,6 +316,10 @@ export function parseInboundMessage(data) {
             }
             return cancelled;
         }
+        case "ai-action": {
+            const aiAction = parseAiAction(data);
+            return aiAction === null ? null : { source: DASHBOARD_SOURCE, type: "ai-action", ...aiAction };
+        }
         default:
             return null;
     }
@@ -522,7 +559,7 @@ export function sendPickResource(dashboardOrigin, target, request) {
  * Never touches any secret.
  */
 export function listenToDashboard(options) {
-    const { dashboardOrigin, onToken, onResizeAck, onTheme, onTitleAction, onSaveBarAction, onNavigate, onResourcePicked, onResourcePickCancelled, } = options;
+    const { dashboardOrigin, onToken, onResizeAck, onTheme, onTitleAction, onSaveBarAction, onNavigate, onResourcePicked, onResourcePickCancelled, onAiAction, } = options;
     const target = options.target;
     const expectSource = options.expectSource;
     const onMessage = (event) => {
@@ -572,11 +609,32 @@ export function listenToDashboard(options) {
             case "resource-pick-cancelled":
                 onResourcePickCancelled?.(message.requestId);
                 break;
+            case "ai-action":
+                onAiAction?.({ action: message.action, values: message.values });
+                break;
         }
     };
     target?.addEventListener("message", onMessage);
     return () => target?.removeEventListener("message", onMessage);
 }
+/**
+ * Receive the action Queek AI opened this page for, from the exact dashboard origin only (the same gate as the token).
+ * Like `installAuthFetch`, it listens on the global window and accepts only messages from the embedding parent
+ * window; pass `target` / `expectSource` to override (`expectSource: null` turns the source check off).
+ * Stage `values` in your form and show them editable; NEVER save on load, only the merchant's own Save writes.
+ * Returns an unsubscribe function.
+ */
+export function onAiAction(handler, options) {
+    const scope = globalThis;
+    const win = scope.window?.location !== undefined ? scope.window : undefined;
+    const expectSource = options.expectSource !== undefined ? options.expectSource : win?.parent;
+    return listenToDashboard({
+        dashboardOrigin: options.dashboardOrigin,
+        target: options.target ?? win,
+        expectSource: expectSource ?? undefined,
+        onAiAction: handler,
+    });
+}
 /** Validate a title-bar action shape, then cap its strings. */
 function clipTitleActionDef(value) {
     const def = parseTitleActionDef(value);

package/dist/hono.d.ts

@@ -9,14 +9,17 @@
  */
 import { Hono } from "hono";
 import { type InstallHandlerOptions } from "./install-handlers.js";
-import { type ProxyRequestOptions, type ProxyResponder } from "./proxy.js";
+import { type AiToolRequestOptions, type ProxyRequestOptions, type ProxyResponder } from "./proxy.js";
 import { type WebhookHandlerOptions } from "./webhooks.js";
 export type { InstallCallbacks, InstallHandlerOptions } from "./install-handlers.js";
-export type { ProxyRequestOptions, ProxyResponder } from "./proxy.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
@@ -29,3 +32,12 @@ export declare function createWebhookHandler(options: WebhookHandlerOptions): Ho
 export declare function createProxyHandler(options: ProxyRequestOptions & {
     onVerified: ProxyResponder;
 }): Hono;
+/**
+ * Mount the Queek AI read tools (`GET /:tool`) — a thin wrapper built ONLY on
+ * `handleAiToolRequest`. Mount it at the `ai` segment of the proxy
+ * (`app.route("/proxy/ai", createAiToolHandler({ subpath, secrets, tools }))`);
+ * `subpath` is the manifest `extensions.proxy.subpath`, `secrets` resolves the
+ * proxy secrets of installation `kid`, and `tools` holds the handlers of the
+ * manifest `ai.tools`.
+ */
+export declare function createAiToolHandler(options: AiToolRequestOptions): Hono;

package/dist/hono.js

@@ -9,20 +9,28 @@
  */
 import { Hono } from "hono";
 import { handleInstallRequest } from "./install-handlers.js";
-import { handleProxyRequest } from "./proxy.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;
 }
 /**
@@ -39,3 +47,16 @@ export function createProxyHandler(options) {
     app.get("*", (c) => handleProxyRequest(c.req.raw, requestOptions, onVerified));
     return app;
 }
+/**
+ * Mount the Queek AI read tools (`GET /:tool`) — a thin wrapper built ONLY on
+ * `handleAiToolRequest`. Mount it at the `ai` segment of the proxy
+ * (`app.route("/proxy/ai", createAiToolHandler({ subpath, secrets, tools }))`);
+ * `subpath` is the manifest `extensions.proxy.subpath`, `secrets` resolves the
+ * proxy secrets of installation `kid`, and `tools` holds the handlers of the
+ * manifest `ai.tools`.
+ */
+export function createAiToolHandler(options) {
+    const app = new Hono();
+    app.get("/:tool", (c) => handleAiToolRequest(c.req.raw, c.req.param("tool"), options));
+    return app;
+}

package/dist/index.d.ts

@@ -14,12 +14,13 @@ 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 { 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, 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 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";
 export { createLogger, type LogFields, type Logger, type LoggerOptions, type LogLevel, REDACTED, } from "./logger.js";
-export { buildProxyCanonicalString, handleProxyRequest, PROXY_CUSTOMER_PARAM, PROXY_KID_PARAM, PROXY_MAX_SKEW_SECONDS, PROXY_NONCE_PARAM, PROXY_SHOP_PARAM, PROXY_SIGNATURE_PARAM, PROXY_TIMESTAMP_PARAM, type ProxyFailure, type ProxyQuery, type ProxyRequestOptions, type ProxyResponder, type ProxyStoreOptions, type ProxyVerification, type ProxyVerifyOptions, signProxyQuery, verifyProxyDelivery, verifyProxyQuery, verifyProxyQueryDetailed, } from "./proxy.js";
+export { aiEditableSettingKeys, isReservedAiInputKey, MANIFEST_AI_ACTION_INPUT_TYPES, MANIFEST_AI_OUTPUT_TYPES, MANIFEST_AI_RESERVED_INPUT_KEYS, MANIFEST_AI_RESERVED_INPUT_PREFIX, MANIFEST_AI_TOOL_INPUT_TYPES, MANIFEST_SETTING_TYPES, type ManifestAi, type ManifestAiAction, type ManifestAiInput, type ManifestAiInputType, type ManifestAiOutputField, type ManifestAiOutputType, type ManifestAiTool, type ManifestSetting, type ManifestSettingType, } from "./manifest.js";
+export { type AiToolCall, type AiToolHandler, type AiToolOutput, type AiToolRequestOptions, buildProxyCanonicalString, handleAiToolRequest, handleProxyRequest, PROXY_CUSTOMER_PARAM, PROXY_KID_PARAM, PROXY_MAX_SKEW_SECONDS, PROXY_NONCE_PARAM, PROXY_SHOP_PARAM, PROXY_SIGNATURE_PARAM, PROXY_SURFACE_PARAM, PROXY_TIMESTAMP_PARAM, type ProxyFailure, type ProxyQuery, type ProxyRequestOptions, type ProxyResponder, type ProxyStoreOptions, type ProxySurface, type ProxyVerification, type ProxyVerifyOptions, signProxyQuery, verifyProxyDelivery, verifyProxyQuery, verifyProxyQueryDetailed, } from "./proxy.js";
 export { type ResyncListItem, type ResyncOptions, type ResyncResult, resyncFromQueek, } from "./resync.js";
 export { APP_SCOPE_REQUIRED_CODE, APP_SCOPE_UNDECLARED_CODE, AppScopeRequiredError, appScopeRequiredFromError, buildScopeRequestLink, createInstallationScopesClient, type InstallationScopes, type InstallationScopesClient, type InstallationScopesClientOptions, InvalidScopesError, isAppScopeRequired, MAX_SCOPE_LENGTH, MAX_SCOPE_LIST, normaliseScopeList, type QueryScopesOptions, type RequestScopesLinkOptions, type RevokeScopesOptions, revokeScopesPath, type ScopeRequestLinkOptions, splitInstallationScopes, } from "./scopes.js";
 export { MAX_TIMESTAMP_SKEW_SECONDS, SECRET_PREFIX, type SignatureFailure, type SignatureInput, secretKeyBytes, signQueekPayload, type VerifyOptions, verifyQueekSignature, verifyQueekSignatureDetailed, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.js";

package/dist/index.js

@@ -15,11 +15,12 @@ export { apiHostsFromEnv, createQueekClient, DEFAULT_API_HOSTS, DEFAULT_MAX_RETR
 export { collectedDefinitions, createRecord, sendAlert, setSetupNotice, } from "./collected.js";
 export { decryptSecret, encryptSecret, parseStoreKey, storeKeyFingerprint, } from "./crypto.js";
 export { decodeBody, readHeader, } from "./delivery.js";
-export { APP_SOURCE, BRIDGE_VERSION, buildReadyMessage, capText, clipOutbound, DASHBOARD_SOURCE, 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, parseInboundMessage, parseOutboundMessage, sendAck, sendBridgeMessage, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, sendToast, } from "./frame.js";
+export { APP_SOURCE, BRIDGE_VERSION, buildReadyMessage, capText, clipOutbound, DASHBOARD_SOURCE, 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, parseInboundMessage, parseOutboundMessage, sendAck, sendBridgeMessage, sendNavigated, sendOpen, sendPickResource, sendReady, sendResize, sendSaveBar, sendTitle, sendToast, } from "./frame.js";
 export { INSTALL_EVENT, RESYNC_EVENT, SCOPES_UPDATE_EVENT, SETTINGS_EVENT, UNINSTALL_EVENT, } from "./handoff.js";
 export { buildInstallationRecord, handleInstallDelivery, handleInstallRequest, installationScopesEqual, saveResyncedInstallation, saveScopesUpdateInstallation, } from "./install-handlers.js";
 export { createLogger, REDACTED, } from "./logger.js";
-export { buildProxyCanonicalString, handleProxyRequest, PROXY_CUSTOMER_PARAM, PROXY_KID_PARAM, PROXY_MAX_SKEW_SECONDS, PROXY_NONCE_PARAM, PROXY_SHOP_PARAM, PROXY_SIGNATURE_PARAM, PROXY_TIMESTAMP_PARAM, signProxyQuery, verifyProxyDelivery, verifyProxyQuery, verifyProxyQueryDetailed, } from "./proxy.js";
+export { aiEditableSettingKeys, isReservedAiInputKey, MANIFEST_AI_ACTION_INPUT_TYPES, MANIFEST_AI_OUTPUT_TYPES, MANIFEST_AI_RESERVED_INPUT_KEYS, MANIFEST_AI_RESERVED_INPUT_PREFIX, MANIFEST_AI_TOOL_INPUT_TYPES, MANIFEST_SETTING_TYPES, } from "./manifest.js";
+export { buildProxyCanonicalString, handleAiToolRequest, handleProxyRequest, PROXY_CUSTOMER_PARAM, PROXY_KID_PARAM, PROXY_MAX_SKEW_SECONDS, PROXY_NONCE_PARAM, PROXY_SHOP_PARAM, PROXY_SIGNATURE_PARAM, PROXY_SURFACE_PARAM, PROXY_TIMESTAMP_PARAM, signProxyQuery, verifyProxyDelivery, verifyProxyQuery, verifyProxyQueryDetailed, } from "./proxy.js";
 export { resyncFromQueek, } from "./resync.js";
 export { APP_SCOPE_REQUIRED_CODE, APP_SCOPE_UNDECLARED_CODE, AppScopeRequiredError, appScopeRequiredFromError, buildScopeRequestLink, createInstallationScopesClient, InvalidScopesError, isAppScopeRequired, MAX_SCOPE_LENGTH, MAX_SCOPE_LIST, normaliseScopeList, revokeScopesPath, splitInstallationScopes, } from "./scopes.js";
 export { MAX_TIMESTAMP_SKEW_SECONDS, SECRET_PREFIX, secretKeyBytes, signQueekPayload, verifyQueekSignature, verifyQueekSignatureDetailed, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, } from "./signatures.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);