@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/core/streamAnalytics.js

@@ -0,0 +1,131 @@
+import { createAnalytics } from "./analytics.js";
+import { logger } from "../utils/logger.js";
+import { extractTokenUsage, createEmptyTokenUsage, } from "../utils/tokenUtils.js";
+import { NoOutputGeneratedError } from "ai";
+/**
+ * Base implementation for collecting analytics from Vercel AI SDK stream results
+ */
+export class BaseStreamAnalyticsCollector {
+    /**
+     * Collect token usage from stream result
+     * Uses centralized tokenUtils for consistent extraction across providers
+     */
+    async collectUsage(result) {
+        try {
+            const usage = await result.usage;
+            if (!usage) {
+                logger.debug("No usage data available from stream result");
+                return createEmptyTokenUsage();
+            }
+            // Use centralized token extraction utility
+            // Handles multiple provider formats, cache tokens, reasoning tokens,
+            // and cache savings calculation
+            return extractTokenUsage(usage);
+        }
+        catch (error) {
+            if (NoOutputGeneratedError.isInstance(error)) {
+                logger.debug("No output generated from stream — returning empty usage");
+            }
+            else {
+                logger.warn("Failed to collect usage from stream result", { error });
+            }
+            return createEmptyTokenUsage();
+        }
+    }
+    /**
+     * Collect response metadata from stream result
+     */
+    async collectMetadata(result) {
+        try {
+            const [response, finishReason] = await Promise.all([
+                result.response,
+                result.finishReason,
+            ]);
+            return {
+                id: response?.id,
+                model: response?.model,
+                timestamp: response?.timestamp instanceof Date
+                    ? response.timestamp.getTime()
+                    : response?.timestamp || Date.now(),
+                finishReason: finishReason,
+            };
+        }
+        catch (error) {
+            if (NoOutputGeneratedError.isInstance(error)) {
+                logger.debug("No output generated from stream — returning default metadata");
+            }
+            else {
+                logger.warn("Failed to collect metadata from stream result", {
+                    error,
+                });
+            }
+            return {
+                timestamp: Date.now(),
+                finishReason: "error",
+            };
+        }
+    }
+    /**
+     * Create comprehensive analytics from stream result
+     */
+    async createAnalytics(provider, model, result, responseTime, metadata) {
+        try {
+            // Collect analytics data in parallel
+            const [usage, responseMetadata] = await Promise.all([
+                this.collectUsage(result),
+                this.collectMetadata(result),
+            ]);
+            // Get final text content and finish reason.
+            // Guard each promise individually: AI SDK v6 rejects all of these with
+            // NoOutputGeneratedError when the stream produced no output.
+            const [content, finishReason, toolResults, toolCalls] = await Promise.all([
+                Promise.resolve(result.text).catch(() => ""),
+                Promise.resolve(result.finishReason).catch(() => "error"),
+                Promise.resolve(result.toolResults || []).catch(() => []),
+                Promise.resolve(result.toolCalls || []).catch(() => []),
+            ]);
+            // Create comprehensive analytics
+            return createAnalytics(provider, model, {
+                usage,
+                content,
+                response: responseMetadata,
+                finishReason: finishReason,
+                toolResults: toolResults,
+                toolCalls: toolCalls,
+            }, responseTime, {
+                ...metadata,
+                streamingMode: true,
+                responseId: responseMetadata.id,
+                finishReason: finishReason,
+            });
+        }
+        catch (error) {
+            logger.error("Failed to create analytics from stream result", {
+                provider,
+                model,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Return minimal analytics on error
+            return createAnalytics(provider, model, { usage: { input: 0, output: 0, total: 0 } }, responseTime, {
+                ...metadata,
+                streamingMode: true,
+                analyticsError: true,
+            });
+        }
+    }
+    /**
+     * Clean up resources and force garbage collection if needed
+     */
+    cleanup() {
+        // Only force garbage collection if memory usage exceeds 500 MB
+        const heapUsed = process.memoryUsage().heapUsed;
+        const GC_THRESHOLD = 500 * 1024 * 1024; // 500 MB
+        if (typeof global !== "undefined" && global.gc && heapUsed > GC_THRESHOLD) {
+            global.gc();
+        }
+    }
+}
+/**
+ * Global instance of stream analytics collector
+ */
+export const streamAnalyticsCollector = new BaseStreamAnalyticsCollector();

package/dist/client/errors.d.ts

@@ -0,0 +1,299 @@
+/**
+ * Error Classes for NeuroLink Client SDK
+ *
+ * Provides comprehensive error classification and handling for API errors,
+ * network errors, validation errors, and more.
+ *
+ * @module @neurolink/client/errors
+ */
+import type { ApiError, JsonObject } from "../types/clientTypes.js";
+/**
+ * Standard error codes for NeuroLink API errors
+ */
+export declare const ErrorCode: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+    readonly CONFLICT: "CONFLICT";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly GATEWAY_TIMEOUT: "GATEWAY_TIMEOUT";
+    readonly BAD_GATEWAY: "BAD_GATEWAY";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CONNECTION_REFUSED: "CONNECTION_REFUSED";
+    readonly DNS_ERROR: "DNS_ERROR";
+    readonly CONFIGURATION_ERROR: "CONFIGURATION_ERROR";
+    readonly SERIALIZATION_ERROR: "SERIALIZATION_ERROR";
+    readonly STREAM_ERROR: "STREAM_ERROR";
+    readonly ABORT_ERROR: "ABORT_ERROR";
+    readonly PROVIDER_ERROR: "PROVIDER_ERROR";
+    readonly MODEL_NOT_FOUND: "MODEL_NOT_FOUND";
+    readonly CONTEXT_LENGTH_EXCEEDED: "CONTEXT_LENGTH_EXCEEDED";
+    readonly CONTENT_FILTERED: "CONTENT_FILTERED";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Base error class for all NeuroLink client errors
+ *
+ * Provides consistent error structure with error codes, status codes,
+ * and additional metadata.
+ */
+export declare class NeuroLinkError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: ErrorCodeType;
+    /** HTTP status code (if applicable) */
+    readonly status?: number;
+    /** Additional error details */
+    readonly details?: JsonObject;
+    /** Whether the error is retryable */
+    readonly retryable: boolean;
+    /** Request ID for error tracking */
+    readonly requestId?: string;
+    constructor(message: string, code?: ErrorCodeType, options?: {
+        status?: number;
+        details?: JsonObject;
+        retryable?: boolean;
+        requestId?: string;
+        cause?: Error;
+    });
+    /**
+     * Convert error to API error format
+     */
+    toApiError(): ApiError;
+    /**
+     * Convert error to JSON
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error for HTTP-related failures
+ */
+export declare class HttpError extends NeuroLinkError {
+    /** HTTP response headers */
+    readonly headers?: Record<string, string>;
+    /** HTTP response body */
+    readonly body?: unknown;
+    constructor(message: string, status: number, options?: {
+        code?: ErrorCodeType;
+        details?: JsonObject;
+        headers?: Record<string, string>;
+        body?: unknown;
+        requestId?: string;
+    });
+}
+/**
+ * Error for rate limiting (429)
+ */
+export declare class ClientRateLimitError extends HttpError {
+    /** Retry-After value in seconds (if provided) */
+    readonly retryAfter?: number;
+    /** Rate limit reset time */
+    readonly resetAt?: Date;
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+        resetAt?: Date;
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for validation failures (400)
+ */
+export declare class ClientValidationError extends HttpError {
+    /** Field-level validation errors */
+    readonly fieldErrors?: Record<string, string[]>;
+    constructor(message?: string, options?: {
+        fieldErrors?: Record<string, string[]>;
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for authentication failures (401)
+ */
+export declare class ClientAuthenticationError extends HttpError {
+    constructor(message?: string, options?: {
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for authorization failures (403)
+ */
+export declare class ClientAuthorizationError extends HttpError {
+    constructor(message?: string, options?: {
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for not found (404)
+ */
+export declare class NotFoundError extends HttpError {
+    /** Resource type that was not found */
+    readonly resourceType?: string;
+    /** Resource ID that was not found */
+    readonly resourceId?: string;
+    constructor(message?: string, options?: {
+        resourceType?: string;
+        resourceId?: string;
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for network-related failures
+ */
+export declare class ClientNetworkError extends NeuroLinkError {
+    constructor(message?: string, options?: {
+        code?: ErrorCodeType;
+        details?: JsonObject;
+        cause?: Error;
+        requestId?: string;
+    });
+}
+/**
+ * Error for request timeout
+ */
+export declare class ClientTimeoutError extends ClientNetworkError {
+    /** Timeout duration in milliseconds */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, message?: string, options?: {
+        details?: JsonObject;
+        requestId?: string;
+    });
+}
+/**
+ * Error for connection refused
+ */
+export declare class ClientConnectionError extends ClientNetworkError {
+    /** Target host */
+    readonly host?: string;
+    /** Target port */
+    readonly port?: number;
+    constructor(message?: string, options?: {
+        host?: string;
+        port?: number;
+        details?: JsonObject;
+        cause?: Error;
+        requestId?: string;
+    });
+}
+/**
+ * Error for request cancellation
+ */
+export declare class AbortError extends NeuroLinkError {
+    constructor(message?: string, options?: {
+        requestId?: string;
+    });
+}
+/**
+ * Error for configuration issues
+ */
+export declare class ClientConfigurationError extends NeuroLinkError {
+    /** Configuration field with issue */
+    readonly field?: string;
+    constructor(message: string, options?: {
+        field?: string;
+        details?: JsonObject;
+    });
+}
+/**
+ * Error for stream processing failures
+ */
+export declare class StreamError extends NeuroLinkError {
+    constructor(message?: string, options?: {
+        details?: JsonObject;
+        cause?: Error;
+        requestId?: string;
+    });
+}
+/**
+ * Error from AI provider
+ */
+export declare class ClientProviderError extends NeuroLinkError {
+    /** Provider name */
+    readonly provider?: string;
+    /** Model name */
+    readonly model?: string;
+    /** Original provider error */
+    readonly providerError?: unknown;
+    constructor(message: string, options?: {
+        provider?: string;
+        model?: string;
+        providerError?: unknown;
+        status?: number;
+        details?: JsonObject;
+        retryable?: boolean;
+        requestId?: string;
+    });
+}
+/**
+ * Error for context length exceeded
+ */
+export declare class ContextLengthError extends ClientProviderError {
+    /** Maximum allowed tokens */
+    readonly maxTokens?: number;
+    /** Requested tokens */
+    readonly requestedTokens?: number;
+    constructor(message?: string, options?: {
+        maxTokens?: number;
+        requestedTokens?: number;
+        provider?: string;
+        model?: string;
+        requestId?: string;
+    });
+}
+/**
+ * Error for content filtering
+ */
+export declare class ContentFilterError extends ClientProviderError {
+    /** Filter category that triggered */
+    readonly category?: string;
+    constructor(message?: string, options?: {
+        category?: string;
+        provider?: string;
+        model?: string;
+        requestId?: string;
+    });
+}
+/**
+ * Create an error from an API error response
+ */
+export declare function createErrorFromResponse(apiError: ApiError, options?: {
+    requestId?: string;
+}): NeuroLinkError;
+/**
+ * Create an error from a native Error object
+ */
+export declare function createErrorFromNative(error: Error, options?: {
+    requestId?: string;
+}): NeuroLinkError;
+/**
+ * Map HTTP status code to error code
+ */
+export declare function mapStatusToErrorCode(status: number): ErrorCodeType;
+/**
+ * Check if a status code is retryable
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Check if an error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Type guard for NeuroLinkError
+ */
+export declare function isNeuroLinkError(error: unknown): error is NeuroLinkError;
+/**
+ * Type guard for ApiError
+ */
+export declare function isApiError(error: unknown): error is ApiError;