@proveanything/smartlinks 1.16.7 → 1.17.0

package/dist/api/index.d.ts

@@ -37,6 +37,8 @@ export { containers } from "./containers";
 export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
+export { integrations } from "./integrations";
+export { secrets } from "./secrets";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/index.js

@@ -40,6 +40,8 @@ export { containers } from "./containers";
 export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
+export { integrations } from "./integrations";
+export { secrets } from "./secrets";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/integrations.d.ts

@@ -0,0 +1,28 @@
+import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued } from "../types/integrations";
+export declare namespace integrations {
+    /** List flows in a collection. GET /integrations/flows */
+    function listFlows(collectionId: string, query?: ListFlowsQuery): Promise<FlowList>;
+    /** Create a flow. POST /integrations/flows */
+    function createFlow(collectionId: string, input: CreateFlowInput): Promise<IntegrationFlow>;
+    /** Get one flow. GET /integrations/flows/:id */
+    function getFlow(collectionId: string, id: string): Promise<IntegrationFlow>;
+    /** Update whitelisted fields. PUT /integrations/flows/:id */
+    function updateFlow(collectionId: string, id: string, input: UpdateFlowInput): Promise<IntegrationFlow>;
+    /** Soft-delete a flow. DELETE /integrations/flows/:id */
+    function deleteFlow(collectionId: string, id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    function runFlow(collectionId: string, id: string, options?: RunFlowInput & {
+        async?: boolean;
+    }): Promise<RunFlowResult>;
+    /** Type guard: the run executed inline and returned a summary. */
+    function isRunSummary(r: RunFlowResult): r is RunFlowSummary;
+    /** Type guard: the run was enqueued (async). */
+    function isRunEnqueued(r: RunFlowResult): r is RunFlowEnqueued;
+}

package/dist/api/integrations.js

@@ -0,0 +1,82 @@
+// src/api/integrations.ts
+//
+// Integration flow management + execution. Flows model input/output pipelines
+// (inbound: fetch external -> write entity; outbound: read entity -> transform ->
+// send). Credentials live in the secret store (see the `secrets` namespace); a flow
+// only carries an opaque credentialRef in config.connection.auth.
+//
+// Endpoints: /admin/collection/:collectionId/integrations/flows
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { request, post, put, del } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+function encodeQuery(params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        search.set(key, typeof value === "boolean" ? (value ? "true" : "false") : String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+export var integrations;
+(function (integrations) {
+    const base = (collectionId) => `/admin/collection/${enc(collectionId)}/integrations/flows`;
+    /** List flows in a collection. GET /integrations/flows */
+    async function listFlows(collectionId, query = {}) {
+        return request(`${base(collectionId)}${encodeQuery(query)}`);
+    }
+    integrations.listFlows = listFlows;
+    /** Create a flow. POST /integrations/flows */
+    async function createFlow(collectionId, input) {
+        return post(base(collectionId), input);
+    }
+    integrations.createFlow = createFlow;
+    /** Get one flow. GET /integrations/flows/:id */
+    async function getFlow(collectionId, id) {
+        return request(`${base(collectionId)}/${enc(id)}`);
+    }
+    integrations.getFlow = getFlow;
+    /** Update whitelisted fields. PUT /integrations/flows/:id */
+    async function updateFlow(collectionId, id, input) {
+        return put(`${base(collectionId)}/${enc(id)}`, input);
+    }
+    integrations.updateFlow = updateFlow;
+    /** Soft-delete a flow. DELETE /integrations/flows/:id */
+    async function deleteFlow(collectionId, id) {
+        return del(`${base(collectionId)}/${enc(id)}`);
+    }
+    integrations.deleteFlow = deleteFlow;
+    /**
+     * 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.
+     */
+    async function runFlow(collectionId, id, options = {}) {
+        const { async: runAsync } = options, body = __rest(options, ["async"]);
+        const qs = runAsync ? "?async=true" : "";
+        return post(`${base(collectionId)}/${enc(id)}/run${qs}`, body);
+    }
+    integrations.runFlow = runFlow;
+    /** Type guard: the run executed inline and returned a summary. */
+    function isRunSummary(r) {
+        return r.status !== undefined;
+    }
+    integrations.isRunSummary = isRunSummary;
+    /** Type guard: the run was enqueued (async). */
+    function isRunEnqueued(r) {
+        return r.enqueued === true;
+    }
+    integrations.isRunEnqueued = isRunEnqueued;
+})(integrations || (integrations = {}));

package/dist/api/secrets.d.ts

@@ -0,0 +1,15 @@
+import type { SecretMeta, SecretList, SetSecretInput, SetSecretResult, ListSecretsQuery } from "../types/integrations";
+export declare namespace secrets {
+    /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
+    function list(collectionId: string, query?: ListSecretsQuery): Promise<SecretList>;
+    /** Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow. */
+    function set(collectionId: string, input: SetSecretInput): Promise<SetSecretResult>;
+    /** Metadata for one secret (never the value). GET /secrets/:ref */
+    function get(collectionId: string, ref: string): Promise<SecretMeta>;
+    /** Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint } */
+    function rotate(collectionId: string, ref: string, input: SetSecretInput): Promise<SetSecretResult>;
+    /** Soft-delete a secret. DELETE /secrets/:ref */
+    function remove(collectionId: string, ref: string): Promise<{
+        deleted: boolean;
+    }>;
+}

package/dist/api/secrets.js

@@ -0,0 +1,52 @@
+// src/api/secrets.ts
+//
+// Sealed-secret store — the credentials that back integration flows and other
+// server-side handlers. WRITE-ONLY from the client: you can set, rotate, list
+// (refs + masked hints + metadata) and delete, but a value NEVER comes back over the
+// API. It is sealed at rest and resolved server-side only, at execution time.
+//
+// Typical use: `set` a credential, take the returned `ref`, and put it on a flow's
+// config.connection.auth.credentialRef.
+//
+// Endpoints: /admin/collection/:collectionId/secrets
+import { request, post, put, del } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+function encodeQuery(params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+export var secrets;
+(function (secrets) {
+    const base = (collectionId) => `/admin/collection/${enc(collectionId)}/secrets`;
+    /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
+    async function list(collectionId, query = {}) {
+        return request(`${base(collectionId)}${encodeQuery(query)}`);
+    }
+    secrets.list = list;
+    /** Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow. */
+    async function set(collectionId, input) {
+        return post(base(collectionId), input);
+    }
+    secrets.set = set;
+    /** Metadata for one secret (never the value). GET /secrets/:ref */
+    async function get(collectionId, ref) {
+        return request(`${base(collectionId)}/${enc(ref)}`);
+    }
+    secrets.get = get;
+    /** Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint } */
+    async function rotate(collectionId, ref, input) {
+        return put(`${base(collectionId)}/${enc(ref)}`, input);
+    }
+    secrets.rotate = rotate;
+    /** Soft-delete a secret. DELETE /secrets/:ref */
+    async function remove(collectionId, ref) {
+        return del(`${base(collectionId)}/${enc(ref)}`);
+    }
+    secrets.remove = remove;
+})(secrets || (secrets = {}));

package/dist/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,

package/dist/docs/integrations.md

@@ -0,0 +1,141 @@
+# Integrations
+
+An **integration flow** is one input/output pipeline between SmartLinks and an external
+system. There are two directions:
+
+- **outbound** — read a SmartLinks entity (v1: a product), transform it with field
+  mappings, and send it to an external endpoint.
+- **inbound** — fetch from an external system and write a SmartLinks entity. *(Executor is
+  outbound-first; inbound lands in a later increment.)*
+
+Flows are triggered three ways, all converging on the same executor:
+
+- **manual** — `integrations.runFlow(...)`, inline (returns a run summary) or enqueued.
+- **event** — an outbound flow subscribed to an event type (e.g. `product.updated`) fires
+  automatically when that entity changes.
+- **schedule** — a flow carrying a cron/interval `schedule` is run by the scan job. *(next)*
+
+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.
+
+---
+
+## The flow model
+
+```ts
+interface IntegrationFlow {
+  id: string
+  direction: 'inbound' | 'outbound'
+  name: string
+  status: 'draft' | 'active' | 'paused' | 'error'  // only 'active' flows fire on events/schedule
+  eventTypes: string[]                              // e.g. ['product.updated']
+  schedule: string | null                           // cron/interval for scheduled flows
+  sourceEntity: string | null                       // outbound source, v1: 'product'
+  targetEntity: string | null                       // inbound target
+  config: {
+    connection?: {
+      baseUrl?: string
+      sendEndpoint?: string                          // outbound: appended to baseUrl
+      defaultHeaders?: Record<string, string>
+      auth?: { method: 'api_key' | 'bearer' | 'basic' | ..., headerName?: string, credentialRef?: string }
+    }
+    fieldMappings?: FieldMapping[]
+  }
+  // ...run watermark/telemetry: lastRunAt, lastRunStatus, lastRunCount, totalSynced
+}
+```
+
+### Field mappings (transform)
+
+Each mapping produces one field on the target payload:
+
+| transformType | uses | meaning |
+|---|---|---|
+| `direct` | `sourcePath` | copy the value at that dot-path |
+| `static` | `transformExpression` | a constant |
+| `template` | `transformExpression` | a Liquid template rendered against the source record |
+| `jsonata` / `ai` | — | recognised but not yet executed; reported as a per-field error |
+
+A single field's failure is collected and the rest continue (partial success) — it never
+aborts the whole record.
+
+---
+
+## Secrets (write-only)
+
+The secret store is **write-only from the client**: you can set, rotate, list (refs +
+masked hints + metadata) and delete — but a value never comes back over the API.
+
+```ts
+import { secrets, integrations } from '@proveanything/smartlinks'
+
+// 1. Store the destination credential — keep the returned ref.
+const { ref } = await secrets.set(collectionId, {
+  name: 'Acme API key',
+  purpose: 'integration',
+  value: 'sk_live_…',           // sent once; never retrievable
+})
+
+// list shows refs + masked hints only (safe to render)
+const { secrets: list } = await secrets.list(collectionId)
+// → [{ ref, name: 'Acme API key', hint: '…live_1a2b', purpose, createdAt, ... }]
+```
+
+---
+
+## Creating and running a flow
+
+```ts
+// 2. Create an outbound flow that pushes products to Acme, authed by the secret above.
+const flow = await integrations.createFlow(collectionId, {
+  appId: 'my-integration-app',
+  direction: 'outbound',
+  name: 'Push products to Acme',
+  status: 'active',
+  eventTypes: ['product.updated'],   // fire whenever a product changes
+  sourceEntity: 'product',
+  config: {
+    connection: {
+      baseUrl: 'https://api.acme.example',
+      sendEndpoint: '/v1/products',
+      auth: { method: 'api_key', headerName: 'X-API-Key', credentialRef: ref },
+    },
+    fieldMappings: [
+      { targetPath: 'sku',   sourcePath: 'sku',  transformType: 'direct' },
+      { targetPath: 'name',  sourcePath: 'name', transformType: 'direct' },
+      { targetPath: 'label', transformType: 'template', transformExpression: '{{name}} ({{sku}})' },
+    ],
+  },
+})
+
+// 3a. Test it now against one product — inline, returns a summary.
+const result = await integrations.runFlow(collectionId, flow.id, { entityId: 'P1045716' })
+if (integrations.isRunSummary(result)) {
+  console.log(result) // { records: 1, sent: 1, failed: 0, status: 'success' }
+}
+
+// 3b. Or enqueue on the worker (returns immediately).
+await integrations.runFlow(collectionId, flow.id, { entityId: 'P1045716', async: true })
+```
+
+Once `status: 'active'` with `eventTypes: ['product.updated']`, editing that product in the
+admin API fires the flow automatically — no manual run needed.
+
+---
+
+## Reference
+
+| Function | HTTP |
+|---|---|
+| `integrations.listFlows(collectionId, query?)` | `GET /integrations/flows` |
+| `integrations.createFlow(collectionId, input)` | `POST /integrations/flows` |
+| `integrations.getFlow(collectionId, id)` | `GET /integrations/flows/:id` |
+| `integrations.updateFlow(collectionId, id, input)` | `PUT /integrations/flows/:id` |
+| `integrations.deleteFlow(collectionId, id)` | `DELETE /integrations/flows/:id` |
+| `integrations.runFlow(collectionId, id, opts?)` | `POST /integrations/flows/:id/run` |
+| `secrets.list(collectionId, query?)` | `GET /secrets` |
+| `secrets.set(collectionId, input)` | `POST /secrets` |
+| `secrets.get(collectionId, ref)` | `GET /secrets/:ref` |
+| `secrets.rotate(collectionId, ref, input)` | `PUT /secrets/:ref` |
+| `secrets.remove(collectionId, ref)` | `DELETE /secrets/:ref` |