@proveanything/smartlinks 1.16.7 → 1.17.0

package/dist/openapi.yaml

@@ -22860,6 +22860,276 @@ components:
     UploadMessage:
       type: object
       additionalProperties: true
+    FieldMapping:
+      type: object
+      properties:
+        targetPath:
+          type: string
+        sourcePath:
+          type: string
+        transformType:
+          $ref: "#/components/schemas/TransformType"
+        transformExpression:
+          type: string
+      required:
+        - targetPath
+        - transformType
+    FlowConnectionAuth:
+      type: object
+      properties:
+        method:
+          $ref: "#/components/schemas/FlowAuthMethod"
+        headerName:
+          type: string
+        credentialRef:
+          type: string
+      required:
+        - method
+    FlowConnection:
+      type: object
+      properties:
+        baseUrl:
+          type: string
+        sendEndpoint:
+          type: string
+        fetchEndpoint:
+          type: string
+        defaultHeaders:
+          type: object
+          additionalProperties:
+            type: string
+        auth:
+          $ref: "#/components/schemas/FlowConnectionAuth"
+    IntegrationFlowConfig:
+      type: object
+      properties:
+        connection:
+          $ref: "#/components/schemas/FlowConnection"
+        fieldMappings:
+          type: array
+          items:
+            $ref: "#/components/schemas/FieldMapping"
+    IntegrationFlow:
+      type: object
+      properties:
+        id:
+          type: string
+        orgId:
+          type: string
+        collectionId:
+          type: string
+        appId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        sourceEntity:
+          type: string
+        targetEntity:
+          type: string
+        config:
+          $ref: "#/components/schemas/IntegrationFlowConfig"
+        createdBy:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        deletedAt:
+          type: string
+        lastRunAt:
+          type: string
+        lastRunStatus:
+          type: string
+        lastRunError:
+          type: string
+        lastRunCount:
+          type: number
+        lastPollAt:
+          type: string
+        lastCursor:
+          type: string
+        totalSynced:
+          type: number
+      required:
+        - id
+        - orgId
+        - collectionId
+        - appId
+        - direction
+        - name
+        - status
+        - eventTypes
+        - schedule
+        - sourceEntity
+        - targetEntity
+        - config
+        - createdBy
+        - createdAt
+        - updatedAt
+    CreateFlowInput:
+      type: object
+      properties:
+        appId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        sourceEntity:
+          type: string
+        targetEntity:
+          type: string
+        config:
+          $ref: "#/components/schemas/IntegrationFlowConfig"
+      required:
+        - appId
+        - direction
+        - name
+    ListFlowsQuery:
+      type: object
+      properties:
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        appId:
+          type: string
+    FlowList:
+      type: object
+      properties:
+        flows:
+          type: array
+          items:
+            $ref: "#/components/schemas/IntegrationFlow"
+      required:
+        - flows
+    RunFlowInput:
+      type: object
+      properties:
+        entityId:
+          type: string
+    RunFlowSummary:
+      type: object
+      properties:
+        flowId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        records:
+          type: number
+        sent:
+          type: number
+        failed:
+          type: number
+        status:
+          $ref: "#/components/schemas/RunStatus"
+      required:
+        - flowId
+        - direction
+        - records
+        - sent
+        - failed
+        - status
+    RunFlowEnqueued:
+      type: object
+      properties:
+        enqueued:
+          type: object
+          additionalProperties: true
+        flowId:
+          type: string
+        entityId:
+          type: string
+      required:
+        - enqueued
+        - flowId
+        - entityId
+    SecretMeta:
+      type: object
+      properties:
+        ref:
+          type: string
+        name:
+          type: string
+        purpose:
+          type: string
+        hint:
+          type: string
+        keyVersion:
+          type: number
+        createdBy:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        rotatedAt:
+          type: string
+      required:
+        - ref
+        - name
+        - purpose
+        - hint
+        - keyVersion
+        - createdBy
+        - createdAt
+        - updatedAt
+    SecretList:
+      type: object
+      properties:
+        secrets:
+          type: array
+          items:
+            $ref: "#/components/schemas/SecretMeta"
+      required:
+        - secrets
+    SetSecretInput:
+      type: object
+      properties:
+        value:
+          type: string
+        name:
+          type: string
+        purpose:
+          type: string
+      required:
+        - value
+    SetSecretResult:
+      type: object
+      properties:
+        ref:
+          type: string
+        hint:
+          type: string
+      required:
+        - ref
+        - hint
+    ListSecretsQuery:
+      type: object
+      properties:
+        purpose:
+          type: string
+    RunFlowResult:
+      type: object
+      additionalProperties: true
     AdminInteractionsQueryRequest:
       type: object
       properties:

