@proveanything/smartlinks 2.0.37 → 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.37  |  Generated: 2026-10-04T09:59:59.885Z
+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
@@ -2748,6 +2754,8 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  data?: AppDataDeclaration;
+  headless?: AppHeadlessDeclaration;
   [key: string]: any;
 }
 ```
@@ -6459,6 +6467,65 @@ interface FacetValueGetParams {
 
 **FacetValueDefinition** = `FacetValue`
 
+### headless
+
+**AppDataField** (interface)
+```typescript
+interface AppDataField {
+  type: AppDataFieldType;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  localized?: boolean;
+  zone?: 'data' | 'owner' | 'admin';
+  public?: boolean;
+  to?: string;
+  options?: string[];
+}
+```
+
+**AppDataType** (interface)
+```typescript
+interface AppDataType {
+  description: string;
+  storage: AppDataStorage;
+  visibility?: 'public' | 'owner' | 'admin';
+  anchors?: Array<'product' | 'variant' | 'batch' | 'proof' | 'contact'>;
+  fields: Record<string, AppDataField>;
+  listing?: { sort?: string[]; filters?: string[] };
+  examples?: Array<Record<string, unknown>>;
+  read?: { list?: string; get?: string; notes?: string };
+  since?: string;
+}
+```
+
+**AppDataDeclaration** (interface)
+```typescript
+interface AppDataDeclaration {
+  schemaVersion: string;
+  types: Record<string, AppDataType>;
+}
+```
+
+**AppHeadlessDeclaration** (interface)
+```typescript
+interface AppHeadlessDeclaration {
+  purpose: string;
+  categories: HeadlessCategory[];
+  primaryTypes: string[];
+  editedIn: { label: string; adminPath?: string; notes?: string };
+  render?: { guidance?: string; seo?: HeadlessSeoHelper[] };
+}
+```
+
+**AppDataFieldType** = ``
+
+**AppDataStorage** = ``
+
+**HeadlessCategory** = ``
+
+**HeadlessSeoHelper** = `'faqPage' | 'product' | 'article' | 'breadcrumbs' | 'organization' | 'localBusiness'`
+
 ### iframeResponder
 
 **CachedData** (interface)
@@ -11131,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

@@ -0,0 +1,112 @@
+# Headless providers: declaring an app's content for other sites
+
+A **headless provider** is an app whose content other sites and apps may use: an FAQ app, a media gallery, content pages, a blog. The site renders the content its own way. The business keeps editing it in the provider's own admin, inside SmartLinks. A site never builds an editor for provider content.
+
+To become a provider, an app declares two blocks in `app.manifest.json`:
+- **`data`**: its data types, meaning how each is stored, its fields, examples and read recipes;
+- **`headless`**: the opt-in, meaning its purpose, categories, which types a site renders, where the owner edits it, and rendering guidance.
+
+Site builders (the Forge agent included) read these declarations to decide "install the FAQ app and use its content" instead of inventing their own.
+
+## The `data` block
+
+```jsonc
+"data": {
+  "schemaVersion": "1.0.0",                 // semver of THIS contract; a major = a breaking change
+  "types": {
+    "<app>.<thing>": {                      // lowercase, dot-separated, e.g. "faq.item"
+      "description": "What one item is, in a sentence.",
+      "storage": { "kind": "record", "recordType": "<the recordType the app writes>" },
+      "visibility": "public",               // the visibility items normally have: public | owner | admin
+      "anchors": ["product"],               // optional: what items can be attached to
+      "fields": {
+        "<key>": {
+          "type": "string",                 // see field types
+          "label": "Question",
+          "required": true,
+          "localized": true,                // translated per language (text types only)
+          "public": true,                   // readable by anonymous visitors
+          "zone": "data"                    // data (default) | owner | admin
+        }
+      },
+      "listing": { "sort": ["order"], "filters": ["category"] },
+      "examples": [ { "<key>": "realistic value" } ],
+      "read": {                             // optional: defaults to the standard calls for the storage
+        "list": "SL.app.records.list(collectionId, appId, { recordType: '...', limit: 50 })",
+        "get":  "SL.app.records.get(collectionId, appId, recordId)",
+        "notes": "anything a site must know, e.g. 'sort by order, then title'"
+      }
+    }
+  }
+}
+```
+
+**Storage kinds:**
+
+| `storage.kind` | The app keeps items in | Read with |
+|---|---|---|
+| `record` (+ `recordType`) | App records: the usual home for content | `SL.app.records.list / get`, filtered by `recordType` |
+| `case` | App cases: requests that get resolved | `SL.app.cases.list / get` |
+| `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).
+
+**Zones and what's public.** App records, cases and threads have three JSONB zones: `data`, `owner` and `admin`. Only `data` can be public, and only when the item's visibility is `public`. Mark each field a visitor may read with `"public": true`. Internal fields (notes, moderation flags) are `zone: "admin"` and never public.
+
+**Examples** are the item's `data` JSON exactly as the app writes it, with realistic content, not lorem ipsum.
+
+## The `headless` block
+
+```jsonc
+"headless": {
+  "purpose": "What content this holds and when a site should use it instead of building its own.",
+  "categories": ["faq"],                    // faq | media | pages | articles | catalog | events | locations
+                                            // | people | reviews | documents | forms | other
+  "primaryTypes": ["faq.item"],             // the types a site renders; others are supporting (e.g. categories)
+  "editedIn": { "label": "FAQ → Questions", "adminPath": "#/questions" },
+  "render": {
+    "guidance": "Group by category; questions expand to show answers.",
+    "seo": ["faqPage"]                      // SL.seo.schema helpers a site should use
+  }
+}
+```
+
+A primary type must be readable by visitors: public visibility, at least one public field, and at least one example.
+
+## Checking a declaration
+
+- **In Forge:** `forge-headless check` validates it against the app's real public data on its test collection. `forge-headless register` validates it and records it in Forge, which makes the app a provider that site builds can find.
+- **Anywhere else:**
+  - `npx smartlinks-headless [appDir] [--collection <id> --app <appId>]`;
+  - or `SL.headless.validate(manifest, { samples })` in code.
+
+Errors block. Warnings are worth fixing, and the most useful one is *real data has "x" but it isn't declared*.
+
+## Adding a headless mode to an existing app (procedure)
+
+1. **Find what the app stores.** Search the source for its writes and reads:
+   - `SL.app.records.create / upsert / bulkUpsert` (note each `recordType`);
+   - `SL.app.cases`, `SL.app.threads`;
+   - `appConfiguration.setConfig` / data items.
+
+   Each distinct `recordType` (or config key) the business edits is a candidate type.
+2. **Find the fields.** Read the admin forms and the TypeScript types for what each item holds. Note which zone each field is written to.
+3. **Decide what's public.** Content a visitor sees is public. Notes, flags and anything personal are not, and move to `zone: "admin"` if the app keeps them in `data`.
+4. **Write the `data` block:** a type per content thing, its storage, fields, listing, and one or two realistic examples taken from the app's real data.
+5. **Write the `headless` block:** purpose, categories, primary types, where it's edited (the admin screen's name and route), and render and SEO guidance.
+6. **Check against real data** (`forge-headless check`). Declare any real fields you missed, or confirm they're internal.
+7. **Register** (`forge-headless register`) once it's valid.
+8. **Keep the data contract stable.** Adding fields or types is a minor bump of `schemaVersion`; renaming or removing them is a major one.
+
+Don't change how the app stores data just to declare it. The declaration describes what already exists. If something must change (say, an internal field sitting in the public `data` zone), make that a separate, deliberate change.

