@lizard-build/sdk 0.1.36 → 0.1.38

package/README.md

@@ -82,7 +82,7 @@ sandbox.kill()
 
 ## Persisting Work Across Sandboxes
 
-Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards everything written inside it. State that has to outlive a sandbox goes on a **volume** — a separate disk mounted at `/data` that a later sandbox re-attaches.
+Sandboxes are **ephemeral**: killing one, or letting it hit its timeout, discards everything written inside it. State that has to outlive a sandbox goes on a **volume** — a separate disk mounted at `/workspace` that a later sandbox re-attaches.
 
 A volume is node-local, so it fixes the region too. You don't thread a region through both calls: the sandbox is placed wherever its volume already lives.
 
@@ -90,25 +90,25 @@ A volume is node-local, so it fixes the region too. You don't thread a region th
 const vol = await lizard.volumes.getOrCreate('agent-scratch', { sizeGb: 10 })
 
 const first = await lizard.create('codex', { volumeName: 'agent-scratch' })
-await first.process.exec('pip install numpy pandas && echo "notes" > /data/notes.txt')
-await first.kill()          // sandbox gone, /data survives
+await first.process.exec('pip install numpy pandas && echo "notes" > /workspace/notes.txt')
+await first.kill()          // sandbox gone, /workspace survives
 
 const second = await lizard.create('codex', { volumeName: 'agent-scratch' })
-console.log(await second.fs.read('/data/notes.txt'))   // "notes"
+console.log(await second.fs.read('/workspace/notes.txt'))   // "notes"
 ```
 
 ```python
 vol = lizard.volumes.get_or_create("agent-scratch", size_gb=10)
 
 first = lizard.create("codex", volume_name="agent-scratch")
-first.process.exec_('echo "notes" > /data/notes.txt')
-first.kill()                # sandbox gone, /data survives
+first.process.exec_('echo "notes" > /workspace/notes.txt')
+first.kill()                # sandbox gone, /workspace survives
 
 second = lizard.create("codex", volume_name="agent-scratch")
