@proveanything/smartlinks 2.0.36 → 2.0.38

package/dist/api/ai.d.ts

@@ -111,8 +111,8 @@ declare namespace aiInternal {
         }>;
     }
     /**
-     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
-     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     * AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day
+     * over an optional date window (YYYY-MM-DD). Usage only — requests, tokens, images; no cost figures.
      */
     function usage(collectionId: string, params?: {
         groupBy?: string | string[];

package/dist/api/ai.js

@@ -224,8 +224,8 @@ var aiInternal;
         sessions.clear = clear;
     })(sessions = aiInternal.sessions || (aiInternal.sessions = {}));
     /**
-     * AI usage / cost report for a collection, grouped by any of model/serviceTier/appId/feature/mode
-     * over an optional date window. `costUnits` are OPAQUE internal units, never provider currency.
+     * AI usage for a collection (daily totals), grouped by any of model/appId/feature/mode/surface/provider/day
+     * over an optional date window (YYYY-MM-DD). Usage only — requests, tokens, images; no cost figures.
      */
     async function usage(collectionId, params) {
         const groupBy = Array.isArray(params === null || params === void 0 ? void 0 : params.groupBy) ? params.groupBy.join(',') : params === null || params === void 0 ? void 0 : params.groupBy;

package/dist/context.js

@@ -40,6 +40,21 @@ export function readContext(overrides) {
             if (window.location.search)
                 readSearchParamsInto(out, new URLSearchParams(window.location.search));
         }
+        // 4. the SITE the page is served as (lowest precedence). When an app runs as a public website at
+        //    its own hostname (an "app site"), the host page injects window.__SMARTLINKS_SITE__ =
+        //    { collectionId, appId, channel, host } — so a site knows its collection with no URL params.
+        const site = globalThis.__SMARTLINKS_SITE__;
+        if (site && typeof site === 'object') {
+            const fill = (key, value) => { if (out[key] == null && typeof value === 'string' && value)
+                out[key] = value; };
+            fill('collectionId', site.collectionId);
+            fill('appId', site.appId);
+            // A site on a pre-release channel calls that channel's server functions (stable needs no channel).
+            if (site.channel && site.channel !== 'stable') {
+                fill('appChannel', site.channel);
+                fill('appChannelApp', site.appId);
+            }
+        }
     }
     catch (_a) {
         /* non-browser / bad URL — return what we have */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.36  |  Generated: 2026-10-03T15:04:37.396Z
+Version: 2.0.38  |  Generated: 2026-10-05T12:10:36.598Z
 
 This is a concise summary of all available API functions and types.
 
@@ -918,8 +918,20 @@ interface AiUsageReport {
   groupBy: string[]
   from?: string | null
   to?: string | null
-  totals: { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }
-  groups: Array<Record<string, any> & { promptTokens: number; outputTokens: number; totalTokens: number; requests: number; costUnits: number }>
+  totals: AiUsageTotals
+  groups: Array<Record<string, any> & AiUsageTotals>
+}
+```
+
+**AiUsageTotals** (interface)
+```typescript
+interface AiUsageTotals {
+  promptTokens: number
+  outputTokens: number
+  cachedTokens: number
+  totalTokens: number
+  requests: number
+  images: number
 }
 ```
 
@@ -2736,6 +2748,8 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  data?: AppDataDeclaration;
+  headless?: AppHeadlessDeclaration;
   [key: string]: any;
 }
 ```
@@ -6447,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/dist/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/dist/docs/server-functions.md

@@ -275,7 +275,7 @@ await SL.functions.call(collectionId, 'pressCounter', {}, { channel: null })   /
 ```
 
 **Public address on the collection's own site (webhooks, integrations).** Every collection has a
-site host — `<name>.smartlinks.host` once a name is claimed, else `c-<shortId>.smartlinks.host` —
+site host — `<name>.smartlinks.host` once a name is claimed, else `c-<collectionId>.smartlinks.host` —
 returned as `collection.siteHost`. App functions are reachable there:
 
 ```

package/dist/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/dist/headless.d.ts

@@ -0,0 +1,31 @@
+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. */
+    recipes: Record<string, {
+        list: string;
+        get?: 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;

package/dist/headless.js

@@ -0,0 +1,225 @@
+// =============================================================================
+// headless — validate an app's headless-provider declaration (manifest `data` + `headless`).
+//
+//   SL.headless.validate(manifest, { samples })  → { ok, errors, warnings, recipes }
+//
+// Pure (no network): the `smartlinks-headless` CLI and Forge both call it. `samples` are real items
+// (each type's `data` zone JSON) — the check then reports fields the real data has but the
+// declaration doesn't, and values that don't match their declared type.
+// Spec: docs/headless-providers.md.
+// =============================================================================
+import { HEADLESS_CATEGORIES } from './types/headless.js';
+const FIELD_TYPES = new Set([
+    'string', 'text', 'richtext', 'markdown', 'number', 'boolean', 'date', 'datetime', 'enum', 'url',
+    'image', 'file', 'ref', 'string[]', 'ref[]', 'json',
+]);
+const TEXT_TYPES = new Set(['string', 'text', 'richtext', 'markdown']);
+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.-]+)?$/;
+/** 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`,
+                get: 'SL.app.records.get(collectionId, appId, recordId)',
+            };
+        case 'case':
+            return { list: 'SL.app.cases.list(collectionId, appId, { limit: 50 })', get: 'SL.app.cases.get(collectionId, appId, caseId)' };
+        case 'thread':
+            return { list: 'SL.app.threads.list(collectionId, appId, { limit: 50 })', get: 'SL.app.threads.get(collectionId, appId, threadId)' };
+        case 'config':
+            return { list: `SL.appConfiguration.getConfig({ collectionId, appId })${s.key ? `  // → config.${s.key}` : ''}` };
+        default:
+            return { list: '(unknown storage)' };
+    }
+}
+function isPlaceholder(v) {
+    return typeof v === 'string' && /lorem ipsum|^(todo|tbd|example|test|foo|bar)$/i.test(v.trim());
+}
+/** Does a value fit a declared field? Returns a reason when it doesn't. */
+function mismatch(field, value) {
+    if (value === null || value === undefined)
+        return null;
+    const t = field.type;
+    const isLocalizedObject = field.localized && typeof value === 'object' && !Array.isArray(value) &&
+        Object.values(value).every((x) => typeof x === 'string');
+    switch (t) {
+        case 'string':
+        case 'text':
+        case 'richtext':
+        case 'markdown':
+            return typeof value === 'string' || isLocalizedObject ? null : `expected ${t} (a string${field.localized ? ' or { lang: string }' : ''})`;
+        case 'url':
+            return typeof value === 'string' ? null : 'expected a URL string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value) ? null : 'expected a number';
+        case 'boolean':
+            return typeof value === 'boolean' ? null : 'expected true/false';
+        case 'date':
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value) ? null : 'expected an ISO date (YYYY-MM-DD)';
+        case 'datetime':
+            return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? null : 'expected an ISO date-time';
+        case 'enum':
+            return (field.options || []).includes(value) ? null : `expected one of ${(field.options || []).join(', ')}`;
+        case 'image':
+        case 'file':
+            return typeof value === 'string' || (typeof value === 'object' && !Array.isArray(value) && typeof value.url === 'string')
+                ? null : `expected a URL string or { url }`;
+        case 'ref':
+            return typeof value === 'string' ? null : 'expected an id string';
+        case 'string[]':
+        case 'ref[]':
+            return Array.isArray(value) && value.every((x) => typeof x === 'string') ? null : 'expected an array of strings';
+        default:
+            return null;
+    }
+}
+function checkItems(label, typeId, type, items, out) {
+    const fields = type.fields || {};
+    const undeclared = new Map();
+    items.forEach((item, i) => {
+        const at = `data.types.${typeId}.${label === 'example' ? 'examples' : 'realData'}[${i}]`;
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            out.errors.push({ path: at, message: `${label} must be an object (the item's data JSON)` });
+            return;
+        }
+        for (const [key, field] of Object.entries(fields)) {
+            if ((field.zone || 'data') !== 'data')
+                continue; // examples / samples are the data zone
+            const value = item[key];
+            if (field.required && (value === undefined || value === null || value === '')) {
+                ;
+                (label === 'example' ? out.errors : out.warnings).push({ path: `${at}.${key}`, message: `required field "${key}" is missing` });
+                continue;
+            }
+            const why = mismatch(field, value);
+            if (why)
+                (label === 'example' ? out.errors : out.warnings).push({ path: `${at}.${key}`, message: `"${key}": ${why}` });
+            if (label === 'example' && isPlaceholder(value))
+                out.warnings.push({ path: `${at}.${key}`, message: 'looks like placeholder text — use realistic content' });
+        }
+        for (const key of Object.keys(item))
+            if (!(key in fields))
+                undeclared.set(key, (undeclared.get(key) || 0) + 1);
+    });
+    for (const [key, n] of undeclared) {
+        out.warnings.push({
+            path: `data.types.${typeId}.fields`,
+            message: label === 'example'
+                ? `example uses "${key}", which isn't a declared field`
+                : `real data has "${key}" (in ${n} of ${items.length} items) but it isn't declared — declare it, or confirm it's internal`,
+        });
+    }
+}
+/** Validate a manifest's `data` + `headless` blocks. */
+export function validate(manifest, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    const recipes = {};
+    const err = (path, message) => errors.push({ path, message });
+    const warn = (path, message) => warnings.push({ path, message });
+    const data = manifest && manifest.data;
+    const headless = manifest && manifest.headless;
+    // ---- data
+    if (!data) {
+        err('data', headless ? 'a headless app needs a `data` block declaring its types' : 'no `data` block');
+    }
+    else {
+        if (!data.schemaVersion || !SEMVER.test(data.schemaVersion))
+            err('data.schemaVersion', 'set a semver, e.g. "1.0.0"');
+        const types = data.types || {};
+        if (!Object.keys(types).length)
+            err('data.types', 'declare at least one type');
+        const typeIds = new Set(Object.keys(types));
+        for (const [typeId, type] of Object.entries(types)) {
+            const at = `data.types.${typeId}`;
+            if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/.test(typeId))
+                err(at, 'type ids are lowercase, dot-separated (e.g. "faq.item")');
+            if (!type.description || type.description.trim().length < 10)
+                err(`${at}.description`, 'say what one item is, in a sentence');
+            const kind = type.storage && type.storage.kind;
+            if (!STORAGE_KINDS.has(kind))
+                err(`${at}.storage`, 'storage.kind must be record, case, thread or config');
+            if (kind === 'record' && !type.storage.recordType)
+                err(`${at}.storage.recordType`, 'record storage needs the recordType the app writes');
+            if (type.visibility && !['public', 'owner', 'admin'].includes(type.visibility))
+                err(`${at}.visibility`, 'public, owner or admin');
+            const fields = type.fields || {};
+            if (!Object.keys(fields).length)
+                err(`${at}.fields`, 'declare the fields');
+            for (const [key, f] of Object.entries(fields)) {
+                const fat = `${at}.fields.${key}`;
+                if (!f || !FIELD_TYPES.has(f.type)) {
+                    err(fat, `unknown type "${f && f.type}" (one of ${[...FIELD_TYPES].join(', ')})`);
+                    continue;
+                }
+                if (f.type === 'enum' && !(f.options && f.options.length))
+                    err(fat, 'an enum needs options');
+                if ((f.type === 'ref' || f.type === 'ref[]') && !(f.to && (typeIds.has(f.to) || PLATFORM_REFS.has(f.to)))) {
+                    err(fat, `"to" must name a declared type or product/contact/proof`);
+                }
+                if (f.localized && !TEXT_TYPES.has(f.type))
+                    warn(fat, 'only text fields can be localized');
+                if (f.public && f.zone && f.zone !== 'data')
+                    err(fat, `a ${f.zone}-zone field can't be public — only the data zone is readable publicly`);
+            }
+            for (const k of (type.listing && type.listing.sort) || [])
+                if (!(k.replace(/^-/, '') in fields))
+                    err(`${at}.listing.sort`, `"${k}" isn't a field`);
+            for (const k of (type.listing && type.listing.filters) || [])
+                if (!(k in fields))
+                    err(`${at}.listing.filters`, `"${k}" isn't a field`);
+            if (type.examples)
+                checkItems('example', typeId, type, type.examples, { errors, warnings });
+            const samples = opts.samples && opts.samples[typeId];
+            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 } : {}));
+        }
+    }
+    // ---- headless
+    if (headless) {
+        if (!headless.purpose || headless.purpose.trim().length < 40) {
+            err('headless.purpose', 'explain what content this holds and when a site should use it (a few sentences)');
+        }
+        const cats = headless.categories || [];
+        if (!cats.length)
+            err('headless.categories', `pick at least one: ${HEADLESS_CATEGORIES.join(', ')}`);
+        for (const c of cats)
+            if (!HEADLESS_CATEGORIES.includes(c))
+                err('headless.categories', `"${c}" isn't a category (${HEADLESS_CATEGORIES.join(', ')})`);
+        if (!headless.editedIn || !headless.editedIn.label)
+            err('headless.editedIn.label', 'say where the business edits this content (the app admin screen)');
+        for (const s of (headless.render && headless.render.seo) || [])
+            if (!SEO_HELPERS.has(s))
+                err('headless.render.seo', `"${s}" isn't an SEO helper (${[...SEO_HELPERS].join(', ')})`);
+        const types = (data && data.types) || {};
+        const primary = headless.primaryTypes || [];
+        if (!primary.length)
+            err('headless.primaryTypes', 'name the type(s) a site renders');
+        for (const id of primary) {
+            const type = types[id];
+            if (!type) {
+                err('headless.primaryTypes', `"${id}" isn't a declared type`);
+                continue;
+            }
+            if (type.visibility === 'admin')
+                err(`data.types.${id}.visibility`, 'a primary type must be readable by visitors (visibility public)');
+            const publicFields = Object.entries(type.fields || {}).filter(([, f]) => f.public);
+            if (!publicFields.length)
+                err(`data.types.${id}.fields`, 'mark the fields a visitor may read with "public": true');
+            if (!type.examples || !type.examples.length)
+                err(`data.types.${id}.examples`, 'add at least one realistic example item');
+            if (!type.read)
+                warn(`data.types.${id}.read`, 'no read recipe — the standard one for its storage is used (see recipes)');
+        }
+        if (!(headless.render && headless.render.guidance))
+            warn('headless.render.guidance', 'add a line on how a site should present this content');
+    }
+    return { ok: errors.length === 0, errors, warnings, recipes };
+}

