@illuma-ai/observability-core 0.1.0

package/dist/span-client.js

@@ -0,0 +1,141 @@
+/**
+ * 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 { IngestionEventType } from './types.js';
+import { GenerationClient } from './generation-client.js';
+import { generateId, currentISOTimestamp } from './utils.js';
+export class SpanClient {
+    /** Observation ID of this span. */
+    id;
+    /** Trace this span 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;
+    }
+    /**
+     * 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) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.SPAN_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.traceId,
+                parentObservationId: this.id,
+                startTime,
+            },
+        });
+        return new SpanClient(id, this.traceId, this._enqueue);
+    }
+    /**
+     * 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) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.GENERATION_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.traceId,
+                parentObservationId: this.id,
+                startTime,
+            },
+        });
+        return new GenerationClient(id, this.traceId, this._enqueue);
+    }
+    /**
+     * Create a point-in-time event nested under this span.
+     *
+     * @param params - Event parameters. `traceId` and `parentObservationId` are set automatically.
+     */
+    event(params) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.EVENT_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.traceId,
+                parentObservationId: this.id,
+                startTime,
+            },
+        });
+    }
+    /**
+     * Attach a score to this span.
+     *
+     * @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,
+            },
+        });
+    }
+    /**
+     * Update this span with additional data.
+     *
+     * @param params - Fields to merge into the existing span.
+     * @returns This SpanClient for chaining.
+     */
+    update(params) {
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.SPAN_UPDATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: this.id,
+                traceId: this.traceId,
+                ...params,
+            },
+        });
+        return 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) {
+        return this.update({
+            ...params,
+            endTime: params?.endTime ?? currentISOTimestamp(),
+        });
+    }
+}
+//# sourceMappingURL=span-client.js.map

package/dist/span-client.js.map

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

package/dist/trace-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Client handle for a trace.
+ *
+ * Returned by `ObservabilityCoreClient.trace()`. Acts as the root of an
+ * observation tree — all spans, generations, events, and scores are created
+ * as children of a trace.
+ */
+import type { TraceParams, SpanParams, GenerationParams, EventParams, ScoreParams, IngestionEvent } from './types.js';
+import { SpanClient } from './span-client.js';
+import { GenerationClient } from './generation-client.js';
+export declare class TraceClient {
+    /** Trace ID. */
+    readonly id: string;
+    /** Enqueueing callback provided by the owning core client. */
+    private readonly _enqueue;
+    constructor(id: string, enqueue: (event: IngestionEvent) => void);
+    /**
+     * Create a span observation as a direct child of this trace.
+     *
+     * @param params - Span parameters. `traceId` is set automatically.
+     * @returns A SpanClient for the new span.
+     */
+    span(params?: Partial<SpanParams>): SpanClient;
+    /**
+     * Create an LLM generation observation as a direct child of this trace.
+     *
+     * @param params - Generation parameters. `traceId` is set automatically.
+     * @returns A GenerationClient for the new generation.
+     */
+    generation(params?: Partial<GenerationParams>): GenerationClient;
+    /**
+     * Create a point-in-time event as a direct child of this trace.
+     *
+     * @param params - Event parameters. `traceId` is set automatically.
+     */
+    event(params?: Partial<EventParams>): void;
+    /**
+     * Attach a score to this trace.
+     *
+     * @param params - Score parameters. `traceId` is set automatically.
+     */
+    score(params: Omit<ScoreParams, 'traceId'>): void;
+    /**
+     * Update this trace with additional data (e.g. output, metadata, tags).
+     *
+     * @param params - Fields to merge into the existing trace.
+     * @returns This TraceClient for chaining.
+     */
+    update(params: Partial<TraceParams>): this;
+}
+//# sourceMappingURL=trace-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace-client.d.ts","sourceRoot":"","sources":["../src/trace-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,qBAAa,WAAW;IACtB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI;IAKhE;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU;IAmB9C;;;;;OAKG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB;IAmBhE;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAiB1C;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,IAAI;IAajD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;CAa3C"}

package/dist/trace-client.js

