@proveanything/smartlinks 1.3.20 → 1.3.21

package/dist/api/batch.d.ts

@@ -1,4 +1,4 @@
-import { BatchResponse, BatchCreateRequest, BatchUpdateRequest } from "../types/batch";
+import { BatchResponse, BatchCreateRequest, BatchUpdateRequest, SearchBatchesRequest, BatchTag } from "../types/batch";
 export declare namespace batch {
     /**
      * Get a single batch by ID for a collection and product (admin only).
@@ -75,4 +75,84 @@ export declare namespace batch {
      * @throws ErrorResponse if the request fails
      */
     function lookupSN(collectionId: string, productId: string, batchId: string, codeId: string): Promise<any>;
+    /**
+     * Search for batches across all products in a collection.
+     * Allows searching by batch ID or name, with optional product filtering.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param params - Optional search parameters (search term, productId filter, limit)
+     * @returns Promise resolving to an array of matching BatchResponse objects
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Search for batches containing "2024"
+     * const batches = await batch.searchInCollection('coll_123', {
+     *   search: 'BATCH-2024',
+     *   limit: 50
+     * })
+     *
+     * // Filter batches for a specific product
+     * const productBatches = await batch.searchInCollection('coll_123', {
+     *   productId: 'prod_abc',
+     *   limit: 100
+     * })
+     *
+     * // Get all batches in collection
+     * const allBatches = await batch.searchInCollection('coll_123')
+     *
+     * // Check for expired batches
+     * batches.forEach(batch => {
+     *   if (batch.expiryDate?.seconds) {
+     *     const expiryDate = new Date(batch.expiryDate.seconds * 1000)
+     *     if (expiryDate < new Date()) {
+     *       console.log(`Batch ${batch.id} is expired`)
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    function searchInCollection(collectionId: string, params?: SearchBatchesRequest): Promise<BatchResponse[]>;
+    /**
+     * Find a specific batch by ID across all products in a collection.
+     * Returns the batch along with the productId it belongs to.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param batchId - Batch ID to find
+     * @returns Promise resolving to a BatchResponse with productId
+     * @throws ErrorResponse if the request fails (404 if not found)
+     *
+     * @example
+     * ```typescript
+     * // Find which product contains a specific batch
+     * const batch = await batch.findInCollection('coll_123', 'BATCH-2024-001')
+     * console.log(`Batch found in product: ${batch.productId}`)
+     * console.log(`Expires: ${batch.expiryDate}`)
+     * ```
+     */
+    function findInCollection(collectionId: string, batchId: string): Promise<BatchResponse>;
+    /**
+     * Get all tags/codes assigned to a specific batch.
+     * Shows which claim set codes have been assigned to this batch.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param batchId - Batch ID
+     * @param claimSetId - Optional claim set ID to filter results
+     * @returns Promise resolving to an array of BatchTag objects
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all tags assigned to a batch
+     * const tags = await batch.getBatchTags('coll_123', 'BATCH-2024-001')
+     * console.log(`Batch has ${tags.length} tags assigned`)
+     * tags.forEach(tag => {
+     *   console.log(`Code: ${tag.code}, ClaimSet: ${tag.claimSetId}, TagID: ${tag.tagId}`)
+     * })
+     *
+     * // Get tags from a specific claim set
+     * const claimSetTags = await batch.getBatchTags('coll_123', 'BATCH-2024-001', '000001')
+     * ```
+     */
+    function getBatchTags(collectionId: string, batchId: string, claimSetId?: string): Promise<BatchTag[]>;
 }

package/dist/api/batch.js

@@ -115,4 +115,108 @@ export var batch;
         return request(path);
     }
     batch.lookupSN = lookupSN;
