@juspay/neurolink 9.94.7 → 9.95.1

package/dist/lib/types/analytics.d.ts

@@ -78,3 +78,130 @@ export type PerformanceMetrics = {
         external: number;
     };
 };
+export type TimeRangeOption = {
+    start: Date;
+    end: Date;
+};
+/**
+ * Quality score subset captured on an analytics telemetry record.
+ */
+export type AnalyticsQualityScore = {
+    overall: number;
+    relevance: number;
+    accuracy: number;
+    completeness: number;
+    reasoning?: string;
+};
+/**
+ * Single request lifecycle record for advanced analytics aggregation.
+ */
+export type TelemetryRecord = {
+    id: string;
+    provider: string;
+    model: string;
+    userId?: string;
+    teamId?: string;
+    department?: string;
+    timestamp: number;
+    latency: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost: number;
+    isError: boolean;
+    errorMessage?: string;
+    qualityScore?: AnalyticsQualityScore;
+};
+/**
+ * Pluggable storage backend for analytics telemetry records.
+ */
+export type AnalyticsStorage = {
+    /** Save a telemetry record */
+    saveRecord(record: TelemetryRecord): Promise<void>;
+    /** Retrieve all records */
+    getRecords(): Promise<TelemetryRecord[]>;
+    /** Clear storage */
+    clear(): Promise<void>;
+};
+/**
+ * Options for the bounded in-memory analytics storage backend.
+ */
+export type InMemoryAnalyticsStorageOptions = {
+    /** Maximum records to retain. Oldest records are evicted when exceeded. */
+    maxRecords?: number;
+};
+export type ProviderMetricsOptions = {
+    providers?: string[];
+    timeRange?: TimeRangeOption | string;
+    metrics?: string[];
+};
+export type ProviderMetricItem = {
+    name: string;
+    averageLatency: number;
+    averageResponseTime: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    errorRate: number;
+    successRate: number;
+    costPerToken: number;
+    totalCost: number;
+    requestCount: number;
+};
+export type ProviderMetricsResult = {
+    averageLatency: number;
+    averageResponseTime: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    errorRate: number;
+    successRate: number;
+    costPerToken: number;
+    totalCost: number;
+    requestCount: number;
+    providers: ProviderMetricItem[];
+};
+export type CostAnalysisOptions = {
+    timeRange?: TimeRangeOption | string;
+    groupBy?: string | string[];
+    includeProjections?: boolean;
+};
+export type CostGroupItem = {
+    groupKey: string;
+    provider?: string;
+    model?: string;
+    userId?: string;
+    totalCost: number;
+    costPerToken: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    requestCount: number;
+};
+export type CostAnalysisResult = {
+    totalCost: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    requestCount: number;
+    groups: Record<string, CostGroupItem>;
+    providers: CostGroupItem[];
+    projections?: {
+        nextMonth: number;
+        nextQuarter: number;
+    };
+};
+export type TeamAnalyticsOptions = {
+    teamId?: string;
+    departments?: string[];
+    metrics?: string[];
+    timeRange?: TimeRangeOption | string;
+};
+export type TeamAnalyticsResult = {
+    totalRequests: number;
+    uniqueUsers: number;
+    providersUsed: string[];
+    costBreakdownByProvider: Record<string, number>;
+    costBreakdownByUser: Record<string, number>;
+    qualityScores?: AnalyticsQualityScore;
+};

package/dist/lib/types/cli.d.ts

@@ -138,8 +138,8 @@ export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClass
  * Batch command arguments
  */
 export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
-    /** Input file path */
-    file?: string;
+    /** Prompts-list file path (the `<promptsFile>` positional) */
+    promptsFile?: string;
     /** AI provider to use */
     provider?: string;
     /** Model name */
@@ -1684,3 +1684,8 @@ export type CliAudioPlayerCommand = {
     command: string;
     args: string[];
 };
+/**
+ * The CLI flags validated by `validateCliInputFiles` before a
+ * generate/stream/batch run starts (--image/--csv/--pdf/--video/--file).
+ */
+export type CliValidatedFileOption = "--image" | "--csv" | "--pdf" | "--video" | "--file";

package/dist/lib/utils/logger.d.ts

