@juspay/neurolink 10.1.2 → 10.2.0

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

@@ -700,6 +700,40 @@ export type ProxyStats = {
     totalQuotaRateLimits: number;
     accounts: Record<string, AccountStats>;
 };
+/** Durability and reconciliation state for the proxy usage counters. */
+export type ProxyStatsPersistenceStatus = {
+    enabled: boolean;
+    filePath: string | null;
+    revision: number;
+    pendingMutations: number;
+    inFlightMutations: number;
+    unpersistedMutations: number;
+    lastFlushedAt: number | null;
+    lastReconciledAt: number | null;
+    lastRecoveryAt: number | null;
+    lastError: string | null;
+};
+/** Versioned on-disk snapshot shared by overlapping proxy workers. */
+export type PersistedProxyStatsSnapshot = {
+    schemaVersion: 1;
+    revision: number;
+    updatedAt: number;
+    stats: ProxyStats;
+};
+/** Ownership metadata for the proxy statistics cross-process lock. */
+export type ProxyStatsLockOwner = {
+    token: string;
+    pid: number;
+    acquiredAt: number;
+};
+/** Construction options for an isolated proxy statistics store. */
+export type ProxyUsageStatsStoreOptions = {
+    filePath?: string;
+    flushIntervalMs?: number;
+    lockTimeoutMs?: number;
+    staleLockMs?: number;
+    now?: () => number;
+};
 export type RefreshableAccount = {
     token: string;
     refreshToken?: string;
@@ -874,6 +908,8 @@ export type ProxyPaths = {
     quotaFile: string;
     /** account-cooldowns.json — restart-safe account cooldown state */
     cooldownFile: string;
+    /** proxy-usage-stats.json — restart- and handoff-safe usage counters */
+    statsFile?: string;
     /** Whether this is a dev-mode isolated instance */
     isDev: boolean;
 };
@@ -1876,6 +1912,7 @@ export type ProxyStartApp = {
 };
 /** Stats shape consumed by the proxy status printer. */
 export type StatusStats = {
+    startedAt?: number;
     totalAttempts?: number;
     totalAttemptErrors?: number;
     totalRequests: number;
@@ -1896,7 +1933,9 @@ export type StatusStats = {
         transientRateLimits?: number;
         quotaRateLimits?: number;
         cooling: boolean;
+        status?: "active" | "cooling" | "disabled" | "excluded" | "removed";
     }[];
+    persistence?: ProxyStatsPersistenceStatus;
 };
 /** Sub-action of the `proxy telemetry` CLI command. */
 export type ProxyTelemetryAction = "setup" | "start" | "stop" | "status" | "logs" | "import-dashboard";

package/dist/proxy/proxyPaths.d.ts

@@ -14,3 +14,4 @@
  */
 import type { ProxyPaths } from "../types/index.js";
 export declare function resolveProxyPaths(dev: boolean): ProxyPaths;
+export declare function resolveProxyUsageStatsPath(paths: ProxyPaths): string;

package/dist/proxy/proxyPaths.js

@@ -22,6 +22,7 @@ export function resolveProxyPaths(dev) {
             logsDir: join(base, "logs"),
             quotaFile: join(base, "account-quotas.json"),
             cooldownFile: join(base, "account-cooldowns.json"),
+            statsFile: join(base, "proxy-usage-stats.json"),
             isDev: true,
         };
     }
@@ -31,6 +32,10 @@ export function resolveProxyPaths(dev) {
         logsDir: join(base, "logs"),
         quotaFile: join(base, "account-quotas.json"),
         cooldownFile: join(base, "account-cooldowns.json"),
+        statsFile: join(base, "proxy-usage-stats.json"),
         isDev: false,
     };
 }
+export function resolveProxyUsageStatsPath(paths) {
+    return paths.statsFile ?? join(paths.stateDir, "proxy-usage-stats.json");
+}

package/dist/proxy/usageStats.d.ts

@@ -1,13 +1,67 @@
 /**
- * Proxy Usage Statistics
- * Tracks per-account request counts, token usage, and error rates.
- * In-memory only — resets on proxy restart.
+ * Proxy usage statistics with restart- and handoff-safe persistence.
+ *
+ * Request handlers update memory synchronously. Small deltas are merged into a
+ * shared snapshot asynchronously, under a cross-process lock, so overlapping
+ * rolling workers cannot overwrite each other's counters.
  */
-import type { AccountStats, ProxyStats } from "../types/index.js";
+import type { AccountStats, ProxyStats, ProxyStatsPersistenceStatus, ProxyUsageStatsStoreOptions } from "../types/index.js";
+export declare class ProxyUsageStatsStore {
+    private readonly now;
+    private readonly flushIntervalMs;
+    private readonly lockTimeoutMs;
+    private readonly staleLockMs;
+    private filePath?;
+    private stats;
+    private pending;
+    private pendingMutations;
+    private inFlightMutations;
+    private revision;
+    private flushTimer;
+    private readonly flushMutex;
+    private lastFlushedAt?;
+    private lastReconciledAt?;
+    private lastRecoveryAt?;
+    private lastError?;
+    constructor(options?: ProxyUsageStatsStoreOptions);
+    initialize(filePath?: string): Promise<void>;
+    recordAttempt(accountLabel: string, accountType: string): void;
+    recordFinalSuccess(accountLabel?: string, accountType?: string): void;
+    recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
+    recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
+    getStats(): ProxyStats;
+    getAccountStats(label: string): AccountStats | undefined;
+    getPersistenceStatus(): ProxyStatsPersistenceStatus;
+    flush(): Promise<void>;
+    reconcile(): Promise<ProxyStats>;
+    resetMemory(): void;
+    resetForTests(): Promise<void>;
+    private markMutation;
+    private applyAttempt;
+    private applyFinalSuccess;
+    private applyAttemptError;
+    private applyFinalError;
+    private ensureAccount;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private readSnapshot;
+    private applySnapshot;
+    private recoverCorruptSnapshot;
+    private quarantineCorruptSnapshot;
+    private pruneCorruptSnapshots;
+    private describeError;
+}
+export declare function initUsageStats(filePath: string): Promise<void>;
 export declare function recordAttempt(accountLabel: string, accountType: string): void;
 export declare function recordFinalSuccess(accountLabel?: string, accountType?: string): void;
 export declare function recordAttemptError(accountLabel: string, accountType: string, status: number, rateLimitKind?: "transient" | "quota"): void;
 export declare function recordFinalError(_status: number, accountLabel?: string, accountType?: string): void;
 export declare function getStats(): ProxyStats;
+export declare function getReconciledStats(): Promise<ProxyStats>;
 export declare function getAccountStats(label: string): AccountStats | undefined;
+export declare function getUsageStatsPersistenceStatus(): ProxyStatsPersistenceStatus;
+export declare function flushUsageStats(): Promise<void>;
+/** Reset process-local counters while intentionally preserving durable state. */
 export declare function resetStats(): void;
+/** Disconnect persistence and clear singleton state between isolated tests. */
+export declare function resetUsageStatsForTests(): Promise<void>;