@lizard-build/sdk 0.1.35 → 0.1.37

package/dist/index.mjs

@@ -439,8 +439,10 @@ var SandboxClient = class {
         projectId,
         metadata: opts?.metadata,
         envs: opts?.envs,
+        region: opts?.region,
         volumeId: opts?.volumeId,
-        volumeName: opts?.volumeName
+        volumeName: opts?.volumeName,
+        lizardToken: opts?.lizardToken
       })
     });
     if (!res.ok) await handleApiError(res);
@@ -531,8 +533,14 @@ var Sandbox = class extends SandboxClient {
   /**
    * Connect to an existing sandbox by its ID.
    *
-   * If the sandbox is currently paused, it will be automatically resumed
-   * before this call returns.
+   * 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.
    *
    * @example
    * ```ts
@@ -540,7 +548,7 @@ var Sandbox = class extends SandboxClient {
    * ```
    */
   static async connect(sandboxId, opts) {
-    await SandboxClient.resumeSandbox(sandboxId, opts);
+    await SandboxClient.getSandboxInfo(sandboxId, opts);
     return new this({ sandboxId, ...opts });
   }
   /**
@@ -563,37 +571,23 @@ var Sandbox = class extends SandboxClient {
     return SandboxClient.killSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Pause the sandbox microVM by freezing its vCPUs.
-   *
-   * 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 buy you time past the original deadline. Resuming pushes the
-   * expiry forward by however long the sandbox was paused — so a pause/resume cycle
-   * costs no runtime — but that adjustment only happens on `resume()`. A sandbox left
-   * paused past its original `expiresAt` is deleted there, within a minute, and
-   * `resume()` then returns `false`.
-   *
-   * In other words: pause and come back *before* the original deadline and you lose
-   * nothing; leave it paused across the deadline and it is gone. Pass `timeoutMs: 0`
-   * at create time to opt out of expiry entirely, which is the only way to park a
-   * sandbox indefinitely.
+   * Pause the sandbox by freezing it in place.
    *
-   * @returns `true` if paused successfully.
+   * @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.
    */
   async pause(opts) {
     return SandboxClient.pauseSandbox(this.sandboxId, this.resolveOpts(opts));
   }
   /**
-   * Resume a paused sandbox by unfreezing its vCPUs.
+   * Resume a paused sandbox.
    *
-   * The expiry is pushed forward by the time spent paused, so the timeout measures
-   * running time rather than wall-clock — provided the original deadline had not
-   * already passed while paused. See {@link pause}.
-   *
-   * @returns `true` if resumed successfully, `false` if the sandbox no longer exists
-   * (including because it expired while paused).
+   * @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.
    */
   async resume(opts) {
     return SandboxClient.resumeSandbox(this.sandboxId, this.resolveOpts(opts));
@@ -1049,13 +1043,233 @@ var MetricsAPI = class {
   }
 };
 
+// src/platform/workspaces.ts
+var WorkspacesAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List workspaces the calling credential can see.
+   *
+   * A scoped API key sees only what it is scoped to: a workspace-scoped key returns
+   * that one workspace, and a project-scoped key returns the workspace containing its
+   * project. A full key returns every workspace the account belongs to.
+   */
+  list() {
+    return this.client.get("/api/workspaces");
+  }
+  /** Create a workspace. The caller becomes its owner. */
+  create(opts) {
+    return this.client.post("/api/workspaces", opts);
+  }
+  /**
+   * Delete a workspace.
+   *
+   * Empty-only by default — the server refuses while any project or sandbox remains,
+   * so this cannot quietly destroy a user's work. Pass `{ force: true }` to delete a
+   * workspace and everything in it; that is irreversible.
+   */
+  delete(id, opts) {
+    const qs = opts?.force ? "" : "?requireEmpty=true";
+    return this.client.delete(`/api/workspaces/${id}${qs}`);
+  }
+  /**
+   * Find a workspace by name, slug, or id, or `null` if there is no such workspace.
+   * Matching is exact; id wins, then slug, then name.
+   */
+  async find(nameOrSlugOrId) {
+    const all = await this.list();
+    return all.find((w) => w.id === nameOrSlugOrId) ?? all.find((w) => w.slug === nameOrSlugOrId) ?? all.find((w) => w.name === nameOrSlugOrId) ?? null;
+  }
+};
+
+// src/platform/api-keys.ts
+var ApiKeysAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List the account's API keys. Previews only — full keys are never returned here. */
+  list() {
+    return this.client.get("/api/account/api-keys");
+  }
+  /**
+   * Create an API key.
+   *
+   * The response is the only place the full key appears. Omitting every scope creates
+   * a full-access key; the server rejects an attempt to create one from a key that is
+   * itself scoped.
+   */
+  create(opts) {
+    const scopes = [
+      ...opts.scopes ?? [],
+      ...(opts.workspaces ?? []).map((id) => ({ type: "workspace", id })),
+      ...(opts.projects ?? []).map((id) => ({ type: "project", id }))
+    ];
+    return this.client.post("/api/account/api-keys", { name: opts.name, scopes });
+  }
+  /** Revoke a key by id. It stops working immediately, everywhere. */
+  delete(id) {
+    return this.client.delete(`/api/account/api-keys/${id}`);
+  }
+};
+
+// src/platform/regions.ts
+var RegionsAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List every region, including ones not currently accepting workloads. */
+  list() {
+    return this.client.get("/api/regions");
+  }
+};
+
+// src/platform/billing.ts
+var BillingAPI = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Current balance, status, burn rate, and runway. */
+  balance() {
+    return this.client.get("/api/billing/balance");
+  }
+  /** A page of balance transactions, newest first. */
+  transactions(opts) {
+    const qs = new URLSearchParams();
+    if (opts?.limit !== void 0) qs.set("limit", String(opts.limit));
+    if (opts?.cursor) qs.set("cursor", opts.cursor);
+    if (opts?.includeUsage) qs.set("includeUsage", "1");
+    const q = qs.toString();
+    return this.client.get(`/api/billing/transactions${q ? `?${q}` : ""}`);
+  }
+  /** Cost summary for the current billing period, broken down by resource. */
+  summary() {
+    return this.client.get("/api/billing/summary");
+  }
+  /** Live (not-yet-invoiced) usage accumulating right now. */
+  live() {
+    return this.client.get("/api/billing/live");
+  }
+};
+
+// src/volume/index.ts
+var Volume = class _Volume {
+  constructor(opts) {
+    this.volumeId = opts.volumeId;
+    this.name = opts.name;
+    this.config = new ConnectionConfig(opts);
+  }
+  /**
+   * Create a volume. Throws `ConflictError` (409) if the project already has one with
+   * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
+   */
+  static async create(projectId, name, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5, region: opts?.region })
+    });
+    if (!res.ok) await handleApiError(res);
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
+  }
+  /**
+   * Return the project's volume with this name, creating it first if it does not
+   * exist yet. This is the reason a volume's name is its key: an agent that wants
+   * "the scratch disk for this task" no longer has to store an id between runs.
+   *
+   * An existing volume is returned as-is — `sizeGb` applies only to a fresh create
+   * and never resizes one that is already there.
+   */
+  static async getOrCreate(projectId, name, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
+      method: "POST",
+      headers: config.headers,
+      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5, region: opts?.region, getOrCreate: true })
+    });
+    if (!res.ok) await handleApiError(res);
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
+  }
+  /** Look a volume up by name or by id. */
+  static async get(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    const vol = await res.json();
+    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
+  }
+  static async list(projectId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /** Delete a volume by name or by id, without constructing one first. */
+  static async delete(projectId, nameOrId, opts) {
+    const config = new ConnectionConfig(opts);
+    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
+      method: "DELETE",
+      headers: config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+  async getInfo(projectId) {
+    const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
+      headers: this.config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  async delete(projectId) {
+    const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
+      method: "DELETE",
+      headers: this.config.headers
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+};
+
 // src/lizard.ts
 var Lizard = class {
   constructor(opts) {
+    // ── Volumes, bound to this client's project ───────────────────────────────
+    /**
+     * Persistent volumes in this client's project.
+     *
+     * The same calls as the static {@link Volume} methods, minus the `projectId`
+     * argument — the client already knows it.
+     *
+     * @requires `project` to be set in the constructor.
+     *
+     * @example
+     * ```ts
+     * const lizard = new Lizard({ project: 'my-project' })
+     * const vol = await lizard.volumes.getOrCreate('scratch', { sizeGb: 10 })
+     * const sb  = await lizard.create('codex', { volumeName: 'scratch' })
+     * ```
+     */
+    this.volumes = {
+      create: async (name, opts) => Volume.create(await this.projectId(), name, { ...await this.connectionOpts(), ...opts }),
+      getOrCreate: async (name, opts) => Volume.getOrCreate(await this.projectId(), name, { ...await this.connectionOpts(), ...opts }),
+      get: async (nameOrId, opts) => Volume.get(await this.projectId(), nameOrId, { ...await this.connectionOpts(), ...opts }),
+      list: async (opts) => Volume.list(await this.projectId(), { ...await this.connectionOpts(), ...opts }),
+      delete: async (nameOrId, opts) => Volume.delete(await this.projectId(), nameOrId, { ...await this.connectionOpts(), ...opts })
+    };
     this.config = new ConnectionConfig(opts);
     this.projectRef = opts.project;
     const platform = new PlatformClient(opts);
     this._platform = platform;
+    this.workspaces = new WorkspacesAPI(platform);
+    this.apiKeys = new ApiKeysAPI(platform);
+    this.regions = new RegionsAPI(platform);
+    this.billing = new BillingAPI(platform);
     this.projects = new ProjectsAPI(platform);
     this.services = new ServicesAPI(platform);
     this.addons = new AddonsAPI(platform);
@@ -1081,7 +1295,7 @@ var Lizard = class {
     const sandboxOpts = { ...opts, ...await this.connectionOpts(), projectId };
     return template ? Sandbox.create(template, sandboxOpts) : Sandbox.create(sandboxOpts);
   }
-  /** Connect to an existing sandbox by ID (resumes it if paused). */
+  /** Connect to an existing sandbox by ID. Throws `NotFoundError` if it is gone. */
   async connect(sandboxId, opts) {
     return Sandbox.connect(sandboxId, await this.connectionOpts(opts));
   }
@@ -1089,6 +1303,20 @@ var Lizard = class {
   async list(opts) {
     return Sandbox.list(await this.connectionOpts(opts));
   }
+  // ── Account ───────────────────────────────────────────────────────────────
+  /**
+   * The account this credential belongs to — the SDK's `lizard whoami`.
+   *
+   * Works for a scoped key as well as a full one: the identity is the account that
+   * created the key, which is what the key's usage bills to.
+   */
+  async whoami() {
+    return this.platform.get("/api/auth/me");
+  }
+  /** The underlying HTTP client, for endpoints this SDK does not wrap yet. */
+  get platform() {
+    return this._platform;
+  }
 };
 
 // src/code-interpreter/types.ts
@@ -1280,100 +1508,27 @@ async function* readLines(body) {
     reader.releaseLock();
   }
 }
-
-// src/volume/index.ts
-var Volume = class _Volume {
-  constructor(opts) {
-    this.volumeId = opts.volumeId;
-    this.name = opts.name;
-    this.config = new ConnectionConfig(opts);
-  }
-  /**
-   * Create a volume. Throws `ConflictError` (409) if the project already has one with
-   * this name — use {@link getOrCreate} when you want "make sure this exists" instead.
-   */
-  static async create(projectId, name, opts) {
-    const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
-      method: "POST",
-      headers: config.headers,
-      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5 })
-    });
-    if (!res.ok) await handleApiError(res);
-    const vol = await res.json();
-    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
-  }
-  /**
-   * Return the project's volume with this name, creating it first if it does not
-   * exist yet. This is the reason a volume's name is its key: an agent that wants
-   * "the scratch disk for this task" no longer has to store an id between runs.
-   *
-   * An existing volume is returned as-is — `sizeGb` applies only to a fresh create
-   * and never resizes one that is already there.
-   */
-  static async getOrCreate(projectId, name, opts) {
-    const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
-      method: "POST",
-      headers: config.headers,
-      body: JSON.stringify({ name, sizeGb: opts?.sizeGb ?? 5, getOrCreate: true })
-    });
-    if (!res.ok) await handleApiError(res);
-    const vol = await res.json();
-    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
-  }
-  /** Look a volume up by name or by id. */
-  static async get(projectId, nameOrId, opts) {
-    const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
-      headers: config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-    const vol = await res.json();
-    return new _Volume({ volumeId: vol.id, name: vol.name, ...opts });
-  }
-  static async list(projectId, opts) {
-    const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes`, {
-      headers: config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
-  }
-  /** Delete a volume by name or by id, without constructing one first. */
-  static async delete(projectId, nameOrId, opts) {
-    const config = new ConnectionConfig(opts);
-    const res = await fetch(`${config.apiUrl}/api/projects/${projectId}/volumes/${encodeURIComponent(nameOrId)}`, {
-      method: "DELETE",
-      headers: config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-  }
-  async getInfo(projectId) {
-    const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
-      headers: this.config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-    return res.json();
-  }
-  async delete(projectId) {
-    const res = await fetch(`${this.config.apiUrl}/api/projects/${projectId}/volumes/${this.volumeId}`, {
-      method: "DELETE",
-      headers: this.config.headers
-    });
-    if (!res.ok) await handleApiError(res);
-  }
-};
 export {
+  AddonsAPI,
+  ApiKeysAPI,
   AuthenticationError,
+  BillingAPI,
   CodeSandbox,
   ConflictError,
   DeployHandle,
+  DomainsAPI,
   Lizard,
   LizardError,
+  MetricsAPI,
   NotFoundError,
+  PlatformClient,
+  ProjectsAPI,
+  RegionsAPI,
   Sandbox,
+  SecretsAPI,
+  ServicesAPI,
   TimeoutError,
   Volume,
+  WorkspacesAPI,
   resolveProjectId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Firecracker microVM sandboxes for AI agents — boot Linux in milliseconds, run code, write files, expose ports over HTTPS, then pause a session with memory intact and resume it later. TypeScript SDK for Lizard Sandboxes (lizard.build).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",