cyberdesk 1.8.0 → 1.10.0

package/dist/index.d.ts

@@ -1,9 +1,58 @@
-import { type MachineResponse, type WorkflowResponse, type RunResponse, type ConnectionResponse, type TrajectoryResponse, type PaginatedResponseMachineResponse, type PaginatedResponseWorkflowResponse, type PaginatedResponseRunResponse, type PaginatedResponseConnectionResponse, type PaginatedResponseTrajectoryResponse, type MachineStatus, type RunStatus, type ConnectionStatus, type MachineCreate, type WorkflowCreate, type RunCreate, type ConnectionCreate, type TrajectoryCreate, type MachineUpdate, type WorkflowUpdate, type RunUpdate, type TrajectoryUpdate } from './client/types.gen';
+/**
+ * @fileoverview Cyberdesk TypeScript SDK
+ *
+ * A comprehensive SDK for interacting with the Cyberdesk Cloud API.
+ * Provides typed methods for managing machines, workflows, runs, and more.
+ *
+ * @module cyberdesk
+ * @example
+ * ```typescript
+ * import { createCyberdeskClient } from 'cyberdesk';
+ *
+ * const client = createCyberdeskClient('your-api-key');
+ *
+ * // List machines
+ * const { data: machines } = await client.machines.list();
+ *
+ * // Create and run a workflow
+ * const { data: workflow } = await client.workflows.create({
+ *   name: 'My Workflow',
+ *   main_prompt: 'Perform this task...'
+ * });
+ *
+ * const { data: run } = await client.runs.create({
+ *   workflow_id: workflow.id
+ * });
+ * ```
+ */
+import { type MachineResponse, type WorkflowResponse, type RunResponse, type ConnectionResponse, type TrajectoryResponse, type PaginatedResponseMachineResponse, type PaginatedResponseWorkflowResponse, type PaginatedResponseRunResponse, type PaginatedResponseConnectionResponse, type PaginatedResponseTrajectoryResponse, type MachineStatus, type RunStatus, type ConnectionStatus, type MachineCreate, type WorkflowCreate, type RunCreate, type FileInput, type ConnectionCreate, type TrajectoryCreate, type MachineUpdate, type WorkflowUpdate, type RunUpdate, type TrajectoryUpdate, type RunAttachmentCreate, type RunAttachmentUpdate, type RunAttachmentResponse, type RunAttachmentDownloadUrlResponse, type AttachmentType, type PaginatedResponseRunAttachmentResponse } from './client/types.gen';
 export * from './client/types.gen';
 export * from './client/sdk.gen';
 export * from './client/client.gen';
