@juspay/neurolink 9.94.7 → 9.95.1

package/dist/cli/factories/commandFactory.js

@@ -24,7 +24,7 @@ import { initializeCliParser } from "../parser.js";
 import { formatFileSize, saveAudioToFile } from "../utils/audioFileUtils.js";
 import { playAudio } from "../utils/audioPlayer.js";
 import { resolveFilePaths } from "../utils/pathResolver.js";
-import { validateCliInputFiles, validateCsvMaxRows, } from "../utils/inputValidation.js";
+import { validateCliInputFiles, validateCsvMaxRows, validatePromptsFilePath, } from "../utils/inputValidation.js";
 import { animatedWrite } from "../utils/typewriter.js";
 import { createStreamAbortHandler } from "../utils/abortHandler.js";
 import { formatVideoFileSize, getVideoMetadataSummary, saveVideoToFile, } from "../utils/videoFileUtils.js";
@@ -742,11 +742,18 @@ export class CLICommandFactory {
             alias: "skills-dir",
         },
     };
-    // Helper method to build options for commands
-    static buildOptions(yargs, additionalOptions = {}) {
+    // Helper method to build options for commands. `excludeOptions` drops
+    // common flags from registration entirely (not just from validation) —
+    // #1191 round-5: batch uses this to omit `commonOptions.file` so `--file`
+    // isn't a recognized flag at all, since it would collide with the
+    // `<file>` positional (the prompts list).
+    static buildOptions(yargs, additionalOptions = {}, excludeOptions = []) {
+        const baseOptions = excludeOptions.length === 0
+            ? CLICommandFactory.commonOptions
+            : Object.fromEntries(Object.entries(CLICommandFactory.commonOptions).filter(([key]) => !excludeOptions.includes(key)));
         return (yargs
             .options({
-            ...CLICommandFactory.commonOptions,
+            ...baseOptions,
             ...additionalOptions,
         })
             // NEW9: implies relationships so users who pass --stt-provider or
@@ -1543,11 +1550,19 @@ export class CLICommandFactory {
      */
     static createBatchCommand() {
         return {
-            command: "batch <file>",
+            // #1191 round-5: the positional is named `promptsFile`, not `file` —
+            // yargs implicitly accepts `--<positionalName>` as a flag alias for
+            // any positional regardless of whether it's separately registered via
+            // `.options()`, so a positional literally named `file` would let
+            // `--file` silently pass strictOptions() even after removing
+            // `commonOptions.file` below. Renaming the key (invocation syntax is
+            // unaffected — it's still just `neurolink batch prompts.txt`) is what
+            // actually makes `--file` an unknown argument.
+            command: "batch <promptsFile>",
             describe: "Process multiple prompts from a file",
             builder: (yargs) => {
                 return CLICommandFactory.buildOptions(yargs
-                    .positional("file", {
+                    .positional("promptsFile", {
                     type: "string",
                     description: "File with prompts (one per line)",
                     demandOption: true,
@@ -1555,7 +1570,11 @@ export class CLICommandFactory {
                     .example("$0 batch prompts.txt", "Process prompts from file")
                     .example("$0 batch questions.txt --format json", "Export results as JSON")
                     .example("$0 batch tasks.txt -p vertex --delay 2000", "Use Vertex AI with 2s delay")
-                    .example("$0 batch batch.txt --output results.json", "Save results to file"));
+                    .example("$0 batch batch.txt --output results.json", "Save results to file"), {}, 
+                // `--file` is not a batch flag — the positional above is the
+                // prompts-list path. Omit it from registration so it's rejected
+                // as unknown rather than silently accepted then ignored.
+                ["file"]);
             },
             handler: async (argv) => await CLICommandFactory.executeBatch(argv),
         };
@@ -3349,13 +3368,30 @@ export class CLICommandFactory {
         CLICommandFactory.validateAnthropicSubscriptionOptions(options);
         const spinner = options.quiet ? null : ora().start();
         try {
-            if (!argv.file) {
+            if (!argv.promptsFile) {
                 throw new Error("No file specified");
             }
-            if (!fs.existsSync(argv.file)) {
-                throw new Error(`File not found: ${argv.file}`);
-            }
-            const buffer = fs.readFileSync(argv.file);
+            // #291/round-4 #1191: validate multimodal flags and resolve their
+            // paths *before* the prompts file is read/parsed below, mirroring
+            // generate/stream (which validate all inputs before any processing).
+            // Previously this ran after `fs.readFileSync(resolvedPromptsPath)`,
+            // so a large prompts file paired with an invalid --image path paid
+            // the read/parse cost before the flag error ever surfaced. `--file`
+            // (the common auto-detect flag) isn't registered on batch at all —
+            // see createBatchCommand — so `argv.file` can never be set here; no
+            // exclusion needed to protect the (differently-named) positional.
+            validateCliInputFiles(argv);
+            const batchImages = CLICommandFactory.processCliImages(argv.image);
+            const batchCsvFiles = CLICommandFactory.processCliCSVFiles(argv.csv);
+            const batchPdfFiles = CLICommandFactory.processCliPDFFiles(argv.pdf);
+            const batchVideoFiles = CLICommandFactory.processCliVideoFiles(argv.video);
+            // #291: route the prompts-list positional through the same friendly
+            // aggregated-error path as the multimodal flags above (not found /
+            // unreadable / directory / malformed file:// URL), instead of a raw
+            // existsSync+readFileSync that throws an unfriendly EISDIR when
+            // pointed at a directory.
+            const resolvedPromptsPath = validatePromptsFilePath(argv.promptsFile);
+            const buffer = fs.readFileSync(resolvedPromptsPath);
             const prompts = buffer
                 .toString("utf8")
                 .split("\n")
@@ -3390,6 +3426,19 @@ export class CLICommandFactory {
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };
             const sessionId = globalSession.getCurrentSessionId();
+            // batchImages/batchCsvFiles/batchPdfFiles/batchVideoFiles were already
+            // validated and resolved above, before the prompts file was read.
+            if (batchImages?.length ||
+                batchCsvFiles?.length ||
+                batchPdfFiles?.length ||
+                batchVideoFiles?.length) {
+                // Pause the spinner so the notice isn't swallowed by its re-renders.
+                // Safety-relevant, so always visible (not gated behind --quiet) and
+                // written to stderr so `--format json` output on stdout stays parseable.
+                spinner?.stop();
+                logger.alwaysStderr(chalk.yellow("⚠️  Multimodal files (--image/--csv/--pdf/--video) are attached to ALL prompts in this batch."));
+                spinner?.start();
+            }
             for (let i = 0; i < prompts.length; i++) {
                 if (spinner) {
                     spinner.text = `Processing ${i + 1}/${prompts.length}: ${prompts[i].substring(0, 30)}...`;
@@ -3425,7 +3474,33 @@ export class CLICommandFactory {
                         ? { ...contextMetadata, sessionId }
                         : contextMetadata;
                     const runBatchGenerate = () => sdk.generate({
-                        input: { text: inputText },
+                        input: {
+                            text: inputText,
+                            ...(batchImages?.length && { images: batchImages }),
+                            ...(batchCsvFiles?.length && { csvFiles: batchCsvFiles }),
+                            ...(batchPdfFiles?.length && { pdfFiles: batchPdfFiles }),
+                            ...(batchVideoFiles?.length && {
+                                videoFiles: batchVideoFiles,
+                            }),
+                        },
+                        // Only construct these when the corresponding files are
+                        // actually attached — batch has no CSV/video mode to opt into,
+                        // unlike generate/stream, so an empty options object here is
+                        // pure noise on every prompt of every batch run.
+                        ...(batchCsvFiles?.length && {
+                            csvOptions: {
+                                maxRows: argv.csvMaxRows,
+                                formatStyle: argv.csvFormat,
+                            },
+                        }),
+                        ...(batchVideoFiles?.length && {
+                            videoOptions: {
+                                frames: argv.videoFrames,
+                                quality: argv.videoQuality,
+                                format: argv.videoFormat,
+                                transcribeAudio: argv.transcribeAudio,
+                            },
+                        }),
                         provider: enhancedOptions.provider,
                         model: enhancedOptions.model,
                         temperature: enhancedOptions.temperature,

package/dist/cli/utils/inputValidation.d.ts

@@ -1,12 +1,13 @@
 /**
  * CLI Input Validation Utilities
  *
- * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
- * --csv-max-rows before a generate/stream/batch run starts, so bad input
- * fails fast with a clear message instead of surfacing deep inside provider
- * calls. Exported as standalone functions (rather than private statics on
- * CLICommandFactory) so callers — including tests — can import and invoke
- * them directly, without reaching into the class via an `unknown` cast.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, and --csv-max-rows before a
+ * generate/stream/batch run starts, so bad input fails fast with a clear
+ * message instead of surfacing deep inside provider calls. Exported as
+ * standalone functions (rather than private statics on CLICommandFactory)
+ * so callers — including tests — can import and invoke them directly,
+ * without reaching into the class via an `unknown` cast.
  */
 /**
  * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
@@ -24,11 +25,23 @@ export declare const CLI_SOFT_LIMITS_MB: {
 };
 /**
  * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
- * starts: every local path must exist, must not be a directory, and — for
- * the flags with a soft limit — triggers a size warning above the
- * threshold. URLs/data URIs skip both existence and size checks (#319).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export declare function validateCliInputFiles(argv: Record<string, unknown>): void;
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export declare function validatePromptsFilePath(rawPath: string): string;
 /**
  * #310: validate --csv-max-rows is a positive integer in the range
  * 1-100000, matching the documented option range (the value previously

package/dist/cli/utils/inputValidation.js

@@ -1,17 +1,20 @@
 /**
  * CLI Input Validation Utilities
  *
- * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
- * --csv-max-rows before a generate/stream/batch run starts, so bad input
- * fails fast with a clear message instead of surfacing deep inside provider
- * calls. Exported as standalone functions (rather than private statics on
- * CLICommandFactory) so callers — including tests — can import and invoke
- * them directly, without reaching into the class via an `unknown` cast.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, and --csv-max-rows before a
+ * generate/stream/batch run starts, so bad input fails fast with a clear
+ * message instead of surfacing deep inside provider calls. Exported as
+ * standalone functions (rather than private statics on CLICommandFactory)
+ * so callers — including tests — can import and invoke them directly,
+ * without reaching into the class via an `unknown` cast.
  */
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { logger } from "../../lib/utils/logger.js";
-import { resolveFilePaths } from "./pathResolver.js";
+import { redactUrlForError } from "../../lib/utils/logSanitize.js";
+import { resolveFilePath } from "./pathResolver.js";
 /**
  * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
  * defined here rather than reusing `lib/processors/config/sizeLimits.ts`'s
@@ -26,18 +29,126 @@ export const CLI_SOFT_LIMITS_MB = {
     PDF_MAX_MB: 100,
     VIDEO_MAX_MB: 500,
 };
+// `file://` is intentionally excluded here: it addresses a local path, so it
+// must still go through directory/missing-path validation below (via
+// tryResolveFileUrl in validateSingleLocalPath). Only genuine remote/inline
+// references (http(s), data URIs) skip validation entirely (#319).
 function isNonLocalFileReference(filePath) {
     const lower = filePath.toLowerCase();
     return (lower.startsWith("http://") ||
         lower.startsWith("https://") ||
-        lower.startsWith("file://") ||
         lower.startsWith("data:"));
 }
+// #291: a `file://` URL still points at something on disk, so validation
+// needs the real filesystem path. Returns undefined (instead of throwing)
+// for a malformed URL so the caller can report a friendly error.
+function tryResolveFileUrl(filePath) {
+    if (!filePath.toLowerCase().startsWith("file://")) {
+        return filePath;
+    }
+    try {
+        return fileURLToPath(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Shared aggregated-error format for any invalid local file path (missing,
+ * unreadable, a directory, or a malformed `file://` URL). Used by both the
+ * flag-based loop in `validateCliInputFiles` and the batch `<promptsFile>`
+ * positional check in `validatePromptsFilePath`, so every caller gets the
+ * same clear error + troubleshooting hints instead of a raw exception.
+ */
+function buildInvalidFileError(errors) {
+    return new Error("❌ One or more input files are invalid:\n" +
+        `${errors.join("\n")}\n` +
+        "💡 Troubleshooting:\n" +
+        "  • Check the path is correct and relative to your current directory, or pass an absolute path / URL.\n" +
+        `  • Check your working directory (${process.cwd()}).\n` +
+        "  • For remote resources, prefix the value with http:// or https://.\n" +
+        "  • If you pointed at a folder, point at the file inside it instead.");
+}
+/**
+ * Validate a single raw path/URL value for `option`, pushing a friendly
+ * message onto `errors` instead of letting fs calls throw a raw exception
+ * (ENOENT, EACCES/EPERM TOCTOU, a directory, or a malformed `file://` URL).
+ * Returns the resolved local filesystem path on success (or the original
+ * value unchanged for a skipped http(s)/data: reference), and `undefined`
+ * when an error was pushed.
+ *
+ * `rawPath` is redacted via `redactUrlForError` before ever being
+ * interpolated into a message — a `file://` value can carry a sensitive
+ * query string, fragment, or embedded `user:pass@` credentials that must
+ * never be echoed back verbatim. This is a no-op for ordinary filesystem
+ * paths (they aren't parseable as a URL, so the redaction fallback simply
+ * returns them unchanged).
+ */
+function validateSingleLocalPath(option, rawPath, errors, warnAtMB) {
+    const resolvedPath = resolveFilePath(rawPath);
+    if (isNonLocalFileReference(resolvedPath)) {
+        // URLs / data: refs skip both existence and size checks (#319).
+        return resolvedPath;
+    }
+    const safeRawPath = redactUrlForError(rawPath);
+    // #291: `file://` URLs are local paths in disguise — validate the decoded
+    // filesystem path so a directory or missing path is still caught here
+    // instead of failing cryptically deep in processing.
+    const pathToValidate = tryResolveFileUrl(resolvedPath);
+    if (pathToValidate === undefined) {
+        errors.push(`${option} is not a valid file:// URL: ${safeRawPath}`);
+        return undefined;
+    }
+    const safeResolvedPath = redactUrlForError(pathToValidate);
+    // Single statSync covers existence, directory rejection, and the size
+    // warning below — avoids a second syscall and closes the TOCTOU gap a
+    // separate existsSync()+statSync() pair would leave.
+    let stat;
+    try {
+        stat = fs.statSync(pathToValidate);
+    }
+    catch (err) {
+        // Only ENOENT actually means "not found" — EACCES (permission denied),
+        // ELOOP (symlink loop), ENOTDIR, etc. are real failures that get masked
+        // (and made undebuggable) if we blanket-label every statSync error the
+        // same way.
+        const code = err?.code;
+        if (code === "ENOENT") {
+            errors.push(`${option} path not found: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        }
+        else {
+            const reason = err instanceof Error ? err.message : String(err);
+            errors.push(`${option} path could not be accessed: ${safeRawPath} (resolved to ${safeResolvedPath}) — ` +
+                `${code ? `${code}: ` : ""}${reason}`);
+        }
+        return undefined;
+    }
+    // #288: reject a directory before it fails cryptically deep in processing
+    // (readFileSync on a dir throws a raw EISDIR).
+    if (stat.isDirectory()) {
+        errors.push(`${option} path is a directory, not a file: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        return undefined;
+    }
+    // #319: warn (not error) when a local multimodal file is unusually large
+    // so the user isn't surprised by slow processing / token blowups. Safety-
+    // relevant, so always visible (not gated behind --quiet) and written to
+    // stderr — never stdout — so `--format json` output stays parseable.
+    if (warnAtMB !== undefined) {
+        const sizeMB = stat.size / (1024 * 1024);
+        if (sizeMB > warnAtMB) {
+            logger.alwaysStderr(chalk.yellow(`⚠️  ${option} file ${safeRawPath} is ${sizeMB.toFixed(1)}MB ` +
+                `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
+                `or exceed provider token/size limits.`));
+        }
+    }
+    return pathToValidate;
+}
 /**
  * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
- * starts: every local path must exist, must not be a directory, and — for
- * the flags with a soft limit — triggers a size warning above the
- * threshold. URLs/data URIs skip both existence and size checks (#319).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export function validateCliInputFiles(argv) {
     const fileArgs = [
@@ -63,64 +174,39 @@ export function validateCliInputFiles(argv) {
         },
         { option: "--file", value: argv.file },
     ];
-    const missingPaths = [];
+    const errors = [];
     for (const { option, value, warnAtMB } of fileArgs) {
         if (!value) {
             continue;
         }
         const rawPaths = Array.isArray(value) ? value : [value];
-        const resolvedPaths = resolveFilePaths(rawPaths);
-        for (let i = 0; i < resolvedPaths.length; i++) {
-            const resolvedPath = resolvedPaths[i];
-            // URLs / data: refs skip both existence and size checks (#319).
-            if (isNonLocalFileReference(resolvedPath)) {
-                continue;
-            }
-            // Single statSync covers existence, directory rejection, and the
-            // size warning below — avoids a second syscall and closes the
-            // TOCTOU gap a separate existsSync()+statSync() pair would leave.
-            let stat;
-            try {
-                stat = fs.statSync(resolvedPath);
-            }
-            catch (err) {
-                // Only ENOENT actually means "not found" — EACCES (permission
-                // denied), ELOOP (symlink loop), ENOTDIR, etc. are real failures
-                // that get masked (and made undebuggable) if we blanket-label
-                // every statSync error the same way.
-                const code = err?.code;
-                if (code === "ENOENT") {
-                    missingPaths.push(`${option} path not found: ${rawPaths[i]} (resolved to ${resolvedPath})`);
-                }
-                else {
-                    const reason = err instanceof Error ? err.message : String(err);
-                    missingPaths.push(`${option} path could not be accessed: ${rawPaths[i]} (resolved to ${resolvedPath}) — ` +
-                        `${code ? `${code}: ` : ""}${reason}`);
-                }
-                continue;
-            }
-            if (stat.isDirectory()) {
-                missingPaths.push(`${option} path is a directory, not a file: ${rawPaths[i]} (resolved to ${resolvedPath})`);
-                continue;
-            }
-            // #319: warn (not error) when a local multimodal file is unusually
-            // large so the user isn't surprised by slow processing / token blowups.
-            if (warnAtMB !== undefined) {
-                const sizeMB = stat.size / (1024 * 1024);
-                if (sizeMB > warnAtMB) {
-                    logger.always(chalk.yellow(`⚠️  ${option} file ${rawPaths[i]} is ${sizeMB.toFixed(1)}MB ` +
-                        `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
-                        `or exceed provider token/size limits.`));
-                }
-            }
+        for (const rawPath of rawPaths) {
+            validateSingleLocalPath(option, rawPath, errors, warnAtMB);
         }
     }
-    if (missingPaths.length > 0) {
-        throw new Error("❌ One or more input files are invalid:\n" +
-            `${missingPaths.join("\n")}\n` +
-            "💡 Check the path is correct and relative to your current directory, " +
-            "or pass an absolute path / URL.");
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
+    }
+}
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export function validatePromptsFilePath(rawPath) {
+    const errors = [];
+    const resolved = validateSingleLocalPath("<file>", rawPath, errors);
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
     }
+    // `errors` is empty here, so `validateSingleLocalPath` did not return
+    // undefined.
+    return resolved;
 }
 /**
  * #310: validate --csv-max-rows is a positive integer in the range

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

@@ -0,0 +1,7 @@
+/**
+ * Analytics Module Exports (runtime values only — types live in src/lib/types)
+ */
+export { calculateAdvancedCost } from "./pricing.js";
+export { InMemoryAnalyticsStorage, DEFAULT_ANALYTICS_STORAGE_MAX_RECORDS, } from "./storage.js";
+export { AnalyticsService } from "./service.js";
+export { parseAnalyticsQualityScore } from "./parseQualityScore.js";

package/dist/lib/analytics/index.js

@@ -0,0 +1,8 @@
+/**
+ * Analytics Module Exports (runtime values only — types live in src/lib/types)
+ */
+export { calculateAdvancedCost } from "./pricing.js";
+export { InMemoryAnalyticsStorage, DEFAULT_ANALYTICS_STORAGE_MAX_RECORDS, } from "./storage.js";
+export { AnalyticsService } from "./service.js";
+export { parseAnalyticsQualityScore } from "./parseQualityScore.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * Safe narrowing of unknown event payloads into AnalyticsQualityScore.
+ */
+import type { AnalyticsQualityScore } from "../types/index.js";
+/**
+ * Convert an unknown quality-score payload into AnalyticsQualityScore.
+ * Returns undefined for missing, null, or malformed values.
+ */
+export declare function parseAnalyticsQualityScore(value: unknown): AnalyticsQualityScore | undefined;

package/dist/lib/analytics/parseQualityScore.js

@@ -0,0 +1,30 @@
+/**
+ * Safe narrowing of unknown event payloads into AnalyticsQualityScore.
+ */
+/**
+ * Convert an unknown quality-score payload into AnalyticsQualityScore.
+ * Returns undefined for missing, null, or malformed values.
+ */
+export function parseAnalyticsQualityScore(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    // Reject NaN/Infinity — typeof NaN === "number"
+    if (!Number.isFinite(record.overall) ||
+        !Number.isFinite(record.relevance) ||
+        !Number.isFinite(record.accuracy) ||
+        !Number.isFinite(record.completeness)) {
+        return undefined;
+    }
+    return {
+        overall: record.overall,
+        relevance: record.relevance,
+        accuracy: record.accuracy,
+        completeness: record.completeness,
+        ...(typeof record.reasoning === "string"
+            ? { reasoning: record.reasoning }
+            : {}),
+    };
+}
+//# sourceMappingURL=parseQualityScore.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Analytics cost helpers.
+ *
+ * Prefer costs already computed by the telemetry/pricing pipeline
+ * (`utils/pricing.calculateCost` / span `ai.cost.total`). This module
+ * is a thin compatibility wrapper — it does not maintain a second
+ * hardcoded pricing table.
+ */
+/**
+ * Calculate cost from token counts using the canonical SDK pricing table.
+ * Returns 0 when the provider/model combination is unknown.
+ *
+ * Partial model-name matching uses longest-prefix preference inside
+ * `calculateCost` / `findRates` — shorter keys (e.g. `gpt-4o`) never
+ * win over more specific ones (e.g. `gpt-4o-mini`).
+ *
+ * @param model - Model name
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @param provider - Provider name (improves rate lookup; defaults to
+ *   cross-provider search via openrouter alias)
+ * @returns Total cost in USD
+ */
+export declare function calculateAdvancedCost(model: string | undefined, inputTokens: number, outputTokens: number, provider?: string): number;

package/dist/lib/analytics/pricing.js

@@ -0,0 +1,38 @@
+/**
+ * Analytics cost helpers.
+ *
+ * Prefer costs already computed by the telemetry/pricing pipeline
+ * (`utils/pricing.calculateCost` / span `ai.cost.total`). This module
+ * is a thin compatibility wrapper — it does not maintain a second
+ * hardcoded pricing table.
+ */
+import { calculateCost } from "../utils/pricing.js";
+/**
+ * Calculate cost from token counts using the canonical SDK pricing table.
+ * Returns 0 when the provider/model combination is unknown.
+ *
+ * Partial model-name matching uses longest-prefix preference inside
+ * `calculateCost` / `findRates` — shorter keys (e.g. `gpt-4o`) never
+ * win over more specific ones (e.g. `gpt-4o-mini`).
+ *
+ * @param model - Model name
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @param provider - Provider name (improves rate lookup; defaults to
+ *   cross-provider search via openrouter alias)
+ * @returns Total cost in USD
+ */
+export function calculateAdvancedCost(model, inputTokens, outputTokens, provider) {
+    if (!model) {
+        return 0;
+    }
+    // When provider is unknown, use the openrouter/litellm cross-provider
+    // search path in findRates (PROVIDER_ALIASES → __cross_provider__).
+    const resolvedProvider = provider && provider.length > 0 ? provider : "openrouter";
+    return calculateCost(resolvedProvider, model, {
+        input: inputTokens,
+        output: outputTokens,
+        total: inputTokens + outputTokens,
+    });
+}
+//# sourceMappingURL=pricing.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Advanced Analytics Service Layer
+ * Handles metrics collection, aggregation, cost analysis, and projections.
+ */
+import type { AnalyticsStorage, CostAnalysisOptions, CostAnalysisResult, ProviderMetricsOptions, ProviderMetricsResult, TeamAnalyticsOptions, TeamAnalyticsResult, TelemetryRecord } from "../types/index.js";
+export declare class AnalyticsService {
+    private storage;
+    constructor(storage?: AnalyticsStorage);
+    /**
+     * Helper to parse dynamic time range formats safely
+     */
+    private parseTimeRange;
+    /**
+     * Capture a request lifecycle record
+     */
+    trackRequest(record: Omit<TelemetryRecord, "id" | "cost"> & {
+        cost?: number;
+    }): Promise<void>;
+    /**
+     * getProviderMetrics implementation
+     */
+    getProviderMetrics(options?: ProviderMetricsOptions): Promise<ProviderMetricsResult>;
+    /**
+     * Helper to format timestamps for date groupings.
+     * Clones the Date so week arithmetic never mutates the caller's value.
+     */
+    private formatGroupDate;
+    /**
+     * getCostAnalysis implementation
+     */
+    getCostAnalysis(options?: CostAnalysisOptions): Promise<CostAnalysisResult>;
+    /**
+     * getTeamAnalytics implementation
+     */
+    getTeamAnalytics(options?: TeamAnalyticsOptions): Promise<TeamAnalyticsResult>;
+}