@juspay/neurolink 9.82.0 → 9.84.0

package/dist/utils/pricing.js

@@ -87,8 +87,18 @@ const PRICING = {
             cacheRead: 1.5 / 1_000_000,
             cacheCreation: 18.75 / 1_000_000,
         },
-        "claude-3-sonnet": { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000 },
-        "claude-3-haiku": { input: 0.25 / 1_000_000, output: 1.25 / 1_000_000 },
+        "claude-3-sonnet": {
+            input: 3.0 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.3 / 1_000_000,
+            cacheCreation: 3.75 / 1_000_000,
+        },
+        "claude-3-haiku": {
+            input: 0.25 / 1_000_000,
+            output: 1.25 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
+            cacheCreation: 0.3125 / 1_000_000,
+        },
     },
     // Google Vertex AI — Claude models on Vertex (same pricing, @ date suffix)
     vertex: {
@@ -138,26 +148,95 @@ const PRICING = {
     // OpenAI — updated March 2026
     openai: {
         // GPT-5.x family
-        "gpt-5.4": { input: 2.5 / 1_000_000, output: 15.0 / 1_000_000 },
-        "gpt-5.2": { input: 1.75 / 1_000_000, output: 14.0 / 1_000_000 },
-        "gpt-5.1": { input: 0.625 / 1_000_000, output: 5.0 / 1_000_000 },
-        "gpt-5.1-codex": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-5": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-5-mini": { input: 0.25 / 1_000_000, output: 2.0 / 1_000_000 },
-        "gpt-5-nano": { input: 0.05 / 1_000_000, output: 0.4 / 1_000_000 },
+        // cacheRead = 0.25x input (cached input tokens; no separate cacheCreation).
+        "gpt-5.4": {
+            input: 2.5 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.625 / 1_000_000,
+        },
+        "gpt-5.2": {
+            input: 1.75 / 1_000_000,
+            output: 14.0 / 1_000_000,
+            cacheRead: 0.4375 / 1_000_000,
+        },
+        "gpt-5.1": {
+            input: 0.625 / 1_000_000,
+            output: 5.0 / 1_000_000,
+            cacheRead: 0.15625 / 1_000_000,
+        },
+        "gpt-5.1-codex": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gpt-5": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gpt-5-mini": {
+            input: 0.25 / 1_000_000,
+            output: 2.0 / 1_000_000,
+            cacheRead: 0.0625 / 1_000_000,
+        },
+        "gpt-5-nano": {
+            input: 0.05 / 1_000_000,
+            output: 0.4 / 1_000_000,
+            cacheRead: 0.0125 / 1_000_000,
+        },
         // GPT-4.1 family
-        "gpt-4.1": { input: 2.0 / 1_000_000, output: 8.0 / 1_000_000 },
-        "gpt-4.1-mini": { input: 0.4 / 1_000_000, output: 1.6 / 1_000_000 },
-        "gpt-4.1-nano": { input: 0.1 / 1_000_000, output: 0.4 / 1_000_000 },
+        "gpt-4.1": {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+        },
+        "gpt-4.1-mini": {
+            input: 0.4 / 1_000_000,
+            output: 1.6 / 1_000_000,
+            cacheRead: 0.1 / 1_000_000,
+        },
+        "gpt-4.1-nano": {
+            input: 0.1 / 1_000_000,
+            output: 0.4 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
+        },
         // GPT-4o family
-        "gpt-4o": { input: 2.5 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-4o-mini": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "gpt-4o": {
+            input: 2.5 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.625 / 1_000_000,
+        },
+        "gpt-4o-mini": {
+            input: 0.15 / 1_000_000,
+            output: 0.6 / 1_000_000,
+            cacheRead: 0.0375 / 1_000_000,
+        },
         // o-series reasoning
-        o3: { input: 2.0 / 1_000_000, output: 8.0 / 1_000_000 },
-        "o3-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
-        "o4-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
-        o1: { input: 15.0 / 1_000_000, output: 60.0 / 1_000_000 },
-        "o1-mini": { input: 0.55 / 1_000_000, output: 2.2 / 1_000_000 },
+        o3: {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+        },
+        "o3-mini": {
+            input: 1.1 / 1_000_000,
+            output: 4.4 / 1_000_000,
+            cacheRead: 0.275 / 1_000_000,
+        },
+        "o4-mini": {
+            input: 1.1 / 1_000_000,
+            output: 4.4 / 1_000_000,
+            cacheRead: 0.275 / 1_000_000,
+        },
+        o1: {
+            input: 15.0 / 1_000_000,
+            output: 60.0 / 1_000_000,
+            cacheRead: 3.75 / 1_000_000,
+        },
+        "o1-mini": {
+            input: 0.55 / 1_000_000,
+            output: 2.2 / 1_000_000,
+            cacheRead: 0.1375 / 1_000_000,
+        },
         // Legacy
         "gpt-4-turbo": { input: 10.0 / 1_000_000, output: 30.0 / 1_000_000 },
         "gpt-4": { input: 30.0 / 1_000_000, output: 60.0 / 1_000_000 },
@@ -166,52 +245,83 @@ const PRICING = {
     // Google (Gemini) — updated March 2026
     google: {
         // Gemini 3.1 family (all require -preview suffix)
+        // cacheRead = 0.25x input (cached content tokens; explicit-cache storage is
+        // billed separately by TTL/time, so no per-token cacheCreation rate here).
         "gemini-3.1-pro-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         "gemini-3.1-flash-lite-preview": {
             input: 0.25 / 1_000_000,
             output: 1.5 / 1_000_000,
+            cacheRead: 0.0625 / 1_000_000,
         },
         "gemini-3.1-flash-image-preview": {
             input: 0.5 / 1_000_000,
             output: 3.0 / 1_000_000,
+            cacheRead: 0.125 / 1_000_000,
         },
         "gemini-3.1-pro-preview-customtools": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         // Gemini 3 family
         "gemini-3-flash-preview": {
             input: 0.5 / 1_000_000,
             output: 3.0 / 1_000_000,
+            cacheRead: 0.125 / 1_000_000,
         },
         "gemini-3-pro-image-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         /** @deprecated SHUT DOWN March 9, 2026. Migrate to gemini-3.1-pro-preview. */
         "gemini-3-pro-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         // Gemini 2.5 family
-        "gemini-2.5-flash": { input: 0.3 / 1_000_000, output: 2.5 / 1_000_000 },
-        "gemini-2.5-pro": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
+        "gemini-2.5-flash": {
+            input: 0.3 / 1_000_000,
+            output: 2.5 / 1_000_000,
+            cacheRead: 0.075 / 1_000_000,
+        },
+        "gemini-2.5-pro": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
         "gemini-2.5-flash-lite": {
             input: 0.1 / 1_000_000,
             output: 0.4 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
         },
         // Gemini 2.0 family (deprecated June 2026)
-        "gemini-2.0-flash": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "gemini-2.0-flash": {
+            input: 0.15 / 1_000_000,
+            output: 0.6 / 1_000_000,
+            cacheRead: 0.0375 / 1_000_000,
+        },
         "gemini-2.0-flash-lite": {
             input: 0.075 / 1_000_000,
             output: 0.3 / 1_000_000,
+            cacheRead: 0.01875 / 1_000_000,
         },
         // Gemini 1.5 family
-        "gemini-1.5-pro": { input: 1.25 / 1_000_000, output: 5.0 / 1_000_000 },
-        "gemini-1.5-flash": { input: 0.075 / 1_000_000, output: 0.3 / 1_000_000 },
+        "gemini-1.5-pro": {
+            input: 1.25 / 1_000_000,
+            output: 5.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gemini-1.5-flash": {
+            input: 0.075 / 1_000_000,
+            output: 0.3 / 1_000_000,
+            cacheRead: 0.01875 / 1_000_000,
+        },
     },
     // Mistral AI
     mistral: {
@@ -594,8 +704,16 @@ export function calculateCost(provider, model, usage) {
     let cost = 0;
     cost += (usage.input || 0) * rates.input;
     cost += (usage.output || 0) * rates.output;
-    if (usage.cacheReadTokens && rates.cacheRead) {
-        cost += usage.cacheReadTokens * rates.cacheRead;
+    if (usage.cacheReadTokens) {
+        // Price cache reads at the discounted cacheRead rate when one exists;
+        // otherwise fall back to the full input rate. The overlapping extractor
+        // (tokenUtils) moves cached tokens out of `input` into `cacheReadTokens`
+        // for OpenAI/Gemini-family providers, so without this fallback a provider
+        // that reports cached tokens but has no cacheRead rate would bill those
+        // tokens at $0 (silent undercharge). Falling back to the input rate keeps
+        // total cost identical to pre-split billing for unpriced providers, while
+        // priced providers still get the cheaper cacheRead rate.
+        cost += usage.cacheReadTokens * (rates.cacheRead ?? rates.input);
     }
     if (usage.cacheCreationTokens && rates.cacheCreation) {
         cost += usage.cacheCreationTokens * rates.cacheCreation;

package/dist/utils/responseValidator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Response Validator
+ *
+ * Standalone utility for validating and optionally mutating LLM response text.
+ * Handles length checks (including truncation), phrase checks, JSON schema
+ * validation, and custom validators.  Returns a structured result telling the
+ * caller whether to continue, abort, or retry — the caller owns the retry loop.
+ *
+ * No async I/O, no telemetry spans, no processor classes.
+ */
+import type { ResponseValidationConfig, ResponseValidationResult } from "../types/index.js";
+/**
+ * Validate (and optionally mutate) an LLM response.
+ *
+ * @param responseText - The raw text returned by the model.
+ * @param config       - Validation rules and action preferences.
+ * @param retryCount   - Current retry iteration (passed through to result).
+ * @returns A {@link ResponseValidationResult} with the (possibly truncated)
+ *          text, a disposition action, all issues found, and optional feedback.
+ */
+export declare function validateResponse(responseText: string, config: ResponseValidationConfig, retryCount?: number): ResponseValidationResult;

package/dist/utils/responseValidator.js

@@ -0,0 +1,353 @@
+/**
+ * Response Validator
+ *
+ * Standalone utility for validating and optionally mutating LLM response text.
+ * Handles length checks (including truncation), phrase checks, JSON schema
+ * validation, and custom validators.  Returns a structured result telling the
+ * caller whether to continue, abort, or retry — the caller owns the retry loop.
+ *
+ * No async I/O, no telemetry spans, no processor classes.
+ */
+import { logger } from "./logger.js";
+// =============================================================================
+// JSON SCHEMA VALIDATION (internal)
+// =============================================================================
+/**
+ * Check that `data` matches the given JSON Schema node.
+ * Supports: type, properties, required, items, minimum, maximum,
+ * minLength, maxLength, pattern, enum.
+ *
+ * Bug C5 fix: `typeof null === "object"` — null is never a valid object.
+ */
+function matchesJsonSchemaNode(data, schema, path) {
+    const issues = [];
+    const expectedType = schema["type"];
+    if (expectedType !== undefined) {
+        const valid = (() => {
+            switch (expectedType) {
+                case "string":
+                    return typeof data === "string";
+                case "number":
+                    return typeof data === "number";
+                case "integer":
+                    return typeof data === "number" && Number.isInteger(data);
+                case "boolean":
+                    return typeof data === "boolean";
+                case "null":
+                    return data === null;
+                case "array":
+                    return Array.isArray(data);
+                case "object":
+                    // Bug C5 fix: null must be explicitly excluded
+                    return (data !== null && typeof data === "object" && !Array.isArray(data));
+                default:
+                    return true;
+            }
+        })();
+        if (!valid) {
+            issues.push({
+                category: "json_schema",
+                severity: "error",
+                message: `Expected type "${expectedType}" at "${path}", got ${data === null ? "null" : Array.isArray(data) ? "array" : typeof data}`,
+                field: path,
+            });
+            // Cannot validate sub-constraints if the type is wrong
+            return issues;
+        }
+    }
+    // --- string constraints ---
+    if (typeof data === "string") {
+        const minLen = schema["minLength"];
+        const maxLen = schema["maxLength"];
+        const pattern = schema["pattern"];
+        if (minLen !== undefined && data.length < minLen) {
+            issues.push({
+                category: "json_schema",
+                severity: "error",
+                message: `"${path}" length ${data.length} is below minLength ${minLen}`,
+                field: path,
+            });
+        }
+        if (maxLen !== undefined && data.length > maxLen) {
+            issues.push({
+                category: "json_schema",
+                severity: "error",
+                message: `"${path}" length ${data.length} exceeds maxLength ${maxLen}`,
+                field: path,
+            });
+        }
+        if (pattern !== undefined) {
+            // JSON schema "pattern" validation is skipped at runtime to avoid
+            // dynamic RegExp construction from schema data (CodeQL js/regex-injection).
+            // Patterns are validated at schema authoring time, not at response time.
+            issues.push({
+                category: "json_schema",
+                severity: "info",
+                message: `"${path}" has a pattern constraint "${pattern}" (not enforced at runtime)`,
+                field: path,
+            });
+        }
+    }
+    // --- number constraints ---
+    if (typeof data === "number") {
+        const minimum = schema["minimum"];
+        const maximum = schema["maximum"];
+        if (minimum !== undefined && data < minimum) {
+            issues.push({
+                category: "json_schema",
+                severity: "error",
+                message: `"${path}" value ${data} is below minimum ${minimum}`,
+                field: path,
+            });
+        }
+        if (maximum !== undefined && data > maximum) {
+            issues.push({
+                category: "json_schema",
+                severity: "error",
+                message: `"${path}" value ${data} exceeds maximum ${maximum}`,
+                field: path,
+            });
+        }
+    }
+    // --- enum ---
+    const enumValues = schema["enum"];
+    if (enumValues !== undefined && !enumValues.includes(data)) {
+        issues.push({
+            category: "json_schema",
+            severity: "error",
+            message: `"${path}" must be one of [${enumValues.map(String).join(", ")}], got ${String(data)}`,
+            field: path,
+        });
+    }
+    // --- object: properties + required ---
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+        const obj = data;
+        const properties = schema["properties"];
+        const required = schema["required"];
+        if (required) {
+            for (const key of required) {
+                if (!(key in obj)) {
+                    issues.push({
+                        category: "json_schema",
+                        severity: "error",
+                        message: `Required property "${key}" is missing at "${path}"`,
+                        field: `${path}.${key}`,
+                    });
+                }
+            }
+        }
+        if (properties) {
+            for (const [key, propSchema] of Object.entries(properties)) {
+                if (key in obj) {
+                    issues.push(...matchesJsonSchemaNode(obj[key], propSchema, path ? `${path}.${key}` : key));
+                }
+            }
+        }
+    }
+    // --- array: items ---
+    if (Array.isArray(data)) {
+        const itemSchema = schema["items"];
+        if (itemSchema) {
+            data.forEach((item, idx) => {
+                issues.push(...matchesJsonSchemaNode(item, itemSchema, `${path}[${idx}]`));
+            });
+        }
+    }
+    return issues;
+}
+function validateJsonSchema(text, schema) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [
+            {
+                category: "json_schema",
+                severity: "error",
+                message: "Response is not valid JSON",
+                field: "$",
+            },
+        ];
+    }
+    return matchesJsonSchemaNode(parsed, schema, "$");
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+function buildFeedback(issues) {
+    const errors = issues.filter((i) => i.severity === "error");
+    if (errors.length === 0) {
+        return "Validation warnings were raised. Please review your response.";
+    }
+    return ("The response failed validation:\n" +
+        errors.map((e) => `  - [${e.category}] ${e.message}`).join("\n"));
+}
+// =============================================================================
+// MAIN EXPORT
+// =============================================================================
+/**
+ * Validate (and optionally mutate) an LLM response.
+ *
+ * @param responseText - The raw text returned by the model.
+ * @param config       - Validation rules and action preferences.
+ * @param retryCount   - Current retry iteration (passed through to result).
+ * @returns A {@link ResponseValidationResult} with the (possibly truncated)
+ *          text, a disposition action, all issues found, and optional feedback.
+ */
+export function validateResponse(responseText, config, retryCount) {
+    const issues = [];
+    let text = responseText;
+    // -------------------------------------------------------------------------
+    // 1. Minimum length
+    // -------------------------------------------------------------------------
+    if (config.minLength !== undefined && text.length < config.minLength) {
+        issues.push({
+            category: "length",
+            severity: "error",
+            message: `Response length ${text.length} is below required minimum of ${config.minLength}`,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // 2. Maximum length — applies truncation or records the issue
+    // -------------------------------------------------------------------------
+    if (config.maxLength !== undefined && text.length > config.maxLength) {
+        const action = config.truncationAction ?? "truncate";
+        switch (action) {
+            case "truncate": {
+                // Bug C6 fix: ensure keepLength cannot go negative
+                const rawSuffix = config.truncationSuffix ?? "...";
+                const suffix = rawSuffix.slice(0, config.maxLength);
+                const keepLength = Math.max(config.maxLength - suffix.length, 0);
+                text = text.slice(0, keepLength) + suffix;
+                issues.push({
+                    category: "length",
+                    severity: "info",
+                    message: `Response was truncated from ${responseText.length} to ${config.maxLength} characters`,
+                });
+                if (logger.shouldLog("debug")) {
+                    logger.debug(`[responseValidator] truncated response to ${config.maxLength} chars`);
+                }
+                break;
+            }
+            case "abort": {
+                issues.push({
+                    category: "length",
+                    severity: "error",
+                    message: `Response length ${text.length} exceeds maximum of ${config.maxLength}; aborting`,
+                });
+                return {
+                    text,
+                    action: "abort",
+                    issues,
+                    feedback: `Response exceeded maximum length of ${config.maxLength} characters.`,
+                    retryCount,
+                };
+            }
+            case "retry": {
+                issues.push({
+                    category: "length",
+                    severity: "error",
+                    message: `Response length ${text.length} exceeds maximum of ${config.maxLength}; requesting retry`,
+                });
+                return {
+                    text,
+                    action: "retry",
+                    issues,
+                    feedback: "Response exceeded max length, please shorten",
+                    retryCount,
+                };
+            }
+            case "warn":
+            default: {
+                issues.push({
+                    category: "length",
+                    severity: "warning",
+                    message: `Response length ${text.length} exceeds maximum of ${config.maxLength} (warn-only)`,
+                });
+                logger.warn(`[responseValidator] response length ${text.length} exceeds maxLength ${config.maxLength}`);
+                break;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 3. Required phrases
+    // -------------------------------------------------------------------------
+    if (config.requiredPhrases && config.requiredPhrases.length > 0) {
+        const lowerText = text.toLowerCase();
+        for (const phrase of config.requiredPhrases) {
+            if (!lowerText.includes(phrase.toLowerCase())) {
+                issues.push({
+                    category: "phrase",
+                    severity: "error",
+                    message: `Required phrase "${phrase}" was not found in the response`,
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 4. Forbidden phrases
+    // -------------------------------------------------------------------------
+    if (config.forbiddenPhrases && config.forbiddenPhrases.length > 0) {
+        const lowerText = text.toLowerCase();
+        for (const phrase of config.forbiddenPhrases) {
+            if (lowerText.includes(phrase.toLowerCase())) {
+                issues.push({
+                    category: "phrase",
+                    severity: "error",
+                    message: `Forbidden phrase "${phrase}" was found in the response`,
+                });
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 5. JSON schema
+    // -------------------------------------------------------------------------
+    if (config.jsonSchema) {
+        const schemaIssues = validateJsonSchema(text, config.jsonSchema);
+        issues.push(...schemaIssues);
+    }
+    // -------------------------------------------------------------------------
+    // 6. Custom validator
+    // -------------------------------------------------------------------------
+    if (config.customValidator) {
+        const customIssue = config.customValidator(text);
+        if (customIssue !== null) {
+            issues.push(customIssue);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 7. Determine final action
+    // -------------------------------------------------------------------------
+    const hasErrors = issues.some((i) => i.severity === "error");
+    if (hasErrors) {
+        if (logger.shouldLog("debug")) {
+            logger.debug("[responseValidator] validation failed", {
+                issueCount: issues.length,
+                retryOnFailure: config.retryOnFailure,
+            });
+        }
+        if (config.retryOnFailure) {
+            return {
+                text,
+                action: "retry",
+                issues,
+                feedback: buildFeedback(issues),
+                retryCount,
+            };
+        }
+        return {
+            text,
+            action: "abort",
+            issues,
+            feedback: buildFeedback(issues),
+            retryCount,
+        };
+    }
+    return {
+        text,
+        action: "continue",
+        issues,
+        retryCount,
+    };
+}

package/dist/utils/tokenUtils.d.ts

@@ -38,6 +38,17 @@ export declare function extractCacheCreationTokens(usage: RawUsageObject): numbe
  * Supports: cacheReadInputTokens, cacheReadTokens
  */
 export declare function extractCacheReadTokens(usage: RawUsageObject): number | undefined;
+/**
+ * Extract cache read token count from the OVERLAPPING-convention nested path
+ * used by OpenAI / DeepSeek / NIM / OpenAI-compatible providers:
+ * `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Unlike {@link extractCacheReadTokens} (non-overlapping Anthropic/Vertex
+ * convention where cache tokens are reported SEPARATELY from input), the value
+ * returned here is a SUBSET already included in `prompt_tokens`. Callers that
+ * use this value MUST subtract it from `input` to avoid double-counting.
+ */
+export declare function extractCachedInputTokensOverlapping(usage: RawUsageObject): number | undefined;
 /**
  * Calculate cache savings percentage
  *