@proveanything/smartlinks 2.0.37 → 2.0.38

package/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.38  |  Generated: 2026-10-05T12:10:36.598Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2748,6 +2748,8 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  data?: AppDataDeclaration;
+  headless?: AppHeadlessDeclaration;
   [key: string]: any;
 }
 ```
@@ -6459,6 +6461,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)

package/docs/headless-providers.md

@@ -0,0 +1,104 @@
+# 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 })` |
+
+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/docs/site-seo.md

@@ -0,0 +1,67 @@
+# 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.
+- **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.
+- **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/openapi.yaml

@@ -19459,6 +19459,10 @@ components:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
           $ref: "#/components/schemas/AppManifestFunctions"
+        data:
+          $ref: "#/components/schemas/AppDataDeclaration"
+        headless:
+          $ref: "#/components/schemas/AppHeadlessDeclaration"
       required:
         - name
         - version
@@ -25155,6 +25159,161 @@ components:
           type: boolean
     FacetValueDefinition:
       $ref: "#/components/schemas/FacetValue"
+    AppDataField:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/AppDataFieldType"
+        label:
+          type: string
+        description:
+          type: string
+        required:
+          type: boolean
+        localized:
+          type: boolean
+        zone:
+          type: string
+          enum:
+            - data
+            - owner
+            - admin
+        public:
+          type: boolean
+        to:
+          type: string
+        options:
+          type: array
+          items:
+            type: string
+      required:
+        - type
+    AppDataType:
+      type: object
+      properties:
+        description:
+          type: string
+        storage:
+          $ref: "#/components/schemas/AppDataStorage"
+        visibility:
+          type: string
+          enum:
+            - public
+            - owner
+            - admin
+        anchors:
+          type: array
+          items:
+            type: string
+            enum:
+              - product
+              - variant
+              - batch
+              - proof
+              - contact
+        fields:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/AppDataField"
+        listing:
+          type: object
+          additionalProperties: true
+        examples:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        read:
+          type: object
+          additionalProperties: true
+        since:
+          type: string
+      required:
+        - description
+        - storage
+        - fields
+    AppDataDeclaration:
+      type: object
+      properties:
+        schemaVersion:
+          type: string
+        types:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/AppDataType"
+      required:
+        - schemaVersion
+        - types
+    AppHeadlessDeclaration:
+      type: object
+      properties:
+        purpose:
+          type: string
+        categories:
+          type: array
+          items:
+            $ref: "#/components/schemas/HeadlessCategory"
+        primaryTypes:
+          type: array
+          items:
+            type: string
+        editedIn:
+          type: object
+          additionalProperties: true
+        render:
+          type: object
+          additionalProperties: true
+      required:
+        - purpose
+        - categories
+        - primaryTypes
+        - editedIn
+    AppDataFieldType:
+      type: string
+      enum:
+        - string
+        - text
+        - richtext
+        - markdown
+        - number
+        - boolean
+        - date
+        - datetime
+        - enum
+        - url
+        - image
+        - file
+        - ref
+        - "string[]"
+        - "ref[]"
+        - json
+    AppDataStorage:
+      type: object
+      additionalProperties: true
+    HeadlessCategory:
+      type: string
+      enum:
+        - faq
+        - media
+        - pages
+        - articles
+        - catalog
+        - events
+        - locations
+        - people
+        - reviews
+        - documents
+        - forms
+        - other
+    HeadlessSeoHelper:
+      type: string
+      enum:
+        - faqPage
+        - product
+        - article
+        - breadcrumbs
+        - organization
+        - localBusiness
     CachedData:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.37",
+  "version": "2.0.38",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,8 @@
   "bin": {
     "smartlinks-register-release": "scripts/register-release.mjs",
     "smartlinks-publish": "scripts/publish.mjs",
-    "smartlinks-doctor": "scripts/doctor.mjs"
+    "smartlinks-doctor": "scripts/doctor.mjs",
+    "smartlinks-headless": "scripts/headless-check.mjs"
   },
   "files": [
     "dist/",
@@ -38,6 +39,7 @@
     "scripts/register-release.mjs",
     "scripts/publish.mjs",
     "scripts/doctor.mjs",
+    "scripts/headless-check.mjs",
     "scripts/lib/",
     "openapi.yaml",
     "README.md"

package/scripts/headless-check.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// =============================================================================
+// smartlinks-headless — check an app's headless-provider declaration (manifest `data` + `headless`).
+//
+//   smartlinks-headless [appDir]                                  # the declaration on its own
+//   smartlinks-headless [appDir] --collection <id> --app <appId>  # also against real public data
+//   smartlinks-headless ... --json                                # machine-readable result
+//
+// With --collection/--app it samples each record type's PUBLIC items from that collection and reports
+// fields the real data has that the declaration doesn't (and values that don't fit their type).
+// API base: --api <url>, else SMARTLINKS_API_BASE, else https://smartlinks.app/api/v1.
+// Spec: docs/headless-providers.md. Exit code: 0 = valid, 1 = errors.
+// =============================================================================
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const { validate } = await import(pathToFileURL(resolve(here, '../dist/headless.js')).href)
+
+const args = process.argv.slice(2)
+const flag = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined }
+const json = args.includes('--json')
+const positional = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && args[i - 1].startsWith('--') && args[i - 1] !== '--json'))
+const appDir = resolve(positional[0] || process.cwd())
+const collectionId = flag('collection')
+const appId = flag('app')
+const apiBase = (flag('api') || process.env.SMARTLINKS_API_BASE || 'https://smartlinks.app/api/v1').replace(/\/+$/, '')
+
+const C = process.stdout.isTTY && !json
+  ? { red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m' }
+  : { red: '', green: '', yellow: '', dim: '', bold: '', reset: '' }
+
+function fail(message) {
+  if (json) console.log(JSON.stringify({ ok: false, errors: [{ path: '', message }], warnings: [], recipes: {} }))
+  else console.error(`${C.red}smartlinks-headless: ${message}${C.reset}`)
+  process.exit(1)
+}
+
+const manifestPath = ['public/app.manifest.json', 'app.manifest.json', 'dist/app.manifest.json'].map((p) => join(appDir, p)).find(existsSync)
+if (!manifestPath) fail(`no app.manifest.json under ${appDir} (looked in public/, ., dist/)`)
+let manifest
+try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch (e) { fail(`can't parse ${manifestPath}: ${e.message}`) }
+
+// Real public items per record type, when a collection is given.
+const samples = {}
+const sampled = []
+if (collectionId && appId && manifest.data && manifest.data.types) {
+  for (const [typeId, type] of Object.entries(manifest.data.types)) {
+    if (!type || !type.storage || type.storage.kind !== 'record' || !type.storage.recordType) continue
+    const url = `${apiBase}/public/collection/${encodeURIComponent(collectionId)}/app/${encodeURIComponent(appId)}/records?recordType=${encodeURIComponent(type.storage.recordType)}&limit=25`
+    try {
+      const res = await fetch(url, { headers: { accept: 'application/json' } })
+      if (!res.ok) { sampled.push(`${typeId}: HTTP ${res.status}`); continue }
+      const body = await res.json()
+      const items = (Array.isArray(body) ? body : body.data || body.items || []).map((r) => (r && r.data) || {})
+      samples[typeId] = items
+      sampled.push(`${typeId}: ${items.length} public item${items.length === 1 ? '' : 's'}`)
+    } catch (e) {
+      sampled.push(`${typeId}: ${e.message}`)
+    }
+  }
+} else if (collectionId || appId) {
+  fail('--collection and --app go together')
+}
+
+const result = validate(manifest, { samples })
+
+if (json) {
+  console.log(JSON.stringify({ ...result, manifest: manifestPath, sampled }, null, 2))
+  process.exit(result.ok ? 0 : 1)
+}
+
+console.log(`${C.bold}smartlinks-headless${C.reset} ${C.dim}${manifestPath}${C.reset}`)
+if (!manifest.headless) console.log(`${C.dim}No "headless" block: checking the data declaration only.${C.reset}`)
+if (sampled.length) console.log(`${C.dim}Sampled from ${collectionId}: ${sampled.join('; ')}${C.reset}`)
+for (const e of result.errors) console.log(`${C.red}✗ ${e.path}${C.reset}  ${e.message}`)
+for (const w of result.warnings) console.log(`${C.yellow}! ${w.path}${C.reset}  ${w.message}`)
+if (Object.keys(result.recipes).length) {
+  console.log(`\n${C.bold}Read recipes${C.reset}`)
+  for (const [t, r] of Object.entries(result.recipes)) console.log(`  ${t}\n    list: ${r.list}${r.get ? `\n    get:  ${r.get}` : ''}`)
+}
+console.log(result.ok
+  ? `\n${C.green}✓ valid${result.warnings.length ? ` (${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'})` : ''}${C.reset}`
+  : `\n${C.red}${result.errors.length} error${result.errors.length === 1 ? '' : 's'}${C.reset}`)
+process.exit(result.ok ? 0 : 1)