@proveanything/smartlinks 2.1.14 → 2.1.15

package/dist/api/integrations.d.ts

@@ -105,4 +105,32 @@ export declare namespace integrations {
     function runConnectorStep<T = unknown>(collectionId: string, appId: string, step: ConnectorConsoleStep, input?: Record<string, unknown> & {
         flowId?: string;
     }): Promise<T>;
+    /**
+     * Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a
+     * coupon… The connector's function runs with its own credentials and is told who asked.
+     * POST /integrations/connectors/:appId/actions/:action { input }
+     */
+    function runConnectorAction<T = unknown>(collectionId: string, appId: string, action: string, input?: Record<string, unknown>): Promise<T>;
+    /**
+     * PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`,
+     * plus `member` ones when signed in.
+     * GET /public/collection/:collectionId/connectors/:appId/actions
+     */
+    function listConnectorActions(collectionId: string, appId: string): Promise<{
+        actions: Array<{
+            name: string;
+            title: string;
+            description?: string;
+            visibility: 'public' | 'member' | 'admin';
+            input?: Record<string, unknown>;
+            output?: Record<string, unknown>;
+        }>;
+    }>;
+    /**
+     * PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member.
+     * 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one;
+     * 400 with `missing[]` when a required input is absent.
+     * POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+     */
+    function callConnectorAction<T = unknown>(collectionId: string, appId: string, action: string, input?: Record<string, unknown>): Promise<T>;
 }

package/dist/api/integrations.js

@@ -200,4 +200,32 @@ export var integrations;
         return post(`${connectorsBase(collectionId)}/${enc(appId)}/steps/${enc(step)}`, input);
     }
     integrations.runConnectorStep = runConnectorStep;
