@lizard-build/sdk 0.1.22 → 0.1.24

package/dist/index.d.ts

@@ -177,12 +177,13 @@ declare class SandboxClient {
  *
  * Each sandbox is a full Linux environment with its own filesystem, network,
  * and process namespace. Sandboxes are spun up from templates and can be
- * paused to a snapshot, then resumed instantly — perfect for stateful AI
- * agent sessions or ephemeral code execution.
+ * paused — vCPUs frozen, memory and running processes kept — then resumed
+ * instantly, perfect for stateful AI agent sessions or ephemeral code
+ * execution.
  *
  * @example Basic usage:
  * ```ts
- * import { Sandbox } from 'lizard'
+ * 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")')
@@ -245,8 +246,8 @@ declare class Sandbox extends SandboxClient {
     /**
      * Create a new Lizard sandbox from the specified template.
      *
-     * Available templates: `base` (Debian + Node.js 20) and `code-interpreter-v1`
-     * (Python 3.11 + Node.js 20). Custom templates can be built and pushed via
+     * 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`.
      *
      * @param template Name of the sandbox template to boot from.
@@ -262,7 +263,7 @@ declare class Sandbox extends SandboxClient {
      * 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.
+     * before this call returns.
      *
      * @example
      * ```ts
@@ -286,16 +287,21 @@ declare class Sandbox extends SandboxClient {
      */
     kill(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Snapshot and pause the sandbox microVM.
+     * Pause the sandbox microVM by freezing its vCPUs.
      *
-     * The sandbox state — memory, filesystem, and running processes — is saved
-     * to a snapshot. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     * Memory, filesystem, and running processes are held in the host's RAM —
+     * nothing is written to disk, so a paused sandbox does not survive a host
+     * failure. Resume with `sandbox.resume()` or `Sandbox.connect(id)`.
+     *
+     * Pausing does not stop the timeout: a paused sandbox is still deleted at
+     * its original expiry (default 5 minutes). Pass `timeoutMs: 0` at create
+     * time to opt out of expiry.
      *
      * @returns `true` if paused successfully.
      */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /**
-     * Resume a paused sandbox from its last snapshot.
+     * Resume a paused sandbox by unfreezing its vCPUs.
      *
      * @returns `true` if resumed successfully.
      */
@@ -327,47 +333,428 @@ declare class Sandbox extends SandboxClient {
     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?: {
+        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 VM. */
+    exec(id: string, cmd: string, opts?: {
+        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>;
+}
+
+interface Secret {
+    key: string;
+    value: string;
+}
+interface SetSecretOpts {
+    key: string;
+    value: string;
+    /** Target a specific service. Omit for project-scope. */
+    serviceId?: string;
+    /** If true, set at project scope (shared across all services). */
+    global?: boolean;
+}
+interface ListSecretsOpts {
+    serviceId?: string;
+}
+declare class SecretsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /**
+     * List secrets for a project or service.
+     *
+     * @param projectId - The project ID.
+     * @param opts.serviceId - If given, list service-scoped secrets instead of project secrets.
+     */
+    list(projectId: string, opts?: ListSecretsOpts): Promise<Secret[]>;
+    /**
+     * Set one or more secrets.
+     *
+     * ```ts
+     * // Service-scoped secret (default):
+     * await lizard.secrets.set(projectId, { key: 'DATABASE_URL', value: '${{postgres.DATABASE_URL}}', serviceId })
+     *
+     * // Project-scoped (shared across all services):
+     * await lizard.secrets.set(projectId, { key: 'LOG_LEVEL', value: 'info', global: true })
+     * ```
+     */
+    set(projectId: string, secrets: SetSecretOpts | SetSecretOpts[]): Promise<void>;
+    /** Delete a secret by key. */
+    delete(projectId: string, opts: {
+        key: string;
+        serviceId?: string;
+    }): Promise<void>;
+}
+
+interface DomainInfo {
+    domain: string;
+    /** 'pending' until DNS propagates and the platform verifies the CNAME/TXT record. */
+    verified: boolean;
+    txtRecord?: string;
+    cnameTarget?: string;
+}
+declare class DomainsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /**
+     * Show the current domain(s) for a service.
+     * The platform-assigned `.onlizard.com` subdomain is always present.
+     */
+    list(serviceId: string): Promise<DomainInfo[]>;
+    /**
+     * Attach a custom domain to a service.
+     * Returns the DNS records to add before calling `verify()`.
+     *
+     * @example
+     * ```ts
+     * const info = await lizard.domains.add(serviceId, 'api.example.com')
+     * console.log('Add CNAME:', info.cnameTarget)
+     * ```
+     */
+    add(serviceId: string, domain: string): 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>;
+}
+
+type MetricRange = '1h' | '6h' | '24h' | '7d' | '14d' | '30d';
+interface MetricPoint {
+    t: number;
+    value: number;
+}
+interface ServiceMetrics {
+    cpu: MetricPoint[];
+    memory: MetricPoint[];
+    networkRx: MetricPoint[];
+    networkTx: MetricPoint[];
+    diskRead: MetricPoint[];
+    diskWrite: MetricPoint[];
+}
+interface CostMetrics {
+    compute: number;
+    egress: number;
+    storage: number;
+    total: number;
+    currency: string;
+}
+declare class MetricsAPI {
+    private readonly client;
+    constructor(client: PlatformClient);
+    /** Get CPU metrics for a service or addon. */
+    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>;
+}
+
 interface LizardOpts extends ConnectionOpts {
     /**
      * The project every sandbox created through this client belongs to — its ID,
-     * slug, or name. Required: sandboxes are billed per project, so a project-less
-     * sandbox cannot be created.
+     * slug, or name. Required for sandbox operations; optional for platform
+     * management (projects, services, addons, etc.).
      */
-    project: string;
+    project?: string;
 }
 /**
- * The Lizard client — the entry point for creating sandboxes.
+ * The Lizard client — entry point for sandboxes and platform management.
  *
- * A client is pinned to one project (billing is metered per project), so every
- * sandbox it creates is attributed correctly. The project reference — ID, slug,
- * or name — is resolved to a project ID on first use and cached.
- *
- * @example
+ * @example Sandbox usage (backward-compatible)
  * ```ts
- * import { Lizard } from '@lizard-build/sdk'
- *
- * const lizard = new Lizard({ project: 'my-project' }) // apiKey from LIZARD_API_KEY
- *
+ * const lizard = new Lizard({ project: 'my-project' })
  * const sandbox = await lizard.create('base')
  * await sandbox.process.exec('echo hello')
  * await sandbox.kill()
  * ```
+ *
+ * @example Platform management
+ * ```ts
+ * const lizard = new Lizard({ apiKey: process.env.LIZARD_API_KEY })
+ *
+ * // Deploy from git
+ * const deploy = await lizard.services.deploy({ projectId, name: 'api', repoUrl: '...', branch: 'main' })
+ * const result = await deploy.wait()
+ * console.log('Deployed to', result.url)
+ *
+ * // Add a Postgres addon and wire it to the service
+ * const pg = await lizard.addons.create({ projectId, type: 'postgres' })
+ * await lizard.secrets.set(projectId, {
+ *   serviceId: result.serviceId,
+ *   key: 'DATABASE_URL',
+ *   value: `${{${pg.name}.DATABASE_URL}}`,
+ * })
+ * ```
  */
 declare class Lizard {
     private readonly config;
     private readonly projectRef;
+    private _platform;
+    /** Manage projects. */
+    readonly projects: ProjectsAPI;
+    /** Deploy and manage services. */
+    readonly services: ServicesAPI;
+    /** Manage addons (postgres, redis, s3, mysql, mongodb). */
+    readonly addons: AddonsAPI;
+    /** Manage secrets and environment variables. */
+    readonly secrets: SecretsAPI;
+    /** Manage custom domains. */
+    readonly domains: DomainsAPI;
+    /** Query CPU, memory, network, disk, and cost metrics. */
+    readonly metrics: MetricsAPI;
     constructor(opts: LizardOpts);
     /** Resolve the client's project reference to a stable project ID (cached). */
     projectId(): Promise<string>;
     private connectionOpts;
     /**
      * Create a new sandbox in this client's project.
-     *
-     * @example
-     * ```ts
-     * const sandbox = await lizard.create('base')
-     * const sandbox = await lizard.create('code-interpreter-v1', { timeoutMs: 600_000 })
-     * ```
+     * @requires `project` to be set in the constructor.
      */
     create(template?: string, opts?: Omit<SandboxOpts, 'project' | 'projectId'>): Promise<Sandbox>;
     /** Connect to an existing sandbox by ID (resumes it if paused). */
@@ -578,4 +965,4 @@ declare class Volume {
     delete(projectId: string): Promise<void>;
 }
 
-export { AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CreateContextOpts, type CreateVolumeOpts, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, NotFoundError, type ProcessOpts, type ProcessResult, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };
+export { type Addon, type AddonType, AuthenticationError, type CodeContext, CodeSandbox, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type DeployEvent, DeployHandle, type DomainInfo, Execution, ExecutionError, type FileInfo, type FsOpts, Lizard, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, NotFoundError, type ProcessOpts, type ProcessResult, type Project, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type ScaleOpts, type Secret, type Service, type ServiceMetrics, type SetSecretOpts, TimeoutError, Volume, type VolumeInfo, resolveProjectId };