@proveanything/smartlinks 2.1.16 → 2.1.17

package/dist/testing/index.js

@@ -77,7 +77,7 @@ function allowsSl(p, resource, op) {
 }
 /** A fresh in-memory store — pass the same one to several test contexts to simulate concurrent callers. */
 export function createFunctionTestMemory() {
-    return { records: [], counters: {}, contacts: [], interactions: [], bookings: createBookingsMemory() };
+    return { records: [], counters: {}, contacts: [], interactions: [], bookings: createBookingsMemory(), transactions: {}, history: [] };
 }
 const stub = (method, args) => ({ __stub: true, method, args });
 /**
@@ -101,6 +101,9 @@ export function createFunctionTestContext(opts) {
         return fn ? fn(...args) : stub(`${resource}.${name}`, args);
     };
     const mem = opts.memory || createFunctionTestMemory();
+    // A memory built before history / transactions existed still works.
+    mem.history = mem.history || [];
+    mem.transactions = mem.transactions || {};
     const ar = impl.appRecords || {};
     const pr = impl.products || {};
     const at = impl.attestations || {};
@@ -147,6 +150,60 @@ export function createFunctionTestContext(opts) {
             return null; Object.assign(r, fields); return Object.assign({}, r); },
         delete: async (id) => { const r = mem.records.find((x) => x.id === id); if (r)
             r.deletedAt = new Date().toISOString(); return {}; },
+        // Numbers in data changed in place, with atLeast / atMost checked after the change (as the platform).
+        adjust: async (id, by = {}, opts = {}) => {
+            var _a, _b;
+            const r = mem.records.find((x) => x.id === id && !x.deletedAt);
+            if (!r)
+                throw Object.assign(new Error('Record not found'), { code: 'NOT_FOUND', statusCode: 404 });
+            const data = r.data || {};
+            const keys = [...new Set([...Object.keys(by), ...Object.keys(opts.atLeast || {}), ...Object.keys(opts.atMost || {})])];
+            const bad = keys.find((k) => data[k] != null && typeof data[k] !== 'number');
+            if (bad)
+                throw Object.assign(new Error(`data.${bad} isn't a number, so it can't be adjusted`), { code: 'NOT_A_NUMBER', statusCode: 400, key: bad });
+            const next = {};
+            for (const k of keys)
+                next[k] = ((_a = data[k]) !== null && _a !== void 0 ? _a : 0) + ((_b = by[k]) !== null && _b !== void 0 ? _b : 0);
+            const broken = Object.entries(opts.atLeast || {}).some(([k, n]) => next[k] < n) || Object.entries(opts.atMost || {}).some(([k, n]) => next[k] > n);
+            if (broken)
+                throw Object.assign(new Error('The change would break its condition (atLeast / atMost)'), { code: 'CONDITION_FAILED', statusCode: 409, current: Object.fromEntries(keys.map((k) => { var _a; return [k, (_a = data[k]) !== null && _a !== void 0 ? _a : 0]; })) });
+            r.data = Object.assign(Object.assign({}, data), Object.fromEntries(Object.keys(by).map((k) => [k, next[k]])));
+            return Object.assign({}, r);
+        },
+        // count / sum: / avg: / min: / max: over data numbers, grouped by top-level fields or data keys
+        // ('data.location'); filters.data (exact) as the platform. A simple stand-in for tests.
+        aggregate: async (params = {}) => {
+            const { groupBy = [], metrics = ['count'], filters = {} } = params || {};
+            const rows = mem.records.filter((r) => !r.deletedAt &&
+                (!filters.record_type || r.recordType === filters.record_type) &&
+                (!filters.status || r.status === filters.status) &&
+                Object.entries(filters.data || {}).every(([k, v]) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String((r.data || {})[k]))));
+            const field = (r, f) => (f.startsWith('data.') ? (r.data || {})[f.slice(5)] : r[f === 'record_type' ? 'recordType' : f]);
+            const measure = (set) => {
+                const out = {};
+                for (const m of metrics) {
+                    if (m === 'count') {
+                        out.count = set.length;
+                        continue;
+                    }
+                    const [fn, key] = String(m).split(':');
+                    const nums = set.map((r) => (r.data || {})[key]).filter((v) => typeof v === 'number');
+                    const sum = nums.reduce((a, b) => a + b, 0);
+                    out[`${fn}_${key}`] = !nums.length ? null : fn === 'sum' ? sum : fn === 'avg' ? sum / nums.length : fn === 'min' ? Math.min(...nums) : Math.max(...nums);
+                }
+                return out;
+            };
+            if (!groupBy.length)
+                return measure(rows);
+            const buckets = new Map();
+            for (const r of rows) {
+                const key = JSON.stringify(groupBy.map((f) => { var _a; return (_a = field(r, f)) !== null && _a !== void 0 ? _a : null; }));
+                if (!buckets.has(key))
+                    buckets.set(key, []);
+                buckets.get(key).push(r);
+            }
+            return { groups: [...buckets].map(([key, set]) => (Object.assign(Object.assign({}, Object.fromEntries(groupBy.map((f, i) => [f, JSON.parse(key)[i]]))), measure(set)))) };
+        },
         // Simple equality filter on top-level fields (recordType, proofId, customId, status, …).
         query: async (params = {}) => {
             const _a = params || {}, { limit, offset, sort } = _a, where = __rest(_a, ["limit", "offset", "sort"]);
@@ -158,6 +215,60 @@ export function createFunctionTestContext(opts) {
             return { data, pagination: { total: all.length, limit: size, offset: from, hasMore: from + data.length < all.length } };
         },
     };
+    // The app's history, in memory (newest first when read, like the platform).
+    let nextEventId = 1;
+    const memLog = (type, data = {}, opts = {}) => {
+        var _a;
+        if (typeof type !== 'string' || !/^[a-z][a-z0-9._-]{0,63}$/.test(type))
+            throw Object.assign(new Error('history type: lowercase letters, digits and . _ - (e.g. "stock.moved")'), { code: 'INVALID_INPUT', statusCode: 400 });
+        const ev = { id: `ev-${nextEventId++}`, at: new Date().toISOString(), type, entityId: (_a = opts.entityId) !== null && _a !== void 0 ? _a : null, data: data || {}, actorType: null, actorId: null };
+        mem.history.push(ev);
+        return { id: ev.id };
+    };
+    const memHistoryQuery = async (params = {}) => {
+        const types = params.types == null ? null : (Array.isArray(params.types) ? params.types : [params.types]);
+        return mem.history
+            .filter((e) => (!types || types.includes(e.type)) && (params.entityId == null || e.entityId === params.entityId) &&
+            Object.entries(params.data || {}).every(([k, v]) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(e.data[k]))))
+            .slice().reverse().slice(0, params.limit || 100).map((e) => (Object.assign({}, e)));
+    };
+    // All ops or none, like the platform: records are restored when an op fails; a repeat of an
+    // idempotencyKey replays the first results.
+    const memTransaction = async (ops, opts = {}) => {
+        const key = opts.idempotencyKey;
+        if (key && mem.transactions[key])
+            return { results: mem.transactions[key], replayed: true };
+        const before = JSON.parse(JSON.stringify(mem.records));
+        const historyBefore = mem.history.length;
+        const results = [];
+        for (let i = 0; i < ops.length; i++) {
+            const o = ops[i] || {};
+            try {
+                if (o.op === 'create')
+                    results.push(await memRecords.create(o.record || {}));
+                else if (o.op === 'update')
+                    results.push(await memRecords.update(o.recordId, o.fields || {}));
+                else if (o.op === 'adjust')
+                    results.push(await memRecords.adjust(o.recordId, o.by, { atLeast: o.atLeast, atMost: o.atMost }));
+                else if (o.op === 'delete') {
+                    await memRecords.delete(o.recordId);
+                    results.push({ deleted: o.recordId });
+                }
+                else if (o.op === 'log')
+                    results.push({ logged: memLog(o.type, o.data, { entityId: o.entityId }).id });
+                else
+                    throw Object.assign(new Error(`ops[${i}].op must be create, update, adjust, delete or log`), { code: 'INVALID_INPUT', statusCode: 400 });
+            }
+            catch (err) {
+                mem.records.splice(0, mem.records.length, ...before);
+                mem.history.splice(historyBefore);
+                throw Object.assign(err, { opIndex: i });
+            }
+        }
+        if (key)
+            mem.transactions[key] = results;
+        return { results, replayed: false };
+    };
     const recordsFn = (name) => ar[name] ? ar[name].bind(ar) : (impl.appRecords ? undefined : memRecords[name]);
     const sl = {
         appRecords: {
@@ -169,6 +280,17 @@ export function createFunctionTestContext(opts) {
             get: gated('records', 'read', recordsFn('get'), 'get'),
             query: gated('records', 'read', recordsFn('query'), 'query'),
             listTypes: gated('records', 'read', recordsFn('listTypes'), 'listTypes'),
+            adjust: gated('records', 'write', recordsFn('adjust'), 'adjust'),
+            aggregate: gated('records', 'read', recordsFn('aggregate'), 'aggregate'),
+        },
+        transaction: gated('records', 'write', impl.transaction ? impl.transaction : (impl.appRecords ? undefined : async (ops, opts) => {
+            if (Array.isArray(ops) && ops.some((o) => o && o.op === 'log') && !allowsSl(parsed, 'history', 'write'))
+                throw new CapabilityError('sl:history:write');
+            return memTransaction(ops, opts);
+        }), 'transaction'),
+        history: {
+            log: gated('history', 'write', async (type, data, opts) => memLog(type, data, opts), 'log'),
+            query: gated('history', 'read', memHistoryQuery, 'query'),
         },
         products: {
             get: gated('products', 'read', pr.get && pr.get.bind(pr), 'get'),

package/dist/types/appManifest.d.ts

@@ -490,6 +490,53 @@ export interface ServerFunctionBookings {
         }>;
     };
 }
+/** One write in ctx.sl.transaction. */
+export type RecordTransactionOp = {
+    op: 'create';
+    record: Record<string, any>;
+} | {
+    op: 'update';
+    recordId: string;
+    fields: Record<string, any>;
+} | {
+    op: 'adjust';
+    recordId: string;
+    by: Record<string, number>;
+    atLeast?: Record<string, number>;
+    atMost?: Record<string, number>;
+} | {
+    op: 'delete';
+    recordId: string;
+}
+/** An event in the app's history (BigQuery): commits with the other ops, delivered after. Needs sl:history:write. */
+ | {
+    op: 'log';
+    type: string;
+    data?: Record<string, any>;
+    entityId?: string;
+};
+/** One event from an app's history. */
+export interface AppHistoryEvent {
+    id: string;
+    at: string;
+    type: string;
+    entityId: string | null;
+    data: Record<string, any>;
+    actorType: 'user' | 'contact' | null;
+    actorId: string | null;
+}
+/** Reading an app's history: its own events in this collection, newest first. */
+export interface AppHistoryQuery {
+    types?: string | string[];
+    entityId?: string;
+    /** Exact match on top-level data keys (one value or several). */
+    data?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+    /** ISO dates. Default: the last 30 days; at most 400 days. */
+    from?: string;
+    to?: string;
+    /** Default 100, at most 1000. */
+    limit?: number;
+}
 export interface ServerFunctionSl {
     /** THIS app's bookings, slots and blocks (`sl:bookings:read` / `sl:bookings:write`). */
     bookings: ServerFunctionBookings;
@@ -502,8 +549,48 @@ export interface ServerFunctionSl {
      */
     appRecords: {
         claim(fields: Record<string, any>): Promise<AppRecordClaimResult>;
+        /**
+         * Numbers in a record's `data`, changed in place in one statement: two scanners on one bin never lose
+         * a count. `by` `{ qty: -5 }` (missing counts as 0). `atLeast` / `atMost` are checked on the values
+         * AFTER the change: `{ atLeast: { qty: 0 } }` never takes a bin below zero. Refusals carry `code`:
+         * `NOT_FOUND`, `NOT_A_NUMBER`, `CONDITION_FAILED` (with `current` values). → the updated record.
+         */
+        adjust(recordId: string, by: Record<string, number>, opts?: {
+            atLeast?: Record<string, number>;
+            atMost?: Record<string, number>;
+        }): Promise<any>;
+        /** Totals over THIS app's records: count, sum/avg/min/max of data numbers, grouped by data keys. */
+        aggregate(params?: import('./appObjects.js').AggregateRequest): Promise<import('./appObjects.js').AggregateResponse & Record<string, unknown>>;
         [method: string]: any;
     };
+    /**
+     * Several record writes that land together or not at all (take 5 from bin A AND add 5 to order line B
+     * AND log the move). Needs `sl:records:write`; THIS app's records in THIS collection only. A failing op
+     * rolls everything back; its error says which (`opIndex`) and why (`code`). With `idempotencyKey`, a
+     * repeat of the key (a scanner retrying after a dropped signal) returns the first results
+     * (`replayed: true`) instead of writing twice; keys are remembered for 30 days.
+     */
+    transaction(ops: RecordTransactionOp[], opts?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        results: any[];
+        replayed: boolean;
+    }>;
+    /**
+     * The app's HISTORY: append-only events kept in BigQuery (stock moved, a count taken, an order shipped),
+     * so the app's records hold current state and never grow with activity. `log` (`sl:history:write`)
+     * stores one event (it arrives within seconds; a failed delivery is retried, never lost); inside a
+     * transaction use a `log` op instead, so it commits with the change. `query` (`sl:history:read`) reads
+     * this app's events in this collection, newest first.
+     */
+    history: {
+        log(type: string, data?: Record<string, any>, opts?: {
+            entityId?: string;
+        }): Promise<{
+            id: string;
+        }>;
+        query(params?: AppHistoryQuery): Promise<AppHistoryEvent[]>;
+    };
     /** Atomic named counters for this app in this collection (`sl:data:write` / `sl:data:read`). */
     counters: ServerFunctionCounters;
     /** Tags (`sl:tags:read`): `resolve(id)` → the real tag in THIS collection, or `null` for a made-up id. */

package/dist/types/appObjects.d.ts

@@ -55,8 +55,29 @@ export interface AggregateRequest {
         expires_at?: {
             lte?: string;
         };
+        updated_at?: {
+            gte?: string;
+            lte?: string;
+        };
+        /** Records only: exact match on top-level data keys, one value or any of several. */
+        data?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+        /** Records only: numeric comparisons on top-level data keys (numbers only; others never match). */
+        dataRange?: Record<string, {
+            gte?: number;
+            gt?: number;
+            lte?: number;
+            lt?: number;
+        }>;
     };
+    /**
+     * Columns per resource; records also take top-level data keys as `'data.<key>'` (e.g. `'data.location'`),
+     * up to 5. Each group comes back with its key under the same name.
+     */
     groupBy?: string[];
+    /**
+     * `'count'`; records also take `'sum:<key>'`, `'avg:<key>'`, `'min:<key>'`, `'max:<key>'` over numbers in a
+     * top-level data key (non-numbers ignored) → `sum_<key>`, `avg_<key>`… in the result.
+     */
     metrics?: string[];
     timeSeriesField?: string;
     timeSeriesInterval?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
@@ -66,7 +87,7 @@ export interface AggregateRequest {
  */
 export interface AggregateResponse {
     groups?: ({
-        count: number;
+        count?: number;
     } & Record<string, unknown>)[];
     timeSeries?: ({
         bucket: string;

package/dist/types/claimSet.d.ts

@@ -361,6 +361,8 @@ export interface PartnerTagHit {
         url: string | null;
     };
     range: ClaimSetRange | null;
+    /** The group the tag was added to, if any */
+    group: ClaimSetRange | null;
 }
 export interface CreatePartnerClaimSetRequest {
     name: string;

package/dist/types/clientLog.d.ts

@@ -0,0 +1,46 @@
+/**
+ * An app reporting an error it saw (errors.report): kept in the platform's one error log (CloudEvents + ECS
+ * rows in BigQuery), the same place server-side errors go. Say what it was about with entityType/entityId
+ * (a tag's chip UID, a product id, an order id), put routing facts in labels and the detail in context.
+ * Never include keys, passwords or tokens: the server drops any field whose name looks like one.
+ */
+export interface ClientErrorReport {
+    /** Which app: 'sidekick', 'studio', a site's app id. Default 'client'. */
+    app?: string;
+    appVersion?: string;
+    /** The collection it concerns, when there is one (owners see their collection's errors) */
+    collectionId?: string;
+    /** What was being done: 'tag.program', 'order.submit', … */
+    operation?: string;
+    severity?: 'debug' | 'info' | 'warning' | 'error' | 'critical';
+    /** A short stable code: 'TAG_LOST', 'TIMEOUT', … (this or message is required) */
+    errorCode?: string;
+    errorType?: string;
+    message?: string;
+    stack?: string;
+    /** What it was about: 'tag', 'product', 'order', … */
+    entityType?: string;
+    /** …and which one: a chip UID (normalised for 'tag'), a product id, … */
+    entityId?: string;
+    labels?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    /** An operation id to group by (a batch, a job) */
+    refId?: string;
+    correlationId?: string;
+}
+/** One kept error event, as the lookups return it (newest first). */
+export 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;
+}

package/dist/types/clientLog.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -45,3 +45,4 @@ export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
 export * from "./headless.js";
+export * from "./clientLog.js";

package/dist/types/index.js

@@ -47,3 +47,4 @@ export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
 export * from "./headless.js";
+export * from "./clientLog.js";

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.16  |  Generated: 2026-11-10T17:19:48.505Z
+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
@@ -5966,6 +6007,7 @@ interface PartnerTagHit {
   set: PartnerClaimSet | null
   tag: ClaimSetRangeTag & { url: string | null }
   range: ClaimSetRange | null
+  group: ClaimSetRange | null
 }
 ```
 
@@ -5993,6 +6035,48 @@ type ClaimSetScope = { collectionId: 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)
@@ -12830,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,
@@ -13462,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/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: