@proveanything/smartlinks 1.3.16 → 1.3.18

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 = {}));