@langfuse/client 4.0.0-beta.0 → 4.0.0-beta.2

package/dist/index.d.ts

@@ -2,17 +2,73 @@ import * as _langfuse_core from '@langfuse/core';
 import { LangfuseAPIClient, Dataset, DatasetItem, DatasetRunItem, ParsedMediaReference, CreatePromptRequest, ChatMessage, ChatMessageWithPlaceholders, PlaceholderMessage, BasePrompt, Prompt, ScoreBody } from '@langfuse/core';
 import { Span } from '@opentelemetry/api';
 
+/**
+ * Function type for linking dataset items to OpenTelemetry spans.
+ * This allows dataset items to be associated with specific traces for experiment tracking.
+ *
+ * @param obj - Object containing the OpenTelemetry span
+ * @param runName - Name of the dataset run
+ * @param runArgs - Optional arguments for the dataset run
+ * @returns Promise that resolves to the created dataset run item
+ *
+ * @public
+ */
 type LinkDatasetItemFunction = (obj: {
     otelSpan: Span;
 }, runName: string, runArgs?: {
+    /** Description of the dataset run */
     description?: string;
+    /** Additional metadata for the dataset run */
     metadata?: any;
 }) => Promise<DatasetRunItem>;
+/**
+ * Manager for dataset operations in Langfuse.
+ *
+ * Provides methods to retrieve datasets and their items, with automatic
+ * pagination handling and convenient linking functionality for experiments.
+ *
+ * @public
+ */
 declare class DatasetManager {
     private apiClient;
+    /**
+     * Creates a new DatasetManager instance.
+     *
+     * @param params - Configuration object containing the API client
+     * @internal
+     */
     constructor(params: {
         apiClient: LangfuseAPIClient;
     });
+    /**
+     * Retrieves a dataset by name along with all its items.
+     *
+     * This method automatically handles pagination to fetch all dataset items
+     * and enhances each item with a `link` function for easy experiment tracking.
+     *
+     * @param name - The name of the dataset to retrieve
+     * @param options - Optional configuration for fetching
+     * @param options.fetchItemsPageSize - Number of items to fetch per page (default: 50)
+     *
+     * @returns Promise that resolves to the dataset with enhanced items
+     *
+     * @example
+     * ```typescript
+     * const dataset = await langfuse.dataset.get("my-dataset");
+     *
+     * for (const item of dataset.items) {
+     *   // Use the item data for your experiment
+     *   const result = await processItem(item.input);
+     *
+     *   // Link the result to the dataset item
+     *   await item.link(
+     *     { otelSpan: currentSpan },
+     *     "experiment-run-1",
+     *     { description: "Testing new model" }
+     *   );
+     * }
+     * ```
+     */
     get(name: string, options?: {
         fetchItemsPageSize: number;
     }): Promise<Dataset & {
@@ -20,34 +76,61 @@ declare class DatasetManager {
             link: LinkDatasetItemFunction;
         })[];
     }>;
+    /**
+     * Creates a link function for a specific dataset item.
+     *
+     * @param item - The dataset item to create a link function for
+     * @returns A function that can link the item to OpenTelemetry spans
+     * @internal
+     */
     private createDatasetItemLinkFunction;
 }
 
+/**
+ * Parameters for resolving media references in objects.
+ *
+ * @template T - The type of the object being processed
+ * @public
+ */
 type LangfuseMediaResolveMediaReferencesParams<T> = {
+    /** The object to process for media references */
     obj: T;
+    /** The format to resolve media references to (currently only "base64DataUri" is supported) */
     resolveWith: "base64DataUri";
+    /** Maximum depth to traverse when processing nested objects (default: 10) */
     maxDepth?: number;
 };
