@proveanything/smartlinks 2.0.21 → 2.0.24

package/dist/openapi.yaml

@@ -18255,6 +18255,11 @@ components:
           type: array
           items:
             type: string
+        dataScope:
+          type: string
+          enum:
+            - collection
+            - global
         apiVersion:
           type: string
         handler:
@@ -18274,6 +18279,41 @@ components:
       required:
         - files
         - definitions
+    AppDataOpts:
+      type: object
+      properties:
+        scope:
+          type: string
+          enum:
+            - collection
+            - global
+        productId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        dataId:
+          type: string
+        queries:
+          type: object
+          additionalProperties: true
+    AppDataHandle:
+      type: object
+      properties: {}
+    ServerFunctionSl:
+      type: object
+      properties:
+        appRecords: {}
+        products: {}
+        attestations: {}
+        appData:
+          $ref: "#/components/schemas/AppDataHandle"
+      required:
+        - appRecords
+        - products
+        - attestations
+        - appData
     ServerFunctionCaller:
       type: object
       properties:
@@ -18298,7 +18338,8 @@ components:
           type: string
         appId:
           type: string
-        sl: {}
+        sl:
+          $ref: "#/components/schemas/ServerFunctionSl"
         secrets:
           type: object
           additionalProperties: true
@@ -18314,6 +18355,30 @@ components:
         - secrets
         - caller
         - fetch
+    ServerFunctionHttpEvent:
+      type: object
+      properties:
+        method:
+          type: string
+        body:
+          type: object
+          additionalProperties: true
+        query:
+          type: object
+          additionalProperties: true
+        headers:
+          type: object
+          additionalProperties: true
+        rawBody:
+          type: object
+          additionalProperties: true
+        contentType:
+          type: string
+      required:
+        - method
+        - body
+        - query
+        - headers
     AppAdminConfig:
       type: object
       properties:
@@ -18397,6 +18462,40 @@ components:
         - scope
         - name
         - type
+    PublicViewParams:
+      type: object
+      properties:
+        required:
+          type: array
+          items:
+            type: string
+        optional:
+          type: array
+          items:
+            type: string
+    PublicView:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        kind:
+          $ref: "#/components/schemas/PublicViewKind"
+        route:
+          type: string
+        set:
+          type: object
+          additionalProperties:
+            type: string
+        params:
+          $ref: "#/components/schemas/PublicViewParams"
+        default:
+          type: boolean
+      required:
+        - id
+        - title
+        - kind
     AppManifest:
       type: object
       properties:
@@ -18472,6 +18571,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/DeepLinkEntry"
+        publicViews:
+          type: array
+          items:
+            $ref: "#/components/schemas/PublicView"
         executor:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
@@ -18532,6 +18635,11 @@ components:
       enum:
         - caller
         - collection
+    PublicViewKind:
+      type: string
+      enum:
+        - contextual
+        - standalone
     PaginatedResponse:
       type: object
       properties:
@@ -29290,7 +29398,8 @@ components:
       type: object
       properties:
         appId:
-          type: string
+          type: object
+          additionalProperties: true
     AllocateSequenceInput:
       type: object
       properties:

package/dist/testing/index.d.ts

@@ -24,6 +24,25 @@ export interface TestSlImpl {
     attestations?: {
         create?(fields: any): any;
     };
+    /**
+     * THIS app's own data. Provide impls to assert calls, or omit to use a built-in in-memory store
+     * (so a counter test actually persists across calls within the test). `.global`/`.collection` and
+     * per-call `{ scope }` share the same store in the harness.
+     */
+    appData?: {
+        get?(opts?: any): any;
+        set?(data: any, opts?: any): any;
+        getData?(opts?: any): any;
+        setData?(data: any, opts?: any): any;
+        delete?(opts?: any): any;
+    };
+    /** Cross-app reads: return another app's data as the caller would see it. Keyed by appId. */
+    app?: (appId: string) => {
+        data?: {
+            get?(opts?: any): any;
+            getData?(opts?: any): any;
+        };
+    };
 }
 export interface TestCaller {
     userId?: string | null;

package/dist/testing/index.js

@@ -102,6 +102,36 @@ export function createFunctionTestContext(opts) {
             create: gated('attestations', 'write', at.create && at.create.bind(at), 'create'),
         },
     };
