@proveanything/smartlinks 1.3.16 → 1.3.18

package/dist/docs/API_SUMMARY.md

@@ -1,9 +1,22 @@
 # Smartlinks API Summary
 
-Version: 1.3.16  |  Generated: 2026-02-06T12:14:25.408Z
+Version: 1.3.18  |  Generated: 2026-02-07T16:00:44.350Z
 
 This is a concise summary of all available API functions and types.
 
+## Documentation
+
+For detailed guides on specific features:
+
+- **[AI & Chat Completions](ai.md)** - Chat completions, RAG (document-grounded Q&A), voice integration, streaming, tool calling, podcast generation
+- **[Widgets](widgets.md)** - Embeddable React components for parent applications
+- **[Realtime](realtime.md)** - Real-time data updates and WebSocket connections
+- **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication
+- **[i18n](i18n.md)** - Internationalization and localization
+- **[Liquid Templates](liquid-templates.md)** - Dynamic templating for content generation
+- **[Theme System](theme.system.md)** - Theme configuration and customization
+- **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
+
 ## API Namespaces
 
 The Smartlinks SDK is organized into the following namespaces:
@@ -42,7 +55,7 @@ The Smartlinks SDK is organized into the following namespaces:
 - **qr** - Lookup short codes to resolve collection/product/proof context.
 
 — AI & Utilities —
-- **ai** - Generate content and images, search photos, chat, upload files, and cache.
+- **ai** - Chat completions, RAG (document Q&A), podcast generation, TTS, content/image generation, voice integration.
 - **serialNumber** - Assign, lookup, and manage serial numbers across scopes.
 
 — Other —
@@ -2173,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
 }
