@agent-os-sdk/client 0.9.25 → 0.9.27

package/src/client/retry.ts

@@ -1,150 +0,0 @@
-/**
- * Agent OS SDK - Retry Logic
- * 
- * Enterprise-grade retry with:
- * - Exponential backoff with jitter
- * - Respect for Retry-After headers
- * - Idempotency-aware mutation retries
- * - Proper abort signal handling (no listener leaks)
- */
-
-import { AgentOsError, NetworkError, TimeoutError, RateLimitError } from "../errors/index.js";
-import type { RetryConfig } from "./config.js";
-
-/**
- * Context for retry decision-making.
- */
-export interface RetryContext {
-    /** HTTP method (GET, POST, etc.) */
-    method: string;
-
-    /** Whether the request has an idempotency key */
-    hasIdempotencyKey: boolean;
-}
-
-/**
- * Wraps an async function with retry logic.
- * 
- * IMPORTANT: Mutations (POST/PUT/PATCH/DELETE) are only retried if hasIdempotencyKey is true.
- * This prevents duplicate side effects.
- * 
- * @param fn - Function to execute (receives an AbortSignal)
- * @param config - Retry configuration
- * @param context - Request context for retry decisions
- * @param parentSignal - Optional parent AbortSignal for cancellation
- */
-export async function withRetry<T>(
-    fn: (signal: AbortSignal) => Promise<T>,
-    config: RetryConfig,
-    context: RetryContext,
-    parentSignal?: AbortSignal
-): Promise<T> {
-    let lastError: Error | undefined;
-
-    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
-        // Check parent abort before each attempt
-        if (parentSignal?.aborted) {
-            throw new Error("Request aborted");
-        }
-
-        const controller = new AbortController();
-
-        // Proper abort propagation without listener leak
-        const onAbort = () => controller.abort();
-        parentSignal?.addEventListener("abort", onAbort, { once: true });
-
-        try {
-            return await fn(controller.signal);
-        } catch (err) {
-            lastError = err as Error;
-
-            // If parent aborted, don't retry
-            if (controller.signal.aborted && parentSignal?.aborted) {
-                throw err;
-            }
-
-            // Check if this error is retryable
-            if (!shouldRetry(err, config, context)) {
-                throw err;
-            }
-
-            // Last attempt reached
-            if (attempt === config.maxRetries) {
-                throw err;
-            }
-
-            // Rate limit: use Retry-After if available
-            if (err instanceof RateLimitError && err.retryAfterMs) {
-                await sleep(err.retryAfterMs);
-                continue;
-            }
-
-            // Exponential backoff with jitter
-            const delay = calculateBackoff(attempt, config);
-            await sleep(delay);
-        } finally {
-            // CRITICAL: Always cleanup listener to prevent memory leak
-            parentSignal?.removeEventListener("abort", onAbort);
-        }
-    }
-
-    throw lastError ?? new Error("Retry failed");
-}
-
-/**
- * Determines if an error should trigger a retry.
- */
-function shouldRetry(
-    err: unknown,
-    config: RetryConfig,
-    context: RetryContext
-): boolean {
-    // Network and timeout errors are always retryable
-    if (err instanceof NetworkError || err instanceof TimeoutError) {
-        return true;
-    }
-
-    // Unknown errors are not retryable
-    if (!(err instanceof AgentOsError)) {
-        return false;
-    }
-
-    // Check if status code is in retryable list
-    if (!config.retryableStatuses.includes(err.status)) {
-        return false;
-    }
-
-    // CRITICAL: Only retry mutations if they have an idempotency key
-    // This prevents duplicate side effects from retrying POST/PUT/PATCH/DELETE
-    const isMutation = !["GET", "HEAD", "OPTIONS"].includes(context.method.toUpperCase());
-    if (isMutation && !context.hasIdempotencyKey) {
-        return false;
-    }
-
-    return true;
-}
-
-/**
- * Calculates backoff delay with exponential increase and jitter.
- */
-function calculateBackoff(attempt: number, config: RetryConfig): number {
-    // Exponential backoff: baseDelay * 2^attempt
-    const exponential = config.baseDelayMs * Math.pow(2, attempt);
-
-    // Cap at max delay
-    const capped = Math.min(exponential, config.maxDelayMs);
-
-    // Add jitter to prevent thundering herd
-    const jitter = capped * config.jitterFactor * Math.random();
-
-    return Math.floor(capped + jitter);
-}
-
-/**
- * Sleep utility.
- */
-function sleep(ms: number): Promise<void> {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-export { sleep };

package/src/client/sanitize.ts

@@ -1,31 +0,0 @@
-/**
- * Header Sanitization — Security layer for HTTP headers
- * 
- * Removes control characters and enforces size limits.
- * 
- * @see sdk-upgrade.md Section 1.4
- */
-
-const MAX_LEN = 1024;
-
-/**
- * Sanitize a single header value.
- * - Removes control characters (0x00-0x1F, 0x7F)
- * - Truncates to MAX_LEN
- */
-export function sanitizeHeader(v: string): string {
-    return v.replace(/[\u0000-\u001F\u007F]/g, "").slice(0, MAX_LEN);
-}
-
-/**
- * Sanitize all header values in a record.
- * Mutates in place for performance.
- */
-export function sanitizeHeaders(h: Record<string, string>): Record<string, string> {
-    for (const k in h) {
-        if (Object.prototype.hasOwnProperty.call(h, k) && h[k] !== undefined) {
-            h[k] = sanitizeHeader(h[k]);
-        }
-    }
-    return h;
-}

package/src/client/timeout.ts

@@ -1,59 +0,0 @@
-/**
- * Agent OS SDK - Timeout Logic
- * 
- * Wraps async operations with per-attempt timeout.
- * Proper abort signal propagation without listener leaks.
- */
-
-import { TimeoutError } from "../errors/index.js";
-
-/**
- * Wraps an async function with a timeout.
- * 
- * The timeout is per-attempt, not global. This ensures that slow attempts
- * don't consume the entire retry budget.
- * 
- * @param fn - Function to execute (receives an AbortSignal)
- * @param timeoutMs - Timeout in milliseconds
- * @param parentSignal - Optional parent AbortSignal for cancellation
- */
-export async function withTimeout<T>(
-    fn: (signal: AbortSignal) => Promise<T>,
-    timeoutMs: number,
-    parentSignal?: AbortSignal
-): Promise<T> {
-    const controller = new AbortController();
-
-    // Propagate parent abort
-    const onAbort = () => controller.abort();
-    parentSignal?.addEventListener("abort", onAbort, { once: true });
-
-    // Set timeout
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-        return await fn(controller.signal);
-    } catch (err) {
-        // If our timeout triggered the abort (not parent), throw TimeoutError
-        if (controller.signal.aborted && !parentSignal?.aborted) {
-            throw new TimeoutError(timeoutMs);
-        }
-        throw err;
-    } finally {
-        clearTimeout(timeoutId);
-        parentSignal?.removeEventListener("abort", onAbort);
-    }
-}
-
-/**
- * Creates an AbortController that times out after the specified duration.
- * Useful for creating deadline-aware operations.
- * 
- * @param timeoutMs - Timeout in milliseconds
- * @returns AbortController that will abort after timeout
- */
-export function createTimeoutController(timeoutMs: number): AbortController {
-    const controller = new AbortController();
-    setTimeout(() => controller.abort(), timeoutMs);
-    return controller;
-}

