@proveanything/smartlinks 1.3.17 → 1.3.18

package/dist/api/order.d.ts

@@ -1,4 +1,4 @@
-import { CreateOrderRequest, CreateOrderResponse, GetOrderResponse, UpdateOrderRequest, UpdateOrderResponse, DeleteOrderResponse, ListOrdersRequest, ListOrdersResponse, AddItemsRequest, AddItemsResponse, RemoveItemsRequest, RemoveItemsResponse, LookupOrdersRequest, LookupOrdersResponse } 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 } from "../types/order";
 /**
  * Order Management API
  *
@@ -34,20 +34,26 @@ export declare namespace order {
      */
     function create(collectionId: string, data: CreateOrderRequest): Promise<CreateOrderResponse>;
     /**
-     * Get a single order by ID with all its items.
+     * Get a single order by ID.
      *
      * @param collectionId - Identifier of the parent collection
      * @param orderId - Order ID
+     * @param params - Optional parameters (includeItems)
      * @returns Promise resolving to a GetOrderResponse object
      * @throws ErrorResponse if the request fails
      *
      * @example
      * ```typescript
+     * // Get order without items (faster)
      * const order = await order.get('coll_123', 'order_abc123')
      * console.log(`Order has ${order.itemCount} items`)
+     *
+     * // Get order with items
+     * const orderWithItems = await order.get('coll_123', 'order_abc123', { includeItems: true })
+     * console.log(orderWithItems.items) // Items array available
      * ```
      */
-    function get(collectionId: string, orderId: string): Promise<GetOrderResponse>;
+    function get(collectionId: string, orderId: string, params?: GetOrderParams): Promise<GetOrderResponse>;
     /**
      * Update order status or metadata.
      * Items are managed separately via addItems/removeItems.
@@ -95,7 +101,7 @@ export declare namespace order {
      *
      * @example
      * ```typescript
-     * // List all orders
+     * // List all orders (without items for better performance)
      * const all = await order.list('coll_123')
      *
      * // List with filters
@@ -105,13 +111,40 @@ export declare namespace order {
      *   offset: 0
      * })
      *
-     * // Filter by customer
+     * // Filter by customer with items
      * const customerOrders = await order.list('coll_123', {
-     *   customerId: 'CUST-789'
+     *   customerId: 'CUST-789',
+     *   includeItems: true
      * })
      * ```
      */
     function list(collectionId: string, params?: ListOrdersRequest): Promise<ListOrdersResponse>;
+    /**
+     * Get items from an order with pagination support.
+     * Use this for orders with many items instead of includeItems.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to a GetOrderItemsResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get first page of items
+     * const page1 = await order.getItems('coll_123', 'order_abc123', {
+     *   limit: 100,
+     *   offset: 0
+     * })
+     *
+     * // Get next page
+     * const page2 = await order.getItems('coll_123', 'order_abc123', {
+     *   limit: 100,
+     *   offset: 100
+     * })
+     * ```
+     */
+    function getItems(collectionId: string, orderId: string, params?: GetOrderItemsParams): Promise<GetOrderItemsResponse>;
     /**
      * Add additional items to an existing order.
      *
@@ -186,4 +219,99 @@ export declare namespace order {
      * ```
      */
     function lookup(collectionId: string, data: LookupOrdersRequest): Promise<LookupOrdersResponse>;
