@agent-os-sdk/client 0.3.14 → 0.4.0

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

package/src/index.ts

@@ -64,6 +64,68 @@ export {
     type Unwrapped,
 } from "./client/helpers.js";
 
+// ============================================================================
+// Typed Errors (Enterprise)
+// ============================================================================
+export {
+    // Base class
+    AgentOsError,
+    type ErrorOptions,
+    // Error classes
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    ConflictError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    NetworkError,
+    TimeoutError,
+    // Field errors
+    type FieldError,
+    // Type guards
+    isAgentOsError,
+    isRetryableError,
+    isAuthError,
+    isClientError,
+    isServerError,
+} from "./errors/index.js";
+
+export { createErrorFromResponse } from "./errors/factory.js";
+
+// ============================================================================
+// Network Configuration
+// ============================================================================
+export {
+    type RetryConfig,
+    type NetworkConfig,
+    DEFAULT_NETWORK_CONFIG,
+    INTERACTIVE_NETWORK_CONFIG,
+    BACKGROUND_NETWORK_CONFIG,
+    mergeNetworkConfig,
+} from "./client/config.js";
+
+// ============================================================================
+// Retry & Timeout Utilities
+// ============================================================================
+export { withRetry, type RetryContext, sleep } from "./client/retry.js";
+export { withTimeout, createTimeoutController } from "./client/timeout.js";
+
+// ============================================================================
+// Pagination Utilities
+// ============================================================================
+export {
+    paginate,
+    collectAll,
+    getFirst,
+    type OffsetPaginatedResponse,
+    type CursorPaginatedResponse,
+    type OffsetParams,
+    type CursorParams,
+    type PaginateOptions,
+} from "./client/pagination.js";
+
+
 // ============================================================================
 // Raw Client & Core Types
 // ============================================================================
@@ -74,6 +136,11 @@ export {
     type TypedClient,
     type ClientOptions,
     type APIResponse,
+    // SDK Hooks for observability (OTEL, Sentry, etc.)
+    type SDKHooks,
+    type HookRequestContext,
+    type HookResponseContext,
+    type HookErrorContext,
 } from "./client/raw.js";
 
 // Export OpenAPI types
@@ -85,7 +152,7 @@ export type { paths, components } from "./client/raw.js";
 
 // Core modules
 export { AgentsModule, type Agent, type AgentVersion, type AgentListResponse, type AgentGraphResponse } from "./modules/agents.js";
-export { RunsModule, type Run, type RunStatus, type RunEvent, type RunListResponse, type RunEventsResponse, type CreateRunResponse, type RunEventsPollResponse, type RunEventDto } from "./modules/runs.js";
+export { RunsModule, type Run, type RunStatus, type RunEvent, type RunListResponse, type RunEventsResponse, type CreateRunResponse, type RunEventsPollResponse, type RunEventDto, type FollowOptions, type FollowEvent } from "./modules/runs.js";
 export { ThreadsModule, type Thread, type ThreadState, type ThreadMessage, type ThreadRun, type ThreadListResponse, type ThreadMessagesResponse } from "./modules/threads.js";
 export { ToolsModule, type Tool, type ToolListResponse } from "./modules/tools.js";
 export { KnowledgeModule, type KnowledgeDataset, type KnowledgeSearchResponse } from "./modules/knowledge.js";
@@ -112,7 +179,7 @@ export { UsageModule, type UsageResponse, type UsageQuota } from "./modules/usag
 export { McpModule, type McpServer } from "./modules/mcp.js";
 export { A2aModule, type JsonRpcRequest, type JsonRpcResponse, type A2aAgentCard } from "./modules/a2a.js";
 export { MeModule, type MeResponse } from "./modules/me.js";
