@promptmetrics/sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,1373 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  AuthorizationError: () => AuthorizationError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  PromptMetrics: () => PromptMetrics,
+  PromptMetricsError: () => PromptMetricsError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/http.ts
+var import_axios = __toESM(require("axios"));
+
+// src/utils/errors.ts
+var PromptMetricsError = class extends Error {
+  constructor(message, statusCode, code, details) {
+    super(message);
+    this.name = "PromptMetricsError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Custom JSON serialization to include message field
+   */
+  toJSON() {
+    const result = {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      code: this.code
+    };
+    if (this.details !== void 0) {
+      result.details = this.details;
+    }
+    return result;
+  }
+};
+var AuthenticationError = class extends PromptMetricsError {
+  constructor(message = "Invalid API key or authentication failed") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends PromptMetricsError {
+  constructor(message = "You do not have permission to access this resource") {
+    super(message, 403, "AUTHORIZATION_ERROR");
+    this.name = "AuthorizationError";
+  }
+};
+var NotFoundError = class extends PromptMetricsError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND_ERROR");
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends PromptMetricsError {
+  constructor(message = "Invalid request parameters", details) {
+    super(message, 400, "VALIDATION_ERROR", details);
+    this.name = "ValidationError";
+  }
+};
+var RateLimitError = class extends PromptMetricsError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429, "RATE_LIMIT_ERROR");
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends PromptMetricsError {
+  constructor(message = "Internal server error") {
+    super(message, 500, "SERVER_ERROR");
+    this.name = "ServerError";
+  }
+};
+var NetworkError = class extends PromptMetricsError {
+  constructor(message = "Network request failed") {
+    super(message, void 0, "NETWORK_ERROR");
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends PromptMetricsError {
+  constructor(message = "Request timeout") {
+    super(message, 408, "TIMEOUT_ERROR");
+    this.name = "TimeoutError";
+  }
+};
+
+// src/utils/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.maxRetries = config.maxRetries || 3;
+    this.debug = config.debug || false;
+    this.client = import_axios.default.create({
+      baseURL: config.baseURL,
+      timeout: config.timeout || 3e4,
+      headers: {
+        "Authorization": `Bearer ${config.apiKey}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (this.debug) {
+      this.client.interceptors.request.use((request) => {
+        console.log("[PromptMetrics SDK] Request:", {
+          method: request.method,
+          url: request.url,
+          params: request.params,
+          data: request.data
+        });
+        return request;
+      });
+    }
+    if (this.debug) {
+      this.client.interceptors.response.use(
+        (response) => {
+          console.log("[PromptMetrics SDK] Response:", {
+            status: response.status,
+            data: response.data
+          });
+          return response;
+        },
+        (error) => {
+          console.error("[PromptMetrics SDK] Error:", error);
+          return Promise.reject(error);
+        }
+      );
+    }
+  }
+  /**
+   * Make HTTP request with retry logic
+   */
+  async request(config) {
+    let lastError;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const response = await this.client.request(config);
+        return response.data;
+      } catch (error) {
+        lastError = this.handleError(error);
+        if (!this.shouldRetry(error) || attempt === this.maxRetries - 1) {
+          throw lastError;
+        }
+        const delay = Math.min(1e3 * Math.pow(2, attempt), 1e4);
+        await this.sleep(delay);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * GET request
+   */
+  async get(url, config) {
+    return this.request({ ...config, method: "GET", url });
+  }
+  /**
+   * POST request
+   */
+  async post(url, data, config) {
+    return this.request({ ...config, method: "POST", url, data });
+  }
+  /**
+   * PUT request
+   */
+  async put(url, data, config) {
+    return this.request({ ...config, method: "PUT", url, data });
+  }
+  /**
+   * PATCH request
+   */
+  async patch(url, data, config) {
+    return this.request({ ...config, method: "PATCH", url, data });
+  }
+  /**
+   * DELETE request
+   */
+  async delete(url, config) {
+    return this.request({ ...config, method: "DELETE", url });
+  }
+  /**
+   * Handle axios errors and convert to SDK errors
+   * Extracts details from backend HttpException format
+   */
+  handleError(error) {
+    if (!error.response) {
+      if (error.code === "ECONNABORTED") {
+        return new TimeoutError("Request timeout");
+      }
+      return new NetworkError(error.message || "Network request failed");
+    }
+    const { status, data } = error.response;
+    const errorData = data;
+    const message = errorData?.message || error.message || "An error occurred";
+    const details = errorData?.data;
+    switch (status) {
+      case 401:
+        return new AuthenticationError(message);
+      case 403:
+        return new AuthorizationError(message);
+      case 404:
+        return new NotFoundError(message);
+      case 400:
+        return new ValidationError(message, details);
+      case 429:
+        return new RateLimitError(message);
+      case 500:
+      case 502:
+      case 503:
+      case 504:
+        return new ServerError(message);
+      default:
+        return new PromptMetricsError(message, status, void 0, details);
+    }
+  }
+  /**
+   * Determine if request should be retried
+   */
+  shouldRetry(error) {
+    if (!error.response) {
+      return true;
+    }
+    const status = error.response.status;
+    return status >= 500 || status === 429;
+  }
+  /**
+   * Sleep utility for retry backoff
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/resources/base.ts
+var BaseResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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
+   */
+  transformResponse(backendResponse) {
+    if (typeof backendResponse === "object" && backendResponse !== null && "responseData" in backendResponse && backendResponse.responseData?.data !== void 0) {
+      return backendResponse.responseData.data;
+    }
+    return backendResponse;
+  }
+};
+
+// src/resources/templates.ts
+var TemplateResource = class 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'
+   * });
+   * ```
+   */
+  async get(identifier, options) {
+    const response = await this.http.get(
+      `/template/${identifier}`,
+      {
+        params: options || {}
+      }
+    );
+    const template = this.transformResponse(response);
+    if (!options?.version && !options?.env_label && template.versions) {
+      const productionVersion = template.versions.find(
+        (v) => v.env_label === "production"
+      );
+      if (productionVersion) {
+        template.versions = [productionVersion];
+      } else {
+        const latestVersion = template.versions.reduce(
+          (latest, current) => current.version > latest.version ? current : latest
+        );
+        template.versions = [latestVersion];
+      }
+    }
+    return 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
+   * });
+   * ```
+   */
+  async list(options) {
+    const response = await this.http.get(
+      "/template/prompts",
+      {
+        params: options || {}
+      }
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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']
+   * });
+   * ```
+   */
+  async run(identifier, options) {
+    const response = await this.http.post(
+      `/template/${identifier}/run`,
+      options || {}
+    );
+    return this.transformResponse(response);
+  }
+};
+
+// src/resources/logs.ts
+var LogResource = class 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'
+   * });
+   * ```
+   */
+  async list(options = {}) {
+    const params = {
+      source: "SDK",
+      ...options
+    };
+    const response = await this.http.get(
+      "/prompt-logs",
+      {
+        params
+      }
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async get(logId) {
+    const response = await this.http.get(
+      `/prompt-logs/${logId}`
+    );
+    return this.transformResponse(response);
+  }
+};
+
+// src/utils/context.ts
+var import_async_hooks = require("async_hooks");
+var ContextManager = class {
+  constructor() {
+    this.storage = new import_async_hooks.AsyncLocalStorage();
+  }
+  /**
+   * Get current trace context
+   */
+  getContext() {
+    return this.storage.getStore();
+  }
+  /**
+   * Get current trace ID
+   */
+  getCurrentTraceId() {
+    return this.getContext()?.trace_id;
+  }
+  /**
+   * Get current span ID
+   */
+  getCurrentSpanId() {
+    return this.getContext()?.span_id;
+  }
+  /**
+   * Get current parent span ID
+   */
+  getParentSpanId() {
+    return this.getContext()?.parent_span_id;
+  }
+  /**
+   * Get current group ID
+   */
+  getGroupId() {
+    return this.getContext()?.group_id;
+  }
+  /**
+   * Get current group type
+   */
+  getGroupType() {
+    return this.getContext()?.group_type;
+  }
+  /**
+   * Get current metadata
+   */
+  getMetadata() {
+    return this.getContext()?.metadata;
+  }
+  /**
+   * Run function with new context
+   */
+  run(context, fn) {
+    return this.storage.run(context, fn);
+  }
+  /**
+   * Run async function with new context
+   */
+  async runAsync(context, fn) {
+    return this.storage.run(context, fn);
+  }
+  /**
+   * Update current context (merge with existing)
+   */
+  updateContext(updates) {
+    const current = this.getContext();
+    if (current) {
+      Object.assign(current, updates);
+    }
+  }
+  /**
+   * Set group for current context and all child spans
+   */
+  updateGroup(group_id, group_type) {
+    this.updateContext({ group_id, group_type });
+  }
+  /**
+   * Add metadata to current context
+   */
+  addMetadata(metadata) {
+    const current = this.getContext();
+    if (current) {
+      current.metadata = { ...current.metadata, ...metadata };
+    }
+  }
+  /**
+   * Add score to current context
+   */
+  addScore(score) {
+    const current = this.getContext();
+    if (current) {
+      if (!current.scores) {
+        current.scores = [];
+      }
+      const scoreWithTimestamp = {
+        ...score,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      current.scores.push(scoreWithTimestamp);
+    }
+  }
+};
+var contextManager = new ContextManager();
+
+// src/resources/versions.ts
+var VersionResource = class extends BaseResource {
+  async get(identifier, versionNumber) {
+    if (versionNumber !== void 0) {
+      const response = await this.http.get(
+        `/template-version/${identifier}`,
+        { params: { version: versionNumber } }
+      );
+      return this.transformResponse(response);
+    } else {
+      const response = await this.http.get(
+        `/template-version/${identifier}`
+      );
+      return this.transformResponse(response);
+    }
+  }
+  /**
+   * 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;
+   * }
+   * ```
+   */
+  async run(versionId, options) {
+    const context = contextManager.getContext();
+    const requestPayload = {
+      ...options,
+      // Include trace correlation data if available
+      trace_id: context?.trace_id,
+      span_id: context?.span_id,
+      group_id: context?.group_id
+    };
+    const response = await this.http.post(
+      `/template-version/${versionId}/run`,
+      requestPayload
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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 },
+   * });
+   *
+   * ```
+   */
+  async update(versionId, options) {
+    const response = await this.http.put(
+      `/template-version/${versionId}`,
+      options
+    );
+    return this.transformResponse(response);
+  }
+};
+
+// src/resources/providers.ts
+var ProviderResource = class 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);
+   * ```
+   */
+  async list() {
+    const response = await this.http.get(
+      "/llm-provider"
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async getModels(slug) {
+    const response = await this.http.get(
+      `/llm-provider/${slug}/models`
+    );
+    return this.transformResponse(response);
+  }
+};
+
+// src/resources/traces.ts
+var TraceResource = class 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'
+    *   }
+  * });
+    * ```
+    */
+  async create(options) {
+    const response = await this.http.post(
+      "/traces",
+      options
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async createBatch(traces) {
+    if (!traces || traces.length === 0) {
+      throw new Error("Traces array cannot be empty");
+    }
+    if (traces.length > 100) {
+      throw new Error("Maximum 100 traces allowed per batch");
+    }
+    const response = await this.http.post("/traces/batch", { traces });
+    return this.transformResponse(response);
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async addScore(span_id, options) {
+    const response = await this.http.post(
+      `/traces/${span_id}/score`,
+      options
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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
+   *   }
+   * });
+   * ```
+   */
+  async updateMetadata(span_id, options) {
+    const response = await this.http.patch(
+      `/traces/${span_id}/metadata`,
+      options
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getBySpanId(span_id) {
+    const response = await this.http.get(
+      `/traces/span/${span_id}`
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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}`);
+   *   });
+   * });
+   * ```
+   */
+  async getTrace(trace_id) {
+    const response = await this.http.get(
+      `/traces/trace/${trace_id}`
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async getGroup(group_id) {
+    const response = await this.http.get(
+      `/traces/group/${group_id}`
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async list(options) {
+    const response = await this.http.get(
+      "/traces",
+      { params: options }
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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`);
+   * });
+   * ```
+   */
+  async getAnalytics(options) {
+    const response = await this.http.get(
+      "/traces/analytics",
+      { params: options }
+    );
+    return this.transformResponse(response);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async cleanup(before_date) {
+    const response = await this.http.delete("/traces/cleanup", {
+      data: { before_date }
+    });
+    return this.transformResponse(response);
+  }
+};
+
+// src/utils/track.ts
+var Track = class {
+  /**
+   * 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) {
+    const spanId = contextManager.getCurrentSpanId();
+    if (!spanId) {
+      throw new Error(
+        "No active span context. metadata() must be called within a @traceable function."
+      );
+    }
+    contextManager.addMetadata(extraData);
+  }
+  /**
+   * 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) {
+    const spanId = contextManager.getCurrentSpanId();
+    if (!spanId) {
+      throw new Error(
+        "No active span context. score() must be called within a @traceable function."
+      );
+    }
+    contextManager.addScore(options);
+  }
+  /**
+   * 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) {
+    contextManager.updateGroup(options.group_id, options.group_type);
+  }
+};
+
+// src/utils/id-generator.ts
+var import_crypto = require("crypto");
+var IdGenerator = class {
+  /**
+   * Generate a unique trace ID
+   */
+  static generateTraceId() {
+    return `trace_${Date.now()}_${(0, import_crypto.randomBytes)(8).toString("hex")}`;
+  }
+  /**
+   * Generate a unique span ID
+   */
+  static generateSpanId() {
+    return `span_${Date.now()}_${(0, import_crypto.randomBytes)(8).toString("hex")}`;
+  }
+  /**
+   * Generate a unique group ID
+   */
+  static generateGroupId(prefix = "group") {
+    return `${prefix}_${Date.now()}_${(0, import_crypto.randomBytes)(8).toString("hex")}`;
+  }
+};
+
+// src/decorators/traceable.ts
+function traceable(traceResource, options = {}) {
+  return function(_target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    if (options.disabled) {
+      return descriptor;
+    }
+    descriptor.value = async function(...args) {
+      const functionName = options.name || propertyKey;
+      const currentContext = contextManager.getContext();
+      const trace_id = currentContext?.trace_id || IdGenerator.generateTraceId();
+      const span_id = IdGenerator.generateSpanId();
+      const parent_span_id = currentContext?.span_id;
+      const group_id = currentContext?.group_id;
+      const group_type = currentContext?.group_type;
+      const tags = [...currentContext?.tags || [], ...options.tags || []];
+      const metadata = {
+        ...currentContext?.metadata,
+        ...options.metadata
+      };
+      const start_time = /* @__PURE__ */ new Date();
+      let status = "SUCCESS";
+      let error;
+      let result;
+      let input;
+      let output;
+      let capturedContext;
+      if (args.length > 0) {
+        input = {};
+        args.slice(0, 3).forEach((arg, index) => {
+          try {
+            input[`arg_${index}`] = JSON.parse(JSON.stringify(arg));
+          } catch {
+            input[`arg_${index}`] = String(arg);
+          }
+        });
+      }
+      try {
+        result = await contextManager.runAsync(
+          {
+            trace_id,
+            span_id,
+            parent_span_id,
+            group_id,
+            group_type,
+            tags,
+            metadata,
+            scores: []
+            // Initialize empty scores array
+          },
+          async () => {
+            const res = await originalMethod.apply(this, args);
+            capturedContext = contextManager.getContext();
+            return res;
+          }
+        );
+        try {
+          const serialized = JSON.parse(JSON.stringify(result));
+          if (Array.isArray(serialized)) {
+            output = { result: serialized };
+          } else if (typeof serialized === "object" && serialized !== null) {
+            output = serialized;
+          } else {
+            output = { result: serialized };
+          }
+        } catch {
+          output = { result: String(result) };
+        }
+      } catch (err) {
+        status = "ERROR";
+        error = {
+          message: err instanceof Error ? err.message : String(err),
+          stack: err instanceof Error ? err.stack : void 0,
+          code: err.code
+        };
+        throw err;
+      } finally {
+        const end_time = /* @__PURE__ */ new Date();
+        const duration_ms = end_time.getTime() - start_time.getTime();
+        try {
+          const contextScores = capturedContext?.scores;
+          const contextMetadata = capturedContext?.metadata || {};
+          const finalMetadata = {
+            ...metadata,
+            ...contextMetadata
+          };
+          await traceResource.create({
+            trace_id,
+            span_id,
+            parent_span_id,
+            function_name: functionName,
+            start_time,
+            end_time,
+            duration_ms,
+            status,
+            error,
+            input,
+            output,
+            metadata: finalMetadata,
+            scores: contextScores,
+            tags,
+            group_id,
+            group_type
+          });
+        } catch (traceError) {
+          console.error("[PromptMetrics] Failed to send trace:", traceError);
+        }
+      }
+      return result;
+    };
+    return descriptor;
+  };
+}
+function createTraceableDecorator(traceResource) {
+  return (options = {}) => traceable(traceResource, options);
+}
+
+// src/client.ts
+var PromptMetrics = class {
+  /**
+   * Create a new PromptMetrics client
+   *
+   * @param config - Configuration options
+   * @throws {ValidationError} If API key is missing or invalid
+   */
+  constructor(config) {
+    this.validateConfig(config);
+    const baseURL = process.env.BASE_URL;
+    if (!baseURL) {
+      throw new ValidationError(
+        "BASE_URL environment variable is required. Please set it in your .env file."
+      );
+    }
+    this.httpClient = new HttpClient({
+      baseURL,
+      apiKey: config.apiKey,
+      timeout: config.timeout,
+      maxRetries: config.maxRetries,
+      debug: config.debug
+    });
+    this.templates = new TemplateResource(this.httpClient);
+    this.versions = new VersionResource(this.httpClient);
+    this.logs = new LogResource(this.httpClient);
+    this.providers = new ProviderResource(this.httpClient);
+    this.traces = new TraceResource(this.httpClient);
+    this.track = new Track();
+  }
+  /**
+   * 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 = {}) {
+    return createTraceableDecorator(this.traces)(options);
+  }
+  /**
+   * Get current trace ID from context
+   */
+  getCurrentTraceId() {
+    return contextManager.getCurrentTraceId();
+  }
+  /**
+   * Get current span ID from context
+   */
+  getCurrentSpanId() {
+    return contextManager.getCurrentSpanId();
+  }
+  /**
+   * Validate configuration
+   */
+  validateConfig(config) {
+    if (!config.apiKey) {
+      throw new ValidationError(
+        "API key is required. Please provide a valid workspace API key (starts with pm_)."
+      );
+    }
+    if (typeof config.apiKey !== "string") {
+      throw new ValidationError("API key must be a string.");
+    }
+    if (!config.apiKey.startsWith("pm_")) {
+      throw new ValidationError(
+        'Invalid API key format. Workspace API keys should start with "pm_".'
+      );
+    }
+    if (config.apiKey.length < 20) {
+      throw new ValidationError(
+        "API key appears to be too short. Please check your API key."
+      );
+    }
+  }
+};
+
+// src/index.ts
+var VERSION = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  AuthorizationError,
+  NetworkError,
+  NotFoundError,
+  PromptMetrics,
+  PromptMetricsError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  VERSION,
+  ValidationError
+});