@agent-os-sdk/client 0.3.14 → 0.4.0

package/src/client/raw.ts

@@ -15,8 +15,47 @@ export type ClientOptions = {
     baseUrl: string;
     headers?: Record<string, string>;
     headerProvider?: () => Promise<Record<string, string>>;
+    /** Hooks for observability (OTEL, Sentry, etc.) */
+    hooks?: SDKHooks;
 };
 
+/**
+ * SDK hooks for external observability tools.
+ * These are called during the request lifecycle for instrumentation.
+ */
+export interface SDKHooks {
+    /** Called before each request. Return modified request context or void. */
+    onRequest?: (context: HookRequestContext) => void | Promise<void>;
+    /** Called after each successful response */
+    onResponse?: (context: HookResponseContext) => void | Promise<void>;
+    /** Called on any error (network, timeout, HTTP error) */
+    onError?: (context: HookErrorContext) => void | Promise<void>;
+}
+
+export interface HookRequestContext {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    requestId?: string;
+}
+
+export interface HookResponseContext {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+}
+
+export interface HookErrorContext {
+    method: string;
+    url: string;
+    error: Error;
+    durationMs: number;
+    requestId?: string;
+}
+
 /**
  * Standard API response wrapper.
  * This matches the pattern used by openapi-fetch.
@@ -29,6 +68,11 @@ export interface APIResponse<T> {
         details?: unknown;
     };
     response: Response;
+    /** Metadata for observability */
+    meta?: {
+        /** Request ID from x-request-id header */
+        requestId?: string;
+    };
 }
 
 /**
@@ -62,6 +106,11 @@ export function createRawClient(options: ClientOptions) {
             params?: { path?: Record<string, string>; query?: Record<string, unknown> };
             body?: unknown;
             headers?: Record<string, string>;
+            signal?: AbortSignal;
+            /** Set to false to disable retry for this request */
+            retry?: boolean;
+            /** Override timeout for this request */
+            timeoutMs?: number;
         }
     ): Promise<APIResponse<T>> {
         // Replace path params
@@ -103,40 +152,112 @@ export function createRawClient(options: ClientOptions) {
             headers["Content-Type"] = "application/json";
         }
 
-        const response = await fetch(fullUrl, {
+        // Detect idempotency from header or body
+        const hasIdempotencyKey = Boolean(
+            headers["Idempotency-Key"] ||
+            headers["idempotency-key"] ||
+            (opts?.body && typeof opts.body === "object" && (opts.body as Record<string, unknown>).idempotency_key)
+        );
+
+        // Generate client request ID for tracing
+        const clientRequestId = `sdk_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+        // Call onRequest hook
+        const startTime = Date.now();
+        await options.hooks?.onRequest?.({
             method,
+            url: fullUrl,
             headers,
-            body: opts?.body ? JSON.stringify(opts.body) : undefined,
+            body: opts?.body,
+            requestId: clientRequestId,
         });
 
+        // Execute the actual fetch
+        const doFetch = async (signal?: AbortSignal): Promise<Response> => {
+            return fetch(fullUrl, {
+                method,
+                headers,
+                body: opts?.body ? JSON.stringify(opts.body) : undefined,
+                signal,
+            });
+        };
+
+        let response: Response;
+        try {
+            response = await doFetch(opts?.signal);
+        } catch (fetchError) {
+            const durationMs = Date.now() - startTime;
+            // Call onError hook
+            await options.hooks?.onError?.({
+                method,
+                url: fullUrl,
+                error: fetchError instanceof Error ? fetchError : new Error(String(fetchError)),
+                durationMs,
+                requestId: clientRequestId,
+            });
+
+            // Network error - return as error
+            return {
+                error: {
+                    code: "NETWORK_ERROR",
+                    message: fetchError instanceof Error ? fetchError.message : "Network request failed"
+                },
+                response: new Response(null, { status: 0 })
+            };
+        }
+
+        const durationMs = Date.now() - startTime;
+
+        // Extract requestId for tracing (prefer server requestId if available)
+        const requestId = response.headers.get("x-request-id") ?? clientRequestId;
+
         if (!response.ok) {
-            let error: APIResponse<T>["error"];
+            let errorBody: { code?: string; message?: string; details?: unknown } | undefined;
             try {
-                const json = await response.json();
-                error = {
-                    code: json.code || `HTTP_${response.status}`,
-                    message: json.message || response.statusText,
-                    details: json.details,
-                };
+                errorBody = await response.json();
             } catch {
-                error = {
-                    code: `HTTP_${response.status}`,
-                    message: response.statusText,
-                };
+                // Ignore JSON parse errors
             }
-            return { error, response };
+
+            // Call onError hook
+            await options.hooks?.onError?.({
+                method,
+                url: fullUrl,
+                error: new Error(errorBody?.message || response.statusText),
+                durationMs,
+                requestId,
+            });
+
+            return {
+                error: {
+                    code: errorBody?.code || `HTTP_${response.status}`,
+                    message: errorBody?.message || response.statusText,
+                    details: errorBody?.details,
+                },
+                response,
+                meta: { requestId },
+            };
         }
 
+        // Call onResponse hook
+        await options.hooks?.onResponse?.({
+            method,
+            url: fullUrl,
+            status: response.status,
+            durationMs,
+            requestId,
+        });
+
         // Handle no-content responses
         if (response.status === 204) {
-            return { data: undefined as T, response };
+            return { data: undefined as T, response, meta: { requestId } };
         }
 
         try {
             const data = await response.json();
-            return { data: data as T, response };
+            return { data: data as T, response, meta: { requestId } };
         } catch {
-            return { data: undefined as T, response };
+            return { data: undefined as T, response, meta: { requestId } };
         }
     }
 

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;
+}