@stravigor/saina 0.4.8 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravigor/saina",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "type": "module",
   "description": "AI module for the Strav framework",
   "license": "MIT",

package/src/providers/anthropic_provider.ts

@@ -1,4 +1,5 @@
 import { parseSSE } from '../utils/sse_parser.ts'
+import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
 import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
 import type {
   AIProvider,
@@ -23,6 +24,7 @@ export class AnthropicProvider implements AIProvider {
   private baseUrl: string
   private defaultModel: string
   private defaultMaxTokens: number
+  private retryOptions: RetryOptions
 
   constructor(config: ProviderConfig) {
     this.name = 'anthropic'
@@ -30,21 +32,21 @@ export class AnthropicProvider implements AIProvider {
     this.baseUrl = (config.baseUrl ?? 'https://api.anthropic.com').replace(/\/$/, '')
     this.defaultModel = config.model
     this.defaultMaxTokens = config.maxTokens ?? 4096
+    this.retryOptions = {
+      maxRetries: config.maxRetries ?? 3,
+      baseDelay: config.retryBaseDelay ?? 1000,
+    }
   }
 
   async complete(request: CompletionRequest): Promise<CompletionResponse> {
     const body = this.buildRequestBody(request, false)
 
-    const response = await fetch(`${this.baseUrl}/v1/messages`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('Anthropic', response.status, text)
-    }
+    const response = await retryableFetch(
+      'Anthropic',
+      `${this.baseUrl}/v1/messages`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
     return this.parseResponse(data)
@@ -53,16 +55,12 @@ export class AnthropicProvider implements AIProvider {
   async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
     const body = this.buildRequestBody(request, true)
 
-    const response = await fetch(`${this.baseUrl}/v1/messages`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('Anthropic', response.status, text)
-    }
+    const response = await retryableFetch(
+      'Anthropic',
+      `${this.baseUrl}/v1/messages`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     if (!response.body) {
       throw new ExternalServiceError('Anthropic', undefined, 'No stream body returned')

package/src/providers/openai_provider.ts

@@ -1,4 +1,5 @@
 import { parseSSE } from '../utils/sse_parser.ts'
+import { retryableFetch, type RetryOptions } from '../utils/retry.ts'
 import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
 import type {
   AIProvider,
@@ -24,6 +25,7 @@ export class OpenAIProvider implements AIProvider {
   private baseUrl: string
   private defaultModel: string
   private defaultMaxTokens?: number
+  private retryOptions: RetryOptions
 
   constructor(config: ProviderConfig, name?: string) {
     this.name = name ?? 'openai'
@@ -31,6 +33,10 @@ export class OpenAIProvider implements AIProvider {
     this.baseUrl = (config.baseUrl ?? 'https://api.openai.com').replace(/\/$/, '')
     this.defaultModel = config.model
     this.defaultMaxTokens = config.maxTokens
+    this.retryOptions = {
+      maxRetries: config.maxRetries ?? 3,
+      baseDelay: config.retryBaseDelay ?? 1000,
+    }
   }
 
   /** Whether this provider supports OpenAI's native json_schema response format. */
@@ -41,16 +47,12 @@ export class OpenAIProvider implements AIProvider {
   async complete(request: CompletionRequest): Promise<CompletionResponse> {
     const body = this.buildRequestBody(request, false)
 
-    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('OpenAI', response.status, text)
-    }
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/chat/completions`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
     return this.parseResponse(data)
@@ -59,16 +61,12 @@ export class OpenAIProvider implements AIProvider {
   async *stream(request: CompletionRequest): AsyncIterable<StreamChunk> {
     const body = this.buildRequestBody(request, true)
 
-    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('OpenAI', response.status, text)
-    }
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/chat/completions`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     if (!response.body) {
       throw new ExternalServiceError('OpenAI', undefined, 'No stream body returned')
@@ -157,16 +155,12 @@ export class OpenAIProvider implements AIProvider {
       model: model ?? 'text-embedding-3-small',
     }
 
-    const response = await fetch(`${this.baseUrl}/v1/embeddings`, {
-      method: 'POST',
-      headers: this.buildHeaders(),
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('OpenAI', response.status, text)
-    }
+    const response = await retryableFetch(
+      'OpenAI',
+      `${this.baseUrl}/v1/embeddings`,
+      { method: 'POST', headers: this.buildHeaders(), body: JSON.stringify(body) },
+      this.retryOptions
+    )
 
     const data: any = await response.json()
 

package/src/types.ts

@@ -161,6 +161,8 @@ export interface ProviderConfig {
   baseUrl?: string
   maxTokens?: number
   temperature?: number
+  maxRetries?: number
+  retryBaseDelay?: number
 }
 
 export interface SainaConfig {

package/src/utils/retry.ts

@@ -0,0 +1,100 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+
+export interface RetryOptions {
+  maxRetries?: number
+  baseDelay?: number
+  maxDelay?: number
+  retryableStatuses?: number[]
+}
+
+const DEFAULT_RETRYABLE = [429, 500, 502, 503, 529]
+
+/**
+ * Fetch with automatic retry and exponential backoff for transient errors.
+ *
+ * Retries on 429 (rate limit), 5xx, and network failures.
+ * Parses the `retry-after` header when available; otherwise uses
+ * exponential backoff with jitter.
+ *
+ * Returns the successful `Response`. On final failure, throws
+ * `ExternalServiceError` with the last status and body.
+ */
+export async function retryableFetch(
+  service: string,
+  url: string,
+  init: RequestInit,
+  options?: RetryOptions
+): Promise<Response> {
+  const maxRetries = options?.maxRetries ?? 3
+  const baseDelay = options?.baseDelay ?? 1000
+  const maxDelay = options?.maxDelay ?? 60_000
+  const retryable = options?.retryableStatuses ?? DEFAULT_RETRYABLE
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let response: Response
+
+    try {
+      response = await fetch(url, init)
+    } catch (err) {
+      // Network error (DNS, connection refused, etc.)
+      if (attempt === maxRetries) {
+        throw new ExternalServiceError(
+          service,
+          undefined,
+          err instanceof Error ? err.message : String(err)
+        )
+      }
+      await sleep(backoffDelay(attempt, baseDelay, maxDelay))
+      continue
+    }
+
+    if (response.ok) return response
+
+    // Non-retryable status — fail immediately
+    if (!retryable.includes(response.status)) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    // Retryable status — wait and retry (unless last attempt)
+    if (attempt === maxRetries) {
+      const text = await response.text()
+      throw new ExternalServiceError(service, response.status, text)
+    }
+
+    const delay = parseRetryAfter(response) ?? backoffDelay(attempt, baseDelay, maxDelay)
+    await sleep(delay)
+  }
+
+  // Unreachable, but satisfies TypeScript
+  throw new ExternalServiceError(service, undefined, 'Retry loop exited unexpectedly')
+}
+
+/**
+ * Parse the `retry-after` header into milliseconds.
+ * Supports both delta-seconds ("2") and HTTP-date formats.
+ */
+function parseRetryAfter(response: Response): number | null {
+  const header = response.headers.get('retry-after')
+  if (!header) return null
+
+  const seconds = Number(header)
+  if (!Number.isNaN(seconds)) return seconds * 1000
+
+  // HTTP-date format
+  const date = Date.parse(header)
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
+
+  return null
+}
+
+/** Exponential backoff with jitter: base * 2^attempt + random jitter, capped at maxDelay. */
+function backoffDelay(attempt: number, baseDelay: number, maxDelay: number): number {
+  const exp = baseDelay * 2 ** attempt
+  const jitter = Math.random() * baseDelay
+  return Math.min(exp + jitter, maxDelay)
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}