@proveanything/smartlinks 2.0.38 → 2.0.39

package/dist/api/functions.d.ts

@@ -62,7 +62,7 @@ export declare namespace functions {
     }): string;
     /**
      * Call a PUBLIC app server function inline (surface `'public'`).
-     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
+     * App-scoped: `POST /fn/public/collection/:c/app/:appId/functions/:name`.
      *
      * @example
      * // App calling its own function (appId from initializeApi({ appId })):
@@ -73,7 +73,7 @@ export declare namespace functions {
     function call<T = FunctionCallResult>(collectionId: string, name: string, body?: Record<string, any>, opts?: FunctionCallOptions): Promise<T>;
     /**
      * Call an ADMIN app server function (surface `'admin'`; requires an admin session).
-     * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+     * App-scoped: `POST /fn/admin/collection/:c/app/:appId/functions/:name`.
      */
     function callAdmin<T = FunctionCallResult>(collectionId: string, name: string, body?: Record<string, any>, opts?: FunctionCallOptions): Promise<T>;
     /**

package/dist/api/functions.js

@@ -14,6 +14,10 @@
 // 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.
 //
+// PREFIX. App-scoped calls go to /fn/{public|admin}/collection/…/functions/… (under the API base,
+// so /api/v1/fn/…): one prefix for all function traffic, which the platform can route to its own
+// service. The same call without /fn still works (older SDKs). The flat alias has no /fn form.
+//
 // RELEASE CHANNEL. The channel is part of the URL — /collection/:c/app/:appId/<channel>/functions/:name
 // — never a query param (the function owns its query string, and a configured URL such as a webhook
 // can only ever hit the channel it names). With NO channel the server runs the release the collection
@@ -55,7 +59,7 @@ function appBase(surface, collectionId, opts) {
     if (!app)
         return `/${surface}/collection/${c}`; // deprecated flat alias — resolves installed apps only
     const ch = resolveFunctionChannel(opts, app);
-    return `/${surface}/collection/${c}/app/${encodeURIComponent(app)}${ch ? `/${ch}` : ''}`;
+    return `/fn/${surface}/collection/${c}/app/${encodeURIComponent(app)}${ch ? `/${ch}` : ''}`;
 }
 /** The API path a function call goes to (exported for hosts/tests that need the exact URL). */
 export function functionPath(surface, collectionId, name, opts = {}) {
@@ -94,7 +98,7 @@ export var functions;
     functions.siteUrl = siteUrl;
     /**
      * Call a PUBLIC app server function inline (surface `'public'`).
-     * App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`.
+     * App-scoped: `POST /fn/public/collection/:c/app/:appId/functions/:name`.
      *
      * @example
      * // App calling its own function (appId from initializeApi({ appId })):
@@ -108,7 +112,7 @@ export var functions;
     functions.call = call;
     /**
      * Call an ADMIN app server function (surface `'admin'`; requires an admin session).
-     * App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+     * App-scoped: `POST /fn/admin/collection/:c/app/:appId/functions/:name`.
      */
     async function callAdmin(collectionId, name, body = {}, opts = {}) {
         return post(fnPath('admin', collectionId, name, opts), body);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.38  |  Generated: 2026-10-05T12:10:36.598Z
+Version: 2.0.39  |  Generated: 2026-10-05T14:14:46.558Z
 
 This is a concise summary of all available API functions and types.
 
@@ -26,6 +26,12 @@ For detailed guides on specific features:
 - **[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
+- **[Headless Providers](headless-providers.md)** - Declaring an app's content for other sites: the manifest `data` + `headless` blocks (types, storage, public fields, examples, read recipes, categories), `SL.headless.validate`, `smartlinks-headless`, and the procedure for adding a headless mode
+- **[Websites: SEO + GEO](site-seo.md)** - For apps served as websites: platform-generated robots/sitemap/llms.txt, canonical addresses, `SL.seo.head` / `SL.seo.jsonLd` / `SL.seo.schema.*`, `SL.site.ready()`, routes in `sitemap-paths.txt`
+- **[Agent Tools](agent-tools.md)** - Exposing app functions as AI agent tools
+- **[Host Dependency Contract](host-dependency-contract.md)** - The shared dependencies (React, the SDK…) the host provides, and what an app must externalise
+- **[Theme Tokens](theme-tokens.md)** - The `--sl-*` semantic token contract hosts set and apps bind to (`theme.css`)
+- **[CSS Baseline](css-baseline.md)** - The frozen `sl-*` structural helper classes hosts guarantee
 - **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
 - **[Native Facade](native-facade.md)** - Contract layer for accessing device capabilities (share, NFC, haptics) across host shells
 - **[i18n](i18n.md)** - Internationalization and localization
@@ -11192,22 +11198,22 @@ The release channel a call targets, or undefined for "the collection's installed
 **functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
 The API path a function call goes to (exported for hosts/tests that need the exact URL).
 
-**siteUrl**(collection: { siteHost?: string | null } | string,
-    name: string,
+**siteUrl**(collection: { siteHost?: string | null } | string,
+    name: string,
     opts: FunctionSiteUrlOptions & { appId?: string } = {}) → `string`
 The PUBLIC address of an app function on the collection's own site — what you give a third party as a webhook URL, or call from the collection's public pages: `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`. Every HTTP method the function declares works there, with the raw body for signature checks. Pass the collection (or its siteHost). This address is for public/integration calls; signed-in calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session never goes to a tenant hostname. const col = await SL.collection.get(collectionId) const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' }) // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
 
-**call**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /fn/public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
 
-**callAdmin**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /fn/admin/collection/:c/app/:appId/functions/:name`.
 
 **list**(collectionId: string, opts: FunctionCallOptions = {}) → `Promise<FunctionListResponse>`
 List the public functions available for a collection (discovery). Scoped to one app when an appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.

package/dist/docs/headless-providers.md

@@ -50,6 +50,14 @@ Site builders (the Forge agent included) read these declarations to decide "inst
 | `thread` | App threads: discussions, Q&A, reviews | `SL.app.threads.list / get` |
 | `config` (+ optional `key`) | App configuration: settings, small fixed lists | `SL.appConfiguration.getConfig({ collectionId, appId })` |
 
+**What the read calls return.** This is fixed by the storage kind, so a provider never needs to describe it, and site builders get it from the checker and `forge-cms describe`:
+
+- **`record`, `case`, `thread`:** `list` returns `{ data: Item[], pagination: { total, limit, offset, hasMore } }`.
+  - The items are in **`response.data`**, never `response.items` or `response.records`.
+  - Each item's declared fields are in **`item.data`** (e.g. `record.data.question`). `id`, `status`, `productId` and the dates are top-level.
+  - Page with `offset` / `limit` while `pagination.hasMore`. `get` returns one item.
+- **`config`:** the configuration object. Items are in `config.<key>` when the type names a `key`.
+
 Products, contacts and proofs are platform data. Reference them with `ref` fields (`"to": "product"`); never redeclare them.
 
 **Field types:** `string`, `text`, `richtext` (HTML), `markdown`, `number`, `boolean`, `date` (YYYY-MM-DD), `datetime`, `enum` (+ `options`), `url`, `image` and `file` (a URL or `{ url, ... }`), `ref` and `ref[]` (+ `to`: a declared type id, or `product` / `contact` / `proof`), `string[]`, `json` (avoid where a typed field fits).

package/dist/docs/site-seo.md

@@ -8,9 +8,10 @@ get all of this from Hub.
 - **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
   `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
   the site's host, which the build can't know.
-- **Declare your routes** in `public/sitemap-paths.txt`, one path per line (`/`, `/menu`,
-  `/book`). They go into the sitemap and `llms.txt` on the right host. Pre-rendered pages
-  (`about/index.html`) are found automatically.
+- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
+  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
+  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
+  the router. Pre-rendered pages (`about/index.html`) are found automatically.
 - **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
   domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
   consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set

package/dist/headless.d.ts

@@ -8,12 +8,26 @@ export interface HeadlessValidation {
     ok: boolean;
     errors: HeadlessIssue[];
     warnings: HeadlessIssue[];
-    /** The read recipe for each type: the declared one, else the standard one for its storage. */
+    /**
+     * The read recipe for each type: the declared one, else the standard one for its storage — plus what
+     * the call returns and where an item's fields are. Those two always come from the storage kind (the
+     * platform's response shape), never from the app, so a custom recipe can't leave them out.
+     */
     recipes: Record<string, {
         list: string;
         get?: string;
+        returns: string;
+        item: string;
     }>;
 }
+/**
+ * What a type's read calls return, and where one item's declared fields live — fixed by the storage
+ * kind (see app-objects.md "Paginated List Responses"). Sites must read items from `response.data`.
+ */
+export declare function responseShape(type: AppDataType): {
+    returns: string;
+    item: string;
+};
 /** The standard SDK read calls for a type, from how it's stored. `appId` / `collectionId` are the caller's variables. */
 export declare function standardRecipe(type: AppDataType): {
     list: string;

package/dist/headless.js

@@ -18,13 +18,36 @@ const PLATFORM_REFS = new Set(['product', 'contact', 'proof']);
 const SEO_HELPERS = new Set(['faqPage', 'product', 'article', 'breadcrumbs', 'organization', 'localBusiness']);
 const STORAGE_KINDS = new Set(['record', 'case', 'thread', 'config']);
 const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+/**
+ * What a type's read calls return, and where one item's declared fields live — fixed by the storage
+ * kind (see app-objects.md "Paginated List Responses"). Sites must read items from `response.data`.
+ */
+export function responseShape(type) {
+    const s = type.storage;
+    const first = Object.keys(type.fields || {})[0] || 'field';
+    const paged = (name) => `list → { data: ${name}[], pagination: { total, limit, offset, hasMore } }. The items are in response.data (not response.items / response.records); page with offset/limit while pagination.hasMore. get → one ${name}.`;
+    switch (s && s.kind) {
+        case 'record':
+            return { returns: paged('AppRecord'), item: `Each record's declared fields are in record.data (e.g. record.data.${first}); record.id, record.productId, record.status, record.createdAt are top-level.` };
+        case 'case':
+            return { returns: paged('AppCase'), item: `Each case's declared fields are in case.data (e.g. case.data.${first}); id, status, category and dates are top-level.` };
+        case 'thread':
+            return { returns: paged('AppThread'), item: `Each thread's declared fields are in thread.data (e.g. thread.data.${first}); replies are in thread.replies.` };
+        case 'config': {
+            const key = s.key;
+            return { returns: "The app's configuration object for the collection.", item: key ? `The items are in config.${key}; each item's fields are its declared fields.` : 'The declared fields are top-level properties of the config object.' };
+        }
+        default:
+            return { returns: '(unknown storage)', item: '' };
+    }
+}
 /** The standard SDK read calls for a type, from how it's stored. `appId` / `collectionId` are the caller's variables. */
 export function standardRecipe(type) {
     const s = type.storage;
     switch (s && s.kind) {
         case 'record':
             return {
-                list: `SL.app.records.list(collectionId, appId, { recordType: '${s.recordType}', limit: 50 })  // → { data: AppRecord[] }; fields in record.data`,
+                list: `SL.app.records.list(collectionId, appId, { recordType: '${s.recordType}', limit: 50 })`,
                 get: 'SL.app.records.get(collectionId, appId, recordId)',
             };
         case 'case':
@@ -179,7 +202,8 @@ export function validate(manifest, opts = {}) {
             if (samples && samples.length)
                 checkItems('real item', typeId, type, samples, { errors, warnings });
             const std = standardRecipe(type);
-            recipes[typeId] = Object.assign({ list: (type.read && type.read.list) || std.list }, ((type.read && type.read.get) || std.get ? { get: (type.read && type.read.get) || std.get } : {}));
+            const get = (type.read && type.read.get) || std.get;
+            recipes[typeId] = Object.assign(Object.assign({ list: (type.read && type.read.list) || std.list }, (get ? { get } : {})), responseShape(type));
         }
     }
     // ---- headless

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.38  |  Generated: 2026-10-05T12:10:36.598Z
+Version: 2.0.39  |  Generated: 2026-10-05T14:14:46.558Z
 
 This is a concise summary of all available API functions and types.
 
@@ -26,6 +26,12 @@ For detailed guides on specific features:
 - **[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
+- **[Headless Providers](headless-providers.md)** - Declaring an app's content for other sites: the manifest `data` + `headless` blocks (types, storage, public fields, examples, read recipes, categories), `SL.headless.validate`, `smartlinks-headless`, and the procedure for adding a headless mode
+- **[Websites: SEO + GEO](site-seo.md)** - For apps served as websites: platform-generated robots/sitemap/llms.txt, canonical addresses, `SL.seo.head` / `SL.seo.jsonLd` / `SL.seo.schema.*`, `SL.site.ready()`, routes in `sitemap-paths.txt`
+- **[Agent Tools](agent-tools.md)** - Exposing app functions as AI agent tools
+- **[Host Dependency Contract](host-dependency-contract.md)** - The shared dependencies (React, the SDK…) the host provides, and what an app must externalise
+- **[Theme Tokens](theme-tokens.md)** - The `--sl-*` semantic token contract hosts set and apps bind to (`theme.css`)
+- **[CSS Baseline](css-baseline.md)** - The frozen `sl-*` structural helper classes hosts guarantee
 - **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
 - **[Native Facade](native-facade.md)** - Contract layer for accessing device capabilities (share, NFC, haptics) across host shells
 - **[i18n](i18n.md)** - Internationalization and localization
@@ -11192,22 +11198,22 @@ The release channel a call targets, or undefined for "the collection's installed
 **functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
 The API path a function call goes to (exported for hosts/tests that need the exact URL).
 
-**siteUrl**(collection: { siteHost?: string | null } | string,
-    name: string,
+**siteUrl**(collection: { siteHost?: string | null } | string,
+    name: string,
     opts: FunctionSiteUrlOptions & { appId?: string } = {}) → `string`
 The PUBLIC address of an app function on the collection's own site — what you give a third party as a webhook URL, or call from the collection's public pages: `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`. Every HTTP method the function declares works there, with the raw body for signature checks. Pass the collection (or its siteHost). This address is for public/integration calls; signed-in calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session never goes to a tenant hostname. const col = await SL.collection.get(collectionId) const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' }) // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
 
-**call**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /fn/public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
 
-**callAdmin**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /fn/admin/collection/:c/app/:appId/functions/:name`.
 
 **list**(collectionId: string, opts: FunctionCallOptions = {}) → `Promise<FunctionListResponse>`
 List the public functions available for a collection (discovery). Scoped to one app when an appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.

package/docs/headless-providers.md

@@ -50,6 +50,14 @@ Site builders (the Forge agent included) read these declarations to decide "inst
 | `thread` | App threads: discussions, Q&A, reviews | `SL.app.threads.list / get` |
 | `config` (+ optional `key`) | App configuration: settings, small fixed lists | `SL.appConfiguration.getConfig({ collectionId, appId })` |
 
+**What the read calls return.** This is fixed by the storage kind, so a provider never needs to describe it, and site builders get it from the checker and `forge-cms describe`:
+
+- **`record`, `case`, `thread`:** `list` returns `{ data: Item[], pagination: { total, limit, offset, hasMore } }`.
+  - The items are in **`response.data`**, never `response.items` or `response.records`.
+  - Each item's declared fields are in **`item.data`** (e.g. `record.data.question`). `id`, `status`, `productId` and the dates are top-level.
+  - Page with `offset` / `limit` while `pagination.hasMore`. `get` returns one item.
+- **`config`:** the configuration object. Items are in `config.<key>` when the type names a `key`.
+
 Products, contacts and proofs are platform data. Reference them with `ref` fields (`"to": "product"`); never redeclare them.
 
 **Field types:** `string`, `text`, `richtext` (HTML), `markdown`, `number`, `boolean`, `date` (YYYY-MM-DD), `datetime`, `enum` (+ `options`), `url`, `image` and `file` (a URL or `{ url, ... }`), `ref` and `ref[]` (+ `to`: a declared type id, or `product` / `contact` / `proof`), `string[]`, `json` (avoid where a typed field fits).

package/docs/site-seo.md

@@ -8,9 +8,10 @@ get all of this from Hub.
 - **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
   `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
   the site's host, which the build can't know.
-- **Declare your routes** in `public/sitemap-paths.txt`, one path per line (`/`, `/menu`,
-  `/book`). They go into the sitemap and `llms.txt` on the right host. Pre-rendered pages
-  (`about/index.html`) are found automatically.
+- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
+  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
+  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
+  the router. Pre-rendered pages (`about/index.html`) are found automatically.
 - **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
   domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
   consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.38",
+  "version": "2.0.39",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",