@@ -0,0 +1,121 @@
+/**
+ * Client handle for a trace.
+ *
+ * Returned by `ObservabilityCoreClient.trace()`. Acts as the root of an
+ * observation tree — all spans, generations, events, and scores are created
+ * as children of a trace.
+ */
+import { IngestionEventType } from './types.js';
+import { SpanClient } from './span-client.js';
+import { GenerationClient } from './generation-client.js';
+import { generateId, currentISOTimestamp } from './utils.js';
+export class TraceClient {
+    /** Trace ID. */
+    id;
+    /** Enqueueing callback provided by the owning core client. */
+    _enqueue;
+    constructor(id, enqueue) {
+        this.id = id;
+        this._enqueue = enqueue;
+    }
+    /**
+     * Create a span observation as a direct child of this trace.
+     *
+     * @param params - Span parameters. `traceId` is set automatically.
+     * @returns A SpanClient for the new span.
+     */
+    span(params) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.SPAN_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.id,
+                startTime,
+            },
+        });
+        return new SpanClient(id, this.id, this._enqueue);
+    }
+    /**
+     * Create an LLM generation observation as a direct child of this trace.
+     *
+     * @param params - Generation parameters. `traceId` is set automatically.
+     * @returns A GenerationClient for the new generation.
+     */
+    generation(params) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.GENERATION_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.id,
+                startTime,
+            },
+        });
+        return new GenerationClient(id, this.id, this._enqueue);
+    }
+    /**
+     * Create a point-in-time event as a direct child of this trace.
+     *
+     * @param params - Event parameters. `traceId` is set automatically.
+     */
+    event(params) {
+        const id = params?.id ?? generateId();
+        const startTime = params?.startTime ?? currentISOTimestamp();
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.EVENT_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                ...params,
+                id,
+                traceId: this.id,
+                startTime,
+            },
+        });
+    }
+    /**
+     * Attach a score to this trace.
+     *
+     * @param params - Score parameters. `traceId` is set automatically.
+     */
+    score(params) {
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.SCORE_CREATE,
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: params.id ?? generateId(),
+                traceId: this.id,
+                ...params,
+            },
+        });
+    }
+    /**
+     * Update this trace with additional data (e.g. output, metadata, tags).
+     *
+     * @param params - Fields to merge into the existing trace.
+     * @returns This TraceClient for chaining.
+     */
+    update(params) {
+        this._enqueue({
+            id: generateId(),
+            type: IngestionEventType.TRACE_CREATE, // Langfuse uses trace-create for upserts
+            timestamp: currentISOTimestamp(),
+            body: {
+                id: this.id,
+                ...params,
+            },
+        });
+        return this;
+    }
+}
+//# sourceMappingURL=trace-client.js.map

