@juspay/neurolink 9.30.0 → 9.31.0

package/dist/lib/auth/tokenStore.js

@@ -18,8 +18,7 @@ import { homedir } from "os";
 import { createHash } from "crypto";
 import { logger } from "../utils/logger.js";
 import { TokenStoreError } from "../types/errors.js";
-// Re-export for backward compatibility
-export { TokenStoreError } from "../types/errors.js";
+import { AsyncMutex } from "../utils/asyncMutex.js";
 const { readFile, writeFile, mkdir, unlink, access, chmod, rename } = fs;
 // =============================================================================
 // TOKEN STORE CLASS
@@ -62,12 +61,14 @@ export class TokenStore {
     static TOKEN_FILE = "tokens.json";
     static FILE_PERMISSIONS = 0o600;
     static DIR_PERMISSIONS = 0o700;
-    /** Default expiration buffer: 5 minutes */
-    static DEFAULT_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+    /** Default expiration buffer: 1 hour (proactive refresh before actual expiry) */
+    static DEFAULT_EXPIRY_BUFFER_MS = 60 * 60 * 1000;
     storagePath;
     encryptionEnabled;
     encryptionKey;
     tokenRefreshers = new Map();
+    inFlightRefreshes = new Map();
+    _mutex = new AsyncMutex();
     /**
      * Creates a new TokenStore instance
      *
@@ -105,6 +106,14 @@ export class TokenStore {
      * @throws TokenStoreError if storage fails
      */
     async saveTokens(provider, tokens) {
+        return this._mutex.runExclusive(async () => {
+            await this._saveTokensInternal(provider, tokens);
+        });
+    }
+    /**
+     * Internal save without mutex — callers must already hold the mutex.
+     */
+    async _saveTokensInternal(provider, tokens) {
         // Validate tokens before saving
         this.validateTokens(tokens);
         const storageDir = join(this.storagePath, "..");
@@ -168,6 +177,14 @@ export class TokenStore {
      * @throws TokenStoreError if reading fails (other than file not found)
      */
     async loadTokens(provider) {
+        return this._mutex.runExclusive(async () => {
+            return this._loadTokensInternal(provider);
+        });
+    }
+    /**
+     * Internal load without mutex — callers must already hold the mutex.
+     */
+    async _loadTokensInternal(provider) {
         try {
             const storageData = await this.loadStorageData();
             const providerData = storageData.providers[provider];
@@ -199,35 +216,40 @@ export class TokenStore {
      * @throws TokenStoreError if deletion fails
      */
     async clearTokens(provider) {
-        try {
-            const storageData = await this.loadStorageData();
-            if (!storageData.providers[provider]) {
-                logger.debug("No tokens to clear for provider", { provider });
-                return;
-            }
-            delete storageData.providers[provider];
-            storageData.lastModified = Date.now();
-            // If no more providers, delete the file entirely
-            if (Object.keys(storageData.providers).length === 0) {
-                await this.deleteStorageFile();
-            }
-            else {
-                await this.saveStorageData(storageData);
+        return this._mutex.runExclusive(async () => {
+            // Clear in-memory refresh state so re-adding an account starts fresh
+            this.inFlightRefreshes.delete(provider);
+            this.tokenRefreshers.delete(provider);
+            try {
+                const storageData = await this.loadStorageData();
+                if (!storageData.providers[provider]) {
+                    logger.debug("No tokens to clear for provider", { provider });
+                    return;
+                }
+                delete storageData.providers[provider];
+                storageData.lastModified = Date.now();
+                // If no more providers, delete the file entirely
+                if (Object.keys(storageData.providers).length === 0) {
+                    await this.deleteStorageFile();
+                }
+                else {
+                    await this.saveStorageData(storageData);
+                }
+                logger.info("OAuth tokens cleared successfully", { provider });
             }
-            logger.info("OAuth tokens cleared successfully", { provider });
-        }
-        catch (error) {
-            if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
-                logger.debug("No tokens to clear for provider", { provider });
-                return;
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    logger.debug("No tokens to clear for provider", { provider });
+                    return;
+                }
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error("Failed to clear OAuth tokens", {
+                    provider,
+                    error: errorMessage,
+                });
+                throw new TokenStoreError(`Failed to clear tokens for ${provider}: ${errorMessage}`, "STORAGE_ERROR");
             }
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            logger.error("Failed to clear OAuth tokens", {
-                provider,
-                error: errorMessage,
-            });
-            throw new TokenStoreError(`Failed to clear tokens for ${provider}: ${errorMessage}`, "STORAGE_ERROR");
-        }
+        });
     }
     /**
      * Checks if the given tokens are expired
@@ -251,47 +273,105 @@ export class TokenStore {
      * @throws TokenStoreError if refresh fails
      */
     async getValidToken(provider) {
-        const tokens = await this.loadTokens(provider);
-        if (!tokens) {
+        // Phase 1: Read token under mutex (fast)
+        const snapshot = await this._mutex.runExclusive(async () => {
+            const tokens = await this._loadTokensInternal(provider);
+            if (!tokens) {
+                return null;
+            }
+            return { ...tokens };
+        });
+        if (!snapshot) {
             logger.debug("No tokens found for provider", { provider });
             return null;
         }
-        // Check if token is expired or about to expire
-        if (this.isTokenExpired(tokens)) {
-            logger.debug("Token expired or expiring soon", {
+        // Token is still valid — return immediately
+        if (!this.isTokenExpired(snapshot)) {
+            return snapshot.accessToken;
+        }
+        logger.debug("Token expired or expiring soon", {
+            provider,
+            expiresAt: new Date(snapshot.expiresAt).toISOString(),
+        });
+        // Phase 2: Refresh OUTSIDE the mutex so other reads are not blocked
+        const refresher = this.tokenRefreshers.get(provider);
+        if (!refresher || !snapshot.refreshToken) {
+            logger.debug("No refresher configured or no refresh token available", {
                 provider,
-                expiresAt: new Date(tokens.expiresAt).toISOString(),
+                hasRefresher: !!refresher,
+                hasRefreshToken: !!snapshot.refreshToken,
             });
-            // Try to refresh if a refresher is configured
-            const refresher = this.tokenRefreshers.get(provider);
-            if (refresher && tokens.refreshToken) {
-                try {
-                    logger.info("Refreshing expired token", { provider });
-                    const newTokens = await refresher(tokens.refreshToken);
-                    // Save the new tokens
-                    await this.saveTokens(provider, newTokens);
-                    logger.info("Token refreshed successfully", { provider });
-                    return newTokens.accessToken;
-                }
-                catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : String(error);
-                    logger.error("Failed to refresh token", {
-                        provider,
-                        error: errorMessage,
-                    });
-                    throw new TokenStoreError(`Failed to refresh token for ${provider}: ${errorMessage}`, "REFRESH_ERROR");
-                }
+            // No refresher/refresh-token available — fall back to hard expiry check.
+            // The proactive buffer only applies when a refresh is possible.
+            return this.isTokenExpired(snapshot, 0) ? null : snapshot.accessToken;
+        }
+        // Deduplicate concurrent refresh calls for the same provider:
+        // If a refresh is already in-flight, await it instead of starting another.
+        const existing = this.inFlightRefreshes.get(provider);
+        if (existing) {
+            logger.debug("Awaiting in-flight refresh for provider", { provider });
+            const result = await existing;
+            return result.accessToken;
+        }
+        const refreshTokenValue = snapshot.refreshToken;
+        const refreshPromise = (async () => {
+            let newTokens;
+            try {
+                logger.info("Refreshing expired token", { provider });
+                newTokens = await refresher(refreshTokenValue);
             }
-            else {
-                logger.debug("No refresher configured or no refresh token available", {
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error("Failed to refresh token", {
                     provider,
-                    hasRefresher: !!refresher,
-                    hasRefreshToken: !!tokens.refreshToken,
+                    error: errorMessage,
                 });
-                return null;
+                throw new TokenStoreError(`Failed to refresh token for ${provider}: ${errorMessage}`, "REFRESH_ERROR");
             }
+            // Phase 3: Write refreshed token under mutex (fast).
+            // Re-check that the token is still expired before overwriting —
+            // another caller may have already persisted a fresh token.
+            // Also guard against resurrecting cleared/disabled entries:
+            // if the entry was removed or disabled during the in-flight refresh,
+            // skip the save to avoid re-creating a dead entry.
+            const persistedTokens = await this._mutex.runExclusive(async () => {
+                // Guard: do not resurrect cleared entries
+                const current = await this._loadTokensInternal(provider);
+                if (!current) {
+                    logger.debug("Skipping token persist — provider entry was cleared during refresh", { provider });
+                    return newTokens; // return refreshed tokens to caller but don't persist
+                }
+                // Guard: do not resurrect disabled entries
+                try {
+                    const storageData = await this.loadStorageData();
+                    const providerData = storageData.providers[provider];
+                    if (providerData?.disabled) {
+                        logger.debug("Skipping token persist — provider was disabled during refresh", { provider });
+                        return newTokens;
+                    }
+                }
+                catch {
+                    // Storage read failure — proceed cautiously
+                }
+                if (!this.isTokenExpired(current)) {
+                    // Another caller already persisted a fresh token — use theirs.
+                    logger.debug("Skipping token persist — another refresh already wrote a valid token", { provider });
+                    return current;
+                }
+                await this._saveTokensInternal(provider, newTokens);
+                return newTokens;
+            });
+            logger.info("Token refreshed successfully", { provider });
+            return persistedTokens;
+        })();
+        this.inFlightRefreshes.set(provider, refreshPromise);
+        try {
+            const newTokens = await refreshPromise;
+            return newTokens.accessToken;
+        }
+        finally {
+            this.inFlightRefreshes.delete(provider);
         }
-        return tokens.accessToken;
     }
     /**
      * Sets the token refresher function for a provider
@@ -347,14 +427,212 @@ export class TokenStore {
             throw error;
         }
     }
+    /**
+     * Lists all provider keys that start with the given prefix
+     *
+     * @param prefix - The prefix to filter by (e.g., "anthropic:")
+     * @returns Array of matching provider keys
+     */
+    async listByPrefix(prefix) {
+        const allProviders = await this.listProviders();
+        return allProviders.filter((key) => key.startsWith(prefix));
+    }
+    // ===========================================================================
+    // DISABLED STATE METHODS
+    // ===========================================================================
+    /**
+     * Marks a provider's tokens as permanently disabled (persisted to disk).
+     *
+     * Disabled accounts are skipped immediately by consumers — no wasted
+     * round-trips. The state survives proxy restarts because it is stored
+     * alongside the tokens in the JSON file.
+     *
+     * @param provider - The provider key (e.g., "anthropic:user@example.com")
+     * @param reason - Optional human-readable reason (e.g., "refresh_failed")
+     */
+    async markDisabled(provider, reason) {
+        return this._mutex.runExclusive(async () => {
+            let storageData;
+            try {
+                storageData = await this.loadStorageData();
+            }
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    logger.debug("No token storage found — nothing to disable", {
+                        provider,
+                    });
+                    return;
+                }
+                throw error;
+            }
+            const providerData = storageData.providers[provider];
+            if (!providerData) {
+                logger.debug("No tokens found for provider — nothing to disable", {
+                    provider,
+                });
+                return;
+            }
+            providerData.disabled = true;
+            providerData.disabledAt = Date.now();
+            providerData.disabledReason = reason;
+            storageData.lastModified = Date.now();
+            await this.saveStorageData(storageData);
+            logger.info("Provider marked as disabled", {
+                provider,
+                reason: reason ?? "unspecified",
+            });
+        });
+    }
+    /**
+     * Re-enables a previously disabled provider (persisted to disk).
+     *
+     * Clears the disabled flag, timestamp, and reason so the account can
+     * be used again by the proxy pool.
+     *
+     * @param provider - The provider key (e.g., "anthropic:user@example.com")
+     */
+    async markEnabled(provider) {
+        return this._mutex.runExclusive(async () => {
+            let storageData;
+            try {
+                storageData = await this.loadStorageData();
+            }
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    logger.debug("No token storage found — nothing to enable", {
+                        provider,
+                    });
+                    return;
+                }
+                throw error;
+            }
+            const providerData = storageData.providers[provider];
+            if (!providerData) {
+                logger.debug("No tokens found for provider — nothing to enable", {
+                    provider,
+                });
+                return;
+            }
+            providerData.disabled = false;
+            delete providerData.disabledAt;
+            delete providerData.disabledReason;
+            storageData.lastModified = Date.now();
+            await this.saveStorageData(storageData);
+            logger.info("Provider re-enabled", { provider });
+        });
+    }
+    /**
+     * Checks whether a provider's tokens are currently disabled.
+     *
+     * Returns false for providers that don't exist in the store (no tokens
+     * at all) and for entries that predate the disabled field (backward compat).
+     *
+     * @param provider - The provider key
+     * @returns true if the provider entry exists and is disabled
+     */
+    async isDisabled(provider) {
+        return this._mutex.runExclusive(async () => {
+            try {
+                const storageData = await this.loadStorageData();
+                const providerData = storageData.providers[provider];
+                return providerData?.disabled === true;
+            }
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    return false;
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Lists all provider keys that are currently disabled.
+     *
+     * @returns Array of disabled provider keys (empty if none or no storage file)
+     */
+    async listDisabled() {
+        return this._mutex.runExclusive(async () => {
+            try {
+                const storageData = await this.loadStorageData();
+                return Object.entries(storageData.providers)
+                    .filter(([, data]) => data.disabled === true)
+                    .map(([key]) => key);
+            }
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    return [];
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Removes expired and unrefreshable token entries from disk.
+     *
+     * An entry is pruned when:
+     *   - Its access token is expired (with optional buffer) AND it has no
+     *     refresh token, AND it is NOT manually disabled.
+     *
+     * Manually disabled entries are preserved so that `auth enable` can
+     * re-enable them later. They are only removed via explicit `clearTokens`.
+     *
+     * @param bufferMs - Extra buffer in milliseconds to subtract from expiresAt
+     *                   when checking expiry (default: 0 — strict expiry check)
+     * @returns Array of provider keys that were removed
+     */
+    async pruneExpired(bufferMs = 0) {
+        return this._mutex.runExclusive(async () => {
+            let storageData;
+            try {
+                storageData = await this.loadStorageData();
+            }
+            catch (error) {
+                if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                    return [];
+                }
+                throw error;
+            }
+            const now = Date.now();
+            const pruned = [];
+            for (const [key, providerData] of Object.entries(storageData.providers)) {
+                const isExpired = providerData.tokens.expiresAt - bufferMs <= now;
+                const hasNoRefreshToken = !providerData.tokens.refreshToken;
+                const isManuallyDisabled = providerData.disabled === true;
+                // Only prune expired+unrefreshable entries that are NOT manually disabled
+                if (isExpired && hasNoRefreshToken && !isManuallyDisabled) {
+                    delete storageData.providers[key];
+                    pruned.push(key);
+                }
+            }
+            if (pruned.length > 0) {
+                storageData.lastModified = Date.now();
+                if (Object.keys(storageData.providers).length === 0) {
+                    await this.deleteStorageFile();
+                }
+                else {
+                    await this.saveStorageData(storageData);
+                }
+                logger.info("Pruned expired token entries", {
+                    removed: pruned,
+                    count: pruned.length,
+                });
+            }
+            return pruned;
+        });
+    }
     /**
      * Clears all stored tokens for all providers
      *
      * @throws TokenStoreError if deletion fails
      */
     async clearAllTokens() {
-        await this.deleteStorageFile();
-        logger.info("All OAuth tokens cleared");
+        return this._mutex.runExclusive(async () => {
+            // Clear all in-memory refresh state so re-adding accounts starts fresh
+            this.inFlightRefreshes.clear();
+            this.tokenRefreshers.clear();
+            await this.deleteStorageFile();
+            logger.info("All OAuth tokens cleared");
+        });
     }
     // ===========================================================================
     // PRIVATE HELPER METHODS

package/dist/lib/client/aiSdkAdapter.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Vercel AI SDK Compatibility Layer
+ *
+ * Provides compatibility with the Vercel AI SDK by implementing the
+ * LanguageModelV1 interface. This allows NeuroLink to be used as a
+ * drop-in replacement for other AI providers in AI SDK applications.
+ *
+ * @module @neurolink/ai-sdk
+ */
+import type { LanguageModel, LanguageModelCallOptions, LanguageModelResponse, LanguageModelStreamResponse, NeuroLinkProviderOptions, ModelOptions } from "../types/clientTypes.js";
+import { NeuroLinkClient } from "./httpClient.js";
+/**
+ * NeuroLink Language Model implementation compatible with Vercel AI SDK
+ *
+ * Implements the LanguageModelV1 interface for drop-in compatibility.
+ *
+ * @example Using with AI SDK
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { createNeuroLinkModel } from '@neurolink/ai-sdk';
+ *
+ * const model = createNeuroLinkModel({
+ *   baseUrl: 'https://api.neurolink.example.com',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * const result = await generateText({
+ *   model: model('gpt-4o'),
+ *   prompt: 'Hello, world!',
+ * });
+ * ```
+ */
+export declare class NeuroLinkLanguageModel implements LanguageModel {
+    readonly modelId: string;
+    readonly provider: string;
+    private client;
+    private options;
+    constructor(client: NeuroLinkClient, modelId: string, provider: string, options?: ModelOptions);
+    /**
+     * Generate a non-streaming response
+     */
+    doGenerate(options: LanguageModelCallOptions): Promise<LanguageModelResponse>;
+    /**
+     * Generate a streaming response
+     *
+     * Uses an async queue so that each text delta from the provider is yielded
+     * to the consumer immediately, rather than buffering the entire response.
+     */
+    doStream(options: LanguageModelCallOptions): Promise<LanguageModelStreamResponse>;
+    /**
+     * Map NeuroLink finish reasons to AI SDK finish reasons
+     */
+    private mapFinishReason;
+}
+/**
+ * NeuroLink Provider for Vercel AI SDK
+ *
+ * Creates model instances that are compatible with the Vercel AI SDK.
+ *
+ * @example
+ * ```typescript
+ * import { neurolink } from '@neurolink/ai-sdk';
+ *
+ * const provider = neurolink({
+ *   baseUrl: 'https://api.neurolink.example.com',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Create a model
+ * const model = provider('gpt-4o');
+ *
+ * // Use with AI SDK
+ * const result = await generateText({
+ *   model,
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+export declare class NeuroLinkProvider {
+    private client;
+    private defaultProvider;
+    private defaultModel;
+    constructor(options: NeuroLinkProviderOptions);
+    /**
+     * Create a language model instance
+     *
+     * @param modelId - Model ID (e.g., 'gpt-4o', 'claude-3-opus')
+     * @param options - Additional model options
+     */
+    model(modelId?: string, options?: ModelOptions): NeuroLinkLanguageModel;
+    /**
+     * Alias for model() - makes the provider callable
+     */
+    call(modelId?: string, options?: ModelOptions): NeuroLinkLanguageModel;
+    /**
+     * Infer provider from model ID
+     */
+    private inferProvider;
+    /**
+     * Get the underlying client
+     */
+    getClient(): NeuroLinkClient;
+}
+/**
+ * Create a NeuroLink provider for Vercel AI SDK
+ *
+ * @example
+ * ```typescript
+ * import { createNeuroLinkProvider, generateText } from '@neurolink/ai-sdk';
+ *
+ * const neurolink = createNeuroLinkProvider({
+ *   baseUrl: 'https://api.neurolink.example.com',
+ *   apiKey: process.env.NEUROLINK_API_KEY,
+ * });
+ *
+ * const result = await generateText({
+ *   model: neurolink('gpt-4o'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+export declare function createNeuroLinkProvider(options: NeuroLinkProviderOptions): NeuroLinkProvider & ((modelId?: string, modelOptions?: ModelOptions) => NeuroLinkLanguageModel);
+/**
+ * Create a standalone NeuroLink model for Vercel AI SDK
+ *
+ * @example
+ * ```typescript
+ * import { createNeuroLinkModel, generateText } from '@neurolink/ai-sdk';
+ *
+ * const model = createNeuroLinkModel({
+ *   baseUrl: 'https://api.neurolink.example.com',
+ *   apiKey: process.env.NEUROLINK_API_KEY,
+ *   modelId: 'gpt-4o',
+ *   provider: 'openai',
+ * });
+ *
+ * const result = await generateText({
+ *   model,
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ */
+export declare function createNeuroLinkModel(options: NeuroLinkProviderOptions & {
+    modelId: string;
+    provider?: string;
+}): NeuroLinkLanguageModel;
+/**
+ * Default export for easy provider creation
+ *
+ * @example
+ * ```typescript
+ * import { neurolink } from '@neurolink/ai-sdk';
+ *
+ * const provider = neurolink({
+ *   baseUrl: 'https://api.neurolink.example.com',
+ *   apiKey: 'your-key',
+ * });
+ *
+ * const model = provider('gpt-4o');
+ * ```
+ */
+export declare const neurolink: typeof createNeuroLinkProvider;
+/**
+ * Create an AI SDK compatible streaming response from NeuroLink stream
+ *
+ * @example
+ * ```typescript
+ * // In a Next.js API route or server action
+ * import { createStreamingResponse } from '@neurolink/ai-sdk';
+ *
+ * export async function POST(req: Request) {
+ *   const { prompt } = await req.json();
+ *
+ *   const stream = await createStreamingResponse({
+ *     baseUrl: process.env.NEUROLINK_URL,
+ *     apiKey: process.env.NEUROLINK_API_KEY,
+ *     input: { text: prompt },
+ *     provider: 'openai',
+ *     model: 'gpt-4o',
+ *   });
+ *
+ *   return stream;
+ * }
+ * ```
+ */
+export declare function createStreamingResponse(options: NeuroLinkProviderOptions & {
+    input: {
+        text: string;
+    };
+    model: string;
+    provider?: string;
+    temperature?: number;
+    maxTokens?: number;
+    systemPrompt?: string;
+}): Promise<Response>;
+export type { LanguageModel, LanguageModelCallOptions, LanguageModelResponse, LanguageModelStreamResponse, NeuroLinkProviderOptions, ModelOptions, } from "../types/clientTypes.js";