@agent-os-sdk/client 0.1.0

package/src/client/AgentOsClient.ts

@@ -0,0 +1,269 @@
+/**
+ * Agent OS SDK - Main Client
+ * 
+ * Fully typed API client for Agent OS platform.
+ * All HTTP calls must go through this client.
+ * 
+ * @example
+ * ```ts
+ * const api = new AgentOsClient({
+ *   baseUrl: "http://localhost:5000",
+ *   tenantId: "...",
+ *   workspaceId: "...",
+ *   token: "...",
+ * });
+ * 
+ * const run = await api.runs.create({
+ *   agent_id: "...",
+ *   input: { message: "Hello" },
+ * });
+ * ```
+ */
+
+import { createRawClient, type RawClient } from "./raw.js";
+import { AgentsModule } from "../modules/agents.js";
+import { RunsModule } from "../modules/runs.js";
+import { ThreadsModule } from "../modules/threads.js";
+import { ToolsModule } from "../modules/tools.js";
+import { KnowledgeModule } from "../modules/knowledge.js";
+import { TriggersModule } from "../modules/triggers.js";
+import { CredentialsModule } from "../modules/credentials.js";
+import { BuilderModule } from "../modules/builder.js";
+import { MembersModule } from "../modules/members.js";
+import { TenantsModule } from "../modules/tenants.js";
+import { WorkspacesModule } from "../modules/workspaces.js";
+
+// New modules
+import { PromptsModule } from "../modules/prompts.js";
+import { TracesModule } from "../modules/traces.js";
+import { FilesModule } from "../modules/files.js";
+import { VectorStoresModule } from "../modules/vectorStores.js";
+import { EvaluationModule } from "../modules/evaluation.js";
+import { CheckpointsModule } from "../modules/checkpoints.js";
+import { PlaygroundModule } from "../modules/playground.js";
+import { CronsModule } from "../modules/crons.js";
+import { DlqModule } from "../modules/dlq.js";
+import { StoreModule } from "../modules/store.js";
+import { AuditModule } from "../modules/audit.js";
+import { UsageModule } from "../modules/usage.js";
+import { McpModule } from "../modules/mcp.js";
+import { A2aModule } from "../modules/a2a.js";
+import { MeModule } from "../modules/me.js";
+import { InfoModule } from "../modules/info.js";
+import { MetricsModule } from "../modules/metrics.js";
+import { GraphsModule } from "../modules/graphs.js";
+
+export type AgentOsClientOptions = {
+    /** Base URL of the Agent OS API */
+    baseUrl: string;
+
+    /** Tenant ID (multi-tenant) */
+    tenantId: string;
+
+    /** Workspace ID */
+    workspaceId: string;
+
+    /** Optional auth token */
+    token?: string;
+
+    /** Optional member ID (for identity header) */
+    memberId?: string;
+
+    /** Custom headers */
+    headers?: Record<string, string>;
+
+    /** Kernel base URL (for meta-agent, different from control plane) */
+    kernelBaseUrl?: string;
+};
+
+export class AgentOsClient {
+    private readonly _client: RawClient;
+    private readonly _baseUrl: string;
+    private readonly _tenantId: string;
+    private readonly _workspaceId: string;
+    private readonly _token?: string;
+    private readonly _memberId?: string;
+    private readonly _customHeaders: Record<string, string>;
+    private readonly _kernelBaseUrl: string;
+
+    // Core modules
+    /** Agents API: CRUD, versions, graph */
+    readonly agents: AgentsModule;
+    /** Runs API: create, stream, cancel, resume, replay */
+    readonly runs: RunsModule;
+    /** Threads API: conversations, state, messages */
+    readonly threads: ThreadsModule;
+    /** Tools API: definitions, registry */
+    readonly tools: ToolsModule;
+    /** Knowledge API: vector stores, RAG */
+    readonly knowledge: KnowledgeModule;
+    /** Triggers API: webhooks, crons */
+    readonly triggers: TriggersModule;
+    /** Credentials API: BYOK secrets */
+    readonly credentials: CredentialsModule;
+    /** Builder API: Meta-agent for AI-assisted agent creation */
+    readonly builder: BuilderModule;
+    /** Members API: Tenant member management */
+    readonly members: MembersModule;
+    /** Tenants API: Tenant settings */
+    readonly tenants: TenantsModule;
+    /** Workspaces API: Workspace management */
+    readonly workspaces: WorkspacesModule;
+
+    // New modules
+    /** Prompts API: Prompt Hub CMS */
+    readonly prompts: PromptsModule;
+    /** Traces API: OTEL observability */
+    readonly traces: TracesModule;
+    /** Files API: S3 file storage */
+    readonly files: FilesModule;
+    /** VectorStores API: pgvector semantic search */
+    readonly vectorStores: VectorStoresModule;
+    /** Evaluation API: Datasets & experiments */
+    readonly evaluation: EvaluationModule;
+    /** Checkpoints API: Time-travel debugging */
+    readonly checkpoints: CheckpointsModule;
+    /** Playground API: Ephemeral sandbox */
+    readonly playground: PlaygroundModule;
+    /** Crons API: Cron job scheduling */
+    readonly crons: CronsModule;
+    /** DLQ API: Dead letter queue */
+    readonly dlq: DlqModule;
+    /** Store API: Key-value storage */
+    readonly store: StoreModule;
+    /** Audit API: Audit logs */
+    readonly audit: AuditModule;
+    /** Usage API: Quotas and usage */
+    readonly usage: UsageModule;
+    /** MCP API: Model Context Protocol */
+    readonly mcp: McpModule;
+    /** A2A API: Agent-to-Agent protocol */
+    readonly a2a: A2aModule;
+    /** Me API: Current user identity */
+    readonly me: MeModule;
+    /** Info API: Server information */
+    readonly info: InfoModule;
+    /** Metrics API: Prometheus metrics */
+    readonly metrics: MetricsModule;
+    /** Graphs API: Validation and introspection */
+    readonly graphs: GraphsModule;
+
+    // ======================== Convenience Aliases ========================
+    /**
+     * Alias for evaluation.listExperiments() - provides first-level access to experiments
+     * @example client.experiments.list() // same as client.evaluation.listExperiments()
+     */
+    readonly experiments: {
+        list: EvaluationModule["listExperiments"];
+        get: EvaluationModule["getExperiment"];
+        create: EvaluationModule["createExperiment"];
+    };
+
+    /**
+     * Alias for agents.listVersions() - provides first-level access to agent versions
+     */
+    readonly agentVersions: {
+        list: (agentId: string) => ReturnType<AgentsModule["listVersions"]>;
+        get: (agentId: string, versionId: string) => ReturnType<AgentsModule["getVersion"]>;
+        create: (agentId: string, body: Parameters<AgentsModule["createVersion"]>[1]) => ReturnType<AgentsModule["createVersion"]>;
+    };
+
+    constructor(options: AgentOsClientOptions) {
+        this._baseUrl = options.baseUrl;
+        this._kernelBaseUrl = options.kernelBaseUrl ?? options.baseUrl.replace(':5000', ':8001');
+        this._tenantId = options.tenantId;
+        this._workspaceId = options.workspaceId;
+        this._token = options.token;
+        this._memberId = options.memberId;
+        this._customHeaders = options.headers ?? {};
+
+        this._client = createRawClient({
+            baseUrl: options.baseUrl,
+            headers: this._getHeaders(),
+        });
+
+        const getHeaders = () => this._getHeaders();
+        const getWorkspaceId = () => this._workspaceId;
+        const getTenantId = () => this._tenantId;
+
+        // Initialize core modules
+        this.agents = new AgentsModule(this._client, getHeaders);
+        this.runs = new RunsModule(this._client, this._baseUrl, getHeaders);
+        this.threads = new ThreadsModule(this._client, getHeaders);
+        this.tools = new ToolsModule(this._client, getHeaders);
+        this.knowledge = new KnowledgeModule(this._client, getWorkspaceId, getHeaders);
+        this.triggers = new TriggersModule(this._client, getHeaders);
+        this.credentials = new CredentialsModule(this._client, getWorkspaceId, getHeaders);
+        this.builder = new BuilderModule(this._kernelBaseUrl, getHeaders);
+        this.members = new MembersModule(this._client, getHeaders);
+        this.tenants = new TenantsModule(this._client, getHeaders);
+        this.workspaces = new WorkspacesModule(this._client, getTenantId, getHeaders);
+
+        // Initialize new modules
+        this.prompts = new PromptsModule(this._client, getHeaders);
+        this.traces = new TracesModule(this._client, getHeaders);
+        this.files = new FilesModule(this._client, getHeaders);
+        this.vectorStores = new VectorStoresModule(this._client, getHeaders);
+        this.evaluation = new EvaluationModule(this._client, getHeaders);
+        this.checkpoints = new CheckpointsModule(this._client, getHeaders);
+        this.playground = new PlaygroundModule(this._client, getHeaders);
+        this.crons = new CronsModule(this._client, getHeaders);
+        this.dlq = new DlqModule(this._client, getHeaders);
+        this.store = new StoreModule(this._client, getHeaders);
+        this.audit = new AuditModule(this._client, getHeaders);
+        this.usage = new UsageModule(this._client, getHeaders);
+        this.mcp = new McpModule(this._client, getHeaders);
+        this.a2a = new A2aModule(this._client, getHeaders);
+        this.me = new MeModule(this._client, getHeaders);
+        this.info = new InfoModule(this._client, getHeaders);
+        this.metrics = new MetricsModule(this._baseUrl, getHeaders);
+        this.graphs = new GraphsModule(this._client, getHeaders);
+
+        // Initialize convenience aliases
+        this.experiments = {
+            list: this.evaluation.listExperiments.bind(this.evaluation),
+            get: this.evaluation.getExperiment.bind(this.evaluation),
+            create: this.evaluation.createExperiment.bind(this.evaluation),
+        };
+
+        this.agentVersions = {
+            list: (agentId: string) => this.agents.listVersions(agentId),
+            get: (agentId: string, versionId: string) => this.agents.getVersion(agentId, versionId),
+            create: (agentId: string, body: any) => this.agents.createVersion(agentId, body),
+        };
+    }
+
+    private _getHeaders(): Record<string, string> {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            "X-Tenant-Id": this._tenantId,
+            "X-Workspace-Id": this._workspaceId,
+            ...this._customHeaders,
+        };
+
+        if (this._token) {
+            headers["Authorization"] = `Bearer ${this._token}`;
+        }
+
+        if (this._memberId) {
+            headers["X-Member-Id"] = this._memberId;
+        }
+
+        return headers;
+    }
+
+    /** Current tenant ID */
+    get tenantId(): string {
+        return this._tenantId;
+    }
+
+    /** Current workspace ID */
+    get workspaceId(): string {
+        return this._workspaceId;
+    }
+
+    /** Raw HTTP client (use modules instead) */
+    get raw(): RawClient {
+        return this._client;
+    }
+}

