feat: add retry with exponential backoff in client.ts (DIS-143)

Co-Authored-By: Chris K <ckorhonen@gmail.com>

Author: devin-ai-integration[bot]

src/cli.ts

@@ -38,6 +38,8 @@ program
   .option("--base-url <url>", "API base URL")
   .option("--timeout <ms>", "Request timeout in milliseconds", "30000")
   .option("--verbose", "Log request and response info to stderr")
+  .option("--max-retries <n>", "Max retries on 429/5xx (0 to disable)", "3")
+  .option("--no-retry", "Disable request retries")
 
 function getClient(): OpenSeaClient {
   const opts = program.opts<{
@@ -46,6 +48,8 @@ function getClient(): OpenSeaClient {
     baseUrl?: string
     timeout: string
     verbose?: boolean
+    maxRetries: string
+    retry: boolean
   }>()
 
   const apiKey = opts.apiKey ?? process.env.OPENSEA_API_KEY
@@ -56,12 +60,17 @@ function getClient(): OpenSeaClient {
     process.exit(2)
   }
 
+  const maxRetries = opts.retry
+    ? parseIntOption(opts.maxRetries, "--max-retries")
+    : 0
+
   return new OpenSeaClient({
     apiKey,
     chain: opts.chain,
     baseUrl: opts.baseUrl,
     timeout: parseIntOption(opts.timeout, "--timeout"),
     verbose: opts.verbose,
+    maxRetries,
   })
 }
 

src/client.ts

@@ -2,20 +2,43 @@ import type { OpenSeaClientConfig } from "./types/index.js"
 
 const DEFAULT_BASE_URL = "https://api.opensea.io"
 const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_MAX_RETRIES = 3
+const DEFAULT_RETRY_BASE_DELAY_MS = 1_000
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500
+}
+
+function parseRetryAfter(header: string | null): number | undefined {
+  if (!header) return undefined
+  const seconds = Number(header)
+  if (!Number.isNaN(seconds)) return seconds * 1000
+  const date = Date.parse(header)
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
+  return undefined
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
 
 export class OpenSeaClient {
   private apiKey: string
   private baseUrl: string
   private defaultChain: string
   private timeoutMs: number
   private verbose: boolean
+  private maxRetries: number
+  private retryBaseDelay: number
 
   constructor(config: OpenSeaClientConfig) {
     this.apiKey = config.apiKey
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL
     this.defaultChain = config.chain ?? "ethereum"
     this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS
     this.verbose = config.verbose ?? false
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES
+    this.retryBaseDelay = config.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY_MS
   }
 
   async get<T>(path: string, params?: Record<string, unknown>): Promise<T> {
@@ -33,23 +56,18 @@ export class OpenSeaClient {
       console.error(`[verbose] GET ${url.toString()}`)
     }
 
-    const response = await fetch(url.toString(), {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        "x-api-key": this.apiKey,
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "x-api-key": this.apiKey,
+        },
+        signal: AbortSignal.timeout(this.timeoutMs),
       },
-      signal: AbortSignal.timeout(this.timeoutMs),
-    })
-
-    if (this.verbose) {
-      console.error(`[verbose] ${response.status} ${response.statusText}`)
-    }
-
-    if (!response.ok) {
-      const body = await response.text()
-      throw new OpenSeaAPIError(response.status, body, path)
-    }
+      path,
+    )
 
     return response.json() as Promise<T>
   }
@@ -82,28 +100,62 @@ export class OpenSeaClient {
       console.error(`[verbose] POST ${url.toString()}`)
     }
 
-    const response = await fetch(url.toString(), {
-      method: "POST",
-      headers,
-      body: body ? JSON.stringify(body) : undefined,
-      signal: AbortSignal.timeout(this.timeoutMs),
-    })
-
-    if (this.verbose) {
-      console.error(`[verbose] ${response.status} ${response.statusText}`)
-    }
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new OpenSeaAPIError(response.status, text, path)
-    }
+    const response = await this.fetchWithRetry(
+      url.toString(),
+      {
+        method: "POST",
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      },
+      path,
+    )
 
     return response.json() as Promise<T>
   }
 
   getDefaultChain(): string {
     return this.defaultChain
   }
+
+  private async fetchWithRetry(
+    url: string,
+    init: RequestInit,
+    path: string,
+  ): Promise<Response> {
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetch(url, init)
+
+      if (this.verbose) {
+        console.error(`[verbose] ${response.status} ${response.statusText}`)
+      }
+
+      if (response.ok) {
+        return response
+      }
+
+      if (attempt < this.maxRetries && isRetryableStatus(response.status)) {
+        const retryAfterMs = parseRetryAfter(
+          response.headers.get("Retry-After"),
+        )
+        const backoffMs = this.retryBaseDelay * 2 ** attempt
+        const jitterMs = Math.random() * this.retryBaseDelay
+        const delayMs = Math.max(retryAfterMs ?? 0, backoffMs) + jitterMs
+
+        if (this.verbose) {
+          console.error(
+            `[verbose] Retry ${attempt + 1}/${this.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`,
+          )
+        }
+
+        await sleep(delayMs)
+        continue
+      }
+
+      const text = await response.text()
+      throw new OpenSeaAPIError(response.status, text, path)
+    }
+  }
 }
 
 export class OpenSeaAPIError extends Error {

src/types/index.ts

@@ -6,6 +6,8 @@ export interface OpenSeaClientConfig {
   chain?: string
   timeout?: number
   verbose?: boolean
+  maxRetries?: number
+  retryBaseDelay?: number
 }
 
 export interface CommandOptions {