feat: add HTTP 429 rate limit retry support

.gitignore

@@ -102,3 +102,6 @@ web_modules/
 
 npm/
 openapi/
+ARCHITECTURE.md
+.claude
+deno.lock

mod.ts

@@ -1,15 +1,35 @@
 // deno-lint-ignore-file no-explicit-any
 import { Api, ApiConfig, HttpResponse } from "./openapi/client.ts";
+import { createRateLimitFetch } from "./rate_limit_fetch.ts";
+import type { RateLimitFetchConfig } from "./rate_limit_fetch.ts";
+
+export interface LagoClientConfig extends ApiConfig {
+  /**
+   * Rate limit retry configuration
+   */
+  rateLimitRetry?: RateLimitFetchConfig;
+}
+
+export const Client = (apiKey: string, apiConfig?: LagoClientConfig) => {
+  const { rateLimitRetry, ...restConfig } = apiConfig ?? {};
+
+  // Create rate-limit-aware fetch if configured
+  const customFetch = rateLimitRetry
+    ? createRateLimitFetch(
+      (restConfig?.customFetch ?? globalThis.fetch) as typeof fetch,
+      rateLimitRetry,
+    )
+    : restConfig?.customFetch;
 
-export const Client = (apiKey: string, apiConfig?: ApiConfig) => {
   const api = new Api({
     securityWorker: (apiKey) =>
       apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {},
     // Cloudflare Workers doesn't support some options like credentials so need to override default
     baseApiParams: {
       redirect: "follow",
     },
-    ...apiConfig,
+    ...restConfig,
+    ...(customFetch && { customFetch }),
   });
   api.setSecurityData(apiKey);
   return api;
@@ -42,4 +62,9 @@ export async function getLagoError<T>(error: any) {
   throw new Error(error);
 }
 
+// Rate limit exports
+export { LagoRateLimitError } from "./rate_limit_error.ts";
+export { parseRateLimitHeaders, type RateLimitHeaders } from "./rate_limit_headers.ts";
+export { createRateLimitFetch, type RateLimitFetchConfig } from "./rate_limit_fetch.ts";
+
 export * from "./openapi/client.ts";

rate_limit_error.ts

@@ -0,0 +1,27 @@
+/**
+ * Error class for rate limit (HTTP 429) responses
+ */
+export class LagoRateLimitError extends Error {
+  public readonly limit: number;
+  public readonly remaining: number;
+  public readonly reset: number; // seconds until window resets
+  public readonly retryAfter: number; // milliseconds to wait before retrying
+
+  constructor(
+    limit: number,
+    remaining: number,
+    reset: number,
+  ) {
+    super(
+      `Rate limit exceeded. Limit: ${limit}, Remaining: ${remaining}, Reset in: ${reset}s`,
+    );
+    this.name = "LagoRateLimitError";
+    this.limit = limit;
+    this.remaining = remaining;
+    this.reset = reset;
+    this.retryAfter = reset * 1000; // Convert seconds to milliseconds
+
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, LagoRateLimitError.prototype);
+  }
+}