@langfuse/core 5.5.3 → 5.6.0

package/dist/index.d.ts

@@ -1304,6 +1304,49 @@ interface DatasetItem {
     datasetName: string;
     createdAt: string;
     updatedAt: string;
+    /** Resolved Langfuse media references found in input, expectedOutput, and metadata. */
+    mediaReferences: DatasetItemMediaReference[];
+}
+
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+
+interface DatasetItemMediaReference {
+    /** The dataset item field containing the reference */
+    field: DatasetItemMediaReferenceField;
+    /** The Langfuse media reference string, e.g. `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@` */
+    referenceString: string;
+    /** JSONPath of the string holding the reference within the field, e.g. `$['image']` */
+    jsonPath: string;
+    /** The resolved media record. */
+    media: DatasetItemMediaReferenceMedia;
+}
+
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+type DatasetItemMediaReferenceField = "input" | "expectedOutput" | "metadata";
+declare const DatasetItemMediaReferenceField: {
+    readonly Input: "input";
+    readonly ExpectedOutput: "expectedOutput";
+    readonly Metadata: "metadata";
+};
+
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+interface DatasetItemMediaReferenceMedia {
+    /** The unique langfuse identifier of the media record */
+    mediaId: string;
+    /** The MIME type of the media record */
+    contentType: string;
+    /** The size of the media record in bytes */
+    contentLength: number;
+    /** The signed download URL of the media record */
+    url: string;
+    /** The expiry date and time of the download URL */
+    urlExpiry: string;
 }
 
 /**
@@ -1850,6 +1893,9 @@ type index$w_CorrectionScore = CorrectionScore;
 type index$w_CreateScoreValue = CreateScoreValue;
 type index$w_Dataset = Dataset;
 type index$w_DatasetItem = DatasetItem;
+type index$w_DatasetItemMediaReference = DatasetItemMediaReference;
+declare const index$w_DatasetItemMediaReferenceField: typeof DatasetItemMediaReferenceField;
+type index$w_DatasetItemMediaReferenceMedia = DatasetItemMediaReferenceMedia;
 type index$w_DatasetRun = DatasetRun;
 type index$w_DatasetRunItem = DatasetRunItem;
 type index$w_DatasetRunWithItems = DatasetRunWithItems;
@@ -1881,7 +1927,7 @@ type index$w_TraceWithDetails = TraceWithDetails;
 type index$w_TraceWithFullDetails = TraceWithFullDetails;
 type index$w_Usage = Usage;
 declare namespace index$w {
-  export { AccessDeniedError$1 as AccessDeniedError, type index$w_BaseScore as BaseScore, type index$w_BaseScoreV1 as BaseScoreV1, type index$w_BooleanScore as BooleanScore, type index$w_BooleanScoreV1 as BooleanScoreV1, type index$w_CategoricalScore as CategoricalScore, type index$w_CategoricalScoreV1 as CategoricalScoreV1, type index$w_Comment as Comment, index$w_CommentObjectType as CommentObjectType, type index$w_ConfigCategory as ConfigCategory, type index$w_CorrectionScore as CorrectionScore, type index$w_CreateScoreValue as CreateScoreValue, type index$w_Dataset as Dataset, type index$w_DatasetItem as DatasetItem, type index$w_DatasetRun as DatasetRun, type index$w_DatasetRunItem as DatasetRunItem, type index$w_DatasetRunWithItems as DatasetRunWithItems, index$w_DatasetStatus as DatasetStatus, Error$1 as Error, type index$w_MapValue as MapValue, MethodNotAllowedError$1 as MethodNotAllowedError, type index$w_Model as Model, type index$w_ModelPrice as ModelPrice, index$w_ModelUsageUnit as ModelUsageUnit, NotFoundError$1 as NotFoundError, type index$w_NumericScore as NumericScore, type index$w_NumericScoreV1 as NumericScoreV1, type index$w_Observation as Observation, index$w_ObservationLevel as ObservationLevel, type index$w_ObservationV2 as ObservationV2, type index$w_ObservationsView as ObservationsView, type index$w_PricingTier as PricingTier, type index$w_PricingTierCondition as PricingTierCondition, type index$w_PricingTierInput as PricingTierInput, index$w_PricingTierOperator as PricingTierOperator, index$w_Score as Score, type index$w_ScoreConfig as ScoreConfig, index$w_ScoreConfigDataType as ScoreConfigDataType, index$w_ScoreDataType as ScoreDataType, index$w_ScoreSource as ScoreSource, ScoreV1$1 as ScoreV1, type index$w_Session as Session, type index$w_SessionWithTraces as SessionWithTraces, type index$w_TextScore as TextScore, type index$w_TextScoreV1 as TextScoreV1, type Trace$1 as Trace, type index$w_TraceWithDetails as TraceWithDetails, type index$w_TraceWithFullDetails as TraceWithFullDetails, UnauthorizedError$1 as UnauthorizedError, type index$w_Usage as Usage };
+  export { AccessDeniedError$1 as AccessDeniedError, type index$w_BaseScore as BaseScore, type index$w_BaseScoreV1 as BaseScoreV1, type index$w_BooleanScore as BooleanScore, type index$w_BooleanScoreV1 as BooleanScoreV1, type index$w_CategoricalScore as CategoricalScore, type index$w_CategoricalScoreV1 as CategoricalScoreV1, type index$w_Comment as Comment, index$w_CommentObjectType as CommentObjectType, type index$w_ConfigCategory as ConfigCategory, type index$w_CorrectionScore as CorrectionScore, type index$w_CreateScoreValue as CreateScoreValue, type index$w_Dataset as Dataset, type index$w_DatasetItem as DatasetItem, type index$w_DatasetItemMediaReference as DatasetItemMediaReference, index$w_DatasetItemMediaReferenceField as DatasetItemMediaReferenceField, type index$w_DatasetItemMediaReferenceMedia as DatasetItemMediaReferenceMedia, type index$w_DatasetRun as DatasetRun, type index$w_DatasetRunItem as DatasetRunItem, type index$w_DatasetRunWithItems as DatasetRunWithItems, index$w_DatasetStatus as DatasetStatus, Error$1 as Error, type index$w_MapValue as MapValue, MethodNotAllowedError$1 as MethodNotAllowedError, type index$w_Model as Model, type index$w_ModelPrice as ModelPrice, index$w_ModelUsageUnit as ModelUsageUnit, NotFoundError$1 as NotFoundError, type index$w_NumericScore as NumericScore, type index$w_NumericScoreV1 as NumericScoreV1, type index$w_Observation as Observation, index$w_ObservationLevel as ObservationLevel, type index$w_ObservationV2 as ObservationV2, type index$w_ObservationsView as ObservationsView, type index$w_PricingTier as PricingTier, type index$w_PricingTierCondition as PricingTierCondition, type index$w_PricingTierInput as PricingTierInput, index$w_PricingTierOperator as PricingTierOperator, index$w_Score as Score, type index$w_ScoreConfig as ScoreConfig, index$w_ScoreConfigDataType as ScoreConfigDataType, index$w_ScoreDataType as ScoreDataType, index$w_ScoreSource as ScoreSource, ScoreV1$1 as ScoreV1, type index$w_Session as Session, type index$w_SessionWithTraces as SessionWithTraces, type index$w_TextScore as TextScore, type index$w_TextScoreV1 as TextScoreV1, type Trace$1 as Trace, type index$w_TraceWithDetails as TraceWithDetails, type index$w_TraceWithFullDetails as TraceWithFullDetails, UnauthorizedError$1 as UnauthorizedError, type index$w_Usage as Usage };
 }
 
 /**
@@ -3217,17 +3263,24 @@ interface PatchMediaBody {
  * This file was auto-generated by Fern from our API Definition.
  */
 
