@usequeek/app-sdk 0.5.1 → 0.6.0

package/dist/merchant-schema.js

@@ -1,6 +1,6 @@
 /**
  * GENERATED from openapi/merchant.json — do not edit by hand.
- * Refresh with: pnpm --filter @usequeek/app-sdk gen:merchant [url-or-path]
+ * Refresh with: npm run gen:merchant [url-or-path]
  * See scripts/gen-merchant-types.mjs for source precedence.
  */
 /**

package/dist/proxy.d.ts

@@ -0,0 +1,122 @@
+import { type InstallationRecord, type InstallationStore } from "./store.js";
+/**
+ * Storefront app-proxy query verification, byte-for-byte compatible with
+ * Queek's `App\Services\Apps\AppProxyService` (queek_backend).
+ *
+ * Queek signs a READ fetch to the app's proxy handler with the installation's
+ * `proxy_secret` (`signQuery`): the app verifies server-side before answering
+ * the shopper. Canonical signature (Shopify-style, per-install secret):
+ *
+ *   sig = hex HMAC-SHA256 over
+ *     path + "\n" + shop + "\n" + ts + "\n" + sorted(k=v&...) (sig excluded),
+ *
+ * where each pair is `rawurlencode(key)=rawurlencode(value)` and keys sort
+ * byte-wise. The HMAC key is the FULL `whsec_…` string — no base64 decode
+ * step (the single most common integration bug cannot happen here).
+ *
+ * `path` is the QUEEK-side canonical path (`/apps/<subpath>/<rest>`, what
+ * the backend signs in `fetch()`), NOT the app's local route: pass it
+ * explicitly per route (see `handleProxyRequest`).
+ *
+ * Layering mirrors the install/webhook handlers: layer 1
+ * `verifyProxyDelivery` takes plain data (path + query) and returns a plain
+ * result — zero request/response types; layer 2 `handleProxyRequest` adapts
+ * the Web standard onto layer 1; `@usequeek/app-sdk/hono`
+ * `createProxyHandler` adapts Hono onto layer 2.
+ */
+export declare const PROXY_SIGNATURE_PARAM = "sig";
+export declare const PROXY_TIMESTAMP_PARAM = "ts";
+export declare const PROXY_NONCE_PARAM = "jti";
+export declare const PROXY_SHOP_PARAM = "shop";
+export declare const PROXY_CUSTOMER_PARAM = "logged_in_customer_id";
+export declare const PROXY_KID_PARAM = "kid";
+/** Backend `apps.proxy_signature_skew_seconds` default; the floor (60s) below applies regardless. */
+export declare const PROXY_MAX_SKEW_SECONDS = 300;
+/** Query params as any framework holds them (duplicates collapse to the first value). */
+export type ProxyQuery = Record<string, string | string[] | null | undefined>;
+/** Failure reason when proxy verification rejects a query. */
+export type ProxyFailure = "missing_params" | "stale_timestamp" | "missing_secret" | "signature_mismatch" | "unknown_installation" | "replayed";
+/**
+ * The canonical string the MAC covers — mirrors `AppProxyService::signature()`
+ * exactly (sig excluded, keys byte-sorted, rawurlencoded pairs).
+ */
+export declare function buildProxyCanonicalString(path: string, params: Record<string, string>): string;
+/**
+ * One hex signature for one secret — mirrors `AppProxyService::signature()`.
+ * Exported so tests (and dev harnesses) can recompute a signature
+ * independently of the verifier; production traffic is signed by Queek.
+ */
+export declare function signProxyQuery(path: string, params: Record<string, string>, secret: string): string;
+export interface ProxyVerifyOptions {
+    /** Unix seconds to judge freshness against (defaults to now). Exposed for tests. */
+    nowSeconds?: number;
+    /** Allowed clock skew in seconds (defaults to PROXY_MAX_SKEW_SECONDS; floored at 60 like the backend). */
+    maxSkewSeconds?: number;
+}
+/**
+ * Pure verification over explicitly passed secrets — mirrors
+ * `AppProxyService::verifyQuery()` (structure → skew → secret presence →
+ * MAC over every active secret). No replay enforcement here: single-use
+ * `jti` needs storage, so the store-backed `verifyProxyDelivery` claims it
+ * (the framework-free translation of the backend's atomic `Cache::add`).
+ */
+export declare function verifyProxyQueryDetailed(path: string, query: ProxyQuery, secrets: string[], options?: ProxyVerifyOptions): {
+    ok: true;
+} | {
+    ok: false;
+    reason: ProxyFailure;
+};
+/** Boolean fast path over {@link verifyProxyQueryDetailed}. */
+export declare function verifyProxyQuery(path: string, query: ProxyQuery, secrets: string[], options?: ProxyVerifyOptions): boolean;
+export interface ProxyStoreOptions extends ProxyVerifyOptions {
+    store: InstallationStore;
+    /**
+     * Skip the single-use `jti` claim (NOT recommended; exposed for tests and
+     * for apps that enforce replay themselves). Defaults to enforcing, like
+     * the backend.
+     */
+    enforceReplay?: boolean;
+}
+export type ProxyVerification = {
+    ok: true;
+    installation: InstallationRecord;
+    params: Record<string, string>;
+} | {
+    ok: false;
+    reason: ProxyFailure;
+    status: 401;
+};
+/**
+ * Layer 1: verify one signed proxy query from plain data — no `Request`, no
+ * framework. Resolves the installation from the existing store by the `kid`
+ * routing hint (the installation p_id Queek signs in); without a `kid` it
+ * falls back to trying each stored proxy secret, the signature naming the
+ * sender (same rationale as the webhook resolver). Freshness is enforced
+ * before attribution; a verified `jti` is claimed atomically so a captured
+ * read cannot be replayed.
+ */
+export declare function verifyProxyDelivery(input: {
+    path: string;
+    query: ProxyQuery;
+}, options: ProxyStoreOptions): Promise<ProxyVerification>;
+export interface ProxyRequestOptions extends ProxyStoreOptions {
+    /**
+     * The Queek-side canonical path the backend signed
+     * (`/apps/<subpath>/<rest>`, e.g. `/apps/booking/availability`) — the
+     * app's local route is NOT it. Pass one per route.
+     */
+    path: string;
+}
+/** What the app answers once the query verifies (it owns the body — slots, JSON, …). */
+export type ProxyResponder = (verified: {
+    installation: InstallationRecord;
+    params: Record<string, string>;
+}) => Response | Promise<Response>;
+/**
+ * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads the query
+ * off the request URL, calls the core, builds the `Response`. Phase 1 is
+ * read-only by binding rule (the backend only ever sends GET), so only
+ * `GET` is served; anything else answers 405.
+ */
+export declare function handleProxyRequest(request: Request, options: ProxyRequestOptions, onVerified: ProxyResponder): Promise<Response>;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/proxy.js