+    // appData — own-data (capability-gated only, no role gate). Delegates to a provided impl, else a
+    // built-in in-memory store so read-modify-write (e.g. a counter) works across calls in one test.
+    const ad = impl.appData || {};
+    const memConfig = {};
+    const memData = {};
+    const deepMerge = (t, s) => { for (const k of Object.keys(s || {}))
+        t[k] = (s[k] && typeof s[k] === 'object' && !Array.isArray(s[k])) ? deepMerge(t[k] || {}, s[k]) : s[k]; return t; };
+    const makeAppData = () => ({
+        get: gated('data', 'read', ad.get ? ad.get.bind(ad) : (async () => (Object.assign({}, memConfig))), 'get'),
+        set: gated('data', 'write', ad.set ? ad.set.bind(ad) : (async (data) => deepMerge(memConfig, data)), 'set'),
+        getData: gated('data', 'read', ad.getData ? ad.getData.bind(ad) : (async (opts = {}) => (opts.dataId ? memData[opts.dataId] : Object.values(memData))), 'getData'),
+        setData: gated('data', 'write', ad.setData ? ad.setData.bind(ad) : (async (data, opts = {}) => { if (opts.dataId)
+            memData[opts.dataId] = data; return data; }), 'setData'),
+        delete: gated('data', 'write', ad.delete ? ad.delete.bind(ad) : (async (opts = {}) => { if (opts.dataId)
+            delete memData[opts.dataId];
+        else
+            for (const k of Object.keys(memConfig))
+                delete memConfig[k]; }), 'delete'),
+    });
+    sl.appData = Object.assign(makeAppData(), { global: makeAppData(), collection: makeAppData() });
+    sl.app = (appId) => {
+        const other = (impl.app && impl.app(appId)) || {};
+        const od = other.data || {};
+        return {
+            data: {
+                get: gated('data', 'read', od.get ? od.get.bind(od) : (async () => null), 'app.get'),
+                getData: gated('data', 'read', od.getData ? od.getData.bind(od) : (async () => []), 'app.getData'),
+            },
+        };
+    };
     const secretsMap = opts.secrets || {};
     const baseFetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : undefined);
     const via = (def.trigger && def.trigger.type) || 'http';

