@proveanything/smartlinks 2.1.13 → 2.1.15

package/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/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/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/package.json

@@ -1,87 +1,87 @@
-{
-  "name": "@proveanything/smartlinks",
-  "version": "2.1.13",
-  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js",
-      "default": "./dist/testing/index.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "import": "./dist/*.js",
-      "default": "./dist/*.js"
-    },
-    "./baseline.css": "./dist/baseline.css",
-    "./baseline.classes.json": "./dist/baseline.classes.json",
-    "./theme.css": "./dist/theme.css",
-    "./theme-boot.js": "./dist/theme-boot.js",
-    "./package.json": "./package.json"
-  },
-  "bin": {
-    "smartlinks-register-release": "scripts/register-release.mjs",
-    "smartlinks-publish": "scripts/publish.mjs",
-    "smartlinks-doctor": "scripts/doctor.mjs",
-    "smartlinks-headless": "scripts/headless-check.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "scripts/register-release.mjs",
-    "scripts/publish.mjs",
-    "scripts/doctor.mjs",
-    "scripts/headless-check.mjs",
-    "scripts/lib/",
-    "openapi.yaml",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node test/run.cjs",
-    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
-    "docs": "typedoc",
-    "docs:summary": "node generate-api-summary.cjs",
-    "docs:openapi": "node generate-openapi.cjs",
-    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
-    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
-    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "smartlinks",
-    "api",
-    "authentication",
-    "traceability",
-    "blockchain",
-    "typescript",
-    "sdk"
-  ],
-  "author": "Glenn Shoosmith",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "cross-fetch": "^3.1.5",
-    "es-module-lexer": "^1.7.0"
-  },
-  "devDependencies": {
-    "ts-node": "^10.9.1",
-    "typedoc": "^0.25.13",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typescript": "^4.9.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Prove-Anything/smartlinks.git"
-  },
-  "homepage": "https://smartlinks.app"
-}
+{
+  "name": "@proveanything/smartlinks",
+  "version": "2.1.15",
+  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./baseline.css": "./dist/baseline.css",
+    "./baseline.classes.json": "./dist/baseline.classes.json",
+    "./theme.css": "./dist/theme.css",
+    "./theme-boot.js": "./dist/theme-boot.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "smartlinks-register-release": "scripts/register-release.mjs",
+    "smartlinks-publish": "scripts/publish.mjs",
+    "smartlinks-doctor": "scripts/doctor.mjs",
+    "smartlinks-headless": "scripts/headless-check.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "scripts/register-release.mjs",
+    "scripts/publish.mjs",
+    "scripts/doctor.mjs",
+    "scripts/headless-check.mjs",
+    "scripts/lib/",
+    "openapi.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.cjs",
+    "build": "tsc && node scripts/fix-esm-extensions.mjs && node generate-api-summary.cjs && node generate-openapi.cjs && node scripts/copy-docs-to-dist.cjs && node scripts/build-baseline.mjs",
+    "docs": "typedoc",
+    "docs:summary": "node generate-api-summary.cjs",
+    "docs:openapi": "node generate-openapi.cjs",
+    "docs:openapi:lint": "npx --yes @redocly/cli@latest lint openapi.yaml",
+    "docs:openapi:check": "node generate-openapi.cjs && npx --yes @redocly/cli@latest lint openapi.yaml",
+    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "smartlinks",
+    "api",
+    "authentication",
+    "traceability",
+    "blockchain",
+    "typescript",
+    "sdk"
+  ],
+  "author": "Glenn Shoosmith",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.5",
+    "es-module-lexer": "^1.7.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.1",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^4.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Prove-Anything/smartlinks.git"
+  },
+  "homepage": "https://smartlinks.app"
+}