@agent-os-sdk/client 0.3.15 → 0.4.1

package/src/index.ts

@@ -42,135 +42,156 @@ export { AgentOsClient, type AgentOsClientOptions, type AuthProvider } from "./c
 
 // Auth Provider Types
 export {
-    type ApiTokenAuth,
-    type JwtAuth,
-    isApiTokenAuth,
-    isJwtAuth,
-    isBrowser,
-    isApiToken,
-    isJwtToken,
+    isApiToken, isApiTokenAuth, isBrowser, isJwtAuth, isJwtToken, type ApiTokenAuth,
+    type JwtAuth
 } from "./client/auth.js";
 
 // ============================================================================
 // Helpers & Utilities
 // ============================================================================
 export {
-    unwrap,
-    toResult,
-    SDKError,
-    type PaginationParams,
-    type PaginatedResponse,
-    type Result,
-    type Unwrapped,
+    SDKError, toResult, unwrap, type PaginatedResponse, type PaginationParams, type Result,
+    type Unwrapped
 } from "./client/helpers.js";
 
+// ============================================================================
+// Typed Errors (Enterprise)
+// ============================================================================
+export {
+    // Base class
+    AgentOsError, ConflictError, ForbiddenError, NetworkError, NotFoundError, RateLimitError,
+    ServerError, TimeoutError,
+    // Error classes
+    UnauthorizedError, ValidationError,
+    // Type guards
+    isAgentOsError, isAuthError,
+    isClientError, isRetryableError, isServerError, type ErrorOptions,
+    // Field errors
+    type FieldError
+} from "./errors/index.js";
+
+export { createErrorFromResponse } from "./errors/factory.js";
+
+// ============================================================================
+// Network Configuration
+// ============================================================================
+export {
+    BACKGROUND_NETWORK_CONFIG, DEFAULT_NETWORK_CONFIG,
+    INTERACTIVE_NETWORK_CONFIG, mergeNetworkConfig, type NetworkConfig, type RetryConfig
+} from "./client/config.js";
+
+// ============================================================================
+// Retry & Timeout Utilities
+// ============================================================================
+export { sleep, withRetry, type RetryContext } from "./client/retry.js";
+export { createTimeoutController, withTimeout } from "./client/timeout.js";
+
+// ============================================================================
+// Pagination Utilities
+// ============================================================================
+export {
+    collectAll,
+    getFirst, paginate, type CursorPaginatedResponse, type CursorParams, type OffsetPaginatedResponse, type OffsetParams, type PaginateOptions
+} from "./client/pagination.js";
+
+
 // ============================================================================
 // Raw Client & Core Types
 // ============================================================================
 export {
     createRawClient,
-    createTypedClient,
-    type RawClient,
-    type TypedClient,
-    type ClientOptions,
-    type APIResponse,
+    createTypedClient, type APIResponse, type ClientOptions, type HookErrorContext, type HookRequestContext,
+    type HookResponseContext, type RawClient,
+    // SDK Hooks for observability (OTEL, Sentry, etc.)
+    type SDKHooks, type TypedClient
 } from "./client/raw.js";
 
 // Export OpenAPI types
-export type { paths, components } from "./client/raw.js";
+export type { components, paths } from "./client/raw.js";
 
 // ============================================================================
 // Module Classes
 // ============================================================================
 
 // 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 { 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";
-export { TriggersModule, type Trigger, type TriggerListResponse } from "./modules/triggers.js";
-export { CredentialsModule, type Credential, type CredentialListResponse, type CredentialType } from "./modules/credentials.js";
+export { AgentsModule, type Agent, type AgentGraphResponse, type AgentListResponse, type AgentVersion } from "./modules/agents.js";
 export { BuilderModule, type BuilderChatRequest, type BuilderChatResponse, type BuilderStreamEvent, type GraphUpdateAction } from "./modules/builder.js";
-export { MembersModule, type Member, type MemberListResponse } from "./modules/members.js";
+export { CredentialsModule, type Credential, type CredentialListResponse, type CredentialType } from "./modules/credentials.js";
+export { KnowledgeModule, type KnowledgeDataset, type KnowledgeSearchResponse } from "./modules/knowledge.js";
+export { MembersModule, type Member, type MemberListResponse, type Role } from "./modules/members.js";
+export { RunsModule, type CreateRunResponse, type FollowEvent, type FollowOptions, type Run, type RunEvent, type RunEventDto, type RunEventsPollResponse, type RunEventsResponse, type RunListResponse, type RunStatus } from "./modules/runs.js";
 export { TenantsModule, type Tenant } from "./modules/tenants.js";
