@proveanything/smartlinks 2.0.56 → 2.0.57

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.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
@@ -2853,10 +2854,156 @@ 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
+  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 {
@@ -6899,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
 }
 ```
@@ -6982,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 {
@@ -7193,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'`
@@ -11507,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,

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.

package/docs/integrations.md

@@ -15,6 +15,10 @@ Flows are triggered three ways, all converging on the same executor:
   automatically when that entity changes.
 - **schedule** — a flow carrying a cron/interval `schedule` is run by the scan job. *(next)*
 
+Provider-specific logic (a provider's payload format, its API, its connect form) lives in a
+**connector app**, not in the engine: see **[Connectors](connectors.md)**. A flow uses one with
+`config.connector = { appId }`.
+
 Credentials are **never** stored on the flow. The connection holds an opaque
 `credentialRef` into the **sealed-secret store** (`secrets` namespace); the value is sealed
 at rest and resolved server-side only, at execution.

package/docs/overview.md

@@ -94,6 +94,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Connectors** | `docs/connectors.md` | Connector apps: the manifest `connector` block + the functions the integration engine calls |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
 | **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |