@lizard-build/sdk 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,479 @@
+interface ConnectionOpts {
+    apiKey?: string;
+    apiUrl?: string;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+declare class ConnectionConfig {
+    readonly apiKey: string;
+    readonly apiUrl: string;
+    readonly timeoutMs: number;
+    constructor(opts?: ConnectionOpts);
+    get headers(): Record<string, string>;
+}
+
+/**
+ * The result of a process execution inside a Lizard microVM.
+ */
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface ProcessOpts {
+    timeoutMs?: number;
+    envs?: Record<string, string>;
+    user?: string;
+    workdir?: string;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+}
+/**
+ * Runs processes inside a Lizard sandbox microVM.
+ *
+ * Access via `sandbox.process`.
+ */
+declare class Process {
+    private readonly sandboxId;
+    private readonly config;
+    constructor(sandboxId: string, config: ConnectionConfig);
+    /**
+     * Execute a command inside the microVM and wait for it to complete.
+     *
+     * The command runs in a shell inside the Lizard sandbox and returns
+     * stdout, stderr, and the exit code when it finishes.
+     *
+     * @param cmd Shell command to run inside the microVM.
+     * @param opts Optional execution options — environment variables, working
+     *   directory, user, and timeout.
+     *
+     * @example
+     * ```ts
+     * const result = await sandbox.process.exec('node index.js')
+     * console.log(result.stdout)
+     * ```
+     *
+     * @example Run with a custom working directory and env vars:
+     * ```ts
+     * const result = await sandbox.process.exec('npm test', {
+     *   workdir: '/app',
+     *   envs: { NODE_ENV: 'test' },
+     * })
+     * ```
+     */
+    exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+}
+
+interface FsOpts {
+    user?: string;
+}
+interface FileInfo {
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+    size: number;
+}
+/**
+ * Read and write files inside a Lizard sandbox microVM.
+ *
+ * Access via `sandbox.fs`.
+ */
+declare class Fs {
+    private readonly sandboxId;
+    private readonly config;
+    constructor(sandboxId: string, config: ConnectionConfig);
+    /**
+     * Write a file into the microVM filesystem.
+     *
+     * Creates parent directories automatically if they don't exist.
+     *
+     * @example
+     * ```ts
+     * await sandbox.fs.write('/app/index.js', 'console.log("hello")')
+     * ```
+     *
+     * @example Write binary data:
+     * ```ts
+     * await sandbox.fs.write('/app/data.bin', buffer)
+     * ```
+     */
+    write(path: string, data: string | Uint8Array, opts?: FsOpts): Promise<void>;
+    /**
+     * Read a file from the microVM filesystem.
+     *
+     * @returns The file contents as a UTF-8 string.
+     *
+     * @example
+     * ```ts
+     * const content = await sandbox.fs.read('/app/index.js')
+     * ```
+     */
+    read(path: string, opts?: FsOpts): Promise<string>;
+    /**
+     * List files and directories at the given path inside the microVM.
+     *
+     * @example
+     * ```ts
+     * const entries = await sandbox.fs.list('/app')
+     * ```
+     */
+    list(path: string, opts?: FsOpts): Promise<FileInfo[]>;
+    /**
+     * Remove a file or directory from the microVM filesystem.
+     */
+    remove(path: string, opts?: FsOpts): Promise<void>;
+    /**
+     * Create a directory (and any missing parents) inside the microVM.
+     */
+    makeDir(path: string, opts?: FsOpts): Promise<void>;
+    private execInternal;
+}
+
+interface SandboxInfo {
+    sandboxId: string;
+    template: string;
+    startedAt: string;
+    endAt: string;
+    metadata?: Record<string, string>;
+}
+interface SandboxOpts extends ConnectionOpts {
+    template?: string;
+    metadata?: Record<string, string>;
+    envs?: Record<string, string>;
+    timeoutMs?: number;
+}
+/**
+ * Low-level HTTP client for the Lizard sandbox API.
+ * Extended by the `Sandbox` class — you typically don't use this directly.
+ */
+declare class SandboxClient {
+    protected static createSandbox(template: string, timeoutMs: number, opts?: SandboxOpts): Promise<{
+        sandboxId: string;
+    }>;
+    protected static killSandbox(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    protected static pauseSandbox(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    protected static resumeSandbox(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    protected static listSandboxes(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+    protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
+    protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
+}
+
+/**
+ * A Lizard sandbox — an isolated Firecracker microVM that boots in milliseconds.
+ *
+ * Each sandbox is a full Linux environment with its own filesystem, network,
+ * and process namespace. Sandboxes are spun up from templates and can be
+ * paused to a snapshot, then resumed instantly — perfect for stateful AI
+ * agent sessions or ephemeral code execution.
+ *
+ * @example Basic usage:
+ * ```ts
+ * import { Sandbox } from 'lizard'
+ *
+ * const sandbox = await Sandbox.create('node22')
+ * await sandbox.fs.write('/app/index.js', 'console.log("hello world")')
+ * const result = await sandbox.process.exec('node /app/index.js')
+ * console.log(result.stdout) // "hello world"
+ * await sandbox.kill()
+ * ```
+ *
+ * @example Pause and resume a long-running session:
+ * ```ts
+ * const sandbox = await Sandbox.create('python312')
+ * await sandbox.process.exec('pip install numpy')
+ * const id = sandbox.sandboxId
+ * await sandbox.pause()
+ *
+ * // Later — resume exactly where it left off:
+ * const resumed = await Sandbox.connect(id)
+ * await resumed.process.exec('python -c "import numpy; print(numpy.__version__)"')
+ * ```
+ */
+declare class Sandbox extends SandboxClient {
+    protected static readonly defaultTemplate: string;
+    protected static readonly defaultTimeoutMs: number;
+    /**
+     * Unique identifier of this sandbox microVM.
+     */
+    readonly sandboxId: string;
+    /**
+     * Read and write files inside the microVM filesystem.
+     *
+     * @example
+     * ```ts
+     * await sandbox.fs.write('/app/main.py', 'print("hello")')
+     * const src = await sandbox.fs.read('/app/main.py')
+     * ```
+     */
+    readonly fs: Fs;
+    /**
+     * Execute processes inside the microVM.
+     *
+     * @example
+     * ```ts
+     * const { stdout } = await sandbox.process.exec('python main.py')
+     * ```
+     */
+    readonly process: Process;
+    protected readonly connectionConfig: ConnectionConfig;
+    constructor(opts: {
+        sandboxId: string;
+    } & ConnectionOpts);
+    /**
+     * Create a new Lizard sandbox from the default `base` template.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await Sandbox.create()
+     * ```
+     */
+    static create(opts?: SandboxOpts): Promise<Sandbox>;
+    /**
+     * Create a new Lizard sandbox from the specified template.
+     *
+     * Available templates include `base`, `node22`, and `python312`. Custom
+     * templates can be built and pushed via `lizard push`.
+     *
+     * @param template Name of the sandbox template to boot from.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await Sandbox.create('node22')
+     * const sandbox = await Sandbox.create('python312', { timeoutMs: 10 * 60 * 1000 })
+     * ```
+     */
+    static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
+    /**
+     * Connect to an existing sandbox by its ID.
+     *
+     * If the sandbox is currently paused, it will be automatically resumed
+     * from its last snapshot before this call returns.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await Sandbox.connect('sandbox_abc123')
+     * ```
+     */
+    static connect(sandboxId: string, opts?: ConnectionOpts): Promise<Sandbox>;
+    /**
+     * List all running sandboxes for the authenticated account.
+     *
+     * @example
+     * ```ts
+     * const sandboxes = await Sandbox.list()
+     * ```
+     */
+    static list(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+    /**
+     * Kill the sandbox and release its resources immediately.
+     *
+     * @returns `true` if the microVM was terminated, `false` if it was already gone.
+     */
+    kill(opts?: ConnectionOpts): Promise<boolean>;
+    /**
+     * Snapshot and pause the sandbox microVM.
+     *
+     * The sandbox state — memory, filesystem, and running processes — is saved
+     * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     *
+     * @returns `true` if paused successfully.
+     */
+    pause(opts?: ConnectionOpts): Promise<boolean>;
+    /**
+     * Resume a paused sandbox from its last snapshot.
+     *
+     * @returns `true` if resumed successfully.
+     */
+    resume(opts?: ConnectionOpts): Promise<boolean>;
+    /**
+     * Get metadata and status information about this sandbox.
+     */
+    getInfo(opts?: ConnectionOpts): Promise<SandboxInfo>;
+    /**
+     * Extend or reduce the sandbox timeout.
+     *
+     * @param timeoutMs New timeout in milliseconds measured from now.
+     */
+    setTimeout(timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
+    /**
+     * Get the public HTTPS URL for a port exposed inside the sandbox.
+     *
+     * Useful for accessing HTTP servers started inside the microVM from your
+     * agent or tests without additional tunneling.
+     *
+     * @example
+     * ```ts
+     * await sandbox.process.exec('npx -y serve -p 3000 &')
+     * const url = sandbox.getHost(3000)
+     * // https://{sandboxId}-3000.sandbox.lizard.run
+     * ```
+     */
+    getHost(port: number): string;
+    private resolveOpts;
+}
+
+declare class LizardError extends Error {
+    constructor(message: string);
+}
+declare class AuthenticationError extends LizardError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends LizardError {
+    constructor(message?: string);
+}
+declare class TimeoutError extends LizardError {
+    constructor(message?: string);
+}
+
+/** A single output item produced during code execution. */
+type OutputItem = {
+    type: 'stdout';
+    data: string;
+    ts: number;
+} | {
+    type: 'stderr';
+    data: string;
+    ts: number;
+} | {
+    type: 'result';
+    mime: string;
+    data: string;
+} | {
+    type: 'error';
+    name: string;
+    message: string;
+    traceback: string;
+};
+/** Error thrown when executed code raises an exception. */
+declare class ExecutionError extends Error {
+    readonly name: string;
+    readonly traceback: string;
+    constructor(name: string, message: string, traceback: string);
+}
+/** Full result of a runCode() call. */
+declare class Execution {
+    /** All stdout text, concatenated. */
+    stdout: string;
+    /** All stderr text, concatenated. */
+    stderr: string;
+    /** Rich output items (images, JSON, HTML, plain values). */
+    results: OutputItem[];
+    /** Execution error if the code threw an exception. */
+    error?: ExecutionError;
+    /** Monotonically increasing counter for this context. */
+    executionCount: number;
+    get success(): boolean;
+    get text(): string;
+}
+/** An isolated stateful execution context. */
+type CodeContext = {
+    id: string;
+    language: string;
+    cwd: string;
+};
+type RunCodeLanguage = 'python' | 'javascript' | 'bash' | (string & Record<never, never>);
+interface RunCodeOpts {
+    /** Language to run in. Defaults to python. */
+    language?: RunCodeLanguage;
+    /** Use a specific context instead of the per-language default. */
+    context?: CodeContext;
+    /** Extra environment variables available to the code. */
+    envs?: Record<string, string>;
+    /** Max time to wait for the code to finish, in ms. Default: 60_000. */
+    timeoutMs?: number;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    onResult?: (item: OutputItem) => void;
+    onError?: (err: ExecutionError) => void;
+}
+interface CreateContextOpts {
+    language?: RunCodeLanguage;
+    cwd?: string;
+}
+
+/**
+ * A Lizard sandbox with built-in stateful code execution.
+ *
+ * Extends the base Sandbox with `runCode()` — executes code in a persistent
+ * kernel so variables and imports survive between calls.
+ *
+ * Supports Python, JavaScript (Node.js), and Bash out of the box.
+ *
+ * @example
+ * ```ts
+ * import { CodeSandbox } from 'lizard/code-interpreter'
+ *
+ * const sandbox = await CodeSandbox.create()
+ *
+ * await sandbox.runCode('x = 42')
+ * const result = await sandbox.runCode('print(x * 2)')
+ * console.log(result.stdout) // "84\n"
+ *
+ * await sandbox.kill()
+ * ```
+ *
+ * @example Run JavaScript:
+ * ```ts
+ * const result = await sandbox.runCode('1 + 1', { language: 'javascript' })
+ * console.log(result.results[0].data) // "2"
+ * ```
+ */
+declare class CodeSandbox extends Sandbox {
+    protected static readonly defaultTemplate = "code-interpreter-v1";
+    private get serverUrl();
+    /**
+     * Execute code in a persistent kernel.
+     *
+     * Variables, imports, and function definitions from previous calls are
+     * available in subsequent calls within the same context.
+     *
+     * @param code  Source code to run.
+     * @param opts  Language, context, env vars, timeout, and streaming callbacks.
+     *
+     * @returns Execution result with stdout, stderr, results, and any error.
+     *
+     * @throws {ExecutionError} if you pass neither language nor context and no
+     *   default context exists — which cannot happen in normal usage.
+     *
+     * @example
+     * ```ts
+     * const result = await sandbox.runCode(`
+     *   import math
+     *   print(math.sqrt(144))
+     * `)
+     * console.log(result.stdout) // "12.0\n"
+     * ```
+     */
+    runCode(code: string, opts?: RunCodeOpts): Promise<Execution>;
+    /**
+     * Create a new isolated execution context.
+     *
+     * Each context maintains its own variable namespace and process state.
+     * Useful for running multiple independent sessions in the same sandbox.
+     *
+     * @example
+     * ```ts
+     * const ctx = await sandbox.createContext({ language: 'python' })
+     * await sandbox.runCode('x = 10', { context: ctx })
+     * await sandbox.runCode('print(x)', { context: ctx }) // prints 10
+     * ```
+     */
+    createContext(opts?: CreateContextOpts): Promise<CodeContext>;
+    /**
+     * List all active execution contexts in this sandbox.
+     */
+    listContexts(): Promise<CodeContext[]>;
+    /**
+     * Delete an execution context and free its resources.
+     */
+    deleteContext(context: CodeContext | string): Promise<void>;
+    /**
+     * Restart a context, clearing all variables and state.
+     */
+    restartContext(context: CodeContext | string): Promise<void>;
+    static create(opts?: SandboxOpts): Promise<CodeSandbox>;
+    static create(template: string, opts?: SandboxOpts): Promise<CodeSandbox>;
+    static connect(sandboxId: string, opts?: ConnectionOpts): Promise<CodeSandbox>;
+}
+
+export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, Execution, ExecutionError, type FileInfo, type FsOpts, LizardError, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError };