@blaxel/core 0.2.67-preview.88 → 0.2.67-preview.89

package/dist/cjs/types/image/image.d.ts

@@ -0,0 +1,202 @@
+import { Sandbox } from "../client/types.gen.js";
+export declare const SANDBOX_API_IMAGE = "ghcr.io/blaxel-ai/sandbox";
+export declare const SANDBOX_API_PATH = "/usr/local/bin/sandbox-api";
+/**
+ * Represents a local file to be copied into the build context.
+ */
+export interface LocalFile {
+    sourcePath: string;
+    destinationPath: string;
+    contextName: string;
+}
+/**
+ * Contains all information needed to generate a deployable folder.
+ */
+export interface ImageBuildContext {
+    baseImage: string;
+    instructions: string[];
+    localFiles: LocalFile[];
+    hasEntrypoint: boolean;
+}
+/**
+ * Options for building and deploying an image
+ */
+export interface ImageBuildOptions {
+    name: string;
+    memory?: number;
+    timeout?: number;
+    onStatusChange?: (status: string) => void;
+    sandboxVersion?: string;
+}
+/**
+ * A fluent builder for creating sandbox images programmatically.
+ *
+ * Similar to Modal's Image class, allows chaining operations to build
+ * a custom image from a base image.
+ *
+ * @example
+ * ```typescript
+ * const image = ImageInstance.fromRegistry("python:3.11-slim")
+ *   .runCommands("apt-get update && apt-get install -y git curl")
+ *   .workdir("/app")
+ *   .runCommands("pip install --upgrade pip")
+ *   .env({ PYTHONUNBUFFERED: "1" });
+ *
+ * await image.build({
+ *   name: "my-sandbox",
+ *   memory: 4096,
+ *   timeout: 900000,
+ *   onStatusChange: console.log,
+ *   sandboxVersion: "latest",
+ * });
+ * ```
+ */
+export declare class ImageInstance {
+    private _context;
+    constructor(context: ImageBuildContext);
+    /**
+     * Create an image from a Docker registry image.
+     *
+     * @param tag - The image tag (e.g., "python:3.11-slim", "ubuntu:22.04")
+     * @returns A new Image instance
+     */
+    static fromRegistry(tag: string): ImageInstance;
+    /**
+     * Set the working directory for subsequent instructions.
+     *
+     * @param path - The working directory path inside the container
+     * @returns A new Image instance with the working directory set
+     */
+    workdir(path: string): ImageInstance;
+    /**
+     * Run shell commands in the image.
+     *
+     * @param commands - One or more shell commands to run
+     * @returns A new Image instance with the commands added
+     */
+    runCommands(...commands: string[]): ImageInstance;
+    /**
+     * Set environment variables.
+     *
+     * @param variables - Environment variables as an object
+     * @returns A new Image instance with the environment variables set
+     */
+    env(variables: Record<string, string>): ImageInstance;
+    /**
+     * Copy files or directories from the build context to the image.
+     *
+     * @param source - Source path (relative to build context)
+     * @param destination - Destination path in the image
+     * @returns A new Image instance with the copy instruction
+     */
+    copy(source: string, destination: string): ImageInstance;
+    /**
+     * Add a local file to the build context and copy it to the image.
+     *
+     * @param sourcePath - Path to the local file
+     * @param destination - Destination path in the image
+     * @param contextName - Optional name for the file in the build context
+     * @returns A new Image instance with the file added
+     */
+    addLocalFile(sourcePath: string, destination: string, contextName?: string): ImageInstance;
+    /**
+     * Add a local directory to the build context and copy it to the image.
+     *
+     * @param sourcePath - Path to the local directory
+     * @param destination - Destination path in the image
+     * @param contextName - Optional name for the directory in the build context
+     * @returns A new Image instance with the directory added
+     */
+    addLocalDir(sourcePath: string, destination: string, contextName?: string): ImageInstance;
+    /**
+     * Expose ports.
+     *
+     * @param ports - Port numbers to expose
+     * @returns A new Image instance with the ports exposed
+     */
+    expose(...ports: number[]): ImageInstance;
+    /**
+     * Set the entrypoint for the image.
+     *
+     * @param args - Entrypoint command and arguments
+     * @returns A new Image instance with the entrypoint set
+     */
+    entrypoint(...args: string[]): ImageInstance;
+    /**
+     * Set the user for subsequent instructions.
+     *
+     * @param user - Username or UID
+     * @returns A new Image instance with the user set
+     */
+    user(user: string): ImageInstance;
+    /**
+     * Add labels to the image.
+     *
+     * @param labels - Labels as an object
+     * @returns A new Image instance with the labels added
+     */
+    label(labels: Record<string, string>): ImageInstance;
+    /**
+     * Define a build argument.
+     *
+     * @param name - Argument name
+     * @param defaultValue - Optional default value
+     * @returns A new Image instance with the argument defined
+     */
+    arg(name: string, defaultValue?: string): ImageInstance;
+    /**
+     * Get the generated Dockerfile content.
+     */
+    get dockerfile(): string;
+    /**
+     * Get a hash of the image configuration.
+     */
+    get hash(): string;
+    /**
+     * Get the base image tag.
+     */
+    get baseImage(): string;
+    private _hasSandboxApi;
+    private _prepareForSandbox;
+    /**
+     * Write the image to a deployable folder structure.
+     *
+     * @param outputPath - Path to the output directory
+     * @param name - Optional name for the generated folder (defaults to hash-based name)
+     * @returns Path to the generated folder
+     */
+    write(outputPath: string, name?: string): string;
+    /**
+     * Write the image to a deployable folder in a temporary directory.
+     *
+     * @returns Path to the generated folder
+     */
+    writeTemp(): string;
+    private _createZip;
+    private _createSandboxPayload;
+    private _createSandboxWithUpload;
+    private _uploadZip;
+    private _getSandboxStatus;
+    private _waitForDeployment;
+    /**
+     * Build and deploy the image as a sandbox.
+     *
+     * This method:
+     * 1. Prepares the image for sandbox deployment (adds sandbox-api)
+     * 2. Builds the image folder
+     * 3. Creates a zip of the folder
+     * 4. Creates/updates the sandbox resource
+     * 5. Uploads the zip to Blaxel
+     * 6. Waits for deployment to complete
+     *
+     * @param options - Build options
+     * @returns The deployed Sandbox object
+     */
+    build(options: ImageBuildOptions): Promise<Sandbox>;
+    /**
+     * Build and deploy the image as a sandbox (sync version).
+     *
+     * @deprecated Use build() instead - this is provided for API parity with Python SDK
+     */
+    buildSync(options: ImageBuildOptions): Promise<Sandbox>;
+}

package/dist/cjs/types/image/image.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @vitest-environment node
+ */
+export {};

package/dist/cjs/types/image/index.d.ts

@@ -0,0 +1 @@
+export { ImageInstance, ImageBuildContext, ImageBuildOptions, LocalFile, SANDBOX_API_IMAGE, SANDBOX_API_PATH, } from "./image.js";

package/dist/cjs/types/index.d.ts

@@ -9,6 +9,7 @@ export * from "./common/internal.js";
 export * from "./common/logger.js";
 export * from "./common/settings.js";
 export * from "./common/webhook.js";
+export * from "./image/index.js";
 export * from "./jobs/index.js";
 export * from "./mcp/index.js";
 export * from "./models/index.js";