package/src/errors/factory.ts

@@ -1,140 +0,0 @@
-/**
- * Agent OS SDK - Error Factory
- * 
- * Creates typed errors from HTTP responses.
- * Preserves backend error codes and details for debugging.
- */
-
-import {
-    AgentOsError,
-    UnauthorizedError,
-    ForbiddenError,
-    NotFoundError,
-    ConflictError,
-    ValidationError,
-    RateLimitError,
-    ServerError,
-    type FieldError,
-    type ErrorOptions,
-} from "./index.js";
-
-/**
- * Creates a typed error from an HTTP response.
- * 
- * @param response - The fetch Response object
- * @param body - Parsed JSON body (if available)
- * @param requestPath - The original request path (for 404 errors)
- */
-export function createErrorFromResponse(
-    response: Response,
-    body?: { code?: string; message?: string; detail?: string; title?: string; details?: unknown },
-    requestPath?: string
-): AgentOsError {
-    const status = response.status;
-    const message =
-        body?.message ||
-        body?.detail ||
-        body?.title ||
-        response.statusText ||
-        `HTTP ${status}`;
-    const requestId = response.headers.get("x-request-id") ?? undefined;
-    const opts: ErrorOptions = {
-        requestId,
-        backendCode: body?.code,
-        details: body?.details,
-    };
-
-    switch (status) {
-        case 401:
-            return new UnauthorizedError(message, opts);
-
-        case 403:
-            return new ForbiddenError(message, opts);
-
-        case 404:
-            return new NotFoundError(message, requestPath, opts);
-
-        case 409:
-            return new ConflictError(message, opts);
-
-        case 400:
-        case 422:
-            return new ValidationError(
-                message,
-                status as 400 | 422,
-                parseFieldErrors(body?.details),
-                opts
-            );
-
-        case 429:
-            const retryAfterHeader = response.headers.get("Retry-After");
-            let retryAfterMs: number | undefined;
-
-            if (retryAfterHeader) {
-                // Retry-After can be seconds or a date
-                const seconds = parseInt(retryAfterHeader, 10);
-                if (!isNaN(seconds)) {
-                    retryAfterMs = seconds * 1000;
-                } else {
-                    // Try parsing as date
-                    const date = new Date(retryAfterHeader);
-                    if (!isNaN(date.getTime())) {
-                        retryAfterMs = Math.max(0, date.getTime() - Date.now());
-                    }
-                }
-            }
-
-            return new RateLimitError(message, retryAfterMs, opts);
-
-        default:
-            if (status >= 500) {
-                return new ServerError(message, status, opts);
-            }
-            // Fallback for unknown 4xx errors
-            return new ServerError(message, status, opts);
-    }
-}
-
-/**
- * Parses field errors from various backend formats.
- */
-function parseFieldErrors(details: unknown): FieldError[] | undefined {
-    if (!details || typeof details !== "object") {
-        return undefined;
-    }
-
-    // Format 1: Array of { field, message } objects
-    if (Array.isArray(details)) {
-        const errors = details.filter(
-            (d): d is FieldError =>
-                typeof d === "object" &&
-                d !== null &&
-                typeof d.field === "string" &&
-                typeof d.message === "string"
-        );
-        return errors.length > 0 ? errors : undefined;
-    }
-
-    // Format 2: { errors: [...] }
-    if ("errors" in details && Array.isArray((details as { errors: unknown }).errors)) {
-        return parseFieldErrors((details as { errors: unknown[] }).errors);
-    }
-
-    // Format 3: { field: [messages] } (Rails/Django style)
-    const entries = Object.entries(details);
-    if (entries.every(([, v]) => Array.isArray(v))) {
-        const errors: FieldError[] = [];
-        for (const [field, messages] of entries) {
-            if (Array.isArray(messages)) {
-                for (const message of messages) {
-                    if (typeof message === "string") {
-                        errors.push({ field, message });
-                    }
-                }
-            }
-        }
-        return errors.length > 0 ? errors : undefined;
-    }
-
-    return undefined;
-}