@illuma-ai/observability-core 0.1.0

package/dist/core-client.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Abstract base class for all observability clients.
+ *
+ * Platform-specific packages (Node.js, browser) extend this class and
+ * implement `fetchWithRetry` using the appropriate HTTP primitive.
+ *
+ * The core client owns:
+ * - Event batching and auto-flush logic
+ * - Auth header construction
+ * - Retry policy with exponential backoff
+ * - 207 Multi-Status response handling
+ */
+import type { ObservabilityClientConfig, TraceParams, ScoreParams, IngestionEvent, FetchOptions, FetchResponse } from './types.js';
+import { TraceClient } from './trace-client.js';
+export declare abstract class ObservabilityCoreClient {
+    protected readonly publicKey: string;
+    protected readonly secretKey: string;
+    protected readonly baseUrl: string;
+    protected readonly flushAt: number;
+    protected readonly flushInterval: number;
+    protected readonly maxRetries: number;
+    protected readonly enabled: boolean;
+    protected readonly release: string | undefined;
+    protected readonly requestTimeout: number;
+    /** Buffered events waiting to be flushed. */
+    private _queue;
+    /** Periodic flush timer handle (platform-agnostic — both Node and browser return a value). */
+    private _flushTimer;
+    /** Guards against concurrent flushes stomping the queue. */
+    private _flushInProgress;
+    /** Pre-computed authorization header. */
+    private readonly _authHeader;
+    /** Logger — can be overridden by subclasses for platform-specific logging. */
+    protected logger: {
+        debug: (..._args: unknown[]) => void;
+        info: (..._args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+    constructor(config: ObservabilityClientConfig);
+    /**
+     * Perform an HTTP fetch with retry logic.
+     *
+     * Subclasses implement this using their platform's HTTP client (e.g. `node:fetch`,
+     * `globalThis.fetch`, `undici`, etc.).
+     *
+     * @param url - Fully qualified URL to request.
+     * @param options - Method, headers, body, and optional AbortSignal.
+     * @returns A simplified response object.
+     */
+    protected abstract fetchWithRetry(url: string, options: FetchOptions): Promise<FetchResponse>;
+    /**
+     * Create (or upsert) a trace and return a handle for adding child observations.
+     *
+     * @param params - Trace parameters.
+     * @returns A TraceClient bound to this trace ID.
+     */
+    trace(params?: TraceParams): TraceClient;
+    /**
+     * Submit a standalone score (not attached via a TraceClient).
+     *
+     * @param params - Score parameters including the target traceId.
+     */
+    score(params: ScoreParams): void;
+    /**
+     * Add an event to the internal queue.
+     * Triggers an automatic flush when the queue reaches `flushAt`.
+     *
+     * @param event - The ingestion event to buffer.
+     */
+    enqueue(event: IngestionEvent): void;
+    /**
+     * Flush all buffered events to the server.
+     *
+     * Safe to call concurrently — only one flush runs at a time.
+     * Events queued during a flush are picked up on the next flush.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush remaining events and stop the periodic flush timer.
+     *
+     * Call this before process exit (Node.js) or page unload (browser) to
+     * ensure no events are lost.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Return the current event queue. Intended for testing.
+     */
+    getQueue(): ReadonlyArray<IngestionEvent>;
+    /**
+     * Send a batch of events to the ingestion endpoint with retry.
+     *
+     * Handles 207 Multi-Status responses by logging per-event errors.
+     */
+    private _sendBatch;
+    /**
+     * Platform-agnostic sleep helper.
+     */
+    private _sleep;
+}
+//# sourceMappingURL=core-client.d.ts.map

package/dist/core-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-client.d.ts","sourceRoot":"","sources":["../src/core-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,cAAc,EAGd,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0BhD,8BAAsB,uBAAuB;IAG3C,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACnC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACnC,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IACzC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IACpC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAI1C,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAwB;IAEtC,8FAA8F;IAC9F,OAAO,CAAC,WAAW,CAA+C;IAElE,4DAA4D;IAC5D,OAAO,CAAC,gBAAgB,CAAS;IAEjC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,8EAA8E;IAC9E,SAAS,CAAC,MAAM;;;;;MAAiB;gBAIrB,MAAM,EAAE,yBAAyB;IAkC7C;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,aAAa,CAAC;IAIzB;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW;IAyBxC;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAchC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAUpC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5B;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAU/B;;OAEG;IACH,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC;IAMzC;;;;OAIG;YACW,UAAU;IAsExB;;OAEG;IACH,OAAO,CAAC,MAAM;CAGf"}

package/dist/core-client.js

@@ -0,0 +1,253 @@
+/**
+ * Abstract base class for all observability clients.
+ *
+ * Platform-specific packages (Node.js, browser) extend this class and
+ * implement `fetchWithRetry` using the appropriate HTTP primitive.
+ *
+ * The core client owns:
+ * - Event batching and auto-flush logic
+ * - Auth header construction
+ * - Retry policy with exponential backoff
+ * - 207 Multi-Status response handling
+ */
+import { IngestionEventType } from './types.js';
+import { TraceClient } from './trace-client.js';
+import { generateId, currentISOTimestamp, encodeBasicAuth, backoffDelay, defaultLogger, safeStringify, } from './utils.js';
+// ---------------------------------------------------------------------------
+// Default configuration values
+// ---------------------------------------------------------------------------
+const DEFAULT_BASE_URL = 'http://localhost:3000';
+const DEFAULT_FLUSH_AT = 15;
+const DEFAULT_FLUSH_INTERVAL_MS = 10_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const SDK_NAME = '@illuma-ai/observability-core';
+const SDK_VERSION = '0.1.0';
+// ---------------------------------------------------------------------------
+// Abstract core client
+// ---------------------------------------------------------------------------
+export class ObservabilityCoreClient {
+    // -- Configuration --------------------------------------------------------
+    publicKey;
+    secretKey;
+    baseUrl;
+    flushAt;
+    flushInterval;
+    maxRetries;
+    enabled;
+    release;
+    requestTimeout;
+    // -- Internal state -------------------------------------------------------
+    /** Buffered events waiting to be flushed. */
+    _queue = [];
+    /** Periodic flush timer handle (platform-agnostic — both Node and browser return a value). */
+    _flushTimer = null;
+    /** Guards against concurrent flushes stomping the queue. */
+    _flushInProgress = false;
+    /** Pre-computed authorization header. */
+    _authHeader;
+    /** Logger — can be overridden by subclasses for platform-specific logging. */
+    logger = defaultLogger;
+    // -- Constructor ----------------------------------------------------------
+    constructor(config) {
+        if (!config.publicKey || !config.secretKey) {
+            throw new Error('ObservabilityCoreClient: publicKey and secretKey are required.');
+        }
+        this.publicKey = config.publicKey;
+        this.secretKey = config.secretKey;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.flushAt = config.flushAt ?? DEFAULT_FLUSH_AT;
+        this.flushInterval = config.flushInterval ?? DEFAULT_FLUSH_INTERVAL_MS;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.enabled = config.enabled ?? true;
+        this.release = config.release;
+        this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this._authHeader = encodeBasicAuth(this.publicKey, this.secretKey);
+        // Start periodic flush timer
+        if (this.enabled && this.flushInterval > 0) {
+            this._flushTimer = setInterval(() => {
+                void this.flush();
+            }, this.flushInterval);
+            // Allow Node.js to exit even if the timer is still alive
+            if (typeof this._flushTimer === 'object' && 'unref' in this._flushTimer) {
+                this._flushTimer.unref();
+            }
+        }
+    }
+    // -- Public API -----------------------------------------------------------
+    /**
+     * Create (or upsert) a trace and return a handle for adding child observations.
+     *
+     * @param params - Trace parameters.
+     * @returns A TraceClient bound to this trace ID.
+     */
+    trace(params) {
+        if (!this.enabled) {
+            // Return a no-op-safe client that still has the right shape
+            const traceId = params?.id ?? generateId();
+            return new TraceClient(traceId, () => { });
+        }
+        const traceId = params?.id ?? generateId();
+        const timestamp = params?.timestamp ?? currentISOTimestamp();
+        this.enqueue({
+            id: generateId(),
+            type: IngestionEventType.TRACE_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id: traceId,
+                timestamp,
+                ...(this.release && !params?.version ? { version: this.release } : {}),
+            },
+        });
+        return new TraceClient(traceId, (event) => this.enqueue(event));
+    }
+    /**
+     * Submit a standalone score (not attached via a TraceClient).
+     *
+     * @param params - Score parameters including the target traceId.
+     */
+    score(params) {
+        if (!this.enabled)
+            return;
+        this.enqueue({
+            id: generateId(),
+            type: IngestionEventType.SCORE_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: params.id ?? generateId(),
+                ...params,
+            },
+        });
+    }
+    /**
+     * Add an event to the internal queue.
+     * Triggers an automatic flush when the queue reaches `flushAt`.
+     *
+     * @param event - The ingestion event to buffer.
+     */
+    enqueue(event) {
+        if (!this.enabled)
+            return;
+        this._queue.push(event);
+        if (this._queue.length >= this.flushAt) {
+            void this.flush();
+        }
+    }
+    /**
+     * Flush all buffered events to the server.
+     *
+     * Safe to call concurrently — only one flush runs at a time.
+     * Events queued during a flush are picked up on the next flush.
+     */
+    async flush() {
+        if (!this.enabled)
+            return;
+        if (this._flushInProgress)
+            return;
+        if (this._queue.length === 0)
+            return;
+        this._flushInProgress = true;
+        // Snapshot and clear the queue atomically so new events go to a fresh array
+        const batch = this._queue;
+        this._queue = [];
+        try {
+            await this._sendBatch(batch);
+        }
+        catch (err) {
+            // Re-queue failed events so they can be retried on the next flush
+            this.logger.error('Flush failed, re-queuing events:', err);
+            this._queue = batch.concat(this._queue);
+        }
+        finally {
+            this._flushInProgress = false;
+        }
+    }
+    /**
+     * Flush remaining events and stop the periodic flush timer.
+     *
+     * Call this before process exit (Node.js) or page unload (browser) to
+     * ensure no events are lost.
+     */
+    async shutdown() {
+        if (this._flushTimer !== null) {
+            clearInterval(this._flushTimer);
+            this._flushTimer = null;
+        }
+        // Final flush
+        await this.flush();
+    }
+    /**
+     * Return the current event queue. Intended for testing.
+     */
+    getQueue() {
+        return this._queue;
+    }
+    // -- Internal -------------------------------------------------------------
+    /**
+     * Send a batch of events to the ingestion endpoint with retry.
+     *
+     * Handles 207 Multi-Status responses by logging per-event errors.
+     */
+    async _sendBatch(batch) {
+        const url = `${this.baseUrl}/api/public/ingestion`;
+        const requestBody = {
+            batch,
+            metadata: {
+                sdkName: SDK_NAME,
+                sdkVersion: SDK_VERSION,
+                publicKey: this.publicKey,
+            },
+        };
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const response = await this.fetchWithRetry(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: this._authHeader,
+                    },
+                    body: safeStringify(requestBody),
+                });
+                // 207 Multi-Status — some events may have failed individually
+                if (response.status === 207) {
+                    const result = (await response.json());
+                    if (result.errors && result.errors.length > 0) {
+                        this.logger.warn(`Ingestion batch partially failed: ${result.errors.length} error(s)`, result.errors);
+                    }
+                    return; // Batch accepted (even if some events had errors)
+                }
+                // 2xx — full success
+                if (response.ok) {
+                    return;
+                }
+                // 4xx client errors (except 429) — retrying won't help
+                if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                    const text = await response.text();
+                    this.logger.error(`Ingestion batch rejected (${response.status}): ${text}`);
+                    return; // Drop the batch — it won't succeed on retry
+                }
+                // 429 or 5xx — transient, will retry
+                lastError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+            }
+            // Wait before retrying (skip wait after last attempt)
+            if (attempt < this.maxRetries) {
+                const delay = backoffDelay(attempt);
+                await this._sleep(delay);
+            }
+        }
+        // All retries exhausted — throw so the caller can re-queue
+        throw lastError ?? new Error('Flush failed after retries');
+    }
+    /**
+     * Platform-agnostic sleep helper.
+     */
+    _sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=core-client.js.map

