@illuma-ai/observability-core 0.1.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,wCAAwC;AACxC,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IAC1B,mCAAe,CAAA;IACf,uCAAmB,CAAA;IACnB,uCAAmB,CAAA;IACnB,mCAAe,CAAA;AACjB,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,QAAQ;IACR,WAAW,EAAE,aAAa;IAC1B,WAAW,EAAE,aAAa;IAE1B,cAAc;IACd,iBAAiB,EAAE,mBAAmB;IACtC,iBAAiB,EAAE,mBAAmB;IAEtC,sCAAsC;IACtC,YAAY,EAAE,cAAc;IAE5B,SAAS;IACT,YAAY,EAAE,cAAc;IAE5B,eAAe;IACf,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared utility functions for the observability SDK.
+ *
+ * These helpers are intentionally dependency-free so they work in both
+ * Node.js and browser environments without polyfills.
+ */
+/**
+ * Generate a unique ID suitable for trace / observation / event identifiers.
+ *
+ * Prefers `crypto.randomUUID()` (available in Node 19+, modern browsers,
+ * and Cloudflare Workers). Falls back to a manual v4-style UUID built from
+ * `Math.random()` for older runtimes.
+ */
+export declare function generateId(): string;
+/**
+ * Returns the current time as an ISO-8601 string with millisecond precision.
+ */
+export declare function currentISOTimestamp(): string;
+/**
+ * Safely serialise any value to a JSON string.
+ *
+ * - Handles circular references by replacing them with `"[Circular]"`.
+ * - Catches any other `JSON.stringify` errors and returns a fallback string.
+ *
+ * @param value - The value to serialise.
+ * @param indent - Optional indentation for pretty-printing.
+ */
+export declare function safeStringify(value: unknown, indent?: number): string;
+/**
+ * Encode a public-key / secret-key pair into a Basic Authorization header value.
+ *
+ * Uses `btoa` in browsers and `Buffer` in Node.js.
+ *
+ * @param publicKey - The public API key (username).
+ * @param secretKey - The secret API key (password).
+ * @returns The full header value, e.g. `"Basic cHVibGljOnNlY3JldA=="`.
+ */
+export declare function encodeBasicAuth(publicKey: string, secretKey: string): string;
+/**
+ * Compute exponential backoff delay with jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @param baseMs - Base delay in milliseconds.
+ * @returns Delay in milliseconds.
+ */
+export declare function backoffDelay(attempt: number, baseMs?: number): number;
+/**
+ * Simple no-op logger that can be replaced by platform-specific implementations.
+ * Avoids direct console usage so the SDK stays silent by default.
+ */
+export declare const defaultLogger: {
+    debug: (..._args: unknown[]) => void;
+    info: (..._args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+//# 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;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAenC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAgB5E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,CAKnE;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa;sBACN,OAAO,EAAE,KAAG,IAAI;qBACjB,OAAO,EAAE,KAAG,IAAI;oBACjB,OAAO,EAAE,KAAG,IAAI;qBAKf,OAAO,EAAE,KAAG,IAAI;CAIlC,CAAC"}

package/dist/utils.js

@@ -0,0 +1,114 @@
+/**
+ * Shared utility functions for the observability SDK.
+ *
+ * These helpers are intentionally dependency-free so they work in both
+ * Node.js and browser environments without polyfills.
+ */
+/**
+ * Generate a unique ID suitable for trace / observation / event identifiers.
+ *
+ * Prefers `crypto.randomUUID()` (available in Node 19+, modern browsers,
+ * and Cloudflare Workers). Falls back to a manual v4-style UUID built from
+ * `Math.random()` for older runtimes.
+ */
+export function generateId() {
+    // crypto.randomUUID is available in Node >= 19, modern browsers, workers
+    if (typeof globalThis !== 'undefined' &&
+        typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    // Fallback: RFC-4122 v4 UUID from Math.random
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Returns the current time as an ISO-8601 string with millisecond precision.
+ */
+export function currentISOTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Safely serialise any value to a JSON string.
+ *
+ * - Handles circular references by replacing them with `"[Circular]"`.
+ * - Catches any other `JSON.stringify` errors and returns a fallback string.
+ *
+ * @param value - The value to serialise.
+ * @param indent - Optional indentation for pretty-printing.
+ */
+export function safeStringify(value, indent) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return '[Circular]';
+                }
+                seen.add(val);
+            }
+            // Convert BigInt to string since JSON.stringify can't handle it
+            if (typeof val === 'bigint') {
+                return val.toString();
+            }
+            return val;
+        }, indent);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Encode a public-key / secret-key pair into a Basic Authorization header value.
+ *
+ * Uses `btoa` in browsers and `Buffer` in Node.js.
+ *
+ * @param publicKey - The public API key (username).
+ * @param secretKey - The secret API key (password).
+ * @returns The full header value, e.g. `"Basic cHVibGljOnNlY3JldA=="`.
+ */
+export function encodeBasicAuth(publicKey, secretKey) {
+    const credentials = `${publicKey}:${secretKey}`;
+    // Node.js
+    if (typeof Buffer !== 'undefined') {
+        return `Basic ${Buffer.from(credentials).toString('base64')}`;
+    }
+    // Browser / Workers
+    if (typeof btoa === 'function') {
+        return `Basic ${btoa(credentials)}`;
+    }
+    throw new Error('No base64 encoder available. Ensure you are running in Node.js or a modern browser.');
+}
+/**
+ * Compute exponential backoff delay with jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @param baseMs - Base delay in milliseconds.
+ * @returns Delay in milliseconds.
+ */
+export function backoffDelay(attempt, baseMs = 1000) {
+    const exponential = baseMs * Math.pow(2, attempt);
+    // Add up to 25 % random jitter to avoid thundering herd
+    const jitter = exponential * 0.25 * Math.random();
+    return Math.min(exponential + jitter, 30_000); // cap at 30 s
+}
+/**
+ * Simple no-op logger that can be replaced by platform-specific implementations.
+ * Avoids direct console usage so the SDK stays silent by default.
+ */
+export const defaultLogger = {
+    debug: (..._args) => { },
+    info: (..._args) => { },
+    warn: (...args) => {
+        // Warnings are surfaced by default so users know about misconfiguration
+        // eslint-disable-next-line no-console
+        console.warn('[illuma-observability]', ...args);
+    },
+    error: (...args) => {
+        // eslint-disable-next-line no-console
+        console.error('[illuma-observability]', ...args);
+    },
+};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,yEAAyE;IACzE,IACE,OAAO,UAAU,KAAK,WAAW;QACjC,OAAO,UAAU,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,EACnD,CAAC;QACD,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;IACxC,CAAC;IAED,8CAA8C;IAC9C,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QACnE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,MAAe;IAC3D,MAAM,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;IAE3B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CACnB,KAAK,EACL,CAAC,IAAI,EAAE,GAAY,EAAE,EAAE;YACrB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBAC5C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBAClB,OAAO,YAAY,CAAC;gBACtB,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC;YACD,gEAAgE;YAChE,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;YACxB,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,SAAiB;IAClE,MAAM,WAAW,GAAG,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;IAEhD,UAAU;IACV,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,SAAS,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;IAChE,CAAC;IAED,oBAAoB;IACpB,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,SAAS,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;IACtC,CAAC;IAED,MAAM,IAAI,KAAK,CACb,qFAAqF,CACtF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,MAAM,GAAG,IAAI;IACzD,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClD,wDAAwD;IACxD,MAAM,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAClD,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;IACxC,IAAI,EAAE,CAAC,GAAG,KAAgB,EAAQ,EAAE,GAAE,CAAC;IACvC,IAAI,EAAE,CAAC,GAAG,IAAe,EAAQ,EAAE;QACjC,wEAAwE;QACxE,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,wBAAwB,EAAE,GAAG,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,EAAE,CAAC,GAAG,IAAe,EAAQ,EAAE;QAClC,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,GAAG,IAAI,CAAC,CAAC;IACnD,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@illuma-ai/observability-core",
+  "version": "0.1.0",
+  "description": "Core observability SDK - shared foundation for Node.js and browser clients",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "@types/node": "^20.14.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/illuma-ai/observability.git",
+    "directory": "packages/observability-core"
+  },
+  "license": "MIT",
+  "keywords": [
+    "llm",
+    "observability",
+    "tracing",
+    "langfuse",
+    "illuma",
+    "langchain",
+    "openai"
+  ]
+}