+/**
+ * Request a presigned media upload URL. Provide exactly one context: a trace (traceId, optionally observationId) or a dataset item (datasetId + datasetItemId). field is required and must match the chosen context.
+ */
 interface GetMediaUploadUrlRequest {
-    /** The trace ID associated with the media record */
-    traceId: string;
+    /** The trace the media is associated with. Null for dataset item media uploads. */
+    traceId?: string;
     /** The observation ID associated with the media record. If the media record is associated directly with a trace, this will be null. */
     observationId?: string;
+    /** The dataset the media belongs to. Null for trace/observation media uploads. */
+    datasetId?: string;
+    /** The dataset item the media is associated with (need not exist yet). Null for trace/observation media uploads. */
+    datasetItemId?: string;
     contentType: MediaContentType;
     /** The size of the media record in bytes */
     contentLength: number;
     /** The SHA-256 hash of the media record */
     sha256Hash: string;
-    /** The trace / observation field the media record is associated with. This can be one of `input`, `output`, `metadata` */
+    /** The item field the media is in: `input`/`output`/`metadata` (trace) or `input`/`expectedOutput`/`metadata` (dataset item). */
     field: string;
 }
 
@@ -8551,8 +8604,10 @@ declare class Media {
      *
      * @example
      *     await client.media.getUploadUrl({
-     *         traceId: "traceId",
+     *         traceId: undefined,
      *         observationId: undefined,
+     *         datasetId: undefined,
+     *         datasetItemId: undefined,
      *         contentType: "image/png",
      *         contentLength: 1,
      *         sha256Hash: "sha256Hash",
@@ -10123,7 +10178,12 @@ declare class Sessions {
     protected readonly _options: Sessions.Options;
     constructor(_options: Sessions.Options);
     /**
-     * Get sessions
+     * Get sessions.
+     *
+     * This legacy endpoint is not recommended for new data extraction workflows.
+     * Use the v2 observations endpoint with a bounded time range and group rows by
+     * `sessionId` instead:
+     * `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
      *
      * @param {LangfuseAPI.GetSessionsRequest} request
      * @param {Sessions.RequestOptions} requestOptions - Request-specific configuration.
@@ -10140,7 +10200,12 @@ declare class Sessions {
     list(request?: GetSessionsRequest, requestOptions?: Sessions.RequestOptions): HttpResponsePromise<PaginatedSessions>;
     private __list;
     /**
-     * Get a session. Please note that `traces` on this endpoint are not paginated, if you plan to fetch large sessions, consider `GET /api/public/traces?sessionId=<sessionId>`
+     * Get a session.
+     *
+     * Please note that `traces` on this endpoint are not paginated. For large
+     * sessions or new data extraction workflows, use the v2 observations endpoint
+     * with a URL-encoded `sessionId` filter and a bounded time range:
+     * `GET /api/public/v2/observations?filter=<sessionId filter>&fromStartTime=<from>&toStartTime=<to>`.
      *
      * @param {string} sessionId - The unique id of a session
      * @param {Sessions.RequestOptions} requestOptions - Request-specific configuration.
@@ -11102,6 +11167,164 @@ declare class LangfuseMedia {
      */
     toJSON(): string | null;
 }
+/**
+ * Parameters for constructing a {@link LangfuseMediaReference}.
+ *
+ * @public
+ */
+type LangfuseMediaReferenceParams = {
+    /** The unique Langfuse identifier of the media record */
+    mediaId: string;
+    /** The MIME type of the media record */
+    contentType: string;
+    /** The signed download URL of the media record */
+    url: string;
+    /** The expiry date and time (ISO 8601) of the signed download URL */
+    urlExpiry?: string;
+    /** The size of the media record in bytes */
+    contentLength?: number;
+    /**
+     * The original `@@@langfuseMedia:…@@@` reference string. Used to losslessly
+     * round-trip a resolved reference back through the API / tracing when a
+     * fetched dataset item is re-used.
+     */
+    referenceString: string;
+};
+/**
+ * A resolved reference to a media record stored in Langfuse.
+ *
+ * Returned in place of media reference strings when fetching dataset items via
+ * `langfuse.dataset.get`. It holds the media metadata and a signed download
+ * URL, and exposes helpers to fetch the content in the formats commonly
+ * expected by LLM providers.
+ *
+ * The signed `url` is short-lived. Fetch the content promptly, or re-fetch the
+ * dataset item if {@link LangfuseMediaReference.isUrlExpired} returns true.
+ *
+ * @example Feeding media to a provider
+ * ```typescript
+ * const dataset = await langfuse.dataset.get("visual-qa");
+ *
+ * for (const item of dataset.items) {
+ *   const image = item.input.image as LangfuseMediaReference;
+ *
+ *   // OpenAI: { type: "input_image", image_url: await image.fetchDataUri() }
+ *   // Anthropic: { source: { type: "base64", media_type: image.contentType, data: await image.fetchBase64() } }
+ *   // Vercel AI SDK: { type: "image", image: await image.fetchBytes(), mediaType: image.contentType }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class LangfuseMediaReference implements LangfuseMediaReferenceParams {
+    readonly mediaId: string;
+    readonly contentType: string;
+    readonly url: string;
+    readonly urlExpiry?: string;
+    readonly contentLength?: number;
+    readonly referenceString: string;
+    constructor(params: LangfuseMediaReferenceParams);
+    /**
+     * Serializes to the original `@@@langfuseMedia:…@@@` reference string.
+     *
+     * This makes resolved references round-trip losslessly through anything that
+     * serializes with `JSON.stringify` — the dataset item API, experiment/trace
+     * span attributes — so a re-used item links back to its media instead of
+     * persisting a JSON object with a soon-to-expire signed URL.
+     */
+    toJSON(): string;
+    /**
+     * Returns whether the signed download URL is expired or near expiry.
+     *
+     * @param thresholdSeconds - Treat the URL as expired this many seconds before
+     *   its actual expiry to account for clock skew and download time (default: 60).
+     * @returns true if the URL is expired or within the threshold of expiry. If
+     *   the expiry is unknown or unparseable, returns false.
+     */
+    isUrlExpired(thresholdSeconds?: number): boolean;
+    /**
+     * Fetches the media content from the signed URL over the network.
+     *
+     * Useful for local evaluators / image libraries, manual base64 conversion, or
+     * the Vercel AI SDK (`{ type: "image", image: await media.fetchBytes() }`).
+     *
+     * @returns The media content as raw bytes
+     * @throws {Error} If the download fails
+     */
+    fetchBytes(): Promise<Uint8Array>;
+    /**
+     * Fetches the media over the network and returns raw base64 (no data URI prefix).
+     *
+     * Useful for Anthropic (`{ source: { type: "base64", media_type: media.contentType, data: await media.fetchBase64() } }`)
+     * or LangChain (`{ type: "image", base64: await media.fetchBase64(), mime_type: media.contentType }`).
+     *
+     * @returns The media content as a base64 string
+     * @throws {Error} If the download fails
+     */
+    fetchBase64(): Promise<string>;
+    /**
+     * Fetches the media over the network and returns a `data:<contentType>;base64,...` URI.
+     *
+     * Useful for OpenAI (`{ type: "input_image", image_url: await media.fetchDataUri() }`).
+     *
+     * @returns The media content as a base64 data URI
+     * @throws {Error} If the download fails
+     */
+    fetchDataUri(): Promise<string>;
+}
+
+/**
+ * Parameters for {@link uploadMedia}.
+ *
+ * @internal
+ */
+type UploadMediaParams = {
+    /** The API client used to request the upload URL and report completion. */
+    apiClient: LangfuseAPIClient;
+    /** The media to upload. */
+    media: LangfuseMedia;
+    /**
+     * The trace the media belongs to. Omit for media that is not associated with
+     * a trace (e.g. dataset item media).
+     */
+    traceId?: string;
+    /** The observation the media belongs to, if any. */
+    observationId?: string;
+    /**
+     * The dataset the media belongs to. Set together with {@link datasetItemId}
+     * for dataset item media (instead of a trace context).
+     */
+    datasetId?: string;
+    /** The dataset item the media belongs to (need not exist yet). */
+    datasetItemId?: string;
+    /**
+     * The item field the media is associated with — `input`/`output`/`metadata`
+     * for a trace, or `input`/`expectedOutput`/`metadata` for a dataset item.
+     */
+    field: string;
+    /** Logger to use. Defaults to the global logger. */
+    logger?: Logger;
+    /** Maximum number of upload retries on transient failures. Defaults to 3. */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff. Defaults to 1000. */
+    baseDelay?: number;
+};
+/**
+ * Uploads a {@link LangfuseMedia} to Langfuse.
+ *
+ * Requests a presigned upload URL, uploads the content with exponential-backoff
+ * retries, and reports completion. The media may be associated with a trace /
+ * observation (pass {@link UploadMediaParams.traceId}) or stand alone (e.g.
+ * dataset item media), in which case the trace context is omitted.
+ *
+ * If the media has already been uploaded (server returns no upload URL), this
+ * resolves without re-uploading.
+ *
+ * @throws {Error} If required media fields are missing or the upload fails after
+ *   all retries.
+ * @internal
+ */
+declare function uploadMedia(params: UploadMediaParams): Promise<void>;
 
 /**
  * Attribute propagation utilities for Langfuse OpenTelemetry integration.
@@ -11313,4 +11536,4 @@ interface PropagateAttributesParams {
 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$1 as 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, type BaseScoreV3, BlobStorageExportFieldGroup, BlobStorageExportFrequency, BlobStorageExportMode, BlobStorageExportSource, type BlobStorageIntegrationDeletionResponse, BlobStorageIntegrationFileType, type BlobStorageIntegrationResponse, type BlobStorageIntegrationStatusResponse, BlobStorageIntegrationType, type BlobStorageIntegrationsResponse, BlobStorageSyncStatus, type BooleanScore, type BooleanScoreV1, type BooleanScoreV3, type BulkConfig, type CategoricalScore, type CategoricalScoreV1, type CategoricalScoreV3, type ChatMessage, ChatMessageType, type ChatMessageWithPlaceholders, type ChatPrompt, type Comment, CommentObjectType, type ConfigCategory, type CorrectionScore, type CorrectionScoreV3, type CreateAnnotationQueueAssignmentResponse, type CreateAnnotationQueueItemRequest, type CreateAnnotationQueueRequest, type CreateApiKeyRequest, type CreateBlobStorageIntegrationRequest, type CreateChatPromptRequest, CreateChatPromptType, type CreateCommentRequest, type CreateCommentResponse, type CreateDatasetItemRequest, type CreateDatasetRequest, type CreateDatasetRunItemRequest, type CreateEventBody, type CreateEventEvent, type CreateGenerationBody, type CreateGenerationEvent, type CreateModelRequest, type CreateObservationEvent, type CreateProjectRequest, type CreatePromptRequest, type CreateScoreConfigRequest, type CreateScoreValue, type CreateSpanBody, type CreateSpanEvent, type CreateTextPromptRequest, CreateTextPromptType, type CreateUserRequest, type Dataset, type DatasetItem, type DatasetRun, type DatasetRunItem, type DatasetRunWithItems, DatasetStatus, type DeleteAnnotationQueueAssignmentResponse, type DeleteAnnotationQueueItemResponse, type DeleteDatasetItemResponse, type DeleteDatasetRunResponse, type DeleteLlmConnectionResponse, type DeleteMembershipRequest, type DeletePromptRequest, 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 GetMetricsV2Request, type GetModelsRequest, type GetObservationsV2Request, type GetPromptRequest, type GetScoreConfigsRequest, type GetScoresRequest, type GetScoresResponse, GetScoresResponseData, type GetScoresResponseDataBoolean, type GetScoresResponseDataCategorical, type GetScoresResponseDataCorrection, type GetScoresResponseDataNumeric, type GetScoresResponseDataText, type GetScoresResponseTraceData, type GetScoresV3Meta, type GetScoresV3Request, type GetScoresV3Response, type GetSessionsRequest, type GetTraceRequest, 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, LANGFUSE_TRACE_ID_BAGGAGE_KEY, 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$1 as MethodNotAllowedError, type MetricsV2Response, type Model, type ModelPrice, ModelUsageUnit, NotFoundError$1 as NotFoundError, type NumericScore, type NumericScoreV1, type NumericScoreV3, type Observation, type ObservationBody, ObservationLevel, ObservationType, type ObservationV2, type ObservationsV2Meta, type ObservationsV2Response, type ObservationsView, type OpenAiCompletionUsageSchema, type OpenAiResponseUsageSchema, type OpenAiUsage, type OptionalObservationBody, type Organization, 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, PlaceholderMessageType, type PricingTier, type PricingTierCondition, type PricingTierInput, PricingTierOperator, 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, type ScoreBody, type ScoreConfig, ScoreConfigDataType, type ScoreConfigs$1 as ScoreConfigs, ScoreDataType, type ScoreEvent, ScoreSource, type ScoreSubjectExperimentV3, type ScoreSubjectObservationV3, type ScoreSubjectSessionV3, type ScoreSubjectTraceV3, ScoreSubjectV3, ScoreV1$1 as ScoreV1, ScoreV3, type SdkLogBody, type SdkLogEvent, type ServiceProviderConfig, ServiceUnavailableError, type Session, type SessionWithTraces, type Sort, type TextPrompt, type TextScore, type TextScoreV1, type TextScoreV3, type Trace$1 as Trace, type TraceBody, type TraceEvent, type TraceWithDetails, type TraceWithFullDetails, type Traces, UnauthorizedError$1 as 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$z as annotationQueues, base64Decode, base64Encode, base64ToBytes, index$y as blobStorageIntegrations, bytesToBase64, index$x as comments, index$w as commons, configureGlobalLogger, createExperimentId, createExperimentItemId, createLogger, index$v as datasetItems, index$u as datasetRunItems, index$t as datasets, generateUUID, getEnv, getGlobalLogger, getLangfuseTraceIdFromBaggage, getPropagatedAttributesFromContext, index$s as health, index$r as ingestion, index$n as legacy, index$m as llmConnections, LoggerSingleton as logger, index$l as media, index$k as metrics, index$j as models, index$i as observations, index$h as opentelemetry, index$g as organizations, index$f as projects, index as promptVersion, index$e as prompts, propagateAttributes, resetGlobalLogger, safeSetTimeout, index$d as scim, index$c as scoreConfigs, index$a as scores, index$b as scoresV3, serializeValue, index$9 as sessions, setLangfuseTraceIdInBaggage, index$8 as trace, index$3 as unstable, index$1 as utils };
+export { AccessDeniedError$1 as 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, type BaseScoreV3, BlobStorageExportFieldGroup, BlobStorageExportFrequency, BlobStorageExportMode, BlobStorageExportSource, type BlobStorageIntegrationDeletionResponse, BlobStorageIntegrationFileType, type BlobStorageIntegrationResponse, type BlobStorageIntegrationStatusResponse, BlobStorageIntegrationType, type BlobStorageIntegrationsResponse, BlobStorageSyncStatus, type BooleanScore, type BooleanScoreV1, type BooleanScoreV3, type BulkConfig, type CategoricalScore, type CategoricalScoreV1, type CategoricalScoreV3, type ChatMessage, ChatMessageType, type ChatMessageWithPlaceholders, type ChatPrompt, type Comment, CommentObjectType, type ConfigCategory, type CorrectionScore, type CorrectionScoreV3, type CreateAnnotationQueueAssignmentResponse, type CreateAnnotationQueueItemRequest, type CreateAnnotationQueueRequest, type CreateApiKeyRequest, type CreateBlobStorageIntegrationRequest, type CreateChatPromptRequest, CreateChatPromptType, type CreateCommentRequest, type CreateCommentResponse, type CreateDatasetItemRequest, type CreateDatasetRequest, type CreateDatasetRunItemRequest, type CreateEventBody, type CreateEventEvent, type CreateGenerationBody, type CreateGenerationEvent, type CreateModelRequest, type CreateObservationEvent, type CreateProjectRequest, type CreatePromptRequest, type CreateScoreConfigRequest, type CreateScoreValue, type CreateSpanBody, type CreateSpanEvent, type CreateTextPromptRequest, CreateTextPromptType, type CreateUserRequest, type Dataset, type DatasetItem, type DatasetItemMediaReference, DatasetItemMediaReferenceField, type DatasetItemMediaReferenceMedia, type DatasetRun, type DatasetRunItem, type DatasetRunWithItems, DatasetStatus, type DeleteAnnotationQueueAssignmentResponse, type DeleteAnnotationQueueItemResponse, type DeleteDatasetItemResponse, type DeleteDatasetRunResponse, type DeleteLlmConnectionResponse, type DeleteMembershipRequest, type DeletePromptRequest, 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 GetMetricsV2Request, type GetModelsRequest, type GetObservationsV2Request, type GetPromptRequest, type GetScoreConfigsRequest, type GetScoresRequest, type GetScoresResponse, GetScoresResponseData, type GetScoresResponseDataBoolean, type GetScoresResponseDataCategorical, type GetScoresResponseDataCorrection, type GetScoresResponseDataNumeric, type GetScoresResponseDataText, type GetScoresResponseTraceData, type GetScoresV3Meta, type GetScoresV3Request, type GetScoresV3Response, type GetSessionsRequest, type GetTraceRequest, 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, LANGFUSE_TRACE_ID_BAGGAGE_KEY, LangfuseAPIClient, LangfuseAPIError, LangfuseAPITimeoutError, LangfuseMedia, type LangfuseMediaParams, LangfuseMediaReference, type LangfuseMediaReferenceParams, 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$1 as MethodNotAllowedError, type MetricsV2Response, type Model, type ModelPrice, ModelUsageUnit, NotFoundError$1 as NotFoundError, type NumericScore, type NumericScoreV1, type NumericScoreV3, type Observation, type ObservationBody, ObservationLevel, ObservationType, type ObservationV2, type ObservationsV2Meta, type ObservationsV2Response, type ObservationsView, type OpenAiCompletionUsageSchema, type OpenAiResponseUsageSchema, type OpenAiUsage, type OptionalObservationBody, type Organization, 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, PlaceholderMessageType, type PricingTier, type PricingTierCondition, type PricingTierInput, PricingTierOperator, 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, type ScoreBody, type ScoreConfig, ScoreConfigDataType, type ScoreConfigs$1 as ScoreConfigs, ScoreDataType, type ScoreEvent, ScoreSource, type ScoreSubjectExperimentV3, type ScoreSubjectObservationV3, type ScoreSubjectSessionV3, type ScoreSubjectTraceV3, ScoreSubjectV3, ScoreV1$1 as ScoreV1, ScoreV3, type SdkLogBody, type SdkLogEvent, type ServiceProviderConfig, ServiceUnavailableError, type Session, type SessionWithTraces, type Sort, type TextPrompt, type TextScore, type TextScoreV1, type TextScoreV3, type Trace$1 as Trace, type TraceBody, type TraceEvent, type TraceWithDetails, type TraceWithFullDetails, type Traces, UnauthorizedError$1 as UnauthorizedError, type UpdateAnnotationQueueItemRequest, type UpdateEventBody, type UpdateGenerationBody, type UpdateGenerationEvent, type UpdateObservationEvent, type UpdateProjectRequest, type UpdatePromptRequest, type UpdateScoreConfigRequest, type UpdateSpanBody, type UpdateSpanEvent, type UploadMediaParams, type UpsertLlmConnectionRequest, type Usage, type UsageDetails, type UserMeta, index$z as annotationQueues, base64Decode, base64Encode, base64ToBytes, index$y as blobStorageIntegrations, bytesToBase64, index$x as comments, index$w as commons, configureGlobalLogger, createExperimentId, createExperimentItemId, createLogger, index$v as datasetItems, index$u as datasetRunItems, index$t as datasets, generateUUID, getEnv, getGlobalLogger, getLangfuseTraceIdFromBaggage, getPropagatedAttributesFromContext, index$s as health, index$r as ingestion, index$n as legacy, index$m as llmConnections, LoggerSingleton as logger, index$l as media, index$k as metrics, index$j as models, index$i as observations, index$h as opentelemetry, index$g as organizations, index$f as projects, index as promptVersion, index$e as prompts, propagateAttributes, resetGlobalLogger, safeSetTimeout, index$d as scim, index$c as scoreConfigs, index$a as scores, index$b as scoresV3, serializeValue, index$9 as sessions, setLangfuseTraceIdInBaggage, index$8 as trace, index$3 as unstable, uploadMedia, index$1 as utils };

package/dist/index.mjs

@@ -276,7 +276,7 @@ var resetGlobalLogger = () => {
 // package.json
 var package_default = {
   name: "@langfuse/core",
-  version: "5.5.3",
+  version: "5.6.0",
   description: "Core functions and utilities for Langfuse packages",
   type: "module",
   sideEffects: false,
@@ -462,6 +462,7 @@ var commons_exports = {};
 __export(commons_exports, {
   AccessDeniedError: () => AccessDeniedError,
   CommentObjectType: () => CommentObjectType,
+  DatasetItemMediaReferenceField: () => DatasetItemMediaReferenceField,
   DatasetStatus: () => DatasetStatus,
   Error: () => Error2,
   MethodNotAllowedError: () => MethodNotAllowedError,
@@ -475,6 +476,13 @@ __export(commons_exports, {
   UnauthorizedError: () => UnauthorizedError
 });
 
+// src/api/api/resources/commons/types/DatasetItemMediaReferenceField.ts
+var DatasetItemMediaReferenceField = {
+  Input: "input",
+  ExpectedOutput: "expectedOutput",
+  Metadata: "metadata"
+};
+
 // src/api/api/resources/commons/types/PricingTierOperator.ts
 var PricingTierOperator = {
   Gt: "gt",
@@ -6801,8 +6809,10 @@ var Media = class {
    *
    * @example
    *     await client.media.getUploadUrl({
-   *         traceId: "traceId",
+   *         traceId: undefined,
    *         observationId: undefined,
+   *         datasetId: undefined,
+   *         datasetItemId: undefined,
    *         contentType: "image/png",
    *         contentLength: 1,
    *         sha256Hash: "sha256Hash",
@@ -11990,7 +12000,12 @@ var Sessions = class {
     this._options = _options;
   }
   /**
-   * Get sessions
+   * Get sessions.
+   *
+   * This legacy endpoint is not recommended for new data extraction workflows.
+   * Use the v2 observations endpoint with a bounded time range and group rows by
+   * `sessionId` instead:
+   * `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
    *
    * @param {LangfuseAPI.GetSessionsRequest} request
    * @param {Sessions.RequestOptions} requestOptions - Request-specific configuration.
@@ -12114,7 +12129,12 @@ var Sessions = class {
     }
   }
   /**
-   * Get a session. Please note that `traces` on this endpoint are not paginated, if you plan to fetch large sessions, consider `GET /api/public/traces?sessionId=<sessionId>`
+   * Get a session.
+   *
+   * Please note that `traces` on this endpoint are not paginated. For large
+   * sessions or new data extraction workflows, use the v2 observations endpoint
+   * with a URL-encoded `sessionId` filter and a bounded time range:
+   * `GET /api/public/v2/observations?filter=<sessionId filter>&fromStartTime=<from>&toStartTime=<to>`.
    *
    * @param {string} sessionId - The unique id of a session
    * @param {Sessions.RequestOptions} requestOptions - Request-specific configuration.
@@ -14633,6 +14653,196 @@ var LangfuseMedia = class {
     return this.base64DataUri;
   }
 };
+var LangfuseMediaReference = class {
+  constructor(params) {
+    Object.assign(this, params);
+  }
+  /**
+   * Serializes to the original `@@@langfuseMedia:…@@@` reference string.
+   *
+   * This makes resolved references round-trip losslessly through anything that
+   * serializes with `JSON.stringify` — the dataset item API, experiment/trace
+   * span attributes — so a re-used item links back to its media instead of
+   * persisting a JSON object with a soon-to-expire signed URL.
+   */
+  toJSON() {
+    return this.referenceString;
+  }
+  /**
+   * Returns whether the signed download URL is expired or near expiry.
+   *
+   * @param thresholdSeconds - Treat the URL as expired this many seconds before
+   *   its actual expiry to account for clock skew and download time (default: 60).
+   * @returns true if the URL is expired or within the threshold of expiry. If
+   *   the expiry is unknown or unparseable, returns false.
+   */
+  isUrlExpired(thresholdSeconds = 60) {
+    if (!this.urlExpiry) {
+      return false;
+    }
+    const expiryMs = Date.parse(this.urlExpiry);
+    if (Number.isNaN(expiryMs)) {
+      return false;
+    }
+    return expiryMs - Date.now() <= thresholdSeconds * 1e3;
+  }
+  /**
+   * Fetches the media content from the signed URL over the network.
+   *
+   * Useful for local evaluators / image libraries, manual base64 conversion, or
+   * the Vercel AI SDK (`{ type: "image", image: await media.fetchBytes() }`).
+   *
+   * @returns The media content as raw bytes
+   * @throws {Error} If the download fails
+   */
+  async fetchBytes() {
+    const response = await fetch(this.url, { method: "GET", headers: {} });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch media ${this.mediaId}: HTTP ${response.status}`
+      );
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  /**
+   * Fetches the media over the network and returns raw base64 (no data URI prefix).
+   *
+   * Useful for Anthropic (`{ source: { type: "base64", media_type: media.contentType, data: await media.fetchBase64() } }`)
+   * or LangChain (`{ type: "image", base64: await media.fetchBase64(), mime_type: media.contentType }`).
+   *
+   * @returns The media content as a base64 string
+   * @throws {Error} If the download fails
+   */
+  async fetchBase64() {
+    return bytesToBase64(await this.fetchBytes());
+  }
+  /**
+   * Fetches the media over the network and returns a `data:<contentType>;base64,...` URI.
+   *
+   * Useful for OpenAI (`{ type: "input_image", image_url: await media.fetchDataUri() }`).
+   *
+   * @returns The media content as a base64 data URI
+   * @throws {Error} If the download fails
+   */
+  async fetchDataUri() {
+    return `data:${this.contentType};base64,${await this.fetchBase64()}`;
+  }
+};
+
+// src/mediaUpload.ts
+async function uploadMedia(params) {
+  var _a2;
+  const {
+    apiClient,
+    media,
+    traceId,
+    observationId,
+    datasetId,
+    datasetItemId,
+    field,
+    maxRetries = 3,
+    baseDelay = 1e3
+  } = params;
+  const logger = (_a2 = params.logger) != null ? _a2 : getGlobalLogger();
+  const contentSha256Hash = await media.getSha256Hash();
+  if (!media.contentLength || !media._contentType || !contentSha256Hash || !media._contentBytes) {
+    throw new Error("Cannot upload media: media content is incomplete.");
+  }
+  const { uploadUrl, mediaId } = await apiClient.media.getUploadUrl({
+    contentLength: media.contentLength,
+    traceId,
+    observationId,
+    datasetId,
+    datasetItemId,
+    field,
+    contentType: media._contentType,
+    sha256Hash: contentSha256Hash
+  });
+  if (!uploadUrl) {
+    logger.debug(
+      `Media status: Media with ID ${mediaId} already uploaded. Skipping duplicate upload.`
+    );
+    return;
+  }
+  const clientSideMediaId = await media.getId();
+  if (clientSideMediaId !== mediaId) {
+    throw new Error(
+      `Media integrity error: Media ID mismatch between SDK (${clientSideMediaId}) and Server (${mediaId}). Upload cancelled.`
+    );
+  }
+  logger.debug(`Uploading media ${mediaId}...`);
+  const startTime = Date.now();
+  const uploadResponse = await uploadWithBackoff({
+    uploadUrl,
+    contentBytes: media._contentBytes,
+    contentType: media._contentType,
+    contentSha256Hash,
+    maxRetries,
+    baseDelay
+  });
+  if (!uploadResponse) {
+    throw new Error("Media upload process failed");
+  }
+  const uploadSucceeded = uploadResponse.status === 200 || uploadResponse.status === 201;
+  await apiClient.media.patch(mediaId, {
+    uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    uploadHttpStatus: uploadResponse.status,
+    uploadHttpError: await uploadResponse.text(),
+    uploadTimeMs: Date.now() - startTime
+  });
+  logger.debug(`Media upload status reported for ${mediaId}`);
+  if (!uploadSucceeded) {
+    throw new Error(
+      `Media upload failed with HTTP ${uploadResponse.status} after ${maxRetries} retries.`
+    );
+  }
+}
+async function uploadWithBackoff(params) {
+  const {
+    uploadUrl,
+    contentType,
+    contentSha256Hash,
+    contentBytes,
+    maxRetries,
+    baseDelay
+  } = params;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      let parsedHostname;
+      try {
+        parsedHostname = new URL(uploadUrl).hostname;
+      } catch {
+        parsedHostname = "";
+      }
+      const isSelfHostedGcsBucket = parsedHostname === "storage.googleapis.com" || parsedHostname.endsWith(".storage.googleapis.com");
+      const headers = isSelfHostedGcsBucket ? { "Content-Type": contentType } : {
+        "Content-Type": contentType,
+        "x-amz-checksum-sha256": contentSha256Hash,
+        "x-ms-blob-type": "BlockBlob"
+      };
+      const uploadResponse = await fetch(uploadUrl, {
+        method: "PUT",
+        // Recent fetch typings narrow BodyInit to an ArrayBuffer-backed view,
+        // while Uint8Array now defaults to Uint8Array<ArrayBufferLike>. The
+        // media bytes are always ArrayBuffer-backed, so assert the narrower type.
+        body: contentBytes,
+        headers
+      });
+      if (attempt < maxRetries && uploadResponse.status !== 200 && uploadResponse.status !== 201) {
+        throw new Error(`Upload failed with status ${uploadResponse.status}`);
+      }
+      return uploadResponse;
+    } catch (e) {
+      if (attempt === maxRetries) {
+        throw e;
+      }
+      const delay = baseDelay * Math.pow(2, attempt);
+      const jitter = Math.random() * 1e3;
+      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+    }
+  }
+  return void 0;
+}
 
 // src/propagation.ts
 import {
@@ -15068,6 +15278,7 @@ export {
   CommentObjectType,
   CreateChatPromptType,
   CreateTextPromptType,
+  DatasetItemMediaReferenceField,
   DatasetStatus,
   Error2 as Error,
   LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
@@ -15079,6 +15290,7 @@ export {
   LangfuseAPIError,
   LangfuseAPITimeoutError,
   LangfuseMedia,
+  LangfuseMediaReference,
   LangfuseOtelContextKeys,
   LangfuseOtelSpanAttributes,
   LlmAdapter,
@@ -15145,6 +15357,7 @@ export {
   setLangfuseTraceIdInBaggage,
   trace_exports as trace,
   unstable_exports as unstable,
+  uploadMedia,
   utils_exports as utils
 };
 //# sourceMappingURL=index.mjs.map