@proveanything/smartlinks 2.1.15 → 2.1.17

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/errors.d.ts

@@ -0,0 +1,10 @@
+import { ClientErrorReport } from "../types/index.js";
+/**
+ * Report an error an app saw, into the platform's one error log (the same BigQuery error-events table the
+ * server writes to). Best effort: never throws into the flow that failed.
+ */
+export declare namespace errors {
+    function report(event: ClientErrorReport): Promise<{
+        kept: boolean;
+    }>;
+}

package/dist/api/errors.js

@@ -0,0 +1,17 @@
+import { post } from "../http.js";
+/**
+ * Report an error an app saw, into the platform's one error log (the same BigQuery error-events table the
+ * server writes to). Best effort: never throws into the flow that failed.
+ */
+export var errors;
+(function (errors) {
+    async function report(event) {
+        try {
+            return await post(`/admin/log/error`, event);
+        }
+        catch (_a) {
+            return { kept: false };
+        }
+    }
+    errors.report = report;
+})(errors || (errors = {}));

package/dist/api/index.d.ts

@@ -11,6 +11,7 @@ export { form } from "./form.js";
 export { authKit } from "./authKit.js";
 export { claimSet } from "./claimSet.js";
 export { partner } from "./partner.js";
+export { errors } from "./errors.js";
 export { crate } from "./crate.js";
 export { batch } from "./batch.js";
 export { variant } from "./variant.js";

package/dist/api/index.js

@@ -13,6 +13,7 @@ export { form } from "./form.js";
 export { authKit } from "./authKit.js";
 export { claimSet } from "./claimSet.js";
 export { partner } from "./partner.js";
+export { errors } from "./errors.js";
 export { crate } from "./crate.js";
 export { batch } from "./batch.js";
 export { variant } from "./variant.js";

package/dist/api/partner.d.ts

@@ -1,4 +1,4 @@
-import { Partner, PartnerClaimSet, CreatePartnerClaimSetRequest, PartnerTagHit } from "../types/index.js";
+import { Partner, PartnerClaimSet, CreatePartnerClaimSetRequest, PartnerTagHit, ClientErrorEvent } from "../types/index.js";
 /**
  * Partners: organisations above collections (FanConnect, Zenith Coins, …) that own NFC claim sets and
  * assign their tags into collections their people administer. Partners and their members are set up by
@@ -21,4 +21,10 @@ export declare namespace partner {
         uid?: string;
         code?: string;
     }): Promise<PartnerTagHit[]>;
+    /**
+     * 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. For a chip in the partner's sets,
+     * or attempts that named one of them.
+     */
+    function tagAttempts(partnerId: string, uid: string): Promise<ClientErrorEvent[]>;
 }

package/dist/api/partner.js

@@ -42,4 +42,13 @@ export var partner;
         return request(`/admin/partner/${encodeURIComponent(partnerId)}/tags/lookup?${q}`);
     }
     partner.lookupTags = lookupTags;