package/dist/core-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-client.js","sourceRoot":"","sources":["../src/core-client.ts"],"names":[],"mappings":"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"}

package/dist/generation-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Client handle for an LLM generation observation.
+ *
+ * Returned by `TraceClient.generation()` or `SpanClient.generation()`.
+ * Allows scoring, ending, and updating the generation after creation.
+ */
+import type { GenerationParams, IngestionEvent, ScoreParams } from './types.js';
+export declare class GenerationClient {
+    /** Observation ID of this generation. */
+    readonly id: string;
+    /** Trace this generation belongs to. */
+    readonly traceId: string;
+    /** Enqueueing callback provided by the owning core client. */
+    private readonly _enqueue;
+    constructor(id: string, traceId: string, enqueue: (event: IngestionEvent) => void);
+    /**
+     * Update this generation with additional data (e.g. output, usage, endTime).
+     *
+     * @param params - Fields to merge into the existing generation.
+     * @returns This GenerationClient for chaining.
+     */
+    update(params: Partial<GenerationParams>): this;
+    /**
+     * Convenience method to mark this generation as complete.
+     * Sets `endTime` to now and merges any additional params.
+     *
+     * @param params - Optional fields to set on completion (output, usage, etc.).
+     * @returns This GenerationClient for chaining.
+     */
+    end(params?: Partial<GenerationParams>): this;
+    /**
+     * Attach a score to this generation.
+     *
+     * @param params - Score parameters. `traceId` and `observationId` are set automatically.
+     */
+    score(params: Omit<ScoreParams, 'traceId' | 'observationId'>): void;
+}
+//# sourceMappingURL=generation-client.d.ts.map

