@proveanything/smartlinks 1.7.8 → 1.7.10

package/dist/api/order.d.ts

@@ -252,13 +252,22 @@ export declare namespace order {
      *   includeItems: true
      * })
      *
-     * // Find orders containing a specific product batch
+    * // Find orders containing a specific product batch
      * const batchOrders = await order.query('coll_123', {
      *   query: {
-     *     item: {
-     *       productId: 'prod_789',
-     *       batchId: 'BATCH-2024-001'
-     *     }
+    *     productId: 'prod_789',
+    *     batchId: 'BATCH-2024-001'
+    *   },
+    *   includeItems: true
+    * })
+    *
+    * // Find an order containing one of several specific items
+    * const matched = await order.query('coll_123', {
+    *   query: {
+    *     items: [
+    *       { itemType: 'tag', itemId: 'TAG001' },
+    *       { itemType: 'serial', itemId: 'SN12345' }
+    *     ]
      *   },
      *   includeItems: true
      * })

package/dist/api/order.js

@@ -287,9 +287,11 @@ export var order;
     }
     order.lookup = lookup;
     function validateOrderQuery(data) {
-        var _a;
-        if (((_a = data.query) === null || _a === void 0 ? void 0 : _a.item) && !data.query.item.productId) {
-            throw new Error('query.item.productId is required when using item-level order filters');
+        const query = data.query;
+        if (!query)
+            return;
+        if ((query.batchId || query.variantId) && !query.productId) {
+            throw new Error('query.productId is required when using query.batchId or query.variantId');
         }
     }
     /**
@@ -325,13 +327,22 @@ export var order;
      *   includeItems: true
      * })
      *
-     * // Find orders containing a specific product batch
+    * // Find orders containing a specific product batch
      * const batchOrders = await order.query('coll_123', {
      *   query: {
-     *     item: {
-     *       productId: 'prod_789',
-     *       batchId: 'BATCH-2024-001'
-     *     }
+    *     productId: 'prod_789',
+    *     batchId: 'BATCH-2024-001'
+    *   },
+    *   includeItems: true
+    * })
+    *
+    * // Find an order containing one of several specific items
+    * const matched = await order.query('coll_123', {
+    *   query: {
+    *     items: [
+    *       { itemType: 'tag', itemId: 'TAG001' },
+    *       { itemType: 'serial', itemId: 'SN12345' }
+    *     ]
      *   },
      *   includeItems: true
      * })

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.7.8  |  Generated: 2026-03-12T16:18:35.207Z
+Version: 1.7.10  |  Generated: 2026-03-12T18:05:02.102Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4503,38 +4503,34 @@ interface GetOrderItemsResponse {
 }
 ```
 
-**QueryOrderItemFilter** (interface)
-```typescript
-interface QueryOrderItemFilter {
-  productId: string
-  batchId?: string
-  variantId?: string
-}
-```
-
-**QueryOrdersFilter** (interface)
+**QueryOrdersRequest** (interface)
 ```typescript
-interface QueryOrdersFilter {
+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
+  createdAfter?: string           // ISO 8601 date
+  createdBefore?: string          // ISO 8601 date
+  updatedAfter?: string           // ISO 8601 date
+  updatedBefore?: string          // ISO 8601 date
   minItemCount?: number
   maxItemCount?: number
+  productId?: string
+  batchId?: string
+  variantId?: string
+  itemType?: 'tag' | 'proof' | 'serial'
+  itemId?: string
+  itemCollectionId?: string
+  itemMetadata?: Record<string, any>
+  items?: Array<{
+  itemType: 'tag' | 'proof' | 'serial'
+  itemId: string
+  }>
   metadata?: Record<string, any>
-  item?: QueryOrderItemFilter
   sortBy?: string
   sortOrder?: 'asc' | 'desc'
-}
-```
-
-**QueryOrdersRequest** (interface)
-```typescript
-interface QueryOrdersRequest {
-  query?: QueryOrdersFilter
+  }
   limit?: number                    // Optional: Max results (default: 100)
   offset?: number                   // Optional: Pagination offset (default: 0)
   includeItems?: boolean            // Optional: Include items array (default: false)
@@ -6430,7 +6426,7 @@ Find all orders containing specific items (tags, proofs, or serial numbers). Use
 
 **query**(collectionId: string,
     data: QueryOrdersRequest) → `Promise<QueryOrdersResponse>`
-Advanced query for orders with order-level and item-level filtering. 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 }) // Find orders containing a specific product batch const batchOrders = await order.query('coll_123', { query: { item: { productId: 'prod_789', batchId: 'BATCH-2024-001' } }, includeItems: true }) ```
+Advanced query for orders with order-level and item-level filtering. 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 }) // Find orders containing a specific product batch const batchOrders = await order.query('coll_123', { query: { productId: 'prod_789', batchId: 'BATCH-2024-001' }, includeItems: true }) // Find an order containing one of several specific items const matched = await order.query('coll_123', { query: { items: [ { itemType: 'tag', itemId: 'TAG001' }, { itemType: 'serial', itemId: 'SN12345' } ] }, includeItems: true }) ```
 
 **reports**(collectionId: string,
     params?: ReportsParams) → `Promise<ReportsResponse>`

package/dist/docs/ai.md

@@ -349,8 +349,11 @@ if (toolCall) {
 const models = await ai.models.list('my-collection');
 
 // Or filter by provider / capability
-const googleVisionModels = await ai.models.list('my-collection', {
-  provider: 'google',
+const openAiModels = await ai.models.list('my-collection', {
+  provider: 'openai'
+});
+
+const visionModels = await ai.models.list('my-collection', {
   capability: 'vision'
 });
 
@@ -366,13 +369,18 @@ const model = await ai.models.get('my-collection', 'google/gemini-2.5-flash');
 console.log(model.capabilities); // ['text', 'vision', 'audio', 'code']
 ```
 
+Use `ai.models.list(collectionId)` as the source of truth for what your collection can use at runtime. The public docs provide recommendations, but actual availability depends on the SmartLinks model catalog exposed to that collection.
+
 **Recommended Models:**
 
 | Model | Use Case | Speed | Cost |
 |-------|----------|-------|------|
-| `google/gemini-2.5-flash-lite` | Simple Q&A | Fastest | Lowest |
-| `google/gemini-2.5-flash` | General purpose | Fast | Low |
-| `google/gemini-2.5-pro` | Complex reasoning | Slower | Higher |
+| `openai/gpt-5.4` | Default for new agentic and structured-output workflows | Balanced | Medium |
+| `openai/gpt-5-mini` | Lower-cost general purpose and JSON tasks | Fast | Low |
+| `google/gemini-2.5-flash` | Fast multimodal and cost-sensitive general use | Fast | Low |
+| `google/gemini-2.5-pro` | Complex reasoning and heavier multimodal tasks | Slower | Higher |
+
+If you want a safe default for most new work, start with `openai/gpt-5.4`. If you want a lower-cost fallback, use `openai/gpt-5-mini` or `google/gemini-2.5-flash` depending on your latency and pricing goals.
 
 ---
 
@@ -1577,23 +1585,27 @@ console.log('Rate limit reset for user-123');
 ### 1. Choose the Right Model
 
 ```typescript
-// For simple Q&A (fast, cheap)
-await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash-lite',
-  messages: [...]
+// For most new workflows (recommended default)
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5.4',
+  input: 'Create a concise onboarding checklist.'
 });
 
-// For general use (balanced)
-await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [...]
+// For lower-cost structured or JSON-oriented work
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5-mini',
+  input: 'Return a color palette as JSON.'
 });
 
-// For complex reasoning (powerful)
+// For fast multimodal or cost-sensitive general use
 await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-pro',
+  model: 'google/gemini-2.5-flash',
   messages: [...]
 });
+
+// When you need the actual available catalog for this collection
+const available = await ai.models.list('my-collection');
+console.log(available.data.map(model => model.id));
 ```
 
 ### 2. Use Streaming for Long Responses

package/dist/openapi.yaml

@@ -15881,20 +15881,12 @@ components:
         - items
         - limit
         - offset
-    QueryOrderItemFilter:
-      type: object
-      properties:
-        productId:
-          type: string
-        batchId:
-          type: string
-        variantId:
-          type: string
-      required:
-        - productId
-    QueryOrdersFilter:
+    QueryOrdersRequest:
       type: object
       properties:
+        query:
+          type: object
+          additionalProperties: true
         status:
           type: string
         orderRef:
@@ -15913,11 +15905,31 @@ components:
           type: number
         maxItemCount:
           type: number
+        productId:
+          type: string
+        batchId:
+          type: string
+        variantId:
+          type: string
+        itemType:
+          type: string
+          enum:
+            - tag
+            - proof
+            - serial
+        itemId:
+          type: string
+        itemCollectionId:
+          type: string
+        itemMetadata:
+          type: object
+          additionalProperties: true
+        items:
+          type: object
+          additionalProperties: true
         metadata:
           type: object
           additionalProperties: true
-        item:
-          $ref: "#/components/schemas/QueryOrderItemFilter"
         sortBy:
           type: string
         sortOrder:
@@ -15925,17 +15937,15 @@ components:
           enum:
             - asc
             - desc
-    QueryOrdersRequest:
-      type: object
-      properties:
-        query:
-          $ref: "#/components/schemas/QueryOrdersFilter"
         limit:
           type: number
         offset:
           type: number
         includeItems:
           type: boolean
+      required:
+        - itemType
+        - itemId
     QueryOrdersResponse:
       type: object
       properties:

package/dist/types/order.d.ts

@@ -175,38 +175,35 @@ export interface GetOrderItemsResponse {
     limit: number;
     offset: number;
 }
-/**
- * Item-level filters for advanced order querying.
- * Batch and variant identifiers are only meaningful within a product.
- */
-export interface QueryOrderItemFilter {
-    productId: string;
-    batchId?: string;
-    variantId?: string;
-}
-/**
- * Order-level and item-level filters for advanced order querying.
- */
-export interface QueryOrdersFilter {
-    status?: string;
-    orderRef?: string;
-    customerId?: string;
-    createdAfter?: string;
-    createdBefore?: string;
-    updatedAfter?: string;
-    updatedBefore?: string;
-    minItemCount?: number;
-    maxItemCount?: number;
-    metadata?: Record<string, any>;
-    item?: QueryOrderItemFilter;
-    sortBy?: string;
-    sortOrder?: 'asc' | 'desc';
-}
 /**
  * Request for advanced order querying.
  */
 export interface QueryOrdersRequest {
-    query?: QueryOrdersFilter;
+    query?: {
+        status?: string;
+        orderRef?: string;
+        customerId?: string;
+        createdAfter?: string;
+        createdBefore?: string;
+        updatedAfter?: string;
+        updatedBefore?: string;
+        minItemCount?: number;
+        maxItemCount?: number;
+        productId?: string;
+        batchId?: string;
+        variantId?: string;
+        itemType?: 'tag' | 'proof' | 'serial';
+        itemId?: string;
+        itemCollectionId?: string;
+        itemMetadata?: Record<string, any>;
+        items?: Array<{
+            itemType: 'tag' | 'proof' | 'serial';
+            itemId: string;
+        }>;
+        metadata?: Record<string, any>;
+        sortBy?: string;
+        sortOrder?: 'asc' | 'desc';
+    };
     limit?: number;
     offset?: number;
     includeItems?: boolean;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.7.8  |  Generated: 2026-03-12T16:18:35.207Z
+Version: 1.7.10  |  Generated: 2026-03-12T18:05:02.102Z
 
 This is a concise summary of all available API functions and types.
 
@@ -4503,38 +4503,34 @@ interface GetOrderItemsResponse {
 }
 ```
 
-**QueryOrderItemFilter** (interface)
-```typescript
-interface QueryOrderItemFilter {
-  productId: string
-  batchId?: string
-  variantId?: string
-}
-```
-
-**QueryOrdersFilter** (interface)
+**QueryOrdersRequest** (interface)
 ```typescript
-interface QueryOrdersFilter {
+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
+  createdAfter?: string           // ISO 8601 date
+  createdBefore?: string          // ISO 8601 date
+  updatedAfter?: string           // ISO 8601 date
+  updatedBefore?: string          // ISO 8601 date
   minItemCount?: number
   maxItemCount?: number
+  productId?: string
+  batchId?: string
+  variantId?: string
+  itemType?: 'tag' | 'proof' | 'serial'
+  itemId?: string
+  itemCollectionId?: string
+  itemMetadata?: Record<string, any>
+  items?: Array<{
+  itemType: 'tag' | 'proof' | 'serial'
+  itemId: string
+  }>
   metadata?: Record<string, any>
-  item?: QueryOrderItemFilter
   sortBy?: string
   sortOrder?: 'asc' | 'desc'
-}
-```
-
-**QueryOrdersRequest** (interface)
-```typescript
-interface QueryOrdersRequest {
-  query?: QueryOrdersFilter
+  }
   limit?: number                    // Optional: Max results (default: 100)
   offset?: number                   // Optional: Pagination offset (default: 0)
   includeItems?: boolean            // Optional: Include items array (default: false)
@@ -6430,7 +6426,7 @@ Find all orders containing specific items (tags, proofs, or serial numbers). Use
 
 **query**(collectionId: string,
     data: QueryOrdersRequest) → `Promise<QueryOrdersResponse>`
-Advanced query for orders with order-level and item-level filtering. 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 }) // Find orders containing a specific product batch const batchOrders = await order.query('coll_123', { query: { item: { productId: 'prod_789', batchId: 'BATCH-2024-001' } }, includeItems: true }) ```
+Advanced query for orders with order-level and item-level filtering. 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 }) // Find orders containing a specific product batch const batchOrders = await order.query('coll_123', { query: { productId: 'prod_789', batchId: 'BATCH-2024-001' }, includeItems: true }) // Find an order containing one of several specific items const matched = await order.query('coll_123', { query: { items: [ { itemType: 'tag', itemId: 'TAG001' }, { itemType: 'serial', itemId: 'SN12345' } ] }, includeItems: true }) ```
 
 **reports**(collectionId: string,
     params?: ReportsParams) → `Promise<ReportsResponse>`