+    /**
+     * 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. For a chip in the partner's sets,
+     * or attempts that named one of them.
+     */
+    async function tagAttempts(partnerId, uid) {
+        return request(`/admin/partner/${encodeURIComponent(partnerId)}/tags/attempts?uid=${encodeURIComponent(uid)}`);
+    }
+    partner.tagAttempts = tagAttempts;
 })(partner || (partner = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.15  |  Generated: 2026-11-09T15:17:42.472Z
+Version: 2.1.17  |  Generated: 2026-11-11T09:04:21.796Z
 
 This is a concise summary of all available API functions and types.
 
@@ -144,6 +144,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **bookings** - Functions for bookings operations
 - **config** - Functions for config operations
 - **containers** - Functions for containers operations
+- **errors** - Functions for errors operations
 - **facets** - Functions for facets operations
 - **functions** - Functions for functions operations
 - **http** - Functions for http operations
@@ -2838,11 +2839,46 @@ interface ServerFunctionBookings {
 }
 ```
 
+**AppHistoryEvent** (interface)
+```typescript
+interface AppHistoryEvent {
+  id: string;
+  at: string;
+  type: string;
+  entityId: string | null;
+  data: Record<string, any>;
+  actorType: 'user' | 'contact' | null;
+  actorId: string | null;
+}
+```
+
+**AppHistoryQuery** (interface)
+```typescript
+interface AppHistoryQuery {
+  types?: string | string[];
+  entityId?: string;
+  data?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+  from?: string;
+  to?: string;
+  limit?: number;
+}
+```
+
 **ServerFunctionSl** (interface)
 ```typescript
 interface ServerFunctionSl {
   bookings: ServerFunctionBookings;
-  appRecords: { claim(fields: Record<string, any>): Promise<AppRecordClaimResult>; [method: string]: any };
+  appRecords: {
+  claim(fields: Record<string, any>): Promise<AppRecordClaimResult>;
+  adjust(recordId: string, by: Record<string, number>, opts?: { atLeast?: Record<string, number>; atMost?: Record<string, number> }): Promise<any>;
+  aggregate(params?: import('./appObjects').AggregateRequest): Promise<import('./appObjects').AggregateResponse & Record<string, unknown>>;
+  [method: string]: any;
+  };
+  transaction(ops: RecordTransactionOp[], opts?: { idempotencyKey?: string }): Promise<{ results: any[]; replayed: boolean }>;
+  history: {
+  log(type: string, data?: Record<string, any>, opts?: { entityId?: string }): Promise<{ id: string }>;
+  query(params?: AppHistoryQuery): Promise<AppHistoryEvent[]>;
+  };
   counters: ServerFunctionCounters;
   tags: { resolve(id: string): Promise<ResolvedTag | null> };
   contacts: {
@@ -3298,6 +3334,8 @@ interface GetCollectionWidgetsOptions {
 
 **AppFunctionAuthority** = `'caller' | 'collection'`
 
+**RecordTransactionOp** = ``
+
 ### appObjects
 
 **PaginatedResponse<T>** (interface)
@@ -3324,9 +3362,12 @@ interface AggregateRequest {
   created_at?: { gte?: string; lte?: string }
   closed_at?: '__notnull__' | { gte?: string; lte?: string } // cases only
   expires_at?: { lte?: string } // records only
+  updated_at?: { gte?: string; lte?: string } // records only
+  data?: Record<string, string | number | boolean | Array<string | number | boolean>>
+  dataRange?: Record<string, { gte?: number; gt?: number; lte?: number; lt?: number }>
   }
-  groupBy?: string[] // see per-resource allowed values
-  metrics?: string[] // see per-resource allowed values below
+  groupBy?: string[]
+  metrics?: string[]
   timeSeriesField?: string // e.g. 'created_at'
   timeSeriesInterval?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
 }
@@ -3335,7 +3376,7 @@ interface AggregateRequest {
 **AggregateResponse** (interface)
 ```typescript
 interface AggregateResponse {
-  groups?: ({ count: number } & Record<string, unknown>)[]
+  groups?: ({ count?: number } & Record<string, unknown>)[]
   timeSeries?: ({ bucket: string; count: number } & Record<string, unknown>)[]
   count?: number
   avg_close_time_seconds?: number
@@ -5775,10 +5816,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'
@@ -5801,8 +5843,9 @@ interface ClaimSetRange {
 **CreateClaimSetRangeRequest** (interface)
 ```typescript
 interface CreateClaimSetRangeRequest {
+  kind?: ClaimSetRangeKind
   name: string
-  quantity: number
+  quantity?: number
   intendedCollectionId?: string
   intendedProductId?: string
   intendedBatchId?: string
@@ -5837,6 +5880,8 @@ interface ClaimSetRangeTag {
   productId: string | null
   batchId: string | null
   proofId: string | null
+  rangeId: string | null
+  groupId: string | null
   programmedAt: string | null
   scans: number
 }
@@ -5850,6 +5895,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 {
@@ -5939,6 +6007,7 @@ interface PartnerTagHit {
   set: PartnerClaimSet | null
   tag: ClaimSetRangeTag & { url: string | null }
   range: ClaimSetRange | null
+  group: ClaimSetRange | null
 }
 ```
 
@@ -5958,10 +6027,56 @@ 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** = ``
 
+### clientLog
+
+**ClientErrorReport** (interface)
+```typescript
+interface ClientErrorReport {
+  app?: string
+  appVersion?: string
+  collectionId?: string
+  operation?: string
+  severity?: 'debug' | 'info' | 'warning' | 'error' | 'critical'
+  errorCode?: string
+  errorType?: string
+  message?: string
+  stack?: string
+  entityType?: string
+  entityId?: string
+  labels?: Record<string, unknown>
+  context?: Record<string, unknown>
+  refId?: string
+  correlationId?: string
+}
+```
+
+**ClientErrorEvent** (interface)
+```typescript
+interface ClientErrorEvent {
+  id: string
+  time: string
+  event_category: string
+  event_action: string | null
+  log_level: string
+  error_code: string | null
+  error_message: string | null
+  service_name: string | null
+  service_version: string | null
+  collection_id: string | null
+  user_id: string | null
+  labels: Record<string, unknown> | null
+  context: Record<string, unknown> | null
+}
+```
+
 ### collection
 
 **Collection** (interface)
@@ -12464,6 +12579,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).
@@ -12790,6 +12914,10 @@ Update a crate for a collection (admin only). ```typescript const updated = awai
     crateId: string) → `Promise<DeleteCrateResponse>`
 Delete a crate for a collection (admin only). This performs a soft delete. ```typescript await crate.remove('coll_123', 'crate_abc123') ```
 
+### errors
+
+**report**(event: ClientErrorReport) → `Promise<`
+
 ### facets
 
 **list**(collectionId: string,
@@ -13422,6 +13550,9 @@ A new claim set for the partner, on one of its tap domains (owners and admins).
 **lookupTags**(partnerId: string, query: { uid?: string; code?: string }) → `Promise<PartnerTagHit[]>`
 Find a tag across the partner's sets by its chip UID (8 or 14 hex) or its code (printed or bare). Never returns keys.
 
+**tagAttempts**(partnerId: string, uid: string) → `Promise<ClientErrorEvent[]>`
+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. For a chip in the partner's sets, or attempts that named one of them.
+
 ### podcast
 
 **generate**(collectionId: string,

package/dist/docs/app-objects.md

@@ -807,6 +807,29 @@ await app.records.upsert(collectionId, appId, {
 // customId is stored for later reverse-lookup via ?customId=&sourceSystem=
 ```
 
+### Totals over data (sum, average, min, max)
+
+Records also total the numbers in their `data`, grouped by top-level data keys, with data filters and
+numeric ranges. Stock per location, forecast per SKU:
+
+```typescript
+const stock = await app.records.aggregate(collectionId, appId, {
+  groupBy: ['data.location'],                       // up to 5: columns or 'data.<key>'
+  metrics: ['count', 'sum:qty', 'min:qty'],         // count; sum: / avg: / min: / max: + a data key
+  filters: {
+    record_type: 'bin',
+    data: { warehouse: ['north', 'south'] },        // exact match, one value or any of several
+    dataRange: { qty: { gt: 0 } },                  // gte / gt / lte / lt, numbers only
+    updated_at: { gte: '2026-11-01T00:00:00Z' },
+  },
+}, true)
+// stock.groups → [{ 'data.location': 'A1', count: 12, sum_qty: 340, min_qty: 2 }, …]
+```
+
+Values that aren't numbers are left out of sums and averages. To CHANGE numbers safely (stock moves,
+counts), use a server function: `ctx.sl.appRecords.adjust` and `ctx.sl.transaction`
+([server-functions.md](server-functions.md)).
+
 ### Counts by Record Type
 
 `aggregate()` returns counts grouped by `record_type` in a single round-trip — no separate endpoint needed:

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