@providerprotocol/ai 0.0.1

package/src/http/errors.ts

@@ -0,0 +1,112 @@
+import { UPPError, type ErrorCode, type Modality } from '../types/errors.ts';
+
+/**
+ * Map HTTP status codes to UPP error codes
+ */
+export function statusToErrorCode(status: number): ErrorCode {
+  switch (status) {
+    case 400:
+      return 'INVALID_REQUEST';
+    case 401:
+    case 403:
+      return 'AUTHENTICATION_FAILED';
+    case 404:
+      return 'MODEL_NOT_FOUND';
+    case 408:
+      return 'TIMEOUT';
+    case 413:
+      return 'CONTEXT_LENGTH_EXCEEDED';
+    case 429:
+      return 'RATE_LIMITED';
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return 'PROVIDER_ERROR';
+    default:
+      return 'PROVIDER_ERROR';
+  }
+}
+
+/**
+ * Normalize HTTP error responses to UPPError
+ * Maps HTTP status codes to appropriate ErrorCode values
+ * Extracts error message from response body when available
+ */
+export async function normalizeHttpError(
+  response: Response,
+  provider: string,
+  modality: Modality
+): Promise<UPPError> {
+  const code = statusToErrorCode(response.status);
+  let message = `HTTP ${response.status}: ${response.statusText}`;
+
+  try {
+    const body = await response.text();
+    if (body) {
+      try {
+        const json = JSON.parse(body);
+        // Common error message locations across providers
+        const extractedMessage =
+          json.error?.message ||
+          json.message ||
+          json.error?.error?.message ||
+          json.detail;
+
+        if (extractedMessage) {
+          message = extractedMessage;
+        }
+      } catch {
+        // Body is not JSON, use raw text if short
+        if (body.length < 200) {
+          message = body;
+        }
+      }
+    }
+  } catch {
+    // Failed to read body, use default message
+  }
+
+  return new UPPError(message, code, provider, modality, response.status);
+}
+
+/**
+ * Create a network error
+ */
+export function networkError(
+  error: Error,
+  provider: string,
+  modality: Modality
+): UPPError {
+  return new UPPError(
+    `Network error: ${error.message}`,
+    'NETWORK_ERROR',
+    provider,
+    modality,
+    undefined,
+    error
+  );
+}
+
+/**
+ * Create a timeout error
+ */
+export function timeoutError(
+  timeout: number,
+  provider: string,
+  modality: Modality
+): UPPError {
+  return new UPPError(
+    `Request timed out after ${timeout}ms`,
+    'TIMEOUT',
+    provider,
+    modality
+  );
+}
+
+/**
+ * Create a cancelled error
+ */
+export function cancelledError(provider: string, modality: Modality): UPPError {
+  return new UPPError('Request was cancelled', 'CANCELLED', provider, modality);
+}

package/src/http/fetch.ts

