feat: add HTTP 429 rate limit retry support (#83)

* feat: Add HTTP 429 rate limiting support with automatic retry

- Add LagoRateLimitError class for 429 responses
- Parse x-ratelimit-* headers from responses
- Implement automatic retry on 429 with configurable max retries
- Support header-based reset timing and exponential backoff
- Create fetch wrapper to intercept and handle rate limiting
- Add LagoClientConfig with rateLimitRetry options
- Include comprehensive tests for all rate limiting features
- Add RATE_LIMITING.md documentation
- Add rate_limiting_example.ts with usage patterns
- Maintain backward compatibility with existing API
- Do not modify generated OpenAPI code

* fix: correct rate limit test setup

* fix: replace broken mock_fetch with simple fetch mock

mock_fetch library's URLPattern is incompatible with current Deno.
Replace with a lightweight createMockFetch helper.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: gitignore ARCHITECTURE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: update deno.lock

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: implement real exponential backoff, remove dead code and generated docs

- Fix getWaitTime to actually fall back to exponential backoff
  (1s, 2s, 4s...) when x-ratelimit-reset header is missing.
  Previously always used error.retryAfter which defaulted to 60s,
  meaning every retry without a header waited a full minute.
- Change missing-header default from 60 to -1 so the backoff path
  is triggered correctly.
- Remove RateLimitRetryHandler class (rate_limit_retry.ts) — both
  branches of handleResponse() threw unconditionally, making the
  retryOnRateLimit flag a no-op. The class was never used by
  createRateLimitFetch. Remove its export from mod.ts.
- Remove RATE_LIMITING.md (394 lines) and examples/rate_limiting_example.ts
  (305 lines of commented-out code).
- Add test verifying exponential backoff triggers ~1s wait (not 60s)
  when reset header is absent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: remove deno.lock incompatible with CI Deno v1.x

Local Deno generated lockfile v5 which is unsupported by CI's
Deno 1.46.3. Removing so CI can regenerate.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add .claude to .gitignore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add 20s max retry delay cap

Prevents excessively long waits when the server returns a large
x-ratelimit-reset value. Applies to both header-based and
exponential backoff delays.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove deno.lock and add to .gitignore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Lago Developer <dev@lago.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.gitignore

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

deno.lock

@@ -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";

mod.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);
+  }
+}