@proveanything/smartlinks 2.0.57 → 2.0.60

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

@@ -1,10 +1,38 @@
 declare global {
     var __SL_READY__: boolean | undefined;
+    var __SMARTLINKS_SITE__: SiteContext | undefined;
 }
+/** The site a page is being served as. */
+export interface SiteContext {
+    /** The hostname this request arrived on (an automatic address, a chosen name or a custom domain). */
+    host: string;
+    /** The collection the site belongs to: pass it to every SDK call. */
+    collectionId: string;
+    appId: string;
+    /** The release channel being served ('stable' on a live address; 'dev' etc. on a test address). */
+    channel: string;
+    /** Where search engines consolidate the site (custom domain > chosen name > automatic address). */
+    canonicalHost: string;
+}
+type HeaderSource = {
+    headers: Headers | Record<string, string | string[] | undefined>;
+} | Headers;
+/**
+ * On the server: the site this request is rendering. The SmartLinks site router sets it on every
+ * request it hands to your site's server (and drops any value a visitor sends). Null outside the
+ * site runtime, e.g. in local development without the router: fall back to your dev collection.
+ *
+ * @example
+ *   // TanStack Start server function / loader
+ *   const site = SL.site.fromRequest(getRequest())
+ *   const products = await SL.product.list(site!.collectionId)
+ */
+export declare function fromRequest(request: HeaderSource): SiteContext | null;
+/** In the browser: the site the page is served as (the router puts it in the page). Null elsewhere. */
+export declare function current(): SiteContext | null;
 /**
- * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
- * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
- * without it, it waits for the network to go idle (capped). Call once per page, after your data
- * renders. Harmless anywhere else.
+ * @deprecated Sites are server-rendered: crawlers get the finished page from the server, so nothing
+ * waits for this signal any more. Kept as a harmless no-op signal for older pages.
  */
 export declare function ready(): void;
+export {};

package/dist/site.js

@@ -1,11 +1,54 @@
 // =============================================================================
-// site — for apps served as websites.
+// site — for apps served as websites (server-rendered on the SmartLinks site runtime).
 // =============================================================================
