@proveanything/smartlinks 1.3.18 → 1.3.20

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 } 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 } from "../types/order";
 /**
  * Order Management API
  *
@@ -314,4 +314,133 @@ export declare namespace order {
      * ```
      */
     function findByProduct(collectionId: string, productId: string, params?: LookupByProductParams): Promise<LookupByProductResponse>;
+    /**
+     * Get comprehensive scan analytics for all tags in an order.
+     * Returns scan counts, timestamps, locations, devices, and per-tag summaries.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @returns Promise resolving to an OrderAnalyticsResponse with scan analytics
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const analytics = await order.getAnalytics('coll_123', 'order_abc123')
+     *
+     * if (analytics.analytics) {
+     *   console.log(`Total scans: ${analytics.analytics.totalScans}`)
+     *   console.log(`Admin scans: ${analytics.analytics.adminScans}`)
+     *   console.log(`Created at: ${analytics.analytics.estimatedCreatedAt}`)
+     *   console.log(`Unique locations: ${analytics.analytics.uniqueLocations}`)
+     *
+     *   analytics.analytics.tagSummaries.forEach(tag => {
+     *     console.log(`Tag ${tag.tagId}: ${tag.totalScans} scans`)
+     *   })
+     * }
+     * ```
+     */
+    function getAnalytics(collectionId: string, orderId: string): Promise<OrderAnalyticsResponse>;
+    /**
+     * Get chronological timeline of all scan events for an order's tags.
+     * Supports filtering by date range and admin/customer scans.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional filters (limit, date range, isAdmin)
+     * @returns Promise resolving to a TimelineResponse with scan events
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all scan events
+     * const timeline = await order.getTimeline('coll_123', 'order_abc123')
+     *
+     * timeline.timeline.forEach(event => {
+     *   console.log(`${event.timestamp}: ${event.eventType} by ${event.isAdmin ? 'admin' : 'customer'}`)
+     * })
+     *
+     * // Get admin scans only from last week
+     * const adminScans = await order.getTimeline('coll_123', 'order_abc123', {
+     *   isAdmin: true,
+     *   from: '2026-02-01T00:00:00Z',
+     *   limit: 500
+     * })
+     * ```
+     */
+    function getTimeline(collectionId: string, orderId: string, params?: TimelineRequest): Promise<TimelineResponse>;
+    /**
+     * Get location-based scan history for an order's tags.
+     * Shows where the order's tags have been scanned.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional limit parameter
+     * @returns Promise resolving to a LocationResponse with location scans
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const locations = await order.getLocationHistory('coll_123', 'order_abc123', {
+     *   limit: 100
+     * })
+     *
+     * console.log(`Order scanned in ${locations.count} locations`)
+     * locations.locations.forEach(scan => {
+     *   console.log(`${scan.location} at ${scan.timestamp}`)
+     * })
+     * ```
+     */
+    function getLocationHistory(collectionId: string, orderId: string, params?: LocationRequest): Promise<LocationResponse>;
+    /**
+     * Get analytics summary for multiple orders at once.
+     * Efficient way to retrieve scan data for many orders.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Request with array of order IDs and optional date filters
+     * @returns Promise resolving to a BulkAnalyticsResponse with summaries
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const bulk = await order.getBulkAnalytics('coll_123', {
+     *   orderIds: ['order_1', 'order_2', 'order_3'],
+     *   from: '2026-01-01T00:00:00Z'
+     * })
+     *
+     * bulk.results.forEach(result => {
+     *   if (result.analytics) {
+     *     console.log(`${result.orderRef}: ${result.analytics.totalScans} scans`)
+     *   }
+     * })
+     * ```
+     */
+    function getBulkAnalytics(collectionId: string, data: BulkAnalyticsRequest): Promise<BulkAnalyticsResponse>;
+    /**
+     * Get collection-wide analytics summary across all orders.
+     * Returns daily scan counts and admin activity overview.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Optional date range filters
+     * @returns Promise resolving to a CollectionSummaryResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```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'
+     * })
+     * ```
+     */
+    function getCollectionSummary(collectionId: string, params?: SummaryRequest): Promise<CollectionSummaryResponse>;
 }

package/dist/api/order.js

@@ -427,4 +427,153 @@ export var order;
         return request(path);
     }
     order.findByProduct = findByProduct;
