computesdk 1.12.0 → 1.13.0

package/dist/index.d.mts

@@ -1922,6 +1922,155 @@ declare class Child {
     }): Promise<void>;
 }
 
+/**
+ * Overlay - Resource namespace for filesystem overlay operations
+ *
+ * Overlays enable instant sandbox setup from template directories by symlinking
+ * files first for instant access, then copying heavy directories in the background.
+ */
+/**
+ * Options for creating an overlay
+ */
+interface CreateOverlayOptions {
+    /** Absolute path to source directory (template) */
+    source: string;
+    /** Relative path in sandbox where overlay will be mounted */
+    target: string;
+}
+/**
+ * Copy status for overlay background operations
+ */
+type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+/**
+ * Statistics about an overlay
+ */
+interface OverlayStats {
+    /** Number of symlinked files */
+    symlinkedFiles: number;
+    /** Number of symlinked directories */
+    symlinkedDirs: number;
+    /** Paths that were skipped (e.g., .git) */
+    skipped: string[];
+}
+/**
+ * Overlay information (client-side normalized type)
+ */
+interface OverlayInfo {
+    /** Unique overlay identifier */
+    id: string;
+    /** Absolute path to source directory */
+    source: string;
+    /** Relative path in sandbox */
+    target: string;
+    /** When the overlay was created */
+    createdAt: string;
+    /** Statistics about the overlay */
+    stats: OverlayStats;
+    /** Copy status for background operations */
+    copyStatus: OverlayCopyStatus;
+    /** Error message if copy failed */
+    copyError?: string;
+}
+/**
+ * API response for overlay operations (snake_case from server)
+ */
+interface OverlayResponse {
+    id: string;
+    source: string;
+    target: string;
+    created_at: string;
+    stats: {
+        symlinked_files: number;
+        symlinked_dirs: number;
+        skipped: string[];
+    };
+    copy_status: string;
+    copy_error?: string;
+}
+/**
+ * API response for listing overlays
+ */
+interface OverlayListResponse {
+    overlays: OverlayResponse[];
+}
+/**
+ * Overlay resource namespace
+ *
+ * @example
+ * ```typescript
+ * // Create an overlay from a template directory
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ * });
+ * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+ *
+ * // List all overlays
+ * const overlays = await sandbox.filesystem.overlay.list();
+ *
+ * // Get a specific overlay (useful for polling copy status)
+ * const overlay = await sandbox.filesystem.overlay.retrieve('overlay-id');
+ * if (overlay.copyStatus === 'complete') {
+ *   console.log('Background copy finished!');
+ * }
+ *
+ * // Delete an overlay
+ * await sandbox.filesystem.overlay.destroy('overlay-id');
+ * ```
+ */
+declare class Overlay {
+    private createHandler;
+    private listHandler;
+    private retrieveHandler;
+    private destroyHandler;
+    constructor(handlers: {
+        create: (options: CreateOverlayOptions) => Promise<OverlayResponse>;
+        list: () => Promise<OverlayListResponse>;
+        retrieve: (id: string) => Promise<OverlayResponse>;
+        destroy: (id: string) => Promise<void>;
+    });
+    /**
+     * Create a new overlay from a template directory
+     *
+     * The overlay symlinks files from the source directory into the target path,
+     * allowing instant access to template files. Heavy directories (node_modules,
+     * .venv, etc.) are copied in the background.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory
+     * @param options.target - Relative path in sandbox
+     * @returns Overlay info with copy status
+     */
+    create(options: CreateOverlayOptions): Promise<OverlayInfo>;
+    /**
+     * List all overlays for the current sandbox
+     * @returns Array of overlay info
+     */
+    list(): Promise<OverlayInfo[]>;
+    /**
+     * Retrieve a specific overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay info
+     */
+    retrieve(id: string): Promise<OverlayInfo>;
+    /**
+     * Destroy (delete) an overlay
+     * @param id - Overlay ID
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Convert API response to OverlayInfo
+     */
+    private toOverlayInfo;
+    /**
+     * Validate and return copy status, defaulting to 'pending' for unknown values
+     */
+    private validateCopyStatus;
+}
+
 /**
  * Binary WebSocket Protocol Implementation
  *
@@ -2030,6 +2179,14 @@ declare function isCommandExitError(error: unknown): error is CommandExitError;
  * Node.js: Pass WebSocket implementation (e.g., 'ws' library)
  */
 
+/**
+ * Extended filesystem interface with overlay support
+ */
+interface ExtendedFileSystem extends SandboxFileSystem {
+    /** Overlay operations for template directories */
+    readonly overlay: Overlay;
+}
+
 /**
  * WebSocket constructor type
  */
