@proveanything/smartlinks 2.0.6 → 2.0.10

package/dist/docs/iframe-responder.md

@@ -468,3 +468,311 @@ import type {
 ### Portal back exits the app too early
 - Set `state.parentPath` on route changes for screens that should navigate "up" inside the app.
 - Make sure the receiving app listens for `smartlinks-navigate` if the SDK version in use does not already handle it.
+
+---
+
+## Streaming in a hand-rolled parent (without IframeResponder)
+
+The following applies **only if you build your own parent proxy** instead of using the `IframeResponder` class above — which already handles AI streaming for you. It is the wire protocol for forwarding SSE/streaming responses to a child app in proxy mode.
+### Goal
+
+Keep the existing architecture:
+
+- local mode: child calls API directly
+- iframe proxy mode: child never owns auth state and streams through the parent
+
+This keeps user/session authority in the parent while making AI streaming behave like the rest of the SDK transport.
+
+### What changed
+
+Previously, proxy mode only supported one-shot request/response messages:
+
+- `_smartlinksProxyRequest`
+- `_smartlinksProxyResponse`
+
+Streaming now adds a second protocol for long-lived responses:
+
+- `_smartlinksProxyStreamRequest`
+- `_smartlinksProxyStream`
+- `_smartlinksProxyStreamAbort`
+
+### New parent message handling
+
+#### 1. Listen for stream requests
+
+The iframe child may now send this message:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id: string,
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  headers?: Record<string, string>
+}
+```
+
+Parent behavior:
+
+- treat this like a proxied API request
+- build the real API URL from your configured base URL plus `path`
+- send the request using the parent's current auth/session context
+- expect an SSE / streaming response body
+- keep the request open until the stream ends or is aborted
+
+#### 2. Forward stream lifecycle messages back to the child
+
+The parent should send messages back to the iframe using this envelope:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id: string,
+  phase: 'open' | 'event' | 'end' | 'error',
+  data?: any,
+  error?: string,
+  status?: number
+}
+```
+
+Phases:
+
+- `open`
+  - optional but recommended
+  - indicates the upstream streaming request was accepted and a body exists
+- `event`
+  - contains one parsed JSON event from an SSE `data:` frame
+  - send one message per logical event payload
+- `end`
+  - sent once when the stream finishes normally
+- `error`
+  - sent if the upstream request fails before or during streaming
+
+#### 3. Support abort from the child
+
+The child may stop reading early and send:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id: string
+}
+```
+
+Parent behavior:
+
+- look up the active stream by `id`
+- abort the underlying fetch / reader
+- clean up any local state for that stream
+- do not keep streaming after abort
+
+### SSE forwarding rules
+
+The upstream AI endpoints return SSE-like frames. The parent should:
+
+- read the response body as a stream
+- buffer text until line boundaries
+- collect `data:` lines for a single event
+- join multi-line `data:` payloads with `\n`
+- ignore blank events
+- stop on `data: [DONE]`
+- JSON-parse each event payload
+- forward parsed payloads to the iframe as `_smartlinksProxyStream` with `phase: 'event'`
+
+Minimal parsing behavior:
+
+1. accumulate bytes into text
+2. split on `\r?\n`
+3. collect each `data:` line
+4. on blank line, finalize the event
+5. if payload is `[DONE]`, finish
+6. otherwise `JSON.parse(payload)` and forward
+
+### Auth and session expectations
+
+The parent remains the source of truth for auth.
+
+That means the parent stream handler should:
+
+- use the same auth headers/token source as normal proxied requests
+- not require the iframe to know the bearer token or API key
+- naturally pick up the current logged-in user when the stream starts
+- cancel active streams if your app invalidates session state on logout or account switch
+
+In practice, the stream request should use the same header-building logic as your normal parent proxy transport.
+
+### Error handling expectations
+
+If the upstream fetch returns a non-2xx status:
+
+- try to read the JSON error body
+- derive a useful message
+- send one `_smartlinksProxyStream` message with `phase: 'error'`
+- include `status` when available
+- do not send `end` afterward
+
+If the stream body is missing unexpectedly:
+
+- send `phase: 'error'`
+
+If JSON parsing fails for a single event chunk:
+
+- safest behavior is to ignore that malformed chunk and continue
+
+### State the parent should keep
+
+Track active streams in a map keyed by `id`:
+
+```ts
+Map<string, AbortController>
+```
+
+Recommended cleanup points:
+
+- on normal stream end
+- on error
+- on child abort
+- on iframe detach/unmount
+- on parent auth reset/logout if you want all in-flight streams cancelled immediately
+
+### Parent implementation outline
+
+```ts
+const activeStreams = new Map<string, AbortController>()
+
+window.addEventListener('message', async (event) => {
+  const msg = event.data
+
+  if (msg?._smartlinksProxyStreamAbort && msg.id) {
+    activeStreams.get(msg.id)?.abort()
+    activeStreams.delete(msg.id)
+    return
+  }
+
+  if (msg?._smartlinksProxyStreamRequest && msg.id) {
+    const controller = new AbortController()
+    activeStreams.set(msg.id, controller)
+
+    try {
+      const response = await fetch(buildUrl(msg.path), {
+        method: msg.method,
+        headers: msg.headers,
+        body: msg.body ? JSON.stringify(msg.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!response.ok || !response.body) {
+        postError(...)
+        return
+      }
+
+      postOpen(...)
+      await forwardSse(response.body, parsed => postEvent(...parsed))
+      postEnd(...)
+    } catch (err) {
+      if (err?.name !== 'AbortError') postError(...)
+    } finally {
+      activeStreams.delete(msg.id)
+    }
+  }
+})
+```
+
+### Exact protocol summary
+
+#### Child → parent
+
+Standard stream request:
+
+```ts
+{
+  _smartlinksProxyStreamRequest: true,
+  id,
+  method,
+  path,
+  body,
+  headers
+}
+```
+
+Abort request:
+
+```ts
+{
+  _smartlinksProxyStreamAbort: true,
+  id
+}
+```
+
+#### Parent → child
+
+Open:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'open'
+}
+```
+
+Event:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'event',
+  data: parsedJsonEvent
+}
+```
+
+End:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'end'
+}
+```
+
+Error:
+
+```ts
+{
+  _smartlinksProxyStream: true,
+  id,
+  phase: 'error',
+  error: 'message',
+  status?: number
+}
+```
+
+### What does not change
+
+These parts of the parent iframe integration stay the same:
+
+- normal `_smartlinksProxyRequest` request/response flow
+- upload proxy flow
+- auth login/logout postMessage handling
+- route/deep-link handling
+- resize handling
+
+This is an additive protocol, not a replacement.
+
+### Current SDK reference
+
+The SDK implementation lives in:
+
+- [src/http.ts](src/http.ts)
+- [src/iframeResponder.ts](src/iframeResponder.ts)
+- [src/types/iframeResponder.ts](src/types/iframeResponder.ts)
+- [src/api/ai.ts](src/api/ai.ts)
+
+### Practical recommendation
+
+If your parent already uses `IframeResponder`, prefer upgrading to the SDK version with these changes instead of re-implementing the protocol manually.
+
+If your parent has a custom iframe bridge, implement exactly the three new message types above and reuse your existing auth/header logic from normal proxied requests.

package/dist/docs/item-context.md

@@ -1,7 +1,5 @@
 # Item Context (container prop)
 
-> **Copy this file into `node_modules/@proveanything/smartlinks/docs/item-context.md`** in the published SDK package.
-
 When the URL points at a specific item — either a **serial proof URL** or an
 **NFC tap** — the portal derives an `ItemContext` describing what it found
 and hands it to the container as the **`itemContext`** prop.

package/dist/docs/manifests.md

@@ -32,7 +32,7 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
     "instanceResolution": true,
     "instanceParam": "widgetId",
     "files": {
-      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.es.js" },
+      "js": { "umd": "dist/widgets.umd.js", "esm": "dist/widgets.esm.js" },
       "css": null
     },
     "components": [
@@ -46,13 +46,13 @@ app.admin.json      ←  loaded on-demand (setup wizards, import, AI config flow
   },
   "containers": {
     "files": {
-      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" },
+      "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" },
       "css": null
     },
     "components": [{ "name": "PublicContainer", "description": "Full app view." }]
   },
   "executor": {
-    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.es.js" } },
+    "files": { "js": { "umd": "dist/executor.umd.js", "esm": "dist/executor.esm.js" } },
     "factory": "createMyAppExecutor",
     "exports": ["createMyAppExecutor", "getSEO", "getLLMContent"],
     "description": "Programmatic configuration and SEO API for My App."

package/dist/docs/mobile-admin-container.md

@@ -1,6 +1,6 @@
 # Mobile Admin Container SDK
 
-> **Version:** 1.0 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.0 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 This document describes how to build a **Mobile Admin Container** — a SmartLinks microapp that provides an in-the-field operator/admin surface optimised for mobile devices. These containers ship as a **separate `mobileAdmin` bundle** (not inside the `containers` bundle) so that Capacitor plugins, offline helpers, and operator-only code never reach the public consumer bundle.
 
@@ -271,7 +271,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
   "meta": { "appId": "my-app", "name": "My App", "version": "1.0.0" },
 
   "containers": {
-    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.es.js" }, "css": "dist/containers.css" },
+    "files": { "js": { "umd": "dist/containers.umd.js", "esm": "dist/containers.esm.js" }, "css": "dist/containers.css" },
     "components": [
       { "name": "PublicContainer", "description": "Default consumer experience" }
     ]
@@ -281,7 +281,7 @@ Declare the bundle under the top-level `mobileAdmin` key in `app.manifest.json`.
     "files": {
       "js": {
         "umd": "dist/mobile-admin.umd.js",
-        "esm": "dist/mobile-admin.es.js"
+        "esm": "dist/mobile-admin.esm.js"
       },
       "css": null
     },
@@ -416,7 +416,7 @@ The mobile admin bundle has its own Vite config: `vite.config.mobile-admin.ts`.
 
 ```
 dist/mobile-admin.umd.js
-dist/mobile-admin.es.js
+dist/mobile-admin.esm.js
 dist/mobile-admin.css    (if needed)
 ```
 

package/dist/docs/mpa.md

@@ -56,9 +56,9 @@ vite build
 | Step | Config / Script | Gate env var | Output |
 |------|----------------|-------------|--------|
 | 1 | `vite.config.ts` | Always runs | `index.html`, `admin.html`, `assets/*` |
-| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.es.js`, `widgets.css` |
-| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.es.js`, `containers.css` |
-| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.es.js` |
+| 2 | `vite.config.widget.ts` | `VITE_ENABLE_WIDGETS=true` | `widgets.umd.js`, `widgets.esm.js`, `widgets.css` |
+| 3 | `vite.config.container.ts` | `VITE_ENABLE_CONTAINERS=true` | `containers.umd.js`, `containers.esm.js`, `containers.css` |
+| 4 | `vite.config.executor.ts` | `VITE_ENABLE_EXECUTOR!=false` | `executor.umd.js`, `executor.esm.js` |
 | 5 | `scripts/hash-bundles.mjs` | Always runs | Renames bundles with content hashes; patches `dist/app.manifest.json` |
 
 Steps 2–4 produce a harmless stub file when their gate env var is not set. Step 5 detects and skips stub files automatically.
@@ -107,7 +107,7 @@ dist/
 └── executor-[hash].es.js           ← Executor bundle (ESM)
 ```
 
-> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [AI-Native App Manifests](manifests.md) guide for the CSS null warning.
+> Widget and container CSS files are only present when the bundle ships custom styles. Most apps set `"css": null` in the manifest because they rely entirely on Tailwind/shadcn from the parent. See the [App Configuration Files](app-manifest.md) for the CSS null warning.
 
 ---
 
@@ -133,6 +133,6 @@ If the embedded app exposes nested screens, document its "up" navigation path wi
 | [Widgets](widgets.md) | Widget bundle: components, props, settings |
 | [Containers](containers.md) | Container bundle: full-app embeds |
 | [Executor Model](executor.md) | Executor bundle: SEO, LLM content, config mutations |
-| [AI-Native App Manifests](manifests.md) | How manifests wire all bundles together for AI discovery |
+| [App Configuration Files](app-manifest.md) | Manifest + admin reference; widget settings schema; AI workflows |
 | [iframe Responder](iframe-responder.md) | Reading context params inside the iframe |
 | [Portal Back Button](portal-back-button.md) | Hierarchy-aware back navigation for embedded apps |

package/dist/docs/native-facade.md

@@ -1,6 +1,6 @@
 # Native Capability Facade (`host.native` / `SL.native`)
 
-> **Version:** 1.12 · **Platform:** SmartLinks R4 · **Last updated:** 2026-04-30
+> **Version:** 1.12 · **Platform:** SmartLinks R5 · **Last updated:** 2026-09-21
 
 The `NativeFacade` is a thin contract layer between microapps and the device capabilities available on the current host shell (Kotlin, Capacitor iOS/Android, PWA, or browser). It lets a microapp call `host.native.share.share({...})` without knowing whether it's running over `window.SmartlinksScanner`, a Capacitor plugin, or `navigator.share`.
 

package/dist/docs/overview.md

@@ -1,25 +1,21 @@
 # SmartLinks Microapp Development Guide
 
-> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` (current `latest`, 2.0.5) · React 19 · Vite 8 · Tailwind 4  
-> **Last updated:** 2026-03-03
+> **Platform revision:** R5 · **SDK:** `@proveanything/smartlinks@^2` · React 19 · Vite 8 · Router 7 · Tailwind 4 · TS 6.
+> The canonical version/host stack lives in [host-dependency-contract.md](host-dependency-contract.md).
 
 ---
 
 ## What Is a SmartLinks Microapp?
 
-SmartLinks microapps are **modular, embeddable React applications** that extend the SmartLinks digital twin platform. They provide specialised functionality — product information displays, warranty registration, competitions, pamphlet generators, and more — while inheriting context, authentication, and theming from the parent platform.
+SmartLinks connects **physical products to digital experiences**: each item has a digital identity — a **proof** — that a consumer reaches by scanning a QR / NFC tag, then claims and enriches over time. A **microapp** is a focused, embeddable React experience a brand adds to that product's digital life: product info, warranty registration, authenticity checks, manuals, competitions, loyalty, post-purchase support, and more.
 
-### The Digital Twin Ecosystem
+Rather than baking every feature into the core platform, functionality is distributed across purpose-built apps, so a brand adds exactly the experiences its product needs. Each app:
 
-SmartLinks is a **digital twin platform** that connects physical products to digital experiences. Each physical item (a wine bottle, a luxury handbag, a piece of equipment) has a corresponding digital identity — a "proof" — that can be scanned, claimed, and enriched with data over time.
-
-Microapps are the **extensibility layer** of this ecosystem. Rather than building monolithic features into the core platform, functionality is distributed across purpose-built apps that:
-
-- **Embed seamlessly** via iframes in the SmartLinks Portal (public) and Admin Console (management)
-- **Share context** through URL parameters (collection, product, or proof being viewed)
-- **Inherit identity** from the parent platform's authentication system
-- **Adapt visually** to the brand's theme configuration
-- **Communicate bidirectionally** with the parent via postMessage for deep linking and navigation
+- **Embeds** in the SmartLinks Portal (public) and Admin Console (management)
+- **Shares context** through URL parameters (collection, product, proof)
+- **Inherits identity** from the parent platform's auth
+- **Adapts** to the brand's theme
+- **Communicates** with the parent via postMessage for deep linking and navigation
 
 ### Deployment Modes
 
@@ -45,7 +41,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 
 > Product endpoints: use `products` (plural) for new integrations. The older `product` (singular) namespace remains for backward compatibility and is deprecated.
 
-> **Minimum SDK version: `1.4.1`** — Ensure `@proveanything/smartlinks` is at least this version. If not, update with `npm install @proveanything/smartlinks@latest`.
+> **SDK baseline: `@proveanything/smartlinks@^2.0`** (R5). Install/update with `npm install @proveanything/smartlinks@^2.0`. Individual features may need a higher minor — see the relevant doc. The single source of truth for the R5 host/version stack is [`host-dependency-contract.md`](host-dependency-contract.md).
 
 | Topic | File | When to Use |
 |-------|------|-------------|
@@ -64,14 +60,13 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Mobile Admin Container** | `docs/mobile-admin-container.md` | Building a separate Capacitor-aware mobile admin bundle for field operators |
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Server Functions** | `docs/server-functions.md` | App-authored server-side functions `(ctx, event) ⇒ result`: security model, runtime surface, invoking |
-| **Agent Tools** | `docs/agent-tools.md` | Exposing your app's actions to the SmartLinks agent — an MCP facade over server functions; declare now, live loop staged; replaces `app.admin.json` AI setup |
+| **Agent Tools** | `docs/agent-tools.md` | Exposing your app's actions to the SmartLinks agent — an MCP facade over server functions; **opt-in per app, additive, no migration**; complements `app.admin.json` (functions serve/adapt it, don't replace it); live loop staged |
 | **Deploying & Registering** | `docs/deploying-apps.md` | Getting your app into the platform: fast dev publish, channels, deploy keys, registering releases |
 | **Host Dependency Contract (R5)** | `docs/host-dependency-contract.md` | The libraries the host provides (React 19, Router 7, Radix, liquidjs, …), the externalise-don't-bundle rule + Vite config, and React-18 backwards-compat |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
 | **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
-| **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
 | **Real-time Messaging** | `docs/realtime.md` | Adding Ably real-time features (chat, live updates) |
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
@@ -89,6 +84,21 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Proof Share Grants** | `docs/proof-share-grants.md` | Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner) |
 | **Proof Ownership Transfer** | `docs/proof-ownership-transfer.md` | Moving a proof's single owner (directed transfer / open release), accept/cancel, and the state machine |
 | **appConfig / Feature Flags** | `docs/appConfig.md` | `appConfig` settings contract — installed apps, `system.features`/`entitledAppGroups`/`meters`, `isFeatureEnabled()` helper |
+| **App Objects** | `docs/app-objects.md` | Queryable domain objects — `app.records` / `app.cases` / `app.threads`: JSONB zones, visibility, policies, aggregations |
+| **App Data Storage** | `docs/app-data-storage.md` | Decision guide: pick between `appConfiguration` / `userAppData` / `app.records` |
+| **Attestations** | `docs/attestations.md` | Postgres attestations API (proof-level user/admin data; replaces the legacy Firestore path) |
+| **Caching** | `docs/caching.md` | SDK GET cache tiers + TTLs, `invalidateCache({ exact })`, and `force`/push guidance |
+| **Comms & Broadcasts** | `docs/comms.md` | Transactional comms, campaigns, consent, push |
+| **Container Tracking** | `docs/container-tracking.md` | Physical/logical **item** container groupings — *not* app containers (see containers.md) |
+| **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
+| **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
+| **Sequences** | `docs/sequences.md` | Atomic monotonic number allocation (raffle / queue / edition) |
+| **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
+| **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
+| **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |
+| **AI Tools & Skills** | `docs/ai-tools-and-skills.md` | Platform AI capability registry (web research, extraction, images) |
+| **Proof Comms Triggers** | `docs/proof-comms-triggers.md` | Transactional comms fired as a side-effect of proof actions |
 
 ---
 
@@ -99,6 +109,15 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 - **Context via URL params** — All contextual data is passed through URL parameters
 - **SmartLinks NPM module** — All data access and platform interaction goes through `@proveanything/smartlinks`
 - **No standalone auth** — Authentication is handled by the parent SmartLinks platform
+
+> **Use the host-provided `SL`, don't instantiate your own.** When your app runs in a
+> container/iframe, the host injects an already-initialized, authenticated SDK instance (the
+> `SL` prop / the externalized `@proveanything/smartlinks` singleton). Import and use *that*.
+> Calling `initializeApi()` yourself to spin up a **second** SDK instance is a common source
+> of bugs: it won't share the host's auth (so it looks signed-out), won't share the host's
+> cache (duplicate requests, stale data), and in proxy mode it bypasses the host's request
+> routing. Rule of thumb: **host-provided `SL` for anything the platform owns** (auth, config,
+> data, cache); only app-owned state is yours.
 - **Multi-page build** — Separate bundles for public and admin — see `docs/mpa.md`
 - **Embedded back navigation** — Use `docs/portal-back-button.md` when a sub-app has a real content hierarchy
 

package/dist/docs/portal-back-button.md

@@ -1,8 +1,7 @@
 # Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
-> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
-> microapp authors discover it.
+> **For sub-app authors.** How to cooperate with the portal shell's top-level
+> back/up control. See also [`mpa.md`](mpa.md).
 
 When a sub-app is embedded by a portal shell, the shell renders a top-level
 back button. By default that button **exits the app entirely** when tapped —