cyberdesk

Cyberdesk TypeScript SDK

The official TypeScript SDK for Cyberdesk, providing type-safe access to all Cyberdesk APIs.

Installation

npm install cyberdesk

Quick Start

The most common use case is to execute workflows that you've created in the Cyberdesk Dashboard.

import { createCyberdeskClient } from 'cyberdesk';

// Initialize client with your API key
const client = createCyberdeskClient('your-api-key');

// Create a run for your workflow
const { data: run } = await client.runs.create({
  workflow_id: 'your-workflow-id',
  machine_id: 'your-machine-id',
  input_values: {
    // Your workflow-specific input data
    patient_id: '12345',
    patient_first_name: 'John',
    patient_last_name: 'Doe'
  }
});

// Wait for the run to complete
let status = run.status;
while (status === 'scheduling' || status === 'running') {
  await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  const { data: updatedRun } = await client.runs.get(run.id);
  status = updatedRun.status;
}

// Get the output data
if (status === 'success') {
  console.log('Result:', updatedRun.output_data);
} else {
  console.error('Run failed:', updatedRun.error?.join(', '));
}

Desktop Parameters

Configure machine-specific values that automatically populate workflows running on specific desktops:

import { createCyberdeskClient } from 'cyberdesk';

const client = createCyberdeskClient('your-api-key');

// Set desktop parameters for a machine
await client.machines.update('machine-id', {
  machine_parameters: {
    username: 'machine_specific_user',
    api_url: 'https://api-region-east.example.com',
    config_path: 'C:\\MachineA\\config.json'
  },
  machine_sensitive_parameters: {
    password: 'actual_secret_value',  // Stored securely in Basis Theory
    api_key: 'actual_api_key_123'
  }
});

Use in workflows with standard syntax:

Log in to {api_url} using {username} and password {$password}.
Then open the config at {config_path}.

Desktop parameters automatically override run-level inputs and persist across runs. See the Desktop Parameters docs for more details.

Full Documentation

For complete documentation including advanced usage, error handling, and all available methods, visit:

https://docs.cyberdesk.io/sdk-guides/typescript

Custom Base URL

const client = createCyberdeskClient('your-api-key', 'https://your-api.example.com');

Available Methods

Machines

• client.machines.list(params?) - List machines
• client.machines.create(data) - Create machine
• client.machines.get(machineId) - Get machine
• client.machines.update(machineId, data) - Update machine
• client.machines.delete(machineId) - Delete machine

Workflows

• client.workflows.list(params?) - List workflows
• client.workflows.create(data) - Create workflow
• client.workflows.get(workflowId) - Get workflow
• client.workflows.update(workflowId, data) - Update workflow
• client.workflows.delete(workflowId) - Delete workflow

Runs

• client.runs.list(params?) - List runs
• client.runs.create(data) - Create run
• client.runs.get(runId) - Get run
• client.runs.update(runId, data) - Update run
• client.runs.delete(runId) - Delete run

Trajectories

• client.trajectories.list(params?) - List trajectories
• client.trajectories.create(data) - Create trajectory
• client.trajectories.get(trajectoryId) - Get trajectory
• client.trajectories.update(trajectoryId, data) - Update trajectory
• client.trajectories.delete(trajectoryId) - Delete trajectory
• client.trajectories.getLatestForWorkflow(workflowId) - Get latest trajectory for workflow

Connections

• client.connections.list(params?) - List connections
• client.connections.create(data) - Create connection

TypeScript Support

This SDK is built with TypeScript and provides full type safety:

import { 
  createCyberdeskClient, 
  type MachineResponse, 
  type WorkflowResponse 
} from 'cyberdesk';

const client = createCyberdeskClient('your-api-key');

// All parameters and responses are fully typed
const machines: { data?: PaginatedResponseMachineResponse } = 
  await client.machines.list();

Testing

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit with your credentials

# Run all tests
npm test

# Run only webhook tests
npm run test:webhooks

# Run only integration tests (real API calls)
npm run test:integration

See tests/README.md for details.

License

MIT