@proveanything/smartlinks 1.3.18 → 1.3.19

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

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.18  |  Generated: 2026-02-07T16:00:44.350Z
+Version: 1.3.19  |  Generated: 2026-02-08T09:16:59.107Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2395,6 +2395,177 @@ interface LookupByProductResponse {
 }
 ```
 
+**TagScanSummary** (interface)
+```typescript
+interface TagScanSummary {
+  tagId: string
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string | null
+  earliestAdminScanAt: string | null
+}
+```
+
+**OrderAnalyticsResponse** (interface)
+```typescript
+interface OrderAnalyticsResponse {
+  orderRef: string
+  orderId: string
+  itemCount: number
+  tagCount: number
+  analytics: {
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string              // ISO 8601
+  latestScanAt: string                // ISO 8601
+  earliestAdminScanAt: string | null  // ISO 8601
+  earliestCustomerScanAt: string | null // ISO 8601
+  estimatedCreatedAt: string          // ISO 8601 - earliest admin scan or earliest scan
+  uniqueLocations: number
+  locations: string[]                 // Array of location strings
+  uniqueDevices: number
+  devices: string[]                   // Array of device types
+  eventTypes: string[]                // e.g., ["scan_tag", "verify_tag"]
+  tagSummaries: TagScanSummary[]
+  } | null                              // null if no tags found
+  message?: string                      // Only present if no tags found
+}
+```
+
+**TagScanEvent** (interface)
+```typescript
+interface TagScanEvent {
+  codeId: string
+  claimId: string
+  proofId: string | null
+  productId: string | null
+  variantId: string | null
+  batchId: string | null
+  collectionId: string
+  timestamp: string                     // ISO 8601
+  isAdmin: boolean
+  eventType: string | null              // e.g., "scan_tag"
+  location: string | null               // GPS coordinates or location string
+  location_accuracy: number | null
+  deviceType: string | null
+  ip: string | null
+  country: string | null
+  sessionId: string | null
+  metadata: Record<string, any> | null
+}
+```
+
+**TimelineRequest** (interface)
+```typescript
+interface TimelineRequest {
+  limit?: number                        // Max results (default: 1000)
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+  isAdmin?: boolean                     // Filter by admin scans only
+}
+```
+
+**TimelineResponse** (interface)
+```typescript
+interface TimelineResponse {
+  orderRef: string
+  orderId: string
+  timeline: TagScanEvent[]
+  count: number
+}
+```
+
+**LocationRequest** (interface)
+```typescript
+interface LocationRequest {
+  limit?: number                        // Max results (default: 1000)
+}
+```
+
+**LocationResponse** (interface)
+```typescript
+interface LocationResponse {
+  orderRef: string
+  orderId: string
+  locations: LocationScan[]
+  count: number
+}
+```
+
+**BulkAnalyticsRequest** (interface)
+```typescript
+interface BulkAnalyticsRequest {
+  orderIds: string[]                    // Array of order IDs
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+}
+```
+
+**OrderAnalyticsSummary** (interface)
+```typescript
+interface OrderAnalyticsSummary {
+  orderId: string
+  orderRef: string
+  analytics: {
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string | null
+  earliestAdminScanAt: string | null
+  estimatedCreatedAt: string | null
+  tagCount: number
+  tagSummaries: TagScanSummary[]
+  } | null
+}
+```
+
+**BulkAnalyticsResponse** (interface)
+```typescript
+interface BulkAnalyticsResponse {
+  results: OrderAnalyticsSummary[]
+}
+```
+
+**DailyScanCount** (interface)
+```typescript
+interface DailyScanCount {
+  date: string                          // YYYY-MM-DD
+  scanCount: number
+}
+```
+
+**AdminActivityEvent** (interface)
+```typescript
+interface AdminActivityEvent {
+  timestamp: string                     // ISO 8601
+  eventType: string
+  codeId: string
+}
+```
+
+**SummaryRequest** (interface)
+```typescript
+interface SummaryRequest {
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+}
+```
+
+**CollectionSummaryResponse** (interface)
+```typescript
+interface CollectionSummaryResponse {
+  adminActivity: {
+  count: number
+  recent: AdminActivityEvent[]        // Last 100 events
+  }
+  scansByDay: DailyScanCount[]
+  adminScansByDay: DailyScanCount[]
+  customerScansByDay: DailyScanCount[]
+}
+```
+
 ### product
 
 **Product** (interface)
@@ -4177,6 +4348,28 @@ Get reports and aggregations for orders. Provides analytics grouped by status, c
     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`) }) ```
 
+**getAnalytics**(collectionId: string,
+    orderId: string) → `Promise<OrderAnalyticsResponse>`
+Get comprehensive scan analytics for all tags in an order. Returns scan counts, timestamps, locations, devices, and per-tag summaries. ```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`) }) } ```
+
+**getTimeline**(collectionId: string,
+    orderId: string,
+    params?: TimelineRequest) → `Promise<TimelineResponse>`
+Get chronological timeline of all scan events for an order's tags. Supports filtering by date range and admin/customer scans. ```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 }) ```
+
+**getLocationHistory**(collectionId: string,
+    orderId: string,
+    params?: LocationRequest) → `Promise<LocationResponse>`
+Get location-based scan history for an order's tags. Shows where the order's tags have been scanned. ```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}`) }) ```
+
+**getBulkAnalytics**(collectionId: string,
+    data: BulkAnalyticsRequest) → `Promise<BulkAnalyticsResponse>`
+Get analytics summary for multiple orders at once. Efficient way to retrieve scan data for many orders. ```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`) } }) ```
+
+**getCollectionSummary**(collectionId: string,
+    params?: SummaryRequest) → `Promise<CollectionSummaryResponse>`
+Get collection-wide analytics summary across all orders. Returns daily scan counts and admin activity overview. ```typescript // Get all-time collection summary const summary = await order.getCollectionSummary('coll_123') console.log(`Admin activity count: ${summary.adminActivity.count}`) console.log('Scans by day:') summary.scansByDay.forEach(day => { console.log(`  ${day.date}: ${day.scanCount} scans`) }) // Get summary for last 30 days const recentSummary = await order.getCollectionSummary('coll_123', { from: '2026-01-08T00:00:00Z', to: '2026-02-08T00:00:00Z' }) ```
+
 ### product
 
 **get**(collectionId: string,

package/dist/types/order.d.ts

@@ -241,3 +241,165 @@ export interface LookupByProductResponse {
     limit: number;
     offset: number;
 }
+/**
+ * Summary of scans for a single tag.
+ */
+export interface TagScanSummary {
+    tagId: string;
+    totalScans: number;
+    adminScans: number;
+    customerScans: number;
+    earliestScanAt: string | null;
+    earliestAdminScanAt: string | null;
+}
+/**
+ * Complete analytics for an order.
+ */
+export interface OrderAnalyticsResponse {
+    orderRef: string;
+    orderId: string;
+    itemCount: number;
+    tagCount: number;
+    analytics: {
+        totalScans: number;
+        adminScans: number;
+        customerScans: number;
+        earliestScanAt: string;
+        latestScanAt: string;
+        earliestAdminScanAt: string | null;
+        earliestCustomerScanAt: string | null;
+        estimatedCreatedAt: string;
+        uniqueLocations: number;
+        locations: string[];
+        uniqueDevices: number;
+        devices: string[];
+        eventTypes: string[];
+        tagSummaries: TagScanSummary[];
+    } | null;
+    message?: string;
+}
+/**
+ * Individual scan event from timeline.
+ */
+export interface TagScanEvent {
+    codeId: string;
+    claimId: string;
+    proofId: string | null;
+    productId: string | null;
+    variantId: string | null;
+    batchId: string | null;
+    collectionId: string;
+    timestamp: string;
+    isAdmin: boolean;
+    eventType: string | null;
+    location: string | null;
+    location_accuracy: number | null;
+    deviceType: string | null;
+    ip: string | null;
+    country: string | null;
+    sessionId: string | null;
+    metadata: Record<string, any> | null;
+}
+/**
+ * Request for timeline analytics.
+ */
+export interface TimelineRequest {
+    limit?: number;
+    from?: string;
+    to?: string;
+    isAdmin?: boolean;
+}
+/**
+ * Response with scan timeline.
+ */
+export interface TimelineResponse {
+    orderRef: string;
+    orderId: string;
+    timeline: TagScanEvent[];
+    count: number;
+}
+/**
+ * Location-based scan event.
+ */
+export interface LocationScan extends TagScanEvent {
+}
+/**
+ * Request for location history.
+ */
+export interface LocationRequest {
+    limit?: number;
+}
+/**
+ * Response with location history.
+ */
+export interface LocationResponse {
+    orderRef: string;
+    orderId: string;
+    locations: LocationScan[];
+    count: number;
+}
+/**
+ * Request for bulk analytics.
+ */
+export interface BulkAnalyticsRequest {
+    orderIds: string[];
+    from?: string;
+    to?: string;
+}
+/**
+ * Summary analytics for a single order in bulk request.
+ */
+export interface OrderAnalyticsSummary {
+    orderId: string;
+    orderRef: string;
+    analytics: {
+        totalScans: number;
+        adminScans: number;
+        customerScans: number;
+        earliestScanAt: string | null;
+        earliestAdminScanAt: string | null;
+        estimatedCreatedAt: string | null;
+        tagCount: number;
+        tagSummaries: TagScanSummary[];
+    } | null;
+}
+/**
+ * Response from bulk analytics request.
+ */
+export interface BulkAnalyticsResponse {
+    results: OrderAnalyticsSummary[];
+}
+/**
+ * Daily scan count for summary analytics.
+ */
+export interface DailyScanCount {
+    date: string;
+    scanCount: number;
+}
+/**
+ * Admin activity event.
+ */
+export interface AdminActivityEvent {
+    timestamp: string;
+    eventType: string;
+    codeId: string;
+}
+/**
+ * Request for collection summary.
+ */
+export interface SummaryRequest {
+    from?: string;
+    to?: string;
+}
+/**
+ * Response with collection-wide analytics summary.
+ */
+export interface CollectionSummaryResponse {
+    adminActivity: {
+        count: number;
+        recent: AdminActivityEvent[];
+    };
+    scansByDay: DailyScanCount[];
+    adminScansByDay: DailyScanCount[];
+    customerScansByDay: DailyScanCount[];
+}

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.3.18  |  Generated: 2026-02-07T16:00:44.350Z
+Version: 1.3.19  |  Generated: 2026-02-08T09:16:59.107Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2395,6 +2395,177 @@ interface LookupByProductResponse {
 }
 ```
 
+**TagScanSummary** (interface)
+```typescript
+interface TagScanSummary {
+  tagId: string
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string | null
+  earliestAdminScanAt: string | null
+}
+```
+
+**OrderAnalyticsResponse** (interface)
+```typescript
+interface OrderAnalyticsResponse {
+  orderRef: string
+  orderId: string
+  itemCount: number
+  tagCount: number
+  analytics: {
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string              // ISO 8601
+  latestScanAt: string                // ISO 8601
+  earliestAdminScanAt: string | null  // ISO 8601
+  earliestCustomerScanAt: string | null // ISO 8601
+  estimatedCreatedAt: string          // ISO 8601 - earliest admin scan or earliest scan
+  uniqueLocations: number
+  locations: string[]                 // Array of location strings
+  uniqueDevices: number
+  devices: string[]                   // Array of device types
+  eventTypes: string[]                // e.g., ["scan_tag", "verify_tag"]
+  tagSummaries: TagScanSummary[]
+  } | null                              // null if no tags found
+  message?: string                      // Only present if no tags found
+}
+```
+
+**TagScanEvent** (interface)
+```typescript
+interface TagScanEvent {
+  codeId: string
+  claimId: string
+  proofId: string | null
+  productId: string | null
+  variantId: string | null
+  batchId: string | null
+  collectionId: string
+  timestamp: string                     // ISO 8601
+  isAdmin: boolean
+  eventType: string | null              // e.g., "scan_tag"
+  location: string | null               // GPS coordinates or location string
+  location_accuracy: number | null
+  deviceType: string | null
+  ip: string | null
+  country: string | null
+  sessionId: string | null
+  metadata: Record<string, any> | null
+}
+```
+
+**TimelineRequest** (interface)
+```typescript
+interface TimelineRequest {
+  limit?: number                        // Max results (default: 1000)
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+  isAdmin?: boolean                     // Filter by admin scans only
+}
+```
+
+**TimelineResponse** (interface)
+```typescript
+interface TimelineResponse {
+  orderRef: string
+  orderId: string
+  timeline: TagScanEvent[]
+  count: number
+}
+```
+
+**LocationRequest** (interface)
+```typescript
+interface LocationRequest {
+  limit?: number                        // Max results (default: 1000)
+}
+```
+
+**LocationResponse** (interface)
+```typescript
+interface LocationResponse {
+  orderRef: string
+  orderId: string
+  locations: LocationScan[]
+  count: number
+}
+```
+
+**BulkAnalyticsRequest** (interface)
+```typescript
+interface BulkAnalyticsRequest {
+  orderIds: string[]                    // Array of order IDs
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+}
+```
+
+**OrderAnalyticsSummary** (interface)
+```typescript
+interface OrderAnalyticsSummary {
+  orderId: string
+  orderRef: string
+  analytics: {
+  totalScans: number
+  adminScans: number
+  customerScans: number
+  earliestScanAt: string | null
+  earliestAdminScanAt: string | null
+  estimatedCreatedAt: string | null
+  tagCount: number
+  tagSummaries: TagScanSummary[]
+  } | null
+}
+```
+
+**BulkAnalyticsResponse** (interface)
+```typescript
+interface BulkAnalyticsResponse {
+  results: OrderAnalyticsSummary[]
+}
+```
+
+**DailyScanCount** (interface)
+```typescript
+interface DailyScanCount {
+  date: string                          // YYYY-MM-DD
+  scanCount: number
+}
+```
+
+**AdminActivityEvent** (interface)
+```typescript
+interface AdminActivityEvent {
+  timestamp: string                     // ISO 8601
+  eventType: string
+  codeId: string
+}
+```
+
+**SummaryRequest** (interface)
+```typescript
+interface SummaryRequest {
+  from?: string                         // ISO 8601 start date filter
+  to?: string                           // ISO 8601 end date filter
+}
+```
+
+**CollectionSummaryResponse** (interface)
+```typescript
+interface CollectionSummaryResponse {
+  adminActivity: {
+  count: number
+  recent: AdminActivityEvent[]        // Last 100 events
+  }
+  scansByDay: DailyScanCount[]
+  adminScansByDay: DailyScanCount[]
+  customerScansByDay: DailyScanCount[]
+}
+```
+
 ### product
 
 **Product** (interface)
@@ -4177,6 +4348,28 @@ Get reports and aggregations for orders. Provides analytics grouped by status, c
     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`) }) ```
 
+**getAnalytics**(collectionId: string,
+    orderId: string) → `Promise<OrderAnalyticsResponse>`
+Get comprehensive scan analytics for all tags in an order. Returns scan counts, timestamps, locations, devices, and per-tag summaries. ```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`) }) } ```
+
+**getTimeline**(collectionId: string,
+    orderId: string,
+    params?: TimelineRequest) → `Promise<TimelineResponse>`
+Get chronological timeline of all scan events for an order's tags. Supports filtering by date range and admin/customer scans. ```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 }) ```
+
+**getLocationHistory**(collectionId: string,
+    orderId: string,
+    params?: LocationRequest) → `Promise<LocationResponse>`
+Get location-based scan history for an order's tags. Shows where the order's tags have been scanned. ```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}`) }) ```
+
+**getBulkAnalytics**(collectionId: string,
+    data: BulkAnalyticsRequest) → `Promise<BulkAnalyticsResponse>`
+Get analytics summary for multiple orders at once. Efficient way to retrieve scan data for many orders. ```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`) } }) ```
+
+**getCollectionSummary**(collectionId: string,
+    params?: SummaryRequest) → `Promise<CollectionSummaryResponse>`
+Get collection-wide analytics summary across all orders. Returns daily scan counts and admin activity overview. ```typescript // Get all-time collection summary const summary = await order.getCollectionSummary('coll_123') console.log(`Admin activity count: ${summary.adminActivity.count}`) console.log('Scans by day:') summary.scansByDay.forEach(day => { console.log(`  ${day.date}: ${day.scanCount} scans`) }) // Get summary for last 30 days const recentSummary = await order.getCollectionSummary('coll_123', { from: '2026-01-08T00:00:00Z', to: '2026-02-08T00:00:00Z' }) ```
+
 ### product
 
 **get**(collectionId: string,

package/package.json

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