plato-sandbox-sdk 1.1.1

package/README.md

@@ -0,0 +1,339 @@
+# Plato TypeScript SDK
+
+TypeScript/JavaScript client library for the Plato platform - manage sandbox VMs, simulators, and environments programmatically.
+
+## Installation
+
+```bash
+npm install plato-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ApiClient } from 'plato-sdk';
+
+// Initialize the client
+const client = new ApiClient({
+  baseUrl: 'https://api.plato.so',
+  // Or use environment for predefined endpoints
+  // environment: 'production'
+});
+
+// Create an environment
+const response = await client.makeEnvironment({
+  interface_type: 'desktop',
+  env_id: 'my-env-001'
+});
+
+console.log('Environment created:', response);
+```
+
+## Features
+
+- Full TypeScript support with generated types
+- Promise-based API with async/await
+- Built-in error handling and retries
+- Request/response interceptors
+- Timeout configuration
+- Comprehensive API coverage for:
+  - Environment management
+  - Sandbox operations
+  - Simulator control
+  - Worker management
+  - Snapshot creation
+  - SSH and proxy access
+
+## Usage
+
+### Client Configuration
+
+```typescript
+import { ApiClient } from 'plato-sdk';
+
+const client = new ApiClient({
+  baseUrl: 'https://api.plato.so',
+  headers: {
+    'Authorization': 'Bearer your-api-token'
+  },
+  timeoutInSeconds: 60,
+  maxRetries: 3
+});
+```
+
+### Environment Operations
+
+```typescript
+// Create an environment
+const env = await client.makeEnvironment({
+  interface_type: 'desktop',
+  env_id: 'my-environment',
+  variables: [
+    { key: 'DATABASE_URL', value: 'postgresql://...' }
+  ]
+});
+
+// Check job status
+const status = await client.getJobStatus('job-123');
+
+// Get environment state
+const state = await client.getEnvironmentState({
+  env_id: 'my-environment'
+});
+
+// Close environment
+await client.closeEnvironment('my-environment');
+```
+
+### Sandbox Management
+
+```typescript
+// Create a sandbox
+const sandbox = await client.createSandbox({
+  simulator_name: 'ubuntu-22.04',
+  env_vars: {
+    NODE_ENV: 'production'
+  }
+});
+
+// Setup sandbox
+await client.setupSandbox({
+  sandbox_id: sandbox.sandbox_id,
+  commands: ['npm install', 'npm run build']
+});
+
+// Delete sandbox
+await client.deleteSandbox(sandbox.sandbox_id);
+```
+
+### Helper Functions
+
+The SDK includes high-level helper functions that combine API calls with operation monitoring:
+
+```typescript
+import { ApiClient } from 'plato-sdk';
+import { SandboxHelpers } from 'plato-sdk/helpers';
+
+const client = new ApiClient({ baseUrl: 'https://api.plato.so' });
+const helpers = new SandboxHelpers(client);
+
+// Create and wait for sandbox to be ready
+const sandbox = await helpers.createSandbox(
+  {
+    simulator_name: 'ubuntu-22.04',
+    env_vars: { NODE_ENV: 'production' }
+  },
+  {
+    wait: true,  // Wait for operation to complete
+    pollInterval: 2000,  // Check every 2 seconds
+    maxWaitTime: 300000  // Max 5 minutes
+  }
+);
+
+// Setup sandbox with automatic monitoring
+await helpers.setupSandbox(
+  sandbox.sandbox_id,
+  {
+    commands: ['npm install'],
+    files: { '/app/config.json': '{"env":"prod"}' }
+  },
+  { wait: true }
+);
+```
+
+### Working with Simulators
+
+```typescript
+// List available simulators
+const simulators = await client.listSimulators();
+
+// Get simulator details
+const simulator = await client.getSimulator('ubuntu-22.04');
+
+// Start a worker
+const worker = await client.startWorker({
+  simulator_name: 'ubuntu-22.04',
+  worker_id: 'worker-001'
+});
+```
+
+### Snapshot Management
+
+```typescript
+// Create a snapshot
+const snapshot = await client.createSnapshot({
+  sandbox_id: 'sandbox-123',
+  snapshot_name: 'backup-v1'
+});
+
+// Backup environment
+await client.backupEnvironment('env-123');
+
+// Reset environment
+await client.resetEnvironment({
+  env_id: 'env-123',
+  snapshot_id: 'snapshot-456'
+});
+```
+
+### Error Handling
+
+```typescript
+import { ApiError, ApiTimeoutError, BadRequestError } from 'plato-sdk';
+
+try {
+  await client.makeEnvironment({
+    interface_type: 'desktop',
+    env_id: 'my-env'
+  });
+} catch (error) {
+  if (error instanceof BadRequestError) {
+    console.error('Invalid request:', error.body);
+  } else if (error instanceof ApiTimeoutError) {
+    console.error('Request timed out');
+  } else if (error instanceof ApiError) {
+    console.error('API error:', error.statusCode, error.body);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Request Options
+
+Per-request configuration options:
+
+```typescript
+await client.makeEnvironment(
+  { interface_type: 'desktop', env_id: 'my-env' },
+  {
+    timeoutInSeconds: 120,
+    maxRetries: 5,
+    headers: {
+      'X-Custom-Header': 'value'
+    },
+    abortSignal: abortController.signal
+  }
+);
+```
+
+## API Reference
+
+### Core Types
+
+All API types are exported from `plato-sdk/api`:
+
+```typescript
+import type * as Api from 'plato-sdk/api';
+
+const request: Api.MakeEnvironmentRequest = {
+  interface_type: 'desktop',
+  env_id: 'my-env'
+};
+```
+
+### Main Classes
+
+- `ApiClient` - Main API client
+- `SandboxHelpers` - High-level sandbox operations
+- `SandboxMonitor` - Operation monitoring utilities
+
+### Error Types
+
+- `ApiError` - Generic API error
+- `ApiTimeoutError` - Request timeout
+- `BadRequestError` - 400 Bad Request
+
+## Advanced Usage
+
+### Custom Base URL
+
+```typescript
+const client = new ApiClient({
+  baseUrl: process.env.PLATO_API_URL || 'https://api.plato.so'
+});
+```
+
+### Request Interceptors
+
+```typescript
+const client = new ApiClient({
+  baseUrl: 'https://api.plato.so',
+  headers: {
+    'Authorization': `Bearer ${getToken()}`
+  }
+});
+```
+
+### Monitoring Operations
+
+```typescript
+import { SandboxMonitor } from 'plato-sdk/helpers';
+
+const monitor = new SandboxMonitor(client);
+
+const result = await monitor.waitForOperation(
+  'operation-123',
+  {
+    pollInterval: 1000,
+    maxWaitTime: 60000,
+    onProgress: (event) => {
+      console.log('Operation progress:', event.status);
+    }
+  }
+);
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import { ApiClient, type BaseClientOptions } from 'plato-sdk';
+import type * as Api from 'plato-sdk/api';
+
+const options: BaseClientOptions = {
+  baseUrl: 'https://api.plato.so'
+};
+
+const client = new ApiClient(options);
+
+// Full type inference
+const response: Api.MakeEnvironmentResponse =
+  await client.makeEnvironment({
+    interface_type: 'desktop',
+    env_id: 'my-env'
+  });
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- TypeScript 5.0+ (for TypeScript projects)
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# The compiled output will be in the current directory
+```
+
+## License
+
+MIT
+
+## Support
+
+- GitHub Issues: https://github.com/plato-ai/plato-client/issues
+- Documentation: https://github.com/plato-ai/plato-client#readme
+
+## Related Projects
+
+- [Plato Python SDK](../../python/) - Python client library
+- [Plato CLI](../../cli/) - Command-line interface
+- [Plato Go SDK](../../sdk/) - Core Go implementation

package/api/client/index.ts

@@ -0,0 +1 @@
+export * from "./requests/index.js";

package/api/client/requests/CreateSandboxRequest.ts

@@ -0,0 +1,37 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as Api from "../../index.js";
+
+/**
+ * @example
+ *     {
+ *         dataset: "dataset",
+ *         plato_dataset_config: {
+ *             compute: {
+ *                 cpus: 1,
+ *                 memory: 1,
+ *                 disk: 1,
+ *                 app_port: 1,
+ *                 plato_messaging_port: 1
+ *             },
+ *             metadata: {
+ *                 name: "name"
+ *             }
+ *         }
+ *     }
+ */
+export interface CreateSandboxRequest {
+    /** Dataset name (e.g., "base") */
+    dataset: string;
+    plato_dataset_config: Api.SimConfigDataset;
+    /** Timeout in seconds for sandbox creation */
+    timeout?: number;
+    /** Wait time in seconds */
+    wait_time?: number;
+    /** Human-readable alias for the sandbox */
+    alias?: string;
+    /** Optional artifact ID to create sandbox from snapshot */
+    artifact_id?: string;
+    /** Service name */
+    service?: string;
+}

package/api/client/requests/CreateSnapshotRequest.ts

@@ -0,0 +1,11 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {}
+ */
+export interface CreateSnapshotRequest {
+    service?: string;
+    git_hash?: string;
+    dataset?: string;
+}

package/api/client/requests/EvaluateRequest.ts

@@ -0,0 +1,9 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {}
+ */
+export interface EvaluateRequest {
+    value?: Record<string, unknown>;
+}

package/api/client/requests/GetEnvironmentStateRequest.ts

@@ -0,0 +1,11 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         merge_mutations: true
+ *     }
+ */
+export interface GetEnvironmentStateRequest {
+    merge_mutations?: boolean;
+}

package/api/client/requests/GetTestCasesRequest.ts

@@ -0,0 +1,15 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         simulator_name: "simulator_name",
+ *         simulator_id: "simulator_id",
+ *         page_size: 1
+ *     }
+ */
+export interface GetTestCasesRequest {
+    simulator_name?: string;
+    simulator_id?: string;
+    page_size?: number;
+}

package/api/client/requests/LogRequest.ts

@@ -0,0 +1,19 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         source: "source",
+ *         type: "type",
+ *         message: {
+ *             "key": "value"
+ *         },
+ *         timestamp: "timestamp"
+ *     }
+ */
+export interface LogRequest {
+    source: string;
+    type: string;
+    message: Record<string, unknown>;
+    timestamp: string;
+}

package/api/client/requests/MakeEnvironmentRequest.ts

@@ -0,0 +1,27 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         interface_type: "interface_type",
+ *         env_id: "env_id"
+ *     }
+ */
+export interface MakeEnvironmentRequest {
+    interface_type: string;
+    interface_width?: number;
+    interface_height?: number;
+    source?: string;
+    open_page_on_start?: boolean;
+    env_id: string;
+    tag?: string;
+    dataset?: string;
+    artifact_id?: string;
+    env_config?: Record<string, unknown>;
+    record_network_requests?: boolean;
+    record_actions?: boolean;
+    keepalive?: boolean;
+    alias?: string;
+    fast?: boolean;
+    version?: string;
+}

package/api/client/requests/PostEvaluationResultRequest.ts

@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         success: true
+ *     }
+ */
+export interface PostEvaluationResultRequest {
+    success: boolean;
+    reason?: string;
+    agent_version?: string;
+    mutations?: Record<string, unknown>[];
+}

package/api/client/requests/ResetEnvironmentRequest.ts

@@ -0,0 +1,11 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {}
+ */
+export interface ResetEnvironmentRequest {
+    test_case_public_id?: string;
+    agent_version?: string;
+    load_browser_state?: boolean;
+}

package/api/client/requests/SetupRootAccessRequest.ts

@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * @example
+ *     {
+ *         ssh_public_key: "ssh_public_key"
+ *     }
+ */
+export interface SetupRootAccessRequest {
+    /** SSH public key to install for root user */
+    ssh_public_key: string;
+    /** Timeout in seconds */
+    timeout?: number;
+}

package/api/client/requests/SetupSandboxRequest.ts

@@ -0,0 +1,29 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as Api from "../../index.js";
+
+/**
+ * @example
+ *     {
+ *         dataset: "dataset",
+ *         plato_dataset_config: {
+ *             compute: {
+ *                 cpus: 1,
+ *                 memory: 1,
+ *                 disk: 1,
+ *                 app_port: 1,
+ *                 plato_messaging_port: 1
+ *             },
+ *             metadata: {
+ *                 name: "name"
+ *             }
+ *         }
+ *     }
+ */
+export interface SetupSandboxRequest {
+    /** Dataset name */
+    dataset: string;
+    plato_dataset_config: Api.SimConfigDataset;
+    /** SSH public key to install for plato user */
+    ssh_public_key?: string;
+}

package/api/client/requests/StartWorkerRequest.ts

@@ -0,0 +1,28 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as Api from "../../index.js";
+
+/**
+ * @example
+ *     {
+ *         dataset: "dataset",
+ *         plato_dataset_config: {
+ *             compute: {
+ *                 cpus: 1,
+ *                 memory: 1,
+ *                 disk: 1,
+ *                 app_port: 1,
+ *                 plato_messaging_port: 1
+ *             },
+ *             metadata: {
+ *                 name: "name"
+ *             }
+ *         }
+ *     }
+ */
+export interface StartWorkerRequest {
+    service?: string;
+    dataset: string;
+    plato_dataset_config: Api.SimConfigDataset;
+    timeout?: number;
+}

package/api/client/requests/index.ts

@@ -0,0 +1,12 @@
+export type { CreateSandboxRequest } from "./CreateSandboxRequest.js";
+export type { CreateSnapshotRequest } from "./CreateSnapshotRequest.js";
+export type { EvaluateRequest } from "./EvaluateRequest.js";
+export type { GetEnvironmentStateRequest } from "./GetEnvironmentStateRequest.js";
+export type { GetTestCasesRequest } from "./GetTestCasesRequest.js";
+export type { LogRequest } from "./LogRequest.js";
+export type { MakeEnvironmentRequest } from "./MakeEnvironmentRequest.js";
+export type { PostEvaluationResultRequest } from "./PostEvaluationResultRequest.js";
+export type { ResetEnvironmentRequest } from "./ResetEnvironmentRequest.js";
+export type { SetupRootAccessRequest } from "./SetupRootAccessRequest.js";
+export type { SetupSandboxRequest } from "./SetupSandboxRequest.js";
+export type { StartWorkerRequest } from "./StartWorkerRequest.js";

package/api/errors/BadRequestError.ts

@@ -0,0 +1,17 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as core from "../../core/index.js";
+import * as errors from "../../errors/index.js";
+import type * as Api from "../index.js";
+
+export class BadRequestError extends errors.ApiError {
+    constructor(body: Api.ErrorResponse, rawResponse?: core.RawResponse) {
+        super({
+            message: "BadRequestError",
+            statusCode: 400,
+            body: body,
+            rawResponse: rawResponse,
+        });
+        Object.setPrototypeOf(this, BadRequestError.prototype);
+    }
+}

package/api/errors/index.ts

@@ -0,0 +1 @@
+export * from "./BadRequestError.js";

package/api/index.ts

@@ -0,0 +1,3 @@
+export * from "./client/index.js";
+export * from "./errors/index.js";
+export * from "./types/index.js";

package/api/types/ActiveSessionResponse.ts

@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface ActiveSessionResponse {
+    session_id?: string;
+    error?: string;
+}

package/api/types/BackupEnvironmentResponse.ts

@@ -0,0 +1,7 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface BackupEnvironmentResponse {
+    success?: boolean;
+    message?: string;
+    data?: Record<string, unknown>;
+}

package/api/types/CdpUrlResponse.ts

@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface CdpUrlResponse {
+    data?: CdpUrlResponse.Data;
+    error?: string;
+}
+
+export namespace CdpUrlResponse {
+    export interface Data {
+        cdp_url?: string;
+    }
+}

package/api/types/CloseEnvironmentResponse.ts

@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface CloseEnvironmentResponse {
+    success?: boolean;
+    message?: string;
+}

package/api/types/CreateSandboxResponse.ts

@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface CreateSandboxResponse {
+    /** Public URL for the sandbox */
+    url?: string;
+    /** Public ID of the sandbox job */
+    job_public_id: string;
+    /** Job group ID for the sandbox */
+    job_group_id: string;
+    /** Current status of the sandbox */
+    status?: string;
+    /** Correlation ID for monitoring operation progress via SSE */
+    correlation_id?: string;
+}

package/api/types/CreateSnapshotResponse.ts

@@ -0,0 +1,10 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface CreateSnapshotResponse {
+    artifact_id: string;
+    status: string;
+    timestamp: string;
+    correlation_id: string;
+    s3_uri: string;
+    git_hash?: string;
+}

package/api/types/DeleteSandboxResponse.ts

@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface DeleteSandboxResponse {
+    success?: boolean;
+    message?: string;
+}