@@ -162,6 +162,17 @@ declare class NeuroLinkLogger {
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args: unknown[]): void;
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -200,6 +211,7 @@ export declare const logger: {
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
     always: (...args: unknown[]) => void;
+    alwaysStderr: (...args: unknown[]) => void;
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;

package/dist/lib/utils/logger.js

@@ -347,6 +347,19 @@ class NeuroLinkLogger {
     always(...args) {
         console.log(...args);
     }
+    /**
+     * Logs messages unconditionally using `console.error` (stderr).
+     *
+     * Same semantics as `always()` — bypasses log level checks and debug mode
+     * gating — but targets stderr instead of stdout. Use this for output that
+     * must stay visible (safety warnings, notices) without risking corruption
+     * of machine-readable stdout (e.g. `--format json`).
+     *
+     * @param args - The arguments to log. These are passed directly to `console.error`.
+     */
+    alwaysStderr(...args) {
+        console.error(...args);
+    }
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
@@ -436,6 +449,9 @@ export const logger = {
     always: (...args) => {
         neuroLinkLogger.always(...args);
     },
+    alwaysStderr: (...args) => {
+        neuroLinkLogger.alwaysStderr(...args);
+    },
     table: (data) => {
         neuroLinkLogger.table(data);
     },

package/dist/neurolink.d.ts

@@ -13,6 +13,7 @@ import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import type { DynamicOptions } from "./types/index.js";
 import { SkillsManager } from "./skills/skillsManager.js";
+import type { CostAnalysisOptions, CostAnalysisResult, ProviderMetricsOptions, ProviderMetricsResult, TeamAnalyticsOptions, TeamAnalyticsResult } from "./types/index.js";
 import { TaskManager } from "./tasks/taskManager.js";
 import type { SessionExport, SessionListItem } from "./types/index.js";
 /**
@@ -220,6 +221,7 @@ export declare class NeuroLink {
      */
     private observabilityConfig?;
     private metricsAggregator;
+    private analyticsService;
     /**
      * Per-request metrics trace context backed by AsyncLocalStorage.
      * Safe for concurrent requests on the same SDK instance.
@@ -532,6 +534,30 @@ export declare class NeuroLink {
      * Record a span for metrics tracking
      */
     recordMetricsSpan(span: SpanData): void;
+    /**
+     * Get provider metrics analysis
+     * Retrieves aggregated performance, token usage, latency, and success rates per provider.
+     *
+     * @param options - Filtering options
+     * @returns Comprehensive provider metrics result
+     */
+    getProviderMetrics(options?: ProviderMetricsOptions): Promise<ProviderMetricsResult>;
+    /**
+     * Get cost analysis breakdown
+     * Analyzes AI generation costs across requested groups and provides future projections.
+     *
+     * @param options - Cost configuration options
+     * @returns Detailed cost analysis breakdown
+     */
+    getCostAnalysis(options?: CostAnalysisOptions): Promise<CostAnalysisResult>;
+    /**
+     * Get team-wide usage analytics
+     * Retrieves request counts, unique active users, provider breakdown, and quality scoring.
+     *
+     * @param options - Team query options
+     * @returns Comprehensive team analytics report
+     */
+    getTeamAnalytics(options?: TeamAnalyticsOptions): Promise<TeamAnalyticsResult>;
     /**
      * Record a memory operation span to both instance and global metrics aggregators.
      * This ensures memory spans are visible via sdk.getSpans() and getMetricsAggregator().getSpans().
@@ -546,6 +572,34 @@ export declare class NeuroLink {
      * Gracefully shutdown NeuroLink and all MCP connections
      */
     shutdown(): Promise<void>;
+    /**
+     * Fire-and-forget analytics tracking with rejection logging.
+     */
+    private enqueueAnalyticsTrackRequest;
+    /**
+     * Estimate cost using the canonical SDK pricing table (same source as
+     * AnalyticsService.trackRequest) — avoids diverging TokenTracker rates.
+     */
+    private estimateCostFromUsage;
+    /**
+     * Handle generation:end for Pipeline B spans + advanced analytics.
+     * When pipelineAHandled is set, skips Pipeline B spans but still tracks
+     * analytics so successful AI-SDK generate/stream calls are recorded.
+     * Stream analytics are owned here (not stream:complete) to avoid duplicates.
+     */
+    private handleGenerationEndMetrics;
+    /**
+     * Pipeline B span recording for stream:complete.
+     * Advanced analytics are recorded from generation:end only (avoids duplicates
+     * when both stream:complete and generation:end fire for the same request).
+     */
+    private handleStreamCompleteMetrics;
+    private handleToolEndMetrics;
+    /**
+     * Pipeline B span recording for stream:error.
+     * Analytics for failed streams come from generation:end (success: false).
+     */
+    private handleStreamErrorMetrics;
     /**
      * Initialize event listeners that feed span data to MetricsAggregator.
      * Listens to generation:end, stream:complete, and tool:end events.