-print(second.fs.read("/data/notes.txt"))   # "notes"
+print(second.fs.read("/workspace/notes.txt"))   # "notes"
 ```
 
-Note that only `/data` survives — installed packages and in-memory state do not. Bake tooling into a template instead of reinstalling it per sandbox.
+Note that only `/workspace` survives — installed packages and in-memory state do not. Bake tooling into a template instead of reinstalling it per sandbox.
 
 > `pause()` / `resume()` exist on the client but are **not implemented** for the current runtime and always fail with HTTP 501. Use a volume.
 
@@ -148,6 +148,14 @@ sandbox.process.exec_("lizard volume list")
 
 A key with **no** scope has full access to everything the creating account can reach — pass `workspaces` or `projects` unless you mean that.
 
+### What a scoped key deliberately cannot see
+
+Billing is account-level: one balance, one ledger, one set of saved cards, shared by every workspace. There is no per-workspace view of it, so a scoped key is refused outright (403 `ACCOUNT_SCOPE_REQUIRED`) on `lizard.billing.*` and on account-wide usage, and `whoami()` returns only identity plus the key's own scopes — not the account's email, balance or plan.
+
+That matters because of where these keys end up. A key you hand to a user, or inject into a sandbox with `lizardToken`, is readable by anything running there. It should not be a way to read your card details or spend against them.
+
+For per-workspace spend, use `lizard.metrics` — that is scoped, and is what you would bill a user from.
+
 ## API
 
 ### `new Lizard({ project, apiKey?, apiUrl?, timeoutMs? })`
@@ -187,8 +195,8 @@ List all running sandboxes for the authenticated account.
 | `lizard.apiKeys` | `list()`, `create({ name, workspaces?, projects? })`, `delete(id)` |
 | `lizard.projects` | `list({ workspaceId? })`, `get(id)`, `create({ workspaceId, name })`, `update(id, { name })`, `delete(id)` |
 | `lizard.regions` | `list()` |
-| `lizard.billing` | `balance()`, `transactions({ limit?, cursor?, includeUsage? })`, `summary()`, `live()` |
-| `lizard.whoami()` | The account behind the credential — works for scoped keys too |
+| `lizard.billing` | `balance()`, `transactions({ limit?, cursor?, includeUsage? })`, `summary()`, `live()` — **unscoped keys only** |
+| `lizard.whoami()` | The account behind the credential; a scoped key gets identity and its own scopes, not the account's email or balance |
 | `lizard.platform` | The raw HTTP client, for endpoints not wrapped yet |
 
 `workspaces.delete()` is empty-only by default; the server refuses while any project, sandbox or volume remains. `{ force: true }` deletes the workspace and everything in it, irreversibly.

package/dist/index.d.mts

@@ -303,10 +303,10 @@ interface SandboxOpts extends ConnectionOpts {
      * Defaults to the platform's default sandbox region.
      */
     region?: string;
-    /** Attach a persistent volume by id, mounted at `/data`. */
+    /** Attach a persistent volume by id, mounted at `/workspace`. */
     volumeId?: string;
     /**
-     * Attach a persistent volume by name, mounted at `/data`. A volume's name is its
+     * Attach a persistent volume by name, mounted at `/workspace`. A volume's name is its
      * key inside a project, so this is usually what you want — see {@link Volume}.
      * Requires the sandbox's project to be given as an exact `projectId`.
      */
@@ -361,7 +361,7 @@ declare class SandboxClient {
  *
  * 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
- * {@link Volume}, which is a separate disk you mount at `/data` and re-attach to a
+ * {@link Volume}, which is a separate disk you mount at `/workspace` and re-attach to a
  * later sandbox.
  *
  * @example Basic usage:
@@ -380,13 +380,13 @@ declare class SandboxClient {
  * const vol = await Volume.getOrCreate(projectId, 'agent-scratch', { sizeGb: 10 })
  *
  * const first = await Sandbox.create('codex', { projectId, volumeName: 'agent-scratch' })
- * await first.process.exec('echo "notes" > /data/notes.txt')
+ * await first.process.exec('echo "notes" > /workspace/notes.txt')
  * await first.kill()
  *
  * // A different sandbox, the same disk. No region to thread through: the sandbox
  * // is placed wherever the volume already lives.
  * const second = await Sandbox.create('codex', { projectId, volumeName: 'agent-scratch' })
- * console.log(await second.fs.read('/data/notes.txt')) // "notes"
+ * console.log(await second.fs.read('/workspace/notes.txt')) // "notes"
  * ```
  */
 declare class Sandbox extends SandboxClient {
@@ -1098,6 +1098,12 @@ interface ListTransactionsOpts {
  * a user bills to the account that owns the key. That is what makes per-user
  * workspaces a safe pattern — your users get isolation, you keep one bill — and also
  * what makes {@link Balance.runwayHours} worth watching before you provision more.
+ *
+ * **Requires an unscoped key.** A scoped key is refused with 403
+ * `ACCOUNT_SCOPE_REQUIRED`, because there is no workspace-scoped view of one shared
+ * balance, ledger and set of saved cards — and because a scoped key is meant to be
+ * handed to an end user, who should not be reading your card details or spending
+ * against them. For per-workspace spend, use {@link MetricsAPI.cost} instead.
  */
 declare class BillingAPI {
     private readonly client;
@@ -1281,19 +1287,36 @@ declare class Lizard {
     /**
      * 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.
+     * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
+     * and the key's own `scopes`. The account's email, balance, plan and billing status
+     * are withheld — they belong to the account, not to the key holder, and a scoped key
+     * is meant to be handed to an end user or injected into a sandbox. An unscoped key
+     * or a session sees the full account.
+     *
+     * Reading back `scopes` is the cheapest way to answer "what can this key reach".
      */
     whoami(): Promise<Account>;
     /** The underlying HTTP client, for endpoints this SDK does not wrap yet. */
     get platform(): PlatformClient;
 }
-/** The account behind a credential — see {@link Lizard.whoami}. */
+/**
+ * The account behind a credential — see {@link Lizard.whoami}.
+ *
+ * Everything past `avatarUrl` is present only for an unscoped key or a session; a
+ * scoped key gets `scoped: true` and `scopes` in their place.
+ */
 interface Account {
     id: string;
     username: string;
-    email?: string | null;
     avatarUrl?: string | null;
+    /** True when the calling key is scoped, meaning the account fields below are absent. */
+    scoped?: boolean;
+    /** What the calling key may reach. Present when `scoped` is true. */
+    scopes?: Array<{
+        type: 'workspace' | 'project';
+        id: string;
+    }>;
+    email?: string | null;
     plan?: string;
     billingStatus?: string;
     balanceCents?: number;

package/dist/index.d.ts

@@ -303,10 +303,10 @@ interface SandboxOpts extends ConnectionOpts {
      * Defaults to the platform's default sandbox region.
      */
     region?: string;
-    /** Attach a persistent volume by id, mounted at `/data`. */
+    /** Attach a persistent volume by id, mounted at `/workspace`. */
     volumeId?: string;
     /**
-     * Attach a persistent volume by name, mounted at `/data`. A volume's name is its
+     * Attach a persistent volume by name, mounted at `/workspace`. A volume's name is its
      * key inside a project, so this is usually what you want — see {@link Volume}.
      * Requires the sandbox's project to be given as an exact `projectId`.
      */
@@ -361,7 +361,7 @@ declare class SandboxClient {
  *
  * 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
- * {@link Volume}, which is a separate disk you mount at `/data` and re-attach to a
+ * {@link Volume}, which is a separate disk you mount at `/workspace` and re-attach to a
  * later sandbox.
  *
  * @example Basic usage:
@@ -380,13 +380,13 @@ declare class SandboxClient {
  * const vol = await Volume.getOrCreate(projectId, 'agent-scratch', { sizeGb: 10 })
  *
  * const first = await Sandbox.create('codex', { projectId, volumeName: 'agent-scratch' })
- * await first.process.exec('echo "notes" > /data/notes.txt')
+ * await first.process.exec('echo "notes" > /workspace/notes.txt')
  * await first.kill()
  *
  * // A different sandbox, the same disk. No region to thread through: the sandbox
  * // is placed wherever the volume already lives.
  * const second = await Sandbox.create('codex', { projectId, volumeName: 'agent-scratch' })
- * console.log(await second.fs.read('/data/notes.txt')) // "notes"
+ * console.log(await second.fs.read('/workspace/notes.txt')) // "notes"
  * ```
  */
 declare class Sandbox extends SandboxClient {
@@ -1098,6 +1098,12 @@ interface ListTransactionsOpts {
  * a user bills to the account that owns the key. That is what makes per-user
  * workspaces a safe pattern — your users get isolation, you keep one bill — and also
  * what makes {@link Balance.runwayHours} worth watching before you provision more.
+ *
+ * **Requires an unscoped key.** A scoped key is refused with 403
+ * `ACCOUNT_SCOPE_REQUIRED`, because there is no workspace-scoped view of one shared
+ * balance, ledger and set of saved cards — and because a scoped key is meant to be
+ * handed to an end user, who should not be reading your card details or spending
+ * against them. For per-workspace spend, use {@link MetricsAPI.cost} instead.
  */
 declare class BillingAPI {
     private readonly client;
@@ -1281,19 +1287,36 @@ declare class Lizard {
     /**
      * 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.
+     * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
+     * and the key's own `scopes`. The account's email, balance, plan and billing status
+     * are withheld — they belong to the account, not to the key holder, and a scoped key
+     * is meant to be handed to an end user or injected into a sandbox. An unscoped key
+     * or a session sees the full account.
+     *
+     * Reading back `scopes` is the cheapest way to answer "what can this key reach".
      */
     whoami(): Promise<Account>;
     /** The underlying HTTP client, for endpoints this SDK does not wrap yet. */
     get platform(): PlatformClient;
 }
-/** The account behind a credential — see {@link Lizard.whoami}. */
+/**
+ * The account behind a credential — see {@link Lizard.whoami}.
+ *
+ * Everything past `avatarUrl` is present only for an unscoped key or a session; a
+ * scoped key gets `scoped: true` and `scopes` in their place.
+ */
 interface Account {
     id: string;
     username: string;
-    email?: string | null;
     avatarUrl?: string | null;
+    /** True when the calling key is scoped, meaning the account fields below are absent. */
+    scoped?: boolean;
+    /** What the calling key may reach. Present when `scoped` is true. */
+    scopes?: Array<{
+        type: 'workspace' | 'project';
+        id: string;
+    }>;
+    email?: string | null;
     plan?: string;
     billingStatus?: string;
     balanceCents?: number;

package/dist/index.js

@@ -1354,8 +1354,13 @@ var Lizard = class {
   /**
    * 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.
+   * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
+   * and the key's own `scopes`. The account's email, balance, plan and billing status
+   * are withheld — they belong to the account, not to the key holder, and a scoped key
+   * is meant to be handed to an end user or injected into a sandbox. An unscoped key
+   * or a session sees the full account.
+   *
+   * Reading back `scopes` is the cheapest way to answer "what can this key reach".
    */
   async whoami() {
     return this.platform.get("/api/auth/me");

package/dist/index.mjs

@@ -1307,8 +1307,13 @@ var Lizard = class {
   /**
    * 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.
+   * A **scoped** key gets identity only: `id`, `username`, `avatarUrl`, `scoped: true`
+   * and the key's own `scopes`. The account's email, balance, plan and billing status
+   * are withheld — they belong to the account, not to the key holder, and a scoped key
+   * is meant to be handed to an end user or injected into a sandbox. An unscoped key
+   * or a session sees the full account.
+   *
+   * Reading back `scopes` is the cheapest way to answer "what can this key reach".
    */
   async whoami() {
     return this.platform.get("/api/auth/me");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "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",