Langfuse

import { Langfuse, LangfuseWeb } from 'langfuse';

const { Langfuse, LangfuseWeb } = require('langfuse');

import { Langfuse } from 'langfuse';

// Initialize the client
const langfuse = new Langfuse({
  publicKey: 'your-public-key',
  secretKey: 'your-secret-key',
  baseUrl: 'https://cloud.langfuse.com' // optional
});

// Create a trace
const trace = langfuse.trace({
  name: 'my-application',
  userId: 'user-123',
  metadata: { environment: 'production' }
});

// Add a generation (LLM call)
const generation = trace.generation({
  name: 'chat-completion',
  model: 'gpt-4',
  input: [{ role: 'user', content: 'Hello!' }],
  output: { role: 'assistant', content: 'Hi there!' },
  usage: { input: 10, output: 15, total: 25 }
});

// Flush events to Langfuse
await langfuse.flushAsync();

class Langfuse {
  /**
   * Creates a new trace
   * @param body - Optional trace configuration
   * @returns Trace client for chaining operations
   */
  trace(body?: CreateLangfuseTraceBody): LangfuseTraceClient;

  /**
   * Creates a span observation
   * @param body - Span configuration with traceId
   * @returns Span client for chaining operations
   */
  span(body: CreateLangfuseSpanBody): LangfuseSpanClient;

  /**
   * Creates a generation observation (LLM call)
   * @param body - Generation configuration
   * @returns Generation client for chaining operations
   */
  generation(body: Omit<CreateLangfuseGenerationBody, "promptName" | "promptVersion"> & PromptInput): LangfuseGenerationClient;

  /**
   * Creates an event observation
   * @param body - Event configuration
   * @returns Event client for chaining operations
   */
  event(body: CreateLangfuseEventBody): LangfuseEventClient;

  /**
   * Creates a score for a trace or observation
   * @param body - Score configuration
   * @returns Langfuse instance for chaining
   */
  score(body: CreateLangfuseScoreBody): this;
}

class Langfuse {
  /**
   * Fetches a text prompt with caching support
   * @param name - Prompt name
   * @param version - Optional version (defaults to latest production)
   * @param options - Optional cache TTL configuration
   * @returns Text prompt client
   */
  getPrompt(name: string, version?: number, options?: GetPromptOptions): Promise<TextPromptClient>;

  /**
   * Fetches a chat prompt with caching support
   * @param name - Prompt name
   * @param version - Optional version (defaults to latest production)
   * @param options - Chat-specific configuration
   * @returns Chat prompt client
   */
  getPrompt(name: string, version?: number, options?: GetPromptOptionsChat): Promise<ChatPromptClient>;

  /**
   * Creates a new text prompt
   * @param body - Text prompt configuration
   * @returns Text prompt client
   */
  createPrompt(body: CreateTextPromptBody): Promise<TextPromptClient>;

  /**
   * Creates a new chat prompt
   * @param body - Chat prompt configuration
   * @returns Chat prompt client
   */
  createPrompt(body: CreateChatPromptBody | CreateChatPromptBodyWithPlaceholders): Promise<ChatPromptClient>;
}

class Langfuse {
  /**
   * Fetches a dataset with all its items
   * @param name - Dataset name
   * @param options - Optional pagination settings
   * @returns Dataset with items
   */
  getDataset(name: string, options?: { fetchItemsPageSize: number }): Promise<Dataset>;

  /**
   * Creates a new dataset
   * @param body - Dataset configuration
   * @returns Dataset creation response
   */
  createDataset(body: CreateLangfuseDatasetBody): Promise<CreateLangfuseDatasetResponse>;

  /**
   * Creates a dataset item
   * @param body - Dataset item configuration
   * @returns Dataset item response
   */
  createDatasetItem(body: CreateLangfuseDatasetItemBody): Promise<CreateLangfuseDatasetItemResponse>;

  /**
   * Links an observation to a dataset item for run tracking
   * @param body - Run item configuration
   * @returns Run item response
   */
  createDatasetRunItem(body: CreateLangfuseDatasetRunItemBody): Promise<CreateLangfuseDatasetRunItemResponse>;
}

/**
 * Wraps an OpenAI SDK instance with automatic Langfuse tracing
 * @param sdk - The OpenAI SDK instance to wrap
 * @param langfuseConfig - Optional tracing configuration
 * @returns Wrapped SDK with tracing and flush methods
 */
function observeOpenAI<SDKType extends object>(
  sdk: SDKType,
  langfuseConfig?: LangfuseConfig
): SDKType & LangfuseExtension;

interface LangfuseExtension {
  /** Flushes all pending Langfuse events */
  flushAsync(): Promise<void>;
  /** Shuts down the Langfuse client */
  shutdownAsync(): Promise<void>;
}

class LangfuseMedia {
  /**
   * Creates a media object for upload
   * @param params - Media source (base64, file path, bytes, or object)
   */
  constructor(params: {
    obj?: object;
    base64DataUri?: string;
    contentType?: MediaContentType;
    contentBytes?: Buffer;
    filePath?: string;
  });

