@proveanything/smartlinks 1.15.23 → 1.16.0

package/dist/types/segments.d.ts

@@ -5,6 +5,18 @@ export interface InteractionFilterValue {
     from?: string;
     to?: string;
 }
+export type CustomFieldOperator = 'equals' | 'exists' | 'gt' | 'gte' | 'lt' | 'lte' | 'before' | 'after' | 'within_days' | 'older_than_days';
+export type OwnershipAttributeOperator = 'equals' | 'exists' | 'gt' | 'gte' | 'lt' | 'lte';
+export interface OwnershipAttributePredicate {
+    path: string;
+    operator: OwnershipAttributeOperator;
+    /** Operand: a number for gt/gte/lt/lte, a string for equals; omitted for exists. */
+    value?: string | number;
+}
+export interface OwnershipFacetSelector {
+    key: string;
+    value: string;
+}
 export type SegmentFilterRule = {
     field: 'interaction';
     op: 'had' | 'exists';
@@ -28,6 +40,19 @@ export type SegmentFilterRule = {
         from?: string;
         to?: string;
     };
+} | {
+    type: 'custom_field';
+    field: string;
+    operator: CustomFieldOperator;
+    value?: string | number;
+} | {
+    type: 'ownership';
+    productId?: string;
+    facet?: OwnershipFacetSelector;
+    attribute?: OwnershipAttributePredicate;
+    olderThanDays?: number;
+    withinDays?: number;
+    includeDeleted?: boolean;
 } | {
     type: 'interaction';
     interactionId: string;

package/dist/utils/paths.d.ts

@@ -116,11 +116,18 @@ export interface Gs1DigitalLinkParams {
     product?: Product;
     /** Override the global-owner flag; otherwise read from `product.ownGtin`. */
     ownGtin?: boolean;
-    /** Consumer Product Variant (AI 22). A string or an object with `id`. */
+    /**
+     * A real GS1 **Consumer Product Variant** code (AI 22). Use this when the brand has a
+     * genuine CPV. Takes precedence over `variant` when both are given.
+     */
     cpv?: string | {
         id: string;
     };
-    /** Alias of `cpv` (AI 22). */
+    /**
+     * Internal variant id, emitted as AI 22 (the SmartLinks resolver reads path segment 22
+     * as the variant). Prefer `cpv` when you have a real GS1 CPV code — a non-CPV variant id
+     * in AI 22 is only meaningful to the SmartLinks resolver, not to third-party GS1 resolvers.
+     */
     variant?: string | {
         id: string;
     };

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.23  |  Generated: 2026-08-28T10:57:24.158Z
+Version: 1.16.0  |  Generated: 2026-09-01T12:28:06.435Z
 
 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
@@ -6355,6 +6357,120 @@ 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
+}
+```
+
+**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
+}
+```
+
+**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 +7445,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>
@@ -7531,6 +7650,23 @@ interface InteractionFilterValue {
 }
 ```
 
+**OwnershipAttributePredicate** (interface)
+```typescript
+interface OwnershipAttributePredicate {
+  path: string
+  operator: OwnershipAttributeOperator
+  value?: string | number
+}
+```
+
+**OwnershipFacetSelector** (interface)
+```typescript
+interface OwnershipFacetSelector {
+  key: string
+  value: string
+}
+```
+
 **SegmentRecord** (interface)
 ```typescript
 interface SegmentRecord {
@@ -7591,6 +7727,10 @@ interface SegmentRecipientsResponse {
 }
 ```
 
+**CustomFieldOperator** = ``
+
+**OwnershipAttributeOperator** = `'equals' | 'exists' | 'gt' | 'gte' | 'lt' | 'lte'`
+
 **SegmentFilterRule** = ``
 
 ### tags
@@ -8283,7 +8423,12 @@ interface Gs1DigitalLinkParams {
   gtin?: string
   product?: Product
   ownGtin?: boolean
+  * A real GS1 **Consumer Product Variant** code (AI 22). Use this when the brand has a
+  * genuine CPV. Takes precedence over `variant` when both are given.
   cpv?: string | { id: string }
+  * Internal variant id, emitted as AI 22 (the SmartLinks resolver reads path segment 22
+  * as the variant). Prefer `cpv` when you have a real GS1 CPV code — a non-CPV variant id
+  * in AI 22 is only meaningful to the SmartLinks resolver, not to third-party GS1 resolvers.
   variant?: string | { id: string }
   lot?: string | { id: string }
   batch?: BatchResponse | string
@@ -9745,6 +9890,44 @@ 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) → `Promise<Lot>`
+Get the full lot record.
+
+**getByNumber**(collectionId: string, lotNumber: string) → `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`).
+
+**archive**(collectionId: string, lotId: string) → `Promise<`
+Soft-archive a lot (never deletes members).
+
+**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,94 @@
+# 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`. Archiving never deletes anything.
+- **`destination`** — optional lot-level redirect; wins over the product's on a lot-scoped scan.
+
+---
+
+## 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)
+
+// 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/docs/utils.md

@@ -233,7 +233,8 @@ otherwise).
 | Input | AI | Notes |
 |-------|----|-------|
 | `gtin` / `product.gtin` | 01 | Primary identifier (required) |
-| `cpv` / `variant` | 22 | Consumer Product Variant (path) |
+| `cpv` | 22 | Real GS1 Consumer Product Variant code (path). Wins over `variant`. |
+| `variant` | 22 | Internal variant id, emitted as AI 22 for the SmartLinks resolver. Use `cpv` for a genuine GS1 CPV. |
 | `lot` / `batch` | 10 | Batch/lot (path); a batch object also supplies its expiry |
 | `serial` | 21 | Specific item — a string, or an object (`serialNumber` ?? `id`, e.g. a proof / serial / virtual id) |
 | `expiry` | 17 | Date → `YYMMDD` (query) |