@proveanything/smartlinks 2.0.57 → 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

@@ -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. */
@@ -951,15 +966,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;

package/dist/types/integrations.d.ts

@@ -141,8 +141,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';

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.57  |  Generated: 2026-10-13T11:42:19.247Z
+Version: 2.0.58  |  Generated: 2026-10-13T14:08:01.791Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,7 +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: a manifest `connector` block + server functions (testConnection/describeTarget/sample/transform/send/fetch) that the integration engine and console call for one external provider
+- **[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
@@ -2908,7 +2908,8 @@ interface AppConnectorDeclaration {
   testConnection?: string
   describeTarget?: string
   sample?: string
-  transform?: string
+  shape?: string
+  serialize?: string
   send?: string
   fetch?: string
   }
@@ -2963,18 +2964,34 @@ interface ConnectorRecords {
 }
 ```
 
-**ConnectorTransformInput** (interface)
+**ConnectorShapeInput** (interface)
 ```typescript
-interface ConnectorTransformInput {
+interface ConnectorShapeInput {
   installation: ConnectorInstallation
   records: Array<Record<string, unknown>>
-  mapping: FieldMapping[]
 }
 ```
 
-**ConnectorTransformResult** (interface)
+**ConnectorShapeResult** (interface)
 ```typescript
-interface ConnectorTransformResult {
+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 }>
 }
@@ -7374,7 +7391,7 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
-**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'transform'`
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize'`
 
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
 
@@ -11702,7 +11719,7 @@ Save a connector's non-secret Connect-form values and/or settings. PUT /integrat
     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, `transform` (a dry run) → ConnectorTransformResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
+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
 

package/docs/app-manifest.md

@@ -440,7 +440,7 @@ this is just the manifest shape.
 
 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`, `transform`, `send`, `fetch`). The full
+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)**.
 
 ---

package/docs/connectors.md

@@ -9,16 +9,22 @@ Three layers, each with one job:
 
 | Layer | Holds |
 |---|---|
-| **Engine** (the API) | [Integration flows](integrations.md), runs and their logs, triggers (events, schedule, Run now), the secret store, the deterministic field mapper, generic transports (HTTP, Event Hub). No provider code. |
+| **Engine** (the API) | [Integration flows](integrations.md), runs and their logs, triggers (events, schedule, Run now), the secret store, **the mapping** (each customer's field mappings and rules), generic transports (HTTP, Event Hub). No provider code. |
 | **Integrations console** (a core app) | The one admin screen: installed connectors, connect forms, settings, the mapper with AI assist, flows, runs. |
-| **Connector apps** | One per provider: its connect form, settings, target schema, transform, send/fetch, and any provider-specific panels. |
+| **Connector apps** | One per provider: an **adapter**. Talks to the provider and converts between its format and a clean, provider-neutral document. |
+
+**A connector adapts; core maps.** A connector never holds a customer's mapping. It turns the
+provider's records into provider-neutral documents (`shape`), or provider-ready payloads out of
+documents core has already mapped (`serialize`). Every customer's mapping, routing and rules live in
+core, so they work the same for every provider and can be replayed and traced. This is the line
+SnapLogic (endpoint Snaps vs the Mapper), MuleSoft and Airbyte all draw.
 
 A flow that only posts JSON to a webhook or an Event Hub needs no connector; it uses the engine's
 generic transports (see [integrations.md](integrations.md)).
 
 **No AI at run time.** The AI helps an admin *author* a mapping in the console (from the connector's
 target schema plus real sample records); a person approves it, and it is saved as data and runs
-deterministically. A connector's `transform` must be deterministic too.
+deterministically. A connector's `shape` and `serialize` must be deterministic too.
 
 ---
 
@@ -33,8 +39,10 @@ deterministically. A connector's `transform` must be deterministic too.
   "entities": ["product"],
   "connection": {
     "fields": [
-      { "name": "appId",     "label": "App ID",     "secret": "oneworldsync-app-id",     "required": true },
-      { "name": "secretKey", "label": "Secret key", "secret": "oneworldsync-secret-key", "required": true },
+      // Optional: SmartLinks' own credentials are the default; a customer may enter theirs.
+      { "name": "appId",     "label": "App ID",     "secret": "oneworldsync-app-id" },
+      { "name": "secretKey", "label": "Secret key", "secret": "oneworldsync-secret-key" },
+      { "name": "gln", "label": "GLN", "required": true },
       { "name": "environment", "label": "Environment", "type": "select",
         "options": [ { "value": "preprod", "label": "Pre-production" }, { "value": "production", "label": "Production" } ] }
     ]
@@ -44,12 +52,14 @@ deterministically. A connector's `transform` must be deterministic too.
     "properties": { "targetMarket": { "type": "string", "default": "GB" } }
   },
   "presets": [
-    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product" }
+    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product",
+      "flow": { "config": { "fieldMappings": [ /* a suggested mapping the customer can edit */ ] } } }
   ],
   "functions": {                      // names of this app's server functions
     "testConnection": "testConnection",
     "describeTarget": "describeTarget",
     "sample": "sample",
+    "shape": "shape",
     "fetch": "fetch"
   },
   "panels": [ { "id": "explorer", "title": "Explorer", "component": "Explorer" } ],
@@ -74,9 +84,9 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `title` | Provider display name; defaults to the app name. |
 | `directions` | `inbound` (provider → SmartLinks), `outbound` (SmartLinks → provider), or both. |
 | `entities` | SmartLinks entities it maps, e.g. `["product"]`. |
-| `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
+| `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name on the collection (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
 | `settings` | JSON Schema for installation settings; the console renders it as a form. |
-| `presets[]` | Ready-made flows ("Products → provider") with flow defaults. |
+| `presets[]` | Ready-made flows ("Products → provider"). A preset's `flow.config.fieldMappings` is a **suggested** mapping: the connector's knowledge of the provider, which the customer accepts or edits in core. |
 | `functions` | Which of this app's server functions implement each step (below). Fill in only what applies. |
 | `panels[]` | Provider-specific screens the console mounts (an API explorer, a status page). |
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
@@ -87,28 +97,37 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 
 Each step names one of the app's server functions. Declare them as **http POST, `visibility:
 "admin"`, `authority: "collection"`**: the engine calls them with no signed-in user (a product edit, a
-schedule), and the console calls the same functions while an admin configures the flow
-(`functions.callAdmin(collectionId, name, input, { appId })`). The input arrives as `event.body`;
-return the result as JSON. Capabilities still cap what each one can do: declare the provider's hosts
-(`network:<host>`) and the secrets it reads (`secrets:<name>`).
+schedule), and the console calls the same functions while an admin configures the flow. The input
+arrives as `event.body`; return the result as JSON. Capabilities still cap what each one can do:
+declare the provider's hosts (`network:<host>`) and the secrets it reads (`secrets:<name>`).
 
 | Step | Called by | Input (`event.body`) | Returns |
 |---|---|---|---|
 | `testConnection` | Connect form, **Test** | `{ installation }` | `ConnectorTestResult` `{ ok, message }` |
-| `describeTarget` | Mapper opens | `{ installation }` | `ConnectorTargetSchema` `{ fields: [{ path, label, type, required, enum }] }`: the provider's fields *for this customer* |
+| `describeTarget` | Mapper opens | `{ installation }` | `ConnectorTargetSchema` `{ fields: [{ path, label, type, required, enum }] }`: the provider's fields *for this customer*. Outbound mappings target these paths. |
 | `sample` | Mapper, AI assist, dry run | `{ installation, limit }` | `ConnectorRecords` `{ records }`: real provider records |
-| `transform` | Every run | `ConnectorTransformInput` `{ installation, records, mapping }` | `ConnectorTransformResult` `{ payloads, skipped }`: one payload per record, same order; `null` skips one |
-| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
 | `fetch` | Every inbound run | `ConnectorFetchInput` `{ installation, cursor, limit }` | `ConnectorRecords` `{ records, nextCursor }`: one page per call |
+| `shape` | Every inbound run (and sample dry runs) | `ConnectorShapeInput` `{ installation, records }` | `ConnectorShapeResult` `{ documents, skipped }`: one provider-neutral document per record, same order; `null` skips one |
+| `serialize` | Every outbound run | `ConnectorSerializeInput` `{ installation, documents, eventType? }`: documents core mapped to `describeTarget` paths; a deletion arrives as `{ id, _deleted: true }` | `ConnectorSerializeResult` `{ payloads, skipped }`: one provider payload per document, same order; `null` skips one |
+| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
 
-What happens when a step is left out:
+**How a run flows:**
+- **Inbound:** `fetch` (paged) → `shape` → core maps the documents with the flow's mapping → upsert.
+- **Outbound:** gather the SmartLinks records → core maps them to the provider's fields → `serialize`
+  → `send` (or a generic transport).
 
-- **No `transform`:** the engine's own mapper runs the flow's `fieldMappings` (direct, static, Liquid
-  template).
-- **No `send`:** the flow's own transport: HTTP (`config.connection`), or Azure Event Hub with
+**What happens when a step is left out:**
+- **No `shape`:** core maps the provider records as they come.
+- **No `serialize`:** the mapped documents are sent as they are.
+- **No `send`:** the flow's own transport is used: HTTP (`config.connection`), or Azure Event Hub with
   `config.transport: 'eventhub'` and `config.eventHub`.
 - **No `describeTarget`:** the mapper offers free-text target paths.
 
+**What `shape` should produce:** plain, predictable JSON a person can map without reading the
+provider's documentation. Flatten the provider's envelopes, name things plainly, keep codes alongside
+their meanings, and put repeated sections (ingredients, allergens, nutrients, images) in arrays. The
+same provider record always gives the same document.
+
 ### `installation`
 
 Every step receives the installation it serves:
@@ -124,13 +143,15 @@ interface ConnectorInstallation {
 ```
 
 Secrets are never in it. Read them in the function with `ctx.secrets.get('<name>')`, which needs the
-matching `secrets:<name>` capability.
+matching `secrets:<name>` capability. A secret the customer set on their collection wins; otherwise the
+connector's own app-level secret of that name (set in Forge) is used, so a connector can ship with
+SmartLinks' credentials as the default.
 
-### Example: `fetch`
+### Example: `fetch` and `shape`
 
 ```ts
 // src/functions/index.ts (the app's functions bundle)
-import type { ConnectorFetchInput, ConnectorRecords } from '@proveanything/smartlinks'
+import type { ConnectorFetchInput, ConnectorRecords, ConnectorShapeInput, ConnectorShapeResult } from '@proveanything/smartlinks'
 
 export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
   const { installation, cursor, limit = 50 } = event.body as ConnectorFetchInput
@@ -140,6 +161,18 @@ export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
   const page = await res.json()
   return { records: page.items, nextCursor: page.next ?? null }
 }
+
+export async function shape(_ctx: any, event: any): Promise<ConnectorShapeResult> {
+  const { records } = event.body as ConnectorShapeInput
+  return {
+    documents: records.map((r: any) => ({
+      gtin: r.item?.gtin,
+      name: r.item?.tradeItemDescription?.[0]?.value,
+      brand: r.item?.brandName,
+      ingredients: (r.item?.ingredients ?? []).map((i: any) => ({ name: i.name, percent: i.percentage })),
+    })),
+  }
+}
 ```
 
 ---
@@ -148,9 +181,9 @@ export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
 
 | What | Where |
 |---|---|
-| Connect-form values (non-secret), installation settings | The connector app's config on the collection: `appConfiguration` for `appId`, under `connector.connection` and `connector.settings`. |
-| Credentials | The connector app's secrets, by the names its fields declare. |
-| One flow's use of the connector | The flow: `config.connector = { appId, preset?, settings? }` (per-flow settings override the installation's), plus `config.fieldMappings`. |
+| Connect-form values (non-secret), installation settings | The connector app's config on the collection, in its admin-only zone (`admin.connector.connection`, `admin.connector.settings`). |
+| Credentials | The connector app's secrets, by the names its fields declare (the customer's on their collection, else the connector's default). |
+| One flow's use of the connector | The flow: `config.connector = { appId, preset?, settings? }` (per-flow settings override the installation's), plus `config.fieldMappings`, which core runs. |
 
 ```ts
 await integrations.createFlow(collectionId, {
@@ -162,7 +195,8 @@ await integrations.createFlow(collectionId, {
   targetEntity: 'product',
   config: {
     connector: { appId: 'oneworldsync', preset: 'import-products' },
-    fieldMappings: [ { targetPath: 'name', sourcePath: 'item.tradeItemDescription', transformType: 'direct' } ],
+    // Maps the connector's shaped documents (not the raw provider records) onto the product.
+    fieldMappings: [ { targetPath: 'name', sourcePath: 'name', transformType: 'direct' } ],
   },
 })
 ```
