@observyze/sdk 0.1.0 → 0.1.2

package/dist/index-DEorAmFu.d.mts

@@ -0,0 +1,405 @@
+/**
+ * SDK Configuration and Types
+ */
+/**
+ * Type of span operation
+ */
+declare enum SpanType {
+    LLM = "llm",
+    TOOL = "tool",
+    AGENT = "agent",
+    CHAIN = "chain",
+    RETRIEVAL = "retrieval"
+}
+/**
+ * Status of trace execution
+ */
+declare enum TraceStatus {
+    SUCCESS = "success",
+    ERROR = "error",
+    TIMEOUT = "timeout",
+    RUNNING = "running"
+}
+/**
+ * Error information for a span
+ */
+interface SpanError {
+    message: string;
+    stack?: string;
+    code?: string;
+}
+/**
+ * Token usage information
+ */
+interface TokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    computed_pixels?: number;
+    audio_seconds?: number;
+}
+/**
+ * Individual operation within a trace
+ */
+interface Span$1 {
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    type: SpanType;
+    start_time: Date;
+    end_time: Date;
+    duration_ms: number;
+    input: any;
+    output: any;
+    error?: SpanError;
+    metadata: {
+        model?: string;
+        provider?: string;
+        temperature?: number;
+        max_tokens?: number;
+        [key: string]: any;
+    };
+    tokens?: TokenUsage;
+}
+/**
+ * Complete record of an AI workflow execution
+ */
+interface Trace$1 {
+    trace_id: string;
+    organization_id: string;
+    project_id?: string;
+    name: string;
+    status: TraceStatus;
+    start_time: Date;
+    end_time: Date;
+    duration_ms: number;
+    metadata: Record<string, any>;
+    spans: Span$1[];
+    tags: string[];
+    user_id?: string;
+    session_id?: string;
+    cost?: number;
+    cost_breakdown?: {
+        tokens: number;
+        pixels: number;
+        audio: number;
+    };
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Configuration for Observyze SDK client
+ */
+interface ClientConfig {
+    /**
+     * API key for authentication with Observyze Ingestion Service
+     */
+    apiKey: string;
+    /**
+     * Endpoint URL for the Ingestion Service
+     * @default 'https://api.observyze.com'
+     */
+    endpoint?: string;
+    /**
+     * Maximum number of traces to buffer before flushing
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Time in milliseconds to wait before auto-flushing buffered traces
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * Enable automatic instrumentation of popular LLM libraries
+     * @default true
+     */
+    enableAutoInstrumentation?: boolean;
+    /**
+     * Organization ID (optional, can be extracted from API key)
+     */
+    organizationId?: string;
+    /**
+     * Project ID for trace attribution
+     */
+    projectId?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Dry run mode - don't send traces to server (useful for testing)
+     * @default false
+     */
+    dryRun?: boolean;
+    /**
+     * Automatically scrub PII from trace output before network transmission
+     * @default true
+     */
+    enablePiiRedaction?: boolean;
+}
+/**
+ * Internal configuration with defaults applied
+ */
+interface ResolvedClientConfig extends Required<ClientConfig> {
+}
+
+/**
+ * Trace and Span classes for capturing AI workflow execution
+ */
+
+/**
+ * Represents an individual operation within a trace
+ */
+declare class Span {
+    private data;
+    private startTime;
+    constructor(name: string, type: SpanType, parentSpanId?: string);
+    /**
+     * Set the input data for this span
+     */
+    setInput(input: any): this;
+    /**
+     * Set the output data for this span
+     */
+    setOutput(output: any): this;
+    /**
+     * Record an error that occurred during span execution
+     */
+    setError(error: Error): this;
+    /**
+     * Set metadata for this span
+     */
+    setMetadata(key: string, value: any): this;
+    /**
+     * Set multiple metadata fields at once
+     */
+    setMetadataAll(metadata: Record<string, any>): this;
+    /**
+     * Set token usage information
+     */
+    setTokens(tokens: TokenUsage): this;
+    /**
+     * End the span and calculate duration
+     */
+    end(): void;
+    /**
+     * Get the span ID
+     */
+    get id(): string;
+    /**
+     * Get the span data for serialization
+     */
+    toJSON(): Span$1;
+}
+/**
+ * Represents a complete AI workflow execution
+ */
+declare class Trace {
+    private data;
+    private startTime;
+    private spans;
+    private ended;
+    constructor(name: string, organizationId: string, projectId?: string);
+    /**
+     * Start a new span within this trace
+     */
+    startSpan(name: string, type: SpanType, parentSpanId?: string): Span;
+    /**
+     * Add metadata to the trace
+     */
+    setMetadata(key: string, value: any): this;
+    /**
+     * Set multiple metadata fields at once
+     */
+    setMetadataAll(metadata: Record<string, any>): this;
+    /**
+     * Add tags to the trace
+     */
+    addTag(tag: string): this;
+    /**
+     * Add multiple tags at once
+     */
+    addTags(tags: string[]): this;
+    /**
+     * Set the user ID associated with this trace
+     */
+    setUserId(userId: string): this;
+    /**
+     * Set the session ID associated with this trace
+     */
+    setSessionId(sessionId: string): this;
+    /**
+     * End the trace with a final status
+     */
+    end(status?: TraceStatus): void;
+    /**
+     * Get the trace ID
+     */
+    get id(): string;
+    /**
+     * Check if the trace has ended
+     */
+    get isEnded(): boolean;
+    /**
+     * Get the trace data for serialization
+     */
+    toJSON(): Omit<Trace$1, '_id' | 'created_at' | 'updated_at'>;
+}
+
+/**
+ * Observyze SDK Client
+ * Main entry point for instrumenting AI applications
+ */
+
+/**
+ * Main SDK client for Observyze
+ */
+declare class ObservyzeClient {
+    private config;
+    private traceBuffer;
+    private flushTimer;
+    private isShuttingDown;
+    private readonly MAX_QUEUE_SIZE;
+    private readonly RETRY_DELAYS;
+    constructor(config: ClientConfig);
+    /**
+     * Start a new trace
+     */
+    startTrace(name: string, metadata?: Record<string, any>): Trace;
+    /**
+     * Buffer a completed trace for batch sending
+     */
+    private bufferTrace;
+    /**
+     * Start the auto-flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Flush all buffered traces to the Ingestion Service
+     */
+    flush(): Promise<void>;
+    /**
+     * Send traces with exponential backoff retry
+     */
+    private sendWithRetry;
+    /**
+     * Shutdown the SDK and flush remaining traces
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current buffer size
+     */
+    get bufferSize(): number;
+    /**
+     * Get SDK configuration
+     */
+    getConfig(): Readonly<ResolvedClientConfig>;
+    /**
+     * Wrap an LLM client (OpenAI, Anthropic) to enable auto-instrumentation
+     *
+     * @example
+     * ```typescript
+     * import OpenAI from 'openai'
+     * import { ObservyzeClient } from '@observyze/sdk'
+     *
+     * const nw = new ObservyzeClient({ apiKey: 'your-api-key' })
+     * const openai = new OpenAI({ apiKey: 'openai-key' })
+     *
+     * // Wrap the client to enable auto-instrumentation
+     * nw.wrap(openai)
+     *
+     * // All calls are now automatically traced
+     * const response = await openai.chat.completions.create({
+     *   model: 'gpt-4',
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * })
+     * ```
+     */
+    wrap<T>(client: T): T;
+    /**
+     * Sync local agent .history file to Observyze cloud
+     * Parses JSON/NDJSON agent history and sends to ingestion endpoint.
+     */
+    syncLocalHistory(filePath: string): Promise<void>;
+    /**
+     * Industry-grade PII Redaction (Compliance & RBAC)
+     *
+     * Recursively scrubs PII from trace data before transmission to the cloud.
+     * Coverage: emails, JWTs, bearer tokens, AWS/API keys, SSNs, credit cards,
+     * phone numbers (US + E.164), IPv4/IPv6, passport numbers, ZIP codes, plus
+     * key-based redaction for sensitive JSON fields (password, token, api_key, etc.).
+     *
+     * Design:
+     *  - Pure function, never mutates the original object
+     *  - Depth-limited to 16 levels to prevent stack overflow on deep agent outputs
+     *  - Key-aware: sensitive key names are fully redacted regardless of value format
+     */
+    private static readonly PII_PATTERNS;
+    private static readonly SENSITIVE_KEYS;
+    private static isSensitiveKey;
+    private sanitizePII;
+}
+
+/**
+ * Observyze OpenTelemetry Span Exporter
+ *
+ * Implements `@opentelemetry/sdk-trace-base`'s `SpanExporter` interface
+ * so users can use the standard OTel Node.js SDK and export spans to
+ * the Observyze platform.
+ *
+ * Usage:
+ * ```typescript
+ * import { ObservyzeClient } from '@observyze/sdk'
+ * import { ObservyzeSpanExporter } from '@observyze/sdk/opentelemetry'
+ * import { NodeSDK } from '@opentelemetry/sdk-node'
+ * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
+ *
+ * const nw = new ObservyzeClient({ apiKey: 'nw_...' })
+ *
+ * const sdk = new NodeSDK({
+ *   spanProcessor: new BatchSpanProcessor(
+ *     new ObservyzeSpanExporter(nw, { serviceName: 'my-app' })
+ *   )
+ * })
+ * sdk.start()
+ * ```
+ */
+
+/**
+ * Exporter configuration
+ */
+interface ObservyzeExporterConfig {
+    serviceName?: string;
+    projectId?: string;
+    defaultSpanType?: SpanType | 'llm' | 'tool' | 'agent' | 'chain' | 'retrieval';
+    headers?: Record<string, string>;
+}
+/**
+ * Observyze OpenTelemetry Span Exporter
+ */
+declare class ObservyzeSpanExporter {
+    private client;
+    private config;
+    constructor(client: ObservyzeClient, config?: ObservyzeExporterConfig);
+    /**
+     * Export spans — called by OTel SDK when spans are ready.
+     * Converts OTel spans to Observyze traces and buffers them.
+     */
+    export(spans: any[], resultCallback: (result: {
+        code: number;
+        error?: Error;
+    }) => void): Promise<void>;
+    /**
+     * Called when the exporter is shut down.
+     * Flushes any remaining buffered traces via the SDK client.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Called by the OTel SDK to force-export buffered spans.
+     */
+    forceFlush(): Promise<void>;
+}
+
+export { type ClientConfig as C, ObservyzeClient as O, type ResolvedClientConfig as R, Span as S, type TokenUsage as T, type ObservyzeExporterConfig as a, ObservyzeSpanExporter as b, type Span$1 as c, type SpanError as d, SpanType as e, Trace as f, type Trace$1 as g, TraceStatus as h };