@juspay/neurolink 9.24.0 → 9.25.1

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

@@ -0,0 +1,204 @@
+/**
+ * Langfuse Exporter
+ * Exports spans to Langfuse observability platform
+ */
+import { SpanType } from "../types/spanTypes.js";
+import { SpanSerializer } from "../utils/spanSerializer.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * Langfuse exporter for LLM observability
+ * Supports traces, generations, spans, and scores
+ */
+export class LangfuseExporter extends BaseExporter {
+    publicKey;
+    secretKey;
+    baseUrl;
+    release;
+    constructor(config) {
+        super("langfuse", config);
+        this.publicKey = config.publicKey;
+        this.secretKey = config.secretKey;
+        this.baseUrl = config.baseUrl ?? "https://cloud.langfuse.com";
+        this.release = config.release;
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Verify credentials with a simple check
+        if (!this.publicKey || !this.secretKey) {
+            throw new Error("Langfuse publicKey and secretKey are required");
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 5000);
+    }
+    async exportSpan(span) {
+        const startTime = Date.now();
+        try {
+            // Create trace if this is a root span
+            if (!span.parentSpanId) {
+                await this.createTrace(span);
+            }
+            // Create span/generation based on type
+            if (span.type === SpanType.MODEL_GENERATION) {
+                await this.createGeneration(span);
+            }
+            else {
+                await this.createSpan(span);
+            }
+            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();
+        const results = await Promise.allSettled(spans.map((s) => this.exportSpan(s)));
+        const successful = results.filter((r) => r.status === "fulfilled" && r.value.success).length;
+        const failed = spans.length - successful;
+        return {
+            success: failed === 0,
+            exportedCount: successful,
+            failedCount: failed,
+            errors: results
+                .filter((r) => r.status === "rejected" ||
+                (r.status === "fulfilled" && !r.value.success))
+                .map((r, i) => ({
+                spanId: spans[i].spanId,
+                error: r.status === "rejected" ? String(r.reason) : "Export failed",
+                retryable: true,
+            })),
+            durationMs: 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 Langfuse API
+     */
+    async ping() {
+        const credentials = Buffer.from(`${this.publicKey}:${this.secretKey}`).toString("base64");
+        const response = await fetch(`${this.baseUrl}/api/public/health`, {
+            method: "GET",
+            headers: {
+                Authorization: `Basic ${credentials}`,
+            },
+        });
+        if (!response.ok && response.status !== 404) {
+            // 404 is acceptable as health endpoint may not exist
+            throw new Error(`Langfuse API unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Create a Langfuse trace
+     */
+    async createTrace(span) {
+        const body = {
+            id: span.traceId,
+            name: span.name,
+            userId: span.attributes["user.id"],
+            sessionId: span.attributes["session.id"],
+            // Only pick safe, non-PII attributes for metadata — intentionally excludes
+            // input, output, error.stack, and other user content to match Braintrust exporter
+            metadata: filterSafeMetadata(span.attributes),
+            release: this.release,
+            tags: this.extractTags(span),
+        };
+        await this.apiCall("/api/public/traces", body);
+    }
+    /**
+     * Create a Langfuse span
+     */
+    async createSpan(span) {
+        const langfuseSpan = SpanSerializer.toLangfuseFormat(span);
+        const body = {
+            ...langfuseSpan,
+            traceId: span.traceId,
+        };
+        await this.apiCall("/api/public/spans", body);
+    }
+    /**
+     * Create a Langfuse generation (for LLM calls)
+     */
+    async createGeneration(span) {
+        const langfuseSpan = SpanSerializer.toLangfuseFormat(span);
+        const body = {
+            traceId: span.traceId,
+            id: langfuseSpan.id,
+            parentObservationId: langfuseSpan.parentObservationId,
+            name: langfuseSpan.name,
+            startTime: langfuseSpan.startTime,
+            endTime: langfuseSpan.endTime,
+            model: span.attributes["ai.model"],
+            modelParameters: {
+                temperature: span.attributes["ai.temperature"],
+                maxTokens: span.attributes["ai.max_tokens"],
+                topP: span.attributes["ai.top_p"],
+            },
+            input: langfuseSpan.input,
+            output: langfuseSpan.output,
+            usage: langfuseSpan.usage,
+            metadata: langfuseSpan.metadata,
+            level: langfuseSpan.level,
+            statusMessage: langfuseSpan.statusMessage,
+        };
+        await this.apiCall("/api/public/generations", body);
+    }
+    /**
+     * Make API call to Langfuse
+     */
+    async apiCall(path, body) {
+        const credentials = Buffer.from(`${this.publicKey}:${this.secretKey}`).toString("base64");
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${credentials}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Langfuse API error: ${response.status} - ${text}`);
+        }
+    }
+    /**
+     * Extract tags from span attributes
+     */
+    extractTags(span) {
+        const tags = [];
+        if (span.attributes["ai.provider"]) {
+            tags.push(`provider:${span.attributes["ai.provider"]}`);
+        }
+        if (span.attributes["ai.model"]) {
+            tags.push(`model:${span.attributes["ai.model"]}`);
+        }
+        if (span.attributes["deployment.environment"]) {
+            tags.push(`env:${span.attributes["deployment.environment"]}`);
+        }
+        return tags;
+    }
+}
+// Safe metadata filtering imported from shared module to avoid duplication
+import { filterSafeMetadata } from "../utils/safeMetadata.js";
+//# sourceMappingURL=langfuseExporter.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * LangSmith Exporter
+ * Exports spans to LangSmith observability platform
+ */
+import type { ExporterHealthStatus, ExportResult, LangSmithExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * LangSmith exporter for LangChain ecosystem observability
+ * Supports runs with proper type mapping
+ */
+export declare class LangSmithExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly projectName;
+    private readonly endpoint;
+    constructor(config: LangSmithExporterConfig);
+    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 LangSmith API
+     */
+    protected ping(): Promise<void>;
+}

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

@@ -0,0 +1,124 @@
+/**
+ * LangSmith Exporter
+ * Exports spans to LangSmith observability platform
+ */
+import { logger } from "../../utils/logger.js";
+import { SpanSerializer } from "../utils/spanSerializer.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * LangSmith exporter for LangChain ecosystem observability
+ * Supports runs with proper type mapping
+ */
+export class LangSmithExporter extends BaseExporter {
+    apiKey;
+    projectName;
+    endpoint;
+    constructor(config) {
+        super("langsmith", config);
+        this.apiKey = config.apiKey;
+        this.projectName = config.projectName ?? "default";
+        this.endpoint = config.endpoint ?? "https://api.smith.langchain.com";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Verify API key with a test request
+        try {
+            const response = await fetch(`${this.endpoint}/api/v1/info`, {
+                headers: { "x-api-key": this.apiKey },
+            });
+            if (!response.ok) {
+                throw new Error(`LangSmith initialization failed: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            // Allow initialization to proceed even if API is unreachable
+            // This enables offline/test scenarios
+            logger.warn("[LangSmith] 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 langsmithRun = SpanSerializer.toLangSmithFormat(span);
+            const response = await fetch(`${this.endpoint}/api/v1/runs`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": this.apiKey,
+                },
+                body: JSON.stringify({
+                    ...langsmithRun,
+                    session_name: this.projectName,
+                }),
+            });
+            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 runs = spans.map((s) => ({
+                ...SpanSerializer.toLangSmithFormat(s),
+                session_name: this.projectName,
+            }));
+            const response = await fetch(`${this.endpoint}/api/v1/runs/batch`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": this.apiKey,
+                },
+                body: JSON.stringify({ runs }),
+            });
+            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 LangSmith API
+     */
+    async ping() {
+        const response = await fetch(`${this.endpoint}/api/v1/info`, {
+            headers: { "x-api-key": this.apiKey },
+        });
+        if (!response.ok) {
+            throw new Error(`LangSmith API unreachable: ${response.status}`);
+        }
+    }
+}
+//# sourceMappingURL=langsmithExporter.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * OpenTelemetry Exporter
+ * Exports spans to OTLP-compatible backends
+ */
+import type { ExporterHealthStatus, ExportResult, OtelExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * OpenTelemetry exporter for OTLP-compatible backends
+ * Supports HTTP, gRPC, and Zipkin protocols
+ */
+export declare class OtelExporter extends BaseExporter {
+    private readonly endpoint;
+    private readonly protocol;
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly resourceAttributes;
+    private readonly compression;
+    constructor(config: OtelExporterConfig);
+    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 OTLP endpoint
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Get the export URL based on protocol
+     */
+    private getExportUrl;
+    /**
+     * Send request with optional gzip compression
+     * @param endpoint - The URL to send to
+     * @param body - The payload to send
+     */
+    private sendRequest;
+}

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

@@ -0,0 +1,165 @@
+/**
+ * OpenTelemetry Exporter
+ * Exports spans to OTLP-compatible backends
+ */
+import { gzipSync } from "zlib";
+import { SpanSerializer } from "../utils/spanSerializer.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * OpenTelemetry exporter for OTLP-compatible backends
+ * Supports HTTP, gRPC, and Zipkin protocols
+ */
+export class OtelExporter extends BaseExporter {
+    endpoint;
+    protocol;
+    serviceName;
+    serviceVersion;
+    resourceAttributes;
+    compression;
+    constructor(config) {
+        super("opentelemetry", config);
+        this.endpoint = config.endpoint;
+        this.protocol = config.protocol ?? "http";
+        this.serviceName = config.serviceName ?? "neurolink-ai";
+        this.serviceVersion = config.serviceVersion ?? "1.0.0";
+        this.resourceAttributes = config.resourceAttributes ?? {};
+        this.compression = config.compression ?? "none";
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        this.initialized = true;
+        this.startFlushInterval(this.config.flushIntervalMs ?? 5000);
+    }
+    async exportSpan(span) {
+        // Intentionally buffer spans rather than exporting immediately.
+        // OTLP is designed for batch export (resourceSpans envelope), so we
+        // accumulate spans and flush them together via exportBatch() on the
+        // configured flushInterval or when the buffer reaches maxBufferSize.
+        this.bufferSpan(span);
+        return this.createSuccessResult(0, 0);
+    }
+    async exportBatch(spans) {
+        const startTime = Date.now();
+        try {
+            const otelSpans = spans.map((s) => SpanSerializer.toOtelFormat(s));
+            const payload = {
+                resourceSpans: [
+                    {
+                        resource: {
+                            attributes: [
+                                {
+                                    key: "service.name",
+                                    value: { stringValue: this.serviceName },
+                                },
+                                {
+                                    key: "service.version",
+                                    value: { stringValue: this.serviceVersion },
+                                },
+                                ...Object.entries(this.resourceAttributes).map(([key, value]) => ({
+                                    key,
+                                    value: { stringValue: value },
+                                })),
+                            ],
+                        },
+                        scopeSpans: [
+                            {
+                                scope: {
+                                    name: "neurolink-observability",
+                                    version: "1.0.0",
+                                },
+                                spans: otelSpans,
+                            },
+                        ],
+                    },
+                ],
+            };
+            const url = this.getExportUrl();
+            await this.sendRequest(url, payload);
+            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, ["Endpoint unreachable"]);
+        }
+    }
+    /**
+     * Verify connectivity to OTLP endpoint
+     */
+    async ping() {
+        const response = await fetch(this.endpoint, { method: "HEAD" });
+        // 405 (Method Not Allowed) is acceptable for HEAD requests
+        if (!response.ok && response.status !== 405) {
+            throw new Error(`OTLP endpoint unreachable: ${response.status}`);
+        }
+    }
+    /**
+     * Get the export URL based on protocol
+     */
+    getExportUrl() {
+        switch (this.protocol) {
+            case "http":
+                return `${this.endpoint}/v1/traces`;
+            case "zipkin":
+                return `${this.endpoint}/api/v2/spans`;
+            case "grpc":
+                // For gRPC, this would use @grpc/grpc-js
+                return this.endpoint;
+            default:
+                return `${this.endpoint}/v1/traces`;
+        }
+    }
+    /**
+     * Send request with optional gzip compression
+     * @param endpoint - The URL to send to
+     * @param body - The payload to send
+     */
+    async sendRequest(endpoint, body) {
+        const jsonBody = JSON.stringify(body);
+        let bodyData = jsonBody;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        // Apply gzip compression if configured
+        if (this.compression === "gzip") {
+            const compressed = gzipSync(Buffer.from(jsonBody));
+            // Convert Buffer to Uint8Array for fetch compatibility
+            bodyData = new Uint8Array(compressed);
+            headers["Content-Encoding"] = "gzip";
+        }
+        // Add any custom headers from config
+        if (this.config.headers) {
+            Object.assign(headers, this.config.headers);
+        }
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers,
+            body: bodyData,
+        });
+        if (!response.ok) {
+            throw new Error(`OTLP export failed: ${response.statusText}`);
+        }
+    }
+}
+//# sourceMappingURL=otelExporter.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * PostHog Exporter
+ * Exports spans to PostHog product analytics platform
+ * @see https://posthog.com/docs/api
+ */
+import type { ExporterHealthStatus, ExportResult, PostHogExporterConfig, SpanData } from "../types/index.js";
+import { BaseExporter } from "./baseExporter.js";
+/**
+ * PostHog exporter for product analytics and LLM event tracking
+ * Supports capturing LLM interactions as events with properties
+ */
+export declare class PostHogExporter extends BaseExporter {
+    private readonly apiKey;
+    private readonly host;
+    private readonly personalApiKey?;
+    constructor(config: PostHogExporterConfig);
+    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 PostHog API
+     */
+    protected ping(): Promise<void>;
+    /**
+     * Convert span to PostHog event format
+     */
+    private convertToPostHogEvent;
+    /**
+     * Get event name based on span type
+     */
+    private getEventName;
+    /**
+     * Convert span status to string
+     */
+    private getStatusString;
+    /**
+     * Extract custom properties from span attributes
+     * Filters out standard attributes that are already handled
+     */
+    private extractCustomProperties;
+}