@proveanything/smartlinks 2.0.57 → 2.0.60

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
@@ -19778,6 +19780,11 @@ components:
             $ref: "#/components/schemas/ConnectorPanel"
         aiGuide:
           type: string
+        recordId:
+          type: string
+        limits:
+          type: object
+          additionalProperties: true
       required:
         - provider
         - directions
@@ -19860,7 +19867,7 @@ components:
           type: string
       required:
         - records
-    ConnectorTransformInput:
+    ConnectorShapeInput:
       type: object
       properties:
         installation:
@@ -19870,15 +19877,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:
@@ -19906,12 +19938,26 @@ components:
       type: object
       properties:
         results:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
+          type: object
+          additionalProperties: true
+        index:
+          type: number
+        ok:
+          type: boolean
+        status:
+          type: number
+        error:
+          type: string
+        externalId:
+          type: string
+        retryable:
+          type: boolean
+        retryAfterSeconds:
+          type: number
       required:
         - results
+        - index
+        - ok
     ConnectorFetchInput:
       type: object
       properties:
@@ -26251,6 +26297,12 @@ components:
           type: string
         totalSynced:
           type: number
+        circuitOpenedAt:
+          type: string
+        circuitProbeAt:
+          type: string
+        circuitReason:
+          type: string
       required:
         - id
         - orgId
@@ -26267,6 +26319,47 @@ components:
         - createdBy
         - createdAt
         - updatedAt
+    FailedRecord:
+      type: object
+      properties:
+        id:
+          type: string
+        entityId:
+          type: string
+        externalId:
+          type: string
+        status:
+          type: string
+          enum:
+            - failed
+            - dead
+        attempts:
+          type: number
+        nextAttemptAt:
+          type: string
+        lastError:
+          type: string
+        updatedAt:
+          type: string
+      required:
+        - id
+        - status
+        - attempts
+    FailedRecordList:
+      type: object
+      properties:
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/FailedRecord"
+        nextCursor:
+          type: string
+      required:
+        - direction
+        - items
+        - nextCursor
     CreateFlowInput:
       type: object
       properties:
@@ -26338,6 +26431,8 @@ components:
           type: number
         skipped:
           type: number
+        held:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId:
@@ -26734,7 +26829,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.60",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",