@proveanything/smartlinks 1.3.1 → 1.3.3

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.1  |  Generated: 2026-01-30T18:12:23.404Z
+Version: 1.3.3  |  Generated: 2026-02-02T14:12:19.424Z
 
 This is a concise summary of all available API functions and types.
 
@@ -51,7 +51,9 @@ The Smartlinks SDK is organized into the following namespaces:
 - **jobs** - Functions for jobs operations
 - **journeysAnalytics** - Functions for journeysAnalytics operations
 - **location** - Functions for location operations
+- **order** - Functions for order operations
 - **realtime** - Functions for realtime operations
+- **tags** - Functions for tags operations
 - **template** - Functions for template operations
 
 ## HTTP Utilities
@@ -1386,6 +1388,15 @@ interface CommsState {
 }
 ```
 
+**FieldCondition** (interface)
+```typescript
+interface FieldCondition {
+  dependsOn: string          // key of the field to check (not path)
+  operator: ConditionOperator
+  value?: string | string[]  // required for equals/notEquals/contains/notContains
+}
+```
+
 **BaseField** (interface)
 ```typescript
 interface BaseField {
@@ -1429,7 +1440,9 @@ interface ContactSchema {
 
 **SubjectType** = `'product' | 'proof' | 'batch'`
 
-**FieldWidget** = `'text' | 'email' | 'tel' | 'select' | 'checkbox'`
+**ConditionOperator** = ``
+
+**FieldWidget** = `'text' | 'email' | 'tel' | 'select' | 'multiselect' | 'checkbox' | 'number' | 'date' | 'url'`
 
 **FieldType** = ``
 
@@ -1943,6 +1956,124 @@ interface NfcClaimTagRequest {
 }
 ```
 
+### order
+
+**OrderItem** (interface)
+```typescript
+interface OrderItem {
+  id: string                        // UUID
+  orderId: string                   // Parent order ID
+  itemType: 'tag' | 'proof' | 'serial' // Type of item
+  itemId: string                    // The tag ID, proof ID, or serial number
+  metadata: Record<string, any>     // Item-specific metadata
+  createdAt: string                 // ISO 8601 timestamp
+}
+```
+
+**Order** (interface)
+```typescript
+interface Order {
+  id: string                        // UUID
+  orgId: string                     // Organization ID
+  collectionId: string              // Collection ID
+  orderRef?: string                 // Customer's own order reference/ID (e.g., "ORD-12345")
+  customerId?: string               // Customer's own customer ID (can map to CRM/contacts)
+  status: string                    // e.g., "pending", "processing", "shipped", "completed"
+  itemCount: number                 // Cached count of items (maintained automatically)
+  metadata: Record<string, any>     // Flexible additional data
+  items: OrderItem[]                // Array of items in this order
+  createdAt: string                 // ISO 8601 timestamp
+  updatedAt: string                 // ISO 8601 timestamp
+}
+```
+
+**CreateOrderRequest** (interface)
+```typescript
+interface CreateOrderRequest {
+  items: Array<{
+  itemType: 'tag' | 'proof' | 'serial' // Required: Type of item
+  itemId: string                        // Required: Item identifier
+  metadata?: Record<string, any>        // Optional: Item-specific data
+  }>
+  orderRef?: string                       // Optional: Your own order reference/ID
+  customerId?: string                     // Optional: Your customer ID
+  status?: string                         // Optional: Order status (default: "pending")
+  metadata?: Record<string, any>          // Optional: Order-level metadata
+}
+```
+
+**UpdateOrderRequest** (interface)
+```typescript
+interface UpdateOrderRequest {
+  orderRef?: string                 // Optional: Update order reference
+  customerId?: string               // Optional: Update customer ID
+  status?: string                   // Optional: Update status
+  metadata?: Record<string, any>    // Optional: Merge with existing metadata
+}
+```
+
+**DeleteOrderResponse** (interface)
+```typescript
+interface DeleteOrderResponse {
+  success: boolean
+}
+```
+
+**ListOrdersRequest** (interface)
+```typescript
+interface ListOrdersRequest {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  status?: string                   // Optional: Filter by status
+  orderRef?: string                 // Optional: Filter by order reference
+  customerId?: string               // Optional: Filter by customer ID
+}
+```
+
+**ListOrdersResponse** (interface)
+```typescript
+interface ListOrdersResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
+**AddItemsRequest** (interface)
+```typescript
+interface AddItemsRequest {
+  items: Array<{
+  itemType: 'tag' | 'proof' | 'serial' // Required: Type of item
+  itemId: string                        // Required: Item identifier
+  metadata?: Record<string, any>        // Optional: Item-specific data
+  }>
+}
+```
+
+**RemoveItemsRequest** (interface)
+```typescript
+interface RemoveItemsRequest {
+  itemIds: string[]                 // Array of OrderItem IDs to remove
+}
+```
+
+**LookupOrdersRequest** (interface)
+```typescript
+interface LookupOrdersRequest {
+  items: Array<{
+  itemType: 'tag' | 'proof' | 'serial' // Required: Type of item
+  itemId: string                        // Required: Item identifier
+  }>
+}
+```
+
+**LookupOrdersResponse** (interface)
+```typescript
+interface LookupOrdersResponse {
+  orders: Order[]                   // All orders containing any of the specified items
+}
+```
+
 ### product
 
 **Product** (interface)
@@ -2108,6 +2239,164 @@ interface SegmentRecipientsResponse {
 }
 ```
 
+### tags
+
+**Tag** (interface)
+```typescript
+interface Tag {
+  id: string                        // UUID
+  orgId: string                     // Organization ID
+  tagId: string                     // Unique tag identifier (globally unique)
+  collectionId: string              // Collection ID
+  productId: string                 // Product ID
+  variantId?: string | null         // Optional: Variant ID
+  batchId?: string | null           // Optional: Batch ID
+  proofId: string                   // Proof ID (serial number or explicit)
+  metadata: Record<string, any>     // Additional metadata (e.g., serialIndex)
+  createdAt: string                 // ISO 8601 timestamp
+  updatedAt: string                 // ISO 8601 timestamp
+}
+```
+
+**CreateTagRequest** (interface)
+```typescript
+interface CreateTagRequest {
+  tagId: string                     // Required: Unique tag identifier
+  productId: string                 // Required: Product ID
+  variantId?: string                // Optional: Variant ID
+  batchId?: string                  // Optional: Batch ID
+  proofId?: string                  // Optional: Explicit proof ID (if omitted, auto-generates serial)
+  useSerialNumber?: boolean         // Optional: Explicitly request serial number generation
+  metadata?: Record<string, any>    // Optional: Additional metadata
+  force?: boolean                   // Optional: Overwrite if tag exists in same collection (default: false)
+}
+```
+
+**CreateTagsBatchRequest** (interface)
+```typescript
+interface CreateTagsBatchRequest {
+  tags: Array<{
+  tagId: string                   // Required: Unique tag identifier
+  productId: string               // Required: Product ID
+  variantId?: string              // Optional: Variant ID
+  batchId?: string                // Optional: Batch ID
+  proofId?: string                // Optional: If omitted, auto-generates serial number
+  metadata?: Record<string, any>  // Optional: Additional metadata
+  }>
+  force?: boolean                   // Optional: Overwrite existing tags in same collection (default: false)
+}
+```
+
+**CreateTagsBatchResponse** (interface)
+```typescript
+interface CreateTagsBatchResponse {
+  summary: {
+  total: number                   // Total tags in request
+  created: number                 // Successfully created
+  updated: number                 // Successfully updated (with force=true)
+  failed: number                  // Failed to create/update
+  conflicts: number               // Already exist (without force=true)
+  }
+  results: {
+  created: Tag[]                  // Array of successfully created tags
+  updated: Tag[]                  // Array of successfully updated tags
+  failed: Array<{
+  tagId: string
+  reason: string                // Error code (e.g., "TAG_ASSIGNED_ELSEWHERE", "CREATE_FAILED")
+  message: string               // Human-readable error message
+  existingTag?: Tag             // Existing tag if applicable
+  }>
+  conflicts: Array<{
+  tagId: string
+  reason: string                // "TAG_ALREADY_ASSIGNED"
+  message: string
+  existingTag: Tag              // The existing tag
+  }>
+  }
+}
+```
+
+**UpdateTagRequest** (interface)
+```typescript
+interface UpdateTagRequest {
+  productId?: string                // Optional: Update product ID
+  variantId?: string | null         // Optional: Update variant ID (null to clear)
+  batchId?: string | null           // Optional: Update batch ID (null to clear)
+  proofId?: string                  // Optional: Update proof ID
+  metadata?: Record<string, any>    // Optional: Merge with existing metadata
+}
+```
+
+**DeleteTagResponse** (interface)
+```typescript
+interface DeleteTagResponse {
+  success: boolean
+}
+```
+
+**ListTagsRequest** (interface)
+```typescript
+interface ListTagsRequest {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  productId?: string                // Optional: Filter by product ID
+  variantId?: string                // Optional: Filter by variant ID
+  batchId?: string                  // Optional: Filter by batch ID
+}
+```
+
+**ListTagsResponse** (interface)
+```typescript
+interface ListTagsResponse {
+  tags: Tag[]
+  limit: number
+  offset: number
+}
+```
+
+**PublicGetTagRequest** (interface)
+```typescript
+interface PublicGetTagRequest {
+  embed?: string                    // Optional: Comma-separated values: "collection", "product", "proof"
+}
+```
+
+**PublicGetTagResponse** (interface)
+```typescript
+interface PublicGetTagResponse {
+  tag: Tag
+  collection?: any                  // Included if embed contains "collection"
+  product?: any                     // Included if embed contains "product"
+  proof?: any                       // Included if embed contains "proof"
+}
+```
+
+**PublicBatchLookupRequest** (interface)
+```typescript
+interface PublicBatchLookupRequest {
+  tagIds: string[]                  // Array of tag IDs to lookup
+  embed?: string                    // Optional: Comma-separated: "collection", "product", "proof"
+}
+```
+
+**PublicBatchLookupResponse** (interface)
+```typescript
+interface PublicBatchLookupResponse {
+  tags: Record<string, Tag>         // Map: tagId → Tag object
+  collections?: Record<string, any> // Map: collectionId → Collection (if embed=collection)
+  products?: Record<string, any>    // Map: productId → Product (if embed=product)
+  proofs?: Record<string, any>      // Map: proofId → Proof (if embed=proof)
+}
+```
+
+**PublicBatchLookupQueryRequest** (interface)
+```typescript
+interface PublicBatchLookupQueryRequest {
+  tagIds: string                    // Comma-separated tag IDs
+  embed?: string                    // Optional: Comma-separated: "collection", "product", "proof"
+}
+```
+
 ### template
 
 **TemplateBase** (interface)
@@ -2256,61 +2545,61 @@ type AppConfigOptions = {
 
 **LoginResponse** (type)
 ```typescript
-type LoginResponse = {
-  id: string
-  name: string
-  email: string
-  bearerToken: string
-  account: Record<string, any>
+type LoginResponse = {
+  id: string
+  name: string
+  email: string
+  bearerToken: string
+  account: Record<string, any>
 }
 ```
 
 **VerifyTokenResponse** (type)
 ```typescript
-type VerifyTokenResponse = {
-  valid: boolean
-  id?: string
-  name?: string
-  email?: string
-  account?: Record<string, any>
+type VerifyTokenResponse = {
+  valid: boolean
+  id?: string
+  name?: string
+  email?: string
+  account?: Record<string, any>
 }
 ```
 
 **AccountInfoResponse** (type)
 ```typescript
-type AccountInfoResponse = {
-  accessType: string;
-  analyticsCode: string;
-  analyticsId: string;
-  auth_time: number;
-  baseCollectionId: string;
-  clientType: string;
-  email: string;
-  email_verified: boolean;
-  features: {
-    actionLogger: boolean;
-    adminCollections: boolean;
-    adminApps: boolean;
-    apiKeys: boolean;
-    adminUsers: boolean;
-    [key: string]: boolean;
-  };
-  iat: number;
-  id: string;
-  iss: string;
-  location: string | null;
-  name: string;
-  picture: string;
-  sites: {
-    [siteName: string]: boolean;
-  };
-  sub: string;
-  uid: string;
-  userId: string;
-  contactId: string
-  whitelabel: {
-    [key: string]: any;
-  }
+type AccountInfoResponse = {
+  accessType: string;
+  analyticsCode: string;
+  analyticsId: string;
+  auth_time: number;
+  baseCollectionId: string;
+  clientType: string;
+  email: string;
+  email_verified: boolean;
+  features: {
+    actionLogger: boolean;
+    adminCollections: boolean;
+    adminApps: boolean;
+    apiKeys: boolean;
+    adminUsers: boolean;
+    [key: string]: boolean;
+  };
+  iat: number;
+  id: string;
+  iss: string;
+  location: string | null;
+  name: string;
+  picture: string;
+  sites: {
+    [siteName: string]: boolean;
+  };
+  sub: string;
+  uid: string;
+  userId: string;
+  contactId: string
+  whitelabel: {
+    [key: string]: any;
+  }
 }
 ```
 
@@ -2318,15 +2607,15 @@ type AccountInfoResponse = {
 
 ### ai
 
-**generateContent**(collectionId: string,
-    params: AIGenerateContentRequest,
+**generateContent**(collectionId: string,
+    params: AIGenerateContentRequest,
     admin: boolean = true) → `Promise<any>`
 Generate text/content via AI (admin)
 
 **generateImage**(collectionId: string, params: AIGenerateImageRequest) → `Promise<any>`
 Generate an image via AI (admin)
 
-**searchPhotos**(collectionId: string,
+**searchPhotos**(collectionId: string,
     params: AISearchPhotosRequest) → `Promise<AISearchPhotosPhoto[]>`
 Search stock photos or similar via AI (admin)
 
@@ -2370,39 +2659,39 @@ Post a chat message to the AI (admin or public)
 **upload**(options: UploadAssetOptions) → `Promise<Asset>`
 Upload an asset file
 
-**getForCollection**(collectionId: string,
+**getForCollection**(collectionId: string,
     assetId: string) → `Promise<AssetResponse>`
 Upload an asset file
 
 **listForCollection**(collectionId: string) → `Promise<AssetResponse[]>`
 Upload an asset file
 
-**getForProduct**(collectionId: string,
-    productId: string,
+**getForProduct**(collectionId: string,
+    productId: string,
     assetId: string) → `Promise<AssetResponse>`
 Upload an asset file
 
-**listForProduct**(collectionId: string,
+**listForProduct**(collectionId: string,
     productId: string) → `Promise<AssetResponse[]>`
 Upload an asset file
 
-**getForProof**(collectionId: string,
-    productId: string,
-    proofId: string,
+**getForProof**(collectionId: string,
+    productId: string,
+    proofId: string,
     assetId: string) → `Promise<AssetResponse>`
 Upload an asset file
 
-**listForProof**(collectionId: string,
-    productId: string,
-    proofId: string,
+**listForProof**(collectionId: string,
+    productId: string,
+    proofId: string,
     appId?: string) → `Promise<AssetResponse[]>`
 Upload an asset file
 
-**uploadAsset**(collectionId: string,
-    productId: string,
-    proofId: string,
-    file: File,
-    extraData?: Record<string, any>,
+**uploadAsset**(collectionId: string,
+    productId: string,
+    proofId: string,
+    file: File,
+    extraData?: Record<string, any>,
     onProgress?: (percent: number) → `void`
 Uploads an asset file to a proof, with optional extraData as JSON. Supports progress reporting via onProgress callback (browser only).
 
@@ -2417,43 +2706,43 @@ Remove an asset by id within a scope (admin)
 
 ### async
 
-**enqueueAsyncJob**(collectionId: string,
+**enqueueAsyncJob**(collectionId: string,
     params: EnqueueAsyncJobRequest) → `Promise<EnqueueAsyncJobResponse>`
 Enqueue a background job for a collection POST /admin/collection/:collectionId/async/jobs (202)
 
-**getAsyncJobStatus**(collectionId: string,
+**getAsyncJobStatus**(collectionId: string,
     jobId: number) → `Promise<Job>`
 Get job status by ID (may return 404 if completed/removed) GET /admin/collection/:collectionId/async/jobs/:jobId
 
 ### attestation
 
-**list**(collectionId: string,
-    productId: string,
+**list**(collectionId: string,
+    productId: string,
     proofId: string) → `Promise<AttestationResponse[]>`
 List all attestations for a proof.
 
-**get**(collectionId: string,
-    productId: string,
-    proofId: string,
+**get**(collectionId: string,
+    productId: string,
+    proofId: string,
     attestationId: string) → `Promise<AttestationResponse>`
 Get a single attestation by ID.
 
-**create**(collectionId: string,
-    productId: string,
-    proofId: string,
+**create**(collectionId: string,
+    productId: string,
+    proofId: string,
     data: AttestationCreateRequest) → `Promise<AttestationResponse>`
 Create a new attestation for a proof.
 
-**update**(collectionId: string,
-    productId: string,
-    proofId: string,
-    attestationId: string,
+**update**(collectionId: string,
+    productId: string,
+    proofId: string,
+    attestationId: string,
     data: AttestationUpdateRequest) → `Promise<AttestationResponse>`
 Update an attestation.
 
-**remove**(collectionId: string,
-    productId: string,
-    proofId: string,
+**remove**(collectionId: string,
+    productId: string,
+    proofId: string,
     attestationId: string) → `Promise<void>`
 Delete an attestation.
 
@@ -2477,11 +2766,11 @@ Requests a JWT for the current user and a specific collection/product/proof Vali
 **registerUser**(user: UserAccountRegistrationRequest) → `Promise<LoginResponse>`
 Tries to register a new user account. Can return a bearer token, or a Firebase token
 
-**getUserToken**(opts?: {
-    email?: string
-    collectionId?: string
-    userId?: string
-    expiry?: string
+**getUserToken**(opts?: {
+    email?: string
+    collectionId?: string
+    userId?: string
+    expiry?: string
   }) → `Promise<`
 Admin: Get a user bearer token (impersonation/automation). POST /admin/auth/userToken All fields are optional; at least one identifier should be provided.
 
@@ -2570,91 +2859,91 @@ Verify phone verification code (public).
 
 ### batch
 
-**get**(collectionId: string,
-    productId: string,
+**get**(collectionId: string,
+    productId: string,
     batchId: string) → `Promise<BatchResponse>`
 Get a single batch by ID for a collection and product (admin only).
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     productId: string) → `Promise<BatchResponse[]>`
 List all batches for a collection and product (admin only).
 
-**create**(collectionId: string,
-    productId: string,
+**create**(collectionId: string,
+    productId: string,
     data: BatchCreateRequest) → `Promise<BatchResponse>`
 Create a new batch for a collection and product (admin only).
 
-**update**(collectionId: string,
-    productId: string,
-    batchId: string,
+**update**(collectionId: string,
+    productId: string,
+    batchId: string,
     data: BatchUpdateRequest) → `Promise<BatchResponse>`
 Update a batch for a collection and product (admin only).
 
-**remove**(collectionId: string,
-    productId: string,
+**remove**(collectionId: string,
+    productId: string,
     batchId: string) → `Promise<void>`
 Delete a batch for a collection and product (admin only).
 
-**getPublic**(collectionId: string,
-    productId: string,
+**getPublic**(collectionId: string,
+    productId: string,
     batchId: string) → `Promise<BatchResponse>`
 Get a single batch by ID for a collection and product (public endpoint).
 
-**getSN**(collectionId: string,
-    productId: string,
-    batchId: string,
-    startIndex: number = 0,
+**getSN**(collectionId: string,
+    productId: string,
+    batchId: string,
+    startIndex: number = 0,
     count: number = 10) → `Promise<any>`
 Get serial numbers for a batch (admin only).
 
-**lookupSN**(collectionId: string,
-    productId: string,
-    batchId: string,
+**lookupSN**(collectionId: string,
+    productId: string,
+    batchId: string,
     codeId: string) → `Promise<any>`
 Look up a serial number by code for a batch (admin only).
 
 ### broadcasts
 
-**create**(collectionId: string,
+**create**(collectionId: string,
     body: Omit<BroadcastRecord, 'id' | 'collectionId' | 'createdAt'>) → `Promise<BroadcastRecord>`
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     query: ListBroadcastsQuery = {}) → `Promise<BroadcastList>`
 
-**get**(collectionId: string,
+**get**(collectionId: string,
     id: string) → `Promise<BroadcastRecord>`
 
-**update**(collectionId: string,
-    id: string,
+**update**(collectionId: string,
+    id: string,
     body: Partial<Omit<BroadcastRecord, 'id' | 'collectionId' | 'createdAt'>>) → `Promise<BroadcastRecord>`
 
-**remove**(collectionId: string,
+**remove**(collectionId: string,
     id: string) → `Promise<void>`
 
-**recipients**(collectionId: string,
-    id: string,
+**recipients**(collectionId: string,
+    id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<BroadcastRecipientsResponse>`
 
-**preview**(collectionId: string,
-    id: string,
+**preview**(collectionId: string,
+    id: string,
     body: BroadcastPreviewRequest) → `Promise<BroadcastPreviewResponse>`
 
-**send**(collectionId: string,
-    id: string,
+**send**(collectionId: string,
+    id: string,
     body: BroadcastSendRequest = {}) → `Promise<`
 
-**sendTest**(collectionId: string,
-    id: string,
+**sendTest**(collectionId: string,
+    id: string,
     body: BroadcastSendTestRequest) → `Promise<BroadcastSendTestResponse>`
 
-**sendManual**(collectionId: string,
-    id: string,
+**sendManual**(collectionId: string,
+    id: string,
     body: BroadcastSendManualRequest) → `Promise<BroadcastSendManualResponse>`
 
-**append**(collectionId: string,
+**append**(collectionId: string,
     body: BroadcastAppendEventBody) → `Promise<AppendResult>`
 
-**appendBulk**(collectionId: string,
+**appendBulk**(collectionId: string,
     body: BroadcastAppendBulkBody) → `Promise<AppendBulkResult>`
 
 ### claimSet
@@ -2740,78 +3029,78 @@ Assign a value to a serial number for a collection (admin only).
 **getPushVapidPublicKey**(collectionId: string) → `Promise<import("../types/comms").PushVapidResponse>`
 Public: Get VAPID public key used for Web Push subscriptions. GET /public/collection/:collectionId/comm/push/vapidPublicKey Note: Key may be global; path is collection-scoped for consistency.
 
-**registerPush**(collectionId: string,
+**registerPush**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register a Web Push subscription under unified comms. POST /public/collection/:collectionId/comm/push/register
 
-**getSettings**(collectionId: string,
+**getSettings**(collectionId: string,
     opts: { includeSecret?: boolean } = {}) → `Promise<import("../types/comms").CommsSettingsGetResponse>`
 Admin: Get current comms settings for a collection. GET /admin/collection/:collectionId/comm.settings Optional query: includeSecret=true to include unsub.secret in response.
 
-**patchSettings**(collectionId: string,
+**patchSettings**(collectionId: string,
     body: import("../types/comms") → `void`
 Admin: Patch comms settings for a collection. PATCH /admin/collection/:collectionId/comm.settings
 
 **getPublicTopics**(collectionId: string) → `Promise<import("../types/comms").CommsPublicTopicsResponse>`
 Public: Fetch configured topics for a collection. GET /public/collection/:collectionId/comm/topics
 
-**unsubscribe**(collectionId: string,
+**unsubscribe**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Unsubscribe a contact from a category or channel. GET /public/collection/:collectionId/comm/unsubscribe
 
-**upsertConsent**(collectionId: string,
+**upsertConsent**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert default consent for a contact. POST /public/collection/:collectionId/comm/consent
 
-**upsertPreferences**(collectionId: string,
+**upsertPreferences**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert preferences for a specific subject (or default if subject omitted). POST /public/collection/:collectionId/comm/preferences
 
-**subscribe**(collectionId: string,
+**subscribe**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Subscribe/unsubscribe contact to a subject. POST /public/collection/:collectionId/comm/subscribe
 
-**checkSubscription**(collectionId: string,
+**checkSubscription**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Check subscription status for a subject. GET /public/collection/:collectionId/comm/subscription/check
 
-**listMethods**(collectionId: string,
+**listMethods**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: List registered contact methods. GET /public/collection/:collectionId/comm/methods
 
-**registerEmail**(collectionId: string,
+**registerEmail**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register email method for a contact. POST /public/collection/:collectionId/comm/email/register
 
-**registerSms**(collectionId: string,
+**registerSms**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register SMS method for a contact. POST /public/collection/:collectionId/comm/sms/register
 
-**resolveSubscriptions**(collectionId: string,
+**resolveSubscriptions**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Resolve contacts for a subject with identity hints. POST /public/collection/:collectionId/comm/subscriptions/resolve
 
-**queryByUser**(collectionId: string,
+**queryByUser**(collectionId: string,
     body: CommsQueryByUser = {}) → `Promise<CommunicationEvent[]>`
 Analytics: Query communication events by user or contact. POST /admin/collection/:collectionId/comm/query/by-user
 
-**queryRecipientIds**(collectionId: string,
+**queryRecipientIds**(collectionId: string,
     body: CommsRecipientIdsQuery) → `Promise<RecipientId[]>`
 Analytics: Recipient IDs for a communication source. POST /admin/collection/:collectionId/comm/query/recipient-ids
 
-**queryRecipientsWithoutAction**(collectionId: string,
+**queryRecipientsWithoutAction**(collectionId: string,
     body: CommsRecipientsWithoutActionQuery) → `Promise<RecipientId[]>`
 Analytics: Recipients who did not perform an action. POST /admin/collection/:collectionId/comm/query/recipients/without-action
 
-**queryRecipientsWithAction**(collectionId: string,
+**queryRecipientsWithAction**(collectionId: string,
     body: CommsRecipientsWithActionQuery) → `Promise<RecipientId[] | RecipientWithOutcome[]>`
 Analytics: Recipients who performed an action, optionally with outcome. POST /admin/collection/:collectionId/comm/query/recipients/with-action
 
-**logCommunicationEvent**(collectionId: string,
+**logCommunicationEvent**(collectionId: string,
     body: LogCommunicationEventBody) → `Promise<AppendResult>`
 Logging: Append a single communication event. POST /admin/collection/:collectionId/comm/log
 
-**logBulkCommunicationEvents**(collectionId: string,
+**logBulkCommunicationEvents**(collectionId: string,
     body: LogBulkCommunicationEventsBody | ({ sourceId: string; ids: string[]; idField?: 'userId'|'contactId'; [k: string]: any }) → `void`
 Logging: Append many communication events for a list of IDs. POST /admin/collection/:collectionId/comm/log/bulk
 
@@ -2819,39 +3108,42 @@ Logging: Append many communication events for a list of IDs. POST /admin/collect
 
 **create**(collectionId: string, data: ContactCreateRequest) → `Promise<ContactResponse>`
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     params?: { limit?: number; offset?: number; includeDeleted?: boolean }) → `Promise<ContactListResponse>`
 
-**get**(collectionId: string,
-    contactId: string,
+**get**(collectionId: string,
+    contactId: string,
     params?: { includeDeleted?: boolean }) → `Promise<ContactResponse>`
 
-**update**(collectionId: string,
-    contactId: string,
+**update**(collectionId: string,
+    contactId: string,
     data: ContactUpdateRequest) → `Promise<ContactResponse>`
 
 **remove**(collectionId: string, contactId: string) → `Promise<void>`
 
-**lookup**(collectionId: string,
+**lookup**(collectionId: string,
     params: { email?: string; phone?: string }) → `Promise<ContactResponse>`
 
-**upsert**(collectionId: string,
+**upsert**(collectionId: string,
     data: ContactCreateRequest) → `Promise<ContactResponse>`
 
-**publicUpsert**(collectionId: string,
+**publicUpsert**(collectionId: string,
     data: PublicContactUpsertRequest) → `Promise<PublicContactUpsertResponse>`
 
 **publicGetMine**(collectionId: string) → `Promise<PublicGetMyContactResponse>`
 
-**publicUpdateMine**(collectionId: string,
+**publicUpdateMine**(collectionId: string,
     data: ContactPatch) → `Promise<PublicUpdateMyContactResponse>`
 
 **publicGetSchema**(collectionId: string) → `Promise<ContactSchema>`
+Public: Get contact update schema for a collection Fetches the public contact schema including core fields, custom fields with conditional visibility rules, and visibility/editability settings. Custom fields may include a `condition` property that specifies when the field should be displayed. Apps rendering these forms should: 1. Evaluate each field's `condition` against current form values 2. Hide fields whose conditions are not met 3. Skip validation for hidden fields (they shouldn't be required when not visible)
 
 **erase**(collectionId: string, contactId: string, body?: any) → `Promise<ContactResponse>`
+Public: Get contact update schema for a collection Fetches the public contact schema including core fields, custom fields with conditional visibility rules, and visibility/editability settings. Custom fields may include a `condition` property that specifies when the field should be displayed. Apps rendering these forms should: 1. Evaluate each field's `condition` against current form values 2. Hide fields whose conditions are not met 3. Skip validation for hidden fields (they shouldn't be required when not visible)
 
-**getUser**(collectionId: string,
+**getUser**(collectionId: string,
     userId: string,) → `Promise<UserSearchResponse>`
+Public: Get contact update schema for a collection Fetches the public contact schema including core fields, custom fields with conditional visibility rules, and visibility/editability settings. Custom fields may include a `condition` property that specifies when the field should be displayed. Apps rendering these forms should: 1. Evaluate each field's `condition` against current form values 2. Hide fields whose conditions are not met 3. Skip validation for hidden fields (they shouldn't be required when not visible)
 
 ### crate
 
@@ -2889,108 +3181,108 @@ Delete a form for a collection (admin only).
 
 ### interactions
 
-**query**(collectionId: string,
+**query**(collectionId: string,
     body: AdminInteractionsQueryRequest) → `Promise<InteractionEventRow[]>`
 POST /admin/collection/:collectionId/interactions/query Flexible query for interaction events with optional includes.
 
-**countsByOutcome**(collectionId: string,
+**countsByOutcome**(collectionId: string,
     query: AdminInteractionsCountsByOutcomeRequest = {}) → `Promise<OutcomeCount[]>`
 POST /admin/collection/:collectionId/interactions/counts-by-outcome Returns array of { outcome, count }.
 
-**appendEvent**(collectionId: string,
+**appendEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
 POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
-**updateEvent**(collectionId: string,
+**updateEvent**(collectionId: string,
     body: UpdateInteractionBody) → `Promise<`
 POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
-**submitPublicEvent**(collectionId: string,
+**submitPublicEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
 Appends one interaction event from a public source.
 
-**create**(collectionId: string,
+**create**(collectionId: string,
     body: CreateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
 Appends one interaction event from a public source.
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
 Appends one interaction event from a public source.
 
-**get**(collectionId: string,
+**get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
 Appends one interaction event from a public source.
 
-**update**(collectionId: string,
-    id: string,
+**update**(collectionId: string,
+    id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
 Appends one interaction event from a public source.
 
-**remove**(collectionId: string,
+**remove**(collectionId: string,
     id: string) → `Promise<void>`
 Appends one interaction event from a public source.
 
-**publicCountsByOutcome**(collectionId: string,
-    body: PublicInteractionsCountsByOutcomeRequest,
+**publicCountsByOutcome**(collectionId: string,
+    body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
 Appends one interaction event from a public source.
 
-**publicMyInteractions**(collectionId: string,
-    body: PublicInteractionsByUserRequest,
+**publicMyInteractions**(collectionId: string,
+    body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
 Appends one interaction event from a public source.
 
-**publicList**(collectionId: string,
+**publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
 Appends one interaction event from a public source.
 
-**publicGet**(collectionId: string,
+**publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
 Appends one interaction event from a public source.
 
 ### jobs
 
-**listJobs**(collectionId: string,
+**listJobs**(collectionId: string,
     query: ListJobsQuery = {}) → `Promise<JobsPage>`
 List visible jobs for a collection GET /admin/collection/:collectionId/jobs
 
-**getJob**(collectionId: string,
+**getJob**(collectionId: string,
     jobId: number) → `Promise<Job>`
 Get a single job GET /admin/collection/:collectionId/jobs/:jobId
 
 ### journeys
 
-**create**(collectionId: string,
+**create**(collectionId: string,
     body: CreateJourneyBody) → `Promise<JourneyRecord>`
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     query: ListJourneysQuery = {}) → `Promise<JourneyList>`
 
-**get**(collectionId: string,
+**get**(collectionId: string,
     id: string) → `Promise<JourneyRecord>`
 
-**update**(collectionId: string,
-    id: string,
+**update**(collectionId: string,
+    id: string,
     body: UpdateJourneyBody) → `Promise<JourneyRecord>`
 
-**remove**(collectionId: string,
+**remove**(collectionId: string,
     id: string) → `Promise<void>`
 
 ### journeysAnalytics
 
-**stats**(collectionId: string,
-    journeyId: string,
+**stats**(collectionId: string,
+    journeyId: string,
     body: JourneyStatsRequest = {}) → `Promise<JourneyStatsResponse>`
 POST /admin/collection/:collectionId/journeys.analytics/:journeyId/stats Computes journey stats over a time window; outcome defaults to 'success'. If `finalStepId` is provided, includes `currentlyActive` and `completed` fields.
 
-**recipients**(collectionId: string,
-    journeyId: string,
-    stepId: string,
+**recipients**(collectionId: string,
+    journeyId: string,
+    stepId: string,
     body: JourneyStepRecipientsRequest = {}) → `Promise<JourneyStepRecipientsResponse>`
 POST /admin/collection/:collectionId/journeys.analytics/:journeyId/steps/:stepId/recipients Returns recipient IDs for a given journey step. For completed/pending, `interactionId` is required; outcome defaults to 'success'.
 
-**funnelReport**(collectionId: string,
-    journeyId: string,
+**funnelReport**(collectionId: string,
+    journeyId: string,
     body: JourneyFunnelReportRequest) → `Promise<JourneyFunnelReportResponse>`
 POST /admin/collection/:collectionId/journeys.analytics/:journeyId/funnel-report Computes conversion, counts, and avg time across mapped steps in a period.
 
@@ -3002,14 +3294,14 @@ Platform: Create a global location (super admin; requires features.adminApps) PO
 **create**(collectionId: string, params: LocationPayload) → `Promise<Location>`
 Admin: Create a collection-scoped location POST /admin/collection/:collectionId/location
 
-**search**(collectionId: string,
+**search**(collectionId: string,
     query: LocationSearchQuery = {}) → `Promise<LocationSearchResponse>`
 Admin: Search locations to pick during setup (combines collection + global) GET /admin/collection/:collectionId/location/search
 
 **getPublic**(locationId: string) → `Promise<Location>`
 Public: Fetch a global location by ID GET /public/location/:locationId
 
-**getPublicForCollection**(collectionId: string,
+**getPublicForCollection**(collectionId: string,
     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
 
@@ -3024,6 +3316,43 @@ Validate an NFC tag payload (public). POST /public/nfc/validate
 **lookupTag**(tagId: string) → `Promise<NfcTagInfo[]>`
 Lookup a tag by its ID (public). GET /public/nfc/findByTag/:tagId
 
+### order
+
+**create**(collectionId: string,
+    data: CreateOrderRequest) → `Promise<CreateOrderResponse>`
+Create a new order with items. ```typescript const order = await order.create('coll_123', { orderRef: 'ORD-12345', customerId: 'CUST-789', items: [ { itemType: 'tag', itemId: 'TAG001' }, { itemType: 'tag', itemId: 'TAG002' }, { itemType: 'serial', itemId: 'SN12345' } ], status: 'pending', metadata: { shipmentId: 'SHIP-789', destination: 'Warehouse B' } }) ```
+
+**get**(collectionId: string,
+    orderId: string) → `Promise<GetOrderResponse>`
+Get a single order by ID with all its items. ```typescript const order = await order.get('coll_123', 'order_abc123') console.log(`Order has ${order.itemCount} items`) ```
+
+**update**(collectionId: string,
+    orderId: string,
+    data: UpdateOrderRequest) → `Promise<UpdateOrderResponse>`
+Update order status or metadata. Items are managed separately via addItems/removeItems. ```typescript const updated = await order.update('coll_123', 'order_abc123', { status: 'shipped', metadata: { trackingNumber: '1Z999AA10123456784', shippedAt: '2026-02-02T14:30:00Z' } }) ```
+
+**remove**(collectionId: string,
+    orderId: string) → `Promise<DeleteOrderResponse>`
+Delete an order and all its items (cascade delete). ```typescript await order.remove('coll_123', 'order_abc123') ```
+
+**list**(collectionId: string,
+    params?: ListOrdersRequest) → `Promise<ListOrdersResponse>`
+List orders for a collection with optional filters and pagination. Orders are returned in descending order by createdAt (newest first). ```typescript // List all orders const all = await order.list('coll_123') // List with filters const pending = await order.list('coll_123', { status: 'pending', limit: 50, offset: 0 }) // Filter by customer const customerOrders = await order.list('coll_123', { customerId: 'CUST-789' }) ```
+
+**addItems**(collectionId: string,
+    orderId: string,
+    data: AddItemsRequest) → `Promise<AddItemsResponse>`
+Add additional items to an existing order. ```typescript const updated = await order.addItems('coll_123', 'order_abc123', { items: [ { itemType: 'tag', itemId: 'TAG003' }, { itemType: 'proof', itemId: 'proof_xyz' } ] }) console.log(`Order now has ${updated.itemCount} items`) ```
+
+**removeItems**(collectionId: string,
+    orderId: string,
+    data: RemoveItemsRequest) → `Promise<RemoveItemsResponse>`
+Remove specific items from an order. ```typescript const updated = await order.removeItems('coll_123', 'order_abc123', { itemIds: ['item_001', 'item_002'] }) ```
+
+**lookup**(collectionId: string,
+    data: LookupOrdersRequest) → `Promise<LookupOrdersResponse>`
+Find all orders containing specific items (tags, proofs, or serial numbers). Use case: Scan a tag and immediately see if it's part of any order. ```typescript // Scan a tag and find associated orders const result = await order.lookup('coll_123', { items: [ { itemType: 'tag', itemId: 'TAG001' } ] }) if (result.orders.length > 0) { console.log(`Tag is part of ${result.orders.length} order(s)`) result.orders.forEach(ord => { console.log(`Order ${ord.orderRef}: ${ord.status}`) }) } // Batch lookup multiple items const batchResult = await order.lookup('coll_123', { items: [ { itemType: 'tag', itemId: 'TAG001' }, { itemType: 'serial', itemId: 'SN12345' }, { itemType: 'proof', itemId: 'proof_xyz' } ] }) ```
+
 ### product
 
 **get**(collectionId: string,
@@ -3127,29 +3456,66 @@ Get an Ably token for admin real-time communication. This endpoint returns an Ab
 
 ### segments
 
-**create**(collectionId: string,
+**create**(collectionId: string,
     body: Omit<SegmentRecord, 'id' | 'collectionId' | 'createdAt'>) → `Promise<SegmentRecord>`
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     query: ListSegmentsQuery = {}) → `Promise<SegmentList>`
 
-**get**(collectionId: string,
+**get**(collectionId: string,
     id: string) → `Promise<SegmentRecord>`
 
-**update**(collectionId: string,
-    id: string,
+**update**(collectionId: string,
+    id: string,
     body: Partial<Omit<SegmentRecord, 'id' | 'collectionId' | 'createdAt'>>) → `Promise<SegmentRecord>`
 
-**remove**(collectionId: string,
+**remove**(collectionId: string,
     id: string) → `Promise<void>`
 
-**calculate**(collectionId: string,
+**calculate**(collectionId: string,
     id: string) → `Promise<SegmentCalculateResult>`
 
-**recipients**(collectionId: string,
-    id: string,
+**recipients**(collectionId: string,
+    id: string,
     query: { limit?: number; offset?: number } = {}) → `Promise<SegmentRecipientsResponse>`
 
+### tags
+
+**create**(collectionId: string,
+    data: CreateTagRequest) → `Promise<CreateTagResponse>`
+Create a single tag mapping. If proofId is not provided, automatically generates a serial number. ```typescript // Auto-generate serial number const tag = await tags.create('coll_123', { tagId: 'TAG001', productId: 'prod_456', variantId: 'var_789' }) // Use explicit proof ID const tag2 = await tags.create('coll_123', { tagId: 'TAG002', productId: 'prod_456', proofId: 'proof_explicit_123' }) ```
+
+**createBatch**(collectionId: string,
+    data: CreateTagsBatchRequest) → `Promise<CreateTagsBatchResponse>`
+Create multiple tag mappings efficiently in a batch operation. By default, auto-generates serial numbers for all tags without explicit proofId. Tags are grouped by product/variant/batch and serial numbers are generated in a single transaction per group for optimal performance. ```typescript const result = await tags.createBatch('coll_123', { tags: [ { tagId: 'TAG001', productId: 'prod_456', variantId: 'var_789' }, { tagId: 'TAG002', productId: 'prod_456', variantId: 'var_789' }, { tagId: 'TAG003', productId: 'prod_456', batchId: 'batch_100' } ] }) console.log(`Created: ${result.summary.created}, Failed: ${result.summary.failed}`) ```
+
+**update**(collectionId: string,
+    tagId: string,
+    data: UpdateTagRequest) → `Promise<UpdateTagResponse>`
+Update an existing tag mapping. ```typescript const updated = await tags.update('coll_123', 'TAG001', { variantId: 'var_999', metadata: { notes: 'Updated variant' } }) ```
+
+**remove**(collectionId: string,
+    tagId: string) → `Promise<DeleteTagResponse>`
+Delete a tag mapping. ```typescript await tags.remove('coll_123', 'TAG001') ```
+
+**get**(collectionId: string,
+    tagId: string) → `Promise<GetTagResponse>`
+Get a single tag mapping by tagId. ```typescript const tag = await tags.get('coll_123', 'TAG001') ```
+
+**list**(collectionId: string,
+    params?: ListTagsRequest) → `Promise<ListTagsResponse>`
+List all tags for a collection with optional filters and pagination. ```typescript // List all tags const all = await tags.list('coll_123') // List with filters const filtered = await tags.list('coll_123', { productId: 'prod_456', variantId: 'var_789', limit: 50, offset: 0 }) ```
+
+**publicGet**(tagId: string,
+    params?: PublicGetTagRequest) → `Promise<PublicGetTagResponse>`
+Public lookup of a single tag by tagId. Optionally embed related collection, product, or proof data. No authentication required. ```typescript // Simple lookup const result = await tags.publicGet('TAG001') // With embedded data const withData = await tags.publicGet('TAG001', { embed: 'collection,product,proof' }) console.log(withData.tag, withData.collection, withData.product, withData.proof) ```
+
+**publicBatchLookup**(data: PublicBatchLookupRequest) → `Promise<PublicBatchLookupResponse>`
+Public batch lookup of multiple tags in a single request (POST). Optionally embed related data. Related data is deduplicated and batch-fetched. No authentication required. ```typescript const result = await tags.publicBatchLookup({ tagIds: ['TAG001', 'TAG002', 'TAG003'], embed: 'collection,product' }) // Access tags and deduplicated collections/products console.log(result.tags['TAG001']) console.log(result.collections) console.log(result.products) ```
+
+**publicBatchLookupQuery**(params: PublicBatchLookupQueryRequest) → `Promise<PublicBatchLookupQueryResponse>`
+Public batch lookup of multiple tags using query parameters (GET). Alternative to publicBatchLookup for simple GET requests. No authentication required. ```typescript const result = await tags.publicBatchLookupQuery({ tagIds: 'TAG001,TAG002,TAG003', embed: 'collection' }) ```
+
 ### template
 
 **getAll**(collectionId: string) → `Promise<Template[]>`
@@ -3158,14 +3524,14 @@ Get an Ably token for admin real-time communication. This endpoint returns an Ab
 
 **create**(collectionId: string, data: TemplateInput) → `Promise<Template>`
 
-**update**(collectionId: string,
-    templateId: string,
+**update**(collectionId: string,
+    templateId: string,
     data: TemplateUpdate) → `Promise<Template>`
 
 **del**(collectionId: string, templateId: string) → `Promise<Template>`
 
-**uploadAsset**(collectionId: string,
-    templateId: string,
+**uploadAsset**(collectionId: string,
+    templateId: string,
     file: File | Blob) → `Promise<`
 
 **getAllowed**(collectionId: string) → `Promise<TemplatePublic[]>`
@@ -3176,55 +3542,55 @@ Get an Ably token for admin real-time communication. This endpoint returns an Ab
 
 **getAllowedGlobal**(collectionId: string) → `Promise<TemplatePublic[]>`
 
-**render**(collectionId: string,
-    templateId: string,
+**render**(collectionId: string,
+    templateId: string,
     body: TemplateRenderRequest) → `Promise<TemplateRenderResponse>`
 
-**renderSource**(collectionId: string,
+**renderSource**(collectionId: string,
     body: TemplateRenderSourceRequest) → `Promise<TemplateRenderSourceResponse>`
 
 ### variant
 
-**get**(collectionId: string,
-    productId: string,
+**get**(collectionId: string,
+    productId: string,
     variantId: string) → `Promise<VariantResponse>`
 Get a single variant by ID for a collection and product (admin only).
 
-**list**(collectionId: string,
+**list**(collectionId: string,
     productId: string) → `Promise<VariantResponse[]>`
 List all variants for a collection and product (admin only).
 
-**create**(collectionId: string,
-    productId: string,
+**create**(collectionId: string,
+    productId: string,
     data: VariantCreateRequest) → `Promise<VariantResponse>`
 Create a new variant for a collection and product (admin only).
 
-**update**(collectionId: string,
-    productId: string,
-    variantId: string,
+**update**(collectionId: string,
+    productId: string,
+    variantId: string,
     data: VariantUpdateRequest) → `Promise<VariantResponse>`
 Update a variant for a collection and product (admin only).
 
-**remove**(collectionId: string,
-    productId: string,
+**remove**(collectionId: string,
+    productId: string,
     variantId: string) → `Promise<void>`
 Delete a variant for a collection and product (admin only).
 
-**getPublic**(collectionId: string,
-    productId: string,
+**getPublic**(collectionId: string,
+    productId: string,
     variantId: string) → `Promise<VariantResponse>`
 Get a single variant by ID for a collection and product (public endpoint).
 
-**getSN**(collectionId: string,
-    productId: string,
-    variantId: string,
-    startIndex: number = 0,
+**getSN**(collectionId: string,
+    productId: string,
+    variantId: string,
+    startIndex: number = 0,
     count: number = 10) → `Promise<any>`
 Get serial numbers for a variant (admin only).
 
-**lookupSN**(collectionId: string,
-    productId: string,
-    variantId: string,
+**lookupSN**(collectionId: string,
+    productId: string,
+    variantId: string,
     codeId: string) → `Promise<any>`
 Look up a serial number by code for a variant (admin only).