@proveanything/smartlinks 2.0.21 → 2.0.24

package/dist/api/functions.d.ts

@@ -8,9 +8,16 @@ export interface FunctionListEntry {
 export interface FunctionListResponse {
     functions: FunctionListEntry[];
 }
-/** Options for a function call. `appId` scopes resolution to one app (recommended). */
+/**
+ * Options for a function call.
+ * - `appId` scopes resolution to one app (recommended; falls back to the SDK app context).
+ * - `channel` selects which release to run when addressing an app that is NOT enabled on the
+ *   collection (enablement isn't required — the app is resolved directly by id). Defaults to
+ *   `stable` server-side, so pass `channel: 'dev'` to test a dev build before installing it.
+ */
 export interface FunctionCallOptions {
     appId?: string;
+    channel?: string;
 }
 export declare namespace functions {
     /**

package/dist/api/functions.js

@@ -14,13 +14,15 @@
 // which the server resolves by bare name and REJECTS with 409 AMBIGUOUS_FUNCTION when more than one
 // installed app defines that name. Always prefer an appId.
 import { post, request, getAppContext } from "../http.js";
-function fnPath(surface, collectionId, name, appId) {
+function fnPath(surface, collectionId, name, opts = {}) {
+    var _a;
     const c = encodeURIComponent(collectionId);
     const n = encodeURIComponent(name);
-    const app = appId !== null && appId !== void 0 ? appId : getAppContext();
+    const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+    const q = opts.channel ? `?channel=${encodeURIComponent(opts.channel)}` : '';
     return app
-        ? `/${surface}/collection/${c}/app/${encodeURIComponent(app)}/functions/${n}`
-        : `/${surface}/collection/${c}/functions/${n}`; // deprecated flat alias
+        ? `/${surface}/collection/${c}/app/${encodeURIComponent(app)}/functions/${n}${q}`
+        : `/${surface}/collection/${c}/functions/${n}${q}`; // deprecated flat alias
 }
 export var functions;
 (function (functions) {
@@ -35,7 +37,7 @@ export var functions;
      * await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
      */
     async function call(collectionId, name, body = {}, opts = {}) {
-        return post(fnPath('public', collectionId, name, opts.appId), body);
+        return post(fnPath('public', collectionId, name, opts), body);
     }
     functions.call = call;
     /**
@@ -43,7 +45,7 @@ export var functions;
      * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
      */
     async function callAdmin(collectionId, name, body = {}, opts = {}) {
-        return post(fnPath('admin', collectionId, name, opts.appId), body);
+        return post(fnPath('admin', collectionId, name, opts), body);
     }
     functions.callAdmin = callAdmin;
     /**
@@ -54,9 +56,10 @@ export var functions;
         var _a;
         const c = encodeURIComponent(collectionId);
         const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+        const q = opts.channel ? `?channel=${encodeURIComponent(opts.channel)}` : '';
         const path = app
-            ? `/public/collection/${c}/app/${encodeURIComponent(app)}/functions`
-            : `/public/collection/${c}/functions`;
+            ? `/public/collection/${c}/app/${encodeURIComponent(app)}/functions${q}`
+            : `/public/collection/${c}/functions${q}`;
         return request(path);
     }
     functions.list = list;

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+export interface SmartLinksContext {
+    collectionId?: string;
+    appId?: string;
+    productId?: string;
+    proofId?: string;
+    /** Any other declared view params (e.g. pageId, voteId, orientation, tvMode). */
+    [key: string]: string | undefined;
+}
+/**
+ * Merge the app's context from `overrides` (e.g. container props) → URL hash query → URL search,
+ * with the FIRST source winning (props override the URL, hash overrides search). Safe in non-browser
+ * environments (returns just the overrides). Empty-string values are kept (a param that was set to "").
+ *
+ * @example
+ *   // Works identically whether embedded as a page (URL) or a container (props):
+ *   const { collectionId, productId } = SL.readContext(containerProps)
+ */
+export declare function readContext(overrides?: Record<string, string | undefined>): SmartLinksContext;

package/dist/context.js

@@ -0,0 +1,48 @@
+// src/context.ts
+// Read the app's runtime CONTEXT (collectionId, appId, productId, proofId, and any app-specific
+// params) regardless of how the app was delivered. A public app renders the SAME page whether it is:
+//   - a PAGE (index.html / HashRouter) — context arrives in the URL search and/or the hash query, or
+//   - a COMPONENT (PublicContainer) — context arrives as props from the parent.
+// This helper merges those sources with a clear precedence so apps stop hand-rolling the
+// `containerProps || hash || search` chain. See docs/design/public-views.md.
+function readSearchParamsInto(out, usp) {
+    usp.forEach((value, key) => {
+        if (out[key] == null && value != null)
+            out[key] = value; // first writer wins
+    });
+}
+/**
+ * Merge the app's context from `overrides` (e.g. container props) → URL hash query → URL search,
+ * with the FIRST source winning (props override the URL, hash overrides search). Safe in non-browser
+ * environments (returns just the overrides). Empty-string values are kept (a param that was set to "").
+ *
+ * @example
+ *   // Works identically whether embedded as a page (URL) or a container (props):
+ *   const { collectionId, productId } = SL.readContext(containerProps)
+ */
+export function readContext(overrides) {
+    const out = {};
+    // 1. overrides (container props) win.
+    if (overrides) {
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value != null && out[key] == null)
+                out[key] = value;
+        }
+    }
+    try {
+        if (typeof window !== 'undefined' && window.location) {
+            // 2. hash query (e.g. "#/preview?collectionId=..&pageId=..") — the CDN/hash-router form.
+            const hash = window.location.hash || '';
+            const q = hash.indexOf('?');
+            if (q >= 0)
+                readSearchParamsInto(out, new URLSearchParams(hash.slice(q + 1)));
+            // 3. search string.
+            if (window.location.search)
+                readSearchParamsInto(out, new URLSearchParams(window.location.search));
+        }
+    }
+    catch (_a) {
+        /* non-browser / bad URL — return what we have */
+    }
+    return out;
+}

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.21  |  Generated: 2026-09-25T17:47:14.766Z
+Version: 2.0.24  |  Generated: 2026-09-27T07:52:03.418Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2132,6 +2132,7 @@ interface AppFunctionDef {
   authority?: AppFunctionAuthority;
   elevated?: boolean;
   capabilities?: string[];
+  dataScope?: 'collection' | 'global';
   apiVersion?: string;
   handler?: string;
 }
