langwatch 0.5.1 → 0.7.1

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-DTEZr0Jn.mjs';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-fAgqv8OM.mjs';
+import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.mjs';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-nE9dgTwc.mjs';
 export { l as attributes } from './types-DRiQaKFG.mjs';
-import { p as paths, P as PromptResponse, g as Prompt } from './types-jrEEZt9d.mjs';
+import { p as paths, P as PromptResponse, g as CreatePromptBody, U as UpdatePromptBody, h as PromptData, i as Prompt } from './types-DbPAi4US.mjs';
 import openApiCreateClient from 'openapi-fetch';
+import { z } from 'zod';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/exporter-trace-otlp-http';
 import '@opentelemetry/api-logs';
@@ -10,16 +11,20 @@ import '@opentelemetry/api';
 import '@opentelemetry/semantic-conventions';
 import '@opentelemetry/semantic-conventions/incubating';
 
-type LangwatchApiClient = ReturnType<typeof openApiCreateClient<paths>>;
+/**
+ * Creates a new LangWatch API client.
+ * @param apiKey - The API key to use for authentication. Defaults to LANGWATCH_API_KEY environment variable.
+ * @param endpoint - The endpoint to use for the API client. Defaults to LANGWATCH_ENDPOINT environment variable or internal DEFAULT_ENDPOINT.
+ * @returns A new LangWatch API client.
+ */
+declare const createLangWatchApiClient: (apiKey?: string, endpoint?: string) => openApiCreateClient.Client<paths, `${string}/${string}`>;
+type LangwatchApiClient = ReturnType<typeof createLangWatchApiClient>;
 
 interface InternalConfig {
     langwatchApiClient: LangwatchApiClient;
     logger: Logger;
 }
 
-type CreatePromptBody = NonNullable<paths["/api/prompts"]["post"]["requestBody"]>["content"]["application/json"];
-type UpdatePromptBody = NonNullable<paths["/api/prompts/{id}"]["put"]["requestBody"]>["content"]["application/json"];
-
 type SyncAction = "created" | "updated" | "conflict" | "up_to_date";
 type ConfigData = NonNullable<paths["/api/prompts/{id}/sync"]["post"]["requestBody"]>["content"]["application/json"]["configData"];
 interface SyncResult {
@@ -32,15 +37,255 @@ interface SyncResult {
         remoteConfigData: ConfigData;
     };
 }