+    /**
+     * Search for batches across all products in a collection.
+     * Allows searching by batch ID or name, with optional product filtering.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param params - Optional search parameters (search term, productId filter, limit)
+     * @returns Promise resolving to an array of matching BatchResponse objects
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Search for batches containing "2024"
+     * const batches = await batch.searchInCollection('coll_123', {
+     *   search: 'BATCH-2024',
+     *   limit: 50
+     * })
+     *
+     * // Filter batches for a specific product
+     * const productBatches = await batch.searchInCollection('coll_123', {
+     *   productId: 'prod_abc',
+     *   limit: 100
+     * })
+     *
+     * // Get all batches in collection
+     * const allBatches = await batch.searchInCollection('coll_123')
+     *
+     * // Check for expired batches
+     * batches.forEach(batch => {
+     *   if (batch.expiryDate?.seconds) {
+     *     const expiryDate = new Date(batch.expiryDate.seconds * 1000)
+     *     if (expiryDate < new Date()) {
+     *       console.log(`Batch ${batch.id} is expired`)
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    async function searchInCollection(collectionId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.search)
+            queryParams.append('search', params.search);
+        if (params === null || params === void 0 ? void 0 : params.productId)
+            queryParams.append('productId', params.productId);
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/batch${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    batch.searchInCollection = searchInCollection;
+    /**
+     * Find a specific batch by ID across all products in a collection.
+     * Returns the batch along with the productId it belongs to.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param batchId - Batch ID to find
+     * @returns Promise resolving to a BatchResponse with productId
+     * @throws ErrorResponse if the request fails (404 if not found)
+     *
+     * @example
+     * ```typescript
+     * // Find which product contains a specific batch
+     * const batch = await batch.findInCollection('coll_123', 'BATCH-2024-001')
+     * console.log(`Batch found in product: ${batch.productId}`)
+     * console.log(`Expires: ${batch.expiryDate}`)
+     * ```
+     */
+    async function findInCollection(collectionId, batchId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/batch/${encodeURIComponent(batchId)}`;
+        return request(path);
+    }
+    batch.findInCollection = findInCollection;
+    /**
+     * Get all tags/codes assigned to a specific batch.
+     * Shows which claim set codes have been assigned to this batch.
+     *
+     * @param collectionId - Identifier of the collection
+     * @param batchId - Batch ID
+     * @param claimSetId - Optional claim set ID to filter results
+     * @returns Promise resolving to an array of BatchTag objects
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all tags assigned to a batch
+     * const tags = await batch.getBatchTags('coll_123', 'BATCH-2024-001')
+     * console.log(`Batch has ${tags.length} tags assigned`)
+     * tags.forEach(tag => {
+     *   console.log(`Code: ${tag.code}, ClaimSet: ${tag.claimSetId}, TagID: ${tag.tagId}`)
+     * })
+     *
+     * // Get tags from a specific claim set
+     * const claimSetTags = await batch.getBatchTags('coll_123', 'BATCH-2024-001', '000001')
+     * ```
+     */
+    async function getBatchTags(collectionId, batchId, claimSetId) {
+        const queryParams = new URLSearchParams();
+        if (claimSetId)
+            queryParams.append('claimSetId', claimSetId);
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/batch/${encodeURIComponent(batchId)}/tags${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    batch.getBatchTags = getBatchTags;
 })(batch || (batch = {}));

package/dist/api/order.d.ts

@@ -1,4 +1,4 @@
-import { CreateOrderRequest, CreateOrderResponse, GetOrderParams, GetOrderResponse, UpdateOrderRequest, UpdateOrderResponse, DeleteOrderResponse, ListOrdersRequest, ListOrdersResponse, GetOrderItemsParams, GetOrderItemsResponse, AddItemsRequest, AddItemsResponse, RemoveItemsRequest, RemoveItemsResponse, QueryOrdersRequest, QueryOrdersResponse, ReportsParams, ReportsResponse, LookupOrdersRequest, LookupOrdersResponse, LookupByProductParams, LookupByProductResponse, OrderAnalyticsResponse, TimelineRequest, TimelineResponse, LocationRequest, LocationResponse, BulkAnalyticsRequest, BulkAnalyticsResponse, SummaryRequest, CollectionSummaryResponse } from "../types/order";
+import { CreateOrderRequest, CreateOrderResponse, GetOrderParams, GetOrderResponse, UpdateOrderRequest, UpdateOrderResponse, DeleteOrderResponse, ListOrdersRequest, ListOrdersResponse, GetOrderItemsParams, GetOrderItemsResponse, AddItemsRequest, AddItemsResponse, RemoveItemsRequest, RemoveItemsResponse, QueryOrdersRequest, QueryOrdersResponse, ReportsParams, ReportsResponse, LookupOrdersRequest, LookupOrdersResponse, LookupByProductParams, LookupByProductResponse, OrderAnalyticsResponse, TimelineRequest, TimelineResponse, LocationRequest, LocationResponse, BulkAnalyticsRequest, BulkAnalyticsResponse, SummaryRequest, CollectionSummaryResponse, FindOrdersByAttributeParams, FindOrdersByAttributeResponse, FindItemsByAttributeParams, FindItemsByAttributeResponse, GetOrderIdsParams, GetOrderIdsResponse } from "../types/order";
 /**
  * Order Management API
  *
@@ -443,4 +443,169 @@ export declare namespace order {
      * ```
      */
     function getCollectionSummary(collectionId: string, params?: SummaryRequest): Promise<CollectionSummaryResponse>;
+    /**
+     * Find all orders containing items from a specific batch.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param batchId - Batch ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find orders with items from a specific batch
+     * const { orders } = await order.findByBatch('coll_123', 'BATCH-2024-001', {
+     *   includeItems: true,
+     *   limit: 50
+     * })
+     *
+     * // Get unique customers who received this batch
+     * const customers = [...new Set(orders.map(o => o.customerId).filter(Boolean))]
+     * console.log(`Batch delivered to ${customers.length} customers`)
+     * ```
+     */
+    function findByBatch(collectionId: string, batchId: string, params?: FindOrdersByAttributeParams): Promise<FindOrdersByAttributeResponse>;
+    /**
+     * Find all orders containing items from a specific product.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Product ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find all orders containing a product
+     * const { orders, limit, offset } = await order.findOrdersByProduct('coll_123', 'prod_789', {
+     *   limit: 100
+     * })
+     *
+     * console.log(`Product appears in ${orders.length} orders`)
+     * ```
+     */
+    function findOrdersByProduct(collectionId: string, productId: string, params?: FindOrdersByAttributeParams): Promise<FindOrdersByAttributeResponse>;
+    /**
+     * Find all orders containing items from a specific variant.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param variantId - Variant ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find orders with a specific variant
+     * const { orders } = await order.findByVariant('coll_123', 'var_456', {
+     *   includeItems: true
+     * })
+     *
+     * console.log(`Variant ${variantId} in ${orders.length} orders`)
+     * ```
+     */
+    function findByVariant(collectionId: string, variantId: string, params?: FindOrdersByAttributeParams): Promise<FindOrdersByAttributeResponse>;
+    /**
+     * Get individual order items (not full orders) for a specific batch.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param batchId - Batch ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get items from a batch with order info
+     * const { items, count } = await order.findItemsByBatch('coll_123', 'BATCH-2024-001', {
+     *   includeOrder: true,
+     *   limit: 100
+     * })
+     *
+     * // Group by order status
+     * const byStatus = items.reduce((acc, item) => {
+     *   const status = item.order?.status || 'unknown'
+     *   acc[status] = (acc[status] || 0) + 1
+     *   return acc
+     * }, {})
+     * ```
+     */
+    function findItemsByBatch(collectionId: string, batchId: string, params?: FindItemsByAttributeParams): Promise<FindItemsByAttributeResponse>;
+    /**
+     * Get individual order items for a specific product.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Product ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all items for a product
+     * const { items } = await order.findItemsByProduct('coll_123', 'prod_789', {
+     *   includeOrder: true
+     * })
+     *
+     * console.log(`Product delivered in ${items.length} order items`)
+     * ```
+     */
+    function findItemsByProduct(collectionId: string, productId: string, params?: FindItemsByAttributeParams): Promise<FindItemsByAttributeResponse>;
+    /**
+     * Get individual order items for a specific variant.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param variantId - Variant ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get variant items with order details
+     * const { items, count } = await order.findItemsByVariant('coll_123', 'var_456', {
+     *   includeOrder: true,
+     *   limit: 50
+     * })
+     * ```
+     */
+    function findItemsByVariant(collectionId: string, variantId: string, params?: FindItemsByAttributeParams): Promise<FindItemsByAttributeResponse>;
+    /**
+     * Get unique order IDs containing items matching the specified attribute.
+     * Lightweight query that only returns order IDs, not full order objects.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param attribute - Attribute to search by ('batchId', 'productId', or 'variantId')
+     * @param value - Value to search for
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to a GetOrderIdsResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get order IDs for a batch (fast count)
+     * const { orderIds, count } = await order.getOrderIdsByAttribute(
+     *   'coll_123',
+     *   'batchId',
+     *   'BATCH-2024-001'
+     * )
+     * console.log(`Batch appears in ${count} orders`)
+     *
+     * // Get order IDs for a product
+     * const productOrders = await order.getOrderIdsByAttribute(
+     *   'coll_123',
+     *   'productId',
+     *   'prod_789',
+     *   { limit: 500 }
+     * )
+     * ```
+     */
+    function getOrderIdsByAttribute(collectionId: string, attribute: 'batchId' | 'productId' | 'variantId', value: string, params?: GetOrderIdsParams): Promise<GetOrderIdsResponse>;
 }

