@observyze/sdk 0.1.3 → 0.1.4

package/dist/index-IZdiaORv.d.mts

@@ -0,0 +1,477 @@
+import { SpanType, TokenUsage, Span as Span$1, TraceStatus, Trace as Trace$1 } from '@observyze/types';
+
+/**
+ * SDK Configuration and Types
+ */
+
+/**
+ * Configuration for Observyze SDK client
+ */
+interface ClientConfig {
+    /**
+     * API key for authentication with Observyze Ingestion Service
+     */
+    apiKey: string;
+    /**
+     * Endpoint URL for the Ingestion Service
+     * @default 'http://localhost:3001'
+     */
+    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;
+    /**
+     * Phase 5: Automatically scrub PII from trace output before network transmission
+     * @default true
+     */
+    enablePiiRedaction?: boolean;
+    /**
+     * Phase 4: Autonomous Circuit Breaker
+     * Hallucination score threshold (0-1) above which execution is blocked
+     * @default 0.8
+     */
+    hallucinationThreshold?: number;
+    /**
+     * Phase 4: Autonomous Circuit Breaker
+     * Safety score threshold (0-1) above which execution is blocked
+     * @default 0.9
+     */
+    safetyThreshold?: number;
+    /**
+     * Minimum confidence threshold for circuit breaker blocking (0-1).
+     * If confidence is below this threshold, high scores trigger alert-only instead of halt.
+     * @default 0.4
+     */
+    confidenceThreshold?: number;
+    /**
+     * Evaluation service URL for real-time guardrail checks
+     * In production, this should be https://api.observyze.com
+     * @default 'http://localhost:3000'
+     */
+    evalEndpoint?: string;
+    /**
+     * Enable circuit breaker - block execution on high hallucination/safety scores
+     * @default true
+     */
+    enableCircuitBreaker?: boolean;
+    /**
+     * Fail closed when evaluation service is unreachable.
+     * If true, guardrail checks will block execution on errors (safe default).
+     * If false, guardrail checks will allow execution on errors (fail open).
+     * @default true
+     */
+    failClosed?: boolean;
+    /**
+     * Automatically redirect LLM client (OpenAI, Anthropic) base URLs to Observyze proxy gateway
+     * to ensure Redis-backed circuit breakers are enforced.
+     * @default true
+     */
+    enableProxyRedirect?: boolean;
+}
+/**
+ * Internal configuration with defaults applied
+ */
+interface ResolvedClientConfig extends Required<ClientConfig> {
+}
+/**
+ * Result of a connection test.
+ * Verifies the SDK can reach Observyze and send a real trace end-to-end.
+ */
+interface TestConnectionResult {
+    /** Whether the test trace was accepted by Observyze */
+    ok: boolean;
+    /** The trace ID of the sent test trace (present when ok === true) */
+    traceId?: string;
+    /** HTTP status returned by the API (present when the request failed) */
+    status?: number;
+    /** Human-readable message with the outcome or the exact failure reason */
+    message: string;
+}
+/**
+ * Result of a guardrail evaluation check.
+ * score is null when evaluation could not be performed.
+ */
+interface GuardrailResult {
+    pass: boolean;
+    /** The hallucination score (0-1), or null if evaluation failed */
+    score: number | null;
+    /** Confidence in the evaluation score (0-1), null if unavailable */
+    confidence?: number | null;
+    /** The safety score (0-1), or null if evaluation failed */
+    safetyScore?: number | null;
+    /** Human-readable reason for the result */
+    reason?: string;
+    /** How the evaluation was performed */
+    evaluationSource?: 'live' | 'consensus' | 'nli_fast_path' | 'error' | 'disabled' | 'fallback';
+    /** Why a live evaluation didn't happen (only set when evaluationSource is 'error' or 'fallback') */
+    fallbackReason?: string;
+}
+
+/**
+ * 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'>;
+}
+
+/**
+ * Auto-Instrumentation API
+ * Provides nw.wrap() API for instrumenting LLM clients
+ */
+
+/**
+ * Supported client types for auto-instrumentation
+ */
+type SupportedClient = {
+    chat: {
+        completions: {
+            create: Function;
+        };
+    };
+} | {
+    messages: {
+        create: Function;
+    };
+};
+/**
+ * Detect the type of LLM client and apply appropriate instrumentation
+ */
+declare function wrap<T extends SupportedClient>(client: T, nwClient: ObservyzeClient): T;
+
+/**
+ * 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;
+    /**
+     * Parse a JSON API error response and extract trace_id, error code, and message.
+     * The api-gateway error handler includes these fields in every error response.
+     */
+    private static parseApiError;
+    /**
+     * Format an API error into a user-friendly message with trace_id for correlation.
+     * Example output:
+     *   "Observyze API error (401 [ref: err_a1b2c3d4]): MISSING_PROVIDER_KEY — No API key configured..."
+     */
+    private static formatApiError;
+    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 extends SupportedClient>(client: T): T;
+    /**
+     * Verify that the SDK can reach Observyze and send traces end-to-end.
+     *
+     * This is the definitive "is my integration working?" test for SDK users.
+     * It sends a real test trace through the EXACT same pipeline used by
+     * `flush()` / the wrapped LLM clients (same endpoint, apiKey, retry logic),
+     * so a successful call proves the whole chain works from your code:
+     *   - apiKey is valid and authorized
+     *   - endpoint is reachable from your environment
+     *   - organization / project resolution works
+     *   - the ingest pipeline accepts and stores traces
+     *
+     * @example
+     * ```typescript
+     * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
+     * const result = await nw.testConnection()
+     * // { ok: true, traceId: 'nw_xxx', message: 'Connection successful...' }
+     * ```
+     *
+     * The returned traceId can be searched in the Observyze dashboard (Traces →
+     * search the trace name "Observyze Connection Test") to confirm it landed.
+     */
+    testConnection(): Promise<TestConnectionResult>;
+    /**
+     * 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;
+    /**
+     * Phase 4: Autonomous Circuit Breakers (Requirement 4.1)
+     * Evaluate a trace or text for hallucination in real-time.
+     * If hallucination score > hallucinationThreshold, the SDK blocks execution.
+     *
+     * Returns GuardrailResult with score: null when evaluation couldn't be performed.
+     * In failClosed mode, null scores result in blocked execution.
+     * In failOpen mode, null scores allow execution through.
+     */
+    checkGuardrails(content: string | any): Promise<GuardrailResult>;
+    /**
+     * Phase 4: Autonomous Circuit Breakers
+     * Execute an agent action wrapped with the Circuit Breaker.
+     * Pauses execution if hallucination score >= hallucinationThreshold and requests human review.
+     * @throws Error when execution is blocked by circuit breaker
+     */
+    executeWithCircuitBreaker<T>(agentExecution: () => Promise<T>, traceContext?: any): Promise<T>;
+    /**
+     * Phase 4: Bug Bounty Protocol (Automated) (Requirement 4.2)
+     * Automatically shard persistent failure cases to external security researcher endpoints (e.g. HackerOne wrapper)
+     */
+    reportBugBounty(traceId: string, securityEndpoint: string, failureContext: any): Promise<void>;
+}
+
+/**
+ * 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 TestConnectionResult as T, type ObservyzeExporterConfig as a, ObservyzeSpanExporter as b, type SupportedClient as c, Trace as d, wrap as w };

package/dist/index-IZdiaORv.d.ts

@@ -0,0 +1,477 @@
+import { SpanType, TokenUsage, Span as Span$1, TraceStatus, Trace as Trace$1 } from '@observyze/types';
+
+/**
+ * SDK Configuration and Types
+ */
+
+/**
+ * Configuration for Observyze SDK client
+ */
+interface ClientConfig {
+    /**
+     * API key for authentication with Observyze Ingestion Service
+     */
+    apiKey: string;
+    /**
+     * Endpoint URL for the Ingestion Service
+     * @default 'http://localhost:3001'
+     */
+    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;
+    /**
+     * Phase 5: Automatically scrub PII from trace output before network transmission
+     * @default true
+     */
+    enablePiiRedaction?: boolean;
+    /**
+     * Phase 4: Autonomous Circuit Breaker
+     * Hallucination score threshold (0-1) above which execution is blocked
+     * @default 0.8
+     */
+    hallucinationThreshold?: number;
+    /**
+     * Phase 4: Autonomous Circuit Breaker
+     * Safety score threshold (0-1) above which execution is blocked
+     * @default 0.9
+     */
+    safetyThreshold?: number;
+    /**
+     * Minimum confidence threshold for circuit breaker blocking (0-1).
+     * If confidence is below this threshold, high scores trigger alert-only instead of halt.
+     * @default 0.4
+     */
+    confidenceThreshold?: number;
+    /**
+     * Evaluation service URL for real-time guardrail checks
+     * In production, this should be https://api.observyze.com
+     * @default 'http://localhost:3000'
+     */
+    evalEndpoint?: string;
+    /**
+     * Enable circuit breaker - block execution on high hallucination/safety scores
+     * @default true
+     */
+    enableCircuitBreaker?: boolean;
+    /**
+     * Fail closed when evaluation service is unreachable.
+     * If true, guardrail checks will block execution on errors (safe default).
+     * If false, guardrail checks will allow execution on errors (fail open).
+     * @default true
+     */
+    failClosed?: boolean;
+    /**
+     * Automatically redirect LLM client (OpenAI, Anthropic) base URLs to Observyze proxy gateway
+     * to ensure Redis-backed circuit breakers are enforced.
+     * @default true
+     */
+    enableProxyRedirect?: boolean;
+}
+/**
+ * Internal configuration with defaults applied
+ */
+interface ResolvedClientConfig extends Required<ClientConfig> {
+}
+/**
+ * Result of a connection test.
+ * Verifies the SDK can reach Observyze and send a real trace end-to-end.
+ */
+interface TestConnectionResult {
+    /** Whether the test trace was accepted by Observyze */
+    ok: boolean;
+    /** The trace ID of the sent test trace (present when ok === true) */
+    traceId?: string;
+    /** HTTP status returned by the API (present when the request failed) */
+    status?: number;
+    /** Human-readable message with the outcome or the exact failure reason */
+    message: string;
+}
+/**
+ * Result of a guardrail evaluation check.
+ * score is null when evaluation could not be performed.
+ */
+interface GuardrailResult {
+    pass: boolean;
+    /** The hallucination score (0-1), or null if evaluation failed */
+    score: number | null;
+    /** Confidence in the evaluation score (0-1), null if unavailable */
+    confidence?: number | null;
+    /** The safety score (0-1), or null if evaluation failed */
+    safetyScore?: number | null;
+    /** Human-readable reason for the result */
+    reason?: string;
+    /** How the evaluation was performed */
+    evaluationSource?: 'live' | 'consensus' | 'nli_fast_path' | 'error' | 'disabled' | 'fallback';
+    /** Why a live evaluation didn't happen (only set when evaluationSource is 'error' or 'fallback') */
+    fallbackReason?: string;
+}
+
+/**
+ * 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'>;
+}
+
+/**
+ * Auto-Instrumentation API
+ * Provides nw.wrap() API for instrumenting LLM clients
+ */
+
+/**
+ * Supported client types for auto-instrumentation
+ */
+type SupportedClient = {
+    chat: {
+        completions: {
+            create: Function;
+        };
+    };
+} | {
+    messages: {
+        create: Function;
+    };
+};
+/**
+ * Detect the type of LLM client and apply appropriate instrumentation
+ */
+declare function wrap<T extends SupportedClient>(client: T, nwClient: ObservyzeClient): T;
+
+/**
+ * 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;
+    /**
+     * Parse a JSON API error response and extract trace_id, error code, and message.
+     * The api-gateway error handler includes these fields in every error response.
+     */
+    private static parseApiError;
+    /**
+     * Format an API error into a user-friendly message with trace_id for correlation.
+     * Example output:
+     *   "Observyze API error (401 [ref: err_a1b2c3d4]): MISSING_PROVIDER_KEY — No API key configured..."
+     */
+    private static formatApiError;
+    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 extends SupportedClient>(client: T): T;
+    /**
+     * Verify that the SDK can reach Observyze and send traces end-to-end.
+     *
+     * This is the definitive "is my integration working?" test for SDK users.
+     * It sends a real test trace through the EXACT same pipeline used by
+     * `flush()` / the wrapped LLM clients (same endpoint, apiKey, retry logic),
+     * so a successful call proves the whole chain works from your code:
+     *   - apiKey is valid and authorized
+     *   - endpoint is reachable from your environment
+     *   - organization / project resolution works
+     *   - the ingest pipeline accepts and stores traces
+     *
+     * @example
+     * ```typescript
+     * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
+     * const result = await nw.testConnection()
+     * // { ok: true, traceId: 'nw_xxx', message: 'Connection successful...' }
+     * ```
+     *
+     * The returned traceId can be searched in the Observyze dashboard (Traces →
+     * search the trace name "Observyze Connection Test") to confirm it landed.
+     */
+    testConnection(): Promise<TestConnectionResult>;
+    /**
+     * 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;
+    /**
+     * Phase 4: Autonomous Circuit Breakers (Requirement 4.1)
+     * Evaluate a trace or text for hallucination in real-time.
+     * If hallucination score > hallucinationThreshold, the SDK blocks execution.
+     *
+     * Returns GuardrailResult with score: null when evaluation couldn't be performed.
+     * In failClosed mode, null scores result in blocked execution.
+     * In failOpen mode, null scores allow execution through.
+     */
+    checkGuardrails(content: string | any): Promise<GuardrailResult>;
+    /**
+     * Phase 4: Autonomous Circuit Breakers
+     * Execute an agent action wrapped with the Circuit Breaker.
+     * Pauses execution if hallucination score >= hallucinationThreshold and requests human review.
+     * @throws Error when execution is blocked by circuit breaker
+     */
+    executeWithCircuitBreaker<T>(agentExecution: () => Promise<T>, traceContext?: any): Promise<T>;
+    /**
+     * Phase 4: Bug Bounty Protocol (Automated) (Requirement 4.2)
+     * Automatically shard persistent failure cases to external security researcher endpoints (e.g. HackerOne wrapper)
+     */
+    reportBugBounty(traceId: string, securityEndpoint: string, failureContext: any): Promise<void>;
+}
+
+/**
+ * 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 TestConnectionResult as T, type ObservyzeExporterConfig as a, ObservyzeSpanExporter as b, type SupportedClient as c, Trace as d, wrap as w };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { O as ObservyzeClient } from './index--b41_E-1.mjs';
-export { C as ClientConfig, a as ObservyzeExporterConfig, b as ObservyzeSpanExporter, R as ResolvedClientConfig, S as Span, c as SupportedClient, T as Trace, w as wrap } from './index--b41_E-1.mjs';
+import { O as ObservyzeClient } from './index-IZdiaORv.mjs';
+export { C as ClientConfig, a as ObservyzeExporterConfig, b as ObservyzeSpanExporter, R as ResolvedClientConfig, S as Span, c as SupportedClient, T as TestConnectionResult, d as Trace, w as wrap } from './index-IZdiaORv.mjs';
 export { Span as SpanData, SpanError, SpanType, TokenUsage, Trace as TraceData, TraceStatus } from '@observyze/types';
 
 interface OpenAIClient {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as ObservyzeClient } from './index--b41_E-1.js';
-export { C as ClientConfig, a as ObservyzeExporterConfig, b as ObservyzeSpanExporter, R as ResolvedClientConfig, S as Span, c as SupportedClient, T as Trace, w as wrap } from './index--b41_E-1.js';
+import { O as ObservyzeClient } from './index-IZdiaORv.js';
+export { C as ClientConfig, a as ObservyzeExporterConfig, b as ObservyzeSpanExporter, R as ResolvedClientConfig, S as Span, c as SupportedClient, T as TestConnectionResult, d as Trace, w as wrap } from './index-IZdiaORv.js';
 export { Span as SpanData, SpanError, SpanType, TokenUsage, Trace as TraceData, TraceStatus } from '@observyze/types';
 
 interface OpenAIClient {

package/dist/index.js

@@ -804,6 +804,69 @@ var ObservyzeClient = class _ObservyzeClient {
   wrap(client) {
     return wrap(client, this);
   }
+  /**
+   * Verify that the SDK can reach Observyze and send traces end-to-end.
+   *
+   * This is the definitive "is my integration working?" test for SDK users.
+   * It sends a real test trace through the EXACT same pipeline used by
+   * `flush()` / the wrapped LLM clients (same endpoint, apiKey, retry logic),
+   * so a successful call proves the whole chain works from your code:
+   *   - apiKey is valid and authorized
+   *   - endpoint is reachable from your environment
+   *   - organization / project resolution works
+   *   - the ingest pipeline accepts and stores traces
+   *
+   * @example
+   * ```typescript
+   * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
+   * const result = await nw.testConnection()
+   * // { ok: true, traceId: 'nw_xxx', message: 'Connection successful...' }
+   * ```
+   *
+   * The returned traceId can be searched in the Observyze dashboard (Traces →
+   * search the trace name "Observyze Connection Test") to confirm it landed.
+   */
+  async testConnection() {
+    if (this.config.dryRun) {
+      return {
+        ok: false,
+        message: "Dry-run mode is enabled, so no trace was actually sent. Set dryRun: false to run a real connection test."
+      };
+    }
+    const trace = new Trace(
+      "Observyze Connection Test",
+      this.config.organizationId,
+      this.config.projectId
+    );
+    const span = trace.startSpan("connection-test", import_types.SpanType.LLM);
+    span.setInput({ prompt: "Observyze SDK connection test" });
+    span.setOutput({ response: "Connection successful" });
+    span.setTokens({ input: 5, output: 4, total: 9 });
+    span.setMetadata("source", "sdk-test-connection");
+    span.end();
+    trace.setMetadata("source", "sdk-test-connection");
+    trace.addTag("setup-test");
+    trace.end(import_types.TraceStatus.SUCCESS);
+    try {
+      await this.sendWithRetry([trace]);
+      return {
+        ok: true,
+        traceId: trace.id,
+        message: `Connection successful. Test trace ${trace.id} was sent to Observyze. Search for "Observyze Connection Test" in Dashboard \u2192 Traces to confirm it landed.`
+      };
+    } catch (error) {
+      const rawMessage = error?.message || String(error);
+      const statusMatch = rawMessage.match(/\((\d{3})/);
+      const isNetworkFailure = !statusMatch && /fetch|network|ENOTFOUND|ECONNREFUSED|ETIMEDOUT/i.test(rawMessage);
+      const defaultEndpoint = "http://localhost:3001";
+      const hint = isNetworkFailure && this.config.endpoint === defaultEndpoint ? ` You are using the default endpoint (${defaultEndpoint}). For production, set endpoint: "https://api.observyze.com" in the ObservyzeClient config, then re-run.` : isNetworkFailure ? " Check that your endpoint is reachable from this environment (firewalls, proxies, DNS) and that you are not using a local endpoint in production." : "";
+      return {
+        ok: false,
+        ...statusMatch ? { status: parseInt(statusMatch[1], 10) } : {},
+        message: rawMessage + hint
+      };
+    }
+  }
   /**
    * Sync local agent .history file to Observyze cloud
    * Parses JSON/NDJSON agent history and sends to ingestion endpoint.

package/dist/index.mjs

@@ -563,6 +563,69 @@ var ObservyzeClient = class _ObservyzeClient {
   wrap(client) {
     return wrap(client, this);
   }
+  /**
+   * Verify that the SDK can reach Observyze and send traces end-to-end.
+   *
+   * This is the definitive "is my integration working?" test for SDK users.
+   * It sends a real test trace through the EXACT same pipeline used by
+   * `flush()` / the wrapped LLM clients (same endpoint, apiKey, retry logic),
+   * so a successful call proves the whole chain works from your code:
+   *   - apiKey is valid and authorized
+   *   - endpoint is reachable from your environment
+   *   - organization / project resolution works
+   *   - the ingest pipeline accepts and stores traces
+   *
+   * @example
+   * ```typescript
+   * const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY })
+   * const result = await nw.testConnection()
+   * // { ok: true, traceId: 'nw_xxx', message: 'Connection successful...' }
+   * ```
+   *
+   * The returned traceId can be searched in the Observyze dashboard (Traces →
+   * search the trace name "Observyze Connection Test") to confirm it landed.
+   */
+  async testConnection() {
+    if (this.config.dryRun) {
+      return {
+        ok: false,
+        message: "Dry-run mode is enabled, so no trace was actually sent. Set dryRun: false to run a real connection test."
+      };
+    }
+    const trace = new Trace(
+      "Observyze Connection Test",
+      this.config.organizationId,
+      this.config.projectId
+    );
+    const span = trace.startSpan("connection-test", SpanType.LLM);
+    span.setInput({ prompt: "Observyze SDK connection test" });
+    span.setOutput({ response: "Connection successful" });
+    span.setTokens({ input: 5, output: 4, total: 9 });
+    span.setMetadata("source", "sdk-test-connection");
+    span.end();
+    trace.setMetadata("source", "sdk-test-connection");
+    trace.addTag("setup-test");
+    trace.end(TraceStatus.SUCCESS);
+    try {
+      await this.sendWithRetry([trace]);
+      return {
+        ok: true,
+        traceId: trace.id,
+        message: `Connection successful. Test trace ${trace.id} was sent to Observyze. Search for "Observyze Connection Test" in Dashboard \u2192 Traces to confirm it landed.`
+      };
+    } catch (error) {
+      const rawMessage = error?.message || String(error);
+      const statusMatch = rawMessage.match(/\((\d{3})/);
+      const isNetworkFailure = !statusMatch && /fetch|network|ENOTFOUND|ECONNREFUSED|ETIMEDOUT/i.test(rawMessage);
+      const defaultEndpoint = "http://localhost:3001";
+      const hint = isNetworkFailure && this.config.endpoint === defaultEndpoint ? ` You are using the default endpoint (${defaultEndpoint}). For production, set endpoint: "https://api.observyze.com" in the ObservyzeClient config, then re-run.` : isNetworkFailure ? " Check that your endpoint is reachable from this environment (firewalls, proxies, DNS) and that you are not using a local endpoint in production." : "";
+      return {
+        ok: false,
+        ...statusMatch ? { status: parseInt(statusMatch[1], 10) } : {},
+        message: rawMessage + hint
+      };
+    }
+  }
   /**
    * Sync local agent .history file to Observyze cloud
    * Parses JSON/NDJSON agent history and sends to ingestion endpoint.

package/dist/opentelemetry/index.d.mts

@@ -1,2 +1,2 @@
-export { a as ObservyzeExporterConfig, b as ObservyzeSpanExporter } from '../index--b41_E-1.mjs';
+export { a as ObservyzeExporterConfig, b as ObservyzeSpanExporter } from '../index-IZdiaORv.mjs';
 import '@observyze/types';

package/dist/opentelemetry/index.d.ts

@@ -1,2 +1,2 @@
-export { a as ObservyzeExporterConfig, b as ObservyzeSpanExporter } from '../index--b41_E-1.js';
+export { a as ObservyzeExporterConfig, b as ObservyzeSpanExporter } from '../index-IZdiaORv.js';
 import '@observyze/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@observyze/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Node.js SDK for Observyze AI Observability Platform",
   "files": [
     "dist"