@proveanything/smartlinks 2.1.14 → 2.1.16

package/dist/api/claimSet.d.ts

@@ -1,4 +1,4 @@
-import { ClaimSetScope, ClaimSetRange, CreateClaimSetRangeRequest, UpdateClaimSetRangeRequest, ClaimSetRangeTagsPage, ClaimSetRangeTag, ClaimSetRangeNextTag, ImportClaimSetRangeUidsRequest, ImportClaimSetRangeUidsResponse, AssignClaimSetRangeRequest, AssignClaimSetRangeResponse, ClaimSetRangeFile, UpdateClaimDataRequest, AssignClaimsRequest, CreateClaimSetTagRequest, CreateClaimSetTagResponse, CreateClaimSetRequest, ImportClaimSetTagsRequest, ImportClaimSetTagsResponse } from "../types/index.js";
+import { ClaimSetScope, ClaimSetRange, CreateClaimSetRangeRequest, UpdateClaimSetRangeRequest, ClaimSetRangeTagsPage, ClaimSetRangeTag, ClaimSetRangeNextTag, ImportClaimSetRangeUidsRequest, ImportClaimSetRangeUidsResponse, AssignClaimSetRangeRequest, AddClaimSetRangeMemberRequest, AddClaimSetRangeMemberResponse, CloseClaimSetRangeResponse, AssignClaimSetRangeResponse, ClaimSetRangeFile, UpdateClaimDataRequest, AssignClaimsRequest, CreateClaimSetTagRequest, CreateClaimSetTagResponse, CreateClaimSetRequest, ImportClaimSetTagsRequest, ImportClaimSetTagsResponse } from "../types/index.js";
 export declare namespace claimSet {
     /**
      * Get all claim sets.
@@ -106,6 +106,14 @@ export declare namespace claimSet {
         function update(scope: ClaimSetScope, claimSetId: string, rangeId: string, params: UpdateClaimSetRangeRequest): Promise<ClaimSetRange>;
         /** Finish minting a range that was interrupted. */
         function resume(scope: ClaimSetScope, claimSetId: string, rangeId: string): Promise<ClaimSetRange>;
+        /** Close an open range: it becomes a range with the quantity it reached (removed if nothing was minted). */
+        function close(scope: ClaimSetScope, claimSetId: string, rangeId: string): Promise<CloseClaimSetRangeResponse>;
+        /** Put an existing tag of the set into a group (by code or chip UID), assigning it if a collection is given. */
+        function addMember(scope: ClaimSetScope, claimSetId: string, groupId: string, params: AddClaimSetRangeMemberRequest): Promise<AddClaimSetRangeMemberResponse>;
+        /** Take a tag out of a group. Its assignment is left as it is. */
+        function removeMember(scope: ClaimSetScope, claimSetId: string, groupId: string, code: string): Promise<{
+            range: ClaimSetRange;
+        }>;
         /** The range's tags in index order, a page at a time (keys: owners/admins only). */
         function tags(scope: ClaimSetScope, claimSetId: string, rangeId: string, options?: {
             from?: number;

package/dist/api/claimSet.js

@@ -190,6 +190,21 @@ export var claimSet;
             return post(`${rangesBase(scope, claimSetId)}/${encodeURIComponent(rangeId)}/resume`, {});
         }
         ranges.resume = resume;
+        /** Close an open range: it becomes a range with the quantity it reached (removed if nothing was minted). */
+        async function close(scope, claimSetId, rangeId) {
+            return post(`${rangesBase(scope, claimSetId)}/${encodeURIComponent(rangeId)}/close`, {});
+        }
+        ranges.close = close;
+        /** Put an existing tag of the set into a group (by code or chip UID), assigning it if a collection is given. */
+        async function addMember(scope, claimSetId, groupId, params) {
+            return post(`${rangesBase(scope, claimSetId)}/${encodeURIComponent(groupId)}/members`, params);
+        }
+        ranges.addMember = addMember;
+        /** Take a tag out of a group. Its assignment is left as it is. */
+        async function removeMember(scope, claimSetId, groupId, code) {
+            return del(`${rangesBase(scope, claimSetId)}/${encodeURIComponent(groupId)}/members/${encodeURIComponent(code)}`);
+        }
+        ranges.removeMember = removeMember;
         /** The range's tags in index order, a page at a time (keys: owners/admins only). */
         async function tags(scope, claimSetId, rangeId, options = {}) {
             const q = new URLSearchParams();

package/dist/api/integrations.d.ts

@@ -105,4 +105,32 @@ export declare namespace integrations {
     function runConnectorStep<T = unknown>(collectionId: string, appId: string, step: ConnectorConsoleStep, input?: Record<string, unknown> & {
         flowId?: string;
     }): Promise<T>;
+    /**
+     * Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a
+     * coupon… The connector's function runs with its own credentials and is told who asked.
+     * POST /integrations/connectors/:appId/actions/:action { input }
+     */
+    function runConnectorAction<T = unknown>(collectionId: string, appId: string, action: string, input?: Record<string, unknown>): Promise<T>;
+    /**
+     * PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`,
+     * plus `member` ones when signed in.
+     * GET /public/collection/:collectionId/connectors/:appId/actions
+     */
+    function listConnectorActions(collectionId: string, appId: string): Promise<{
+        actions: Array<{
+            name: string;
+            title: string;
+            description?: string;
+            visibility: 'public' | 'member' | 'admin';
+            input?: Record<string, unknown>;
+            output?: Record<string, unknown>;
+        }>;
+    }>;
+    /**
+     * PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member.
+     * 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one;
+     * 400 with `missing[]` when a required input is absent.
+     * POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+     */
+    function callConnectorAction<T = unknown>(collectionId: string, appId: string, action: string, input?: Record<string, unknown>): Promise<T>;
 }

package/dist/api/integrations.js

@@ -200,4 +200,32 @@ export var integrations;
         return post(`${connectorsBase(collectionId)}/${enc(appId)}/steps/${enc(step)}`, input);
     }
     integrations.runConnectorStep = runConnectorStep;
+    /**
+     * Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a
+     * coupon… The connector's function runs with its own credentials and is told who asked.
+     * POST /integrations/connectors/:appId/actions/:action { input }
+     */
+    async function runConnectorAction(collectionId, appId, action, input = {}) {
+        return post(`${connectorsBase(collectionId)}/${enc(appId)}/actions/${enc(action)}`, { input });
+    }
+    integrations.runConnectorAction = runConnectorAction;
+    /**
+     * PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`,
+     * plus `member` ones when signed in.
+     * GET /public/collection/:collectionId/connectors/:appId/actions
+     */
+    async function listConnectorActions(collectionId, appId) {
+        return request(`/public/collection/${enc(collectionId)}/connectors/${enc(appId)}/actions`);
+    }
+    integrations.listConnectorActions = listConnectorActions;
+    /**
+     * PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member.
+     * 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one;
+     * 400 with `missing[]` when a required input is absent.
+     * POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+     */
+    async function callConnectorAction(collectionId, appId, action, input = {}) {
+        return post(`/public/collection/${enc(collectionId)}/connectors/${enc(appId)}/actions/${enc(action)}`, { input });
+    }
+    integrations.callConnectorAction = callConnectorAction;
 })(integrations || (integrations = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.14  |  Generated: 2026-11-09T13:01:05.900Z
+Version: 2.1.16  |  Generated: 2026-11-10T17:19:48.505Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,7 +65,7 @@ For detailed guides on specific features:
 - **[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), 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
+- **[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; actions (provider operations on demand); 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
@@ -3112,6 +3112,19 @@ interface ConnectorPanel {
 }
 ```
 
+**ConnectorAction** (interface)
+```typescript
+interface ConnectorAction {
+  name: string
+  title?: string
+  description?: string
+  function: string
+  visibility?: 'admin' | 'member' | 'public'
+  input?: Record<string, unknown>
+  output?: Record<string, unknown>
+}
+```
+
 **AppConnectorDeclaration** (interface)
 ```typescript
 interface AppConnectorDeclaration {
@@ -3134,6 +3147,7 @@ interface AppConnectorDeclaration {
   lookup?: string
   }
   panels?: ConnectorPanel[]
+  actions?: ConnectorAction[]
   aiGuide?: string
   recordId?: string
   limits?: { requestsPerSecond?: number; maxEvents?: number; maxAttributes?: number }
@@ -5761,10 +5775,11 @@ interface ClaimSetRange {
   id: string
   claimSetId: string
   namespace: string
+  kind: ClaimSetRangeKind
   name: string
   notes: string | null
-  startIndex: number
-  endIndex: number
+  startIndex: number | null
+  endIndex: number | null
   quantity: number
   tagType: ClaimSetTagType
   fulfilment: 'printer' | 'sidekick'
@@ -5787,8 +5802,9 @@ interface ClaimSetRange {
 **CreateClaimSetRangeRequest** (interface)
 ```typescript
 interface CreateClaimSetRangeRequest {
+  kind?: ClaimSetRangeKind
   name: string
-  quantity: number
+  quantity?: number
   intendedCollectionId?: string
   intendedProductId?: string
   intendedBatchId?: string
@@ -5823,6 +5839,8 @@ interface ClaimSetRangeTag {
   productId: string | null
   batchId: string | null
   proofId: string | null
+  rangeId: string | null
+  groupId: string | null
   programmedAt: string | null
   scans: number
 }
@@ -5836,6 +5854,29 @@ interface ClaimSetRangeTagsPage {
 }
 ```
 
+**AddClaimSetRangeMemberRequest** (interface)
+```typescript
+interface AddClaimSetRangeMemberRequest {
+  code?: string
+  uid?: string
+  collectionId?: string
+  productId?: string
+  batchId?: string
+  data?: Record<string, unknown>
+  clear?: boolean
+}
+```
+
+**AddClaimSetRangeMemberResponse** (interface)
+```typescript
+interface AddClaimSetRangeMemberResponse {
+  tag: ClaimSetRangeTag
+  range: ClaimSetRange
+  assigned: { changed: number; skipped: Array<{ code: string; index: number | null; reason: 'other_range' | 'has_proof' | 'assigned_elsewhere'; collectionId?: string }> }
+  movedFrom: string | null
+}
+```
+
 **ImportClaimSetRangeUidsRequest** (interface)
 ```typescript
 interface ImportClaimSetRangeUidsRequest {
@@ -5944,7 +5985,11 @@ type ClaimSetScope = { collectionId: string }
 
 **ClaimSetTagType** = `'ntag424' | 'ntag21x' | 'qr'`
 
-**ClaimSetRangeStatus** = `'minting' | 'minted' | 'sent' | 'received' | 'assigned'`
+**ClaimSetRangeKind** = `'range' | 'open' | 'group'`
+
+**ClaimSetRangeStatus** = `'minting' | 'minted' | 'sent' | 'received' | 'assigned' | 'open' | 'group'`
+
+**CloseClaimSetRangeResponse** = `ClaimSetRange | { id: string`
 
 **ClaimSetImportResult** = ``
 
@@ -7980,6 +8025,7 @@ interface IntegrationFlowConfig {
   signing?: { credentialRef: string; previousCredentialRef?: string }
   identity?: { policy?: IdentityPolicy; hashKeyCredentialRef?: string }
   eventMapping?: EventMapping
+  envelopeFormat?: 'cloudevents'
   connection?: FlowConnection
   fieldMappings?: FieldMapping[]
   connector?: FlowConnectorRef
@@ -8222,6 +8268,7 @@ interface ConnectorLookupResult {
 **EventEnvelope** (interface)
 ```typescript
 interface EventEnvelope {
+  specVersion: number
   id: string
   type: string
   entityType: string | null
@@ -8234,6 +8281,8 @@ interface EventEnvelope {
   contactId: string | null
   userId: string | null
   externalIds: Record<string, string>
+  anonymousId: string | null
+  sessionId: string | null
   emailHash?: string | null
   phoneHash?: string | null
   hashAlgorithm?: 'hmac-sha256' | null
@@ -8243,6 +8292,7 @@ interface EventEnvelope {
   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
+  consent: { channels: Record<'email' | 'sms' | 'push' | 'whatsapp', 'opted_in' | 'opted_out' | 'suppressed' | 'unknown'>; topics: Record<string, boolean>; updatedAt: string | null } | null
   subject: Record<string, unknown>
   event?: { name: string; attributes: Record<string, unknown>; rule: string | null }
   attributes: Record<string, unknown>
@@ -12445,6 +12495,15 @@ Name, notes, order details, or a stage move (sent to the printer, received).
 **resume**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<ClaimSetRange>`
 Finish minting a range that was interrupted.
 
+**close**(scope: ClaimSetScope, claimSetId: string, rangeId: string) → `Promise<CloseClaimSetRangeResponse>`
+Close an open range: it becomes a range with the quantity it reached (removed if nothing was minted).
+
+**addMember**(scope: ClaimSetScope, claimSetId: string, groupId: string, params: AddClaimSetRangeMemberRequest) → `Promise<AddClaimSetRangeMemberResponse>`
+Put an existing tag of the set into a group (by code or chip UID), assigning it if a collection is given.
+
+**removeMember**(scope: ClaimSetScope, claimSetId: string, groupId: string, code: string) → `Promise<`
+Take a tag out of a group. Its assignment is left as it is.
+
 **tags**(scope: ClaimSetScope, claimSetId: string, rangeId: string,
       options: { from?: number; limit?: number; keys?: boolean } = {}) → `Promise<ClaimSetRangeTagsPage>`
 The range's tags in index order, a page at a time (keys: owners/admins only).
@@ -12984,6 +13043,22 @@ Save a connector's non-secret Connect-form values and/or settings. PUT /integrat
     input: Record<string, unknown> & { flowId?: string } = {}) → `Promise<T>`
 Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, and dry runs of `shape` ({ records }) → ConnectorShapeResult and `serialize` ({ documents }) → ConnectorSerializeResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
 
+**runConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+Invoke a connector ACTION from the console (any visibility): redeem, enrol, adjust points, issue a coupon… The connector's function runs with its own credentials and is told who asked. POST /integrations/connectors/:appId/actions/:action { input }
+
+**listConnectorActions**(collectionId: string,
+    appId: string) → `Promise<`
+PUBLIC (the Hub, a site): the connector actions the caller may invoke — those declared `public`, plus `member` ones when signed in. GET /public/collection/:collectionId/connectors/:appId/actions
+
+**callConnectorAction**(collectionId: string,
+    appId: string,
+    action: string,
+    input: Record<string, unknown> = {}) → `Promise<T>`
+PUBLIC (the Hub, a site): invoke a connector action — e.g. redeem a reward for the signed-in member. 401 SIGN_IN_REQUIRED for a `member` action without a session; 403 for an admin-only one; 400 with `missing[]` when a required input is absent. POST /public/collection/:collectionId/connectors/:appId/actions/:action { input }
+
 ### interactions
 
 **query**(collectionId: string,

package/dist/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/dist/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/dist/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/dist/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