@lizard-build/sdk 0.1.37 → 0.1.39

package/README.md

@@ -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

@@ -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;
@@ -1125,6 +1131,7 @@ interface VolumeInfo {
     createdAt: number;
 }
 interface CreateVolumeOpts extends ConnectionOpts {
+    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Existing volumes are never resized. */
     sizeGb?: number;
     /**
      * Region to place the volume in, e.g. `'us-east-1'`. A volume is node-local, so
@@ -1281,19 +1288,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

@@ -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;
@@ -1125,6 +1131,7 @@ interface VolumeInfo {
     createdAt: number;
 }
 interface CreateVolumeOpts extends ConnectionOpts {
+    /** Whole GB, default 5. New volumes allow 1–50 GB unless the server config sets another maximum. Existing volumes are never resized. */
     sizeGb?: number;
     /**
      * Region to place the volume in, e.g. `'us-east-1'`. A volume is node-local, so
@@ -1281,19 +1288,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.37",
+  "version": "0.1.39",
   "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",