@langfuse/core 4.3.0 → 4.4.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Context } from '@opentelemetry/api';
+
 /**
  * Enumeration of log levels in order of severity (lowest to highest).
  */
@@ -179,6 +181,7 @@ declare const resetGlobalLogger: () => void;
 declare const LANGFUSE_TRACER_NAME = "langfuse-sdk";
 declare const LANGFUSE_SDK_VERSION: string;
 declare const LANGFUSE_SDK_NAME = "javascript";
+declare const LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT = "sdk-experiment";
 declare enum LangfuseOtelSpanAttributes {
     TRACE_NAME = "langfuse.trace.name",
     TRACE_USER_ID = "user.id",
@@ -205,6 +208,15 @@ declare enum LangfuseOtelSpanAttributes {
     RELEASE = "langfuse.release",
     VERSION = "langfuse.version",
     AS_ROOT = "langfuse.internal.as_root",
+    EXPERIMENT_ID = "langfuse.experiment.id",
+    EXPERIMENT_NAME = "langfuse.experiment.name",
+    EXPERIMENT_DESCRIPTION = "langfuse.experiment.description",
+    EXPERIMENT_METADATA = "langfuse.experiment.metadata",
+    EXPERIMENT_DATASET_ID = "langfuse.experiment.dataset.id",
+    EXPERIMENT_ITEM_ID = "langfuse.experiment.item.id",
+    EXPERIMENT_ITEM_EXPECTED_OUTPUT = "langfuse.experiment.item.expected_output",
+    EXPERIMENT_ITEM_METADATA = "langfuse.experiment.item.metadata",
+    EXPERIMENT_ITEM_ROOT_OBSERVATION_ID = "langfuse.experiment.item.root_observation_id",
     TRACE_COMPAT_USER_ID = "langfuse.user.id",
     TRACE_COMPAT_SESSION_ID = "langfuse.session.id"
 }
@@ -980,6 +992,10 @@ interface Dataset {
     name: string;
     description?: string;
     metadata?: unknown;
+    /** JSON Schema for validating dataset item inputs */
+    inputSchema?: unknown;
+    /** JSON Schema for validating dataset item expected outputs */
+    expectedOutputSchema?: unknown;
     projectId: string;
     createdAt: string;
     updatedAt: string;
@@ -1469,6 +1485,10 @@ interface CreateDatasetRequest {
     name: string;
     description?: string;
     metadata?: unknown;
+    /** JSON Schema for validating dataset item inputs. When set, all new and existing dataset items will be validated against this schema. */
+    inputSchema?: unknown;
+    /** JSON Schema for validating dataset item expected outputs. When set, all new and existing dataset items will be validated against this schema. */
+    expectedOutputSchema?: unknown;
 }
 
 /**
@@ -2523,13 +2543,15 @@ interface GetObservationsRequest {
     /** Optional filter to only include observations with a certain version. */
     version?: string;
     /**
-     * JSON string containing an array of filter conditions. When provided, this takes precedence over legacy filter parameters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+     * JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, type, level, environment, fromStartTime, ...).
+     *
+     * ## Filter Structure
      * Each filter condition has the following structure:
      * ```json
      * [
      *   {
      *     "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
-     *     "column": string,         // Required. Column to filter on
+     *     "column": string,         // Required. Column to filter on (see available columns below)
      *     "operator": string,       // Required. Operator based on type:
      *                               // - datetime: ">", "<", ">=", "<="
      *                               // - string: "=", "contains", "does not contain", "starts with", "ends with"
@@ -2546,6 +2568,78 @@ interface GetObservationsRequest {
      *   }
      * ]
      * ```
+     *
+     * ## Available Columns
+     *
+     * ### Core Observation Fields
+     * - `id` (string) - Observation ID
+     * - `type` (string) - Observation type (SPAN, GENERATION, EVENT)
+     * - `name` (string) - Observation name
+     * - `traceId` (string) - Associated trace ID
+     * - `startTime` (datetime) - Observation start time
+     * - `endTime` (datetime) - Observation end time
+     * - `environment` (string) - Environment tag
+     * - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
+     * - `statusMessage` (string) - Status message
+     * - `version` (string) - Version tag
+     *
+     * ### Performance Metrics
+     * - `latency` (number) - Latency in seconds (calculated: end_time - start_time)
+     * - `timeToFirstToken` (number) - Time to first token in seconds
+     * - `tokensPerSecond` (number) - Output tokens per second
+     *
+     * ### Token Usage
+     * - `inputTokens` (number) - Number of input tokens
+     * - `outputTokens` (number) - Number of output tokens
+     * - `totalTokens` (number) - Total tokens (alias: `tokens`)
+     *
+     * ### Cost Metrics
+     * - `inputCost` (number) - Input cost in USD
+     * - `outputCost` (number) - Output cost in USD
+     * - `totalCost` (number) - Total cost in USD
+     *
+     * ### Model Information
+     * - `model` (string) - Provided model name
+     * - `promptName` (string) - Associated prompt name
+     * - `promptVersion` (number) - Associated prompt version
+     *
+     * ### Structured Data
+     * - `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.
+     *
+     * ### Scores (requires join with scores table)
+     * - `scores_avg` (number) - Average of numeric scores (alias: `scores`)
+     * - `score_categories` (categoryOptions) - Categorical score values
+     *
+     * ### Associated Trace Fields (requires join with traces table)
+     * - `userId` (string) - User ID from associated trace
+     * - `traceName` (string) - Name from associated trace
+     * - `traceEnvironment` (string) - Environment from associated trace
+     * - `traceTags` (arrayOptions) - Tags from associated trace
+     *
+     * ## Filter Examples
+     * ```json
+     * [
+     *   {
+     *     "type": "string",
+     *     "column": "type",
+     *     "operator": "=",
+     *     "value": "GENERATION"
+     *   },
+     *   {
+     *     "type": "number",
+     *     "column": "latency",
+     *     "operator": ">=",
+     *     "value": 2.5
+     *   },
+     *   {
+     *     "type": "stringObject",
+     *     "column": "metadata",
+     *     "key": "environment",
+     *     "operator": "=",
+     *     "value": "production"
+     *   }
+     * ]
+     * ```
      */
     filter?: string;
 }
@@ -2816,16 +2910,39 @@ interface OrganizationProjectsResponse {
     projects: OrganizationProject[];
 }
 
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+interface OrganizationApiKey {
+    id: string;
+    createdAt: string;
+    expiresAt?: string;
+    lastUsedAt?: string;
+    note?: string;
+    publicKey: string;
+    displaySecretKey: string;
+}
+
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+interface OrganizationApiKeysResponse {
+    apiKeys: OrganizationApiKey[];
+}
+
 type index$b_DeleteMembershipRequest = DeleteMembershipRequest;
 type index$b_MembershipDeletionResponse = MembershipDeletionResponse;
 type index$b_MembershipRequest = MembershipRequest;
 type index$b_MembershipResponse = MembershipResponse;
 declare const index$b_MembershipRole: typeof MembershipRole;
 type index$b_MembershipsResponse = MembershipsResponse;
+type index$b_OrganizationApiKey = OrganizationApiKey;
+type index$b_OrganizationApiKeysResponse = OrganizationApiKeysResponse;
 type index$b_OrganizationProject = OrganizationProject;
 type index$b_OrganizationProjectsResponse = OrganizationProjectsResponse;
 declare namespace index$b {
-  export { type index$b_DeleteMembershipRequest as DeleteMembershipRequest, type index$b_MembershipDeletionResponse as MembershipDeletionResponse, type index$b_MembershipRequest as MembershipRequest, type index$b_MembershipResponse as MembershipResponse, index$b_MembershipRole as MembershipRole, type index$b_MembershipsResponse as MembershipsResponse, type index$b_OrganizationProject as OrganizationProject, type index$b_OrganizationProjectsResponse as OrganizationProjectsResponse };
+  export { type index$b_DeleteMembershipRequest as DeleteMembershipRequest, type index$b_MembershipDeletionResponse as MembershipDeletionResponse, type index$b_MembershipRequest as MembershipRequest, type index$b_MembershipResponse as MembershipResponse, index$b_MembershipRole as MembershipRole, type index$b_MembershipsResponse as MembershipsResponse, type index$b_OrganizationApiKey as OrganizationApiKey, type index$b_OrganizationApiKeysResponse as OrganizationApiKeysResponse, type index$b_OrganizationProject as OrganizationProject, type index$b_OrganizationProjectsResponse as OrganizationProjectsResponse };
 }
 
 /**
@@ -3686,7 +3803,7 @@ interface CreateScoreRequest {
     /** The value of the score. Must be passed as string for categorical scores, and numeric for boolean and numeric scores. Boolean score values must equal either 1 or 0 (true or false) */
     value: CreateScoreValue;
     comment?: string;
-    metadata?: unknown;
+    metadata?: Record<string, unknown>;
     /** The environment of the score. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'. */
     environment?: string;
     /** The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue. */
@@ -3801,13 +3918,15 @@ interface GetTracesRequest {
     /** Comma-separated list of fields to include in the response. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'. */
     fields?: string;
     /**
-     * JSON string containing an array of filter conditions. When provided, this takes precedence over legacy filter parameters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+     * JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+     *
+     * ## Filter Structure
      * Each filter condition has the following structure:
      * ```json
      * [
      *   {
      *     "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
-     *     "column": string,         // Required. Column to filter on
+     *     "column": string,         // Required. Column to filter on (see available columns below)
      *     "operator": string,       // Required. Operator based on type:
      *                               // - datetime: ">", "<", ">=", "<="
      *                               // - string: "=", "contains", "does not contain", "starts with", "ends with"
@@ -3824,6 +3943,86 @@ interface GetTracesRequest {
      *   }
      * ]
      * ```
+     *
+     * ## Available Columns
+     *
+     * ### Core Trace Fields
+     * - `id` (string) - Trace ID
+     * - `name` (string) - Trace name
+     * - `timestamp` (datetime) - Trace timestamp
+     * - `userId` (string) - User ID
+     * - `sessionId` (string) - Session ID
+     * - `environment` (string) - Environment tag
+     * - `version` (string) - Version tag
+     * - `release` (string) - Release tag
+     * - `tags` (arrayOptions) - Array of tags
+     * - `bookmarked` (boolean) - Bookmark status
+     *
+     * ### Structured Data
+     * - `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.
+     *
+     * ### Aggregated Metrics (from observations)
+     * These metrics are aggregated from all observations within the trace:
+     * - `latency` (number) - Latency in seconds (time from first observation start to last observation end)
+     * - `inputTokens` (number) - Total input tokens across all observations
+     * - `outputTokens` (number) - Total output tokens across all observations
+     * - `totalTokens` (number) - Total tokens (alias: `tokens`)
+     * - `inputCost` (number) - Total input cost in USD
+     * - `outputCost` (number) - Total output cost in USD
+     * - `totalCost` (number) - Total cost in USD
+     *
+     * ### Observation Level Aggregations
+     * These fields aggregate observation levels within the trace:
+     * - `level` (string) - Highest severity level (ERROR > WARNING > DEFAULT > DEBUG)
+     * - `warningCount` (number) - Count of WARNING level observations
+     * - `errorCount` (number) - Count of ERROR level observations
+     * - `defaultCount` (number) - Count of DEFAULT level observations
+     * - `debugCount` (number) - Count of DEBUG level observations
+     *
+     * ### Scores (requires join with scores table)
+     * - `scores_avg` (number) - Average of numeric scores (alias: `scores`)
+     * - `score_categories` (categoryOptions) - Categorical score values
+     *
+     * ## Filter Examples
+     * ```json
+     * [
+     *   {
+     *     "type": "datetime",
+     *     "column": "timestamp",
+     *     "operator": ">=",
+     *     "value": "2024-01-01T00:00:00Z"
+     *   },
+     *   {
+     *     "type": "string",
+     *     "column": "userId",
+     *     "operator": "=",
+     *     "value": "user-123"
+     *   },
+     *   {
+     *     "type": "number",
+     *     "column": "totalCost",
+     *     "operator": ">=",
+     *     "value": 0.01
+     *   },
+     *   {
+     *     "type": "arrayOptions",
+     *     "column": "tags",
+     *     "operator": "all of",
+     *     "value": ["production", "critical"]
+     *   },
+     *   {
+     *     "type": "stringObject",
+     *     "column": "metadata",
+     *     "key": "customer_tier",
+     *     "operator": "=",
+     *     "value": "enterprise"
+     *   }
+     * ]
+     * ```
+     *
+     * ## Performance Notes
+     * - Filtering on `userId`, `sessionId`, or `metadata` may enable skip indexes for better query performance
+     * - Score filters require a join with the scores table and may impact query performance
      */
     filter?: string;
 }
@@ -4646,7 +4845,9 @@ declare class Datasets {
      *     await client.datasets.create({
      *         name: "name",
      *         description: undefined,
-     *         metadata: undefined
+     *         metadata: undefined,
+     *         inputSchema: undefined,
+     *         expectedOutputSchema: undefined
      *     })
      */
     create(request: CreateDatasetRequest, requestOptions?: Datasets.RequestOptions): HttpResponsePromise<Dataset>;
@@ -5647,6 +5848,22 @@ declare class Organizations {
      */
     getOrganizationProjects(requestOptions?: Organizations.RequestOptions): HttpResponsePromise<OrganizationProjectsResponse>;
     private __getOrganizationProjects;
+    /**
+     * Get all API keys for the organization associated with the API key (requires organization-scoped API key)
+     *
+     * @param {Organizations.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link LangfuseAPI.Error}
+     * @throws {@link LangfuseAPI.UnauthorizedError}
+     * @throws {@link LangfuseAPI.AccessDeniedError}
+     * @throws {@link LangfuseAPI.MethodNotAllowedError}
+     * @throws {@link LangfuseAPI.NotFoundError}
+     *
+     * @example
+     *     await client.organizations.getOrganizationApiKeys()
+     */
+    getOrganizationApiKeys(requestOptions?: Organizations.RequestOptions): HttpResponsePromise<OrganizationApiKeysResponse>;
+    private __getOrganizationApiKeys;
     protected _getAuthorizationHeader(): Promise<string | undefined>;
 }
 
@@ -6770,6 +6987,23 @@ declare function base64ToBytes(base64: string): Uint8Array;
 declare function bytesToBase64(bytes: Uint8Array): string;
 declare function base64Encode(input: string): string;
 declare function base64Decode(input: string): string;
+/**
+ * Generate a random experiment ID (16 hex characters from 8 random bytes).
+ * @internal
+ */
+declare function createExperimentId(): Promise<string>;
+/**
+ * Generate experiment item ID from input hash (first 16 hex chars of SHA-256).
+ * Skips serialization if input is already a string.
+ * @internal
+ */
+declare function createExperimentItemId(input: any): Promise<string>;
+/**
+ * Serialize a value to JSON string, handling undefined/null.
+ * Skips serialization if value is already a string.
+ * @internal
+ */
+declare function serializeValue(value: any): string | undefined;
 
 type ParsedMediaReference = {
     mediaId: string;
@@ -6925,4 +7159,186 @@ declare class LangfuseMedia {
     toJSON(): string | null;
 }
 
-export { AccessDeniedError, type AnnotationQueue, type AnnotationQueueAssignmentRequest, type AnnotationQueueItem, AnnotationQueueObjectType, AnnotationQueueStatus, type ApiKeyDeletionResponse, type ApiKeyList, type ApiKeyResponse, type ApiKeySummary, type AuthenticationScheme, type BaseEvent, type BasePrompt, type BaseScore, type BaseScoreV1, BlobStorageExportFrequency, BlobStorageExportMode, type BlobStorageIntegrationDeletionResponse, BlobStorageIntegrationFileType, type BlobStorageIntegrationResponse, BlobStorageIntegrationType, type BlobStorageIntegrationsResponse, type BooleanScore, type BooleanScoreV1, type BulkConfig, type CategoricalScore, type CategoricalScoreV1, type ChatMessage, ChatMessageWithPlaceholders, type ChatPrompt, type Comment, CommentObjectType, type ConfigCategory, type CreateAnnotationQueueAssignmentResponse, type CreateAnnotationQueueItemRequest, type CreateAnnotationQueueRequest, type CreateApiKeyRequest, type CreateBlobStorageIntegrationRequest, type CreateChatPromptRequest, type CreateCommentRequest, type CreateCommentResponse, type CreateDatasetItemRequest, type CreateDatasetRequest, type CreateDatasetRunItemRequest, type CreateEventBody, type CreateEventEvent, type CreateGenerationBody, type CreateGenerationEvent, type CreateModelRequest, type CreateObservationEvent, type CreateProjectRequest, CreatePromptRequest, type CreateScoreConfigRequest, type CreateScoreRequest, type CreateScoreResponse, type CreateScoreValue, type CreateSpanBody, type CreateSpanEvent, type CreateTextPromptRequest, type CreateUserRequest, type Dataset, type DatasetItem, type DatasetRun, type DatasetRunItem, type DatasetRunWithItems, DatasetStatus, type DeleteAnnotationQueueAssignmentResponse, type DeleteAnnotationQueueItemResponse, type DeleteDatasetItemResponse, type DeleteDatasetRunResponse, type DeleteMembershipRequest, type DeleteTraceResponse, type DeleteTracesRequest, type EmptyResponse, Error$1 as Error, type FilterConfig, type GetAnnotationQueueItemsRequest, type GetAnnotationQueuesRequest, type GetCommentsRequest, type GetCommentsResponse, type GetDatasetItemsRequest, type GetDatasetRunsRequest, type GetDatasetsRequest, type GetLlmConnectionsRequest, type GetMediaResponse, type GetMediaUploadUrlRequest, type GetMediaUploadUrlResponse, type GetMetricsRequest, type GetModelsRequest, type GetObservationsRequest, type GetPromptRequest, type GetScoreConfigsRequest, type GetScoresRequest, type GetScoresResponse, GetScoresResponseData, type GetScoresResponseDataBoolean, type GetScoresResponseDataCategorical, type GetScoresResponseDataNumeric, type GetScoresResponseTraceData, type GetSessionsRequest, type GetTracesRequest, type HealthResponse, type IngestionError, IngestionEvent, type IngestionRequest, type IngestionResponse, type IngestionSuccess, type IngestionUsage, LANGFUSE_SDK_NAME, LANGFUSE_SDK_VERSION, LANGFUSE_TRACER_NAME, LangfuseAPIClient, LangfuseAPIError, LangfuseAPITimeoutError, LangfuseMedia, type LangfuseMediaParams, LangfuseOtelSpanAttributes, type ListDatasetRunItemsRequest, type ListPromptsMetaRequest, type ListUsersRequest, LlmAdapter, type LlmConnection, LogLevel, Logger, type LoggerConfig, type MapValue, MediaContentType, type MembershipDeletionResponse, type MembershipRequest, type MembershipResponse, MembershipRole, type MembershipsResponse, MethodNotAllowedError, type MetricsResponse, type Model, type ModelPrice, ModelUsageUnit, NotFoundError, type NumericScore, type NumericScoreV1, type Observation, type ObservationBody, ObservationLevel, ObservationType, type Observations$1 as Observations, type ObservationsView, type ObservationsViews, type OpenAiCompletionUsageSchema, type OpenAiResponseUsageSchema, type OpenAiUsage, type OptionalObservationBody, type OrganizationProject, type OrganizationProjectsResponse, type OtelAttribute, type OtelAttributeValue, type OtelResource, type OtelResourceSpan, type OtelScope, type OtelScopeSpan, type OtelSpan, type OtelTraceRequest, type OtelTraceResponse, type PaginatedAnnotationQueueItems, type PaginatedAnnotationQueues, type PaginatedDatasetItems, type PaginatedDatasetRunItems, type PaginatedDatasetRuns, type PaginatedDatasets, type PaginatedLlmConnections, type PaginatedModels, type PaginatedSessions, type ParsedMediaReference, type PatchMediaBody, type PlaceholderMessage, type Project, type ProjectDeletionResponse, type Projects$1 as Projects, Prompt, type PromptMeta, type PromptMetaListResponse, PromptType, type ResourceMeta, type ResourceType, type ResourceTypesResponse, type SchemaExtension, type SchemaResource, type SchemasResponse, type ScimEmail, type ScimFeatureSupport, type ScimName, type ScimUser, type ScimUsersListResponse, Score$1 as Score, type ScoreBody, type ScoreConfig, type ScoreConfigs$1 as ScoreConfigs, ScoreDataType, type ScoreEvent, ScoreSource, ScoreV1, type SdkLogBody, type SdkLogEvent, type ServiceProviderConfig, ServiceUnavailableError, type Session, type SessionWithTraces, type Sort, type TextPrompt, type Trace$1 as Trace, type TraceBody, type TraceEvent, type TraceWithDetails, type TraceWithFullDetails, type Traces, UnauthorizedError, type UpdateAnnotationQueueItemRequest, type UpdateEventBody, type UpdateGenerationBody, type UpdateGenerationEvent, type UpdateObservationEvent, type UpdateProjectRequest, type UpdatePromptRequest, type UpdateScoreConfigRequest, type UpdateSpanBody, type UpdateSpanEvent, type UpsertLlmConnectionRequest, type Usage, type UsageDetails, type UserMeta, index$q as annotationQueues, base64Decode, base64Encode, base64ToBytes, index$p as blobStorageIntegrations, bytesToBase64, index$o as comments, index$n as commons, configureGlobalLogger, createLogger, index$m as datasetItems, index$l as datasetRunItems, index$k as datasets, generateUUID, getEnv, getGlobalLogger, index$j as health, index$i as ingestion, index$h as llmConnections, LoggerSingleton as logger, index$g as media, index$f as metrics, index$e as models, index$d as observations, index$c as opentelemetry, index$b as organizations, index$a as projects, index as promptVersion, index$9 as prompts, resetGlobalLogger, safeSetTimeout, index$8 as scim, index$5 as score, index$7 as scoreConfigs, index$6 as scoreV2, index$4 as sessions, index$3 as trace, index$1 as utils };
+/**
+ * Attribute propagation utilities for Langfuse OpenTelemetry integration.
+ *
+ * This module provides the `propagateAttributes` function for setting trace-level
+ * attributes (userId, sessionId, metadata) that automatically propagate to all child spans
+ * within the context.
+ */
+
+type CorrelatedKey = "userId" | "sessionId" | "metadata" | "version" | "tags";
+declare const experimentKeys: readonly ["experimentId", "experimentName", "experimentMetadata", "experimentDatasetId", "experimentItemId", "experimentItemMetadata", "experimentItemRootObservationId"];
+type ExperimentKey = (typeof experimentKeys)[number];
+type PropagatedKey = CorrelatedKey | ExperimentKey;
+type PropagatedExperimentAttributes = {
+    experimentId: string;
+    experimentName: string;
+    experimentMetadata?: string;
+    experimentDatasetId?: string;
+    experimentItemId: string;
+    experimentItemMetadata?: string;
+    experimentItemRootObservationId: string;
+};
+declare const LangfuseOtelContextKeys: Record<PropagatedKey, symbol>;
+/**
+ * Parameters for propagateAttributes function.
+ *
+ * @public
+ */
+interface PropagateAttributesParams {
+    /**
+     * User identifier to associate with all spans in this context.
+     * Must be a string ≤200 characters. Use this to track which user
+     * generated each trace and enable e.g. per-user cost/performance analysis.
+     */
+    userId?: string;
+    /**
+     * Session identifier to associate with all spans in this context.
+     * Must be a string ≤200 characters. Use this to group related traces
+     * within a user session (e.g., a conversation thread, multi-turn interaction).
+     */
+    sessionId?: string;
+    /**
+     * Additional key-value metadata to propagate to all spans.
+     * - Keys and values must be strings
+     * - All values must be ≤200 characters
+     * - Use for dimensions like internal correlating identifiers
+     * - AVOID: large payloads, sensitive data, non-string values (will be dropped with warning)
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Version identifier for parts of your application that are independently versioned, e.g. agents
+     */
+    version?: string;
+    /**
+     * List of tags to categorize the group of observations
+     */
+    tags?: string[];
+    /**
+     * If true, propagates attributes using OpenTelemetry baggage for
+     * cross-process/service propagation.
+     *
+     * **Security warning**: When enabled, attribute values are added to HTTP headers
+     * on ALL outbound requests. Only enable if values are safe to transmit via HTTP
+     * headers and you need cross-service tracing.
+     *
+     * @defaultValue false
+     */
+    asBaggage?: boolean;
+    /**
+     * **INTERNAL USE ONLY** - For Langfuse experiment framework.
+     *
+     * This parameter is used internally by the Langfuse experiment system to propagate
+     * experiment context to child spans. It should NOT be used by external code.
+     *
+     * @internal
+     */
+    _internalExperiment?: PropagatedExperimentAttributes;
+}
+/**
+ * Propagate trace-level attributes to all spans created within this context.
+ *
+ * This function sets attributes on the currently active span AND automatically
+ * propagates them to all new child spans created within the callback. This is the
+ * recommended way to set trace-level attributes like userId, sessionId, and metadata
+ * dimensions that should be consistently applied across all observations in a trace.
+ *
+ * **IMPORTANT**: Call this as early as possible within your trace/workflow. Only the
+ * currently active span and spans created after entering this context will have these
+ * attributes. Pre-existing spans will NOT be retroactively updated.
+ *
+ * **Why this matters**: Langfuse aggregation queries (e.g., total cost by userId,
+ * filtering by sessionId) only include observations that have the attribute set.
+ * If you call `propagateAttributes` late in your workflow, earlier spans won't be
+ * included in aggregations for that attribute.
+ *
+ * @param params - Configuration for attributes to propagate
+ * @param fn - Callback function (sync or async) within which attributes are propagated
+ * @returns The result of the callback function
+ *
+ * @example
+ * Basic usage with user and session tracking:
+ *
+ * ```typescript
+ * import { startActiveObservation, propagateAttributes } from '@langfuse/tracing';
+ *
+ * // Set attributes early in the trace
+ * await startActiveObservation('user_workflow', async (span) => {
+ *   await propagateAttributes({
+ *     userId: 'user_123',
+ *     sessionId: 'session_abc',
+ *     metadata: { experiment: 'variant_a', environment: 'production' }
+ *   }, async () => {
+ *     // All spans created here will have userId, sessionId, and metadata
+ *     const llmSpan = startObservation('llm_call', { input: 'Hello' });
+ *     // This span inherits: userId, sessionId, experiment, environment
+ *     llmSpan.end();
+ *
+ *     const gen = startObservation('completion', {}, { asType: 'generation' });
+ *     // This span also inherits all attributes
+ *     gen.end();
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * Late propagation (anti-pattern):
+ *
+ * ```typescript
+ * await startActiveObservation('workflow', async (span) => {
+ *   // These spans WON'T have userId
+ *   const earlySpan = startObservation('early_work', { input: 'data' });
+ *   earlySpan.end();
+ *
+ *   // Set attributes in the middle
+ *   await propagateAttributes({ userId: 'user_123' }, async () => {
+ *     // Only spans created AFTER this point will have userId
+ *     const lateSpan = startObservation('late_work', { input: 'more' });
+ *     lateSpan.end();
+ *   });
+ *
+ *   // Result: Aggregations by userId will miss "early_work" span
+ * });
+ * ```
+ *
+ * @example
+ * Cross-service propagation with baggage (advanced):
+ *
+ * ```typescript
+ * import fetch from 'node-fetch';
+ *
+ * // Service A - originating service
+ * await startActiveObservation('api_request', async () => {
+ *   await propagateAttributes({
+ *     userId: 'user_123',
+ *     sessionId: 'session_abc',
+ *     asBaggage: true  // Propagate via HTTP headers
+ *   }, async () => {
+ *     // Make HTTP request to Service B
+ *     const response = await fetch('https://service-b.example.com/api');
+ *     // userId and sessionId are now in HTTP headers
+ *   });
+ * });
+ *
+ * // Service B - downstream service
+ * // OpenTelemetry will automatically extract baggage from HTTP headers
+ * // and propagate to spans in Service B
+ * ```
+ *
+ * @remarks
+ * - **Validation**: All attribute values (userId, sessionId, metadata values)
+ *   must be strings ≤200 characters. Invalid values will be dropped with a
+ *   warning logged. Ensure values meet constraints before calling.
+ * - **OpenTelemetry**: This uses OpenTelemetry context propagation under the hood,
+ *   making it compatible with other OTel-instrumented libraries.
+ * - **Baggage Security**: When `asBaggage=true`, attribute values are added to HTTP
+ *   headers on outbound requests. Only use for non-sensitive values and when you
+ *   need cross-service tracing.
+ *
+ * @public
+ */
+declare function propagateAttributes<A extends unknown[], F extends (...args: A) => ReturnType<F>>(params: PropagateAttributesParams, fn: F): ReturnType<F>;
+declare function getPropagatedAttributesFromContext(context: Context): Record<string, string | string[]>;
+
+export { AccessDeniedError, type AnnotationQueue, type AnnotationQueueAssignmentRequest, type AnnotationQueueItem, AnnotationQueueObjectType, AnnotationQueueStatus, type ApiKeyDeletionResponse, type ApiKeyList, type ApiKeyResponse, type ApiKeySummary, type AuthenticationScheme, type BaseEvent, type BasePrompt, type BaseScore, type BaseScoreV1, BlobStorageExportFrequency, BlobStorageExportMode, type BlobStorageIntegrationDeletionResponse, BlobStorageIntegrationFileType, type BlobStorageIntegrationResponse, BlobStorageIntegrationType, type BlobStorageIntegrationsResponse, type BooleanScore, type BooleanScoreV1, type BulkConfig, type CategoricalScore, type CategoricalScoreV1, type ChatMessage, ChatMessageWithPlaceholders, type ChatPrompt, type Comment, CommentObjectType, type ConfigCategory, type CreateAnnotationQueueAssignmentResponse, type CreateAnnotationQueueItemRequest, type CreateAnnotationQueueRequest, type CreateApiKeyRequest, type CreateBlobStorageIntegrationRequest, type CreateChatPromptRequest, type CreateCommentRequest, type CreateCommentResponse, type CreateDatasetItemRequest, type CreateDatasetRequest, type CreateDatasetRunItemRequest, type CreateEventBody, type CreateEventEvent, type CreateGenerationBody, type CreateGenerationEvent, type CreateModelRequest, type CreateObservationEvent, type CreateProjectRequest, CreatePromptRequest, type CreateScoreConfigRequest, type CreateScoreRequest, type CreateScoreResponse, type CreateScoreValue, type CreateSpanBody, type CreateSpanEvent, type CreateTextPromptRequest, type CreateUserRequest, type Dataset, type DatasetItem, type DatasetRun, type DatasetRunItem, type DatasetRunWithItems, DatasetStatus, type DeleteAnnotationQueueAssignmentResponse, type DeleteAnnotationQueueItemResponse, type DeleteDatasetItemResponse, type DeleteDatasetRunResponse, type DeleteMembershipRequest, type DeleteTraceResponse, type DeleteTracesRequest, type EmptyResponse, Error$1 as Error, type FilterConfig, type GetAnnotationQueueItemsRequest, type GetAnnotationQueuesRequest, type GetCommentsRequest, type GetCommentsResponse, type GetDatasetItemsRequest, type GetDatasetRunsRequest, type GetDatasetsRequest, type GetLlmConnectionsRequest, type GetMediaResponse, type GetMediaUploadUrlRequest, type GetMediaUploadUrlResponse, type GetMetricsRequest, type GetModelsRequest, type GetObservationsRequest, type GetPromptRequest, type GetScoreConfigsRequest, type GetScoresRequest, type GetScoresResponse, GetScoresResponseData, type GetScoresResponseDataBoolean, type GetScoresResponseDataCategorical, type GetScoresResponseDataNumeric, type GetScoresResponseTraceData, type GetSessionsRequest, type GetTracesRequest, type HealthResponse, type IngestionError, IngestionEvent, type IngestionRequest, type IngestionResponse, type IngestionSuccess, type IngestionUsage, LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT, LANGFUSE_SDK_NAME, LANGFUSE_SDK_VERSION, LANGFUSE_TRACER_NAME, LangfuseAPIClient, LangfuseAPIError, LangfuseAPITimeoutError, LangfuseMedia, type LangfuseMediaParams, LangfuseOtelContextKeys, LangfuseOtelSpanAttributes, type ListDatasetRunItemsRequest, type ListPromptsMetaRequest, type ListUsersRequest, LlmAdapter, type LlmConnection, LogLevel, Logger, type LoggerConfig, type MapValue, MediaContentType, type MembershipDeletionResponse, type MembershipRequest, type MembershipResponse, MembershipRole, type MembershipsResponse, MethodNotAllowedError, type MetricsResponse, type Model, type ModelPrice, ModelUsageUnit, NotFoundError, type NumericScore, type NumericScoreV1, type Observation, type ObservationBody, ObservationLevel, ObservationType, type Observations$1 as Observations, type ObservationsView, type ObservationsViews, type OpenAiCompletionUsageSchema, type OpenAiResponseUsageSchema, type OpenAiUsage, type OptionalObservationBody, type OrganizationApiKey, type OrganizationApiKeysResponse, type OrganizationProject, type OrganizationProjectsResponse, type OtelAttribute, type OtelAttributeValue, type OtelResource, type OtelResourceSpan, type OtelScope, type OtelScopeSpan, type OtelSpan, type OtelTraceRequest, type OtelTraceResponse, type PaginatedAnnotationQueueItems, type PaginatedAnnotationQueues, type PaginatedDatasetItems, type PaginatedDatasetRunItems, type PaginatedDatasetRuns, type PaginatedDatasets, type PaginatedLlmConnections, type PaginatedModels, type PaginatedSessions, type ParsedMediaReference, type PatchMediaBody, type PlaceholderMessage, type Project, type ProjectDeletionResponse, type Projects$1 as Projects, Prompt, type PromptMeta, type PromptMetaListResponse, PromptType, type PropagateAttributesParams, type ResourceMeta, type ResourceType, type ResourceTypesResponse, type SchemaExtension, type SchemaResource, type SchemasResponse, type ScimEmail, type ScimFeatureSupport, type ScimName, type ScimUser, type ScimUsersListResponse, Score$1 as Score, type ScoreBody, type ScoreConfig, type ScoreConfigs$1 as ScoreConfigs, ScoreDataType, type ScoreEvent, ScoreSource, ScoreV1, type SdkLogBody, type SdkLogEvent, type ServiceProviderConfig, ServiceUnavailableError, type Session, type SessionWithTraces, type Sort, type TextPrompt, type Trace$1 as Trace, type TraceBody, type TraceEvent, type TraceWithDetails, type TraceWithFullDetails, type Traces, UnauthorizedError, type UpdateAnnotationQueueItemRequest, type UpdateEventBody, type UpdateGenerationBody, type UpdateGenerationEvent, type UpdateObservationEvent, type UpdateProjectRequest, type UpdatePromptRequest, type UpdateScoreConfigRequest, type UpdateSpanBody, type UpdateSpanEvent, type UpsertLlmConnectionRequest, type Usage, type UsageDetails, type UserMeta, index$q as annotationQueues, base64Decode, base64Encode, base64ToBytes, index$p as blobStorageIntegrations, bytesToBase64, index$o as comments, index$n as commons, configureGlobalLogger, createExperimentId, createExperimentItemId, createLogger, index$m as datasetItems, index$l as datasetRunItems, index$k as datasets, generateUUID, getEnv, getGlobalLogger, getPropagatedAttributesFromContext, index$j as health, index$i as ingestion, index$h as llmConnections, LoggerSingleton as logger, index$g as media, index$f as metrics, index$e as models, index$d as observations, index$c as opentelemetry, index$b as organizations, index$a as projects, index as promptVersion, index$9 as prompts, propagateAttributes, resetGlobalLogger, safeSetTimeout, index$8 as scim, index$5 as score, index$7 as scoreConfigs, index$6 as scoreV2, serializeValue, index$4 as sessions, index$3 as trace, index$1 as utils };