@proveanything/smartlinks 2.0.57 → 2.0.58

package/docs/site-seo.md

@@ -1,68 +1,69 @@
-# 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.
+# 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
+
+- **Every page is server-rendered.** A website runs on the SmartLinks site runtime (see
+  [websites.md](websites.md)): the first response for any URL is the finished HTML, with its title,
+  description, link-preview image, structured data and real status codes (404s are 404s). Search
+  engines, AI crawlers and link previews read it without running JavaScript.
+- **`/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.
+- **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))
+
+```
+
+| 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`. In a server-rendered site, prefer the router's own head support (TanStack Start's route
+`head()`), so the tags are in the server's HTML; use `SL.seo.schema.*` to build the JSON-LD for it.
+
+`SL.site.ready()` is no longer needed: pages arrive finished from the server.
+
+## 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/docs/websites.md

@@ -0,0 +1,91 @@
+# Websites: server-rendered on the SmartLinks site runtime
+
+A website built on SmartLinks is an app whose public side is a **server-rendered site** at its own
+address: an automatic `*.smartlinks.host` name, a chosen name, or the business's own domain. Every
+page arrives as finished HTML, so search engines, AI crawlers and link previews see the real
+content, and visitors see it before any JavaScript runs.
+
+## How a request is served
+
+```
+visitor / crawler / agent
+  └─► SmartLinks site router (edge)
+        ├─ /robots.txt, /sitemap.xml, /llms.txt     made by the platform (site-seo.md)
+        ├─ a file in your build (has an extension)   served from the build, cached at the edge
+        └─ anything else                             your site's server renders it
+              • runs in an isolated worker, close to the SmartLinks API
+              • may call the SmartLinks API and the hosts you declare, nothing else
+              • request header x-sl-site says which site it is (SL.site.fromRequest)
+```
+
+The router also adds the canonical or noindex header, the security headers, and
+`window.__SMARTLINKS_SITE__` to every HTML page (read in the browser with `SL.site.current()` or
+`SL.readContext()`).
+
+## The build
+
+The website template (TanStack Start) produces this; you don't write it by hand.
+
+```
+dist/
+├── index.html? / assets/…       the client build (hashed files: cached for a year)
+├── sitemap-paths.txt            your pages, "<path> [Title]" per line (site-seo.md)
+├── _server/                     the server bundle: one ES module entry + its chunks
+│   └── index.mjs                exports default { fetch(request, env, ctx) }  (WinterTC)
+└── app.manifest.json
+```
+
+Manifest:
+
+```jsonc
+"site": {
+  "server": {
+    "main": "_server/index.mjs",            // the server entry, inside the build
+    "compatibilityFlags": ["nodejs_compat"] // allowed: nodejs_compat, nodejs_compat_v2, nodejs_als
+  },
+  "network": ["api.example-weather.com"]    // other hosts the server may call (optional)
+}
+```
+
+On publish, the server folder becomes the site's server for that channel. Promote copies the same
+bytes. `_server/` is never served to visitors.
+
+## The server's rules
+
+- **Which site:** `const site = SL.site.fromRequest(request)` gives `{ host, collectionId, appId,
+  channel, canonicalHost }`. One build serves every site it's installed on, so always take the
+  collection from here, never from a constant.
+- **Data:** call the SmartLinks API with the SDK as you would in the browser. The server reads what
+  an anonymous visitor could read on that site, and only that collection. It holds no keys and no
+  signed-in user.
+- **Writes** (contact forms, entries, sign-ups) go to your app's **server functions**
+  (server-functions.md), called from the browser as today. Their capabilities, secrets and limits
+  apply.
+- **Other hosts:** only those in `site.network`. Anything else is refused (`403 Blocked`).
+- **Limits per request:** a CPU-time budget and a cap on outgoing calls. A page that needs more is
+  doing work that belongs in a server function or a scheduled job.
+- **No secrets** in the server bundle and no Node built-ins beyond `nodejs_compat`.
+
+## Caching
+
+The router keeps a rendered page at the edge when your response says it may:
+
+| Your response | At the edge |
+|---|---|
+| `Cache-Control: public, s-maxage=300` (the template's default for pages) | kept up to 5 minutes |
+| `private`, `no-store`, `no-cache`, or a `Set-Cookie` | never kept |
+| no `Cache-Control` | never kept |
+
+Cached pages are keyed by the release and the collection's **content generation**: when products,
+public app records, app settings or the collection change, the generation moves and every page of
+the collection's sites re-renders on its next visit (within about 30 seconds). Publishing a release
+does the same. Tracking parameters (`utm_*`, `gclid`, `fbclid`…) don't create separate entries.
+
+Keep pages the same for every visitor. Anything personal (a signed-in owner's products, a basket)
+renders in the browser after load.
+
+## Locally
+
+`npm run dev` runs the site with your dev collection (`.env`: `VITE_SL_COLLECTION_ID`), because
+there's no router to say which site it is: `SL.site.fromRequest()` is null, so fall back to it.
+Forge's preview runs the same server code the site runtime does.

package/openapi.yaml

@@ -19766,7 +19766,9 @@ components:
           type: string
         sample:
           type: string
-        transform:
+        shape:
+          type: string
+        serialize:
           type: string
         send:
           type: string
@@ -19860,7 +19862,7 @@ components:
           type: string
       required:
         - records
-    ConnectorTransformInput:
+    ConnectorShapeInput:
       type: object
       properties:
         installation:
@@ -19870,15 +19872,40 @@ components:
           items:
             type: object
             additionalProperties: true
-        mapping:
+      required:
+        - installation
+        - records
+    ConnectorShapeResult:
+      type: object
+      properties:
+        documents:
           type: array
           items:
-            $ref: "#/components/schemas/FieldMapping"
+            type: object
+            additionalProperties: true
+        skipped:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - documents
+    ConnectorSerializeInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        documents:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        eventType:
+          type: string
       required:
         - installation
-        - records
-        - mapping
-    ConnectorTransformResult:
+        - documents
+    ConnectorSerializeResult:
       type: object
       properties:
         payloads:
@@ -26734,7 +26761,8 @@ components:
         - testConnection
         - describeTarget
         - sample
-        - transform
+        - shape
+        - serialize
     RunTrigger:
       type: string
       enum:

package/package.json

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