+/**
+ * Service for managing prompt resources via the Langwatch API.
+ * Constructor creates a proxy that wraps the service and traces all methods.
+ *
+ * Responsibilities:
+ * - CRUD operations for prompts
+ * - Creating prompt versions
+ * - Error handling with contextual information
+ *
+ * All methods return raw PromptResponse data from the API.
+ */
+declare class PromptsApiService {
+    private readonly apiClient;
+    constructor(config?: Pick<InternalConfig, "langwatchApiClient">);
+    /**
+     * Handles API errors by throwing a PromptsError with operation context.
+     * @param operation Description of the operation being performed.
+     * @param error The error object returned from the API client.
+     * @throws {PromptsError}
+     */
+    private handleApiError;
+    /**
+     * Fetches all prompts from the API.
+     * @returns Array of raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    getAll(): Promise<PromptResponse[]>;
+    /**
+     * Fetches a single prompt by its ID.
+     * @param id The prompt's unique identifier.
+     * @returns Raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    get: (id: string, options?: {
+        version?: string;
+    }) => Promise<PromptResponse>;
+    /**
+     * Validates if a prompt exists.
+     * @param id The prompt's unique identifier.
+     * @returns True if prompt exists, false otherwise.
+     * @throws {PromptsError} If the API call fails (not 404).
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Creates a new prompt.
+     * @param params The prompt creation payload, matching the OpenAPI schema.
+     * @returns Raw PromptResponse data of the created prompt.
+     * @throws {PromptsError} If the API call fails.
+     */
+    create(params: CreatePromptBody): Promise<PromptResponse>;
+    /**
+     * Updates an existing prompt.
+     * @param id The prompt's unique identifier.
+     * @param params The update payload, matching the OpenAPI schema.
+     * @returns Raw PromptResponse data of the updated prompt.
+     * @throws {PromptsError} If the API call fails.
+     */
+    update(id: string, params: UpdatePromptBody): Promise<PromptResponse>;
+    /**
+     * Deletes a prompt by its ID.
+     * @param id The prompt's unique identifier.
+     * @throws {PromptsError} If the API call fails.
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Fetches all versions for a given prompt.
+     * @param id The prompt's unique identifier.
+     * @returns Array of raw PromptResponse data for each version.
+     * @throws {PromptsError} If the API call fails.
+     */
+    getVersions(id: string): Promise<PromptResponse[]>;
+    /**
+     * Upserts a prompt with local configuration - creates if doesn't exist, updates version if exists.
+     * @param handle The prompt's handle/identifier.
+     * @param config Local prompt configuration.
+     * @returns Object with created flag and raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    upsert(handle: string, config: {
+        model: string;
+        modelParameters?: {
+            temperature?: number;
+            max_tokens?: number;
+        };
+        messages: Array<{
+            role: "system" | "user" | "assistant";
+            content: string;
+        }>;
+    }): Promise<{
+        created: boolean;
+        prompt: PromptResponse;
+    }>;
+    /**
+     * Sync a prompt with local content, handling conflicts and version management
+     */
+    sync(params: {
+        name: string;
+        configData: ConfigData;
+        localVersion?: number;
+        commitMessage?: string;
+    }): Promise<SyncResult>;
+}
+
+type PromptDependency = string | {
+    version?: string;
+    file?: string;
+};
+type PromptsConfig = {
+    prompts: Record<string, PromptDependency>;
+};
+declare const localPromptConfigSchema: z.ZodObject<{
+    model: z.ZodString;
+    modelParameters: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        content: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type LocalPromptConfig = z.infer<typeof localPromptConfigSchema>;
+type MaterializedPrompt = {
+    id: string;
+    name: string;
+    version: number;
+    versionId: string;
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    prompt: string;
+    temperature?: number;
+    maxTokens?: number;
+    inputs?: any;
+    outputs?: any;
+    updatedAt: string;
+};
+type PromptsLockEntry = {
+    version: number;
+    versionId: string;
+    materialized: string;
+};
+type PromptsLock = {
+    lockfileVersion: number;
+    prompts: Record<string, PromptsLockEntry>;
+};
+
+declare class FileManager {
+    private static readonly PROMPTS_CONFIG_FILE;
+    private static readonly PROMPTS_LOCK_FILE;
+    private static readonly PROMPTS_DIR;
+    private static readonly MATERIALIZED_DIR;
+    static getPromptsConfigPath(): string;
+    static getPromptsLockPath(): string;
+    static getPromptsDir(): string;
+    static getMaterializedDir(): string;
+    static ensureDirectories(): void;
+    static loadPromptsConfig(): PromptsConfig;
+    static savePromptsConfig(config: PromptsConfig): void;
+    static initializePromptsConfig(): {
+        created: boolean;
+        path: string;
+    };
+    static loadPromptsLock: () => PromptsLock;
+    static savePromptsLock(lock: PromptsLock): void;
+    static initializePromptsLock(): {
+        created: boolean;
+        path: string;
+    };
+    static loadLocalPrompt: (filePath: string) => LocalPromptConfig;
+    static saveMaterializedPrompt(name: string, prompt: MaterializedPrompt): string;
+    static getLocalPromptFiles: () => string[];
+    static promptNameFromPath(filePath: string): string;
+    static cleanupOrphanedMaterializedFiles(currentDependencies: Set<string>): string[];
+    static updateLockEntry(lock: PromptsLock, name: string, prompt: MaterializedPrompt, materializedPath: string): void;
+    static removeFromLock(lock: PromptsLock, names: string[]): void;
+    static addToGitignore(entry: string): {
+        added: boolean;
+        existed: boolean;
+    };
+}
+
+interface LocalPromptsServiceConfig {
+    fileManager?: typeof FileManager;
+    logger?: Logger;
+}
+/**
+ * Service for retrieving prompts from local filesystem sources.
+ *
+ * Searches for prompts in the following priority order:
+ * 1. Explicit file mapping in prompts.json config
+ * 2. Materialized path from prompts-lock.json
+ * 3. Direct file scanning in prompts directory
+ */
+declare class LocalPromptsService {
+    private readonly fileManager;
+    private readonly logger;
+    constructor(config?: LocalPromptsServiceConfig);
+    /**
+     * Retrieves a prompt using the configured search strategy.
+     * Tries each source in priority order until found or all sources exhausted.
+     */
+    get(handleOrId: string): Promise<PromptData | null>;
+    /**
+     * Searches for prompt using explicit file mapping in prompts.json.
+     * Looks for dependencies with a 'file' property pointing to a specific path.
+     */
+    private getFromConfig;
+    /**
+     * Searches for prompt using materialized path from lock file.
+     * Lock file contains resolved paths for prompts that have been synced/materialized.
+     */
+    private getFromLockFile;
+    /**
+     * Searches for prompt by scanning all .prompt.yaml files in prompts directory.
+     * Extracts prompt name from file path and matches against the requested handle.
+     * This is the fallback method when explicit mappings don't exist.
+     */
+    private getFromLocalFiles;
+    /**
+     * Get dependency from config
+     */
+    private getDependencyFromConfig;
+    /**
+     * Converts LocalPromptConfig to PromptData format
+     */
+    private convertToPromptData;
+}
 
+interface PromptsFacadeDependencies {
+    promptsApiService: PromptsApiService;
+    localPromptsService: LocalPromptsService;
+}
 /**
  * Facade for prompt operations in the LangWatch SDK.
  * Provides a simplified interface for common prompt management tasks.
  */
 declare class PromptsFacade {
-    private readonly service;
-    private readonly config;
-    constructor(config: InternalConfig);
+    private readonly promptsApiService;
+    private readonly localPromptsService;
+    constructor(config: InternalConfig & PromptsFacadeDependencies);
     /**
      * Creates a new prompt.
      * @param data The prompt creation payload.
@@ -115,10 +360,10 @@ interface LangWatchConstructorOptions {
 declare class LangWatch {
     #private;
     private readonly config;
-    private readonly tracer;
     readonly prompts: PromptsFacade;
     readonly traces: TracesFacade;
     constructor(options?: LangWatchConstructorOptions);
+    get apiClient(): LangwatchApiClient;
 }
 
 declare const logger: {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-DTEZr0Jn.js';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-BIlL6-SW.js';
+import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.js';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-DsHp9FYU.js';
 export { l as attributes } from './types-DRiQaKFG.js';
-import { p as paths, P as PromptResponse, g as Prompt } from './types-DyUmlaDx.js';
+import { p as paths, P as PromptResponse, g as CreatePromptBody, U as UpdatePromptBody, h as PromptData, i as Prompt } from './types-B9772cUR.js';
 import openApiCreateClient from 'openapi-fetch';
+import { z } from 'zod';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/exporter-trace-otlp-http';
 import '@opentelemetry/api-logs';
@@ -10,16 +11,20 @@ import '@opentelemetry/api';
 import '@opentelemetry/semantic-conventions';
 import '@opentelemetry/semantic-conventions/incubating';
 
-type LangwatchApiClient = ReturnType<typeof openApiCreateClient<paths>>;
+/**
+ * Creates a new LangWatch API client.
+ * @param apiKey - The API key to use for authentication. Defaults to LANGWATCH_API_KEY environment variable.
+ * @param endpoint - The endpoint to use for the API client. Defaults to LANGWATCH_ENDPOINT environment variable or internal DEFAULT_ENDPOINT.
+ * @returns A new LangWatch API client.
+ */
+declare const createLangWatchApiClient: (apiKey?: string, endpoint?: string) => openApiCreateClient.Client<paths, `${string}/${string}`>;
+type LangwatchApiClient = ReturnType<typeof createLangWatchApiClient>;
 
 interface InternalConfig {
     langwatchApiClient: LangwatchApiClient;
     logger: Logger;
 }
 
-type CreatePromptBody = NonNullable<paths["/api/prompts"]["post"]["requestBody"]>["content"]["application/json"];
-type UpdatePromptBody = NonNullable<paths["/api/prompts/{id}"]["put"]["requestBody"]>["content"]["application/json"];
-
 type SyncAction = "created" | "updated" | "conflict" | "up_to_date";
 type ConfigData = NonNullable<paths["/api/prompts/{id}/sync"]["post"]["requestBody"]>["content"]["application/json"]["configData"];
 interface SyncResult {
@@ -32,15 +37,255 @@ interface SyncResult {
         remoteConfigData: ConfigData;
     };
 }
+/**
+ * Service for managing prompt resources via the Langwatch API.
+ * Constructor creates a proxy that wraps the service and traces all methods.
+ *
+ * Responsibilities:
+ * - CRUD operations for prompts
+ * - Creating prompt versions
+ * - Error handling with contextual information
+ *
+ * All methods return raw PromptResponse data from the API.
+ */
+declare class PromptsApiService {
+    private readonly apiClient;
+    constructor(config?: Pick<InternalConfig, "langwatchApiClient">);
+    /**
+     * Handles API errors by throwing a PromptsError with operation context.
+     * @param operation Description of the operation being performed.
+     * @param error The error object returned from the API client.
+     * @throws {PromptsError}
+     */
+    private handleApiError;
+    /**
+     * Fetches all prompts from the API.
+     * @returns Array of raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    getAll(): Promise<PromptResponse[]>;
+    /**
+     * Fetches a single prompt by its ID.
+     * @param id The prompt's unique identifier.
+     * @returns Raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    get: (id: string, options?: {
+        version?: string;
+    }) => Promise<PromptResponse>;
+    /**
+     * Validates if a prompt exists.
+     * @param id The prompt's unique identifier.
+     * @returns True if prompt exists, false otherwise.
+     * @throws {PromptsError} If the API call fails (not 404).
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Creates a new prompt.
+     * @param params The prompt creation payload, matching the OpenAPI schema.
+     * @returns Raw PromptResponse data of the created prompt.
+     * @throws {PromptsError} If the API call fails.
+     */
+    create(params: CreatePromptBody): Promise<PromptResponse>;
+    /**
+     * Updates an existing prompt.
+     * @param id The prompt's unique identifier.
+     * @param params The update payload, matching the OpenAPI schema.
+     * @returns Raw PromptResponse data of the updated prompt.
+     * @throws {PromptsError} If the API call fails.
+     */
+    update(id: string, params: UpdatePromptBody): Promise<PromptResponse>;
+    /**
+     * Deletes a prompt by its ID.
+     * @param id The prompt's unique identifier.
+     * @throws {PromptsError} If the API call fails.
+     */
+    delete(id: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Fetches all versions for a given prompt.
+     * @param id The prompt's unique identifier.
+     * @returns Array of raw PromptResponse data for each version.
+     * @throws {PromptsError} If the API call fails.
+     */
+    getVersions(id: string): Promise<PromptResponse[]>;
+    /**
+     * Upserts a prompt with local configuration - creates if doesn't exist, updates version if exists.
+     * @param handle The prompt's handle/identifier.
+     * @param config Local prompt configuration.
+     * @returns Object with created flag and raw PromptResponse data.
+     * @throws {PromptsError} If the API call fails.
+     */
+    upsert(handle: string, config: {
+        model: string;
+        modelParameters?: {
+            temperature?: number;
+            max_tokens?: number;
+        };
+        messages: Array<{
+            role: "system" | "user" | "assistant";
+            content: string;
+        }>;
+    }): Promise<{
+        created: boolean;
+        prompt: PromptResponse;
+    }>;
+    /**
+     * Sync a prompt with local content, handling conflicts and version management
+     */
+    sync(params: {
+        name: string;
+        configData: ConfigData;
+        localVersion?: number;
+        commitMessage?: string;
+    }): Promise<SyncResult>;
+}
+
+type PromptDependency = string | {
+    version?: string;
+    file?: string;
+};
+type PromptsConfig = {
+    prompts: Record<string, PromptDependency>;
+};
+declare const localPromptConfigSchema: z.ZodObject<{
+    model: z.ZodString;
+    modelParameters: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        content: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type LocalPromptConfig = z.infer<typeof localPromptConfigSchema>;
+type MaterializedPrompt = {
+    id: string;
+    name: string;
+    version: number;
+    versionId: string;
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    prompt: string;
+    temperature?: number;
+    maxTokens?: number;
+    inputs?: any;
+    outputs?: any;
+    updatedAt: string;
+};
+type PromptsLockEntry = {
+    version: number;
+    versionId: string;
+    materialized: string;
+};
+type PromptsLock = {
+    lockfileVersion: number;
+    prompts: Record<string, PromptsLockEntry>;
+};
+
+declare class FileManager {
+    private static readonly PROMPTS_CONFIG_FILE;
+    private static readonly PROMPTS_LOCK_FILE;
+    private static readonly PROMPTS_DIR;
+    private static readonly MATERIALIZED_DIR;
+    static getPromptsConfigPath(): string;
+    static getPromptsLockPath(): string;
+    static getPromptsDir(): string;
+    static getMaterializedDir(): string;
+    static ensureDirectories(): void;
+    static loadPromptsConfig(): PromptsConfig;
+    static savePromptsConfig(config: PromptsConfig): void;
+    static initializePromptsConfig(): {
+        created: boolean;
+        path: string;
+    };
+    static loadPromptsLock: () => PromptsLock;
+    static savePromptsLock(lock: PromptsLock): void;
+    static initializePromptsLock(): {
+        created: boolean;
+        path: string;
+    };
+    static loadLocalPrompt: (filePath: string) => LocalPromptConfig;
+    static saveMaterializedPrompt(name: string, prompt: MaterializedPrompt): string;
+    static getLocalPromptFiles: () => string[];
+    static promptNameFromPath(filePath: string): string;
+    static cleanupOrphanedMaterializedFiles(currentDependencies: Set<string>): string[];
+    static updateLockEntry(lock: PromptsLock, name: string, prompt: MaterializedPrompt, materializedPath: string): void;
+    static removeFromLock(lock: PromptsLock, names: string[]): void;
+    static addToGitignore(entry: string): {
+        added: boolean;
+        existed: boolean;
+    };
+}
+
+interface LocalPromptsServiceConfig {
+    fileManager?: typeof FileManager;
+    logger?: Logger;
+}
+/**
+ * Service for retrieving prompts from local filesystem sources.
+ *
+ * Searches for prompts in the following priority order:
+ * 1. Explicit file mapping in prompts.json config
+ * 2. Materialized path from prompts-lock.json
+ * 3. Direct file scanning in prompts directory
+ */
+declare class LocalPromptsService {
+    private readonly fileManager;
+    private readonly logger;
+    constructor(config?: LocalPromptsServiceConfig);
+    /**
+     * Retrieves a prompt using the configured search strategy.
+     * Tries each source in priority order until found or all sources exhausted.
+     */
+    get(handleOrId: string): Promise<PromptData | null>;
+    /**
+     * Searches for prompt using explicit file mapping in prompts.json.
+     * Looks for dependencies with a 'file' property pointing to a specific path.
+     */
+    private getFromConfig;
+    /**
+     * Searches for prompt using materialized path from lock file.
+     * Lock file contains resolved paths for prompts that have been synced/materialized.
+     */
+    private getFromLockFile;
+    /**
+     * Searches for prompt by scanning all .prompt.yaml files in prompts directory.
+     * Extracts prompt name from file path and matches against the requested handle.
+     * This is the fallback method when explicit mappings don't exist.
+     */
+    private getFromLocalFiles;
+    /**
+     * Get dependency from config
+     */
+    private getDependencyFromConfig;
+    /**
+     * Converts LocalPromptConfig to PromptData format
+     */
+    private convertToPromptData;
+}
 
+interface PromptsFacadeDependencies {
+    promptsApiService: PromptsApiService;
+    localPromptsService: LocalPromptsService;
+}
 /**
  * Facade for prompt operations in the LangWatch SDK.
  * Provides a simplified interface for common prompt management tasks.
  */
 declare class PromptsFacade {
-    private readonly service;
-    private readonly config;
-    constructor(config: InternalConfig);
+    private readonly promptsApiService;
+    private readonly localPromptsService;
+    constructor(config: InternalConfig & PromptsFacadeDependencies);
     /**
      * Creates a new prompt.
      * @param data The prompt creation payload.
@@ -115,10 +360,10 @@ interface LangWatchConstructorOptions {
 declare class LangWatch {
     #private;
     private readonly config;
-    private readonly tracer;
     readonly prompts: PromptsFacade;
     readonly traces: TracesFacade;
     constructor(options?: LangWatchConstructorOptions);
+    get apiClient(): LangwatchApiClient;
 }
 
 declare const logger: {