package/dist/types/appManifest.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+/// <reference types="node" />
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -258,6 +260,13 @@ export interface AppFunctionDef {
      * Grammar: `sl:<resource>:<read|write>`, `network` (or `network:<host>`), `secrets:<ref>`.
      */
     capabilities?: string[];
+    /**
+     * Default scope for `ctx.sl.appData.*` — `'collection'` (this collection; the default) or
+     * `'global'` (the app's app-wide bucket, shared by every collection that installed it). A function
+     * whose data is global-by-intent declares `'global'` and then just uses `appData.get()/set()`.
+     * Per-call `{ scope }` and the `appData.global` / `appData.collection` handles override this.
+     */
+    dataScope?: 'collection' | 'global';
     /** SDK/manifest API version this function targets (pinned for runtime compatibility). */
     apiVersion?: string;
     /** Exported handler name in the functions bundle. Defaults to `name`. */
@@ -268,6 +277,57 @@ export interface AppManifestFunctions {
     files: AppManifestFiles;
     definitions: AppFunctionDef[];
 }
+/** Scope + selector options for `ctx.sl.appData.*`. */
+export interface AppDataOpts {
+    /** `'collection'` (this collection) or `'global'` (the app's app-wide bucket). Defaults to the function's `dataScope`. */
+    scope?: 'collection' | 'global';
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    /** For `getData`/`setData`/`delete`: the keyed data item id. */
+    dataId?: string;
+    queries?: Record<string, any>;
+}
+/** Read/write handle for an app's own durable data. `set` deep-merges the singleton config blob. */
+export 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>;
+}
+/**
+ * The capability-gated SmartLinks surface handed to a server function. Two access modes:
+ *  - by APP identity — `appData` / `appRecords` are THIS app's OWN data (any scope), gated by the
+ *    declared capability only (the caller's role is irrelevant — it's the app's own namespace).
+ *  - by CALLER identity — everything else (products, attestations, and `app(id)` cross-app reads)
+ *    is bounded by what the invoking user could do through the permissioned API.
+ */
+export interface ServerFunctionSl {
+    /** THIS app's records (own namespace). */
+    appRecords: any;
+    /** Products, scoped by caller authority + declared capability. */
+    products: any;
+    /** Attestations, scoped by caller authority + declared capability. */
+    attestations: any;
+    /**
+     * THIS app's durable data/config. Default scope follows the function's declared `dataScope`
+     * (else `collection`). `appData.global` / `appData.collection` force a scope regardless.
+     * Own-data access is gated by `sl:data:read` / `sl:data:write` only.
+     */
+    appData: AppDataHandle & {
+        global: AppDataHandle;
+        collection: AppDataHandle;
+    };
+    /**
+     * Read ANOTHER app's data in this collection, by CALLER identity — only what the invoking user
+     * could read (admin sees all; otherwise public-filtered, private fields stripped). Read-only;
+     * never another app's private/global store, never another collection. Gated by `sl:data:read`.
+     */
+    app(appId: string): {
+        data: Pick<AppDataHandle, 'get' | 'getData'>;
+    };
+}
 /** Identity of whoever invoked a server function. */
 export interface ServerFunctionCaller {
     /** Authenticated user id, or `null` for anonymous/public/system invocations. */
@@ -297,7 +357,7 @@ export interface ServerFunctionContext {
      *                   only — never a global superuser.
      * Declared `capabilities` cap what these calls may do.
      */
-    sl: any;
+    sl: ServerFunctionSl;
     /**
      * Capability-gated secret access (both require the `secrets:<ref>` capability).
      * `get(ref)` resolves the collection's OWN secret first (a client's credential), then falls back
@@ -315,7 +375,29 @@ export interface ServerFunctionContext {
     /** Structured logging captured into run telemetry. */
     log: (message: string, data?: Record<string, any>) => void;
 }
-/** The signature every SmartLinks server function implements. */
+/** The HTTP request handed to an `http`-trigger function as `event`. */
+export interface ServerFunctionHttpEvent<TBody = any> {
+    method: string;
+    /** Parsed JSON body (when the request was JSON). */
+    body: TBody;
+    query: Record<string, any>;
+    /** Raw request headers (lower-cased keys). */
+    headers: Record<string, any>;
+    /** Raw request body bytes, when captured — for non-JSON inputs (XML, form, …). */
+    rawBody?: string | Buffer | null;
+    /** The request `content-type`, if any. */
+    contentType?: string | null;
+}
+/**
+ * The signature every SmartLinks server function implements.
+ *
+ * RETURN CONTRACT (http trigger): whatever you return **is** the HTTP response.
+ *  - a plain value → JSON body, HTTP 200 (no `{ ok, result }` envelope);
+ *  - a web-standard `Response` → passed through verbatim (your status, headers, content-type, body —
+ *    XML, CSV, binary, redirect, custom status);
+ *  - throwing → HTTP 500 `{ error, message, code }`. For expected errors, return a `Response` with
+ *    your own 4xx/5xx.
+ */
 export type ServerFunctionHandler<TEvent = any, TResult = any> = (ctx: ServerFunctionContext, event: TEvent) => Promise<TResult> | TResult;
 /**
  * Shape of `app.admin.json` -- the separate admin configuration file pointed to
@@ -403,6 +485,41 @@ export interface AppAdminConfig {
  * Setup, import, tunable, and metrics configuration lives in a separate
  * `app.admin.json` file. Use the `admin` field to locate and fetch it.
  */
+/** A public view's kind: context-aware (tag-tap) vs a full-screen, non-contextual screen. */
+export type PublicViewKind = 'contextual' | 'standalone';
+/** The caller-supplied params a public view expects. */
+export interface PublicViewParams {
+    /** Params the view REQUIRES to render (e.g. `['collectionId','pageId']`). */
+    required?: string[];
+    /** Params the view can use if present (e.g. `['productId','proofId','orientation']`). */
+    optional?: string[];
+}
+/**
+ * A declared PUBLIC VIEW of the app — one soft-routed entry over the single public bundle
+ * (`index.html` → HashRouter), so the platform + Dev Hub can enumerate and target it instead of
+ * guessing at undeclared hash routes. A view is `route` + fixed params (`set`) + caller `params` +
+ * a `kind`. It is a DELIVERY-agnostic description: the same view renders as a `page` (standalone
+ * HTML, hash-routed, its own CSS — embed in an iframe or open directly) or, for a `contextual` view,
+ * as a `component` (PublicContainer, props context). NOT a separate build. See
+ * docs/design/public-views.md. (Distinct from `linkable`/DeepLinkEntry, which is deep-link
+ * discovery; publicViews is the top-level public-entry taxonomy used for preview + tag-tap routing.)
+ */
+export interface PublicView {
+    /** Stable id, unique within the app. */
+    id: string;
+    /** Human label (Dev Hub dropdown, platform pickers). */
+    title: string;
+    /** `contextual` (context-aware, tag-tap target) or `standalone` (full-screen display/kiosk). */
+    kind: PublicViewKind;
+    /** Hash route within the public bundle. Defaults to `/`. */
+    route?: string;
+    /** Query params this view PINS (e.g. `{ tvMode: 'true' }`), merged under the caller's params. */
+    set?: Record<string, string>;
+    /** The params the caller supplies. */
+    params?: PublicViewParams;
+    /** The default `contextual` view — the tag-tap target. At most one view sets this. */
+    default?: boolean;
+}
 export interface AppManifest {
     $schema?: string;
     meta?: {
@@ -491,6 +608,14 @@ export interface AppManifest {
      * @see DeepLinkEntry
      */
     linkable?: DeepLinkEntry[];
+    /**
+     * The app's PUBLIC VIEWS — the soft-routed entries over the single public bundle
+     * (contextual page, display board, kiosk/TV, …), so the platform + Dev Hub can enumerate,
+     * preview, and target them. Declares `route` + fixed `set` params + caller `params` + `kind`
+     * per view; the `default` contextual view is the tag-tap target. See PublicView +
+     * docs/design/public-views.md.
+     */
+    publicViews?: PublicView[];
     /**
      * Executor bundle declaration. Present when the app ships a programmatic executor
      * for AI-driven configuration, server-side SEO, and LLM content generation.

package/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/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.