+    /**
+     * Advanced query for orders with date filtering, metadata search, and sorting.
+     * More powerful than the basic list() function.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Query parameters with filters, sorting, and pagination
+     * @returns Promise resolving to a QueryOrdersResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find pending orders created in January 2026
+     * const result = await order.query('coll_123', {
+     *   query: {
+     *     status: 'pending',
+     *     createdAfter: '2026-01-01T00:00:00Z',
+     *     createdBefore: '2026-02-01T00:00:00Z',
+     *     sortBy: 'createdAt',
+     *     sortOrder: 'desc'
+     *   },
+     *   limit: 50
+     * })
+     *
+     * // Find orders with specific metadata and item count
+     * const highPriority = await order.query('coll_123', {
+     *   query: {
+     *     metadata: { priority: 'high' },
+     *     minItemCount: 10,
+     *     maxItemCount: 100
+     *   },
+     *   includeItems: true
+     * })
+     * ```
+     */
+    function query(collectionId: string, data: QueryOrdersRequest): Promise<QueryOrdersResponse>;
+    /**
+     * Get reports and aggregations for orders.
+     * Provides analytics grouped by status, customer, product, date, etc.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Report parameters specifying grouping and filters
+     * @returns Promise resolving to a ReportsResponse with aggregated data
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get order counts by status
+     * const statusReport = await order.reports('coll_123', {
+     *   groupByStatus: true
+     * })
+     * console.log(statusReport.ordersByStatus)
+     * // { pending: 45, shipped: 123, completed: 789 }
+     *
+     * // Get comprehensive analytics
+     * const fullReport = await order.reports('coll_123', {
+     *   groupByStatus: true,
+     *   groupByProduct: true,
+     *   includeItemStats: true,
+     *   createdAfter: '2026-01-01T00:00:00Z'
+     * })
+     * console.log(fullReport.itemStats?.avgItemsPerOrder)
+     *
+     * // Get top 10 customers by order count
+     * const topCustomers = await order.reports('coll_123', {
+     *   groupByCustomer: true,
+     *   topN: 10
+     * })
+     * ```
+     */
+    function reports(collectionId: string, params?: ReportsParams): Promise<ReportsResponse>;
+    /**
+     * Find all orders containing items with a specific product ID.
+     * Uses the automatic productSummary tracking in order metadata.
+     *
+     * @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 LookupByProductResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find all orders with a specific product
+     * const result = await order.findByProduct('coll_123', 'product_abc123', {
+     *   limit: 50,
+     *   includeItems: false
+     * })
+     *
+     * result.orders.forEach(ord => {
+     *   const count = ord.metadata.productSummary?.['product_abc123'] ?? 0
+     *   console.log(`Order ${ord.orderRef} has ${count} items of this product`)
+     * })
+     * ```
+     */
+    function findByProduct(collectionId: string, productId: string, params?: LookupByProductParams): Promise<LookupByProductResponse>;
 }

package/dist/api/order.js

@@ -40,21 +40,31 @@ export var order;
     }
     order.create = create;
     /**
-     * Get a single order by ID with all its items.
+     * Get a single order by ID.
      *
      * @param collectionId - Identifier of the parent collection
      * @param orderId - Order ID
+     * @param params - Optional parameters (includeItems)
      * @returns Promise resolving to a GetOrderResponse object
      * @throws ErrorResponse if the request fails
      *
      * @example
      * ```typescript
+     * // Get order without items (faster)
      * const order = await order.get('coll_123', 'order_abc123')
      * console.log(`Order has ${order.itemCount} items`)
+     *
+     * // Get order with items
+     * const orderWithItems = await order.get('coll_123', 'order_abc123', { includeItems: true })
+     * console.log(orderWithItems.items) // Items array available
      * ```
      */
-    async function get(collectionId, orderId) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/${encodeURIComponent(orderId)}`;
+    async function get(collectionId, orderId, params) {
+        const queryParams = new URLSearchParams();
+        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/${encodeURIComponent(orderId)}${query ? `?${query}` : ''}`;
         return request(path);
     }
     order.get = get;
@@ -113,7 +123,7 @@ export var order;
      *
      * @example
      * ```typescript
-     * // List all orders
+     * // List all orders (without items for better performance)
      * const all = await order.list('coll_123')
      *
      * // List with filters
@@ -123,9 +133,10 @@ export var order;
      *   offset: 0
      * })
      *
-     * // Filter by customer
+     * // Filter by customer with items
      * const customerOrders = await order.list('coll_123', {
-     *   customerId: 'CUST-789'
+     *   customerId: 'CUST-789',
+     *   includeItems: true
      * })
      * ```
      */