  /**
   * Returns a media reference string for storage
   * @returns Reference string in format @@@langfuseMedia:type={...}|id={...}@@@
   */
  toJSON(): string | undefined;

  /**
   * Resolves media references in an object to base64 data URIs
   * @param params - Object with references and resolution settings
   * @returns Object with resolved media content
   */
  static resolveMediaReferences<T>(
    params: LangfuseMediaResolveMediaReferencesParams<T>
  ): Promise<T>;
}

class Langfuse {
  /** Public API client for direct API access */
  api: LangfusePublicApi<null>["api"];
}

class Langfuse {
  constructor(params?: {
    publicKey?: string;
    secretKey?: string;
  } & LangfuseOptions);
}

interface LangfuseOptions {
  /** Persistence strategy: localStorage, sessionStorage, cookie, or memory */
  persistence?: "localStorage" | "sessionStorage" | "cookie" | "memory";
  /** Custom name for persistence storage */
  persistence_name?: string;
  /** Enable/disable tracing */
  enabled?: boolean;
  /** Base URL for Langfuse API */
  baseUrl?: string;
  /** Number of events before auto-flush (default: 15) */
  flushAt?: number;
  /** Flush interval in milliseconds (default: 10000) */
  flushInterval?: number;
  /** Request timeout in milliseconds (default: 5000) */
  requestTimeout?: number;
  /** Release version identifier */
  release?: string;
  /** Environment name */
  environment?: string;
  /** Function to mask sensitive data */
  mask?: MaskFunction;
  /** Sampling rate (0-1) */
  sampleRate?: number;
  /** Number of retries for failed requests (default: 3) */
  fetchRetryCount?: number;
  /** Retry delay in milliseconds (default: 3000) */
  fetchRetryDelay?: number;
  /** SDK integration identifier */
  sdkIntegration?: string;
  /** Additional HTTP headers */
  additionalHeaders?: Record<string, string>;
}

class Langfuse {
  /**
   * Flushes all pending events asynchronously
   * @returns Promise that resolves when all events are sent
   */
  flushAsync(): Promise<void>;

  /**
   * Shuts down the client, flushing all pending events
   * @returns Promise that resolves when shutdown is complete
   */
  shutdownAsync(): Promise<void>;

  /**
   * Registers an event listener
   * @param event - Event name
   * @param cb - Callback function
   * @returns Unsubscribe function
   */
  on(event: string, cb: (...args: any[]) => void): () => void;

  /**
   * Enables or disables debug mode
   * @param enabled - Debug mode state (default: true)
   */
  debug(enabled?: boolean): void;

  /**
   * @deprecated Use flushAsync() instead. This method does not wait for events to be sent.
   * Flushes pending events synchronously with optional callback
   * @param callback - Optional callback function
   */
  flush(callback?: (err?: any, data?: any) => void): void;

  /**
   * @deprecated Use shutdownAsync() instead. This method does not wait for events to be processed.
   * Shuts down the client synchronously
   */
  shutdown(): void;
}

class Langfuse {
  /**
   * Fetches traces with optional filtering
   * @param query - Filter and pagination options
   * @returns Paginated traces response
   */
  fetchTraces(query?: GetLangfuseTracesQuery): Promise<GetLangfuseTracesResponse>;

  /**
   * Fetches a specific trace by ID
   * @param traceId - Trace identifier
   * @returns Trace with full details
   */
  fetchTrace(traceId: string): Promise<{ data: GetLangfuseTraceResponse }>;

  /**
   * Fetches observations with optional filtering
   * @param query - Filter and pagination options
   * @returns Paginated observations response
   */
  fetchObservations(query?: GetLangfuseObservationsQuery): Promise<GetLangfuseObservationsResponse>;

  /**
   * Fetches a specific observation by ID
   * @param observationId - Observation identifier
   * @returns Observation details
   */
  fetchObservation(observationId: string): Promise<{ data: GetLangfuseObservationResponse }>;

  /**
   * Fetches sessions with optional filtering
   * @param query - Filter and pagination options
   * @returns Paginated sessions response
   */
  fetchSessions(query?: GetLangfuseSessionsQuery): Promise<GetLangfuseSessionsResponse>;
}

class LangfuseWeb {
  /**
   * Creates a web-only Langfuse client
   * @param params - Configuration without secretKey
   */
  constructor(params?: Omit<LangfuseOptions, "secretKey">);

  /**
   * Creates a score and flushes immediately
   * @param body - Score configuration
   * @returns Promise resolving to LangfuseWeb instance
   */
  score(body: CreateLangfuseScoreBody): Promise<this>;
}

class LangfuseMemoryStorage {
  /**
   * Gets a stored property value
   * @param key - Property key
   * @returns Stored value or undefined
   */
  getProperty(key: LangfusePersistedProperty): any | undefined;

  /**
   * Sets a property value in memory
   * @param key - Property key
   * @param value - Value to store (null to clear)
   */
  setProperty(key: LangfusePersistedProperty, value: any | null): void;
}

enum LangfusePersistedProperty {
  /** Queue persistence key */
  Queue = "queue"
}