+export { ThreadsModule, type Thread, type ThreadListResponse, type ThreadMessage, type ThreadMessagesResponse, type ThreadRun, type ThreadState } from "./modules/threads.js";
+export { ToolsModule, type Tool, type ToolListResponse } from "./modules/tools.js";
+export { TriggersModule, type Trigger, type TriggerListResponse } from "./modules/triggers.js";
 export { WorkspacesModule, type Workspace, type WorkspaceListResponse } from "./modules/workspaces.js";
 
 // Platform modules
-export { PromptsModule, type Prompt, type PromptVersion, type PromptListResponse } from "./modules/prompts.js";
-export { TracesModule, type Trace, type Span, type TraceListResponse, type SpanData, type FeedbackRequest } from "./modules/traces.js";
-export { FilesModule, type StoredFile, type FileListResponse, type PresignedUpload } from "./modules/files.js";
-export { VectorStoresModule, type VectorStore, type VectorStoreListResponse, type VectorQueryResult } from "./modules/vectorStores.js";
-export { EvaluationModule, type EvalDataset, type Experiment, type ExampleData } from "./modules/evaluation.js";
+export { A2aModule, type A2aAgentCard, type JsonRpcRequest, type JsonRpcResponse } from "./modules/a2a.js";
+export { AuditModule, type AuditListResponse, type AuditLogEntry } from "./modules/audit.js";
+export { CatalogModule, type CatalogVersions, type NodeCatalogResponse, type NodeDefinition, type ToolCatalogResponse, type ToolDefinition, type TriggerCatalogResponse, type TriggerTemplate } from "./modules/catalog.js";
 export { CheckpointsModule, type Checkpoint, type CheckpointsResponse } from "./modules/checkpoints.js";
-export { PlaygroundModule, type PlaygroundSession } from "./modules/playground.js";
 export { CronsModule, type CronJob, type CronJobListResponse } from "./modules/crons.js";