-export { InfoModule, type ServerInfo } from "./modules/info.js";
+export { InfoModule, type ServerInfo, type ServerCapabilities } from "./modules/info.js";
 export { MetricsModule, type MetricsResponse } from "./modules/metrics.js";
 export { GraphsModule, type GraphValidationResult, type GraphIntrospectionResult } from "./modules/graphs.js";
 export { CatalogModule, type CatalogVersions, type NodeCatalogResponse, type ToolCatalogResponse, type TriggerCatalogResponse, type NodeDefinition, type ToolDefinition, type TriggerTemplate } from "./modules/catalog.js";
@@ -120,6 +187,9 @@ export { CatalogModule, type CatalogVersions, type NodeCatalogResponse, type Too
 // Approvals is real (has backend implementation)
 export { ApprovalsModule, type Approval, type ApprovalStatus, type ApprovalDecision, type ApprovalListResponse, type ApprovalStatusResponse } from "./modules/approvals.js";
 
+export { ApiTokensModule, type ApiToken, type ApiTokenSecret, type CreateTokenRequest, type RotateTokenResponse } from "./modules/apiTokens.js";
+export { MembershipsModule, type MembershipResponse, type EnsureMembershipRequest } from "./modules/memberships.js";
+
 // ============================================================================
 // SSE Streaming
 // ============================================================================

package/src/modules/audit.ts

@@ -37,11 +37,21 @@ export class AuditModule {
         workspace_id?: string;
         from?: string;
         to?: string;
-        skip?: number;
-        take?: number;
+        limit?: number;
+        offset?: number;
     }): Promise<APIResponse<AuditListResponse>> {
+        const queryParams: any = { ...params };
+        if (params?.limit !== undefined) {
+            queryParams.take = params.limit;
+            delete queryParams.limit;
+        }
+        if (params?.offset !== undefined) {
+            queryParams.skip = params.offset;
+            delete queryParams.offset;
+        }
+
         return this.client.GET<AuditListResponse>("/v1/api/audit", {
-            params: { query: params },
+            params: { query: queryParams },
             headers: this.headers(),
         });
     }
@@ -63,12 +73,73 @@ export class AuditModule {
         query?: string;
         from?: string;
         to?: string;
-        skip?: number;
-        take?: number;
+        limit?: number;
+        offset?: number;
     }): Promise<APIResponse<AuditListResponse>> {
+        const queryParams: any = { ...params };
+        if (params?.limit !== undefined) {
+            queryParams.take = params.limit;
+            delete queryParams.limit;
+        }
+        if (params?.offset !== undefined) {
+            queryParams.skip = params.offset;
+            delete queryParams.offset;
+        }
+
         return this.client.GET<AuditListResponse>("/v1/api/audit/search", {
-            params: { query: params },
+            params: { query: queryParams },
             headers: this.headers(),
         });
     }
+
+    /**
+     * Iterate through all audit logs with automatic pagination.
+     * 
+     * @example
+     * ```ts
+     * // Get all audit logs for a specific action
+     * for await (const entry of client.audit.iterate({ action: "agent.created" })) {
+     *     console.log(entry.actor, entry.action);
+     * }
+     * ```
+     */
+    async *iterate(
+        filters?: {
+            actor?: string;
+            action?: string;
+            resource?: string;
+            workspace_id?: string;
+            from?: string;
+            to?: string;
+        },
+        options?: { pageSize?: number; maxItems?: number; signal?: AbortSignal }
+    ): AsyncGenerator<AuditLogEntry, void, unknown> {
+        const pageSize = options?.pageSize ?? 100;
+        const maxItems = options?.maxItems ?? Infinity;
+        let offset = 0;
+        let yielded = 0;
+        let hasMore = true;
+
+        while (hasMore && yielded < maxItems) {
+            if (options?.signal?.aborted) return;
+
+            const response = await this.list({
+                ...filters,
+                limit: Math.min(pageSize, maxItems - yielded),
+                offset,
+            });
+
+            if (response.error) throw response.error;
+            const data = response.data!;
+
+            for (const entry of data.items) {
+                if (yielded >= maxItems) return;
+                yield entry;
+                yielded++;
+            }
+
+            offset += data.items.length;
+            hasMore = offset < data.total && data.items.length > 0;
+        }
+    }
 }

