@langfuse/core 4.0.0-alpha.0

package/dist/logger/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Enumeration of log levels in order of severity (lowest to highest).
+ */
+export declare enum LogLevel {
+    /** Critical errors that may cause application failure */
+    ERROR = 3,
+    /** Warning messages for potentially harmful situations */
+    WARN = 2,
+    /** General informational messages */
+    INFO = 1,
+    /** Detailed debug information for troubleshooting */
+    DEBUG = 0
+}
+/**
+ * Configuration options for the Logger.
+ */
+export interface LoggerConfig {
+    /** The minimum log level to output */
+    level: LogLevel;
+    /** Optional prefix to prepend to all log messages */
+    prefix?: string;
+    /** Whether to include timestamps in log messages (default: true) */
+    enableTimestamp?: boolean;
+}
+/**
+ * A configurable logger class that supports different log levels and formatting.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({ level: LogLevel.DEBUG, prefix: 'Langfuse SDK' });
+ * logger.info('Application started');
+ * logger.error('An error occurred', error);
+ * ```
+ */
+export declare class Logger {
+    private config;
+    /**
+     * Creates a new Logger instance.
+     *
+     * @param config - Configuration options for the logger
+     */
+    constructor(config?: LoggerConfig);
+    /**
+     * Determines if a message should be logged based on the current log level.
+     *
+     * @param level - The log level to check
+     * @returns True if the message should be logged, false otherwise
+     */
+    private shouldLog;
+    /**
+     * Formats a log message with timestamp, prefix, and log level.
+     *
+     * @param level - The log level string
+     * @param message - The message to format
+     * @returns The formatted message string
+     */
+    private formatMessage;
+    /**
+     * Logs an error message.
+     *
+     * @param message - The error message to log
+     * @param args - Additional arguments to pass to console.error
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a warning message.
+     *
+     * @param message - The warning message to log
+     * @param args - Additional arguments to pass to console.warn
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Logs an informational message.
+     *
+     * @param message - The info message to log
+     * @param args - Additional arguments to pass to console.info
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Logs a debug message.
+     *
+     * @param message - The debug message to log
+     * @param args - Additional arguments to pass to console.debug
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Sets the minimum log level.
+     *
+     * @param level - The new log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current log level.
+     *
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+}
+/**
+ * Singleton class that manages a global logger instance.
+ */
+declare class LoggerSingleton {
+    private static instance;
+    private static defaultConfig;
+    /**
+     * Gets the singleton logger instance, creating it if it doesn't exist.
+     *
+     * @returns The singleton logger instance
+     */
+    static getInstance(): Logger;
+    /**
+     * Configures the global logger with new settings.
+     * This will replace the existing logger instance.
+     *
+     * @param config - The new logger configuration
+     */
+    static configure(config: LoggerConfig): void;
+    /**
+     * Resets the singleton logger instance and configuration.
+     * Useful for testing or reinitializing the logger.
+     */
+    static reset(): void;
+}
+/**
+ * Creates a new Logger instance with the specified configuration.
+ * This is independent of the global singleton logger.
+ *
+ * @param config - Optional configuration for the logger
+ * @returns A new Logger instance
+ *
+ * @example
+ * ```typescript
+ * const customLogger = createLogger({ level: LogLevel.DEBUG, prefix: 'Custom' });
+ * customLogger.debug('This is a debug message');
+ * ```
+ */
+export declare const createLogger: (config?: LoggerConfig) => Logger;
+/**
+ * Gets the global singleton logger instance.
+ * If no logger exists, creates one with default configuration.
+ *
+ * @returns The global logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = getGlobalLogger();
+ * logger.info('Application started');
+ * ```
+ */
+export declare const getGlobalLogger: () => Logger;
+/**
+ * Configures the global logger with new settings.
+ * This should be called early in your application initialization.
+ *
+ * @param config - The logger configuration
+ *
+ * @example
+ * ```typescript
+ * configureGlobalLogger({
+ *   level: LogLevel.DEBUG,
+ *   prefix: 'Langfuse SDK',
+ *   enableTimestamp: true
+ * });
+ * ```
+ */
+export declare const configureGlobalLogger: (config: LoggerConfig) => void;
+/**
+ * Resets the global logger instance and configuration.
+ * Primarily used for testing to ensure clean state between tests.
+ *
+ * @example
+ * ```typescript
+ * // In test teardown
+ * resetGlobalLogger();
+ * ```
+ */
+export declare const resetGlobalLogger: () => void;
+/**
+ * The singleton logger instance for convenient access.
+ * Use this for quick access to the global logger.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@langfuse/core';
+ *
+ * logger.getInstance().info('Quick logging');
+ * ```
+ */
+export { LoggerSingleton as logger };
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,oBAAY,QAAQ;IAClB,yDAAyD;IACzD,KAAK,IAAI;IACT,0DAA0D;IAC1D,IAAI,IAAI;IACR,qCAAqC;IACrC,IAAI,IAAI;IACR,qDAAqD;IACrD,KAAK,IAAI;CACV;AAuBD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;OAIG;gBACS,MAAM,GAAE,YAAuC;IAO3D;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMhD;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMhD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;OAIG;IACH,QAAQ,IAAI,QAAQ;CAGrB;AAED;;GAEG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAuB;IAC9C,OAAO,CAAC,MAAM,CAAC,aAAa,CAE1B;IAEF;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM;IAO5B;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAK5C;;;OAGG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAIrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,YAAY,KAAG,MAEpD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,QAAO,MAElC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,YAAY,KAAG,IAE5D,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,QAAO,IAEpC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,OAAO,EAAE,eAAe,IAAI,MAAM,EAAE,CAAC"}

package/dist/logger/index.js

@@ -0,0 +1,254 @@
+var _a;
+import { getEnv } from "../utils.js";
+/**
+ * Enumeration of log levels in order of severity (lowest to highest).
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Critical errors that may cause application failure */
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    /** Warning messages for potentially harmful situations */
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    /** General informational messages */
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    /** Detailed debug information for troubleshooting */
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+})(LogLevel || (LogLevel = {}));
+function parseLogLevelFromEnv() {
+    if (typeof process === "object" && "env" in process) {
+        const envValue = getEnv("LANGFUSE_LOG_LEVEL");
+        const value = (envValue !== null && envValue !== void 0 ? envValue : "").toUpperCase();
+        switch (value) {
+            case "ERROR":
+                return LogLevel.ERROR;
+            case "WARN":
+                return LogLevel.WARN;
+            case "INFO":
+                return LogLevel.INFO;
+            case "DEBUG":
+                return LogLevel.DEBUG;
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * A configurable logger class that supports different log levels and formatting.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({ level: LogLevel.DEBUG, prefix: 'Langfuse SDK' });
+ * logger.info('Application started');
+ * logger.error('An error occurred', error);
+ * ```
+ */
+export class Logger {
+    /**
+     * Creates a new Logger instance.
+     *
+     * @param config - Configuration options for the logger
+     */
+    constructor(config = { level: LogLevel.INFO }) {
+        this.config = {
+            enableTimestamp: true,
+            ...config,
+        };
+    }
+    /**
+     * Determines if a message should be logged based on the current log level.
+     *
+     * @param level - The log level to check
+     * @returns True if the message should be logged, false otherwise
+     */
+    shouldLog(level) {
+        return level >= this.config.level;
+    }
+    /**
+     * Formats a log message with timestamp, prefix, and log level.
+     *
+     * @param level - The log level string
+     * @param message - The message to format
+     * @returns The formatted message string
+     */
+    formatMessage(level, message) {
+        const timestamp = this.config.enableTimestamp
+            ? new Date().toISOString()
+            : "";
+        const prefix = this.config.prefix || "[Langfuse SDK]";
+        const parts = [timestamp, prefix, `[${level}]`, message].filter(Boolean);
+        return parts.join(" ");
+    }
+    /**
+     * Logs an error message.
+     *
+     * @param message - The error message to log
+     * @param args - Additional arguments to pass to console.error
+     */
+    error(message, ...args) {
+        if (this.shouldLog(LogLevel.ERROR)) {
+            console.error(this.formatMessage("ERROR", message), ...args);
+        }
+    }
+    /**
+     * Logs a warning message.
+     *
+     * @param message - The warning message to log
+     * @param args - Additional arguments to pass to console.warn
+     */
+    warn(message, ...args) {
+        if (this.shouldLog(LogLevel.WARN)) {
+            console.warn(this.formatMessage("WARN", message), ...args);
+        }
+    }
+    /**
+     * Logs an informational message.
+     *
+     * @param message - The info message to log
+     * @param args - Additional arguments to pass to console.info
+     */
+    info(message, ...args) {
+        if (this.shouldLog(LogLevel.INFO)) {
+            console.info(this.formatMessage("INFO", message), ...args);
+        }
+    }
+    /**
+     * Logs a debug message.
+     *
+     * @param message - The debug message to log
+     * @param args - Additional arguments to pass to console.debug
+     */
+    debug(message, ...args) {
+        if (this.shouldLog(LogLevel.DEBUG)) {
+            console.debug(this.formatMessage("DEBUG", message), ...args);
+        }
+    }
+    /**
+     * Sets the minimum log level.
+     *
+     * @param level - The new log level
+     */
+    setLevel(level) {
+        this.config.level = level;
+    }
+    /**
+     * Gets the current log level.
+     *
+     * @returns The current log level
+     */
+    getLevel() {
+        return this.config.level;
+    }
+}
+/**
+ * Singleton class that manages a global logger instance.
+ */
+class LoggerSingleton {
+    /**
+     * Gets the singleton logger instance, creating it if it doesn't exist.
+     *
+     * @returns The singleton logger instance
+     */
+    static getInstance() {
+        if (!LoggerSingleton.instance) {
+            LoggerSingleton.instance = new Logger(LoggerSingleton.defaultConfig);
+        }
+        return LoggerSingleton.instance;
+    }
+    /**
+     * Configures the global logger with new settings.
+     * This will replace the existing logger instance.
+     *
+     * @param config - The new logger configuration
+     */
+    static configure(config) {
+        LoggerSingleton.defaultConfig = config;
+        LoggerSingleton.instance = new Logger(config);
+    }
+    /**
+     * Resets the singleton logger instance and configuration.
+     * Useful for testing or reinitializing the logger.
+     */
+    static reset() {
+        LoggerSingleton.instance = null;
+        LoggerSingleton.defaultConfig = { level: LogLevel.INFO };
+    }
+}
+LoggerSingleton.instance = null;
+LoggerSingleton.defaultConfig = {
+    level: (_a = parseLogLevelFromEnv()) !== null && _a !== void 0 ? _a : LogLevel.INFO,
+};
+/**
+ * Creates a new Logger instance with the specified configuration.
+ * This is independent of the global singleton logger.
+ *
+ * @param config - Optional configuration for the logger
+ * @returns A new Logger instance
+ *
+ * @example
+ * ```typescript
+ * const customLogger = createLogger({ level: LogLevel.DEBUG, prefix: 'Custom' });
+ * customLogger.debug('This is a debug message');
+ * ```
+ */
+export const createLogger = (config) => {
+    return new Logger(config);
+};
+/**
+ * Gets the global singleton logger instance.
+ * If no logger exists, creates one with default configuration.
+ *
+ * @returns The global logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = getGlobalLogger();
+ * logger.info('Application started');
+ * ```
+ */
+export const getGlobalLogger = () => {
+    return LoggerSingleton.getInstance();
+};
+/**
+ * Configures the global logger with new settings.
+ * This should be called early in your application initialization.
+ *
+ * @param config - The logger configuration
+ *
+ * @example
+ * ```typescript
+ * configureGlobalLogger({
+ *   level: LogLevel.DEBUG,
+ *   prefix: 'Langfuse SDK',
+ *   enableTimestamp: true
+ * });
+ * ```
+ */
+export const configureGlobalLogger = (config) => {
+    LoggerSingleton.configure(config);
+};
+/**
+ * Resets the global logger instance and configuration.
+ * Primarily used for testing to ensure clean state between tests.
+ *
+ * @example
+ * ```typescript
+ * // In test teardown
+ * resetGlobalLogger();
+ * ```
+ */
+export const resetGlobalLogger = () => {
+    LoggerSingleton.reset();
+};
+/**
+ * The singleton logger instance for convenient access.
+ * Use this for quick access to the global logger.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@langfuse/core';
+ *
+ * logger.getInstance().info('Quick logging');
+ * ```
+ */
+export { LoggerSingleton as logger };

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import { MediaContentType } from "./api/api/index.js";
+export type ParsedMediaReference = {
+    mediaId: string;
+    source: string;
+    contentType: MediaContentType;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,gBAAgB,CAAC;CAC/B,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+type LangfuseEnvVar = "LANGFUSE_PUBLIC_KEY" | "LANGFUSE_SECRET_KEY" | "LANGFUSE_BASE_URL" | "LANGFUSE_BASEURL" | "LANGFUSE_TIMEOUT" | "LANGFUSE_FLUSH_AT" | "LANGFUSE_FLUSH_INTERVAL" | "LANGFUSE_LOG_LEVEL" | "LANGFUSE_RELEASE" | "LANGFUSE_TRACING_ENVIRONMENT";
+export declare function getEnv(key: LangfuseEnvVar): string | undefined;
+export declare function generateUUID(globalThis?: any): string;
+export declare function safeSetTimeout(fn: () => void, timeout: number): any;
+export declare function uint8ArrayToBase64(arr: Uint8Array): string;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,GACf,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,GACnB,yBAAyB,GACzB,oBAAoB,GACpB,kBAAkB,GAClB,8BAA8B,CAAC;AAEnC,wBAAgB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQ9D;AAGD,wBAAgB,YAAY,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,MAAM,CAsBrD;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAQnE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAY1D"}

package/dist/utils.js

@@ -0,0 +1,52 @@
+export function getEnv(key) {
+    if (typeof process !== "undefined" && process.env[key]) {
+        return process.env[key];
+    }
+    else if (typeof globalThis !== "undefined") {
+        return globalThis[key];
+    }
+    return;
+}
+// https://stackoverflow.com/a/8809472
+export function generateUUID(globalThis) {
+    // Public Domain/MIT
+    let d = new Date().getTime(); //Timestamp
+    let d2 = (globalThis &&
+        globalThis.performance &&
+        globalThis.performance.now &&
+        globalThis.performance.now() * 1000) ||
+        0; //Time in microseconds since page-load or 0 if unsupported
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
+        let r = Math.random() * 16; //random number between 0 and 16
+        if (d > 0) {
+            //Use timestamp until depleted
+            r = (d + r) % 16 | 0;
+            d = Math.floor(d / 16);
+        }
+        else {
+            //Use microseconds since page-load if supported
+            r = (d2 + r) % 16 | 0;
+            d2 = Math.floor(d2 / 16);
+        }
+        return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+    });
+}
+export function safeSetTimeout(fn, timeout) {
+    const t = setTimeout(fn, timeout);
+    // We unref if available to prevent Node.js hanging on exit
+    if (t === null || t === void 0 ? void 0 : t.unref) {
+        t === null || t === void 0 ? void 0 : t.unref();
+    }
+    return t;
+}
+export function uint8ArrayToBase64(arr) {
+    // Try Buffer first (Node.js)
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(arr).toString("base64");
+    }
+    // Use btoa for browsers and edge runtimes
+    if (typeof btoa !== "undefined") {
+        return btoa(String.fromCharCode(...arr));
+    }
+    throw new Error("Base64 encoding not available");
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@langfuse/core",
+  "version": "4.0.0-alpha.0",
+  "description": "Core functions and utilities for Langfuse packages",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "author": "Langfuse",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "clean": "rm -rf dist"
+  }
+}