+    /**
+     * Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a
+     * coupon… The connector's function runs with its own credentials and is told who asked.
+     * POST /integrations/connectors/:appId/actions/:action { input }
+     */
+    async function runConnectorAction(collectionId, appId, action, input = {}) {
+        return post(`${connectorsBase(collectionId)}/${enc(appId)}/actions/${enc(action)}`, { input });
+    }
+    integrations.runConnectorAction = runConnectorAction;
+    /**
+     * PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`,
+     * plus `member` ones when signed in.
+     * GET /public/collection/:collectionId/connectors/:appId/actions
+     */
+    async function listConnectorActions(collectionId, appId) {
+        return request(`/public/collection/${enc(collectionId)}/connectors/${enc(appId)}/actions`);
+    }
+    integrations.listConnectorActions = listConnectorActions;
+    /**
+     * PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member.
+     * 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one;
+     * 400 with `missing[]` when a required input is absent.
+     * POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+     */
+    async function callConnectorAction(collectionId, appId, action, input = {}) {
+        return post(`/public/collection/${enc(collectionId)}/connectors/${enc(appId)}/actions/${enc(action)}`, { input });
+    }
+    integrations.callConnectorAction = callConnectorAction;
 })(integrations || (integrations = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.14  |  Generated: 2026-11-09T13:01:05.900Z
+Version: 2.1.15  |  Generated: 2026-11-09T15:17:42.472Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,7 +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), event patterns, the event envelope (interaction/contact/event sources), identity policy, event mapping, signed deliveries, contact as a target, field mappings
-- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send/describeEvents/lookup); loyalty and CRM connectors; core does the mapping
+- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send/describeEvents/lookup); loyalty and CRM connectors; actions (provider operations on demand); core does the mapping
 - **[Entitlements](entitlements.md)** - "Is this person gold or above?" answered on demand from signed claims, a connector lookup (cached), or the contact — never a mirrored member base; gates on interaction types and in server functions
 - **[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
@@ -3112,6 +3112,19 @@ interface ConnectorPanel {
 }
 ```
 
+**ConnectorAction** (interface)
+```typescript
+interface ConnectorAction {
+  name: string
+  title?: string
+  description?: string
+  function: string
+  visibility?: 'admin' | 'member' | 'public'
+  input?: Record<string, unknown>
+  output?: Record<string, unknown>
+}
+```
+
 **AppConnectorDeclaration** (interface)
 ```typescript
 interface AppConnectorDeclaration {
@@ -3134,6 +3147,7 @@ interface AppConnectorDeclaration {
   lookup?: string
   }
   panels?: ConnectorPanel[]
+  actions?: ConnectorAction[]
   aiGuide?: string
   recordId?: string
   limits?: { requestsPerSecond?: number; maxEvents?: number; maxAttributes?: number }
@@ -7980,6 +7994,7 @@ interface IntegrationFlowConfig {
   signing?: { credentialRef: string; previousCredentialRef?: string }
   identity?: { policy?: IdentityPolicy; hashKeyCredentialRef?: string }
   eventMapping?: EventMapping
+  envelopeFormat?: 'cloudevents'
   connection?: FlowConnection
   fieldMappings?: FieldMapping[]
   connector?: FlowConnectorRef
@@ -8222,6 +8237,7 @@ interface ConnectorLookupResult {
 **EventEnvelope** (interface)
 ```typescript
 interface EventEnvelope {
+  specVersion: number
   id: string
   type: string
   entityType: string | null
@@ -8234,6 +8250,8 @@ interface EventEnvelope {
   contactId: string | null
   userId: string | null
   externalIds: Record<string, string>
+  anonymousId: string | null
+  sessionId: string | null
   emailHash?: string | null
   phoneHash?: string | null
   hashAlgorithm?: 'hmac-sha256' | null
@@ -8243,6 +8261,7 @@ interface EventEnvelope {
   identityPolicy: IdentityPolicy
   product: { id: string; name?: string | null; sku?: string | null; gtin?: string | null; variantId?: string | null; batchId?: string | null } | null
   proof: { id: string } | null
+  consent: { channels: Record<'email' | 'sms' | 'push' | 'whatsapp', 'opted_in' | 'opted_out' | 'suppressed' | 'unknown'>; topics: Record<string, boolean>; updatedAt: string | null } | null
   subject: Record<string, unknown>
   event?: { name: string; attributes: Record<string, unknown>; rule: string | null }
   attributes: Record<string, unknown>
@@ -12984,6 +13003,22 @@ Save a connector's non-secret Connect-form values and/or settings. PUT /integrat
     input: Record<string, unknown> & { flowId?: string } = {}) → `Promise<T>`
 Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, and dry runs of `shape` ({ records }) → ConnectorShapeResult and `serialize` ({ documents }) → ConnectorSerializeResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
 
+**runConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a coupon… The connector's function runs with its own credentials and is told who asked. POST /integrations/connectors/:appId/actions/:action { input }
+
+**listConnectorActions**(collectionId: string,
+    appId: string) → `Promise<`
+PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`, plus `member` ones when signed in. GET /public/collection/:collectionId/connectors/:appId/actions
+
+**callConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member. 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one; 400 with `missing[]` when a required input is absent. POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+
 ### interactions
 
 **query**(collectionId: string,

package/dist/docs/connectors.md

@@ -92,6 +92,7 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
 | `recordId` | Path of the provider's own id in a fetched record (e.g. `gtin`). Inbound records are landed and matched by it, so a re-import updates the same product instead of creating another. Default `id`; a flow can override it (`config.upsert.externalIdPath`). |
 | `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker; `{ maxEvents, maxAttributes }` when the provider caps registered events — a flow's `eventMapping` is checked against them when saved. |
+| `actions[]` | Provider operations invoked on demand (redeem, enrol, issue…): name, title, function, `visibility`, input schema. See [Actions](#actions-provider-operations-on-demand). |
 
 ---
 
@@ -219,6 +220,61 @@ A connector should ship an `eventMapping` **preset** with the provider's standar
 
 ---
 
+## Actions: provider operations on demand
+
+Steps are called by the engine. **Actions** are called when someone asks: redeem a reward, enrol a
+member, issue a coupon, raise a ticket, send a receipt, check a balance. A connector declares them in
+the manifest and implements each as a server function; the platform decides who may call them and
+runs them with the connector's credentials, telling the function who asked.
+
+```jsonc
+"connector": {
+  "actions": [
+    { "name": "redeem", "title": "Redeem a reward", "function": "redeemReward", "visibility": "member",
+      "input": { "type": "object", "required": ["rewardId"], "properties": { "rewardId": { "type": "string" } } } },
+    { "name": "enrol", "title": "Join the programme", "function": "enrolMember", "visibility": "member" },
+    { "name": "coupon-status", "title": "Coupon status", "function": "couponStatus", "visibility": "public" },
+    { "name": "adjust-points", "title": "Adjust points", "function": "adjustPoints" }     // admin only (the default)
+  ]
+}
+```
+
+| `visibility` | Who may invoke it |
+|---|---|
+| `admin` (default) | the console and admin API; any app function |
+| `member` | also a signed-in person through the Hub / a site |
+| `public` | also anyone |
+
+The function receives `event.body = { input, installation, caller: { userId, contactId, role, surface } }`
+and returns JSON (or a `Response`). `input.required` fields from the declared schema are checked before
+the function runs (400 with `missing[]`); fuller validation is the connector's job.
+
+```ts
+export async function redeemReward(ctx: any, event: any) {
+  const { input, caller } = event.body
+  if (!caller.contactId) return new Response(JSON.stringify({ error: 'no_contact' }), { status: 400 })
+  const memberId = (await ctx.sl.contacts.forCaller())?.customFields?.loyaltyMemberId   // written by Profile
+  const res = await ctx.fetch(`${api}/members/${memberId}/redemptions`, { method: 'POST', headers: auth(await ctx.secrets.get('apiKey')), body: JSON.stringify({ reward: input.rewardId }) })
+  return res.json()
+}
+```
+
+Calling an action:
+
+```ts
+// From the Hub or a site (visibility public / member):
+const { actions } = await integrations.listConnectorActions(collectionId, 'acme-loyalty')
+const out = await integrations.callConnectorAction(collectionId, 'acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From another app's server function (any visibility; needs sl:connectors:write):
+const out = await ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From the console (any visibility):
+await integrations.runConnectorAction(collectionId, 'acme-loyalty', 'adjust-points', { memberId, delta: 100 })
+```
+
+---
+
 ## Where configuration lives
 
 | What | Where |

package/dist/docs/integrations.md

@@ -118,6 +118,7 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
 
 ```jsonc
 {
+  "specVersion": 1,                            // bumped only when a consumer could break
   "id": "0b2b…",                               // the event's id — stable across retries; use it as the destination's idempotency / transaction id
   "type": "interaction.submitted:quiz-1",
   "entityType": "interaction", "entityId": "0b2b…",
@@ -126,12 +127,14 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
   "identity": {
     "contactId": "…", "userId": "…",
     "externalIds": { "acme-loyalty": "M-9", "crm": "C-1" },     // ids other systems know this person by
+    "anonymousId": "v-77", "sessionId": "s-1",                  // the visitor / device and session, before anyone signed in (every policy)
     "emailHash": "…", "phoneHash": "…", "hashAlgorithm": "hmac-sha256"   // policy 'hashed' (default)
     // "email", "phone": only under policy 'raw'
   },
   "identityPolicy": "hashed",
   "product": { "id": "P1", "name": "Widget", "sku": "W-1", "gtin": "0500…", "variantId": null, "batchId": null },
   "proof": { "id": "…" },
+  "consent": { "channels": { "email": "opted_in", "sms": "suppressed", "push": "unknown", "whatsapp": "unknown" }, "topics": { "offers": true }, "updatedAt": "…" },   // null when about nobody we hold
   "subject": { "interactionId": "quiz-1", "outcome": "completed", "metadata": { "score": 9 }, "source": "hub" },
   "event": { "name": "engagement_completed", "attributes": { "kind": "quiz", "score": 9 }, "rule": "quiz" },   // from eventMapping
   "attributes": {}
@@ -142,6 +145,11 @@ Field mappings read envelope paths (`identity.externalIds.acme-loyalty`, `subjec
 `event.name`, `product.sku`). With no mappings the envelope itself is sent. A failed event delivery
 keeps its envelope and is retried from it; a product is re-read instead.
 
+**CloudEvents.** `config.envelopeFormat: 'cloudevents'` wraps each delivered body (mapped or not) as a
+CloudEvents 1.0 structured event — `{ specversion: '1.0', id, type, source: 'urn:smartlinks:collection:<id>',
+subject, time, datacontenttype, dataschema: 'urn:smartlinks:envelope:v1', data }` — the shape every event
+bus, lake and serverless tool already consumes.
+
 ```ts
 const flow = await integrations.createFlow(collectionId, {
   appId: 'core-integrations', direction: 'outbound', name: 'Engagement → loyalty', status: 'active',

package/dist/docs/server-functions.md

@@ -518,6 +518,7 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
 | Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
 | Land a loyalty / CRM provider's view of a person (member id, tier, points, tags, external ids) | `ctx.sl.members.apply({ identity, contact?, loyalty?, tags?, externalIds? }, { provider })` → `{ contactId, op }` — matches by id, external id, email or phone; profile fields fill-empty only; see [connectors.md](connectors.md#loyalty-and-crm-connectors) | `sl:members:write` |
+| Invoke a connector's action — redeem, enrol, issue a coupon, raise a ticket — with the connector's credentials | `ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId })` → the action's result; `ctx.sl.connectors.actions(appId)` lists them; see [connectors.md](connectors.md#actions-provider-operations-on-demand) | `sl:connectors:write` |
 | Ask "is this person gold or above?" without holding their member record | `ctx.sl.entitlements.check('tier>=gold')` → `{ allowed, basis, asOf, attributes }` for the signed-in caller (or `{ identity, token, fallback }`); see [entitlements.md](entitlements.md) | `sl:entitlements:read` |
 | Take a booking with your own checks (hours, queue token, payment) | `ctx.sl.bookings.create({ slotId \| resource + time, contactId, status, idempotencyKey })` — never oversold, never double-booked; also `confirm` / `cancel` / `move` / `mine` / `freebusy` / `message` (everyone booked, hydrated) / `slots.*` / `blocks.*` (see [bookings.md](bookings.md)) | `sl:bookings:write` (`sl:bookings:read` to read) |
 

package/dist/openapi.yaml

@@ -21235,6 +21235,32 @@ components:
         - id
         - title
         - component
+    ConnectorAction:
+      type: object
+      properties:
+        name:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        function:
+          type: string
+        visibility:
+          type: string
+          enum:
+            - admin
+            - member
+            - public
+        input:
+          type: object
+          additionalProperties: true
+        output:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+        - function
     AppConnectorDeclaration:
       type: object
       properties:
@@ -21288,6 +21314,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ConnectorPanel"
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorAction"
         aiGuide:
           type: string
         recordId:
@@ -29060,6 +29090,10 @@ components:
           additionalProperties: true
         eventMapping:
           $ref: "#/components/schemas/EventMapping"
+        envelopeFormat:
+          type: string
+          enum:
+            - cloudevents
         connection:
           $ref: "#/components/schemas/FlowConnection"
         fieldMappings:
@@ -29520,6 +29554,8 @@ components:
     EventEnvelope:
       type: object
       properties:
+        specVersion:
+          type: number
         id:
           type: string
         type:
@@ -29547,6 +29583,10 @@ components:
           type: object
           additionalProperties:
             type: string
+        anonymousId:
+          type: string
+        sessionId:
+          type: string
         emailHash:
           type: string
         phoneHash:
@@ -29567,6 +29607,9 @@ components:
         proof:
           type: object
           additionalProperties: true
+        consent:
+          type: object
+          additionalProperties: true
         subject:
           type: object
           additionalProperties: true
@@ -29577,6 +29620,7 @@ components:
           type: object
           additionalProperties: true
       required:
+        - specVersion
         - id
         - type
         - entityType
@@ -29589,9 +29633,12 @@ components:
         - contactId
         - userId
         - externalIds
+        - anonymousId
+        - sessionId
         - identityPolicy
         - product
         - proof
+        - consent
         - subject
         - attributes
     CapturedRequest:

package/dist/types/appManifest.d.ts

@@ -1030,6 +1030,27 @@ export interface ConnectorPanel {
     /** Exported component name in the app's widgets bundle (manifest `widgets.files`). */
     component: string;
 }
+/**
+ * A named provider operation invoked ON DEMAND (not by the engine): redeem a reward, enrol a member,
+ * issue a coupon, raise a ticket, send a receipt. Called by an app function (`ctx.sl.connectors.call`),
+ * by the Hub (public route — only `public`, or `member` for a signed-in person) or by the console. The
+ * function receives `{ input, installation, caller }` and returns JSON; it runs with the connector's
+ * own credentials and is told who asked.
+ */
+export interface ConnectorAction {
+    /** `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$` */
+    name: string;
+    title?: string;
+    description?: string;
+    /** This app's server function implementing it. */
+    function: string;
+    /** Who may invoke it outside functions and the console. Default 'admin'. */
+    visibility?: 'admin' | 'member' | 'public';
+    /** JSON Schema for `input`; `required` fields are checked before the function runs. */
+    input?: Record<string, unknown>;
+    /** JSON Schema for the result (documentation; not enforced). */
+    output?: Record<string, unknown>;
+}
 /**
  * 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
@@ -1092,6 +1113,8 @@ export interface AppConnectorDeclaration {
         lookup?: string;
     };
     panels?: ConnectorPanel[];
+    /** On-demand operations the connector offers (see ConnectorAction). */
+    actions?: ConnectorAction[];
     /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
     aiGuide?: string;
     /**

package/dist/types/integrations.d.ts

@@ -92,6 +92,12 @@ export interface IntegrationFlowConfig {
     };
     /** Event-sourced flows: fold SmartLinks events into the provider's registered events. */
     eventMapping?: EventMapping;
+    /**
+     * Wrap each delivered body as a CloudEvents 1.0 structured event
+     * ({ specversion, id, type, source, subject, time, datacontenttype, dataschema, data }) — the shape
+     * event buses, lakes and serverless tools consume without custom code.
+     */
+    envelopeFormat?: 'cloudevents';
     connection?: FlowConnection;
     fieldMappings?: FieldMapping[];
     /** Run this flow through a connector app's functions instead of the built-in mapper/transport. */
@@ -369,6 +375,8 @@ export interface ConnectorLookupResult {
  * connector's `serialize` / `send`, after the flow's identity policy and event mapping.
  */
 export interface EventEnvelope {
+    /** Schema version of this envelope. Bumped only when a consumer could break (a field removed or changed). */
+    specVersion: number;
     /** The event's id: stable across retries; use it as the provider's transaction / idempotency id. */
     id: string;
     /** Spine event name, e.g. 'interaction.submitted:<typeId>', 'contact.updated', 'tag.scanned:scan_redirect'. */
@@ -384,6 +392,9 @@ export interface EventEnvelope {
         userId: string | null;
         /** Ids other systems know this person by, keyed by system (a connector's `provider`). */
         externalIds: Record<string, string>;
+        /** The visitor / device id before anyone signed in (an analytics destination stitches on it later). Under every policy. */
+        anonymousId: string | null;
+        sessionId: string | null;
         emailHash?: string | null;
         phoneHash?: string | null;
         hashAlgorithm?: 'hmac-sha256' | null;
@@ -403,6 +414,15 @@ export interface EventEnvelope {
     proof: {
         id: string;
     } | null;
+    /**
+     * The person's communication consent, summarised per channel from the contact's comms state; null
+     * when the event is about nobody we hold. A CRM or CDP must not act against it.
+     */
+    consent: {
+        channels: Record<'email' | 'sms' | 'push' | 'whatsapp', 'opted_in' | 'opted_out' | 'suppressed' | 'unknown'>;
+        topics: Record<string, boolean>;
+        updatedAt: string | null;
+    } | null;
     /** The event's own fields: an interaction's interactionId / outcome / metadata, a scan's codeId / country, a contact's profile. */
     subject: Record<string, unknown>;
     /** From the flow's event mapping, when it has one. */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.14  |  Generated: 2026-11-09T13:01:05.900Z
+Version: 2.1.15  |  Generated: 2026-11-09T15:17:42.472Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,7 +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), event patterns, the event envelope (interaction/contact/event sources), identity policy, event mapping, signed deliveries, contact as a target, field mappings
-- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send/describeEvents/lookup); loyalty and CRM connectors; core does the mapping
+- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send/describeEvents/lookup); loyalty and CRM connectors; actions (provider operations on demand); core does the mapping
 - **[Entitlements](entitlements.md)** - "Is this person gold or above?" answered on demand from signed claims, a connector lookup (cached), or the contact — never a mirrored member base; gates on interaction types and in server functions
 - **[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
@@ -3112,6 +3112,19 @@ interface ConnectorPanel {
 }
 ```
 
+**ConnectorAction** (interface)
+```typescript
+interface ConnectorAction {
+  name: string
+  title?: string
+  description?: string
+  function: string
+  visibility?: 'admin' | 'member' | 'public'
+  input?: Record<string, unknown>
+  output?: Record<string, unknown>
+}
+```
+
 **AppConnectorDeclaration** (interface)
 ```typescript
 interface AppConnectorDeclaration {
@@ -3134,6 +3147,7 @@ interface AppConnectorDeclaration {
   lookup?: string
   }
   panels?: ConnectorPanel[]
+  actions?: ConnectorAction[]
   aiGuide?: string
   recordId?: string
   limits?: { requestsPerSecond?: number; maxEvents?: number; maxAttributes?: number }
@@ -7980,6 +7994,7 @@ interface IntegrationFlowConfig {
   signing?: { credentialRef: string; previousCredentialRef?: string }
   identity?: { policy?: IdentityPolicy; hashKeyCredentialRef?: string }
   eventMapping?: EventMapping
+  envelopeFormat?: 'cloudevents'
   connection?: FlowConnection
   fieldMappings?: FieldMapping[]
   connector?: FlowConnectorRef
@@ -8222,6 +8237,7 @@ interface ConnectorLookupResult {
 **EventEnvelope** (interface)
 ```typescript
 interface EventEnvelope {
+  specVersion: number
   id: string
   type: string
   entityType: string | null
@@ -8234,6 +8250,8 @@ interface EventEnvelope {
   contactId: string | null
   userId: string | null
   externalIds: Record<string, string>
+  anonymousId: string | null
+  sessionId: string | null
   emailHash?: string | null
   phoneHash?: string | null
   hashAlgorithm?: 'hmac-sha256' | null
@@ -8243,6 +8261,7 @@ interface EventEnvelope {
   identityPolicy: IdentityPolicy
   product: { id: string; name?: string | null; sku?: string | null; gtin?: string | null; variantId?: string | null; batchId?: string | null } | null
   proof: { id: string } | null
+  consent: { channels: Record<'email' | 'sms' | 'push' | 'whatsapp', 'opted_in' | 'opted_out' | 'suppressed' | 'unknown'>; topics: Record<string, boolean>; updatedAt: string | null } | null
   subject: Record<string, unknown>
   event?: { name: string; attributes: Record<string, unknown>; rule: string | null }
   attributes: Record<string, unknown>
@@ -12984,6 +13003,22 @@ Save a connector's non-secret Connect-form values and/or settings. PUT /integrat
     input: Record<string, unknown> & { flowId?: string } = {}) → `Promise<T>`
 Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, and dry runs of `shape` ({ records }) → ConnectorShapeResult and `serialize` ({ documents }) → ConnectorSerializeResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
 
+**runConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a coupon… The connector's function runs with its own credentials and is told who asked. POST /integrations/connectors/:appId/actions/:action { input }
+
+**listConnectorActions**(collectionId: string,
+    appId: string) → `Promise<`
+PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`, plus `member` ones when signed in. GET /public/collection/:collectionId/connectors/:appId/actions
+
+**callConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member. 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one; 400 with `missing[]` when a required input is absent. POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+
 ### interactions
 
 **query**(collectionId: string,

package/docs/connectors.md

@@ -92,6 +92,7 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
 | `recordId` | Path of the provider's own id in a fetched record (e.g. `gtin`). Inbound records are landed and matched by it, so a re-import updates the same product instead of creating another. Default `id`; a flow can override it (`config.upsert.externalIdPath`). |
 | `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker; `{ maxEvents, maxAttributes }` when the provider caps registered events — a flow's `eventMapping` is checked against them when saved. |
+| `actions[]` | Provider operations invoked on demand (redeem, enrol, issue…): name, title, function, `visibility`, input schema. See [Actions](#actions-provider-operations-on-demand). |
 
 ---
 
@@ -219,6 +220,61 @@ A connector should ship an `eventMapping` **preset** with the provider's standar
 
 ---
 
+## Actions: provider operations on demand
+
+Steps are called by the engine. **Actions** are called when someone asks: redeem a reward, enrol a
+member, issue a coupon, raise a ticket, send a receipt, check a balance. A connector declares them in
+the manifest and implements each as a server function; the platform decides who may call them and
+runs them with the connector's credentials, telling the function who asked.
+
+```jsonc
+"connector": {
+  "actions": [
+    { "name": "redeem", "title": "Redeem a reward", "function": "redeemReward", "visibility": "member",
+      "input": { "type": "object", "required": ["rewardId"], "properties": { "rewardId": { "type": "string" } } } },
+    { "name": "enrol", "title": "Join the programme", "function": "enrolMember", "visibility": "member" },
+    { "name": "coupon-status", "title": "Coupon status", "function": "couponStatus", "visibility": "public" },
+    { "name": "adjust-points", "title": "Adjust points", "function": "adjustPoints" }     // admin only (the default)
+  ]
+}
+```
+
+| `visibility` | Who may invoke it |
+|---|---|
+| `admin` (default) | the console and admin API; any app function |
+| `member` | also a signed-in person through the Hub / a site |
+| `public` | also anyone |
+
+The function receives `event.body = { input, installation, caller: { userId, contactId, role, surface } }`
+and returns JSON (or a `Response`). `input.required` fields from the declared schema are checked before
+the function runs (400 with `missing[]`); fuller validation is the connector's job.
+
+```ts
+export async function redeemReward(ctx: any, event: any) {
+  const { input, caller } = event.body
+  if (!caller.contactId) return new Response(JSON.stringify({ error: 'no_contact' }), { status: 400 })
+  const memberId = (await ctx.sl.contacts.forCaller())?.customFields?.loyaltyMemberId   // written by Profile
+  const res = await ctx.fetch(`${api}/members/${memberId}/redemptions`, { method: 'POST', headers: auth(await ctx.secrets.get('apiKey')), body: JSON.stringify({ reward: input.rewardId }) })
+  return res.json()
+}
+```
+
+Calling an action:
+
+```ts
+// From the Hub or a site (visibility public / member):
+const { actions } = await integrations.listConnectorActions(collectionId, 'acme-loyalty')
+const out = await integrations.callConnectorAction(collectionId, 'acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From another app's server function (any visibility; needs sl:connectors:write):
+const out = await ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From the console (any visibility):
+await integrations.runConnectorAction(collectionId, 'acme-loyalty', 'adjust-points', { memberId, delta: 100 })
+```
+
+---
+
 ## Where configuration lives
 
 | What | Where |

package/docs/integrations.md

@@ -118,6 +118,7 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
 
 ```jsonc
 {
+  "specVersion": 1,                            // bumped only when a consumer could break
   "id": "0b2b…",                               // the event's id — stable across retries; use it as the destination's idempotency / transaction id
   "type": "interaction.submitted:quiz-1",
   "entityType": "interaction", "entityId": "0b2b…",
@@ -126,12 +127,14 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
   "identity": {
     "contactId": "…", "userId": "…",
     "externalIds": { "acme-loyalty": "M-9", "crm": "C-1" },     // ids other systems know this person by
+    "anonymousId": "v-77", "sessionId": "s-1",                  // the visitor / device and session, before anyone signed in (every policy)
     "emailHash": "…", "phoneHash": "…", "hashAlgorithm": "hmac-sha256"   // policy 'hashed' (default)
     // "email", "phone": only under policy 'raw'
   },
   "identityPolicy": "hashed",
   "product": { "id": "P1", "name": "Widget", "sku": "W-1", "gtin": "0500…", "variantId": null, "batchId": null },
   "proof": { "id": "…" },
+  "consent": { "channels": { "email": "opted_in", "sms": "suppressed", "push": "unknown", "whatsapp": "unknown" }, "topics": { "offers": true }, "updatedAt": "…" },   // null when about nobody we hold
   "subject": { "interactionId": "quiz-1", "outcome": "completed", "metadata": { "score": 9 }, "source": "hub" },
   "event": { "name": "engagement_completed", "attributes": { "kind": "quiz", "score": 9 }, "rule": "quiz" },   // from eventMapping
   "attributes": {}
@@ -142,6 +145,11 @@ Field mappings read envelope paths (`identity.externalIds.acme-loyalty`, `subjec
 `event.name`, `product.sku`). With no mappings the envelope itself is sent. A failed event delivery
 keeps its envelope and is retried from it; a product is re-read instead.
 
+**CloudEvents.** `config.envelopeFormat: 'cloudevents'` wraps each delivered body (mapped or not) as a
+CloudEvents 1.0 structured event — `{ specversion: '1.0', id, type, source: 'urn:smartlinks:collection:<id>',
+subject, time, datacontenttype, dataschema: 'urn:smartlinks:envelope:v1', data }` — the shape every event
+bus, lake and serverless tool already consumes.
+
 ```ts
 const flow = await integrations.createFlow(collectionId, {
   appId: 'core-integrations', direction: 'outbound', name: 'Engagement → loyalty', status: 'active',

package/docs/server-functions.md

@@ -518,6 +518,7 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Put a visitor's details on a contact | `ctx.sl.contacts.upsert({ email, firstName, … })` → `{ contactId, created }` (fills empty fields only) | `sl:contacts:write` |
 | Record "they did X" | `ctx.sl.interactions.record({ interactionId, contactId, outcome, metadata })` | `sl:interactions:write` |
 | Land a loyalty / CRM provider's view of a person (member id, tier, points, tags, external ids) | `ctx.sl.members.apply({ identity, contact?, loyalty?, tags?, externalIds? }, { provider })` → `{ contactId, op }` — matches by id, external id, email or phone; profile fields fill-empty only; see [connectors.md](connectors.md#loyalty-and-crm-connectors) | `sl:members:write` |
+| Invoke a connector's action — redeem, enrol, issue a coupon, raise a ticket — with the connector's credentials | `ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId })` → the action's result; `ctx.sl.connectors.actions(appId)` lists them; see [connectors.md](connectors.md#actions-provider-operations-on-demand) | `sl:connectors:write` |
 | Ask "is this person gold or above?" without holding their member record | `ctx.sl.entitlements.check('tier>=gold')` → `{ allowed, basis, asOf, attributes }` for the signed-in caller (or `{ identity, token, fallback }`); see [entitlements.md](entitlements.md) | `sl:entitlements:read` |
 | Take a booking with your own checks (hours, queue token, payment) | `ctx.sl.bookings.create({ slotId \| resource + time, contactId, status, idempotencyKey })` — never oversold, never double-booked; also `confirm` / `cancel` / `move` / `mine` / `freebusy` / `message` (everyone booked, hydrated) / `slots.*` / `blocks.*` (see [bookings.md](bookings.md)) | `sl:bookings:write` (`sl:bookings:read` to read) |
 

package/openapi.yaml

@@ -21235,6 +21235,32 @@ components:
         - id
         - title
         - component
+    ConnectorAction:
+      type: object
+      properties:
+        name:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        function:
+          type: string
+        visibility:
+          type: string
+          enum:
+            - admin
+            - member
+            - public
+        input:
+          type: object
+          additionalProperties: true
+        output:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+        - function
     AppConnectorDeclaration:
       type: object
       properties:
@@ -21288,6 +21314,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ConnectorPanel"
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorAction"
         aiGuide:
           type: string
         recordId:
@@ -29060,6 +29090,10 @@ components:
           additionalProperties: true
         eventMapping:
           $ref: "#/components/schemas/EventMapping"
+        envelopeFormat:
+          type: string
+          enum:
+            - cloudevents
         connection:
           $ref: "#/components/schemas/FlowConnection"
         fieldMappings:
@@ -29520,6 +29554,8 @@ components:
     EventEnvelope:
       type: object
       properties:
+        specVersion:
+          type: number
         id:
           type: string
         type:
@@ -29547,6 +29583,10 @@ components:
           type: object
           additionalProperties:
             type: string
+        anonymousId:
+          type: string
+        sessionId:
+          type: string
         emailHash:
           type: string
         phoneHash:
@@ -29567,6 +29607,9 @@ components:
         proof:
           type: object
           additionalProperties: true
+        consent:
+          type: object
+          additionalProperties: true
         subject:
           type: object
           additionalProperties: true
@@ -29577,6 +29620,7 @@ components:
           type: object
           additionalProperties: true
       required:
+        - specVersion
         - id
         - type
         - entityType
@@ -29589,9 +29633,12 @@ components:
         - contactId
         - userId
         - externalIds
+        - anonymousId
+        - sessionId
         - identityPolicy
         - product
         - proof
+        - consent
         - subject
         - attributes
     CapturedRequest:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.1.14",
+  "version": "2.1.15",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",