@agent-os-sdk/client 0.9.8 → 0.9.10

package/src/modules/datasets.ts

@@ -0,0 +1,142 @@
+/**
+ * Datasets Module — Evaluation datasets and examples.
+ * 
+ * Endpoints: /v1/api/datasets
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface Dataset {
+    id: string;
+    name: string;
+    description?: string;
+    agent_id?: string;
+    example_count: number;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface DatasetExample {
+    id: string;
+    dataset_id: string;
+    input: unknown;
+    expected_output?: unknown;
+    metadata?: unknown;
+    created_at: string;
+}
+
+export interface ExampleInput {
+    input: unknown;
+    expected_output?: unknown;
+    metadata?: unknown;
+}
+
+// =============================================================================
+// Module
+// =============================================================================
+
+export class DatasetsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List datasets in the workspace.
+     */
+    async list(params?: {
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<Dataset[]>> {
+        return this.client.GET<Dataset[]>("/v1/api/datasets", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a specific dataset by ID.
+     */
+    async get(datasetId: string): Promise<APIResponse<Dataset>> {
+        return this.client.GET<Dataset>("/v1/api/datasets/{id}", {
+            params: { path: { id: datasetId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Create a new evaluation dataset.
+     */
+    async create(body: {
+        name: string;
+        description?: string;
+        agent_id?: string;
+    }): Promise<APIResponse<Dataset>> {
+        return this.client.POST<Dataset>("/v1/api/datasets", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Update a dataset (partial update).
+     */
+    async update(datasetId: string, body: {
+        name?: string;
+        description?: string;
+        agent_id?: string;
+    }): Promise<APIResponse<Dataset>> {
+        return this.client.PATCH<Dataset>("/v1/api/datasets/{id}", {
+            params: { path: { id: datasetId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Soft delete a dataset.
+     */
+    async delete(datasetId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/datasets/{id}", {
+            params: { path: { id: datasetId } },
+            headers: this.headers(),
+        });
+    }
+
+    // ======================== Examples ========================
+
+    /**
+     * List examples for a dataset.
+     */
+    async listExamples(datasetId: string, params?: {
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<DatasetExample[]>> {
+        return this.client.GET<DatasetExample[]>("/v1/api/datasets/{id}/examples", {
+            params: { path: { id: datasetId }, query: params },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Add examples to a dataset (batch).
+     */
+    async addExamples(datasetId: string, examples: ExampleInput[]): Promise<APIResponse<DatasetExample[]>> {
+        return this.client.POST<DatasetExample[]>("/v1/api/datasets/{id}/examples", {
+            params: { path: { id: datasetId } },
+            body: { examples },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete a specific example.
+     */
+    async deleteExample(datasetId: string, exampleId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/datasets/{id}/examples/{exampleId}", {
+            params: { path: { id: datasetId, exampleId } },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/files.ts

@@ -4,21 +4,23 @@
 
 import type { RawClient, APIResponse, components } from "../client/raw.js";
 
+type FileListItem = components["schemas"]["FileListItem"];
+type FileDetail = components["schemas"]["FileDetail"];
 type CreatePresignedUploadRequest = components["schemas"]["CreatePresignedUploadRequest"];
 type PresignedUploadResponse = components["schemas"]["PresignedUploadResponse"];
 type ConfirmUploadRequest = components["schemas"]["ConfirmUploadRequest"];
+type FileConfirmResponse = components["schemas"]["FileConfirmResponse"];
+type PresignedDownloadResponse = components["schemas"]["PresignedDownloadResponse"];
 
 export interface StoredFile {
     id: string;
     filename: string;
     content_type: string;
     size_bytes: number;
-    sha256: string;
-    storage_uri: string;
-    workspace_id: string;
-    uploaded_by?: string;
+    sha256?: string;
     status: "pending" | "confirmed" | "deleted";
     created_at: string;
+    updated_at?: string;
 }
 
 export interface FileListResponse {
@@ -29,39 +31,109 @@ export interface FileListResponse {
 export interface PresignedUpload {
     file_id: string;
     upload_url: string;
-    expires_at: string;
+    expires_in: number;
+    object_key: string;
+}
+
+export interface ConfirmedUpload {
+    file_id: string;
+    status: string;
+    size_bytes: number;
+    sha256?: string;
 }
 
 export interface PresignedDownload {
+    file_id: string;
     download_url: string;
-    expires_at: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    expires_in: number;
 }
 
 export class FilesModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
+    private resolveWorkspaceId(workspaceId?: string): string {
+        if (workspaceId && workspaceId.trim().length > 0) {
+            return workspaceId.trim();
+        }
+
+        const headers = this.headers();
+        const fromHeader = headers["X-Workspace-Id"] ?? headers["x-workspace-id"];
+        if (fromHeader && fromHeader.trim().length > 0) {
+            return fromHeader.trim();
+        }
+
+        throw new Error("workspace_id is required (pass workspaceId or set X-Workspace-Id in client headers)");
+    }
+
+    private static toStoredFile(item: FileListItem | FileDetail): StoredFile {
+        return {
+            id: item.id ?? "",
+            filename: item.filename ?? "",
+            content_type: item.content_type ?? "application/octet-stream",
+            size_bytes: item.size_bytes ?? 0,
+            sha256: "sha256" in item ? item.sha256 ?? undefined : undefined,
+            status: (item.status ?? "pending") as StoredFile["status"],
+            created_at: item.created_at ?? "",
+            updated_at: "updated_at" in item ? item.updated_at ?? undefined : undefined,
+        };
+    }
+
     /**
-     * List all files.
+     * List files in a workspace.
      */
     async list(params?: {
         workspace_id?: string;
+        status?: string;
         limit?: number;
         offset?: number;
     }): Promise<APIResponse<FileListResponse>> {
-        return this.client.GET<FileListResponse>("/v1/api/files", {
-            params: { query: params },
+        const workspaceId = this.resolveWorkspaceId(params?.workspace_id);
+        const response = await this.client.GET<FileListItem[]>("/v1/api/workspaces/{workspaceId}/files", {
+            params: {
+                path: { workspaceId },
+                query: {
+                    status: params?.status,
+                    limit: params?.limit,
+                    offset: params?.offset,
+                },
+            },
             headers: this.headers(),
         });
+
+        const items = Array.isArray(response.data)
+            ? response.data.map((item) => FilesModule.toStoredFile(item))
+            : [];
+
+        return {
+            ...response,
+            data: {
+                items,
+                total: items.length,
+            },
+        };
     }
 
     /**
      * Get a file by ID.
      */
-    async get(fileId: string): Promise<APIResponse<StoredFile>> {
-        return this.client.GET<StoredFile>("/v1/api/files/{id}", {
-            params: { path: { id: fileId } },
+    async get(fileId: string, workspaceId?: string): Promise<APIResponse<StoredFile>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const response = await this.client.GET<FileDetail>("/v1/api/workspaces/{workspaceId}/files/{fileId}", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
         });
+
+        if (!response.data) {
+            return response as APIResponse<StoredFile>;
+        }
+
+        return {
+            ...response,
+            data: FilesModule.toStoredFile(response.data),
+        };
     }
 
     /**
@@ -69,44 +141,68 @@ export class FilesModule {
      */
     async createUpload(body: {
         filename: string;
-        content_type: string;
+        content_type?: string;
         size_bytes?: number;
         expected_sha256?: string;
-    }): Promise<APIResponse<PresignedUpload>> {
-        return this.client.POST<PresignedUpload>("/v1/api/files/upload", {
-            body,
+    }, workspaceId?: string): Promise<APIResponse<PresignedUpload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const requestBody: CreatePresignedUploadRequest = {
+            filename: body.filename,
+            content_type: body.content_type,
+            size_bytes: body.size_bytes,
+            expected_sha256: body.expected_sha256,
+        };
+        return this.client.POST<PresignedUploadResponse>("/v1/api/workspaces/{workspaceId}/files/presign", {
+            params: { path: { workspaceId: resolvedWorkspaceId } },
+            body: requestBody,
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<PresignedUpload>>;
     }
 
     /**
      * Confirm an upload.
      */
-    async confirmUpload(fileId: string, sha256: string): Promise<APIResponse<StoredFile>> {
-        return this.client.POST<StoredFile>("/v1/api/files/{id}/confirm", {
-            params: { path: { id: fileId } },
-            body: { sha256 },
+    async confirmUpload(fileId: string, sha256?: string, workspaceId?: string): Promise<APIResponse<ConfirmedUpload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        const requestBody: ConfirmUploadRequest = { sha256 };
+        return this.client.POST<FileConfirmResponse>("/v1/api/workspaces/{workspaceId}/files/{fileId}/confirm", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
+            body: requestBody,
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<ConfirmedUpload>>;
     }
 
     /**
      * Get a presigned download URL.
      */
-    async getDownloadUrl(fileId: string): Promise<APIResponse<PresignedDownload>> {
-        return this.client.GET<PresignedDownload>("/v1/api/files/{id}/download", {
-            params: { path: { id: fileId } },
+    async getDownloadUrl(fileId: string, workspaceId?: string): Promise<APIResponse<PresignedDownload>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        return this.client.GET<PresignedDownloadResponse>("/v1/api/workspaces/{workspaceId}/files/{fileId}/download", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
-        });
+        }) as Promise<APIResponse<PresignedDownload>>;
     }
 
     /**
      * Delete a file.
      */
-    async delete(fileId: string): Promise<APIResponse<void>> {
-        return this.client.DELETE<void>("/v1/api/files/{id}", {
-            params: { path: { id: fileId } },
+    async delete(fileId: string, workspaceId?: string): Promise<APIResponse<void>> {
+        const resolvedWorkspaceId = this.resolveWorkspaceId(workspaceId);
+        return this.client.DELETE<void>("/v1/api/workspaces/{workspaceId}/files/{fileId}", {
+            params: { path: { workspaceId: resolvedWorkspaceId, fileId } },
             headers: this.headers(),
         });
     }
+
+    /**
+     * Alias for createUpload with explicit semantic name.
+     */
+    async createPresignedUpload(body: {
+        filename: string;
+        content_type?: string;
+        size_bytes?: number;
+        expected_sha256?: string;
+    }, workspaceId?: string): Promise<APIResponse<PresignedUpload>> {
+        return this.createUpload(body, workspaceId);
+    }
 }

package/src/modules/graphs.ts

@@ -115,7 +115,7 @@ export interface GraphsIntrospectResponse {
     mermaid: string;
     nodes: string[];
     edges: [string, string][];
-    graph_type?: string;
+    type?: string;
 }
 
 // ============ Module ============

package/src/modules/members.ts

@@ -159,7 +159,6 @@ export class MembersModule {
 
     /**
      * Remove a member from the tenant.
-     * Note: Use delete() - remove() is provided as alias for backwards compatibility.
      */
     async delete(memberId: string): Promise<APIResponse<void>> {
         return this.client.DELETE<void>("/v1/api/members/{id}", {
@@ -168,12 +167,6 @@ export class MembersModule {
         });
     }
 
-    /** 
-     * Alias for delete() (backwards compatibility)
-     * @deprecated Use delete() instead
-     */
-    remove = (memberId: string) => this.delete(memberId);
-
     /**
      * Resend invitation email.
      */

package/src/modules/observability.ts

@@ -0,0 +1,28 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export type FrontendLogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+
+export interface FrontendLogPayload {
+    level: FrontendLogLevel;
+    message: string;
+    stack?: string;
+    route?: string;
+    url?: string;
+    user_agent?: string;
+    session_id?: string;
+    context?: Record<string, unknown>;
+}
+
+export class ObservabilityModule {
+    constructor(
+        private client: RawClient,
+        private headers: () => Record<string, string>
+    ) { }
+
+    async logFrontend(payload: FrontendLogPayload): Promise<APIResponse<Record<string, unknown>>> {
+        return this.client.POST<Record<string, unknown>>("/v1/api/observability/frontend-log", {
+            body: payload,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/roles.ts

@@ -0,0 +1,112 @@
+/**
+ * Roles Module — Tenant role and permission management.
+ * 
+ * Endpoints: /v1/api/roles
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TenantRole {
+    id: string;
+    name: string;
+    is_system: boolean;
+    permissions: string[];
+    created_at: string;
+    members_count: number;
+}
+
+export interface RoleListResponse {
+    items: TenantRole[];
+}
+
+export interface PermissionsListResponse {
+    items: string[];
+}
+
+// =============================================================================
+// Module
+// =============================================================================
+
+export class RolesModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
+
+    /**
+     * List all roles available in the tenant.
+     */
+    async list(): Promise<APIResponse<RoleListResponse>> {
+        return this.client.GET<RoleListResponse>("/v1/api/roles", {
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Get a specific role by ID.
+     */
+    async get(roleId: string): Promise<APIResponse<TenantRole>> {
+        return this.client.GET<TenantRole>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * List all available system permissions.
+     */
+    async getPermissions(): Promise<APIResponse<PermissionsListResponse>> {
+        return this.client.GET<PermissionsListResponse>("/v1/api/roles/permissions", {
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Create a new custom role.
+     */
+    async create(body: {
+        name: string;
+        permissions?: string[];
+    }): Promise<APIResponse<TenantRole>> {
+        return this.client.POST<TenantRole>("/v1/api/roles", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Update an existing custom role.
+     * System roles cannot be updated.
+     */
+    async update(roleId: string, body: {
+        name?: string;
+        permissions?: string[];
+    }): Promise<APIResponse<TenantRole>> {
+        return this.client.PUT<TenantRole>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Delete a custom role.
+     * System roles and roles assigned to members cannot be deleted.
+     */
+    async delete(roleId: string): Promise<APIResponse<void>> {
+        return this.client.DELETE<void>("/v1/api/roles/{id}", {
+            params: { path: { id: roleId } },
+            headers: this.headers(),
+        });
+    }
+
+    /**
+     * Seed default permissions for all roles in the tenant.
+     */
+    async seedDefaults(): Promise<APIResponse<{ message: string }>> {
+        return this.client.POST<{ message: string }>("/v1/api/roles/seed-defaults", {
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/runs.ts

@@ -110,13 +110,15 @@ export class RunsModule {
         agent_id: string;
         thread?: { thread_id?: string } | { new_thread: true };
         input?: unknown;
+        /** Optional bundle pinning (draft/published). When omitted, backend resolves live bundle. */
+        bundle_id?: string;
         /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
         idempotency_key?: string;
     }): Promise<APIResponse<CreateRunResponse>> {
-        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        // Send canonical X-Idempotency-Key header + body idempotency_key for backend contract parity.
         const headers: Record<string, string> = {};
         if (body.idempotency_key) {
-            headers["Idempotency-Key"] = body.idempotency_key;
+            headers["X-Idempotency-Key"] = body.idempotency_key;
         }
 
         return this.client.POST<CreateRunResponse>("/v1/api/runs", {

package/src/modules/threads.ts

@@ -93,10 +93,10 @@ export class ThreadsModule {
         /** Idempotency key for safe retries. When set, duplicate requests with the same key return the original response. */
         idempotency_key?: string;
     }): Promise<APIResponse<Thread>> {
-        // Send Idempotency-Key in HEADER (enterprise standard) + body (backend compat)
+        // Send canonical X-Idempotency-Key header + body idempotency_key for backend contract parity.
         const headers: Record<string, string> = { ...this.headers() };
         if (body?.idempotency_key) {
-            headers["Idempotency-Key"] = body.idempotency_key;
+            headers["X-Idempotency-Key"] = body.idempotency_key;
         }
 
         return this.client.POST<Thread>("/v1/api/threads", {