package/src/client/helpers.ts

@@ -0,0 +1,98 @@
+/**
+ * SDK Helper Types and Functions
+ * 
+ * Provides utilities for working with API responses.
+ */
+
+import type { APIResponse } from "./raw.js";
+
+// ============================================================================
+// Pagination
+// ============================================================================
+
+/**
+ * Standard pagination parameters used across all list endpoints.
+ * Extends Record to be compatible with query parameter types.
+ */
+export interface PaginationParams extends Record<string, unknown> {
+    /** Maximum number of items to return (default: 20) */
+    limit?: number;
+    /** Number of items to skip (default: 0) */
+    offset?: number;
+}
+
+/**
+ * Paginated list response wrapper.
+ */
+export interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+}
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+/**
+ * SDK-specific error class with structured error data.
+ */
+export class SDKError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown;
+
+    constructor(response: APIResponse<unknown>) {
+        const message = response.error?.message || `HTTP ${response.response.status}`;
+        super(message);
+        this.name = "SDKError";
+        this.code = response.error?.code || `HTTP_${response.response.status}`;
+        this.status = response.response.status;
+        this.details = response.error?.details;
+    }
+}
+
+/**
+ * Unwraps an APIResponse, returning the data directly or throwing on error.
+ * Use this when you want the cleaner "throws on error" pattern.
+ * 
+ * @example
+ * ```ts
+ * // Instead of:
+ * const { data, error } = await client.agents.list();
+ * if (error) throw new Error(error.message);
+ * 
+ * // Use:
+ * const agents = await unwrap(client.agents.list());
+ * ```
+ */
+export async function unwrap<T>(promise: Promise<APIResponse<T>>): Promise<T> {
+    const result = await promise;
+    if (result.error || !result.data) {
+        throw new SDKError(result);
+    }
+    return result.data;
+}
+
+/**
+ * Type helper for unwrapped responses.
+ */
+export type Unwrapped<T> = T extends APIResponse<infer U> ? U : never;
+
+// ============================================================================
+// Result Pattern (Alternative to exceptions)
+// ============================================================================
+
+export type Result<T, E = SDKError> =
+    | { success: true; data: T }
+    | { success: false; error: E };
+
+/**
+ * Converts an APIResponse to a Result type for pattern matching.
+ */
+export async function toResult<T>(promise: Promise<APIResponse<T>>): Promise<Result<T>> {
+    const result = await promise;
+    if (result.error || !result.data) {
+        return { success: false, error: new SDKError(result) };
+    }
+    return { success: true, data: result.data };
+}