@@ -2593,7 +2750,7 @@ interface BatchWriteResponse {
 declare class Sandbox {
     readonly sandboxId: string;
     readonly provider: string;
-    readonly filesystem: SandboxFileSystem;
+    readonly filesystem: ExtendedFileSystem;
     readonly terminal: Terminal;
     readonly run: Run;
     readonly server: Server;
@@ -2827,6 +2984,47 @@ declare class Sandbox {
         operation: 'write' | 'delete';
         content?: string;
     }>): Promise<BatchWriteResponse>;
+    /**
+     * Create a new filesystem overlay from a template directory
+     *
+     * Overlays enable instant sandbox setup by symlinking template files first,
+     * then copying heavy directories (node_modules, .venv, etc.) in the background.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory (template)
+     * @param options.target - Relative path in sandbox where overlay will be mounted
+     * @returns Overlay response with copy status
+     *
+     * @example
+     * ```typescript
+     * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+     * const overlay = await sandbox.filesystem.overlay.create({
+     *   source: '/templates/nextjs',
+     *   target: 'project',
+     * });
+     * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+     * ```
+     */
+    createOverlay(options: CreateOverlayOptions): Promise<OverlayResponse>;
+    /**
+     * List all filesystem overlays for the current sandbox
+     * @returns List of overlays with their copy status
+     */
+    listOverlays(): Promise<OverlayListResponse>;
+    /**
+     * Get a specific filesystem overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay details with current copy status
+     */
+    getOverlay(id: string): Promise<OverlayResponse>;
+    /**
+     * Delete a filesystem overlay
+     * @param id - Overlay ID
+     */
+    deleteOverlay(id: string): Promise<void>;
     /**
      * Create a new persistent terminal session
      *
@@ -3321,6 +3519,8 @@ interface CreateSandboxOptions {
     envs?: Record<string, string>;
     name?: string;
     namespace?: string;
+    /** Docker image to use for the sandbox (for infrastructure providers like Railway) */
+    image?: string;
 }
 /**
  * Options for finding or creating a named sandbox
@@ -3511,4 +3711,4 @@ declare const PROVIDER_ENV_VARS: {
     readonly blaxel: readonly ["BL_API_KEY", "BL_WORKSPACE"];
 };
 
-export { type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };
+export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };

package/dist/index.d.ts

@@ -1922,6 +1922,155 @@ declare class Child {
     }): Promise<void>;
 }
 
+/**
+ * Overlay - Resource namespace for filesystem overlay operations
+ *
+ * Overlays enable instant sandbox setup from template directories by symlinking
+ * files first for instant access, then copying heavy directories in the background.
+ */
+/**
+ * Options for creating an overlay
+ */
+interface CreateOverlayOptions {
+    /** Absolute path to source directory (template) */
+    source: string;
+    /** Relative path in sandbox where overlay will be mounted */
+    target: string;
+}
+/**
+ * Copy status for overlay background operations
+ */
+type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+/**
+ * Statistics about an overlay
+ */
+interface OverlayStats {
+    /** Number of symlinked files */
+    symlinkedFiles: number;
+    /** Number of symlinked directories */
+    symlinkedDirs: number;
+    /** Paths that were skipped (e.g., .git) */
+    skipped: string[];
+}
+/**
+ * Overlay information (client-side normalized type)
+ */
+interface OverlayInfo {
+    /** Unique overlay identifier */
+    id: string;
+    /** Absolute path to source directory */
+    source: string;
+    /** Relative path in sandbox */
+    target: string;
+    /** When the overlay was created */
+    createdAt: string;
+    /** Statistics about the overlay */
+    stats: OverlayStats;
+    /** Copy status for background operations */
+    copyStatus: OverlayCopyStatus;
+    /** Error message if copy failed */
+    copyError?: string;
+}
+/**
+ * API response for overlay operations (snake_case from server)
+ */
+interface OverlayResponse {
+    id: string;
+    source: string;
+    target: string;
+    created_at: string;
+    stats: {
+        symlinked_files: number;
+        symlinked_dirs: number;
+        skipped: string[];
+    };
+    copy_status: string;
+    copy_error?: string;
+}
+/**
+ * API response for listing overlays
+ */
+interface OverlayListResponse {
+    overlays: OverlayResponse[];
+}
+/**
+ * Overlay resource namespace
+ *
+ * @example
+ * ```typescript
+ * // Create an overlay from a template directory
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ * });
+ * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+ *
+ * // List all overlays
+ * const overlays = await sandbox.filesystem.overlay.list();
+ *
+ * // Get a specific overlay (useful for polling copy status)
+ * const overlay = await sandbox.filesystem.overlay.retrieve('overlay-id');
+ * if (overlay.copyStatus === 'complete') {
+ *   console.log('Background copy finished!');
+ * }
+ *
+ * // Delete an overlay
+ * await sandbox.filesystem.overlay.destroy('overlay-id');
+ * ```
+ */
+declare class Overlay {
+    private createHandler;
+    private listHandler;
+    private retrieveHandler;
+    private destroyHandler;
+    constructor(handlers: {
+        create: (options: CreateOverlayOptions) => Promise<OverlayResponse>;
+        list: () => Promise<OverlayListResponse>;
+        retrieve: (id: string) => Promise<OverlayResponse>;
+        destroy: (id: string) => Promise<void>;
+    });
+    /**
+     * Create a new overlay from a template directory
+     *
+     * The overlay symlinks files from the source directory into the target path,
+     * allowing instant access to template files. Heavy directories (node_modules,
+     * .venv, etc.) are copied in the background.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory
+     * @param options.target - Relative path in sandbox
+     * @returns Overlay info with copy status
+     */
+    create(options: CreateOverlayOptions): Promise<OverlayInfo>;
+    /**
+     * List all overlays for the current sandbox
+     * @returns Array of overlay info
+     */
+    list(): Promise<OverlayInfo[]>;
+    /**
+     * Retrieve a specific overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay info
+     */
+    retrieve(id: string): Promise<OverlayInfo>;
+    /**
+     * Destroy (delete) an overlay
+     * @param id - Overlay ID
+     */
+    destroy(id: string): Promise<void>;
+    /**
+     * Convert API response to OverlayInfo
+     */
+    private toOverlayInfo;
+    /**
+     * Validate and return copy status, defaulting to 'pending' for unknown values
+     */
+    private validateCopyStatus;
+}
+
 /**
  * Binary WebSocket Protocol Implementation
  *
@@ -2030,6 +2179,14 @@ declare function isCommandExitError(error: unknown): error is CommandExitError;
  * Node.js: Pass WebSocket implementation (e.g., 'ws' library)
  */
 