@@ -141,11 +152,49 @@ export var order;
             queryParams.append('orderRef', params.orderRef);
         if (params === null || params === void 0 ? void 0 : params.customerId)
             queryParams.append('customerId', params.customerId);
+        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${query ? `?${query}` : ''}`;
         return request(path);
     }
     order.list = list;
+    /**
+     * Get items from an order with pagination support.
+     * Use this for orders with many items instead of includeItems.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to a GetOrderItemsResponse object
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get first page of items
+     * const page1 = await order.getItems('coll_123', 'order_abc123', {
+     *   limit: 100,
+     *   offset: 0
+     * })
+     *
+     * // Get next page
+     * const page2 = await order.getItems('coll_123', 'order_abc123', {
+     *   limit: 100,
+     *   offset: 100
+     * })
+     * ```
+     */
+    async function getItems(collectionId, orderId, 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/${encodeURIComponent(orderId)}/items${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.getItems = getItems;
     /**
      * Add additional items to an existing order.
      *
@@ -237,4 +286,145 @@ export var order;
         return post(path, data);
     }
     order.lookup = lookup;
+    /**
+     * Advanced query for orders with date filtering, metadata search, and sorting.
+     * More powerful than the basic list() function.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Query parameters with filters, sorting, and pagination
+     * @returns Promise resolving to a QueryOrdersResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find pending orders created in January 2026
+     * const result = await order.query('coll_123', {
+     *   query: {
+     *     status: 'pending',
+     *     createdAfter: '2026-01-01T00:00:00Z',
+     *     createdBefore: '2026-02-01T00:00:00Z',
+     *     sortBy: 'createdAt',
+     *     sortOrder: 'desc'
+     *   },
+     *   limit: 50
+     * })
+     *
+     * // Find orders with specific metadata and item count
+     * const highPriority = await order.query('coll_123', {
+     *   query: {
+     *     metadata: { priority: 'high' },
+     *     minItemCount: 10,
+     *     maxItemCount: 100
+     *   },
+     *   includeItems: true
+     * })
+     * ```
+     */
+    async function query(collectionId, data) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/query`;
+        return post(path, data);
+    }
+    order.query = query;
+    /**
+     * Get reports and aggregations for orders.
+     * Provides analytics grouped by status, customer, product, date, etc.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Report parameters specifying grouping and filters
+     * @returns Promise resolving to a ReportsResponse with aggregated data
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get order counts by status
+     * const statusReport = await order.reports('coll_123', {
+     *   groupByStatus: true
+     * })
+     * console.log(statusReport.ordersByStatus)
+     * // { pending: 45, shipped: 123, completed: 789 }
+     *
+     * // Get comprehensive analytics
+     * const fullReport = await order.reports('coll_123', {
+     *   groupByStatus: true,
+     *   groupByProduct: true,
+     *   includeItemStats: true,
+     *   createdAfter: '2026-01-01T00:00:00Z'
+     * })
+     * console.log(fullReport.itemStats?.avgItemsPerOrder)
+     *
+     * // Get top 10 customers by order count
+     * const topCustomers = await order.reports('coll_123', {
+     *   groupByCustomer: true,
+     *   topN: 10
+     * })
+     * ```
+     */
+    async function reports(collectionId, params) {
+        const queryParams = new URLSearchParams();
+        if (params === null || params === void 0 ? void 0 : params.groupByStatus)
+            queryParams.append('groupByStatus', 'true');
+        if (params === null || params === void 0 ? void 0 : params.groupByCollection)
+            queryParams.append('groupByCollection', 'true');
+        if (params === null || params === void 0 ? void 0 : params.groupByCustomer)
+            queryParams.append('groupByCustomer', 'true');
+        if (params === null || params === void 0 ? void 0 : params.groupByDate)
+            queryParams.append('groupByDate', 'true');
+        if (params === null || params === void 0 ? void 0 : params.groupByItemType)
+            queryParams.append('groupByItemType', 'true');
+        if (params === null || params === void 0 ? void 0 : params.groupByProduct)
+            queryParams.append('groupByProduct', 'true');
+        if (params === null || params === void 0 ? void 0 : params.includeItemStats)
+            queryParams.append('includeItemStats', 'true');
+        if ((params === null || params === void 0 ? void 0 : params.includeCount) !== undefined)
+            queryParams.append('includeCount', params.includeCount.toString());
+        if (params === null || params === void 0 ? void 0 : params.topN)
+            queryParams.append('topN', params.topN.toString());
+        if (params === null || params === void 0 ? void 0 : params.status)
+            queryParams.append('status', params.status);
+        if (params === null || params === void 0 ? void 0 : params.createdAfter)
+            queryParams.append('createdAfter', params.createdAfter);
+        if (params === null || params === void 0 ? void 0 : params.createdBefore)
+            queryParams.append('createdBefore', params.createdBefore);
+        const query = queryParams.toString();
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/reports${query ? `?${query}` : ''}`;
+        return request(path);
+    }
+    order.reports = reports;
+    /**
+     * Find all orders containing items with a specific product ID.
+     * Uses the automatic productSummary tracking in order metadata.
+     *
+     * @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 LookupByProductResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Find all orders with a specific product
+     * const result = await order.findByProduct('coll_123', 'product_abc123', {
+     *   limit: 50,
+     *   includeItems: false
+     * })
+     *
+     * result.orders.forEach(ord => {
+     *   const count = ord.metadata.productSummary?.['product_abc123'] ?? 0
+     *   console.log(`Order ${ord.orderRef} has ${count} items of this product`)
+     * })
+     * ```
+     */
+    async function findByProduct(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.findByProduct = findByProduct;
 })(order || (order = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.17  |  Generated: 2026-02-07T10:31:27.478Z
+Version: 1.3.18  |  Generated: 2026-02-07T16:00:44.350Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2186,8 +2186,11 @@ interface Order {
   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
+  metadata: {
+  productSummary?: Record<string, number>  // productId -> count (auto-maintained)
+  [key: string]: any              // Flexible additional data
+  }
+  items?: OrderItem[]               // Array of items (only when includeItems=true)
   createdAt: string                 // ISO 8601 timestamp
   updatedAt: string                 // ISO 8601 timestamp
 }
@@ -2208,6 +2211,13 @@ interface CreateOrderRequest {
 }
 ```
 
+**GetOrderParams** (interface)
+```typescript
+interface GetOrderParams {
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
 **UpdateOrderRequest** (interface)
 ```typescript
 interface UpdateOrderRequest {
@@ -2233,6 +2243,7 @@ interface ListOrdersRequest {
   status?: string                   // Optional: Filter by status
   orderRef?: string                 // Optional: Filter by order reference
   customerId?: string               // Optional: Filter by customer ID
+  includeItems?: boolean            // Optional: Include items array (default: false)
 }
 ```
 
@@ -2280,6 +2291,110 @@ interface LookupOrdersResponse {
 }
 ```
 
+**GetOrderItemsParams** (interface)
+```typescript
+interface GetOrderItemsParams {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+}
+```
+
+**GetOrderItemsResponse** (interface)
+```typescript
+interface GetOrderItemsResponse {
+  items: OrderItem[]
+  limit: number
+  offset: number
+}
+```
+
+**QueryOrdersRequest** (interface)
+```typescript
+interface QueryOrdersRequest {
+  query?: {
+  status?: string
+  orderRef?: string
+  customerId?: string
+  createdAfter?: string           // ISO 8601 date
+  createdBefore?: string          // ISO 8601 date
+  updatedAfter?: string           // ISO 8601 date
+  updatedBefore?: string          // ISO 8601 date
+  minItemCount?: number
+  maxItemCount?: number
+  metadata?: Record<string, any>
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
+  }
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
+**QueryOrdersResponse** (interface)
+```typescript
+interface QueryOrdersResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
+**ReportsParams** (interface)
+```typescript
+interface ReportsParams {
+  groupByStatus?: boolean
+  groupByCollection?: boolean
+  groupByCustomer?: boolean
+  groupByDate?: boolean
+  groupByItemType?: boolean
+  groupByProduct?: boolean
+  includeItemStats?: boolean
+  includeCount?: boolean            // default: true
+  topN?: number                     // for customer/product grouping (default: 10)
+  status?: string
+  createdAfter?: string             // ISO 8601 date
+  createdBefore?: string            // ISO 8601 date
+}
+```
+
+**ReportsResponse** (interface)
+```typescript
+interface ReportsResponse {
+  totalOrders?: number
+  ordersByStatus?: Record<string, number>
+  ordersByCollection?: Record<string, number>
+  ordersByCustomer?: Record<string, number>
+  ordersByDate?: Record<string, number>
+  itemsByType?: Record<string, number>
+  itemsByProduct?: Record<string, number>
+  itemStats?: {
+  totalItems: number
+  avgItemsPerOrder: number
+  maxItemsInOrder: number
+  minItemsInOrder: number
+  }
+}
+```
+
+**LookupByProductParams** (interface)
+```typescript
+interface LookupByProductParams {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
+**LookupByProductResponse** (interface)
+```typescript
+interface LookupByProductResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
 ### product
 
 **Product** (interface)
@@ -4013,8 +4128,9 @@ Lookup a tag by its ID (public). GET /public/nfc/findByTag/:tagId
 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`) ```
+    orderId: string,
+    params?: GetOrderParams) → `Promise<GetOrderResponse>`
+Get a single order by ID. ```typescript // Get order without items (faster) const order = await order.get('coll_123', 'order_abc123') console.log(`Order has ${order.itemCount} items`) // Get order with items const orderWithItems = await order.get('coll_123', 'order_abc123', { includeItems: true }) console.log(orderWithItems.items) // Items array available ```
 
 **update**(collectionId: string,
     orderId: string,
@@ -4027,7 +4143,12 @@ Delete an order and all its items (cascade delete). ```typescript await order.re
 
 **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' }) ```
+List orders for a collection with optional filters and pagination. Orders are returned in descending order by createdAt (newest first). ```typescript // List all orders (without items for better performance) 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 with items const customerOrders = await order.list('coll_123', { customerId: 'CUST-789', includeItems: true }) ```
+
+**getItems**(collectionId: string,
+    orderId: string,
+    params?: GetOrderItemsParams) → `Promise<GetOrderItemsResponse>`
+Get items from an order with pagination support. Use this for orders with many items instead of includeItems. ```typescript // Get first page of items const page1 = await order.getItems('coll_123', 'order_abc123', { limit: 100, offset: 0 }) // Get next page const page2 = await order.getItems('coll_123', 'order_abc123', { limit: 100, offset: 100 }) ```
 
 **addItems**(collectionId: string,
     orderId: string,
@@ -4043,6 +4164,19 @@ Remove specific items from an order. ```typescript const updated = await order.r
     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' } ] }) ```
 
+**query**(collectionId: string,
+    data: QueryOrdersRequest) → `Promise<QueryOrdersResponse>`
+Advanced query for orders with date filtering, metadata search, and sorting. More powerful than the basic list() function. ```typescript // Find pending orders created in January 2026 const result = await order.query('coll_123', { query: { status: 'pending', createdAfter: '2026-01-01T00:00:00Z', createdBefore: '2026-02-01T00:00:00Z', sortBy: 'createdAt', sortOrder: 'desc' }, limit: 50 }) // Find orders with specific metadata and item count const highPriority = await order.query('coll_123', { query: { metadata: { priority: 'high' }, minItemCount: 10, maxItemCount: 100 }, includeItems: true }) ```
+
+**reports**(collectionId: string,
+    params?: ReportsParams) → `Promise<ReportsResponse>`
+Get reports and aggregations for orders. Provides analytics grouped by status, customer, product, date, etc. ```typescript // Get order counts by status const statusReport = await order.reports('coll_123', { groupByStatus: true }) console.log(statusReport.ordersByStatus) // { pending: 45, shipped: 123, completed: 789 } // Get comprehensive analytics const fullReport = await order.reports('coll_123', { groupByStatus: true, groupByProduct: true, includeItemStats: true, createdAfter: '2026-01-01T00:00:00Z' }) console.log(fullReport.itemStats?.avgItemsPerOrder) // Get top 10 customers by order count const topCustomers = await order.reports('coll_123', { groupByCustomer: true, topN: 10 }) ```
+
+**findByProduct**(collectionId: string,
+    productId: string,
+    params?: LookupByProductParams) → `Promise<LookupByProductResponse>`
+Find all orders containing items with a specific product ID. Uses the automatic productSummary tracking in order metadata. ```typescript // Find all orders with a specific product const result = await order.findByProduct('coll_123', 'product_abc123', { limit: 50, includeItems: false }) result.orders.forEach(ord => { const count = ord.metadata.productSummary?.['product_abc123'] ?? 0 console.log(`Order ${ord.orderRef} has ${count} items of this product`) }) ```
+
 ### product
 
 **get**(collectionId: string,

package/dist/types/order.d.ts

@@ -26,8 +26,11 @@ export interface Order {
     customerId?: string;
     status: string;
     itemCount: number;
-    metadata: Record<string, any>;
-    items: OrderItem[];
+    metadata: {
+        productSummary?: Record<string, number>;
+        [key: string]: any;
+    };
+    items?: OrderItem[];
     createdAt: string;
     updatedAt: string;
 }
@@ -50,6 +53,12 @@ export interface CreateOrderRequest {
  */
 export interface CreateOrderResponse extends Order {
 }
+/**
+ * Query parameters for getting a single order.
+ */
+export interface GetOrderParams {
+    includeItems?: boolean;
+}
 /**
  * Response from getting a single order.
  */
@@ -85,6 +94,7 @@ export interface ListOrdersRequest {
     status?: string;
     orderRef?: string;
     customerId?: string;
+    includeItems?: boolean;
 }
 /**
  * Response from listing orders.
@@ -135,3 +145,99 @@ export interface LookupOrdersRequest {
 export interface LookupOrdersResponse {
     orders: Order[];
 }
+/**
+ * Query parameters for getting order items.
+ */
+export interface GetOrderItemsParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Response from getting order items.
+ */
+export interface GetOrderItemsResponse {
+    items: OrderItem[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Request for advanced order querying.
+ */
+export interface QueryOrdersRequest {
+    query?: {
+        status?: string;
+        orderRef?: string;
+        customerId?: string;
+        createdAfter?: string;
+        createdBefore?: string;
+        updatedAfter?: string;
+        updatedBefore?: string;
+        minItemCount?: number;
+        maxItemCount?: number;
+        metadata?: Record<string, any>;
+        sortBy?: string;
+        sortOrder?: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+    includeItems?: boolean;
+}
+/**
+ * Response from advanced order querying.
+ */
+export interface QueryOrdersResponse {
+    orders: Order[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Query parameters for order reports.
+ */
+export interface ReportsParams {
+    groupByStatus?: boolean;
+    groupByCollection?: boolean;
+    groupByCustomer?: boolean;
+    groupByDate?: boolean;
+    groupByItemType?: boolean;
+    groupByProduct?: boolean;
+    includeItemStats?: boolean;
+    includeCount?: boolean;
+    topN?: number;
+    status?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+}
+/**
+ * Response from order reports.
+ */
+export interface ReportsResponse {
+    totalOrders?: number;
+    ordersByStatus?: Record<string, number>;
+    ordersByCollection?: Record<string, number>;
+    ordersByCustomer?: Record<string, number>;
+    ordersByDate?: Record<string, number>;
+    itemsByType?: Record<string, number>;
+    itemsByProduct?: Record<string, number>;
+    itemStats?: {
+        totalItems: number;
+        avgItemsPerOrder: number;
+        maxItemsInOrder: number;
+        minItemsInOrder: number;
+    };
+}
+/**
+ * Query parameters for looking up orders by product.
+ */
+export interface LookupByProductParams {
+    limit?: number;
+    offset?: number;
+    includeItems?: boolean;
+}
+/**
+ * Response from looking up orders by product.
+ */
+export interface LookupByProductResponse {
+    orders: Order[];
+    limit: number;
+    offset: number;
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.17  |  Generated: 2026-02-07T10:31:27.478Z
+Version: 1.3.18  |  Generated: 2026-02-07T16:00:44.350Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2186,8 +2186,11 @@ interface Order {
   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
+  metadata: {
+  productSummary?: Record<string, number>  // productId -> count (auto-maintained)
+  [key: string]: any              // Flexible additional data
+  }
+  items?: OrderItem[]               // Array of items (only when includeItems=true)
   createdAt: string                 // ISO 8601 timestamp
   updatedAt: string                 // ISO 8601 timestamp
 }
@@ -2208,6 +2211,13 @@ interface CreateOrderRequest {
 }
 ```
 
+**GetOrderParams** (interface)
+```typescript
+interface GetOrderParams {
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
 **UpdateOrderRequest** (interface)
 ```typescript
 interface UpdateOrderRequest {
@@ -2233,6 +2243,7 @@ interface ListOrdersRequest {
   status?: string                   // Optional: Filter by status
   orderRef?: string                 // Optional: Filter by order reference
   customerId?: string               // Optional: Filter by customer ID
+  includeItems?: boolean            // Optional: Include items array (default: false)
 }
 ```
 
@@ -2280,6 +2291,110 @@ interface LookupOrdersResponse {
 }
 ```
 
+**GetOrderItemsParams** (interface)
+```typescript
+interface GetOrderItemsParams {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+}
+```
+
+**GetOrderItemsResponse** (interface)
+```typescript
+interface GetOrderItemsResponse {
+  items: OrderItem[]
+  limit: number
+  offset: number
+}
+```
+
+**QueryOrdersRequest** (interface)
+```typescript
+interface QueryOrdersRequest {
+  query?: {
+  status?: string
+  orderRef?: string
+  customerId?: string
+  createdAfter?: string           // ISO 8601 date
+  createdBefore?: string          // ISO 8601 date
+  updatedAfter?: string           // ISO 8601 date
+  updatedBefore?: string          // ISO 8601 date
+  minItemCount?: number
+  maxItemCount?: number
+  metadata?: Record<string, any>
+  sortBy?: string
+  sortOrder?: 'asc' | 'desc'
+  }
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
+**QueryOrdersResponse** (interface)
+```typescript
+interface QueryOrdersResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
+**ReportsParams** (interface)
+```typescript
+interface ReportsParams {
+  groupByStatus?: boolean
+  groupByCollection?: boolean
+  groupByCustomer?: boolean
+  groupByDate?: boolean
+  groupByItemType?: boolean
+  groupByProduct?: boolean
+  includeItemStats?: boolean
+  includeCount?: boolean            // default: true
+  topN?: number                     // for customer/product grouping (default: 10)
+  status?: string
+  createdAfter?: string             // ISO 8601 date
+  createdBefore?: string            // ISO 8601 date
+}
+```
+
+**ReportsResponse** (interface)
+```typescript
+interface ReportsResponse {
+  totalOrders?: number
+  ordersByStatus?: Record<string, number>
+  ordersByCollection?: Record<string, number>
+  ordersByCustomer?: Record<string, number>
+  ordersByDate?: Record<string, number>
+  itemsByType?: Record<string, number>
+  itemsByProduct?: Record<string, number>
+  itemStats?: {
+  totalItems: number
+  avgItemsPerOrder: number
+  maxItemsInOrder: number
+  minItemsInOrder: number
+  }
+}
+```
+
+**LookupByProductParams** (interface)
+```typescript
+interface LookupByProductParams {
+  limit?: number                    // Optional: Max results (default: 100)
+  offset?: number                   // Optional: Pagination offset (default: 0)
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
+**LookupByProductResponse** (interface)
+```typescript
+interface LookupByProductResponse {
+  orders: Order[]
+  limit: number
+  offset: number
+}
+```
+
 ### product
 
 **Product** (interface)
@@ -4013,8 +4128,9 @@ Lookup a tag by its ID (public). GET /public/nfc/findByTag/:tagId
 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`) ```
+    orderId: string,
+    params?: GetOrderParams) → `Promise<GetOrderResponse>`
+Get a single order by ID. ```typescript // Get order without items (faster) const order = await order.get('coll_123', 'order_abc123') console.log(`Order has ${order.itemCount} items`) // Get order with items const orderWithItems = await order.get('coll_123', 'order_abc123', { includeItems: true }) console.log(orderWithItems.items) // Items array available ```
 
 **update**(collectionId: string,
     orderId: string,
@@ -4027,7 +4143,12 @@ Delete an order and all its items (cascade delete). ```typescript await order.re
 
 **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' }) ```
+List orders for a collection with optional filters and pagination. Orders are returned in descending order by createdAt (newest first). ```typescript // List all orders (without items for better performance) 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 with items const customerOrders = await order.list('coll_123', { customerId: 'CUST-789', includeItems: true }) ```
+
+**getItems**(collectionId: string,
+    orderId: string,
+    params?: GetOrderItemsParams) → `Promise<GetOrderItemsResponse>`
+Get items from an order with pagination support. Use this for orders with many items instead of includeItems. ```typescript // Get first page of items const page1 = await order.getItems('coll_123', 'order_abc123', { limit: 100, offset: 0 }) // Get next page const page2 = await order.getItems('coll_123', 'order_abc123', { limit: 100, offset: 100 }) ```
 
 **addItems**(collectionId: string,
     orderId: string,
@@ -4043,6 +4164,19 @@ Remove specific items from an order. ```typescript const updated = await order.r
     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' } ] }) ```
 
+**query**(collectionId: string,
+    data: QueryOrdersRequest) → `Promise<QueryOrdersResponse>`
+Advanced query for orders with date filtering, metadata search, and sorting. More powerful than the basic list() function. ```typescript // Find pending orders created in January 2026 const result = await order.query('coll_123', { query: { status: 'pending', createdAfter: '2026-01-01T00:00:00Z', createdBefore: '2026-02-01T00:00:00Z', sortBy: 'createdAt', sortOrder: 'desc' }, limit: 50 }) // Find orders with specific metadata and item count const highPriority = await order.query('coll_123', { query: { metadata: { priority: 'high' }, minItemCount: 10, maxItemCount: 100 }, includeItems: true }) ```
+
+**reports**(collectionId: string,
+    params?: ReportsParams) → `Promise<ReportsResponse>`
+Get reports and aggregations for orders. Provides analytics grouped by status, customer, product, date, etc. ```typescript // Get order counts by status const statusReport = await order.reports('coll_123', { groupByStatus: true }) console.log(statusReport.ordersByStatus) // { pending: 45, shipped: 123, completed: 789 } // Get comprehensive analytics const fullReport = await order.reports('coll_123', { groupByStatus: true, groupByProduct: true, includeItemStats: true, createdAfter: '2026-01-01T00:00:00Z' }) console.log(fullReport.itemStats?.avgItemsPerOrder) // Get top 10 customers by order count const topCustomers = await order.reports('coll_123', { groupByCustomer: true, topN: 10 }) ```
+
+**findByProduct**(collectionId: string,
+    productId: string,
+    params?: LookupByProductParams) → `Promise<LookupByProductResponse>`
+Find all orders containing items with a specific product ID. Uses the automatic productSummary tracking in order metadata. ```typescript // Find all orders with a specific product const result = await order.findByProduct('coll_123', 'product_abc123', { limit: 50, includeItems: false }) result.orders.forEach(ord => { const count = ord.metadata.productSummary?.['product_abc123'] ?? 0 console.log(`Order ${ord.orderRef} has ${count} items of this product`) }) ```
+
 ### product
 
 **get**(collectionId: string,

package/package.json

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