@proveanything/smartlinks 2.0.5 → 2.0.9

package/dist/types/segments.d.ts

@@ -95,7 +95,7 @@ export interface SegmentCalculateResult {
     note?: string;
 }
 export interface SegmentRecipientsResponse {
-    items: import('./comms').Recipient[];
+    items: import('./comms.js').Recipient[];
     limit: number;
     offset: number;
     total: number;

package/dist/types/widgets.d.ts

@@ -1,5 +1,5 @@
-import type { TagContext } from './nfc';
-import type { ItemContext } from './itemContext';
+import type { TagContext } from './nfc.js';
+import type { ItemContext } from './itemContext.js';
 /**
  * Structured navigation request emitted via the `onNavigate` prop when a
  * widget or container needs to navigate the parent platform shell to another

package/dist/utils/conditions.d.ts

@@ -1,4 +1,4 @@
-import type { ItemContext } from '../types/itemContext';
+import type { ItemContext } from '../types/itemContext.js';
 /**
  * Geographic region definitions for country-based conditions
  */

package/dist/utils/index.d.ts

@@ -2,6 +2,6 @@
  * Utility functions and helpers for working with smartlinks data.
  * @module utils
  */
-export * from './paths';
-export * from './conditions';
-export * from './anonId';
+export * from './paths.js';
+export * from './conditions.js';
+export * from './anonId.js';

package/dist/utils/index.js

@@ -3,6 +3,6 @@
  * Utility functions and helpers for working with smartlinks data.
  * @module utils
  */
-export * from './paths';
-export * from './conditions';
-export * from './anonId';
+export * from './paths.js';
+export * from './conditions.js';
+export * from './anonId.js';

package/dist/utils/paths.d.ts

@@ -1,7 +1,7 @@
-import type { Product } from '../types/product';
-import type { Collection } from '../types/collection';
-import type { BatchResponse } from '../types/batch';
-import type { Proof } from '../types/proof';
+import type { Product } from '../types/product.js';
+import type { Collection } from '../types/collection.js';
+import type { BatchResponse } from '../types/batch.js';
+import type { Proof } from '../types/proof.js';
 /**
  * Parameters for building a portal path.
  * Pass in objects where available - the function will extract the needed properties.

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.5  |  Generated: 2026-09-20T10:49:16.300Z
+Version: 2.0.9  |  Generated: 2026-09-21T16:23:55.650Z
 
 This is a concise summary of all available API functions and types.
 
@@ -17,15 +17,13 @@ For detailed guides on specific features:
 - **[Containers](containers.md)** - Building full-app embeddable containers (lazy-loaded)
 - **[Mobile Admin Container](mobile-admin-container.md)** - Building mobile-optimised operator/admin containers as a separate bundle
 - **[Container Tracking](container-tracking.md)** - Hierarchical physical/logical container groupings with item membership
-- **[Scanner Containers](scanner-container.md)** - Building scanner microapps for the SmartLinks Scanner Android host (RFID, NFC, QR, key events)
 - **[Multi-Page App Architecture](mpa.md)** - Vite MPA build pipeline: public/admin entry points, widget/container/executor bundles, content-hashed CDN assets
 - **[App Configuration Files](app-manifest.md)** - `app.manifest.json` and `app.admin.json` reference — bundles, components, setup questions, import schemas, tunable fields, and metrics
 - **[Executor Model](executor.md)** - Programmatic JS bundles for AI-driven setup, server-side SEO metadata generation, and LLM content for AI crawlers
 - **[Server Functions](server-functions.md)** - App-authored server-side "edge functions" (`async (ctx, event) => result`): http/event/cron triggers, the visibility/authority/capabilities security model, and the pre-scoped `ctx` (authority-scoped SDK, capability-gated secrets + fetch)
 - **[Deploying & Registering an App](deploying-apps.md)** - Publish → build → register: the app CDN layout (smartlinks.app), dev/beta/prod channels, channel-scoped deploy keys, the `POST /apps/:appId/releases` registration endpoint + validation, and how to wire it into your build so a bad manifest fails the deploy
 - **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
-- **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
-- **[iframe Streaming Parent Changes](iframe-streaming-parent-changes.md)** - Parent-side changes required to support AI streaming in iframe proxy mode
+- **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication (incl. hand-rolled streaming protocol)
 - **[Utilities](utils.md)** - Helper functions for building portal paths, URLs, and common tasks
 - **[UI Utils](ui-utils.md)** - Reusable, themeable admin UI React component library for microapps
 - **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
@@ -63,7 +61,6 @@ For detailed guides on specific features:
 - **[Integrations](integrations.md)** - Inbound/outbound integration flows + the sealed-secret store; triggers (manual/event/schedule), field mappings, and the Syndigo/Event Hub outbound path
 - **[AI Tools & Skills](ai-tools-and-skills.md)** - The AI capability catalog: skills apps invoke by name (e.g. research.brand), the tools the AI reaches for (web fetch/screenshot/brand assets/image gen), the agent loop, and how apps discover them
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
-- **[AI-Native App Manifests](manifests.md)** - How AI workflows discover, configure, and import apps via structured manifests and prose guides
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
 
 ## Choosing App Storage
@@ -220,8 +217,8 @@ Returns true if the SDK currently has any auth credential set (bearer token or A
 }) → `void`
 Configure the SDK's built-in in-memory GET cache. The cache is transparent — it sits inside the HTTP layer and requires no changes to your existing API calls. All GET requests benefit automatically. Per-resource rules (collections/products → 1 h, proofs → 30 s, etc.) override this value. in-memory only (`'none'`, default). Ignored in Node.js. fallback, from the original fetch time (default: 7 days). `SmartlinksOfflineError` with stale data instead of propagating the network error. caches on page load/refresh. IndexedDB persists for offline. ```ts // Enable IndexedDB persistence for offline support configureSdkCache({ persistence: 'indexeddb' }) // Disable cache entirely in test environments configureSdkCache({ enabled: false }) // Keep caches across page refreshes (not recommended for production) configureSdkCache({ clearOnPageLoad: false }) ```
 
-**invalidateCache**(urlPattern?: string) → `void`
-Manually invalidate entries in the SDK's GET cache. *contains* this string is removed. Omit (or pass `undefined`) to wipe the entire cache. ```ts invalidateCache()                     // clear everything invalidateCache('/collection/abc123') // one specific collection invalidateCache('/product/')          // all legacy singular product responses invalidateCache('/products/')         // all canonical plural product responses ```
+**invalidateCache**(urlPattern?: string, options?: InvalidateCacheOptions) → `void`
+Manually invalidate entries in the SDK's GET cache. Note: the GET cache is **in-memory, per page load** (with an optional L2 IndexedDB layer when persistence is enabled) — it does not persist across reloads unless you opt into persistence, so it rarely needs disabling "for correctness". *contains* this string is removed). With `{ exact: true }`, matches the path precisely. Omit to wipe the entire cache. ```ts invalidateCache()                                  // clear everything invalidateCache('/collection/abc123')              // that collection AND everything under it invalidateCache('/collection/abc123', { exact: true }) // ONLY that collection entry invalidateCache('/products/')                      // all canonical plural product responses ```
 
 **proxyUploadFormData**(path: string,
   formData: FormData,
@@ -1841,6 +1838,9 @@ interface AppManifest {
   version: string;
   platformRevision?: string;
   appId: string;
+  moduleFormat?: 'umd' | 'esm' | 'dual';
+  sharedDependencies?: string;
+  globals?: Record<string, string>;
   seo?: {
   strategy?: 'executor' | string;
   priority?: number;

package/docs/agent-tools.md

@@ -0,0 +1,111 @@
+# Agent tools — exposing your app's actions to the SmartLinks agent
+
+> **SmartLinks SDK 2.x.** Redraft of the earlier "Agent Skills & Tools" RFC, now built on
+> [server functions](server-functions.md). **Staged rollout:** the *declaration + discovery* ship in
+> V2 (do them now); the *live agent loop* (a parent chat agent calling your tools) lights up when the
+> platform agent can consume them. Everything you declare is useful before then — a tool is a server
+> function, already invocable via http/event.
+
+## The model: app-authored capabilities
+
+An app declares **capabilities** — app-authored logic the platform runs, each with a declared
+security envelope (`visibility` / `authority` / `capabilities`). There is **one engine** (the
+server-functions runtime) and several **triggers** into it: `http`, `event`, `cron`, and **`agent`**.
+
+**An agent tool is not a new runtime — it's an MCP-shaped facade over a capability.** By default a
+tool *is a server function*: the agent's `tools/call` routes into the same `(ctx, event) => result`
+with the same capability envelope. You author the logic once; the agent is just another caller.
+
+Use a **client tool** (a `postMessage` handler in your live admin iframe) only for genuinely
+UI-coupled actions that must run in the open app. It is **not** the default — headless server
+functions are, because they work whether or not your UI is mounted.
+
+## Declaring a tool
+
+You already declare server functions in `app.manifest.json` (see
+[server-functions.md](server-functions.md)). Mark one **agent-invocable** and give the agent what it
+needs to call it — a description and an input schema:
+
+```jsonc
+{
+  "functions": {
+    "files": { "js": { "umd": "dist/functions.umd.js" } },
+    "definitions": [
+      {
+        "name": "createFaq",
+        "trigger": { "type": "http", "methods": ["POST"] },
+        "visibility": "admin",
+        "authority": "collection",
+        "capabilities": ["sl:records:write"],
+
+        // ── makes it an agent tool ──
+        "agent": {
+          "tool": true,
+          "title": "Create an FAQ entry",
+          "description": "Add a question/answer to this collection's FAQ. Use when the user asks to add or draft an FAQ.",
+          "input": { /* JSON Schema for the arguments the agent supplies as event.body */ },
+          "approval": "auto"        // auto | require  (require = human confirmation before the call)
+        }
+      }
+    ]
+  }
+}
+```
+
+The handler is an ordinary server function — the agent-supplied arguments arrive as `event.body`:
+
+```js
+export async function createFaq(ctx, event) {
+  const { question, answer } = event.body || {}
+  // validate, then act with your declared authority/capabilities:
+  const rec = await ctx.sl.appRecords.create({ recordType: 'faq', data: { question, answer } })
+  return { id: rec.id }
+}
+```
+
+## What the agent sees (MCP shape)
+
+The platform derives an **MCP tool list** from your manifest and drives the standard flow — `tools/list`
+→ `tools/call` → structured result — with streaming, cancellation, and approval layered on. You don't
+implement the wire protocol; you declare tools and write handlers. (The live loop is the staged part.)
+
+## Security
+
+Identical to server functions — nothing new to reason about:
+- **`visibility`** — who may call (admin/public).
+- **`authority`** — whose identity `ctx.sl` carries (`caller` vs `collection`).
+- **`capabilities`** — least-privilege, capped even when elevated.
+- **`agent.approval: "require"`** — the agent must get human confirmation before invoking (use for
+  destructive or public-facing actions).
+
+Untrusted third-party tools run in the platform's isolated runner — the same boundary as untrusted
+server functions.
+
+## Replacing `app.admin.json` AI setup
+
+This supersedes the `app.admin.json` "AI setup" schema-extraction model (the outer agent reading a
+schema and handing back JSON blobs). Instead the app owns its domain logic and exposes **real,
+capability-scoped actions** the agent invokes — with multi-turn and streaming. The AI-schema path is
+**deprecated as of V2** (still works through the V2 line; removed later).
+
+## What ships now vs staged
+
+| Now (V2) | Staged (on the platform agent) |
+|---|---|
+| The `agent` declaration in the manifest | The live agent conversation calling your tools |
+| SDK types for it; tool descriptors surfaced for discovery | `tools/call` streaming, cancellation, cross-app toolbelt arbitration |
+| Your handlers run today via http/event | Human-approval UX for `approval: "require"` |
+
+## Adopting this in an existing app
+
+Do it in order — each step is a drop-in migration prompt (see the migration steps that ship with the
+SDK). Roughly:
+
+1. **Server functions** — add the `functions` block + build target + test harness (if the app
+   doesn't have them). See [server-functions.md](server-functions.md).
+2. **Expose tools** — add the `agent` block to the functions you want the agent to call; give each a
+   title/description/input schema and an approval mode.
+3. **Retire `app.admin.json` AI setup** — move any AI-authoring behaviour to tools; drop the
+   AI-schema block.
+
+Steps 1–2 are safe to ship now; step 3 as you migrate each app off the old AI path.