+/**
+ * Extended filesystem interface with overlay support
+ */
+interface ExtendedFileSystem extends SandboxFileSystem {
+    /** Overlay operations for template directories */
+    readonly overlay: Overlay;
+}
+
 /**
  * WebSocket constructor type
  */
@@ -2593,7 +2750,7 @@ interface BatchWriteResponse {
 declare class Sandbox {
     readonly sandboxId: string;
     readonly provider: string;
-    readonly filesystem: SandboxFileSystem;
+    readonly filesystem: ExtendedFileSystem;
     readonly terminal: Terminal;
     readonly run: Run;
     readonly server: Server;
@@ -2827,6 +2984,47 @@ declare class Sandbox {
         operation: 'write' | 'delete';
         content?: string;
     }>): Promise<BatchWriteResponse>;
+    /**
+     * Create a new filesystem overlay from a template directory
+     *
+     * Overlays enable instant sandbox setup by symlinking template files first,
+     * then copying heavy directories (node_modules, .venv, etc.) in the background.
+     *
+     * @param options - Overlay creation options
+     * @param options.source - Absolute path to source directory (template)
+     * @param options.target - Relative path in sandbox where overlay will be mounted
+     * @returns Overlay response with copy status
+     *
+     * @example
+     * ```typescript
+     * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+     * const overlay = await sandbox.filesystem.overlay.create({
+     *   source: '/templates/nextjs',
+     *   target: 'project',
+     * });
+     * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+     * ```
+     */
+    createOverlay(options: CreateOverlayOptions): Promise<OverlayResponse>;
+    /**
+     * List all filesystem overlays for the current sandbox
+     * @returns List of overlays with their copy status
+     */
+    listOverlays(): Promise<OverlayListResponse>;
+    /**
+     * Get a specific filesystem overlay by ID
+     *
+     * Useful for polling the copy status of an overlay.
+     *
+     * @param id - Overlay ID
+     * @returns Overlay details with current copy status
+     */
+    getOverlay(id: string): Promise<OverlayResponse>;
+    /**
+     * Delete a filesystem overlay
+     * @param id - Overlay ID
+     */
+    deleteOverlay(id: string): Promise<void>;
     /**
      * Create a new persistent terminal session
      *
@@ -3321,6 +3519,8 @@ interface CreateSandboxOptions {
     envs?: Record<string, string>;
     name?: string;
     namespace?: string;
+    /** Docker image to use for the sandbox (for infrastructure providers like Railway) */
+    image?: string;
 }
 /**
  * Options for finding or creating a named sandbox
@@ -3511,4 +3711,4 @@ declare const PROVIDER_ENV_VARS: {
     readonly blaxel: readonly ["BL_API_KEY", "BL_WORKSPACE"];
 };
 
-export { type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };
+export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };

package/dist/index.js

@@ -1898,6 +1898,87 @@ var Child = class {
   }
 };
 
+// src/client/resources/overlay.ts
+var Overlay = class {
+  constructor(handlers) {
+    this.createHandler = handlers.create;
+    this.listHandler = handlers.list;
+    this.retrieveHandler = handlers.retrieve;
+    this.destroyHandler = handlers.destroy;
+  }
+  /**
+   * Create a new overlay from a template directory
+   *
+   * The overlay symlinks files from the source directory into the target path,
+   * allowing instant access to template files. Heavy directories (node_modules,
+   * .venv, etc.) are copied in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory
+   * @param options.target - Relative path in sandbox
+   * @returns Overlay info with copy status
+   */
+  async create(options) {
+    const response = await this.createHandler(options);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * List all overlays for the current sandbox
+   * @returns Array of overlay info
+   */
+  async list() {
+    const response = await this.listHandler();
+    return response.overlays.map((o) => this.toOverlayInfo(o));
+  }
+  /**
+   * Retrieve a specific overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay info
+   */
+  async retrieve(id) {
+    const response = await this.retrieveHandler(id);
+    return this.toOverlayInfo(response);
+  }
+  /**
+   * Destroy (delete) an overlay
+   * @param id - Overlay ID
+   */
+  async destroy(id) {
+    return this.destroyHandler(id);
+  }
+  /**
+   * Convert API response to OverlayInfo
+   */
+  toOverlayInfo(response) {
+    return {
+      id: response.id,
+      source: response.source,
+      target: response.target,
+      createdAt: response.created_at,
+      stats: {
+        symlinkedFiles: response.stats.symlinked_files,
+        symlinkedDirs: response.stats.symlinked_dirs,
+        skipped: response.stats.skipped
+      },
+      copyStatus: this.validateCopyStatus(response.copy_status),
+      copyError: response.copy_error
+    };
+  }
+  /**
+   * Validate and return copy status, defaulting to 'pending' for unknown values
+   */
+  validateCopyStatus(status) {
+    const validStatuses = ["pending", "in_progress", "complete", "failed"];
+    if (validStatuses.includes(status)) {
+      return status;
+    }
+    return "pending";
+  }
+};
+
 // src/client/types.ts
 var CommandExitError = class extends Error {
   constructor(result) {
@@ -1992,7 +2073,13 @@ var Sandbox = class {
       },
       remove: async (path) => {
         await this.deleteFile(path);
-      }
+      },
+      overlay: new Overlay({
+        create: async (options) => this.createOverlay(options),
+        list: async () => this.listOverlays(),
+        retrieve: async (id) => this.getOverlay(id),
+        destroy: async (id) => this.deleteOverlay(id)
+      })
     };
     this.terminal = new Terminal({
       create: async (options) => this.createTerminal(options),
@@ -2477,6 +2564,63 @@ API request failed (${response.status}): ${error}`
     });
   }
   // ============================================================================
+  // Filesystem Overlays
+  // ============================================================================
+  /**
+   * Create a new filesystem overlay from a template directory
+   *
+   * Overlays enable instant sandbox setup by symlinking template files first,
+   * then copying heavy directories (node_modules, .venv, etc.) in the background.
+   *
+   * @param options - Overlay creation options
+   * @param options.source - Absolute path to source directory (template)
+   * @param options.target - Relative path in sandbox where overlay will be mounted
+   * @returns Overlay response with copy status
+   *
+   * @example
+   * ```typescript
+   * // Prefer using sandbox.filesystem.overlay.create() for camelCase response
+   * const overlay = await sandbox.filesystem.overlay.create({
+   *   source: '/templates/nextjs',
+   *   target: 'project',
+   * });
+   * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
+   * ```
+   */
+  async createOverlay(options) {
+    return this.request("/filesystem/overlays", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * List all filesystem overlays for the current sandbox
+   * @returns List of overlays with their copy status
+   */
+  async listOverlays() {
+    return this.request("/filesystem/overlays");
+  }
+  /**
+   * Get a specific filesystem overlay by ID
+   *
+   * Useful for polling the copy status of an overlay.
+   *
+   * @param id - Overlay ID
+   * @returns Overlay details with current copy status
+   */
+  async getOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`);
+  }
+  /**
+   * Delete a filesystem overlay
+   * @param id - Overlay ID
+   */
+  async deleteOverlay(id) {
+    return this.request(`/filesystem/overlays/${id}`, {
+      method: "DELETE"
+    });
+  }
+  // ============================================================================
   // Terminal Management
   // ============================================================================
   /**