@proveanything/smartlinks 1.13.8 → 1.13.9

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.8  |  Generated: 2026-05-11T12:03:30.435Z
+Version: 1.13.9  |  Generated: 2026-05-12T11:17:48.753Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5457,8 +5457,9 @@ interface InteractionTypeRecord {
   permissions?: InteractionPermissions
   data?: {
   display?: InteractionDisplay
-  scopes?: Record<string, InteractionDisplay>;
+  scopes?: Record<string, InteractionDisplay>
   interactionType?: string
+  effects?: InteractionEffect[]
   [key: string]: unknown
   }
   createdAt: string
@@ -5526,6 +5527,113 @@ interface SubmitInteractionError {
 }
 ```
 
+**InteractionEffect** (interface)
+```typescript
+interface InteractionEffect {
+  type: EffectType
+  config?: EffectConfig
+}
+```
+
+**LoyaltyEffectConfig** (interface)
+```typescript
+interface LoyaltyEffectConfig {
+  [key: string]: never
+}
+```
+
+**TransactionalEffectConfig** (interface)
+```typescript
+interface TransactionalEffectConfig {
+  templateId: string
+  * Channel to use.
+  * Default: 'preferred' — auto-selects the contact's best available channel.
+  channel?: 'email' | 'sms' | 'push' | 'whatsapp' | 'wallet' | 'preferred'
+  props?: Record<string, unknown>
+  include?: {
+  productId?: string
+  proofId?:   string
+  user?:      boolean
+  appCase?:   string
+  appThread?: string
+  appRecord?: string
+  }
+  appId?: string
+}
+```
+
+**WebhookEffectConfig** (interface)
+```typescript
+interface WebhookEffectConfig {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  body?: Record<string, unknown>
+  timeout?: number
+}
+```
+
+**TagEffectConfig** (interface)
+```typescript
+interface TagEffectConfig {
+  tags: string[]
+  action?: 'add' | 'remove'
+}
+```
+
+**AppRecordEffectConfig** (interface)
+```typescript
+interface AppRecordEffectConfig {
+  appId?: string
+  recordType?: string
+  * Singleton cardinality key. At most one record per recordType+singletonPer will
+  * exist per scope. Common values: 'contact', 'product', 'proof', 'global'
+  singletonPer?: string
+  data?: Record<string, unknown>
+  anchors?: {
+  productId?: string
+  proofId?:   string
+  variantId?: string
+  batchId?:   string
+  }
+}
+```
+
+**SegmentEffectConfig** (interface)
+```typescript
+interface SegmentEffectConfig {
+  segmentId: string
+  action?: 'add' | 'remove'
+}
+```
+
+**InteractionEventContext** (interface)
+```typescript
+interface InteractionEventContext {
+  eventId:       string | null
+  collectionId:  string
+  appId:         string | null
+  interactionId: string | null
+  contactId:     string | null
+  userId:        string | null
+  productId:     string | null
+  proofId:       string | null
+  variantId:     string | null
+  batchId:       string | null
+  outcome:       string | null
+  eventType:     string | null
+  source:        string | null
+  timestamp:     string | null
+  metadata:      Record<string, unknown>
+  broadcastId:   string | null
+  journeyId:     string | null
+}
+```
+
+**EffectType** = ``
+
+**EffectConfig** = ``
+
 ### jobs
 
 **Job** (interface)

package/dist/docs/interactions.md

@@ -280,6 +280,195 @@ When defining a journey trigger, reference the `interactionId` that should fire
 
 ---
 
+## Interaction Effects
+
+**Interaction effects** are automatic side-effects that fire immediately after an interaction event is recorded. They are defined directly on the interaction definition (`data.effects`) and run inline, fire-and-forget — they never block or fail the interaction response.
+
+Common use cases: send a confirmation email, post a webhook to a CRM, tag the contact, award loyalty points, create an app record, or add the contact to a segment.
+
+### How It Works
+
+1. Event is logged to BigQuery
+2. Interaction definition is loaded
+3. Each configured effect runs **in order**, fire-and-forget
+4. Response is returned to the caller immediately
+
+A failure in one effect is logged and swallowed; subsequent effects still run.
+
+> **Note:** `transactional` and `webhook` effects currently run inline. They are planned to move to background jobs for retry-on-failure support once the jobs infrastructure is fully operational.
+
+### Configuring Effects
+
+Pass `data.effects` when creating or updating an interaction type:
+
+```typescript
+await SL.interactions.create(collectionId, {
+  id: 'donation',
+  appId: 'my-app',
+  permissions: { allowPublicSubmit: true },
+  data: {
+    effects: [
+      {
+        type: 'transactional',
+        config: {
+          templateId: 'tmpl_donation_receipt',
+          channel: 'email',
+          props: {
+            donationAmount: '{{metadata.amount}}',
+            campaignName: '{{metadata.campaign}}',
+          },
+        },
+      },
+      {
+        type: 'tag',
+        config: { tags: ['donor'] },
+      },
+    ],
+  },
+});
+```
+
+### Token Interpolation
+
+All effect `config` values support `{{token}}` interpolation resolved from the event context at runtime. Nested paths using dot notation are supported (e.g. `{{metadata.amount}}`).
+
+| Token | Description |
+|---|---|
+| `{{eventId}}` | BigQuery event UUID |
+| `{{collectionId}}` | Collection / brand ID |
+| `{{appId}}` | App ID that submitted the event |
+| `{{interactionId}}` | Interaction definition ID |
+| `{{contactId}}` | Contact UUID (if resolved) |
+| `{{userId}}` | Firebase UID (if authenticated) |
+| `{{productId}}` | Product ID (if provided with event) |
+| `{{proofId}}` | Proof ID (if provided with event) |
+| `{{variantId}}` | Variant ID (if provided with event) |
+| `{{batchId}}` | Batch ID (if provided with event) |
+| `{{outcome}}` | Event outcome (e.g. `"submitted"`) |
+| `{{eventType}}` | Event type string |
+| `{{source}}` | Event source string |
+| `{{timestamp}}` | ISO 8601 event timestamp |
+| `{{metadata.*}}` | Any key from the event `metadata` object |
+
+Tokens that resolve to `null` or `undefined` become an empty string.
+
+### Effect Types
+
+#### `loyalty`
+
+Awards loyalty points by evaluating `LoyaltyEarningRule` records configured against this interaction. Earning rules are managed separately via the Loyalty API. If no rules are configured, this effect is a no-op.
+
+```json
+{ "type": "loyalty", "config": {} }
+```
+
+#### `transactional`
+
+Sends a message to the contact using a comms template. Supports all channels with full Liquid template hydration.
+
+```json
+{
+  "type": "transactional",
+  "config": {
+    "templateId": "tmpl_donation_receipt",
+    "channel": "email",
+    "props": {
+      "donationAmount": "{{metadata.amount}}"
+    }
+  }
+}
+```
+
+`channel` defaults to `"preferred"` — auto-selects the contact's best available channel respecting consent, suppression, and template availability. Optionally pass `include` to hydrate product/proof/user context, and `props` for additional Liquid variables.
+
+#### `webhook`
+
+Posts a JSON payload to an HTTP endpoint. All config values support `{{token}}` interpolation.
+
+```json
+{
+  "type": "webhook",
+  "config": {
+    "url": "https://crm.example.com/api/events",
+    "headers": { "Authorization": "Bearer sk_live_abc123" },
+    "body": {
+      "contactId": "{{contactId}}",
+      "amount": "{{metadata.amount}}"
+    },
+    "timeout": 8000
+  }
+}
+```
+
+When `body` is omitted, a standard payload is sent containing `eventId`, `collectionId`, `appId`, `interactionId`, `contactId`, `userId`, `productId`, `proofId`, `outcome`, `eventType`, `metadata`, and `timestamp`.
+
+#### `tag`
+
+Adds or removes string tags on the contact record. Skipped if there is no `contactId` on the event.
+
+```json
+{
+  "type": "tag",
+  "config": {
+    "tags": ["donor", "tier-{{metadata.tier}}"],
+    "action": "add"
+  }
+}
+```
+
+`action` defaults to `"add"`. Duplicate adds are no-ops; removing a tag not present is a no-op.
+
+#### `appRecord`
+
+Creates or upserts an app record scoped to the event context. Use `singletonPer` for cardinality control — if a matching singleton already exists it is updated rather than duplicated.
+
+```json
+{
+  "type": "appRecord",
+  "config": {
+    "recordType": "participation",
+    "singletonPer": "contact",
+    "data": {
+      "participatedAt": "{{timestamp}}",
+      "outcome": "{{outcome}}"
+    }
+  }
+}
+```
+
+Common `singletonPer` values: `"contact"`, `"product"`, `"proof"`, `"global"`.
+
+#### `segment`
+
+Adds or removes the contact from a **static** segment. Skipped if there is no `contactId` on the event.
+
+```json
+{
+  "type": "segment",
+  "config": {
+    "segmentId": "seg_donors_2026",
+    "action": "add"
+  }
+}
+```
+
+The segment must already exist and be of `filterType: 'static'`.
+
+### Effects Error Handling
+
+| Scenario | Behaviour |
+|---|---|
+| Effect throws (e.g. template not found, webhook 500) | Error logged server-side; next effect continues |
+| Contact has no email, `transactional` channel = `email` | Effect throws, logged, skipped |
+| `contactId` absent on anonymous event | `tag`, `appRecord`, `segment` log a warning and skip |
+| Unknown `type` value | Warning logged, effect skipped |
+| `loyalty` — no earning rules configured | Silent no-op |
+| Interaction has no `data.effects` | No effects run, no overhead |
+
+Effects do **not** propagate errors back to the API caller.
+
+---
+
 ## TypeScript Types
 
 ```typescript
@@ -299,6 +488,17 @@ import type {
   AdminInteractionsCountsByOutcomeRequest,
   PublicInteractionsCountsByOutcomeRequest,
   PublicInteractionsByUserRequest,
+  // Effects
+  InteractionEffect,              // Single effect entry { type, config? }
+  EffectType,                     // 'loyalty' | 'transactional' | 'webhook' | 'tag' | 'appRecord' | 'segment'
+  EffectConfig,                   // Union of all effect config shapes
+  LoyaltyEffectConfig,
+  TransactionalEffectConfig,
+  WebhookEffectConfig,
+  TagEffectConfig,
+  AppRecordEffectConfig,
+  SegmentEffectConfig,
+  InteractionEventContext,        // Token interpolation context shape
 } from '@proveanything/smartlinks';
 ```
 

package/dist/openapi.yaml

@@ -21121,6 +21121,10 @@ components:
             $ref: "#/components/schemas/InteractionDisplay"
         interactionType:
           type: string
+        effects:
+          type: array
+          items:
+            $ref: "#/components/schemas/InteractionEffect"
         createdAt:
           type: string
       required:
@@ -21196,6 +21200,183 @@ components:
             - FORBIDDEN
       required:
         - error
+    InteractionEffect:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/EffectType"
+        config:
+          $ref: "#/components/schemas/EffectConfig"
+      required:
+        - type
+    LoyaltyEffectConfig:
+      type: object
+      properties: {}
+    TransactionalEffectConfig:
+      type: object
+      properties:
+        templateId:
+          type: string
+        channel:
+          type: string
+          enum:
+            - email
+            - sms
+            - push
+            - whatsapp
+            - wallet
+            - preferred
+        props:
+          type: object
+          additionalProperties: true
+        include:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        user:
+          type: boolean
+        appCase:
+          type: string
+        appThread:
+          type: string
+        appRecord:
+          type: string
+        appId:
+          type: string
+      required:
+        - templateId
+    WebhookEffectConfig:
+      type: object
+      properties:
+        url:
+          type: string
+        method:
+          type: string
+          enum:
+            - GET
+            - POST
+            - PUT
+            - PATCH
+            - DELETE
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+        body:
+          type: object
+          additionalProperties: true
+        timeout:
+          type: number
+      required:
+        - url
+    TagEffectConfig:
+      type: object
+      properties:
+        tags:
+          type: array
+          items:
+            type: string
+        action:
+          type: string
+          enum:
+            - add
+            - remove
+      required:
+        - tags
+    AppRecordEffectConfig:
+      type: object
+      properties:
+        appId:
+          type: string
+        recordType:
+          type: string
+        singletonPer:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+        anchors:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+    SegmentEffectConfig:
+      type: object
+      properties:
+        segmentId:
+          type: string
+        action:
+          type: string
+          enum:
+            - add
+            - remove
+      required:
+        - segmentId
+    InteractionEventContext:
+      type: object
+      properties:
+        eventId:
+          type: string
+        collectionId:
+          type: string
+        appId:
+          type: string
+        interactionId:
+          type: string
+        contactId:
+          type: string
+        userId:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        outcome:
+          type: string
+        eventType:
+          type: string
+        source:
+          type: string
+        timestamp:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        broadcastId:
+          type: string
+        journeyId:
+          type: string
+      required:
+        - eventId
+        - collectionId
+        - appId
+        - interactionId
+        - contactId
+        - userId
+        - productId
+        - proofId
+        - variantId
+        - batchId
+        - outcome
+        - eventType
+        - source
+        - timestamp
+        - metadata
+        - broadcastId
+        - journeyId
     Job:
       type: object
       properties:

package/dist/types/interaction.d.ts

@@ -185,6 +185,7 @@ export interface InteractionTypeRecord {
         display?: InteractionDisplay;
         scopes?: Record<string, InteractionDisplay>;
         interactionType?: string;
+        effects?: InteractionEffect[];
         [key: string]: unknown;
     };
     createdAt: string;
@@ -218,3 +219,99 @@ export interface SubmitInteractionError {
     error: 'FORBIDDEN';
     reason: 'not_public' | 'auth_required' | 'duplicate' | 'duplicate_anon' | 'disabled' | 'before_start' | 'after_end' | 'origin_forbidden';
 }
+export type EffectType = 'loyalty' | 'transactional' | 'webhook' | 'tag' | 'appRecord' | 'segment';
+export interface InteractionEffect {
+    type: EffectType;
+    config?: EffectConfig;
+}
+export type EffectConfig = LoyaltyEffectConfig | TransactionalEffectConfig | WebhookEffectConfig | TagEffectConfig | AppRecordEffectConfig | SegmentEffectConfig;
+/** No config required — earning rules are driven by the interactionId */
+export interface LoyaltyEffectConfig {
+    [key: string]: never;
+}
+export interface TransactionalEffectConfig {
+    /** Required. Firestore template ID */
+    templateId: string;
+    /**
+     * Channel to use.
+     * Default: 'preferred' — auto-selects the contact's best available channel.
+     */
+    channel?: 'email' | 'sms' | 'push' | 'whatsapp' | 'wallet' | 'preferred';
+    /** Additional Liquid variables. Supports {{token}} interpolation. */
+    props?: Record<string, unknown>;
+    /** Hydration directives. productId/proofId default to the event's own values. */
+    include?: {
+        productId?: string;
+        proofId?: string;
+        user?: boolean;
+        appCase?: string;
+        appThread?: string;
+        appRecord?: string;
+    };
+    /** Override the appId logged on the comms event row. */
+    appId?: string;
+}
+export interface WebhookEffectConfig {
+    /** Required. Target URL. Supports {{token}} interpolation. */
+    url: string;
+    /** HTTP verb. Default: 'POST' */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Additional HTTP headers. Supports {{token}} interpolation on values. */
+    headers?: Record<string, string>;
+    /** JSON body template. Supports {{token}} interpolation on string values. */
+    body?: Record<string, unknown>;
+    /** Request timeout in milliseconds. Default: 10000 */
+    timeout?: number;
+}
+export interface TagEffectConfig {
+    /** One or more tag strings to add or remove. Supports {{token}} interpolation. */
+    tags: string[];
+    /** Default: 'add' */
+    action?: 'add' | 'remove';
+}
+export interface AppRecordEffectConfig {
+    /** Override the appId for the created record. */
+    appId?: string;
+    /** Record type identifier. Default: 'default' */
+    recordType?: string;
+    /**
+     * Singleton cardinality key. At most one record per recordType+singletonPer will
+     * exist per scope. Common values: 'contact', 'product', 'proof', 'global'
+     */
+    singletonPer?: string;
+    /** Data object stored on the record. Supports {{token}} interpolation. */
+    data?: Record<string, unknown>;
+    /** Override scope anchors. Defaults to the event's own ids. */
+    anchors?: {
+        productId?: string;
+        proofId?: string;
+        variantId?: string;
+        batchId?: string;
+    };
+}
+export interface SegmentEffectConfig {
+    /** Required. UUID of the static segment to modify */
+    segmentId: string;
+    /** Default: 'add' */
+    action?: 'add' | 'remove';
+}
+/** Shape of the event context used for {{token}} interpolation in effect configs */
+export interface InteractionEventContext {
+    eventId: string | null;
+    collectionId: string;
+    appId: string | null;
+    interactionId: string | null;
+    contactId: string | null;
+    userId: string | null;
+    productId: string | null;
+    proofId: string | null;
+    variantId: string | null;
+    batchId: string | null;
+    outcome: string | null;
+    eventType: string | null;
+    source: string | null;
+    timestamp: string | null;
+    metadata: Record<string, unknown>;
+    broadcastId: string | null;
+    journeyId: string | null;
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.8  |  Generated: 2026-05-11T12:03:30.435Z
+Version: 1.13.9  |  Generated: 2026-05-12T11:17:48.753Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5457,8 +5457,9 @@ interface InteractionTypeRecord {
   permissions?: InteractionPermissions
   data?: {
   display?: InteractionDisplay
-  scopes?: Record<string, InteractionDisplay>;
+  scopes?: Record<string, InteractionDisplay>
   interactionType?: string
+  effects?: InteractionEffect[]
   [key: string]: unknown
   }
   createdAt: string
@@ -5526,6 +5527,113 @@ interface SubmitInteractionError {
 }
 ```
 
+**InteractionEffect** (interface)
+```typescript
+interface InteractionEffect {
+  type: EffectType
+  config?: EffectConfig
+}
+```
+
+**LoyaltyEffectConfig** (interface)
+```typescript
+interface LoyaltyEffectConfig {
+  [key: string]: never
+}
+```
+
+**TransactionalEffectConfig** (interface)
+```typescript
+interface TransactionalEffectConfig {
+  templateId: string
+  * Channel to use.
+  * Default: 'preferred' — auto-selects the contact's best available channel.
+  channel?: 'email' | 'sms' | 'push' | 'whatsapp' | 'wallet' | 'preferred'
+  props?: Record<string, unknown>
+  include?: {
+  productId?: string
+  proofId?:   string
+  user?:      boolean
+  appCase?:   string
+  appThread?: string
+  appRecord?: string
+  }
+  appId?: string
+}
+```
+
+**WebhookEffectConfig** (interface)
+```typescript
+interface WebhookEffectConfig {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  body?: Record<string, unknown>
+  timeout?: number
+}
+```
+
+**TagEffectConfig** (interface)
+```typescript
+interface TagEffectConfig {
+  tags: string[]
+  action?: 'add' | 'remove'
+}
+```
+
+**AppRecordEffectConfig** (interface)
+```typescript
+interface AppRecordEffectConfig {
+  appId?: string
+  recordType?: string
+  * Singleton cardinality key. At most one record per recordType+singletonPer will
+  * exist per scope. Common values: 'contact', 'product', 'proof', 'global'
+  singletonPer?: string
+  data?: Record<string, unknown>
+  anchors?: {
+  productId?: string
+  proofId?:   string
+  variantId?: string
+  batchId?:   string
+  }
+}
+```
+
+**SegmentEffectConfig** (interface)
+```typescript
+interface SegmentEffectConfig {
+  segmentId: string
+  action?: 'add' | 'remove'
+}
+```
+
+**InteractionEventContext** (interface)
+```typescript
+interface InteractionEventContext {
+  eventId:       string | null
+  collectionId:  string
+  appId:         string | null
+  interactionId: string | null
+  contactId:     string | null
+  userId:        string | null
+  productId:     string | null
+  proofId:       string | null
+  variantId:     string | null
+  batchId:       string | null
+  outcome:       string | null
+  eventType:     string | null
+  source:        string | null
+  timestamp:     string | null
+  metadata:      Record<string, unknown>
+  broadcastId:   string | null
+  journeyId:     string | null
+}
+```
+
+**EffectType** = ``
+
+**EffectConfig** = ``
+
 ### jobs
 
 **Job** (interface)

package/docs/interactions.md

@@ -280,6 +280,195 @@ When defining a journey trigger, reference the `interactionId` that should fire
 
 ---
 
+## Interaction Effects
+
+**Interaction effects** are automatic side-effects that fire immediately after an interaction event is recorded. They are defined directly on the interaction definition (`data.effects`) and run inline, fire-and-forget — they never block or fail the interaction response.
+
+Common use cases: send a confirmation email, post a webhook to a CRM, tag the contact, award loyalty points, create an app record, or add the contact to a segment.
+
+### How It Works
+
+1. Event is logged to BigQuery
+2. Interaction definition is loaded
+3. Each configured effect runs **in order**, fire-and-forget
+4. Response is returned to the caller immediately
+
+A failure in one effect is logged and swallowed; subsequent effects still run.
+
+> **Note:** `transactional` and `webhook` effects currently run inline. They are planned to move to background jobs for retry-on-failure support once the jobs infrastructure is fully operational.
+
+### Configuring Effects
+
+Pass `data.effects` when creating or updating an interaction type:
+
+```typescript
+await SL.interactions.create(collectionId, {
+  id: 'donation',
+  appId: 'my-app',
+  permissions: { allowPublicSubmit: true },
+  data: {
+    effects: [
+      {
+        type: 'transactional',
+        config: {
+          templateId: 'tmpl_donation_receipt',
+          channel: 'email',
+          props: {
+            donationAmount: '{{metadata.amount}}',
+            campaignName: '{{metadata.campaign}}',
+          },
+        },
+      },
+      {
+        type: 'tag',
+        config: { tags: ['donor'] },
+      },
+    ],
+  },
+});
+```
+
+### Token Interpolation
+
+All effect `config` values support `{{token}}` interpolation resolved from the event context at runtime. Nested paths using dot notation are supported (e.g. `{{metadata.amount}}`).
+
+| Token | Description |
+|---|---|
+| `{{eventId}}` | BigQuery event UUID |
+| `{{collectionId}}` | Collection / brand ID |
+| `{{appId}}` | App ID that submitted the event |
+| `{{interactionId}}` | Interaction definition ID |
+| `{{contactId}}` | Contact UUID (if resolved) |
+| `{{userId}}` | Firebase UID (if authenticated) |
+| `{{productId}}` | Product ID (if provided with event) |
+| `{{proofId}}` | Proof ID (if provided with event) |
+| `{{variantId}}` | Variant ID (if provided with event) |
+| `{{batchId}}` | Batch ID (if provided with event) |
+| `{{outcome}}` | Event outcome (e.g. `"submitted"`) |
+| `{{eventType}}` | Event type string |
+| `{{source}}` | Event source string |
+| `{{timestamp}}` | ISO 8601 event timestamp |
+| `{{metadata.*}}` | Any key from the event `metadata` object |
+
+Tokens that resolve to `null` or `undefined` become an empty string.
+
+### Effect Types
+
+#### `loyalty`
+
+Awards loyalty points by evaluating `LoyaltyEarningRule` records configured against this interaction. Earning rules are managed separately via the Loyalty API. If no rules are configured, this effect is a no-op.
+
+```json
+{ "type": "loyalty", "config": {} }
+```
+
+#### `transactional`
+
+Sends a message to the contact using a comms template. Supports all channels with full Liquid template hydration.
+
+```json
+{
+  "type": "transactional",
+  "config": {
+    "templateId": "tmpl_donation_receipt",
+    "channel": "email",
+    "props": {
+      "donationAmount": "{{metadata.amount}}"
+    }
+  }
+}
+```
+
+`channel` defaults to `"preferred"` — auto-selects the contact's best available channel respecting consent, suppression, and template availability. Optionally pass `include` to hydrate product/proof/user context, and `props` for additional Liquid variables.
+
+#### `webhook`
+
+Posts a JSON payload to an HTTP endpoint. All config values support `{{token}}` interpolation.
+
+```json
+{
+  "type": "webhook",
+  "config": {
+    "url": "https://crm.example.com/api/events",
+    "headers": { "Authorization": "Bearer sk_live_abc123" },
+    "body": {
+      "contactId": "{{contactId}}",
+      "amount": "{{metadata.amount}}"
+    },
+    "timeout": 8000
+  }
+}
+```
+
+When `body` is omitted, a standard payload is sent containing `eventId`, `collectionId`, `appId`, `interactionId`, `contactId`, `userId`, `productId`, `proofId`, `outcome`, `eventType`, `metadata`, and `timestamp`.
+
+#### `tag`
+
+Adds or removes string tags on the contact record. Skipped if there is no `contactId` on the event.
+
+```json
+{
+  "type": "tag",
+  "config": {
+    "tags": ["donor", "tier-{{metadata.tier}}"],
+    "action": "add"
+  }
+}
+```
+
+`action` defaults to `"add"`. Duplicate adds are no-ops; removing a tag not present is a no-op.
+
+#### `appRecord`
+
+Creates or upserts an app record scoped to the event context. Use `singletonPer` for cardinality control — if a matching singleton already exists it is updated rather than duplicated.
+
+```json
+{
+  "type": "appRecord",
+  "config": {
+    "recordType": "participation",
+    "singletonPer": "contact",
+    "data": {
+      "participatedAt": "{{timestamp}}",
+      "outcome": "{{outcome}}"
+    }
+  }
+}
+```
+
+Common `singletonPer` values: `"contact"`, `"product"`, `"proof"`, `"global"`.
+
+#### `segment`
+
+Adds or removes the contact from a **static** segment. Skipped if there is no `contactId` on the event.
+
+```json
+{
+  "type": "segment",
+  "config": {
+    "segmentId": "seg_donors_2026",
+    "action": "add"
+  }
+}
+```
+
+The segment must already exist and be of `filterType: 'static'`.
+
+### Effects Error Handling
+
+| Scenario | Behaviour |
+|---|---|
+| Effect throws (e.g. template not found, webhook 500) | Error logged server-side; next effect continues |
+| Contact has no email, `transactional` channel = `email` | Effect throws, logged, skipped |
+| `contactId` absent on anonymous event | `tag`, `appRecord`, `segment` log a warning and skip |
+| Unknown `type` value | Warning logged, effect skipped |
+| `loyalty` — no earning rules configured | Silent no-op |
+| Interaction has no `data.effects` | No effects run, no overhead |
+
+Effects do **not** propagate errors back to the API caller.
+
+---
+
 ## TypeScript Types
 
 ```typescript
@@ -299,6 +488,17 @@ import type {
   AdminInteractionsCountsByOutcomeRequest,
   PublicInteractionsCountsByOutcomeRequest,
   PublicInteractionsByUserRequest,
+  // Effects
+  InteractionEffect,              // Single effect entry { type, config? }
+  EffectType,                     // 'loyalty' | 'transactional' | 'webhook' | 'tag' | 'appRecord' | 'segment'
+  EffectConfig,                   // Union of all effect config shapes
+  LoyaltyEffectConfig,
+  TransactionalEffectConfig,
+  WebhookEffectConfig,
+  TagEffectConfig,
+  AppRecordEffectConfig,
+  SegmentEffectConfig,
+  InteractionEventContext,        // Token interpolation context shape
 } from '@proveanything/smartlinks';
 ```
 

package/openapi.yaml

@@ -21121,6 +21121,10 @@ components:
             $ref: "#/components/schemas/InteractionDisplay"
         interactionType:
           type: string
+        effects:
+          type: array
+          items:
+            $ref: "#/components/schemas/InteractionEffect"
         createdAt:
           type: string
       required:
@@ -21196,6 +21200,183 @@ components:
             - FORBIDDEN
       required:
         - error
+    InteractionEffect:
+      type: object
+      properties:
+        type:
+          $ref: "#/components/schemas/EffectType"
+        config:
+          $ref: "#/components/schemas/EffectConfig"
+      required:
+        - type
+    LoyaltyEffectConfig:
+      type: object
+      properties: {}
+    TransactionalEffectConfig:
+      type: object
+      properties:
+        templateId:
+          type: string
+        channel:
+          type: string
+          enum:
+            - email
+            - sms
+            - push
+            - whatsapp
+            - wallet
+            - preferred
+        props:
+          type: object
+          additionalProperties: true
+        include:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        user:
+          type: boolean
+        appCase:
+          type: string
+        appThread:
+          type: string
+        appRecord:
+          type: string
+        appId:
+          type: string
+      required:
+        - templateId
+    WebhookEffectConfig:
+      type: object
+      properties:
+        url:
+          type: string
+        method:
+          type: string
+          enum:
+            - GET
+            - POST
+            - PUT
+            - PATCH
+            - DELETE
+        headers:
+          type: object
+          additionalProperties:
+            type: string
+        body:
+          type: object
+          additionalProperties: true
+        timeout:
+          type: number
+      required:
+        - url
+    TagEffectConfig:
+      type: object
+      properties:
+        tags:
+          type: array
+          items:
+            type: string
+        action:
+          type: string
+          enum:
+            - add
+            - remove
+      required:
+        - tags
+    AppRecordEffectConfig:
+      type: object
+      properties:
+        appId:
+          type: string
+        recordType:
+          type: string
+        singletonPer:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+        anchors:
+          type: object
+          additionalProperties: true
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+    SegmentEffectConfig:
+      type: object
+      properties:
+        segmentId:
+          type: string
+        action:
+          type: string
+          enum:
+            - add
+            - remove
+      required:
+        - segmentId
+    InteractionEventContext:
+      type: object
+      properties:
+        eventId:
+          type: string
+        collectionId:
+          type: string
+        appId:
+          type: string
+        interactionId:
+          type: string
+        contactId:
+          type: string
+        userId:
+          type: string
+        productId:
+          type: string
+        proofId:
+          type: string
+        variantId:
+          type: string
+        batchId:
+          type: string
+        outcome:
+          type: string
+        eventType:
+          type: string
+        source:
+          type: string
+        timestamp:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+        broadcastId:
+          type: string
+        journeyId:
+          type: string
+      required:
+        - eventId
+        - collectionId
+        - appId
+        - interactionId
+        - contactId
+        - userId
+        - productId
+        - proofId
+        - variantId
+        - batchId
+        - outcome
+        - eventType
+        - source
+        - timestamp
+        - metadata
+        - broadcastId
+        - journeyId
     Job:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.13.8",
+  "version": "1.13.9",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",