-export { DlqModule, type DlqMessage, type DlqListResponse } from "./modules/dlq.js";
-export { StoreModule, type StoreValue } from "./modules/store.js";
-export { AuditModule, type AuditLogEntry, type AuditListResponse } from "./modules/audit.js";
-export { UsageModule, type UsageResponse, type UsageQuota } from "./modules/usage.js";
+export { DlqModule, type DlqListResponse, type DlqMessage } from "./modules/dlq.js";
+export { EvaluationModule, type EvalDataset, type ExampleData, type Experiment } from "./modules/evaluation.js";
+export { FilesModule, type FileListResponse, type PresignedUpload, type StoredFile } from "./modules/files.js";
+export { GraphsModule, type GraphIntrospectionResult, type GraphValidationResult } from "./modules/graphs.js";
+export { InfoModule, type ServerCapabilities, type ServerInfo } from "./modules/info.js";
 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 { 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";
+export { PlaygroundModule, type PlaygroundSession } from "./modules/playground.js";
+export { PromptsModule, type Prompt, type PromptListResponse, type PromptVersion } from "./modules/prompts.js";
+export { StoreModule, type StoreValue } from "./modules/store.js";
+export { TracesModule, type FeedbackRequest, type Span, type SpanData, type Trace, type TraceListResponse } from "./modules/traces.js";
+export { UsageModule, type UsageQuota, type UsageResponse } from "./modules/usage.js";
+export { VectorStoresModule, type VectorQueryResult, type VectorStore, type VectorStoreListResponse } from "./modules/vectorStores.js";
 
 // Approvals is real (has backend implementation)
-export { ApprovalsModule, type Approval, type ApprovalStatus, type ApprovalDecision, type ApprovalListResponse, type ApprovalStatusResponse } from "./modules/approvals.js";
+export { ApprovalsModule, type Approval, type ApprovalDecision, type ApprovalListResponse, type ApprovalStatus, type ApprovalStatusResponse } from "./modules/approvals.js";
+
+export { ApiTokensModule, type ApiToken, type ApiTokenSecret, type CreateTokenRequest, type RotateTokenResponse } from "./modules/apiTokens.js";
+export { MembershipsModule, type EnsureMembershipRequest, type MembershipResponse } from "./modules/memberships.js";
 
 // ============================================================================
 // SSE Streaming
 // ============================================================================
-export { streamSSE, parseSSE, type SSEEvent, type SSEOptions, type RunStreamEvent, type RunSSEEvent, type RunEventDto as SSERunEventDto } from "./sse/client.js";
+export { parseSSE, streamSSE, type RunSSEEvent, type RunStreamEvent, type SSEEvent, type SSEOptions, type RunEventDto as SSERunEventDto } from "./sse/client.js";
 
 // ============================================================================
 // Convenience Type Re-exports
 // ============================================================================
 export type {
+    AddMessageRequest, AgentBundle,
     // Agent types
-    Agent as AgentSchema,
-    CreateAgentRequest,
-    UpdateAgentRequest,
-    AgentBundle,
-    CreateAgentVersionRequest,
-    // Run types
-    RunResponse,
-    RunDetailResponse,
-    WaitRunResponse,
-    BatchRunResponse,
+    Agent as AgentSchema, BatchRunResponse,
     CancelRunResponse,
-    ReplayRequest,
-    // Thread types
-    ThreadRequest,
-    ThreadSearchRequest,
-    AddMessageRequest,
     // Checkpoint types
     CheckpointDetail,
-    CheckpointListResponse,
+    CheckpointListResponse, CreateAgentRequest, CreateAgentVersionRequest,
     // Credential types
     CreateCredentialRequest,
-    UpdateCredentialRequest,
     // Cron types
     CreateCronJobRequest,
-    UpdateCronJobRequest,
-    // Member types
-    InviteMemberRequest,
-    UpdateMemberRequest,
-    // Prompt types
-    CreatePromptRequest,
-    CreatePromptVersionRequest,
-    // File types
-    CreatePresignedUploadRequest,
-    PresignedUploadResponse,
-    // Vector Store types
-    VectorStoreResponse,
-    VectorQueryRequest,
-    VectorQueryResponse,
     // Evaluation types
     CreateDatasetRequest,
     CreateExperimentRequest,
+    // File types
+    CreatePresignedUploadRequest,
+    // Prompt types
+    CreatePromptRequest,
+    CreatePromptVersionRequest,
+    // Member types
+    InviteMemberRequest, PresignedUploadResponse,
     // Error types
-    ProblemDetails,
+    ProblemDetails, ReplayRequest, RunDetailResponse,
+    // Run types
+    RunResponse,
+    // Thread types
+    ThreadRequest,
+    ThreadSearchRequest, UpdateAgentRequest, UpdateCredentialRequest, UpdateCronJobRequest, UpdateMemberRequest, VectorQueryRequest,
+    VectorQueryResponse,
+    // Vector Store types
+    VectorStoreResponse, WaitRunResponse
 } from "./client/raw.js";
+

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/builder.ts

@@ -36,10 +36,17 @@ export type CatalogVersions = {
     triggers: string;
 };
 
+export type ChatHistoryMessage = {
+    role: 'user' | 'assistant';
+    content: string;
+};
+
 export type BuilderChatRequest = {
     message: string;
     current_graph_spec?: Record<string, unknown>;
     thread_id?: string;
+    /** Previous conversation history for context */
+    history?: ChatHistoryMessage[];
     /** Catalog versions to use for validation */
     catalog_versions?: CatalogVersions;
     /** Combined hash of all catalogs for integrity */

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", {

package/src/modules/info.ts

@@ -10,8 +10,44 @@ export interface ServerInfo {
     environment: string;
     features?: string[];
     uptime_seconds?: number;
+    commit_hash?: string;
+    api_version?: string;
 }
 
+/** Normalized server capabilities (camelCase, with defaults) */
+export interface ServerCapabilities {
+    /** Server version */
+    version?: string;
+    /** Git commit hash */
+    commitHash?: string;
+    /** API version */
+    apiVersion?: string;
+    /** Environment (production, staging, development) */
+    environment?: string;
+    /** Feature flags - all default to false if not present */
+    features: {
+        sseResume: boolean;
+        cronTriggers: boolean;
+        batchRuns: boolean;
+        hitl: boolean;
+        traces: boolean;
+        vectorStores: boolean;
+        evaluations: boolean;
+        [key: string]: boolean;
+    };
+    /** Server limits */
+    limits?: {
+        maxBatchSize?: number;
+        maxFileSize?: number;
+        [key: string]: number | undefined;
+    };
+    /** SDK version that fetched this (useful for support) */
+    sdkVersion: string;
+}
+
+// SDK version from package (will be replaced at build time or use constant)
+const SDK_VERSION = "0.4.0";
+
 export class InfoModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
@@ -32,4 +68,76 @@ export class InfoModule {
             headers: this.headers(),
         });
     }