package/dist/trace-client.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Core types for the Illuma Observability SDK.
+ *
+ * This module is the single source of truth for all observability types.
+ * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible.
+ */
+/** Observation severity / log level. */
+export declare enum ObservationLevel {
+    DEBUG = "DEBUG",
+    DEFAULT = "DEFAULT",
+    WARNING = "WARNING",
+    ERROR = "ERROR"
+}
+/**
+ * Ingestion event type constants.
+ * These match the Langfuse API exactly so the server can process them
+ * without any translation layer.
+ */
+export declare const IngestionEventType: {
+    readonly TRACE_CREATE: "trace-create";
+    readonly SPAN_CREATE: "span-create";
+    readonly SPAN_UPDATE: "span-update";
+    readonly GENERATION_CREATE: "generation-create";
+    readonly GENERATION_UPDATE: "generation-update";
+    readonly EVENT_CREATE: "event-create";
+    readonly SCORE_CREATE: "score-create";
+    readonly SDK_LOG: "sdk-log";
+};
+export type IngestionEventType = (typeof IngestionEventType)[keyof typeof IngestionEventType];
+/** Configuration accepted by all observability client constructors. */
+export interface ObservabilityClientConfig {
+    /** Public API key (used as the Basic-auth username). */
+    publicKey: string;
+    /** Secret API key (used as the Basic-auth password). */
+    secretKey: string;
+    /**
+     * Base URL of the observability server.
+     * @default "http://localhost:3000"
+     */
+    baseUrl?: string;
+    /**
+     * Number of events to buffer before auto-flushing.
+     * @default 15
+     */
+    flushAt?: number;
+    /**
+     * Interval in milliseconds between periodic flushes.
+     * @default 10000
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of retry attempts for failed network requests.
+     * Uses exponential backoff between retries.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * When false the SDK silently drops all events.
+     * Useful for disabling observability in certain environments.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Application release / version tag attached to every trace.
+     * Helps correlate traces with deployments.
+     */
+    release?: string;
+    /**
+     * Per-request timeout in milliseconds for flush HTTP calls.
+     * @default 10000
+     */
+    requestTimeout?: number;
+}
+/** Standard token / cost usage counters. */
+export interface UsageParams {
+    /** Number of input tokens. */
+    input?: number;
+    /** Number of output tokens. */
+    output?: number;
+    /** Total tokens (input + output). If omitted, computed from input + output. */
+    total?: number;
+    /** Unit label, e.g. "TOKENS", "CHARACTERS", "IMAGES". */
+    unit?: string;
+    /** Cost of the input in USD. */
+    inputCost?: number;
+    /** Cost of the output in USD. */
+    outputCost?: number;
+    /** Total cost in USD. */
+    totalCost?: number;
+}
+/**
+ * Flexible usage details for models with non-standard billing dimensions.
+ * Keys are dimension names, values are numeric counts.
+ *
+ * @example
+ * { "cachedTokens": 200, "audioTokens": 50 }
+ */
+export type UsageDetailsParams = Record<string, number>;
+/** Parameters for creating or updating a trace. */
+export interface TraceParams {
+    /** Client-generated trace ID. Auto-generated if omitted. */
+    id?: string;
+    /** Human-readable name for this trace. */
+    name?: string;
+    /** Identifies the end user. */
+    userId?: string;
+    /** Session grouping key. */
+    sessionId?: string;
+    /** The input payload (any serializable value). */
+    input?: unknown;
+    /** The output payload (any serializable value). */
+    output?: unknown;
+    /** Arbitrary key-value metadata. */
+    metadata?: Record<string, unknown>;
+    /** Tags for filtering and grouping. */
+    tags?: string[];
+    /** Whether this trace is publicly shareable. */
+    public?: boolean;
+    /** Application version / release override. */
+    version?: string;
+    /** ISO-8601 timestamp. Defaults to now. */
+    timestamp?: string;
+}
+/** Parameters for creating or updating an LLM generation observation. */
+export interface GenerationParams {
+    /** Client-generated observation ID. Auto-generated if omitted. */
+    id?: string;
+    /** Trace this generation belongs to (set automatically when created via TraceClient). */
+    traceId?: string;
+    /** Parent observation ID for nesting. */
+    parentObservationId?: string;
+    /** Human-readable name. */
+    name?: string;
+    /** ISO-8601 start timestamp. */
+    startTime?: string;
+    /** ISO-8601 completion timestamp. */
+    endTime?: string;
+    /** ISO-8601 time of first token received (streaming). */
+    completionStartTime?: string;
+    /** Model identifier, e.g. "gpt-4o", "claude-3-opus". */
+    model?: string;
+    /** Model parameters (temperature, max_tokens, etc.). */
+    modelParameters?: Record<string, unknown>;
+    /** Prompt / messages sent to the model. */
+    input?: unknown;
+    /** Model response. */
+    output?: unknown;
+    /** Token / cost usage. */
+    usage?: UsageParams;
+    /** Extended usage details for non-standard billing. */
+    usageDetails?: UsageDetailsParams;
+    /** Arbitrary metadata. */
+    metadata?: Record<string, unknown>;
+    /** Observation severity level. */
+    level?: ObservationLevel;
+    /** Status message (e.g. error description). */
+    statusMessage?: string;
+    /** Application version override. */
+    version?: string;
+    /** Reference to a prompt template ID managed in the UI. */
+    promptName?: string;
+    /** Version of the prompt template. */
+    promptVersion?: number;
+}
+/** Parameters for creating or updating a span observation. */
+export interface SpanParams {
+    /** Client-generated observation ID. Auto-generated if omitted. */
+    id?: string;
+    /** Trace this span belongs to (set automatically). */
+    traceId?: string;
+    /** Parent observation ID for nesting. */
+    parentObservationId?: string;
+    /** Human-readable name. */
+    name?: string;
+    /** ISO-8601 start timestamp. */
+    startTime?: string;
+    /** ISO-8601 end timestamp. */
+    endTime?: string;
+    /** Input payload. */
+    input?: unknown;
+    /** Output payload. */
+    output?: unknown;
+    /** Arbitrary metadata. */
+    metadata?: Record<string, unknown>;
+    /** Observation severity level. */
+    level?: ObservationLevel;
+    /** Status message. */
+    statusMessage?: string;
+    /** Application version override. */
+    version?: string;
+}
+/** Parameters for creating an event observation (no duration). */
+export interface EventParams {
+    /** Client-generated observation ID. Auto-generated if omitted. */
+    id?: string;
+    /** Trace this event belongs to (set automatically). */
+    traceId?: string;
+    /** Parent observation ID for nesting. */
+    parentObservationId?: string;
+    /** Human-readable name. */
+    name?: string;
+    /** ISO-8601 timestamp. */
+    startTime?: string;
+    /** Input payload. */
+    input?: unknown;
+    /** Output payload. */
+    output?: unknown;
+    /** Arbitrary metadata. */
+    metadata?: Record<string, unknown>;
+    /** Observation severity level. */
+    level?: ObservationLevel;
+    /** Status message. */
+    statusMessage?: string;
+    /** Application version override. */
+    version?: string;
+}
+/** Parameters for creating a score (evaluation metric). */
+export interface ScoreParams {
+    /** Client-generated score ID. Auto-generated if omitted. */
+    id?: string;
+    /** Trace to attach this score to. */
+    traceId: string;
+    /** Optional observation within the trace to score. */
+    observationId?: string;
+    /** Score name / metric key, e.g. "accuracy", "helpfulness". */
+    name: string;
+    /** Numeric score value. */
+    value: number;
+    /** Human-readable comment explaining the score. */
+    comment?: string;
+    /** Data type hint: "NUMERIC" or "BOOLEAN". */
+    dataType?: 'NUMERIC' | 'BOOLEAN';
+    /** Optional config ID for score definitions managed in the UI. */
+    configId?: string;
+}
+/** A single event in the ingestion batch. */
+export interface IngestionEvent {
+    /** Unique event ID for deduplication. */
+    id: string;
+    /** Discriminator — one of the IngestionEventType constants. */
+    type: IngestionEventType;
+    /** ISO-8601 timestamp of when this event was created on the client. */
+    timestamp: string;
+    /** Event-specific payload. Shape depends on `type`. */
+    body: Record<string, unknown>;
+    /** Metadata about the SDK that produced this event. */
+    metadata?: {
+        /** SDK name, e.g. "@illuma-ai/observability-node". */
+        sdkName?: string;
+        /** SDK version. */
+        sdkVersion?: string;
+        /** Public key (for server-side correlation). */
+        publicKey?: string;
+    };
+}
+/**
+ * Batch request body sent to `POST /api/public/ingestion`.
+ * Mirrors the Langfuse batch ingestion contract.
+ */
+export interface IngestionBatchRequest {
+    /** Array of ingestion events. */
+    batch: IngestionEvent[];
+    /** Optional metadata about the sending SDK. */
+    metadata?: {
+        sdkName?: string;
+        sdkVersion?: string;
+        publicKey?: string;
+    };
+}
+/** Per-event result within a 207 Multi-Status response. */
+export interface IngestionEventResult {
+    /** The event ID this result refers to. */
+    id: string;
+    /** HTTP status code for this individual event. */
+    status: number;
+    /** Error message if status is not 2xx. */
+    message?: string;
+}
+/** Response body from `POST /api/public/ingestion` (207 Multi-Status). */
+export interface IngestionBatchResponse {
+    /** Per-event success / failure results. */
+    successes: IngestionEventResult[];
+    errors: IngestionEventResult[];
+}
+/** Options for the abstract fetch method implemented by platform clients. */
+export interface FetchOptions {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+/** Simplified response shape returned by platform fetch implementations. */
+export interface FetchResponse {
+    status: number;
+    statusText: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+    ok: boolean;
+}
+//# 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":"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"}

package/dist/types.js

@@ -0,0 +1,39 @@
+/**
+ * Core types for the Illuma Observability SDK.
+ *
+ * This module is the single source of truth for all observability types.
+ * It mirrors the Langfuse ingestion API contract so payloads are wire-compatible.
+ */
+// ---------------------------------------------------------------------------
+// Enums & Constants
+// ---------------------------------------------------------------------------
+/** Observation severity / log level. */
+export var ObservationLevel;
+(function (ObservationLevel) {
+    ObservationLevel["DEBUG"] = "DEBUG";
+    ObservationLevel["DEFAULT"] = "DEFAULT";
+    ObservationLevel["WARNING"] = "WARNING";
+    ObservationLevel["ERROR"] = "ERROR";
+})(ObservationLevel || (ObservationLevel = {}));
+/**
+ * Ingestion event type constants.
+ * These match the Langfuse API exactly so the server can process them
+ * without any translation layer.
+ */
+export const IngestionEventType = {
+    // Traces
+    TRACE_CREATE: 'trace-create',
+    // Spans
+    SPAN_CREATE: 'span-create',
+    SPAN_UPDATE: 'span-update',
+    // Generations
+    GENERATION_CREATE: 'generation-create',
+    GENERATION_UPDATE: 'generation-update',
+    // Events (point-in-time observations)
+    EVENT_CREATE: 'event-create',
+    // Scores
+    SCORE_CREATE: 'score-create',
+    // SDK metadata
+    SDK_LOG: 'sdk-log',
+};
+//# sourceMappingURL=types.js.map