package/dist/types/index.d.ts

@@ -38,5 +38,6 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
 export * from "./config";
 export * from "./widgets";

package/dist/types/index.js

@@ -40,5 +40,6 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
 export * from "./config";
 export * from "./widgets";

package/dist/types/integrations.d.ts

@@ -0,0 +1,136 @@
+export type FlowDirection = 'inbound' | 'outbound';
+export type FlowStatus = 'draft' | 'active' | 'paused' | 'error';
+export type RunStatus = 'success' | 'partial' | 'error';
+/** How one source field maps to one target field during transform. */
+export type TransformType = 'direct' | 'static' | 'template' | 'jsonata' | 'ai';
+export interface FieldMapping {
+    /** Dot-path in the produced target object (required). */
+    targetPath: string;
+    /** Dot-path in the source record. Used by `direct`. */
+    sourcePath?: string;
+    transformType: TransformType;
+    /** Constant (`static`) or Liquid template (`template`), etc. */
+    transformExpression?: string;
+}
+export type FlowAuthMethod = 'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none';
+export interface FlowConnectionAuth {
+    method: FlowAuthMethod;
+    /** Header name for `api_key` (defaults server-side to X-API-Key). */
+    headerName?: string;
+    /** Opaque reference into the secret store; resolved server-side at execution. */
+    credentialRef?: string;
+}
+export interface FlowConnection {
+    baseUrl?: string;
+    /** Outbound: path appended to baseUrl for sends. */
+    sendEndpoint?: string;
+    /** Inbound: path appended to baseUrl for fetches. */
+    fetchEndpoint?: string;
+    defaultHeaders?: Record<string, string>;
+    auth?: FlowConnectionAuth;
+}
+export interface IntegrationFlowConfig {
+    connection?: FlowConnection;
+    fieldMappings?: FieldMapping[];
+    [key: string]: any;
+}
+export interface IntegrationFlow {
+    id: string;
+    orgId: string;
+    collectionId: string;
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status: FlowStatus;
+    /** Event types this flow subscribes to, e.g. ['product.updated']. */
+    eventTypes: string[];
+    /** Cron/interval string for scheduled flows, or null. */
+    schedule: string | null;
+    sourceEntity: string | null;
+    targetEntity: string | null;
+    config: IntegrationFlowConfig;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    lastRunAt?: string | null;
+    lastRunStatus?: string | null;
+    lastRunError?: string | null;
+    lastRunCount?: number | null;
+    lastPollAt?: string | null;
+    lastCursor?: string | null;
+    totalSynced?: number | null;
+}
+export interface CreateFlowInput {
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status?: FlowStatus;
+    eventTypes?: string[];
+    schedule?: string | null;
+    sourceEntity?: string | null;
+    targetEntity?: string | null;
+    config?: IntegrationFlowConfig;
+}
+export type UpdateFlowInput = Partial<Omit<CreateFlowInput, 'direction'>> & {
+    status?: FlowStatus;
+};
+export interface ListFlowsQuery {
+    direction?: FlowDirection;
+    status?: FlowStatus;
+    appId?: string;
+}
+export interface FlowList {
+    flows: IntegrationFlow[];
+}
+/** Options for a manual flow run. */
+export interface RunFlowInput {
+    /** Run for a single source entity; omit for the flow's scheduled gather. */
+    entityId?: string;
+}
+/** Inline (synchronous) run summary. */
+export interface RunFlowSummary {
+    flowId: string;
+    direction: FlowDirection;
+    records: number;
+    sent: number;
+    failed: number;
+    status: RunStatus;
+}
+/** Response when a run is enqueued (?async=true). */
+export interface RunFlowEnqueued {
+    enqueued: true;
+    flowId: string;
+    entityId: string | null;
+}
+export type RunFlowResult = RunFlowSummary | RunFlowEnqueued;
+/** Metadata for a stored secret. NEVER includes the value or ciphertext. */
+export interface SecretMeta {
+    ref: string;
+    name: string | null;
+    purpose: string;
+    /** Masked hint (e.g. last few chars) — safe to display. */
+    hint: string;
+    keyVersion: number;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    rotatedAt?: string | null;
+}
+export interface SecretList {
+    secrets: SecretMeta[];
+}
+export interface SetSecretInput {
+    value: string;
+    name?: string;
+    /** Grouping/scoping label, defaults to 'integration' server-side. */
+    purpose?: string;
+}
+/** Result of set/rotate — the ref to store on a flow's connection, plus a hint. */
+export interface SetSecretResult {
+    ref: string;
+    hint: string;
+}
+export interface ListSecretsQuery {
+    purpose?: string;
+}

