@usequeek/app-sdk 0.6.1 → 0.7.0

package/dist/merchant-schema.js

@@ -8,4 +8,3 @@
  * Do not make direct changes to the file.
  */
 export {};
-//# sourceMappingURL=merchant-schema.js.map

package/dist/proxy.d.ts

@@ -1,22 +1,22 @@
 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).
+ * the way Queek signs proxy reads.
  *
  * 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):
+ * `proxy_secret`: the app verifies server-side before answering the
+ * shopper. Canonical signature (per-installation 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
+ * where each pair is `encode(key)=encode(value)` (RFC 3986 percent-encoding) 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`).
+ * `path` is the QUEEK-side canonical path (`/apps/<subpath>/<rest>`, the
+ * path Queek signs), 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
@@ -30,19 +30,19 @@ 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. */
+/** Default allowed clock skew in seconds; 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).
+ * The canonical string the MAC covers, exactly as Queek builds it (sig
+ * excluded, keys byte-sorted, percent-encoded pairs).
  */
 export declare function buildProxyCanonicalString(path: string, params: Record<string, string>): string;
 /**
- * One hex signature for one secret — mirrors `AppProxyService::signature()`.
+ * One hex signature for one secret, computed as Queek computes it.
  * Exported so tests (and dev harnesses) can recompute a signature
  * independently of the verifier; production traffic is signed by Queek.
  */
@@ -50,15 +50,14 @@ export declare function signProxyQuery(path: string, params: Record<string, stri
 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). */
+    /** Allowed clock skew in seconds (defaults to PROXY_MAX_SKEW_SECONDS; floored at 60). */
     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`).
+ * Pure verification over explicitly passed secrets (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 atomically.
  */
 export declare function verifyProxyQueryDetailed(path: string, query: ProxyQuery, secrets: string[], options?: ProxyVerifyOptions): {
     ok: true;
@@ -72,8 +71,7 @@ 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.
+     * for apps that enforce replay themselves). Defaults to enforcing.
      */
     enforceReplay?: boolean;
 }
@@ -101,7 +99,7 @@ export declare function verifyProxyDelivery(input: {
 }, options: ProxyStoreOptions): Promise<ProxyVerification>;
 export interface ProxyRequestOptions extends ProxyStoreOptions {
     /**
-     * The Queek-side canonical path the backend signed
+     * The Queek-side canonical path Queek signed
      * (`/apps/<subpath>/<rest>`, e.g. `/apps/booking/availability`) — the
      * app's local route is NOT it. Pass one per route.
      */
@@ -114,9 +112,8 @@ export type ProxyResponder = (verified: {
 }) => 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.
+ * off the request URL, calls the core, builds the `Response`. Proxy reads
+ * are read-only (Queek 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.js

@@ -3,22 +3,22 @@ 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).
+ * the way Queek signs proxy reads.
  *
  * 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):
+ * `proxy_secret`: the app verifies server-side before answering the
+ * shopper. Canonical signature (per-installation 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
+ * where each pair is `encode(key)=encode(value)` (RFC 3986 percent-encoding) 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`).
+ * `path` is the QUEEK-side canonical path (`/apps/<subpath>/<rest>`, the
+ * path Queek signs), 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
@@ -32,15 +32,15 @@ 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. */
+/** Default allowed clock skew in seconds; 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). */
+/** RFC 3986 percent-encoding: everything except `[A-Za-z0-9-_.~]` is `%XX` (upper-case hex), the encoding Queek signs with. */
 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. */
+/** Scalar query values as strings, as Queek's signer reads them: null becomes `""`, an array contributes its first value, everything else stringifies. `undefined` means absent. */
 function proxyString(value) {
     if (value === undefined)
         return undefined;
@@ -59,8 +59,8 @@ function normalizeQuery(query) {
     return out;
 }
 /**
- * The canonical string the MAC covers — mirrors `AppProxyService::signature()`
- * exactly (sig excluded, keys byte-sorted, rawurlencoded pairs).
+ * The canonical string the MAC covers, exactly as Queek builds it (sig
+ * excluded, keys byte-sorted, percent-encoded pairs).
  */
 export function buildProxyCanonicalString(path, params) {
     const sorted = { ...params };
@@ -70,7 +70,7 @@ export function buildProxyCanonicalString(path, params) {
     return `${path}\n${sorted[PROXY_SHOP_PARAM] ?? ""}\n${sorted[PROXY_TIMESTAMP_PARAM] ?? ""}\n${pairs.join("&")}`;
 }
 /**
- * One hex signature for one secret — mirrors `AppProxyService::signature()`.
+ * One hex signature for one secret, computed as Queek computes it.
  * Exported so tests (and dev harnesses) can recompute a signature
  * independently of the verifier; production traffic is signed by Queek.
  */
@@ -98,11 +98,10 @@ function proxyMacMatches(path, params, sig, secret) {
     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`).