+/**
+ * Create a Cyberdesk API client
+ *
+ * @param apiKey - Your Cyberdesk API key
+ * @param baseUrl - Optional API base URL (defaults to https://api.cyberdesk.io)
+ * @returns Configured client with all API endpoints
+ *
+ * @example
+ * ```typescript
+ * const client = createCyberdeskClient('your-api-key');
+ * const machines = await client.machines.list();
+ * ```
+ */
 export declare function createCyberdeskClient(apiKey: string, baseUrl?: string): {
     machines: {
+        /**
+         * List machines with optional filtering
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @param params.status - Filter by machine status
+         * @returns Paginated list of machines
+         */
         list: (params?: {
             skip?: number;
             limit?: number;
@@ -12,18 +61,42 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             data?: PaginatedResponseMachineResponse;
             error?: any;
         }>;
+        /**
+         * Create a new machine
+         *
+         * @param data - Machine configuration
+         * @returns Created machine details
+         */
         create: (data: MachineCreate) => Promise<{
             data?: MachineResponse;
             error?: any;
         }>;
+        /**
+         * Get a specific machine by ID
+         *
+         * @param machineId - The ID of the machine
+         * @returns Machine details
+         */
         get: (machineId: string) => Promise<{
             data?: MachineResponse;
             error?: any;
         }>;
+        /**
+         * Update a machine
+         *
+         * @param machineId - The ID of the machine to update
+         * @param data - Update data (name, status, availability, etc.)
+         * @returns Updated machine details
+         */
         update: (machineId: string, data: MachineUpdate) => Promise<{
             data?: MachineResponse;
             error?: any;
         }>;
+        /**
+         * Delete a machine
+         *
+         * @param machineId - The ID of the machine to delete
+         */
         delete: (machineId: string) => Promise<({
             data: undefined;
             error: import("./client/types.gen").HttpValidationError;
@@ -36,6 +109,14 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
         }>;
     };
     workflows: {
+        /**
+         * List workflows
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @returns Paginated list of workflows
+         */
         list: (params?: {
             skip?: number;
             limit?: number;
@@ -43,18 +124,51 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             data?: PaginatedResponseWorkflowResponse;
             error?: any;
         }>;
+        /**
+         * Create a new workflow
+         *
+         * @param data - Workflow configuration including name and main prompt
+         * @returns Created workflow details
+         *
+         * @example
+         * ```typescript
+         * const workflow = await client.workflows.create({
+         *   name: 'My Workflow',
+         *   main_prompt: 'Perform this task...',
+         *   includes_file_exports: true
+         * });
+         * ```
+         */
         create: (data: WorkflowCreate) => Promise<{
             data?: WorkflowResponse;
             error?: any;
         }>;
+        /**
+         * Get a specific workflow by ID
+         *
+         * @param workflowId - The ID of the workflow
+         * @returns Workflow details
+         */
         get: (workflowId: string) => Promise<{
             data?: WorkflowResponse;
             error?: any;
         }>;
+        /**
+         * Update a workflow
+         *
+         * @param workflowId - The ID of the workflow to update
+         * @param data - Update data (name, main_prompt, output_schema, etc.)
+         * @returns Updated workflow details
+         */
         update: (workflowId: string, data: WorkflowUpdate) => Promise<{
             data?: WorkflowResponse;
             error?: any;
         }>;
+        /**
+         * Delete a workflow
+         *
+         * @param workflowId - The ID of the workflow to delete
+         */
         delete: (workflowId: string) => Promise<({
             data: undefined;
             error: import("./client/types.gen").HttpValidationError;
@@ -67,6 +181,17 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
         }>;
     };
     runs: {
+        /**
+         * List runs with optional filtering
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @param params.status - Filter by run status (scheduling, running, success, cancelled, error)
+         * @param params.workflow_id - Filter by workflow ID
+         * @param params.machine_id - Filter by machine ID
+         * @returns Paginated list of runs
+         */
         list: (params?: {
             skip?: number;
             limit?: number;
@@ -77,18 +202,60 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             data?: PaginatedResponseRunResponse;
             error?: any;
         }>;
+        /**
+         * Create a new run
+         *
+         * @param data - Run configuration
+         * @param data.workflow_id - The workflow to run
+         * @param data.machine_id - Optional machine ID (auto-selected if not provided)
+         * @param data.input_values - Optional input values for workflow variables
+         * @param data.file_inputs - Optional files to upload to the machine
+         * @returns Created run details
+         *
+         * @example
+         * ```typescript
+         * const run = await client.runs.create({
+         *   workflow_id: 'workflow-id',
+         *   input_values: { prompt: 'Hello' },
+         *   file_inputs: [{
+         *     filename: 'data.txt',
+         *     content: 'base64-encoded-content',
+         *     target_path: '~/CyberdeskTransfers/',
+         *     cleanup_imports_after_run: true
+         *   }]
+         * });
+         * ```
+         */
         create: (data: RunCreate) => Promise<{
             data?: RunResponse;
             error?: any;
         }>;
+        /**
+         * Get a specific run by ID
+         *
+         * @param runId - The ID of the run
+         * @returns Run details including status, output, and attachments
+         */
         get: (runId: string) => Promise<{
             data?: RunResponse;
             error?: any;
         }>;
+        /**
+         * Update a run
+         *
+         * @param runId - The ID of the run to update
+         * @param data - Update data (status, output_data, error messages, etc.)
+         * @returns Updated run details
+         */
         update: (runId: string, data: RunUpdate) => Promise<{
             data?: RunResponse;
             error?: any;
         }>;
+        /**
+         * Delete a run
+         *
+         * @param runId - The ID of the run to delete
+         */
         delete: (runId: string) => Promise<({
             data: undefined;
             error: import("./client/types.gen").HttpValidationError;
@@ -101,6 +268,16 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
         }>;
     };
     connections: {
+        /**
+         * List connections with optional filtering
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @param params.machine_id - Filter by machine ID
+         * @param params.status - Filter by connection status
+         * @returns Paginated list of connections
+         */
         list: (params?: {
             skip?: number;
             limit?: number;
@@ -110,12 +287,27 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             data?: PaginatedResponseConnectionResponse;
             error?: any;
         }>;
+        /**
+         * Create a new connection
+         *
+         * @param data - Connection data including machine ID and websocket info
+         * @returns Created connection details
+         */
         create: (data: ConnectionCreate) => Promise<{
             data?: ConnectionResponse;
             error?: any;
         }>;
     };
     trajectories: {
+        /**
+         * List trajectories with optional filtering
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @param params.workflow_id - Filter by workflow ID
+         * @returns Paginated list of trajectories
+         */
         list: (params?: {
             skip?: number;
             limit?: number;
@@ -124,18 +316,48 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             data?: PaginatedResponseTrajectoryResponse;
             error?: any;
         }>;
+        /**
+         * Create a new trajectory
+         *
+         * A trajectory represents a recorded sequence of actions for a workflow.
+         *
+         * @param data - Trajectory data
+         * @param data.workflow_id - The workflow this trajectory belongs to
+         * @param data.trajectory_data - Array of recorded actions
+         * @param data.dimensions - Display dimensions when trajectory was recorded
+         * @param data.original_input_values - Input values used during recording
+         * @returns Created trajectory details
+         */
         create: (data: TrajectoryCreate) => Promise<{
             data?: TrajectoryResponse;
             error?: any;
         }>;
+        /**
+         * Get a specific trajectory by ID
+         *
+         * @param trajectoryId - The ID of the trajectory
+         * @returns Trajectory details including recorded actions
+         */
         get: (trajectoryId: string) => Promise<{
             data?: TrajectoryResponse;
             error?: any;
         }>;
+        /**
+         * Update a trajectory
+         *
+         * @param trajectoryId - The ID of the trajectory to update
+         * @param data - Update data (trajectory_data)
+         * @returns Updated trajectory details
+         */
         update: (trajectoryId: string, data: TrajectoryUpdate) => Promise<{
             data?: TrajectoryResponse;
             error?: any;
         }>;
+        /**
+         * Delete a trajectory
+         *
+         * @param trajectoryId - The ID of the trajectory to delete
+         */
         delete: (trajectoryId: string) => Promise<({
             data: undefined;
             error: import("./client/types.gen").HttpValidationError;
@@ -146,10 +368,130 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
             request: Request;
             response: Response;
         }>;
+        /**
+         * Get the latest trajectory for a workflow
+         *
+         * Returns the most recently created trajectory for the specified workflow.
+         * Useful for replaying the latest recorded actions.
+         *
+         * @param workflowId - The ID of the workflow
+         * @returns Latest trajectory for the workflow, or null if none exists
+         */
         getLatestForWorkflow: (workflowId: string) => Promise<{
             data?: TrajectoryResponse;
             error?: any;
         }>;
     };
+    run_attachments: {
+        /**
+         * List run attachments with optional filtering
+         *
+         * @param params - Optional query parameters
+         * @param params.skip - Number of items to skip (for pagination)
+         * @param params.limit - Maximum number of items to return
+         * @param params.run_id - Filter by run ID
+         * @param params.attachment_type - Filter by attachment type (input/output)
+         * @returns Paginated list of run attachments
+         */
+        list: (params?: {
+            skip?: number;
+            limit?: number;
+            run_id?: string;
+            attachment_type?: AttachmentType;
+        }) => Promise<{
+            data?: PaginatedResponseRunAttachmentResponse;
+            error?: any;
+        }>;
+        /**
+         * Create a new run attachment
+         *
+         * @param data - Attachment data including file content as base64
+         * @returns Created attachment details
+         */
+        create: (data: RunAttachmentCreate) => Promise<{
+            data?: RunAttachmentResponse;
+            error?: any;
+        }>;
+        /**
+         * Get run attachment details
+         *
+         * @param attachmentId - The ID of the attachment
+         * @returns Attachment metadata
+         */
+        get: (attachmentId: string) => Promise<{
+            data?: RunAttachmentResponse;
+            error?: any;
+        }>;
+        /**
+         * Get a signed download URL for a run attachment
+         *
+         * The returned URL will trigger an automatic download when accessed in a browser.
+         *
+         * @param attachmentId - The ID of the attachment
+         * @param expiresIn - URL expiration time in seconds (10-3600). Default: 300 (5 minutes)
+         * @returns Object containing the signed URL and expiration time
+         *
+         * @example
+         * ```typescript
+         * const { data } = await client.run_attachments.getDownloadUrl('attachment-id', 600);
+         * if (data) {
+         *   console.log(`Download URL: ${data.url}`);
+         *   console.log(`Expires in: ${data.expires_in} seconds`);
+         * }
+         * ```
+         */
+        getDownloadUrl: (attachmentId: string, expiresIn?: number) => Promise<{
+            data?: RunAttachmentDownloadUrlResponse;
+            error?: any;
+        }>;
+        /**
+         * Download a run attachment file directly
+         *
+         * This method returns the raw file content. For a download URL instead,
+         * use `getDownloadUrl()`.
+         *
+         * @param attachmentId - The ID of the attachment to download
+         * @returns Raw file data
+         *
+         * @example
+         * ```typescript
+         * const { data } = await client.run_attachments.download('attachment-id');
+         * if (data) {
+         *   // Handle raw file bytes
+         *   const blob = new Blob([data]);
+         * }
+         * ```
+         */
+        download: (attachmentId: string) => Promise<{
+            data?: any;
+            error?: any;
+        }>;
+        /**
+         * Update a run attachment (e.g., set expiration)
+         *
+         * @param attachmentId - The ID of the attachment to update
+         * @param data - Update data
+         * @returns Updated attachment details
+         */
+        update: (attachmentId: string, data: RunAttachmentUpdate) => Promise<{
+            data?: RunAttachmentResponse;
+            error?: any;
+        }>;
+        /**
+         * Delete a run attachment
+         *
+         * @param attachmentId - The ID of the attachment to delete
+         */
+        delete: (attachmentId: string) => Promise<({
+            data: undefined;
+            error: import("./client/types.gen").HttpValidationError;
+        } | {
+            data: void;
+            error: undefined;
+        }) & {
+            request: Request;
+            response: Response;
+        }>;
+    };
 };
-export type { MachineResponse, WorkflowResponse, RunResponse, ConnectionResponse, TrajectoryResponse, PaginatedResponseMachineResponse, PaginatedResponseWorkflowResponse, PaginatedResponseRunResponse, PaginatedResponseConnectionResponse, PaginatedResponseTrajectoryResponse, };
+export type { MachineResponse, WorkflowResponse, RunResponse, ConnectionResponse, TrajectoryResponse, RunAttachmentResponse, RunAttachmentDownloadUrlResponse, FileInput, AttachmentType, PaginatedResponseMachineResponse, PaginatedResponseWorkflowResponse, PaginatedResponseRunResponse, PaginatedResponseConnectionResponse, PaginatedResponseTrajectoryResponse, PaginatedResponseRunAttachmentResponse, };