@proveanything/smartlinks 2.1.13 → 2.1.15

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,9 @@ 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` |
+| Invoke a connector's action — redeem, enrol, issue a coupon, raise a ticket — with the connector's credentials | `ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId })` → the action's result; `ctx.sl.connectors.actions(appId)` lists them; see [connectors.md](connectors.md#actions-provider-operations-on-demand) | `sl:connectors:write` |
+| Ask "is this person gold or above?" without holding their member record | `ctx.sl.entitlements.check('tier>=gold')` → `{ allowed, basis, asOf, attributes }` for the signed-in caller (or `{ identity, token, fallback }`); see [entitlements.md](entitlements.md) | `sl:entitlements:read` |
 | Take a booking with your own checks (hours, queue token, payment) | `ctx.sl.bookings.create({ slotId \| resource + time, contactId, status, idempotencyKey })` — never oversold, never double-booked; also `confirm` / `cancel` / `move` / `mine` / `freebusy` / `message` (everyone booked, hydrated) / `slots.*` / `blocks.*` (see [bookings.md](bookings.md)) | `sl:bookings:write` (`sl:bookings:read` to read) |
 
 Notes:

package/dist/openapi.yaml

@@ -21235,6 +21235,32 @@ components:
         - id
         - title
         - component
+    ConnectorAction:
+      type: object
+      properties:
+        name:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        function:
+          type: string
+        visibility:
+          type: string
+          enum:
+            - admin
+            - member
+            - public
+        input:
+          type: object
+          additionalProperties: true
+        output:
+          type: object
+          additionalProperties: true
+      required:
+        - name
+        - function
     AppConnectorDeclaration:
       type: object
       properties:
@@ -21280,10 +21306,18 @@ components:
           type: string
         fetch:
           type: string
+        describeEvents:
+          type: string
+        lookup:
+          type: string
         panels:
           type: array
           items:
             $ref: "#/components/schemas/ConnectorPanel"
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorAction"
         aiGuide:
           type: string
         recordId:
@@ -29014,9 +29048,52 @@ 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"
+        envelopeFormat:
+          type: string
+          enum:
+            - cloudevents
         connection:
           $ref: "#/components/schemas/FlowConnection"
         fieldMappings:
@@ -29049,9 +29126,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 +29503,144 @@ 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:
+        specVersion:
+          type: number
+        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
+        anonymousId:
+          type: string
+        sessionId:
+          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
+        consent:
+          type: object
+          additionalProperties: true
+        subject:
+          type: object
+          additionalProperties: true
+        event:
+          type: object
+          additionalProperties: true
+        attributes:
+          type: object
+          additionalProperties: true
+      required:
+        - specVersion
+        - id
+        - type
+        - entityType
+        - entityId
+        - occurredAt
+        - collectionId
+        - orgId
+        - appId
+        - identity
+        - contactId
+        - userId
+        - externalIds
+        - anonymousId
+        - sessionId
+        - identityPolicy
+        - product
+        - proof
+        - consent
+        - subject
+        - attributes
     CapturedRequest:
       type: object
       properties:
@@ -29763,6 +29980,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 +30008,8 @@ components:
         - sample
         - shape
         - serialize
+        - describeEvents
+        - lookup
     RunTrigger:
       type: string
       enum:

package/dist/types/appManifest.d.ts

@@ -1030,6 +1030,27 @@ export interface ConnectorPanel {
     /** Exported component name in the app's widgets bundle (manifest `widgets.files`). */
     component: string;
 }
+/**
+ * A named provider operation invoked ON DEMAND (not by the engine): redeem a reward, enrol a member,
+ * issue a coupon, raise a ticket, send a receipt. Called by an app function (`ctx.sl.connectors.call`),
+ * by the Hub (public route — only `public`, or `member` for a signed-in person) or by the console. The
+ * function receives `{ input, installation, caller }` and returns JSON; it runs with the connector's
+ * own credentials and is told who asked.
+ */
+export interface ConnectorAction {
+    /** `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$` */
+    name: string;
+    title?: string;
+    description?: string;
+    /** This app's server function implementing it. */
+    function: string;
+    /** Who may invoke it outside functions and the console. Default 'admin'. */
+    visibility?: 'admin' | 'member' | 'public';
+    /** JSON Schema for `input`; `required` fields are checked before the function runs. */
+    input?: Record<string, unknown>;
+    /** JSON Schema for the result (documentation; not enforced). */
+    output?: Record<string, unknown>;
+}
 /**
  * The connector contract. Every function named here is one of this app's server functions
  * (manifest `functions.definitions`); the engine calls it with collection authority, capped by the
@@ -1078,8 +1099,22 @@ 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[];
+    /** On-demand operations the connector offers (see ConnectorAction). */
+    actions?: ConnectorAction[];
     /** Path (under the app's public files) of a guide the AI mapping assistant reads. */
     aiGuide?: string;
     /**
@@ -1088,9 +1123,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,66 @@ 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;
+    /**
+     * Wrap each delivered body as a CloudEvents 1.0 structured event
+     * ({ specversion, id, type, source, subject, time, datacontenttype, dataschema, data }) — the shape
+     * event buses, lakes and serverless tools consume without custom code.
+     */
+    envelopeFormat?: 'cloudevents';
     connection?: FlowConnection;
     fieldMappings?: FieldMapping[];
     /** Run this flow through a connector app's functions instead of the built-in mapper/transport. */
@@ -57,8 +116,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 +328,111 @@ 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 {
+    /** Schema version of this envelope. Bumped only when a consumer could break (a field removed or changed). */
+    specVersion: number;
+    /** The event's id: stable across retries; use it as the provider's transaction / idempotency id. */
+    id: string;
+    /** Spine event name, e.g. 'interaction.submitted:<typeId>', 'contact.updated', 'tag.scanned:scan_redirect'. */
+    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>;
+        /** The visitor / device id before anyone signed in (an analytics destination stitches on it later). Under every policy. */
+        anonymousId: string | null;
+        sessionId: string | null;
+        emailHash?: string | null;
+        phoneHash?: string | null;
+        hashAlgorithm?: 'hmac-sha256' | null;
+        /** 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 person's communication consent, summarised per channel from the contact's comms state; null
+     * when the event is about nobody we hold. A CRM or CDP must not act against it.
+     */
+    consent: {
+        channels: Record<'email' | 'sms' | 'push' | 'whatsapp', 'opted_in' | 'opted_out' | 'suppressed' | 'unknown'>;
+        topics: Record<string, boolean>;
+        updatedAt: string | null;
+    } | null;
+    /** The event's own fields: an interaction's interactionId / outcome / metadata, a scan's codeId / country, a contact's profile. */
+    subject: Record<string, unknown>;
+    /** From the flow's event mapping, when it has one. */
+    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';