@proveanything/smartlinks 1.3.19 → 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/crate.d.ts

@@ -1,22 +1,111 @@
+import { GetCrateResponse, CreateCrateRequest, CreateCrateResponse, UpdateCrateRequest, UpdateCrateResponse, DeleteCrateResponse, ListCratesRequest, ListCratesResponse } from "../types/crate";
+/**
+ * Crate Management API
+ *
+ * Manage crates (containers for tags/products) within collections.
+ */
 export declare namespace crate {
     /**
-     * Get a single crate by ID for a collection (admin only).
+     * List crates for a collection with pagination support.
+     * Returns crates in pages, with support for soft-deleted crates.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Optional query parameters for pagination and filtering
+     * @returns Promise resolving to a ListCratesResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await crate.list('coll_123', { limit: 100 })
+     * console.log(`Found ${page1.items.length} crates`)
+     *
+     * // Get next page
+     * if (page1.hasMore) {
+     *   const page2 = await crate.list('coll_123', {
+     *     limit: 100,
+     *     startAfter: page1.lastId
+     *   })
+     * }
+     *
+     * // Include soft-deleted crates
+     * const withDeleted = await crate.list('coll_123', {
+     *   includeDeleted: true
+     * })
+     * ```
      */
-    function get(collectionId: string, crateId: string): Promise<any>;
+    function list(collectionId: string, params?: ListCratesRequest): Promise<ListCratesResponse>;
     /**
-     * List all crates for a collection (admin only).
+     * Get a single crate by ID for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @returns Promise resolving to a GetCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const crate = await crate.get('coll_123', 'crate_abc123')
+     * console.log(`Crate has ${crate.items?.length ?? 0} items`)
+     * ```
      */
-    function list(collectionId: string): Promise<any[]>;
+    function get(collectionId: string, crateId: string): Promise<GetCrateResponse>;
     /**
      * Create a new crate for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Crate creation data
+     * @returns Promise resolving to a CreateCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const newCrate = await crate.create('coll_123', {
+     *   items: [
+     *     {
+     *       id: 'tag_001',
+     *       codeId: 'ABC123',
+     *       productId: 'prod_1',
+     *       productName: 'Product Name'
+     *     }
+     *   ]
+     * })
+     * console.log(`Created crate ${newCrate.id}`)
+     * ```
      */
-    function create(collectionId: string, data: any): Promise<any>;
+    function create(collectionId: string, data: CreateCrateRequest): Promise<CreateCrateResponse>;
     /**
      * Update a crate for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @param data - Update data
+     * @returns Promise resolving to an UpdateCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const updated = await crate.update('coll_123', 'crate_abc123', {
+     *   items: [
+     *     { id: 'tag_002', codeId: 'XYZ789', productId: 'prod_2' }
+     *   ]
+     * })
+     * ```
      */
-    function update(collectionId: string, crateId: string, data: any): Promise<any>;
+    function update(collectionId: string, crateId: string, data: UpdateCrateRequest): Promise<UpdateCrateResponse>;
     /**
      * Delete a crate for a collection (admin only).
+     * This performs a soft delete.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @returns Promise resolving to a DeleteCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * await crate.remove('coll_123', 'crate_abc123')
+     * ```
      */
-    function remove(collectionId: string, crateId: string): Promise<void>;
+    function remove(collectionId: string, crateId: string): Promise<DeleteCrateResponse>;
 }

package/dist/api/crate.js

@@ -1,24 +1,94 @@
 import { request, post, put, del } from "../http";
+/**
+ * Crate Management API
+ *
+ * Manage crates (containers for tags/products) within collections.
+ */
 export var crate;
 (function (crate) {
     /**
-     * Get a single crate by ID for a collection (admin only).
+     * List crates for a collection with pagination support.
+     * Returns crates in pages, with support for soft-deleted crates.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Optional query parameters for pagination and filtering
+     * @returns Promise resolving to a ListCratesResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await crate.list('coll_123', { limit: 100 })
+     * console.log(`Found ${page1.items.length} crates`)
+     *
+     * // Get next page
+     * if (page1.hasMore) {
+     *   const page2 = await crate.list('coll_123', {
+     *     limit: 100,
+     *     startAfter: page1.lastId
+     *   })
+     * }
+     *
+     * // Include soft-deleted crates
+     * const withDeleted = await crate.list('coll_123', {
+     *   includeDeleted: true
+     * })
+     * ```
      */
-    async function get(collectionId, crateId) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate/${encodeURIComponent(crateId)}`;
+    async function list(collectionId, 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.startAfter)
+            queryParams.append('startAfter', params.startAfter);
+        if (params === null || params === void 0 ? void 0 : params.includeDeleted)
+            queryParams.append('includeDeleted', 'true');
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate${query ? `?${query}` : ''}`;
         return request(path);
     }
-    crate.get = get;
+    crate.list = list;
     /**
-     * List all crates for a collection (admin only).
+     * Get a single crate by ID for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @returns Promise resolving to a GetCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const crate = await crate.get('coll_123', 'crate_abc123')
+     * console.log(`Crate has ${crate.items?.length ?? 0} items`)
+     * ```
      */
-    async function list(collectionId) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate`;
+    async function get(collectionId, crateId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate/${encodeURIComponent(crateId)}`;
         return request(path);
     }
-    crate.list = list;
+    crate.get = get;
     /**
      * Create a new crate for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Crate creation data
+     * @returns Promise resolving to a CreateCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const newCrate = await crate.create('coll_123', {
+     *   items: [
+     *     {
+     *       id: 'tag_001',
+     *       codeId: 'ABC123',
+     *       productId: 'prod_1',
+     *       productName: 'Product Name'
+     *     }
+     *   ]
+     * })
+     * console.log(`Created crate ${newCrate.id}`)
+     * ```
      */
     async function create(collectionId, data) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate`;
@@ -27,6 +97,21 @@ export var crate;
     crate.create = create;
     /**
      * Update a crate for a collection (admin only).
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @param data - Update data
+     * @returns Promise resolving to an UpdateCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const updated = await crate.update('coll_123', 'crate_abc123', {
+     *   items: [
+     *     { id: 'tag_002', codeId: 'XYZ789', productId: 'prod_2' }
+     *   ]
+     * })
+     * ```
      */
     async function update(collectionId, crateId, data) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate/${encodeURIComponent(crateId)}`;
@@ -35,6 +120,17 @@ export var crate;
     crate.update = update;
     /**
      * Delete a crate for a collection (admin only).
+     * This performs a soft delete.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param crateId - Crate ID
+     * @returns Promise resolving to a DeleteCrateResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * await crate.remove('coll_123', 'crate_abc123')
+     * ```
      */
     async function remove(collectionId, crateId) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/crate/${encodeURIComponent(crateId)}`;

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>;
 }