@proveanything/smartlinks 1.15.24 → 1.16.1

package/dist/api/index.d.ts

@@ -34,6 +34,7 @@ export { order } from "./order";
 export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
+export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
 export { config } from "./config";

package/dist/api/index.js

@@ -37,6 +37,7 @@ export { order } from "./order";
 export { app } from "./appObjects";
 export { attestations } from "./attestations";
 export { containers } from "./containers";
+export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
 export { config } from "./config";

package/dist/api/lots.d.ts

@@ -0,0 +1,50 @@
+import { Lot, LotCreateInput, LotUpdateInput, ListLotsParams, ResolveLotResponse, ListLotProductsResponse } from "../types/lots";
+/**
+ * Lots — collection-scoped production groupings that span one or more products.
+ * Writes and admin reads hit `/admin/collection/:cid/lots`; the `public*` reads hit
+ * `/public/collection/:cid/lots` for cross-app consumers. Admin vs public is the path
+ * prefix (auth is the ambient bearer token); there is no `admin` flag in this SDK.
+ */
+export declare namespace lots {
+    /** Create a lot (resolves its selector into members). */
+    function create(collectionId: string, lot: LotCreateInput): Promise<Lot>;
+    /** List lots (summary rows; `payload`/`productIds` omitted). Filter by status, search, or containing productId. */
+    function list(collectionId: string, params?: ListLotsParams): Promise<Lot[]>;
+    /** Get the full lot record. Pass `{ includeDeleted: true }` to fetch a soft-deleted one. */
+    function get(collectionId: string, lotId: string, opts?: {
+        includeDeleted?: boolean;
+    }): Promise<Lot>;
+    /** Look up a lot by its number (case-insensitive) — used by scan/resolver flows. */
+    function getByNumber(collectionId: string, lotNumber: string, opts?: {
+        includeDeleted?: boolean;
+    }): Promise<Lot>;
+    /** Update a lot. Re-resolves members if the selector changed (response then carries `diff`). */
+    function update(collectionId: string, lotId: string, lot: LotUpdateInput): Promise<Lot>;
+    /**
+     * 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}.
+     */
+    function remove(collectionId: string, lotId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Archive a lot — a live lifecycle state (stays visible, keeps its number). Not a delete. */
+    function archive(collectionId: string, lotId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Restore a soft-deleted lot. Rejects (409) if a live lot now uses the same number. */
+    function restore(collectionId: string, lotId: string): Promise<Lot>;
+    /** Re-resolve members from the current selector; returns the lot + a member diff. */
+    function resolve(collectionId: string, lotId: string): Promise<ResolveLotResponse>;
+    /** Paginated member product summaries. */
+    function listProducts(collectionId: string, lotId: string, opts?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ListLotProductsResponse>;
+    function publicList(collectionId: string, params?: ListLotsParams): Promise<Lot[]>;
+    function publicGet(collectionId: string, lotId: string): Promise<Lot>;
+    function publicGetByNumber(collectionId: string, lotNumber: string): Promise<Lot>;
+    function publicListProducts(collectionId: string, lotId: string, opts?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ListLotProductsResponse>;
+}

package/dist/api/lots.js

@@ -0,0 +1,114 @@
+// src/api/lots.ts
+import { request, post, put, del } from "../http";
+/**
+ * Lots — collection-scoped production groupings that span one or more products.
+ * Writes and admin reads hit `/admin/collection/:cid/lots`; the `public*` reads hit
+ * `/public/collection/:cid/lots` for cross-app consumers. Admin vs public is the path
+ * prefix (auth is the ambient bearer token); there is no `admin` flag in this SDK.
+ */
+export var lots;
+(function (lots) {
+    function adminBase(collectionId) {
+        return `/admin/collection/${encodeURIComponent(collectionId)}/lots`;
+    }
+    function publicBase(collectionId) {
+        return `/public/collection/${encodeURIComponent(collectionId)}/lots`;
+    }
+    function listQuery(params = {}) {
+        const qs = new URLSearchParams();
+        if (params.status)
+            qs.append('status', params.status);
+        if (params.search)
+            qs.append('search', params.search);
+        if (params.productId)
+            qs.append('productId', params.productId);
+        if (params.includeDeleted)
+            qs.append('includeDeleted', 'true');
+        const s = qs.toString();
+        return s ? `?${s}` : '';
+    }
+    function pageQuery(opts = {}) {
+        const qs = new URLSearchParams();
+        if (opts.page)
+            qs.append('page', String(opts.page));
+        if (opts.limit)
+            qs.append('limit', String(opts.limit));
+        const s = qs.toString();
+        return s ? `?${s}` : '';
+    }
+    // ── Admin (writes + admin reads) ──
+    /** Create a lot (resolves its selector into members). */
+    async function create(collectionId, lot) {
+        return post(adminBase(collectionId), lot);
+    }
+    lots.create = create;
+    /** List lots (summary rows; `payload`/`productIds` omitted). Filter by status, search, or containing productId. */
+    async function list(collectionId, params = {}) {
+        const res = await request(`${adminBase(collectionId)}${listQuery(params)}`);
+        return res.lots;
+    }
+    lots.list = list;
+    /** Get the full lot record. Pass `{ includeDeleted: true }` to fetch a soft-deleted one. */
+    async function get(collectionId, lotId, opts = {}) {
+        const qs = opts.includeDeleted ? '?includeDeleted=true' : '';
+        return request(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}${qs}`);
+    }
+    lots.get = get;
+    /** Look up a lot by its number (case-insensitive) — used by scan/resolver flows. */
+    async function getByNumber(collectionId, lotNumber, opts = {}) {
+        const qs = opts.includeDeleted ? '?includeDeleted=true' : '';
+        return request(`${adminBase(collectionId)}/by-number/${encodeURIComponent(lotNumber)}${qs}`);
+    }
+    lots.getByNumber = getByNumber;
+    /** Update a lot. Re-resolves members if the selector changed (response then carries `diff`). */
+    async function update(collectionId, lotId, lot) {
+        return put(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}`, lot);
+    }
+    lots.update = update;
+    /**
+     * 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}.
+     */
+    async function remove(collectionId, lotId) {
+        return del(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}`);
+    }
+    lots.remove = remove;
+    /** Archive a lot — a live lifecycle state (stays visible, keeps its number). Not a delete. */
+    async function archive(collectionId, lotId) {
+        return post(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}/archive`, {});
+    }
+    lots.archive = archive;
+    /** Restore a soft-deleted lot. Rejects (409) if a live lot now uses the same number. */
+    async function restore(collectionId, lotId) {
+        return post(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}/restore`, {});
+    }
+    lots.restore = restore;
+    /** Re-resolve members from the current selector; returns the lot + a member diff. */
+    async function resolve(collectionId, lotId) {
+        return post(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}/resolve`, {});
+    }
+    lots.resolve = resolve;
+    /** Paginated member product summaries. */
+    async function listProducts(collectionId, lotId, opts = {}) {
+        return request(`${adminBase(collectionId)}/${encodeURIComponent(lotId)}/products${pageQuery(opts)}`);
+    }
+    lots.listProducts = listProducts;
+    // ── Public (cross-app reads) ──
+    async function publicList(collectionId, params = {}) {
+        const res = await request(`${publicBase(collectionId)}${listQuery(params)}`);
+        return res.lots;
+    }
+    lots.publicList = publicList;
+    async function publicGet(collectionId, lotId) {
+        return request(`${publicBase(collectionId)}/${encodeURIComponent(lotId)}`);
+    }
+    lots.publicGet = publicGet;
+    async function publicGetByNumber(collectionId, lotNumber) {
+        return request(`${publicBase(collectionId)}/by-number/${encodeURIComponent(lotNumber)}`);
+    }
+    lots.publicGetByNumber = publicGetByNumber;
+    async function publicListProducts(collectionId, lotId, opts = {}) {
+        return request(`${publicBase(collectionId)}/${encodeURIComponent(lotId)}/products${pageQuery(opts)}`);
+    }
+    lots.publicListProducts = publicListProducts;
+})(lots || (lots = {}));

package/dist/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/dist/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/dist/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`).

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, AuthLocat
 export type { UserAccountRegistrationRequest, } from "./types/auth";
 export type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, CommsSettings, TopicConfig, CommsSettingsGetResponse, CommsSettingsPatchBody, CommsPublicTopicsResponse, UnsubscribeQuery, UnsubscribeResponse, CommsConsentUpsertRequest, CommsPreferencesUpsertRequest, CommsSubscribeRequest, CommsSubscribeResponse, CommsSubscriptionCheckQuery, CommsSubscriptionCheckResponse, CommsListMethodsQuery, CommsListMethodsResponse, RegisterEmailMethodRequest, RegisterSmsMethodRequest, RegisterMethodResponse, SubscriptionsResolveRequest, SubscriptionsResolveResponse, } from "./types/comms";
 export type { BatchResponse, BatchCreateRequest, BatchUpdateRequest, } from "./types/batch";
+export type { Lot, LotStatus, LotSelector, LotPayload, LotCreateInput, LotUpdateInput, ListLotsParams, ListLotsResponse, LotMemberDiff, ResolveLotResponse, LotProductSummary, ListLotProductsResponse, LotResolutionResult, } from "./types/lots";
 export type { VariantResponse, VariantCreateRequest, VariantUpdateRequest, } from "./types/variant";
 export type { BroadcastSendRequest } from "./types/broadcasts";
 export type { AppConfigOptions } from "./api/appConfiguration";