@agent-os-sdk/client 0.1.0

package/src/modules/threads.ts

@@ -0,0 +1,287 @@
+/**
+ * Threads Module - Fully Typed
+ * 
+ * Naming conventions:
+ * - get* for singular items
+ * - list* for collections
+ * - create*, update*, delete* for mutations
+ * 
+ * Convenience aliases are provided for common access patterns.
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
+
+// Response types
+export interface Thread {
+    id: string;
+    workspace_id: string;
+    tenant_id: string;
+    channel?: string;
+    external_conversation_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface ThreadState {
+    thread_id: string;
+    values: Record<string, unknown>;
+    next?: string[];
+    tasks?: unknown[];
+    metadata?: Record<string, unknown>;
+}
+
+export interface ThreadHistory {
+    thread_id: string;
+    checkpoints: unknown[];
+}
+
+export interface ThreadMessage {
+    id: string;
+    thread_id: string;
+    role: "human" | "assistant" | "system" | "developer";
+    content: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+}
+
+export interface ThreadRun {
+    run_id: string;
+    thread_id: string;
+    agent_id: string;
+    status: string;
+    created_at: string;
+    completed_at?: string;
+}
+
+export type ThreadListResponse = PaginatedResponse<Thread>;
+export type ThreadMessagesResponse = PaginatedResponse<ThreadMessage>;
+export type ThreadRunsResponse = PaginatedResponse<ThreadRun>;
+
+export interface ThreadSearchResponse {
+    items: Thread[];
+    total: number;
+}
+
+export interface ThreadPruneResponse {
+    deleted_count: number;
+    thread_ids: string[];
+}
+
+export class ThreadsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    // ======================== CRUD ========================
+
+    /**
+     * Create a new thread.
+     * @example
+     * ```ts
+     * const { data: thread } = await client.threads.create();
+     * ```
+     */
+    async create(body?: {
+        channel?: string;
+        external_conversation_id?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<APIResponse<Thread>> {
+        return this.client.POST<Thread>("/v1/api/threads", {
+            body: body ?? {},
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a thread by ID.
+     * @example
+     * ```ts
+     * const { data: thread } = await client.threads.get("thread-uuid");
+     * ```
+     */
+    async get(threadId: string): Promise<APIResponse<Thread>> {
+        return this.client.GET<Thread>("/v1/api/threads/{id}", {
+            params: { path: { id: threadId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * List all threads.
+     * @example
+     * ```ts
+     * const { data } = await client.threads.list({ limit: 20 });
+     * ```
+     */
+    async list(params?: PaginationParams & {
+        workspace_id?: string;
+    }): Promise<APIResponse<ThreadListResponse>> {
+        return this.client.GET<ThreadListResponse>("/v1/api/threads", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete a thread.
+     */
+    async delete(threadId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/threads/{id}", {
+            params: { path: { id: threadId } },
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== State ========================
+
+    /**
+     * Get the current state of a thread.
+     * @example
+     * ```ts
+     * const { data: state } = await client.threads.getState("thread-uuid");
+     * ```
+     */
+    async getState(threadId: string): Promise<APIResponse<ThreadState>> {
+        return this.client.GET<ThreadState>("/v1/api/threads/{id}/state", {
+            params: { path: { id: threadId } },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias: threads.state() -> threads.getState() */
+    state = (threadId: string) => this.getState(threadId);
+
+    // ======================== History ========================
+
+    /**
+     * Get the history of a thread.
+     */
+    async getHistory(threadId: string): Promise<APIResponse<ThreadHistory>> {
+        return this.client.GET<ThreadHistory>("/v1/api/threads/{id}/history", {
+            params: { path: { id: threadId } },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias: threads.history() -> threads.getHistory() */
+    history = (threadId: string) => this.getHistory(threadId);
+
+    // ======================== Runs ========================
+
+    /**
+     * Get runs for a thread.
+     * @example
+     * ```ts
+     * const { data } = await client.threads.getRuns("thread-uuid");
+     * ```
+     */
+    async getRuns(threadId: string, params?: PaginationParams & {
+        status?: string
+    }): Promise<APIResponse<ThreadRunsResponse>> {
+        return this.client.GET<ThreadRunsResponse>("/v1/api/threads/{id}/runs", {
+            params: { path: { id: threadId }, query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias: threads.runs() -> threads.getRuns() */
+    runs = (threadId: string, params?: PaginationParams & { status?: string }) =>
+        this.getRuns(threadId, params);
+
+    /**
+     * Create a run within a thread.
+     */
+    async createRun(threadId: string, body: {
+        agent_id: string;
+        input?: unknown;
+        idempotency_key?: string;
+    }): Promise<APIResponse<ThreadRun>> {
+        return this.client.POST<ThreadRun>("/v1/api/threads/{id}/runs", {
+            params: { path: { id: threadId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Messages ========================
+
+    /**
+     * Get messages in a thread.
+     * @example
+     * ```ts
+     * const { data } = await client.threads.getMessages("thread-uuid");
+     * ```
+     */
+    async getMessages(threadId: string, params?: PaginationParams): Promise<APIResponse<ThreadMessagesResponse>> {
+        return this.client.GET<ThreadMessagesResponse>("/v1/api/threads/{id}/messages", {
+            params: { path: { id: threadId }, query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /** Alias: threads.messages() -> threads.getMessages() */
+    messages = (threadId: string, params?: PaginationParams) => this.getMessages(threadId, params);
+
+    /**
+     * Add a message to a thread.
+     */
+    async addMessage(threadId: string, body: {
+        role?: "human" | "system" | "developer";
+        content: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<APIResponse<ThreadMessage>> {
+        return this.client.POST<ThreadMessage>("/v1/api/threads/{id}/messages", {
+            params: { path: { id: threadId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Search ========================
+
+    /**
+     * Search threads.
+     */
+    async search(body: {
+        workspace_id?: string;
+        agent_id?: string;
+        created_after?: string;
+        created_before?: string;
+        sort_by?: string;
+        sort_desc?: boolean;
+    } & PaginationParams): Promise<APIResponse<ThreadSearchResponse>> {
+        return this.client.POST<ThreadSearchResponse>("/v1/api/threads/search", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Copy/Fork ========================
+
+    /**
+     * Copy/fork a thread.
+     */
+    async copy(threadId: string, options?: { copy_history?: boolean }): Promise<APIResponse<Thread>> {
+        return this.client.POST<Thread>("/v1/api/threads/{id}/copy", {
+            params: { path: { id: threadId } },
+            body: options ?? {},
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Prune ========================
+
+    /**
+     * Prune old threads.
+     */
+    async prune(body: {
+        workspace_id?: string;
+        older_than_days?: number;
+        dry_run?: boolean;
+    } & PaginationParams): Promise<APIResponse<ThreadPruneResponse>> {
+        return this.client.POST<ThreadPruneResponse>("/v1/api/threads/prune", {
+            body,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/tools.ts

@@ -0,0 +1,65 @@
+/**
+ * Tools Module - Fully Typed
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+export interface Tool {
+    name: string;
+    description?: string;
+    category?: string;
+    parameters?: Record<string, unknown>;
+    required_credentials?: string[];
+    is_builtin: boolean;
+    created_at?: string;
+}
+
+export interface ToolListResponse {
+    items: Tool[];
+    total: number;
+}
+
+export interface ToolCallResult {
+    success: boolean;
+    output?: unknown;
+    error?: string;
+}
+
+export class ToolsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List all available tools.
+     */
+    async list(params?: {
+        category?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<ToolListResponse>> {
+        return this.client.GET<ToolListResponse>("/v1/api/tools", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a tool by name.
+     */
+    async get(toolName: string): Promise<APIResponse<Tool>> {
+        return this.client.GET<Tool>("/v1/api/tools/{name}", {
+            params: { path: { name: toolName } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Call a tool directly (testing).
+     */
+    async call(toolName: string, args: unknown): Promise<APIResponse<ToolCallResult>> {
+        return this.client.POST<ToolCallResult>("/v1/api/tools/{name}/call", {
+            params: { path: { name: toolName } },
+            body: { arguments: args },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/traces.ts

@@ -0,0 +1,117 @@
+/**
+ * Traces Module - Fully Typed
+ */
+
+import type { RawClient, APIResponse, components } from "../client/raw.js";
+
+export type SpanData = components["schemas"]["SpanData"];
+type BatchIngestRequest = components["schemas"]["BatchIngestRequest"];
+type AddFeedbackRequest = components["schemas"]["AddFeedbackRequest"];
+
+export interface FeedbackRequest {
+    span_id: string;
+    score?: string;
+    comment?: string;
+    corrections?: Record<string, unknown>;
+}
+
+export interface Trace {
+    trace_id: string;
+    run_id?: string;
+    root_span_id: string;
+    name: string;
+    status: "ok" | "error" | "pending";
+    start_time: string;
+    end_time?: string;
+    duration_ms?: number;
+    span_count: number;
+}
+
+export interface Span {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    kind: string;
+    status: string;
+    status_message?: string;
+    start_time_unix_nano: number;
+    end_time_unix_nano?: number;
+    run_id?: string;
+    attributes?: Record<string, unknown>;
+    events?: unknown[];
+}
+
+export interface TraceListResponse {
+    items: Trace[];
+    total: number;
+}
+
+export interface SpanListResponse {
+    items: Span[];
+    total: number;
+}
+
+export interface TraceDetail extends Trace {
+    spans: Span[];
+}
+
+export class TracesModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List traces.
+     */
+    async list(params?: {
+        run_id?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<TraceListResponse>> {
+        return this.client.GET<TraceListResponse>("/v1/api/traces", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a trace by ID.
+     */
+    async get(traceId: string): Promise<APIResponse<TraceDetail>> {
+        return this.client.GET<TraceDetail>("/v1/api/traces/{id}", {
+            params: { path: { id: traceId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get spans for a trace.
+     */
+    async getSpans(traceId: string): Promise<APIResponse<SpanListResponse>> {
+        return this.client.GET<SpanListResponse>("/v1/api/traces/{id}/spans", {
+            params: { path: { id: traceId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Ingest spans (batch).
+     */
+    async ingest(spans: SpanData[]): Promise<APIResponse<void>> {
+        return this.client.POST<void>("/v1/api/traces/ingest", {
+            body: { spans },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Add feedback to a span.
+     */
+    async addFeedback(feedback: FeedbackRequest): Promise<APIResponse<void>> {
+        return this.client.POST<void>("/v1/api/traces/feedback", {
+            body: feedback,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/triggers.ts

@@ -0,0 +1,113 @@
+/**
+ * Triggers Module - Fully Typed
+ */
+
+import type { RawClient, APIResponse, components } from "../client/raw.js";
+
+type UpdateTriggerRequest = components["schemas"]["UpdateTriggerRequest"];
+
+export interface Trigger {
+    id: string;
+    name: string;
+    workspace_id: string;
+    agent_id: string;
+    agent_version_id?: string;
+    trigger_type: "webhook" | "schedule" | "event";
+    config?: Record<string, unknown>;
+    webhook_url?: string;
+    webhook_secret?: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface TriggerListResponse {
+    items: Trigger[];
+    total: number;
+}
+
+export interface TriggerInvokeResponse {
+    run_id: string;
+    triggered_at: string;
+}
+
+export class TriggersModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List all triggers.
+     */
+    async list(params?: {
+        workspace_id?: string;
+        agent_id?: string;
+        trigger_type?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<APIResponse<TriggerListResponse>> {
+        return this.client.GET<TriggerListResponse>("/v1/api/triggers", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a trigger by ID.
+     */
+    async get(triggerId: string): Promise<APIResponse<Trigger>> {
+        return this.client.GET<Trigger>("/v1/api/triggers/{id}", {
+            params: { path: { id: triggerId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Create a new trigger.
+     */
+    async create(body: {
+        name: string;
+        agent_id: string;
+        agent_version_id?: string;
+        trigger_type: "webhook" | "schedule" | "event";
+        config?: Record<string, unknown>;
+    }): Promise<APIResponse<Trigger>> {
+        return this.client.POST<Trigger>("/v1/api/triggers", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Update a trigger.
+     */
+    async update(triggerId: string, body: {
+        name?: string;
+        is_active?: boolean;
+    }): Promise<APIResponse<Trigger>> {
+        return this.client.PUT<Trigger>("/v1/api/triggers/{id}", {
+            params: { path: { id: triggerId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete a trigger.
+     */
+    async delete(triggerId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/triggers/{id}", {
+            params: { path: { id: triggerId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Invoke a trigger manually.
+     */
+    async invoke(triggerId: string, payload?: unknown): Promise<APIResponse<TriggerInvokeResponse>> {
+        return this.client.POST<TriggerInvokeResponse>("/v1/api/triggers/{id}/invoke", {
+            params: { path: { id: triggerId } },
+            body: { payload },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/usage.ts

@@ -0,0 +1,32 @@
+/**
+ * Usage Module - Fully Typed
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+export interface UsageQuota {
+    resource: string;
+    limit: number;
+    used: number;
+    remaining: number;
+}
+
+export interface UsageResponse {
+    workspace_id: string;
+    period_start: string;
+    period_end: string;
+    quotas: UsageQuota[];
+}
+
+export class UsageModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * Get current usage and quotas.
+     */
+    async get(): Promise<APIResponse<UsageResponse>> {
+        return this.client.GET<UsageResponse>("/v1/api/usage", {
+            headers: this.headers(),
+        });
+    }
+}