@proveanything/smartlinks 2.1.15 → 2.1.17

package/docs/server-functions.md

@@ -514,6 +514,10 @@ Prefer the platform primitives above over a dependency; when you do need one, pi
 | Read ANOTHER app's data (as the caller may see it) | `ctx.sl.app('other-app').data.get()` — caller-authority, this collection, public-filtered, read-only | `sl:data:read` |
 | Guarantee a UNIQUE claim (one entry per tag, one-per-user, idempotency key, a number nobody else holds) | `ctx.sl.appRecords.claim({ …, singletonPer, customId })` → `{ record, created, conflict? }` — see below | `sl:records:write` |
 | Hand out the next number (tickets, order numbers) | `ctx.sl.counters.next('tickets')` — atomic, distinct per caller | `sl:data:write` |
+| Change numbers in a record (stock, counts, balances) without losing updates | `ctx.sl.appRecords.adjust(id, { qty: -5 }, { atLeast: { qty: 0 } })` — in place, conditions checked after the change | `sl:records:write` |
+| Several record writes that land together or not at all (a stock move) | `ctx.sl.transaction([ops], { idempotencyKey })` — see below | `sl:records:write` |
+| Totals: stock per location, forecast per SKU | `ctx.sl.appRecords.aggregate({ groupBy: ['data.location'], metrics: ['sum:qty'] })` | `sl:records:read` |
+| Keep a history of what happened (stock moves, counts) without growing your records | `ctx.sl.history.log('stock.moved', {…})`, or a `log` op in a transaction; read with `ctx.sl.history.query({…})` | `sl:history:write` / `sl:history:read` |
 | 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` |
@@ -579,6 +583,90 @@ reads the last value handed out (`null` before the first). Name a new counter to
 `customId: String(n)`. If the claim says `conflict: 'customId'`, take `next()` again. A failed or raced
 attempt only leaves a gap — never a duplicate.
 
+### `appRecords.adjust(id, by, { atLeast?, atMost? })` — numbers that never lose an update
+
+Adds to numbers in a record's `data` in ONE statement, so twenty scanners taking from the same bin at
+once each land: no read-then-write, no lost counts. A missing value counts as 0. `atLeast` / `atMost` are
+checked on the values **after** the change, inside the same statement:
+
+```ts
+// Take 5 from bin A — refused (nothing changes) if it would go below zero.
+await ctx.sl.appRecords.adjust(binA, { qty: -5 }, { atLeast: { qty: 0 } })
+```
+
+Refusals carry `code`: `NOT_FOUND` (not this app's record in this collection, or deleted), `NOT_A_NUMBER`
+(the key holds something else), `CONDITION_FAILED` (409, with the `current` values). Only top-level data
+keys; a key named only in a condition is checked as it stands.
+
+### `transaction(ops, { idempotencyKey? })` — all or nothing
+
+Several writes as ONE transaction: every op lands, or none does. The classic: take stock out of bin A,
+put it on order line B, and log the move.
+
+```ts
+const { results, replayed } = await ctx.sl.transaction([
+  { op: 'adjust', recordId: binA, by: { qty: -5 }, atLeast: { qty: 0 } },
+  { op: 'adjust', recordId: orderLineB, by: { picked: 5 } },
+  { op: 'create', record: { recordType: 'movement', data: { from: binA, to: orderLineB, qty: 5 } } },
+], { idempotencyKey: scanId })
+```
+
+- Ops: `create` (`record`), `update` (`recordId`, `fields`), `adjust` (`recordId`, `by`, `atLeast?`,
+  `atMost?`), `delete` (`recordId`), `log` (`type`, `data`, `entityId?`: a history event, see below).
+  Up to 50, run in order. This app's records in this collection only.
+- A failing op rolls everything back. The error says which op (`opIndex`) and why (its `code`).
+- Change events and realtime updates go out only after the transaction commits, never for a rollback.
+- **`idempotencyKey`** ("this was already done"): recorded in the same commit, with what was written
+  (ids only). The same key again within 7 days doesn't write; it returns those records as they are now,
+  with `replayed: true`. So a handheld that retries after a dropped signal never moves stock twice. Two
+  calls with one key at the same moment: one commits, the other replays it. A transaction that failed
+  leaves its key free, so a retry can still succeed.
+- Use the scan's or the request's own id as the key (one key = one intended change).
+- Browser code never writes stock directly: a warehouse screen calls your function.
+
+### `history` — what happened, kept without growing your records
+
+Keep **current state** in records (a bin's quantity, an order's status) and **what happened** in the app's
+history: append-only events in SmartLinks' analytics store, kept for good, cheap however many there
+are. Picking every order line for years would bloat records; as history it costs nothing operational.
+
+```ts
+// In a transaction: commits with the stock change, or not at all.
+await ctx.sl.transaction([
+  { op: 'adjust', recordId: binA, by: { qty: -5 }, atLeast: { qty: 0 } },
+  { op: 'log', type: 'stock.moved', entityId: binA, data: { sku: 'EDP-50', from: 'A1', to: orderId, qty: 5 } },
+], { idempotencyKey: scanId })
+
+// On its own:
+await ctx.sl.history.log('count.taken', { bin: 'A1', counted: 40, expected: 42 }, { entityId: binA })
+
+// Reading back: this app's events in this collection, newest first (default last 30 days, max 400).
+const moves = await ctx.sl.history.query({ types: 'stock.moved', entityId: binA, limit: 20 })
+// → [{ id, at, type, entityId, data, actorType, actorId }]
+```
+
+- `type`: lowercase letters, digits and `. _ -` (`stock.moved`). `data`: up to 32 KB, so **log a summary**:
+  one line for "5 of EDP-50", not five; one line for an RFID count, not one per tag.
+- Delivery takes seconds and is retried until it lands; a logged event is never lost. A query reads the
+  analytics store, so expect about a second: right for a history panel, not for a hot path.
+- The person who called your function is recorded as the actor.
+
+### `appRecords.aggregate(params)` — totals
+
+Counts and sums over your app's records, worked out in the database:
+
+```ts
+await ctx.sl.appRecords.aggregate({
+  groupBy: ['data.location', 'data.sku'],          // columns, or top-level data keys
+  metrics: ['count', 'sum:qty'],                   // sum: / avg: / min: / max: over data numbers
+  filters: { record_type: 'bin', data: { warehouse: 'north' }, dataRange: { qty: { gt: 0 } } },
+})
+// → { groups: [{ 'data.location': 'A1', 'data.sku': 'EDP-50', count: 3, sum_qty: 42 }, …] }
+```
+
+Non-numbers are ignored by `sum`/`avg`/`min`/`max`. The same request works from the browser through
+`app.records.aggregate` (admin) — see [app-objects.md](app-objects.md).
+
 ### `tags.resolve(id)` — is this tap real?
 
 A tap hands your app the virtual-proof id `<claimSetId>-<code>`. `resolve` returns

package/docs/tag-ranges.md

@@ -55,6 +55,35 @@ 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).
+
+## When a tag fails on the phone
+
+`errors.report({ app: 'sidekick', operation: 'tag.program', errorCode: 'TAG_LOST', message, entityType: 'tag',
+entityId: chipUid, labels: { claimSetId, code, failedStep }, context: { steps, timings, hostLog } })` keeps what
+the phone saw in the platform's one error log (never a key: fields that look like one are dropped).
+`partner.tagAttempts(partner.id, chipUid)` and the platform's tag lookup read it back, newest first, so a
+failing chip can be understood by its UID without the phone's console.
+
 ## 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

@@ -9141,6 +9141,35 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/partner/{partnerId}/tags/attempts:
+    get:
+      tags:
+        - partner
+      summary: "What phones reported about one chip (errors.report with entityType 'tag'), newest first: a tag that failed to program or register, with the host's NFC log in context."
+      operationId: partner_tagAttempts
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: partnerId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ClientErrorEvent"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/partner/{partnerId}/tags/lookup:
     get:
       tags:
@@ -14952,6 +14981,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 +15102,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:
@@ -20764,6 +20857,56 @@ components:
       required:
         - slots
         - blocks
+    AppHistoryEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        at:
+          type: string
+        type:
+          type: string
+        entityId:
+          type: string
+        data:
+          type: object
+          additionalProperties: true
+        actorType:
+          type: string
+          enum:
+            - user
+            - contact
+        actorId:
+          type: string
+      required:
+        - id
+        - at
+        - type
+        - entityId
+        - data
+        - actorType
+        - actorId
+    AppHistoryQuery:
+      type: object
+      properties:
+        types:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        entityId:
+          type: string
+        data:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+        from:
+          type: string
+        to:
+          type: string
+        limit:
+          type: number
     ServerFunctionSl:
       type: object
       properties:
@@ -20772,6 +20915,9 @@ components:
         appRecords:
           type: object
           additionalProperties: true
+        history:
+          type: object
+          additionalProperties: true
         counters:
           $ref: "#/components/schemas/ServerFunctionCounters"
         tags:
@@ -20793,6 +20939,7 @@ components:
       required:
         - bookings
         - appRecords
+        - history
         - counters
         - tags
         - contacts
@@ -21568,6 +21715,9 @@ components:
       enum:
         - caller
         - collection
+    RecordTransactionOp:
+      type: object
+      additionalProperties: true
     PaginatedResponse:
       type: object
       properties:
@@ -21617,6 +21767,19 @@ components:
         expires_at:
           type: object
           additionalProperties: true
+        updated_at:
+          type: object
+          additionalProperties: true
+        data:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
+        dataRange:
+          type: object
+          additionalProperties:
+            type: object
+            additionalProperties: true
         groupBy:
           type: array
           items:
@@ -25919,6 +26082,8 @@ components:
           type: string
         namespace:
           type: string
+        kind:
+          $ref: "#/components/schemas/ClaimSetRangeKind"
         name:
           type: string
         notes:
@@ -25972,6 +26137,7 @@ components:
         - id
         - claimSetId
         - namespace
+        - kind
         - name
         - notes
         - startIndex
@@ -25995,6 +26161,8 @@ components:
     CreateClaimSetRangeRequest:
       type: object
       properties:
+        kind:
+          $ref: "#/components/schemas/ClaimSetRangeKind"
         name:
           type: string
         quantity:
@@ -26018,7 +26186,6 @@ components:
           type: string
       required:
         - name
-        - quantity
     UpdateClaimSetRangeRequest:
       type: object
       properties:
@@ -26062,6 +26229,10 @@ components:
           type: string
         proofId:
           type: string
+        rangeId:
+          type: string
+        groupId:
+          type: string
         programmedAt:
           type: string
         scans:
@@ -26075,6 +26246,8 @@ components:
         - productId
         - batchId
         - proofId
+        - rangeId
+        - groupId
         - programmedAt
         - scans
     ClaimSetRangeTagsPage:
@@ -26103,6 +26276,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:
@@ -26272,12 +26480,15 @@ components:
           $ref: "#/components/schemas/ClaimSetRangeTag"
         range:
           $ref: "#/components/schemas/ClaimSetRange"
+        group:
+          $ref: "#/components/schemas/ClaimSetRange"
       required:
         - namespace
         - claimSetId
         - set
         - tag
         - range
+        - group
     CreatePartnerClaimSetRequest:
       type: object
       properties:
@@ -26303,6 +26514,12 @@ components:
         - ntag424
         - ntag21x
         - qr
+    ClaimSetRangeKind:
+      type: string
+      enum:
+        - range
+        - open
+        - group
     ClaimSetRangeStatus:
       type: string
       enum:
@@ -26311,6 +26528,11 @@ components:
         - sent
         - received
         - assigned
+        - open
+        - group
+    CloseClaimSetRangeResponse:
+      type: object
+      additionalProperties: true
     ClaimSetImportResult:
       type: string
       enum:
@@ -26324,6 +26546,92 @@ components:
         - duplicate_uid
         - uid_in_use
         - uid_conflict
+    ClientErrorReport:
+      type: object
+      properties:
+        app:
+          type: string
+        appVersion:
+          type: string
+        collectionId:
+          type: string
+        operation:
+          type: string
+        severity:
+          type: string
+          enum:
+            - debug
+            - info
+            - warning
+            - error
+            - critical
+        errorCode:
+          type: string
+        errorType:
+          type: string
+        message:
+          type: string
+        stack:
+          type: string
+        entityType:
+          type: string
+        entityId:
+          type: string
+        labels:
+          type: object
+          additionalProperties: true
+        context:
+          type: object
+          additionalProperties: true
+        refId:
+          type: string
+        correlationId:
+          type: string
+    ClientErrorEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        time:
+          type: string
+        event_category:
+          type: string
+        event_action:
+          type: string
+        log_level:
+          type: string
+        error_code:
+          type: string
+        error_message:
+          type: string
+        service_name:
+          type: string
+        service_version:
+          type: string
+        collection_id:
+          type: string
+        user_id:
+          type: string
+        labels:
+          type: object
+          additionalProperties: true
+        context:
+          type: object
+          additionalProperties: true
+      required:
+        - id
+        - time
+        - event_category
+        - event_action
+        - log_level
+        - error_code
+        - error_message
+        - service_name
+        - service_version
+        - collection_id
+        - user_id
+        - labels
+        - context
     Collection:
       type: object
       properties:

package/package.json

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