@@ -0,0 +1,204 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { toResponse } from "./delivery.js";
+import { normalisePid } from "./store.js";
+/**
+ * Storefront app-proxy query verification, byte-for-byte compatible with
+ * Queek's `App\Services\Apps\AppProxyService` (queek_backend).
+ *
+ * Queek signs a READ fetch to the app's proxy handler with the installation's
+ * `proxy_secret` (`signQuery`): the app verifies server-side before answering
+ * the shopper. Canonical signature (Shopify-style, per-install secret):
+ *
+ *   sig = hex HMAC-SHA256 over
+ *     path + "\n" + shop + "\n" + ts + "\n" + sorted(k=v&...) (sig excluded),
+ *
+ * where each pair is `rawurlencode(key)=rawurlencode(value)` and keys sort
+ * byte-wise. The HMAC key is the FULL `whsec_…` string — no base64 decode
+ * step (the single most common integration bug cannot happen here).
+ *
+ * `path` is the QUEEK-side canonical path (`/apps/<subpath>/<rest>`, what
+ * the backend signs in `fetch()`), NOT the app's local route: pass it
+ * explicitly per route (see `handleProxyRequest`).
+ *
+ * Layering mirrors the install/webhook handlers: layer 1
+ * `verifyProxyDelivery` takes plain data (path + query) and returns a plain
+ * result — zero request/response types; layer 2 `handleProxyRequest` adapts
+ * the Web standard onto layer 1; `@usequeek/app-sdk/hono`
+ * `createProxyHandler` adapts Hono onto layer 2.
+ */
+export const PROXY_SIGNATURE_PARAM = "sig";
+export const PROXY_TIMESTAMP_PARAM = "ts";
+export const PROXY_NONCE_PARAM = "jti";
+export const PROXY_SHOP_PARAM = "shop";
+export const PROXY_CUSTOMER_PARAM = "logged_in_customer_id";
+export const PROXY_KID_PARAM = "kid";
+/** Backend `apps.proxy_signature_skew_seconds` default; the floor (60s) below applies regardless. */
+export const PROXY_MAX_SKEW_SECONDS = 300;
+/** PHP `rawurlencode`: everything except `[A-Za-z0-9-_.~]` is `%XX` (upper-case hex). */
+function proxyEncode(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (ch) => {
+        return `%${ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`;
+    });
+}
+/** PHP `strval` for scalar query values: null/undefined become `""`, everything else stringifies. */
+function proxyString(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return "";
+    return Array.isArray(value) ? proxyString(value[0]) : String(value);
+}
+/** Collapse a query to plain strings (duplicates → first value, undefined → absent). */
+function normalizeQuery(query) {
+    const out = {};
+    for (const [key, value] of Object.entries(query)) {
+        const flat = proxyString(value);
+        if (flat !== undefined)
+            out[key] = flat;
+    }
+    return out;
+}
+/**
+ * The canonical string the MAC covers — mirrors `AppProxyService::signature()`
+ * exactly (sig excluded, keys byte-sorted, rawurlencoded pairs).
+ */
+export function buildProxyCanonicalString(path, params) {
+    const sorted = { ...params };
+    delete sorted[PROXY_SIGNATURE_PARAM];
+    const keys = Object.keys(sorted).sort();
+    const pairs = keys.map((key) => `${proxyEncode(key)}=${proxyEncode(sorted[key])}`);
+    return `${path}\n${sorted[PROXY_SHOP_PARAM] ?? ""}\n${sorted[PROXY_TIMESTAMP_PARAM] ?? ""}\n${pairs.join("&")}`;
+}
+/**
+ * One hex signature for one secret — mirrors `AppProxyService::signature()`.
+ * Exported so tests (and dev harnesses) can recompute a signature
+ * independently of the verifier; production traffic is signed by Queek.
+ */
+export function signProxyQuery(path, params, secret) {
+    return createHmac("sha256", secret).update(buildProxyCanonicalString(path, params), "utf8").digest("hex");
+}
+function readProxyFields(params) {
+    return {
+        sig: params[PROXY_SIGNATURE_PARAM] ?? "",
+        ts: params[PROXY_TIMESTAMP_PARAM] ?? "",
+        jti: params[PROXY_NONCE_PARAM] ?? "",
+    };
+}
+function proxySkewExceeded(ts, options) {
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const maxSkew = Math.max(60, options.maxSkewSeconds ?? PROXY_MAX_SKEW_SECONDS);
+    return Math.abs(now - Number(ts)) > maxSkew;
+}
+function proxyMacMatches(path, params, sig, secret) {
+    if (secret === "")
+        return false;
+    const expected = signProxyQuery(path, params, secret);
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const candidateBuf = Buffer.from(sig, "utf8");
+    return candidateBuf.length === expectedBuf.length && timingSafeEqual(candidateBuf, expectedBuf);
+}
+/**
+ * Pure verification over explicitly passed secrets — mirrors
+ * `AppProxyService::verifyQuery()` (structure → skew → secret presence →
+ * MAC over every active secret). No replay enforcement here: single-use
+ * `jti` needs storage, so the store-backed `verifyProxyDelivery` claims it
+ * (the framework-free translation of the backend's atomic `Cache::add`).
+ */
+export function verifyProxyQueryDetailed(path, query, secrets, options = {}) {
+    const params = normalizeQuery(query);
+    const { sig, ts, jti } = readProxyFields(params);
+    if (sig === "" || ts === "" || jti === "" || !/^\d+$/.test(ts)) {
+        return { ok: false, reason: "missing_params" };
+    }
+    if (proxySkewExceeded(ts, options)) {
+        return { ok: false, reason: "stale_timestamp" };
+    }
+    if (secrets.length === 0 || secrets[0] === "") {
+        return { ok: false, reason: "missing_secret" };
+    }
+    for (const secret of secrets) {
+        if (proxyMacMatches(path, params, sig, secret)) {
+            return { ok: true };
+        }
+    }
+    return { ok: false, reason: "signature_mismatch" };
+}
+/** Boolean fast path over {@link verifyProxyQueryDetailed}. */
+export function verifyProxyQuery(path, query, secrets, options = {}) {
+    return verifyProxyQueryDetailed(path, query, secrets, options).ok;
+}
+/**
+ * Layer 1: verify one signed proxy query from plain data — no `Request`, no
+ * framework. Resolves the installation from the existing store by the `kid`
+ * routing hint (the installation p_id Queek signs in); without a `kid` it
+ * falls back to trying each stored proxy secret, the signature naming the
+ * sender (same rationale as the webhook resolver). Freshness is enforced
+ * before attribution; a verified `jti` is claimed atomically so a captured
+ * read cannot be replayed.
+ */
+export async function verifyProxyDelivery(input, options) {
+    const fail = (reason) => ({ ok: false, reason, status: 401 });
+    const params = normalizeQuery(input.query);
+    const { sig, ts, jti } = readProxyFields(params);
+    if (sig === "" || ts === "" || jti === "" || !/^\d+$/.test(ts)) {
+        return fail("missing_params");
+    }
+    if (proxySkewExceeded(ts, options)) {
+        return fail("stale_timestamp");
+    }
+    const kid = params[PROXY_KID_PARAM];
+    const rows = await options.store.listInstallations();
+    // Normalise the routing hint before comparing: stored pids are canonical
+    // integer strings, but the hint may arrive as a JSON integer or a
+    // non-canonical decimal string (`"1021.0"`); canonical strings compare
+    // exactly as before.
+    const candidates = kid !== undefined && kid !== ""
+        ? rows.filter((row) => row.installationPid === normalisePid(kid))
+        : rows.filter((row) => row.proxySecret !== null && row.proxySecret !== undefined);
+    if (candidates.length === 0) {
+        return fail("unknown_installation");
+    }
+    const secrets = candidates.map((row) => row.proxySecret ?? "");
+    if (secrets.length === 0 || secrets[0] === "") {
+        return fail("missing_secret");
+    }
+    let installation = null;
+    for (const candidate of candidates) {
+        if (proxyMacMatches(input.path, params, sig, candidate.proxySecret ?? "")) {
+            installation = candidate;
+            break;
+        }
+    }
+    if (!installation) {
+        return fail("signature_mismatch");
+    }
+    if (options.enforceReplay ?? true) {
+        if (!(await options.store.claimWebhookId(`proxy-jti:${jti}`))) {
+            return fail("replayed");
+        }
+    }
+    return { ok: true, installation, params };
+}
+/**
+ * Layer 2: the Web-standard wrapper, built ONLY on layer 1 — reads the query
+ * off the request URL, calls the core, builds the `Response`. Phase 1 is
+ * read-only by binding rule (the backend only ever sends GET), so only
+ * `GET` is served; anything else answers 405.
+ */
+export async function handleProxyRequest(request, options, onVerified) {
+    if (request.method.toUpperCase() !== "GET") {
+        return toResponse({ status: 405, body: { ok: false, error: "method_not_allowed" } });
+    }
+    const url = new URL(request.url);
+    const query = {};
+    for (const key of url.searchParams.keys()) {
+        query[key] = url.searchParams.get(key);
+    }
+    const verified = await verifyProxyDelivery({ path: options.path, query }, options);
+    if (!verified.ok) {
+        const result = { status: verified.status, body: { ok: false, error: verified.reason } };
+        return toResponse(result);
+    }
+    return onVerified({ installation: verified.installation, params: verified.params });
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Optional React bindings for `@usequeek/app-sdk` (U2).
+ *
+ * Import from `@usequeek/app-sdk/react` (requires the optional `react`
+ * peer) — a thin layer built ONLY on the framework-free core (`frame.js` /
+ * `theme.js`): `<QueekProvider>` owns one bridge subscription, and
+ * `useQueek()` exposes `{ toast, saveBar, title, navigate, pickResource,
+ * theme }` over it.
+ *
+ * No JSX in this file (the build stays plain `tsc`, no `jsx` flag).
+ */
+import { type ReactNode } from "react";
+import { type BridgeTheme, type EmbedEventTarget, type EmbedPostTarget, type PickResourceRequest, type ResourceItem, type SaveBarAction, type SaveBarState, type TitleActionDef, type ToastTone } from "./frame.js";
+import { type ThemeMode } from "./theme.js";
+/** A pick with no dashboard answer settles after this long (never deadlocks). */
+export declare const PICK_TIMEOUT_MS: number;
+/**
+ * How long after `ready` the provider waits for the dashboard's capability
+ * handshake (on its `theme` message) before treating the dashboard as legacy.
+ */
+export declare const HANDSHAKE_TIMEOUT_MS = 1500;
+export type { BridgeTheme, PickResourceRequest, ResourceItem, SaveBarAction, SaveBarState, ThemeMode, TitleActionDef, ToastTone, };
+export interface ToastOptions {
+    tone?: ToastTone;
+    durationMs?: number;
+}
+export interface TitleActions {
+    primaryAction?: TitleActionDef;
+    secondaryActions?: TitleActionDef[];
+}
+export interface SaveBarApi {
+    dirty: () => void;
+    clean: () => void;
+    onAction: (handler: (action: SaveBarAction) => void) => () => void;
+}
+export interface TitleApi {
+    set: (heading: string, actions?: TitleActions) => void;
+    onAction: (handler: (id: string) => void) => () => void;
+}
+export interface NavigateApi {
+    /** Report an in-app move so the dashboard mirrors it in its URL. */
+    report: (path: string) => void;
+    /** Follow dashboard-driven moves (back/forward, sidebar). */
+    onNavigate: (handler: (path: string) => void) => () => void;
+    /** Ask the dashboard to open a dashboard path or https URL. */
+    open: (target: string) => void;
+}
+export interface ThemeApi {
+    mode: ThemeMode;
+}
+export interface QueekApi {
+    toast: (message: string, options?: ToastOptions) => void;
+    saveBar: SaveBarApi;
+    title: TitleApi;
+    navigate: NavigateApi;
+    /** Resolve with the picked items, or null when the merchant cancels. */
+    pickResource: (request: PickResourceRequest) => Promise<ResourceItem[] | null>;
+    theme: ThemeApi;
+}
+export interface QueekProviderProps {
+    dashboardOrigin: string;
+    children?: ReactNode;
+    /** Declared in `ready{capabilities}` so old dashboards degrade gracefully. */
+    capabilities?: string[];
+    sdkVersion?: string;
+    postTarget?: EmbedPostTarget;
+    listenTarget?: EmbedEventTarget;
+    getHref?: () => string;
+    /**
+     * Required `event.source` for bridge messages. Defaults to the global
+     * window's parent when present; pass `null` to disable the source check.
+     */
+    expectSource?: unknown;
+}
+export declare function QueekProvider(props: QueekProviderProps): ReactNode;
+/** Bridge actions + live theme over the framework-free core. */
+export declare function useQueek(): QueekApi;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"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"}