package/dist/api/order.js

@@ -576,4 +576,251 @@ export var order;
         return post(path, params || {});
     }
     order.getCollectionSummary = getCollectionSummary;
+    /**
+     * Find all orders containing items from a specific batch.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param batchId - Batch ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find orders with items from a specific batch
+     * const { orders } = await order.findByBatch('coll_123', 'BATCH-2024-001', {
+     *   includeItems: true,
+     *   limit: 50
+     * })
+     *
+     * // Get unique customers who received this batch
+     * const customers = [...new Set(orders.map(o => o.customerId).filter(Boolean))]
+     * console.log(`Batch delivered to ${customers.length} customers`)
+     * ```
+     */
+    async function findByBatch(collectionId, batchId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeItems)
+            queryParams.append('includeItems', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/batch/${encodeURIComponent(batchId)}${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findByBatch = findByBatch;
+    /**
+     * Find all orders containing items from a specific product.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Product ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find all orders containing a product
+     * const { orders, limit, offset } = await order.findOrdersByProduct('coll_123', 'prod_789', {
+     *   limit: 100
+     * })
+     *
+     * console.log(`Product appears in ${orders.length} orders`)
+     * ```
+     */
+    async function findOrdersByProduct(collectionId, productId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeItems)
+            queryParams.append('includeItems', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/product/${encodeURIComponent(productId)}${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findOrdersByProduct = findOrdersByProduct;
+    /**
+     * Find all orders containing items from a specific variant.
+     * Uses indexed queries for fast lookups across order items.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param variantId - Variant ID to search for
+     * @param params - Optional pagination and includeItems parameters
+     * @returns Promise resolving to a FindOrdersByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find orders with a specific variant
+     * const { orders } = await order.findByVariant('coll_123', 'var_456', {
+     *   includeItems: true
+     * })
+     *
+     * console.log(`Variant ${variantId} in ${orders.length} orders`)
+     * ```
+     */
+    async function findByVariant(collectionId, variantId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeItems)
+            queryParams.append('includeItems', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/variant/${encodeURIComponent(variantId)}${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findByVariant = findByVariant;
+    /**
+     * Get individual order items (not full orders) for a specific batch.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param batchId - Batch ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get items from a batch with order info
+     * const { items, count } = await order.findItemsByBatch('coll_123', 'BATCH-2024-001', {
+     *   includeOrder: true,
+     *   limit: 100
+     * })
+     *
+     * // Group by order status
+     * const byStatus = items.reduce((acc, item) => {
+     *   const status = item.order?.status || 'unknown'
+     *   acc[status] = (acc[status] || 0) + 1
+     *   return acc
+     * }, {})
+     * ```
+     */
+    async function findItemsByBatch(collectionId, batchId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeOrder)
+            queryParams.append('includeOrder', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/batch/${encodeURIComponent(batchId)}/items${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findItemsByBatch = findItemsByBatch;
+    /**
+     * Get individual order items for a specific product.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Product ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all items for a product
+     * const { items } = await order.findItemsByProduct('coll_123', 'prod_789', {
+     *   includeOrder: true
+     * })
+     *
+     * console.log(`Product delivered in ${items.length} order items`)
+     * ```
+     */
+    async function findItemsByProduct(collectionId, productId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeOrder)
+            queryParams.append('includeOrder', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/product/${encodeURIComponent(productId)}/items${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findItemsByProduct = findItemsByProduct;
+    /**
+     * Get individual order items for a specific variant.
+     * Returns all matching items with optional order summary.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param variantId - Variant ID to search for
+     * @param params - Optional pagination and includeOrder parameters
+     * @returns Promise resolving to a FindItemsByAttributeResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get variant items with order details
+     * const { items, count } = await order.findItemsByVariant('coll_123', 'var_456', {
+     *   includeOrder: true,
+     *   limit: 50
+     * })
+     * ```
+     */
+    async function findItemsByVariant(collectionId, variantId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        if (params === null || params === void 0 ? void 0 : params.includeOrder)
+            queryParams.append('includeOrder', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/variant/${encodeURIComponent(variantId)}/items${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.findItemsByVariant = findItemsByVariant;
+    /**
+     * Get unique order IDs containing items matching the specified attribute.
+     * Lightweight query that only returns order IDs, not full order objects.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param attribute - Attribute to search by ('batchId', 'productId', or 'variantId')
+     * @param value - Value to search for
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to a GetOrderIdsResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get order IDs for a batch (fast count)
+     * const { orderIds, count } = await order.getOrderIdsByAttribute(
+     *   'coll_123',
+     *   'batchId',
+     *   'BATCH-2024-001'
+     * )
+     * console.log(`Batch appears in ${count} orders`)
+     *
+     * // Get order IDs for a product
+     * const productOrders = await order.getOrderIdsByAttribute(
+     *   'coll_123',
+     *   'productId',
+     *   'prod_789',
+     *   { limit: 500 }
+     * )
+     * ```
+     */
+    async function getOrderIdsByAttribute(collectionId, attribute, value, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.limit)
+            queryParams.append('limit', params.limit.toString());
+        if (params === null || params === void 0 ? void 0 : params.offset)
+            queryParams.append('offset', params.offset.toString());
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/ids/${attribute}/${encodeURIComponent(value)}${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.getOrderIdsByAttribute = getOrderIdsByAttribute;
 })(order || (order = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.20  |  Generated: 2026-02-08T14:25:23.483Z
+Version: 1.3.21  |  Generated: 2026-02-09T12:29:22.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -625,11 +625,66 @@ interface AuthKitConfig {
 
 ### batch
 
-**BatchResponse** = `any`
+**FirebaseTimestamp** (interface)
+```typescript
+interface FirebaseTimestamp {
+  seconds: number                 // Unix timestamp in seconds
+  nanoseconds?: number            // Nanoseconds component
+}
+```
+
+**BatchResponse** (interface)
+```typescript
+interface BatchResponse {
+  id: string                      // Batch ID
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  productId?: string              // Product ID (for collection-level searches)
+  collectionId?: string           // Collection ID
+  [key: string]: any              // Additional batch fields
+}
+```
 
-**BatchCreateRequest** = `any`
+**BatchCreateRequest** (interface)
+```typescript
+interface BatchCreateRequest {
+  id: string                      // Batch ID
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  [key: string]: any              // Additional batch fields
+}
+```
 
-**BatchUpdateRequest** = `any`
+**BatchUpdateRequest** (interface)
+```typescript
+interface BatchUpdateRequest {
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  [key: string]: any              // Additional batch fields
+}
+```
+
+**SearchBatchesRequest** (interface)
+```typescript
+interface SearchBatchesRequest {
+  search?: string                 // Search term (batch ID or name)
+  productId?: string              // Filter by specific product
+  limit?: number                  // Max results (default: 100)
+}
+```
+
+**BatchTag** (interface)
+```typescript
+interface BatchTag {
+  code: string                    // Code/tag ID
+  claimSetId: string              // Claim set ID
+  collectionId?: string           // Collection ID
+  productId?: string              // Associated product ID
+  batchId?: string                // Batch ID
+  tagId?: string                  // Tag identifier
+  index?: number                  // Position in claim set
+}
+```
 
 ### broadcasts
 
@@ -2239,8 +2294,24 @@ interface OrderItem {
   orderId: string                   // Parent order ID
   itemType: 'tag' | 'proof' | 'serial' // Type of item
   itemId: string                    // The tag ID, proof ID, or serial number
+  collectionId?: string             // Collection ID
+  productId?: string                // Product ID
+  variantId?: string | null         // Variant ID
+  batchId?: string | null           // Batch ID
   metadata: Record<string, any>     // Item-specific metadata
   createdAt: string                 // ISO 8601 timestamp
+  order?: OrderSummary              // Optional order summary (when includeOrder=true)
+}
+```
+
+**OrderSummary** (interface)
+```typescript
+interface OrderSummary {
+  id: string                        // Order ID
+  orderRef?: string                 // Order reference
+  status: string                    // Order status
+  customerId?: string               // Customer ID
+  createdAt: string                 // ISO 8601 timestamp
 }
 ```
 
@@ -2463,6 +2534,61 @@ interface LookupByProductResponse {
 }
 ```
 
+**FindOrdersByAttributeParams** (interface)
+```typescript
+interface FindOrdersByAttributeParams {
+  limit?: number                    // Max results (default: 100)
+  offset?: number                   // Pagination offset (default: 0)
+  includeItems?: boolean            // Include items array (default: false)
+}
+```
+
+**FindOrdersByAttributeResponse** (interface)
+```typescript
+interface FindOrdersByAttributeResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
+**FindItemsByAttributeParams** (interface)
+```typescript
+interface FindItemsByAttributeParams {
+  limit?: number                    // Max results (default: 100)
+  offset?: number                   // Pagination offset (default: 0)
+  includeOrder?: boolean            // Include order summary (default: false)
+}
+```
+
+**FindItemsByAttributeResponse** (interface)
+```typescript
+interface FindItemsByAttributeResponse {
+  items: OrderItem[]
+  count: number
+  limit: number
+  offset: number
+}
+```
+
+**GetOrderIdsParams** (interface)
+```typescript
+interface GetOrderIdsParams {
+  limit?: number                    // Max results (default: 1000)
+  offset?: number                   // Pagination offset (default: 0)
+}
+```
+
+**GetOrderIdsResponse** (interface)
+```typescript
+interface GetOrderIdsResponse {
+  orderIds: string[]
+  count: number
+  attribute: 'batchId' | 'productId' | 'variantId'
+  value: string
+}
+```
+
 **TagScanSummary** (interface)
 ```typescript
 interface TagScanSummary {
@@ -3943,6 +4069,19 @@ Get serial numbers for a batch (admin only).
     codeId: string) → `Promise<any>`
 Look up a serial number by code for a batch (admin only).
 
+**searchInCollection**(collectionId: string,
+    params?: SearchBatchesRequest) → `Promise<BatchResponse[]>`
+Search for batches across all products in a collection. Allows searching by batch ID or name, with optional product filtering. ```typescript // Search for batches containing "2024" const batches = await batch.searchInCollection('coll_123', { search: 'BATCH-2024', limit: 50 }) // Filter batches for a specific product const productBatches = await batch.searchInCollection('coll_123', { productId: 'prod_abc', limit: 100 }) // Get all batches in collection const allBatches = await batch.searchInCollection('coll_123') // Check for expired batches batches.forEach(batch => { if (batch.expiryDate?.seconds) { const expiryDate = new Date(batch.expiryDate.seconds * 1000) if (expiryDate < new Date()) { console.log(`Batch ${batch.id} is expired`) } } }) ```
+
+**findInCollection**(collectionId: string,
+    batchId: string) → `Promise<BatchResponse>`
+Find a specific batch by ID across all products in a collection. Returns the batch along with the productId it belongs to. ```typescript // Find which product contains a specific batch const batch = await batch.findInCollection('coll_123', 'BATCH-2024-001') console.log(`Batch found in product: ${batch.productId}`) console.log(`Expires: ${batch.expiryDate}`) ```
+
+**getBatchTags**(collectionId: string,
+    batchId: string,
+    claimSetId?: string) → `Promise<BatchTag[]>`
+Get all tags/codes assigned to a specific batch. Shows which claim set codes have been assigned to this batch. ```typescript // Get all tags assigned to a batch const tags = await batch.getBatchTags('coll_123', 'BATCH-2024-001') console.log(`Batch has ${tags.length} tags assigned`) tags.forEach(tag => { console.log(`Code: ${tag.code}, ClaimSet: ${tag.claimSetId}, TagID: ${tag.tagId}`) }) // Get tags from a specific claim set const claimSetTags = await batch.getBatchTags('coll_123', 'BATCH-2024-001', '000001') ```
+
 ### broadcasts
 
 **create**(collectionId: string,
@@ -4444,6 +4583,42 @@ Get analytics summary for multiple orders at once. Efficient way to retrieve sca
     params?: SummaryRequest) → `Promise<CollectionSummaryResponse>`
 Get collection-wide analytics summary across all orders. Returns daily scan counts and admin activity overview. ```typescript // Get all-time collection summary const summary = await order.getCollectionSummary('coll_123') console.log(`Admin activity count: ${summary.adminActivity.count}`) console.log('Scans by day:') summary.scansByDay.forEach(day => { console.log(`  ${day.date}: ${day.scanCount} scans`) }) // Get summary for last 30 days const recentSummary = await order.getCollectionSummary('coll_123', { from: '2026-01-08T00:00:00Z', to: '2026-02-08T00:00:00Z' }) ```
 
+**findByBatch**(collectionId: string,
+    batchId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific batch. Uses indexed queries for fast lookups across order items. ```typescript // Find orders with items from a specific batch const { orders } = await order.findByBatch('coll_123', 'BATCH-2024-001', { includeItems: true, limit: 50 }) // Get unique customers who received this batch const customers = [...new Set(orders.map(o => o.customerId).filter(Boolean))] console.log(`Batch delivered to ${customers.length} customers`) ```
+
+**findOrdersByProduct**(collectionId: string,
+    productId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific product. Uses indexed queries for fast lookups across order items. ```typescript // Find all orders containing a product const { orders, limit, offset } = await order.findOrdersByProduct('coll_123', 'prod_789', { limit: 100 }) console.log(`Product appears in ${orders.length} orders`) ```
+
+**findByVariant**(collectionId: string,
+    variantId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific variant. Uses indexed queries for fast lookups across order items. ```typescript // Find orders with a specific variant const { orders } = await order.findByVariant('coll_123', 'var_456', { includeItems: true }) console.log(`Variant ${variantId} in ${orders.length} orders`) ```
+
+**findItemsByBatch**(collectionId: string,
+    batchId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items (not full orders) for a specific batch. Returns all matching items with optional order summary. ```typescript // Get items from a batch with order info const { items, count } = await order.findItemsByBatch('coll_123', 'BATCH-2024-001', { includeOrder: true, limit: 100 }) // Group by order status const byStatus = items.reduce((acc, item) => { const status = item.order?.status || 'unknown' acc[status] = (acc[status] || 0) + 1 return acc }, {}) ```
+
+**findItemsByProduct**(collectionId: string,
+    productId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items for a specific product. Returns all matching items with optional order summary. ```typescript // Get all items for a product const { items } = await order.findItemsByProduct('coll_123', 'prod_789', { includeOrder: true }) console.log(`Product delivered in ${items.length} order items`) ```
+
+**findItemsByVariant**(collectionId: string,
+    variantId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items for a specific variant. Returns all matching items with optional order summary. ```typescript // Get variant items with order details const { items, count } = await order.findItemsByVariant('coll_123', 'var_456', { includeOrder: true, limit: 50 }) ```
+
+**getOrderIdsByAttribute**(collectionId: string,
+    attribute: 'batchId' | 'productId' | 'variantId',
+    value: string,
+    params?: GetOrderIdsParams) → `Promise<GetOrderIdsResponse>`
+Get unique order IDs containing items matching the specified attribute. Lightweight query that only returns order IDs, not full order objects. ```typescript // Get order IDs for a batch (fast count) const { orderIds, count } = await order.getOrderIdsByAttribute( 'coll_123', 'batchId', 'BATCH-2024-001' ) console.log(`Batch appears in ${count} orders`) // Get order IDs for a product const productOrders = await order.getOrderIdsByAttribute( 'coll_123', 'productId', 'prod_789', { limit: 500 } ) ```
+
 ### product
 
 **get**(collectionId: string,

package/dist/types/batch.d.ts

@@ -1,12 +1,55 @@
+/**
+ * Firebase Timestamp object.
+ */
+export interface FirebaseTimestamp {
+    seconds: number;
+    nanoseconds?: number;
+}
 /**
  * Represents a Batch object.
  */
-export type BatchResponse = any;
+export interface BatchResponse {
+    id: string;
+    name?: string;
+    expiryDate?: FirebaseTimestamp | string;
+    productId?: string;
+    collectionId?: string;
+    [key: string]: any;
+}
 /**
  * Request payload for creating a new batch.
  */
-export type BatchCreateRequest = any;
+export interface BatchCreateRequest {
+    id: string;
+    name?: string;
+    expiryDate?: FirebaseTimestamp | string;
+    [key: string]: any;
+}
 /**
  * Request payload for updating an existing batch.
  */
-export type BatchUpdateRequest = any;
+export interface BatchUpdateRequest {
+    name?: string;
+    expiryDate?: FirebaseTimestamp | string;
+    [key: string]: any;
+}
+/**
+ * Query parameters for searching batches in a collection.
+ */
+export interface SearchBatchesRequest {
+    search?: string;
+    productId?: string;
+    limit?: number;
+}
+/**
+ * Tag/code assigned to a batch.
+ */
+export interface BatchTag {
+    code: string;
+    claimSetId: string;
+    collectionId?: string;
+    productId?: string;
+    batchId?: string;
+    tagId?: string;
+    index?: number;
+}

package/dist/types/order.d.ts

@@ -12,8 +12,23 @@ export interface OrderItem {
     orderId: string;
     itemType: 'tag' | 'proof' | 'serial';
     itemId: string;
+    collectionId?: string;
+    productId?: string;
+    variantId?: string | null;
+    batchId?: string | null;
     metadata: Record<string, any>;
     createdAt: string;
+    order?: OrderSummary;
+}
+/**
+ * Summary of order details (included with items when requested).
+ */
+export interface OrderSummary {
+    id: string;
+    orderRef?: string;
+    status: string;
+    customerId?: string;
+    createdAt: string;
 }
 /**
  * Represents an order containing multiple items.
@@ -241,6 +256,55 @@ export interface LookupByProductResponse {
     limit: number;
     offset: number;
 }
+/**
+ * Query parameters for finding orders by batch/product/variant.
+ */
+export interface FindOrdersByAttributeParams {
+    limit?: number;
+    offset?: number;
+    includeItems?: boolean;
+}
+/**
+ * Response from finding orders by batch/product/variant.
+ */
+export interface FindOrdersByAttributeResponse {
+    orders: Order[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Query parameters for finding items by batch/product/variant.
+ */
+export interface FindItemsByAttributeParams {
+    limit?: number;
+    offset?: number;
+    includeOrder?: boolean;
+}
+/**
+ * Response from finding items by batch/product/variant.
+ */
+export interface FindItemsByAttributeResponse {
+    items: OrderItem[];
+    count: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Query parameters for getting order IDs by attribute.
+ */
+export interface GetOrderIdsParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Response from getting order IDs by attribute.
+ */
+export interface GetOrderIdsResponse {
+    orderIds: string[];
+    count: number;
+    attribute: 'batchId' | 'productId' | 'variantId';
+    value: string;
+}
 /**
  * Summary of scans for a single tag.
  */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.20  |  Generated: 2026-02-08T14:25:23.483Z
+Version: 1.3.21  |  Generated: 2026-02-09T12:29:22.158Z
 
 This is a concise summary of all available API functions and types.
 
@@ -625,11 +625,66 @@ interface AuthKitConfig {
 
 ### batch
 
-**BatchResponse** = `any`
+**FirebaseTimestamp** (interface)
+```typescript
+interface FirebaseTimestamp {
+  seconds: number                 // Unix timestamp in seconds
+  nanoseconds?: number            // Nanoseconds component
+}
+```
+
+**BatchResponse** (interface)
+```typescript
+interface BatchResponse {
+  id: string                      // Batch ID
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  productId?: string              // Product ID (for collection-level searches)
+  collectionId?: string           // Collection ID
+  [key: string]: any              // Additional batch fields
+}
+```
 
-**BatchCreateRequest** = `any`
+**BatchCreateRequest** (interface)
+```typescript
+interface BatchCreateRequest {
+  id: string                      // Batch ID
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  [key: string]: any              // Additional batch fields
+}
+```
 
-**BatchUpdateRequest** = `any`
+**BatchUpdateRequest** (interface)
+```typescript
+interface BatchUpdateRequest {
+  name?: string                   // Batch name
+  expiryDate?: FirebaseTimestamp | string  // Firebase timestamp or ISO 8601 date
+  [key: string]: any              // Additional batch fields
+}
+```
+
+**SearchBatchesRequest** (interface)
+```typescript
+interface SearchBatchesRequest {
+  search?: string                 // Search term (batch ID or name)
+  productId?: string              // Filter by specific product
+  limit?: number                  // Max results (default: 100)
+}
+```
+
+**BatchTag** (interface)
+```typescript
+interface BatchTag {
+  code: string                    // Code/tag ID
+  claimSetId: string              // Claim set ID
+  collectionId?: string           // Collection ID
+  productId?: string              // Associated product ID
+  batchId?: string                // Batch ID
+  tagId?: string                  // Tag identifier
+  index?: number                  // Position in claim set
+}
+```
 
 ### broadcasts
 
@@ -2239,8 +2294,24 @@ interface OrderItem {
   orderId: string                   // Parent order ID
   itemType: 'tag' | 'proof' | 'serial' // Type of item
   itemId: string                    // The tag ID, proof ID, or serial number
+  collectionId?: string             // Collection ID
+  productId?: string                // Product ID
+  variantId?: string | null         // Variant ID
+  batchId?: string | null           // Batch ID
   metadata: Record<string, any>     // Item-specific metadata
   createdAt: string                 // ISO 8601 timestamp
+  order?: OrderSummary              // Optional order summary (when includeOrder=true)
+}
+```
+
+**OrderSummary** (interface)
+```typescript
+interface OrderSummary {
+  id: string                        // Order ID
+  orderRef?: string                 // Order reference
+  status: string                    // Order status
+  customerId?: string               // Customer ID
+  createdAt: string                 // ISO 8601 timestamp
 }
 ```
 
@@ -2463,6 +2534,61 @@ interface LookupByProductResponse {
 }
 ```
 
+**FindOrdersByAttributeParams** (interface)
+```typescript
+interface FindOrdersByAttributeParams {
+  limit?: number                    // Max results (default: 100)
+  offset?: number                   // Pagination offset (default: 0)
+  includeItems?: boolean            // Include items array (default: false)
+}
+```
+
+**FindOrdersByAttributeResponse** (interface)
+```typescript
+interface FindOrdersByAttributeResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
+**FindItemsByAttributeParams** (interface)
+```typescript
+interface FindItemsByAttributeParams {
+  limit?: number                    // Max results (default: 100)
+  offset?: number                   // Pagination offset (default: 0)
+  includeOrder?: boolean            // Include order summary (default: false)
+}
+```
+
+**FindItemsByAttributeResponse** (interface)
+```typescript
+interface FindItemsByAttributeResponse {
+  items: OrderItem[]
+  count: number
+  limit: number
+  offset: number
+}
+```
+
+**GetOrderIdsParams** (interface)
+```typescript
+interface GetOrderIdsParams {
+  limit?: number                    // Max results (default: 1000)
+  offset?: number                   // Pagination offset (default: 0)
+}
+```
+
+**GetOrderIdsResponse** (interface)
+```typescript
+interface GetOrderIdsResponse {
+  orderIds: string[]
+  count: number
+  attribute: 'batchId' | 'productId' | 'variantId'
+  value: string
+}
+```
+
 **TagScanSummary** (interface)
 ```typescript
 interface TagScanSummary {
@@ -3943,6 +4069,19 @@ Get serial numbers for a batch (admin only).
     codeId: string) → `Promise<any>`
 Look up a serial number by code for a batch (admin only).
 
+**searchInCollection**(collectionId: string,
+    params?: SearchBatchesRequest) → `Promise<BatchResponse[]>`
+Search for batches across all products in a collection. Allows searching by batch ID or name, with optional product filtering. ```typescript // Search for batches containing "2024" const batches = await batch.searchInCollection('coll_123', { search: 'BATCH-2024', limit: 50 }) // Filter batches for a specific product const productBatches = await batch.searchInCollection('coll_123', { productId: 'prod_abc', limit: 100 }) // Get all batches in collection const allBatches = await batch.searchInCollection('coll_123') // Check for expired batches batches.forEach(batch => { if (batch.expiryDate?.seconds) { const expiryDate = new Date(batch.expiryDate.seconds * 1000) if (expiryDate < new Date()) { console.log(`Batch ${batch.id} is expired`) } } }) ```
+
+**findInCollection**(collectionId: string,
+    batchId: string) → `Promise<BatchResponse>`
+Find a specific batch by ID across all products in a collection. Returns the batch along with the productId it belongs to. ```typescript // Find which product contains a specific batch const batch = await batch.findInCollection('coll_123', 'BATCH-2024-001') console.log(`Batch found in product: ${batch.productId}`) console.log(`Expires: ${batch.expiryDate}`) ```
+
+**getBatchTags**(collectionId: string,
+    batchId: string,
+    claimSetId?: string) → `Promise<BatchTag[]>`
+Get all tags/codes assigned to a specific batch. Shows which claim set codes have been assigned to this batch. ```typescript // Get all tags assigned to a batch const tags = await batch.getBatchTags('coll_123', 'BATCH-2024-001') console.log(`Batch has ${tags.length} tags assigned`) tags.forEach(tag => { console.log(`Code: ${tag.code}, ClaimSet: ${tag.claimSetId}, TagID: ${tag.tagId}`) }) // Get tags from a specific claim set const claimSetTags = await batch.getBatchTags('coll_123', 'BATCH-2024-001', '000001') ```
+
 ### broadcasts
 
 **create**(collectionId: string,
@@ -4444,6 +4583,42 @@ Get analytics summary for multiple orders at once. Efficient way to retrieve sca
     params?: SummaryRequest) → `Promise<CollectionSummaryResponse>`
 Get collection-wide analytics summary across all orders. Returns daily scan counts and admin activity overview. ```typescript // Get all-time collection summary const summary = await order.getCollectionSummary('coll_123') console.log(`Admin activity count: ${summary.adminActivity.count}`) console.log('Scans by day:') summary.scansByDay.forEach(day => { console.log(`  ${day.date}: ${day.scanCount} scans`) }) // Get summary for last 30 days const recentSummary = await order.getCollectionSummary('coll_123', { from: '2026-01-08T00:00:00Z', to: '2026-02-08T00:00:00Z' }) ```
 
+**findByBatch**(collectionId: string,
+    batchId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific batch. Uses indexed queries for fast lookups across order items. ```typescript // Find orders with items from a specific batch const { orders } = await order.findByBatch('coll_123', 'BATCH-2024-001', { includeItems: true, limit: 50 }) // Get unique customers who received this batch const customers = [...new Set(orders.map(o => o.customerId).filter(Boolean))] console.log(`Batch delivered to ${customers.length} customers`) ```
+
+**findOrdersByProduct**(collectionId: string,
+    productId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific product. Uses indexed queries for fast lookups across order items. ```typescript // Find all orders containing a product const { orders, limit, offset } = await order.findOrdersByProduct('coll_123', 'prod_789', { limit: 100 }) console.log(`Product appears in ${orders.length} orders`) ```
+
+**findByVariant**(collectionId: string,
+    variantId: string,
+    params?: FindOrdersByAttributeParams) → `Promise<FindOrdersByAttributeResponse>`
+Find all orders containing items from a specific variant. Uses indexed queries for fast lookups across order items. ```typescript // Find orders with a specific variant const { orders } = await order.findByVariant('coll_123', 'var_456', { includeItems: true }) console.log(`Variant ${variantId} in ${orders.length} orders`) ```
+
+**findItemsByBatch**(collectionId: string,
+    batchId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items (not full orders) for a specific batch. Returns all matching items with optional order summary. ```typescript // Get items from a batch with order info const { items, count } = await order.findItemsByBatch('coll_123', 'BATCH-2024-001', { includeOrder: true, limit: 100 }) // Group by order status const byStatus = items.reduce((acc, item) => { const status = item.order?.status || 'unknown' acc[status] = (acc[status] || 0) + 1 return acc }, {}) ```
+
+**findItemsByProduct**(collectionId: string,
+    productId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items for a specific product. Returns all matching items with optional order summary. ```typescript // Get all items for a product const { items } = await order.findItemsByProduct('coll_123', 'prod_789', { includeOrder: true }) console.log(`Product delivered in ${items.length} order items`) ```
+
+**findItemsByVariant**(collectionId: string,
+    variantId: string,
+    params?: FindItemsByAttributeParams) → `Promise<FindItemsByAttributeResponse>`
+Get individual order items for a specific variant. Returns all matching items with optional order summary. ```typescript // Get variant items with order details const { items, count } = await order.findItemsByVariant('coll_123', 'var_456', { includeOrder: true, limit: 50 }) ```
+
+**getOrderIdsByAttribute**(collectionId: string,
+    attribute: 'batchId' | 'productId' | 'variantId',
+    value: string,
+    params?: GetOrderIdsParams) → `Promise<GetOrderIdsResponse>`
+Get unique order IDs containing items matching the specified attribute. Lightweight query that only returns order IDs, not full order objects. ```typescript // Get order IDs for a batch (fast count) const { orderIds, count } = await order.getOrderIdsByAttribute( 'coll_123', 'batchId', 'BATCH-2024-001' ) console.log(`Batch appears in ${count} orders`) // Get order IDs for a product const productOrders = await order.getOrderIdsByAttribute( 'coll_123', 'productId', 'prod_789', { limit: 500 } ) ```
+
 ### product
 
 **get**(collectionId: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.3.20",
+  "version": "1.3.21",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",