@lizard-build/sdk 0.1.21 → 0.1.23

package/dist/index.d.ts

@@ -327,47 +327,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 +959,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 };