package/dist/generation-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-client.d.ts","sourceRoot":"","sources":["../src/generation-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,qBAAa,gBAAgB;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAGzD,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI;IAO1C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAe/C;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAO7C;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,eAAe,CAAC,GAAG,IAAI;CAapE"}

package/dist/generation-client.js

@@ -0,0 +1,72 @@
+/**
+ * Client handle for an LLM generation observation.
+ *
+ * Returned by `TraceClient.generation()` or `SpanClient.generation()`.
+ * Allows scoring, ending, and updating the generation after creation.
+ */
+import { IngestionEventType } from './types.js';
+import { generateId, currentISOTimestamp } from './utils.js';
+export class GenerationClient {
+    /** Observation ID of this generation. */
+    id;
+    /** Trace this generation belongs to. */
+    traceId;
+    /** Enqueueing callback provided by the owning core client. */
+    _enqueue;
+    constructor(id, traceId, enqueue) {
+        this.id = id;
+        this.traceId = traceId;
+        this._enqueue = enqueue;
+    }
+    /**
+     * Update this generation with additional data (e.g. output, usage, endTime).
+     *
+     * @param params - Fields to merge into the existing generation.
+     * @returns This GenerationClient for chaining.
+     */
+    update(params) {
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.GENERATION_UPDATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: this.id,
+                traceId: this.traceId,
+                ...params,
+            },
+        });
+        return this;
+    }
+    /**
+     * Convenience method to mark this generation as complete.
+     * Sets `endTime` to now and merges any additional params.
+     *
+     * @param params - Optional fields to set on completion (output, usage, etc.).
+     * @returns This GenerationClient for chaining.
+     */
+    end(params) {
+        return this.update({
+            ...params,
+            endTime: params?.endTime ?? currentISOTimestamp(),
+        });
+    }
+    /**
+     * Attach a score to this generation.
+     *
+     * @param params - Score parameters. `traceId` and `observationId` are set automatically.
+     */
+    score(params) {
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.SCORE_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: params.id ?? generateId(),
+                traceId: this.traceId,
+                observationId: this.id,
+                ...params,
+            },
+        });
+    }
+}
+//# sourceMappingURL=generation-client.js.map

