@proveanything/smartlinks 1.15.24 → 1.16.1

package/dist/types/lots.d.ts

@@ -0,0 +1,99 @@
+export type LotStatus = 'open' | 'closed' | 'recalled' | 'archived';
+/** How a lot's member products are resolved. */
+export type LotSelector = {
+    mode: 'facets';
+    rules: Array<{
+        key: string;
+        values: string[];
+    }>;
+} | {
+    mode: 'products';
+    productIds: string[];
+};
+/** Shared lot data (single source of truth — not copied to batches). */
+export interface LotPayload {
+    manufacturedAt?: string | null;
+    expiresAt?: string | null;
+    location?: string | null;
+    custom?: Record<string, any>;
+    [key: string]: any;
+}
+export interface Lot {
+    id: string;
+    collectionId: string;
+    /** Human / GS1 AI(10) identifier, ≤20 chars, unique per collection (case-insensitive). */
+    lotNumber: string;
+    name?: string | null;
+    description?: string | null;
+    status: LotStatus;
+    selector: LotSelector;
+    /** Omitted on list summaries. */
+    payload?: LotPayload;
+    /** Optional lot-level redirect/destination; wins over the product's destination on a lot hit. */
+    destination?: Record<string, any> | null;
+    productCount: number;
+    /** Materialised member product ids. Omitted on list summaries. */
+    productIds?: string[];
+    resolvedAt?: string | null;
+    createdBy?: string | null;
+    updatedBy?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Soft-delete timestamp (recoverable). `null` for live lots. Distinct from `status:'archived'`. */
+    deletedAt?: string | null;
+}
+export interface LotCreateInput {
+    lotNumber: string;
+    name?: string;
+    description?: string;
+    selector?: LotSelector;
+    payload?: LotPayload;
+    destination?: Record<string, any> | null;
+    status?: LotStatus;
+    /** Optional client-supplied id; the server generates one otherwise. */
+    id?: string;
+}
+export type LotUpdateInput = Partial<LotCreateInput>;
+export interface ListLotsParams {
+    status?: LotStatus;
+    search?: string;
+    /** Reverse lookup — lots containing this product id. */
+    productId?: string;
+    /** Admin only: include soft-deleted lots (default false). */
+    includeDeleted?: boolean;
+}
+export interface ListLotsResponse {
+    lots: Lot[];
+}
+/** Member changes returned by resolve/update-with-selector-change. */
+export interface LotMemberDiff {
+    added: string[];
+    removed: string[];
+}
+export interface ResolveLotResponse {
+    lot: Lot;
+    diff: LotMemberDiff;
+}
+export interface LotProductSummary {
+    id: string;
+    name?: string;
+    gtin?: string | null;
+}
+export interface ListLotProductsResponse {
+    products: LotProductSummary[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * Typed result of GS1 AI(10) resolution. The server decides batch-vs-lot based on
+ * the collection's flags (batch first — unique to one product — then lot).
+ */
+export interface LotResolutionResult {
+    match: 'batch' | 'lot' | 'product' | 'none';
+    productId: string;
+    batchId: string | null;
+    lotId: string | null;
+    ai10: string | null;
+    destination?: any;
+}

package/dist/types/lots.js

@@ -0,0 +1,7 @@
+// src/types/lots.ts
+//
+// A Lot is a collection-scoped production grouping that spans one or more products
+// (SKUs). Unlike a batch (a single production run of a single product), a lot is a
+// first-class entity with a selector (how members are matched), a materialised
+// product list, and a shared payload. Lots are never fanned out into batches.
+export {};

package/dist/types/proof.d.ts

@@ -28,6 +28,12 @@ export interface Proof {
     tokenId: string;
     /** Unique identifier for the user */
     userId: string;
+    /** Batch (single production run of this product) this item belongs to, if any. */
+    batchId?: string | null;
+    /** Variant (product definition) this item belongs to, if any. */
+    variantId?: string | null;
+    /** Lot (cross-product production grouping) this item belongs to, if any. Separate from `batchId`. */
+    lotId?: string | null;
     /** Is this proof available to be claimed */
     claimable?: boolean;
     /** Is this proof virtual */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.24  |  Generated: 2026-08-31T17:50:11.496Z
+Version: 1.16.1  |  Generated: 2026-09-01T15:57:41.258Z
 
 This is a concise summary of all available API functions and types.
 
@@ -35,6 +35,7 @@ For detailed guides on specific features:
 - **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
 - **[Proof Share Grants](proof-share-grants.md)** - Delegated, scoped, revocable bearer access to a single proof (read/comment/verify-owner links)
 - **[Proof Ownership Transfer](proof-ownership-transfer.md)** - Moving a proof to a new owner: directed transfer, open release, accept/cancel, and the state machine
+- **[Lots](lots.md)** - Collection-scoped production groupings spanning many SKUs; facet/product selectors, member resolution, and GS1 AI(10) batch-then-lot resolution
 - **[Item Context](item-context.md)** - The `itemContext` container prop derived from a serial-proof URL or NFC tap (what item the URL points at)
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
@@ -135,6 +136,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
+- **lots** - Functions for lots operations
 - **navigation** - Functions for navigation operations
 - **order** - Functions for order operations
 - **products** - Functions for products operations
@@ -3056,6 +3058,63 @@ interface AccountInfoResponse {
 
 ### authKit
 
+**AuthTelemetryEvent** (interface)
+```typescript
+interface AuthTelemetryEvent {
+  eventId: string
+  correlationId: string
+  clientId: string
+  collectionId?: string
+  type: AuthEventType
+  flow: AuthFlow
+  ts: string
+  durationMs?: number
+  outcome?: 'success' | 'error' | 'stalled' | 'abandoned'
+  error?: {
+  code?: string
+  statusCode?: number
+  message?: string
+  name?: string
+  stack?: string
+  endpoint?: string
+  }
+  context: {
+  sdkVersion: string
+  authKitVersion: string
+  mode: 'standalone' | 'embedded' | 'proxy' | 'native'
+  route?: string
+  deepLinkMode?: string
+  userAgent: string
+  platform?: string
+  language?: string
+  online: boolean
+  viewport?: { w: number; h: number }
+  darkMode?: boolean
+  }
+  subject?: { uid?: string; emailHash?: string }
+}
+```
+
+**TelemetryIngestResponse** (interface)
+```typescript
+interface TelemetryIngestResponse {
+  accepted: number
+  rejected: number
+  rejectedIds: string[]
+}
+```
+
+**AuthKitTelemetryConfig** (interface)
+```typescript
+interface AuthKitTelemetryConfig {
+  enabled?: boolean
+  successSampleRate?: number
+  captureJsErrors?: boolean
+  stallThresholdMs?: number
+  retentionDays?: number
+}
+```
+
 **AuthKitUser** (interface)
 ```typescript
 interface AuthKitUser {
@@ -3519,6 +3578,10 @@ interface AuthKitLockoutPolicy {
 }
 ```
 
+**AuthEventType** = ``
+
+**AuthFlow** = ``
+
 **RefreshErrorCode** = ``
 
 **AuthKitErrorCode** = ``
@@ -6355,6 +6418,122 @@ interface LocationSearchResponse {
 
 **LocationPayload** = `Omit<`
 
+### lots
+
+**LotPayload** (interface)
+```typescript
+interface LotPayload {
+  manufacturedAt?: string | null
+  expiresAt?: string | null
+  location?: string | null
+  custom?: Record<string, any>
+  [key: string]: any
+}
+```
+
+**Lot** (interface)
+```typescript
+interface Lot {
+  id: string
+  collectionId: string
+  lotNumber: string
+  name?: string | null
+  description?: string | null
+  status: LotStatus
+  selector: LotSelector
+  payload?: LotPayload
+  destination?: Record<string, any> | null
+  productCount: number
+  productIds?: string[]
+  resolvedAt?: string | null
+  createdBy?: string | null
+  updatedBy?: string | null
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string | null
+}
+```
+
+**LotCreateInput** (interface)
+```typescript
+interface LotCreateInput {
+  lotNumber: string
+  name?: string
+  description?: string
+  selector?: LotSelector
+  payload?: LotPayload
+  destination?: Record<string, any> | null
+  status?: LotStatus
+  id?: string
+}
+```
+
+**ListLotsParams** (interface)
+```typescript
+interface ListLotsParams {
+  status?: LotStatus
+  search?: string
+  productId?: string
+  includeDeleted?: boolean
+}
+```
+
+**ListLotsResponse** (interface)
+```typescript
+interface ListLotsResponse {
+  lots: Lot[]
+}
+```
+
+**LotMemberDiff** (interface)
+```typescript
+interface LotMemberDiff {
+  added: string[]; removed: string[]
+}
+```
+
+**ResolveLotResponse** (interface)
+```typescript
+interface ResolveLotResponse {
+  lot: Lot; diff: LotMemberDiff
+}
+```
+
+**LotProductSummary** (interface)
+```typescript
+interface LotProductSummary {
+  id: string; name?: string; gtin?: string | null
+}
+```
+
+**ListLotProductsResponse** (interface)
+```typescript
+interface ListLotProductsResponse {
+  products: LotProductSummary[]
+  total: number
+  page: number
+  limit: number
+}
+```
+
+**LotResolutionResult** (interface)
+```typescript
+interface LotResolutionResult {
+  match: 'batch' | 'lot' | 'product' | 'none'
+  productId: string
+  batchId: string | null
+  lotId: string | null
+  ai10: string | null
+  destination?: any
+}
+```
+
+**LotStatus** = `'open' | 'closed' | 'recalled' | 'archived'`
+
+**LotSelector** = ``
+
+**LotUpdateInput** = `Partial<LotCreateInput>`
+
 ### loyalty
 
 **LoyaltyScheme** (interface)
@@ -7329,6 +7508,9 @@ interface Proof {
   productId: string
   tokenId: string
   userId: string
+  batchId?: string | null
+  variantId?: string | null
+  lotId?: string | null
   claimable?: boolean
   virtual?: boolean
   data?: Record<string, JsonValue>
@@ -9771,6 +9953,50 @@ Public: Fetch a global location by ID GET /public/location/:locationId
     locationId: string) → `Promise<Location>`
 Public: Fetch a location for a collection; returns either a collection-owned or global fallback GET /public/collection/:collectionId/location/:locationId
 
+### lots
+
+**create**(collectionId: string, lot: LotCreateInput) → `Promise<Lot>`
+Create a lot (resolves its selector into members).
+
+**list**(collectionId: string, params: ListLotsParams = {}) → `Promise<Lot[]>`
+List lots (summary rows; `payload`/`productIds` omitted). Filter by status, search, or containing productId.
+
+**get**(collectionId: string, lotId: string, opts: { includeDeleted?: boolean } = {}) → `Promise<Lot>`
+Get the full lot record. Pass `{ includeDeleted: true }` to fetch a soft-deleted one.
+
+**getByNumber**(collectionId: string, lotNumber: string, opts: { includeDeleted?: boolean } = {}) → `Promise<Lot>`
+Look up a lot by its number (case-insensitive) — used by scan/resolver flows.
+
+**update**(collectionId: string, lotId: string, lot: LotUpdateInput) → `Promise<Lot>`
+Update a lot. Re-resolves members if the selector changed (response then carries `diff`).
+
+**remove**(collectionId: string, lotId: string) → `Promise<`
+Soft-delete a lot — recoverable, and frees its `lotNumber` for reuse. Distinct from {@link archive}. Hidden from reads unless `{ includeDeleted: true }`; undo with {@link restore}.
+
+**archive**(collectionId: string, lotId: string) → `Promise<`
+Archive a lot — a live lifecycle state (stays visible, keeps its number). Not a delete.
+
+**restore**(collectionId: string, lotId: string) → `Promise<Lot>`
+Restore a soft-deleted lot. Rejects (409) if a live lot now uses the same number.
+
+**resolve**(collectionId: string, lotId: string) → `Promise<ResolveLotResponse>`
+Re-resolve members from the current selector; returns the lot + a member diff.
+
+**listProducts**(collectionId: string, lotId: string, opts: { page?: number; limit?: number } = {}) → `Promise<ListLotProductsResponse>`
+Paginated member product summaries.
+
+**publicList**(collectionId: string, params: ListLotsParams = {}) → `Promise<Lot[]>`
+Paginated member product summaries.
+
+**publicGet**(collectionId: string, lotId: string) → `Promise<Lot>`
+Paginated member product summaries.
+
+**publicGetByNumber**(collectionId: string, lotNumber: string) → `Promise<Lot>`
+Paginated member product summaries.
+
+**publicListProducts**(collectionId: string, lotId: string, opts: { page?: number; limit?: number } = {}) → `Promise<ListLotProductsResponse>`
+Paginated member product summaries.
+
 ### loyalty
 
 Loyalty programmes built on top of collections. Configure schemes and earning rules; contacts earn points automatically via interaction events. See the [Loyalty guide](loyalty.md) for the full walkthrough.

package/docs/appConfig.md

@@ -298,8 +298,9 @@ about:
 | `hub`          | The Hub module.                                                      |
 | `portal`       | QR code scan portals.                                                |
 | `virtualItems` | Virtual items — algorithmic per-item IDs with no persistent row (battery serials, scan-to-collect points, bulk QR sheets). Replaces the old root-level `virtualItemsEnabled` boolean, which has been removed (§8) — resolve this like any other feature flag, not as a separate config key. Independent of `itemRecordMode`. |
-| `batches`      | Batch support. Used to be the `Collection.batches` boolean; that field has been removed — this flag is now the only source of truth. |
+| `batches`      | Batch support. Used to be the `Collection.batches` boolean; that field has been removed — this flag is now the only source of truth. Also gates AI(10) **batch** resolution on a GS1 Digital Link scan (§ see `lots.md`). |
 | `variants`     | Variant support. Used to be the `Collection.variants` boolean; that field has been removed — this flag is now the only source of truth. |
+| `lots`         | Lot support — collection-scoped production groupings spanning many SKUs (see `lots.md`). Gates AI(10) **lot** resolution on a GS1 Digital Link scan. Independent of `batches`; when both are on, a scanned AI(10) value resolves batch-first (specific SKU) then lot (broad). |
 
 Same resolution rule as any flag (§4.4) — don't read these off
 `cfg.system.features` directly, always go through `isFeatureEnabled()`.

package/docs/lots.md

@@ -0,0 +1,111 @@
+# Lots
+
+A **Lot** is a collection-scoped production grouping that spans one or more products
+(SKUs) — a single identifier applied across many SKUs and/or many production runs. It's
+the right tool when a manufacturer wants one lot number (e.g. `LOT-2026-09`) across a whole
+range, rather than a per-product **batch** (a single run of a single product).
+
+Lots are a first-class entity (not app records): cross-app readable, admin-written, with a
+real lifecycle. They are **never fanned out into batches** — the lot is the single source of
+truth for its shared data.
+
+---
+
+## Concepts
+
+- **Selector** — how member products are matched. Two modes:
+  - `{ mode: 'facets', rules: [{ key, values }] }` — AND across rules, OR within a rule's values (resolved against the facet index, so it scales to thousands of SKUs).
+  - `{ mode: 'products', productIds: [...] }` — an explicit list.
+- **`productIds` / `productCount`** — the materialised snapshot of resolved members (re-resolved on create, on selector change, and on demand via `resolve`).
+- **`payload`** — shared lot data (dates, supplier ref, custom fields). Lives only on the lot.
+- **`status`** — `open` → `closed` → `recalled` → `archived`. A live lifecycle state, distinct from deletion.
+- **`destination`** — optional lot-level redirect; wins over the product's on a lot-scoped scan.
+
+### Archive vs delete
+
+Two separate ideas — mirroring the platform's `deletedAt` convention:
+
+| | `archive` (`status: 'archived'`) | `remove` (soft-delete, `deletedAt`) |
+|---|---|---|
+| Record | stays **live** & visible | **hidden** from reads unless `includeDeleted: true` |
+| `lotNumber` | **stays reserved** | **freed** for reuse by a new lot |
+| AI(10) scan | not resolved (excluded) | not resolved |
+| Reversible | change status back | `restore` (409 if the number was taken by a live lot) |
+
+Nothing is ever hard-deleted (joins/history stay intact). Use **archive** for "this run is done, keep it around"; use **remove** for "this was a mistake, and I want the number back."
+
+---
+
+## SDK — `SL.lots.*`
+
+Writes and admin reads hit `/admin/collection/:cid/lots`; the `public*` reads hit
+`/public/collection/:cid/lots` for cross-app consumers (auth is the ambient bearer token —
+there's no `admin` flag).
+
+```ts
+import { lots } from '@proveanything/smartlinks'
+
+// Create — facet-targeted lot
+const lot = await lots.create(collectionId, {
+  lotNumber: 'LOT-2026-09',
+  name: 'September Oak run',
+  selector: { mode: 'facets', rules: [
+    { key: 'supplier', values: ['Acme Timber'] },
+    { key: 'range',    values: ['Oslo', 'Bergen'] },
+  ]},
+  payload: { manufacturedAt: '2026-09-01', custom: { supplierBatchRef: 'ACM-7741' } },
+})
+
+const list       = await lots.list(collectionId, { status: 'open' })
+const byId        = await lots.get(collectionId, lot.id)
+const byNumber    = await lots.getByNumber(collectionId, 'LOT-2026-09')  // case-insensitive
+const containing  = await lots.list(collectionId, { productId: 'prd_abc' }) // reverse lookup
+const updated     = await lots.update(collectionId, lot.id, { status: 'closed' })
+const { diff }    = await lots.resolve(collectionId, lot.id)               // { added, removed }
+const members     = await lots.listProducts(collectionId, lot.id, { page: 1, limit: 50 })
+
+await lots.archive(collectionId, lot.id)                       // live, keeps its number
+await lots.remove(collectionId, lot.id)                        // soft-delete, frees the number
+const withDeleted = await lots.list(collectionId, { includeDeleted: true })
+const restored    = await lots.restore(collectionId, lot.id)   // undo a soft-delete
+
+// Cross-app reads
+const publicLots  = await lots.publicList(collectionId)
+```
+
+Exported types: `Lot`, `LotStatus`, `LotSelector`, `LotPayload`, `LotCreateInput`,
+`LotUpdateInput`, `ListLotsParams`, `ResolveLotResponse`, `ListLotProductsResponse`,
+`LotResolutionResult`.
+
+---
+
+## GS1 Digital Link resolution — AI(10)
+
+GS1 gives batch and lot a **single** slot: AI(10) ("Batch or Lot Number"), in a Digital Link
+as `/01/{gtin}/10/{value}`. A physical code carries exactly one value there, so the server
+decides which namespace it belongs to, driven by two **feature flags** — `batches` and `lots`
+— in the platform feature-flag system (`appConfig.system.features`), resolved the standard way
+(`appConfiguration.isFeatureEnabled(collectionId, 'lots')`):
+
+- Explicit `true`/`false` in `system.features` wins; otherwise **enterprise** accounts default
+  a flag on and everyone else defaults off. So AI(10) batch/lot resolution is opt-in — no
+  existing scan changes until `batches`/`lots` is enabled for the collection.
+
+Resolution order — **batch first, then lot** (a hierarchy, not a collision):
+
+1. **Batch** is the narrowest scope (one product). If the scanned product has a batch whose id
+   or name matches the AI(10) value, it wins — a batch is a **specific-SKU override**.
+2. **Lot** is broad (many products). If no batch matches and the value is a lot number *and the
+   scanned product is a member*, the lot resolves.
+3. Otherwise it resolves at the product level.
+
+This means a range can share one lot code, and a single SKU can be given richer/overriding
+detail by creating a batch with the **same** identifier — the batch simply takes precedence for
+that SKU. A recalled lot (`status: 'recalled'`) still resolves so the destination page can show
+a recall notice (a `&recall=1` context param is added).
+
+The server returns a typed shape ({@link LotResolutionResult}); the front end renders it — clients
+should not implement their own fallback.
+
+See also [proof-product-data-scoping.md](proof-product-data-scoping.md) and the GS1 link
+generator in [utils.md](utils.md) (`buildGs1DigitalLink`).