cyberdesk 1.8.0 → 1.10.0

package/dist/index.js

@@ -1,4 +1,31 @@
 "use strict";
+/**
+ * @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
+ * });
+ * ```
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -32,8 +59,16 @@ __exportStar(require("./client/types.gen"), exports);
 __exportStar(require("./client/sdk.gen"), exports);
 __exportStar(require("./client/client.gen"), exports);
 // Configuration
+/** Default API base URL for Cyberdesk Cloud API */
 const DEFAULT_API_BASE_URL = "https://api.cyberdesk.io";
-// Create configured client with API key and connection reuse
+/**
+ * Create a configured HTTP client with authentication
+ *
+ * @internal
+ * @param apiKey - Your Cyberdesk API key
+ * @param baseUrl - API base URL
+ * @returns Configured HTTP client
+ */
 function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL) {
     return (0, client_fetch_1.createClient)({
         baseUrl,
@@ -44,30 +79,70 @@ function createApiClient(apiKey, baseUrl = DEFAULT_API_BASE_URL) {
         },
     });
 }
-// Create API client with your API key
+/**
+ * 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();
+ * ```
+ */
 function createCyberdeskClient(apiKey, baseUrl) {
     const client = createApiClient(apiKey, baseUrl);
     return {
         // Machine endpoints
         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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.listMachinesV1MachinesGet)({
                     client,
                     query: params,
                 });
             }),
+            /**
+             * Create a new machine
+             *
+             * @param data - Machine configuration
+             * @returns Created machine details
+             */
             create: (data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.createMachineV1MachinesPost)({
                     client,
                     body: data,
                 });
             }),
+            /**
+             * Get a specific machine by ID
+             *
+             * @param machineId - The ID of the machine
+             * @returns Machine details
+             */
             get: (machineId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getMachineV1MachinesMachineIdGet)({
                     client,
                     path: { machine_id: machineId },
                 });
             }),
+            /**
+             * 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, data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.updateMachineV1MachinesMachineIdPatch)({
                     client,
@@ -75,6 +150,11 @@ function createCyberdeskClient(apiKey, baseUrl) {
                     body: data,
                 });
             }),
+            /**
+             * Delete a machine
+             *
+             * @param machineId - The ID of the machine to delete
+             */
             delete: (machineId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.deleteMachineV1MachinesMachineIdDelete)({
                     client,
@@ -84,24 +164,60 @@ function createCyberdeskClient(apiKey, baseUrl) {
         },
         // Workflow endpoints
         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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.listWorkflowsV1WorkflowsGet)({
                     client,
                     query: params,
                 });
             }),
+            /**
+             * 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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.createWorkflowV1WorkflowsPost)({
                     client,
                     body: data,
                 });
             }),
+            /**
+             * Get a specific workflow by ID
+             *
+             * @param workflowId - The ID of the workflow
+             * @returns Workflow details
+             */
             get: (workflowId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getWorkflowV1WorkflowsWorkflowIdGet)({
                     client,
                     path: { workflow_id: workflowId },
                 });
             }),
+            /**
+             * 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, data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.updateWorkflowV1WorkflowsWorkflowIdPatch)({
                     client,
@@ -109,6 +225,11 @@ function createCyberdeskClient(apiKey, baseUrl) {
                     body: data,
                 });
             }),
+            /**
+             * Delete a workflow
+             *
+             * @param workflowId - The ID of the workflow to delete
+             */
             delete: (workflowId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.deleteWorkflowV1WorkflowsWorkflowIdDelete)({
                     client,
@@ -118,24 +239,72 @@ function createCyberdeskClient(apiKey, baseUrl) {
         },
         // Run endpoints
         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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.listRunsV1RunsGet)({
                     client,
                     query: params,
                 });
             }),
+            /**
+             * 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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.createRunV1RunsPost)({
                     client,
                     body: data,
                 });
             }),
+            /**
+             * Get a specific run by ID
+             *
+             * @param runId - The ID of the run
+             * @returns Run details including status, output, and attachments
+             */
             get: (runId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getRunV1RunsRunIdGet)({
                     client,
                     path: { run_id: runId },
                 });
             }),
+            /**
+             * 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, data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.updateRunV1RunsRunIdPatch)({
                     client,
@@ -143,6 +312,11 @@ function createCyberdeskClient(apiKey, baseUrl) {
                     body: data,
                 });
             }),
+            /**
+             * Delete a run
+             *
+             * @param runId - The ID of the run to delete
+             */
             delete: (runId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.deleteRunV1RunsRunIdDelete)({
                     client,
@@ -152,12 +326,28 @@ function createCyberdeskClient(apiKey, baseUrl) {
         },
         // Connection endpoints
         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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.listConnectionsV1ConnectionsGet)({
                     client,
                     query: params,
                 });
             }),
+            /**
+             * Create a new connection
+             *
+             * @param data - Connection data including machine ID and websocket info
+             * @returns Created connection details
+             */
             create: (data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.createConnectionV1ConnectionsPost)({
                     client,
@@ -167,24 +357,58 @@ function createCyberdeskClient(apiKey, baseUrl) {
         },
         // Trajectory endpoints
         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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.listTrajectoriesV1TrajectoriesGet)({
                     client,
                     query: params,
                 });
             }),
+            /**
+             * 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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.createTrajectoryV1TrajectoriesPost)({
                     client,
                     body: data,
                 });
             }),
+            /**
+             * Get a specific trajectory by ID
+             *
+             * @param trajectoryId - The ID of the trajectory
+             * @returns Trajectory details including recorded actions
+             */
             get: (trajectoryId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getTrajectoryV1TrajectoriesTrajectoryIdGet)({
                     client,
                     path: { trajectory_id: trajectoryId },
                 });
             }),
+            /**
+             * Update a trajectory
+             *
+             * @param trajectoryId - The ID of the trajectory to update
+             * @param data - Update data (trajectory_data)
+             * @returns Updated trajectory details
+             */
             update: (trajectoryId, data) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.updateTrajectoryV1TrajectoriesTrajectoryIdPatch)({
                     client,
@@ -192,12 +416,26 @@ function createCyberdeskClient(apiKey, baseUrl) {
                     body: data,
                 });
             }),
+            /**
+             * Delete a trajectory
+             *
+             * @param trajectoryId - The ID of the trajectory to delete
+             */
             delete: (trajectoryId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.deleteTrajectoryV1TrajectoriesTrajectoryIdDelete)({
                     client,
                     path: { trajectory_id: trajectoryId },
                 });
             }),
+            /**
+             * 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) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getLatestTrajectoryForWorkflowV1WorkflowsWorkflowIdLatestTrajectoryGet)({
                     client,
@@ -205,5 +443,122 @@ function createCyberdeskClient(apiKey, baseUrl) {
                 });
             }),
         },
+        // Run Attachment endpoints
+        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) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.listRunAttachmentsV1RunAttachmentsGet)({
+                    client,
+                    query: params,
+                });
+            }),
+            /**
+             * Create a new run attachment
+             *
+             * @param data - Attachment data including file content as base64
+             * @returns Created attachment details
+             */
+            create: (data) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.createRunAttachmentV1RunAttachmentsPost)({
+                    client,
+                    body: data,
+                });
+            }),
+            /**
+             * Get run attachment details
+             *
+             * @param attachmentId - The ID of the attachment
+             * @returns Attachment metadata
+             */
+            get: (attachmentId) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.getRunAttachmentV1RunAttachmentsAttachmentIdGet)({
+                    client,
+                    path: { attachment_id: attachmentId },
+                });
+            }),
+            /**
+             * 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, expiresIn) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.getRunAttachmentDownloadUrlV1RunAttachmentsAttachmentIdDownloadUrlGet)({
+                    client,
+                    path: { attachment_id: attachmentId },
+                    query: expiresIn ? { expires_in: expiresIn } : undefined,
+                });
+            }),
+            /**
+             * 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) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.downloadRunAttachmentV1RunAttachmentsAttachmentIdDownloadGet)({
+                    client,
+                    path: { attachment_id: attachmentId },
+                });
+            }),
+            /**
+             * 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, data) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.updateRunAttachmentV1RunAttachmentsAttachmentIdPut)({
+                    client,
+                    path: { attachment_id: attachmentId },
+                    body: data,
+                });
+            }),
+            /**
+             * Delete a run attachment
+             *
+             * @param attachmentId - The ID of the attachment to delete
+             */
+            delete: (attachmentId) => __awaiter(this, void 0, void 0, function* () {
+                return (0, sdk_gen_1.deleteRunAttachmentV1RunAttachmentsAttachmentIdDelete)({
+                    client,
+                    path: { attachment_id: attachmentId },
+                });
+            }),
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberdesk",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "The official TypeScript SDK for Cyberdesk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",