plato-sandbox-sdk 1.1.1

package/helpers/README.md

@@ -0,0 +1,229 @@
+# Plato SDK Helpers
+
+This directory contains **custom helper utilities** that are **NOT generated by Fern**. These files are safe to modify and will not be overwritten when regenerating the SDK.
+
+## Purpose
+
+The helpers provide high-level convenience functions that combine the low-level Fern-generated API client with business logic for:
+
+- Monitoring long-running operations via SSE streams
+- Waiting for sandbox operations to complete
+- Handling operation success/failure states
+
+## Files
+
+### `SandboxMonitor.ts`
+Core monitoring logic that processes SSE event streams and determines operation success/failure.
+
+**Based on:** `sdk/services/sandbox.go` (Go implementation)
+
+**Key Features:**
+- Handles SSE event types: `connected`, `progress`, `run_result`, `ssh_result`, `error`
+- Determines when operations are complete
+- Provides progress callbacks
+- Timeout support
+- Abort signal support
+
+### `SandboxHelpers.ts`
+High-level wrapper functions that combine API calls with automatic monitoring.
+
+**Convenience methods:**
+- `createSandbox()` - Create and wait for sandbox to be ready
+- `setupSandbox()` - Setup sandbox with monitoring
+- `createSnapshot()` - Create snapshot with monitoring
+- `startWorker()` - Start worker with monitoring
+- `setupRootAccess()` - Setup root access with monitoring
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { ApiClient, SandboxHelpers } from '@plato-sdk/typescript';
+
+// Create client
+const client = new ApiClient({
+  baseUrl: 'https://plato.so/api',
+  // Add auth headers, etc.
+});
+
+// Create helpers
+const helpers = new SandboxHelpers(client);
+
+// Create sandbox and wait for it to be ready
+const sandbox = await helpers.createSandbox({
+  dataset: 'base',
+  plato_dataset_config: {
+    compute: {
+      cpus: 2,
+      memory: 4096,
+      disk: 20480,
+      app_port: 8080,
+      plato_messaging_port: 7000
+    },
+    metadata: {
+      name: 'My Sandbox'
+    }
+  }
+}, {
+  onProgress: (message) => {
+    console.log('Progress:', message);
+  },
+  timeoutMs: 600000 // 10 minutes
+});
+
+console.log('Sandbox ready!', sandbox);
+```
+
+### Advanced: Using SandboxMonitor Directly
+
+```typescript
+import { ApiClient, SandboxMonitor } from '@plato-sdk/typescript';
+
+const client = new ApiClient({ /* ... */ });
+const monitor = new SandboxMonitor(client);
+
+// Create sandbox without waiting
+const response = await client.createSandbox({ /* ... */ });
+const sandbox = response.data;
+
+// Later, monitor it manually
+if (sandbox.correlation_id) {
+  await monitor.waitForCompletion(sandbox.correlation_id, {
+    onProgress: (msg) => console.log(msg),
+    timeoutMs: 600000
+  });
+}
+```
+
+### Getting All Events
+
+```typescript
+const monitor = new SandboxMonitor(client);
+
+// Get all events for debugging
+const events = await monitor.waitForCompletionWithEvents(
+  correlationId,
+  {
+    onProgress: (msg) => console.log(msg)
+  }
+);
+
+console.log('All events:', events);
+```
+
+### Error Handling
+
+```typescript
+import { SandboxOperationError } from '@plato-sdk/typescript';
+
+try {
+  await helpers.createSandbox({ /* ... */ });
+} catch (error) {
+  if (error instanceof SandboxOperationError) {
+    console.error('Operation failed:', error.message);
+    console.error('Last event:', error.event);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Create Without Waiting
+
+```typescript
+// Don't wait for operation to complete
+const sandbox = await helpers.createSandbox({
+  dataset: 'base',
+  plato_dataset_config: config
+}, {
+  wait: false  // Return immediately after creating
+});
+
+// Monitor it later if needed
+if (sandbox.correlation_id) {
+  await helpers.getMonitor().waitForCompletion(sandbox.correlation_id);
+}
+```
+
+## How It Works
+
+### SSE Event Flow
+
+The Plato API sends Server-Sent Events to monitor long-running operations:
+
+1. **`connected`** - Initial connection established
+2. **`progress`** - Progress updates (optional)
+3. **Terminal events:**
+   - **`run_result`** - Operation completed (check `success` field)
+   - **`ssh_result`** - SSH operation completed (check `success` field)
+   - **`error`** - Operation failed
+
+### Event Structure
+
+```typescript
+interface OperationEvent {
+  type: 'connected' | 'run_result' | 'ssh_result' | 'error' | 'progress';
+  success?: boolean;    // Only present in result events
+  error?: string;       // Error message if failed
+  message?: string;     // Human-readable status/progress
+}
+```
+
+### Success Detection
+
+An operation is **successful** if:
+- You receive a `run_result` or `ssh_result` event with `success: true`
+
+An operation **failed** if:
+- You receive an `error` event
+- You receive a result event with `success: false`
+- The stream ends without a terminal event
+- The operation times out
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│   Your Application Code             │
+└─────────────┬───────────────────────┘
+              │
+              │ Uses
+              ▼
+┌─────────────────────────────────────┐
+│   SandboxHelpers                    │  ◄── Custom (not generated)
+│   - High-level convenience methods  │
+└─────────────┬───────────────────────┘
+              │
+              │ Uses
+              ▼
+┌─────────────────────────────────────┐
+│   SandboxMonitor                    │  ◄── Custom (not generated)
+│   - SSE event processing            │
+│   - Success/failure detection       │
+└─────────────┬───────────────────────┘
+              │
+              │ Uses
+              ▼
+┌─────────────────────────────────────┐
+│   ApiClient (Fern-generated)        │  ◄── Generated by Fern
+│   - Low-level API calls             │
+│   - SSE streaming                   │
+└─────────────────────────────────────┘
+```
+
+## Why Separate Files?
+
+- **Generated code** (Client.ts, api/*) is overwritten on each `fern generate`
+- **Custom helpers** (this directory) persist across regenerations
+- **Clean separation** between API client and business logic
+- **Easy to maintain** and extend without modifying generated code
+
+## Regenerating the SDK
+
+When you regenerate the SDK with `fern generate`:
+- ✅ Files in `helpers/` are **preserved**
+- ❌ Other files are **overwritten**
+
+This is the recommended pattern for extending Fern-generated SDKs.
+

package/helpers/SandboxHelpers.ts

@@ -0,0 +1,213 @@
+/**
+ * High-level helper functions for sandbox operations.
+ * 
+ * This file is NOT generated by Fern and provides convenient wrappers
+ * around the generated API client with built-in operation monitoring.
+ * 
+ * Based on the Go implementation in sdk/services/sandbox.go
+ */
+
+import type { ApiClient } from "../Client.js";
+import type * as Api from "../api/index.js";
+import { SandboxMonitor, type MonitorOptions } from "./SandboxMonitor.js";
+
+export interface CreateSandboxOptions extends MonitorOptions {
+  /**
+   * Whether to wait for the sandbox to be ready before returning.
+   * If true, monitors the operation until completion.
+   * Default: true
+   */
+  wait?: boolean;
+}
+
+export interface SetupSandboxOptions extends MonitorOptions {
+  /**
+   * Whether to wait for setup to complete before returning.
+   * If true, monitors the operation until completion.
+   * Default: true
+   */
+  wait?: boolean;
+}
+
+/**
+ * High-level helpers for sandbox operations that combine API calls
+ * with operation monitoring.
+ */
+export class SandboxHelpers {
+  private monitor: SandboxMonitor;
+
+  constructor(private readonly client: ApiClient) {
+    this.monitor = new SandboxMonitor(client);
+  }
+
+  /**
+   * Create a sandbox and optionally wait for it to be ready.
+   * 
+   * This is a convenience wrapper that:
+   * 1. Calls createSandbox API
+   * 2. If wait=true (default), monitors the operation until completion
+   * 3. Returns the sandbox info
+   * 
+   * @param request - Sandbox creation request
+   * @param options - Creation and monitoring options
+   * @returns Sandbox information
+   * 
+   * @example
+   * ```typescript
+   * const helpers = new SandboxHelpers(client);
+   * 
+   * // Create and wait for ready (default)
+   * const sandbox = await helpers.createSandbox({
+   *   dataset: "base",
+   *   plato_dataset_config: config
+   * }, {
+   *   onProgress: (msg) => console.log(msg)
+   * });
+   * 
+   * // Create without waiting
+   * const sandbox = await helpers.createSandbox({
+   *   dataset: "base",
+   *   plato_dataset_config: config
+   * }, { wait: false });
+   * ```
+   */
+  async createSandbox(
+    request: Api.CreateSandboxRequest,
+    options: CreateSandboxOptions = {}
+  ): Promise<Api.CreateSandboxResponse> {
+    const { wait = true, ...monitorOptions } = options;
+
+    // Create the sandbox
+    // Note: HttpResponsePromise automatically unwraps to the response type
+    const sandbox = await this.client.createSandbox(request);
+
+    // Wait for it to be ready if requested
+    if (wait && sandbox.correlation_id) {
+      await this.monitor.waitForCompletion(sandbox.correlation_id, monitorOptions);
+    }
+
+    return sandbox;
+  }
+
+  /**
+   * Setup a sandbox and optionally wait for completion.
+   * 
+   * This is a convenience wrapper that:
+   * 1. Calls setupSandbox API
+   * 2. If wait=true (default), monitors the operation until completion
+   * 3. Returns the correlation ID
+   * 
+   * @param jobId - Job ID of the sandbox
+   * @param request - Setup request with dataset config and optional SSH key
+   * @param options - Setup and monitoring options
+   * @returns Setup response with correlation ID
+   * 
+   * @example
+   * ```typescript
+   * const helpers = new SandboxHelpers(client);
+   * 
+   * await helpers.setupSandbox("job_123", {
+   *   dataset: "base",
+   *   plato_dataset_config: config,
+   *   ssh_public_key: publicKey
+   * }, {
+   *   onProgress: (msg) => console.log(msg)
+   * });
+   * ```
+   */
+  async setupSandbox(
+    jobId: string,
+    request: Api.SetupSandboxRequest,
+    options: SetupSandboxOptions = {}
+  ): Promise<Api.SetupSandboxResponse> {
+    const { wait = true, ...monitorOptions } = options;
+
+    // Setup the sandbox
+    const setupResponse = await this.client.setupSandbox(jobId, request);
+
+    // Wait for setup to complete if requested
+    if (wait && setupResponse.correlation_id) {
+      await this.monitor.waitForCompletion(setupResponse.correlation_id, monitorOptions);
+    }
+
+    return setupResponse;
+  }
+
+  /**
+   * Create a snapshot and optionally wait for completion.
+   * 
+   * @param publicId - Public ID of the sandbox
+   * @param request - Snapshot request
+   * @param options - Monitoring options
+   * @returns Snapshot response
+   */
+  async createSnapshot(
+    publicId: string,
+    request: Api.CreateSnapshotRequest,
+    options: MonitorOptions = {}
+  ): Promise<Api.CreateSnapshotResponse> {
+    const snapshot = await this.client.createSnapshot(publicId, request);
+
+    // Note: Snapshot operations may return a correlation_id for monitoring
+    // If it does, we should monitor it
+    if ('correlation_id' in snapshot && typeof (snapshot as any).correlation_id === 'string') {
+      await this.monitor.waitForCompletion((snapshot as any).correlation_id, options);
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Start a Plato worker and optionally wait for completion.
+   * 
+   * @param publicId - Public ID of the sandbox
+   * @param request - Worker start request
+   * @param options - Monitoring options
+   * @returns Worker start response
+   */
+  async startWorker(
+    publicId: string,
+    request: Api.StartWorkerRequest,
+    options: MonitorOptions = {}
+  ): Promise<Api.StartWorkerResponse> {
+    const workerResponse = await this.client.startWorker(publicId, request);
+
+    // Monitor if correlation_id is provided
+    if (workerResponse.correlation_id) {
+      await this.monitor.waitForCompletion(workerResponse.correlation_id, options);
+    }
+
+    return workerResponse;
+  }
+
+  /**
+   * Setup root access and optionally wait for completion.
+   * 
+   * @param publicId - Public ID of the sandbox
+   * @param request - Root access setup request
+   * @param options - Monitoring options
+   * @returns Setup response
+   */
+  async setupRootAccess(
+    publicId: string,
+    request: Api.SetupRootAccessRequest,
+    options: MonitorOptions = {}
+  ): Promise<Api.SetupRootAccessResponse> {
+    const setupResponse = await this.client.setupRootAccess(publicId, request);
+
+    // Monitor if correlation_id is provided
+    if (setupResponse.correlation_id) {
+      await this.monitor.waitForCompletion(setupResponse.correlation_id, options);
+    }
+
+    return setupResponse;
+  }
+
+  /**
+   * Get the underlying monitor for advanced use cases.
+   */
+  getMonitor(): SandboxMonitor {
+    return this.monitor;
+  }
+}
+

package/helpers/SandboxMonitor.ts

@@ -0,0 +1,252 @@
+/**
+ * Helper utilities for monitoring sandbox operations.
+ * 
+ * This file is NOT generated by Fern and contains custom business logic
+ * for handling SSE streams from the Plato API.
+ * 
+ * Based on the Go implementation in sdk/services/sandbox.go
+ */
+
+import type { ApiClient } from "../Client.js";
+import type { OperationEvent } from "../api/types/OperationEvent.js";
+
+export interface MonitorOptions {
+  /**
+   * Timeout in milliseconds for the entire operation.
+   * Default: 600000 (10 minutes)
+   */
+  timeoutMs?: number;
+
+  /**
+   * Callback for progress updates
+   */
+  onProgress?: (message: string) => void;
+
+  /**
+   * Abort signal to cancel the operation
+   */
+  abortSignal?: AbortSignal;
+}
+
+export class SandboxOperationError extends Error {
+  constructor(message: string, public readonly event?: OperationEvent) {
+    super(message);
+    this.name = 'SandboxOperationError';
+  }
+}
+
+export class SandboxMonitor {
+  constructor(private readonly client: ApiClient) {}
+
+  /**
+   * Monitor a sandbox operation until completion.
+   * 
+   * This implements the business logic from the Go SDK (sandbox.go):
+   * - Waits for terminal events (run_result, ssh_result, error)
+   * - Reports progress via callback
+   * - Throws on failure
+   * - Returns on success
+   * 
+   * @param correlationId - Correlation ID from sandbox creation or setup
+   * @param options - Monitoring options
+   * @throws {SandboxOperationError} If the operation fails
+   * @throws {Error} If the stream ends unexpectedly
+   * 
+   * @example
+   * ```typescript
+   * const monitor = new SandboxMonitor(client);
+   * const sandbox = await client.createSandbox({ ... });
+   * 
+   * // Wait for sandbox to be ready
+   * await monitor.waitForCompletion(sandbox.correlation_id, {
+   *   onProgress: (msg) => console.log('Progress:', msg)
+   * });
+   * ```
+   */
+  async waitForCompletion(
+    correlationId: string,
+    options: MonitorOptions = {}
+  ): Promise<void> {
+    const { timeoutMs = 600000, onProgress, abortSignal } = options;
+
+    // Set up timeout
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => {
+      timeoutController.abort();
+    }, timeoutMs);
+
+    // Combine abort signals
+    const combinedSignal = abortSignal 
+      ? this.combineAbortSignals([abortSignal, timeoutController.signal])
+      : timeoutController.signal;
+
+    try {
+      // Get the SSE stream from the generated client
+      // Note: HttpResponsePromise automatically unwraps to the Stream type
+      const stream = await this.client.monitorOperation(correlationId, {
+        abortSignal: combinedSignal,
+        // Increase timeout to match the operation timeout
+        timeoutInSeconds: Math.ceil(timeoutMs / 1000),
+      });
+
+      // Process events from the stream
+      for await (const event of stream) {
+        // NOTE: The Go implementation expects base64-encoded JSON in the SSE data field.
+        // Fern's Stream class should handle the SSE parsing, but we may need to handle
+        // base64 decoding if the API sends it that way. For now, assuming Fern handles it.
+        
+        const result = this.handleEvent(event, onProgress);
+        
+        if (result.shouldTerminate) {
+          if (result.success) {
+            return; // Success!
+          } else {
+            throw new SandboxOperationError(
+              result.error || 'Operation failed',
+              event
+            );
+          }
+        }
+      }
+
+      // Stream ended without terminal event
+      throw new Error('SSE stream ended without completion event');
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Monitor operation and collect all events.
+   * Useful for debugging or detailed progress tracking.
+   * 
+   * @param correlationId - Correlation ID from sandbox creation or setup
+   * @param options - Monitoring options
+   * @returns Array of all events received
+   * @throws {SandboxOperationError} If the operation fails
+   */
+  async waitForCompletionWithEvents(
+    correlationId: string,
+    options: MonitorOptions = {}
+  ): Promise<OperationEvent[]> {
+    const events: OperationEvent[] = [];
+    
+    const wrappedOptions: MonitorOptions = {
+      ...options,
+      onProgress: (message) => {
+        if (options.onProgress) {
+          options.onProgress(message);
+        }
+      },
+    };
+
+    try {
+      const stream = await this.client.monitorOperation(correlationId, {
+        abortSignal: options.abortSignal,
+        timeoutInSeconds: Math.ceil((options.timeoutMs || 600000) / 1000),
+      });
+
+      for await (const event of stream) {
+        events.push(event);
+        
+        const result = this.handleEvent(event, wrappedOptions.onProgress);
+        
+        if (result.shouldTerminate) {
+          if (!result.success) {
+            throw new SandboxOperationError(
+              result.error || 'Operation failed',
+              event
+            );
+          }
+          break;
+        }
+      }
+
+      return events;
+    } catch (error) {
+      // Still return events even on error for debugging
+      if (error instanceof SandboxOperationError) {
+        throw error;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Handle a single operation event and determine if operation should terminate.
+   * 
+   * This implements the state machine from sandbox.go MonitorOperation():
+   * - connected: Continue listening
+   * - progress: Report progress, continue listening
+   * - run_result/ssh_result: Terminal event, check success
+   * - error: Terminal event, always failure
+   * 
+   * @private
+   */
+  private handleEvent(
+    event: OperationEvent,
+    onProgress?: (message: string) => void
+  ): { shouldTerminate: boolean; success?: boolean; error?: string } {
+    switch (event.type) {
+      case 'connected':
+        // Initial connection, continue listening
+        return { shouldTerminate: false };
+
+      case 'progress':
+        // Progress update
+        if (onProgress && event.message) {
+          onProgress(event.message);
+        }
+        return { shouldTerminate: false };
+
+      case 'run_result':
+      case 'ssh_result':
+        // Terminal event - operation completed
+        if (event.success) {
+          // Success!
+          if (onProgress && event.message) {
+            onProgress(event.message);
+          }
+          return { shouldTerminate: true, success: true };
+        } else {
+          // Failed
+          const errorMsg = event.error || event.message || 'Operation failed';
+          return { shouldTerminate: true, success: false, error: errorMsg };
+        }
+
+      case 'error':
+        // Error event - always terminal
+        const errorMsg = event.error || event.message || 'Operation error';
+        return { shouldTerminate: true, success: false, error: errorMsg };
+
+      default:
+        // Unknown event type - log and continue
+        console.warn('Unknown operation event type:', event.type);
+        return { shouldTerminate: false };
+    }
+  }
+
+  /**
+   * Combine multiple abort signals into one.
+   * If any signal aborts, the combined signal aborts.
+   * 
+   * @private
+   */
+  private combineAbortSignals(signals: AbortSignal[]): AbortSignal {
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+      if (signal.aborted) {
+        controller.abort();
+        break;
+      }
+
+      signal.addEventListener('abort', () => {
+        controller.abort();
+      });
+    }
+
+    return controller.signal;
+  }
+}
+

package/helpers/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Custom helpers for the Plato SDK.
+ * 
+ * These utilities are NOT generated by Fern and provide high-level
+ * convenience functions built on top of the generated API client.
+ */
+
+export { SandboxMonitor, SandboxOperationError, type MonitorOptions } from "./SandboxMonitor.js";
+export { SandboxHelpers, type CreateSandboxOptions, type SetupSandboxOptions } from "./SandboxHelpers.js";
+

package/index.ts

@@ -0,0 +1,7 @@
+export * as Api from "./api/index.js";
+export type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
+export { ApiClient } from "./Client.js";
+export { ApiError, ApiTimeoutError } from "./errors/index.js";
+
+// Custom helpers (not generated by Fern)
+export * from "./helpers/index.js";