@lizard-build/sdk 0.1.22 → 0.1.24

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   CodeSandbox: () => CodeSandbox,
+  DeployHandle: () => DeployHandle,
   Lizard: () => Lizard,
   LizardError: () => LizardError,
   NotFoundError: () => NotFoundError,
@@ -369,7 +370,7 @@ var Sandbox = class 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
@@ -400,10 +401,15 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * 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.
    */
@@ -411,7 +417,7 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Resume a paused sandbox from its last snapshot.
+   * Resume a paused sandbox by unfreezing its vCPUs.
    *
    * @returns `true` if resumed successfully.
    */
@@ -456,19 +462,437 @@ var Sandbox = class extends SandboxClient {
 Sandbox.defaultTemplate = "base";
 Sandbox.defaultTimeoutMs = DEFAULT_SANDBOX_TIMEOUT_MS;
 
+// src/platform/client.ts
+var PlatformClient = class {
+  constructor(opts) {
+    this.config = new ConnectionConfig(opts);
+  }
+  async get(path) {
+    const res = await fetch(`${this.config.apiUrl}${path}`, {
+      headers: this.config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  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();
+  }
+  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();
+  }
+  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();
+  }
+  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();
+  }
+  /** 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);
+      }
+    }
+  }
+};
+
+// src/platform/projects.ts
+var ProjectsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all projects the API key can access. */
+  list(opts) {
+    const qs = opts?.workspaceId ? `?workspaceId=${opts.workspaceId}` : "";
+    return this.client.get(`/api/projects${qs}`);
+  }
+  /** Get a project by ID. */
+  get(id) {
+    return this.client.get(`/api/projects/${id}`);
+  }
+  /** Create a new project. */
+  create(opts) {
+    return this.client.post("/api/projects", opts);
+  }
+  /** Update a project's name. */
+  update(id, opts) {
+    return this.client.patch(`/api/projects/${id}`, opts);
+  }
+  /** Delete a project. */
+  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;
+  }
+  /** 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`);
+  }
+};
+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,
+      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 VM. */
+  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}`);
+  }
+};
+
+// src/platform/addons.ts
+var AddonsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all addons in a project. */
+  list(opts) {
+    return this.client.get(`/api/projects/${opts.projectId}/addons`);
+  }
+  /** Get an addon by ID. */
+  get(projectId, addonId) {
+    return this.client.get(`/api/projects/${projectId}/addons/${addonId}`);
+  }
+  /**
+   * 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) {
+    return this.client.post(`/api/projects/${opts.projectId}/addons`, {
+      type: opts.type,
+      name: opts.name,
+      version: opts.version,
+      vcpu: opts.vcpu,
+      memoryMb: opts.memoryMb,
+      storageGb: opts.storageGb
+    });
+  }
+  /** Delete an addon. */
+  delete(projectId, addonId) {
+    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);
+  }
+  /** Restart an addon VM. */
+  redeploy(projectId, addonId) {
+    return this.client.post(`/api/projects/${projectId}/addons/${addonId}/redeploy`, {});
+  }
+};
+
+// src/platform/secrets.ts
+var SecretsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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, opts) {
+    if (opts?.serviceId) {
+      return this.client.get(`/api/apps/${opts.serviceId}/secrets`);
+    }
+    return this.client.get(`/api/projects/${projectId}/secrets`);
+  }
+  /**
+   * 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 })
+   * ```
+   */
+  async set(projectId, secrets) {
+    const items = Array.isArray(secrets) ? secrets : [secrets];
+    const byService = /* @__PURE__ */ new Map();
+    const projectScoped = {};
+    for (const s of items) {
+      if (s.global || !s.serviceId) {
+        projectScoped[s.key] = s.value;
+      } else {
+        if (!byService.has(s.serviceId)) byService.set(s.serviceId, {});
+        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));
+    }
+    for (const [serviceId, kv] of byService) {
+      tasks.push(this.client.post(`/api/apps/${serviceId}/secrets`, kv));
+    }
+    await Promise.all(tasks);
+  }
+  /** Delete a secret by key. */
+  async delete(projectId, opts) {
+    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 });
+    }
+  }
+};
+
+// src/platform/domains.ts
+var DomainsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Show the current domain(s) for a service.
+   * The platform-assigned `.onlizard.com` subdomain is always present.
+   */
+  list(serviceId) {
+    return this.client.get(`/api/apps/${serviceId}/domains`);
+  }
+  /**
+   * 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, domain) {
+    return this.client.post(`/api/apps/${serviceId}/domains`, { 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 });
+  }
+};
+
+// src/platform/metrics.ts
+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}`);
+  }
+  /** Get memory metrics for a service or addon. */
+  memory(id, range = "1h") {
+    return this.client.get(`/api/apps/${id}/metrics/memory?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}`);
+  }
+  /** Get disk I/O metrics for a service. */
+  disk(id, range = "1h") {
+    return this.client.get(`/api/apps/${id}/metrics/disk?range=${range}`);
+  }
+  /**
+   * 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}`);
+  }
+  /**
+   * 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 };
+  }
+};
+
 // src/lizard.ts
 var Lizard = class {
   constructor(opts) {
-    if (!opts?.project) {
-      throw new LizardError(
-        'A project is required. Pass project (its ID, slug, or name): new Lizard({ project: "my-project" }).'
-      );
-    }
     this.config = new ConnectionConfig(opts);
     this.projectRef = opts.project;
+    const platform = new PlatformClient(opts);
+    this._platform = platform;
+    this.projects = new ProjectsAPI(platform);
+    this.services = new ServicesAPI(platform);
+    this.addons = new AddonsAPI(platform);
+    this.secrets = new SecretsAPI(platform);
+    this.domains = new DomainsAPI(platform);
+    this.metrics = new MetricsAPI(platform);
   }
+  // ── Sandbox convenience methods (backward-compatible) ──────────────────
   /** Resolve the client's project reference to a stable project ID (cached). */
   async projectId() {
+    if (!this.projectRef) throw new LizardError("No project set. Pass project in Lizard({ project }) to use sandbox APIs.");
     return resolveProjectId(this.projectRef, this.config);
   }
   async connectionOpts(extra) {
@@ -476,12 +900,7 @@ var Lizard = class {
   }
   /**
    * 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.
    */
   async create(template, opts) {
     const projectId = await this.projectId();
@@ -740,6 +1159,7 @@ var Volume = class _Volume {
 0 && (module.exports = {
   AuthenticationError,
   CodeSandbox,
+  DeployHandle,
   Lizard,
   LizardError,
   NotFoundError,