package/dist/generation-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-client.js","sourceRoot":"","sources":["../src/generation-client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,OAAO,gBAAgB;IAC3B,yCAAyC;IAChC,EAAE,CAAS;IAEpB,wCAAwC;IAC/B,OAAO,CAAS;IAEzB,8DAA8D;IAC7C,QAAQ,CAAkC;IAE3D,YACE,EAAU,EACV,OAAe,EACf,OAAwC;QAExC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAiC;QACtC,IAAI,CAAC,QAAQ,CAAC;YACZ,EAAE,EAAE,UAAU,EAAE;YAChB,IAAI,EAAE,kBAAkB,CAAC,iBAAiB;YAC1C,SAAS,EAAE,mBAAmB,EAAE;YAChC,IAAI,EAAE;gBACJ,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,MAAM;aAC4B;SACxC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAC,MAAkC;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,MAAM;YACT,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,mBAAmB,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAsD;QAC1D,IAAI,CAAC,QAAQ,CAAC;YACZ,EAAE,EAAE,UAAU,EAAE;YAChB,IAAI,EAAE,kBAAkB,CAAC,YAAY;YACrC,SAAS,EAAE,mBAAmB,EAAE;YAChC,IAAI,EAAE;gBACJ,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,UAAU,EAAE;gBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,aAAa,EAAE,IAAI,CAAC,EAAE;gBACtB,GAAG,MAAM;aAC4B;SACxC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @illuma-ai/observability-core
+ *
+ * Shared foundation for Node.js and browser observability clients.
+ * This package provides:
+ * - All TypeScript types and interfaces for the observability system
+ * - Abstract `ObservabilityCoreClient` base class with batching, auth, and retry
+ * - Trace / Span / Generation / Event client handles
+ * - Utility functions (ID generation, timestamps, serialization)
+ *
+ * Platform-specific packages (`@illuma-ai/observability-node`,
+ * `@illuma-ai/observability-web`) extend `ObservabilityCoreClient` and
+ * implement the abstract `fetchWithRetry` method.
+ */
+export { ObservationLevel, IngestionEventType, type ObservabilityClientConfig, type TraceParams, type GenerationParams, type SpanParams, type EventParams, type ScoreParams, type UsageParams, type UsageDetailsParams, type IngestionEvent, type IngestionBatchRequest, type IngestionBatchResponse, type IngestionEventResult, type FetchOptions, type FetchResponse, } from './types.js';
+export { ObservabilityCoreClient } from './core-client.js';
+export { TraceClient } from './trace-client.js';
+export { SpanClient } from './span-client.js';
+export { GenerationClient } from './generation-client.js';
+export { generateId, currentISOTimestamp, safeStringify, encodeBasicAuth, backoffDelay, defaultLogger, } from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @illuma-ai/observability-core
+ *
+ * Shared foundation for Node.js and browser observability clients.
+ * This package provides:
+ * - All TypeScript types and interfaces for the observability system
+ * - Abstract `ObservabilityCoreClient` base class with batching, auth, and retry
+ * - Trace / Span / Generation / Event client handles
+ * - Utility functions (ID generation, timestamps, serialization)
+ *
+ * Platform-specific packages (`@illuma-ai/observability-node`,
+ * `@illuma-ai/observability-web`) extend `ObservabilityCoreClient` and
+ * implement the abstract `fetchWithRetry` method.
+ */
+// Types & constants
+export { ObservationLevel, IngestionEventType, } from './types.js';
+// Abstract core client
+export { ObservabilityCoreClient } from './core-client.js';
+// Observation handle clients
+export { TraceClient } from './trace-client.js';
+export { SpanClient } from './span-client.js';
+export { GenerationClient } from './generation-client.js';
+// Utilities
+export { generateId, currentISOTimestamp, safeStringify, encodeBasicAuth, backoffDelay, defaultLogger, } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GAenB,MAAM,YAAY,CAAC;AAEpB,uBAAuB;AACvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,6BAA6B;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,YAAY;AACZ,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/span-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Client handle for a span observation.
+ *
+ * Returned by `TraceClient.span()` or another `SpanClient.span()`.
+ * Supports nested span and generation creation, enabling arbitrarily deep
+ * observation trees.
+ */
+import type { SpanParams, GenerationParams, EventParams, ScoreParams, IngestionEvent } from './types.js';
+import { GenerationClient } from './generation-client.js';
+export declare class SpanClient {
+    /** Observation ID of this span. */
+    readonly id: string;
+    /** Trace this span belongs to. */
+    readonly traceId: string;
+    /** Enqueueing callback provided by the owning core client. */
+    private readonly _enqueue;
+    constructor(id: string, traceId: string, enqueue: (event: IngestionEvent) => void);
+    /**
+     * Create a child span nested under this span.
+     *
+     * @param params - Span parameters. `traceId` and `parentObservationId` are set automatically.
+     * @returns A new SpanClient for the child span.
+     */
+    span(params?: Partial<SpanParams>): SpanClient;
+    /**
+     * Create an LLM generation observation nested under this span.
+     *
+     * @param params - Generation parameters. `traceId` and `parentObservationId` are set automatically.
+     * @returns A GenerationClient for the new generation.
+     */
+    generation(params?: Partial<GenerationParams>): GenerationClient;
+    /**
+     * Create a point-in-time event nested under this span.
+     *
+     * @param params - Event parameters. `traceId` and `parentObservationId` are set automatically.
+     */
+    event(params?: Partial<EventParams>): void;
+    /**
+     * Attach a score to this span.
+     *
+     * @param params - Score parameters. `traceId` and `observationId` are set automatically.
+     */
+    score(params: Omit<ScoreParams, 'traceId' | 'observationId'>): void;
+    /**
+     * Update this span with additional data.
+     *
+     * @param params - Fields to merge into the existing span.
+     * @returns This SpanClient for chaining.
+     */
+    update(params: Partial<SpanParams>): this;
+    /**
+     * Convenience method to mark this span as complete.
+     * Sets `endTime` to now and merges any additional params.
+     *
+     * @param params - Optional fields to set on completion (output, metadata, etc.).
+     * @returns This SpanClient for chaining.
+     */
+    end(params?: Partial<SpanParams>): this;
+}
+//# sourceMappingURL=span-client.d.ts.map

package/dist/span-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-client.d.ts","sourceRoot":"","sources":["../src/span-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,qBAAa,UAAU;IACrB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAGzD,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI;IAO1C;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU;IAoB9C;;;;;OAKG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB;IAoBhE;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAkB1C;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,eAAe,CAAC,GAAG,IAAI;IAcnE;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAezC;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;CAMxC"}