+function headerOf(source, name) {
+    var _a, _b;
+    const headers = typeof Headers !== 'undefined' && source instanceof Headers ? source : source.headers;
+    if (!headers)
+        return null;
+    if (typeof headers.get === 'function')
+        return headers.get(name);
+    const v = (_a = headers[name]) !== null && _a !== void 0 ? _a : headers[name.toLowerCase()];
+    return Array.isArray(v) ? (_b = v[0]) !== null && _b !== void 0 ? _b : null : v !== null && v !== void 0 ? v : null;
+}
+function parse(raw) {
+    try {
+        const v = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (!v || typeof v !== 'object' || typeof v.collectionId !== 'string')
+            return null;
+        const s = v;
+        return {
+            host: String(s.host || ''),
+            collectionId: String(s.collectionId),
+            appId: String(s.appId || ''),
+            channel: String(s.channel || 'stable'),
+            canonicalHost: String(s.canonicalHost || s.host || ''),
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * On the server: the site this request is rendering. The SmartLinks site router sets it on every
+ * request it hands to your site's server (and drops any value a visitor sends). Null outside the
+ * site runtime, e.g. in local development without the router: fall back to your dev collection.
+ *
+ * @example
+ *   // TanStack Start server function / loader
+ *   const site = SL.site.fromRequest(getRequest())
+ *   const products = await SL.product.list(site!.collectionId)
+ */
+export function fromRequest(request) {
+    return parse(headerOf(request, 'x-sl-site'));
+}
+/** In the browser: the site the page is served as (the router puts it in the page). Null elsewhere. */
+export function current() {
+    return parse(globalThis.__SMARTLINKS_SITE__);
+}
 /**
- * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
- * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
- * without it, it waits for the network to go idle (capped). Call once per page, after your data
- * renders. Harmless anywhere else.
+ * @deprecated Sites are server-rendered: crawlers get the finished page from the server, so nothing
+ * waits for this signal any more. Kept as a harmless no-op signal for older pages.
  */
 export function ready() {
     if (typeof globalThis === 'undefined')

package/dist/types/appManifest.d.ts

@@ -2,7 +2,6 @@
 /// <reference types="node" />
 import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
 import type { RealtimeChannelDeclaration } from './realtime.js';
-import type { FieldMapping } from './integrations.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -831,7 +830,9 @@ export interface AppManifest {
     /**
      * This app is an integration CONNECTOR for one external provider (Syndigo, OneWorldSync, …): the
      * integrations console lists it, draws its connect form and settings, and the integration engine
-     * calls its server functions to test, describe, sample, transform, send and fetch.
+     * calls its server functions to test, describe, sample, shape, serialize, send and fetch. The
+     * customer's mapping is NOT the connector's job: core maps between the connector's provider-neutral
+     * documents and SmartLinks (docs/connectors.md).
      * @see AppConnectorDeclaration · docs/connectors.md
      */
     connector?: AppConnectorDeclaration;
@@ -877,6 +878,9 @@ export interface ConnectorPanel {
  * The connector contract. Every function named here is one of this app's server functions
  * (manifest `functions.definitions`); the engine calls it with collection authority, capped by the
  * capabilities the function declares. A connector fills in only what it needs.
+ *
+ * A connector is an ADAPTER: it talks to the provider and converts between the provider's format and
+ * a clean, provider-neutral document. Each customer's mapping, routing and rules live in core.
  */
 export interface AppConnectorDeclaration {
     /** Stable provider key, e.g. 'syndigo', 'oneworldsync'. */
@@ -892,6 +896,7 @@ export interface AppConnectorDeclaration {
     };
     /** Per-installation settings: a JSON Schema the console renders as a form. */
     settings?: Record<string, unknown>;
+    /** Ready-made flows; a preset's `flow.config.fieldMappings` is a suggested mapping the customer can edit. */
     presets?: ConnectorPreset[];
     /** Names of this app's server functions implementing each step. */
     functions: {
@@ -901,8 +906,18 @@ export interface AppConnectorDeclaration {
         describeTarget?: string;
         /** → ConnectorRecords: real records for the mapper, the AI assistant and dry runs (inbound). */
         sample?: string;
-        /** (ConnectorTransformInput) → ConnectorTransformResult. Must be deterministic — no AI at run time. */
-        transform?: string;
+        /**
+         * Inbound: (ConnectorShapeInput) → ConnectorShapeResult. Provider records → provider-neutral
+         * documents, the same for every customer (no customer mapping). Deterministic — no AI, network or
+         * clock. Omit to hand core the provider records as they are.
+         */
+        shape?: string;
+        /**
+         * Outbound: (ConnectorSerializeInput) → ConnectorSerializeResult. Documents core has mapped to this
+         * provider's fields (`describeTarget` paths) → the provider's wire format (an envelope, a batch).
+         * Deterministic. Omit to send the mapped documents as they are.
+         */
+        serialize?: string;
         /** (ConnectorSendInput) → ConnectorSendResult. Omit to use a generic transport (HTTP, Event Hub). */
         send?: string;
         /** (ConnectorFetchInput) → ConnectorRecords: inbound pull, one page per call. */
@@ -911,6 +926,16 @@ export interface AppConnectorDeclaration {
     panels?: ConnectorPanel[];
     /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
     aiGuide?: string;
+    /**
+     * Path of the provider's own id in a fetched record (e.g. 'gtin', 'item.id'). Inbound records are
+     * landed and matched to SmartLinks entities by it, so a re-import updates rather than duplicates.
+     * Default 'id'; a flow can override it with `config.upsert.externalIdPath`.
+     */
+    recordId?: string;
+    /** Requests per second toward the provider, shared by every SmartLinks worker. */
+    limits?: {
+        requestsPerSecond?: number;
+    };
 }
 /**
  * What every connector function receives about the installation it serves. The engine assembles it
@@ -951,15 +976,31 @@ export interface ConnectorRecords {
     /** Inbound paging: pass back to the next fetch; absent when there's no more. */
     nextCursor?: string | null;
 }
-export interface ConnectorTransformInput {
+/** Inbound: provider records, as fetch / sample returned them. */
+export interface ConnectorShapeInput {
     installation: ConnectorInstallation;
-    /** SmartLinks records (outbound) or provider records (inbound). */
     records: Array<Record<string, unknown>>;
-    /** The flow's saved mapping (`config.fieldMappings`) — the same shape the engine's mapper runs. */
-    mapping: FieldMapping[];
 }
-export interface ConnectorTransformResult {
-    /** One payload per input record, in the same order (null = skip that record, with a reason). */
+export interface ConnectorShapeResult {
+    /** One provider-neutral document per record, in the same order (null = skip it, with a reason). */
+    documents: Array<Record<string, unknown> | null>;
+    skipped?: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+/**
+ * Outbound: documents core has mapped to this provider's fields (keyed by `describeTarget` paths).
+ * A deleted SmartLinks entity arrives as `{ id, _deleted: true }`.
+ */
+export interface ConnectorSerializeInput {
+    installation: ConnectorInstallation;
+    documents: Array<Record<string, unknown>>;
+    /** The event that triggered the run, e.g. 'product.updated' (absent for manual / scheduled runs). */
+    eventType?: string;
+}
+export interface ConnectorSerializeResult {
+    /** One provider payload per document, in the same order (null = skip it, with a reason). */
     payloads: Array<unknown | null>;
     skipped?: Array<{
         index: number;
@@ -977,6 +1018,10 @@ export interface ConnectorSendResult {
         status?: number;
         error?: string;
         externalId?: string;
+        /** Worth retrying? Default: by status (408/425/429/5xx/none yes; other 4xx no). */
+        retryable?: boolean;
+        /** The provider asked to wait this long before retrying (e.g. its Retry-After). */
+        retryAfterSeconds?: number;
     }>;
 }
 export interface ConnectorFetchInput {

package/dist/types/integrations.d.ts

@@ -71,6 +71,32 @@ export interface IntegrationFlow {
     lastPollAt?: string | null;
     lastCursor?: string | null;
     totalSynced?: number | null;
+    /**
+     * Circuit breaker: set while the flow has paused itself because its destination / provider keeps
+     * failing. Nothing is sent or fetched (edits are held as retries) until a probe gets through —
+     * `circuitProbeAt` is the next one — or someone resumes it (`integrations.resumeFlow`).
+     */
+    circuitOpenedAt?: string | null;
+    circuitProbeAt?: string | null;
+    circuitReason?: string | null;
+}
+/** A record that failed: retried on its own with backoff ('failed'), or given up on ('dead'). */
+export interface FailedRecord {
+    /** Outbound: the SmartLinks entity id. Inbound: the landed record's id (pass it to retryFailed). */
+    id: string;
+    entityId?: string | null;
+    /** Inbound: the provider's id for the record. */
+    externalId?: string;
+    status: 'failed' | 'dead';
+    attempts: number;
+    nextAttemptAt?: string | null;
+    lastError?: string | null;
+    updatedAt?: string;
+}
+export interface FailedRecordList {
+    direction: FlowDirection;
+    items: FailedRecord[];
+    nextCursor: string | null;
 }
 export interface CreateFlowInput {
     appId: string;
@@ -109,10 +135,12 @@ export interface RunFlowSummary {
     /** Outbound: records delivered. */
     sent?: number;
     failed: number;
-    /** Inbound: products created / updated, and records the connector skipped. */
+    /** Inbound: products created / updated, and records the connector skipped (outbound: unchanged). */
     created?: number;
     updated?: number;
     skipped?: number;
+    /** Outbound: changes held because the destination is paused (circuit open); sent after it recovers. */
+    held?: number;
     status: RunStatus;
     /** Id of the persisted run row (deep-link into its detail). */
     runId?: string;
@@ -141,8 +169,8 @@ export interface SaveConnectorInstallationInput {
     connection?: Record<string, unknown>;
     settings?: Record<string, unknown>;
 }
-/** Steps the console may run directly (send and fetch only run inside a flow). */
-export type ConnectorConsoleStep = 'testConnection' | 'describeTarget' | 'sample' | 'transform';
+/** Steps the console may run directly (send and fetch only run inside a flow; shape/serialize as dry runs). */
+export type ConnectorConsoleStep = 'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize';
 export type RunTrigger = 'manual' | 'event' | 'schedule' | 'test';
 export type FlowRunStatus = 'running' | 'success' | 'partial' | 'failed' | 'skipped';
 export type FlowRunItemStatus = 'sent' | 'failed' | 'skipped';