@agent-os-sdk/client 0.3.15 → 0.4.0

package/src/client/retry.ts

@@ -0,0 +1,150 @@
+/**
+ * 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/timeout.ts

@@ -0,0 +1,59 @@
+/**
+ * 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

@@ -0,0 +1,135 @@
+/**
+ * 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; details?: unknown },
+    requestPath?: string
+): AgentOsError {
+    const status = response.status;
+    const message = body?.message || 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;
+}

package/src/errors/index.ts

@@ -0,0 +1,365 @@
+/**
+ * Agent OS SDK - Typed Errors
+ * 
+ * Enterprise-grade error classification for predictable error handling.
+ * All errors extend AgentOsError and include semantic information.
+ */
+
+/**
+ * Options for constructing typed errors
+ */
+export interface ErrorOptions {
+    /** Request ID from x-request-id header */
+    requestId?: string;
+    /** Original error code from backend (preserves backend semantics) */
+    backendCode?: string;
+    /** Raw details object from backend response */
+    details?: unknown;
+}
+
+/**
+ * Base class for all Agent OS SDK errors.
+ * Provides consistent structure for error handling and classification.
+ */
+export abstract class AgentOsError extends Error {
+    /** Error code for programmatic handling */
+    abstract readonly code: string;
+
+    /** HTTP status code (0 for network/timeout errors) */
+    abstract readonly status: number;
+
+    /** Request ID from x-request-id header */
+    readonly requestId?: string;
+
+    /** Original error code from backend (preserves backend semantics) */
+    readonly backendCode?: string;
+
+    /** Raw details object from backend response */
+    readonly details?: unknown;
+
+    /** Timestamp when error occurred */
+    readonly timestamp: string = new Date().toISOString();
+
+    constructor(message: string, options?: ErrorOptions) {
+        super(message);
+        this.name = this.constructor.name;
+        this.requestId = options?.requestId;
+        this.backendCode = options?.backendCode;
+        this.details = options?.details;
+
+        // Maintains proper stack trace (V8 engines only)
+        if ("captureStackTrace" in Error && typeof Error.captureStackTrace === "function") {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+
+    /** 
+     * Whether this error is retryable with the same request.
+     * Override in subclasses for specific behavior.
+     */
+    isRetryable(): boolean {
+        return false;
+    }
+
+    /** Convert to JSON for logging/serialization */
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            code: this.code,
+            status: this.status,
+            message: this.message,
+            requestId: this.requestId,
+            backendCode: this.backendCode,
+            details: this.details,
+            timestamp: this.timestamp,
+        };
+    }
+}
+
+// ============================================================================
+// Authentication & Authorization Errors
+// ============================================================================
+
+/**
+ * 401 Unauthorized - Invalid or missing authentication.
+ * 
+ * @example
+ * if (error instanceof UnauthorizedError) {
+ *     // Redirect to login
+ * }
+ */
+export class UnauthorizedError extends AgentOsError {
+    readonly code = "UNAUTHORIZED";
+    readonly status = 401;
+
+    constructor(message = "Authentication required", options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
+/**
+ * 403 Forbidden - Valid auth but insufficient permissions.
+ * 
+ * @example
+ * if (error instanceof ForbiddenError) {
+ *     showToast("You don't have permission to perform this action");
+ * }
+ */
+export class ForbiddenError extends AgentOsError {
+    readonly code = "FORBIDDEN";
+    readonly status = 403;
+
+    constructor(message = "Access denied", options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
+// ============================================================================
+// Resource Errors
+// ============================================================================
+
+/**
+ * 404 Not Found - Resource does not exist.
+ * 
+ * @example
+ * if (error instanceof NotFoundError) {
+ *     console.log(`Not found at: ${error.path}`);
+ * }
+ */
+export class NotFoundError extends AgentOsError {
+    readonly code = "NOT_FOUND";
+    readonly status = 404;
+
+    constructor(
+        message = "Resource not found",
+        /** The request path that returned 404 */
+        readonly path?: string,
+        options?: ErrorOptions
+    ) {
+        super(message, options);
+    }
+}
+
+/**
+ * 409 Conflict - Resource already exists or state conflict.
+ * 
+ * @example
+ * if (error instanceof ConflictError) {
+ *     // Handle duplicate or version mismatch
+ * }
+ */
+export class ConflictError extends AgentOsError {
+    readonly code = "CONFLICT";
+    readonly status = 409;
+
+    constructor(message = "Resource conflict", options?: ErrorOptions) {
+        super(message, options);
+    }
+}
+
+// ============================================================================
+// Validation Errors
+// ============================================================================
+
+/**
+ * Field-level validation error detail.
+ */
+export interface FieldError {
+    field: string;
+    message: string;
+    code?: string;
+}
+
+/**
+ * 400/422 Validation Error - Invalid request data.
+ * 
+ * @example
+ * if (error instanceof ValidationError) {
+ *     error.fieldErrors?.forEach(fe => {
+ *         showFieldError(fe.field, fe.message);
+ *     });
+ * }
+ */
+export class ValidationError extends AgentOsError {
+    readonly code = "VALIDATION_ERROR";
+    readonly status: 400 | 422;
+
+    constructor(
+        message = "Validation failed",
+        status: 400 | 422 = 400,
+        readonly fieldErrors?: FieldError[],
+        options?: ErrorOptions
+    ) {
+        super(message, options);
+        this.status = status;
+    }
+
+    /** Get error message for a specific field */
+    getFieldError(field: string): string | undefined {
+        return this.fieldErrors?.find(fe => fe.field === field)?.message;
+    }
+
+    /** Check if a specific field has an error */
+    hasFieldError(field: string): boolean {
+        return this.fieldErrors?.some(fe => fe.field === field) ?? false;
+    }
+}
+
+// ============================================================================
+// Rate Limiting
+// ============================================================================
+
+/**
+ * 429 Too Many Requests - Rate limit exceeded.
+ * 
+ * @example
+ * if (error instanceof RateLimitError) {
+ *     if (error.retryAfterMs) {
+ *         await sleep(error.retryAfterMs);
+ *         // Retry request
+ *     }
+ * }
+ */
+export class RateLimitError extends AgentOsError {
+    readonly code = "RATE_LIMITED";
+    readonly status = 429;
+
+    constructor(
+        message = "Rate limit exceeded",
+        /** Time to wait before retrying (milliseconds) */
+        readonly retryAfterMs?: number,
+        options?: ErrorOptions
+    ) {
+        super(message, options);
+    }
+
+    isRetryable(): boolean {
+        return true;
+    }
+
+    /** Get retry delay or default */
+    getRetryDelay(defaultMs = 1000): number {
+        return this.retryAfterMs ?? defaultMs;
+    }
+}
+
+// ============================================================================
+// Server Errors
+// ============================================================================
+
+/**
+ * 5xx Server Error - Backend failure.
+ * 
+ * @example
+ * if (error instanceof ServerError) {
+ *     if (error.isRetryable()) {
+ *         // Retry with backoff
+ *     }
+ * }
+ */
+export class ServerError extends AgentOsError {
+    readonly code = "SERVER_ERROR";
+
+    constructor(
+        message = "Internal server error",
+        readonly status: number = 500,
+        options?: ErrorOptions
+    ) {
+        super(message, options);
+    }
+
+    isRetryable(): boolean {
+        // 500, 502, 503, 504 are typically retryable
+        return [500, 502, 503, 504].includes(this.status);
+    }
+}
+
+// ============================================================================
+// Network & Timeout Errors
+// ============================================================================
+
+/**
+ * Network Error - Fetch failed (no response received).
+ * 
+ * @example
+ * if (error instanceof NetworkError) {
+ *     showToast("Network connection failed. Check your internet.");
+ * }
+ */
+export class NetworkError extends AgentOsError {
+    readonly code = "NETWORK_ERROR";
+    readonly status = 0;
+
+    constructor(
+        message = "Network request failed",
+        readonly cause?: Error
+    ) {
+        super(message);
+    }
+
+    isRetryable(): boolean {
+        return true;
+    }
+}
+
+/**
+ * Timeout Error - Request exceeded time limit.
+ * 
+ * @example
+ * if (error instanceof TimeoutError) {
+ *     console.log(`Request timed out after ${error.timeoutMs}ms`);
+ * }
+ */
+export class TimeoutError extends AgentOsError {
+    readonly code = "TIMEOUT";
+    readonly status = 0;
+
+    constructor(
+        /** Timeout duration in milliseconds */
+        readonly timeoutMs: number
+    ) {
+        super(`Request timed out after ${timeoutMs}ms`);
+    }
+
+    isRetryable(): boolean {
+        return true;
+    }
+}
+
+// ============================================================================
+// Error Type Guards
+// ============================================================================
+
+/** Check if error is any Agent OS SDK error */
+export function isAgentOsError(error: unknown): error is AgentOsError {
+    return error instanceof AgentOsError;
+}
+
+/** Check if error is retryable */
+export function isRetryableError(error: unknown): boolean {
+    if (error instanceof AgentOsError) {
+        return error.isRetryable();
+    }
+    return false;
+}
+
+/** Check if error is an auth error (401 or 403) */
+export function isAuthError(error: unknown): error is UnauthorizedError | ForbiddenError {
+    return error instanceof UnauthorizedError || error instanceof ForbiddenError;
+}
+
+/** Check if error is a client error (4xx) */
+export function isClientError(error: unknown): boolean {
+    if (error instanceof AgentOsError) {
+        return error.status >= 400 && error.status < 500;
+    }
+    return false;
+}
+
+/** Check if error is a server error (5xx) */
+export function isServerError(error: unknown): boolean {
+    if (error instanceof AgentOsError) {
+        return error.status >= 500 && error.status < 600;
+    }
+    return false;
+}