@@ -2195,6 +2211,13 @@ interface CreateOrderRequest {
 }
 ```
 
+**GetOrderParams** (interface)
+```typescript
+interface GetOrderParams {
+  includeItems?: boolean            // Optional: Include items array (default: false)
+}
+```
+
 **UpdateOrderRequest** (interface)
 ```typescript
 interface UpdateOrderRequest {
@@ -2220,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)
 }
 ```
 
@@ -2267,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)
@@ -2671,6 +2799,426 @@ interface TemplateRenderSourceResponse {
 
 ### ai (api)
 
+**ContentPart** (interface)
+```typescript
+interface ContentPart {
+  type: 'text' | 'image_url'
+  text?: string
+  image_url?: {
+  url: string
+  detail?: 'auto' | 'low' | 'high'
+  }
+}
+```
+
+**FunctionCall** (interface)
+```typescript
+interface FunctionCall {
+  name: string
+  arguments: string
+}
+```
+
+**ToolCall** (interface)
+```typescript
+interface ToolCall {
+  id: string
+  type: 'function'
+  function: {
+  name: string
+  arguments: string
+  }
+}
+```
+
+**ChatMessage** (interface)
+```typescript
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'function' | 'tool'
+  content: string | ContentPart[]
+  name?: string
+  function_call?: FunctionCall
+  tool_calls?: ToolCall[]
+  tool_call_id?: string
+}
+```
+
+**ToolDefinition** (interface)
+```typescript
+interface ToolDefinition {
+  type: 'function'
+  function: {
+  name: string
+  description: string
+  parameters: {
+  type: 'object'
+  properties: Record<string, {
+  type: string
+  description?: string
+  enum?: string[]
+  }>
+  required?: string[]
+  }
+  }
+}
+```
+
+**ChatCompletionRequest** (interface)
+```typescript
+interface ChatCompletionRequest {
+  messages: ChatMessage[]
+  model?: string
+  stream?: boolean
+  tools?: ToolDefinition[]
+  tool_choice?: 'none' | 'auto' | 'required' | { type: 'function'; function: { name: string } }
+  temperature?: number
+  max_tokens?: number
+  top_p?: number
+  frequency_penalty?: number
+  presence_penalty?: number
+  response_format?: { type: 'text' | 'json_object' }
+  user?: string
+}
+```
+
+**ChatCompletionChoice** (interface)
+```typescript
+interface ChatCompletionChoice {
+  index: number
+  message: ChatMessage
+  finish_reason: 'stop' | 'length' | 'function_call' | 'tool_calls' | 'content_filter' | null
+}
+```
+
+**ChatCompletionResponse** (interface)
+```typescript
+interface ChatCompletionResponse {
+  id: string
+  object: 'chat.completion'
+  created: number
+  model: string
+  choices: ChatCompletionChoice[]
+  usage: {
+  prompt_tokens: number
+  completion_tokens: number
+  total_tokens: number
+  }
+}
+```
+
+**ChatCompletionChunk** (interface)
+```typescript
+interface ChatCompletionChunk {
+  id: string
+  object: 'chat.completion.chunk'
+  created: number
+  model: string
+  choices: Array<{
+  index: number
+  delta: Partial<ChatMessage>
+  finish_reason: string | null
+  }>
+}
+```
+
+**AIModel** (interface)
+```typescript
+interface AIModel {
+  id: string
+  provider: 'gemini' | 'openai'
+  modelId: string
+  name: string
+  description: string
+  capabilities: Array<'text' | 'vision' | 'audio' | 'code'>
+  contextWindow: number
+  pricing: {
+  input: number
+  output: number
+  cached?: number
+  }
+  features: string[]
+  recommended?: string
+}
+```
+
+**ModelList** (interface)
+```typescript
+interface ModelList {
+  object: 'list'
+  data: AIModel[]
+}
+```
+
+**DocumentChunk** (interface)
+```typescript
+interface DocumentChunk {
+  text: string
+  embedding: number[]
+  metadata: {
+  chunkIndex: number
+  documentId: string
+  [key: string]: any
+  }
+}
+```
+
+**IndexDocumentRequest** (interface)
+```typescript
+interface IndexDocumentRequest {
+  productId: string
+  text?: string
+  documentUrl?: string
+  metadata?: Record<string, any>
+  chunkSize?: number
+  overlap?: number
+  provider?: 'openai' | 'gemini'
+}
+```
+
+**IndexDocumentResponse** (interface)
+```typescript
+interface IndexDocumentResponse {
+  success: boolean
+  productId: string
+  documentId: string
+  chunks: number
+  metadata: {
+  textLength: number
+  chunkSize: number
+  overlap: number
+  embeddingDimensions: number
+  }
+  sample?: {
+  text: string
+  chunkIndex: number
+  }
+}
+```
+
+**ConfigureAssistantRequest** (interface)
+```typescript
+interface ConfigureAssistantRequest {
+  productId: string
+  systemPrompt?: string
+  model?: string
+  maxTokensPerResponse?: number
+  temperature?: number
+  rateLimitPerUser?: number
+  allowedTopics?: string[]
+  customInstructions?: {
+  tone?: string
+  additionalRules?: string
+  [key: string]: any
+  }
+}
+```
+
+**ConfigureAssistantResponse** (interface)
+```typescript
+interface ConfigureAssistantResponse {
+  success: boolean
+  configuration: {
+  productId: string
+  systemPrompt: string
+  model: string
+  maxTokensPerResponse: number
+  temperature: number
+  rateLimitPerUser: number
+  allowedTopics: string[]
+  customInstructions?: Record<string, any>
+  updatedAt: string
+  }
+}
+```
+
+**PublicChatRequest** (interface)
+```typescript
+interface PublicChatRequest {
+  productId: string
+  userId: string
+  message: string
+  sessionId?: string
+  stream?: boolean
+}
+```
+
+**PublicChatResponse** (interface)
+```typescript
+interface PublicChatResponse {
+  message: string
+  sessionId: string
+  usage: {
+  prompt_tokens: number
+  completion_tokens: number
+  total_tokens: number
+  }
+  context?: {
+  chunksUsed: number
+  topSimilarity: number
+  }
+}
+```
+
+**Session** (interface)
+```typescript
+interface Session {
+  sessionId: string
+  productId: string
+  userId: string
+  messageCount: number
+  createdAt: string
+  lastActivityAt: string
+  messages: ChatMessage[]
+}
+```
+
+**RateLimitStatus** (interface)
+```typescript
+interface RateLimitStatus {
+  used: number
+  remaining: number
+  resetAt: string
+}
+```
+
+**SessionStatistics** (interface)
+```typescript
+interface SessionStatistics {
+  totalSessions: number
+  activeSessions: number
+  totalMessages: number
+  rateLimitedUsers: number
+}
+```
+
+**VoiceSessionRequest** (interface)
+```typescript
+interface VoiceSessionRequest {
+  productId: string
+  userId: string
+  collectionId: string
+  settings?: {
+  voice?: string
+  language?: string
+  model?: string
+  }
+}
+```
+
+**VoiceSessionResponse** (interface)
+```typescript
+interface VoiceSessionResponse {
+  token: string
+  systemInstruction: string
+  expiresAt: string
+  productName: string
+}
+```
+
+**EphemeralTokenRequest** (interface)
+```typescript
+interface EphemeralTokenRequest {
+  settings?: {
+  ttl?: number
+  voice?: string
+  language?: string
+  model?: string
+  }
+}
+```
+
+**EphemeralTokenResponse** (interface)
+```typescript
+interface EphemeralTokenResponse {
+  token: string
+  expiresAt: string
+}
+```
+
+**TranscriptionResponse** (interface)
+```typescript
+interface TranscriptionResponse {
+  text: string
+}
+```
+
+**TTSRequest** (interface)
+```typescript
+interface TTSRequest {
+  text: string
+  voice?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer'
+  speed?: number
+  format?: 'mp3' | 'opus' | 'aac' | 'flac'
+}
+```
+
+**GeneratePodcastRequest** (interface)
+```typescript
+interface GeneratePodcastRequest {
+  productId: string
+  documentText?: string
+  duration?: number
+  style?: 'casual' | 'professional' | 'educational' | 'entertaining'
+  voices?: {
+  host1?: string
+  host2?: string
+  }
+  includeAudio?: boolean
+  language?: string
+  customInstructions?: string
+}
+```
+
+**PodcastSegment** (interface)
+```typescript
+interface PodcastSegment {
+  speaker: 'host1' | 'host2'
+  text: string
+  timestamp?: number
+  duration?: number
+}
+```
+
+**PodcastScript** (interface)
+```typescript
+interface PodcastScript {
+  title: string
+  description: string
+  segments: PodcastSegment[]
+}
+```
+
+**GeneratePodcastResponse** (interface)
+```typescript
+interface GeneratePodcastResponse {
+  success: boolean
+  podcastId: string
+  script: PodcastScript
+  audio?: {
+  host1Url?: string
+  host2Url?: string
+  mixedUrl?: string
+  }
+  metadata: {
+  duration: number
+  wordCount: number
+  generatedAt: string
+  }
+}
+```
+
+**PodcastStatus** (interface)
+```typescript
+interface PodcastStatus {
+  podcastId: string
+  status: 'generating_script' | 'generating_audio' | 'mixing' | 'completed' | 'failed'
+  progress: number
+  estimatedTimeRemaining?: number
+  error?: string
+  result?: GeneratePodcastResponse
+}
+```
+
 **AIGenerateContentRequest** (interface)
 ```typescript
 interface AIGenerateContentRequest {
@@ -2800,6 +3348,67 @@ type AccountInfoResponse = {
 
 ### ai
 
+**create**(collectionId: string,
+        request: ChatCompletionRequest) → `Promise<ChatCompletionResponse | AsyncIterable<ChatCompletionChunk>>`
+Create a chat completion (streaming or non-streaming)
+
+**list**(collectionId: string) → `Promise<ModelList>`
+List available AI models
+
+**get**(collectionId: string, modelId: string) → `Promise<AIModel>`
+Get specific model information
+
+**indexDocument**(collectionId: string,
+      request: IndexDocumentRequest) → `Promise<IndexDocumentResponse>`
+Index a document for RAG
+
+**configureAssistant**(collectionId: string,
+      request: ConfigureAssistantRequest) → `Promise<ConfigureAssistantResponse>`
+Configure AI assistant behavior
+
+**stats**(collectionId: string) → `Promise<SessionStatistics>`
+Get session statistics
+
+**reset**(collectionId: string, userId: string) → `Promise<`
+Reset rate limit for a user
+
+**generate**(collectionId: string,
+      request: GeneratePodcastRequest) → `Promise<GeneratePodcastResponse>`
+Generate a NotebookLM-style conversational podcast from product documents
+
+**getStatus**(collectionId: string, podcastId: string) → `Promise<PodcastStatus>`
+Get podcast generation status
+
+**generate**(collectionId: string,
+      request: TTSRequest) → `Promise<Blob>`
+Generate text-to-speech audio
+
+**chat**(collectionId: string,
+      request: PublicChatRequest) → `Promise<PublicChatResponse>`
+Chat with product assistant (RAG)
+
+**getSession**(collectionId: string, sessionId: string) → `Promise<Session>`
+Get session history
+
+**clearSession**(collectionId: string, sessionId: string) → `Promise<`
+Clear session history
+
+**getRateLimit**(collectionId: string, userId: string) → `Promise<RateLimitStatus>`
+Check rate limit status
+
+**getToken**(collectionId: string,
+      request: EphemeralTokenRequest) → `Promise<EphemeralTokenResponse>`
+Generate ephemeral token for Gemini Live
+
+**isSupported**() → `boolean`
+Check if voice is supported in browser
+
+**listen**(language = 'en-US') → `Promise<string>`
+Listen for voice input
+
+**speak**(text: string, options?: { voice?: string; rate?: number }) → `Promise<void>`
+Speak text
+
 **generateContent**(collectionId: string,
     params: AIGenerateContentRequest,
     admin: boolean = true) → `Promise<any>`
@@ -3519,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,
@@ -3533,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,
@@ -3549,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,