@@ -2145,6 +2146,40 @@ interface AppManifestFunctions {
 }
 ```
 
+**AppDataOpts** (interface)
+```typescript
+interface AppDataOpts {
+  scope?: 'collection' | 'global';
+  productId?: string;
+  variantId?: string;
+  batchId?: string;
+  dataId?: string;
+  queries?: Record<string, any>;
+}
+```
+
+**AppDataHandle** (interface)
+```typescript
+interface AppDataHandle {
+  get(opts?: AppDataOpts): Promise<any>;
+  set(data: any, opts?: AppDataOpts): Promise<any>;
+  getData(opts?: AppDataOpts): Promise<any>;
+  setData(data: any, opts?: AppDataOpts): Promise<any>;
+  delete(opts?: AppDataOpts): Promise<any>;
+}
+```
+
+**ServerFunctionSl** (interface)
+```typescript
+interface ServerFunctionSl {
+  appRecords: any;
+  products: any;
+  attestations: any;
+  appData: AppDataHandle & { global: AppDataHandle; collection: AppDataHandle };
+  app(appId: string): { data: Pick<AppDataHandle, 'get' | 'getData'> };
+}
+```
+
 **ServerFunctionCaller** (interface)
 ```typescript
 interface ServerFunctionCaller {
@@ -2161,7 +2196,7 @@ interface ServerFunctionCaller {
 interface ServerFunctionContext {
   collectionId: string;
   appId: string;
-  sl: any;
+  sl: ServerFunctionSl;
   secrets: {
   get(ref: string): Promise<string | null>;
   app(ref: string): Promise<string | null>;
@@ -2172,6 +2207,18 @@ interface ServerFunctionContext {
 }
 ```
 
+**ServerFunctionHttpEvent<TBody = any>** (interface)
+```typescript
+interface ServerFunctionHttpEvent<TBody = any> {
+  method: string;
+  body: TBody;
+  query: Record<string, any>;
+  headers: Record<string, any>;
+  rawBody?: string | Buffer | null;
+  contentType?: string | null;
+}
+```
+
 **AppAdminConfig** (interface)
 ```typescript
 interface AppAdminConfig {
@@ -2233,6 +2280,27 @@ interface AppAdminConfig {
 }
 ```
 
+**PublicViewParams** (interface)
+```typescript
+interface PublicViewParams {
+  required?: string[];
+  optional?: string[];
+}
+```
+
+**PublicView** (interface)
+```typescript
+interface PublicView {
+  id: string;
+  title: string;
+  kind: PublicViewKind;
+  route?: string;
+  set?: Record<string, string>;
+  params?: PublicViewParams;
+  default?: boolean;
+}
+```
+
 **AppManifest** (interface)
 ```typescript
 interface AppManifest {
@@ -2267,6 +2335,7 @@ interface AppManifest {
   components: AppContainerComponent[];
   };
   linkable?: DeepLinkEntry[];
+  publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
   [key: string]: any;
@@ -2304,6 +2373,8 @@ interface GetCollectionWidgetsOptions {
 
 **AppFunctionAuthority** = `'caller' | 'collection'`
 
+**PublicViewKind** = `'contextual' | 'standalone'`
+
 ### appObjects
 
 **PaginatedResponse<T>** (interface)
@@ -8969,7 +9040,7 @@ interface FunctionListResponse {
 **FunctionCallOptions** (interface)
 ```typescript
 interface FunctionCallOptions {
-  appId?: string
+  appId?: string; channel?: string
 }
 ```
 

package/dist/docs/app-manifest.md

@@ -332,6 +332,40 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
 | `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
 
+#### `publicViews`
+
+Declares the app's **public views** — the soft-routed entries over your single public bundle
+(`index.html` → HashRouter): the contextual page, a display board, a kiosk/TV screen, etc. Without
+this, those routes/modes are invisible to the platform and the Dev Hub. Each view is a `route` + fixed
+`set` params + caller `params` + a `kind`; the `default` **contextual** view is the tag-tap target.
+It's delivery-agnostic — the same view renders as a **page** (standalone, self-CSS, hash-routed, embed
+in an iframe or open directly) or, for a contextual view, as a **component** (`PublicContainer`).
+Not a separate build. (Distinct from `linkable`, which is deep-link discovery.)
+
+```json
+"publicViews": [
+  { "id": "page",  "title": "Product page",  "kind": "contextual", "route": "/", "default": true,
+    "params": { "required": ["collectionId"], "optional": ["productId", "proofId"] } },
+  { "id": "board", "title": "Display board", "kind": "standalone", "route": "/preview",
+    "params": { "required": ["collectionId", "appId", "pageId"], "optional": ["orientation"] } },
+  { "id": "tv",    "title": "TV / big screen", "kind": "standalone", "route": "/",
+    "set": { "tvMode": "true" }, "params": { "required": ["collectionId", "voteId"] } }
+]
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Stable id, unique within the app |
+| `title` | string | ✅ | Human label (Dev Hub dropdown, platform pickers) |
+| `kind` | `"contextual"` \| `"standalone"` | ✅ | Context-aware (tag-tap) vs full-screen, non-contextual |
+| `route` | string | ❌ | Hash route within the public bundle (defaults to `"/"`) |
+| `set` | object | ❌ | Query params this view PINS (e.g. `{ "tvMode": "true" }`), merged under caller params |
+| `params` | `{ required?: string[]; optional?: string[] }` | ❌ | The params the caller supplies |
+| `default` | boolean | ❌ | The default contextual view — the tag-tap target (at most one) |
+
+Read context the same way in every delivery with **`SL.readContext(props?)`** (merges props → hash →
+search), instead of hand-rolling the `containerProps || hash || search` chain.
+
 #### `records`
 
 Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [App Records Pattern](app-records-pattern.md). Omit if the app does not use scoped records.

package/dist/docs/server-functions.md

@@ -248,10 +248,21 @@ To call a *different* app's function, pass the appId explicitly:
 await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'some-other-app' })
 ```
 
+**The app does NOT have to be enabled on the collection.** Because the appId is explicit, the
+function is resolved directly from the app's release — so you can test an app on any collection
+before installing it (and without it showing up in that collection's menus). Enabling an app is
+currently just a UX courtesy (dropdowns/menus), not a gate on running its functions. For a build
+that isn't the default `stable` channel — e.g. a **dev** app you haven't installed — pass the
+channel:
+
+```ts
+await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app', channel: 'dev' })
+```
+
 If no appId is available (not set on init, none passed), the call falls back to the **deprecated
-flat path** `/collection/:c/functions/:name`, which the server resolves by bare name and **rejects
-with `409 AMBIGUOUS_FUNCTION`** when more than one installed app defines that name (a first-party
-builtin still wins). Always prefer an appId.
+flat path** `/collection/:c/functions/:name`, which searches only the collection's **enabled** apps,
+resolves by bare name, and **rejects with `409 AMBIGUOUS_FUNCTION`** when more than one defines that
+name (a first-party builtin still wins). Always prefer an appId.
 
 > There is no such thing as an app-less function. First-party builtins (e.g. the `functions.ping`
 > diagnostic) belong to the reserved `smartlinks` app. A "global" function is just an app enabled on
@@ -309,7 +320,8 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Hash / HMAC-sign / verify / encrypt | `crypto.subtle` (Web Crypto) | — |
 | Random id / bytes | `crypto.randomUUID()` / `crypto.getRandomValues()` | — |
 | Read or write SmartLinks data | `ctx.sl.*` (records, products, attestations, …) | the matching `sl:<res>:<read\|write>` |
-| Read/write general or app-wide data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — pass `{ scope: 'global' }` for app-wide (shared by every install; global writes need collection authority) | `sl:data:read` / `sl:data:write` |
+| Read/write your app's own data (config, URLs, counters, arrays) | `ctx.sl.appData.get()` / `ctx.sl.appData.set({…})` — collection-scoped by default; `ctx.sl.appData.global.*` (or `{ scope:'global' }`, or declare `dataScope:'global'`) for the app-wide bucket. It's your OWN namespace, so **any** authority may read/write it | `sl:data:read` / `sl:data:write` |
+| Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
 | Guarantee a UNIQUE claim (pool of numbers, one-per-user, idempotency key) | `ctx.sl.appRecords.create({ ref: 'ball:57' })` — the DB unique index rejects a duplicate `ref` (catch = "already taken") | `sl:records:write` |
 
 Notes:
@@ -376,18 +388,41 @@ POST /public/collection/:collectionId/app/:appId/functions/:name   # visibility:
 GET  /{admin|public}/collection/:collectionId/app/:appId/functions # list this app's functions on the surface
 ```
 
+The app-scoped route resolves the app **directly by id**, so the app need not be enabled on the
+collection — handy for testing an un-installed (dev) app. Add `?channel=dev` (default `stable`) to
+pick the release. Enablement (`appConfig.apps[]`) currently only controls menus/discovery, not
+whether a function can run.
+
 The bare-name form (`/collection/:c/functions/:name`, no `/app/:appId`) is a **deprecated alias**:
-it resolves by name across all installed apps, lets a first-party builtin win, and returns
-`409 AMBIGUOUS_FUNCTION` when two apps define the same name. Prefer the app-scoped route (the SDK
-emits it automatically once an appId is set — see "Calling a function from your app").
-
-The request body is delivered to the handler as `event.body` (query string as
-`event.query`). A function only runs on its own surface — calling an `admin` function on
-the public endpoint is a `403`. The response is `{ ok: true, result }` on success, or
-`{ error, message }` (HTTP 400) if the handler returned an error. On the **admin surface**
-the response also includes `logs` (your `ctx.log` lines) and `durationMs` for quick
-debugging; the **public surface returns only `result`** (a public caller never sees your
-internal logs). `GET` on either endpoint lists the functions callable on that surface.
+it searches only the collection's **enabled** apps, resolves by name, lets a first-party builtin
+win, and returns `409 AMBIGUOUS_FUNCTION` when two enabled apps define the same name. Prefer the
+app-scoped route (the SDK emits it automatically once an appId is set — see "Calling a function
+from your app").
+
+> **Security note (first-party model, today):** because enablement is not an auth gate, any app's
+> function can be invoked on any collection by id. That's fine while all apps are first-party and
+> trusted. When untrusted third-party apps arrive, gate *elevated* (`public` + `collection`)
+> invocation of a **non-enabled** app behind install/consent — the app-scoped resolver is the seam.
+
+The handler receives the request as `event`: `event.body` (parsed JSON), `event.query`,
+`event.headers`, `event.rawBody` (raw bytes, for XML/form/other inputs), and `event.contentType`.
+A function only runs on its own surface — calling an `admin` function on the public endpoint is a
+`403`. `GET` on either endpoint lists the functions callable on that surface.
+
+**Response contract — your return IS the response (no envelope):**
+- Return a **plain value** → it becomes the JSON body, HTTP `200`. (`SL.functions.call()` gives you
+  that value directly — `res.value`, not `res.result.value`.)
+- Return a web-standard **`Response`** → passed through verbatim: your status, headers, content-type
+  and body (XML, CSV, text, binary, redirect, custom status). `Response` is a runtime global.
+  ```js
+  return new Response(toXml(data), { status: 200, headers: { "content-type": "application/xml" } })
+  ```
+- **Throw** → HTTP `500` `{ error: "FUNCTION_ERROR", message, code }`. For *expected* errors (400/404/
+  409…), return a `Response` with your own status + body.
+
+One rule: **plain object ⇒ 200; want any other status/headers/content-type ⇒ return a `Response`.**
+Timing comes back in an `X-SL-Function-Duration-Ms` header (admin surface); your `ctx.log` lines land
+in the collection's Errors & Activity feed — the body stays purely your output.
 
 The admin surface is collection-admin gated, so an admin function's `caller` authority runs
 at admin level, attributed to the signed-in admin. The public surface resolves auth if a
@@ -412,7 +447,7 @@ So the end-to-end path is: *write → register the release → enable on a colle
 Every invocation is recorded as an **execution** activity event, carrying your `ctx.log`
 lines. Where to look, easiest first:
 
-- **Admin-surface response** — `logs` + `durationMs` come straight back in the JSON.
+- **Admin-surface response** — timing comes back in the `X-SL-Function-Duration-Ms` header (logs are in Errors & Activity, not the body).
 - **Deployed test mode** — see below; real run, isolated logging.
 - **Owner console** — the collection's **Advanced → Errors & Activity → events** tab,
   filtered to **source = execution**: each run shows as `function <name> ok` (or an error),

package/dist/http.d.ts

@@ -52,6 +52,14 @@ export declare function initializeApi(options: {
      * Preserved across re-initialization when not supplied.
      */
     appId?: string;
+    /**
+     * Declares that a bearer token will arrive asynchronously (e.g. handed by the host over
+     * postMessage in a dev/direct embed). Until setBearerToken() is called, outgoing requests wait
+     * rather than firing unauthenticated. Ignored if a bearerToken is already present.
+     */
+    awaitAuth?: boolean;
+    /** How long (ms) to wait for the async token before letting requests proceed anyway. Default 8000. */
+    awaitAuthTimeoutMs?: number;
     iframeAutoResize?: boolean;
     logger?: Logger;
     /**

package/dist/http.js

@@ -52,6 +52,16 @@ let grantToken = undefined;
  * app-scoped when this is set. Explicit `appId` on a call always overrides it.
  */
 let appContextId = undefined;
+/**
+ * Auth-ready gate. When an app declares (initializeApi({ awaitAuth: true })) that its bearer token
+ * will arrive ASYNCHRONOUSLY — e.g. a dev app embedded in the console that receives its token over
+ * postMessage — outgoing requests await this until setBearerToken() is called, so the app's first
+ * calls don't race the token and 401. Resolved by default (no gating); a timeout resolves it anyway
+ * so a token that never arrives can't hang the app forever.
+ */
+let authReady = Promise.resolve();
+let resolveAuthReady = null;
+function ensureAuthReady() { return authReady; }
 /** Whether initializeApi has been successfully called at least once. */
 let initialized = false;
 /** Safely returns the current browser hostname, or an empty string in non-browser / Node environments. */
@@ -481,6 +491,18 @@ export function initializeApi(options) {
         }
     }
     // else: preserve the existing runtime bearerToken.
+    // Open the auth-ready gate when the caller declares a token is coming but none is set yet, so
+    // requests wait for setBearerToken() instead of firing unauthenticated. A timeout releases it.
+    if (options.awaitAuth && !bearerToken && !resolveAuthReady) {
+        authReady = new Promise((res) => {
+            var _a;
+            resolveAuthReady = res;
+            setTimeout(() => { if (resolveAuthReady) {
+                resolveAuthReady = null;
+                res();
+            } }, (_a = options.awaitAuthTimeoutMs) !== null && _a !== void 0 ? _a : 8000);
+        });
+    }
     proxyMode = !!options.proxyMode;
     // Auto-enable ngrok skip header if domain contains .ngrok.io and user did not explicitly set the flag.
     // Infer ngrok usage from common domains (.ngrok.io or .ngrok-free.dev)
@@ -530,6 +552,12 @@ export function setExtraHeaders(headers) {
  * login or logout event.
  */
 export function setBearerToken(token) {
+    // Release any auth-ready gate the moment a real token arrives (even if the value is unchanged),
+    // so requests that were waiting for the async handoff can proceed.
+    if (token && resolveAuthReady) {
+        resolveAuthReady();
+        resolveAuthReady = null;
+    }
     if (token === bearerToken)
         return;
     bearerToken = token;
@@ -1189,6 +1217,7 @@ export async function proxyUploadFormData(path, formData, onProgress) {
  * Node-safe: IndexedDB calls are no-ops when IDB is unavailable.
  */
 export async function request(path) {
+    await ensureAuthReady();
     const skipCache = shouldSkipCache(path);
     const cacheKey = buildCacheKey(path);
     const ttl = skipCache ? 0 : getTtlForPath(path);
@@ -1314,6 +1343,7 @@ export async function request(path) {
  * Returns the parsed JSON as T, or throws an Error.
  */
 export async function post(path, body, extraHeaders) {
+    await ensureAuthReady();
     if (proxyMode) {
         logDebug('[smartlinks] POST via proxy', { path, body: safeBodyPreview(body) });
         const result = await proxyRequest("POST", path, body, extraHeaders);
@@ -1375,6 +1405,7 @@ export async function post(path, body, extraHeaders) {
  * Returns the parsed JSON as T, or throws an Error.
  */
 export async function put(path, body, extraHeaders) {
+    await ensureAuthReady();
     if (proxyMode) {
         logDebug('[smartlinks] PUT via proxy', { path, body: safeBodyPreview(body) });
         const result = await proxyRequest("PUT", path, body, extraHeaders);
@@ -1436,6 +1467,7 @@ export async function put(path, body, extraHeaders) {
  * Returns the parsed JSON as T, or throws an Error.
  */
 export async function patch(path, body, extraHeaders) {
+    await ensureAuthReady();
     if (proxyMode) {
         logDebug('[smartlinks] PATCH via proxy', { path, body: safeBodyPreview(body) });
         const result = await proxyRequest("PATCH", path, body, extraHeaders);
@@ -1648,6 +1680,7 @@ export async function requestStream(path, options) {
  * Returns the parsed JSON as T, or throws an Error.
  */
 export async function del(path, extraHeaders) {
+    await ensureAuthReady();
     if (proxyMode) {
         logDebug('[smartlinks] DELETE via proxy', { path });
         const result = await proxyRequest("DELETE", path, undefined, extraHeaders);

package/dist/iframe.d.ts

@@ -21,6 +21,20 @@ export declare namespace iframe {
     export function disableAutoIframeResize(): void;
     /** Send a custom message to parent (browser-only). */
     export function sendParentCustom(type: string, payload: Record<string, any>): void;
+    /**
+     * Ask the embedding host (parent window) to hand this app a bearer token, for DIRECT (non-proxied)
+     * mode. Posts `{ type: 'smartlinks:request-auth' }` and resolves with the token from the host's
+     * `{ type: 'smartlinks:auth', bearerToken }` reply, or `null` on timeout / when not embedded.
+     *
+     * Use in a first-party/dev embed where the host owns the session and hands it down (the console dev
+     * preview), then feed it to the SDK:
+     *   SL.initializeApi({ baseURL, proxyMode: false, awaitAuth: true })
+     *   SL.iframe.requestParentAuth().then(t => t && SL.setBearerToken(t))
+     * Untrusted third-party embeds should use proxyMode instead (never hold the user's token).
+     */
+    export function requestParentAuth(opts?: {
+        timeoutMs?: number;
+    }): Promise<string | null>;
     /** Returns true if running inside an iframe (browser). */
     export function isIframe(): boolean;
     /** Returns true if ResizeObserver is supported in current environment. */

package/dist/iframe.js

@@ -122,6 +122,49 @@ export var iframe;
         postParentMessage(type, payload);
     }
     iframe.sendParentCustom = sendParentCustom;
+    /**
+     * Ask the embedding host (parent window) to hand this app a bearer token, for DIRECT (non-proxied)
+     * mode. Posts `{ type: 'smartlinks:request-auth' }` and resolves with the token from the host's
+     * `{ type: 'smartlinks:auth', bearerToken }` reply, or `null` on timeout / when not embedded.
+     *
+     * Use in a first-party/dev embed where the host owns the session and hands it down (the console dev
+     * preview), then feed it to the SDK:
+     *   SL.initializeApi({ baseURL, proxyMode: false, awaitAuth: true })
+     *   SL.iframe.requestParentAuth().then(t => t && SL.setBearerToken(t))
+     * Untrusted third-party embeds should use proxyMode instead (never hold the user's token).
+     */
+    function requestParentAuth(opts) {
+        if (!inIframe())
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            var _a;
+            let done = false;
+            const finish = (v) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                try {
+                    window.removeEventListener('message', onMsg);
+                }
+                catch ( /* ignore */_a) { /* ignore */ }
+                resolve(v);
+            };
+            const onMsg = (e) => {
+                const d = e && e.data;
+                if (d && d.type === 'smartlinks:auth' && typeof d.bearerToken === 'string' && d.bearerToken) {
+                    finish(d.bearerToken);
+                }
+            };
+            const timer = setTimeout(() => finish(null), (_a = opts === null || opts === void 0 ? void 0 : opts.timeoutMs) !== null && _a !== void 0 ? _a : 8000);
+            try {
+                window.addEventListener('message', onMsg);
+            }
+            catch ( /* ignore */_b) { /* ignore */ }
+            postParentMessage('smartlinks:request-auth', {});
+        });
+    }
+    iframe.requestParentAuth = requestParentAuth;
     /** Returns true if running inside an iframe (browser). */
     function isIframe() {
         return inIframe();

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { initializeApi, isInitialized, hasAuthCredentials, configureSdkCache, in
 export * from "./api/index.js";
 export * from "./types/index.js";
 export { iframe } from "./iframe.js";
+export { readContext } from "./context.js";
+export type { SmartLinksContext } from "./context.js";
 export type { InvalidateCacheOptions } from "./http.js";
 export * as cache from './cache.js';
 export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';

package/dist/index.js

@@ -5,6 +5,8 @@ export * from "./api/index.js";
 export * from "./types/index.js";
 // Iframe namespace
 export { iframe } from "./iframe.js";
+// App context reader (props → hash → search), for pages and containers alike
+export { readContext } from "./context.js";
 import * as cache_1 from './cache.js';
 export { cache_1 as cache };
 // IframeResponder (also exported via iframe namespace)