@lizard-build/sdk 0.1.39 → 0.1.41

package/dist/index.mjs

@@ -6,6 +6,7 @@ var ConnectionConfig = class {
     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;
+    this.requestTimeoutMs = opts?.requestTimeoutMs ?? 12e4;
     if (!this.apiKey) {
       throw new Error(
         "Lizard API key is required. Set LIZARD_API_KEY env var or pass apiKey in options."
@@ -27,6 +28,13 @@ var LizardError = class extends Error {
     this.name = "LizardError";
   }
 };
+var ConfigApplyError = class extends LizardError {
+  constructor(result) {
+    super("Config was saved, but one or more side effects failed; inspect result before retrying");
+    this.result = result;
+    this.name = "ConfigApplyError";
+  }
+};
 var AuthenticationError = class extends LizardError {
   constructor(message = "Invalid or missing API key") {
     super(message);
@@ -66,19 +74,358 @@ async function handleApiError(res) {
   throw new LizardError(`API error ${res.status}: ${message}`);
 }
 
+// src/platform/client.ts
+var segment = (value) => encodeURIComponent(value);
+function query(path, values) {
+  const qs = new URLSearchParams();
+  for (const [key, value] of Object.entries(values)) if (value !== void 0) qs.set(key, String(value));
+  return qs.size ? `${path}?${qs}` : path;
+}
+var PlatformClient = class {
+  constructor(opts) {
+    this.config = new ConnectionConfig(opts);
+  }
+  async json(res) {
+    if (!res.ok) await handleApiError(res);
+    if (res.status === 204 || res.headers.get("content-length") === "0") return void 0;
+    const text = await res.text();
+    return text ? JSON.parse(text) : void 0;
+  }
+  request(method, path, body) {
+    return fetch(`${this.config.apiUrl}${path}`, {
+      method,
+      headers: this.config.headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+    }).then((res) => this.json(res));
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  put(path, body) {
+    return this.request("PUT", path, body);
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
+  delete(path, body) {
+    return this.request("DELETE", path, body);
+  }
+  async applyConfig(projectId, body) {
+    const result = await this.post(`/api/projects/${projectId}/config:apply`, body);
+    if (result?.sideEffectFailures?.length) throw new ConfigApplyError(result);
+    return result;
+  }
+  sendBytes(method, path, body, contentType = "application/octet-stream") {
+    const payload = typeof body === "string" || body instanceof Blob ? body : new Blob([new Uint8Array(body)]);
+    return fetch(`${this.config.apiUrl}${path}`, {
+      method,
+      headers: { ...this.config.headers, "Content-Type": contentType },
+      body: payload,
+      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+    }).then((res) => this.json(res));
+  }
+  postForm(path, form) {
+    return fetch(`${this.config.apiUrl}${path}`, {
+      method: "POST",
+      headers: { "X-API-Key": this.config.apiKey },
+      body: form,
+      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+    }).then((res) => this.json(res));
+  }
+  /** Preserves named events, multiline data and UTF-8 split across chunks. */
+  async *events(path, opts = {}) {
+    const res = await fetch(`${this.config.apiUrl}${path}`, {
+      method: opts.method ?? "GET",
+      headers: this.config.headers,
+      body: opts.body === void 0 ? void 0 : JSON.stringify(opts.body),
+      signal: opts.signal
+    });
+    if (!res.ok) await handleApiError(res);
+    if (!res.body) return;
+    const reader = res.body.getReader(), decoder = new TextDecoder();
+    let buffer = "", event = "message", id, data = [];
+    const line = (text) => {
+      if (text === "") {
+        const result = data.length ? { event, data: data.join("\n"), id } : void 0;
+        event = "message";
+        data = [];
+        return result;
+      }
+      if (text.startsWith(":")) return;
+      const colon = text.indexOf(":");
+      const field = colon < 0 ? text : text.slice(0, colon);
+      const value = colon < 0 ? "" : text.slice(colon + 1).replace(/^ /, "");
+      if (field === "data") data.push(value);
+      if (field === "event") event = value;
+      if (field === "id" && !value.includes("\0")) id = value;
+    };
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        let end;
+        while ((end = buffer.indexOf("\n")) >= 0) {
+          const result = line(buffer.slice(0, end).replace(/\r$/, ""));
+          buffer = buffer.slice(end + 1);
+          if (result) yield result;
+        }
+        if (done) break;
+      }
+    } finally {
+      await reader.cancel();
+      reader.releaseLock();
+    }
+  }
+  async *streamSse(path) {
+    for await (const event of this.events(path)) yield event.data;
+  }
+};
+
+// src/platform/storage.ts
+var StorageAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  list(projectId, addonId, opts = {}) {
+    return this.client.get(query(`/api/projects/${projectId}/addons/${addonId}/s3/buckets/${segment(opts.bucket ?? "default")}/objects`, { prefix: opts.prefix }));
+  }
+  upload(projectId, addonId, opts) {
+    const key = opts.key.split("/").map(segment).join("/");
+    return this.client.sendBytes("PUT", `/api/projects/${projectId}/addons/${addonId}/s3/objects/${segment(opts.bucket ?? "default")}/${key}`, opts.source, opts.contentType);
+  }
+};
+
+// src/platform/services.ts
+var DeployHandle = class {
+  constructor(client, serviceId, buildId) {
+    this._client = client;
+    this._serviceId = serviceId;
+    this._buildId = buildId;
+  }
+  get serviceId() {
+    return this._serviceId;
+  }
+  /** Stream build log messages until the server closes the build stream. */
+  async *logs() {
+    let buildId = this._buildId;
+    if (!buildId) {
+      const svc = await this._client.get(`/api/apps/${this._serviceId}`);
+      buildId = svc.builds?.[0]?.id;
+    }
+    if (!buildId) throw new LizardError("No build found for this deploy");
+    for await (const event of this._client.events(`/api/builds/${buildId}/logs`)) {
+      if (event.event === "error") throw new LizardError(event.data);
+      if (event.event === "done") return;
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        data = event.data;
+      }
+      yield typeof data === "string" ? data : event.data;
+    }
+  }
+  /**
+   * Poll until the deploy reaches a terminal state.
+   * @returns `{ url, status }` on success; throws `LizardError` on failure.
+   */
+  async wait(opts) {
+    const deadline = Date.now() + (opts?.timeoutMs ?? 10 * 6e4);
+    const pollMs = opts?.pollMs ?? 3e3;
+    while (Date.now() < deadline) {
+      let buildDone = true;
+      if (this._buildId) {
+        const build = await this._client.get(`/api/builds/${this._buildId}`);
+        if (build.status === "failed" || build.status === "cancelled") throw new LizardError(`Deploy ${build.status}`);
+        buildDone = build.status === "done";
+      }
+      const svc = await this._client.get(`/api/apps/${this._serviceId}`);
+      if (svc.deployStatus === "idle") {
+        if (buildDone && svc.status === "running") return { url: svc.domain ? `https://${svc.domain}` : null, status: "running" };
+        if (svc.status === "crashed") throw new LizardError(`Service crashed after deploy`);
+      }
+      if (svc.deployStatus === "failed") throw new LizardError(`Deploy failed`);
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+    throw new TimeoutError(`Deploy did not complete within ${opts?.timeoutMs ?? 6e5}ms`);
+  }
+};
+var ServicesAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all services in a project. */
+  list(opts) {
+    return this.client.get(`/api/projects/${opts.projectId}/apps`);
+  }
+  /** Get a service by ID. */
+  get(id) {
+    return this.client.get(`/api/apps/${id}`);
+  }
+  /**
+   * Create a service and start a deploy from a git repo.
+   * Returns a DeployHandle to track progress.
+   */
+  async deploy(opts) {
+    const body = {
+      name: opts.name,
+      sourceType: opts.sourceType ?? "github",
+      repoUrl: opts.repoUrl,
+      branch: opts.branch ?? "main",
+      startCommand: opts.startCommand,
+      buildCommand: opts.buildCommand,
+      preDeployCommand: opts.preDeployCommand,
+      dockerfilePath: opts.dockerfilePath,
+      context: opts.rootDirectory,
+      envVars: opts.envVars,
+      skipInitialDeploy: opts.skipInitialDeploy,
+      cpuLimit: opts.cpuLimit,
+      memoryLimit: opts.memoryLimit,
+      containerPort: opts.port ?? opts.containerPort,
+      region: opts.region
+    };
+    const svc = await this.client.post(`/api/projects/${opts.projectId}/apps`, body);
+    const handle = new DeployHandle(this.client, svc.id, svc.buildId);
+    if (opts.waitForDeploy) await handle.wait();
+    return handle;
+  }
+  /**
+   * Upload a tarball and deploy it.
+   *
+   * @param opts.source - A `Buffer`, `Blob`, or `Uint8Array` of a `.tar.gz` file.
+   */
+  async upload(opts) {
+    if (!opts.name && !opts.serviceId) throw new LizardError("name or serviceId is required");
+    const path = query(`/api/projects/${opts.projectId}/apps/upload`, {
+      name: opts.name,
+      appId: opts.serviceId,
+      startCommand: opts.startCommand,
+      buildCommand: opts.buildCommand,
+      preDeployCommand: opts.preDeployCommand,
+      port: opts.port,
+      region: opts.region
+    });
+    const result = await this.client.sendBytes("POST", path, opts.source);
+    return new DeployHandle(this.client, result.id, result.buildId);
+  }
+  /** Trigger a redeploy (rebuild from current source). */
+  async redeploy(id) {
+    const build = await this.client.post(`/api/apps/${id}/redeploy`, {});
+    return new DeployHandle(this.client, id, build.id);
+  }
+  /** Restart a service without rebuilding. */
+  restart(id) {
+    return this.client.post(`/api/apps/${id}/restart`, {});
+  }
+  /** Scale a service. */
+  async scale(id, opts) {
+    if (opts.storageMi !== void 0) throw new LizardError("Storage scaling is only supported for addons");
+    if (opts.replicas !== void 0) await this.client.patch(`/api/apps/${id}/scale`, { replicas: opts.replicas });
+    if (opts.cpuMillis !== void 0 || opts.memoryMi !== void 0) {
+      await this.update(id, {
+        ...opts.cpuMillis !== void 0 ? { cpuLimit: `${opts.cpuMillis}m` } : {},
+        ...opts.memoryMi !== void 0 ? { memoryLimit: `${opts.memoryMi}Mi` } : {}
+      });
+    }
+  }
+  /**
+   * Get recent log lines. For a live tail, use the WebSocket API instead.
+   *
+   * @param opts.limit - Max lines to return (default 200, max 1000).
+   */
+  async logs(id, opts) {
+    const svc = await this.get(id);
+    const result = await this.client.get(query(`/api/projects/${svc.projectId}/logs`, { service: svc.name, limit: opts?.limit ?? 200, since: opts?.since }));
+    return Array.isArray(result) ? result : result.logs ?? [];
+  }
+  /** Execute a command; collect SSE output and require an exit event. */
+  async exec(id, cmd, opts) {
+    const result = { stdout: "", stderr: "", exitCode: -1 };
+    for await (const event of this.client.events(`/api/apps/${id}/exec`, {
+      method: "POST",
+      body: { cmd },
+      signal: AbortSignal.timeout(opts?.timeoutMs ?? 3e5)
+    })) {
+      if (event.event === "error") throw new LizardError(event.data);
+      const data = JSON.parse(event.data);
+      if (data.stream === "stdout" || data.stream === "stderr") result[data.stream] += (data.line ?? "") + "\n";
+      if (event.event === "exit" && typeof data.exitCode === "number") result.exitCode = data.exitCode;
+    }
+    if (result.exitCode === -1) throw new LizardError("Exec stream ended without exit status");
+    return result;
+  }
+  async update(id, opts, controls = {}) {
+    const svc = await this.get(id);
+    let revision = controls.revision;
+    if (!controls.force && revision === void 0) {
+      const project = await this.client.get(`/api/projects/${svc.projectId}`);
+      revision = project.configRevision;
+    }
+    return this.client.applyConfig(svc.projectId, {
+      ...controls.force ? {} : { revision },
+      services: [{ name: svc.name, ...opts, id }]
+    });
+  }
+  events(id, buildId) {
+    return this.client.get(query(`/api/apps/${id}/deploy-events`, { buildId }));
+  }
+  pods(id) {
+    return this.client.get(`/api/apps/${id}/pod-status`);
+  }
+  history(id, opts = {}) {
+    return this.client.get(query(`/api/apps/${id}/logs/history`, opts));
+  }
+  streamLogs(id, signal) {
+    return this.client.events(`/api/apps/${id}/logs`, { signal });
+  }
+  buildLogs(buildId, signal) {
+    return this.client.events(`/api/builds/${buildId}/logs`, { signal });
+  }
+  /** Delete a service. */
+  delete(id) {
+    return this.client.delete(`/api/apps/${id}`);
+  }
+};
+
+// src/platform/github.ts
+var GitHubAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  status() {
+    return this.client.get("/api/github/status");
+  }
+  /** Complete the GitHub App installation in a browser using the caller's account. */
+  installUrl() {
+    return `${this.client.config.apiUrl}/api/auth/github/install`;
+  }
+  async checkout(serviceId, branch) {
+    const services = new ServicesAPI(this.client);
+    await services.update(serviceId, { branch });
+    return services.redeploy(serviceId);
+  }
+};
+
 // src/project.ts
+import { createHash } from "crypto";
 var projectIdCache = /* @__PURE__ */ new Map();
 async function resolveProjectId(ref, config) {
-  const cacheKey = `${config.apiUrl}\0${ref}`;
+  const cacheKey = `${config.apiUrl}\0${createHash("sha256").update(config.apiKey).digest("hex")}\0${ref}`;
   const cached = projectIdCache.get(cacheKey);
   if (cached) return cached;
   const res = await fetch(`${config.apiUrl}/api/projects`, { headers: config.headers });
   if (!res.ok) await handleApiError(res);
   const projects = await res.json();
   const lower = ref.toLowerCase();
-  const match = projects.find(
+  const matches = projects.filter(
     (p) => p.id.toLowerCase() === lower || p.slug?.toLowerCase() === lower || p.name?.toLowerCase() === lower
   );
+  if (matches.length > 1) throw new LizardError("Project reference is ambiguous; pass the project ID");
+  const match = matches[0];
   if (!match) {
     const available = projects.map((p) => p.slug || p.id).join(", ") || "(none)";
     throw new LizardError(
@@ -103,12 +450,12 @@ var Process = class {
     this.config = config;
   }
   /**
-   * Execute a command inside the microVM and wait for it to complete.
+   * Execute a command inside the sandbox 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 cmd Shell command to run inside the sandbox.
    * @param opts Optional execution options — environment variables, working
    *   directory, user, and timeout.
    *
@@ -240,22 +587,23 @@ var Fs = class {
     this.config = config;
   }
   /**
-   * Write a file into the microVM filesystem.
+   * Write a file into the sandbox filesystem.
    *
    * Creates parent directories automatically if they don't exist.
+   * Byte input must contain valid UTF-8; arbitrary binary uploads are unsupported.
    *
    * @example
    * ```ts
    * await sandbox.fs.write('/app/index.js', 'console.log("hello")')
    * ```
    *
-   * @example Write binary data:
+   * @example Write UTF-8 bytes:
    * ```ts
-   * await sandbox.fs.write('/app/data.bin', buffer)
+   * await sandbox.fs.write('/app/notes.txt', new TextEncoder().encode('hello'))
    * ```
    */
   async write(path, data, opts) {
-    const content = typeof data === "string" ? data : new TextDecoder().decode(data);
+    const content = typeof data === "string" ? data : new TextDecoder("utf-8", { fatal: true }).decode(data);
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`, {
       method: "POST",
       headers: this.config.headers,
@@ -264,7 +612,7 @@ var Fs = class {
     if (!res.ok) await handleApiError(res);
   }
   /**
-   * Read a file from the microVM filesystem.
+   * Read a file from the sandbox filesystem.
    *
    * @returns The file contents as a UTF-8 string.
    *
@@ -281,8 +629,17 @@ var Fs = class {
     if (!res.ok) await handleApiError(res);
     return res.text();
   }
+  /** Read a file as bytes. */
+  async readBytes(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, { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return new Uint8Array(await res.arrayBuffer());
+  }
   /**
-   * List files and directories at the given path inside the microVM.
+   * List files and directories at the given path inside the sandbox.
    *
    * @example
    * ```ts
@@ -298,7 +655,7 @@ var Fs = class {
     return res.json();
   }
   /**
-   * Remove a file or directory from the microVM filesystem.
+   * Remove a file or directory from the sandbox filesystem.
    */
   async remove(path, opts) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files`, {
@@ -309,7 +666,7 @@ var Fs = class {
     if (!res.ok) await handleApiError(res);
   }
   /**
-   * Create a directory (and any missing parents) inside the microVM.
+   * Create a directory (and any missing parents) inside the sandbox.
    */
   async makeDir(path, opts) {
     await this.execInternal(`mkdir -p ${JSON.stringify(path)}`, opts?.user);
@@ -480,7 +837,8 @@ var SandboxClient = class {
   }
   static async listSandboxes(opts) {
     const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/sandboxes`, {
+    const path = opts?.projectId ? `/api/projects/${encodeURIComponent(opts.projectId)}/sandboxes` : "/api/sandboxes";
+    const res = await fetch(`${config.apiUrl}${path}`, {
       headers: config.headers
     });
     if (!res.ok) await handleApiError(res);
@@ -536,11 +894,7 @@ var Sandbox = class extends SandboxClient {
    * Verifies the sandbox exists and is reachable, then returns a handle to it.
    * Throws `NotFoundError` if it has been killed or has expired.
    *
-   * This used to call `resume` first, on the assumption that a sandbox you are
-   * reconnecting to might be paused. Sandboxes are pods now and pause/resume is a
-   * `501` on every one of them, so that call turned every `connect()` into an
-   * error against a perfectly healthy sandbox. Connecting does not need to change
-   * a sandbox's state, so it no longer tries to.
+   * Connecting reads sandbox metadata without changing its state.
    *
    * @example
    * ```ts
@@ -565,29 +919,25 @@ var Sandbox = class extends SandboxClient {
   /**
    * Kill the sandbox and release its resources immediately.
    *
-   * @returns `true` if the microVM was terminated, `false` if it was already gone.
+   * @returns `true` if the sandbox was terminated, `false` if it was already gone.
    */
   async kill(opts) {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Pause the sandbox by freezing it in place.
+   * Request sandbox pause. The Kubernetes backend returns HTTP 501.
    *
-   * @deprecated Not implemented for the current runtime — always throws
-   * `LizardError` with HTTP 501. Sandboxes run as pods, and the equivalent is a CRIU
-   * checkpoint of the pod, which is not built. To park work across a gap, put it on a
-   * {@link Volume} and create a fresh sandbox on that volume later; the volume is the
-   * part that is meant to outlive a sandbox.
+   * @deprecated Unsupported on Kubernetes. Save files to a {@link Volume}
+   * and attach it to a new sandbox instead.
    */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Resume a paused sandbox.
+   * Request sandbox resume. The Kubernetes backend returns HTTP 501.
    *
-   * @deprecated Not implemented for the current runtime — always throws
-   * `LizardError` with HTTP 501. See {@link pause}. `Sandbox.connect()` no longer
-   * calls this, so reconnecting to a running sandbox works without it.
+   * @deprecated Unsupported on Kubernetes. Use {@link Sandbox.connect} to
+   * reconnect to a running sandbox.
    */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
@@ -607,102 +957,53 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.setTimeoutSandbox(this.sandboxId, timeoutMs, this.resolveOpts(opts));
   }
   /**
-   * Get the public HTTPS URL for a port exposed inside the sandbox.
+   * Register a public HTTPS route and return its hostname without a scheme.
    *
-   * Useful for accessing HTTP servers started inside the microVM from your
+   * Useful for accessing HTTP servers started inside the sandbox 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.{region}.onlizard.com
+   * // Start an HTTP server on port 3000 before exposing it.
+   * const hostname = await sandbox.getHost(3000)
+   * console.log(`https://${hostname}`)
    * ```
    */
   async getHost(port, opts) {
     const { hostname } = await SandboxClient.exposeSandboxPort(this.sandboxId, port, this.resolveOpts(opts));
     return hostname;
   }
-  resolveOpts(opts) {
-    return { ...this.connectionConfig, ...opts };
+  /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
+  fork(opts = {}) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/fork`, { count: opts.count ?? 1, timeoutMs: opts.timeoutMs ?? 0 });
   }
-};
-Sandbox.defaultTemplate = "base";
-Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
-
-// src/platform/client.ts
-var PlatformClient = class {
-  constructor(opts) {
-    this.config = new ConnectionConfig(opts);
+  /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
+  snapshot(name) {
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name });
   }
-  async get(path) {
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      headers: this.config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
+  unexpose(port) {
+    return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
   }
-  async post(path, body) {
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      method: "POST",
-      headers: this.config.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
+  logs(opts = {}) {
+    return new PlatformClient(this.resolveOpts()).events(query(`/api/sandboxes/${this.sandboxId}/logs`, { tail: opts.tail }), { signal: opts.signal });
   }
-  async patch(path, body) {
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      method: "PATCH",
-      headers: this.config.headers,
-      body: JSON.stringify(body)
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
+  static snapshots(projectId, opts) {
+    return new PlatformClient(opts ?? {}).get(`/api/projects/${projectId}/snapshots`);
   }
-  async delete(path, body) {
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      method: "DELETE",
-      headers: this.config.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0
-    });
-    if (!res.ok) await handleApiError(res);
-    if (res.status === 204 || res.headers.get("content-length") === "0") return void 0;
-    return res.json();
+  /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+  static async restore(snapshotId, opts) {
+    const result = await new PlatformClient(opts ?? {}).post(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}/fork`, { timeoutMs: opts?.timeoutMs ?? 0 });
+    return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });
   }
-  async postForm(path, form) {
-    const headers = { "X-API-Key": this.config.apiKey };
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      method: "POST",
-      headers,
-      body: form
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
+  static deleteSnapshot(snapshotId, opts) {
+    return new PlatformClient(opts ?? {}).delete(`/api/sandbox-snapshots/${encodeURIComponent(snapshotId)}`);
   }
-  /** Stream SSE events from a path, calling handler for each data line. */
-  async *streamSse(path) {
-    const res = await fetch(`${this.config.apiUrl}${path}`, {
-      headers: this.config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-    if (!res.body) return;
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    let buf = "";
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buf += decoder.decode(value, { stream: true });
-      const events = buf.split("\n\n");
-      buf = events.pop();
-      for (const evt of events) {
-        const dataLine = evt.split("\n").find((l) => l.startsWith("data: "));
-        if (dataLine) yield dataLine.slice(6);
-      }
-    }
+  resolveOpts(opts) {
+    return { ...this.connectionConfig, ...opts };
   }
 };
+Sandbox.defaultTemplate = "base";
+Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
 
 // src/platform/projects.ts
 var ProjectsAPI = class {
@@ -730,134 +1031,20 @@ var ProjectsAPI = class {
   delete(id) {
     return this.client.delete(`/api/projects/${id}`);
   }
-};
-
-// src/platform/services.ts
-var DeployHandle = class {
-  constructor(client, serviceId, buildId) {
-    this._client = client;
-    this._serviceId = serviceId;
-    this._buildId = buildId;
-  }
-  get serviceId() {
-    return this._serviceId;
+  apply(id, config) {
+    return this.client.applyConfig(id, config);
   }
-  /** Stream build + runtime log lines until the deploy finishes. */
-  async *logs() {
-    const path = `/api/apps/${this._serviceId}/logs?limit=1000`;
-    const res = await fetch(`${this._client.config.apiUrl}${path}`, {
-      headers: this._client.config.headers
-    });
-    if (!res.ok) return;
-    const body = await res.json();
-    const lines = Array.isArray(body) ? body : body.logs ?? [];
-    for (const l of lines) yield typeof l === "string" ? l : JSON.stringify(l);
-  }
-  /**
-   * Poll until the deploy reaches a terminal state.
-   * @returns `{ url, status }` on success; throws `LizardError` on failure.
-   */
-  async wait(opts) {
-    const deadline = Date.now() + (opts?.timeoutMs ?? 10 * 6e4);
-    const pollMs = opts?.pollMs ?? 3e3;
-    while (Date.now() < deadline) {
-      const svc = await this._client.get(`/api/apps/${this._serviceId}`);
-      if (svc.deployStatus === "idle") {
-        if (svc.status === "running") return { url: svc.domain ? `https://${svc.domain}` : null, status: "running" };
-        if (svc.status === "crashed") throw new LizardError(`Service crashed after deploy`);
-      }
-      if (svc.deployStatus === "failed") throw new LizardError(`Deploy failed`);
-      await new Promise((r) => setTimeout(r, pollMs));
-    }
-    throw new TimeoutError(`Deploy did not complete within ${opts?.timeoutMs ?? 6e5}ms`);
+  services(id) {
+    return this.client.get(`/api/projects/${id}/services`);
   }
-};
-var ServicesAPI = class {
-  constructor(client) {
-    this.client = client;
+  volumeLimits(id) {
+    return this.client.get(`/api/projects/${id}/volume-limits`);
   }
-  /** List all services in a project. */
-  list(opts) {
-    return this.client.get(`/api/projects/${opts.projectId}/apps`);
+  logs(id, opts = {}) {
+    return this.client.get(query(`/api/projects/${id}/logs`, opts));
   }
-  /** Get a service by ID. */
-  get(id) {
-    return this.client.get(`/api/apps/${id}`);
-  }
-  /**
-   * Create a service and start a deploy from a git repo.
-   * Returns a DeployHandle to track progress.
-   */
-  async deploy(opts) {
-    const body = {
-      name: opts.name,
-      sourceType: opts.sourceType ?? "github",
-      repoUrl: opts.repoUrl,
-      branch: opts.branch ?? "main",
-      startCommand: opts.startCommand,
-      buildCommand: opts.buildCommand,
-      containerPort: opts.port ?? opts.containerPort,
-      region: opts.region
-    };
-    const svc = await this.client.post(`/api/projects/${opts.projectId}/apps`, body);
-    return new DeployHandle(this.client, svc.id);
-  }
-  /**
-   * Upload a tarball and deploy it.
-   *
-   * @param opts.source - A `Buffer`, `Blob`, or `Uint8Array` of a `.tar.gz` file.
-   */
-  async upload(opts) {
-    const form = new FormData();
-    const blob = opts.source instanceof Blob ? opts.source : new Blob([opts.source], { type: "application/gzip" });
-    form.append("file", blob, "source.tar.gz");
-    form.append("name", opts.name);
-    if (opts.startCommand) form.append("startCommand", opts.startCommand);
-    if (opts.buildCommand) form.append("buildCommand", opts.buildCommand);
-    if (opts.port !== void 0) form.append("containerPort", String(opts.port));
-    if (opts.region) form.append("region", opts.region);
-    const result = await this.client.postForm(
-      `/api/projects/${opts.projectId}/apps/upload`,
-      form
-    );
-    return new DeployHandle(this.client, result.id, result.buildId);
-  }
-  /** Trigger a redeploy (rebuild from current source). */
-  async redeploy(id) {
-    await this.client.post(`/api/apps/${id}/redeploy`, {});
-    return new DeployHandle(this.client, id);
-  }
-  /** Restart a service without rebuilding. */
-  restart(id) {
-    return this.client.post(`/api/apps/${id}/restart`, {});
-  }
-  /** Scale a service. */
-  scale(id, opts) {
-    return this.client.post(`/api/apps/${id}/scale`, opts);
-  }
-  /**
-   * Get recent log lines. For a live tail, use the WebSocket API instead.
-   *
-   * @param opts.limit - Max lines to return (default 200, max 1000).
-   */
-  async logs(id, opts) {
-    const qs = new URLSearchParams();
-    if (opts?.limit) qs.set("limit", String(opts.limit));
-    if (opts?.since) qs.set("since", opts.since);
-    const result = await this.client.get(`/api/apps/${id}/logs?${qs}`);
-    return Array.isArray(result) ? result : result.logs ?? [];
-  }
-  /** Execute a command inside the running service container. */
-  exec(id, cmd, opts) {
-    return this.client.post(`/api/apps/${id}/exec`, { cmd, timeoutMs: opts?.timeoutMs });
-  }
-  /** Update service configuration. */
-  update(id, opts) {
-    return this.client.patch(`/api/apps/${id}`, opts);
-  }
-  /** Delete a service. */
-  delete(id) {
-    return this.client.delete(`/api/apps/${id}`);
+  streamLogs(id, signal) {
+    return this.client.events(`/api/projects/${id}/logs/stream`, { signal });
   }
 };
 
@@ -872,7 +1059,11 @@ var AddonsAPI = class {
   }
   /** Get an addon by ID. */
   get(projectId, addonId) {
-    return this.client.get(`/api/projects/${projectId}/addons/${addonId}`);
+    return this.list({ projectId }).then((items) => {
+      const addon = items.find((a) => a.id === addonId);
+      if (!addon) throw new Error("Addon not found");
+      return addon;
+    });
   }
   /**
    * Create a new managed addon (database, cache, or object store).
@@ -886,12 +1077,15 @@ var AddonsAPI = class {
    */
   create(opts) {
     return this.client.post(`/api/projects/${opts.projectId}/addons`, {
-      type: opts.type,
+      type: opts.type === "mongodb" ? "mongo" : opts.type,
       name: opts.name,
-      version: opts.version,
-      vcpu: opts.vcpu,
-      memoryMb: opts.memoryMb,
-      storageGb: opts.storageGb
+      region: opts.region,
+      config: {
+        version: opts.version,
+        cpuLimit: opts.vcpu === void 0 ? void 0 : `${opts.vcpu * 1e3}m`,
+        memoryLimit: opts.memoryMb === void 0 ? void 0 : `${opts.memoryMb}Mi`,
+        storageSize: opts.storageGb === void 0 ? void 0 : `${opts.storageGb}Gi`
+      }
     });
   }
   /** Delete an addon. */
@@ -899,13 +1093,29 @@ var AddonsAPI = class {
     return this.client.delete(`/api/projects/${projectId}/addons/${addonId}`);
   }
   /** Resize an addon (CPU / memory / storage). */
-  resize(projectId, addonId, opts) {
-    return this.client.post(`/api/projects/${projectId}/addons/${addonId}/resize`, opts);
+  async resize(projectId, addonId, opts) {
+    await this.client.applyConfig(projectId, {
+      addons: [{
+        id: addonId,
+        limits: { vcpu: opts.vcpu, memoryMb: opts.memoryMb },
+        storageSize: opts.storageGb === void 0 ? void 0 : `${opts.storageGb}Gi`
+      }]
+    });
+    return this.get(projectId, addonId);
   }
-  /** Restart an addon VM. */
+  /** Restart an addon. */
   redeploy(projectId, addonId) {
     return this.client.post(`/api/projects/${projectId}/addons/${addonId}/redeploy`, {});
   }
+  rename(projectId, addonId, name) {
+    return this.client.patch(`/api/projects/${projectId}/addons/${addonId}`, { name });
+  }
+  secrets(projectId, addonId) {
+    return this.client.get(`/api/projects/${projectId}/addons/${addonId}/secrets`);
+  }
+  logs(projectId, addonId) {
+    return this.client.get(`/api/projects/${projectId}/addons/${addonId}/logs`);
+  }
 };
 
 // src/platform/secrets.ts
@@ -948,22 +1158,25 @@ var SecretsAPI = class {
         byService.get(s.serviceId)[s.key] = s.value;
       }
     }
-    const tasks = [];
-    if (Object.keys(projectScoped).length > 0) {
-      tasks.push(this.client.post(`/api/projects/${projectId}/secrets`, projectScoped));
+    const services = {};
+    for (const [id, values] of byService) {
+      const svc = await this.client.get(`/api/apps/${id}`);
+      if (svc.projectId !== projectId) throw new Error("Service does not belong to this project");
+      services[svc.name] = values;
     }
-    for (const [serviceId, kv] of byService) {
-      tasks.push(this.client.post(`/api/apps/${serviceId}/secrets`, kv));
-    }
-    await Promise.all(tasks);
+    await this.client.applyConfig(projectId, { secrets: { shared: projectScoped, services } });
   }
-  /** Delete a secret by key. */
   async delete(projectId, opts) {
+    const secrets = {};
     if (opts.serviceId) {
-      await this.client.delete(`/api/apps/${opts.serviceId}/secrets`, { key: opts.key });
-    } else {
-      await this.client.delete(`/api/projects/${projectId}/secrets`, { key: opts.key });
-    }
+      const svc = await this.client.get(`/api/apps/${opts.serviceId}`);
+      if (svc.projectId !== projectId) throw new Error("Service does not belong to this project");
+      secrets.services = { [svc.name]: { [opts.key]: null } };
+    } else secrets.shared = { [opts.key]: null };
+    await this.client.applyConfig(projectId, { secrets });
+  }
+  refs(projectId, serviceId) {
+    return this.client.get(serviceId ? `/api/apps/${serviceId}/variables:refs` : `/api/projects/${projectId}/variables:refs`);
   }
 };
 
@@ -976,7 +1189,14 @@ var DomainsAPI = class {
    * Show the current domain(s) for a service.
    * The platform-assigned `.onlizard.com` subdomain is always present.
    */
-  list(serviceId) {
+  async list(serviceId) {
+    const result = await this.info(serviceId);
+    return [
+      ...result.domains.map((domain) => ({ domain, verified: true, live: result.dnsOk?.[domain], cnameTarget: result.cnameTarget })),
+      ...result.pending.map((item) => ({ ...item, domain: item.hostname, verified: false }))
+    ];
+  }
+  info(serviceId) {
     return this.client.get(`/api/apps/${serviceId}/domains`);
   }
   /**
@@ -989,15 +1209,23 @@ var DomainsAPI = class {
    * console.log('Add CNAME:', info.cnameTarget)
    * ```
    */
-  add(serviceId, domain) {
-    return this.client.post(`/api/apps/${serviceId}/domains`, { domain });
+  async add(serviceId, domain, opts = {}) {
+    const result = await this.client.post(`/api/apps/${serviceId}/domains`, { hostname: domain, ...opts });
+    return { ...result, domain: result.hostname ?? domain };
   }
   /**
    * Verify that DNS records have propagated and activate the domain.
    * Call after adding the CNAME or TXT record returned by `add()`.
    */
-  verify(serviceId, domain) {
-    return this.client.post(`/api/apps/${serviceId}/domains/verify`, { domain });
+  async verify(serviceId, domain) {
+    const result = await this.client.post(`/api/apps/${serviceId}/domains/verify`, { hostname: domain });
+    return { ...result, domain: result.hostname ?? domain };
+  }
+  generate(serviceId) {
+    return this.client.post(`/api/apps/${serviceId}/domains`, { generate: true });
+  }
+  delete(serviceId, hostname) {
+    return this.client.delete(`/api/apps/${serviceId}/domains/${segment(hostname)}`);
   }
 };
 
@@ -1006,40 +1234,42 @@ var MetricsAPI = class {
   constructor(client) {
     this.client = client;
   }
-  /** Get CPU metrics for a service or addon. */
-  cpu(id, range = "1h") {
-    return this.client.get(`/api/apps/${id}/metrics/cpu?range=${range}`);
+  service(id, range = "1h") {
+    return this.client.get(`/api/apps/${id}/metrics?range=${range}`);
   }
-  /** Get memory metrics for a service or addon. */
-  memory(id, range = "1h") {
-    return this.client.get(`/api/apps/${id}/metrics/memory?range=${range}`);
+  addon(projectId, addonId, range = "1h") {
+    return this.client.get(`/api/projects/${projectId}/addons/${addonId}/metrics?range=${range}`);
   }
-  /** Get network I/O metrics for a service. */
-  network(id, range = "1h") {
-    return this.client.get(`/api/apps/${id}/metrics/network?range=${range}`);
+  project(id, opts = {}) {
+    return this.client.get(query(`/api/projects/${id}/metrics`, opts));
   }
-  /** Get disk I/O metrics for a service. */
-  disk(id, range = "1h") {
-    return this.client.get(`/api/apps/${id}/metrics/disk?range=${range}`);
+  points(raw, name) {
+    const series = raw.series.find((s) => s.metric === name);
+    return (series?.values ?? []).flatMap((value, i) => series?.available?.[i] === false ? [] : [{ t: raw.timestamps[i], value }]);
   }
-  /**
-   * Get cost breakdown for a project over the given range.
-   * Costs are in USD cents unless the `currency` field says otherwise.
-   */
-  cost(projectId, range = "30d") {
-    return this.client.get(`/api/projects/${projectId}/metrics/cost?range=${range}`);
+  async cpu(id, range = "1h") {
+    return this.points(await this.service(id, range), "cpu");
+  }
+  async memory(id, range = "1h") {
+    return this.points(await this.service(id, range), "memory");
+  }
+  async network(id, range = "1h") {
+    const raw = await this.service(id, range);
+    return { rx: this.points(raw, "network_rx"), tx: this.points(raw, "network_tx") };
+  }
+  async disk(id, range = "1h") {
+    const raw = await this.service(id, range);
+    return { read: this.points(raw, "disk_read"), write: this.points(raw, "disk_write") };
   }
-  /**
-   * Convenience: fetch all metric types for a service in one call.
-   */
   async all(id, range = "1h") {
-    const [cpu, memory, network, disk] = await Promise.all([
-      this.cpu(id, range),
-      this.memory(id, range),
-      this.network(id, range),
-      this.disk(id, range)
-    ]);
-    return { cpu, memory, networkRx: network.rx, networkTx: network.tx, diskRead: disk.read, diskWrite: disk.write };
+    const raw = await this.service(id, range);
+    return { cpu: this.points(raw, "cpu"), memory: this.points(raw, "memory"), networkRx: this.points(raw, "network_rx"), networkTx: this.points(raw, "network_tx"), diskRead: this.points(raw, "disk_read"), diskWrite: this.points(raw, "disk_write") };
+  }
+  /** Return the backend's project cost row in USD, without guessing missing totals. */
+  async cost(projectId, range = "30d") {
+    const project = await this.client.get(`/api/projects/${projectId}`);
+    const summary = await this.client.get(query("/api/billing/summary", { workspaceId: project.workspaceId, range }));
+    return summary.projects.find((p) => p.projectId === projectId) ?? null;
   }
 };
 
@@ -1124,6 +1354,71 @@ var RegionsAPI = class {
   }
 };
 
+// src/cli.ts
+import { spawn } from "child_process";
+var LizardCLI = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  run(args, opts = {}) {
+    return new Promise((resolve, reject) => {
+      const env = { ...process.env };
+      if (this.opts.apiKey) {
+        env.LIZARD_API_KEY = this.opts.apiKey;
+        env.LIZARD_TOKEN = this.opts.apiKey;
+      }
+      if (this.opts.apiUrl) env.LIZARD_API_URL = this.opts.apiUrl;
+      const child = spawn(this.opts.executable ?? "lizard", ["--json", ...args], {
+        cwd: this.opts.cwd,
+        env,
+        shell: false,
+        stdio: "pipe",
+        signal: opts.signal,
+        timeout: this.opts.timeoutMs ?? 6e5
+      });
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      let stdout = "", stderr = "", bytes = 0;
+      const collect = (stream, data) => {
+        bytes += Buffer.byteLength(data);
+        if (bytes > 16 * 1024 * 1024) {
+          child.kill();
+          reject(new Error("CLI output exceeds 16 MiB"));
+          return;
+        }
+        if (stream === "stdout") stdout += data;
+        else stderr += data;
+      };
+      child.stdout.on("data", (data) => collect("stdout", data));
+      child.stderr.on("data", (data) => collect("stderr", data));
+      child.on("error", reject);
+      child.on("close", (code, signal) => {
+        if (signal) {
+          reject(new Error(`CLI ended with signal ${signal}`));
+          return;
+        }
+        let events = [];
+        try {
+          events = [JSON.parse(stdout)];
+        } catch {
+          events = stdout.split("\n").filter(Boolean).flatMap((line) => {
+            try {
+              return [JSON.parse(line)];
+            } catch {
+              return [];
+            }
+          });
+        }
+        resolve({ code: code ?? 1, stdout, stderr, events });
+      });
+      child.stdin.on("error", (error) => {
+        if (error.code !== "EPIPE") reject(error);
+      });
+      child.stdin.end(opts.stdin);
+    });
+  }
+};
+
 // src/platform/billing.ts
 var BillingAPI = class {
   constructor(client) {
@@ -1150,6 +1445,46 @@ var BillingAPI = class {
   live() {
     return this.client.get("/api/billing/live");
   }
+  paymentMethods() {
+    return this.client.get("/api/billing/payment-methods");
+  }
+  setupPaymentMethod(returnUrl) {
+    return this.client.post("/api/billing/payment-methods/setup", { returnUrl });
+  }
+  removePaymentMethod(id) {
+    return this.client.delete(`/api/billing/payment-methods/${encodeURIComponent(id)}`);
+  }
+  purchase(creditCents, opts = {}) {
+    if (!Number.isSafeInteger(creditCents) || creditCents <= 0) throw new Error("creditCents must be a positive integer");
+    return this.client.post("/api/billing/purchase", { creditCents, paymentMethod: opts.paymentMethod ?? "card", returnUrl: opts.returnUrl });
+  }
+  autoTopup() {
+    return this.client.get("/api/billing/auto-topup");
+  }
+  setAutoTopup(opts) {
+    return this.client.put("/api/billing/auto-topup", opts);
+  }
+  runAutoTopup() {
+    return this.client.post("/api/billing/auto-topup/run", {});
+  }
+  redeemPromo(code) {
+    return this.client.post("/api/billing/promo/redeem", { code });
+  }
+  x402Quote(creditCents) {
+    return this.client.post("/api/billing/purchase/x402/quote", { creditCents });
+  }
+  paymentStatus(attemptId) {
+    return this.client.get(`/api/billing/purchase/x402/${encodeURIComponent(attemptId)}`);
+  }
+  /** Pay with the CLI's durable x402 journal. Requires CLI >= 4.0.8. Amounts are cents. */
+  async payX402(creditCents, opts) {
+    if (![creditCents, opts.maxTotalCents].every((n) => Number.isSafeInteger(n) && n > 0)) throw new Error("Payment amounts must be positive integer cents");
+    const args = ["credits", "topup", (creditCents / 100).toFixed(2), "--method", "x402", "--max-total", (opts.maxTotalCents / 100).toFixed(2), "--yes"];
+    if (opts.requestId) args.push("--request-id", opts.requestId);
+    const result = await new LizardCLI({ apiKey: this.client.config.apiKey, apiUrl: this.client.config.apiUrl, executable: opts.executable }).run(args);
+    if (result.code !== 0) throw new Error(`x402 CLI exited with code ${result.code}; inspect the payment journal or query paymentStatus before retrying`);
+    return result.events[0];
+  }
 };
 
 // src/volume/index.ts
@@ -1276,6 +1611,8 @@ var Lizard = class {
     this.secrets = new SecretsAPI(platform);
     this.domains = new DomainsAPI(platform);
     this.metrics = new MetricsAPI(platform);
+    this.storage = new StorageAPI(platform);
+    this.github = new GitHubAPI(platform);
   }
   // ── Sandbox convenience methods (backward-compatible) ──────────────────
   /** Resolve the client's project reference to a stable project ID (cached). */
@@ -1368,8 +1705,7 @@ var CodeSandbox = class extends Sandbox {
    *
    * @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.
+   * Code errors appear in `execution.error`; request failures throw.
    *
    * @example
    * ```ts
@@ -1519,10 +1855,13 @@ export {
   AuthenticationError,
   BillingAPI,
   CodeSandbox,
+  ConfigApplyError,
   ConflictError,
   DeployHandle,
   DomainsAPI,
+  GitHubAPI,
   Lizard,
+  LizardCLI,
   LizardError,
   MetricsAPI,
   NotFoundError,
@@ -1532,6 +1871,7 @@ export {
   Sandbox,
   SecretsAPI,
   ServicesAPI,
+  StorageAPI,
   TimeoutError,
   Volume,
   WorkspacesAPI,