@lizard-build/sdk 0.1.1

package/dist/index.mjs

@@ -0,0 +1,579 @@
+// src/config.ts
+var DEFAULT_API_URL = "https://api.lizard.run";
+var DEFAULT_SANDBOX_TIMEOUT_MS = 5 * 60 * 1e3;
+var ConnectionConfig = class {
+  constructor(opts) {
+    this.apiKey = opts?.apiKey ?? process.env.LIZARD_API_KEY ?? "";
+    this.apiUrl = opts?.apiUrl ?? process.env.LIZARD_API_URL ?? DEFAULT_API_URL;
+    this.timeoutMs = opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS;
+    if (!this.apiKey) {
+      throw new Error(
+        "Lizard API key is required. Set LIZARD_API_KEY env var or pass apiKey in options."
+      );
+    }
+  }
+  get headers() {
+    return {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json"
+    };
+  }
+};
+
+// src/errors.ts
+var LizardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LizardError";
+  }
+};
+var AuthenticationError = class extends LizardError {
+  constructor(message = "Invalid or missing API key") {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends LizardError {
+  constructor(message = "Sandbox not found") {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var TimeoutError = class extends LizardError {
+  constructor(message = "Sandbox operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+async function handleApiError(res) {
+  let message;
+  try {
+    const body = await res.json();
+    message = body.error ?? res.statusText;
+  } catch {
+    message = res.statusText;
+  }
+  if (res.status === 401 || res.status === 403) throw new AuthenticationError(message);
+  if (res.status === 404) throw new NotFoundError(message);
+  if (res.status === 408 || res.status === 504) throw new TimeoutError(message);
+  throw new LizardError(`API error ${res.status}: ${message}`);
+}
+
+// src/sandbox/process.ts
+var Process = class {
+  constructor(sandboxId, config) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+  }
+  /**
+   * 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' },
+   * })
+   * ```
+   */
+  async exec(cmd, opts) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({
+        cmd,
+        envs: opts?.envs,
+        user: opts?.user,
+        workdir: opts?.workdir,
+        timeoutMs: opts?.timeoutMs
+      }),
+      signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+};
+
+// src/sandbox/fs.ts
+var Fs = class {
+  constructor(sandboxId, config) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+  }
+  /**
+   * 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)
+   * ```
+   */
+  async write(path, data, opts) {
+    const content = typeof data === "string" ? data : new TextDecoder().decode(data);
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ path, content, user: opts?.user })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+  /**
+   * 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')
+   * ```
+   */
+  async read(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.text();
+  }
+  /**
+   * List files and directories at the given path inside the microVM.
+   *
+   * @example
+   * ```ts
+   * const entries = await sandbox.fs.list('/app')
+   * ```
+   */
+  async list(path, opts) {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/list`);
+    url.searchParams.set("path", path);
+    if (opts?.user) url.searchParams.set("user", opts.user);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /**
+   * Remove a file or directory from the microVM filesystem.
+   */
+  async remove(path, opts) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`, {
+      method: "DELETE",
+      headers: this.config.headers,
+      body: JSON.stringify({ path, user: opts?.user })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+  /**
+   * Create a directory (and any missing parents) inside the microVM.
+   */
+  async makeDir(path, opts) {
+    await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
+  }
+  async execInternal(cmd, user) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ cmd, user })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+};
+
+// src/sandbox/client.ts
+var SandboxClient = class {
+  static async createSandbox(template, timeoutMs, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({
+        template,
+        timeoutMs,
+        metadata: opts?.metadata,
+        envs: opts?.envs
+      })
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  static async killSandbox(sandboxId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}`, {
+      method: "DELETE",
+      headers: config.headers
+    });
+    if (res.status === 404) return false;
+    if (!res.ok) await handleApiError(res);
+    return true;
+  }
+  static async pauseSandbox(sandboxId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}/pause`, {
+      method: "POST",
+      headers: config.headers
+    });
+    if (res.status === 404) return false;
+    if (!res.ok) await handleApiError(res);
+    return true;
+  }
+  static async resumeSandbox(sandboxId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}/resume`, {
+      method: "POST",
+      headers: config.headers
+    });
+    if (res.status === 404) return false;
+    if (!res.ok) await handleApiError(res);
+    return true;
+  }
+  static async listSandboxes(opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  static async getSandboxInfo(sandboxId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}`, {
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  static async setTimeoutSandbox(sandboxId, timeoutMs, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/sandboxes/${sandboxId}/timeout`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({ timeoutMs })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+};
+
+// src/sandbox/index.ts
+var Sandbox = class extends SandboxClient {
+  constructor(opts) {
+    super();
+    this.sandboxId = opts.sandboxId;
+    this.connectionConfig = new ConnectionConfig(opts);
+    this.fs = new Fs(this.sandboxId, this.connectionConfig);
+    this.process = new Process(this.sandboxId, this.connectionConfig);
+  }
+  static async create(templateOrOpts, opts) {
+    const template = typeof templateOrOpts === "string" ? templateOrOpts : templateOrOpts?.template ?? this.defaultTemplate;
+    const sandboxOpts = typeof templateOrOpts === "string" ? opts : templateOrOpts;
+    const timeoutMs = sandboxOpts?.timeoutMs ?? this.defaultTimeoutMs;
+    const { sandboxId } = await SandboxClient.createSandbox(template, timeoutMs, sandboxOpts);
+    return new this({ sandboxId, ...sandboxOpts });
+  }
+  /**
+   * 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 async connect(sandboxId, opts) {
+    await SandboxClient.resumeSandbox(sandboxId, opts);
+    return new this({ sandboxId, ...opts });
+  }
+  /**
+   * List all running sandboxes for the authenticated account.
+   *
+   * @example
+   * ```ts
+   * const sandboxes = await Sandbox.list()
+   * ```
+   */
+  static async list(opts) {
+    return SandboxClient.listSandboxes(opts);
+  }
+  /**
+   * Kill the sandbox and release its resources immediately.
+   *
+   * @returns `true` if the microVM was terminated, `false` if it was already gone.
+   */
+  async kill(opts) {
+    return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
+  }
+  /**
+   * 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.
+   */
+  async pause(opts) {
+    return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
+  }
+  /**
+   * Resume a paused sandbox from its last snapshot.
+   *
+   * @returns `true` if resumed successfully.
+   */
+  async resume(opts) {
+    return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
+  }
+  /**
+   * Get metadata and status information about this sandbox.
+   */
+  async getInfo(opts) {
+    return SandboxClient.getSandboxInfo(this.sandboxId, this.resolveOpts(opts));
+  }
+  /**
+   * Extend or reduce the sandbox timeout.
+   *
+   * @param timeoutMs New timeout in milliseconds measured from now.
+   */
+  async setTimeout(timeoutMs, opts) {
+    return SandboxClient.setTimeoutSandbox(this.sandboxId, timeoutMs, this.resolveOpts(opts));
+  }
+  /**
+   * 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) {
+    const apiHost = new URL(this.connectionConfig.apiUrl).host;
+    const baseHost = apiHost.replace(/^api\./, "");
+    return `${this.sandboxId}-${port}.sandbox.${baseHost}`;
+  }
+  resolveOpts(opts) {
+    return { ...this.connectionConfig, ...opts };
+  }
+};
+Sandbox.defaultTemplate = "base";
+Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
+
+// src/code-interpreter/types.ts
+var ExecutionError = class extends Error {
+  constructor(name, message, traceback) {
+    super(message);
+    this.name = name;
+    this.traceback = traceback;
+  }
+};
+var Execution = class {
+  constructor() {
+    /** All stdout text, concatenated. */
+    this.stdout = "";
+    /** All stderr text, concatenated. */
+    this.stderr = "";
+    /** Rich output items (images, JSON, HTML, plain values). */
+    this.results = [];
+    /** Monotonically increasing counter for this context. */
+    this.executionCount = 0;
+  }
+  get success() {
+    return !this.error;
+  }
+  get text() {
+    return this.stdout;
+  }
+};
+
+// src/code-interpreter/index.ts
+var CODE_INTERPRETER_PORT = 8080;
+var CodeSandbox = class extends Sandbox {
+  get serverUrl() {
+    return `https://${this.getHost(CODE_INTERPRETER_PORT)}`;
+  }
+  /**
+   * 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"
+   * ```
+   */
+  async runCode(code, opts) {
+    if (opts?.context && opts?.language) {
+      throw new Error("Provide context or language, not both");
+    }
+    const body = { code, env_vars: opts?.envs ?? {} };
+    if (opts?.context) body.context_id = opts.context.id;
+    else if (opts?.language) body.language = opts.language;
+    const controller = new AbortController();
+    const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : void 0;
+    try {
+      const res = await fetch(`${this.serverUrl}/execute`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        throw new Error(`Code interpreter returned ${res.status}: ${await res.text()}`);
+      }
+      if (!res.body) throw new Error("Empty response body");
+      const execution = new Execution();
+      for await (const line of readLines(res.body)) {
+        let item;
+        try {
+          item = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (item.type === "stdout") {
+          execution.stdout += item.data;
+          opts?.onStdout?.(item.data);
+        } else if (item.type === "stderr") {
+          execution.stderr += item.data;
+          opts?.onStderr?.(item.data);
+        } else if (item.type === "result") {
+          const out = item;
+          execution.results.push(out);
+          opts?.onResult?.(out);
+        } else if (item.type === "error") {
+          const err = new ExecutionError(
+            item.name,
+            item.message,
+            item.traceback
+          );
+          execution.error = err;
+          opts?.onError?.(err);
+        } else if (item.type === "done") {
+          execution.executionCount = item.execution_count ?? 0;
+          break;
+        }
+      }
+      return execution;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * 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
+   * ```
+   */
+  async createContext(opts) {
+    const res = await fetch(`${this.serverUrl}/contexts`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        language: opts?.language ?? "python",
+        cwd: opts?.cwd ?? "/home/user"
+      })
+    });
+    if (!res.ok) throw new Error(`Failed to create context: ${await res.text()}`);
+    return res.json();
+  }
+  /**
+   * List all active execution contexts in this sandbox.
+   */
+  async listContexts() {
+    const res = await fetch(`${this.serverUrl}/contexts`);
+    if (!res.ok) throw new Error(`Failed to list contexts: ${await res.text()}`);
+    return res.json();
+  }
+  /**
+   * Delete an execution context and free its resources.
+   */
+  async deleteContext(context) {
+    const id = typeof context === "string" ? context : context.id;
+    const res = await fetch(`${this.serverUrl}/contexts/${id}`, { method: "DELETE" });
+    if (!res.ok) throw new Error(`Failed to delete context: ${await res.text()}`);
+  }
+  /**
+   * Restart a context, clearing all variables and state.
+   */
+  async restartContext(context) {
+    const id = typeof context === "string" ? context : context.id;
+    const res = await fetch(`${this.serverUrl}/contexts/${id}/restart`, { method: "POST" });
+    if (!res.ok) throw new Error(`Failed to restart context: ${await res.text()}`);
+  }
+  static async create(templateOrOpts, opts) {
+    return super.create(templateOrOpts, opts);
+  }
+  static async connect(sandboxId, opts) {
+    return super.connect(sandboxId, opts);
+  }
+};
+CodeSandbox.defaultTemplate = "code-interpreter-v1";
+async function* readLines(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim()) yield line;
+      }
+    }
+    if (buf.trim()) yield buf;
+  } finally {
+    reader.releaseLock();
+  }
+}
+export {
+  AuthenticationError,
+  CodeSandbox,
+  LizardError,
+  NotFoundError,
+  Sandbox,
+  TimeoutError
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@lizard-build/sdk",
+  "version": "0.1.1",
+  "description": "Lizard SDK — cloud sandboxes for AI agents",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "lizard",
+    "sandbox",
+    "ai",
+    "agents",
+    "firecracker"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.0.0"
+  }
+}