@proveanything/smartlinks 2.1.13 → 2.1.14

package/docs/interactions.md

@@ -1,540 +1,545 @@
-# Interactions: Event Tracking & Analytics
-
-The `interactions` namespace is a **critical pattern** for tracking user engagement. Many apps rely heavily on it for logging events that can trigger journeys, feed analytics dashboards, and drive aggregated results such as vote counts.
-
-If you want generic page analytics, outbound click tracking, QR landing telemetry, or tag scan dashboards, use [analytics.md](analytics.md) instead. `interactions` is for structured business events and outcomes, not general web analytics.
-
----
-
-## Overview
-
-Interactions have two distinct layers:
-
-| Layer | Purpose |
-|-------|---------|
-| **Interaction Types** | Definitions stored in the database, once per collection: permissions, display metadata, effects. **The server mints each type's `id` (a UUID).** |
-| **Interaction Events** | Individual event records logged each time a user performs that interaction. Each event's `interactionId` is a type's minted `id`. |
-
-## The one rule: create in admin → store the id in config → read it everywhere
-
-**You never choose an interaction id, and you never write one as a string literal.** You choose a readable *key* (e.g. `'vote'`); the server mints the *id* (e.g. `'52bab6fa-…'`). Events must carry the id.
-
-```typescript
-// 1. ADMIN / setup screen — find-or-create the type by your key, then store its minted id in app config.
-const vote = await SL.interactions.ensureType(collectionId, {
-  appId: 'my-app',
-  key: 'vote',                                            // your readable name — NOT the id
-  permissions: { allowPublicSubmit: true, uniquePerUser: true },
-  display: { title: 'Vote' },
-});
-const config = await SL.appConfiguration.getConfig({ collectionId, appId: 'my-app', admin: true });
-await SL.appConfiguration.setConfig({
-  collectionId, appId: 'my-app', admin: true,
-  config: { ...config, interactionIds: { ...config?.interactionIds, vote: vote.id } },
-});
-
-// 2. ANYWHERE ELSE (public widget, container, server function) — read the id from config.
-const { interactionIds } = await SL.appConfiguration.getConfig({ collectionId, appId: 'my-app' });
-await SL.interactions.submitPublicEvent(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.vote,                     // the minted id, from config
-  outcome: 'option-a',
-});
-```
-
-Why it's split this way:
-
-- **Types can only be created on the admin surface.** Public code (widgets, the portal) can submit events but can't create types — so the public side can only learn the id from somewhere admin put it. App config is that place.
-- **`ensureType` is safe to re-run.** It returns the existing type when one with that `key` exists for your app, so run it every time your setup screen saves.
-- **Unknown ids are configuration errors.** If `interactionIds.vote` is missing, the app hasn't been set up in this collection: show "not configured", don't submit, and never fall back to a literal like `'vote'`. (`interactions.create()` exists too, but it ignores any `id` you pass — read `id` from the record it returns.)
-
-The examples below use `interactionIds` — the map you read from config in step 2.
-
----
-
-## Common Use Cases
-
-| Use Case | type `key` (for `ensureType`) | `outcome` example |
-|----------|-------------------------------|-------------------|
-| Competition entry | `competition-entry` | `"entered"` |
-| Voting / polling | `vote` | `"option-a"` |
-| Mailing list signup | `newsletter-signup` | `"subscribed"` |
-| Warranty registration | `warranty-registration` | `"activated"` |
-| Product scan / view | `product-view` | `"scanned"` |
-| Form submission | `registration-form` | `"submitted"` |
-
----
-
-## Interaction Types (Definitions)
-
-Interaction types are defined once per collection and control permissions, display metadata, and uniqueness constraints.
-
-### Create a Type (find-or-create)
-
-Admin only. Returns the type record; its `id` is the minted UUID — store it in app config (see [the one rule](#the-one-rule-create-in-admin--store-the-id-in-config--read-it-everywhere)).
-
-```typescript
-const vote = await SL.interactions.ensureType(collectionId, {
-  appId: 'my-app',
-  key: 'vote',                       // stored as data.interactionType; how ensureType finds it again
-  permissions: {
-    allowPublicSubmit: true,
-    uniquePerUser: true,
-    startAt: '2026-06-01T00:00:00Z',
-    endAt: '2026-06-30T23:59:59Z',
-    allowPublicSummary: true,
-  },
-  display: {
-    title: 'Vote',
-    description: 'Cast your vote for the competition.',
-  },
-});
-// vote.id → '52bab6fa-d868-4616-9342-6731b0f332b2'
-```
-
-### Update / Delete a Type
-
-```typescript
-// Update permissions or display
-await SL.interactions.update(collectionId, interactionIds.vote, {
-  permissions: { endAt: '2026-07-15T23:59:59Z' },
-});
-
-// Delete the definition (does not delete existing events) — and remove it from your config
-await SL.interactions.remove(collectionId, interactionIds.vote);
-```
-
-### List / Get Types
-
-```typescript
-// Admin: list all types for an app (each has data.interactionType = its key)
-const { items } = await SL.interactions.list(collectionId, { appId: 'my-app' });
-
-// Admin: get a single type
-const type = await SL.interactions.get(collectionId, interactionIds.vote);
-
-// Public: list available types (respects permissions)
-const { items } = await SL.interactions.publicList(collectionId, { appId: 'my-app' });
-```
-
----
-
-## Logging Events
-
-Every `interactionId` below is a minted type id read from your app config (`interactionIds`, see [the one rule](#the-one-rule-create-in-admin--store-the-id-in-config--read-it-everywhere)). Events never create types: an id that isn't a type defined for this collection and app is a configuration error.
-
-### Admin Event Append
-
-Use on the server side or in admin flows. Requires `userId` **or** `contactId`.
-
-```typescript
-await SL.interactions.appendEvent(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.vote,
-  outcome: 'option-a',      // The result / choice — used by countsByOutcome()
-  userId: 'user_abc123',    // One of userId or contactId is required
-  productId: 'prod_xyz',    // Optional — scope to a specific product
-  scope: 'round-1',         // Optional — custom segmentation string
-  metadata: { source: 'mobile', region: 'UK' },
-});
-```
-
-### Public Event Submit
-
-Use in client-side app code. Hits the public endpoint and respects interaction permissions (`allowPublicSubmit`, `allowAnonymousSubmit`, `requireAuth`, etc.).
-
-```typescript
-// Authenticated submission
-await SL.interactions.submitPublicEvent(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.competitionEntry,
-  outcome: 'entered',
-  contactId: currentUser.contactId,
-  metadata: { answer: 'Paris' },
-});
-
-// Anonymous submission (interaction must have allowAnonymousSubmit: true)
-const response = await SL.interactions.submitPublicEvent(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.npsScore,
-  outcome: '9',
-  metadata: {
-    anonId: SL.utils.getAnonId(),  // device-level dedup signal
-  },
-});
-
-if (!response.success) {
-  if (response.reason === 'duplicate_anon') {
-    // this device has already submitted
-  }
-}
-```
-
-> **Anonymous submissions** — when `allowAnonymousSubmit: true` is set on the interaction, neither `userId` nor `contactId` is required. Use `utils.getAnonId()` to generate a stable browser-local UUID and pass it as `metadata.anonId`; the server will enforce `uniquePerAnonId` if configured.
-
-### Update an Existing Event
-
-```typescript
-await SL.interactions.updateEvent(collectionId, {
-  eventId: 'evt_abc123',    // Required — the event to update
-  interactionId: interactionIds.vote,
-  userId: 'user_abc123',
-  outcome: 'option-b',      // Override the outcome
-  status: 'deleted',        // Soft-delete the event
-});
-```
-
-### Event Body Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `interactionId` | string | ✅ | The type's minted `id` (from `ensureType`, stored in app config) — never a literal you made up |
-| `userId` or `contactId` | string | ✅ (one of) | The actor. `appendEvent` / `updateEvent` require one of these |
-| `appId` | string | ❌ | Scopes the event to your app |
-| `outcome` | string | ❌ | The result or choice — what `countsByOutcome()` aggregates |
-| `scope` | string | ❌ | Custom segmentation (e.g., `"round-1"`, `"region-uk"`) |
-| `productId` | string | ❌ | Scope to a product |
-| `proofId` | string | ❌ | Scope to a proof |
-| `broadcastId` | string | ❌ | Links the event to a broadcast campaign |
-| `journeyId` | string | ❌ | Links the event to a journey run |
-| `metadata` | object | ❌ | Arbitrary extra data stored with the event |
-| `timestamp` | string | ❌ | ISO datetime override (defaults to server time) |
-| `source` | string | ❌ | Free-text source tag (e.g., `"mobile"`, `"email-link"`) |
-
----
-
-## Reading Results
-
-### Counts by Outcome (Aggregations)
-
-The primary analytics function — returns how many times each outcome was recorded:
-
-```typescript
-// Admin (full access, deduplication options)
-const results = await SL.interactions.countsByOutcome(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.vote,
-  scope: 'round-1',       // Optional — filter by scope
-  from: '2026-06-01',     // Optional — date range
-  to: '2026-06-30',
-  dedupeLatest: true,     // Count only the latest event per user (for re-votes)
-});
-// Returns: [{ outcome: 'option-a', count: 42 }, { outcome: 'option-b', count: 37 }]
-
-// Public (respects allowPublicSummary permission)
-const results = await SL.interactions.publicCountsByOutcome(
-  collectionId,
-  { appId: 'my-app', interactionId: interactionIds.vote },
-  authToken     // Optional — pass if user is authenticated
-);
-```
-
-### Query Event History
-
-Flexible admin query for raw interaction events:
-
-```typescript
-const events = await SL.interactions.query(collectionId, {
-  appId: 'my-app',
-  interactionId: interactionIds.vote,
-  userId: 'user_abc123',      // Filter by user
-  outcome: 'option-a',        // Filter by outcome
-  from: '2026-06-01T00:00Z',
-  to: '2026-06-30T23:59Z',
-  limit: 100,
-  order: 'DESC',
-  latestPerEventId: true,     // Deduplicate: one row per interactionId per user
-  include: ['interaction'],   // Embed the interaction type definition in each row
-});
-```
-
-### Public: User's Own History
-
-Lets authenticated users see their own events:
-
-```typescript
-const myEvents = await SL.interactions.publicMyInteractions(
-  collectionId,
-  { appId: 'my-app', interactionId: interactionIds.vote },
-  authToken
-);
-```
-
----
-
-## Permissions Reference
-
-Set on the interaction type definition via `permissions`:
-
-| Permission | Type | Description |
-|------------|------|-------------|
-| `enabled` | boolean | Master on/off switch for submissions (default: enabled) |
-| `allowPublicSubmit` | boolean | Allow unauthenticated / public submissions |
-| `allowAnonymousSubmit` | boolean | Allow submissions without any session |
-| `requireAuth` | boolean | Block submissions unless user is authenticated |
-| `allowedOrigins` | string[] | Restrict to specific site domains (substring match) |
-| `startAt` | string (ISO) | Earliest time submissions are accepted |
-| `endAt` | string (ISO) | Latest time submissions are accepted |
-| `uniquePerUser` | boolean | Prevent duplicate submissions per user |
-| `uniquePerUserWindowSeconds` | number | Time window for uniqueness (e.g., `86400` = 1 day) |
-| `uniqueOutcome` | string | Outcome tag to check for duplicates (e.g., `"submitted"`) |
-| `uniquePerAnonId` | boolean | Reject a second submission that carries the same `anonId` in metadata |
-| `uniquePerAnonIdWindowSeconds` | number | Time window for `uniquePerAnonId` enforcement; `0` or omitted = all-time |
-| `allowPublicSummary` | boolean | Show counts/aggregates to unauthenticated users |
-| `allowAuthenticatedSummary` | boolean | Show counts/aggregates to authenticated users |
-| `allowOwnRead` | boolean | Let users read their own event history via public API |
-
----
-
-## Integration with Journeys
-
-Interactions are the primary bridge between user actions and automated workflows:
-
-```text
-User submits interaction event
-        ↓
-Platform emits event to Journey trigger
-        ↓
-Journey step runs: send confirmation email, update CRM, award points, etc.
-```
-
-When defining a journey trigger, reference the interaction type (its minted `id`) that should fire it. The interaction `outcome` and `metadata` are available as variables in journey steps.
-
----
-
-## 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.ensureType(collectionId, {
-  appId: 'my-app',
-  key: 'donation',
-  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 type id (the minted UUID) |
-| `{{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
-import type {
-  AppendInteractionBody,          // Event body for appendEvent and submitPublicEvent
-  UpdateInteractionBody,          // Event body for updateEvent
-  SubmitInteractionResponse,      // { success: true; eventId: string }
-  SubmitInteractionError,         // { error: 'FORBIDDEN'; reason: string }
-  InteractionEventRow,            // Raw event record returned by query()
-  OutcomeCount,                   // { outcome: string | null; count: number }
-  InteractionPermissions,         // Full permissions config shape
-  InteractionTypeRecord,          // Definition record from create() / get()
-  InteractionTypeList,            // { items, limit, offset }
-  CreateInteractionTypeBody,      // Body for create() — the server mints the id
-  EnsureInteractionTypeInput,     // Input for ensureType() — { appId, key, permissions?, display?, data? }
-  UpdateInteractionTypeBody,      // Body for update()
-  AdminInteractionsQueryRequest,  // query() filter options
-  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';
-```
-
----
-
-## Best Practices
-
-- Never hardcode an `interactionId`: create types with `ensureType` in admin, keep their ids in app config (`interactionIds.<key>`), read them everywhere else
-- Use descriptive type keys: `warranty-registration`, `competition-entry`, `newsletter-vote`
-- Use `outcome` to capture the choice — it's the key field that `countsByOutcome()` aggregates on
-- Include `metadata` for richer analytics and debugging (`source`, `device`, `region`, etc.)
-- Use `uniquePerUser: true` for actions that should only happen once (votes, registrations)
-- Set `startAt`/`endAt` on the type definition — don't enforce time limits in app code
-- Use `scope` to segment a single interaction type across multiple rounds, regions, or variants
-- Prefer `submitPublicEvent` in client-side widget code; use `appendEvent` in server-side / admin flows
-- Keep `getSEO()` and `getLLMContent()` calls separate from interaction submission paths
+# Interactions: Event Tracking & Analytics
+
+The `interactions` namespace is a **critical pattern** for tracking user engagement. Many apps rely heavily on it for logging events that can trigger journeys, feed analytics dashboards, and drive aggregated results such as vote counts.
+
+If you want generic page analytics, outbound click tracking, QR landing telemetry, or tag scan dashboards, use [analytics.md](analytics.md) instead. `interactions` is for structured business events and outcomes, not general web analytics.
+
+---
+
+## Overview
+
+Interactions have two distinct layers:
+
+| Layer | Purpose |
+|-------|---------|
+| **Interaction Types** | Definitions stored in the database, once per collection: permissions, display metadata, effects. **The server mints each type's `id` (a UUID).** |
+| **Interaction Events** | Individual event records logged each time a user performs that interaction. Each event's `interactionId` is a type's minted `id`. |
+
+## The one rule: create in admin → store the id in config → read it everywhere
+
+**You never choose an interaction id, and you never write one as a string literal.** You choose a readable *key* (e.g. `'vote'`); the server mints the *id* (e.g. `'52bab6fa-…'`). Events must carry the id.
+
+```typescript
+// 1. ADMIN / setup screen — find-or-create the type by your key, then store its minted id in app config.
+const vote = await SL.interactions.ensureType(collectionId, {
+  appId: 'my-app',
+  key: 'vote',                                            // your readable name — NOT the id
+  permissions: { allowPublicSubmit: true, uniquePerUser: true },
+  display: { title: 'Vote' },
+});
+const config = await SL.appConfiguration.getConfig({ collectionId, appId: 'my-app', admin: true });
+await SL.appConfiguration.setConfig({
+  collectionId, appId: 'my-app', admin: true,
+  config: { ...config, interactionIds: { ...config?.interactionIds, vote: vote.id } },
+});
+
+// 2. ANYWHERE ELSE (public widget, container, server function) — read the id from config.
+const { interactionIds } = await SL.appConfiguration.getConfig({ collectionId, appId: 'my-app' });
+await SL.interactions.submitPublicEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.vote,                     // the minted id, from config
+  outcome: 'option-a',
+});
+```
+
+Why it's split this way:
+
+- **Types can only be created on the admin surface.** Public code (widgets, the portal) can submit events but can't create types — so the public side can only learn the id from somewhere admin put it. App config is that place.
+- **`ensureType` is safe to re-run.** It returns the existing type when one with that `key` exists for your app, so run it every time your setup screen saves.
+- **Unknown ids are configuration errors.** If `interactionIds.vote` is missing, the app hasn't been set up in this collection: show "not configured", don't submit, and never fall back to a literal like `'vote'`. (`interactions.create()` exists too, but it ignores any `id` you pass — read `id` from the record it returns.)
+
+The examples below use `interactionIds` — the map you read from config in step 2.
+
+---
+
+## Common Use Cases
+
+| Use Case | type `key` (for `ensureType`) | `outcome` example |
+|----------|-------------------------------|-------------------|
+| Competition entry | `competition-entry` | `"entered"` |
+| Voting / polling | `vote` | `"option-a"` |
+| Mailing list signup | `newsletter-signup` | `"subscribed"` |
+| Warranty registration | `warranty-registration` | `"activated"` |
+| Product scan / view | `product-view` | `"scanned"` |
+| Form submission | `registration-form` | `"submitted"` |
+
+---
+
+## Interaction Types (Definitions)
+
+Interaction types are defined once per collection and control permissions, display metadata, and uniqueness constraints.
+
+### Create a Type (find-or-create)
+
+Admin only. Returns the type record; its `id` is the minted UUID — store it in app config (see [the one rule](#the-one-rule-create-in-admin--store-the-id-in-config--read-it-everywhere)).
+
+```typescript
+const vote = await SL.interactions.ensureType(collectionId, {
+  appId: 'my-app',
+  key: 'vote',                       // stored as data.interactionType; how ensureType finds it again
+  permissions: {
+    allowPublicSubmit: true,
+    uniquePerUser: true,
+    startAt: '2026-06-01T00:00:00Z',
+    endAt: '2026-06-30T23:59:59Z',
+    allowPublicSummary: true,
+  },
+  display: {
+    title: 'Vote',
+    description: 'Cast your vote for the competition.',
+  },
+});
+// vote.id → '52bab6fa-d868-4616-9342-6731b0f332b2'
+```
+
+### Update / Delete a Type
+
+```typescript
+// Update permissions or display
+await SL.interactions.update(collectionId, interactionIds.vote, {
+  permissions: { endAt: '2026-07-15T23:59:59Z' },
+});
+
+// Delete the definition (does not delete existing events) — and remove it from your config
+await SL.interactions.remove(collectionId, interactionIds.vote);
+```
+
+### List / Get Types
+
+```typescript
+// Admin: list all types for an app (each has data.interactionType = its key)
+const { items } = await SL.interactions.list(collectionId, { appId: 'my-app' });
+
+// Admin: get a single type
+const type = await SL.interactions.get(collectionId, interactionIds.vote);
+
+// Public: list available types (respects permissions)
+const { items } = await SL.interactions.publicList(collectionId, { appId: 'my-app' });
+```
+
+---
+
+## Logging Events
+
+Every `interactionId` below is a minted type id read from your app config (`interactionIds`, see [the one rule](#the-one-rule-create-in-admin--store-the-id-in-config--read-it-everywhere)). Events never create types: an id that isn't a type defined for this collection and app is a configuration error.
+
+### Admin Event Append
+
+Use on the server side or in admin flows. Requires `userId` **or** `contactId`.
+
+```typescript
+await SL.interactions.appendEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.vote,
+  outcome: 'option-a',      // The result / choice — used by countsByOutcome()
+  userId: 'user_abc123',    // One of userId or contactId is required
+  productId: 'prod_xyz',    // Optional — scope to a specific product
+  scope: 'round-1',         // Optional — custom segmentation string
+  metadata: { source: 'mobile', region: 'UK' },
+});
+```
+
+### Public Event Submit
+
+Use in client-side app code. Hits the public endpoint and respects interaction permissions (`allowPublicSubmit`, `allowAnonymousSubmit`, `requireAuth`, etc.).
+
+```typescript
+// Authenticated submission
+await SL.interactions.submitPublicEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.competitionEntry,
+  outcome: 'entered',
+  contactId: currentUser.contactId,
+  metadata: { answer: 'Paris' },
+});
+
+// Anonymous submission (interaction must have allowAnonymousSubmit: true)
+const response = await SL.interactions.submitPublicEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.npsScore,
+  outcome: '9',
+  metadata: {
+    anonId: SL.utils.getAnonId(),  // device-level dedup signal
+  },
+});
+
+if (!response.success) {
+  if (response.reason === 'duplicate_anon') {
+    // this device has already submitted
+  }
+}
+```
+
+> **Anonymous submissions** — when `allowAnonymousSubmit: true` is set on the interaction, neither `userId` nor `contactId` is required. Use `utils.getAnonId()` to generate a stable browser-local UUID and pass it as `metadata.anonId`; the server will enforce `uniquePerAnonId` if configured.
+
+### Update an Existing Event
+
+```typescript
+await SL.interactions.updateEvent(collectionId, {
+  eventId: 'evt_abc123',    // Required — the event to update
+  interactionId: interactionIds.vote,
+  userId: 'user_abc123',
+  outcome: 'option-b',      // Override the outcome
+  status: 'deleted',        // Soft-delete the event
+});
+```
+
+### Event Body Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `interactionId` | string | ✅ | The type's minted `id` (from `ensureType`, stored in app config) — never a literal you made up |
+| `userId` or `contactId` | string | ✅ (one of) | The actor. `appendEvent` / `updateEvent` require one of these |
+| `appId` | string | ❌ | Scopes the event to your app |
+| `outcome` | string | ❌ | The result or choice — what `countsByOutcome()` aggregates |
+| `scope` | string | ❌ | Custom segmentation (e.g., `"round-1"`, `"region-uk"`) |
+| `productId` | string | ❌ | Scope to a product |
+| `proofId` | string | ❌ | Scope to a proof |
+| `broadcastId` | string | ❌ | Links the event to a broadcast campaign |
+| `journeyId` | string | ❌ | Links the event to a journey run |
+| `metadata` | object | ❌ | Arbitrary extra data stored with the event |
+| `timestamp` | string | ❌ | ISO datetime override (defaults to server time) |
+| `source` | string | ❌ | Free-text source tag (e.g., `"mobile"`, `"email-link"`) |
+
+---
+
+## Reading Results
+
+### Counts by Outcome (Aggregations)
+
+The primary analytics function — returns how many times each outcome was recorded:
+
+```typescript
+// Admin (full access, deduplication options)
+const results = await SL.interactions.countsByOutcome(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.vote,
+  scope: 'round-1',       // Optional — filter by scope
+  from: '2026-06-01',     // Optional — date range
+  to: '2026-06-30',
+  dedupeLatest: true,     // Count only the latest event per user (for re-votes)
+});
+// Returns: [{ outcome: 'option-a', count: 42 }, { outcome: 'option-b', count: 37 }]
+
+// Public (respects allowPublicSummary permission)
+const results = await SL.interactions.publicCountsByOutcome(
+  collectionId,
+  { appId: 'my-app', interactionId: interactionIds.vote },
+  authToken     // Optional — pass if user is authenticated
+);
+```
+
+### Query Event History
+
+Flexible admin query for raw interaction events:
+
+```typescript
+const events = await SL.interactions.query(collectionId, {
+  appId: 'my-app',
+  interactionId: interactionIds.vote,
+  userId: 'user_abc123',      // Filter by user
+  outcome: 'option-a',        // Filter by outcome
+  from: '2026-06-01T00:00Z',
+  to: '2026-06-30T23:59Z',
+  limit: 100,
+  order: 'DESC',
+  latestPerEventId: true,     // Deduplicate: one row per interactionId per user
+  include: ['interaction'],   // Embed the interaction type definition in each row
+});
+```
+
+### Public: User's Own History
+
+Lets authenticated users see their own events:
+
+```typescript
+const myEvents = await SL.interactions.publicMyInteractions(
+  collectionId,
+  { appId: 'my-app', interactionId: interactionIds.vote },
+  authToken
+);
+```
+
+---
+
+## Permissions Reference
+
+Set on the interaction type definition via `permissions`:
+
+| Permission | Type | Description |
+|------------|------|-------------|
+| `enabled` | boolean | Master on/off switch for submissions (default: enabled) |
+| `allowPublicSubmit` | boolean | Allow unauthenticated / public submissions |
+| `allowAnonymousSubmit` | boolean | Allow submissions without any session |
+| `requireAuth` | boolean | Block submissions unless user is authenticated |
+| `allowedOrigins` | string[] | Restrict to specific site domains (substring match) |
+| `startAt` | string (ISO) | Earliest time submissions are accepted |
+| `endAt` | string (ISO) | Latest time submissions are accepted |
+| `uniquePerUser` | boolean | Prevent duplicate submissions per user |
+| `uniquePerUserWindowSeconds` | number | Time window for uniqueness (e.g., `86400` = 1 day) |
+| `uniqueOutcome` | string | Outcome tag to check for duplicates (e.g., `"submitted"`) |
+| `uniquePerAnonId` | boolean | Reject a second submission that carries the same `anonId` in metadata |
+| `uniquePerAnonIdWindowSeconds` | number | Time window for `uniquePerAnonId` enforcement; `0` or omitted = all-time |
+| `allowPublicSummary` | boolean | Show counts/aggregates to unauthenticated users |
+| `allowAuthenticatedSummary` | boolean | Show counts/aggregates to authenticated users |
+| `allowOwnRead` | boolean | Let users read their own event history via public API |
+| `requires` | `{ entitlement, fallback? }` | Gate submissions on a membership check: `entitlement` is a predicate such as `'tier>=gold'`, `'member'`, `{ points: { gte: 500 } }`; `fallback` is `deny` (default), `allow` or `degrade` when no source can answer. Answered on demand from the collection's configured sources (a signed claim the caller presents as `entitlementToken` / `X-SmartLinks-Entitlement`, the loyalty connector's cached `lookup`, the contact's own loyalty fields) — see [entitlements.md](entitlements.md). A refused submit answers `403 { reason: 'entitlement_denied' }`. |
+
+---
+
+## Integration with Journeys
+
+Interactions are the primary bridge between user actions and automated workflows:
+
+```text
+User submits interaction event
+        ↓
+Platform emits event to Journey trigger
+        ↓
+Journey step runs: send confirmation email, update CRM, award points, etc.
+```
+
+When defining a journey trigger, reference the interaction type (its minted `id`) that should fire it. The interaction `outcome` and `metadata` are available as variables in journey steps.
+
+---
+
+## 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.ensureType(collectionId, {
+  appId: 'my-app',
+  key: 'donation',
+  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 type id (the minted UUID) |
+| `{{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`, `timestamp` — and `envelope`, the same [event envelope](integrations.md#event-sourced-flows-and-the-envelope) outbound flows send (identity under `config.identity.policy`, default `hashed`).
+
+Two more config fields: `signing: { credentialRef, previousCredentialRef? }` adds `X-SmartLinks-Signature` over the body (see [Signed deliveries](integrations.md#signed-deliveries)), and `identity: { policy }` sets what the envelope carries about the person. The destination must be a public host.
+
+The effect runs **once**, with no retry and no delivery log. For retries, a run log, rate limits and event mapping, use an outbound **flow** with `sourceEntity: 'interaction'` subscribed to `interaction.submitted:<typeId>` instead — same payload shape, production guarantees.
+
+#### `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
+import type {
+  AppendInteractionBody,          // Event body for appendEvent and submitPublicEvent
+  UpdateInteractionBody,          // Event body for updateEvent
+  SubmitInteractionResponse,      // { success: true; eventId: string }
+  SubmitInteractionError,         // { error: 'FORBIDDEN'; reason: string }
+  InteractionEventRow,            // Raw event record returned by query()
+  OutcomeCount,                   // { outcome: string | null; count: number }
+  InteractionPermissions,         // Full permissions config shape
+  InteractionTypeRecord,          // Definition record from create() / get()
+  InteractionTypeList,            // { items, limit, offset }
+  CreateInteractionTypeBody,      // Body for create() — the server mints the id
+  EnsureInteractionTypeInput,     // Input for ensureType() — { appId, key, permissions?, display?, data? }
+  UpdateInteractionTypeBody,      // Body for update()
+  AdminInteractionsQueryRequest,  // query() filter options
+  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';
+```
+
+---
+
+## Best Practices
+
+- Never hardcode an `interactionId`: create types with `ensureType` in admin, keep their ids in app config (`interactionIds.<key>`), read them everywhere else
+- Use descriptive type keys: `warranty-registration`, `competition-entry`, `newsletter-vote`
+- Use `outcome` to capture the choice — it's the key field that `countsByOutcome()` aggregates on
+- Include `metadata` for richer analytics and debugging (`source`, `device`, `region`, etc.)
+- Use `uniquePerUser: true` for actions that should only happen once (votes, registrations)
+- Set `startAt`/`endAt` on the type definition — don't enforce time limits in app code
+- Use `scope` to segment a single interaction type across multiple rounds, regions, or variants
+- Prefer `submitPublicEvent` in client-side widget code; use `appendEvent` in server-side / admin flows
+- Keep `getSEO()` and `getLLMContent()` calls separate from interaction submission paths