@proveanything/smartlinks 2.0.55 → 2.0.57

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). */
+export type ConnectorConsoleStep = 'testConnection' | 'describeTarget' | 'sample' | 'transform';
 export type RunTrigger = 'manual' | 'event' | 'schedule' | 'test';
 export type FlowRunStatus = 'running' | 'success' | 'partial' | 'failed' | 'skipped';
 export type FlowRunItemStatus = 'sent' | 'failed' | 'skipped';

package/dist/types/realtime.d.ts

@@ -42,3 +42,47 @@ export interface AblyTokenRequest {
  *   - collection:abc:users:active
  */
 export type RealtimeChannelPattern = string;
+/** Where a realtime listener lives: the collection, and (for app channels) the app. */
+export interface RealtimeScope {
+    collectionId: string;
+    appId?: string;
+}
+/** A message on a channel. `channel` is the logical name ("draw", "feed:admin"). */
+export interface RealtimeMessage {
+    channel: string;
+    event: string;
+    data: unknown;
+    /** When it was sent (ms since epoch), when known. */
+    at?: number;
+}
+/** "This changed" — ids only; refetch through the normal API. */
+export interface RealtimeChangeEvent {
+    /** 'product' | 'proof' | 'asset' | 'record' | 'collection' | 'collection.apps' | 'settings' | … */
+    type: string;
+    id?: string;
+    appId?: string;
+    recordType?: string;
+    productId?: string;
+    proofId?: string;
+    /** 'created' | 'updated' | 'deleted' (records) or 'create' | 'update' | 'delete' (products, proofs…) */
+    status?: string;
+    at: number;
+}
+/** Which changes to hear about — every field given must match. */
+export interface RealtimeChangeFilter {
+    type?: string;
+    id?: string;
+    appId?: string;
+    recordType?: string;
+    productId?: string;
+    proofId?: string;
+}
+/** A channel an app declares in its manifest (`realtime.channels`). */
+export interface RealtimeChannelDeclaration {
+    /** Lowercase letters, numbers, - and _; up to 40 characters. */
+    name: string;
+    /** Who may listen. Default 'admin'. */
+    subscribe?: "public" | "signedIn" | "admin";
+    /** Who may send: those levels, or 'server' (only the app's server functions). Default 'server'. */
+    publish?: "public" | "signedIn" | "admin" | "server";
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.55  |  Generated: 2026-10-12T20:04:55.294Z
+Version: 2.0.57  |  Generated: 2026-10-13T11:42:19.247Z
 
 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: a manifest `connector` block + server functions (testConnection/describeTarget/sample/transform/send/fetch) that the integration engine and console call for one external provider
 - **[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
@@ -2850,12 +2851,159 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  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
+  transform?: 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
+}
+```
+
+**ConnectorTransformInput** (interface)
+```typescript
+interface ConnectorTransformInput {
+  installation: ConnectorInstallation
+  records: Array<Record<string, unknown>>
+  mapping: FieldMapping[]
+}
+```
+
+**ConnectorTransformResult** (interface)
+```typescript
+interface ConnectorTransformResult {
+  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 {
@@ -6898,11 +7046,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
 }
 ```
@@ -6981,13 +7139,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 {
@@ -7192,6 +7374,8 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'transform'`
+
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
 
 **FlowRunStatus** = `'running' | 'success' | 'partial' | 'failed' | 'skipped'`
@@ -9141,6 +9325,59 @@ interface AblyTokenRequest {
 }
 ```
 
+**RealtimeScope** (interface)
+```typescript
+interface RealtimeScope {
+  collectionId: string
+  appId?: string
+}
+```
+
+**RealtimeMessage** (interface)
+```typescript
+interface RealtimeMessage {
+  channel: string
+  event: string
+  data: unknown
+  at?: number
+}
+```
+
+**RealtimeChangeEvent** (interface)
+```typescript
+interface RealtimeChangeEvent {
+  type: string
+  id?: string
+  appId?: string
+  recordType?: string
+  productId?: string
+  proofId?: string
+  status?: string
+  at: number
+}
+```
+
+**RealtimeChangeFilter** (interface)
+```typescript
+interface RealtimeChangeFilter {
+  type?: string
+  id?: string
+  appId?: string
+  recordType?: string
+  productId?: string
+  proofId?: string
+}
+```
+
+**RealtimeChannelDeclaration** (interface)
+```typescript
+interface RealtimeChannelDeclaration {
+  name: string
+  subscribe?: "public" | "signedIn" | "admin"
+  publish?: "public" | "signedIn" | "admin" | "server"
+}
+```
+
 **RealtimeChannelPattern** = `string`
 
 ### research
@@ -11453,6 +11690,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, `transform` (a dry run) → ConnectorTransformResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
+
 ### interactions
 
 **query**(collectionId: string,
@@ -12168,11 +12419,20 @@ Reset rate limit for a user
 
 ### realtime
 
+**channel**(scope: RealtimeScope & { appId: string }, name: string) → `void`
+One of your app's declared channels (manifest `realtime.channels`). ```ts const draw = realtime.channel({ collectionId, appId }, "draw") const off = draw.subscribe("status", (m) => setStatus(m.data)) await draw.publish("status", { phase: "spinning" }) // if the channel lets this viewer publish ```
+
+**onChange**(scope: RealtimeScope, filter: RealtimeChangeFilter, onChangeFn: (change: RealtimeChangeEvent) → `void`
+Something changed: refetch it. IDs only — never data. Admins of the collection see every change; everyone else sees changes to public things (public app records, products). Filter by `type` ('product' | 'proof' | 'asset' | 'record' | 'collection' | 'collection.apps' | 'settings'), `id`, `appId`, `recordType`, `productId`, `proofId`. ```ts const off = realtime.onChange({ collectionId }, { type: "record", appId, recordType: "entry" }, () => refetch()) ```
+
+**onMine**(scope: RealtimeScope, onMessage: (msg: RealtimeMessage) → `void`
+Messages for the signed-in person only (e.g. "scan" — a tag they just scanned on another device).
+
 **getPublicToken**(params: RealtimeTokenRequest) → `Promise<AblyTokenRequest>`
-Get an Ably token for public (user-scoped) real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with appropriate permissions for the specified collection and optional app. Requires user authentication (Bearer token). ```ts const tokenRequest = await realtime.getPublicToken({ collectionId: 'my-collection-id', appId: 'my-app-id' }) // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to channels matching the pattern const channel = ably.channels.get('collection:my-collection-id:app:my-app-id:chat:general') await channel.subscribe('message', (msg) => console.log(msg.data)) ```
+`collection:{collectionId}:*` (subscribe; publish only for the collection's admins).
 
 **getAdminToken**() → `Promise<AblyTokenRequest>`
-Get an Ably token for admin real-time communication. This endpoint returns an Ably TokenRequest that can be used to initialize an Ably client with admin permissions to receive system notifications and alerts. Admin users get subscribe-only (read-only) access to the interaction:{userId} channel pattern. Requires admin authentication (Bearer token). ```ts const tokenRequest = await realtime.getAdminToken() // Use with Ably const ably = new Ably.Realtime.Promise({ authCallback: async (data, callback) => { callback(null, tokenRequest) } }) // Subscribe to admin interaction channel const userId = 'my-user-id' const channel = ably.channels.get(`interaction:${userId}`) await channel.subscribe((message) => { console.log('Admin notification:', message.data) }) ```
+(subscribe only).
 
 ### research
 

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`, `transform`, `send`, `fetch`). The full
+contract is in the **[Connectors guide](connectors.md)**.
+
 ---
 
 ## `app.admin.json`

package/docs/connectors.md

@@ -0,0 +1,204 @@
+# Integration connectors
+
+A **connector** is an app that knows one external provider (a PIM, a content network, a shop
+platform…). It is installed on a collection like any app, versioned and released like any app, and
+it adds a manifest `connector` block plus a handful of [server functions](server-functions.md) the
+integration engine and the integrations console call by convention.
+
+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. |
+| **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. |
+
+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.
+
+---
+
+## The manifest block
+
+```jsonc
+// app.manifest.json
+"connector": {
+  "provider": "oneworldsync",
+  "title": "1WorldSync",
+  "directions": ["inbound"],
+  "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 },
+      { "name": "environment", "label": "Environment", "type": "select",
+        "options": [ { "value": "preprod", "label": "Pre-production" }, { "value": "production", "label": "Production" } ] }
+    ]
+  },
+  "settings": {                       // JSON Schema → a form in the console
+    "type": "object",
+    "properties": { "targetMarket": { "type": "string", "default": "GB" } }
+  },
+  "presets": [
+    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product" }
+  ],
+  "functions": {                      // names of this app's server functions
+    "testConnection": "testConnection",
+    "describeTarget": "describeTarget",
+    "sample": "sample",
+    "fetch": "fetch"
+  },
+  "panels": [ { "id": "explorer", "title": "Explorer", "component": "Explorer" } ],
+  "aiGuide": "connector-ai-guide.md"
+},
+"functions": {
+  "files": { "js": { "umd": "dist/functions.umd.js" } },
+  "definitions": [
+    { "name": "testConnection", "trigger": { "type": "http", "method": "POST" },
+      "visibility": "admin", "authority": "collection",
+      "capabilities": ["network:content1-api.1worldsync.com", "secrets:oneworldsync-app-id", "secrets:oneworldsync-secret-key"] }
+    // …one definition per function named above
+  ]
+}
+```
+
+Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`src/types/appManifest.ts`).
+
+| Field | Meaning |
+|---|---|
+| `provider` | Stable provider key (`syndigo`, `oneworldsync`). |
+| `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. |
+| `settings` | JSON Schema for installation settings; the console renders it as a form. |
+| `presets[]` | Ready-made flows ("Products → provider") with flow defaults. |
+| `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. |
+
+---
+
+## The functions
+
+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>`).
+
+| 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* |
+| `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 |
+
+What happens when a step is left out:
+
+- **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
+  `config.transport: 'eventhub'` and `config.eventHub`.
+- **No `describeTarget`:** the mapper offers free-text target paths.
+
+### `installation`
+
+Every step receives the installation it serves:
+
+```ts
+interface ConnectorInstallation {
+  collectionId: string
+  appId: string             // the connector app
+  flowId?: string | null    // when called for a flow
+  connection: Record<string, unknown>   // non-secret Connect-form fields
+  settings: Record<string, unknown>     // installation settings, with the flow's overrides on top
+}
+```
+
+Secrets are never in it. Read them in the function with `ctx.secrets.get('<name>')`, which needs the
+matching `secrets:<name>` capability.
+
+### Example: `fetch`
+
+```ts
+// src/functions/index.ts (the app's functions bundle)
+import type { ConnectorFetchInput, ConnectorRecords } from '@proveanything/smartlinks'
+
+export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
+  const { installation, cursor, limit = 50 } = event.body as ConnectorFetchInput
+  const appId = await ctx.secrets.get('provider-app-id')
+  const key = await ctx.secrets.get('provider-secret-key')
+  const res = await ctx.fetch(buildSignedUrl(installation, { cursor, limit }, appId, key))
+  const page = await res.json()
+  return { records: page.items, nextCursor: page.next ?? null }
+}
+```
+
+---
+
+## Where configuration lives
+
+| 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`. |
+
+```ts
+await integrations.createFlow(collectionId, {
+  appId: 'core-integrations',
+  direction: 'inbound',
+  name: 'Import products from 1WorldSync',
+  status: 'active',
+  schedule: '0 * * * *',
+  targetEntity: 'product',
+  config: {
+    connector: { appId: 'oneworldsync', preset: 'import-products' },
+    fieldMappings: [ { targetPath: 'name', sourcePath: 'item.tradeItemDescription', transformType: 'direct' } ],
+  },
+})
+```
+
+---
+
+## From the console
+
+```ts
+import { integrations, secrets } from '@proveanything/smartlinks'
+
+const { connectors } = await integrations.listConnectors(collectionId)
+// → [{ appId, name, version, connector, installation: { connection, settings }, secrets: { 'provider-key': { set, hint } } }]
+
+await secrets.put(collectionId, 'provider-key', value, { appId })              // a secret field
+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 })
+```
+
+`send` and `fetch` only run inside a flow. A flow run's summary carries `sent` (outbound) or
+`created` / `updated` / `skipped` (inbound), and every run, inbound or outbound, is in the run history.
+
+---
+
+## 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.
+
+---
+
+## Who can build connectors
+
+First-party connectors run in-process, like any app server function. Third-party connectors will run
+in the isolated runner (see [server-functions.md](server-functions.md)) once that opens up; the contract
+does not change.