@aerol-ai/aerolvm-sdk 0.8.0 → 0.8.2

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.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";
+import type { APITokenList, CallOptions, DestroyAllOptions, BuildImageOptions, BuildImageResult, CloneGeneration, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, FileEvent, FileWatchHandle, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, IdentityRole, IdentityRoleList, IdentityRoleOptions, ListEgressProfilesOptions, TeamQuota, TeamQuotaOptions, WarmPool, WarmPoolOptions, ListIdentityRolesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RevokeSandboxTokensResult, CreateSnapshotOptions, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WatchFilesOptions, WhoAmI } from "./types.js";
 type FetchLike = typeof fetch;
 /** Scoped API token calls, reached as `microvm.tokens`. */
 export interface Tokens {
@@ -11,11 +11,17 @@ export interface Tokens {
      * earlier attempt whose reply was lost; that secret cannot be recovered,
      * so revoke the token and create it again.
      */
-    create(options: CreateAPITokenOptions): Promise<CreatedAPIToken>;
+    create(options: CreateAPITokenOptions, call?: CallOptions): Promise<CreatedAPIToken>;
     /** List every token (auditor or admin); expired ones stay listed for 30 days. */
-    list(): Promise<APITokenList>;
+    list(call?: CallOptions): Promise<APITokenList>;
     /** Revoke a token by id (admin only). Revoking one already gone succeeds. */
-    revoke(id: string): Promise<void>;
+    revoke(id: string, call?: CallOptions): Promise<void>;
+}
+/** What {@link MicroVM.getOrCreate} found or made. */
+export interface GetOrCreateResult {
+    sandbox: Sandbox;
+    /** True only when this call created the sandbox. */
+    created: boolean;
 }
 export interface MicroVMConfig {
     /**
@@ -58,7 +64,9 @@ export interface MicroVMConfig {
      * 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.
+     * how long the client may run. WebSocket streams are not affected. To
+     * cancel or time-limit one call, pass `{ signal }` as that call's last
+     * argument ({@link CallOptions}).
      */
     signal?: AbortSignal;
 }
@@ -69,76 +77,148 @@ export declare class MicroVM {
     readonly team: string;
     private readonly client;
     constructor(config?: MicroVMConfig);
-    create(options: CreateOptions): Promise<Sandbox>;
-    list(options?: ListOptions): Promise<Sandbox[]>;
+    create(options: CreateOptions, call?: CallOptions): Promise<Sandbox>;
+    list(options?: ListOptions, call?: CallOptions): 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>;
+    listPages(options?: ListOptions, call?: CallOptions): AsyncGenerator<Sandbox[]>;
+    get(id: string, options?: GetOptions, call?: CallOptions): 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>;
+    getByName(name: string, options?: GetOptions, call?: CallOptions): Promise<Sandbox | null>;
+    /**
+     * Returns the caller's sandbox called `name`, creating it from `options`
+     * when there is none. `created` is true only when this call made the
+     * sandbox. Safe to retry and to run at the same time from many processes:
+     * names are unique per owner, so when two callers race to create the same
+     * name, one gets a 409 and reads the winner's sandbox instead. An existing
+     * sandbox is returned as it is; its image and settings are not compared
+     * with `options`.
+     */
+    getOrCreate(name: string, options: CreateOptions, call?: CallOptions): Promise<GetOrCreateResult>;
+    start(id: string, call?: CallOptions): Promise<Sandbox>;
+    stop(id: string, call?: CallOptions): Promise<Sandbox>;
+    createSnapshot(id: string, name: string, options?: CreateSnapshotOptions, call?: CallOptions): Promise<SandboxSnapshot>;
+    registerSnapshot(options: RegisterSnapshotOptions, call?: CallOptions): Promise<SandboxSnapshot>;
+    registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">, call?: CallOptions): 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>;
+    getSnapshot(name: string, call?: CallOptions): Promise<SandboxSnapshot>;
     /** List the caller's snapshots, one name-ordered page at a time. */
-    listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
+    listSnapshots(options?: ListSnapshotsOptions, call?: CallOptions): 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>;
-    reconcile(): Promise<void>;
+    deleteSnapshot(name: string, call?: CallOptions): Promise<void>;
+    destroy(id: string, call?: CallOptions): Promise<void>;
+    /**
+     * Deletes every sandbox of yours that carries all of `options.tags` and
+     * returns the IDs of the ones now gone. It lists every page first, then
+     * deletes them one at a time. A sandbox that is already gone (404) counts
+     * as deleted, so a second call, or two calls at once, is safe. Any other
+     * failed delete stops the call and is thrown; the sandboxes already
+     * deleted stay deleted, and calling it again finishes the job. `tags`
+     * must not be empty.
+     */
+    destroyAll(options: DestroyAllOptions, call?: CallOptions): Promise<string[]>;
+    resize(id: string, options: ResizeOptions, call?: CallOptions): Promise<Sandbox>;
+    updateLifecycle(id: string, lifecycle: Lifecycle, call?: CallOptions): Promise<Sandbox>;
+    reconcile(call?: CallOptions): Promise<void>;
     /**
      * Build an {@link Image} on the daemon and optionally push the result to a
      * remote registry. Push credentials are forwarded per request and never
      * persisted by the daemon. Returns the local content-addressed tag and,
      * when push was requested, the pushed reference.
      */
-    buildImage(image: Image, options?: BuildImageOptions): Promise<BuildImageResult>;
-    health(): Promise<HealthStatus>;
+    buildImage(image: Image, options?: BuildImageOptions, call?: CallOptions): Promise<BuildImageResult>;
+    health(call?: CallOptions): 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>;
+    checkNetworkPolicy(options: NetworkPolicyCheckOptions, call?: CallOptions): 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>;
+    putEgressProfile(name: string, options: EgressProfileOptions, call?: CallOptions): Promise<EgressProfile>;
+    getEgressProfile(name: string, call?: CallOptions): Promise<EgressProfile>;
+    listEgressProfiles(options?: ListEgressProfilesOptions, call?: CallOptions): Promise<EgressProfileList>;
     /** Deletes a profile; one that sandboxes still reference is refused (409). */
-    deleteEgressProfile(name: string): Promise<void>;
-    mounts(sandboxID: string): Promise<MountSpecRedacted[]>;
+    deleteEgressProfile(name: string, call?: CallOptions): Promise<void>;
+    /**
+     * Sets how many ready sandboxes every server with a warm pool keeps for an
+     * image (a full replace: the same call twice is a no-op). A create that names
+     * the image then starts from a warm sandbox. Admin only.
+     */
+    putWarmPool(image: string, options: WarmPoolOptions, call?: CallOptions): Promise<WarmPool>;
+    /** Returns an image's warm-pool entry with its status (ready and target, per server). */
+    getWarmPool(image: string, call?: CallOptions): Promise<WarmPool>;
+    /** Returns every warm-pool entry, by image, with its status. */
+    listWarmPools(call?: CallOptions): Promise<WarmPool[]>;
+    /** Deletes an image's warm-pool entry; its warm sandboxes are removed. Deleting a missing entry succeeds. */
+    deleteWarmPool(image: string, call?: CallOptions): Promise<void>;
+    /**
+     * Puts a role tag on a team's cloud identity allow list, or changes its
+     * minimum caller role (`"runner"` or `"admin"`). Admin only. The same call
+     * twice changes nothing, so it is safe to retry.
+     */
+    putIdentityRole(tag: string, options: IdentityRoleOptions, call?: CallOptions): Promise<IdentityRole>;
+    /** Lists a team's cloud identity allow list, one page at a time. Admin only. */
+    listIdentityRoles(options?: ListIdentityRolesOptions, call?: CallOptions): Promise<IdentityRoleList>;
+    /**
+     * Takes a role tag off a team's allow list. Admin only. Sandboxes that use
+     * it keep their current token (at most one hour) and get no new one.
+     * Deleting a tag that is already gone succeeds.
+     */
+    deleteIdentityRole(tag: string, options?: {
+        team?: string;
+    }, call?: CallOptions): Promise<void>;
+    /**
+     * Sets a team's quota: the most sandboxes, CPU and memory its sandboxes
+     * may hold. Admin only. The same limits twice change nothing. A create,
+     * resize or start past the quota fails with 429 `team_quota_exceeded`.
+     */
+    putTeamQuota(team: string, options: TeamQuotaOptions, call?: CallOptions): Promise<TeamQuota>;
+    /** Reads a team's quota and what the team holds now. 404 if it has none. */
+    getTeamQuota(team: string, call?: CallOptions): Promise<TeamQuota>;
+    /** Removes a team's quota. Removing one that is already gone succeeds. */
+    deleteTeamQuota(team: string, call?: CallOptions): Promise<void>;
+    mounts(sandboxID: string, call?: CallOptions): Promise<MountSpecRedacted[]>;
+    /**
+     * Make every token issued for a sandbox so far stop working (see
+     * `sandbox.revokeTokens()`). A token made after the call works.
+     */
+    revokeSandboxTokens(sandboxID: string, call?: CallOptions): Promise<RevokeSandboxTokensResult>;
     /**
      * Read a sandbox's clone-generation token. The token changes whenever the
      * sandbox is resumed from a snapshot, so a change signals "this is a clone."
      * Read-only — the SDK cannot reseed a process inside the guest; see the
      * "Randomness in cloned sandboxes" docs page for the in-guest reseed pattern.
      */
-    cloneGeneration(sandboxID: string): Promise<CloneGeneration>;
+    cloneGeneration(sandboxID: string, call?: CallOptions): Promise<CloneGeneration>;
     execStream(sandboxID: string, options: ExecStreamOptions): ExecStreamHandle;
-    createSession(sandboxID: string, options: CreateSessionOptions): Promise<Session>;
-    listSessions(sandboxID: string): Promise<Session[]>;
-    getSession(sandboxID: string, sessionID: string): Promise<Session>;
-    deleteSession(sandboxID: string, sessionID: string): Promise<void>;
-    signalSession(sandboxID: string, sessionID: string, signal: string): Promise<void>;
-    resizeSession(sandboxID: string, sessionID: string, cols: number, rows: number): Promise<void>;
-    sessionLog(sandboxID: string, sessionID: string): Promise<Uint8Array>;
-    sessionRecording(sandboxID: string, sessionID: string): Promise<Uint8Array>;
+    /**
+     * Watch a folder in a sandbox for changes: `onEvent` gets each create,
+     * write, remove, rename and chmod, in batches every 250 ms. Resolves once
+     * the watch is in place. gVisor and Firecracker sandboxes only; Docker,
+     * containerd, WASM and isolate sandboxes reject with a 501
+     * `MicroVMApiError`. A sandbox whose agent predates file watching rejects
+     * with `MicroVMUnsupportedFeatureError`.
+     */
+    watchFiles(sandboxID: string, path: string, onEvent: (event: FileEvent) => void, options?: WatchFilesOptions): Promise<FileWatchHandle>;
+    createSession(sandboxID: string, options: CreateSessionOptions, call?: CallOptions): Promise<Session>;
+    listSessions(sandboxID: string, call?: CallOptions): Promise<Session[]>;
+    getSession(sandboxID: string, sessionID: string, call?: CallOptions): Promise<Session>;
+    deleteSession(sandboxID: string, sessionID: string, call?: CallOptions): Promise<void>;
+    signalSession(sandboxID: string, sessionID: string, signal: string, call?: CallOptions): Promise<void>;
+    resizeSession(sandboxID: string, sessionID: string, cols: number, rows: number, call?: CallOptions): Promise<void>;
+    sessionLog(sandboxID: string, sessionID: string, call?: CallOptions): Promise<Uint8Array>;
+    sessionRecording(sandboxID: string, sessionID: string, call?: CallOptions): Promise<Uint8Array>;
     attachSession(sandboxID: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
     /**
      * Register a Firecracker rootfs template. Returns immediately with a
@@ -150,25 +230,25 @@ export declare class MicroVM {
      * duplicate ID returns 409 so a retried CI step does not create two
      * rows for the same logical template.
      */
-    createTemplate(options: CreateTemplateOptions): Promise<Template>;
-    listTemplates(): Promise<Template[]>;
-    getTemplate(id: string): Promise<Template>;
-    deleteTemplate(id: string): Promise<void>;
+    createTemplate(options: CreateTemplateOptions, call?: CallOptions): Promise<Template>;
+    listTemplates(call?: CallOptions): Promise<Template[]>;
+    getTemplate(id: string, call?: CallOptions): Promise<Template>;
+    deleteTemplate(id: string, call?: CallOptions): Promise<void>;
     /**
      * Register a WASM module in the host catalogue. Resolution is synchronous —
      * the returned row is typically already `ready`. Use the row's `id` or
      * `moduleRef` on subsequent `create` calls with `runtime: "wasm"`.
      */
-    createWasmModule(options: CreateWasmModuleOptions): Promise<WasmModule>;
-    listWasmModules(): Promise<WasmModule[]>;
-    getWasmModule(id: string): Promise<WasmModule>;
-    deleteWasmModule(id: string): Promise<void>;
+    createWasmModule(options: CreateWasmModuleOptions, call?: CallOptions): Promise<WasmModule>;
+    listWasmModules(call?: CallOptions): Promise<WasmModule[]>;
+    getWasmModule(id: string, call?: CallOptions): Promise<WasmModule>;
+    deleteWasmModule(id: string, call?: CallOptions): Promise<void>;
     /**
      * Upload a compiled core-wasip1 module to the registry under your own
      * credentials and get back the `oci://` ref to use as `moduleRef` on create.
      * The daemon validates and forwards the bytes; it never stores them.
      */
-    pushWasmModule(options: PushWasmModuleOptions): Promise<PushWasmModuleResult>;
+    pushWasmModule(options: PushWasmModuleOptions, call?: CallOptions): Promise<PushWasmModuleResult>;
     /**
      * Re-run the snapshot phase against an existing template. Idempotent
      * under concurrent retry: the daemon's CAS collapses N parallel calls
@@ -180,7 +260,7 @@ export declare class MicroVM {
      * where rebuild is not safe (build in flight) or not supported
      * (`ready_no_snapshot` / `failed` — those need delete+recreate today).
      */
-    rebuildTemplate(id: string): Promise<Template>;
+    rebuildTemplate(id: string, call?: CallOptions): Promise<Template>;
     /**
      * Cluster-level DNS helpers. Exposed as a namespaced accessor (rather
      * than a flat `ingressDNS()` method) so call sites read like
@@ -189,19 +269,21 @@ export declare class MicroVM {
      * see the current client even if MicroVM is later extended.
      */
     get dns(): {
-        target(): Promise<IngressTarget>;
+        target(call?: CallOptions): 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>;
+    whoami(call?: CallOptions): 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;
+    /** The client for one call: the real one, or a view carrying the call's signal. */
+    private clientFor;
     private wrap;
 }
 export {};