@proveanything/smartlinks 2.1.14 → 2.1.16

package/docs/connectors.md

@@ -92,6 +92,7 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `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; `{ maxEvents, maxAttributes }` when the provider caps registered events — a flow's `eventMapping` is checked against them when saved. |
+| `actions[]` | Provider operations invoked on demand (redeem, enrol, issue…): name, title, function, `visibility`, input schema. See [Actions](#actions-provider-operations-on-demand). |
 
 ---
 
@@ -219,6 +220,61 @@ A connector should ship an `eventMapping` **preset** with the provider's standar
 
 ---
 
+## Actions: provider operations on demand
+
+Steps are called by the engine. **Actions** are called when someone asks: redeem a reward, enrol a
+member, issue a coupon, raise a ticket, send a receipt, check a balance. A connector declares them in
+the manifest and implements each as a server function; the platform decides who may call them and
+runs them with the connector's credentials, telling the function who asked.
+
+```jsonc
+"connector": {
+  "actions": [
+    { "name": "redeem", "title": "Redeem a reward", "function": "redeemReward", "visibility": "member",
+      "input": { "type": "object", "required": ["rewardId"], "properties": { "rewardId": { "type": "string" } } } },
+    { "name": "enrol", "title": "Join the programme", "function": "enrolMember", "visibility": "member" },
+    { "name": "coupon-status", "title": "Coupon status", "function": "couponStatus", "visibility": "public" },
+    { "name": "adjust-points", "title": "Adjust points", "function": "adjustPoints" }     // admin only (the default)
+  ]
+}
+```
+
+| `visibility` | Who may invoke it |
+|---|---|
+| `admin` (default) | the console and admin API; any app function |
+| `member` | also a signed-in person through the Hub / a site |
+| `public` | also anyone |
+
+The function receives `event.body = { input, installation, caller: { userId, contactId, role, surface } }`
+and returns JSON (or a `Response`). `input.required` fields from the declared schema are checked before
+the function runs (400 with `missing[]`); fuller validation is the connector's job.
+
+```ts
+export async function redeemReward(ctx: any, event: any) {
+  const { input, caller } = event.body
+  if (!caller.contactId) return new Response(JSON.stringify({ error: 'no_contact' }), { status: 400 })
+  const memberId = (await ctx.sl.contacts.forCaller())?.customFields?.loyaltyMemberId   // written by Profile
+  const res = await ctx.fetch(`${api}/members/${memberId}/redemptions`, { method: 'POST', headers: auth(await ctx.secrets.get('apiKey')), body: JSON.stringify({ reward: input.rewardId }) })
+  return res.json()
+}
+```
+
+Calling an action:
+
+```ts
+// From the Hub or a site (visibility public / member):
+const { actions } = await integrations.listConnectorActions(collectionId, 'acme-loyalty')
+const out = await integrations.callConnectorAction(collectionId, 'acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From another app's server function (any visibility; needs sl:connectors:write):
+const out = await ctx.sl.connectors.call('acme-loyalty', 'redeem', { rewardId: 'R-5' })
+
+// From the console (any visibility):
+await integrations.runConnectorAction(collectionId, 'acme-loyalty', 'adjust-points', { memberId, delta: 100 })
+```
+
+---
+
 ## Where configuration lives
 
 | What | Where |

package/docs/integrations.md

@@ -118,6 +118,7 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
 
 ```jsonc
 {
+  "specVersion": 1,                            // bumped only when a consumer could break
   "id": "0b2b…",                               // the event's id — stable across retries; use it as the destination's idempotency / transaction id
   "type": "interaction.submitted:quiz-1",
   "entityType": "interaction", "entityId": "0b2b…",
@@ -126,12 +127,14 @@ mapped with the flow's field mappings (or handed to a connector's `serialize`):
   "identity": {
     "contactId": "…", "userId": "…",
     "externalIds": { "acme-loyalty": "M-9", "crm": "C-1" },     // ids other systems know this person by
+    "anonymousId": "v-77", "sessionId": "s-1",                  // the visitor / device and session, before anyone signed in (every policy)
     "emailHash": "…", "phoneHash": "…", "hashAlgorithm": "hmac-sha256"   // policy 'hashed' (default)
     // "email", "phone": only under policy 'raw'
   },
   "identityPolicy": "hashed",
   "product": { "id": "P1", "name": "Widget", "sku": "W-1", "gtin": "0500…", "variantId": null, "batchId": null },
   "proof": { "id": "…" },
+  "consent": { "channels": { "email": "opted_in", "sms": "suppressed", "push": "unknown", "whatsapp": "unknown" }, "topics": { "offers": true }, "updatedAt": "…" },   // null when about nobody we hold
   "subject": { "interactionId": "quiz-1", "outcome": "completed", "metadata": { "score": 9 }, "source": "hub" },
   "event": { "name": "engagement_completed", "attributes": { "kind": "quiz", "score": 9 }, "rule": "quiz" },   // from eventMapping
   "attributes": {}
@@ -142,6 +145,11 @@ Field mappings read envelope paths (`identity.externalIds.acme-loyalty`, `subjec
 `event.name`, `product.sku`). With no mappings the envelope itself is sent. A failed event delivery
 keeps its envelope and is retried from it; a product is re-read instead.
 
+**CloudEvents.** `config.envelopeFormat: 'cloudevents'` wraps each delivered body (mapped or not) as a
+CloudEvents 1.0 structured event — `{ specversion: '1.0', id, type, source: 'urn:smartlinks:collection:<id>',
+subject, time, datacontenttype, dataschema: 'urn:smartlinks:envelope:v1', data }` — the shape every event
+bus, lake and serverless tool already consumes.
+
 ```ts
 const flow = await integrations.createFlow(collectionId, {
   appId: 'core-integrations', direction: 'outbound', name: 'Engagement → loyalty', status: 'active',

package/docs/server-functions.md

@@ -518,6 +518,7 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | 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) |
 

package/docs/tag-ranges.md

@@ -55,6 +55,27 @@ tag without a chip, with its URL and key; write it, then `ranges.recordTag(scope
 
 To find where a chip or code went, `partner.lookupTags(partner.id, { uid })` or `{ code }` searches every set the partner owns and returns each hit's set, tag and range, never a key.
 
+## Open ranges and groups
+
+A range's count is fixed when it is minted. Two phone-side jobs don't know their count in advance, so a range
+has a `kind`:
+
+- **`open`**: blank tags programmed on Sidekick one at a time. `ranges.create(scope, set.id, { kind: 'open', name })`
+  reserves only a start index; each `ranges.next()` hands back a free minted code or mints one more, so
+  `quantity`/`endIndex` grow as tags are written (`remaining` is null). One open range per set, and nothing can
+  be minted behind it (`409 RANGE_OPEN`) until `ranges.close(scope, set.id, range.id)` turns it into an ordinary
+  range (an open range that minted nothing is removed instead).
+- **`group`**: tags that already exist, added by tapping, assigned by hand, and moved together later. Assigners may
+  make one: `ranges.create(scope, set.id, { kind: 'group', name, intendedCollectionId? })`. Each tap goes through
+  `ranges.addMember(scope, set.id, group.id, { code | uid, collectionId, productId? })`, which stamps the tag with
+  the group and assigns it with the single-tag rules; `assigned.skipped` says when a tag was left alone (claimed,
+  or in a collection you don't administer). `ranges.assign(scope, set.id, group.id, { collectionId })` moves every
+  member in one go; `ranges.removeMember` takes one out. Groups have no printer file, instructions, import or
+  `next` (`400 NOT_A_RANGE`). Its tags must be codes of the group's set; a chip that is a code elsewhere is
+  `409 OTHER_SET`.
+
+Status reads `open` or `group` for these (and `assigned` once every member of a group is assigned).
+
 ## The printer file
 
 One row per tag, in index order. The manufacturer fills in `UID` and sends the same file back; rows are

package/openapi.yaml

@@ -14952,6 +14952,38 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /{groupId}/members:
+    post:
+      tags:
+        - ranges
+      summary: Put an existing tag of the set into a group (by code or chip UID), assigning it if a collection is given.
+      operationId: ranges_addMember
+      security: []
+      parameters:
+        - name: groupId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AddClaimSetRangeMemberResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AddClaimSetRangeMemberRequest"
   /{rangeId}:
     get:
       tags:
@@ -15041,6 +15073,38 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/AssignClaimSetRangeRequest"
+  /{rangeId}/close:
+    post:
+      tags:
+        - ranges
+      summary: "Close an open range: it becomes a range with the quantity it reached (removed if nothing was minted)."
+      operationId: ranges_close
+      security: []
+      parameters:
+        - name: rangeId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CloseClaimSetRangeResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ClaimSetScope"
   /{rangeId}/export:
     get:
       tags:
@@ -21235,6 +21299,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:
@@ -21288,6 +21378,10 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ConnectorPanel"
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConnectorAction"
         aiGuide:
           type: string
         recordId:
@@ -25889,6 +25983,8 @@ components:
           type: string
         namespace:
           type: string
+        kind:
+          $ref: "#/components/schemas/ClaimSetRangeKind"
         name:
           type: string
         notes:
@@ -25942,6 +26038,7 @@ components:
         - id
         - claimSetId
         - namespace
+        - kind
         - name
         - notes
         - startIndex
@@ -25965,6 +26062,8 @@ components:
     CreateClaimSetRangeRequest:
       type: object
       properties:
+        kind:
+          $ref: "#/components/schemas/ClaimSetRangeKind"
         name:
           type: string
         quantity:
@@ -25988,7 +26087,6 @@ components:
           type: string
       required:
         - name
-        - quantity
     UpdateClaimSetRangeRequest:
       type: object
       properties:
@@ -26032,6 +26130,10 @@ components:
           type: string
         proofId:
           type: string
+        rangeId:
+          type: string
+        groupId:
+          type: string
         programmedAt:
           type: string
         scans:
@@ -26045,6 +26147,8 @@ components:
         - productId
         - batchId
         - proofId
+        - rangeId
+        - groupId
         - programmedAt
         - scans
     ClaimSetRangeTagsPage:
@@ -26073,6 +26177,41 @@ components:
       required:
         - url
         - remaining
+    AddClaimSetRangeMemberRequest:
+      type: object
+      properties:
+        code:
+          type: string
+        uid:
+          type: string
+        collectionId:
+          type: string
+        productId:
+          type: string
+        batchId:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+        clear:
+          type: boolean
+    AddClaimSetRangeMemberResponse:
+      type: object
+      properties:
+        tag:
+          $ref: "#/components/schemas/ClaimSetRangeTag"
+        range:
+          $ref: "#/components/schemas/ClaimSetRange"
+        assigned:
+          type: object
+          additionalProperties: true
+        movedFrom:
+          type: string
+      required:
+        - tag
+        - range
+        - assigned
+        - movedFrom
     ImportClaimSetRangeUidsRequest:
       type: object
       properties:
@@ -26273,6 +26412,12 @@ components:
         - ntag424
         - ntag21x
         - qr
+    ClaimSetRangeKind:
+      type: string
+      enum:
+        - range
+        - open
+        - group
     ClaimSetRangeStatus:
       type: string
       enum:
@@ -26281,6 +26426,11 @@ components:
         - sent
         - received
         - assigned
+        - open
+        - group
+    CloseClaimSetRangeResponse:
+      type: object
+      additionalProperties: true
     ClaimSetImportResult:
       type: string
       enum:
@@ -29060,6 +29210,10 @@ components:
           additionalProperties: true
         eventMapping:
           $ref: "#/components/schemas/EventMapping"
+        envelopeFormat:
+          type: string
+          enum:
+            - cloudevents
         connection:
           $ref: "#/components/schemas/FlowConnection"
         fieldMappings:
@@ -29520,6 +29674,8 @@ components:
     EventEnvelope:
       type: object
       properties:
+        specVersion:
+          type: number
         id:
           type: string
         type:
@@ -29547,6 +29703,10 @@ components:
           type: object
           additionalProperties:
             type: string
+        anonymousId:
+          type: string
+        sessionId:
+          type: string
         emailHash:
           type: string
         phoneHash:
@@ -29567,6 +29727,9 @@ components:
         proof:
           type: object
           additionalProperties: true
+        consent:
+          type: object
+          additionalProperties: true
         subject:
           type: object
           additionalProperties: true
@@ -29577,6 +29740,7 @@ components:
           type: object
           additionalProperties: true
       required:
+        - specVersion
         - id
         - type
         - entityType
@@ -29589,9 +29753,12 @@ components:
         - contactId
         - userId
         - externalIds
+        - anonymousId
+        - sessionId
         - identityPolicy
         - product
         - proof
+        - consent
         - subject
         - attributes
     CapturedRequest:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.1.14",
+  "version": "2.1.16",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",