@proveanything/smartlinks 2.0.37 → 2.0.39

package/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/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.39",
   "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)