@juspay/neurolink 9.23.0 → 9.25.0

package/dist/lib/observability/exporters/arizeExporter.js

@@ -0,0 +1,139 @@
+/**
+ * Arize Exporter
+ * Exports spans to Arize ML monitoring platform
+ */
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Arize exporter for ML monitoring and prediction logs
+ * Supports feature tracking and model performance monitoring
+ */
+export class ArizeExporter extends BaseExporter {
+    spaceKey;
+    apiKey;
+    modelId;
+    modelVersion;
+    endpoint = "https://api.arize.com/v1";
+    constructor(config) {
+        super("arize", config);
+        this.spaceKey = config.spaceKey;
+        this.apiKey = config.apiKey;
+        this.modelId = config.modelId ?? "neurolink-ai";
+        this.modelVersion = config.modelVersion ?? "1.0.0";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 10000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const prediction = this.convertToArizePrediction(span);
+            const response = await fetch(`${this.endpoint}/log`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "space-key": this.spaceKey,
+                },
+                body: JSON.stringify(prediction),
+            });
+            if (!response.ok) {
+                throw new Error(`Export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async exportBatch(spans) {
+        // Arize's /v1/log endpoint does not support batch payloads, so we send
+        // individual requests in parallel. This is intentional — not a missed
+        // optimization.
+        const results = await Promise.all(spans.map((s) => this.exportSpan(s)));
+        const successful = results.filter((r) => r.success).length;
+        const failed = spans.length - successful;
+        return {
+            success: failed === 0,
+            exportedCount: successful,
+            failedCount: failed,
+            errors: results.flatMap((r) => r.errors ?? []),
+            durationMs: results.reduce((sum, r) => sum + r.durationMs, 0),
+        };
+    }
+    async flush() {
+        if (!this.initialized || this.buffer.length === 0) {
+            return;
+        }
+        const spans = [...this.buffer];
+        this.buffer = [];
+        await this.exportBatch(spans);
+    }
+    async shutdown() {
+        await this.flush();
+        this.stopFlushInterval();
+        this.initialized = false;
+    }
+    async healthCheck() {
+        try {
+            await this.withRetry(() => this.ping(), "health check");
+            return this.createHealthStatus(true);
+        }
+        catch {
+            return this.createHealthStatus(false, ["Health check failed"]);
+        }
+    }
+    /**
+     * Verify connectivity to Arize API
+     */
+    async ping() {
+        const response = await fetch(`${this.endpoint}/health`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "space-key": this.spaceKey,
+            },
+        });
+        if (!response.ok && response.status !== 404) {
+            // 404 is acceptable as health endpoint may not exist
+            throw new Error(`Arize API unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Arize prediction log format
+     */
+    convertToArizePrediction(span) {
+        return {
+            space_key: this.spaceKey,
+            model_id: span.attributes["ai.model"] ?? this.modelId,
+            model_version: this.modelVersion,
+            prediction_id: span.spanId,
+            prediction_timestamp: new Date(span.startTime).getTime(),
+            features: {
+                provider: span.attributes["ai.provider"],
+                temperature: span.attributes["ai.temperature"],
+                max_tokens: span.attributes["ai.max_tokens"],
+                user_id: span.attributes["user.id"],
+                session_id: span.attributes["session.id"],
+            },
+            prediction: {
+                input: span.attributes["input"],
+                output: span.attributes["output"],
+            },
+            tags: {
+                span_type: span.type,
+                environment: this.config.environment,
+            },
+            latency_ms: span.durationMs,
+            token_count: {
+                prompt: span.attributes["ai.tokens.input"],
+                completion: span.attributes["ai.tokens.output"],
+                total: span.attributes["ai.tokens.total"],
+            },
+        };
+    }
+}
+//# sourceMappingURL=arizeExporter.js.map

package/dist/lib/observability/exporters/baseExporter.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Abstract base class for all observability exporters
+ * Follows NeuroLink's factory pattern and Mastra's unified exporter interface
+ */
+import type { ExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../types/index.js";
+/**
+ * Abstract base class for all observability exporters
+ * Provides common functionality: buffering, flush intervals, health checks, retry logic
+ */
+export declare abstract class BaseExporter {
+    protected readonly name: string;
+    protected readonly config: ExporterConfig;
+    protected initialized: boolean;
+    protected buffer: SpanData[];
+    protected readonly maxBufferSize: number;
+    protected readonly retries: number;
+    protected flushInterval: ReturnType<typeof setInterval> | null;
+    protected lastExportTime: number;
+    constructor(name: string, config: ExporterConfig);
+    /**
+     * Initialize the exporter connection
+     * Must be called before exporting spans
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Export a single span
+     * @param span - The span data to export
+     */
+    abstract exportSpan(span: SpanData): Promise<ExportResult>;
+    /**
+     * Export multiple spans in batch
+     * @param spans - Array of span data to export
+     */
+    abstract exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    /**
+     * Flush all buffered spans
+     */
+    abstract flush(): Promise<void>;
+    /**
+     * Shutdown the exporter gracefully
+     * Should flush remaining spans before closing
+     */
+    abstract shutdown(): Promise<void>;
+    /**
+     * Check exporter health status
+     * Implementations should make an actual API call to verify connectivity
+     */
+    abstract healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Ping the exporter's backend to verify connectivity
+     * Override this in subclasses to provide backend-specific health check
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Buffer a span for batch export
+     * Triggers flush if buffer is full
+     */
+    protected bufferSpan(span: SpanData): void;
+    /**
+     * Start automatic flush interval
+     * @param intervalMs - Interval in milliseconds between flushes
+     */
+    protected startFlushInterval(intervalMs: number): void;
+    /**
+     * Stop the automatic flush interval
+     */
+    protected stopFlushInterval(): void;
+    /**
+     * Get exporter name
+     */
+    getName(): string;
+    /**
+     * Check if exporter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get number of pending spans in buffer
+     */
+    getPendingCount(): number;
+    /**
+     * Get last export timestamp
+     */
+    getLastExportTime(): number;
+    /**
+     * Create a standard export result for success
+     */
+    protected createSuccessResult(exportedCount: number, durationMs: number): ExportResult;
+    /**
+     * Create a standard export result for failure
+     */
+    protected createFailureResult(spanIds: string[], error: string, durationMs: number, retryable?: boolean): ExportResult;
+    /**
+     * Create a standard health status
+     */
+    protected createHealthStatus(healthy: boolean, errors?: string[]): ExporterHealthStatus;
+    /**
+     * Execute an operation with exponential backoff retry
+     * @param operation - The async operation to execute
+     * @param operationName - Name for logging purposes
+     * @returns The result of the operation
+     * @throws The last error if all retries fail
+     */
+    protected withRetry<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+}
+/**
+ * No-op exporter for when observability is disabled
+ * Provides zero-overhead behavior
+ */
+export declare class NoOpExporter extends BaseExporter {
+    constructor();
+    initialize(): Promise<void>;
+    exportSpan(_span: SpanData): Promise<ExportResult>;
+    exportBatch(_spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+}

package/dist/lib/observability/exporters/baseExporter.js

@@ -0,0 +1,191 @@
+/**
+ * Abstract base class for all observability exporters
+ * Follows NeuroLink's factory pattern and Mastra's unified exporter interface
+ */
+import { logger } from "../../utils/logger.js";
+/**
+ * Abstract base class for all observability exporters
+ * Provides common functionality: buffering, flush intervals, health checks, retry logic
+ */
+export class BaseExporter {
+    name;
+    config;
+    initialized = false;
+    buffer = [];
+    maxBufferSize;
+    retries;
+    flushInterval = null;
+    lastExportTime = 0;
+    constructor(name, config) {
+        this.name = name;
+        this.config = config;
+        this.maxBufferSize = config.maxBufferSize ?? 100;
+        this.retries = config.retries ?? 3;
+    }
+    /**
+     * Ping the exporter's backend to verify connectivity
+     * Override this in subclasses to provide backend-specific health check
+     */
+    async ping() {
+        // Default implementation does nothing
+        // Subclasses should override this to make an actual API call
+    }
+    /**
+     * Buffer a span for batch export
+     * Triggers flush if buffer is full
+     */
+    bufferSpan(span) {
+        this.buffer.push(span);
+        if (this.buffer.length >= this.maxBufferSize) {
+            // Use void to explicitly ignore the promise
+            void this.flush();
+        }
+    }
+    /**
+     * Start automatic flush interval
+     * @param intervalMs - Interval in milliseconds between flushes
+     */
+    startFlushInterval(intervalMs) {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+        }
+        this.flushInterval = setInterval(() => {
+            this.flush().catch((error) => {
+                logger.warn(`[${this.name}] Periodic flush failed`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }, intervalMs);
+    }
+    /**
+     * Stop the automatic flush interval
+     */
+    stopFlushInterval() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = null;
+        }
+    }
+    /**
+     * Get exporter name
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Check if exporter is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get number of pending spans in buffer
+     */
+    getPendingCount() {
+        return this.buffer.length;
+    }
+    /**
+     * Get last export timestamp
+     */
+    getLastExportTime() {
+        return this.lastExportTime;
+    }
+    /**
+     * Create a standard export result for success
+     */
+    createSuccessResult(exportedCount, durationMs) {
+        this.lastExportTime = Date.now();
+        return {
+            success: true,
+            exportedCount,
+            failedCount: 0,
+            durationMs,
+        };
+    }
+    /**
+     * Create a standard export result for failure
+     */
+    createFailureResult(spanIds, error, durationMs, retryable = true) {
+        return {
+            success: false,
+            exportedCount: 0,
+            failedCount: spanIds.length,
+            errors: spanIds.map((spanId) => ({
+                spanId,
+                error,
+                retryable,
+            })),
+            durationMs,
+        };
+    }
+    /**
+     * Create a standard health status
+     */
+    createHealthStatus(healthy, errors) {
+        return {
+            healthy,
+            name: this.name,
+            pendingSpans: this.buffer.length,
+            lastExportTime: this.lastExportTime || undefined,
+            errors,
+        };
+    }
+    /**
+     * Execute an operation with exponential backoff retry
+     * @param operation - The async operation to execute
+     * @param operationName - Name for logging purposes
+     * @returns The result of the operation
+     * @throws The last error if all retries fail
+     */
+    async withRetry(operation, operationName) {
+        const maxRetries = this.retries;
+        const baseDelay = 1000;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries) {
+                    const delay = baseDelay * 2 ** attempt;
+                    logger.warn(`[${this.name}] ${operationName} failed, retrying in ${delay}ms`, {
+                        attempt: attempt + 1,
+                        maxRetries,
+                        error: lastError.message,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    }
+}
+/**
+ * No-op exporter for when observability is disabled
+ * Provides zero-overhead behavior
+ */
+export class NoOpExporter extends BaseExporter {
+    constructor() {
+        super("noop", { enabled: false });
+    }
+    async initialize() {
+        this.initialized = true;
+    }
+    async exportSpan(_span) {
+        return this.createSuccessResult(0, 0);
+    }
+    async exportBatch(_spans) {
+        return this.createSuccessResult(0, 0);
+    }
+    async flush() {
+        // No-op
+    }
+    async shutdown() {
+        this.initialized = false;
+    }
+    async healthCheck() {
+        return this.createHealthStatus(true);
+    }
+}
+//# sourceMappingURL=baseExporter.js.map

package/dist/lib/observability/exporters/braintrustExporter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Braintrust Exporter
+ * Exports spans to Braintrust AI evaluation platform
+ */
+import type { BraintrustExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Braintrust exporter for AI evaluation and scoring
+ * Supports project logs and evaluation metrics
+ */
+export declare class BraintrustExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly projectName;
+    private readonly endpoint;
+    constructor(config: BraintrustExporterConfig);
+    initialize(): Promise<void>;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Braintrust API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to Braintrust log format
+     */
+    private convertToBraintrustLog;
+}

package/dist/lib/observability/exporters/braintrustExporter.js

@@ -0,0 +1,155 @@
+/**
+ * Braintrust Exporter
+ * Exports spans to Braintrust AI evaluation platform
+ */
+import { logger } from "../../utils/logger.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Braintrust exporter for AI evaluation and scoring
+ * Supports project logs and evaluation metrics
+ */
+export class BraintrustExporter extends BaseExporter {
+    apiKey;
+    projectName;
+    endpoint;
+    constructor(config) {
+        super("braintrust", config);
+        this.apiKey = config.apiKey;
+        this.projectName = config.projectName;
+        this.endpoint = config.endpoint ?? "https://api.braintrust.dev";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Verify API key
+        try {
+            const response = await fetch(`${this.endpoint}/v1/project`, {
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+            });
+            if (!response.ok) {
+                throw new Error(`Braintrust initialization failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            logger.warn("[Braintrust] Could not verify API connection:", error instanceof Error ? error.message : error);
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 5000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const log = this.convertToBraintrustLog(span);
+            const response = await fetch(`${this.endpoint}/v1/project_logs/${this.projectName}/insert`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ events: [log] }),
+            });
+            if (!response.ok) {
+                throw new Error(`Export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(1, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult([span.spanId], error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async exportBatch(spans) {
+        const startTime = Date.now();
+        try {
+            const events = spans.map((s) => this.convertToBraintrustLog(s));
+            const response = await fetch(`${this.endpoint}/v1/project_logs/${this.projectName}/insert`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ events }),
+            });
+            if (!response.ok) {
+                throw new Error(`Batch export failed: ${response.statusText}`);
+            }
+            return this.createSuccessResult(spans.length, Date.now() - startTime);
+        }
+        catch (error) {
+            return this.createFailureResult(spans.map((s) => s.spanId), error instanceof Error ? error.message : String(error), Date.now() - startTime);
+        }
+    }
+    async flush() {
+        if (this.buffer.length > 0) {
+            const spans = [...this.buffer];
+            this.buffer = [];
+            await this.exportBatch(spans);
+        }
+    }
+    async shutdown() {
+        await this.flush();
+        this.stopFlushInterval();
+        this.initialized = false;
+    }
+    async healthCheck() {
+        try {
+            await this.withRetry(() => this.ping(), "health check");
+            return this.createHealthStatus(true);
+        }
+        catch {
+            return this.createHealthStatus(false, ["Health check failed"]);
+        }
+    }
+    /**
+     * Verify connectivity to Braintrust API
+     */
+    async ping() {
+        const response = await fetch(`${this.endpoint}/v1/project`, {
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+        });
+        if (!response.ok) {
+            throw new Error(`Braintrust API unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Braintrust log format
+     */
+    convertToBraintrustLog(span) {
+        return {
+            project_name: this.projectName,
+            id: span.spanId,
+            span_id: span.spanId,
+            root_span_id: span.parentSpanId ? undefined : span.spanId,
+            span_parents: span.parentSpanId ? [span.parentSpanId] : [],
+            input: span.attributes["input"],
+            output: span.attributes["output"],
+            expected: span.attributes["expected"],
+            scores: span.attributes["scores"],
+            metadata: {
+                // Pick only safe, non-PII attributes for metadata (avoid leaking input/output)
+                ...(span.attributes["ai.provider"] !== undefined && {
+                    "ai.provider": span.attributes["ai.provider"],
+                }),
+                ...(span.attributes["ai.model"] !== undefined && {
+                    "ai.model": span.attributes["ai.model"],
+                }),
+                // Explicit fields placed after spread so they always win
+                provider: span.attributes["ai.provider"],
+                model: span.attributes["ai.model"],
+                type: span.type,
+                status: span.status,
+                statusMessage: span.statusMessage,
+            },
+            metrics: {
+                tokens: span.attributes["ai.tokens.total"],
+                prompt_tokens: span.attributes["ai.tokens.input"],
+                completion_tokens: span.attributes["ai.tokens.output"],
+                cost: span.attributes["ai.cost.total"],
+                duration_ms: span.durationMs,
+            },
+            created: span.startTime,
+            end_time: span.endTime,
+        };
+    }
+}
+//# sourceMappingURL=braintrustExporter.js.map

package/dist/lib/observability/exporters/datadogExporter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Datadog Exporter
+ * Exports spans to Datadog APM platform
+ */
+import type { DatadogExporterConfig, ExporterHealthStatus, ExportResult, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Datadog exporter for enterprise APM integration
+ * Supports trace correlation and AI-specific custom metrics
+ */
+export declare class DatadogExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly appKey?;
+    private readonly site;
+    private readonly service;
+    private readonly source;
+    private readonly logsEndpoint;
+    constructor(config: DatadogExporterConfig);
+    initialize(): Promise<void>;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Datadog API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to Datadog log format with trace correlation
+     */
+    private convertToDatadogLog;
+    /**
+     * Build Datadog tags from span attributes
+     */
+    private buildTags;
+}