withruntime 0.5.1 → 0.6.0

package/dist/products/network-products.js

@@ -0,0 +1,82 @@
+const enc = encodeURIComponent;
+/** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
+export function domains(t) {
+    return {
+        /** Claims the hostname and answers the DNS records to set. Calling it again
+         * with another sandbox or port points the name there. */
+        add: (input, options) => t.json({ method: "POST", path: "/v1/domains", body: input, ...options }),
+        /** Checks the TXT record now; the name goes live when it matches. */
+        verify: (hostname, options) => t.json({
+            method: "POST",
+            path: `/v1/domains/${enc(hostname)}:verify`,
+            ...options,
+        }),
+        get: (hostname, options) => t.json({ method: "GET", path: `/v1/domains/${enc(hostname)}`, ...options }),
+        list: async (options) => (await t.json({ method: "GET", path: "/v1/domains", ...options })).data,
+        remove: (hostname, options) => t.json({
+            method: "DELETE",
+            path: `/v1/domains/${enc(hostname)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.ports`: a public TCP port to a port of a sandbox. */
+export function ports(t) {
+    return {
+        /** Returns the same public port when called again for the same sandbox and port. */
+        open: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/ports",
+            body: input,
+            ...options,
+        }),
+        list: async (filter = {}, options) => (await t.json({
+            method: "GET",
+            path: `/v1/ports${filter.sandboxId ? `?sandboxId=${enc(filter.sandboxId)}` : ""}`,
+            ...options,
+        })).data,
+        close: (portId, options) => t.json({
+            method: "DELETE",
+            path: `/v1/ports/${enc(portId)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.addresses`: a dedicated outbound address every sandbox of the
+ * account sends from, for allow-lists. */
+export function addresses(t) {
+    return {
+        reserve: (input = {}, options) => t.json({ method: "POST", path: "/v1/addresses", body: input, ...options }),
+        list: async (options) => (await t.json({ method: "GET", path: "/v1/addresses", ...options }))
+            .data,
+        release: (addressId, options) => t.json({
+            method: "DELETE",
+            path: `/v1/addresses/${enc(addressId)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.tunnel`: a WireGuard tunnel from your own network into your sandboxes. */
+export function tunnel(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/tunnel", ...options }),
+        /** Idempotent: returns the tunnel you have. */
+        create: (input = {}, options) => t.json({ method: "POST", path: "/v1/tunnel", body: input, ...options }),
+        delete: (options) => t.json({ method: "DELETE", path: "/v1/tunnel", ...options }),
+        /** Leave publicKey out and Runtime generates the pair; the private key is
+         * then in `config`, shown once. */
+        addPeer: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/tunnel/peers",
+            body: input,
+            ...options,
+        }),
+        rotatePeer: (peerId, input = {}, options) => t.json({
+            method: "POST",
+            path: `/v1/tunnel/peers/${enc(peerId)}:rotate`,
+            body: input,
+            ...options,
+        }),
+        removePeer: (peerId, options) => t.json({ method: "DELETE", path: `/v1/tunnel/peers/${enc(peerId)}`, ...options }),
+    };
+}

package/dist/products/network.d.ts

@@ -24,7 +24,7 @@ export type NetworkPolicy = Required<NetworkRules> & {
     /** Ports reachable without a connect entry. */
     ports: number[];
     connectAllowed: boolean;
-    /** paid, granted, not_paid, revoked or suspended. */
+    /** paid, granted, not_paid, revoked, suspended, or trial (a trial sandbox reaches ports 80 and 443 only). */
     connectReason: string;
     forbiddenPorts: number[];
     updatedAt: string | null;

package/dist/products/sso.d.ts

@@ -0,0 +1,44 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** One identity provider of the account. */
+export type SsoConnection = {
+    id: string;
+    /** Names the connection in its sign-in URLs. */
+    providerId: string;
+    protocol: "oidc" | "saml";
+    provider: "okta" | "entra" | "google" | "other";
+    /** The email domain it answers for. */
+    domain: string;
+    /** When DNS proved the domain; null until then, and nobody signs in until then. */
+    domainVerifiedAt: string | null;
+    /** The TXT record that proves the domain. */
+    verification: {
+        type: "TXT";
+        name: string;
+        value: string;
+    };
+    defaultRole: "admin" | "developer" | "billing";
+    /** Members other than owners sign in only through it. API keys are unaffected. */
+    requireSso: boolean;
+    createdAt: string;
+};
+export type SsoStatus = {
+    connections: SsoConnection[];
+    scim: {
+        tokens: number;
+        users: number;
+        activeUsers: number;
+        groups: {
+            id: string;
+            displayName: string;
+            role: string | null;
+        }[];
+    };
+    /** Where an owner changes single sign-on. */
+    manage: string;
+};
+/** `runtime.sso.get()`: the account's single sign-on and SCIM directory sync.
+ * Read only; an owner changes it on the website. Needs a key made by an owner
+ * or admin. */
+export declare function sso(t: Transport): {
+    get: (options?: RequestOptions) => Promise<SsoStatus>;
+};

package/dist/products/sso.js

@@ -0,0 +1,8 @@
+/** `runtime.sso.get()`: the account's single sign-on and SCIM directory sync.
+ * Read only; an owner changes it on the website. Needs a key made by an owner
+ * or admin. */
+export function sso(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/sso", ...options }),
+    };
+}

package/dist/products/volumes.d.ts

@@ -13,8 +13,16 @@ export type Volume = {
     filesystem: "ext4";
     usedMiB: number | null;
     measuredAt: string | null;
-    /** Always false: a volume lives on one host and is not copied off it. */
-    backedUp: false;
+    /** True once a backup of it has been copied off its host and checked. */
+    backedUp: boolean;
+    /** Daily backups, how long each is kept, and when the newest was taken. */
+    backups: {
+        daily: boolean;
+        retentionDays: number;
+        lastReadyAt: string | null;
+    };
+    /** The backup this volume was restored from, if any. */
+    restoredFrom: string | null;
     attachments: {
         sandboxId: string;
         mode: "rw" | "snapshot";
@@ -26,15 +34,42 @@ export type Volume = {
     readyAt: string | null;
 };
 export type CreateVolume = {
-    sizeMiB: number;
+    /** Required unless restoring: a restore is the backup's size. */
+    sizeMiB?: number;
+    /** A ready backup to restore into the new volume, on any host in its region. */
+    fromBackup?: string;
     name?: string;
     labels?: Record<string, string>;
     region?: string;
 };
+export type VolumeBackupState = "pending" | "ready" | "failed" | "deleting" | "deleted";
+/** A point-in-time copy of a volume, kept off its host. */
+export type VolumeBackup = {
+    id: string;
+    kind: "volume-backup";
+    status: string;
+    state: VolumeBackupState;
+    name: string | null;
+    labels: Record<string, string>;
+    region: string;
+    volumeId: string;
+    sizeMiB: number;
+    trigger: "manual" | "daily";
+    retentionDays: number;
+    logicalBytes: number | null;
+    storedBytes: number | null;
+    meteredBytes: number | null;
+    error: string | null;
+    createdAt: string;
+    readyAt: string | null;
+    expiresAt: string;
+};
 /** Persistent disks: create once, attach when creating a sandbox with
- * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
+ * daily unless that is turned off; restore one with `create({ fromBackup })`. */
 export declare function volumes(t: Transport): {
-    /** Create and wait (up to 10 s) until it is ready. */
+    /** Create and wait (up to 10 s) until it is ready. With `fromBackup`, a
+     * restore; it is ready once the backup is downloaded and checked. */
     create: (input: CreateVolume, options?: RequestOptions) => Promise<Volume>;
     get: (id: string, options?: RequestOptions) => Promise<Volume>;
     list: (query?: {
@@ -44,4 +79,32 @@ export declare function volumes(t: Transport): {
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Volume>>;
     delete: (id: string, options?: RequestOptions) => Promise<Volume>;
+    /** Back a volume up now, off its host, and wait (up to a minute, or
+     * `wait` seconds) for it to be ready. */
+    backup: (id: string, input?: {
+        name?: string;
+        labels?: Record<string, string>;
+        retentionDays?: number;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeBackup>;
+    /** Daily backups on or off, and how many days each is kept. */
+    setBackupPolicy: (id: string, input: {
+        daily?: boolean;
+        retentionDays?: number;
+    }, options?: RequestOptions) => Promise<Volume>;
+    /** Backups, newest first; `{ volumeId }` for one volume's. */
+    backups: (query?: {
+        volumeId?: string;
+        state?: Exclude<VolumeBackupState, "deleted">;
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<Page<VolumeBackup>>;
+    getBackup: (id: string, options?: RequestOptions) => Promise<VolumeBackup>;
+    deleteBackup: (id: string, options?: RequestOptions) => Promise<VolumeBackup>;
+    /** A new volume from a backup: `create({ fromBackup: id })`. */
+    restore: (backupId: string, input?: {
+        name?: string;
+        labels?: Record<string, string>;
+    }, options?: RequestOptions) => Promise<Volume>;
 };

package/dist/products/volumes.js

@@ -1,8 +1,10 @@
 import { Page } from "../page.js";
+const enc = encodeURIComponent;
 /** Persistent disks: create once, attach when creating a sandbox with
- * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
+ * daily unless that is turned off; restore one with `create({ fromBackup })`. */
 export function volumes(t) {
-    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${encodeURIComponent(id)}`, ...options });
+    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${enc(id)}`, ...options });
     const list = async (query = {}, options) => {
         const page = await t.json({
             method: "GET",
@@ -12,16 +14,62 @@ export function volumes(t) {
         });
         return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
     };
+    const backups = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/volume-backups",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => backups({ ...query, cursor }, options));
+    };
     return {
-        /** Create and wait (up to 10 s) until it is ready. */
+        /** Create and wait (up to 10 s) until it is ready. With `fromBackup`, a
+         * restore; it is ready once the backup is downloaded and checked. */
         create: (input, options) => t.json({ method: "POST", path: "/v1/volumes", body: input, wait: 10, ...options }),
         get,
         list,
         delete: (id, options) => t.json({
             method: "POST",
-            path: `/v1/volumes/${encodeURIComponent(id)}:delete`,
+            path: `/v1/volumes/${enc(id)}:delete`,
             body: {},
             ...options,
         }),
+        /** Back a volume up now, off its host, and wait (up to a minute, or
+         * `wait` seconds) for it to be ready. */
+        backup: (id, input = {}, options = {}) => {
+            const { wait = 60, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:backup`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        /** Daily backups on or off, and how many days each is kept. */
+        setBackupPolicy: (id, input, options) => t.json({
+            method: "POST",
+            path: `/v1/volumes/${enc(id)}:backup-policy`,
+            body: input,
+            ...options,
+        }),
+        /** Backups, newest first; `{ volumeId }` for one volume's. */
+        backups,
+        getBackup: (id, options) => t.json({ method: "GET", path: `/v1/volume-backups/${enc(id)}`, ...options }),
+        deleteBackup: (id, options) => t.json({
+            method: "POST",
+            path: `/v1/volume-backups/${enc(id)}:delete`,
+            body: {},
+            ...options,
+        }),
+        /** A new volume from a backup: `create({ fromBackup: id })`. */
+        restore: (backupId, input = {}, options) => t.json({
+            method: "POST",
+            path: "/v1/volumes",
+            body: { ...input, fromBackup: backupId },
+            wait: 10,
+            ...options,
+        }),
     };
 }

package/dist/products/watch.d.ts

@@ -0,0 +1,91 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod";
+export type FileEvent = {
+    type: FileEventType;
+    /** Absolute path in the sandbox. */
+    path: string;
+    isDir: boolean;
+    /** rename: where it was. */
+    oldPath?: string;
+    /** write: how many writes were folded into this one event. */
+    count?: number;
+};
+export type WatchNotice = {
+    k: "overflow";
+    dropped: number | null;
+    reason: "kernel" | "rate";
+} | {
+    k: "limit";
+    watches: number;
+} | {
+    k: "lost";
+    bytes: number;
+};
+export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
+    recursive?: boolean;
+    /** Only these event types; all five by default. */
+    events?: FileEventType[];
+    /** Globs relative to the path: only matching paths are reported. */
+    include?: string[];
+    /** Globs relative to the path. An excluded directory is not watched at all. */
+    exclude?: string[];
+    /** Events are gathered this long and delivered together. Default 100. */
+    batchMs?: number;
+    /** The watch ends by itself after running this long. Default 1 hour. */
+    timeoutMs?: number;
+    maxWatches?: number;
+    /** A batch at a time, rather than one call per event. */
+    onBatch?: (events: FileEvent[]) => void | Promise<void>;
+    /** Events were lost (a flood past the rate cap, the kernel's queue, or a
+     * reader that fell more than 1 MiB behind): rescan what you care about. */
+    onNotice?: (notice: WatchNotice) => void;
+    /** The watch stopped: "stopped", "timeout", "root-removed", or "paused"
+     * (the sandbox paused; call `resume()` once it runs again: nothing is lost). */
+    onExit?: (reason: string) => void;
+};
+export type WatchInfo = {
+    id: string;
+    path: string;
+    processId: string;
+    state: string;
+    startedAt: number;
+};
+/** A running watch. Events arrive through the callbacks until `stop()`. */
+export declare class WatchHandle {
+    #private;
+    private readonly t;
+    private readonly base;
+    readonly id: string;
+    readonly path: string;
+    private readonly options;
+    private readonly onEvent?;
+    cursor: number;
+    constructor(t: Transport, base: string, id: string, path: string, cursor: number, options: WatchOptions, onEvent?: ((event: FileEvent) => void | Promise<void>) | undefined);
+    /** Settles when the watch stops delivering (stopped, ended or paused). */
+    get done(): Promise<void>;
+    /** Start delivering again from where it left off, after a pause. */
+    resume(): void;
+    /** Stop the watch in the sandbox, and stop delivering. */
+    stop(options?: RequestOptions): Promise<void>;
+    /** @internal */
+    begin(): this;
+}
+/** `sbx.files.watch(path, onEvent, options)`: E2B's `watchDir`, with
+ * filters, batches, and a watch that survives a pause without losing events. */
+export declare function watchDirectory(t: Transport, sandboxId: string, path: string, onEvent?: (event: FileEvent) => void | Promise<void>, options?: WatchOptions): Promise<WatchHandle>;
+export declare function sandboxWatches(t: Transport, sandboxId: string): {
+    list: (options?: RequestOptions) => Promise<WatchInfo[]>;
+    /** Events after a cursor, without a stream: for polling. */
+    read: (id: string, cursor?: number, input?: {
+        waitMs?: number;
+    }, options?: RequestOptions) => Promise<{
+        events: FileEvent[];
+        notices: Record<string, unknown>[];
+        nextCursor: number;
+        lostBytes: number;
+        ended: boolean;
+    }>;
+    stop: (id: string, options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/watch.js

@@ -0,0 +1,135 @@
+/** A running watch. Events arrive through the callbacks until `stop()`. */
+export class WatchHandle {
+    t;
+    base;
+    id;
+    path;
+    options;
+    onEvent;
+    cursor;
+    #stopped = false;
+    #following;
+    #abort = new AbortController();
+    constructor(t, base, id, path, cursor, options, onEvent) {
+        this.t = t;
+        this.base = base;
+        this.id = id;
+        this.path = path;
+        this.options = options;
+        this.onEvent = onEvent;
+        this.cursor = cursor;
+    }
+    /** Settles when the watch stops delivering (stopped, ended or paused). */
+    get done() {
+        return this.#following ?? Promise.resolve();
+    }
+    /** Start delivering again from where it left off, after a pause. */
+    resume() {
+        if (this.#stopped)
+            throw new Error("This watch was stopped");
+        this.#abort = new AbortController();
+        this.begin();
+    }
+    /** Stop the watch in the sandbox, and stop delivering. */
+    async stop(options) {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#abort.abort();
+        await this.t
+            .json({ method: "DELETE", path: `${this.base}/${encodeURIComponent(this.id)}`, ...options })
+            .catch(() => undefined);
+        await this.#following?.catch(() => undefined);
+        this.options.onExit?.("stopped");
+    }
+    async #follow() {
+        for (;;) {
+            let next = "exit";
+            try {
+                for await (const event of this.t.events({
+                    method: "GET",
+                    path: `${this.base}/${encodeURIComponent(this.id)}/events`,
+                    query: { cursor: this.cursor, follow: true },
+                    signal: this.#abort.signal,
+                    timeoutMs: 150_000,
+                })) {
+                    this.cursor = event.cursor ?? this.cursor;
+                    if (event.k === "events") {
+                        if (this.options.onBatch)
+                            await this.options.onBatch(event.events);
+                        if (this.onEvent)
+                            for (const item of event.events)
+                                await this.onEvent(item);
+                    }
+                    else if (event.k === "continue")
+                        next = "continue";
+                    else if (event.k === "end" || event.k === "paused") {
+                        if (!this.#stopped)
+                            this.options.onExit?.(event.k === "paused" ? "paused" : event.reason);
+                        return;
+                    }
+                    else if (event.k === "failure")
+                        throw new Error(`${event.code}: ${event.message}`);
+                    else
+                        this.options.onNotice?.(event);
+                }
+            }
+            catch (error) {
+                if (this.#stopped || this.#abort.signal.aborted)
+                    return;
+                throw error;
+            }
+            if (next !== "continue" || this.#stopped)
+                return;
+        }
+    }
+    /** @internal */
+    begin() {
+        this.#following = this.#follow();
+        // An error surfaces through `done`; nothing is left unhandled meanwhile.
+        this.#following.catch(() => undefined);
+        return this;
+    }
+}
+/** `sbx.files.watch(path, onEvent, options)`: E2B's `watchDir`, with
+ * filters, batches, and a watch that survives a pause without losing events. */
+export function watchDirectory(t, sandboxId, path, onEvent, options = {}) {
+    const base = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/files/watches`;
+    const { recursive, events, include, exclude, batchMs, timeoutMs, maxWatches, idempotencyKey, signal, } = options;
+    return t
+        .json({
+        method: "POST",
+        path: base,
+        body: {
+            path,
+            ...(recursive !== undefined ? { recursive } : {}),
+            ...(events ? { events } : {}),
+            ...(include ? { include } : {}),
+            ...(exclude ? { exclude } : {}),
+            ...(batchMs !== undefined ? { batchMs } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(maxWatches !== undefined ? { maxWatches } : {}),
+        },
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+        ...(signal ? { signal } : {}),
+    })
+        .then((watch) => new WatchHandle(t, base, watch.id, watch.path, watch.cursor ?? 0, options, onEvent).begin());
+}
+export function sandboxWatches(t, sandboxId) {
+    const base = `/v1/sandboxes/${encodeURIComponent(sandboxId)}/files/watches`;
+    return {
+        list: async (options) => (await t.json({ method: "GET", path: base, ...options })).data,
+        /** Events after a cursor, without a stream: for polling. */
+        read: (id, cursor = 0, input = {}, options) => t.json({
+            method: "GET",
+            path: `${base}/${encodeURIComponent(id)}/events`,
+            query: { cursor, ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}) },
+            ...options,
+        }),
+        stop: (id, options) => t.json({
+            method: "DELETE",
+            path: `${base}/${encodeURIComponent(id)}`,
+            ...options,
+        }),
+    };
+}

package/dist/sandbox.d.ts

@@ -1,4 +1,5 @@
 import { Page } from "./page.js";
+import { type FileEvent, type WatchHandle, type WatchOptions } from "./products/watch.js";
 import type { RequestOptions, Transport } from "./transport.js";
 import type { CommandResult, ExecOptions, FileEntry, OutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
@@ -175,12 +176,41 @@ export declare class Files {
     private readonly t;
     private readonly sandboxId;
     constructor(t: Transport, sandboxId: string);
+    /** Watch a directory: `onEvent` gets create, write, remove, rename and
+     * chmod events until `handle.stop()`. E2B's `watchDir`, plus filters,
+     * batches, and a watch that loses nothing across a pause:
+     *
+     *   const watch = await sbx.files.watch("/workspace", (e) => console.log(e.type, e.path),
+     *     { recursive: true, exclude: ["node_modules"] });
+     *   ...
+     *   await watch.stop();
+     */
+    watch(path: string, onEvent?: (event: FileEvent) => void | Promise<void>, options?: WatchOptions): Promise<WatchHandle>;
+    /** The watches running in the sandbox, and polling reads by cursor. */
+    get watches(): {
+        list: (options?: RequestOptions) => Promise<import("./products/watch.js").WatchInfo[]>;
+        read: (id: string, cursor?: number, input?: {
+            waitMs?: number;
+        }, options?: RequestOptions) => Promise<{
+            events: FileEvent[];
+            notices: Record<string, unknown>[];
+            nextCursor: number;
+            lostBytes: number;
+            ended: boolean;
+        }>;
+        stop: (id: string, options?: RequestOptions) => Promise<{
+            stopped: boolean;
+        }>;
+    };
     /** A file's bytes, any size. */
     read(path: string, options?: RequestOptions): Promise<Uint8Array>;
     readText(path: string, options?: RequestOptions): Promise<string>;
     /** Writes a file of any size, atomically, making parent directories. Large
-     * ones go in parallel 1 MiB chunks checked against their SHA-256. */
-    write(path: string, data: string | Uint8Array, options?: RequestOptions): Promise<{
+     * ones go in parallel 1 MiB chunks checked against their SHA-256. `mode`
+     * sets its permissions (0o755 for a program); 0o644 when left out. */
+    write(path: string, data: string | Uint8Array, writeOptions?: RequestOptions & {
+        mode?: number;
+    }): Promise<{
         path: string;
         size: number;
     }>;