@proveanything/smartlinks 2.1.12 → 2.1.14

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
+import type { AuthLoginResponse, AppleLoginOptions, MicrosoftLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -93,6 +93,22 @@ export declare namespace authKit {
      * @see AppleLoginOptions
      */
     function appleLogin(clientId: string, identityToken: string, opts?: AppleLoginOptions): Promise<AuthLoginResponse>;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    function microsoftLogin(clientId: string, idToken: string, opts?: MicrosoftLoginOptions): Promise<AuthLoginResponse>;
     /**
      * Exchange a refresh token for a fresh access token (public — the refresh token IS
      * the credential). **Native sessions only**; refresh tokens are issued only when the

package/dist/api/authKit.js

@@ -139,6 +139,30 @@ export var authKit;
         return res;
     }
     authKit.appleLogin = appleLogin;
+    /**
+     * Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft
+     * accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer
+     * token is stored and the cache invalidated.
+     *
+     * Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`)
+     * against the app in the public config's `microsoftClientId`. A site on its own domain can't be a
+     * registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in
+     * page in a popup, which calls this with `opts.returnOrigin` and hands the result back.
+     *
+     * Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400),
+     * `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 —
+     * the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409),
+     * `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+     */
+    async function microsoftLogin(clientId, idToken, opts) {
+        const res = await post(`/authkit/${encodeURIComponent(clientId)}/auth/microsoft`, Object.assign({ idToken }, opts));
+        if (res.token) {
+            setBearerToken(res.token);
+            invalidateCache();
+        }
+        return res;
+    }
+    authKit.microsoftLogin = microsoftLogin;
     /* ===================================
      * Native session refresh (public)
      * =================================== */

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.12  |  Generated: 2026-11-08T14:30:42.034Z
+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 }
 }
 ```
 
@@ -4624,6 +4627,24 @@ interface LogoutResponse {
 }
 ```
 
+**MicrosoftLoginOptions** (interface)
+```typescript
+interface MicrosoftLoginOptions {
+  returnOrigin?: string
+  trustedDeviceToken?: string
+}
+```
+
+**AuthKitAccess** (interface)
+```typescript
+interface AuthKitAccess {
+  mode: 'anyone' | 'organisation'
+  domains?: string[]
+  emails?: string[]
+  microsoftTenants?: Record<string, string>
+}
+```
+
 **AppleLoginOptions** (interface)
 ```typescript
 interface AppleLoginOptions {
@@ -4953,6 +4974,8 @@ interface AuthKitConfig {
   collectionIds?: string[]
   identity?: AuthKitIdentity
   signUp?: 'open' | 'invite'
+  access?: AuthKitAccess
+  microsoftClientId?: string
 }
 ```
 
