@agent-os-sdk/client 0.3.15 → 0.4.0

package/dist/sse/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/sse/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/sse/client.ts"],"names":[],"mappings":"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"}

package/dist/sse/client.js

@@ -31,6 +31,8 @@ export async function* parseSSE(response, options) {
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    // State must be maintained across chunks
+    let currentEvent = { event: "message" };
     try {
         while (true) {
             const { done, value } = await reader.read();
@@ -38,15 +40,29 @@ export async function* parseSSE(response, options) {
                 break;
             buffer += decoder.decode(value, { stream: true });
             const lines = buffer.split("\n");
+            // Keep the last partial line in the buffer
             buffer = lines.pop() ?? "";
-            let currentEvent = { event: "message" };
             for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed === "") {
+                    // Empty line triggers event dispatch if we have data
+                    if (currentEvent.data !== undefined) {
+                        yield currentEvent;
+                    }
+                    // Reset for next event
+                    currentEvent = { event: "message" };
+                    continue;
+                }
                 if (line.startsWith("event:")) {
                     currentEvent.event = line.slice(6).trim();
                 }
                 else if (line.startsWith("data:")) {
                     const dataStr = line.slice(5).trim();
                     try {
+                        // Accumulate data if meaningful (though standard SSE usually has one data line per event, 
+                        // multiline data is possible but rare in this specific protocol. 
+                        // For simplicity and matching current backend, we overwrite or concatenation check could be stricter).
+                        // Given strict JSON protocol, we assume valid info per data line or single data line.
                         currentEvent.data = JSON.parse(dataStr);
                     }
                     catch {
@@ -59,10 +75,6 @@ export async function* parseSSE(response, options) {
                 else if (line.startsWith("retry:")) {
                     currentEvent.retry = parseInt(line.slice(6).trim(), 10);
                 }
-                else if (line === "" && currentEvent.data !== undefined) {
-                    yield currentEvent;
-                    currentEvent = { event: "message" };
-                }
             }
         }
     }

package/package.json

@@ -1,52 +1,51 @@
 {
-    "name": "@agent-os-sdk/client",
-    "version": "0.3.15",
-    "description": "Official TypeScript SDK for Agent OS platform",
-    "type": "module",
-    "main": "./dist/index.js",
-    "module": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./dist/index.js",
-            "types": "./dist/index.d.ts"
-        }
-    },
-    "scripts": {
-        "generate": "tsx scripts/generate.ts",
-        "build": "tsc",
-        "dev": "tsc --watch",
-        "test": "vitest run",
-        "typecheck": "tsc --noEmit",
-        "prepublishOnly": "pnpm build"
-    },
-    "keywords": [
-        "agent-os",
-        "sdk",
-        "ai",
-        "agents",
-        "typescript"
-    ],
-    "author": "Agent OS Team",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/yuri12344/agent-os.git"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "openapi-fetch": "^0.13.0"
-    },
-    "devDependencies": {
-        "openapi-typescript": "^7.4.0",
-        "tsx": "^4.19.0",
-        "typescript": "^5.5.0",
-        "vitest": "^4.0.18"
-    },
-    "files": [
-        "dist",
-        "src"
-    ]
+  "name": "@agent-os-sdk/client",
+  "version": "0.4.0",
+  "description": "Official TypeScript SDK for Agent OS platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "agent-os",
+    "sdk",
+    "ai",
+    "agents",
+    "typescript"
+  ],
+  "author": "Agent OS Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuri12344/agent-os.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.13.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "generate": "tsx scripts/generate.ts",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/client/config.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent OS SDK - Network Configuration
+ * 
+ * Centralized configuration for timeouts, retries, and network policies.
+ */
+
+/**
+ * Retry configuration for network requests.
+ */
+export interface RetryConfig {
+    /** Maximum retry attempts (default: 3) */
+    maxRetries: number;
+
+    /** Base delay between retries in ms (default: 1000) */
+    baseDelayMs: number;
+
+    /** Maximum delay between retries in ms (default: 30000) */
+    maxDelayMs: number;
+
+    /** Jitter factor to prevent thundering herd (0-1, default: 0.2) */
+    jitterFactor: number;
+
+    /** HTTP status codes that trigger retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatuses: number[];
+}
+
+/**
+ * Full network configuration for the SDK client.
+ */
+export interface NetworkConfig {
+    /** Timeout per request attempt in milliseconds (default: 30000) */
+    timeoutMs: number;
+
+    /** Retry configuration */
+    retry: RetryConfig;
+}
+
+/**
+ * Default network configuration.
+ * Balanced for most use cases - 30s timeout, 3 retries with exponential backoff.
+ */
+export const DEFAULT_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 30_000,
+    retry: {
+        maxRetries: 3,
+        baseDelayMs: 1_000,
+        maxDelayMs: 30_000,
+        jitterFactor: 0.2,
+        retryableStatuses: [408, 429, 500, 502, 503, 504],
+    },
+};
+
+/**
+ * Aggressive configuration for interactive UIs.
+ * Shorter timeouts, fewer retries.
+ */
+export const INTERACTIVE_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 10_000,
+    retry: {
+        maxRetries: 1,
+        baseDelayMs: 500,
+        maxDelayMs: 5_000,
+        jitterFactor: 0.1,
+        retryableStatuses: [429, 503, 504],
+    },
+};
+
+/**
+ * Patient configuration for background jobs.
+ * Longer timeouts, more retries.
+ */
+export const BACKGROUND_NETWORK_CONFIG: NetworkConfig = {
+    timeoutMs: 120_000,
+    retry: {
+        maxRetries: 5,
+        baseDelayMs: 2_000,
+        maxDelayMs: 60_000,
+        jitterFactor: 0.3,
+        retryableStatuses: [408, 429, 500, 502, 503, 504],
+    },
+};
+
+/**
+ * Merges user config with defaults.
+ */
+export function mergeNetworkConfig(
+    userConfig?: Partial<NetworkConfig>
+): NetworkConfig {
+    if (!userConfig) {
+        return DEFAULT_NETWORK_CONFIG;
+    }
+
+    return {
+        timeoutMs: userConfig.timeoutMs ?? DEFAULT_NETWORK_CONFIG.timeoutMs,
+        retry: {
+            ...DEFAULT_NETWORK_CONFIG.retry,
+            ...userConfig.retry,
+        },
+    };
+}

