@sylphx/sdk 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -2852,6 +2852,172 @@ async function captureMessage(config, message, options = {}) {
     body: request
   });
 }
+
+// src/sandbox.ts
+var DEFAULT_IMAGE = "registry.sylphx.com/library/exec-server:latest";
+var SandboxClient = class _SandboxClient {
+  id;
+  config;
+  constructor(id, config) {
+    this.id = id;
+    this.config = config;
+  }
+  // ---------------------------------------------------------------------------
+  // Factory
+  // ---------------------------------------------------------------------------
+  /**
+   * Create a new sandbox.
+   *
+   * The sandbox pod starts asynchronously — it will be in `starting` status
+   * after creation. File/run operations will block until the pod is ready.
+   *
+   * @param config - Sylphx config with a secret key (sk_*) and project ref
+   * @param options - Sandbox creation options
+   */
+  static async create(config, options) {
+    const record = await callApi(config, `/sandboxes`, {
+      method: "POST",
+      body: {
+        image: options?.image ?? DEFAULT_IMAGE,
+        idleTimeoutMs: options?.idleTimeoutMs ?? 3e5,
+        resources: options?.resources,
+        env: options?.env,
+        storage: options?.storageGi !== void 0 ? { enabled: true, sizeGi: options.storageGi } : void 0
+      }
+    });
+    return new _SandboxClient(record.id, config);
+  }
+  /**
+   * Reconnect to an existing sandbox by ID.
+   *
+   * Use this to resume operations on a sandbox created in a previous request.
+   */
+  static fromId(config, sandboxId) {
+    return new _SandboxClient(sandboxId, config);
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  /**
+   * Get the current status of this sandbox.
+   */
+  async getStatus() {
+    return callApi(
+      this.config,
+      `/sandboxes/${this.id}`,
+      { method: "GET" }
+    );
+  }
+  /**
+   * Terminate the sandbox immediately.
+   *
+   * Deletes the K8s Pod and Service. PVC (storage) is preserved for reuse.
+   * This operation is idempotent — safe to call multiple times.
+   */
+  async terminate() {
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}`,
+      { method: "DELETE" }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // File Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * Write a file to the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox (e.g. '/workspace/file.py')
+   * @param content - File content as string or Buffer
+   * @param encoding - 'utf8' (default) or 'base64' for binary files
+   */
+  async writeFile(path, content, encoding = "utf8") {
+    const contentStr = Buffer.isBuffer(content) ? content.toString("base64") : content;
+    const effectiveEncoding = Buffer.isBuffer(content) ? "base64" : encoding;
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "POST",
+        body: { path, content: contentStr, encoding: effectiveEncoding }
+      }
+    );
+  }
+  /**
+   * Read a file from the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox
+   * @returns File content as a string
+   */
+  async readFile(path) {
+    const result = await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "GET",
+        query: { path }
+      }
+    );
+    return result.content;
+  }
+  /**
+   * Delete a file from the sandbox filesystem.
+   *
+   * @param path - Absolute path inside the sandbox
+   */
+  async deleteFile(path) {
+    await callApi(
+      this.config,
+      `/sandboxes/${this.id}/files`,
+      {
+        method: "DELETE",
+        query: { path }
+      }
+    );
+  }
+  /**
+   * List files in a directory.
+   *
+   * @param path - Directory path inside the sandbox (default: '/')
+   * @returns Array of file/directory paths
+   */
+  async listFiles(path = "/") {
+    const result = await callApi(
+      this.config,
+      `/sandboxes/${this.id}/list`,
+      {
+        method: "GET",
+        query: { path }
+      }
+    );
+    return result.files;
+  }
+  // ---------------------------------------------------------------------------
+  // Command Execution
+  // ---------------------------------------------------------------------------
+  /**
+   * Run a command inside the sandbox.
+   *
+   * The command runs synchronously inside the exec pod and returns when complete.
+   *
+   * @param command - Full command + args as array (e.g. ['python3', 'script.py'])
+   * @param options - Optional cwd, env, timeout, stdin
+   * @returns { stdout, stderr, exitCode, durationMs }
+   *
+   * @example
+   * ```typescript
+   * const { stdout, exitCode } = await sandbox.run(['python3', '-c', 'print(1+1)'])
+   * console.log(stdout) // "2\n"
+   * console.log(exitCode) // 0
+   * ```
+   */
+  async run(command, options) {
+    return callApi(this.config, `/sandboxes/${this.id}/run`, {
+      method: "POST",
+      body: { command, ...options }
+    });
+  }
+};
 export {
   ACHIEVEMENT_TIER_CONFIG,
   AuthenticationError,
@@ -2862,6 +3028,7 @@ export {
   NotFoundError,
   RETRYABLE_CODES,
   RateLimitError,
+  SandboxClient,
   SylphxError,
   TimeoutError,
   ValidationError,