@lizard-build/sdk 0.1.39 → 0.1.41

package/dist/index.d.ts

@@ -8,10 +8,383 @@ declare class ConnectionConfig {
     readonly apiKey: string;
     readonly apiUrl: string;
     readonly timeoutMs: number;
+    readonly requestTimeoutMs: number;
     constructor(opts?: ConnectionOpts);
     get headers(): Record<string, string>;
 }
 
+interface StreamEvent {
+    event: string;
+    data: string;
+    id?: string;
+}
+/** HTTP transport. Calls never retry mutations or payments. */
+declare class PlatformClient {
+    readonly config: ConnectionConfig;
+    constructor(opts: ConnectionOpts);
+    private json;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T = void>(path: string, body?: unknown): Promise<T>;
+    applyConfig<T>(projectId: string, body: unknown): Promise<T>;
+    sendBytes<T>(method: string, path: string, body: Blob | Uint8Array | string, contentType?: string): Promise<T>;
+    postForm<T>(path: string, form: FormData): Promise<T>;
+    /** Preserves named events, multiline data and UTF-8 split across chunks. */
+    events(path: string, opts?: {
+        method?: string;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): AsyncGenerator<StreamEvent>;
+    streamSse(path: string): AsyncGenerator<string>;
+}
+
+declare class StorageAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    list(projectId: string, addonId: string, opts?: {
+        bucket?: string;
+        prefix?: string;
+    }): Promise<unknown>;
+    upload(projectId: string, addonId: string, opts: {
+        key: string;
+        source: Blob | Uint8Array | string;
+        bucket?: string;
+        contentType?: string;
+    }): Promise<{
+        key: string;
+        etag: string;
+        size: number;
+        url: string | null;
+    }>;
+}
+
+type AddonType = 'postgres' | 'mysql' | 'mongodb' | 'mongo' | 'redis' | 's3';
+interface Addon {
+    id: string;
+    name: string;
+    type: AddonType;
+    projectId: string;
+    status: 'none' | 'running' | 'crashed' | 'stopped';
+    deployStatus: string;
+    version?: string;
+    /** Exposed connection variables (e.g. DATABASE_URL, REDIS_URL). */
+    env?: Record<string, string>;
+}
+interface CreateAddonOpts {
+    projectId: string;
+    type: AddonType;
+    name?: string;
+    version?: string;
+    region?: string;
+    /** vCPU count */
+    vcpu?: number;
+    /** Memory in MB */
+    memoryMb?: number;
+    /** Storage in GB */
+    storageGb?: number;
+}
+declare class AddonsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all addons in a project. */
+    list(opts: {
+        projectId: string;
+    }): Promise<Addon[]>;
+    /** Get an addon by ID. */
+    get(projectId: string, addonId: string): Promise<Addon>;
+    /**
+     * Create a new managed addon (database, cache, or object store).
+     *
+     * @example
+     * ```ts
+     * const pg = await lizard.addons.create({ projectId, type: 'postgres' })
+     * // Inject into a service:
+     * await lizard.secrets.set({ serviceId: svcId, key: 'DATABASE_URL', value: `${{${pg.name}.DATABASE_URL}}` })
+     * ```
+     */
+    create(opts: CreateAddonOpts): Promise<Addon>;
+    /** Delete an addon. */
+    delete(projectId: string, addonId: string): Promise<void>;
+    /** Resize an addon (CPU / memory / storage). */
+    resize(projectId: string, addonId: string, opts: {
+        vcpu?: number;
+        memoryMb?: number;
+        storageGb?: number;
+    }): Promise<Addon>;
+    /** Restart an addon. */
+    redeploy(projectId: string, addonId: string): Promise<void>;
+    rename(projectId: string, addonId: string, name: string): Promise<unknown>;
+    secrets(projectId: string, addonId: string): Promise<Array<{
+        key: string;
+        value: string;
+    }>>;
+    logs(projectId: string, addonId: string): Promise<unknown>;
+}
+
+interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    workspaceId: string;
+    createdAt?: string;
+}
+interface CreateProjectOpts {
+    workspaceId: string;
+    name: string;
+}
+declare class ProjectsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all projects the API key can access. */
+    list(opts?: {
+        workspaceId?: string;
+    }): Promise<Project[]>;
+    /** Get a project by ID. */
+    get(id: string): Promise<Project>;
+    /** Create a new project. */
+    create(opts: CreateProjectOpts): Promise<Project>;
+    /** Update a project's name. */
+    update(id: string, opts: {
+        name?: string;
+    }): Promise<Project>;
+    /** Delete a project. */
+    delete(id: string): Promise<void>;
+    apply(id: string, config: ProjectConfig): Promise<ConfigResult>;
+    services(id: string): Promise<{
+        apps: Service[];
+        addons: Addon[];
+    }>;
+    volumeLimits(id: string): Promise<Record<string, unknown>>;
+    logs(id: string, opts?: {
+        service?: string;
+        level?: string;
+        limit?: number;
+        since?: string;
+        until?: string;
+    }): Promise<LogLine[]>;
+    streamLogs(id: string, signal?: AbortSignal): AsyncGenerator<StreamEvent, any, any>;
+}
+interface ProjectConfig {
+    revision?: number;
+    services?: Array<ServiceUpdate & {
+        id?: string;
+        name?: string;
+    }>;
+    addons?: Array<{
+        id?: string;
+        name?: string;
+        instanceName?: string;
+        type?: string;
+        limits?: {
+            vcpu?: number;
+            memoryMb?: number;
+        };
+        storageSize?: string;
+        config?: Record<string, unknown>;
+    }>;
+    secrets?: {
+        shared?: Record<string, string | null>;
+        services?: Record<string, Record<string, string | null>>;
+    };
+}
+interface ConfigResult {
+    revision: number;
+    services: unknown[];
+    addons: unknown[];
+    sideEffectFailures?: unknown[];
+}
+
+interface Service {
+    id: string;
+    name: string;
+    projectId: string;
+    status: 'none' | 'running' | 'crashed' | 'stopped';
+    deployStatus: 'idle' | 'building' | 'deploying' | 'restarting' | 'failed' | 'deleting';
+    domain?: string;
+    region?: string;
+    sourceType?: 'github' | 'upload' | 'docker';
+    repoUrl?: string;
+    branch?: string;
+    startCommand?: string;
+    buildCommand?: string;
+    containerPort?: number;
+}
+interface CreateServiceOpts {
+    projectId: string;
+    name: string;
+    sourceType?: 'github' | 'upload' | 'docker';
+    repoUrl?: string;
+    branch?: string;
+    startCommand?: string;
+    buildCommand?: string;
+    containerPort?: number;
+    region?: string;
+    preDeployCommand?: string;
+    dockerfilePath?: string;
+    rootDirectory?: string;
+    envVars?: Record<string, string>;
+    skipInitialDeploy?: boolean;
+    cpuLimit?: string;
+    memoryLimit?: string;
+    /** Set to 0 for worker mode (no HTTP listener). */
+    port?: number;
+}
+interface ScaleOpts {
+    replicas?: number;
+    cpuMillis?: number;
+    memoryMi?: number;
+    storageMi?: number;
+}
+interface LogLine {
+    level: 'info' | 'error' | 'warn' | 'debug';
+    message: string;
+    ts: number;
+    service?: string;
+    replica?: string;
+}
+interface DeployEvent {
+    event: 'log' | 'done' | 'error' | 'deployed' | 'failed' | 'deploying';
+    line?: string;
+    message?: string;
+    status?: string;
+    url?: string | null;
+}
+/**
+ * Handle for a running deploy — stream its logs or await completion.
+ *
+ * @example
+ * ```ts
+ * const deploy = await lizard.services.upload({ projectId, source: fs.readFileSync('app.tar.gz') })
+ * for await (const line of deploy.logs()) console.log(line)
+ * const result = await deploy.wait()
+ * console.log('deployed to', result.url)
+ * ```
+ */
+declare class DeployHandle {
+    private readonly _serviceId;
+    private readonly _buildId;
+    private readonly _client;
+    constructor(client: PlatformClient, serviceId: string, buildId?: string);
+    get serviceId(): string;
+    /** Stream build log messages until the server closes the build stream. */
+    logs(): AsyncGenerator<string>;
+    /**
+     * Poll until the deploy reaches a terminal state.
+     * @returns `{ url, status }` on success; throws `LizardError` on failure.
+     */
+    wait(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<{
+        url: string | null;
+        status: string;
+    }>;
+}
+declare class ServicesAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** List all services in a project. */
+    list(opts: {
+        projectId: string;
+    }): Promise<Service[]>;
+    /** Get a service by ID. */
+    get(id: string): Promise<Service>;
+    /**
+     * Create a service and start a deploy from a git repo.
+     * Returns a DeployHandle to track progress.
+     */
+    deploy(opts: CreateServiceOpts & {
+        waitForDeploy?: boolean;
+    }): Promise<DeployHandle>;
+    /**
+     * Upload a tarball and deploy it.
+     *
+     * @param opts.source - A `Buffer`, `Blob`, or `Uint8Array` of a `.tar.gz` file.
+     */
+    upload(opts: {
+        projectId: string;
+        name?: string;
+        serviceId?: string;
+        source: Blob | Uint8Array | string;
+        startCommand?: string;
+        buildCommand?: string;
+        preDeployCommand?: string;
+        port?: number;
+        region?: string;
+    }): Promise<DeployHandle>;
+    /** Trigger a redeploy (rebuild from current source). */
+    redeploy(id: string): Promise<DeployHandle>;
+    /** Restart a service without rebuilding. */
+    restart(id: string): Promise<void>;
+    /** Scale a service. */
+    scale(id: string, opts: ScaleOpts): Promise<void>;
+    /**
+     * Get recent log lines. For a live tail, use the WebSocket API instead.
+     *
+     * @param opts.limit - Max lines to return (default 200, max 1000).
+     */
+    logs(id: string, opts?: {
+        limit?: number;
+        since?: string;
+    }): Promise<LogLine[]>;
+    /** Execute a command; collect SSE output and require an exit event. */
+    exec(id: string, cmd: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    update(id: string, opts: ServiceUpdate, controls?: {
+        revision?: number;
+        force?: boolean;
+    }): Promise<ConfigResult>;
+    events(id: string, buildId?: string): Promise<unknown[]>;
+    pods(id: string): Promise<{
+        pods: unknown[];
+    }>;
+    history(id: string, opts?: {
+        limit?: number;
+        before?: string;
+        level?: string;
+    }): Promise<unknown>;
+    streamLogs(id: string, signal?: AbortSignal): AsyncGenerator<StreamEvent, any, any>;
+    buildLogs(buildId: string, signal?: AbortSignal): AsyncGenerator<StreamEvent, any, any>;
+    /** Delete a service. */
+    delete(id: string): Promise<void>;
+}
+interface ServiceUpdate {
+    name?: string;
+    branch?: string;
+    repoUrl?: string;
+    sourceType?: 'github' | 'upload' | 'docker';
+    buildCommand?: string | null;
+    startCommand?: string | null;
+    preDeployCommand?: string | null;
+    dockerfilePath?: string | null;
+    rootDirectory?: string | null;
+    watchPatterns?: string[];
+    containerPort?: number;
+    cpuLimit?: string;
+    memoryLimit?: string;
+    desiredReplicas?: number;
+    context?: string;
+    autoDeploy?: boolean;
+    vpnEnabled?: boolean;
+}
+
+declare class GitHubAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    status(): Promise<unknown>;
+    /** Complete the GitHub App installation in a browser using the caller's account. */
+    installUrl(): string;
+    checkout(serviceId: string, branch: string): Promise<DeployHandle>;
+}
+
 /** A process this sandbox is currently running. */
 interface ProcessInfo {
     pid: number;
@@ -22,7 +395,7 @@ interface ProcessInfo {
 /** Signals accepted by {@link Process.kill}. */
 type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
 /**
- * The result of a process execution inside a Lizard microVM.
+ * The result of a process execution inside a Lizard sandbox.
  */
 interface ProcessResult {
     stdout: string;
@@ -45,7 +418,7 @@ interface ProcessOpts {
     onPid?: (pid: number) => void;
 }
 /**
- * Runs processes inside a Lizard sandbox microVM.
+ * Runs processes inside a Lizard sandbox.
  *
  * Access via `sandbox.process`.
  */
@@ -54,12 +427,12 @@ declare class Process {
     private readonly config;
     constructor(sandboxId: string, config: ConnectionConfig);
     /**
-     * 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.
      *
@@ -138,7 +511,7 @@ interface FileInfo {
     modTime?: number;
 }
 /**
- * Read and write files inside a Lizard sandbox microVM.
+ * Read and write files inside a Lizard sandbox.
  *
  * Access via `sandbox.fs`.
  */
@@ -147,23 +520,24 @@ declare class Fs {
     private readonly config;
     constructor(sandboxId: string, config: ConnectionConfig);
     /**
-     * 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'))
      * ```
      */
     write(path: string, data: string | Uint8Array, opts?: FsOpts): Promise<void>;
     /**
-     * Read a file from the microVM filesystem.
+     * Read a file from the sandbox filesystem.
      *
      * @returns The file contents as a UTF-8 string.
      *
@@ -173,8 +547,10 @@ declare class Fs {
      * ```
      */
     read(path: string, opts?: FsOpts): Promise<string>;
+    /** Read a file as bytes. */
+    readBytes(path: string, opts?: FsOpts): Promise<Uint8Array>;
     /**
-     * List files and directories at the given path inside the microVM.
+     * List files and directories at the given path inside the sandbox.
      *
      * @example
      * ```ts
@@ -183,11 +559,11 @@ declare class Fs {
      */
     list(path: string, opts?: FsOpts): Promise<FileInfo[]>;
     /**
-     * Remove a file or directory from the microVM filesystem.
+     * Remove a file or directory from the sandbox filesystem.
      */
     remove(path: string, opts?: FsOpts): Promise<void>;
     /**
-     * Create a directory (and any missing parents) inside the microVM.
+     * Create a directory (and any missing parents) inside the sandbox.
      */
     makeDir(path: string, opts?: FsOpts): Promise<void>;
     /**
@@ -344,7 +720,9 @@ declare class SandboxClient {
     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 listSandboxes(opts?: ConnectionOpts & {
+        projectId?: string;
+    }): Promise<SandboxInfo[]>;
     protected static getSandboxInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     protected static setTimeoutSandbox(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     protected static exposeSandboxPort(sandboxId: string, port: number, opts?: ConnectionOpts): Promise<{
@@ -354,10 +732,9 @@ declare class SandboxClient {
 }
 
 /**
- * A Lizard sandbox — an isolated Linux environment that starts in under a second.
+ * A Linux sandbox running on Kubernetes.
  *
- * Each sandbox is a full Linux environment with its own filesystem, network, and
- * process namespace, restored from a pre-warmed template snapshot.
+ * Run commands, read and write files, and expose HTTP ports in a sandbox.
  *
  * Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards
  * everything written inside it. State that has to outlive a sandbox belongs on a
@@ -369,10 +746,14 @@ declare class SandboxClient {
  * import { Sandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await Sandbox.create('base', { project: 'my-project' })
- * 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()
+ * try {
+ *   await sandbox.fs.write('/tmp/hello.txt', 'hello world')
+ *   const result = await sandbox.process.exec('cat /tmp/hello.txt')
+ *   if (result.exitCode !== 0) throw new Error(result.stderr)
+ *   console.log(result.stdout)
+ * } finally {
+ *   await sandbox.kill()
+ * }
  * ```
  *
  * @example Carry work across sandboxes with a volume:
@@ -393,11 +774,11 @@ declare class Sandbox extends SandboxClient {
     protected static readonly defaultTemplate: string;
     protected static readonly defaultTimeoutMs: number;
     /**
-     * Unique identifier of this sandbox microVM.
+     * Unique identifier of this sandbox.
      */
     readonly sandboxId: string;
     /**
-     * Read and write files inside the microVM filesystem.
+     * Read and write files inside the sandbox filesystem.
      *
      * @example
      * ```ts
@@ -407,7 +788,7 @@ declare class Sandbox extends SandboxClient {
      */
     readonly fs: Fs;
     /**
-     * Execute processes inside the microVM.
+     * Execute processes inside the sandbox.
      *
      * @example
      * ```ts
@@ -431,16 +812,15 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 26) and `code-interpreter-v1`
-     * (Python 3.14 + Node.js 26). Custom templates can be built and pushed via
-     * `lizard push`.
+     * Template availability and installed tools depend on the platform and region.
+     * Use `base` for shell commands or `CodeSandbox` for stateful code execution.
      *
      * @param template Name of the sandbox template to boot from.
      *
      * @example
      * ```ts
      * const sandbox = await Sandbox.create('base', { project: 'my-project' })
-     * const sandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
+     * const pythonSandbox = await Sandbox.create('code-interpreter-v1', { project: 'my-project', timeoutMs: 10 * 60 * 1000 })
      * ```
      */
     static create(template: string, opts?: SandboxOpts): Promise<Sandbox>;
@@ -450,11 +830,7 @@ declare class Sandbox 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
@@ -470,29 +846,27 @@ declare class Sandbox extends SandboxClient {
      * const sandboxes = await Sandbox.list()
      * ```
      */
-    static list(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+    static list(opts?: ConnectionOpts & {
+        projectId?: string;
+    }): Promise<SandboxInfo[]>;
     /**
      * 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.
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * 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.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * 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.
      */
     resume(opts?: ConnectionOpts): Promise<boolean>;
     /**
@@ -506,257 +880,38 @@ declare class Sandbox extends SandboxClient {
      */
     setTimeout(timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /**
-     * 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}`)
      * ```
      */
     getHost(port: number, opts?: ConnectionOpts): Promise<string>;
-    private resolveOpts;
-}
-
-/** Shared HTTP helper for platform (non-sandbox) API calls. */
-declare class PlatformClient {
-    readonly config: ConnectionConfig;
-    constructor(opts: ConnectionOpts);
-    get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
-    patch<T>(path: string, body: unknown): Promise<T>;
-    delete<T = void>(path: string, body?: unknown): Promise<T>;
-    postForm<T>(path: string, form: FormData): Promise<T>;
-    /** Stream SSE events from a path, calling handler for each data line. */
-    streamSse(path: string): AsyncGenerator<string>;
-}
-
-interface Project {
-    id: string;
-    name: string;
-    slug: string;
-    workspaceId: string;
-    createdAt?: string;
-}
-interface CreateProjectOpts {
-    workspaceId: string;
-    name: string;
-}
-declare class ProjectsAPI {
-    private readonly client;
-    constructor(client: PlatformClient);
-    /** List all projects the API key can access. */
-    list(opts?: {
-        workspaceId?: string;
-    }): Promise<Project[]>;
-    /** Get a project by ID. */
-    get(id: string): Promise<Project>;
-    /** Create a new project. */
-    create(opts: CreateProjectOpts): Promise<Project>;
-    /** Update a project's name. */
-    update(id: string, opts: {
-        name?: string;
-    }): Promise<Project>;
-    /** Delete a project. */
-    delete(id: string): Promise<void>;
-}
-
-interface Service {
-    id: string;
-    name: string;
-    projectId: string;
-    status: 'none' | 'running' | 'crashed' | 'stopped';
-    deployStatus: 'idle' | 'building' | 'deploying' | 'restarting' | 'failed' | 'deleting';
-    domain?: string;
-    region?: string;
-    sourceType?: 'github' | 'upload';
-    repoUrl?: string;
-    branch?: string;
-    startCommand?: string;
-    buildCommand?: string;
-    containerPort?: number;
-}
-interface CreateServiceOpts {
-    projectId: string;
-    name: string;
-    sourceType?: 'github' | 'upload';
-    repoUrl?: string;
-    branch?: string;
-    startCommand?: string;
-    buildCommand?: string;
-    containerPort?: number;
-    region?: string;
-    /** Set to 0 for worker mode (no HTTP listener). */
-    port?: number;
-}
-interface ScaleOpts {
-    replicas?: number;
-    cpuMillis?: number;
-    memoryMi?: number;
-    storageMi?: number;
-}
-interface LogLine {
-    level: 'info' | 'error' | 'warn' | 'debug';
-    message: string;
-    ts: number;
-    service?: string;
-    replica?: string;
-}
-interface DeployEvent {
-    event: 'log' | 'done' | 'error' | 'deployed' | 'failed' | 'deploying';
-    line?: string;
-    message?: string;
-    status?: string;
-    url?: string | null;
-}
-/**
- * Handle for a running deploy — stream its logs or await completion.
- *
- * @example
- * ```ts
- * const deploy = await lizard.services.upload({ projectId, source: fs.readFileSync('app.tar.gz') })
- * for await (const line of deploy.logs()) console.log(line)
- * const result = await deploy.wait()
- * console.log('deployed to', result.url)
- * ```
- */
-declare class DeployHandle {
-    private readonly _serviceId;
-    private readonly _buildId;
-    private readonly _client;
-    constructor(client: PlatformClient, serviceId: string, buildId?: string);
-    get serviceId(): string;
-    /** Stream build + runtime log lines until the deploy finishes. */
-    logs(): AsyncGenerator<string>;
-    /**
-     * Poll until the deploy reaches a terminal state.
-     * @returns `{ url, status }` on success; throws `LizardError` on failure.
-     */
-    wait(opts?: {
+    /** Fork is unsupported on Kubernetes; the backend returns HTTP 501. */
+    fork(opts?: {
+        count?: number;
         timeoutMs?: number;
-        pollMs?: number;
-    }): Promise<{
-        url: string | null;
-        status: string;
-    }>;
-}
-declare class ServicesAPI {
-    private readonly client;
-    constructor(client: PlatformClient);
-    /** List all services in a project. */
-    list(opts: {
-        projectId: string;
-    }): Promise<Service[]>;
-    /** Get a service by ID. */
-    get(id: string): Promise<Service>;
-    /**
-     * Create a service and start a deploy from a git repo.
-     * Returns a DeployHandle to track progress.
-     */
-    deploy(opts: CreateServiceOpts & {
-        waitForDeploy?: boolean;
-    }): Promise<DeployHandle>;
-    /**
-     * Upload a tarball and deploy it.
-     *
-     * @param opts.source - A `Buffer`, `Blob`, or `Uint8Array` of a `.tar.gz` file.
-     */
-    upload(opts: {
-        projectId: string;
-        name: string;
-        source: Blob | string;
-        startCommand?: string;
-        buildCommand?: string;
-        port?: number;
-        region?: string;
-    }): Promise<DeployHandle>;
-    /** Trigger a redeploy (rebuild from current source). */
-    redeploy(id: string): Promise<DeployHandle>;
-    /** Restart a service without rebuilding. */
-    restart(id: string): Promise<void>;
-    /** Scale a service. */
-    scale(id: string, opts: ScaleOpts): Promise<void>;
-    /**
-     * Get recent log lines. For a live tail, use the WebSocket API instead.
-     *
-     * @param opts.limit - Max lines to return (default 200, max 1000).
-     */
-    logs(id: string, opts?: {
-        limit?: number;
-        since?: string;
-    }): Promise<LogLine[]>;
-    /** Execute a command inside the running service container. */
-    exec(id: string, cmd: string, opts?: {
+    }): Promise<unknown>;
+    /** Snapshot creation is unsupported on Kubernetes; the backend returns HTTP 501. */
+    snapshot(name?: string): Promise<unknown>;
+    unexpose(port: number): Promise<void>;
+    logs(opts?: {
+        tail?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<StreamEvent, any, any>;
+    static snapshots(projectId: string, opts?: ConnectionOpts): Promise<unknown[]>;
+    /** Snapshot restore is unsupported on Kubernetes; the backend returns HTTP 501. */
+    static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
-    }): Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    }>;
-    /** Update service configuration. */
-    update(id: string, opts: Partial<Pick<Service, 'name' | 'startCommand' | 'buildCommand' | 'containerPort' | 'repoUrl' | 'branch' | 'sourceType'>>): Promise<Service>;
-    /** Delete a service. */
-    delete(id: string): Promise<void>;
-}
-
-type AddonType = 'postgres' | 'mysql' | 'mongodb' | 'redis' | 's3';
-interface Addon {
-    id: string;
-    name: string;
-    type: AddonType;
-    projectId: string;
-    status: 'none' | 'running' | 'crashed' | 'stopped';
-    deployStatus: string;
-    version?: string;
-    /** Exposed connection variables (e.g. DATABASE_URL, REDIS_URL). */
-    env?: Record<string, string>;
-}
-interface CreateAddonOpts {
-    projectId: string;
-    type: AddonType;
-    name?: string;
-    version?: string;
-    /** vCPU count */
-    vcpu?: number;
-    /** Memory in MB */
-    memoryMb?: number;
-    /** Storage in GB */
-    storageGb?: number;
-}
-declare class AddonsAPI {
-    private readonly client;
-    constructor(client: PlatformClient);
-    /** List all addons in a project. */
-    list(opts: {
-        projectId: string;
-    }): Promise<Addon[]>;
-    /** Get an addon by ID. */
-    get(projectId: string, addonId: string): Promise<Addon>;
-    /**
-     * Create a new managed addon (database, cache, or object store).
-     *
-     * @example
-     * ```ts
-     * const pg = await lizard.addons.create({ projectId, type: 'postgres' })
-     * // Inject into a service:
-     * await lizard.secrets.set({ serviceId: svcId, key: 'DATABASE_URL', value: `${{${pg.name}.DATABASE_URL}}` })
-     * ```
-     */
-    create(opts: CreateAddonOpts): Promise<Addon>;
-    /** Delete an addon. */
-    delete(projectId: string, addonId: string): Promise<void>;
-    /** Resize an addon (CPU / memory / storage). */
-    resize(projectId: string, addonId: string, opts: {
-        vcpu?: number;
-        memoryMb?: number;
-        storageGb?: number;
-    }): Promise<Addon>;
-    /** Restart an addon VM. */
-    redeploy(projectId: string, addonId: string): Promise<void>;
+    }): Promise<Sandbox>;
+    static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<void>;
+    private resolveOpts;
 }
 
 interface Secret {
@@ -796,17 +951,21 @@ declare class SecretsAPI {
      * ```
      */
     set(projectId: string, secrets: SetSecretOpts | SetSecretOpts[]): Promise<void>;
-    /** Delete a secret by key. */
     delete(projectId: string, opts: {
         key: string;
         serviceId?: string;
     }): Promise<void>;
+    refs(projectId: string, serviceId?: string): Promise<unknown>;
 }
 
 interface DomainInfo {
     domain: string;
     /** 'pending' until DNS propagates and the platform verifies the CNAME/TXT record. */
     verified: boolean;
+    hostname?: string;
+    txtValue?: string;
+    live?: boolean;
+    generated?: boolean;
     txtRecord?: string;
     cnameTarget?: string;
 }
@@ -818,6 +977,7 @@ declare class DomainsAPI {
      * The platform-assigned `.onlizard.com` subdomain is always present.
      */
     list(serviceId: string): Promise<DomainInfo[]>;
+    info(serviceId: string): Promise<DomainStatus>;
     /**
      * Attach a custom domain to a service.
      * Returns the DNS records to add before calling `verify()`.
@@ -828,12 +988,32 @@ declare class DomainsAPI {
      * console.log('Add CNAME:', info.cnameTarget)
      * ```
      */
-    add(serviceId: string, domain: string): Promise<DomainInfo>;
+    add(serviceId: string, domain: string, opts?: {
+        force?: boolean;
+    }): Promise<DomainInfo>;
     /**
      * Verify that DNS records have propagated and activate the domain.
      * Call after adding the CNAME or TXT record returned by `add()`.
      */
     verify(serviceId: string, domain: string): Promise<DomainInfo>;
+    generate(serviceId: string): Promise<{
+        hostname: string;
+        generated: boolean;
+    }>;
+    delete(serviceId: string, hostname: string): Promise<void>;
+}
+interface DomainStatus {
+    domain: string | null;
+    domains: string[];
+    generatedDomain: string | null;
+    cnameTarget: string;
+    dnsOk: Record<string, boolean>;
+    pending: Array<{
+        hostname: string;
+        txtRecord: string;
+        txtValue: string;
+        cnameTarget: string;
+    }>;
 }
 
 type MetricRange = '1h' | '6h' | '24h' | '7d' | '14d' | '30d';
@@ -856,32 +1036,44 @@ interface CostMetrics {
     total: number;
     currency: string;
 }
+interface RawMetrics {
+    timestamps: number[];
+    series: Array<{
+        metric: string;
+        values: number[];
+        available?: boolean[];
+    }>;
+    latest?: Record<string, unknown>;
+    limits?: Record<string, number>;
+}
+interface ProjectCost {
+    projectId: string;
+    costUsd: number;
+    [key: string]: unknown;
+}
 declare class MetricsAPI {
     private readonly client;
     constructor(client: PlatformClient);
-    /** Get CPU metrics for a service or addon. */
+    service(id: string, range?: MetricRange): Promise<RawMetrics>;
+    addon(projectId: string, addonId: string, range?: MetricRange): Promise<RawMetrics>;
+    project(id: string, opts?: {
+        range?: MetricRange;
+        live?: boolean;
+    }): Promise<unknown>;
+    private points;
     cpu(id: string, range?: MetricRange): Promise<MetricPoint[]>;
-    /** Get memory metrics for a service or addon. */
     memory(id: string, range?: MetricRange): Promise<MetricPoint[]>;
-    /** Get network I/O metrics for a service. */
     network(id: string, range?: MetricRange): Promise<{
         rx: MetricPoint[];
         tx: MetricPoint[];
     }>;
-    /** Get disk I/O metrics for a service. */
     disk(id: string, range?: MetricRange): Promise<{
         read: MetricPoint[];
         write: MetricPoint[];
     }>;
-    /**
-     * Get cost breakdown for a project over the given range.
-     * Costs are in USD cents unless the `currency` field says otherwise.
-     */
-    cost(projectId: string, range?: MetricRange): Promise<CostMetrics>;
-    /**
-     * Convenience: fetch all metric types for a service in one call.
-     */
     all(id: string, range?: MetricRange): Promise<ServiceMetrics>;
+    /** Return the backend's project cost row in USD, without guessing missing totals. */
+    cost(projectId: string, range?: MetricRange): Promise<ProjectCost | null>;
 }
 
 interface Workspace {
@@ -1116,6 +1308,37 @@ declare class BillingAPI {
     summary(): Promise<unknown>;
     /** Live (not-yet-invoiced) usage accumulating right now. */
     live(): Promise<unknown>;
+    paymentMethods(): Promise<{
+        items: unknown[];
+    }>;
+    setupPaymentMethod(returnUrl?: string): Promise<{
+        url: string;
+    }>;
+    removePaymentMethod(id: string): Promise<void>;
+    purchase(creditCents: number, opts?: {
+        paymentMethod?: 'card' | 'crypto';
+        returnUrl?: string;
+    }): Promise<{
+        url: string;
+        sessionId?: string;
+    }>;
+    autoTopup(): Promise<unknown>;
+    setAutoTopup(opts: {
+        enabled: boolean;
+        thresholdCents: number;
+        amountCents: number;
+        paymentMethodIds: string[];
+    }): Promise<unknown>;
+    runAutoTopup(): Promise<unknown>;
+    redeemPromo(code: string): Promise<unknown>;
+    x402Quote(creditCents: number): Promise<unknown>;
+    paymentStatus(attemptId: string): Promise<unknown>;
+    /** Pay with the CLI's durable x402 journal. Requires CLI >= 4.0.8. Amounts are cents. */
+    payX402(creditCents: number, opts: {
+        maxTotalCents: number;
+        requestId?: string;
+        executable?: string;
+    }): Promise<unknown>;
 }
 
 interface VolumeInfo {
@@ -1250,6 +1473,8 @@ declare class Lizard {
     readonly domains: DomainsAPI;
     /** Query CPU, memory, network, disk, and cost metrics. */
     readonly metrics: MetricsAPI;
+    readonly storage: StorageAPI;
+    readonly github: GitHubAPI;
     constructor(opts: LizardOpts);
     /** Resolve the client's project reference to a stable project ID (cached). */
     projectId(): Promise<string>;
@@ -1325,7 +1550,7 @@ interface Account {
 
 /**
  * Resolve a project reference — its ID, slug, or name — to the stable project
- * ID the API bills against. Exact-ID refs skip the network entirely.
+ * ID the API bills against. Only resources visible to this credential are used.
  *
  * @throws {LizardError} when the reference matches no project the key can see.
  */
@@ -1334,6 +1559,11 @@ declare function resolveProjectId(ref: string, config: ConnectionConfig): Promis
 declare class LizardError extends Error {
     constructor(message: string);
 }
+/** Config was saved, but one or more deploy/restart actions failed. Never retry blindly. */
+declare class ConfigApplyError extends LizardError {
+    readonly result: unknown;
+    constructor(result: unknown);
+}
 declare class AuthenticationError extends LizardError {
     constructor(message?: string);
 }
@@ -1371,7 +1601,7 @@ type OutputItem = {
     message: string;
     traceback: string;
 };
-/** Error thrown when executed code raises an exception. */
+/** Error returned in Execution.error when executed code raises an exception. */
 declare class ExecutionError extends Error {
     readonly name: string;
     readonly traceback: string;
@@ -1406,7 +1636,7 @@ interface RunCodeOpts {
     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. */
+    /** Client timeout in milliseconds. No client timer is set when omitted. */
     timeoutMs?: number;
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
@@ -1428,7 +1658,7 @@ interface CreateContextOpts {
  *
  * @example
  * ```ts
- * import { CodeSandbox } from 'lizard/code-interpreter'
+ * import { CodeSandbox } from '@lizard-build/sdk'
  *
  * const sandbox = await CodeSandbox.create({ project: 'my-project' })
  *
@@ -1459,8 +1689,7 @@ declare class CodeSandbox 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
@@ -1503,4 +1732,28 @@ declare class CodeSandbox extends Sandbox {
     static connect(sandboxId: string, opts?: ConnectionOpts): Promise<CodeSandbox>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CodeContext, CodeSandbox, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, type ListTransactionsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, ProjectsAPI, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, ServicesAPI, type SetSecretOpts, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+interface CLIResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    events: unknown[];
+}
+interface CLIOptions extends ConnectionOpts {
+    executable?: string;
+    cwd?: string;
+    timeoutMs?: number;
+}
+/** Optional adapter for local CLI workflows. Requires the Lizard CLI on PATH.
+ * Arguments are passed directly, without a shell. It does not add --yes, retry
+ * payments. Authentication follows the CLI configuration.
+ */
+declare class LizardCLI {
+    private readonly opts;
+    constructor(opts?: CLIOptions);
+    run(args: readonly string[], opts?: {
+        stdin?: string;
+        signal?: AbortSignal;
+    }): Promise<CLIResult>;
+}
+
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };