@proveanything/smartlinks 2.1.13 → 2.1.14

package/dist/docs/loyalty.md

@@ -302,6 +302,23 @@ A loyalty failure never causes the interaction event to fail — errors are caug
 
 ---
 
+## External loyalty platforms
+
+The schemes above are SmartLinks' own points. When a brand runs its programme on an external loyalty or
+engagement platform, the platform stays the record of truth and SmartLinks connects to it through a
+**connector app** and the integration engine — no member base is mirrored here:
+
+| Flow | How |
+|---|---|
+| **Earn** — what happens on a pack or in a Hub awards points there | an outbound flow with `sourceEntity: 'interaction' \| 'event'`, an `eventMapping` onto the provider's registered events, signed delivery, retries — [integrations.md](integrations.md#event-sourced-flows-and-the-envelope) |
+| **Profile** — member id, tier and points on the contact | the connector's webhook function calls `ctx.sl.members.apply(...)`; the contact gets `customFields.loyalty` and flat `loyaltyTier / loyaltyPoints / loyaltyMemberId`, usable in segments and comms targeting — [connectors.md](connectors.md#loyalty-and-crm-connectors) |
+| **Gate / display** — "Gold members only", live balance | the entitlement check, answered on demand from a signed claim, the connector's cached `lookup`, or the contact's fields — [entitlements.md](entitlements.md) |
+
+A collection runs one loyalty source: the native schemes here, or an external provider through a
+connector.
+
+---
+
 ## TypeScript Types
 
 ```typescript

package/dist/docs/server-functions.md

@@ -517,6 +517,8 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Check a tapped tag is real | `ctx.sl.tags.resolve(proofId)` → `{ id, claimSetId, code }` or `null` | `sl:tags:read` |
 | 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` |
+| 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) |
 
 Notes:

package/dist/openapi.yaml

@@ -21280,6 +21280,10 @@ components:
           type: string
         fetch:
           type: string
+        describeEvents:
+          type: string
+        lookup:
+          type: string
         panels:
           type: array
           items:
@@ -29014,9 +29018,48 @@ components:
           additionalProperties: true
       required:
         - appId
+    EventMappingRule:
+      type: object
+      properties:
+        id:
+          type: string
+        match:
+          type: object
+          additionalProperties: true
+        event:
+          type: string
+        attributes:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+      required:
+        - event
+    EventMapping:
+      type: object
+      properties:
+        rules:
+          type: array
+          items:
+            $ref: "#/components/schemas/EventMappingRule"
+        unmatched:
+          type: string
+          enum:
+            - skip
+            - passthrough
+      required:
+        - rules
     IntegrationFlowConfig:
       type: object
       properties:
+        signing:
+          type: object
+          additionalProperties: true
+        identity:
+          type: object
+          additionalProperties: true
+        eventMapping:
+          $ref: "#/components/schemas/EventMapping"
         connection:
           $ref: "#/components/schemas/FlowConnection"
         fieldMappings:
@@ -29049,9 +29092,11 @@ components:
         schedule:
           type: string
         sourceEntity:
-          type: string
+          type: object
+          additionalProperties: true
         targetEntity:
-          type: string
+          type: object
+          additionalProperties: true
         config:
           $ref: "#/components/schemas/IntegrationFlowConfig"
         createdBy:
@@ -29424,6 +29469,131 @@ components:
         settings:
           type: object
           additionalProperties: true
+    ConnectorEventsSchema:
+      type: object
+      properties:
+        events:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        limits:
+          type: object
+          additionalProperties: true
+      required:
+        - events
+    ConnectorLookupInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        identity:
+          type: object
+          additionalProperties: true
+        want:
+          type: array
+          items:
+            type: string
+      required:
+        - installation
+        - identity
+    ConnectorLookupResult:
+      type: object
+      properties:
+        found:
+          type: boolean
+        memberId:
+          type: string
+        tier:
+          type: string
+        points:
+          type: number
+        status:
+          type: string
+        attributes:
+          type: object
+          additionalProperties: true
+        asOf:
+          type: string
+      required:
+        - found
+    EventEnvelope:
+      type: object
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+        entityType:
+          type: string
+        entityId:
+          type: string
+        occurredAt:
+          type: string
+        collectionId:
+          type: string
+        orgId:
+          type: string
+        appId:
+          type: string
+        identity:
+          type: object
+          additionalProperties: true
+        contactId:
+          type: string
+        userId:
+          type: string
+        externalIds:
+          type: object
+          additionalProperties:
+            type: string
+        emailHash:
+          type: string
+        phoneHash:
+          type: string
+        hashAlgorithm:
+          type: string
+          enum:
+            - hmac-sha256
+        email:
+          type: string
+        phone:
+          type: string
+        identityPolicy:
+          $ref: "#/components/schemas/IdentityPolicy"
+        product:
+          type: object
+          additionalProperties: true
+        proof:
+          type: object
+          additionalProperties: true
+        subject:
+          type: object
+          additionalProperties: true
+        event:
+          type: object
+          additionalProperties: true
+        attributes:
+          type: object
+          additionalProperties: true
+      required:
+        - id
+        - type
+        - entityType
+        - entityId
+        - occurredAt
+        - collectionId
+        - orgId
+        - appId
+        - identity
+        - contactId
+        - userId
+        - externalIds
+        - identityPolicy
+        - product
+        - proof
+        - subject
+        - attributes
     CapturedRequest:
       type: object
       properties:
@@ -29763,6 +29933,24 @@ components:
         - webhook
         - oauth2
         - none
+    IdentityPolicy:
+      type: string
+      enum:
+        - externalIds
+        - hashed
+        - raw
+    FlowSourceEntity:
+      type: string
+      enum:
+        - product
+        - interaction
+        - contact
+        - event
+    FlowTargetEntity:
+      type: string
+      enum:
+        - product
+        - contact
     UpdateFlowInput:
       $ref: "#/components/schemas/CreateFlowInput"
     ConnectorConsoleStep:
@@ -29773,6 +29961,8 @@ components:
         - sample
         - shape
         - serialize
+        - describeEvents
+        - lookup
     RunTrigger:
       type: string
       enum:

package/dist/types/appManifest.d.ts

@@ -1078,6 +1078,18 @@ export interface AppConnectorDeclaration {
         send?: string;
         /** (ConnectorFetchInput) → ConnectorRecords: inbound pull, one page per call. */
         fetch?: string;
+        /**
+         * Loyalty / engagement providers: → ConnectorEventsSchema, the event names (and attributes) the
+         * provider has registered for this installation. A flow's eventMapping is validated against it when
+         * saved, so a mapping that names an unregistered event or breaks a limit is refused with the reason.
+         */
+        describeEvents?: string;
+        /**
+         * (ConnectorLookupInput) → ConnectorLookupResult: one identity → member id, tier, points, status.
+         * Called by the entitlement check (see docs/entitlements.md) through a cache keyed on an identity
+         * hash, for the TTL the collection sets — one call per active person per TTL, never a sync.
+         */
+        lookup?: string;
     };
     panels?: ConnectorPanel[];
     /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
@@ -1088,9 +1100,15 @@ export interface AppConnectorDeclaration {
      * Default 'id'; a flow can override it with `config.upsert.externalIdPath`.
      */
     recordId?: string;
-    /** Requests per second toward the provider, shared by every SmartLinks worker. */
+    /**
+     * Requests per second toward the provider, shared by every SmartLinks worker; and, for providers that
+     * cap registered events, how many distinct events / attributes per event they accept (a flow's
+     * eventMapping is checked against them when saved).
+     */
     limits?: {
         requestsPerSecond?: number;
+        maxEvents?: number;
+        maxAttributes?: number;
     };
 }
 /**

package/dist/types/integrations.d.ts

@@ -38,7 +38,60 @@ export interface FlowConnectorRef {
     /** Per-flow settings, layered over the installation's. */
     settings?: Record<string, unknown>;
 }