+
+    /**
+     * Get normalized server capabilities for feature detection.
+     * 
+     * This method never assumes feature availability - all features
+     * default to false unless explicitly enabled by the server.
+     * 
+     * @example
+     * ```ts
+     * const caps = await client.info.capabilities();
+     * if (caps.data?.features.sseResume) {
+     *     // Use follow() with resume
+     * } else {
+     *     // Fall back to polling
+     * }
+     * ```
+     */
+    async capabilities(): Promise<APIResponse<ServerCapabilities>> {
+        const response = await this.get();
+
+        if (response.error || !response.data) {
+            // Pass through error - construct proper response without data
+            return {
+                error: response.error,
+                response: response.response,
+                meta: response.meta,
+            };
+        }
+
+        const info = response.data;
+
+        // Transform snake_case features array to camelCase object
+        // CRITICAL: Never assume true - default everything to false
+        const featureArray = info.features ?? [];
+        const features: ServerCapabilities["features"] = {
+            sseResume: featureArray.includes("sse_resume"),
+            cronTriggers: featureArray.includes("cron_triggers"),
+            batchRuns: featureArray.includes("batch_runs"),
+            hitl: featureArray.includes("hitl"),
+            traces: featureArray.includes("traces"),
+            vectorStores: featureArray.includes("vector_stores"),
+            evaluations: featureArray.includes("evaluations"),
+        };
+
+        // Add any other features from array as snake_case → camelCase
+        for (const feature of featureArray) {
+            const camelCase = snakeToCamel(feature);
+            if (!(camelCase in features)) {
+                features[camelCase] = true;
+            }
+        }
+
+        const capabilities: ServerCapabilities = {
+            version: info.version,
+            commitHash: info.commit_hash,
+            apiVersion: info.api_version,
+            environment: info.environment,
+            features,
+            sdkVersion: SDK_VERSION,
+        };
+
+        return {
+            data: capabilities,
+            response: response.response,
+            meta: response.meta,
+        };
+    }
+}
+
+/** Convert snake_case to camelCase */
+function snakeToCamel(str: string): string {
+    return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
 }

package/src/modules/members.ts

@@ -7,8 +7,8 @@
  * - create*, update*, delete* for mutations (NOT remove!)
  */
 
-import type { RawClient, APIResponse } from "../client/raw.js";
-import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
+import type { PaginatedResponse, PaginationParams } from "../client/helpers.js";
+import type { APIResponse, RawClient } from "../client/raw.js";
 
 export interface Member {
     id: string;
@@ -25,6 +25,15 @@ export interface Member {
     updated_at: string;
 }
 
+export interface Role {
+    id: string;
+    name: string;
+    is_system: boolean;
+    permissions?: string[];
+    created_at?: string;
+    members_count?: number;
+}
+
 export interface MemberInviteResponse {
     member_id: string;
     invite_token?: string;
@@ -60,6 +69,66 @@ export class MembersModule {
         });
     }
 
+
+    /**
+     * List all roles in the tenant.
+     */
+    async listRoles(): Promise<APIResponse<{ items: Role[] }>> {
+        return this.client.GET<{ items: Role[] }>("/v1/api/roles", {
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a role by ID.
+     */
+    async getRole(roleId: string): Promise<APIResponse<Role>> {
+        return this.client.GET<Role>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Create a new custom role.
+     */
+    async createRole(body: { name: string; permissions?: string[] }): Promise<APIResponse<Role>> {
+        return this.client.POST<Role>("/v1/api/roles", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Update a custom role.
+     */
+    async updateRole(roleId: string, body: { name?: string; permissions?: string[] }): Promise<APIResponse<Role>> {
+        return this.client.PUT<Role>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete a custom role.
+     */
+    async deleteRole(roleId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * List all available system permissions.
+     */
+    async listPermissions(): Promise<APIResponse<{ items: string[] }>> {
+        return this.client.GET<{ items: string[] }>("/v1/api/roles/permissions", {
+            headers: this.headers(),
+        });
+    }
+
     /**
      * Invite a new member.
      */
@@ -125,4 +194,13 @@ export class MembersModule {
             headers: this.headers(),
         });
     }
+
+    /**
+     * Seed default permissions (Dev only)
+     */
+    async seedDefaults(): Promise<APIResponse<{ message: string }>> {
+        return this.client.POST<{ message: string }>("/v1/api/roles/seed-defaults", {
+            headers: this.headers(),
+        });
+    }
 }