@proveanything/smartlinks 2.0.56 → 2.0.58

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

@@ -827,8 +827,194 @@ export interface AppManifest {
      * provider). Validated by `smartlinks-headless`. @see AppHeadlessDeclaration
      */
     headless?: AppHeadlessDeclaration;
+    /**
+     * 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, 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;
     [key: string]: any;
 }
+/** One field of a connector's "Connect" form. */
+export interface ConnectorConnectionField {
+    /** Key in the installation's connection settings (non-secret fields) — `name` for a secret too. */
+    name: string;
+    label: string;
+    description?: string;
+    /** Store the value as this app's SECRET of this name (sealed, write-only; the function reads it with
+     *  `ctx.secrets.get(secret)`), never in the settings. Declare `secrets:<name>` on the functions. */
+    secret?: string;
+    required?: boolean;
+    /** Input hint for the form. Default 'text'. */
+    type?: 'text' | 'url' | 'select' | 'number' | 'boolean';
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    placeholder?: string;
+}
+/** A ready-made flow a connector offers ("Products → Syndigo"). */
+export interface ConnectorPreset {
+    id: string;
+    title: string;
+    description?: string;
+    direction: 'inbound' | 'outbound';
+    /** SmartLinks entity: outbound source / inbound target. */
+    entity: string;
+    /** Defaults for the flow (event types, schedule, mapping, settings…). */
+    flow?: Record<string, unknown>;
+}
+/** A panel the connector contributes to the integrations console (e.g. an API explorer). */
+export interface ConnectorPanel {
+    id: string;
+    title: string;
+    /** Exported component name in the app's widgets bundle (manifest `widgets.files`). */
+    component: string;
+}
+/**
+ * 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'. */
+    provider: string;
+    /** Display name of the provider ("1WorldSync"). Defaults to the app name. */
+    title?: string;
+    directions: Array<'inbound' | 'outbound'>;
+    /** SmartLinks entities it maps, e.g. ['product']. */
+    entities: string[];
+    /** The console's "Connect" form. */
+    connection?: {
+        fields: ConnectorConnectionField[];
+    };
+    /** 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: {
+        /** → ConnectorTestResult. */
+        testConnection?: string;
+        /** → ConnectorTargetSchema: the provider's fields for THIS customer (the mapper's right-hand side). */
+        describeTarget?: string;
+        /** → ConnectorRecords: real records for the mapper, the AI assistant and dry runs (inbound). */
+        sample?: 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. */
+        fetch?: string;
+    };
+    panels?: ConnectorPanel[];
+    /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
+    aiGuide?: string;
+}
+/**
+ * What every connector function receives about the installation it serves. The engine assembles it
+ * from the connector app's config on the collection (`connector.connection` / `connector.settings`)
+ * with the flow's `config.connector.settings` layered on top.
+ */
+export interface ConnectorInstallation {
+    collectionId: string;
+    /** The connector app. */
+    appId: string;
+    /** The flow being run / configured, when there is one. */
+    flowId?: string | null;
+    /** Non-secret connection fields (secrets are read with ctx.secrets.get). */
+    connection: Record<string, unknown>;
+    /** Installation settings, overridden per flow. */
+    settings: Record<string, unknown>;
+}
+export interface ConnectorTestResult {
+    ok: boolean;
+    /** Shown to the admin: "Connected as …" or what's wrong. */
+    message: string;
+}
+export interface ConnectorTargetField {
+    /** Path in the provider payload, e.g. 'attributes.brandName'. */
+    path: string;
+    label?: string;
+    type?: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+    required?: boolean;
+    description?: string;
+    /** Allowed values, when the provider fixes them. */
+    enum?: string[];
+}
+export interface ConnectorTargetSchema {
+    fields: ConnectorTargetField[];
+}
+export interface ConnectorRecords {
+    records: Array<Record<string, unknown>>;
+    /** Inbound paging: pass back to the next fetch; absent when there's no more. */
+    nextCursor?: string | null;
+}
+/** Inbound: provider records, as fetch / sample returned them. */
+export interface ConnectorShapeInput {
+    installation: ConnectorInstallation;
+    records: Array<Record<string, unknown>>;
+}
+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;
+        reason: string;
+    }>;
+}
+export interface ConnectorSendInput {
+    installation: ConnectorInstallation;
+    payloads: unknown[];
+}
+export interface ConnectorSendResult {
+    results: Array<{
+        index: number;
+        ok: boolean;
+        status?: number;
+        error?: string;
+        externalId?: string;
+    }>;
+}
+export interface ConnectorFetchInput {
+    installation: ConnectorInstallation;
+    cursor?: string | null;
+    limit?: number;
+}
 /**
  * One app entry in the collection widgets response.
  */

