@proveanything/smartlinks 2.0.55 → 2.0.57

package/dist/http.js

@@ -210,6 +210,9 @@ function shouldSkipCache(path) {
     // Never cache auth, account, or user-identity endpoints — they depend on session state.
     if (/\/(auth|account)\//i.test(path))
         return true;
+    // Realtime tokens are single-use (a reused one is rejected by the provider) — never cache them.
+    if (/\/(push\/token|realtime\/)/i.test(path))
+        return true;
     // Never cache /me endpoints (contact/me, loyalty/me, etc.) — always user-specific.
     if (/\/me(\?|$)/i.test(path))
         return true;

package/dist/openapi.yaml

@@ -123,7 +123,7 @@ paths:
     get:
       tags:
         - realtime
-      summary: Get an Ably token for admin real-time communication.
+      summary: (subscribe only).
       operationId: realtime_getAdminToken
       security:
         - bearerAuth: []
@@ -13960,7 +13960,7 @@ paths:
     get:
       tags:
         - realtime
-      summary: realtime.getPublicToken
+      summary: "`collection:{collectionId}:*` (subscribe; publish only for the collection's admins)."
       operationId: realtime_getPublicToken
       security: []
       parameters:
@@ -14018,6 +14018,33 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/realtime/publish:
+    post:
+      tags:
+        - realtime
+      summary: "One of your app's declared channels (manifest `realtime.channels`)."
+      operationId: realtime_channel
+      security: []
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RealtimeScope"
   /public/tags/{tagId}:
     get:
       tags:
@@ -19618,10 +19645,15 @@ components:
           $ref: "#/components/schemas/AppManifestExecutor"
         functions:
           $ref: "#/components/schemas/AppManifestFunctions"
+        realtime:
+          type: object
+          additionalProperties: true
         data:
           $ref: "#/components/schemas/AppDataDeclaration"
         headless:
           $ref: "#/components/schemas/AppHeadlessDeclaration"
+        connector:
+          $ref: "#/components/schemas/AppConnectorDeclaration"
       required:
         - name
         - version
@@ -19629,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:
@@ -25883,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:
@@ -25892,6 +26198,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/FieldMapping"
+        connector:
+          $ref: "#/components/schemas/FlowConnectorRef"
     IntegrationFlow:
       type: object
       properties:
@@ -26024,6 +26332,12 @@ components:
           type: number
         failed:
           type: number
+        created:
+          type: number
+        updated:
+          type: number
+        skipped:
+          type: number
         status:
           $ref: "#/components/schemas/RunStatus"
         runId:
@@ -26032,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:
@@ -26376,6 +26728,13 @@ components:
         - none
     UpdateFlowInput:
       $ref: "#/components/schemas/CreateFlowInput"
+    ConnectorConsoleStep:
+      type: string
+      enum:
+        - testConnection
+        - describeTarget
+        - sample
+        - transform
     RunTrigger:
       type: string
       enum:
@@ -29830,6 +30189,79 @@ components:
         - nonce
         - mac
         - clientId
+    RealtimeScope:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        appId:
+          type: string
+      required:
+        - collectionId
+    RealtimeMessage:
+      type: object
+      properties:
+        channel:
+          type: string
+        event:
+          type: string
+        data: {}
+        at:
+          type: number
+      required:
+        - channel
+        - event
+        - data
+    RealtimeChangeEvent:
+      type: object
+      properties:
+        type:
+          type: string
+        id:
+          type: string
+        appId:
+          type: string
+        recordType:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        status:
+          type: string
+        at:
+          type: number
+      required:
+        - type
+        - at
+    RealtimeChangeFilter:
+      type: object
+      properties:
+        type:
+          type: string
+        id:
+          type: string
+        appId:
+          type: string
+        recordType:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+    RealtimeChannelDeclaration:
+      type: object
+      properties:
+        name:
+          type: string
+        subscribe:
+          type: object
+          additionalProperties: true
+        publish:
+          type: object
+          additionalProperties: true
+      required:
+        - name
     RealtimeChannelPattern:
       type: string
     ResearchFetchRequest:

package/dist/types/appManifest.d.ts

@@ -1,6 +1,8 @@
 /// <reference types="node" />
 /// <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.
  *
@@ -806,6 +808,16 @@ export interface AppManifest {
      * @see AppManifestFunctions
      */
     functions?: AppManifestFunctions;
+    /**
+     * SmartLinks Realtime: the live channels this app uses, with who may listen and who may send
+     * (docs/realtime.md). Only declared channels exist — anything else is refused.
+     * ```json
+     * "realtime": { "channels": [ { "name": "draw", "subscribe": "public", "publish": "admin" } ] }
+     * ```
+     */
+    realtime?: {
+        channels: RealtimeChannelDeclaration[];
+    };
     /**
      * The app's public data model: its data types, how each is stored, fields, examples and read
      * recipes. Required for `headless`. @see AppDataDeclaration · docs/headless-providers.md
@@ -816,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.
  */