+    /**
+     * Get comprehensive scan analytics for all tags in an order.
+     * Returns scan counts, timestamps, locations, devices, and per-tag summaries.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @returns Promise resolving to an OrderAnalyticsResponse with scan analytics
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const analytics = await order.getAnalytics('coll_123', 'order_abc123')
+     *
+     * if (analytics.analytics) {
+     *   console.log(`Total scans: ${analytics.analytics.totalScans}`)
+     *   console.log(`Admin scans: ${analytics.analytics.adminScans}`)
+     *   console.log(`Created at: ${analytics.analytics.estimatedCreatedAt}`)
+     *   console.log(`Unique locations: ${analytics.analytics.uniqueLocations}`)
+     *
+     *   analytics.analytics.tagSummaries.forEach(tag => {
+     *     console.log(`Tag ${tag.tagId}: ${tag.totalScans} scans`)
+     *   })
+     * }
+     * ```
+     */
+    async function getAnalytics(collectionId, orderId) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/analytics/${encodeURIComponent(orderId)}`;
+        return post(path, {});
+    }
+    order.getAnalytics = getAnalytics;
+    /**
+     * Get chronological timeline of all scan events for an order's tags.
+     * Supports filtering by date range and admin/customer scans.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional filters (limit, date range, isAdmin)
+     * @returns Promise resolving to a TimelineResponse with scan events
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all scan events
+     * const timeline = await order.getTimeline('coll_123', 'order_abc123')
+     *
+     * timeline.timeline.forEach(event => {
+     *   console.log(`${event.timestamp}: ${event.eventType} by ${event.isAdmin ? 'admin' : 'customer'}`)
+     * })
+     *
+     * // Get admin scans only from last week
+     * const adminScans = await order.getTimeline('coll_123', 'order_abc123', {
+     *   isAdmin: true,
+     *   from: '2026-02-01T00:00:00Z',
+     *   limit: 500
+     * })
+     * ```
+     */
+    async function getTimeline(collectionId, orderId, params) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/analytics/${encodeURIComponent(orderId)}/timeline`;
+        return post(path, params || {});
+    }
+    order.getTimeline = getTimeline;
+    /**
+     * Get location-based scan history for an order's tags.
+     * Shows where the order's tags have been scanned.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param orderId - Order ID
+     * @param params - Optional limit parameter
+     * @returns Promise resolving to a LocationResponse with location scans
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const locations = await order.getLocationHistory('coll_123', 'order_abc123', {
+     *   limit: 100
+     * })
+     *
+     * console.log(`Order scanned in ${locations.count} locations`)
+     * locations.locations.forEach(scan => {
+     *   console.log(`${scan.location} at ${scan.timestamp}`)
+     * })
+     * ```
+     */
+    async function getLocationHistory(collectionId, orderId, params) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/analytics/${encodeURIComponent(orderId)}/locations`;
+        return post(path, params || {});
+    }
+    order.getLocationHistory = getLocationHistory;
+    /**
+     * Get analytics summary for multiple orders at once.
+     * Efficient way to retrieve scan data for many orders.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param data - Request with array of order IDs and optional date filters
+     * @returns Promise resolving to a BulkAnalyticsResponse with summaries
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```typescript
+     * const bulk = await order.getBulkAnalytics('coll_123', {
+     *   orderIds: ['order_1', 'order_2', 'order_3'],
+     *   from: '2026-01-01T00:00:00Z'
+     * })
+     *
+     * bulk.results.forEach(result => {
+     *   if (result.analytics) {
+     *     console.log(`${result.orderRef}: ${result.analytics.totalScans} scans`)
+     *   }
+     * })
+     * ```
+     */
+    async function getBulkAnalytics(collectionId, data) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/analytics/bulk`;
+        return post(path, data);
+    }
+    order.getBulkAnalytics = getBulkAnalytics;
+    /**
+     * Get collection-wide analytics summary across all orders.
+     * Returns daily scan counts and admin activity overview.
+     *
+     * @param collectionId - Identifier of the parent collection
+     * @param params - Optional date range filters
+     * @returns Promise resolving to a CollectionSummaryResponse
+     * @throws ErrorResponse if the request fails
+     *
+     * @example
+     * ```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'
+     * })
+     * ```
+     */
+    async function getCollectionSummary(collectionId, params) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/orders/analytics/summary`;
+        return post(path, params || {});
+    }
+    order.getCollectionSummary = getCollectionSummary;
 })(order || (order = {}));