@@ -181,7 +215,9 @@ await secrets.put(collectionId, 'provider-key', value, { appId })              /
 await integrations.saveConnectorInstallation(collectionId, appId, { connection: { environment: 'production' } })
 const test = await integrations.runConnectorStep(collectionId, appId, 'testConnection')
 const target = await integrations.runConnectorStep(collectionId, appId, 'describeTarget')
-const dryRun = await integrations.runConnectorStep(collectionId, appId, 'transform', { records, mapping })
+const { records } = await integrations.runConnectorStep(collectionId, appId, 'sample', { limit: 5 })
+const shaped = await integrations.runConnectorStep(collectionId, appId, 'shape', { records })      // dry run
+const wire = await integrations.runConnectorStep(collectionId, appId, 'serialize', { documents })  // dry run
 ```
 
 `send` and `fetch` only run inside a flow. A flow run's summary carries `sent` (outbound) or
@@ -192,8 +228,9 @@ const dryRun = await integrations.runConnectorStep(collectionId, appId, 'transfo
 ## Panels
 
 A connector can contribute screens to the integrations console (an API explorer, say). Each
-`panels[]` entry names a component exported from the app's widgets bundle; the console mounts it host-side and passes it the
-collection and the installation. Panels are admin-only and call the connector's own functions.
+`panels[]` entry names a component exported from the app's widgets bundle; the console mounts it
+host-side and passes it the collection and the installation. Panels are admin-only and call the
+connector's own functions.
 
 ---