+ * Pure verification over explicitly passed secrets (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 atomically.
  */
 export function verifyProxyQueryDetailed(path, query, secrets, options = {}) {
     const params = normalizeQuery(query);
@@ -181,9 +180,9 @@ export async function verifyProxyDelivery(input, options) {
 }
 /**
  * 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.
+ * off the request URL, calls the core, builds the `Response`. Proxy reads
+ * are read-only (Queek 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") {
@@ -201,4 +200,3 @@ export async function handleProxyRequest(request, options, onVerified) {
     }
     return onVerified({ installation: verified.installation, params: verified.params });
 }
-//# sourceMappingURL=proxy.js.map

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 /**
- * Optional React bindings for `@usequeek/app-sdk` (U2).
+ * Optional React bindings for `@usequeek/app-sdk`.
  *
  * Import from `@usequeek/app-sdk/react` (requires the optional `react`
  * peer) — a thin layer built ONLY on the framework-free core (`frame.js` /
@@ -72,7 +72,15 @@ export interface QueekProviderProps {
      */
     expectSource?: unknown;
 }
+/**
+ * Owns the one bridge subscription for the embedded merchant page. Wrap the
+ * app root in it, then call `useQueek()` anywhere below.
+ *
+ * @example
+ * <QueekProvider dashboardOrigin="https://dashboard.usequeek.com" capabilities={["toast"]}>
+ *   <App />
+ * </QueekProvider>
+ */
 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.js

@@ -1,6 +1,6 @@
 "use client";
 /**
- * Optional React bindings for `@usequeek/app-sdk` (U2).
+ * Optional React bindings for `@usequeek/app-sdk`.
  *
  * Import from `@usequeek/app-sdk/react` (requires the optional `react`
  * peer) — a thin layer built ONLY on the framework-free core (`frame.js` /
@@ -33,6 +33,15 @@ function resolveConfig(props, win) {
         expectSource: props.expectSource !== undefined ? props.expectSource : (win?.parent ?? undefined),
     };
 }
+/**
+ * Owns the one bridge subscription for the embedded merchant page. Wrap the
+ * app root in it, then call `useQueek()` anywhere below.
+ *
+ * @example
+ * <QueekProvider dashboardOrigin="https://dashboard.usequeek.com" capabilities={["toast"]}>
+ *   <App />
+ * </QueekProvider>
+ */
 export function QueekProvider(props) {
     const { dashboardOrigin, children, sdkVersion } = props;
     const win = useMemo(() => globalWindow(), []);
@@ -224,7 +233,7 @@ export function QueekProvider(props) {
 function useBridge() {
     const bridge = useContext(QueekBridgeContext);
     if (bridge === null) {
-        throw new Error("useQueek must be used inside <QueekProvider>");
+        throw new Error("useQueek must be called inside <QueekProvider>. Wrap the app root in <QueekProvider>.");
     }
     return bridge;
 }
@@ -259,4 +268,3 @@ export function useQueek() {
     const pickResource = useCallback((request) => bridge.requestPick(request), [bridge]);
     return useMemo(() => ({ toast, saveBar, title, navigate, pickResource, theme: { mode } }), [toast, saveBar, title, navigate, pickResource, mode]);
 }
-//# sourceMappingURL=react.js.map

package/dist/resync.d.ts

@@ -2,7 +2,7 @@ import { type Logger } from "./logger.js";
 import type { InstallationStore } from "./store.js";
 import { type AppTokenProvider } from "./tokens.js";
 /**
- * Connectivity recovery (S1, SDK 0.2.0): after a database loss (or an
+ * Connectivity recovery: after a database loss (or an
  * outage that outlasted the webhook retries), re-list the app's
  * installations from Queek and re-handshake each one's secrets.
  *
@@ -13,7 +13,7 @@ import { type AppTokenProvider } from "./tokens.js";
  *   settings arrive over the EXISTING signed install channel (same handoff
  *   envelope as install), handled by the install handler — which accepts a
  *   resync for an existing installation idempotently.
- * - Per-installation refusals (rev 8, distinguished by code): 409
+ * - Per-installation refusals (distinguished by code): 409
  *   `app_installation_pending` retries later with backoff (bounded, then
  *   skipped + recorded — NEVER purged); 429 `resync_cooldown` is the
  *   rotation COOLDOWN (≤1/hour: skipped + recorded, no retry loop); any
@@ -37,14 +37,14 @@ import { type AppTokenProvider } from "./tokens.js";
  * resync cannot backfill them.
  */
 export interface ResyncOptions {
-    /** The app's Queek backend hosting `/api/v1/apps` (normally any installation's `api_base`). */
+    /** The Queek API host serving `/api/v1/apps` (normally any installation's `api_base`). */
     apiBase: string;
     tokens: AppTokenProvider;
     store: InstallationStore;
     fetchImpl?: typeof fetch;
     /** Sent as User-Agent. Defaults to `queek-app/1.0`. */
     userAgent?: string;
-    /** Extra allowed `apiBase` hosts (test/local backends). */
+    /** Extra allowed `apiBase` hosts (test/local API hosts). */
     allowedApiHosts?: string[];
     logger?: Logger;
     sleep?: (ms: number) => Promise<void>;
@@ -76,5 +76,15 @@ export interface ResyncListItem {
     scopes: string[];
     status: string;
 }
+/**
+ * Recover connectivity after a database loss or a long outage: list the
+ * app's active installations and ask Queek to redeliver each one's secrets
+ * and settings over the signed install channel. A refusal for one
+ * installation never aborts the run; read `cooldownSkipped`,
+ * `pendingSkipped` and `purged` on the result.
+ *
+ * @example
+ * const result = await resyncFromQueek({ apiBase: "https://api.usequeek.com", tokens, store });
+ * console.log(result.resyncRequested.length, "installations asked to redeliver");
+ */
 export declare function resyncFromQueek(options: ResyncOptions): Promise<ResyncResult>;
-//# sourceMappingURL=resync.d.ts.map

package/dist/resync.js

@@ -1,5 +1,5 @@
 import { isInstallationGone, isInstallationPending, isResyncCooldown, RETRY_JITTER_MAX_MS, } from "./app-auth.js";
-import { QueekApiError, queekApiErrorFromResponse } from "./client.js";
+import { DEFAULT_REQUEST_TIMEOUT_MS, QueekApiError, queekApiErrorFromResponse, requestSignal, transportError, tryParseJson, } from "./client.js";
 import { createLogger } from "./logger.js";
 import { resolveAppApiBase } from "./tokens.js";
 const MAX_LIST_ATTEMPTS = 3;
@@ -12,6 +12,17 @@ const RESYNC_BACKOFF_MAX_MS = 5_000;
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Recover connectivity after a database loss or a long outage: list the
+ * app's active installations and ask Queek to redeliver each one's secrets
+ * and settings over the signed install channel. A refusal for one
+ * installation never aborts the run; read `cooldownSkipped`,
+ * `pendingSkipped` and `purged` on the result.
+ *
+ * @example
+ * const result = await resyncFromQueek({ apiBase: "https://api.usequeek.com", tokens, store });
+ * console.log(result.resyncRequested.length, "installations asked to redeliver");
+ */
 export async function resyncFromQueek(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const userAgent = options.userAgent ?? "queek-app/1.0";
@@ -29,14 +40,14 @@ export async function resyncFromQueek(options) {
         headers.set("User-Agent", userAgent);
         let response;
         try {
-            response = await fetchImpl(`${appBase}${path}`, { method: init.method, headers });
+            response = await fetchImpl(`${appBase}${path}`, {
+                method: init.method,
+                headers,
+                signal: requestSignal(undefined, DEFAULT_REQUEST_TIMEOUT_MS),
+            });
         }
         catch (cause) {
-            throw new QueekApiError({
-                status: 0,
-                code: "network_error",
-                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
-            });
+            throw transportError(cause);
         }
         return response;
     }
@@ -49,7 +60,7 @@ export async function resyncFromQueek(options) {
     }
     // -- List (opaque keyset cursor, secret-free) ------------------------------
     // The cursor is never interpreted — echoed back verbatim until
-    // `next_cursor` is null (rev 8: keyset on a stable unique key, scoped to
+    // `next_cursor` is null (keyset on a stable unique key, scoped to
     // the calling app; inserts/uninstalls mid-walk never skip or duplicate).
     const listed = [];
     let cursor = null;
@@ -120,7 +131,7 @@ export async function resyncFromQueek(options) {
                 break;
             }
             if (response.status === 429) {
-                // Per-app bucket (rev 8): back off on `Retry-After` (jittered) and
+                // Per-app bucket: back off on `Retry-After` (jittered) and
                 // retry — never recorded as a cooldown skip. An exhausted budget
                 // aborts the run: the whole app is throttled, so pushing on would
                 // only deepen it; the caller retries later.
@@ -130,7 +141,7 @@ export async function resyncFromQueek(options) {
                 continue;
             }
             if (response.status === 409 && isInstallationPending(error.code)) {
-                // Pending installation (rev 8, mark persisted per B2 review r2):
+                // Pending installation:
                 // retry later with backoff — NEVER purge. An exhausted budget
                 // skips (recorded); the persisted mark survives restarts, so the
                 // purge-absent step below (and after a restart) keeps the row.
@@ -169,7 +180,7 @@ export async function resyncFromQueek(options) {
     }
     // …and purge local rows Queek no longer lists (uninstall-while-down) —
     // EXCEPT rows carrying the persisted pending mark. The list covers
-    // ACTIVE installations only (rev 8), so absence alone never purges a
+    // ACTIVE installations only, so absence alone never purges a
     // pending row — including after a process restart, because the mark
     // lives in the store column, not in memory. The row stays for a later
     // run, when it is active (listed + resynced), gone (404 → purged), or
@@ -192,12 +203,3 @@ export async function resyncFromQueek(options) {
     }
     return result;
 }
-function tryParseJson(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return { message: text.slice(0, 500) };
-    }
-}
-//# sourceMappingURL=resync.js.map

package/dist/scopes.d.ts

@@ -1,8 +1,7 @@
 import { QueekApiError } from "./client.js";
 import type { InstallationStore } from "./store.js";
 /**
- * Optional scopes (plan item 6, Shopify `scopes.query / request / revoke`
- * parity — symbol names cited only).
+ * Optional scopes: query, request and revoke.
  *
  * - `queryScopes`: the cached effective grant split against the app's own
  *   declared-optional list. Store-read only, never a fetch: the app-credential
@@ -14,25 +13,24 @@ import type { InstallationStore } from "./store.js";
  *   consent — it hands the app a link shaped like the bridge
  *   `open`/`navigate` targets (dashboard-relative path, or an absolute URL
  *   under a given dashboard origin) for the app to open via `sendOpen` or
- *   redirect to. The consent screen itself ships with the dashboard (plan
- *   item 8), which honours this link shape.
+ *   redirect to. Opening it requires a dashboard that supports the consent
+ *   screen, which honours this link shape.
  * - `revokeScopes`: `POST
  *   /api/v1/apps/installations/{installation}/scopes/revoke` with the app
- *   JWT (same credential as mint/resync — never auth:sanctum, never the
- *   installation token). Body `{scopes[]}` (1–50, backend
- *   `RevokeAppScopesRequest`); an `Idempotency-Key` rides the write for
+ *   JWT (same credential as mint/resync — not the installation token).
+ *   Body `{scopes[]}` (1–50); an `Idempotency-Key` rides the write for
  *   discipline (generated when the caller does not supply one — the client
  *   write discipline), though the route is naturally idempotent: revoking
  *   a never-granted optional scope is 200 with no change. Required scopes
  *   refuse 422 `app_scope_required` (surfaced as `AppScopeRequiredError`).
  *   On 200 the cached grant is refreshed from the response and the cached
  *   token dropped only when the grant moved (same compare-and-clear as the
- *   scopes_update handler — the backend rewrites live token rows in place,
- *   so the drop is backstop, not mechanism).
+ *   scopes_update handler — Queek rewrites live token rows in place, so
+ *   the drop is a backstop, not the mechanism).
  *
  * Types here are hand-written: the revoke endpoint and the scopes_update
- * handoff live on the app-credential surface, which the frozen
- * `openapi/merchant.json` does not cover (types are generated app-side by
+ * handoff live on the app-credential surface, which the bundled
+ * `openapi/merchant.json` snapshot does not cover (types are generated app-side by
  * `queek app codegen`; the merchant spec file is never hand-edited).
  */
 /** 422 on the revoke endpoint: required scopes are never revocable (uninstall is the remedy). */
@@ -43,8 +41,8 @@ export declare const APP_SCOPE_UNDECLARED_CODE = "app_scope_undeclared";
 export declare function isAppScopeRequired(status: number, code: string | undefined): boolean;
 /**
  * A required-scope refusal, typed so callers switch on the class (or
- * `code`), never on `message`. Carries the offending scopes when the
- * backend named them.
+ * `code`), never on `message`. Carries the offending scopes when Queek
+ * named them.
  */
 export declare class AppScopeRequiredError extends QueekApiError {
     readonly scopes: string[];
@@ -57,13 +55,13 @@ export declare class InvalidScopesError extends Error {
     readonly code = "invalid_scopes";
     constructor(message: string);
 }
-/** Backend `RevokeAppScopesRequest` bounds, mirrored client-side. */
+/** Bounds of the revoke request (1–50 scopes), mirrored client-side. */
 export declare const MAX_SCOPE_LIST = 50;
 export declare const MAX_SCOPE_LENGTH = 120;
 /**
  * Validate + normalise a scope list (trim, drop empties, dedupe keeping
- * first order). Mirrors the backend contract (`required array min:1
- * max:50`, string items) so a malformed call fails before any fetch.
+ * first order). Mirrors the revoke endpoint's rules (a required array of
+ * 1–50 string items) so a malformed call fails before any fetch.
  */
 export declare function normaliseScopeList(scopes: unknown): string[];
 /** The cached-grant split `queryScopes` returns. */
@@ -99,8 +97,7 @@ export interface ScopeRequestLinkOptions {
  * under `dashboardOrigin` (refused exactly like `sendOpen` refuses a bad
  * target).
  *
- * Link shape (the SDK↔dashboard contract the consent screen honours —
- * the only query route the dashboard `AppsPage` serves):
+ * Link shape (the contract the dashboard's consent screen honours):
  * `/apps?app={slug}&view=scopes&scopes={a},{b}` (each scope
  * URL-encoded, comma-separated). The link carries the slug + the scope
  * list only: the dashboard resolves the installation from the signed-in
@@ -132,14 +129,14 @@ export interface InstallationScopesClientOptions {
     store: InstallationStore;
     /**
      * A fresh app JWT per call — e.g. `() => provider.signJwt()`. The revoke
-     * endpoint takes the same app credential as mint/resync (never
-     * auth:sanctum, never the installation token).
+     * endpoint takes the same app credential as mint/resync (not the
+     * installation token).
      */
     signJwt: () => string;
     fetchImpl?: typeof fetch;
     /** Sent as User-Agent. Defaults to `queek-app/1.0`. */
     userAgent?: string;
-    /** Extra allowed `apiBase` hosts (test/local backends). */
+    /** Extra allowed `apiBase` hosts (test/local API hosts). */
     allowedApiHosts?: string[];
     /** The app's dashboard slug (addresses the scope-request consent screen); per-call override wins. */
     appSlug?: string;
@@ -153,11 +150,10 @@ export interface InstallationScopesClientOptions {
     dashboardOrigin?: string;
 }
 /**
- * The per-installation scopes session (Shopify `scopes.query / request /
- * revoke` parity — symbol names cited only). A sibling of the installation
- * client, not a method on it: the installation client's exact type is a
- * committed contract (the generics compat guard), so the scopes surface
- * lives here, wired to the same store + token provider.
+ * The per-installation scopes session. A sibling of the installation
+ * client, not a method on it: the installation client's exact type is part
+ * of the public API (and is guarded by a generics type test), so the
+ * scopes surface lives here, wired to the same store + token provider.
  *
  * - `queryScopes` reads the cached grant (no network).
  * - `requestScopes` builds the dashboard deep link the merchant approves
@@ -170,5 +166,18 @@ export interface InstallationScopesClient {
     requestScopes(scopes: string[], options?: RequestScopesLinkOptions): string;
     revokeScopes(scopes: string[], options?: RevokeScopesOptions): Promise<string[]>;
 }
+/**
+ * Build the optional-scopes session for one installation: read the cached
+ * grant, build the dashboard consent link, and revoke optional scopes.
+ *
+ * @example
+ * const scopes = createInstallationScopesClient({
+ *   installationId,
+ *   store,
+ *   signJwt: () => tokens.signJwt(),
+ *   appSlug: "my-app",
+ *   optionalScopes: ["merchant-orders-read"],
+ * });
+ * const { granted } = await scopes.queryScopes();
+ */
 export declare function createInstallationScopesClient(options: InstallationScopesClientOptions): InstallationScopesClient;
-//# sourceMappingURL=scopes.d.ts.map