@aerol-ai/aerolvm-sdk 0.5.4 → 0.7.0

package/dist/MicroVM.d.ts

@@ -1,11 +1,40 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { BuildImageOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "./types.js";
+import type { APITokenList, BuildImageOptions, BuildImageResult, CloneGeneration, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "./types.js";
 type FetchLike = typeof fetch;
+/** Scoped API token calls, reached as `microvm.tokens`. */
+export interface Tokens {
+    /**
+     * Mint a token (admin only). The result's `token` is the secret, returned
+     * this once and never again. A 409 means the name is taken, possibly by an
+     * earlier attempt whose reply was lost; that secret cannot be recovered,
+     * so revoke the token and create it again.
+     */
+    create(options: CreateAPITokenOptions): Promise<CreatedAPIToken>;
+    /** List every token (auditor or admin); expired ones stay listed for 30 days. */
+    list(): Promise<APITokenList>;
+    /** Revoke a token by id (admin only). Revoking one already gone succeeds. */
+    revoke(id: string): Promise<void>;
+}
 export interface MicroVMConfig {
+    /**
+     * The bearer every request carries: the operator PAT, an `avm_` API token
+     * or an OIDC ID token. Defaults to `SB_PAT_TOKEN`, then its alias
+     * `SB_API_TOKEN`; when both are set, `SB_PAT_TOKEN` wins.
+     */
     patToken?: string;
     apiUrl?: string;
+    /**
+     * The team requests act for, sent as the `X-AerolVM-Team` header on every
+     * HTTP request. Defaults to `SB_TEAM`; with neither, no header is sent and
+     * the server uses the credential's first matching binding. The header only
+     * chooses among teams the credential is already bound to (a team it does
+     * not hold is refused with 403), and the operator PAT ignores it.
+     * WebSocket streams (`execStream`, `attachSession`) cannot carry custom
+     * headers from a browser or Node, so they go without it.
+     */
+    team?: string;
     fetch?: FetchLike;
     /**
      * Wire version of the sandbox daemon API to call. Defaults to the SDK's
@@ -16,25 +45,55 @@ export interface MicroVMConfig {
     apiVersion?: APIVersion;
     /**
      * Retry policy for transient transport errors (socket closed, connection
-     * reset) and retryable HTTP status codes (429, 502, 503, 504). The SDK
-     * retries up to 3 times with exponential backoff by default. Pass
-     * `{ maxRetries: 0 }` to disable.
+     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). The SDK
+     * retries up to 3 times with exponential backoff by default. `exec` retries
+     * only failures that prove the command never reached the server
+     * (connection refused, connect timeout, DNS) and HTTP 429/503, so a command
+     * never runs twice. Pass `{ maxRetries: 0 }` to disable. A 429 or 503
+     * waits as long as the server's `Retry-After` asks, up to
+     * `retry.maxRetryAfterMs` (30 s by default).
      */
     retry?: RetryConfig;
+    /**
+     * Cancels the client's HTTP requests: aborting it ends the request in
+     * flight and any retry wait, so a call never sits out a long
+     * `Retry-After` once aborted. Pass `AbortSignal.timeout(ms)` to bound
+     * how long the client may run. WebSocket streams are not affected.
+     */
+    signal?: AbortSignal;
 }
 export declare class MicroVM {
     readonly apiUrl: string;
     readonly patToken: string;
+    /** The team sent as `X-AerolVM-Team`, or `""` when none is. */
+    readonly team: string;
     private readonly client;
     constructor(config?: MicroVMConfig);
     create(options: CreateOptions): Promise<Sandbox>;
     list(options?: ListOptions): Promise<Sandbox[]>;
-    get(id: string): Promise<Sandbox>;
+    /**
+     * Iterates one server page at a time. Use this for large fleet inventories so
+     * the SDK does not retain every sandbox in memory.
+     */
+    listPages(options?: ListOptions): AsyncGenerator<Sandbox[]>;
+    get(id: string, options?: GetOptions): Promise<Sandbox>;
+    /**
+     * Returns the caller's sandbox with this name, or `null` when there is none.
+     * Names are unique per owner. Throws when the server predates name lookup
+     * (it ignores `?name=`), rather than guessing from an unfiltered list.
+     */
+    getByName(name: string, options?: GetOptions): Promise<Sandbox | null>;
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
+    /** Look a snapshot up by name. In a cluster the request is routed to the node holding the image. */
+    getSnapshot(name: string): Promise<SandboxSnapshot>;
+    /** List the caller's snapshots, one name-ordered page at a time. */
+    listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
+    /** Delete a snapshot by name (idempotent 404 if it does not exist). */
+    deleteSnapshot(name: string): Promise<void>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<Sandbox>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<Sandbox>;
@@ -47,6 +106,22 @@ export declare class MicroVM {
      */
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     health(): Promise<HealthStatus>;
+    /**
+     * Asks whether a sandbox created with these egress fields would reach a
+     * destination, using the same matcher the filter enforces. No sandbox is
+     * needed.
+     */
+    checkNetworkPolicy(options: NetworkPolicyCheckOptions): Promise<NetworkPolicyCheckResult>;
+    /**
+     * Creates or replaces a named egress profile (a full replace: the same body
+     * twice is a no-op). Sandboxes reference it through `egressProfiles`, and a
+     * change reaches every one of them.
+     */
+    putEgressProfile(name: string, options: EgressProfileOptions): Promise<EgressProfile>;
+    getEgressProfile(name: string): Promise<EgressProfile>;
+    listEgressProfiles(options?: ListEgressProfilesOptions): Promise<EgressProfileList>;
+    /** Deletes a profile; one that sandboxes still reference is refused (409). */
+    deleteEgressProfile(name: string): Promise<void>;
     mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
     /**
      * Read a sandbox's clone-generation token. The token changes whenever the
@@ -116,6 +191,17 @@ export declare class MicroVM {
     get dns(): {
         target(): Promise<IngressTarget>;
     };
+    /**
+     * Who the server says the caller is: principal, role, team and when the
+     * credential expires. Every valid credential may ask.
+     */
+    whoami(): Promise<WhoAmI>;
+    /**
+     * Scoped API tokens (`avm_…`) for services and CI, as
+     * `microvm.tokens.create/list/revoke`. Same namespaced shape as
+     * {@link MicroVM.dns}.
+     */
+    get tokens(): Tokens;
     private wrap;
 }
 export {};

package/dist/MicroVM.js

@@ -1,25 +1,31 @@
 import { APIClient, stripTrailingSlashes } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 const defaultAPIURL = "http://127.0.0.1:21212";
-const authRequiredErrorMessage = "PAT token is required. Set patToken or SB_PAT_TOKEN.";
+const authRequiredErrorMessage = "PAT token is required. Set patToken, SB_PAT_TOKEN or SB_API_TOKEN.";
 export class MicroVM {
     apiUrl;
     patToken;
+    /** The team sent as `X-AerolVM-Team`, or `""` when none is. */
+    team;
     client;
     constructor(config = {}) {
-        const patToken = config.patToken ?? readEnv("SB_PAT_TOKEN") ?? "";
+        const patToken = config.patToken ?? readEnv("SB_PAT_TOKEN") ?? readEnv("SB_API_TOKEN") ?? "";
         const apiUrl = normalizeURL(config.apiUrl ?? readEnv("SB_API_URL") ?? defaultAPIURL);
+        const team = (config.team ?? readEnv("SB_TEAM") ?? "").trim();
         if (patToken === "") {
             throw new Error(authRequiredErrorMessage);
         }
         this.apiUrl = apiUrl;
         this.patToken = patToken;
+        this.team = team;
         this.client = new APIClient({
             baseURL: apiUrl,
             patToken,
+            team,
             fetch: config.fetch,
             apiVersion: config.apiVersion,
             retry: config.retry,
+            signal: config.signal,
         });
     }
     async create(options) {
@@ -30,10 +36,28 @@ export class MicroVM {
         const sandboxes = await this.client.list(options);
         return sandboxes.map((sandbox) => this.wrap(sandbox.toJSON()));
     }
-    async get(id) {
-        const sandbox = await this.client.get(id);
+    /**
+     * Iterates one server page at a time. Use this for large fleet inventories so
+     * the SDK does not retain every sandbox in memory.
+     */
+    async *listPages(options) {
+        for await (const page of this.client.listPages(options)) {
+            yield page.map((sandbox) => this.wrap(sandbox.toJSON()));
+        }
+    }
+    async get(id, options) {
+        const sandbox = await this.client.get(id, options);
         return this.wrap(sandbox.toJSON());
     }
+    /**
+     * Returns the caller's sandbox with this name, or `null` when there is none.
+     * Names are unique per owner. Throws when the server predates name lookup
+     * (it ignores `?name=`), rather than guessing from an unfiltered list.
+     */
+    async getByName(name, options) {
+        const sandbox = await this.client.getByName(name, options);
+        return sandbox === null ? null : this.wrap(sandbox.toJSON());
+    }
     async start(id) {
         const sandbox = await this.client.start(id);
         return this.wrap(sandbox.toJSON());
@@ -51,6 +75,18 @@ export class MicroVM {
     async registerSnapshotFromImage(name, image, options = {}) {
         return this.client.registerSnapshotFromImage(name, image, options);
     }
+    /** Look a snapshot up by name. In a cluster the request is routed to the node holding the image. */
+    async getSnapshot(name) {
+        return this.client.getSnapshot(name);
+    }
+    /** List the caller's snapshots, one name-ordered page at a time. */
+    async listSnapshots(options = {}) {
+        return this.client.listSnapshots(options);
+    }
+    /** Delete a snapshot by name (idempotent 404 if it does not exist). */
+    async deleteSnapshot(name) {
+        return this.client.deleteSnapshot(name);
+    }
     async destroy(id) {
         await this.client.destroy(id);
     }
@@ -77,6 +113,32 @@ export class MicroVM {
     async health() {
         return this.client.health();
     }
+    /**
+     * Asks whether a sandbox created with these egress fields would reach a
+     * destination, using the same matcher the filter enforces. No sandbox is
+     * needed.
+     */
+    async checkNetworkPolicy(options) {
+        return this.client.checkNetworkPolicy(options);
+    }
+    /**
+     * Creates or replaces a named egress profile (a full replace: the same body
+     * twice is a no-op). Sandboxes reference it through `egressProfiles`, and a
+     * change reaches every one of them.
+     */
+    async putEgressProfile(name, options) {
+        return this.client.putEgressProfile(name, options);
+    }
+    async getEgressProfile(name) {
+        return this.client.getEgressProfile(name);
+    }
+    async listEgressProfiles(options) {
+        return this.client.listEgressProfiles(options);
+    }
+    /** Deletes a profile; one that sandboxes still reference is refused (409). */
+    async deleteEgressProfile(name) {
+        return this.client.deleteEgressProfile(name);
+    }
     async mounts(sandboxID) {
         return this.client.mounts(sandboxID);
     }
@@ -193,6 +255,26 @@ export class MicroVM {
             target: () => client.ingressDNS(),
         };
     }
+    /**
+     * Who the server says the caller is: principal, role, team and when the
+     * credential expires. Every valid credential may ask.
+     */
+    async whoami() {
+        return this.client.whoami();
+    }
+    /**
+     * Scoped API tokens (`avm_…`) for services and CI, as
+     * `microvm.tokens.create/list/revoke`. Same namespaced shape as
+     * {@link MicroVM.dns}.
+     */
+    get tokens() {
+        const client = this.client;
+        return {
+            create: (options) => client.createAPIToken(options),
+            list: () => client.listAPITokens(),
+            revoke: (id) => client.revokeAPIToken(id),
+        };
+    }
     wrap(sandbox) {
         return new Sandbox(this.client, sandbox);
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
-export type { MicroVMConfig } from "./MicroVM.js";
+export type { MicroVMConfig, Tokens } from "./MicroVM.js";
 export type { RetryConfig } from "./internal/client.js";
-export type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";
+export type { AddCustomDomainOptions, APIToken, APITokenList, CreateAPITokenOptions, CreatedAPIToken, WhoAmI, WhoAmIPrincipal, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";

package/dist/internal/client.d.ts

@@ -1,6 +1,11 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, BinaryLike, BuildImageOptions, BuildImageResult, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, ListOptions, MountSpecRedacted, NetworkUsage, RegisterSnapshotOptions, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule } from "../types.js";
+import type { AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "../types.js";
 type FetchLike = typeof fetch;
+/**
+ * The request header that selects which of a credential's teams a request
+ * acts for. Keep in sync with pkg/api.HeaderTeam on the server.
+ */
+export declare const TEAM_HEADER = "X-AerolVM-Team";
 /**
  * Wire version of the v1-style sandbox endpoints (`/v1/sandboxes`, etc.) this
  * client speaks. The SDK and the server version independently — bumping the
@@ -36,10 +41,24 @@ export interface RetryConfig {
      * waits when `maxRetries` is high. Defaults to `5000`.
      */
     maxDelayMs?: number;
+    /**
+     * Cap in milliseconds on the wait before re-sending a 429 or 503. The SDK
+     * waits as long as the server's `Retry-After` header asks (seconds or an
+     * HTTP date), never less than its own backoff, plus up to a fifth more so
+     * clients told the same value spread out; a longer ask is cut to this. A
+     * missing or malformed header uses the backoff above. Defaults to
+     * `30000`; `0` ignores `Retry-After`.
+     */
+    maxRetryAfterMs?: number;
 }
 export interface APIClientConfig {
     baseURL: string;
     patToken?: string;
+    /**
+     * Sent as the {@link TEAM_HEADER} header on every HTTP request. Empty or
+     * absent sends no header.
+     */
+    team?: string;
     fetch?: FetchLike;
     /**
      * Wire version to call. Defaults to "v1". Pin this if you need a specific
@@ -49,11 +68,37 @@ export interface APIClientConfig {
     apiVersion?: APIVersion;
     /**
      * Retry policy for transient transport errors (socket closed, connection
-     * reset) and retryable HTTP status codes (429, 502, 503, 504). Pass
-     * `{ maxRetries: 0 }` to disable retry entirely.
+     * reset) and retryable HTTP status codes (421, 429, 502, 503, 504). `exec`
+     * is narrower: it retries only failures that prove the command never
+     * reached the server (connection refused, connect timeout, DNS) and HTTP
+     * 429/503. Pass `{ maxRetries: 0 }` to disable retry entirely.
      */
     retry?: RetryConfig;
+    /**
+     * Cancels the client's HTTP requests: aborting it ends the request in
+     * flight and any retry wait, so a call never sits out a long
+     * `Retry-After` once aborted. WebSocket streams are not affected.
+     */
+    signal?: AbortSignal;
 }
+/**
+ * Reads a `Retry-After` value in either form RFC 9110 allows: delta-seconds
+ * (`"120"`) or an HTTP date. Returns the wait in milliseconds (0 for a date
+ * already past), or `undefined` for an absent or malformed value.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, nowMs: number): number | undefined;
+/**
+ * How long {@link APIClient.request} waits before re-sending. `attempt`
+ * counts from 0, `retryAfter` is a 429/503's `Retry-After` header (null
+ * otherwise) and `random` is uniform in [0, 1).
+ *
+ * Without a usable header it is the exponential backoff ±25%. With one, it
+ * never retries sooner than the server asked (nor sooner than the backoff)
+ * and adds up to a fifth so clients told the same value spread out.
+ * `maxRetryAfterMs` is a hard ceiling: when the server asks for at least
+ * that long the client is early anyway, so the spread goes below it instead.
+ */
+export declare function retryDelayMs(config: Required<RetryConfig>, attempt: number, retryAfter: string | null, nowMs: number, random: number): number;
 /**
  * Trim trailing slashes from a URL without a backtracking regex. The natural
  * `value.replace(/\/+$/, "")` is an anchored `+` quantifier — a polynomial
@@ -64,9 +109,11 @@ export declare class APIClient {
     readonly baseURL: string;
     readonly apiVersion: APIVersion;
     private readonly patToken;
+    private readonly team;
     private readonly fetchFn;
     private readonly versionPrefix;
     private readonly retryConfig;
+    private readonly signal;
     constructor(config: APIClientConfig);
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -90,12 +137,25 @@ export declare class APIClient {
     buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
     private resolveImage;
     list(options?: ListOptions): Promise<SandboxResource[]>;
-    get(id: string): Promise<SandboxResource>;
+    /** Streams bounded cluster-list pages and never accumulates the full fleet. */
+    listPages(options?: ListOptions): AsyncGenerator<SandboxResource[]>;
+    /**
+     * Looks up the caller's sandbox by name with one request. The reply is only
+     * trusted when it holds at most one sandbox and that sandbox carries the
+     * requested name: a server that predates `?name=` ignores the filter and
+     * returns an ordinary list page, and acting on its first row would target
+     * the wrong sandbox.
+     */
+    getByName(name: string, options?: GetOptions): Promise<SandboxResource | null>;
+    get(id: string, options?: GetOptions): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
     createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
+    getSnapshot(name: string): Promise<SandboxSnapshot>;
+    listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
+    deleteSnapshot(name: string): Promise<void>;
     destroy(id: string): Promise<void>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;
@@ -149,10 +209,18 @@ export declare class APIClient {
     customDomainDNS(id: string): Promise<CustomDomainDNSRecords>;
     reconcile(): Promise<void>;
     health(): Promise<HealthStatus>;
+    checkNetworkPolicy(options: NetworkPolicyCheckOptions): Promise<NetworkPolicyCheckResult>;
     mounts(id: string): Promise<MountSpecRedacted[]>;
     cloneGeneration(id: string): Promise<CloneGeneration>;
     getNetworkUsage(id: string): Promise<NetworkUsage>;
+    getAudit(id: string, options?: AuditOptions): Promise<AuditPage>;
     setNetworkLimits(id: string, options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    setNetworkPolicy(id: string, options: NetworkPolicyOptions): Promise<NetworkPolicy>;
+    getNetworkLearned(id: string): Promise<NetworkLearned>;
+    putEgressProfile(name: string, options: EgressProfileOptions): Promise<EgressProfile>;
+    getEgressProfile(name: string): Promise<EgressProfile>;
+    listEgressProfiles(options?: ListEgressProfilesOptions): Promise<EgressProfileList>;
+    deleteEgressProfile(name: string): Promise<void>;
     createTemplate(options: CreateTemplateOptions): Promise<Template>;
     listTemplates(): Promise<Template[]>;
     getTemplate(id: string): Promise<Template>;
@@ -163,19 +231,31 @@ export declare class APIClient {
     deleteWasmModule(id: string): Promise<void>;
     pushWasmModule(options: PushWasmModuleOptions): Promise<PushWasmModuleResult>;
     rebuildTemplate(id: string): Promise<Template>;
+    whoami(): Promise<WhoAmI>;
+    createAPIToken(options: CreateAPITokenOptions): Promise<CreatedAPIToken>;
+    listAPITokens(): Promise<APITokenList>;
+    revokeAPIToken(id: string): Promise<void>;
     private wrap;
     private doJSON;
     private doBytes;
     /**
      * Low-level HTTP request with automatic retry for transient failures.
      *
-     * Transport-level errors (socket closed, connection reset, DNS blip) are
-     * always retried regardless of HTTP method — the request never reached the
-     * server so there is no idempotency concern.
+     * Transport-level errors (socket closed, connection reset, timeouts, DNS
+     * blip) and HTTP 421/429/502/503/504 are retried regardless of HTTP method.
+     * Several of those failures can happen after the server received the
+     * request, so a retry may deliver it twice; that is safe only because every
+     * mutating endpoint in the daemon is designed for idempotent retry (e.g.
+     * INSERT OR IGNORE + disambiguation).
+     *
+     * A request passed `{ idempotent: false }` (exec) retries only transport
+     * failures that prove the request never left the client and HTTP 429/503;
+     * everything else is surfaced to the caller rather than risk running the
+     * command twice.
      *
-     * HTTP-level retryable codes (429, 502, 503, 504) are retried for ALL
-     * methods because every mutating endpoint in the daemon is already
-     * designed for idempotent retry (e.g. INSERT OR IGNORE + disambiguation).
+     * A 429 or 503 waits as long as its `Retry-After` asks (see
+     * {@link retryDelayMs}). The client's `signal` ends the request and any
+     * wait.
      */
     private request;
 }
@@ -192,6 +272,11 @@ export declare class SandboxResource implements Sandbox {
     osUser: string;
     env?: Record<string, string>;
     networkBlockAll: boolean;
+    egressStatus?: string;
+    egressProfiles?: string[];
+    egressProfilesApplied?: EgressProfileRef[];
+    networkEgressMode?: string;
+    networkEgressRules?: EgressRule[];
     toolboxEnabled: boolean;
     sshPublicKey?: string;
     sshPrivateKey?: string;
@@ -199,6 +284,8 @@ export declare class SandboxResource implements Sandbox {
     createdAt: string;
     updatedAt: string;
     lastActiveAt: string;
+    name?: string;
+    tags?: Record<string, string>;
     lastError?: string;
     containerCommand?: string[];
     lifecycle: Lifecycle;
@@ -251,6 +338,24 @@ export declare class SandboxResource implements Sandbox {
     updateLifecycle(lifecycle: Lifecycle): Promise<this>;
     getNetworkUsage(): Promise<NetworkUsage>;
     setNetworkLimits(options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    /**
+     * Replaces this sandbox's egress policy while it runs. The call returns
+     * once the new policy is enforced; sending the same policy again is a
+     * no-op, so it is safe to retry.
+     */
+    setNetworkPolicy(options: NetworkPolicyOptions): Promise<NetworkPolicy>;
+    /**
+     * Reads what this sandbox reached in learn mode and the allow list that
+     * would have allowed it. A recording stays readable after the sandbox
+     * switches to enforce, until it is destroyed.
+     */
+    learned(): Promise<NetworkLearned>;
+    /**
+     * Reads this sandbox's audit log: outbound connections and egress denials
+     * (`kind: "egress"`), and secret reads. Denials carry `result: "failure"`
+     * and the policy `reason`.
+     */
+    audit(options?: AuditOptions): Promise<AuditPage>;
     toJSON(): Sandbox;
     private apply;
 }