@langfuse/core 5.5.2 → 5.6.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   CommentObjectType: () => CommentObjectType,
   CreateChatPromptType: () => CreateChatPromptType,
   CreateTextPromptType: () => CreateTextPromptType,
+  DatasetItemMediaReferenceField: () => DatasetItemMediaReferenceField,
   DatasetStatus: () => DatasetStatus,
   Error: () => Error2,
   LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT: () => LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
@@ -45,6 +46,7 @@ __export(index_exports, {
   LangfuseAPIError: () => LangfuseAPIError,
   LangfuseAPITimeoutError: () => LangfuseAPITimeoutError,
   LangfuseMedia: () => LangfuseMedia,
+  LangfuseMediaReference: () => LangfuseMediaReference,
   LangfuseOtelContextKeys: () => LangfuseOtelContextKeys,
   LangfuseOtelSpanAttributes: () => LangfuseOtelSpanAttributes,
   LlmAdapter: () => LlmAdapter,
@@ -111,6 +113,7 @@ __export(index_exports, {
   setLangfuseTraceIdInBaggage: () => setLangfuseTraceIdInBaggage,
   trace: () => trace_exports,
   unstable: () => unstable_exports,
+  uploadMedia: () => uploadMedia,
   utils: () => utils_exports
 });
 module.exports = __toCommonJS(index_exports);
@@ -387,7 +390,7 @@ var resetGlobalLogger = () => {
 // package.json
 var package_default = {
   name: "@langfuse/core",
-  version: "5.5.2",
+  version: "5.6.0",
   description: "Core functions and utilities for Langfuse packages",
   type: "module",
   sideEffects: false,
@@ -573,6 +576,7 @@ var commons_exports = {};
 __export(commons_exports, {
   AccessDeniedError: () => AccessDeniedError,
   CommentObjectType: () => CommentObjectType,
+  DatasetItemMediaReferenceField: () => DatasetItemMediaReferenceField,
   DatasetStatus: () => DatasetStatus,
   Error: () => Error2,
   MethodNotAllowedError: () => MethodNotAllowedError,
@@ -586,6 +590,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",
@@ -6912,8 +6923,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",
@@ -12101,7 +12114,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.
@@ -12225,7 +12243,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.
@@ -14744,6 +14767,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
 var import_api = require("@opentelemetry/api");
@@ -15175,6 +15388,7 @@ function getSpanKeyFromBaggageKey(baggageKey) {
   CommentObjectType,
   CreateChatPromptType,
   CreateTextPromptType,
+  DatasetItemMediaReferenceField,
   DatasetStatus,
   Error,
   LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
@@ -15186,6 +15400,7 @@ function getSpanKeyFromBaggageKey(baggageKey) {
   LangfuseAPIError,
   LangfuseAPITimeoutError,
   LangfuseMedia,
+  LangfuseMediaReference,
   LangfuseOtelContextKeys,
   LangfuseOtelSpanAttributes,
   LlmAdapter,
@@ -15252,6 +15467,7 @@ function getSpanKeyFromBaggageKey(baggageKey) {
   setLangfuseTraceIdInBaggage,
   trace,
   unstable,
+  uploadMedia,
   utils
 });
 //# sourceMappingURL=index.cjs.map