+/**
+ * Manager for media operations in Langfuse.
+ *
+ * Provides methods to resolve media references in objects by replacing
+ * them with actual media content (e.g., base64 data URIs).
+ *
+ * @public
+ */
 declare class MediaManager {
     private apiClient;
+    /**
+     * Creates a new MediaManager instance.
+     *
+     * @param params - Configuration object containing the API client
+     * @internal
+     */
     constructor(params: {
         apiClient: LangfuseAPIClient;
     });
     /**
-     * Replaces the media reference strings in an object with base64 data URIs for the media content.
+     * Replaces media reference strings in an object with base64 data URIs.
      *
-     * This method recursively traverses an object (up to a maximum depth of 10) looking for media reference strings
-     * in the format "@@@langfuseMedia:...@@@". When found, it fetches the actual media content using the provided
-     * Langfuse client and replaces the reference string with a base64 data URI.
+     * This method recursively traverses an object looking for media reference strings
+     * in the format "@@@langfuseMedia:...@@@". When found, it fetches the actual media
+     * content from Langfuse and replaces the reference string with a base64 data URI.
      *
-     * If fetching media content fails for a reference string, a warning is logged and the reference string is left unchanged.
+     * If fetching media content fails for a reference string, a warning is logged
+     * and the reference string is left unchanged.
      *
      * @param params - Configuration object
-     * @param params.obj - The object to process. Can be a primitive value, array, or nested object
-     * @param params.resolveWith - The representation of the media content to replace the media reference string with. Currently only "base64DataUri" is supported.
-     * @param params.maxDepth - Optional. Default is 10. The maximum depth to traverse the object.
-     *
-     * @returns A deep copy of the input object with all media references replaced with base64 data URIs where possible
+     * @returns A deep copy of the input object with media references resolved
      *
      * @example
      * ```typescript
@@ -58,9 +141,9 @@ declare class MediaManager {
      *   }
      * };
      *
-     * const result = await LangfuseMedia.resolveMediaReferences({
+     * const result = await langfuse.media.resolveReferences({
      *   obj,
-     *   langfuseClient
+     *   resolveWith: "base64DataUri"
      * });
      *
      * // Result:
@@ -87,36 +170,106 @@ declare class MediaManager {
     static parseReferenceString(referenceString: string): ParsedMediaReference;
 }
 
+/**
+ * Enumeration of chat message types in Langfuse prompts.
+ *
+ * @public
+ */
 declare enum ChatMessageType {
+    /** Regular chat message with role and content */
     ChatMessage = "chatmessage",
+    /** Placeholder for dynamic content insertion */
     Placeholder = "placeholder"
 }
+/**
+ * Union type representing either a chat message or a placeholder.
+ *
+ * Used in compiled prompts where placeholders may remain unresolved.
+ *
+ * @public
+ */
 type ChatMessageOrPlaceholder = ChatMessage | ({
     type: ChatMessageType.Placeholder;
 } & PlaceholderMessage);
+/**
+ * Represents a LangChain MessagesPlaceholder object.
+ *
+ * Used when converting Langfuse prompts to LangChain format,
+ * unresolved placeholders become LangChain MessagesPlaceholder objects.
+ *
+ * @public
+ */
 type LangchainMessagesPlaceholder = {
+    /** Name of the variable that will provide the messages */
     variableName: string;
+    /** Whether the placeholder is optional (defaults to false) */
     optional?: boolean;
 };
+/**
+ * Type for creating chat prompts that support both regular messages and placeholders.
+ *
+ * Extends the standard chat prompt creation request to allow mixed content types.
+ *
+ * @public
+ */
 type CreateChatPromptBodyWithPlaceholders = {
+    /** Specifies this is a chat prompt */
     type: "chat";
 } & Omit<CreatePromptRequest.Chat, "type" | "prompt"> & {
+    /** Array of chat messages and/or placeholders */
     prompt: (ChatMessage | ChatMessageWithPlaceholders)[];
 };
 
+/**
+ * Base class for all prompt clients.
+ *
+ * @internal
+ */
 declare abstract class BasePromptClient {
+    /** The name of the prompt */
     readonly name: string;
+    /** The version number of the prompt */
     readonly version: number;
+    /** Configuration object associated with the prompt */
     readonly config: unknown;
+    /** Labels associated with the prompt */
     readonly labels: string[];
+    /** Tags associated with the prompt */
     readonly tags: string[];
+    /** Whether this prompt client is using fallback content */
     readonly isFallback: boolean;
+    /** The type of prompt ("text" or "chat") */
     readonly type: "text" | "chat";
+    /** Optional commit message for the prompt version */
     readonly commitMessage: string | null | undefined;
+    /**
+     * Creates a new BasePromptClient instance.
+     *
+     * @param prompt - The base prompt data
+     * @param isFallback - Whether this is fallback content
+     * @param type - The prompt type
+     * @internal
+     */
     constructor(prompt: BasePrompt, isFallback: boolean | undefined, type: "text" | "chat");
+    /** Gets the raw prompt content */
     abstract get prompt(): string | ChatMessageWithPlaceholders[];
+    /** Sets the raw prompt content */
     abstract set prompt(value: string | ChatMessageWithPlaceholders[]);
+    /**
+     * Compiles the prompt by substituting variables and resolving placeholders.
+     *
+     * @param variables - Key-value pairs for variable substitution
+     * @param placeholders - Key-value pairs for placeholder resolution
+     * @returns The compiled prompt content
+     */
     abstract compile(variables?: Record<string, string>, placeholders?: Record<string, any>): string | ChatMessage[] | (ChatMessageOrPlaceholder | any)[];
+    /**
+     * Converts the prompt to a format compatible with LangChain.
+     *
+     * @param options - Options for conversion
+     * @param options.placeholders - Placeholders to resolve during conversion
+     * @returns The prompt in LangChain-compatible format
+     */
     abstract getLangchainPrompt(options?: {
         placeholders?: Record<string, any>;
     }): string | ChatMessage[] | ChatMessageOrPlaceholder[] | (ChatMessage | LangchainMessagesPlaceholder | any)[];
@@ -133,68 +286,264 @@ declare abstract class BasePromptClient {
      * @returns The string with JSON-related braces doubled.
      */
     protected escapeJsonForLangchain(text: string): string;
+    /**
+     * Serializes the prompt client to JSON.
+     *
+     * @returns JSON string representation of the prompt
+     */
     abstract toJSON(): string;
 }
+/**
+ * Client for working with text-based prompts.
+ *
+ * Provides methods to compile text prompts with variable substitution
+ * and convert them to LangChain-compatible formats.
+ *
+ * @public
+ */
 declare class TextPromptClient extends BasePromptClient {
+    /** The original prompt response from the API */
     readonly promptResponse: Prompt.Text;
+    /** The text content of the prompt */
     readonly prompt: string;
+    /**
+     * Creates a new TextPromptClient instance.
+     *
+     * @param prompt - The text prompt data
+     * @param isFallback - Whether this is fallback content
+     */
     constructor(prompt: Prompt.Text, isFallback?: boolean);
+    /**
+     * Compiles the text prompt by substituting variables.
+     *
+     * Uses Mustache templating to replace {{variable}} placeholders with provided values.
+     *
+     * @param variables - Key-value pairs for variable substitution
+     * @param _placeholders - Ignored for text prompts
+     * @returns The compiled text with variables substituted
+     *
+     * @example
+     * ```typescript
+     * const prompt = await langfuse.prompt.get("greeting", { type: "text" });
+     * const compiled = prompt.compile({ name: "Alice" });
+     * // If prompt is "Hello {{name}}!", result is "Hello Alice!"
+     * ```
+     */
     compile(variables?: Record<string, string>, _placeholders?: Record<string, any>): string;
+    /**
+     * Converts the prompt to LangChain PromptTemplate format.
+     *
+     * Transforms Mustache-style {{variable}} syntax to LangChain's {variable} format.
+     *
+     * @param _options - Ignored for text prompts
+     * @returns The prompt string compatible with LangChain PromptTemplate
+     *
+     * @example
+     * ```typescript
+     * const prompt = await langfuse.prompt.get("greeting", { type: "text" });
+     * const langchainFormat = prompt.getLangchainPrompt();
+     * // Transforms "Hello {{name}}!" to "Hello {name}!"
+     * ```
+     */
     getLangchainPrompt(_options?: {
         placeholders?: Record<string, any>;
     }): string;
     toJSON(): string;
 }
+/**
+ * Client for working with chat-based prompts.
+ *
+ * Provides methods to compile chat prompts with variable substitution and
+ * placeholder resolution, and convert them to LangChain-compatible formats.
+ *
+ * @public
+ */
 declare class ChatPromptClient extends BasePromptClient {
+    /** The original prompt response from the API */
     readonly promptResponse: Prompt.Chat;
+    /** The chat messages that make up the prompt */
     readonly prompt: ChatMessageWithPlaceholders[];
+    /**
+     * Creates a new ChatPromptClient instance.
+     *
+     * @param prompt - The chat prompt data
+     * @param isFallback - Whether this is fallback content
+     */
     constructor(prompt: Prompt.Chat, isFallback?: boolean);
     private static normalizePrompt;
+    /**
+     * Compiles the chat prompt by replacing placeholders and variables.
+     *
+     * First resolves placeholders with provided values, then applies variable substitution
+     * to message content using Mustache templating. Unresolved placeholders remain
+     * as placeholder objects in the output.
+     *
+     * @param variables - Key-value pairs for Mustache variable substitution in message content
+     * @param placeholders - Key-value pairs where keys are placeholder names and values are ChatMessage arrays
+     * @returns Array of ChatMessage objects and unresolved placeholder objects
+     *
+     * @example
+     * ```typescript
+     * const prompt = await langfuse.prompt.get("conversation", { type: "chat" });
+     * const compiled = prompt.compile(
+     *   { user_name: "Alice" },
+     *   { examples: [{ role: "user", content: "Hello" }, { role: "assistant", content: "Hi!" }] }
+     * );
+     * ```
+     */
     compile(variables?: Record<string, string>, placeholders?: Record<string, any>): (ChatMessageOrPlaceholder | any)[];
+    /**
+     * Converts the prompt to LangChain ChatPromptTemplate format.
+     *
+     * Resolves placeholders with provided values and converts unresolved ones
+     * to LangChain MessagesPlaceholder objects. Transforms variables from
+     * {{var}} to {var} format without rendering them.
+     *
+     * @param options - Configuration object
+     * @param options.placeholders - Key-value pairs for placeholder resolution
+     * @returns Array of ChatMessage objects and LangChain MessagesPlaceholder objects
+     *
+     * @example
+     * ```typescript
+     * const prompt = await langfuse.prompt.get("conversation", { type: "chat" });
+     * const langchainFormat = prompt.getLangchainPrompt({
+     *   placeholders: { examples: [{ role: "user", content: "Hello" }] }
+     * });
+     * ```
+     */
     getLangchainPrompt(options?: {
         placeholders?: Record<string, any>;
     }): (ChatMessage | LangchainMessagesPlaceholder | any)[];
     toJSON(): string;
 }
 
+/**
+ * Manager for prompt operations in Langfuse.
+ *
+ * Provides methods to create, retrieve, and manage prompts with built-in caching
+ * for optimal performance. Supports both text and chat prompts with variable
+ * substitution and placeholder functionality.
+ *
+ * @public
+ */
 declare class PromptManager {
     private cache;
     private apiClient;
+    /**
+     * Creates a new PromptManager instance.
+     *
+     * @param params - Configuration object containing the API client
+     * @internal
+     */
     constructor(params: {
         apiClient: LangfuseAPIClient;
     });
     get logger(): _langfuse_core.Logger;
+    /**
+     * Creates a new prompt in Langfuse.
+     *
+     * @param body - The prompt data to create (chat prompt)
+     * @returns Promise that resolves to a ChatPromptClient
+     */
     create(body: CreateChatPromptBodyWithPlaceholders): Promise<ChatPromptClient>;
+    /**
+     * Creates a new prompt in Langfuse.
+     *
+     * @param body - The prompt data to create (text prompt)
+     * @returns Promise that resolves to a TextPromptClient
+     */
     create(body: Omit<CreatePromptRequest.Text, "type"> & {
         type?: "text";
     }): Promise<TextPromptClient>;
+    /**
+     * Creates a new prompt in Langfuse.
+     *
+     * @param body - The prompt data to create (chat prompt)
+     * @returns Promise that resolves to a ChatPromptClient
+     */
     create(body: CreatePromptRequest.Chat): Promise<ChatPromptClient>;
+    /**
+     * Updates the labels of an existing prompt version.
+     *
+     * @param params - Update parameters
+     * @param params.name - Name of the prompt to update
+     * @param params.version - Version number of the prompt to update
+     * @param params.newLabels - New labels to apply to the prompt version
+     *
+     * @returns Promise that resolves to the updated prompt
+     *
+     * @example
+     * ```typescript
+     * const updatedPrompt = await langfuse.prompt.update({
+     *   name: "my-prompt",
+     *   version: 1,
+     *   newLabels: ["production", "v2"]
+     * });
+     * ```
+     */
     update(params: {
         name: string;
         version: number;
         newLabels: string[];
     }): Promise<Prompt>;
+    /**
+     * Retrieves a text prompt by name.
+     *
+     * @param name - Name of the prompt to retrieve
+     * @param options - Optional retrieval configuration
+     * @returns Promise that resolves to a TextPromptClient
+     */
     get(name: string, options?: {
+        /** Specific version to retrieve (defaults to latest) */
         version?: number;
+        /** Label to filter by */
         label?: string;
+        /** Cache TTL in seconds (0 to disable caching) */
         cacheTtlSeconds?: number;
+        /** Fallback text content if prompt fetch fails */
         fallback?: string;
+        /** Maximum retry attempts for failed requests */
         maxRetries?: number;
+        /** Specify text prompt type */
         type?: "text";
+        /** Request timeout in milliseconds */
         fetchTimeoutMs?: number;
     }): Promise<TextPromptClient>;
+    /**
+     * Retrieves a chat prompt by name.
+     *
+     * @param name - Name of the prompt to retrieve
+     * @param options - Optional retrieval configuration
+     * @returns Promise that resolves to a ChatPromptClient
+     */
     get(name: string, options?: {
+        /** Specific version to retrieve (defaults to latest) */
         version?: number;
+        /** Label to filter by */
         label?: string;
+        /** Cache TTL in seconds (0 to disable caching) */
         cacheTtlSeconds?: number;
+        /** Fallback chat messages if prompt fetch fails */
         fallback?: ChatMessage[];
+        /** Maximum retry attempts for failed requests */
         maxRetries?: number;
+        /** Specify chat prompt type */
         type: "chat";
+        /** Request timeout in milliseconds */
         fetchTimeoutMs?: number;
     }): Promise<ChatPromptClient>;
     private fetchPromptAndUpdateCache;
 }
 
+/**
+ * Manager for creating and batching score events in Langfuse.
+ *
+ * The ScoreManager handles automatic batching and flushing of score events
+ * to optimize API usage. Scores are automatically sent when the queue reaches
+ * a certain size or after a time interval.
+ *
+ * @public
+ */
 declare class ScoreManager {
     private apiClient;
     private eventQueue;
@@ -202,36 +551,247 @@ declare class ScoreManager {
     private flushTimer;
     private flushAtCount;
     private flushIntervalSeconds;
+    /**
+     * Creates a new ScoreManager instance.
+     *
+     * @param params - Configuration object containing the API client
+     * @internal
+     */
     constructor(params: {
         apiClient: LangfuseAPIClient;
     });
     get logger(): _langfuse_core.Logger;
+    /**
+     * Creates a new score event and adds it to the processing queue.
+     *
+     * Scores are queued and sent in batches for efficiency. The score will be
+     * automatically sent when the queue reaches the flush threshold or after
+     * the flush interval expires.
+     *
+     * @param data - The score data to create
+     *
+     * @example
+     * ```typescript
+     * langfuse.score.create({
+     *   name: "quality",
+     *   value: 0.85,
+     *   traceId: "trace-123",
+     *   comment: "High quality response"
+     * });
+     * ```
+     */
     create(data: ScoreBody): void;
+    /**
+     * Creates a score for a specific observation using its OpenTelemetry span.
+     *
+     * This method automatically extracts the trace ID and observation ID from
+     * the provided span context.
+     *
+     * @param observation - Object containing the OpenTelemetry span
+     * @param data - Score data (traceId and observationId will be auto-populated)
+     *
+     * @example
+     * ```typescript
+     * import { startSpan } from '@langfuse/tracing';
+     *
+     * const span = startSpan({ name: "my-operation" });
+     * langfuse.score.observation(
+     *   { otelSpan: span },
+     *   { name: "accuracy", value: 0.92 }
+     * );
+     * ```
+     */
     observation(observation: {
         otelSpan: Span;
     }, data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
+    /**
+     * Creates a score for a trace using an OpenTelemetry span.
+     *
+     * This method automatically extracts the trace ID from the provided
+     * span context and creates a trace-level score.
+     *
+     * @param observation - Object containing the OpenTelemetry span
+     * @param data - Score data (traceId will be auto-populated)
+     *
+     * @example
+     * ```typescript
+     * import { startSpan } from '@langfuse/tracing';
+     *
+     * const span = startSpan({ name: "my-operation" });
+     * langfuse.score.trace(
+     *   { otelSpan: span },
+     *   { name: "overall_quality", value: 0.88 }
+     * );
+     * ```
+     */
     trace(observation: {
         otelSpan: Span;
     }, data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
+    /**
+     * Creates a score for the currently active observation.
+     *
+     * This method automatically detects the active OpenTelemetry span and
+     * creates an observation-level score. If no active span is found,
+     * a warning is logged and the operation is skipped.
+     *
+     * @param data - Score data (traceId and observationId will be auto-populated)
+     *
+     * @example
+     * ```typescript
+     * import { startActiveSpan } from '@langfuse/tracing';
+     *
+     * startActiveSpan({ name: "my-operation" }, (span) => {
+     *   // Inside the active span
+     *   langfuse.score.activeObservation({
+     *     name: "relevance",
+     *     value: 0.95
+     *   });
+     * });
+     * ```
+     */
     activeObservation(data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
+    /**
+     * Creates a score for the currently active trace.
+     *
+     * This method automatically detects the active OpenTelemetry span and
+     * creates a trace-level score. If no active span is found,
+     * a warning is logged and the operation is skipped.
+     *
+     * @param data - Score data (traceId will be auto-populated)
+     *
+     * @example
+     * ```typescript
+     * import { startActiveSpan } from '@langfuse/tracing';
+     *
+     * startActiveSpan({ name: "my-operation" }, (span) => {
+     *   // Inside the active span
+     *   langfuse.score.activeTrace({
+     *     name: "user_satisfaction",
+     *     value: 4,
+     *     comment: "User rated 4 out of 5 stars"
+     *   });
+     * });
+     * ```
+     */
     activeTrace(data: Omit<ScoreBody, "traceId" | "sessionId" | "observationId" | "datasetRunId">): void;
     private handleFlush;
+    /**
+     * Flushes all pending score events to the Langfuse API.
+     *
+     * This method ensures all queued scores are sent immediately rather than
+     * waiting for the automatic flush interval or batch size threshold.
+     *
+     * @returns Promise that resolves when all pending scores have been sent
+     *
+     * @example
+     * ```typescript
+     * langfuse.score.create({ name: "quality", value: 0.8 });
+     * await langfuse.score.flush(); // Ensures the score is sent immediately
+     * ```
+     */
     flush(): Promise<void>;
+    /**
+     * Gracefully shuts down the score manager by flushing all pending scores.
+     *
+     * This method should be called before your application exits to ensure
+     * all score data is sent to Langfuse.
+     *
+     * @returns Promise that resolves when shutdown is complete
+     *
+     * @example
+     * ```typescript
+     * // Before application exit
+     * await langfuse.score.shutdown();
+     * ```
+     */
     shutdown(): Promise<void>;
 }
 
+/**
+ * Configuration parameters for initializing a LangfuseClient instance.
+ *
+ * @public
+ */
 interface LangfuseClientParams {
+    /**
+     * Public API key for authentication with Langfuse.
+     * Can also be provided via LANGFUSE_PUBLIC_KEY environment variable.
+     */
     publicKey?: string;
+    /**
+     * Secret API key for authentication with Langfuse.
+     * Can also be provided via LANGFUSE_SECRET_KEY environment variable.
+     */
     secretKey?: string;
+    /**
+     * Base URL of the Langfuse instance to connect to.
+     * Can also be provided via LANGFUSE_BASE_URL environment variable.
+     *
+     * @defaultValue "https://cloud.langfuse.com"
+     */
     baseUrl?: string;
+    /**
+     * Request timeout in seconds.
+     * Can also be provided via LANGFUSE_TIMEOUT environment variable.
+     *
+     * @defaultValue 5
+     */
     timeout?: number;
+    /**
+     * Additional HTTP headers to include with API requests.
+     */
     additionalHeaders?: Record<string, string>;
 }
+/**
+ * Main client for interacting with the Langfuse API.
+ *
+ * The LangfuseClient provides access to all Langfuse functionality including:
+ * - Prompt management and retrieval
+ * - Dataset operations
+ * - Score creation and management
+ * - Media upload and handling
+ * - Direct API access for advanced use cases
+ *
+ * @example
+ * ```typescript
+ * // Initialize with explicit credentials
+ * const langfuse = new LangfuseClient({
+ *   publicKey: "pk_...",
+ *   secretKey: "sk_...",
+ *   baseUrl: "https://cloud.langfuse.com"
+ * });
+ *
+ * // Or use environment variables
+ * const langfuse = new LangfuseClient();
+ *
+ * // Use the client
+ * const prompt = await langfuse.prompt.get("my-prompt");
+ * const compiledPrompt = prompt.compile({ variable: "value" });
+ * ```
+ *
+ * @public
+ */
 declare class LangfuseClient {
+    /**
+     * Direct access to the underlying Langfuse API client.
+     * Use this for advanced API operations not covered by the high-level managers.
+     */
     api: LangfuseAPIClient;
+    /**
+     * Manager for prompt operations including creation, retrieval, and caching.
+     */
     prompt: PromptManager;
+    /**
+     * Manager for dataset operations including retrieval and item linking.
+     */
     dataset: DatasetManager;
+    /**
+     * Manager for score creation and batch processing.
+     */
     score: ScoreManager;
+    /**
+     * Manager for media upload and reference resolution.
+     */
     media: MediaManager;
     private baseUrl;
     private projectId;
@@ -299,9 +859,70 @@ declare class LangfuseClient {
      * @deprecated Use media.resolveReferences instead
      */
     resolveMediaReferences: typeof MediaManager.prototype.resolveReferences;
+    /**
+     * Creates a new LangfuseClient instance.
+     *
+     * @param params - Configuration parameters. If not provided, will use environment variables.
+     *
+     * @throws Will log warnings if required credentials are not provided
+     *
+     * @example
+     * ```typescript
+     * // With explicit configuration
+     * const client = new LangfuseClient({
+     *   publicKey: "pk_...",
+     *   secretKey: "sk_...",
+     *   baseUrl: "https://your-instance.langfuse.com"
+     * });
+     *
+     * // Using environment variables
+     * const client = new LangfuseClient();
+     * ```
+     */
     constructor(params?: LangfuseClientParams);
+    /**
+     * Flushes any pending score events to the Langfuse API.
+     *
+     * This method ensures all queued scores are sent immediately rather than
+     * waiting for the automatic flush interval or batch size threshold.
+     *
+     * @returns Promise that resolves when all pending scores have been sent
+     *
+     * @example
+     * ```typescript
+     * langfuse.score.create({ name: "quality", value: 0.8 });
+     * await langfuse.flush(); // Ensures the score is sent immediately
+     * ```
+     */
     flush(): Promise<void>;
+    /**
+     * Gracefully shuts down the client by flushing all pending data.
+     *
+     * This method should be called before your application exits to ensure
+     * all data is sent to Langfuse.
+     *
+     * @returns Promise that resolves when shutdown is complete
+     *
+     * @example
+     * ```typescript
+     * // Before application exit
+     * await langfuse.shutdown();
+     * ```
+     */
     shutdown(): Promise<void>;
+    /**
+     * Generates a URL to view a specific trace in the Langfuse UI.
+     *
+     * @param traceId - The ID of the trace to generate a URL for
+     * @returns Promise that resolves to the trace URL
+     *
+     * @example
+     * ```typescript
+     * const traceId = "trace-123";
+     * const url = await langfuse.getTraceUrl(traceId);
+     * console.log(`View trace at: ${url}`);
+     * ```
+     */
     getTraceUrl(traceId: string): Promise<string>;
 }