package/dist/types/integrations.js

@@ -0,0 +1,10 @@
+// src/types/integrations.ts
+//
+// Integration flows + the sealed-secret store that backs their credentials.
+//
+// A flow is one input/output pipeline: an inbound flow fetches from an external
+// system and writes a SmartLinks entity; an outbound flow reads a SmartLinks entity,
+// transforms it, and sends it out. Credentials are never stored on the flow — the
+// connection carries a `credentialRef` into the secret store, resolved server-side
+// only, at execution.
+export {};

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.16.7  |  Generated: 2026-09-09T11:29:21.917Z
+Version: 1.17.0  |  Generated: 2026-09-13T07:38:31.861Z
 
 This is a concise summary of all available API functions and types.
 
@@ -134,6 +134,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **containers** - Functions for containers operations
 - **facets** - Functions for facets operations
 - **http** - Functions for http operations
+- **integrations** - Functions for integrations operations
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
@@ -142,6 +143,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **order** - Functions for order operations
 - **products** - Functions for products operations
 - **realtime** - Functions for realtime operations
+- **secrets** - Functions for secrets operations
 - **tags** - Functions for tags operations
 - **template** - Functions for template operations
 - **translations** - Functions for translations operations
@@ -5768,6 +5770,195 @@ interface UploadDoneMessage {
 
 **UploadMessage** = ``
 
+### integrations
+
+**FieldMapping** (interface)
+```typescript
+interface FieldMapping {
+  targetPath: string
+  sourcePath?: string
+  transformType: TransformType
+  transformExpression?: string
+}
+```
+
+**FlowConnectionAuth** (interface)
+```typescript
+interface FlowConnectionAuth {
+  method: FlowAuthMethod
+  headerName?: string
+  credentialRef?: string
+}
+```
+
+**FlowConnection** (interface)
+```typescript
+interface FlowConnection {
+  baseUrl?: string
+  sendEndpoint?: string
+  fetchEndpoint?: string
+  defaultHeaders?: Record<string, string>
+  auth?: FlowConnectionAuth
+}
+```
+
+**IntegrationFlowConfig** (interface)
+```typescript
+interface IntegrationFlowConfig {
+  connection?: FlowConnection
+  fieldMappings?: FieldMapping[]
+  [key: string]: any
+}
+```
+
+**IntegrationFlow** (interface)
+```typescript
+interface IntegrationFlow {
+  id: string
+  orgId: string
+  collectionId: string
+  appId: string
+  direction: FlowDirection
+  name: string
+  status: FlowStatus
+  eventTypes: string[]
+  schedule: string | null
+  sourceEntity: string | null
+  targetEntity: string | null
+  config: IntegrationFlowConfig
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+  lastRunAt?: string | null
+  lastRunStatus?: string | null
+  lastRunError?: string | null
+  lastRunCount?: number | null
+  lastPollAt?: string | null
+  lastCursor?: string | null
+  totalSynced?: number | null
+}
+```
+
+**CreateFlowInput** (interface)
+```typescript
+interface CreateFlowInput {
+  appId: string
+  direction: FlowDirection
+  name: string
+  status?: FlowStatus
+  eventTypes?: string[]
+  schedule?: string | null
+  sourceEntity?: string | null
+  targetEntity?: string | null
+  config?: IntegrationFlowConfig
+}
+```
+
+**ListFlowsQuery** (interface)
+```typescript
+interface ListFlowsQuery {
+  direction?: FlowDirection
+  status?: FlowStatus
+  appId?: string
+}
+```
+
+**FlowList** (interface)
+```typescript
+interface FlowList {
+  flows: IntegrationFlow[]
+}
+```
+
+**RunFlowInput** (interface)
+```typescript
+interface RunFlowInput {
+  entityId?: string
+}
+```
+
+**RunFlowSummary** (interface)
+```typescript
+interface RunFlowSummary {
+  flowId: string
+  direction: FlowDirection
+  records: number
+  sent: number
+  failed: number
+  status: RunStatus
+}
+```
+
+**RunFlowEnqueued** (interface)
+```typescript
+interface RunFlowEnqueued {
+  enqueued: true
+  flowId: string
+  entityId: string | null
+}
+```
+
+**SecretMeta** (interface)
+```typescript
+interface SecretMeta {
+  ref: string
+  name: string | null
+  purpose: string
+  hint: string
+  keyVersion: number
+  createdBy: string | null
+  createdAt: string
+  updatedAt: string
+  rotatedAt?: string | null
+}
+```
+
+**SecretList** (interface)
+```typescript
+interface SecretList {
+  secrets: SecretMeta[]
+}
+```
+
+**SetSecretInput** (interface)
+```typescript
+interface SetSecretInput {
+  value: string
+  name?: string
+  purpose?: string
+}
+```
+
+**SetSecretResult** (interface)
+```typescript
+interface SetSecretResult {
+  ref: string
+  hint: string
+}
+```
+
+**ListSecretsQuery** (interface)
+```typescript
+interface ListSecretsQuery {
+  purpose?: string
+}
+```
+
+**FlowDirection** = `'inbound' | 'outbound'`
+
+**FlowStatus** = `'draft' | 'active' | 'paused' | 'error'`
+
+**RunStatus** = `'success' | 'partial' | 'error'`
+
+**TransformType** = `'direct' | 'static' | 'template' | 'jsonata' | 'ai'`
+
+**FlowAuthMethod** = `'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none'`
+
+**UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
+
+**RunFlowResult** = `RunFlowSummary | RunFlowEnqueued`
+
 ### interaction
 
 **AdminInteractionsQueryRequest** (interface)
@@ -9921,6 +10112,34 @@ Perform a PATCH request to any API endpoint.
 **del**(path: string) → `Promise<T>`
 Perform a DELETE request to any API endpoint.
 
+### integrations
+
+**listFlows**(collectionId: string, query: ListFlowsQuery = {}) → `Promise<FlowList>`
+List flows in a collection. GET /integrations/flows
+
+**createFlow**(collectionId: string, input: CreateFlowInput) → `Promise<IntegrationFlow>`
+Create a flow. POST /integrations/flows
+
+**getFlow**(collectionId: string, id: string) → `Promise<IntegrationFlow>`
+Get one flow. GET /integrations/flows/:id
+
+**updateFlow**(collectionId: string, id: string, input: UpdateFlowInput) → `Promise<IntegrationFlow>`
+Update whitelisted fields. PUT /integrations/flows/:id
+
+**deleteFlow**(collectionId: string, id: string) → `Promise<`
+Soft-delete a flow. DELETE /integrations/flows/:id
+
+**runFlow**(collectionId: string,
+    id: string,
+    options: RunFlowInput & { async?: boolean } = {}) → `Promise<RunFlowResult>`
+Run a flow now. POST /integrations/flows/:id/run - inline (default): resolves and returns the run summary. - options.async: enqueue on the worker, returns { enqueued: true }. Pass options.entityId to run for a single source entity.
+
+**isRunSummary**(r: RunFlowResult) → `r is RunFlowSummary`
+Type guard: the run executed inline and returned a summary.
+
+**isRunEnqueued**(r: RunFlowResult) → `r is RunFlowEnqueued`
+Type guard: the run was enqueued (async).
+
 ### interactions
 
 **query**(collectionId: string,
@@ -10613,6 +10832,23 @@ Get an Ably token for public (user-scoped) real-time communication. This endpoin
 **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) }) ```
 
+### secrets
+
+**list**(collectionId: string, query: ListSecretsQuery = {}) → `Promise<SecretList>`
+List secrets as refs + masked hints + metadata (never values). GET /secrets
+
+**set**(collectionId: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow.
+
+**get**(collectionId: string, ref: string) → `Promise<SecretMeta>`
+Metadata for one secret (never the value). GET /secrets/:ref
+
+**rotate**(collectionId: string, ref: string, input: SetSecretInput) → `Promise<SetSecretResult>`
+Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint }
+
+**remove**(collectionId: string, ref: string) → `Promise<`
+Soft-delete a secret. DELETE /secrets/:ref
+
 ### segments
 
 **create**(collectionId: string,