@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/interceptors.js

@@ -0,0 +1,601 @@
+/**
+ * Request Interceptors and Retry Logic
+ *
+ * Provides middleware interceptors for the NeuroLink client SDK including
+ * authentication, logging, retry logic, rate limiting, and request/response transformation.
+ *
+ * @module @neurolink/client/interceptors
+ */
+import { logger } from "../utils/logger.js";
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Calculate delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(attempt, initialDelayMs, maxDelayMs, multiplier) {
+    const delay = initialDelayMs * Math.pow(multiplier, attempt);
+    const jitter = Math.random() * 0.1 * delay;
+    return Math.min(delay + jitter, maxDelayMs);
+}
+/**
+ * Delay utility
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if a status code is retryable
+ */
+function isRetryableStatus(status, retryableStatusCodes) {
+    return retryableStatusCodes.includes(status);
+}
+// =============================================================================
+// Authentication Interceptors
+// =============================================================================
+/**
+ * API Key authentication interceptor
+ *
+ * Adds X-API-Key header to all requests.
+ *
+ * @example
+ * ```typescript
+ * client.use(createApiKeyAuthInterceptor('your-api-key'));
+ * ```
+ */
+export function createApiKeyAuthInterceptor(apiKey) {
+    return async (request, next) => {
+        request.headers["X-API-Key"] = apiKey;
+        return next();
+    };
+}
+/**
+ * Bearer token authentication interceptor
+ *
+ * Adds Authorization header with Bearer token.
+ *
+ * @example
+ * ```typescript
+ * client.use(createBearerAuthInterceptor('your-token'));
+ * ```
+ */
+export function createBearerAuthInterceptor(token) {
+    return async (request, next) => {
+        request.headers["Authorization"] = `Bearer ${token}`;
+        return next();
+    };
+}
+/**
+ * Dynamic authentication interceptor
+ *
+ * Retrieves authentication token dynamically for each request.
+ * Useful for token refresh scenarios.
+ *
+ * @example
+ * ```typescript
+ * client.use(createDynamicAuthInterceptor(async () => {
+ *   const token = await getAccessToken();
+ *   return { type: 'bearer', token };
+ * }));
+ * ```
+ */
+export function createDynamicAuthInterceptor(getAuth) {
+    return async (request, next) => {
+        const auth = await getAuth();
+        if (auth) {
+            if (auth.type === "apiKey") {
+                request.headers["X-API-Key"] = auth.key;
+            }
+            else if (auth.type === "bearer") {
+                request.headers["Authorization"] = `Bearer ${auth.token}`;
+            }
+        }
+        return next();
+    };
+}
+/**
+ * Logging interceptor
+ *
+ * Logs request and response details for debugging.
+ *
+ * @example
+ * ```typescript
+ * client.use(createLoggingInterceptor({
+ *   logRequest: true,
+ *   logResponse: true,
+ *   redactFields: ['apiKey', 'password'],
+ * }));
+ * ```
+ */
+export function createLoggingInterceptor(options = {}) {
+    const { logRequest = true, logResponse = true, logBody = false, logResponseBody = false, logger: customLogger = (message, data) => logger.debug(message, data), redactFields = ["apiKey", "password", "token", "authorization"], } = options;
+    const redact = (obj) => {
+        if (typeof obj !== "object" || obj === null) {
+            return obj;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(redact);
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (redactFields.some((field) => key.toLowerCase().includes(field.toLowerCase()))) {
+                result[key] = "[REDACTED]";
+            }
+            else if (typeof value === "object" && value !== null) {
+                result[key] = redact(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
+    return async (request, next) => {
+        const startTime = Date.now();
+        if (logRequest) {
+            const logData = {
+                method: request.method,
+                url: request.url,
+                requestId: request.context.requestId,
+            };
+            if (logBody && request.body) {
+                logData.body = redact(request.body);
+            }
+            customLogger(`[NeuroLink] Request`, logData);
+        }
+        try {
+            const response = await next();
+            const duration = Date.now() - startTime;
+            if (logResponse) {
+                const logData = {
+                    status: response.status,
+                    duration: `${duration}ms`,
+                    requestId: request.context.requestId,
+                };
+                if (logResponseBody && response.body) {
+                    logData.body = redact(response.body);
+                }
+                customLogger(`[NeuroLink] Response`, logData);
+            }
+            return response;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            customLogger(`[NeuroLink] Error`, {
+                error: error.message,
+                duration: `${duration}ms`,
+                requestId: request.context.requestId,
+            });
+            throw error;
+        }
+    };
+}
+/**
+ * Retry interceptor with exponential backoff
+ *
+ * Automatically retries failed requests with configurable backoff.
+ *
+ * @example
+ * ```typescript
+ * client.use(createRetryInterceptor({
+ *   maxAttempts: 3,
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 10000,
+ *   backoffMultiplier: 2,
+ *   retryableStatusCodes: [429, 500, 502, 503, 504],
+ *   onRetry: (attempt, error) => console.log(`Retry ${attempt}:`, error),
+ * }));
+ * ```
+ */
+export function createRetryInterceptor(options) {
+    const { maxAttempts = 3, initialDelayMs = 1000, maxDelayMs = 10000, backoffMultiplier = 2, retryableStatusCodes = [408, 429, 500, 502, 503, 504], retryOnNetworkError = true, onRetry, shouldRetry, } = options;
+    return async (request, next) => {
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const response = await next();
+                // Check custom retry condition
+                if (shouldRetry && shouldRetry(response, attempt)) {
+                    if (attempt < maxAttempts - 1) {
+                        const delay = calculateBackoffDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier);
+                        onRetry?.(attempt + 1, { message: "Custom retry condition met" }, request);
+                        await sleep(delay);
+                        request.context.retryCount = attempt + 1;
+                        continue;
+                    }
+                }
+                // Check if response status is retryable
+                if (isRetryableStatus(response.status, retryableStatusCodes)) {
+                    if (attempt < maxAttempts - 1) {
+                        const delay = calculateBackoffDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier);
+                        const error = {
+                            code: "RETRYABLE_ERROR",
+                            message: `HTTP ${response.status}`,
+                            status: response.status,
+                            retryable: true,
+                        };
+                        onRetry?.(attempt + 1, error, request);
+                        await sleep(delay);
+                        request.context.retryCount = attempt + 1;
+                        continue;
+                    }
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                // Check if network error and should retry
+                if (retryOnNetworkError && attempt < maxAttempts - 1) {
+                    const delay = calculateBackoffDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier);
+                    onRetry?.(attempt + 1, error, request);
+                    await sleep(delay);
+                    request.context.retryCount = attempt + 1;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError ?? new Error("Max retries exceeded");
+    };
+}
+/**
+ * Token bucket rate limiter
+ */
+class TokenBucket {
+    tokens;
+    lastRefill;
+    maxTokens;
+    refillRate;
+    queue = [];
+    constructor(maxTokens, windowMs) {
+        this.maxTokens = maxTokens;
+        this.tokens = maxTokens;
+        this.lastRefill = Date.now();
+        this.refillRate = maxTokens / windowMs;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+    async acquire(strategy) {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        if (strategy === "throw") {
+            throw new Error("Rate limit exceeded");
+        }
+        // Queue strategy: wait for a token
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject });
+            this.processQueue();
+        });
+    }
+    processQueue() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        const waitTime = Math.ceil((1 - this.tokens) / this.refillRate);
+        setTimeout(() => {
+            this.refill();
+            while (this.tokens >= 1 && this.queue.length > 0) {
+                this.tokens -= 1;
+                const item = this.queue.shift();
+                item?.resolve();
+            }
+            if (this.queue.length > 0) {
+                this.processQueue();
+            }
+        }, waitTime);
+    }
+}
+/**
+ * Rate limiting interceptor
+ *
+ * Limits the rate of requests to prevent overwhelming the API.
+ *
+ * @example
+ * ```typescript
+ * client.use(createRateLimitInterceptor({
+ *   maxRequests: 100,
+ *   windowMs: 60000, // 100 requests per minute
+ *   strategy: 'queue',
+ *   onRateLimited: (waitTime) => console.log(`Rate limited, waiting ${waitTime}ms`),
+ * }));
+ * ```
+ */
+export function createRateLimitInterceptor(options) {
+    const { maxRequests, windowMs, strategy = "queue", onRateLimited } = options;
+    const bucket = new TokenBucket(maxRequests, windowMs);
+    return async (request, next) => {
+        try {
+            await bucket.acquire(strategy);
+        }
+        catch (error) {
+            onRateLimited?.(windowMs / maxRequests);
+            throw error;
+        }
+        return next();
+    };
+}
+// =============================================================================
+// Request/Response Transformation Interceptors
+// =============================================================================
+/**
+ * Request transformation interceptor
+ *
+ * Transform request before sending.
+ *
+ * @example
+ * ```typescript
+ * client.use(createRequestTransformInterceptor((request) => {
+ *   // Add custom header based on request body
+ *   if (request.body?.priority === 'high') {
+ *     request.headers['X-Priority'] = 'high';
+ *   }
+ *   return request;
+ * }));
+ * ```
+ */
+export function createRequestTransformInterceptor(transform) {
+    return async (request, next) => {
+        const transformedRequest = await transform(request);
+        // Update the original request object
+        Object.assign(request, transformedRequest);
+        return next();
+    };
+}
+/**
+ * Response transformation interceptor
+ *
+ * Transform response before returning.
+ *
+ * @example
+ * ```typescript
+ * client.use(createResponseTransformInterceptor((response) => {
+ *   // Add metadata to response
+ *   response.context.processedAt = Date.now();
+ *   return response;
+ * }));
+ * ```
+ */
+export function createResponseTransformInterceptor(transform) {
+    return async (request, next) => {
+        const response = await next();
+        return transform(response);
+    };
+}
+/**
+ * Simple in-memory cache
+ */
+class SimpleCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (Date.now() > entry.expires) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttl) {
+        // Evict oldest entries if cache is full
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, {
+            value,
+            expires: Date.now() + ttl,
+        });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+/**
+ * Caching interceptor
+ *
+ * Caches responses to reduce API calls.
+ *
+ * @example
+ * ```typescript
+ * client.use(createCacheInterceptor({
+ *   ttl: 60000, // 1 minute
+ *   methods: ['GET'],
+ *   includePaths: [/\/api\/tools/, /\/api\/providers/],
+ * }));
+ * ```
+ */
+export function createCacheInterceptor(options) {
+    const { ttl, maxSize = 1000, keyGenerator = (req) => `${req.method}:${req.url}`, methods = ["GET"], includePaths, excludePaths, } = options;
+    const cache = new SimpleCache(maxSize);
+    return async (request, next) => {
+        // Check if request should be cached
+        if (!methods.includes(request.method)) {
+            return next();
+        }
+        // Check path filters
+        const url = new URL(request.url, "http://localhost");
+        if (excludePaths?.some((pattern) => pattern.test(url.pathname))) {
+            return next();
+        }
+        if (includePaths &&
+            !includePaths.some((pattern) => pattern.test(url.pathname))) {
+            return next();
+        }
+        const cacheKey = keyGenerator(request);
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            // Return cached response with cache hit indicator
+            return {
+                ...cached,
+                context: {
+                    ...cached.context,
+                    cacheHit: true,
+                },
+            };
+        }
+        const response = await next();
+        // Only cache successful responses
+        if (response.status >= 200 && response.status < 300) {
+            cache.set(cacheKey, response, ttl);
+        }
+        return response;
+    };
+}
+/**
+ * Timeout interceptor
+ *
+ * Adds a timeout to requests.
+ *
+ * @example
+ * ```typescript
+ * client.use(createTimeoutInterceptor({
+ *   timeout: 30000, // 30 seconds
+ *   onTimeout: (request) => console.log('Request timed out:', request.url),
+ * }));
+ * ```
+ */
+export function createTimeoutInterceptor(options) {
+    const { timeout, onTimeout } = options;
+    return async (request, next) => {
+        const controller = new AbortController();
+        // Store the signal so downstream middleware/httpClient can also use it
+        request.context.timeoutSignal = controller.signal;
+        // Race next() against a timer that rejects on timeout
+        let timeoutId;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timeoutId = setTimeout(() => {
+                controller.abort();
+                onTimeout?.(request);
+                const error = new Error(`Request timed out after ${timeout}ms`);
+                error.name = "TimeoutError";
+                reject(error);
+            }, timeout);
+        });
+        try {
+            const response = await Promise.race([next(), timeoutPromise]);
+            clearTimeout(timeoutId);
+            return response;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === "TimeoutError" ||
+                error.name === "AbortError") {
+                throw new Error(`Request timed out after ${timeout}ms`, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Error handling interceptor
+ *
+ * Provides centralized error handling and transformation.
+ *
+ * @example
+ * ```typescript
+ * client.use(createErrorHandlerInterceptor({
+ *   onError: (error, request) => {
+ *     console.error('Request failed:', error.message);
+ *   },
+ *   reportError: async (error, context) => {
+ *     await errorReportingService.report(error, context);
+ *   },
+ * }));
+ * ```
+ */
+export function createErrorHandlerInterceptor(options = {}) {
+    const { onError, transformError, reportError } = options;
+    return async (request, next) => {
+        try {
+            return await next();
+        }
+        catch (error) {
+            // Report error if configured
+            if (reportError) {
+                await reportError(error, request.context);
+            }
+            // Transform error if configured
+            if (transformError) {
+                const transformed = transformError(error);
+                throw transformed;
+            }
+            // Call custom handler
+            if (onError) {
+                const result = onError(error, request);
+                if (result) {
+                    throw result;
+                }
+            }
+            throw error;
+        }
+    };
+}
+// =============================================================================
+// Composition Utilities
+// =============================================================================
+/**
+ * Compose multiple middleware into one
+ *
+ * @example
+ * ```typescript
+ * const combinedMiddleware = composeMiddleware(
+ *   createLoggingInterceptor(),
+ *   createRetryInterceptor({ maxAttempts: 3 }),
+ *   createRateLimitInterceptor({ maxRequests: 100, windowMs: 60000 }),
+ * );
+ *
+ * client.use(combinedMiddleware);
+ * ```
+ */
+export function composeMiddleware(...middlewares) {
+    return async (request, next) => {
+        let index = 0;
+        const executeNext = async () => {
+            if (index < middlewares.length) {
+                const middleware = middlewares[index++];
+                return middleware(request, executeNext);
+            }
+            return next();
+        };
+        return executeNext();
+    };
+}
+/**
+ * Conditionally apply middleware
+ *
+ * @example
+ * ```typescript
+ * client.use(conditionalMiddleware(
+ *   (request) => request.url.includes('/api/agents'),
+ *   createLoggingInterceptor(),
+ * ));
+ * ```
+ */
+export function conditionalMiddleware(condition, middleware) {
+    return async (request, next) => {
+        if (condition(request)) {
+            return middleware(request, next);
+        }
+        return next();
+    };
+}