feat: add retry utility with exponential backoff

Adds a generic retry helper for transient failures like API throttling
and network errors. Supports configurable max retries, exponential
backoff with jitter, and retryable error filtering.

Author: jesseturner21

src/lib/utils/retry.ts

@@ -0,0 +1,65 @@
+/**
+ * Generic retry utility for transient failures (API throttling, network errors, etc.)
+ */
+
+export interface RetryOptions {
+  maxRetries: number;
+  baseDelayMs: number;
+  maxDelayMs: number;
+  retryableErrors?: string[];
+}
+
+const DEFAULT_OPTIONS: RetryOptions = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 30000,
+};
+
+/**
+ * Retry an async operation with exponential backoff and jitter.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: Partial<RetryOptions> = {},
+): Promise<T> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err as Error;
+
+      if (opts.retryableErrors && opts.retryableErrors.length > 0) {
+        const isRetryable = opts.retryableErrors.some((code) => lastError!.message.includes(code));
+        if (!isRetryable) {
+          throw lastError;
+        }
+      }
+
+      const delay = Math.min(opts.baseDelayMs * Math.pow(2, attempt), opts.maxDelayMs);
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Parse a retry-after header value to milliseconds.
+ */
+export function parseRetryAfter(headerValue: string): number {
+  const seconds = parseInt(headerValue);
+  if (!isNaN(seconds)) {
+    return seconds * 1000;
+  }
+
+  // Try parsing as HTTP date
+  const date = new Date(headerValue);
+  return date.getTime() - Date.now();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}