@proveanything/smartlinks 2.0.56 → 2.0.57

package/dist/openapi.yaml

@@ -19652,6 +19652,8 @@ components:
           $ref: "#/components/schemas/AppDataDeclaration"
         headless:
           $ref: "#/components/schemas/AppHeadlessDeclaration"
+        connector:
+          $ref: "#/components/schemas/AppConnectorDeclaration"
       required:
         - name
         - version
@@ -19659,6 +19661,268 @@ components:
         - function
         - files
         - components
+    ConnectorConnectionField:
+      type: object
+      properties:
+        name:
+          type: string
+        label:
+          type: string
+        description:
+          type: string
+        secret:
+          type: string
+        required:
+          type: boolean
+        type:
+          type: string
+          enum:
+            - text
+            - url
+            - select
+            - number
+            - boolean
+        options:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        placeholder:
+          type: string
+      required:
+        - name
+        - label
+    ConnectorPreset:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        direction:
+          type: string
+          enum:
+            - inbound
+            - outbound
+        entity:
+          type: string
+        flow:
+          type: object
+          additionalProperties: true
+      required:
+        - id
+        - title
+        - direction
+        - entity
+    ConnectorPanel:
+      type: object
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        component:
+          type: string
+      required:
+        - id
+        - title
+        - component
+    AppConnectorDeclaration:
+      type: object
+      properties:
+        provider:
+          type: string
+        title:
+          type: string
+        directions:
+          type: array
+          items:
+            type: string
+            enum:
+              - inbound
+              - outbound
+        entities:
+          type: array
+          items:
+            type: string
+        connection:
+          type: object
+          additionalProperties: true
+        settings:
+          type: object
+          additionalProperties: true
+        presets:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorPreset"
+        functions:
+          type: object
+          additionalProperties: true
+        testConnection:
+          type: string
+        describeTarget:
+          type: string
+        sample:
+          type: string
+        transform:
+          type: string
+        send:
+          type: string
+        fetch:
+          type: string
+        panels:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorPanel"
+        aiGuide:
+          type: string
+      required:
+        - provider
+        - directions
+        - entities
+        - functions
+    ConnectorInstallation:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+        flowId:
+          type: string
+        connection:
+          type: object
+          additionalProperties: true
+        settings:
+          type: object
+          additionalProperties: true
+      required:
+        - collectionId
+        - appId
+        - connection
+        - settings
+    ConnectorTestResult:
+      type: object
+      properties:
+        ok:
+          type: boolean
+        message:
+          type: string
+      required:
+        - ok
+        - message
+    ConnectorTargetField:
+      type: object
+      properties:
+        path:
+          type: string
+        label:
+          type: string
+        type:
+          type: string
+          enum:
+            - string
+            - number
+            - boolean
+            - date
+            - object
+            - array
+        required:
+          type: boolean
+        description:
+          type: string
+        enum:
+          type: array
+          items:
+            type: string
+      required:
+        - path
+    ConnectorTargetSchema:
+      type: object
+      properties:
+        fields:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorTargetField"
+      required:
+        - fields
+    ConnectorRecords:
+      type: object
+      properties:
+        records:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        nextCursor:
+          type: string
+      required:
+        - records
+    ConnectorTransformInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        records:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        mapping:
+          type: array
+          items:
+            $ref: "#/components/schemas/FieldMapping"
+      required:
+        - installation
+        - records
+        - mapping
+    ConnectorTransformResult:
+      type: object
+      properties:
+        payloads:
+          type: array
+          items: {}
+        skipped:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - payloads
+    ConnectorSendInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        payloads:
+          type: array
+          items: {}
+      required:
+        - installation
+        - payloads
+    ConnectorSendResult:
+      type: object
+      properties:
+        results:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - results
+    ConnectorFetchInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        cursor:
+          type: string
+        limit:
+          type: number
+      required:
+        - installation
     CollectionAppWidget:
       type: object
       properties:
@@ -25913,6 +26177,18 @@ components:
             type: string
         auth:
           $ref: "#/components/schemas/FlowConnectionAuth"
+    FlowConnectorRef:
+      type: object
+      properties:
+        appId:
+          type: string
+        preset:
+          type: string
+        settings:
+          type: object
+          additionalProperties: true
+      required:
+        - appId
     IntegrationFlowConfig:
       type: object
       properties:
@@ -25922,6 +26198,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/FieldMapping"
+        connector:
+          $ref: "#/components/schemas/FlowConnectorRef"
     IntegrationFlow:
       type: object
       properties:
@@ -26054,6 +26332,12 @@ components:
           type: number
         failed:
           type: number
+        created:
+          type: number
+        updated:
+          type: number
+        skipped:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId:
@@ -26062,9 +26346,47 @@ components:
         - flowId
         - direction
         - records
-        - sent
         - failed
         - status
+    InstalledConnector:
+      type: object
+      properties:
+        appId:
+          type: string
+        name:
+          type: string
+        channel:
+          type: string
+        version:
+          type: string
+        connector:
+          type: object
+          additionalProperties: true
+        installation:
+          type: object
+          additionalProperties: true
+        secrets:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+      required:
+        - appId
+        - name
+        - channel
+        - version
+        - connector
+        - installation
+        - secrets
+    SaveConnectorInstallationInput:
+      type: object
+      properties:
+        connection:
+          type: object
+          additionalProperties: true
+        settings:
+          type: object
+          additionalProperties: true
     CapturedRequest:
       type: object
       properties:
@@ -26406,6 +26728,13 @@ components:
         - none
     UpdateFlowInput:
       $ref: "#/components/schemas/CreateFlowInput"
+    ConnectorConsoleStep:
+      type: string
+      enum:
+        - testConnection
+        - describeTarget
+        - sample
+        - transform
     RunTrigger:
       type: string
       enum:

package/dist/types/appManifest.d.ts

@@ -2,6 +2,7 @@
 /// <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.
  *
@@ -827,8 +828,162 @@ 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, transform, send and fetch.
+     * @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.
+ */
+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>;
+    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;
+        /** (ConnectorTransformInput) → ConnectorTransformResult. Must be deterministic — no AI at run time. */
+        transform?: 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;
+}
+export interface ConnectorTransformInput {
+    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). */
+    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). */
+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';