package/dist/index.d.ts

@@ -8,6 +8,9 @@ export type { InvalidateCacheOptions } from "./http.js";
 export * as cache from './cache.js';
 export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
 export * as utils from './utils/index.js';
+export * as seo from './seo.js';
+export * as site from './site.js';
+export * as headless from './headless.js';
 export { SHARED_DEPENDENCY_CONTRACT_VERSION, SHARED_DEPENDENCIES, SHARED_DEPENDENCY_SPECIFIERS, importMapPathFor, getHostSharedDependencies, } from './shared-dependencies.js';
 export type { SharedDependency, HostSharedDependencies } from './shared-dependencies.js';
 export { AI_TOOL_NAMES, BUILTIN_AI_TOOLS, getBuiltinAiTool } from './ai-tools.js';

package/dist/index.js

@@ -13,6 +13,12 @@ export { cache_1 as cache };
 export { IframeResponder, isAdminFromRoles, buildIframeSrc, } from './iframeResponder.js';
 import * as utils_1 from './utils/index.js';
 export { utils_1 as utils };
+import * as seo_1 from './seo.js';
+export { seo_1 as seo };
+import * as site_1 from './site.js';
+export { site_1 as site };
+import * as headless_1 from './headless.js';
+export { headless_1 as headless };
 // Shared dependency contract (host↔app) — one source of truth for externalized deps
 export { SHARED_DEPENDENCY_CONTRACT_VERSION, SHARED_DEPENDENCIES, SHARED_DEPENDENCY_SPECIFIERS, importMapPathFor, getHostSharedDependencies, } from './shared-dependencies.js';
 // Built-in AI tool catalog (design-time discovery of the core agentic toolset)