@promptmetrics/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1320 @@
+import { AxiosRequestConfig } from 'axios';
+
+interface HttpClientConfig {
+    baseURL: string;
+    apiKey: string;
+    timeout?: number;
+    maxRetries?: number;
+    debug?: boolean;
+}
+/**
+ * HTTP client with automatic retry logic and error handling
+ */
+declare class HttpClient {
+    private client;
+    private maxRetries;
+    private debug;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make HTTP request with retry logic
+     */
+    request<T>(config: AxiosRequestConfig): Promise<T>;
+    /**
+     * GET request
+     */
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Handle axios errors and convert to SDK errors
+     * Extracts details from backend HttpException format
+     */
+    private handleError;
+    /**
+     * Determine if request should be retried
+     */
+    private shouldRetry;
+    /**
+     * Sleep utility for retry backoff
+     */
+    private sleep;
+}
+
+/**
+ * Common types used across the SDK
+ */
+/**
+ * Core configuration types
+ */
+interface PromptMetricsConfig {
+    /** Workspace API key (starts with pm_) - Required */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retries for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Backend response wrapper
+ */
+interface BackendResponse<T> {
+    success: boolean;
+    message: string;
+    responseData: {
+        data: T;
+    };
+    error?: string;
+}
+/**
+ * Error types
+ */
+interface PromptMetricsErrorResponse {
+    success: false;
+    message: string;
+    error?: string | ErrorObject;
+}
+interface ErrorObject {
+    message: string;
+    type?: string;
+    code?: string;
+    param?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Pagination metadata
+ */
+interface PaginationMeta {
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+}
+
+/**
+ * Template-related types
+ */
+/**
+ * Message types for templates
+ */
+interface Message {
+    role: "system" | "user" | "assistant" | "function" | "tool";
+    content: string;
+    name?: string;
+    variable?: string[];
+    tool_call_id?: string;
+    tool_calls?: unknown[];
+}
+interface TemplateMetadata {
+    [key: string]: string | number | boolean | null | undefined;
+}
+interface TemplateOptions {
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    [key: string]: string | number | boolean | null | undefined;
+}
+interface Template {
+    _id: string;
+    workspace_id: string;
+    parent_id?: string | null;
+    name: string;
+    description?: string;
+    is_folder: boolean;
+    created_by: string;
+    risk_level?: "LOW" | "MEDIUM" | "HIGH";
+    created_at: string;
+    updated_at: string;
+    versions?: TemplateVersion[];
+    tags?: Array<{
+        _id: string;
+        name: string;
+        color?: string;
+    }>;
+    rating_details?: {
+        rating: number;
+        rated_by: string;
+        rated_by_email: string;
+        rated_at: string;
+    };
+}
+interface TemplateVersion {
+    _id: string;
+    template_id: string;
+    version: number;
+    labels: string[];
+    env_label: "development" | "staging" | "production";
+    model_id?: string | null;
+    created_by: string | {
+        _id: string;
+        first_name: string;
+        last_name: string;
+        email: string;
+    };
+    message_format: "f-string" | "jinja2";
+    metadata: TemplateMetadata;
+    display_mode: number;
+    api_type: string | null;
+    messages: Message[];
+    options: TemplateOptions;
+    created_at: string;
+    updated_at: string;
+    model?: {
+        _id: string;
+        name: string;
+        provider_id: string;
+        prompt_cost_per_million_token: number;
+        output_cost_per_million_token: number;
+        cached_input_cost_per_million_token: number;
+    };
+    model_name?: string;
+    provider?: {
+        _id: string;
+        name: string;
+        slug: string;
+    } | string;
+    provider_slug?: string;
+    workspace_id?: string;
+}
+/**
+ * List prompts options (workspace_id comes from API key)
+ */
+interface ListPromptsOptions {
+    search?: string;
+    parent_id?: string | null;
+    risk_level?: "LOW" | "MEDIUM" | "HIGH";
+    created_by?: string;
+    start_date?: string;
+    end_date?: string;
+    sort_by?: "created_at" | "updated_at" | "name";
+    sort_order?: "asc" | "desc";
+    page?: number;
+    per_page?: number;
+}
+/**
+ * List prompts response
+ */
+interface ListPromptsResponse {
+    prompts: Template[];
+    total: number;
+}
+/**
+ * Get template options
+ */
+interface GetTemplateOptions {
+    /** Specific version number to fetch */
+    version?: number;
+    /** Environment label to filter versions */
+    env_label?: "development" | "staging" | "production";
+}
+/**
+ * Run template options (canary-aware)
+ * Used by templates.run() method
+ */
+interface RunTemplateOptions {
+    /** Variables to substitute in template messages */
+    variables?: Record<string, unknown>;
+    /** Model name override */
+    model?: string;
+    /** Model ID override */
+    model_id?: string;
+    /** LLM parameters override */
+    parameters?: Record<string, unknown>;
+    /** Custom messages override */
+    messages?: Message[];
+    /** API type override */
+    api_type?: "chat.completion" | "response";
+    /** Custom tags to associate with this prompt log */
+    pm_tags?: string[];
+    /** Trace ID for correlation */
+    trace_id?: string;
+    /** Span ID for correlation */
+    span_id?: string;
+    /** Group ID for correlation */
+    group_id?: string;
+    /** Specific version number to run (bypasses canary) */
+    version?: number;
+    /** Environment label to run (production uses canary if active) */
+    env_label?: "development" | "staging" | "production" | "legacy" | "canary";
+    /** Version name/description to run (bypasses canary) */
+    version_name?: string;
+}
+
+/**
+ * Provider and model types
+ */
+interface LLMModel {
+    _id: string;
+    name: string;
+    provider_id: string;
+    prompt_cost_per_million_token: number;
+    output_cost_per_million_token: number;
+    cached_input_cost_per_million_token: number;
+    created_at?: string;
+    updated_at?: string;
+}
+interface LLMProvider {
+    _id: string;
+    name: string;
+    slug: string;
+    has_key?: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+interface ProviderWithModels extends LLMProvider {
+    models: LLMModel[];
+    parameters?: Record<string, unknown>[];
+}
+
+/**
+ * Version-related types
+ */
+
+/**
+ * Options for running a specific template version
+ */
+interface RunVersionOptions {
+    /** Variables to substitute in template messages */
+    variables?: Record<string, unknown>;
+    model?: string;
+    parameters?: Record<string, unknown>;
+    messages?: Message[];
+    /** Custom tags to associate with this prompt log (stored as string array) */
+    pm_tags?: string[];
+}
+/**
+ * Options for updating a template version
+ */
+interface UpdateVersionOptions {
+    /** Environment label */
+    env_label?: "development" | "staging" | "production";
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+interface RequestObject {
+    model?: string;
+    messages?: Message[];
+    temperature?: number;
+    max_tokens?: number;
+    [key: string]: unknown;
+}
+interface ResponseObject {
+    id?: string;
+    model?: string;
+    choices?: Array<{
+        message?: Message;
+        finish_reason?: string;
+        index?: number;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Log-related types
+ */
+
+interface PromptLog {
+    _id: string;
+    request_id: string;
+    template_version_id: string;
+    template_id: string;
+    workspace_id: string;
+    created_by: string;
+    source: "website" | "sdk";
+    llm_prompt_tokens: number;
+    llm_completion_tokens: number;
+    llm_total_tokens: number;
+    prompt_cost: number;
+    completion_cost: number;
+    total_cost: number;
+    request_object: RequestObject;
+    response_object: ResponseObject;
+    error_object?: ErrorObject | null;
+    latency: number;
+    status: "SUCCESS" | "ERROR";
+    messages: Message[];
+    model_id: string | null;
+    model_name: string;
+    start_time: string;
+    end_time: string;
+    variables: Record<string, string>;
+    options: TemplateOptions;
+    note?: string;
+    created_at: string;
+    updated_at: string;
+    trace_id?: string;
+    span_id?: string;
+    group_id?: string;
+    tags?: string[];
+}
+interface ListLogsOptions {
+    template_id?: string;
+    template_version_id?: string;
+    model_id?: string;
+    start_date?: string;
+    end_date?: string;
+    status?: "SUCCESS" | "ERROR" | "all";
+    source?: "website" | "sdk";
+    limit?: number;
+    page?: number;
+    sort_by?: "created_at" | "latency" | "cost" | "tokens" | "status";
+    sort_order?: "asc" | "desc";
+}
+
+/**
+ * Trace/Tracking types for @traceable decorator
+ */
+
+type TraceStatus = "SUCCESS" | "ERROR" | "PENDING";
+interface TraceError {
+    message: string;
+    stack?: string;
+    code?: string;
+}
+interface TraceScore {
+    criteria: string;
+    value: number;
+    timestamp: string;
+}
+interface Trace {
+    _id: string;
+    workspace_id: string;
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    function_name: string;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    status: TraceStatus;
+    error?: TraceError;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    scores?: TraceScore[];
+    group_id?: string;
+    group_type?: string;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+}
+interface TraceTreeNode extends Omit<Trace, "_id" | "workspace_id" | "created_at" | "updated_at"> {
+    _id: string;
+    children: TraceTreeNode[];
+}
+interface CreateTraceOptions {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    function_name: string;
+    start_time: Date | string;
+    end_time: Date | string;
+    duration_ms: number;
+    status: TraceStatus;
+    error?: TraceError;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    scores?: Array<{
+        criteria: string;
+        value: number;
+    }>;
+    tags?: string[];
+    group_id?: string;
+    group_type?: string;
+}
+interface AddTraceScoreOptions {
+    criteria: string;
+    value: number;
+}
+interface UpdateTraceMetadataOptions {
+    metadata: Record<string, unknown>;
+}
+interface ListTracesOptions {
+    trace_id?: string;
+    function_name?: string;
+    status?: TraceStatus;
+    group_id?: string;
+    group_type?: string;
+    tags?: string[];
+    start_date?: string;
+    end_date?: string;
+    page?: number;
+    limit?: number;
+}
+interface TraceListResponse {
+    traces: Trace[];
+    pagination: PaginationMeta;
+}
+interface TraceAnalytics {
+    total_traces: number;
+    success_rate: number;
+    average_duration_ms: number;
+    error_count: number;
+    function_breakdown: Array<{
+        function_name: string;
+        count: number;
+        avg_duration_ms: number;
+        success_rate: number;
+    }>;
+}
+/**
+ * Decorator options for @traceable
+ */
+interface TraceableOptions {
+    /** Name of the function (for display) */
+    name?: string;
+    /** Static metadata to attach */
+    metadata?: Record<string, unknown>;
+    /** Tags for categorization (e.g., ['payment', 'critical', 'production']) */
+    tags?: string[];
+    /** Disable tracing for this function */
+    disabled?: boolean;
+}
+
+/**
+ * Base resource class with shared functionality
+ */
+declare abstract class BaseResource {
+    protected http: HttpClient;
+    constructor(http: HttpClient);
+    /**
+     * Transform backend response to SDK format
+     * Extracts data from the general response wrapper
+     *
+     * Backend format: { success: true, message: "...", responseData: { data: {...} } }
+     * SDK format: Just the data
+     */
+    protected transformResponse<T>(backendResponse: BackendResponse<T> | T): T;
+}
+
+/**
+ * Template resource for managing and executing templates
+ */
+declare class TemplateResource extends BaseResource {
+    /**
+     * Get a template by ID or name
+     * Workspace ID is automatically determined from API key
+     *
+     * @param identifier - Template ID or name
+     * @param options - Optional version and env_label filters
+     * @param options.version - Specific version number to fetch
+     * @param options.env_label - Environment label: 'development' | 'staging' | 'production'
+     * @returns Template with versions
+     *
+     * @example
+     * ```typescript
+     * // Get template by ID (returns all versions)
+     * const template = await client.templates.get('template_id_123');
+     *
+     * // Get template by name (returns all versions)
+     * const template = await client.templates.get('my-template-name');
+     *
+     * // Get specific version
+     * const template = await client.templates.get('my-template', {
+     *   version: 2
+     * });
+     *
+     * // Get by environment label
+     * const template = await client.templates.get('my-template', {
+     *   env_label: 'production'
+     * });
+     * ```
+     */
+    get(identifier: string, options?: GetTemplateOptions): Promise<Template>;
+    /**
+     * List prompts (templates) with advanced filtering
+     * Workspace ID is automatically determined from API key
+     *
+     * @param options - Filter and pagination options
+     * @param options.search - Search in prompt name/description
+     * @param options.parent_id - Filter by parent folder ID
+     * @param options.risk_level - Filter by risk level: 'LOW' | 'MEDIUM' | 'HIGH'
+     * @param options.created_by - Filter by creator user ID
+     * @param options.start_date - Filter by creation date (ISO string)
+     * @param options.end_date - Filter by creation date (ISO string)
+     * @param options.sort_by - Sort field: 'created_at' | 'updated_at' | 'name'
+     * @param options.sort_order - Sort order: 'asc' | 'desc'
+     * @param options.page - Page number (default: 1)
+     * @param options.per_page - Items per page (default: 50)
+     * @returns Prompts list with total count
+     *
+     * @example
+     * ```typescript
+     * // List all prompts
+     * const result = await client.templates.list();
+     * console.log(`Found ${result.total} prompts`);
+     *
+     * // Search and filter prompts
+     * const result = await client.templates.list({
+     *   search: 'customer',
+     *   risk_level: 'HIGH',
+     *   sort_by: 'updated_at',
+     *   sort_order: 'desc'
+     * });
+     *
+     * // Paginate results
+     * const result = await client.templates.list({
+     *   page: 1,
+     *   per_page: 20
+     * });
+     * ```
+     */
+    list(options?: ListPromptsOptions): Promise<ListPromptsResponse>;
+    /**
+     * Run a template (canary-aware)
+     *
+     * This method supports canary deployments:
+     * - If no version/env_label specified: Uses production with canary support
+     * - If specific version/env_label specified: Uses that version directly (no canary)
+     *
+     * @param identifier - Template ID or name
+     * @param options - Run options including variables, model overrides, and version selection
+     * @returns PromptLog with execution results
+     *
+     * @example
+     * ```typescript
+     * // Run template with production version (canary-aware)
+     * const result = await client.templates.run('my-template', {
+     *   variables: { name: 'John', topic: 'AI' }
+     * });
+     *
+     * // Run specific version (bypasses canary)
+     * const result = await client.templates.run('my-template', {
+     *   version: 3,
+     *   variables: { name: 'John' }
+     * });
+     *
+     * // Run with environment label
+     * const result = await client.templates.run('my-template', {
+     *   env_label: 'staging',
+     *   variables: { name: 'John' }
+     * });
+     *
+     * // Run with model override and tags
+     * const result = await client.templates.run('my-template', {
+     *   variables: { name: 'John' },
+     *   model: 'gpt-4',
+     *   pm_tags: ['production', 'customer-support']
+     * });
+     * ```
+     */
+    run(identifier: string, options?: RunTemplateOptions): Promise<PromptLog>;
+}
+
+/**
+ * Log resource for accessing prompt execution logs
+ */
+declare class LogResource extends BaseResource {
+    /**
+     * List prompt logs (SDK logs only by default)
+     *
+     * @param options - List options including filters, pagination
+     * @returns Array of prompt logs
+     *
+     * @example
+     * ```typescript
+     * // List all SDK logs (workspace_id from API key)
+     * const logs = await client.logs.list({});
+     *
+     * // Filter by template
+     * const logs = await client.logs.list({
+     *   template_id: 'template_123'
+     * });
+     *
+     * // Filter by template version
+     * const logs = await client.logs.list({
+     *   template_version_id: 'version_123'
+     * });
+     *
+     * // Filter by date range
+     * const logs = await client.logs.list({
+     *   start_date: '2024-01-01',
+     *   end_date: '2024-01-31'
+     * });
+     *
+     * // Filter by status
+     * const logs = await client.logs.list({
+     *   status: 'SUCCESS'
+     * });
+     *
+     * // Paginate and sort results
+     * const logs = await client.logs.list({
+     *   page: 1,
+     *   limit: 50,
+     *   sort_by: 'created_at',
+     *   sort_order: 'desc'
+     * });
+     * ```
+     */
+    list(options?: ListLogsOptions): Promise<PromptLog[]>;
+    /**
+     * Get a single prompt log by ID
+     *
+     * @param logId - Log ID
+     * @returns Prompt log details
+     *
+     * @example
+     * ```typescript
+     * const log = await client.logs.get('log_123');
+     * ```
+     */
+    get(logId: string): Promise<PromptLog>;
+}
+
+/**
+ * Template version resource for managing and executing specific versions
+ */
+declare class VersionResource extends BaseResource {
+    /**
+     * Get a template version
+     *
+     * @param versionId - Version ID
+     * @returns Template version details
+     *
+     * @example
+     * ```typescript
+     * // Get by version ID
+     * const version = await client.versions.get('version_123');
+     *
+     * // Get by template name + version number
+     * const version = await client.versions.get('my-template', 2);
+     *
+     * // Get by template ID + version number
+     * const version = await client.versions.get('template_123', 1);
+     * ```
+     */
+    get(versionId: string): Promise<TemplateVersion>;
+    get(templateIdentifier: string, versionNumber: number): Promise<TemplateVersion>;
+    /**
+     * Run a template version with variables
+     *
+     * Automatically correlates with active trace context if called within @traceable function.
+     * The prompt_log will be linked to the current trace for end-to-end observability.
+     *
+     * @param versionId - Version ID to run
+     * @param options - Run options including variables and parameters
+     * @returns Prompt execution log
+     *
+     * @example
+     * ```typescript
+     * // Run a version with variables
+     * const result = await client.versions.run('version_123', {
+     *   variables: {
+     *     user_name: 'John',
+     *     topic: 'AI'
+     *   }
+     * });
+     *
+     * // Run with custom parameters
+     * const result = await client.versions.run('version_123', {
+     *   variables: { topic: 'ML' },
+     *   parameters: {
+     *     temperature: 0.7,
+     *     max_tokens: 500
+     *   }
+     * });
+     *
+     * // Run with custom tags (stored directly in prompt log)
+     * const result = await client.versions.run('version_123', {
+     *   variables: { topic: 'AI' },
+     *   pm_tags: ['customer-support', 'high-priority', 'eu-region']
+     * });
+     *
+     * // Run within traced function (auto-correlation)
+     * @pm.traceable({ name: 'generate_response' })
+     * async generateResponse(input: string) {
+     *   // This run will be automatically linked to the trace
+     *   const result = await pm.versions.run('version_123', {
+     *     variables: { input }
+     *   });
+     *   return result;
+     * }
+     * ```
+     */
+    run(versionId: string, options?: RunVersionOptions): Promise<PromptLog>;
+    /**
+     * Update a template version
+     *
+     * @param versionId - Version ID to update
+     * @param options - Update options (env_label, metadata, etc.)
+     * @returns Updated template version
+     *
+     * @example
+     * ```typescript
+     * // Update environment label
+     * const version = await client.versions.update('version_123', {
+     *   env_label: 'production'
+     * });
+     *
+     * // Update metadata
+     * const version = await client.versions.update('version_123', {
+     *   metadata: {
+     *     deployed_by: 'John Doe',
+     *     deployment_date: '2024-01-15'
+     *   }
+     * });
+     *
+     * // Update both env_label and metadata
+     * const version = await client.versions.update('version_123', {
+     *   env_label: 'staging',
+     *   metadata: { tested: true },
+     * });
+     *
+     * ```
+     */
+    update(versionId: string, options: UpdateVersionOptions): Promise<TemplateVersion>;
+}
+
+/**
+ * Provider resource for accessing LLM providers and models
+ */
+declare class ProviderResource extends BaseResource {
+    /**
+     * List all LLM providers
+     *
+     * Returns providers with `has_key` flag indicating if user has configured API key
+     *
+     * @returns Array of LLM providers
+     *
+     * @example
+     * ```typescript
+     * // List all providers
+     * const providers = await client.providers.list();
+     *
+     * // Check which providers have keys configured
+     * const configuredProviders = providers.filter(p => p.has_key);
+     * ```
+     */
+    list(): Promise<LLMProvider[]>;
+    /**
+     * Get models for a specific provider by slug
+     *
+     * Returns provider details with all available models and parameters.
+     * Only returns models if user has API key configured for the provider.
+     *
+     * @param slug - Provider slug (e.g., 'openai', 'anthropic', 'google')
+     * @returns Provider with models and parameters
+     *
+     * @example
+     * ```typescript
+     * // Get OpenAI models
+     * const openai = await client.providers.getModels('openai');
+     * console.log(openai.models); // Array of OpenAI models
+     *
+     * // Get Anthropic models
+     * const anthropic = await client.providers.getModels('anthropic');
+     * console.log(anthropic.models); // Array of Claude models
+     *
+     * // Get Google models
+     * const google = await client.providers.getModels('google');
+     * console.log(google.models); // Array of Gemini models
+     * ```
+     */
+    getModels(slug: string): Promise<ProviderWithModels>;
+}
+
+/**
+ * Trace resource for tracking function execution and workflows
+ *
+ * @example
+ * ```typescript
+ * // Create a trace
+ * const trace = await client.traces.create({
+ *   trace_id: 'trace_123',
+ *   span_id: 'span_abc',
+ *   function_name: 'process_data',
+ *   start_time: new Date(),
+ *   end_time: new Date(),
+ *   duration_ms: 150,
+ *   status: 'SUCCESS'
+ * });
+ *
+ * // Add a score
+ * await client.traces.addScore('span_abc', {
+ *   criteria: 'accuracy',
+ *   value: 0.95
+ * });
+ *
+ * // Get trace tree
+ * const tree = await client.traces.getTrace('trace_123');
+ * ```
+ */
+declare class TraceResource extends BaseResource {
+    /**
+     * Create a new trace
+     *
+     * @param options - Trace creation options
+     * @returns Created trace
+     *
+     * @example
+     * ```typescript
+     * const trace = await client.traces.create({
+     *   trace_id: 'trace_123',
+     *   span_id: 'span_abc',
+     *   function_name: 'process_customer_data',
+     *   function_type: 'CUSTOM',
+     *   start_time: new Date('2025-12-08T10:00:00Z'),
+     *   end_time: new Date('2025-12-08T10:00:02Z'),
+     *   duration_ms: 2000,
+     *   status: 'SUCCESS',
+     *   metadata: {
+     *     customer_id: '12345',
+     *     processing_stage: 'enrichment'
+     *   }
+   * });
+     * ```
+     */
+    create(options: CreateTraceOptions): Promise<Trace>;
+    /**
+     * Create multiple traces in batch (optimized for high throughput)
+     *
+     * Reduces HTTP overhead by sending multiple traces in a single request.
+     * Supports partial success - some traces may succeed while others fail.
+     *
+     * @param traces - Array of trace creation options (max 100)
+     * @returns Batch result with created traces and errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.traces.createBatch([
+     *   {
+     *     trace_id: 'trace_123',
+     *     span_id: 'span_abc',
+     *     function_name: 'step_1',
+     *     start_time: new Date(),
+     *     end_time: new Date(),
+     *     duration_ms: 100,
+     *     status: 'SUCCESS'
+     *   },
+     *   {
+     *     trace_id: 'trace_123',
+     *     span_id: 'span_def',
+     *     function_name: 'step_2',
+     *     start_time: new Date(),
+     *     end_time: new Date(),
+     *     duration_ms: 200,
+     *     status: 'SUCCESS'
+     *   }
+     * ]);
+     *
+     * console.log(`Created: ${result.summary.successful}, Failed: ${result.summary.failed}`);
+     * ```
+     */
+    createBatch(traces: CreateTraceOptions[]): Promise<{
+        created: Trace[];
+        errors: Array<{
+            index: number;
+            error: string;
+        }>;
+        summary: {
+            total: number;
+            successful: number;
+            failed: number;
+        };
+    }>;
+    /**
+     * Add a score to a trace
+     *
+     * @param span_id - Span ID of the trace
+     * @param options - Score options
+     * @returns Updated trace with score
+     *
+     * @example
+     * ```typescript
+     * const trace = await client.traces.addScore('span_abc', {
+     *   criteria: 'coherence',
+     *   value: 0.92
+     * });
+     * ```
+     */
+    addScore(span_id: string, options: AddTraceScoreOptions): Promise<Trace>;
+    /**
+     * Update trace metadata
+     *
+     * @param span_id - Span ID of the trace
+     * @param options - Metadata update options
+     * @returns Updated trace
+     *
+     * @example
+     * ```typescript
+     * const trace = await client.traces.updateMetadata('span_abc', {
+     *   metadata: {
+     *     processing_result: 'completed',
+     *     items_processed: 150
+     *   }
+     * });
+     * ```
+     */
+    updateMetadata(span_id: string, options: UpdateTraceMetadataOptions): Promise<Trace>;
+    /**
+     * Get a single trace by span_id
+     *
+     * @param span_id - Span ID of the trace
+     * @returns Trace details
+     *
+     * @example
+     * ```typescript
+     * const trace = await client.traces.getBySpanId('span_abc');
+     * console.log(trace.function_name, trace.duration_ms);
+     * ```
+     */
+    getBySpanId(span_id: string): Promise<Trace>;
+    /**
+     * Get entire trace tree by trace_id
+     *
+     * Returns all spans in the trace organized as a tree structure
+     * with parent-child relationships
+     *
+     * @param trace_id - Trace ID
+     * @returns Array of trace tree nodes with nested children
+     *
+     * @example
+     * ```typescript
+     * const tree = await client.traces.getTrace('trace_123');
+     *
+     * // Tree structure with children
+     * tree.forEach(root => {
+     *   console.log(`Root: ${root.function_name}`);
+     *   root.children.forEach(child => {
+     *     console.log(`  Child: ${child.function_name}`);
+     *   });
+     * });
+     * ```
+     */
+    getTrace(trace_id: string): Promise<TraceTreeNode[]>;
+    /**
+     * Get all traces for a group_id
+     *
+     * @param group_id - Group ID (e.g., conversation_id, workflow_id)
+     * @returns Array of traces in the group
+     *
+     * @example
+     * ```typescript
+     * const traces = await client.traces.getGroup('conversation_abc');
+     * console.log(`Found ${traces.length} traces in conversation`);
+     * ```
+     */
+    getGroup(group_id: string): Promise<Trace[]>;
+    /**
+     * List traces with filters and pagination
+     *
+     * @param options - List options with filters
+     * @returns Paginated list of traces
+     *
+     * @example
+     * ```typescript
+     * // List all traces
+     * const result = await client.traces.list();
+     *
+     * // Filter by function name
+     * const filtered = await client.traces.list({
+     *   function_name: 'process_customer_data',
+     *   status: 'SUCCESS',
+     *   page: 1,
+     *   limit: 50
+     * });
+     *
+     * // Filter by date range
+     * const recent = await client.traces.list({
+     *   start_date: '2025-12-01T00:00:00Z',
+     *   end_date: '2025-12-08T23:59:59Z'
+     * });
+     * ```
+     */
+    list(options?: ListTracesOptions): Promise<TraceListResponse>;
+    /**
+     * Get trace analytics for workspace
+     *
+     * Returns aggregated statistics about trace execution including
+     * success rates, average duration, and function-level breakdown
+     *
+     * @param options - Optional date range filter
+     * @returns Analytics data
+     *
+     * @example
+     * ```typescript
+     * // Get all-time analytics
+     * const analytics = await client.traces.getAnalytics();
+     * console.log(`Success rate: ${analytics.success_rate}%`);
+     * console.log(`Avg duration: ${analytics.average_duration_ms}ms`);
+     *
+     * // Get analytics for date range
+     * const weeklyAnalytics = await client.traces.getAnalytics({
+     *   start_date: '2025-12-01T00:00:00Z',
+     *   end_date: '2025-12-08T23:59:59Z'
+     * });
+     *
+     * // Function breakdown
+     * analytics.function_breakdown.forEach(fn => {
+     *   console.log(`${fn.function_name}: ${fn.count} calls, ${fn.avg_duration_ms}ms avg`);
+     * });
+     * ```
+     */
+    getAnalytics(options?: {
+        start_date?: string;
+        end_date?: string;
+    }): Promise<TraceAnalytics>;
+    /**
+     * Delete old traces (cleanup)
+     *
+     * Deletes traces older than the specified date
+     *
+     * @param before_date - Delete traces before this date
+     * @returns Number of traces deleted
+     *
+     * @example
+     * ```typescript
+     * // Delete traces older than 90 days
+     * const ninetyDaysAgo = new Date();
+     * ninetyDaysAgo.setDate(ninetyDaysAgo.getDate() - 90);
+     *
+     * const result = await client.traces.cleanup(ninetyDaysAgo.toISOString());
+     * console.log(`Deleted ${result.deleted_count} old traces`);
+     * ```
+     */
+    cleanup(before_date: string): Promise<{
+        deleted_count: number;
+    }>;
+}
+
+/**
+ * Track helper for context-aware metadata, score, and group tracking
+ * Similar to Python's pm.track.metadata(), pm.track.score(), pm.track.group()
+ *
+ * All tracking methods collect data in context, which is sent when the trace is created.
+ */
+declare class Track {
+    /**
+     * Add metadata to the current span
+     * Metadata is collected in context and sent when the trace is created
+     *
+     * @example
+     * ```typescript
+     * pm.track.metadata({
+     *   customer_id: '12345',
+     *   processing_stage: 'enrichment'
+     * });
+     * ```
+     */
+    metadata(extraData: Record<string, unknown>): void;
+    /**
+     * Add a score to the current span
+     * Score is collected in context and sent when the trace is created
+     *
+     * @example
+     * ```typescript
+     * pm.track.score({
+     *   criteria: 'coherence',
+     *   value: 0.92
+     * });
+     * ```
+     */
+    score(options: {
+        criteria: string;
+        value: number;
+    }): void;
+    /**
+     * Set group for current context and all child spans
+     * Uses context to propagate group to nested functions
+     *
+     * @example
+     * ```typescript
+     * pm.track.group({
+     *   group_id: 'conversation_abc',
+     *   group_type: 'conversation'  // Flexible - use any string
+     * });
+     * ```
+     */
+    group(options: {
+        group_id: string;
+        group_type: string;
+    }): void;
+}
+
+/**
+ * Main PromptMetrics SDK client
+ *
+ * @example
+ * ```typescript
+ * import { PromptMetrics } from '@promptmetrics/sdk';
+ *
+ * const client = new PromptMetrics({
+ *   apiKey: 'pm_xxxxxxxxxxxxx'
+ * });
+ *
+ * // Run a template
+ * const result = await client.templates.run('customer-support', {
+ *   workspace_id: 'workspace_123',
+ *   label: 'production',
+ *   variables: { customer_name: 'John', issue: 'billing' }
+ * });
+ *
+ * // Get logs
+ * const logs = await client.logs.list({
+ *   workspace_id: 'workspace_123',
+ *   limit: 100
+ * });
+ * ```
+ */
+declare class PromptMetrics {
+    private httpClient;
+    /** Template operations */
+    templates: TemplateResource;
+    /** Template version operations */
+    versions: VersionResource;
+    /** Log operations */
+    logs: LogResource;
+    /** Provider and model operations */
+    providers: ProviderResource;
+    /** Trace and tracking operations */
+    traces: TraceResource;
+    /** Track helper for context-aware metadata, score, and group tracking */
+    track: Track;
+    /**
+     * Create a new PromptMetrics client
+     *
+     * @param config - Configuration options
+     * @throws {ValidationError} If API key is missing or invalid
+     */
+    constructor(config: PromptMetricsConfig);
+    /**
+     * Create a @traceable decorator for automatic function tracking
+     *
+     * @param options - Decorator options
+     * @returns Decorator function
+     *
+     * @example
+     * ```typescript
+     * class MyService {
+     *   @pm.traceable({ name: 'process_data' })
+     *   async processData(input: string) {
+     *     // Automatically tracked
+     *     return result;
+     *   }
+     * }
+     * ```
+     */
+    traceable(options?: TraceableOptions): (_target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+    /**
+     * Get current trace ID from context
+     */
+    getCurrentTraceId(): string | undefined;
+    /**
+     * Get current span ID from context
+     */
+    getCurrentSpanId(): string | undefined;
+    /**
+     * Validate configuration
+     */
+    private validateConfig;
+}
+
+/**
+ * Base error class for PromptMetrics SDK
+ */
+declare class PromptMetricsError extends Error {
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(message: string, statusCode?: number, code?: string, details?: unknown);
+    /**
+     * Custom JSON serialization to include message field
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication error (401)
+ */
+declare class AuthenticationError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Authorization error (403)
+ */
+declare class AuthorizationError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Not found error (404)
+ */
+declare class NotFoundError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Validation error (400)
+ */
+declare class ValidationError extends PromptMetricsError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Rate limit error (429)
+ */
+declare class RateLimitError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Server error (500)
+ */
+declare class ServerError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Network error
+ */
+declare class NetworkError extends PromptMetricsError {
+    constructor(message?: string);
+}
+/**
+ * Timeout error
+ */
+declare class TimeoutError extends PromptMetricsError {
+    constructor(message?: string);
+}
+
+/**
+ * @promptmetrics/sdk
+ *
+ * Official TypeScript/JavaScript SDK for PromptMetrics API
+ *
+ * @example
+ * ```typescript
+ * import { PromptMetrics } from '@promptmetrics/sdk';
+ *
+ * const client = new PromptMetrics({
+ *   apiKey: process.env.PROMPTMETRICS_API_KEY
+ * });
+ *
+ * const result = await client.templates.run('my-template', {
+ *   workspace_id: 'workspace_123',
+ *   label: 'production',
+ *   variables: { name: 'John' }
+ * });
+ * ```
+ */
+
+declare const VERSION = "1.0.0";
+
+export { type AddTraceScoreOptions, AuthenticationError, AuthorizationError, type CreateTraceOptions, type GetTemplateOptions, type LLMModel, type LLMProvider, type ListLogsOptions, type ListPromptsOptions, type ListPromptsResponse, type ListTracesOptions, type Message, NetworkError, NotFoundError, type PromptLog, PromptMetrics, type PromptMetricsConfig, PromptMetricsError, type PromptMetricsErrorResponse, type ProviderWithModels, RateLimitError, type RunTemplateOptions, type RunVersionOptions, ServerError, type Template, type TemplateMetadata, type TemplateOptions, type TemplateVersion, TimeoutError, type Trace, type TraceAnalytics, type TraceError, type TraceListResponse, type TraceScore, type TraceStatus, type TraceTreeNode, type TraceableOptions, type UpdateTraceMetadataOptions, type UpdateVersionOptions, VERSION, ValidationError };