+import type { ConnectorInstallation } from './appManifest.js';
+/** What about a person an event-sourced flow lets leave. Default 'hashed'. */
+export type IdentityPolicy = 'externalIds' | 'hashed' | 'raw';
+/**
+ * Many SmartLinks events → the provider's few registered event names. Rules are tried in order; the
+ * first match names the provider event and renders its attributes (a literal, a Liquid template over
+ * the envelope, or `{ path, default }`). An unmatched event is skipped (recorded as such) unless
+ * `unmatched: 'passthrough'`. Validated against the connector's `describeEvents` when the flow is saved.
+ */
+export interface EventMappingRule {
+    id?: string;
+    match?: {
+        types?: string[];
+        interactionIds?: string[];
+        outcomes?: string[];
+        appIds?: string[];
+    };
+    /** The provider's registered event name. */
+    event: string;
+    attributes?: Record<string, string | number | boolean | {
+        path: string;
+        default?: unknown;
+    } | {
+        value: unknown;
+    }>;
+}
+export interface EventMapping {
+    rules: EventMappingRule[];
+    unmatched?: 'skip' | 'passthrough';
+}
+/** What an outbound flow reads: the product that changed, or ONE spine event as the envelope. */
+export type FlowSourceEntity = 'product' | 'interaction' | 'contact' | 'event';
+/** What an inbound flow writes. */
+export type FlowTargetEntity = 'product' | 'contact';
 export interface IntegrationFlowConfig {
+    /**
+     * Signed deliveries: X-SmartLinks-Signature `t=<unix>,v1=<hex HMAC-SHA256(secret, t + '.' + body)>`
+     * over the exact bytes sent. `previousCredentialRef` keeps the old secret signing during a rotation.
+     */
+    signing?: {
+        credentialRef: string;
+        previousCredentialRef?: string;
+    };
+    /**
+     * Event-sourced flows: what about the person leaves (default 'hashed': ids + HMAC hashes of email and
+     * phone, never the values). `hashKeyCredentialRef` names the brand's own hash key, so hashes match a
+     * mirror they built; otherwise a per-collection platform key is used.
+     */
+    identity?: {
+        policy?: IdentityPolicy;
+        hashKeyCredentialRef?: string;
+    };
+    /** Event-sourced flows: fold SmartLinks events into the provider's registered events. */
+    eventMapping?: EventMapping;
     connection?: FlowConnection;
     fieldMappings?: FieldMapping[];
     /** Run this flow through a connector app's functions instead of the built-in mapper/transport. */
@@ -57,8 +110,10 @@ export interface IntegrationFlow {
     eventTypes: string[];
     /** Cron/interval string for scheduled flows, or null. */
     schedule: string | null;
-    sourceEntity: string | null;
-    targetEntity: string | null;
+    /** Outbound: what the flow reads (product | interaction | contact | event). */
+    sourceEntity: FlowSourceEntity | string | null;
+    /** Inbound: what the flow writes (product | contact). */
+    targetEntity: FlowTargetEntity | string | null;
     config: IntegrationFlowConfig;
     createdBy: string | null;
     createdAt: string;
@@ -267,7 +322,97 @@ export interface SaveConnectorInstallationInput {
     settings?: Record<string, unknown>;
 }
 /** Steps the console may run directly (send and fetch only run inside a flow; shape/serialize as dry runs). */
-export type ConnectorConsoleStep = 'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize';
+export type ConnectorConsoleStep = 'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize' | 'describeEvents' | 'lookup';
+/** `describeEvents` → what the provider has registered for this installation (loyalty / engagement). */
+export interface ConnectorEventsSchema {
+    events: Array<{
+        name: string;
+        title?: string;
+        attributes?: Array<{
+            name: string;
+            type?: string;
+            required?: boolean;
+        }>;
+    }>;
+    limits?: {
+        maxEvents?: number;
+        maxAttributes?: number;
+    };
+}
+/** `lookup` input: one identity, as the collection's lookup policy sends it (raw, or hashed). */
+export interface ConnectorLookupInput {
+    installation: ConnectorInstallation;
+    identity: {
+        externalId?: string | null;
+        email?: string | null;
+        phone?: string | null;
+        emailHash?: string | null;
+        phoneHash?: string | null;
+        contactId?: string | null;
+    };
+    /** Attribute names the gate wants, e.g. ['tier', 'points', 'status']. */
+    want?: string[];
+}
+/** `lookup` result. Throw (or return non-2xx) for an outage — never `found: false`. */
+export interface ConnectorLookupResult {
+    found: boolean;
+    memberId?: string | null;
+    tier?: string | null;
+    points?: number | null;
+    status?: string | null;
+    attributes?: Record<string, unknown>;
+    /** When the provider's answer is from (ISO). */
+    asOf?: string | null;
+}
+/**
+ * The one shape a SmartLinks event has when it leaves the platform — what event-sourced flows hand a
+ * connector's `serialize` / `send`, after the flow's identity policy and event mapping.
+ */
+export interface EventEnvelope {
+    /** 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'. */
+    type: string;
+    entityType: string | null;
+    entityId: string | null;
+    occurredAt: string;
+    collectionId: string;
+    orgId: string;
+    appId: string | null;
+    identity: {
+        contactId: string | null;
+        userId: string | null;
+        /** Ids other systems know this person by, keyed by system (a connector's `provider`). */
+        externalIds: Record<string, string>;
+        emailHash?: string | null;
+        phoneHash?: string | null;
+        hashAlgorithm?: 'hmac-sha256' | null;
+        /** Only under identity policy 'raw'. */
+        email?: string | null;
+        phone?: string | null;
+    };
+    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;
+    /** 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. */
+    event?: {
+        name: string;
+        attributes: Record<string, unknown>;
+        rule: string | null;
+    };
+    attributes: Record<string, unknown>;
+}
 export type RunTrigger = 'manual' | 'event' | 'schedule' | 'test';
 export type FlowRunStatus = 'running' | 'success' | 'partial' | 'failed' | 'skipped';
 export type FlowRunItemStatus = 'sent' | 'failed' | 'skipped';

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.13  |  Generated: 2026-11-09T11:51:55.948Z
+Version: 2.1.14  |  Generated: 2026-11-09T13:01:05.900Z
 
 This is a concise summary of all available API functions and types.
 
@@ -64,8 +64,9 @@ For detailed guides on specific features:
 - **[Analytics](analytics.md)** - Web analytics, link-click tracking, QR/tag scan telemetry, and event reporting
 - **[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), field mappings, and the Syndigo/Event Hub outbound path
-- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send); core does the mapping
+- **[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
+- **[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
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
@@ -3129,11 +3130,13 @@ interface AppConnectorDeclaration {
   serialize?: string
   send?: string
   fetch?: string
+  describeEvents?: string
+  lookup?: string
   }
   panels?: ConnectorPanel[]
   aiGuide?: string
   recordId?: string
-  limits?: { requestsPerSecond?: number }
+  limits?: { requestsPerSecond?: number; maxEvents?: number; maxAttributes?: number }
 }
 ```
 
@@ -7953,9 +7956,30 @@ interface FlowConnectorRef {
 }
 ```
 
+**EventMappingRule** (interface)
+```typescript
+interface EventMappingRule {
+  id?: string
+  match?: { types?: string[]; interactionIds?: string[]; outcomes?: string[]; appIds?: string[] }
+  event: string
+  attributes?: Record<string, string | number | boolean | { path: string; default?: unknown } | { value: unknown }>
+}
+```
+
+**EventMapping** (interface)
+```typescript
+interface EventMapping {
+  rules: EventMappingRule[]
+  unmatched?: 'skip' | 'passthrough'
+}
+```
+
 **IntegrationFlowConfig** (interface)
 ```typescript
 interface IntegrationFlowConfig {
+  signing?: { credentialRef: string; previousCredentialRef?: string }
+  identity?: { policy?: IdentityPolicy; hashKeyCredentialRef?: string }
+  eventMapping?: EventMapping
   connection?: FlowConnection
   fieldMappings?: FieldMapping[]
   connector?: FlowConnectorRef
@@ -7975,8 +7999,8 @@ interface IntegrationFlow {
   status: FlowStatus
   eventTypes: string[]
   schedule: string | null
-  sourceEntity: string | null
-  targetEntity: string | null
+  sourceEntity: FlowSourceEntity | string | null
+  targetEntity: FlowTargetEntity | string | null
   config: IntegrationFlowConfig
   createdBy: string | null
   createdAt: string
@@ -8165,6 +8189,66 @@ interface SaveConnectorInstallationInput {
 }
 ```
 
+**ConnectorEventsSchema** (interface)
+```typescript
+interface ConnectorEventsSchema {
+  events: Array<{ name: string; title?: string; attributes?: Array<{ name: string; type?: string; required?: boolean }> }>
+  limits?: { maxEvents?: number; maxAttributes?: number }
+}
+```
+
+**ConnectorLookupInput** (interface)
+```typescript
+interface ConnectorLookupInput {
+  installation: ConnectorInstallation
+  identity: { externalId?: string | null; email?: string | null; phone?: string | null; emailHash?: string | null; phoneHash?: string | null; contactId?: string | null }
+  want?: string[]
+}
+```
+
+**ConnectorLookupResult** (interface)
+```typescript
+interface ConnectorLookupResult {
+  found: boolean
+  memberId?: string | null
+  tier?: string | null
+  points?: number | null
+  status?: string | null
+  attributes?: Record<string, unknown>
+  asOf?: string | null
+}
+```
+
+**EventEnvelope** (interface)
+```typescript
+interface EventEnvelope {
+  id: string
+  type: string
+  entityType: string | null
+  entityId: string | null
+  occurredAt: string
+  collectionId: string
+  orgId: string
+  appId: string | null
+  identity: {
+  contactId: string | null
+  userId: string | null
+  externalIds: Record<string, string>
+  emailHash?: string | null
+  phoneHash?: string | null
+  hashAlgorithm?: 'hmac-sha256' | null
+  email?: string | null
+  phone?: string | null
+  }
+  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
+  subject: Record<string, unknown>
+  event?: { name: string; attributes: Record<string, unknown>; rule: string | null }
+  attributes: Record<string, unknown>
+}
+```
+
 **CapturedRequest** (interface)
 ```typescript
 interface CapturedRequest {
@@ -8367,9 +8451,15 @@ interface RecordTypesResponse {
 
 **FlowAuthMethod** = `'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none'`
 
+**IdentityPolicy** = `'externalIds' | 'hashed' | 'raw'`
+
+**FlowSourceEntity** = `'product' | 'interaction' | 'contact' | 'event'`
+
+**FlowTargetEntity** = `'product' | 'contact'`
+
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
-**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize'`
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize' | 'describeEvents' | 'lookup'`
 
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`