package/dist/types/integrations.d.ts

@@ -29,9 +29,20 @@ export interface FlowConnection {
     defaultHeaders?: Record<string, string>;
     auth?: FlowConnectionAuth;
 }
+/** A flow driven by a connector app (docs/connectors.md). */
+export interface FlowConnectorRef {
+    /** The connector app (manifest `connector` block), installed on the collection. */
+    appId: string;
+    /** The preset the flow was created from, if any. */
+    preset?: string;
+    /** Per-flow settings, layered over the installation's. */
+    settings?: Record<string, unknown>;
+}
 export interface IntegrationFlowConfig {
     connection?: FlowConnection;
     fieldMappings?: FieldMapping[];
+    /** Run this flow through a connector app's functions instead of the built-in mapper/transport. */
+    connector?: FlowConnectorRef;
     [key: string]: any;
 }
 export interface IntegrationFlow {
@@ -95,12 +106,43 @@ export interface RunFlowSummary {
     flowId: string;
     direction: FlowDirection;
     records: number;
-    sent: number;
+    /** Outbound: records delivered. */
+    sent?: number;
     failed: number;
+    /** Inbound: products created / updated, and records the connector skipped. */
+    created?: number;
+    updated?: number;
+    skipped?: number;
     status: RunStatus;
     /** Id of the persisted run row (deep-link into its detail). */
     runId?: string;
 }
+/** One installed connector app, as the integrations console sees it. */
+export interface InstalledConnector {
+    appId: string;
+    name: string;
+    /** The release channel installed on this collection. */
+    channel: string;
+    version: string | null;
+    connector: import('./appManifest.js').AppConnectorDeclaration;
+    /** Non-secret Connect-form values + installation settings. */
+    installation: {
+        connection: Record<string, unknown>;
+        settings: Record<string, unknown>;
+    };
+    /** Each secret the Connect form declares: whether it is set (+ masked hint). Never a value. */
+    secrets: Record<string, {
+        set: boolean;
+        hint?: string | null;
+    }>;
+}
+export interface SaveConnectorInstallationInput {
+    /** Non-secret fields only; secret fields are set with `secrets.put` for the connector's appId. */
+    connection?: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+/** 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';

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.56  |  Generated: 2026-10-12T20:58:59.335Z
+Version: 2.0.58  |  Generated: 2026-10-13T14:08:01.791Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,6 +65,7 @@ For detailed guides on specific features:
 - **[Analytics Metadata Conventions](analytics-metadata-conventions.md)** - Standard recommended keys and conventions for analytics metadata fields
 - **[Loyalty: Points, Members & Earning Rules](loyalty.md)** - Loyalty schemes, automatic point earning via interaction rules, member balances, transaction history, and manual adjustments
 - **[Integrations](integrations.md)** - Inbound/outbound integration flows + the sealed-secret store; triggers (manual/event/schedule), field mappings, and the Syndigo/Event Hub outbound path
+- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send); core does the mapping
 - **[AI Tools & Skills](ai-tools-and-skills.md)** - The AI capability catalog: skills apps invoke by name (e.g. research.brand), the tools the AI reaches for (web fetch/screenshot/brand assets/image gen), the agent loop, and how apps discover them
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
@@ -2853,10 +2854,173 @@ interface AppManifest {
   realtime?: { channels: RealtimeChannelDeclaration[] };
   data?: AppDataDeclaration;
   headless?: AppHeadlessDeclaration;
+  connector?: AppConnectorDeclaration;
   [key: string]: any;
 }
 ```
 
+**ConnectorConnectionField** (interface)
+```typescript
+interface ConnectorConnectionField {
+  name: string
+  label: string
+  description?: string
+  secret?: string
+  required?: boolean
+  type?: 'text' | 'url' | 'select' | 'number' | 'boolean'
+  options?: Array<{ value: string; label: string }>
+  placeholder?: string
+}
+```
+
+**ConnectorPreset** (interface)
+```typescript
+interface ConnectorPreset {
+  id: string
+  title: string
+  description?: string
+  direction: 'inbound' | 'outbound'
+  entity: string
+  flow?: Record<string, unknown>
+}
+```
+
+**ConnectorPanel** (interface)
+```typescript
+interface ConnectorPanel {
+  id: string
+  title: string
+  component: string
+}
+```
+
+**AppConnectorDeclaration** (interface)
+```typescript
+interface AppConnectorDeclaration {
+  provider: string
+  title?: string
+  directions: Array<'inbound' | 'outbound'>
+  entities: string[]
+  connection?: { fields: ConnectorConnectionField[] }
+  settings?: Record<string, unknown>
+  presets?: ConnectorPreset[]
+  functions: {
+  testConnection?: string
+  describeTarget?: string
+  sample?: string
+  shape?: string
+  serialize?: string
+  send?: string
+  fetch?: string
+  }
+  panels?: ConnectorPanel[]
+  aiGuide?: string
+}
+```
+
+**ConnectorInstallation** (interface)
+```typescript
+interface ConnectorInstallation {
+  collectionId: string
+  appId: string
+  flowId?: string | null
+  connection: Record<string, unknown>
+  settings: Record<string, unknown>
+}
+```
+
+**ConnectorTestResult** (interface)
+```typescript
+interface ConnectorTestResult {
+  ok: boolean
+  message: string
+}
+```
+
+**ConnectorTargetField** (interface)
+```typescript
+interface ConnectorTargetField {
+  path: string
+  label?: string
+  type?: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array'
+  required?: boolean
+  description?: string
+  enum?: string[]
+}
+```
+
+**ConnectorTargetSchema** (interface)
+```typescript
+interface ConnectorTargetSchema {
+  fields: ConnectorTargetField[]
+}
+```
+
+**ConnectorRecords** (interface)
+```typescript
+interface ConnectorRecords {
+  records: Array<Record<string, unknown>>
+  nextCursor?: string | null
+}
+```
+
+**ConnectorShapeInput** (interface)
+```typescript
+interface ConnectorShapeInput {
+  installation: ConnectorInstallation
+  records: Array<Record<string, unknown>>
+}
+```
+
+**ConnectorShapeResult** (interface)
+```typescript
+interface ConnectorShapeResult {
+  documents: Array<Record<string, unknown> | null>
+  skipped?: Array<{ index: number; reason: string }>
+}
+```
+
+**ConnectorSerializeInput** (interface)
+```typescript
+interface ConnectorSerializeInput {
+  installation: ConnectorInstallation
+  documents: Array<Record<string, unknown>>
+  eventType?: string
+}
+```
+
+**ConnectorSerializeResult** (interface)
+```typescript
+interface ConnectorSerializeResult {
+  payloads: Array<unknown | null>
+  skipped?: Array<{ index: number; reason: string }>
+}
+```
+
+**ConnectorSendInput** (interface)
+```typescript
+interface ConnectorSendInput {
+  installation: ConnectorInstallation
+  payloads: unknown[]
+}
+```
+
+**ConnectorSendResult** (interface)
+```typescript
+interface ConnectorSendResult {
+  results: Array<{ index: number; ok: boolean; status?: number; error?: string; externalId?: string }>
+}
+```
+
+**ConnectorFetchInput** (interface)
+```typescript
+interface ConnectorFetchInput {
+  installation: ConnectorInstallation
+  cursor?: string | null
+  limit?: number
+}
+```
+
 **CollectionAppWidget** (interface)
 ```typescript
 interface CollectionAppWidget {
@@ -6899,11 +7063,21 @@ interface FlowConnection {
 }
 ```
 
+**FlowConnectorRef** (interface)
+```typescript
+interface FlowConnectorRef {
+  appId: string
+  preset?: string
+  settings?: Record<string, unknown>
+}
+```
+
 **IntegrationFlowConfig** (interface)
 ```typescript
 interface IntegrationFlowConfig {
   connection?: FlowConnection
   fieldMappings?: FieldMapping[]
+  connector?: FlowConnectorRef
   [key: string]: any
 }
 ```
@@ -6982,13 +7156,37 @@ interface RunFlowSummary {
   flowId: string
   direction: FlowDirection
   records: number
-  sent: number
+  sent?: number
   failed: number
+  created?: number
+  updated?: number
+  skipped?: number
   status: RunStatus
   runId?: string
 }
 ```
 
+**InstalledConnector** (interface)
+```typescript
+interface InstalledConnector {
+  appId: string
+  name: string
+  channel: string
+  version: string | null
+  connector: import('./appManifest').AppConnectorDeclaration
+  installation: { connection: Record<string, unknown>; settings: Record<string, unknown> }
+  secrets: Record<string, { set: boolean; hint?: string | null }>
+}
+```
+
+**SaveConnectorInstallationInput** (interface)
+```typescript
+interface SaveConnectorInstallationInput {
+  connection?: Record<string, unknown>
+  settings?: Record<string, unknown>
+}
+```
+
 **CapturedRequest** (interface)
 ```typescript
 interface CapturedRequest {
@@ -7193,6 +7391,8 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize'`
+
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
 
 **FlowRunStatus** = `'running' | 'success' | 'partial' | 'failed' | 'skipped'`
@@ -11507,6 +11707,20 @@ Enable enhanced logging. POST /integrations/logging/:connectionId (omit ttlMinut
 **cancelLogging**(collectionId: string, connectionId: string) → `Promise<`
 Cancel enhanced logging now. DELETE /integrations/logging/:connectionId
 
+**listConnectors**(collectionId: string) → `Promise<`
+The collection's installed connector apps. GET /integrations/connectors
+
+**saveConnectorInstallation**(collectionId: string,
+    appId: string,
+    input: SaveConnectorInstallationInput) → `Promise<`
+Save a connector's non-secret Connect-form values and/or settings. PUT /integrations/connectors/:appId/installation
+
+**runConnectorStep**(collectionId: string,
+    appId: string,
+    step: ConnectorConsoleStep,
+    input: Record<string, unknown> & { flowId?: string } = {}) → `Promise<T>`
+Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, and dry runs of `shape` ({ records }) → ConnectorShapeResult and `serialize` ({ documents }) → ConnectorSerializeResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
+
 ### interactions
 
 **query**(collectionId: string,

package/docs/app-manifest.md

@@ -436,6 +436,13 @@ this is just the manifest shape.
 | `definitions[].authority` | string | `caller` \| `collection` — whose authority it runs as |
 | `definitions[].capabilities` | string[] | Least-privilege grants (`sl:<res>:<read\|write>`, `network[:<host>]`, `secrets:<ref>`) |
 
+#### `connector`
+
+Marks the app as an integration **connector** for one external provider: the integrations console
+lists it and draws its connect form and settings, and the integration engine calls its server
+functions (`testConnection`, `describeTarget`, `sample`, `fetch`, `shape`, `serialize`, `send`). It adapts the provider's format; core does each customer's mapping. The full
+contract is in the **[Connectors guide](connectors.md)**.
+
 ---
 
 ## `app.admin.json`