@@ -7933,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
@@ -7955,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
@@ -8145,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 {
@@ -8347,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'`
 
@@ -11937,6 +12047,9 @@ Sign in with LinkedIn (OpenID Connect) via a server-side authorization code (pub
 **appleLogin**(clientId: string, identityToken: string, opts?: AppleLoginOptions) → `Promise<AuthLoginResponse>`
 Sign in with Apple via an Apple identity token (public). Mirrors {@link googleLogin}. On success the returned bearer token is stored automatically and the cache is invalidated. Notable error codes (thrown as `SmartlinksApiError`, read via `err.errorCode`): - `MISSING_APPLE_TOKEN` (400), `APPLE_AUTH_NOT_CONFIGURED` (400), `INVALID_APPLE_TOKEN` (401), `APPLE_AUTH_FAILED` (500) - `ACCOUNT_EXISTS_UNVERIFIED` (409) — an unverified account already owns this email; the server refuses to silently link. `err.details.requiresEmailVerification` is `true`. Recoverable: the user should sign in with their password (or reset it), then link Apple from settings. **The same 409 can now come back from {@link googleLogin}** under the shared verified-to-verified linking policy. Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. Pass `opts.trustedDeviceToken` to skip the challenge on a recognized device.
 
+**microsoftLogin**(clientId: string, idToken: string, opts?: MicrosoftLoginOptions) → `Promise<AuthLoginResponse>`
+Sign in with Microsoft — work or school accounts from any organisation, and personal Microsoft accounts — via a Microsoft ID token (public). Mirrors {@link appleLogin}: on success the bearer token is stored and the cache invalidated. Get the ID token from Microsoft's sign-in (response_type `id_token`, scope `openid profile email`) against the app in the public config's `microsoftClientId`. A site on its own domain can't be a registered address of that app, so the SmartLinks sign-in UI opens SmartLinks' Microsoft sign-in page in a popup, which calls this with `opts.returnOrigin` and hands the result back. Notable error codes: `MISSING_MICROSOFT_TOKEN` (400), `MICROSOFT_AUTH_NOT_CONFIGURED` (400), `INVALID_MICROSOFT_TOKEN` (401), `MICROSOFT_ORIGIN_NOT_ALLOWED` (403), `NOT_IN_ORGANISATION` (403 — the login setup's {@link AuthKitAccess} rule), `ACCOUNT_EXISTS_UNVERIFIED` (409), `MICROSOFT_AUTH_FAILED` (500). Gated by step-up MFA like every sign-in.
+
 **refreshToken**(clientId: string, refreshToken: string) → `Promise<RefreshResponse>`
 Exchange a refresh token for a fresh access token (public — the refresh token IS the credential). **Native sessions only**; refresh tokens are issued only when the host opted in via `initializeApi({ platform: 'native' })`. On success the new access token is stored automatically (`setBearerToken`). The returned `refreshToken` is **rotated** — the caller must persist it and discard the old one before refreshing again. ⚠️ **Single-use, no retry, serialize calls.** This method issues exactly one request and never retries: replaying a consumed refresh token triggers `REFRESH_TOKEN_REUSE_DETECTED` (the whole session family is revoked). The caller is responsible for ensuring only one refresh is in flight at a time (e.g. across tabs or resume events). Errors (thrown as `SmartlinksApiError`, read via `err.errorCode`): `MISSING_REFRESH_TOKEN` (400), `INVALID_REFRESH_TOKEN` (401), `REFRESH_TOKEN_REUSE_DETECTED` (401) — the last two mean a hard logout.
 

package/dist/docs/auth-kit.md

@@ -259,6 +259,56 @@ try {
 > ⚠️ This is a behaviour change for `googleLogin`, which previously merged silently in
 > this case. Handle the 409 for both methods.
 
+### Sign in with Microsoft
+
+Work or school accounts from **any** organisation, and personal Microsoft accounts (Outlook, Hotmail,
+Live). Add `'microsoft'` to `enabledProviders` — that's all: SmartLinks' own Microsoft app serves every
+organisation, so neither you nor your users' IT registers anything.
+
+```ts
+const session = await authKit.microsoftLogin(clientId, microsoftIdToken, { returnOrigin });
+```
+
+- **In the SmartLinks sign-in UI** the Microsoft button opens SmartLinks' Microsoft sign-in page
+  (`https://smartlinks.app/apps/account/stable/microsoft-proxy.html`) in a popup — the one address
+  registered with Microsoft — which signs in and hands the session back to your site. Your site must be
+  one of the login setup's own (its collections' domains or site addresses, or `allowedRedirectDomains`),
+  else `MICROSOFT_ORIGIN_NOT_ALLOWED` (403).
+- **Your own UI:** get an ID token from Microsoft (`response_type=id_token`, scope `openid profile email`,
+  authority `https://login.microsoftonline.com/common`) for the app in the public config's
+  `microsoftClientId`, and pass it here.
+- **Some companies' IT approves new apps for their staff.** The first person from such a company sees
+  "needs admin approval"; their IT approves SmartLinks once for the organisation and everyone can sign in.
+- **Your own name on Microsoft's screen (optional):** register your own *multitenant* app in Microsoft
+  Entra (Supported account types: any organisation + personal accounts; Web redirect URI as above, with
+  "ID tokens" ticked; token configuration: optional claim `xms_edov` on the ID token) and set its
+  Application (client) ID as `microsoftClientId`.
+- A Microsoft account's email is trusted only when Microsoft vouches that its organisation owns the
+  domain (or for personal accounts): an organisation can give its users any address. Linking to an
+  existing account by email follows the same verified-to-verified rule as Google and Apple.
+
+### Who can sign in (`access`)
+
+Restrict a login setup to one organisation — no keys, no IT:
+
+```ts
+await authKit.update(collectionId, clientId, {
+  access: { mode: 'organisation', domains: ['acme.com'], emails: ['contractor@gmail.com'] },
+});
+```
+
+- Someone is from acme.com when their **verified** email is at acme.com, they're one of `emails`, or they
+  signed in with Microsoft from acme's own Microsoft organisation (looked up from the domain when you
+  save — `microsoftTenants` is filled in for you).
+- Checked on **every** sign-in method each time a session is issued: everyone else gets
+  `NOT_IN_ORGANISATION` (403) with a message naming the domain. Tighten the rule and people already in
+  are refused from their next sign-in.
+- `register` refuses outside addresses before making anything, and never signs an unverified address
+  straight in (even in `immediate` mode) — it must be verified first.
+- Phone-only and WhatsApp-only accounts have no email to prove an organisation, so they can't get in.
+- The public config (`load`) returns `access: { mode, domains }` so your page can say who it's for; the
+  `emails` list is never public. `{ mode: 'anyone' }` (or no `access`) lets everyone in, as before.
+
 ### Refresh tokens (native sessions)
 
 Native/Capacitor hosts can hold long-lived sessions via refresh tokens. Opt in **once**

package/dist/docs/connectors.md

@@ -1,7 +1,7 @@
 # Integration connectors
 
 A **connector** is an app that knows one external provider (a PIM, a content network, a shop
-platform…). It is installed on a collection like any app, versioned and released like any app, and
+platform, a loyalty or CRM system…). It is installed on a collection like any app, versioned and released like any app, and
 it adds a manifest `connector` block plus a handful of [server functions](server-functions.md) the
 integration engine and the integrations console call by convention.
 
@@ -83,7 +83,7 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `provider` | Stable provider key (`syndigo`, `oneworldsync`). |
 | `title` | Provider display name; defaults to the app name. |
 | `directions` | `inbound` (provider → SmartLinks), `outbound` (SmartLinks → provider), or both. |
-| `entities` | SmartLinks entities it maps, e.g. `["product"]`. |
+| `entities` | SmartLinks entities it maps: `product`, and for people-shaped providers `interaction`, `contact`, `event` (see [Loyalty and CRM connectors](#loyalty-and-crm-connectors)). |
 | `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name on the collection (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
 | `settings` | JSON Schema for installation settings; the console renders it as a form. |
 | `presets[]` | Ready-made flows ("Products → provider"). A preset's `flow.config.fieldMappings` is a **suggested** mapping: the connector's knowledge of the provider, which the customer accepts or edits in core. |
@@ -91,7 +91,7 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `panels[]` | Provider-specific screens the console mounts (an API explorer, a status page). |
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
 | `recordId` | Path of the provider's own id in a fetched record (e.g. `gtin`). Inbound records are landed and matched by it, so a re-import updates the same product instead of creating another. Default `id`; a flow can override it (`config.upsert.externalIdPath`). |
-| `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker. |
+| `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker; `{ maxEvents, maxAttributes }` when the provider caps registered events — a flow's `eventMapping` is checked against them when saved. |
 
 ---
 
@@ -111,7 +111,9 @@ declare the provider's hosts (`network:<host>`) and the secrets it reads (`secre
 | `fetch` | Every inbound run | `ConnectorFetchInput` `{ installation, cursor, limit }` | `ConnectorRecords` `{ records, nextCursor }`: one page per call |
 | `shape` | Every inbound run (and sample dry runs) | `ConnectorShapeInput` `{ installation, records }` | `ConnectorShapeResult` `{ documents, skipped }`: one provider-neutral document per record, same order; `null` skips one |
 | `serialize` | Every outbound run | `ConnectorSerializeInput` `{ installation, documents, entities, targetOptions, eventType? }`: documents core mapped to `describeTarget` paths; `entities` = the SmartLinks record each came from (id, name); `targetOptions` = per-field options the mapping carries (e.g. locale, unit); a deletion arrives as `{ id, _deleted: true }` | `ConnectorSerializeResult` `{ payloads, skipped }`: one provider payload per document, same order; `null` skips one |
-| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
+| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads, eventType? }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId, retryable?, retryAfterSeconds? }] }` — `retryable: false` for a provider validation error (dead at once), `true` / a 5xx or 429 status for anything worth retrying |
+| `describeEvents` | Mapper opens; a flow with an `eventMapping` is saved | `{ installation }` | `ConnectorEventsSchema` `{ events: [{ name, title, attributes: [{ name, type, required }] }], limits: { maxEvents, maxAttributes } }`: the event names the provider has registered for this customer |
+| `lookup` | An entitlement check (`docs/entitlements.md`) | `ConnectorLookupInput` `{ installation, identity: { externalId, email, phone } \| { externalId, emailHash, phoneHash }, want }` | `ConnectorLookupResult` `{ found, memberId, tier, points, status, attributes, asOf }`. Throw for an outage — never `found: false` |
 
 **How a run flows:**
 - **Inbound:** `fetch` (paged; every record is landed as received) → `shape` → core maps the documents
@@ -182,6 +184,41 @@ export async function shape(_ctx: any, event: any): Promise<ConnectorShapeResult
 
 ---
 
+## Loyalty and CRM connectors
+
+A provider that is about **people** rather than products uses the same contract with three more
+pieces; nothing provider-specific lives in core. Full contract: `loyalty-connector-authoring.md` in the
+platform's design docs; the shapes are in [integrations.md](integrations.md#event-sourced-flows-and-the-envelope).
+
+| Flow | What core does | What the connector does |
+|---|---|---|
+| **Earn** (us → them) | an outbound flow with `sourceEntity: 'interaction' \| 'contact' \| 'event'` sends one **envelope** per event, through the flow's identity policy and `eventMapping`, signed, with retries and a run log | `describeEvents` (what the provider has registered), `serialize` (envelope → the provider's event payload), `send` if the generic HTTP destination can't make the call |
+| **Profile** (them → us) | `ctx.sl.members.apply(document)` matches the contact and writes member id, tier, points, tags, external ids; or an inbound flow with `targetEntity: 'contact'` | an **HTTP-trigger function** receiving the provider's member webhook (verify their signature, then apply); or `fetch` + `shape` for a poll |
+| **Gate / display** (on demand) | `entitlements.check` — claims → cached `lookup` → the contact's own loyalty fields → fallback; Valkey cache keyed on an identity hash, brand-set TTL | `lookup`: one identity → tier / points / status |
+
+```ts
+// A member webhook: the provider tells us about a person; we land it on the contact.
+export default async function memberWebhook(event: any, ctx: any) {
+  verifyProviderSignature(event, await ctx.secrets.get('webhookSecret'))
+  const m = event.body
+  return ctx.sl.members.apply({
+    identity: { externalId: m.memberId, email: m.email },
+    contact:  { firstName: m.firstName, lastName: m.lastName },        // fills empty fields only
+    loyalty:  { memberId: m.memberId, tier: m.tier, points: m.points, status: m.status, asOf: m.updatedAt },
+    tags:     { add: [`tier:${m.tier}`] },
+  }, { provider: 'acme-loyalty' })                                     // → { contactId, op: 'created' | 'updated' | 'unchanged' }
+}
+```
+
+Declare it `{ "trigger": { "type": "http" }, "capabilities": ["sl:members:write", "secrets:webhookSecret"] }`;
+`sl:members:write` is approved by the admin on install. The envelope's `identity.externalIds[<provider>]`
+is the member id this wrote back, so **Earn** can address the member by the provider's own id.
+
+A connector should ship an `eventMapping` **preset** with the provider's standard event names and an
+`aiGuide` paragraph, so the console's assistant proposes a customer's mapping in the provider's terms.
+
+---
+
 ## Where configuration lives
 
 | What | Where |
@@ -220,6 +257,7 @@ await secrets.put(collectionId, 'provider-key', value, { appId })              /
 await integrations.saveConnectorInstallation(collectionId, appId, { connection: { environment: 'production' } })
 const test = await integrations.runConnectorStep(collectionId, appId, 'testConnection')
 const target = await integrations.runConnectorStep(collectionId, appId, 'describeTarget')
+const events = await integrations.runConnectorStep(collectionId, appId, 'describeEvents')   // loyalty / engagement providers
 const { records } = await integrations.runConnectorStep(collectionId, appId, 'sample', { limit: 5 })
 const shaped = await integrations.runConnectorStep(collectionId, appId, 'shape', { records })      // dry run
 const wire = await integrations.runConnectorStep(collectionId, appId, 'serialize', { documents })  // dry run

package/dist/docs/entitlements.md

@@ -0,0 +1,90 @@
+# Entitlements: "can this person do this?" without a mirror of their member base
+
+A brand with twenty million members wants a game only Gold members can play. SmartLinks never copies
+the member base to find out. A **gate** says what it needs — a predicate such as `tier>=gold` — and the
+platform asks the collection's configured **sources**, in order, stopping at the first that answers.
+The brand's system stays the record of truth; every answer says where it came from (`basis`) and how
+old it is (`asOf`).
+
+| Source | Data kept here | When it fits |
+|---|---|---|
+| **claims** | none | the brand's SSO or app issues a short-lived signed token carrying the tier; the caller presents it |
+| **lookup** | a hashed key → a small answer, for minutes | the loyalty connector's `lookup` step answers for one person; cached in Valkey under an HMAC of the identity for the TTL the brand sets (default 15 min; "not a member" 5 min); one in-flight lookup per key; the connector's own rate limit applies |
+| **contact** | what the contact already holds | `customFields.loyalty` / `loyaltyTier` written by the connector's member webhook (`ctx.sl.members.apply`) |
+| **fallback** | — | when nothing answered: `deny` (default), `allow`, or `degrade` (allow, flagged `degraded: true`) |
+
+Every decision is one structured log line — gate, predicate, allowed, basis, age, an identity **hash**
+— and never an identifier. A caller sees `attributes` (tier, points, status, member) and never a member
+id.
+
+## Predicates
+
+```
+'tier>=gold'   'tier=silver'   'tier in gold,platinum'   'points>=500'   'member'
+{ tier: { gte: 'gold' } }   { tier: { in: ['gold', 'platinum'] } }   { member: true }
+{ attribute: { path: 'status', eq: 'active' } }
+{ all: [p1, p2] }   { any: [p1, p2] }   { not: p }
+```
+
+Tier comparisons use the collection's ordered `tiers` list (lowest first); a tier the list doesn't know
+never satisfies an ordered comparison. A malformed predicate is a configuration error (`BAD_PREDICATE`),
+never a silent denial.
+
+## Where gates live
+
+**An interaction type** — the public submit route checks it; the caller may present a claim:
+
+```ts
+await SL.interactions.updateInteraction(collectionId, appId, typeId, {
+  permissions: { allowPublicSubmit: true, requires: { entitlement: 'tier>=gold', fallback: 'deny' } },
+})
+// A refused submit: 403 { error: 'FORBIDDEN', reason: 'entitlement_denied' }
+// With a claim: body.entitlementToken = '<jwt>'  or header X-SmartLinks-Entitlement: <jwt>
+```
+
+**A server function** — for the signed-in caller by default:
+
+```ts
+const d = await ctx.sl.entitlements.check('tier>=gold')          // needs sl:entitlements:read
+// → { allowed: true, basis: 'lookup-cache', asOf: '2026-11-08T09:00:00.000Z', attributes: { tier: 'gold', points: 1500, member: true } }
+if (!d.allowed) return new Response(JSON.stringify({ error: 'gold_only' }), { status: 403 })
+// Someone else, or a presented claim:
+await ctx.sl.entitlements.check({ points: { gte: 500 } }, { identity: { email }, token, fallback: 'degrade' })
+```
+
+## Configuring a collection
+
+The `entitlements` setting group (`settings.set(collectionId, 'entitlements', {...})`):
+
+```jsonc
+{
+  "sources": ["claims", "lookup", "contact"],        // tried in this order
+  "fallback": "deny",
+  "tiers": ["bronze", "silver", "gold", "platinum"], // lowest first
+  "claims": {
+    "secretRef": "sec_brand_sso",                     // HS256 shared secret in the secret store …
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----…",     // … or an RS256 / ES256 public key
+    "issuer": "https://login.brand.example", "audience": "smartlinks",
+    "tierClaim": "tier", "memberIdClaim": "sub", "attributesClaim": "entitlements", "maxAgeSec": 900
+  },
+  "lookup": {
+    "connectorAppId": "acme-loyalty", "provider": "acme-loyalty",
+    "ttlSec": 900, "negativeTtlSec": 300,
+    "identity": "raw",                                // what the connector's lookup receives: 'raw' (email/phone) or 'hashed'
+    "want": ["tier", "points", "status"]
+  }
+}
+```
+
+The connector side (`lookup`) is one step: one identity in, `{ found, memberId, tier, points, status,
+asOf }` out; throw on an outage so the next source is tried — see
+[connectors.md](connectors.md#loyalty-and-crm-connectors).
+
+## What a brand can be told
+
+- We never need a copy of your member base: claims and lookups hold nothing, or a minutes-old answer per
+  active person.
+- Where you want a local copy, it holds no identifiers (the HMAC mirror — on request).
+- Your system remains the record of truth: every answer carries `asOf` and `basis`; TTLs are yours to set.
+- You see every call: the connector's calls are rate-limited, logged, and leave from a fixed egress IP.
+- Nothing leaves without a policy: the envelope's identity policy per flow.