package/src/modules/catalog.ts

@@ -39,14 +39,17 @@ export interface CatalogMetadata {
 }
 
 export interface NodeCatalogResponse extends CatalogMetadata {
-    nodes: Record<string, NodeDefinition>;
+    nodes: NodeDefinition[];
 }
 
 export interface NodeDefinition {
-    kind: string;
+    id: string;
+    title: string;
     category: string;
-    description: string;
+    description?: string;
+    ports?: { inputs?: string[]; outputs?: string[] };
     config_schema?: Record<string, unknown>;
+    default_config?: Record<string, unknown>;
 }
 
 export interface ToolCatalogResponse extends CatalogMetadata {
@@ -65,7 +68,7 @@ export interface ToolDefinition {
 }
 
 export interface TriggerCatalogResponse extends CatalogMetadata {
-    triggers: TriggerTemplate[];
+    templates: TriggerTemplate[];
 }
 
 export interface TriggerTemplate {
@@ -75,6 +78,20 @@ export interface TriggerTemplate {
     run_input_schema?: Record<string, unknown>;
 }
 
+export interface PresetCatalogResponse extends CatalogMetadata {
+    presets: PresetDefinition[];
+}
+
+export interface PresetDefinition {
+    preset_slug: string;
+    base_node_slug: string;
+    title: string;
+    description?: string;
+    default_config?: Record<string, unknown>;
+    locked_fields?: string[];
+    ui_variant?: string;
+}
+
 export class CatalogModule {
     constructor(private client: RawClient) { }
 
@@ -115,6 +132,18 @@ export class CatalogModule {
         return response;
     }
 
+    /**
+     * Get the Node Presets Catalog.
+     * Returns pre-configured node variants with locked fields.
+     */
+    async getPresets(version: string = "1"): Promise<APIResponse<PresetCatalogResponse>> {
+        const response = await this.client.GET<PresetCatalogResponse>("/v1/api/catalog/presets", {
+            params: { query: { version } },
+        });
+
+        return response;
+    }
+
     /**
      * Get all catalogs at once for convenience.
      * Returns combined catalog data with versions.
@@ -124,25 +153,29 @@ export class CatalogModule {
             nodes: NodeCatalogResponse;
             tools: ToolCatalogResponse;
             triggers: TriggerCatalogResponse;
+            presets: PresetCatalogResponse;
             catalog_versions: CatalogVersions;
         };
         error?: { code: string; message: string; details?: unknown };
     }> {
-        const [nodesRes, toolsRes, triggersRes] = await Promise.all([
+        const [nodesRes, toolsRes, triggersRes, presetsRes] = await Promise.all([
             this.getNodes(version),
             this.getTools(version),
             this.getTriggers(version),
+            this.getPresets(version),
         ]);
 
         if (nodesRes.error) return { data: undefined, error: nodesRes.error };
         if (toolsRes.error) return { data: undefined, error: toolsRes.error };
         if (triggersRes.error) return { data: undefined, error: triggersRes.error };
+        if (presetsRes.error) return { data: undefined, error: presetsRes.error };
 
         return {
             data: {
                 nodes: nodesRes.data!,
                 tools: toolsRes.data!,
                 triggers: triggersRes.data!,
+                presets: presetsRes.data!,
                 catalog_versions: {
                     nodes: version,
                     tools: version,

package/src/modules/checkpoints.ts

@@ -66,7 +66,7 @@ export class CheckpointsModule {
      * Replay from a checkpoint.
      */
     async replay(checkpointId: string, options?: {
-        mode?: "best_effort" | "deterministic";
+        mode?: "best_effort" | "strict";
         modified_state?: unknown;
     }): Promise<APIResponse<ReplayResponse>> {
         return this.client.POST<ReplayResponse>("/v1/api/checkpoints/{id}/replay", {