package/src/client/pagination.ts

@@ -0,0 +1,218 @@
+/**
+ * Agent OS SDK - Pagination Utilities
+ * 
+ * Auto-paginating iterators that support both offset and cursor pagination.
+ * Designed to work with any list endpoint.
+ */
+
+import type { APIResponse } from "./raw.js";
+
+// ============================================================================
+// Response Types
+// ============================================================================
+
+/**
+ * Offset-based paginated response.
+ * Most common format for list endpoints.
+ */
+export interface OffsetPaginatedResponse<T> {
+    items: T[];
+    total: number;
+}
+
+/**
+ * Cursor-based paginated response.
+ * Better for large datasets and real-time consistency.
+ */
+export interface CursorPaginatedResponse<T> {
+    items: T[];
+    next_cursor?: string;
+    has_more: boolean;
+}
+
+/**
+ * Union type for both pagination styles.
+ */
+export type PaginatedResponse<T> =
+    | OffsetPaginatedResponse<T>
+    | CursorPaginatedResponse<T>;
+
+// ============================================================================
+// Parameter Types
+// ============================================================================
+
+/**
+ * Offset pagination parameters.
+ */
+export interface OffsetParams {
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Cursor pagination parameters.
+ */
+export interface CursorParams {
+    limit?: number;
+    after?: string;
+}
+
+/**
+ * Combined pagination parameters.
+ */
+export type PaginationParams = OffsetParams | CursorParams;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Checks if response uses cursor pagination.
+ */
+function isCursorResponse<T>(response: PaginatedResponse<T>): response is CursorPaginatedResponse<T> {
+    return "has_more" in response;
+}
+
+// ============================================================================
+// Paginate Function
+// ============================================================================
+
+/**
+ * Options for pagination behavior.
+ */
+export interface PaginateOptions {
+    /** Number of items per page (default: 100) */
+    pageSize?: number;
+
+    /** Maximum total items to fetch (default: unlimited) */
+    maxItems?: number;
+
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+
+/**
+ * Creates an async iterator that automatically paginates through results.
+ * Supports both offset and cursor pagination transparently.
+ * 
+ * @example
+ * // Basic usage
+ * for await (const run of paginate(
+ *     (p) => client.runs.list(p),
+ *     { status: "completed" }
+ * )) {
+ *     console.log(run.id);
+ * }
+ * 
+ * @example
+ * // With options
+ * for await (const agent of paginate(
+ *     (p) => client.agents.list(p),
+ *     { workspace_id: "ws_123" },
+ *     { pageSize: 50, maxItems: 200 }
+ * )) {
+ *     console.log(agent.name);
+ * }
+ */
+export async function* paginate<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">,
+    options?: PaginateOptions
+): AsyncGenerator<T, void, unknown> {
+    const pageSize = options?.pageSize ?? 100;
+    const maxItems = options?.maxItems ?? Infinity;
+    const signal = options?.signal;
+
+    let offset = 0;
+    let cursor: string | undefined;
+    let hasMore = true;
+    let yielded = 0;
+
+    while (hasMore && yielded < maxItems) {
+        // Check for cancellation
+        if (signal?.aborted) {
+            return;
+        }
+
+        // Build params based on pagination style
+        const params = {
+            ...baseParams,
+            limit: Math.min(pageSize, maxItems - yielded),
+            ...(cursor !== undefined ? { after: cursor } : { offset }),
+        } as P;
+
+        const response = await fetchPage(params);
+
+        if (response.error) {
+            throw response.error;
+        }
+
+        const data = response.data!;
+
+        for (const item of data.items) {
+            if (yielded >= maxItems) {
+                return;
+            }
+            yield item;
+            yielded++;
+        }
+
+        // Update pagination state based on response type
+        if (isCursorResponse(data)) {
+            cursor = data.next_cursor;
+            hasMore = data.has_more && data.items.length > 0;
+        } else {
+            offset += data.items.length;
+            hasMore = offset < data.total && data.items.length > 0;
+        }
+    }
+}
+
+// ============================================================================
+// Collect Utility
+// ============================================================================
+
+/**
+ * Collects all items from a paginated endpoint into an array.
+ * Useful when you need all items at once.
+ * 
+ * @example
+ * const allRuns = await collectAll(
+ *     (p) => client.runs.list(p),
+ *     { status: "completed" },
+ *     { maxItems: 1000 }
+ * );
+ */
+export async function collectAll<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">,
+    options?: PaginateOptions
+): Promise<T[]> {
+    const items: T[] = [];
+
+    for await (const item of paginate(fetchPage, baseParams, options)) {
+        items.push(item);
+    }
+
+    return items;
+}
+
+/**
+ * Gets the first item from a paginated endpoint.
+ * More efficient than collecting all items when you only need one.
+ * 
+ * @example
+ * const latestRun = await getFirst(
+ *     (p) => client.runs.list({ ...p, order: "desc" }),
+ *     { agent_id: "agent_123" }
+ * );
+ */
+export async function getFirst<T, P extends PaginationParams>(
+    fetchPage: (params: P) => Promise<APIResponse<PaginatedResponse<T>>>,
+    baseParams: Omit<P, "limit" | "offset" | "after">
+): Promise<T | undefined> {
+    for await (const item of paginate(fetchPage, baseParams, { pageSize: 1, maxItems: 1 })) {
+        return item;
+    }
+    return undefined;
+}

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