@opendatalabs/vana-sdk 0.1.0-alpha.a25bcc7 → 0.1.0-alpha.a6b60fc

package/dist/core/apiClient.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/apiClient.ts"],"sourcesContent":["import type {\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n} from \"../types/generics\";\nimport {\n  RetryUtility,\n  RateLimiter,\n  MiddlewarePipeline,\n  CircuitBreaker,\n} from \"./generics\";\n\n/**\n * Configuration for the generic API client\n */\nexport interface ApiClientConfig {\n  /** Base URL for all requests */\n  baseUrl?: string;\n  /** Default headers */\n  headers?: Record<string, string>;\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Retry configuration */\n  retry?: RetryConfig;\n  /** Rate limiting configuration */\n  rateLimit?: RateLimiterConfig;\n  /** Circuit breaker configuration */\n  circuitBreaker?: {\n    failureThreshold: number;\n    recoveryTimeout: number;\n    halfOpenMaxAttempts?: number;\n  };\n}\n\n/**\n * HTTP method types\n */\nexport type HttpMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\";\n\n/**\n * Request options for API calls\n */\nexport interface RequestOptions {\n  /** HTTP method */\n  method?: HttpMethod;\n  /** Request headers */\n  headers?: Record<string, string>;\n  /** Query parameters */\n  params?: Record<string, unknown>;\n  /** Request timeout */\n  timeout?: number;\n  /** Skip retry for this request */\n  skipRetry?: boolean;\n  /** Skip rate limiting for this request */\n  skipRateLimit?: boolean;\n}\n\n/**\n * Generic API client with middleware, retry, rate limiting, and circuit breaker support\n */\nexport class ApiClient {\n  private readonly config: Required<ApiClientConfig>;\n  private readonly middleware: MiddlewarePipeline;\n  private readonly rateLimiter?: RateLimiter;\n  private readonly circuitBreaker?: CircuitBreaker;\n\n  constructor(config: ApiClientConfig = {}) {\n    this.config = {\n      baseUrl: config.baseUrl ?? \"\",\n      headers: config.headers ?? {},\n      timeout: config.timeout ?? 30000,\n      retry: config.retry ?? {\n        maxAttempts: 3,\n        baseDelay: 1000,\n        backoffMultiplier: 2,\n        shouldRetry: (error) => error.message.includes(\"network\"),\n      },\n      rateLimit: config.rateLimit ?? {\n        requestsPerWindow: 100,\n        windowMs: 60000,\n      },\n      circuitBreaker: config.circuitBreaker ?? {\n        failureThreshold: 5,\n        recoveryTimeout: 60000,\n        halfOpenMaxAttempts: 3,\n      },\n    };\n\n    this.middleware = new MiddlewarePipeline();\n    this.rateLimiter = new RateLimiter(this.config.rateLimit);\n    this.circuitBreaker = new CircuitBreaker(this.config.circuitBreaker);\n  }\n\n  /**\n   * Add middleware to the request pipeline\n   *\n   * @param middleware - The middleware function to add to the pipeline\n   */\n  use(middleware: Middleware): void {\n    this.middleware.use(middleware);\n  }\n\n  /**\n   * Make a generic HTTP request\n   *\n   * @param url - The URL to make the request to\n   * @param options - Request options including method, headers, body, etc.\n   * @returns Promise resolving to the response data\n   */\n  async request<TData = unknown>(\n    url: string,\n    options: RequestOptions = {},\n  ): Promise<GenericResponse<TData>> {\n    const fullUrl = this.buildUrl(url);\n    const requestOptions = this.buildRequestOptions(options);\n\n    const request: GenericRequest<{\n      url: string;\n      options: RequestOptions;\n    }> = {\n      params: {\n        url: fullUrl,\n        options: requestOptions,\n      },\n      options: requestOptions,\n    };\n\n    // Apply rate limiting\n    if (!options.skipRateLimit && this.rateLimiter) {\n      await this.rateLimiter.waitForSlot();\n    }\n\n    // Execute with circuit breaker\n    if (this.circuitBreaker) {\n      return this.circuitBreaker.execute(() =>\n        this.executeRequest<TData>(request),\n      );\n    }\n\n    return this.executeRequest<TData>(request);\n  }\n\n  /**\n   * Make a GET request\n   *\n   * @param url - The URL to make the GET request to\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async get<TData = unknown>(\n    url: string,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, { ...options, method: \"GET\" });\n  }\n\n  /**\n   * Make a POST request\n   *\n   * @param url - The URL to make the POST request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async post<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Make a PUT request\n   *\n   * @param url - The URL to make the PUT request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async put<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"PUT\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Make a DELETE request\n   *\n   * @param url - The URL to make the DELETE request to\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async delete<TData = unknown>(\n    url: string,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, { ...options, method: \"DELETE\" });\n  }\n\n  /**\n   * Make a PATCH request\n   *\n   * @param url - The URL to make the PATCH request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async patch<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"PATCH\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Execute the actual HTTP request with middleware and retry\n   *\n   * @param request - The generic request object containing URL and options\n   * @returns Promise resolving to the generic response with data\n   */\n  private async executeRequest<TData>(\n    request: GenericRequest<{ url: string; options: RequestOptions }>,\n  ): Promise<GenericResponse<TData>> {\n    const executeWithRetry = async (): Promise<GenericResponse<TData>> => {\n      try {\n        // Process request through middleware\n        const processedRequest = await this.middleware.processRequest(request);\n\n        // Make the actual HTTP request\n        const response = await this.makeHttpRequest<TData>(\n          (\n            processedRequest as GenericRequest<{\n              url: string;\n              options: RequestOptions;\n            }>\n          ).params.url,\n          (\n            processedRequest as GenericRequest<{\n              url: string;\n              options: RequestOptions;\n            }>\n          ).params.options,\n        );\n\n        // Process response through middleware\n        const processedResponse =\n          await this.middleware.processResponse(response);\n\n        return processedResponse;\n      } catch (error) {\n        // Try to handle error with middleware\n        const handledResponse = await this.middleware.handleError<\n          typeof request,\n          GenericResponse<TData>\n        >(error as Error, request);\n\n        if (handledResponse) {\n          return handledResponse;\n        }\n\n        throw error;\n      }\n    };\n\n    // Apply retry logic if not skipped\n    if (!request.params.options.skipRetry) {\n      return RetryUtility.withRetry(executeWithRetry, this.config.retry);\n    }\n\n    return executeWithRetry();\n  }\n\n  /**\n   * Make the actual HTTP request using fetch API\n   *\n   * @param url - The URL to make the request to\n   * @param options - The request options including method, headers, body, etc.\n   * @returns Promise resolving to the generic response with data\n   */\n  private async makeHttpRequest<TData>(\n    url: string,\n    options: RequestOptions,\n  ): Promise<GenericResponse<TData>> {\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => {\n      controller.abort();\n    }, options.timeout ?? this.config.timeout);\n\n    try {\n      const response = await fetch(url, {\n        method: options.method ?? \"GET\",\n        headers: {\n          ...this.config.headers,\n          ...options.headers,\n        },\n        signal: controller.signal,\n        // Add body for POST/PUT/PATCH requests\n        ...(options.method &&\n          [\"POST\", \"PUT\", \"PATCH\"].includes(options.method) && {\n            body: JSON.stringify(options.params),\n          }),\n      });\n\n      clearTimeout(timeoutId);\n\n      const responseData: unknown = await response.json();\n      const data = responseData as { message?: string; [key: string]: unknown };\n\n      if (!response.ok) {\n        return {\n          data: null as unknown as TData,\n          success: false,\n          error: {\n            code: response.status.toString(),\n            message: data.message ?? response.statusText,\n            details: data,\n          },\n        };\n      }\n\n      return {\n        data: responseData as TData,\n        success: true,\n        meta: {\n          status: response.status,\n          statusText: response.statusText,\n          headers: Object.fromEntries(response.headers.entries()),\n        },\n      };\n    } catch (error) {\n      clearTimeout(timeoutId);\n\n      if (error instanceof Error && error.name === \"AbortError\") {\n        return {\n          data: null as unknown as TData,\n          success: false,\n          error: {\n            code: \"TIMEOUT\",\n            message: \"Request timeout\",\n            details: error,\n          },\n        };\n      }\n\n      return {\n        data: null as unknown as TData,\n        success: false,\n        error: {\n          code: \"NETWORK_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Build the full URL\n   *\n   * @param url - The URL or path to build the full URL from\n   * @returns The complete URL string\n   */\n  private buildUrl(url: string): string {\n    if (url.startsWith(\"http\")) {\n      return url;\n    }\n\n    const baseUrl = this.config.baseUrl.endsWith(\"/\")\n      ? this.config.baseUrl.slice(0, -1)\n      : this.config.baseUrl;\n    const path = url.startsWith(\"/\") ? url : `/${url}`;\n\n    return `${baseUrl}${path}`;\n  }\n\n  /**\n   * Build request options with defaults\n   *\n   * @param options - The request options to merge with defaults\n   * @returns The merged request options with defaults applied\n   */\n  private buildRequestOptions(options: RequestOptions): RequestOptions {\n    return {\n      method: \"GET\",\n      headers: {},\n      timeout: this.config.timeout,\n      ...options,\n    };\n  }\n\n  /**\n   * Get client statistics\n   *\n   * @returns Object containing client statistics and performance metrics\n   */\n  getStats() {\n    return {\n      rateLimiter: this.rateLimiter\n        ? {\n            remaining: this.rateLimiter.getRemainingRequests(),\n            resetTime: this.rateLimiter.getResetTime(),\n          }\n        : null,\n      circuitBreaker: this.circuitBreaker\n        ? {\n            state: this.circuitBreaker.getState(),\n            failures: this.circuitBreaker.getFailures(),\n          }\n        : null,\n      middleware: {\n        count: this.middleware.getMiddleware().length,\n      },\n    };\n  }\n\n  /**\n   * Reset client state\n   */\n  reset(): void {\n    this.circuitBreaker?.reset();\n    this.middleware.clear();\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/core/apiClient.ts"],"sourcesContent":["/**\n * Provides a generic HTTP client with enterprise-grade resilience features.\n *\n * @remarks\n * This module implements a robust API client with automatic retry, rate limiting,\n * circuit breaker pattern, and middleware support. It's used internally by the SDK\n * for all HTTP operations and can be extended for custom API integrations.\n *\n * **Architecture:**\n * - Middleware pipeline for request/response transformation\n * - Exponential backoff retry with configurable policies\n * - Token bucket rate limiting to prevent API throttling\n * - Circuit breaker to fail fast when services are down\n *\n * @category Networking\n * @module apiClient\n */\n\nimport type {\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n} from \"../types/generics\";\nimport {\n  RetryUtility,\n  RateLimiter,\n  MiddlewarePipeline,\n  CircuitBreaker,\n} from \"./generics\";\n\n/**\n * Configures the API client's behavior and resilience features.\n *\n * @remarks\n * Provides fine-grained control over HTTP client behavior including\n * retry strategies, rate limiting, and circuit breaker thresholds.\n *\n * @category Networking\n */\nexport interface ApiClientConfig {\n  /** Base URL for all requests */\n  baseUrl?: string;\n  /** Default headers */\n  headers?: Record<string, string>;\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Retry configuration */\n  retry?: RetryConfig;\n  /** Rate limiting configuration */\n  rateLimit?: RateLimiterConfig;\n  /** Circuit breaker configuration */\n  circuitBreaker?: {\n    failureThreshold: number;\n    recoveryTimeout: number;\n    halfOpenMaxAttempts?: number;\n  };\n}\n\n/**\n * Represents supported HTTP methods for API operations.\n *\n * @category Networking\n */\nexport type HttpMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\";\n\n/**\n * Configures individual HTTP request behavior.\n *\n * @remarks\n * Allows per-request overrides of client defaults including headers,\n * timeout, and resilience features. Use to customize specific requests\n * without affecting global configuration.\n *\n * @category Networking\n */\nexport interface RequestOptions {\n  /** HTTP method */\n  method?: HttpMethod;\n  /** Request headers */\n  headers?: Record<string, string>;\n  /** Query parameters */\n  params?: Record<string, unknown>;\n  /** Request timeout */\n  timeout?: number;\n  /** Skip retry for this request */\n  skipRetry?: boolean;\n  /** Skip rate limiting for this request */\n  skipRateLimit?: boolean;\n}\n\n/**\n * Provides resilient HTTP client functionality with enterprise features.\n *\n * @remarks\n * This client implements multiple resilience patterns to ensure reliable\n * API communication even under adverse conditions. It automatically handles\n * transient failures, rate limits, and service outages while providing\n * hooks for custom behavior through middleware.\n *\n * **Features:**\n * - Automatic retry with exponential backoff\n * - Rate limiting to prevent API throttling\n * - Circuit breaker for fast failure detection\n * - Middleware pipeline for request/response transformation\n * - Configurable timeouts and headers\n *\n * @example\n * ```typescript\n * // Create client with custom configuration\n * const client = new ApiClient({\n *   baseUrl: 'https://api.example.com',\n *   headers: { 'API-Key': 'secret' },\n *   retry: {\n *     maxAttempts: 5,\n *     baseDelay: 2000\n *   },\n *   rateLimit: {\n *     requestsPerWindow: 50,\n *     windowMs: 60000\n *   }\n * });\n *\n * // Add logging middleware\n * client.use(async (req, next) => {\n *   console.log(`Request: ${req.params.url}`);\n *   const res = await next(req);\n *   console.log(`Response: ${res.status}`);\n *   return res;\n * });\n *\n * // Make resilient API calls\n * const data = await client.get('/users');\n * ```\n *\n * @category Networking\n */\nexport class ApiClient {\n  private readonly config: Required<ApiClientConfig>;\n  private readonly middleware: MiddlewarePipeline;\n  private readonly rateLimiter?: RateLimiter;\n  private readonly circuitBreaker?: CircuitBreaker;\n\n  constructor(config: ApiClientConfig = {}) {\n    this.config = {\n      baseUrl: config.baseUrl ?? \"\",\n      headers: config.headers ?? {},\n      timeout: config.timeout ?? 30000,\n      retry: config.retry ?? {\n        maxAttempts: 3,\n        baseDelay: 1000,\n        backoffMultiplier: 2,\n        shouldRetry: (error) => error.message.includes(\"network\"),\n      },\n      rateLimit: config.rateLimit ?? {\n        requestsPerWindow: 100,\n        windowMs: 60000,\n      },\n      circuitBreaker: config.circuitBreaker ?? {\n        failureThreshold: 5,\n        recoveryTimeout: 60000,\n        halfOpenMaxAttempts: 3,\n      },\n    };\n\n    this.middleware = new MiddlewarePipeline();\n    this.rateLimiter = new RateLimiter(this.config.rateLimit);\n    this.circuitBreaker = new CircuitBreaker(this.config.circuitBreaker);\n  }\n\n  /**\n   * Adds middleware to the request processing pipeline.\n   *\n   * @remarks\n   * Middleware functions execute in order of registration and can transform\n   * requests, responses, or implement cross-cutting concerns like logging,\n   * authentication, or caching.\n   *\n   * @param middleware - The middleware function to add to the pipeline\n   *\n   * @example\n   * ```typescript\n   * // Add authentication middleware\n   * client.use(async (req, next) => {\n   *   req.options.headers = {\n   *     ...req.options.headers,\n   *     'Authorization': `Bearer ${getToken()}`\n   *   };\n   *   return next(req);\n   * });\n   *\n   * // Add response caching\n   * client.use(async (req, next) => {\n   *   const cached = cache.get(req.params.url);\n   *   if (cached) return cached;\n   *\n   *   const res = await next(req);\n   *   if (res.status === 'success') {\n   *     cache.set(req.params.url, res);\n   *   }\n   *   return res;\n   * });\n   * ```\n   */\n  use(middleware: Middleware): void {\n    this.middleware.use(middleware);\n  }\n\n  /**\n   * Executes an HTTP request with full resilience features.\n   *\n   * @remarks\n   * This is the core request method that applies all configured resilience\n   * patterns including retry, rate limiting, and circuit breaking. It processes\n   * the request through the middleware pipeline before execution.\n   *\n   * @param url - The URL to make the request to.\n   *   Can be relative (uses baseUrl) or absolute.\n   * @param options - Request options including method, headers, body, etc.\n   * @returns Promise resolving to the response data\n   *\n   * @throws {Error} When request fails after all retry attempts.\n   *   Check error message for details.\n   * @throws {Error} When circuit breaker is open.\n   *   Wait for recovery timeout before retrying.\n   *\n   * @example\n   * ```typescript\n   * const response = await client.request('/api/data', {\n   *   method: 'POST',\n   *   headers: { 'Content-Type': 'application/json' },\n   *   params: { name: 'John', age: 30 },\n   *   timeout: 5000\n   * });\n   * ```\n   */\n  async request<TData = unknown>(\n    url: string,\n    options: RequestOptions = {},\n  ): Promise<GenericResponse<TData>> {\n    const fullUrl = this.buildUrl(url);\n    const requestOptions = this.buildRequestOptions(options);\n\n    const request: GenericRequest<{\n      url: string;\n      options: RequestOptions;\n    }> = {\n      params: {\n        url: fullUrl,\n        options: requestOptions,\n      },\n      options: requestOptions,\n    };\n\n    // Apply rate limiting\n    if (!options.skipRateLimit && this.rateLimiter) {\n      await this.rateLimiter.waitForSlot();\n    }\n\n    // Execute with circuit breaker\n    if (this.circuitBreaker) {\n      return this.circuitBreaker.execute(() =>\n        this.executeRequest<TData>(request),\n      );\n    }\n\n    return this.executeRequest<TData>(request);\n  }\n\n  /**\n   * Make a GET request\n   *\n   * @param url - The URL to make the GET request to\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async get<TData = unknown>(\n    url: string,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, { ...options, method: \"GET\" });\n  }\n\n  /**\n   * Make a POST request\n   *\n   * @param url - The URL to make the POST request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async post<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Make a PUT request\n   *\n   * @param url - The URL to make the PUT request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async put<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"PUT\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Make a DELETE request\n   *\n   * @param url - The URL to make the DELETE request to\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async delete<TData = unknown>(\n    url: string,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, { ...options, method: \"DELETE\" });\n  }\n\n  /**\n   * Make a PATCH request\n   *\n   * @param url - The URL to make the PATCH request to\n   * @param data - The data to send in the request body\n   * @param options - Request options (excluding method)\n   * @returns Promise resolving to the response data\n   */\n  async patch<TData = unknown>(\n    url: string,\n    data?: unknown,\n    options: Omit<RequestOptions, \"method\"> = {},\n  ): Promise<GenericResponse<TData>> {\n    return this.request<TData>(url, {\n      ...options,\n      method: \"PATCH\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        ...options.headers,\n      },\n      params: data as Record<string, unknown>,\n    });\n  }\n\n  /**\n   * Execute the actual HTTP request with middleware and retry\n   *\n   * @param request - The generic request object containing URL and options\n   * @returns Promise resolving to the generic response with data\n   */\n  private async executeRequest<TData>(\n    request: GenericRequest<{ url: string; options: RequestOptions }>,\n  ): Promise<GenericResponse<TData>> {\n    const executeWithRetry = async (): Promise<GenericResponse<TData>> => {\n      try {\n        // Process request through middleware\n        const processedRequest = await this.middleware.processRequest(request);\n\n        // Make the actual HTTP request\n        const response = await this.makeHttpRequest<TData>(\n          (\n            processedRequest as GenericRequest<{\n              url: string;\n              options: RequestOptions;\n            }>\n          ).params.url,\n          (\n            processedRequest as GenericRequest<{\n              url: string;\n              options: RequestOptions;\n            }>\n          ).params.options,\n        );\n\n        // Process response through middleware\n        const processedResponse =\n          await this.middleware.processResponse(response);\n\n        return processedResponse;\n      } catch (error) {\n        // Try to handle error with middleware\n        const handledResponse = await this.middleware.handleError<\n          typeof request,\n          GenericResponse<TData>\n        >(error as Error, request);\n\n        if (handledResponse) {\n          return handledResponse;\n        }\n\n        throw error;\n      }\n    };\n\n    // Apply retry logic if not skipped\n    if (!request.params.options.skipRetry) {\n      return RetryUtility.withRetry(executeWithRetry, this.config.retry);\n    }\n\n    return executeWithRetry();\n  }\n\n  /**\n   * Make the actual HTTP request using fetch API\n   *\n   * @param url - The URL to make the request to\n   * @param options - The request options including method, headers, body, etc.\n   * @returns Promise resolving to the generic response with data\n   */\n  private async makeHttpRequest<TData>(\n    url: string,\n    options: RequestOptions,\n  ): Promise<GenericResponse<TData>> {\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => {\n      controller.abort();\n    }, options.timeout ?? this.config.timeout);\n\n    try {\n      const response = await fetch(url, {\n        method: options.method ?? \"GET\",\n        headers: {\n          ...this.config.headers,\n          ...options.headers,\n        },\n        signal: controller.signal,\n        // Add body for POST/PUT/PATCH requests\n        ...(options.method &&\n          [\"POST\", \"PUT\", \"PATCH\"].includes(options.method) && {\n            body: JSON.stringify(options.params),\n          }),\n      });\n\n      clearTimeout(timeoutId);\n\n      const responseData: unknown = await response.json();\n      const data = responseData as { message?: string; [key: string]: unknown };\n\n      if (!response.ok) {\n        return {\n          data: null as unknown as TData,\n          success: false,\n          error: {\n            code: response.status.toString(),\n            message: data.message ?? response.statusText,\n            details: data,\n          },\n        };\n      }\n\n      return {\n        data: responseData as TData,\n        success: true,\n        meta: {\n          status: response.status,\n          statusText: response.statusText,\n          headers: Object.fromEntries(response.headers.entries()),\n        },\n      };\n    } catch (error) {\n      clearTimeout(timeoutId);\n\n      if (error instanceof Error && error.name === \"AbortError\") {\n        return {\n          data: null as unknown as TData,\n          success: false,\n          error: {\n            code: \"TIMEOUT\",\n            message: \"Request timeout\",\n            details: error,\n          },\n        };\n      }\n\n      return {\n        data: null as unknown as TData,\n        success: false,\n        error: {\n          code: \"NETWORK_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Build the full URL\n   *\n   * @param url - The URL or path to build the full URL from\n   * @returns The complete URL string\n   */\n  private buildUrl(url: string): string {\n    if (url.startsWith(\"http\")) {\n      return url;\n    }\n\n    const baseUrl = this.config.baseUrl.endsWith(\"/\")\n      ? this.config.baseUrl.slice(0, -1)\n      : this.config.baseUrl;\n    const path = url.startsWith(\"/\") ? url : `/${url}`;\n\n    return `${baseUrl}${path}`;\n  }\n\n  /**\n   * Build request options with defaults\n   *\n   * @param options - The request options to merge with defaults\n   * @returns The merged request options with defaults applied\n   */\n  private buildRequestOptions(options: RequestOptions): RequestOptions {\n    return {\n      method: \"GET\",\n      headers: {},\n      timeout: this.config.timeout,\n      ...options,\n    };\n  }\n\n  /**\n   * Get client statistics\n   *\n   * @returns Object containing client statistics and performance metrics\n   */\n  getStats() {\n    return {\n      rateLimiter: this.rateLimiter\n        ? {\n            remaining: this.rateLimiter.getRemainingRequests(),\n            resetTime: this.rateLimiter.getResetTime(),\n          }\n        : null,\n      circuitBreaker: this.circuitBreaker\n        ? {\n            state: this.circuitBreaker.getState(),\n            failures: this.circuitBreaker.getFailures(),\n          }\n        : null,\n      middleware: {\n        count: this.middleware.getMiddleware().length,\n      },\n    };\n  }\n\n  /**\n   * Reset client state\n   */\n  reset(): void {\n    this.circuitBreaker?.reset();\n    this.middleware.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core/generics.cjs

@@ -34,12 +34,26 @@ class BaseController {
     this.context = context;
   }
   /**
-   * Execute a request with optional middleware pipeline
+   * Executes a request with optional middleware pipeline.
+   *
+   * @remarks
+   * Processes request through middleware chain, executes handler, and applies
+   * response middleware in reverse order. Handles errors through error middleware
+   * before failing the request.
    *
    * @param request - The generic request object containing parameters and metadata
    * @param handler - The function that processes the request parameters
    * @param middleware - Optional array of middleware functions to apply
    * @returns Promise resolving to a generic response object
+   *
+   * @example
+   * ```typescript
+   * const response = await this.executeRequest(
+   *   { params: { id: 123 }, options: {} },
+   *   async (params) => await fetchData(params.id),
+   *   [loggingMiddleware, cachingMiddleware]
+   * );
+   * ```
    */
   async executeRequest(request, handler, middleware = []) {
     try {
@@ -88,11 +102,24 @@ class BaseController {
     }
   }
   /**
-   * Validate parameters with optional custom validator
+   * Validates parameters with optional custom validator.
+   *
+   * @remarks
+   * Type guard that validates and asserts parameter types at runtime.
+   * Use for input validation in public API methods.
    *
    * @param params - The parameters to validate
    * @param validator - Optional function to validate parameter types
-   * @throws Error if validation fails, asserts type if successful
+   * @throws {Error} When validation fails.
+   *   Provide valid parameters matching expected type.
+   *
+   * @example
+   * ```typescript
+   * this.validateParams<MyParams>(params, (p): p is MyParams => {
+   *   return typeof p === 'object' && 'id' in p;
+   * });
+   * // TypeScript now knows params is MyParams
+   * ```
    */
   validateParams(params, validator) {
     if (validator && !validator(params)) {

package/dist/core/generics.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/generics.ts"],"sourcesContent":["import type {\n  Controller,\n  ControllerContext,\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n  Cache,\n  Observer,\n  Observable,\n} from \"../types/generics\";\n\n/**\n * Base controller class with common functionality\n */\nexport abstract class BaseController<\n  TContext extends ControllerContext = ControllerContext,\n> implements Controller<TContext>\n{\n  public readonly context: TContext;\n\n  constructor(context: TContext) {\n    this.context = context;\n  }\n\n  /**\n   * Execute a request with optional middleware pipeline\n   *\n   * @param request - The generic request object containing parameters and metadata\n   * @param handler - The function that processes the request parameters\n   * @param middleware - Optional array of middleware functions to apply\n   * @returns Promise resolving to a generic response object\n   */\n  protected async executeRequest<TParams, TResponse>(\n    request: GenericRequest<TParams>,\n    handler: (params: TParams) => Promise<TResponse>,\n    middleware: Middleware[] = [],\n  ): Promise<GenericResponse<TResponse>> {\n    try {\n      // Apply request middleware\n      let processedRequest = request;\n      for (const mw of middleware) {\n        if (mw.request) {\n          processedRequest = (await mw.request(\n            processedRequest,\n          )) as GenericRequest<TParams>;\n        }\n      }\n\n      // Execute handler\n      let response = await handler(processedRequest.params);\n\n      // Apply response middleware\n      for (const mw of middleware.reverse()) {\n        if (mw.response) {\n          response = (await mw.response(response)) as Awaited<TResponse>;\n        }\n      }\n\n      return {\n        data: response,\n        success: true,\n      };\n    } catch (error) {\n      // Handle errors with middleware\n      for (const mw of middleware) {\n        if (mw.error) {\n          const handled = await mw.error(error as Error, request);\n          if (handled) {\n            return {\n              data: handled as TResponse,\n              success: true,\n            };\n          }\n        }\n      }\n\n      return {\n        // TODO(TYPES): undefined coerced to TResponse for error case.\n        // Future improvement: Use discriminated union with success: false\n        // to properly type data as undefined when error occurs.\n        data: undefined as unknown as TResponse,\n        success: false,\n        error: {\n          code: \"EXECUTION_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Validate parameters with optional custom validator\n   *\n   * @param params - The parameters to validate\n   * @param validator - Optional function to validate parameter types\n   * @throws Error if validation fails, asserts type if successful\n   */\n  protected validateParams<T>(\n    params: unknown,\n    validator?: (params: unknown) => params is T,\n  ): asserts params is T {\n    if (validator && !validator(params)) {\n      throw new Error(\"Invalid parameters\");\n    }\n  }\n}\n\n/**\n * Generic retry utility with exponential backoff\n */\nexport class RetryUtility {\n  private static async delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  static async withRetry<T>(\n    operation: () => Promise<T>,\n    config: RetryConfig,\n  ): Promise<T> {\n    let lastError: Error | undefined;\n\n    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {\n      try {\n        return await operation();\n      } catch (error) {\n        lastError = error as Error;\n\n        // Check if we should retry\n        if (config.shouldRetry && !config.shouldRetry(lastError, attempt)) {\n          throw lastError;\n        }\n\n        // Don't delay on the last attempt\n        if (attempt === config.maxAttempts) {\n          break;\n        }\n\n        // Calculate delay with exponential backoff and jitter\n        const baseDelay =\n          config.baseDelay *\n          Math.pow(config.backoffMultiplier ?? 2, attempt - 1);\n        const maxDelay = config.maxDelay ?? 30000;\n        const jitter = config.jitter ?? 0;\n\n        let delay = Math.min(baseDelay, maxDelay);\n\n        if (jitter > 0) {\n          delay += Math.random() * jitter * delay;\n        }\n\n        await this.delay(delay);\n      }\n    }\n\n    throw lastError ?? new Error(\"Operation failed after retries\");\n  }\n}\n\n/**\n * Generic rate limiter\n */\nexport class RateLimiter {\n  private requests: number[] = [];\n\n  constructor(private config: RateLimiterConfig) {}\n\n  async checkLimit(): Promise<boolean> {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n\n    // Remove requests outside the window\n    this.requests = this.requests.filter((time) => time > windowStart);\n\n    // Check if we can make a request\n    if (this.requests.length < this.config.requestsPerWindow) {\n      this.requests.push(now);\n      return true;\n    }\n\n    return false;\n  }\n\n  async waitForSlot(): Promise<void> {\n    while (!(await this.checkLimit())) {\n      await new Promise((resolve) => setTimeout(resolve, 100));\n    }\n  }\n\n  getRemainingRequests(): number {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n    const activeRequests = this.requests.filter((time) => time > windowStart);\n    return Math.max(0, this.config.requestsPerWindow - activeRequests.length);\n  }\n\n  getResetTime(): number {\n    if (this.requests.length === 0) return 0;\n    return Math.max(0, this.requests[0] + this.config.windowMs - Date.now());\n  }\n}\n\n/**\n * Generic in-memory cache implementation\n */\nexport class MemoryCache<TKey = string, TValue = unknown>\n  implements Cache<TKey, TValue>\n{\n  private cache = new Map<TKey, { value: TValue; expiry?: number }>();\n\n  async get(key: TKey): Promise<TValue | undefined> {\n    const item = this.cache.get(key);\n\n    if (!item) return undefined;\n\n    // Check if expired\n    if (item.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    return item.value;\n  }\n\n  async set(key: TKey, value: TValue, ttl?: number): Promise<void> {\n    const expiry = ttl ? Date.now() + ttl : undefined;\n    this.cache.set(key, { value, expiry });\n  }\n\n  async delete(key: TKey): Promise<boolean> {\n    return this.cache.delete(key);\n  }\n\n  async clear(): Promise<void> {\n    this.cache.clear();\n  }\n\n  async has(key: TKey): Promise<boolean> {\n    const exists = this.cache.has(key);\n    if (!exists) return false;\n\n    // Check expiry\n    const item = this.cache.get(key);\n    if (item?.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  size(): number {\n    return this.cache.size;\n  }\n\n  keys(): TKey[] {\n    return Array.from(this.cache.keys());\n  }\n}\n\n/**\n * Generic event emitter implementation\n */\nexport class EventEmitter<TEvent = unknown> implements Observable<TEvent> {\n  private observers: Observer<TEvent>[] = [];\n\n  subscribe(observer: Observer<TEvent>): () => void {\n    this.observers.push(observer);\n\n    return () => {\n      this.unsubscribe(observer);\n    };\n  }\n\n  unsubscribe(observer: Observer<TEvent>): void {\n    const index = this.observers.indexOf(observer);\n    if (index > -1) {\n      this.observers.splice(index, 1);\n    }\n  }\n\n  emit(event: TEvent): void {\n    for (const observer of this.observers) {\n      try {\n        const result = observer.notify(event);\n        if (result instanceof Promise) {\n          result.catch((error) => {\n            console.error(\"Observer error:\", error);\n          });\n        }\n      } catch (error) {\n        console.error(\"Observer error:\", error);\n      }\n    }\n  }\n\n  getObserverCount(): number {\n    return this.observers.length;\n  }\n\n  removeAllObservers(): void {\n    this.observers = [];\n  }\n}\n\n/**\n * Generic middleware pipeline\n */\nexport class MiddlewarePipeline {\n  private middleware: Middleware<any, any>[] = [];\n\n  use(middleware: Middleware<any, any>): void {\n    this.middleware.push(middleware);\n  }\n\n  async processRequest<TRequest>(request: TRequest): Promise<TRequest> {\n    let processed = request;\n\n    for (const mw of this.middleware) {\n      if (mw.request) {\n        processed = await mw.request(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async processResponse<TResponse>(response: TResponse): Promise<TResponse> {\n    let processed = response;\n\n    // Process in reverse order\n    for (const mw of this.middleware.slice().reverse()) {\n      if (mw.response) {\n        processed = await mw.response(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async handleError<TRequest, TResponse>(\n    error: Error,\n    request: TRequest,\n  ): Promise<TResponse | void> {\n    for (const mw of this.middleware) {\n      if (mw.error) {\n        const result = await mw.error(error, request);\n        if (result) {\n          return result;\n        }\n      }\n    }\n  }\n\n  getMiddleware(): Middleware<any, any>[] {\n    return [...this.middleware];\n  }\n\n  clear(): void {\n    this.middleware = [];\n  }\n}\n\n/**\n * Generic async queue for managing concurrent operations\n */\nexport class AsyncQueue<T = unknown> {\n  private queue: Array<() => Promise<T>> = [];\n  private running = 0;\n\n  constructor(private concurrency = 1) {}\n\n  async add<R>(operation: () => Promise<R>): Promise<R> {\n    return new Promise((resolve, reject) => {\n      this.queue.push(async () => {\n        try {\n          const result = await operation();\n          resolve(result as unknown as R);\n          return result as unknown as T;\n        } catch (error) {\n          reject(error);\n          throw error;\n        } finally {\n          this.running--;\n          this.processQueue();\n        }\n      });\n\n      this.processQueue();\n    });\n  }\n\n  private processQueue(): void {\n    while (this.running < this.concurrency && this.queue.length > 0) {\n      const operation = this.queue.shift();\n      if (operation) {\n        this.running++;\n        operation().catch(() => {\n          // Error already handled in add method\n        });\n      }\n    }\n  }\n\n  get pending(): number {\n    return this.queue.length;\n  }\n\n  get active(): number {\n    return this.running;\n  }\n\n  get size(): number {\n    return this.queue.length + this.running;\n  }\n\n  clear(): void {\n    this.queue = [];\n  }\n}\n\n/**\n * Generic circuit breaker pattern\n */\nexport class CircuitBreaker {\n  private state: \"closed\" | \"open\" | \"half-open\" = \"closed\";\n  private failures = 0;\n  private lastFailureTime = 0;\n  private successes = 0;\n\n  constructor(\n    private config: {\n      failureThreshold: number;\n      recoveryTimeout: number;\n      halfOpenMaxAttempts?: number;\n    },\n  ) {}\n\n  async execute<TResult>(operation: () => Promise<TResult>): Promise<TResult> {\n    if (this.state === \"open\") {\n      if (Date.now() - this.lastFailureTime > this.config.recoveryTimeout) {\n        this.state = \"half-open\";\n        this.successes = 0;\n      } else {\n        throw new Error(\"Circuit breaker is open\");\n      }\n    }\n\n    try {\n      const result = await operation();\n      this.onSuccess();\n      return result;\n    } catch (error) {\n      this.onFailure();\n      throw error;\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n\n    if (this.state === \"half-open\") {\n      this.successes++;\n      if (this.successes >= (this.config.halfOpenMaxAttempts ?? 1)) {\n        this.state = \"closed\";\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    this.lastFailureTime = Date.now();\n\n    if (this.failures >= this.config.failureThreshold) {\n      this.state = \"open\";\n    }\n  }\n\n  getState(): string {\n    return this.state;\n  }\n\n  getFailures(): number {\n    return this.failures;\n  }\n\n  reset(): void {\n    this.state = \"closed\";\n    this.failures = 0;\n    this.successes = 0;\n    this.lastFailureTime = 0;\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/core/generics.ts"],"sourcesContent":["/**\n * Provides generic utilities for resilient SDK operations.\n *\n * @remarks\n * This module contains reusable patterns for building robust SDK features including\n * retry logic, rate limiting, circuit breakers, caching, and middleware pipelines.\n * These utilities follow enterprise patterns for fault tolerance and scalability.\n *\n * @category Infrastructure\n * @module generics\n */\n\nimport type {\n  Controller,\n  ControllerContext,\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n  Cache,\n  Observer,\n  Observable,\n} from \"../types/generics\";\n\n/**\n * Provides base controller functionality with middleware support.\n *\n * @remarks\n * Abstract base class for SDK controllers that provides request execution\n * with middleware pipeline, parameter validation, and error handling.\n * All SDK controllers extend this base for consistent behavior.\n *\n * @category Infrastructure\n */\nexport abstract class BaseController<\n  TContext extends ControllerContext = ControllerContext,\n> implements Controller<TContext>\n{\n  public readonly context: TContext;\n\n  constructor(context: TContext) {\n    this.context = context;\n  }\n\n  /**\n   * Executes a request with optional middleware pipeline.\n   *\n   * @remarks\n   * Processes request through middleware chain, executes handler, and applies\n   * response middleware in reverse order. Handles errors through error middleware\n   * before failing the request.\n   *\n   * @param request - The generic request object containing parameters and metadata\n   * @param handler - The function that processes the request parameters\n   * @param middleware - Optional array of middleware functions to apply\n   * @returns Promise resolving to a generic response object\n   *\n   * @example\n   * ```typescript\n   * const response = await this.executeRequest(\n   *   { params: { id: 123 }, options: {} },\n   *   async (params) => await fetchData(params.id),\n   *   [loggingMiddleware, cachingMiddleware]\n   * );\n   * ```\n   */\n  protected async executeRequest<TParams, TResponse>(\n    request: GenericRequest<TParams>,\n    handler: (params: TParams) => Promise<TResponse>,\n    middleware: Middleware[] = [],\n  ): Promise<GenericResponse<TResponse>> {\n    try {\n      // Apply request middleware\n      let processedRequest = request;\n      for (const mw of middleware) {\n        if (mw.request) {\n          processedRequest = (await mw.request(\n            processedRequest,\n          )) as GenericRequest<TParams>;\n        }\n      }\n\n      // Execute handler\n      let response = await handler(processedRequest.params);\n\n      // Apply response middleware\n      for (const mw of middleware.reverse()) {\n        if (mw.response) {\n          response = (await mw.response(response)) as Awaited<TResponse>;\n        }\n      }\n\n      return {\n        data: response,\n        success: true,\n      };\n    } catch (error) {\n      // Handle errors with middleware\n      for (const mw of middleware) {\n        if (mw.error) {\n          const handled = await mw.error(error as Error, request);\n          if (handled) {\n            return {\n              data: handled as TResponse,\n              success: true,\n            };\n          }\n        }\n      }\n\n      return {\n        // TODO(TYPES): undefined coerced to TResponse for error case.\n        // Future improvement: Use discriminated union with success: false\n        // to properly type data as undefined when error occurs.\n        data: undefined as unknown as TResponse,\n        success: false,\n        error: {\n          code: \"EXECUTION_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Validates parameters with optional custom validator.\n   *\n   * @remarks\n   * Type guard that validates and asserts parameter types at runtime.\n   * Use for input validation in public API methods.\n   *\n   * @param params - The parameters to validate\n   * @param validator - Optional function to validate parameter types\n   * @throws {Error} When validation fails.\n   *   Provide valid parameters matching expected type.\n   *\n   * @example\n   * ```typescript\n   * this.validateParams<MyParams>(params, (p): p is MyParams => {\n   *   return typeof p === 'object' && 'id' in p;\n   * });\n   * // TypeScript now knows params is MyParams\n   * ```\n   */\n  protected validateParams<T>(\n    params: unknown,\n    validator?: (params: unknown) => params is T,\n  ): asserts params is T {\n    if (validator && !validator(params)) {\n      throw new Error(\"Invalid parameters\");\n    }\n  }\n}\n\n/**\n * Implements retry logic with exponential backoff and jitter.\n *\n * @remarks\n * Provides configurable retry behavior for transient failures with\n * exponential backoff, maximum delay caps, and optional jitter to\n * prevent thundering herd problems.\n *\n * @example\n * ```typescript\n * const result = await RetryUtility.withRetry(\n *   async () => await unreliableOperation(),\n *   {\n *     maxAttempts: 5,\n *     baseDelay: 1000,\n *     backoffMultiplier: 2,\n *     maxDelay: 30000,\n *     shouldRetry: (error) => error.code === 'NETWORK_ERROR'\n *   }\n * );\n * ```\n *\n * @category Infrastructure\n */\nexport class RetryUtility {\n  private static async delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  static async withRetry<T>(\n    operation: () => Promise<T>,\n    config: RetryConfig,\n  ): Promise<T> {\n    let lastError: Error | undefined;\n\n    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {\n      try {\n        return await operation();\n      } catch (error) {\n        lastError = error as Error;\n\n        // Check if we should retry\n        if (config.shouldRetry && !config.shouldRetry(lastError, attempt)) {\n          throw lastError;\n        }\n\n        // Don't delay on the last attempt\n        if (attempt === config.maxAttempts) {\n          break;\n        }\n\n        // Calculate delay with exponential backoff and jitter\n        const baseDelay =\n          config.baseDelay *\n          Math.pow(config.backoffMultiplier ?? 2, attempt - 1);\n        const maxDelay = config.maxDelay ?? 30000;\n        const jitter = config.jitter ?? 0;\n\n        let delay = Math.min(baseDelay, maxDelay);\n\n        if (jitter > 0) {\n          delay += Math.random() * jitter * delay;\n        }\n\n        await this.delay(delay);\n      }\n    }\n\n    throw lastError ?? new Error(\"Operation failed after retries\");\n  }\n}\n\n/**\n * Implements token bucket rate limiting for API calls.\n *\n * @remarks\n * Prevents API throttling by limiting requests per time window.\n * Uses sliding window algorithm for smooth rate limiting without\n * burst spikes at window boundaries.\n *\n * @example\n * ```typescript\n * const limiter = new RateLimiter({\n *   requestsPerWindow: 100,\n *   windowMs: 60000 // 100 requests per minute\n * });\n *\n * // Check before making request\n * if (await limiter.checkLimit()) {\n *   await makeApiCall();\n * } else {\n *   await limiter.waitForSlot();\n *   await makeApiCall();\n * }\n * ```\n *\n * @category Infrastructure\n */\nexport class RateLimiter {\n  private requests: number[] = [];\n\n  constructor(private config: RateLimiterConfig) {}\n\n  async checkLimit(): Promise<boolean> {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n\n    // Remove requests outside the window\n    this.requests = this.requests.filter((time) => time > windowStart);\n\n    // Check if we can make a request\n    if (this.requests.length < this.config.requestsPerWindow) {\n      this.requests.push(now);\n      return true;\n    }\n\n    return false;\n  }\n\n  async waitForSlot(): Promise<void> {\n    while (!(await this.checkLimit())) {\n      await new Promise((resolve) => setTimeout(resolve, 100));\n    }\n  }\n\n  getRemainingRequests(): number {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n    const activeRequests = this.requests.filter((time) => time > windowStart);\n    return Math.max(0, this.config.requestsPerWindow - activeRequests.length);\n  }\n\n  getResetTime(): number {\n    if (this.requests.length === 0) return 0;\n    return Math.max(0, this.requests[0] + this.config.windowMs - Date.now());\n  }\n}\n\n/**\n * Generic in-memory cache implementation\n */\nexport class MemoryCache<TKey = string, TValue = unknown>\n  implements Cache<TKey, TValue>\n{\n  private cache = new Map<TKey, { value: TValue; expiry?: number }>();\n\n  async get(key: TKey): Promise<TValue | undefined> {\n    const item = this.cache.get(key);\n\n    if (!item) return undefined;\n\n    // Check if expired\n    if (item.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    return item.value;\n  }\n\n  async set(key: TKey, value: TValue, ttl?: number): Promise<void> {\n    const expiry = ttl ? Date.now() + ttl : undefined;\n    this.cache.set(key, { value, expiry });\n  }\n\n  async delete(key: TKey): Promise<boolean> {\n    return this.cache.delete(key);\n  }\n\n  async clear(): Promise<void> {\n    this.cache.clear();\n  }\n\n  async has(key: TKey): Promise<boolean> {\n    const exists = this.cache.has(key);\n    if (!exists) return false;\n\n    // Check expiry\n    const item = this.cache.get(key);\n    if (item?.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  size(): number {\n    return this.cache.size;\n  }\n\n  keys(): TKey[] {\n    return Array.from(this.cache.keys());\n  }\n}\n\n/**\n * Generic event emitter implementation\n */\nexport class EventEmitter<TEvent = unknown> implements Observable<TEvent> {\n  private observers: Observer<TEvent>[] = [];\n\n  subscribe(observer: Observer<TEvent>): () => void {\n    this.observers.push(observer);\n\n    return () => {\n      this.unsubscribe(observer);\n    };\n  }\n\n  unsubscribe(observer: Observer<TEvent>): void {\n    const index = this.observers.indexOf(observer);\n    if (index > -1) {\n      this.observers.splice(index, 1);\n    }\n  }\n\n  emit(event: TEvent): void {\n    for (const observer of this.observers) {\n      try {\n        const result = observer.notify(event);\n        if (result instanceof Promise) {\n          result.catch((error) => {\n            console.error(\"Observer error:\", error);\n          });\n        }\n      } catch (error) {\n        console.error(\"Observer error:\", error);\n      }\n    }\n  }\n\n  getObserverCount(): number {\n    return this.observers.length;\n  }\n\n  removeAllObservers(): void {\n    this.observers = [];\n  }\n}\n\n/**\n * Generic middleware pipeline\n */\nexport class MiddlewarePipeline {\n  private middleware: Middleware<any, any>[] = [];\n\n  use(middleware: Middleware<any, any>): void {\n    this.middleware.push(middleware);\n  }\n\n  async processRequest<TRequest>(request: TRequest): Promise<TRequest> {\n    let processed = request;\n\n    for (const mw of this.middleware) {\n      if (mw.request) {\n        processed = await mw.request(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async processResponse<TResponse>(response: TResponse): Promise<TResponse> {\n    let processed = response;\n\n    // Process in reverse order\n    for (const mw of this.middleware.slice().reverse()) {\n      if (mw.response) {\n        processed = await mw.response(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async handleError<TRequest, TResponse>(\n    error: Error,\n    request: TRequest,\n  ): Promise<TResponse | void> {\n    for (const mw of this.middleware) {\n      if (mw.error) {\n        const result = await mw.error(error, request);\n        if (result) {\n          return result;\n        }\n      }\n    }\n  }\n\n  getMiddleware(): Middleware<any, any>[] {\n    return [...this.middleware];\n  }\n\n  clear(): void {\n    this.middleware = [];\n  }\n}\n\n/**\n * Generic async queue for managing concurrent operations\n */\nexport class AsyncQueue<T = unknown> {\n  private queue: Array<() => Promise<T>> = [];\n  private running = 0;\n\n  constructor(private concurrency = 1) {}\n\n  async add<R>(operation: () => Promise<R>): Promise<R> {\n    return new Promise((resolve, reject) => {\n      this.queue.push(async () => {\n        try {\n          const result = await operation();\n          resolve(result as unknown as R);\n          return result as unknown as T;\n        } catch (error) {\n          reject(error);\n          throw error;\n        } finally {\n          this.running--;\n          this.processQueue();\n        }\n      });\n\n      this.processQueue();\n    });\n  }\n\n  private processQueue(): void {\n    while (this.running < this.concurrency && this.queue.length > 0) {\n      const operation = this.queue.shift();\n      if (operation) {\n        this.running++;\n        operation().catch(() => {\n          // Error already handled in add method\n        });\n      }\n    }\n  }\n\n  get pending(): number {\n    return this.queue.length;\n  }\n\n  get active(): number {\n    return this.running;\n  }\n\n  get size(): number {\n    return this.queue.length + this.running;\n  }\n\n  clear(): void {\n    this.queue = [];\n  }\n}\n\n/**\n * Generic circuit breaker pattern\n */\nexport class CircuitBreaker {\n  private state: \"closed\" | \"open\" | \"half-open\" = \"closed\";\n  private failures = 0;\n  private lastFailureTime = 0;\n  private successes = 0;\n\n  constructor(\n    private config: {\n      failureThreshold: number;\n      recoveryTimeout: number;\n      halfOpenMaxAttempts?: number;\n    },\n  ) {}\n\n  async execute<TResult>(operation: () => Promise<TResult>): Promise<TResult> {\n    if (this.state === \"open\") {\n      if (Date.now() - this.lastFailureTime > this.config.recoveryTimeout) {\n        this.state = \"half-open\";\n        this.successes = 0;\n      } else {\n        throw new Error(\"Circuit breaker is open\");\n      }\n    }\n\n    try {\n      const result = await operation();\n      this.onSuccess();\n      return result;\n    } catch (error) {\n      this.onFailure();\n      throw error;\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n\n    if (this.state === \"half-open\") {\n      this.successes++;\n      if (this.successes >= (this.config.halfOpenMaxAttempts ?? 1)) {\n        this.state = \"closed\";\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    this.lastFailureTime = Date.now();\n\n    if (this.failures >= this.config.failureThreshold) {\n      this.state = \"open\";\n    }\n  }\n\n  getState(): string {\n    return this.state;\n  }\n\n  getFailures(): number {\n    return this.failures;\n  }\n\n  reset(): void {\n    this.state = \"closed\";\n    this.failures = 0;\n    this.successes = 0;\n    this.lastFailureTime = 0;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core/generics.d.ts

@@ -1,37 +1,126 @@
+/**
+ * Provides generic utilities for resilient SDK operations.
+ *
+ * @remarks
+ * This module contains reusable patterns for building robust SDK features including
+ * retry logic, rate limiting, circuit breakers, caching, and middleware pipelines.
+ * These utilities follow enterprise patterns for fault tolerance and scalability.
+ *
+ * @category Infrastructure
+ * @module generics
+ */
 import type { Controller, ControllerContext, GenericRequest, GenericResponse, RetryConfig, RateLimiterConfig, Middleware, Cache, Observer, Observable } from "../types/generics";
 /**
- * Base controller class with common functionality
+ * Provides base controller functionality with middleware support.
+ *
+ * @remarks
+ * Abstract base class for SDK controllers that provides request execution
+ * with middleware pipeline, parameter validation, and error handling.
+ * All SDK controllers extend this base for consistent behavior.
+ *
+ * @category Infrastructure
  */
 export declare abstract class BaseController<TContext extends ControllerContext = ControllerContext> implements Controller<TContext> {
     readonly context: TContext;
     constructor(context: TContext);
     /**
-     * Execute a request with optional middleware pipeline
+     * Executes a request with optional middleware pipeline.
+     *
+     * @remarks
+     * Processes request through middleware chain, executes handler, and applies
+     * response middleware in reverse order. Handles errors through error middleware
+     * before failing the request.
      *
      * @param request - The generic request object containing parameters and metadata
      * @param handler - The function that processes the request parameters
      * @param middleware - Optional array of middleware functions to apply
      * @returns Promise resolving to a generic response object
+     *
+     * @example
+     * ```typescript
+     * const response = await this.executeRequest(
+     *   { params: { id: 123 }, options: {} },
+     *   async (params) => await fetchData(params.id),
+     *   [loggingMiddleware, cachingMiddleware]
+     * );
+     * ```
      */
     protected executeRequest<TParams, TResponse>(request: GenericRequest<TParams>, handler: (params: TParams) => Promise<TResponse>, middleware?: Middleware[]): Promise<GenericResponse<TResponse>>;
     /**
-     * Validate parameters with optional custom validator
+     * Validates parameters with optional custom validator.
+     *
+     * @remarks
+     * Type guard that validates and asserts parameter types at runtime.
+     * Use for input validation in public API methods.
      *
      * @param params - The parameters to validate
      * @param validator - Optional function to validate parameter types
-     * @throws Error if validation fails, asserts type if successful
+     * @throws {Error} When validation fails.
+     *   Provide valid parameters matching expected type.
+     *
+     * @example
+     * ```typescript
+     * this.validateParams<MyParams>(params, (p): p is MyParams => {
+     *   return typeof p === 'object' && 'id' in p;
+     * });
+     * // TypeScript now knows params is MyParams
+     * ```
      */
     protected validateParams<T>(params: unknown, validator?: (params: unknown) => params is T): asserts params is T;
 }
 /**
- * Generic retry utility with exponential backoff
+ * Implements retry logic with exponential backoff and jitter.
+ *
+ * @remarks
+ * Provides configurable retry behavior for transient failures with
+ * exponential backoff, maximum delay caps, and optional jitter to
+ * prevent thundering herd problems.
+ *
+ * @example
+ * ```typescript
+ * const result = await RetryUtility.withRetry(
+ *   async () => await unreliableOperation(),
+ *   {
+ *     maxAttempts: 5,
+ *     baseDelay: 1000,
+ *     backoffMultiplier: 2,
+ *     maxDelay: 30000,
+ *     shouldRetry: (error) => error.code === 'NETWORK_ERROR'
+ *   }
+ * );
+ * ```
+ *
+ * @category Infrastructure
  */
 export declare class RetryUtility {
     private static delay;
     static withRetry<T>(operation: () => Promise<T>, config: RetryConfig): Promise<T>;
 }
 /**
- * Generic rate limiter
+ * Implements token bucket rate limiting for API calls.
+ *
+ * @remarks
+ * Prevents API throttling by limiting requests per time window.
+ * Uses sliding window algorithm for smooth rate limiting without
+ * burst spikes at window boundaries.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({
+ *   requestsPerWindow: 100,
+ *   windowMs: 60000 // 100 requests per minute
+ * });
+ *
+ * // Check before making request
+ * if (await limiter.checkLimit()) {
+ *   await makeApiCall();
+ * } else {
+ *   await limiter.waitForSlot();
+ *   await makeApiCall();
+ * }
+ * ```
+ *
+ * @category Infrastructure
  */
 export declare class RateLimiter {
     private config;

package/dist/core/generics.js

@@ -4,12 +4,26 @@ class BaseController {
     this.context = context;
   }
   /**
-   * Execute a request with optional middleware pipeline
+   * Executes a request with optional middleware pipeline.
+   *
+   * @remarks
+   * Processes request through middleware chain, executes handler, and applies
+   * response middleware in reverse order. Handles errors through error middleware
+   * before failing the request.
    *
    * @param request - The generic request object containing parameters and metadata
    * @param handler - The function that processes the request parameters
    * @param middleware - Optional array of middleware functions to apply
    * @returns Promise resolving to a generic response object
+   *
+   * @example
+   * ```typescript
+   * const response = await this.executeRequest(
+   *   { params: { id: 123 }, options: {} },
+   *   async (params) => await fetchData(params.id),
+   *   [loggingMiddleware, cachingMiddleware]
+   * );
+   * ```
    */
   async executeRequest(request, handler, middleware = []) {
     try {
@@ -58,11 +72,24 @@ class BaseController {
     }
   }
   /**
-   * Validate parameters with optional custom validator
+   * Validates parameters with optional custom validator.
+   *
+   * @remarks
+   * Type guard that validates and asserts parameter types at runtime.
+   * Use for input validation in public API methods.
    *
    * @param params - The parameters to validate
    * @param validator - Optional function to validate parameter types
-   * @throws Error if validation fails, asserts type if successful
+   * @throws {Error} When validation fails.
+   *   Provide valid parameters matching expected type.
+   *
+   * @example
+   * ```typescript
+   * this.validateParams<MyParams>(params, (p): p is MyParams => {
+   *   return typeof p === 'object' && 'id' in p;
+   * });
+   * // TypeScript now knows params is MyParams
+   * ```
    */
   validateParams(params, validator) {
     if (validator && !validator(params)) {

package/dist/core/generics.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/generics.ts"],"sourcesContent":["import type {\n  Controller,\n  ControllerContext,\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n  Cache,\n  Observer,\n  Observable,\n} from \"../types/generics\";\n\n/**\n * Base controller class with common functionality\n */\nexport abstract class BaseController<\n  TContext extends ControllerContext = ControllerContext,\n> implements Controller<TContext>\n{\n  public readonly context: TContext;\n\n  constructor(context: TContext) {\n    this.context = context;\n  }\n\n  /**\n   * Execute a request with optional middleware pipeline\n   *\n   * @param request - The generic request object containing parameters and metadata\n   * @param handler - The function that processes the request parameters\n   * @param middleware - Optional array of middleware functions to apply\n   * @returns Promise resolving to a generic response object\n   */\n  protected async executeRequest<TParams, TResponse>(\n    request: GenericRequest<TParams>,\n    handler: (params: TParams) => Promise<TResponse>,\n    middleware: Middleware[] = [],\n  ): Promise<GenericResponse<TResponse>> {\n    try {\n      // Apply request middleware\n      let processedRequest = request;\n      for (const mw of middleware) {\n        if (mw.request) {\n          processedRequest = (await mw.request(\n            processedRequest,\n          )) as GenericRequest<TParams>;\n        }\n      }\n\n      // Execute handler\n      let response = await handler(processedRequest.params);\n\n      // Apply response middleware\n      for (const mw of middleware.reverse()) {\n        if (mw.response) {\n          response = (await mw.response(response)) as Awaited<TResponse>;\n        }\n      }\n\n      return {\n        data: response,\n        success: true,\n      };\n    } catch (error) {\n      // Handle errors with middleware\n      for (const mw of middleware) {\n        if (mw.error) {\n          const handled = await mw.error(error as Error, request);\n          if (handled) {\n            return {\n              data: handled as TResponse,\n              success: true,\n            };\n          }\n        }\n      }\n\n      return {\n        // TODO(TYPES): undefined coerced to TResponse for error case.\n        // Future improvement: Use discriminated union with success: false\n        // to properly type data as undefined when error occurs.\n        data: undefined as unknown as TResponse,\n        success: false,\n        error: {\n          code: \"EXECUTION_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Validate parameters with optional custom validator\n   *\n   * @param params - The parameters to validate\n   * @param validator - Optional function to validate parameter types\n   * @throws Error if validation fails, asserts type if successful\n   */\n  protected validateParams<T>(\n    params: unknown,\n    validator?: (params: unknown) => params is T,\n  ): asserts params is T {\n    if (validator && !validator(params)) {\n      throw new Error(\"Invalid parameters\");\n    }\n  }\n}\n\n/**\n * Generic retry utility with exponential backoff\n */\nexport class RetryUtility {\n  private static async delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  static async withRetry<T>(\n    operation: () => Promise<T>,\n    config: RetryConfig,\n  ): Promise<T> {\n    let lastError: Error | undefined;\n\n    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {\n      try {\n        return await operation();\n      } catch (error) {\n        lastError = error as Error;\n\n        // Check if we should retry\n        if (config.shouldRetry && !config.shouldRetry(lastError, attempt)) {\n          throw lastError;\n        }\n\n        // Don't delay on the last attempt\n        if (attempt === config.maxAttempts) {\n          break;\n        }\n\n        // Calculate delay with exponential backoff and jitter\n        const baseDelay =\n          config.baseDelay *\n          Math.pow(config.backoffMultiplier ?? 2, attempt - 1);\n        const maxDelay = config.maxDelay ?? 30000;\n        const jitter = config.jitter ?? 0;\n\n        let delay = Math.min(baseDelay, maxDelay);\n\n        if (jitter > 0) {\n          delay += Math.random() * jitter * delay;\n        }\n\n        await this.delay(delay);\n      }\n    }\n\n    throw lastError ?? new Error(\"Operation failed after retries\");\n  }\n}\n\n/**\n * Generic rate limiter\n */\nexport class RateLimiter {\n  private requests: number[] = [];\n\n  constructor(private config: RateLimiterConfig) {}\n\n  async checkLimit(): Promise<boolean> {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n\n    // Remove requests outside the window\n    this.requests = this.requests.filter((time) => time > windowStart);\n\n    // Check if we can make a request\n    if (this.requests.length < this.config.requestsPerWindow) {\n      this.requests.push(now);\n      return true;\n    }\n\n    return false;\n  }\n\n  async waitForSlot(): Promise<void> {\n    while (!(await this.checkLimit())) {\n      await new Promise((resolve) => setTimeout(resolve, 100));\n    }\n  }\n\n  getRemainingRequests(): number {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n    const activeRequests = this.requests.filter((time) => time > windowStart);\n    return Math.max(0, this.config.requestsPerWindow - activeRequests.length);\n  }\n\n  getResetTime(): number {\n    if (this.requests.length === 0) return 0;\n    return Math.max(0, this.requests[0] + this.config.windowMs - Date.now());\n  }\n}\n\n/**\n * Generic in-memory cache implementation\n */\nexport class MemoryCache<TKey = string, TValue = unknown>\n  implements Cache<TKey, TValue>\n{\n  private cache = new Map<TKey, { value: TValue; expiry?: number }>();\n\n  async get(key: TKey): Promise<TValue | undefined> {\n    const item = this.cache.get(key);\n\n    if (!item) return undefined;\n\n    // Check if expired\n    if (item.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    return item.value;\n  }\n\n  async set(key: TKey, value: TValue, ttl?: number): Promise<void> {\n    const expiry = ttl ? Date.now() + ttl : undefined;\n    this.cache.set(key, { value, expiry });\n  }\n\n  async delete(key: TKey): Promise<boolean> {\n    return this.cache.delete(key);\n  }\n\n  async clear(): Promise<void> {\n    this.cache.clear();\n  }\n\n  async has(key: TKey): Promise<boolean> {\n    const exists = this.cache.has(key);\n    if (!exists) return false;\n\n    // Check expiry\n    const item = this.cache.get(key);\n    if (item?.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  size(): number {\n    return this.cache.size;\n  }\n\n  keys(): TKey[] {\n    return Array.from(this.cache.keys());\n  }\n}\n\n/**\n * Generic event emitter implementation\n */\nexport class EventEmitter<TEvent = unknown> implements Observable<TEvent> {\n  private observers: Observer<TEvent>[] = [];\n\n  subscribe(observer: Observer<TEvent>): () => void {\n    this.observers.push(observer);\n\n    return () => {\n      this.unsubscribe(observer);\n    };\n  }\n\n  unsubscribe(observer: Observer<TEvent>): void {\n    const index = this.observers.indexOf(observer);\n    if (index > -1) {\n      this.observers.splice(index, 1);\n    }\n  }\n\n  emit(event: TEvent): void {\n    for (const observer of this.observers) {\n      try {\n        const result = observer.notify(event);\n        if (result instanceof Promise) {\n          result.catch((error) => {\n            console.error(\"Observer error:\", error);\n          });\n        }\n      } catch (error) {\n        console.error(\"Observer error:\", error);\n      }\n    }\n  }\n\n  getObserverCount(): number {\n    return this.observers.length;\n  }\n\n  removeAllObservers(): void {\n    this.observers = [];\n  }\n}\n\n/**\n * Generic middleware pipeline\n */\nexport class MiddlewarePipeline {\n  private middleware: Middleware<any, any>[] = [];\n\n  use(middleware: Middleware<any, any>): void {\n    this.middleware.push(middleware);\n  }\n\n  async processRequest<TRequest>(request: TRequest): Promise<TRequest> {\n    let processed = request;\n\n    for (const mw of this.middleware) {\n      if (mw.request) {\n        processed = await mw.request(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async processResponse<TResponse>(response: TResponse): Promise<TResponse> {\n    let processed = response;\n\n    // Process in reverse order\n    for (const mw of this.middleware.slice().reverse()) {\n      if (mw.response) {\n        processed = await mw.response(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async handleError<TRequest, TResponse>(\n    error: Error,\n    request: TRequest,\n  ): Promise<TResponse | void> {\n    for (const mw of this.middleware) {\n      if (mw.error) {\n        const result = await mw.error(error, request);\n        if (result) {\n          return result;\n        }\n      }\n    }\n  }\n\n  getMiddleware(): Middleware<any, any>[] {\n    return [...this.middleware];\n  }\n\n  clear(): void {\n    this.middleware = [];\n  }\n}\n\n/**\n * Generic async queue for managing concurrent operations\n */\nexport class AsyncQueue<T = unknown> {\n  private queue: Array<() => Promise<T>> = [];\n  private running = 0;\n\n  constructor(private concurrency = 1) {}\n\n  async add<R>(operation: () => Promise<R>): Promise<R> {\n    return new Promise((resolve, reject) => {\n      this.queue.push(async () => {\n        try {\n          const result = await operation();\n          resolve(result as unknown as R);\n          return result as unknown as T;\n        } catch (error) {\n          reject(error);\n          throw error;\n        } finally {\n          this.running--;\n          this.processQueue();\n        }\n      });\n\n      this.processQueue();\n    });\n  }\n\n  private processQueue(): void {\n    while (this.running < this.concurrency && this.queue.length > 0) {\n      const operation = this.queue.shift();\n      if (operation) {\n        this.running++;\n        operation().catch(() => {\n          // Error already handled in add method\n        });\n      }\n    }\n  }\n\n  get pending(): number {\n    return this.queue.length;\n  }\n\n  get active(): number {\n    return this.running;\n  }\n\n  get size(): number {\n    return this.queue.length + this.running;\n  }\n\n  clear(): void {\n    this.queue = [];\n  }\n}\n\n/**\n * Generic circuit breaker pattern\n */\nexport class CircuitBreaker {\n  private state: \"closed\" | \"open\" | \"half-open\" = \"closed\";\n  private failures = 0;\n  private lastFailureTime = 0;\n  private successes = 0;\n\n  constructor(\n    private config: {\n      failureThreshold: number;\n      recoveryTimeout: number;\n      halfOpenMaxAttempts?: number;\n    },\n  ) {}\n\n  async execute<TResult>(operation: () => Promise<TResult>): Promise<TResult> {\n    if (this.state === \"open\") {\n      if (Date.now() - this.lastFailureTime > this.config.recoveryTimeout) {\n        this.state = \"half-open\";\n        this.successes = 0;\n      } else {\n        throw new Error(\"Circuit breaker is open\");\n      }\n    }\n\n    try {\n      const result = await operation();\n      this.onSuccess();\n      return result;\n    } catch (error) {\n      this.onFailure();\n      throw error;\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n\n    if (this.state === \"half-open\") {\n      this.successes++;\n      if (this.successes >= (this.config.halfOpenMaxAttempts ?? 1)) {\n        this.state = \"closed\";\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    this.lastFailureTime = Date.now();\n\n    if (this.failures >= this.config.failureThreshold) {\n      this.state = \"open\";\n    }\n  }\n\n  getState(): string {\n    return this.state;\n  }\n\n  getFailures(): number {\n    return this.failures;\n  }\n\n  reset(): void {\n    this.state = \"closed\";\n    this.failures = 0;\n    this.successes = 0;\n    this.lastFailureTime = 0;\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/core/generics.ts"],"sourcesContent":["/**\n * Provides generic utilities for resilient SDK operations.\n *\n * @remarks\n * This module contains reusable patterns for building robust SDK features including\n * retry logic, rate limiting, circuit breakers, caching, and middleware pipelines.\n * These utilities follow enterprise patterns for fault tolerance and scalability.\n *\n * @category Infrastructure\n * @module generics\n */\n\nimport type {\n  Controller,\n  ControllerContext,\n  GenericRequest,\n  GenericResponse,\n  RetryConfig,\n  RateLimiterConfig,\n  Middleware,\n  Cache,\n  Observer,\n  Observable,\n} from \"../types/generics\";\n\n/**\n * Provides base controller functionality with middleware support.\n *\n * @remarks\n * Abstract base class for SDK controllers that provides request execution\n * with middleware pipeline, parameter validation, and error handling.\n * All SDK controllers extend this base for consistent behavior.\n *\n * @category Infrastructure\n */\nexport abstract class BaseController<\n  TContext extends ControllerContext = ControllerContext,\n> implements Controller<TContext>\n{\n  public readonly context: TContext;\n\n  constructor(context: TContext) {\n    this.context = context;\n  }\n\n  /**\n   * Executes a request with optional middleware pipeline.\n   *\n   * @remarks\n   * Processes request through middleware chain, executes handler, and applies\n   * response middleware in reverse order. Handles errors through error middleware\n   * before failing the request.\n   *\n   * @param request - The generic request object containing parameters and metadata\n   * @param handler - The function that processes the request parameters\n   * @param middleware - Optional array of middleware functions to apply\n   * @returns Promise resolving to a generic response object\n   *\n   * @example\n   * ```typescript\n   * const response = await this.executeRequest(\n   *   { params: { id: 123 }, options: {} },\n   *   async (params) => await fetchData(params.id),\n   *   [loggingMiddleware, cachingMiddleware]\n   * );\n   * ```\n   */\n  protected async executeRequest<TParams, TResponse>(\n    request: GenericRequest<TParams>,\n    handler: (params: TParams) => Promise<TResponse>,\n    middleware: Middleware[] = [],\n  ): Promise<GenericResponse<TResponse>> {\n    try {\n      // Apply request middleware\n      let processedRequest = request;\n      for (const mw of middleware) {\n        if (mw.request) {\n          processedRequest = (await mw.request(\n            processedRequest,\n          )) as GenericRequest<TParams>;\n        }\n      }\n\n      // Execute handler\n      let response = await handler(processedRequest.params);\n\n      // Apply response middleware\n      for (const mw of middleware.reverse()) {\n        if (mw.response) {\n          response = (await mw.response(response)) as Awaited<TResponse>;\n        }\n      }\n\n      return {\n        data: response,\n        success: true,\n      };\n    } catch (error) {\n      // Handle errors with middleware\n      for (const mw of middleware) {\n        if (mw.error) {\n          const handled = await mw.error(error as Error, request);\n          if (handled) {\n            return {\n              data: handled as TResponse,\n              success: true,\n            };\n          }\n        }\n      }\n\n      return {\n        // TODO(TYPES): undefined coerced to TResponse for error case.\n        // Future improvement: Use discriminated union with success: false\n        // to properly type data as undefined when error occurs.\n        data: undefined as unknown as TResponse,\n        success: false,\n        error: {\n          code: \"EXECUTION_ERROR\",\n          message: error instanceof Error ? error.message : \"Unknown error\",\n          details: error,\n        },\n      };\n    }\n  }\n\n  /**\n   * Validates parameters with optional custom validator.\n   *\n   * @remarks\n   * Type guard that validates and asserts parameter types at runtime.\n   * Use for input validation in public API methods.\n   *\n   * @param params - The parameters to validate\n   * @param validator - Optional function to validate parameter types\n   * @throws {Error} When validation fails.\n   *   Provide valid parameters matching expected type.\n   *\n   * @example\n   * ```typescript\n   * this.validateParams<MyParams>(params, (p): p is MyParams => {\n   *   return typeof p === 'object' && 'id' in p;\n   * });\n   * // TypeScript now knows params is MyParams\n   * ```\n   */\n  protected validateParams<T>(\n    params: unknown,\n    validator?: (params: unknown) => params is T,\n  ): asserts params is T {\n    if (validator && !validator(params)) {\n      throw new Error(\"Invalid parameters\");\n    }\n  }\n}\n\n/**\n * Implements retry logic with exponential backoff and jitter.\n *\n * @remarks\n * Provides configurable retry behavior for transient failures with\n * exponential backoff, maximum delay caps, and optional jitter to\n * prevent thundering herd problems.\n *\n * @example\n * ```typescript\n * const result = await RetryUtility.withRetry(\n *   async () => await unreliableOperation(),\n *   {\n *     maxAttempts: 5,\n *     baseDelay: 1000,\n *     backoffMultiplier: 2,\n *     maxDelay: 30000,\n *     shouldRetry: (error) => error.code === 'NETWORK_ERROR'\n *   }\n * );\n * ```\n *\n * @category Infrastructure\n */\nexport class RetryUtility {\n  private static async delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n\n  static async withRetry<T>(\n    operation: () => Promise<T>,\n    config: RetryConfig,\n  ): Promise<T> {\n    let lastError: Error | undefined;\n\n    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {\n      try {\n        return await operation();\n      } catch (error) {\n        lastError = error as Error;\n\n        // Check if we should retry\n        if (config.shouldRetry && !config.shouldRetry(lastError, attempt)) {\n          throw lastError;\n        }\n\n        // Don't delay on the last attempt\n        if (attempt === config.maxAttempts) {\n          break;\n        }\n\n        // Calculate delay with exponential backoff and jitter\n        const baseDelay =\n          config.baseDelay *\n          Math.pow(config.backoffMultiplier ?? 2, attempt - 1);\n        const maxDelay = config.maxDelay ?? 30000;\n        const jitter = config.jitter ?? 0;\n\n        let delay = Math.min(baseDelay, maxDelay);\n\n        if (jitter > 0) {\n          delay += Math.random() * jitter * delay;\n        }\n\n        await this.delay(delay);\n      }\n    }\n\n    throw lastError ?? new Error(\"Operation failed after retries\");\n  }\n}\n\n/**\n * Implements token bucket rate limiting for API calls.\n *\n * @remarks\n * Prevents API throttling by limiting requests per time window.\n * Uses sliding window algorithm for smooth rate limiting without\n * burst spikes at window boundaries.\n *\n * @example\n * ```typescript\n * const limiter = new RateLimiter({\n *   requestsPerWindow: 100,\n *   windowMs: 60000 // 100 requests per minute\n * });\n *\n * // Check before making request\n * if (await limiter.checkLimit()) {\n *   await makeApiCall();\n * } else {\n *   await limiter.waitForSlot();\n *   await makeApiCall();\n * }\n * ```\n *\n * @category Infrastructure\n */\nexport class RateLimiter {\n  private requests: number[] = [];\n\n  constructor(private config: RateLimiterConfig) {}\n\n  async checkLimit(): Promise<boolean> {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n\n    // Remove requests outside the window\n    this.requests = this.requests.filter((time) => time > windowStart);\n\n    // Check if we can make a request\n    if (this.requests.length < this.config.requestsPerWindow) {\n      this.requests.push(now);\n      return true;\n    }\n\n    return false;\n  }\n\n  async waitForSlot(): Promise<void> {\n    while (!(await this.checkLimit())) {\n      await new Promise((resolve) => setTimeout(resolve, 100));\n    }\n  }\n\n  getRemainingRequests(): number {\n    const now = Date.now();\n    const windowStart = now - this.config.windowMs;\n    const activeRequests = this.requests.filter((time) => time > windowStart);\n    return Math.max(0, this.config.requestsPerWindow - activeRequests.length);\n  }\n\n  getResetTime(): number {\n    if (this.requests.length === 0) return 0;\n    return Math.max(0, this.requests[0] + this.config.windowMs - Date.now());\n  }\n}\n\n/**\n * Generic in-memory cache implementation\n */\nexport class MemoryCache<TKey = string, TValue = unknown>\n  implements Cache<TKey, TValue>\n{\n  private cache = new Map<TKey, { value: TValue; expiry?: number }>();\n\n  async get(key: TKey): Promise<TValue | undefined> {\n    const item = this.cache.get(key);\n\n    if (!item) return undefined;\n\n    // Check if expired\n    if (item.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    return item.value;\n  }\n\n  async set(key: TKey, value: TValue, ttl?: number): Promise<void> {\n    const expiry = ttl ? Date.now() + ttl : undefined;\n    this.cache.set(key, { value, expiry });\n  }\n\n  async delete(key: TKey): Promise<boolean> {\n    return this.cache.delete(key);\n  }\n\n  async clear(): Promise<void> {\n    this.cache.clear();\n  }\n\n  async has(key: TKey): Promise<boolean> {\n    const exists = this.cache.has(key);\n    if (!exists) return false;\n\n    // Check expiry\n    const item = this.cache.get(key);\n    if (item?.expiry && Date.now() > item.expiry) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  size(): number {\n    return this.cache.size;\n  }\n\n  keys(): TKey[] {\n    return Array.from(this.cache.keys());\n  }\n}\n\n/**\n * Generic event emitter implementation\n */\nexport class EventEmitter<TEvent = unknown> implements Observable<TEvent> {\n  private observers: Observer<TEvent>[] = [];\n\n  subscribe(observer: Observer<TEvent>): () => void {\n    this.observers.push(observer);\n\n    return () => {\n      this.unsubscribe(observer);\n    };\n  }\n\n  unsubscribe(observer: Observer<TEvent>): void {\n    const index = this.observers.indexOf(observer);\n    if (index > -1) {\n      this.observers.splice(index, 1);\n    }\n  }\n\n  emit(event: TEvent): void {\n    for (const observer of this.observers) {\n      try {\n        const result = observer.notify(event);\n        if (result instanceof Promise) {\n          result.catch((error) => {\n            console.error(\"Observer error:\", error);\n          });\n        }\n      } catch (error) {\n        console.error(\"Observer error:\", error);\n      }\n    }\n  }\n\n  getObserverCount(): number {\n    return this.observers.length;\n  }\n\n  removeAllObservers(): void {\n    this.observers = [];\n  }\n}\n\n/**\n * Generic middleware pipeline\n */\nexport class MiddlewarePipeline {\n  private middleware: Middleware<any, any>[] = [];\n\n  use(middleware: Middleware<any, any>): void {\n    this.middleware.push(middleware);\n  }\n\n  async processRequest<TRequest>(request: TRequest): Promise<TRequest> {\n    let processed = request;\n\n    for (const mw of this.middleware) {\n      if (mw.request) {\n        processed = await mw.request(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async processResponse<TResponse>(response: TResponse): Promise<TResponse> {\n    let processed = response;\n\n    // Process in reverse order\n    for (const mw of this.middleware.slice().reverse()) {\n      if (mw.response) {\n        processed = await mw.response(processed);\n      }\n    }\n\n    return processed;\n  }\n\n  async handleError<TRequest, TResponse>(\n    error: Error,\n    request: TRequest,\n  ): Promise<TResponse | void> {\n    for (const mw of this.middleware) {\n      if (mw.error) {\n        const result = await mw.error(error, request);\n        if (result) {\n          return result;\n        }\n      }\n    }\n  }\n\n  getMiddleware(): Middleware<any, any>[] {\n    return [...this.middleware];\n  }\n\n  clear(): void {\n    this.middleware = [];\n  }\n}\n\n/**\n * Generic async queue for managing concurrent operations\n */\nexport class AsyncQueue<T = unknown> {\n  private queue: Array<() => Promise<T>> = [];\n  private running = 0;\n\n  constructor(private concurrency = 1) {}\n\n  async add<R>(operation: () => Promise<R>): Promise<R> {\n    return new Promise((resolve, reject) => {\n      this.queue.push(async () => {\n        try {\n          const result = await operation();\n          resolve(result as unknown as R);\n          return result as unknown as T;\n        } catch (error) {\n          reject(error);\n          throw error;\n        } finally {\n          this.running--;\n          this.processQueue();\n        }\n      });\n\n      this.processQueue();\n    });\n  }\n\n  private processQueue(): void {\n    while (this.running < this.concurrency && this.queue.length > 0) {\n      const operation = this.queue.shift();\n      if (operation) {\n        this.running++;\n        operation().catch(() => {\n          // Error already handled in add method\n        });\n      }\n    }\n  }\n\n  get pending(): number {\n    return this.queue.length;\n  }\n\n  get active(): number {\n    return this.running;\n  }\n\n  get size(): number {\n    return this.queue.length + this.running;\n  }\n\n  clear(): void {\n    this.queue = [];\n  }\n}\n\n/**\n * Generic circuit breaker pattern\n */\nexport class CircuitBreaker {\n  private state: \"closed\" | \"open\" | \"half-open\" = \"closed\";\n  private failures = 0;\n  private lastFailureTime = 0;\n  private successes = 0;\n\n  constructor(\n    private config: {\n      failureThreshold: number;\n      recoveryTimeout: number;\n      halfOpenMaxAttempts?: number;\n    },\n  ) {}\n\n  async execute<TResult>(operation: () => Promise<TResult>): Promise<TResult> {\n    if (this.state === \"open\") {\n      if (Date.now() - this.lastFailureTime > this.config.recoveryTimeout) {\n        this.state = \"half-open\";\n        this.successes = 0;\n      } else {\n        throw new Error(\"Circuit breaker is open\");\n      }\n    }\n\n    try {\n      const result = await operation();\n      this.onSuccess();\n      return result;\n    } catch (error) {\n      this.onFailure();\n      throw error;\n    }\n  }\n\n  private onSuccess(): void {\n    this.failures = 0;\n\n    if (this.state === \"half-open\") {\n      this.successes++;\n      if (this.successes >= (this.config.halfOpenMaxAttempts ?? 1)) {\n        this.state = \"closed\";\n      }\n    }\n  }\n\n  private onFailure(): void {\n    this.failures++;\n    this.lastFailureTime = Date.now();\n\n    if (this.failures >= this.config.failureThreshold) {\n      this.state = \"open\";\n    }\n  }\n\n  getState(): string {\n    return this.state;\n  }\n\n  getFailures(): number {\n    return this.failures;\n  }\n\n  reset(): void {\n    this.state = \"closed\";\n    this.failures = 0;\n    this.successes = 0;\n    this.lastFailureTime = 0;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/core.cjs

@@ -99,7 +99,8 @@ class VanaCore {
   protocol;
   /** Handles environment-specific operations like encryption and file systems. */
   platform;
-  relayerCallbacks;
+  relayerConfig;
+  relayerCallback;
   downloadRelayer;
   storageManager;
   hasRequiredStorage;
@@ -132,7 +133,30 @@ class VanaCore {
   constructor(platform, config) {
     this.platform = platform;
     this.validateConfig(config);
-    this.relayerCallbacks = config.relayerCallbacks;
+    this.relayerConfig = config.relayer;
+    if (config.relayer) {
+      if (typeof config.relayer !== "string" && typeof config.relayer !== "function") {
+        throw new import_errors.InvalidConfigurationError(
+          "Relayer must be either a URL string or a callback function"
+        );
+      }
+      if (typeof config.relayer === "string") {
+        const url = config.relayer;
+        this.relayerCallback = async (request) => {
+          const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(request)
+          });
+          if (!response.ok) {
+            throw new Error(`Relayer request failed: ${response.statusText}`);
+          }
+          return response.json();
+        };
+      } else {
+        this.relayerCallback = config.relayer;
+      }
+    }
     this.downloadRelayer = config.downloadRelayer;
     this.ipfsGateways = config.ipfsGateways;
     this.hasRequiredStorage = (0, import_types.hasStorageConfig)(config);
@@ -219,7 +243,7 @@ class VanaCore {
       },
       applicationClient: walletClient,
       // Using same wallet for now
-      relayerCallbacks: this.relayerCallbacks,
+      relayer: this.relayerCallback,
       downloadRelayer: this.downloadRelayer,
       storageManager: this.storageManager,
       subgraphUrl,
@@ -254,7 +278,7 @@ class VanaCore {
   validateStorageRequired() {
     if (!this.hasRequiredStorage) {
       throw new import_errors.InvalidConfigurationError(
-        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayerCallbacks.storeGrantFile implementation, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
+        "Storage configuration is required for this operation. Please configure storage providers in VanaConfig.storage, provide a relayer configuration, or pass pre-stored URLs to avoid this dependency. \n\nFor better type safety, consider using VanaCoreFactory.createWithStorage() with VanaConfigWithStorage to catch this error at compile time."
       );
     }
   }
@@ -303,13 +327,6 @@ class VanaCore {
     if (!config) {
       throw new import_errors.InvalidConfigurationError("Configuration object is required");
     }
-    if (config.relayerCallbacks !== void 0) {
-      if (typeof config.relayerCallbacks !== "object") {
-        throw new import_errors.InvalidConfigurationError(
-          "relayerCallbacks must be an object"
-        );
-      }
-    }
     if (config.storage?.providers) {
       if (typeof config.storage.providers !== "object") {
         throw new import_errors.InvalidConfigurationError(
@@ -460,7 +477,7 @@ class VanaCore {
     return {
       chainId: this.chainId,
       chainName: this.chainName,
-      relayerCallbacks: this.relayerCallbacks,
+      relayerConfig: this.relayerConfig,
       storageProviders: this.storageManager?.getStorageProviders() ?? [],
       defaultStorageProvider: this.storageManager?.getDefaultStorageProvider()
     };