package/src/client/raw.ts

@@ -0,0 +1,241 @@
+/**
+ * Agent OS SDK - Raw HTTP Client
+ * 
+ * Fully typed HTTP client using openapi-fetch with generated OpenAPI types.
+ * All types are automatically inferred from the backend Swagger specification.
+ */
+
+import createClient, { type Client, type FetchOptions } from "openapi-fetch";
+import type { paths, components } from "../generated/openapi.js";
+
+// Re-export types for external use
+export type { paths, components };
+
+export type ClientOptions = {
+    baseUrl: string;
+    headers?: Record<string, string>;
+};
+
+/**
+ * Standard API response wrapper.
+ * This matches the pattern used by openapi-fetch.
+ */
+export interface APIResponse<T> {
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    response: Response;
+}
+
+/**
+ * Typed API client using openapi-fetch.
+ * All paths and responses are fully typed from OpenAPI spec.
+ */
+export type TypedClient = Client<paths>;
+
+/**
+ * Creates a typed HTTP client with openapi-fetch.
+ * This provides full type inference for all API endpoints.
+ */
+export function createTypedClient(options: ClientOptions): TypedClient {
+    return createClient<paths>({
+        baseUrl: options.baseUrl,
+        headers: options.headers,
+    });
+}
+
+/**
+ * Legacy raw client interface (for backward compatibility).
+ * Wraps openapi-fetch to provide the old interface while maintaining types.
+ */
+export function createRawClient(options: ClientOptions) {
+    const { baseUrl, headers: defaultHeaders = {} } = options;
+
+    async function request<T>(
+        method: string,
+        path: string,
+        opts?: {
+            params?: { path?: Record<string, string>; query?: Record<string, unknown> };
+            body?: unknown;
+            headers?: Record<string, string>;
+        }
+    ): Promise<APIResponse<T>> {
+        // Replace path params
+        let url = path;
+        if (opts?.params?.path) {
+            for (const [key, value] of Object.entries(opts.params.path)) {
+                url = url.replace(`{${key}}`, encodeURIComponent(value));
+                // Also handle {id} pattern common in our API
+                url = url.replace(`{id}`, encodeURIComponent(value));
+            }
+        }
+
+        // Build query string
+        if (opts?.params?.query) {
+            const query = new URLSearchParams();
+            for (const [key, value] of Object.entries(opts.params.query)) {
+                if (value !== undefined && value !== null) {
+                    query.append(key, String(value));
+                }
+            }
+            const queryStr = query.toString();
+            if (queryStr) {
+                url += `?${queryStr}`;
+            }
+        }
+
+        const fullUrl = `${baseUrl}${url}`;
+        const headers: Record<string, string> = {
+            ...defaultHeaders,
+            ...opts?.headers,
+        };
+
+        if (opts?.body) {
+            headers["Content-Type"] = "application/json";
+        }
+
+        const response = await fetch(fullUrl, {
+            method,
+            headers,
+            body: opts?.body ? JSON.stringify(opts.body) : undefined,
+        });
+
+        if (!response.ok) {
+            let error: APIResponse<T>["error"];
+            try {
+                const json = await response.json();
+                error = {
+                    code: json.code || `HTTP_${response.status}`,
+                    message: json.message || response.statusText,
+                    details: json.details,
+                };
+            } catch {
+                error = {
+                    code: `HTTP_${response.status}`,
+                    message: response.statusText,
+                };
+            }
+            return { error, response };
+        }
+
+        // Handle no-content responses
+        if (response.status === 204) {
+            return { data: undefined as T, response };
+        }
+
+        try {
+            const data = await response.json();
+            return { data: data as T, response };
+        } catch {
+            return { data: undefined as T, response };
+        }
+    }
+
+    return {
+        GET: <T>(path: string, opts?: Parameters<typeof request>[2]) =>
+            request<T>("GET", path, opts),
+        POST: <T>(path: string, opts?: Parameters<typeof request>[2]) =>
+            request<T>("POST", path, opts),
+        PUT: <T>(path: string, opts?: Parameters<typeof request>[2]) =>
+            request<T>("PUT", path, opts),
+        PATCH: <T>(path: string, opts?: Parameters<typeof request>[2]) =>
+            request<T>("PATCH", path, opts),
+        DELETE: <T>(path: string, opts?: Parameters<typeof request>[2]) =>
+            request<T>("DELETE", path, opts),
+    };
+}
+
+export type RawClient = ReturnType<typeof createRawClient>;
+
+// ============================================================================
+// Convenience type exports from OpenAPI schemas
+// ============================================================================
+
+// Agent types
+export type Agent = components["schemas"]["AgentBundleAgent"];
+export type CreateAgentRequest = components["schemas"]["CreateAgentRequest"];
+export type UpdateAgentRequest = components["schemas"]["UpdateAgentRequest"];
+export type AgentBundle = components["schemas"]["AgentBundle"];
+export type AgentVersion = components["schemas"]["AgentBundleVersion"];
+export type CreateAgentVersionRequest = components["schemas"]["CreateAgentVersionRequest"];
+
+// Run types
+export type RunResponse = components["schemas"]["RunResponse"];
+export type RunDetailResponse = components["schemas"]["RunDetailResponse"];
+export type CreateRunRequest = components["schemas"]["CreateRunRequest"];
+export type WaitRunRequest = components["schemas"]["WaitRunRequest"];
+export type WaitRunResponse = components["schemas"]["WaitRunResponse"];
+export type BatchRunRequest = components["schemas"]["BatchRunRequest"];
+export type BatchRunResponse = components["schemas"]["BatchRunResponse"];
+export type ReplayRequest = components["schemas"]["ReplayRequest"];
+export type CancelRequest = components["schemas"]["CancelRequest"];
+export type CancelRunResponse = components["schemas"]["CancelRunResponse"];
+
+// Thread types
+export type ThreadRequest = components["schemas"]["ThreadRequest"];
+export type ThreadSearchRequest = components["schemas"]["ThreadSearchRequest"];
+export type ThreadCopyRequest = components["schemas"]["ThreadCopyRequest"];
+export type ThreadPruneRequest = components["schemas"]["ThreadPruneRequest"];
+export type AddMessageRequest = components["schemas"]["AddMessageRequest"];
+
+// Checkpoint types
+export type CheckpointDetail = components["schemas"]["CheckpointDetail"];
+export type CheckpointNode = components["schemas"]["CheckpointNode"];
+export type CheckpointListResponse = components["schemas"]["CheckpointListResponse"];
+export type CheckpointIndexResponse = components["schemas"]["CheckpointIndexResponse"];
+export type CreateCheckpointRequest = components["schemas"]["CreateCheckpointRequest"];
+
+// Credential types
+export type CreateCredentialRequest = components["schemas"]["CreateCredentialRequest"];
+export type UpdateCredentialRequest = components["schemas"]["UpdateCredentialRequest"];
+
+// Evaluation types
+export type CreateDatasetRequest = components["schemas"]["CreateDatasetRequest"];
+export type CreateExperimentRequest = components["schemas"]["CreateExperimentRequest"];
+export type ExampleData = components["schemas"]["ExampleData"];
+export type AddExamplesRequest = components["schemas"]["AddExamplesRequest"];
+
+// Vector Store types
+export type VectorStoreResponse = components["schemas"]["VectorStoreResponse"];
+export type VectorQueryRequest = components["schemas"]["VectorQueryRequest"];
+export type VectorQueryResponse = components["schemas"]["VectorQueryResponse"];
+export type VectorSearchResult = components["schemas"]["VectorSearchResult"];
+export type VectorStoreFileResponse = components["schemas"]["VectorStoreFileResponse"];
+
+// Cron types
+export type CreateCronJobRequest = components["schemas"]["CreateCronJobRequest"];
+export type UpdateCronJobRequest = components["schemas"]["UpdateCronJobRequest"];
+
+// Member types
+export type InviteMemberRequest = components["schemas"]["InviteMemberRequest"];
+export type UpdateMemberRequest = components["schemas"]["UpdateMemberRequest"];
+
+// Tenant/Workspace types
+export type UpdateTenantRequest = components["schemas"]["UpdateTenantRequest"];
+export type UpdateWorkspaceRequest = components["schemas"]["UpdateWorkspaceRequest"];
+
+// Prompt types
+export type CreatePromptRequest = components["schemas"]["CreatePromptRequest"];
+export type CreatePromptVersionRequest = components["schemas"]["CreatePromptVersionRequest"];
+
+// File types
+export type CreatePresignedUploadRequest = components["schemas"]["CreatePresignedUploadRequest"];
+export type PresignedUploadResponse = components["schemas"]["PresignedUploadResponse"];
+export type ConfirmUploadRequest = components["schemas"]["ConfirmUploadRequest"];
+
+// Trace types
+export type SpanData = components["schemas"]["SpanData"];
+export type BatchIngestRequest = components["schemas"]["BatchIngestRequest"];
+export type AddFeedbackRequest = components["schemas"]["AddFeedbackRequest"];
+
+// Trigger types
+export type UpdateTriggerRequest = components["schemas"]["UpdateTriggerRequest"];
+
+// Store types
+export type StoreValueRequest = components["schemas"]["StoreValueRequest"];
+
+// Problem details (errors)
+export type ProblemDetails = components["schemas"]["ProblemDetails"];

package/src/generated/index.ts

@@ -0,0 +1,2 @@
+// Auto-generated - do not edit
+export type * from "./openapi.js";