package/docs/ai.md

@@ -349,8 +349,11 @@ if (toolCall) {
 const models = await ai.models.list('my-collection');
 
 // Or filter by provider / capability
-const googleVisionModels = await ai.models.list('my-collection', {
-  provider: 'google',
+const openAiModels = await ai.models.list('my-collection', {
+  provider: 'openai'
+});
+
+const visionModels = await ai.models.list('my-collection', {
   capability: 'vision'
 });
 
@@ -366,13 +369,18 @@ const model = await ai.models.get('my-collection', 'google/gemini-2.5-flash');
 console.log(model.capabilities); // ['text', 'vision', 'audio', 'code']
 ```
 
+Use `ai.models.list(collectionId)` as the source of truth for what your collection can use at runtime. The public docs provide recommendations, but actual availability depends on the SmartLinks model catalog exposed to that collection.
+
 **Recommended Models:**
 
 | Model | Use Case | Speed | Cost |
 |-------|----------|-------|------|
-| `google/gemini-2.5-flash-lite` | Simple Q&A | Fastest | Lowest |
-| `google/gemini-2.5-flash` | General purpose | Fast | Low |
-| `google/gemini-2.5-pro` | Complex reasoning | Slower | Higher |
+| `openai/gpt-5.4` | Default for new agentic and structured-output workflows | Balanced | Medium |
+| `openai/gpt-5-mini` | Lower-cost general purpose and JSON tasks | Fast | Low |
+| `google/gemini-2.5-flash` | Fast multimodal and cost-sensitive general use | Fast | Low |
+| `google/gemini-2.5-pro` | Complex reasoning and heavier multimodal tasks | Slower | Higher |
+
+If you want a safe default for most new work, start with `openai/gpt-5.4`. If you want a lower-cost fallback, use `openai/gpt-5-mini` or `google/gemini-2.5-flash` depending on your latency and pricing goals.
 
 ---
 
@@ -1577,23 +1585,27 @@ console.log('Rate limit reset for user-123');
 ### 1. Choose the Right Model
 
 ```typescript
-// For simple Q&A (fast, cheap)
-await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash-lite',
-  messages: [...]
+// For most new workflows (recommended default)
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5.4',
+  input: 'Create a concise onboarding checklist.'
 });
 
-// For general use (balanced)
-await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-flash',
-  messages: [...]
+// For lower-cost structured or JSON-oriented work
+await ai.chat.responses.create('my-collection', {
+  model: 'openai/gpt-5-mini',
+  input: 'Return a color palette as JSON.'
 });
 
-// For complex reasoning (powerful)
+// For fast multimodal or cost-sensitive general use
 await ai.chat.completions.create('my-collection', {
-  model: 'google/gemini-2.5-pro',
+  model: 'google/gemini-2.5-flash',
   messages: [...]
 });
+
+// When you need the actual available catalog for this collection
+const available = await ai.models.list('my-collection');
+console.log(available.data.map(model => model.id));
 ```
 
 ### 2. Use Streaming for Long Responses

package/openapi.yaml

@@ -15881,20 +15881,12 @@ components:
         - items
         - limit
         - offset
-    QueryOrderItemFilter:
-      type: object
-      properties:
-        productId:
-          type: string
-        batchId:
-          type: string
-        variantId:
-          type: string
-      required:
-        - productId
-    QueryOrdersFilter:
+    QueryOrdersRequest:
       type: object
       properties:
+        query:
+          type: object
+          additionalProperties: true
         status:
           type: string
         orderRef:
@@ -15913,11 +15905,31 @@ components:
           type: number
         maxItemCount:
           type: number
+        productId:
+          type: string
+        batchId:
+          type: string
+        variantId:
+          type: string
+        itemType:
+          type: string
+          enum:
+            - tag
+            - proof
+            - serial
+        itemId:
+          type: string
+        itemCollectionId:
+          type: string
+        itemMetadata:
+          type: object
+          additionalProperties: true
+        items:
+          type: object
+          additionalProperties: true
         metadata:
           type: object
           additionalProperties: true
-        item:
-          $ref: "#/components/schemas/QueryOrderItemFilter"
         sortBy:
           type: string
         sortOrder:
@@ -15925,17 +15937,15 @@ components:
           enum:
             - asc
             - desc
-    QueryOrdersRequest:
-      type: object
-      properties:
-        query:
-          $ref: "#/components/schemas/QueryOrdersFilter"
         limit:
           type: number
         offset:
           type: number
         includeItems:
           type: boolean
+      required:
+        - itemType
+        - itemId
     QueryOrdersResponse:
       type: object
       properties:

package/package.json

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