@proveanything/smartlinks 2.1.12 → 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

@@ -9641,6 +9641,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /authkit/{clientId}/auth/microsoft:
+    post:
+      tags:
+        - authKit
+      summary: authKit.microsoftLogin
+      operationId: authKit_microsoftLogin
+      security: []
+      parameters:
+        - name: clientId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthLoginResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MicrosoftLoginOptions"
   /authkit/{clientId}/auth/phone/send-code:
     post:
       tags:
@@ -21248,6 +21280,10 @@ components:
           type: string
         fetch:
           type: string
+        describeEvents:
+          type: string
+        lookup:
+          type: string
         panels:
           type: array
           items:
@@ -23933,6 +23969,35 @@ components:
           additionalProperties: true
       required:
         - success
+    MicrosoftLoginOptions:
+      type: object
+      properties:
+        returnOrigin:
+          type: string
+        trustedDeviceToken:
+          type: string
+    AuthKitAccess:
+      type: object
+      properties:
+        mode:
+          type: string
+          enum:
+            - anyone
+            - organisation
+        domains:
+          type: array
+          items:
+            type: string
+        emails:
+          type: array
+          items:
+            type: string
+        microsoftTenants:
+          type: object
+          additionalProperties:
+            type: string
+      required:
+        - mode
     AppleLoginOptions:
       type: object
       properties:
@@ -24449,6 +24514,10 @@ components:
           enum:
             - open
             - invite
+        access:
+          $ref: "#/components/schemas/AuthKitAccess"
+        microsoftClientId:
+          type: string
       required:
         - id
     AuthKitInviteRequest:
@@ -24581,6 +24650,7 @@ components:
         - ACCOUNT_EXISTS_UNVERIFIED
         - APPLE_AUTH_FAILED
         - SIGN_UP_CLOSED
+        - NOT_IN_ORGANISATION
     MfaFactor:
       type: string
       enum:
@@ -28948,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:
@@ -28983,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:
@@ -29358,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:
@@ -29697,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:
@@ -29707,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/authKit.d.ts

@@ -98,6 +98,40 @@ export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN'
  * Options for {@link authKit.appleLogin}. All fields are optional — only the
  * `identityToken` (passed as a positional argument) is required by the server.
  */
+/** Options for {@link authKit.microsoftLogin}. */
+export interface MicrosoftLoginOptions {
+    /**
+     * The site the session will be handed to, when signing in through a popup page on another address
+     * (the SmartLinks Microsoft sign-in page does this). The server refuses unless it's one of the login
+     * setup's own sites (`MICROSOFT_ORIGIN_NOT_ALLOWED`). Leave it out when signing in on the site itself.
+     */
+    returnOrigin?: string;
+    /** Skip the step-up MFA challenge on a recognised device. */
+    trustedDeviceToken?: string;
+}
+/**
+ * Who can sign in through a login setup, whatever the method (password, magic link, phone, WhatsApp,
+ * Google, Apple, LinkedIn, Microsoft):
+ * - `anyone` (also: no `access`) — anyone, as before;
+ * - `organisation` — people from the listed organisations: a VERIFIED email at one of `domains`, one of
+ *   the listed `emails`, or signing in with Microsoft from the domain's own Microsoft organisation. A
+ *   Microsoft email alone doesn't count (an organisation can give its users any address), so on save
+ *   the server looks up each domain's Microsoft organisation itself — nobody types a tenant id.
+ *
+ * Checked every time a session is issued (tightening it shuts people out from their next sign-in);
+ * refused with `NOT_IN_ORGANISATION` (403). Registration refuses outside addresses up front and never
+ * signs an unverified address straight in. Accounts with no email (phone / WhatsApp only) can't show
+ * they're from an organisation. The public config returns only `{ mode, domains }`.
+ */
+export interface AuthKitAccess {
+    mode: 'anyone' | 'organisation';
+    /** e.g. `['acme.com']` (no `@`; exact domains — list subsidiaries' domains too). Up to 50. */
+    domains?: string[];
+    /** Particular people allowed besides the organisations, e.g. a contractor. Up to 50. Never public. */
+    emails?: string[];
+    /** Server-filled on save: `{ 'acme.com': '<Microsoft tenant id>' }` for domains with a Microsoft organisation. Read-only. */
+    microsoftTenants?: Record<string, string>;
+}
 export interface AppleLoginOptions {
     /** Apple authorization code. Accepted but ignored by the server for now (reserved for future server-side token exchange). */
     authorizationCode?: string;
@@ -128,7 +162,7 @@ export interface AppleLoginOptions {
  * `ACCOUNT_EXISTS_UNVERIFIED` case also carries `requiresEmailVerification: true`
  * in `SmartlinksApiError.details`.
  */
-export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED' | 'SIGN_UP_CLOSED';
+export type AuthKitErrorCode = 'MISSING_APPLE_TOKEN' | 'APPLE_AUTH_NOT_CONFIGURED' | 'INVALID_APPLE_TOKEN' | 'ACCOUNT_EXISTS_UNVERIFIED' | 'APPLE_AUTH_FAILED' | 'SIGN_UP_CLOSED' | 'NOT_IN_ORGANISATION' | 'MISSING_MICROSOFT_TOKEN' | 'MICROSOFT_AUTH_NOT_CONFIGURED' | 'INVALID_MICROSOFT_TOKEN' | 'MICROSOFT_ORIGIN_NOT_ALLOWED' | 'MICROSOFT_AUTH_FAILED';
 /** A second-step method: a code by email or text message, or from an authenticator app. */
 export type MfaFactor = 'email' | 'sms' | 'totp';
 /**
@@ -445,6 +479,16 @@ export interface AuthKitConfig {
      * Setting `invite` needs own logins first (`OWN_LOGINS_REQUIRED`, 409).
      */
     signUp?: 'open' | 'invite';
+    /** Who can sign in — see {@link AuthKitAccess}. Absent = anyone. */
+    access?: AuthKitAccess;
+    /**
+     * Sign in with Microsoft: add `'microsoft'` to `enabledProviders`. SmartLinks' own Microsoft app serves
+     * every organisation and personal Microsoft accounts, so nothing else is needed. Set this only to show
+     * your OWN name on Microsoft's sign-in screen: the Application (client) ID of your own multitenant app
+     * registration (redirect URI: https://smartlinks.app/apps/account/stable/microsoft-proxy.html). On the
+     * public config it's the effective id (yours, else SmartLinks').
+     */
+    microsoftClientId?: string;
 }
 /** Body of {@link authKit.invite}. */
 export interface AuthKitInviteRequest {

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';