package/dist/docs/site-seo.md

@@ -0,0 +1,68 @@
+# Websites: search engines and AI crawlers (SEO + GEO)
+
+For apps served as websites (an app site at `<name>.smartlinks.host` or a custom domain). Hub sites
+get all of this from Hub.
+
+## What the platform does for you
+
+- **`/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.
+- **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
+  your own canonical unless a page has a different canonical page.
+- **Previews stay out of search.** A sandbox collection's sites, and any test build (dev, alpha,
+  beta), are served with `X-Robots-Tag: noindex` and a `robots.txt` that disallows everything,
+  whatever the build ships.
+
+## What you do: `SL.seo` and `SL.site`
+
+```ts
+import * as SL from '@proveanything/smartlinks'
+
+// Per route, from its data — on every route change:
+SL.seo.head({
+  title: `${product.name} — ${brand}`,
+  description: product.description,       // ~150 characters, says what the page is
+  image: product.heroImage?.url,           // absolute; used for link previews
+  type: 'product',                         // 'website' | 'article' | 'product'
+})
+
+// Structured data (schema.org JSON-LD). The id names the block, so calling again replaces it:
+SL.seo.jsonLd('page', SL.seo.schema.product(product, { url: location.href, brand }))
+SL.seo.jsonLd('faq', SL.seo.schema.faqPage(faqs.map((f) => ({ question: f.q, answer: f.a }))))
+SL.seo.jsonLd('org', SL.seo.schema.organization(collection))
+
+// When the page's data has rendered:
+SL.site.ready()
+```
+
+| Builder | For |
+|---|---|
+| `schema.product(product, { url, brand, offer, rating })` | product pages (`offer` only when it's really sold) |
+| `schema.faqPage([{ question, answer }])` | FAQs: rich results, and the answer-shaped content AI search cites |
+| `schema.organization(collection)` | the brand behind the site (home page) |
+| `schema.localBusiness(collection, { type, address, telephone, openingHours })` | a business with a place (`type: 'Florist'`, `'Restaurant'`…) |
+| `schema.breadcrumbs([{ name, url }])` | nested pages |
+| `schema.article({ headline, datePublished, … })` | posts, guides, news |
+
+`seo.head` removes tags a previous route set and the next one doesn't. Both are no-ops without a
+`document` (SSR, tests).
+
+`site.ready()` tells the platform's page renderer the page is complete, so it can snapshot the
+content for crawlers that don't run JavaScript. Without it, the renderer waits for the network to go
+quiet.
+
+## Content that gets found
+
+- **Content in the page, not behind interaction.** FAQ answers in `<details>` are fine; answers
+  fetched only when a question is clicked aren't seen.
+- **One `<h1>` per page**, a logical heading order, `alt` text on content images.
+- **Answer-shaped writing.** A short summary near the top, question-style headings where they fit.
+  This is what AI assistants quote.
+- **Real links** (`<a href>`) between pages, never hash routes.

package/dist/headless.d.ts

@@ -0,0 +1,45 @@
+import type { AppDataDeclaration, AppDataType, AppHeadlessDeclaration } from './types/headless.js';
+export interface HeadlessIssue {
+    /** Where: e.g. `headless.purpose`, `data.types.faq.item.fields.answer`. */
+    path: string;
+    message: string;
+}
+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 — 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;
+    get?: string;
+};
+export interface ValidateOptions {
+    /** Real items per type id (each item's `data` zone JSON), e.g. sampled from a test collection. */
+    samples?: Record<string, Array<Record<string, unknown>>>;
+}
+/** Validate a manifest's `data` + `headless` blocks. */
+export declare function validate(manifest: {
+    data?: AppDataDeclaration;
+    headless?: AppHeadlessDeclaration;
+    [k: string]: any;
+}, opts?: ValidateOptions): HeadlessValidation;