@@ -0,0 +1,210 @@
+import type { ProviderConfig } from '../types/provider.ts';
+import type { Modality } from '../types/errors.ts';
+import { UPPError } from '../types/errors.ts';
+import {
+  normalizeHttpError,
+  networkError,
+  timeoutError,
+  cancelledError,
+} from './errors.ts';
+
+/**
+ * Default timeout in milliseconds
+ */
+const DEFAULT_TIMEOUT = 120000; // 2 minutes
+
+/**
+ * Execute fetch with retry, timeout, and error normalization
+ *
+ * @param url - Request URL
+ * @param init - Fetch init options
+ * @param config - Provider config
+ * @param provider - Provider name for error messages
+ * @param modality - Modality for error messages
+ */
+export async function doFetch(
+  url: string,
+  init: RequestInit,
+  config: ProviderConfig,
+  provider: string,
+  modality: Modality
+): Promise<Response> {
+  const fetchFn = config.fetch ?? fetch;
+  const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  const strategy = config.retryStrategy;
+
+  // Pre-request delay (e.g., token bucket)
+  if (strategy?.beforeRequest) {
+    const delay = await strategy.beforeRequest();
+    if (delay > 0) {
+      await sleep(delay);
+    }
+  }
+
+  let lastError: UPPError | undefined;
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+
+    try {
+      const response = await fetchWithTimeout(
+        fetchFn,
+        url,
+        init,
+        timeout,
+        provider,
+        modality
+      );
+
+      // Check for HTTP errors
+      if (!response.ok) {
+        const error = await normalizeHttpError(response, provider, modality);
+
+        // Check for Retry-After header
+        const retryAfter = response.headers.get('Retry-After');
+        if (retryAfter && strategy) {
+          const seconds = parseInt(retryAfter, 10);
+          if (!isNaN(seconds) && 'setRetryAfter' in strategy) {
+            (strategy as { setRetryAfter: (s: number) => void }).setRetryAfter(
+              seconds
+            );
+          }
+        }
+
+        // Try to retry
+        if (strategy) {
+          const delay = await strategy.onRetry(error, attempt);
+          if (delay !== null) {
+            await sleep(delay);
+            lastError = error;
+            continue;
+          }
+        }
+
+        throw error;
+      }
+
+      // Success - reset strategy state
+      strategy?.reset?.();
+
+      return response;
+    } catch (error) {
+      // Already a UPPError, handle retry
+      if (error instanceof UPPError) {
+        if (strategy) {
+          const delay = await strategy.onRetry(error, attempt);
+          if (delay !== null) {
+            await sleep(delay);
+            lastError = error;
+            continue;
+          }
+        }
+        throw error;
+      }
+
+      // Network error
+      const uppError = networkError(error as Error, provider, modality);
+
+      if (strategy) {
+        const delay = await strategy.onRetry(uppError, attempt);
+        if (delay !== null) {
+          await sleep(delay);
+          lastError = uppError;
+          continue;
+        }
+      }
+
+      throw uppError;
+    }
+  }
+}
+
+/**
+ * Fetch with timeout
+ */
+async function fetchWithTimeout(
+  fetchFn: typeof fetch,
+  url: string,
+  init: RequestInit,
+  timeout: number,
+  provider: string,
+  modality: Modality
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  // Merge abort signals if one was provided
+  const existingSignal = init.signal;
+  if (existingSignal) {
+    existingSignal.addEventListener('abort', () => controller.abort());
+  }
+
+  try {
+    const response = await fetchFn(url, {
+      ...init,
+      signal: controller.signal,
+    });
+    return response;
+  } catch (error) {
+    if ((error as Error).name === 'AbortError') {
+      // Check if it was the user's signal or our timeout
+      if (existingSignal?.aborted) {
+        throw cancelledError(provider, modality);
+      }
+      throw timeoutError(timeout, provider, modality);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Streaming fetch - returns response without checking ok status
+ * Used when we need to read the stream for SSE
+ */
+export async function doStreamFetch(
+  url: string,
+  init: RequestInit,
+  config: ProviderConfig,
+  provider: string,
+  modality: Modality
+): Promise<Response> {
+  const fetchFn = config.fetch ?? fetch;
+  const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+  const strategy = config.retryStrategy;
+
+  // Pre-request delay
+  if (strategy?.beforeRequest) {
+    const delay = await strategy.beforeRequest();
+    if (delay > 0) {
+      await sleep(delay);
+    }
+  }
+
+  // For streaming, we don't retry - the consumer handles errors
+  try {
+    const response = await fetchWithTimeout(
+      fetchFn,
+      url,
+      init,
+      timeout,
+      provider,
+      modality
+    );
+    return response;
+  } catch (error) {
+    if (error instanceof UPPError) {
+      throw error;
+    }
+    throw networkError(error as Error, provider, modality);
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,31 @@
+// Key management
+export {
+  resolveApiKey,
+  RoundRobinKeys,
+  WeightedKeys,
+  DynamicKey,
+} from './keys.ts';
+
+// Retry strategies
+export {
+  ExponentialBackoff,
+  LinearBackoff,
+  NoRetry,
+  TokenBucket,
+  RetryAfterStrategy,
+} from './retry.ts';
+
+// HTTP fetch
+export { doFetch, doStreamFetch } from './fetch.ts';
+
+// SSE parsing
+export { parseSSEStream, parseSimpleTextStream } from './sse.ts';
+
+// Error utilities
+export {
+  normalizeHttpError,
+  networkError,
+  timeoutError,
+  cancelledError,
+  statusToErrorCode,
+} from './errors.ts';

package/src/http/keys.ts

@@ -0,0 +1,136 @@
+import type { ProviderConfig, KeyStrategy } from '../types/provider.ts';
+import { UPPError, type Modality } from '../types/errors.ts';
+
+/**
+ * Round-robin through a list of API keys
+ */
+export class RoundRobinKeys implements KeyStrategy {
+  private keys: string[];
+  private index = 0;
+
+  constructor(keys: string[]) {
+    if (keys.length === 0) {
+      throw new Error('RoundRobinKeys requires at least one key');
+    }
+    this.keys = keys;
+  }
+
+  getKey(): string {
+    const key = this.keys[this.index]!;
+    this.index = (this.index + 1) % this.keys.length;
+    return key;
+  }
+}
+
+/**
+ * Weighted random selection of API keys
+ */
+export class WeightedKeys implements KeyStrategy {
+  private entries: Array<{ key: string; weight: number }>;
+  private totalWeight: number;
+
+  constructor(keys: Array<{ key: string; weight: number }>) {
+    if (keys.length === 0) {
+      throw new Error('WeightedKeys requires at least one key');
+    }
+    this.entries = keys;
+    this.totalWeight = keys.reduce((sum, k) => sum + k.weight, 0);
+  }
+
+  getKey(): string {
+    const random = Math.random() * this.totalWeight;
+    let cumulative = 0;
+
+    for (const entry of this.entries) {
+      cumulative += entry.weight;
+      if (random <= cumulative) {
+        return entry.key;
+      }
+    }
+
+    // Fallback to last key (shouldn't happen)
+    return this.entries[this.entries.length - 1]!.key;
+  }
+}
+
+/**
+ * Dynamic key selection based on custom logic
+ */
+export class DynamicKey implements KeyStrategy {
+  private selector: () => string | Promise<string>;
+
+  constructor(selector: () => string | Promise<string>) {
+    this.selector = selector;
+  }
+
+  async getKey(): Promise<string> {
+    return this.selector();
+  }
+}
+
+/**
+ * Check if a value is a KeyStrategy
+ */
+function isKeyStrategy(value: unknown): value is KeyStrategy {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'getKey' in value &&
+    typeof (value as KeyStrategy).getKey === 'function'
+  );
+}
+
+/**
+ * Resolve API key from ProviderConfig
+ * Falls back to environment variable if provided and config.apiKey is not set
+ * Throws UPPError with AUTHENTICATION_FAILED if no key is available
+ *
+ * @param config - Provider configuration
+ * @param envVar - Environment variable name to check as fallback
+ * @param provider - Provider name for error messages
+ * @param modality - Modality for error messages
+ */
+export async function resolveApiKey(
+  config: ProviderConfig,
+  envVar?: string,
+  provider = 'unknown',
+  modality: Modality = 'llm'
+): Promise<string> {
+  const { apiKey } = config;
+
+  // If apiKey is provided in config
+  if (apiKey !== undefined) {
+    // String
+    if (typeof apiKey === 'string') {
+      return apiKey;
+    }
+
+    // Function
+    if (typeof apiKey === 'function') {
+      return apiKey();
+    }
+
+    // KeyStrategy
+    if (isKeyStrategy(apiKey)) {
+      return apiKey.getKey();
+    }
+  }
+
+  // Try environment variable
+  if (envVar) {
+    const envValue = process.env[envVar];
+    if (envValue) {
+      return envValue;
+    }
+  }
+
+  // No key found
+  throw new UPPError(
+    envVar
+      ? `API key not found. Set ${envVar} environment variable or provide apiKey in config.`
+      : 'API key not found. Provide apiKey in config.',
+    'AUTHENTICATION_FAILED',
+    provider,
+    modality
+  );
+}

package/src/http/retry.ts

@@ -0,0 +1,205 @@
+import type { RetryStrategy } from '../types/provider.ts';
+import type { UPPError } from '../types/errors.ts';
+
+/**
+ * Exponential backoff retry strategy
+ */
+export class ExponentialBackoff implements RetryStrategy {
+  private maxAttempts: number;
+  private baseDelay: number;
+  private maxDelay: number;
+  private jitter: boolean;
+
+  constructor(options: {
+    maxAttempts?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    jitter?: boolean;
+  } = {}) {
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.baseDelay = options.baseDelay ?? 1000;
+    this.maxDelay = options.maxDelay ?? 30000;
+    this.jitter = options.jitter ?? true;
+  }
+
+  onRetry(error: UPPError, attempt: number): number | null {
+    if (attempt > this.maxAttempts) {
+      return null;
+    }
+
+    // Only retry on retryable errors
+    if (!this.isRetryable(error)) {
+      return null;
+    }
+
+    // Calculate delay with exponential backoff
+    let delay = this.baseDelay * Math.pow(2, attempt - 1);
+    delay = Math.min(delay, this.maxDelay);
+
+    // Add jitter
+    if (this.jitter) {
+      delay = delay * (0.5 + Math.random());
+    }
+
+    return Math.floor(delay);
+  }
+
+  private isRetryable(error: UPPError): boolean {
+    return (
+      error.code === 'RATE_LIMITED' ||
+      error.code === 'NETWORK_ERROR' ||
+      error.code === 'TIMEOUT' ||
+      error.code === 'PROVIDER_ERROR'
+    );
+  }
+}
+
+/**
+ * Linear backoff retry strategy
+ */
+export class LinearBackoff implements RetryStrategy {
+  private maxAttempts: number;
+  private delay: number;
+
+  constructor(options: {
+    maxAttempts?: number;
+    delay?: number;
+  } = {}) {
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.delay = options.delay ?? 1000;
+  }
+
+  onRetry(error: UPPError, attempt: number): number | null {
+    if (attempt > this.maxAttempts) {
+      return null;
+    }
+
+    // Only retry on retryable errors
+    if (!this.isRetryable(error)) {
+      return null;
+    }
+
+    return this.delay * attempt;
+  }
+
+  private isRetryable(error: UPPError): boolean {
+    return (
+      error.code === 'RATE_LIMITED' ||
+      error.code === 'NETWORK_ERROR' ||
+      error.code === 'TIMEOUT' ||
+      error.code === 'PROVIDER_ERROR'
+    );
+  }
+}
+
+/**
+ * No retry strategy - fail immediately
+ */
+export class NoRetry implements RetryStrategy {
+  onRetry(): null {
+    return null;
+  }
+}
+
+/**
+ * Token bucket rate limiter with retry
+ */
+export class TokenBucket implements RetryStrategy {
+  private tokens: number;
+  private maxTokens: number;
+  private refillRate: number; // tokens per second
+  private lastRefill: number;
+  private maxAttempts: number;
+
+  constructor(options: {
+    maxTokens?: number;
+    refillRate?: number;
+    maxAttempts?: number;
+  } = {}) {
+    this.maxTokens = options.maxTokens ?? 10;
+    this.refillRate = options.refillRate ?? 1;
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.tokens = this.maxTokens;
+    this.lastRefill = Date.now();
+  }
+
+  beforeRequest(): number {
+    this.refill();
+
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return 0;
+    }
+
+    // Calculate time until next token
+    const msPerToken = 1000 / this.refillRate;
+    return Math.ceil(msPerToken);
+  }
+
+  onRetry(error: UPPError, attempt: number): number | null {
+    if (attempt > this.maxAttempts) {
+      return null;
+    }
+
+    if (error.code !== 'RATE_LIMITED') {
+      return null;
+    }
+
+    // Wait for token bucket to refill
+    const msPerToken = 1000 / this.refillRate;
+    return Math.ceil(msPerToken * 2); // Wait for 2 tokens
+  }
+
+  reset(): void {
+    this.tokens = this.maxTokens;
+    this.lastRefill = Date.now();
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    const newTokens = elapsed * this.refillRate;
+
+    this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+    this.lastRefill = now;
+  }
+}
+
+/**
+ * Retry strategy that respects Retry-After headers
+ */
+export class RetryAfterStrategy implements RetryStrategy {
+  private maxAttempts: number;
+  private fallbackDelay: number;
+  private lastRetryAfter?: number;
+
+  constructor(options: {
+    maxAttempts?: number;
+    fallbackDelay?: number;
+  } = {}) {
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.fallbackDelay = options.fallbackDelay ?? 5000;
+  }
+
+  /**
+   * Set the Retry-After value from response headers
+   * Call this before onRetry when you have a Retry-After header
+   */
+  setRetryAfter(seconds: number): void {
+    this.lastRetryAfter = seconds * 1000;
+  }
+
+  onRetry(error: UPPError, attempt: number): number | null {
+    if (attempt > this.maxAttempts) {
+      return null;
+    }
+
+    if (error.code !== 'RATE_LIMITED') {
+      return null;
+    }
+
+    const delay = this.lastRetryAfter ?? this.fallbackDelay;
+    this.lastRetryAfter = undefined;
+    return delay;
+  }
+}