@proveanything/smartlinks 1.3.26 → 1.3.27

package/README.md

@@ -18,6 +18,7 @@ For the full list of functions and types, see the API summary:
 - [Widgets](docs/widgets.md) - Embeddable React components
 - [Realtime](docs/realtime.md) - Realtime data updates
 - [iframe Responder](docs/iframe-responder.md) - iframe integration
+- [Utilities](docs/utils.md) - Helper functions for paths, URLs, and common tasks
 
 ## Install
 
@@ -159,6 +160,53 @@ try {
 
 For comprehensive error handling examples and migration guidance, see [examples/error-handling-demo.ts](examples/error-handling-demo.ts).
 
+## Utility Functions
+
+The SDK includes a simple utility for building portal URLs. Pass in objects and it extracts what it needs:
+
+### Build Portal Paths
+
+```ts
+import { utils } from '@proveanything/smartlinks'
+
+// Pass in objects - extracts shortId, portalUrl, product ID, GTIN, etc.
+const url = utils.buildPortalPath({
+  collection: myCollection,
+  product: myProduct  // reads ownGtin from product
+})
+// Returns: https://portal.smartlinks.io/c/abc123/prod1
+
+// With proof object
+const withProof = utils.buildPortalPath({
+  collection: myCollection,
+  product: myProduct,
+  proof: myProof
+})
+// Returns: https://portal.smartlinks.io/c/abc123/prod1/proof1
+
+// GTIN path (ownGtin read from product.ownGtin)
+const gtinPath = utils.buildPortalPath({
+  collection: myCollection,
+  product: myProduct,  // if product.ownGtin is true, uses /01/ format
+  batch: myBatch,      // extracts batch ID and expiry date
+  variant: myVariant
+})
+// Returns: https://portal.smartlinks.io/01/1234567890123/10/batch1/22/var1?17=260630
+
+// Or pass just IDs if you don't have full objects
+const simple = utils.buildPortalPath({
+  collection: { shortId: 'abc123' },
+  productId: 'prod1',
+  batchId: 'batch1',  // just string, no expiry
+  queryParams: { utm_source: 'email' }
+})
+// Returns: /c/abc123/prod1?utm_source=email
+```
+
+Pass objects where you have them (collection, product, batch, variant, proof) and the function extracts the needed properties. Or pass just IDs (productId, batchId) for simpler cases.
+
+For complete documentation, see [docs/utils.md](docs/utils.md).
+
 ## Common tasks
 
 ### Products

package/dist/api/ai.d.ts

@@ -1,382 +1,5 @@
-/** Content part for multimodal messages */
-export interface ContentPart {
-    type: 'text' | 'image_url';
-    text?: string;
-    image_url?: {
-        url: string;
-        detail?: 'auto' | 'low' | 'high';
-    };
-}
-/** Function call representation */
-export interface FunctionCall {
-    name: string;
-    arguments: string;
-}
-/** Tool call representation */
-export interface ToolCall {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-/** Chat message with role and content */
-export interface ChatMessage {
-    role: 'system' | 'user' | 'assistant' | 'function' | 'tool';
-    content: string | ContentPart[];
-    name?: string;
-    function_call?: FunctionCall;
-    tool_calls?: ToolCall[];
-    tool_call_id?: string;
-}
-/** Tool/Function definition */
-export interface ToolDefinition {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: {
-            type: 'object';
-            properties: Record<string, {
-                type: string;
-                description?: string;
-                enum?: string[];
-            }>;
-            required?: string[];
-        };
-    };
-}
-/** Chat completion request */
-export 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;
-}
-/** Chat completion choice */
-export interface ChatCompletionChoice {
-    index: number;
-    message: ChatMessage;
-    finish_reason: 'stop' | 'length' | 'function_call' | 'tool_calls' | 'content_filter' | null;
-}
-/** Chat completion response */
-export interface ChatCompletionResponse {
-    id: string;
-    object: 'chat.completion';
-    created: number;
-    model: string;
-    choices: ChatCompletionChoice[];
-    usage: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-}
-/** Streaming chunk */
-export interface ChatCompletionChunk {
-    id: string;
-    object: 'chat.completion.chunk';
-    created: number;
-    model: string;
-    choices: Array<{
-        index: number;
-        delta: Partial<ChatMessage>;
-        finish_reason: string | null;
-    }>;
-}
-/** AI Model information */
-export 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;
-}
-/** List of models */
-export interface ModelList {
-    object: 'list';
-    data: AIModel[];
-}
-/** Document chunk with embedding */
-export interface DocumentChunk {
-    text: string;
-    embedding: number[];
-    metadata: {
-        chunkIndex: number;
-        documentId: string;
-        [key: string]: any;
-    };
-}
-/** Index document request */
-export interface IndexDocumentRequest {
-    productId: string;
-    text?: string;
-    documentUrl?: string;
-    metadata?: Record<string, any>;
-    chunkSize?: number;
-    overlap?: number;
-    provider?: 'openai' | 'gemini';
-}
-/** Index document response */
-export interface IndexDocumentResponse {
-    success: boolean;
-    productId: string;
-    documentId: string;
-    chunks: number;
-    metadata: {
-        textLength: number;
-        chunkSize: number;
-        overlap: number;
-        embeddingDimensions: number;
-    };
-    sample?: {
-        text: string;
-        chunkIndex: number;
-    };
-}
-/** Configure assistant request */
-export interface ConfigureAssistantRequest {
-    productId: string;
-    systemPrompt?: string;
-    model?: string;
-    maxTokensPerResponse?: number;
-    temperature?: number;
-    rateLimitPerUser?: number;
-    allowedTopics?: string[];
-    customInstructions?: {
-        tone?: string;
-        additionalRules?: string;
-        [key: string]: any;
-    };
-}
-/** Configure assistant response */
-export 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;
-    };
-}
-/** Public chat request */
-export interface PublicChatRequest {
-    productId: string;
-    userId: string;
-    message: string;
-    sessionId?: string;
-    stream?: boolean;
-}
-/** Public chat response */
-export interface PublicChatResponse {
-    message: string;
-    sessionId: string;
-    usage: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-    };
-    context?: {
-        chunksUsed: number;
-        topSimilarity: number;
-    };
-}
-/** Session information */
-export interface Session {
-    sessionId: string;
-    productId: string;
-    userId: string;
-    messageCount: number;
-    createdAt: string;
-    lastActivityAt: string;
-    messages: ChatMessage[];
-}
-/** Rate limit status */
-export interface RateLimitStatus {
-    used: number;
-    remaining: number;
-    resetAt: string;
-}
-/** Session statistics */
-export interface SessionStatistics {
-    totalSessions: number;
-    activeSessions: number;
-    totalMessages: number;
-    rateLimitedUsers: number;
-}
-/** Voice session request */
-export interface VoiceSessionRequest {
-    productId: string;
-    userId: string;
-    collectionId: string;
-    settings?: {
-        voice?: string;
-        language?: string;
-        model?: string;
-    };
-}
-/** Voice session response */
-export interface VoiceSessionResponse {
-    token: string;
-    systemInstruction: string;
-    expiresAt: string;
-    productName: string;
-}
-/** Ephemeral token request */
-export interface EphemeralTokenRequest {
-    settings?: {
-        ttl?: number;
-        voice?: string;
-        language?: string;
-        model?: string;
-    };
-}
-/** Ephemeral token response */
-export interface EphemeralTokenResponse {
-    token: string;
-    expiresAt: string;
-}
-/** Transcription response */
-export interface TranscriptionResponse {
-    text: string;
-}
-/** TTS request */
-export interface TTSRequest {
-    text: string;
-    voice?: 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
-    speed?: number;
-    format?: 'mp3' | 'opus' | 'aac' | 'flac';
-}
-/** Podcast generation request */
-export interface GeneratePodcastRequest {
-    productId: string;
-    documentText?: string;
-    duration?: number;
-    style?: 'casual' | 'professional' | 'educational' | 'entertaining';
-    voices?: {
-        host1?: string;
-        host2?: string;
-    };
-    includeAudio?: boolean;
-    language?: string;
-    customInstructions?: string;
-}
-/** Podcast script segment */
-export interface PodcastSegment {
-    speaker: 'host1' | 'host2';
-    text: string;
-    timestamp?: number;
-    duration?: number;
-}
-/** Podcast script */
-export interface PodcastScript {
-    title: string;
-    description: string;
-    segments: PodcastSegment[];
-}
-/** Podcast generation response */
-export interface GeneratePodcastResponse {
-    success: boolean;
-    podcastId: string;
-    script: PodcastScript;
-    audio?: {
-        host1Url?: string;
-        host2Url?: string;
-        mixedUrl?: string;
-    };
-    metadata: {
-        duration: number;
-        wordCount: number;
-        generatedAt: string;
-    };
-}
-/** Podcast status */
-export interface PodcastStatus {
-    podcastId: string;
-    status: 'generating_script' | 'generating_audio' | 'mixing' | 'completed' | 'failed';
-    progress: number;
-    estimatedTimeRemaining?: number;
-    error?: string;
-    result?: GeneratePodcastResponse;
-}
-export interface AIGenerateContentRequest {
-    /** The prompt or message contents sent to the AI */
-    contents: string | any;
-    /** Desired MIME type of the response payload (e.g. 'application/json', 'text/plain') */
-    responseMimeType?: string;
-    /** Optional system instruction or system prompt to steer the model */
-    systemInstruction?: string;
-    /** AI provider identifier (e.g. 'openai', 'google', 'anthropic') */
-    provider?: string;
-    /** The model name to use (e.g. 'gpt-4o', 'gemini-1.5-pro') */
-    model?: string;
-    /** Allow passing additional provider/model-specific options */
-    [key: string]: any;
-}
-export interface AIGenerateImageRequest {
-    /** Text prompt describing the desired image */
-    prompt: string;
-    /** AI provider identifier (e.g. 'openai', 'google', 'stability') */
-    provider?: string;
-    /** Optional model name to use for image generation */
-    model?: string;
-    /** Requested image size, e.g. '1024x1024' */
-    size?: string;
-    /** Additional provider/model-specific options */
-    [key: string]: any;
-}
-export interface AISearchPhotosRequest {
-    /** Search query keyword(s) */
-    query: string;
-    /** Number of results to return per page (e.g. 1) */
-    per_page?: number;
-    /** Desired orientation of photos */
-    orientation?: 'landscape' | 'portrait' | 'squarish';
-    /** Additional provider-specific options */
-    [key: string]: any;
-}
-export interface AISearchPhotosPhoto {
-    /** Direct image URL */
-    url: string;
-    /** Alt text/description for accessibility */
-    alt?: string;
-    /** Photographer display name */
-    photographer?: string;
-    /** Link to the photographer profile */
-    photographerUrl?: string;
-    /** Allow extra fields */
-    [key: string]: any;
-}
+import type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto } from "../types/ai";
+export type { ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, PodcastScript, GeneratePodcastResponse, PodcastStatus, AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto, };
 export declare namespace ai {
     namespace chat {
         namespace completions {
@@ -393,7 +16,10 @@ export declare namespace ai {
         /**
          * List available AI models
          */
-        function list(collectionId: string): Promise<ModelList>;
+        function list(collectionId: string): Promise<{
+            object: 'list';
+            data: AIModel[];
+        }>;
         /**
          * Get specific model information
          */

package/dist/api/ai.js

@@ -17,7 +17,7 @@ export var ai;
              * @returns Chat completion response or async iterable for streaming
              */
             async function create(collectionId, request) {
-                const path = `/admin/${encodeURIComponent(collectionId)}/ai/v1/chat/completions`;
+                const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/v1/chat/completions`;
                 if (request.stream) {
                     // TODO: Implement streaming via SSE
                     throw new Error('Streaming not yet implemented');
@@ -36,7 +36,7 @@ export var ai;
          * List available AI models
          */
         async function list(collectionId) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/models`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/models`;
             return request(path);
         }
         models.list = list;
@@ -44,7 +44,7 @@ export var ai;
          * Get specific model information
          */
         async function get(collectionId, modelId) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/models/${encodeURIComponent(modelId)}`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/models/${encodeURIComponent(modelId)}`;
             return request(path);
         }
         models.get = get;
@@ -58,7 +58,7 @@ export var ai;
          * Index a document for RAG
          */
         async function indexDocument(collectionId, request) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/indexDocument`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/indexDocument`;
             return post(path, request);
         }
         rag.indexDocument = indexDocument;
@@ -66,7 +66,7 @@ export var ai;
          * Configure AI assistant behavior
          */
         async function configureAssistant(collectionId, request) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/configureAssistant`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/configureAssistant`;
             return post(path, request);
         }
         rag.configureAssistant = configureAssistant;
@@ -80,7 +80,7 @@ export var ai;
          * Get session statistics
          */
         async function stats(collectionId) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/sessions/stats`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/sessions/stats`;
             return request(path);
         }
         sessions.stats = stats;
@@ -94,7 +94,7 @@ export var ai;
          * Reset rate limit for a user
          */
         async function reset(collectionId, userId) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/rate-limit/${encodeURIComponent(userId)}/reset`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/rate-limit/${encodeURIComponent(userId)}/reset`;
             return post(path, {});
         }
         rateLimit.reset = reset;
@@ -108,7 +108,7 @@ export var ai;
          * Generate a NotebookLM-style conversational podcast from product documents
          */
         async function generate(collectionId, request) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/generatePodcast`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/generatePodcast`;
             return post(path, request);
         }
         podcast.generate = generate;
@@ -116,7 +116,7 @@ export var ai;
          * Get podcast generation status
          */
         async function getStatus(collectionId, podcastId) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/podcast/${encodeURIComponent(podcastId)}`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/podcast/${encodeURIComponent(podcastId)}`;
             return request(path);
         }
         podcast.getStatus = getStatus;
@@ -130,7 +130,7 @@ export var ai;
          * Generate text-to-speech audio
          */
         async function generate(collectionId, request) {
-            const path = `/admin/${encodeURIComponent(collectionId)}/ai/tts`;
+            const path = `/admin/collection/${encodeURIComponent(collectionId)}/ai/tts`;
             // Note: This would need special handling for binary response
             return post(path, request);
         }
@@ -145,7 +145,7 @@ export var ai;
          * Chat with product assistant (RAG)
          */
         async function chat(collectionId, request) {
-            const path = `/${encodeURIComponent(collectionId)}/ai/chat`;
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/chat`;
             return post(path, request);
         }
         publicApi.chat = chat;
@@ -153,7 +153,7 @@ export var ai;
          * Get session history
          */
         async function getSession(collectionId, sessionId) {
-            const path = `/${encodeURIComponent(collectionId)}/ai/session/${encodeURIComponent(sessionId)}`;
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/session/${encodeURIComponent(sessionId)}`;
             return request(path);
         }
         publicApi.getSession = getSession;
@@ -161,7 +161,7 @@ export var ai;
          * Clear session history
          */
         async function clearSession(collectionId, sessionId) {
-            const path = `/${encodeURIComponent(collectionId)}/ai/session/${encodeURIComponent(sessionId)}`;
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/session/${encodeURIComponent(sessionId)}`;
             return del(path);
         }
         publicApi.clearSession = clearSession;
@@ -169,7 +169,7 @@ export var ai;
          * Check rate limit status
          */
         async function getRateLimit(collectionId, userId) {
-            const path = `/${encodeURIComponent(collectionId)}/ai/rate-limit/${encodeURIComponent(userId)}`;
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/rate-limit/${encodeURIComponent(userId)}`;
             return request(path);
         }
         publicApi.getRateLimit = getRateLimit;
@@ -177,7 +177,7 @@ export var ai;
          * Generate ephemeral token for Gemini Live
          */
         async function getToken(collectionId, request) {
-            const path = `/${encodeURIComponent(collectionId)}/ai/token`;
+            const path = `/public/collection/${encodeURIComponent(collectionId)}/ai/token`;
             return post(path, request);
         }
         publicApi.getToken = getToken;

package/dist/api/index.d.ts

@@ -29,4 +29,3 @@ export { location } from "./location";
 export * as realtime from "./realtime";
 export { tags } from "./tags";
 export { order } from "./order";
-export type { AIGenerateContentRequest, AIGenerateImageRequest, AISearchPhotosRequest, AISearchPhotosPhoto, ContentPart, FunctionCall, ToolCall, ChatMessage, ToolDefinition, ChatCompletionRequest, ChatCompletionChoice, ChatCompletionResponse, ChatCompletionChunk, AIModel, ModelList, DocumentChunk, IndexDocumentRequest, IndexDocumentResponse, ConfigureAssistantRequest, ConfigureAssistantResponse, PublicChatRequest, PublicChatResponse, Session, RateLimitStatus, SessionStatistics, VoiceSessionRequest, VoiceSessionResponse, EphemeralTokenRequest, EphemeralTokenResponse, TranscriptionResponse, TTSRequest, GeneratePodcastRequest, GeneratePodcastResponse, PodcastScript, PodcastSegment, PodcastStatus, } from "./ai";