@juspay/neurolink 9.23.0 → 9.25.0

package/dist/observability/exporters/baseExporter.js

@@ -0,0 +1,190 @@
+/**
+ * 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);
+    }
+}

package/dist/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/observability/exporters/braintrustExporter.js

@@ -0,0 +1,154 @@
+/**
+ * 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,
+        };
+    }
+}

package/dist/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;
+}

package/dist/observability/exporters/datadogExporter.js

@@ -0,0 +1,196 @@
+/**
+ * Datadog Exporter
+ * Exports spans to Datadog APM platform
+ */
+import { logger } from "../../utils/logger.js";
+import { SpanStatus } from "../types/spanTypes.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Datadog exporter for enterprise APM integration
+ * Supports trace correlation and AI-specific custom metrics
+ */
+export class DatadogExporter extends BaseExporter {
+    apiKey;
+    appKey;
+    site;
+    service;
+    source;
+    logsEndpoint;
+    constructor(config) {
+        super("datadog", config);
+        this.apiKey = config.apiKey;
+        this.appKey = config.appKey;
+        this.site = config.site ?? "us1";
+        this.service = config.service ?? "neurolink";
+        this.source = config.source ?? "neurolink-ai";
+        const baseDomain = this.site === "us1" ? "datadoghq.com" : `${this.site}.datadoghq.com`;
+        this.logsEndpoint = `https://http-intake.logs.${baseDomain}/api/v2/logs`;
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Validate API key
+        try {
+            const validateUrl = this.site === "us1"
+                ? "https://api.datadoghq.com/api/v1/validate"
+                : `https://api.${this.site}.datadoghq.com/api/v1/validate`;
+            const response = await fetch(validateUrl, {
+                headers: {
+                    "DD-API-KEY": this.apiKey,
+                    ...(this.appKey && { "DD-APPLICATION-KEY": this.appKey }),
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`Datadog API key validation failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            // Allow initialization to proceed even if API is unreachable
+            logger.warn("[Datadog] Could not verify API connection:", error instanceof Error ? error.message : error);
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 10000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            const log = this.convertToDatadogLog(span);
+            const response = await fetch(this.logsEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "DD-API-KEY": this.apiKey,
+                },
+                body: JSON.stringify([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 logs = spans.map((s) => this.convertToDatadogLog(s));
+            const response = await fetch(this.logsEndpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "DD-API-KEY": this.apiKey,
+                },
+                body: JSON.stringify(logs),
+            });
+            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 Datadog API
+     */
+    async ping() {
+        const validateUrl = this.site === "us1"
+            ? "https://api.datadoghq.com/api/v1/validate"
+            : `https://api.${this.site}.datadoghq.com/api/v1/validate`;
+        const response = await fetch(validateUrl, {
+            headers: { "DD-API-KEY": this.apiKey },
+        });
+        if (!response.ok) {
+            throw new Error(`Datadog API validation failed: ${response.status}`);
+        }
+    }
+    /**
+     * Convert span to Datadog log format with trace correlation
+     */
+    convertToDatadogLog(span) {
+        return {
+            ddsource: this.source,
+            ddtags: this.buildTags(span),
+            hostname: process.env.HOSTNAME || "unknown",
+            message: `${span.type}: ${span.name}`,
+            service: this.service,
+            status: span.status === SpanStatus.ERROR ? "error" : "info",
+            timestamp: new Date(span.startTime).getTime(),
+            // Trace correlation
+            dd: {
+                trace_id: span.traceId,
+                span_id: span.spanId,
+            },
+            // AI-specific attributes
+            ai: {
+                provider: span.attributes["ai.provider"],
+                model: span.attributes["ai.model"],
+                tokens: {
+                    input: span.attributes["ai.tokens.input"],
+                    output: span.attributes["ai.tokens.output"],
+                    total: span.attributes["ai.tokens.total"],
+                },
+                cost: span.attributes["ai.cost.total"],
+                duration_ms: span.durationMs,
+            },
+            // User context
+            usr: {
+                id: span.attributes["user.id"],
+                session_id: span.attributes["session.id"],
+            },
+            // Error details
+            ...(span.status === SpanStatus.ERROR && {
+                error: {
+                    message: span.statusMessage,
+                    type: span.attributes["error.type"],
+                    stack: span.attributes["error.stack"],
+                },
+            }),
+        };
+    }
+    /**
+     * Build Datadog tags from span attributes
+     */
+    buildTags(span) {
+        const tags = [
+            `env:${this.config.environment ?? "production"}`,
+            `version:${this.config.version ?? "unknown"}`,
+            `span_type:${span.type}`,
+        ];
+        if (span.attributes["ai.provider"]) {
+            tags.push(`ai_provider:${span.attributes["ai.provider"]}`);
+        }
+        if (span.attributes["ai.model"]) {
+            tags.push(`ai_model:${span.attributes["ai.model"]}`);
+        }
+        if (span.attributes["tool.name"]) {
+            tags.push(`tool:${span.attributes["tool.name"]}`);
+        }
+        return tags.join(",");
+    }
+}

package/dist/observability/exporters/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Observability exporters exports
+ */
+export { ArizeExporter } from "./arizeExporter.js";
+export { BaseExporter, NoOpExporter } from "./baseExporter.js";
+export { BraintrustExporter } from "./braintrustExporter.js";
+export { DatadogExporter } from "./datadogExporter.js";
+export { LaminarExporter } from "./laminarExporter.js";
+export { LangfuseExporter } from "./langfuseExporter.js";
+export { LangSmithExporter } from "./langsmithExporter.js";
+export { OtelExporter } from "./otelExporter.js";
+export { PostHogExporter } from "./posthogExporter.js";
+export { SentryExporter } from "./sentryExporter.js";

package/dist/observability/exporters/index.js

@@ -0,0 +1,13 @@
+/**
+ * Observability exporters exports
+ */
+export { ArizeExporter } from "./arizeExporter.js";
+export { BaseExporter, NoOpExporter } from "./baseExporter.js";
+export { BraintrustExporter } from "./braintrustExporter.js";
+export { DatadogExporter } from "./datadogExporter.js";
+export { LaminarExporter } from "./laminarExporter.js";
+export { LangfuseExporter } from "./langfuseExporter.js";
+export { LangSmithExporter } from "./langsmithExporter.js";
+export { OtelExporter } from "./otelExporter.js";
+export { PostHogExporter } from "./posthogExporter.js";
+export { SentryExporter } from "./sentryExporter.js";

package/dist/observability/exporters/laminarExporter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Laminar Exporter
+ * Exports spans to Laminar LLM tracing platform
+ * @see https://docs.laminar.run/
+ */
+import type { ExporterHealthStatus, ExportResult, LaminarExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Laminar exporter for LLM pipeline tracing and monitoring
+ * Supports detailed traces with input/output tracking
+ */
+export declare class LaminarExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly projectApiKey?;
+    private readonly baseUrl;
+    constructor(config: LaminarExporterConfig);
+    initialize(): Promise<void>;
+    /**
+     * Get authorization headers
+     */
+    private getHeaders;
+    exportSpan(span: SpanData): Promise<ExportResult>;
+    exportBatch(spans: SpanData[]): Promise<ExportResult>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    healthCheck(): Promise<ExporterHealthStatus>;
+    /**
+     * Verify connectivity to Laminar API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to Laminar trace format
+     */
+    private convertToLaminarTrace;
+    /**
+     * Map NeuroLink span type to Laminar type
+     */
+    private mapSpanTypeToLaminarType;
+    /**
+     * Map span status to Laminar status format
+     */
+    private mapSpanStatus;
+    /**
+     * Extract additional metadata from span attributes
+     * Filters out standard attributes that are already handled
+     */
+    private extractMetadata;
+}