withruntime 0.11.2 → 0.12.0

package/dist/codesandbox/index.d.ts

@@ -1,6 +1,6 @@
 import type { Runtime } from "../client.js";
 import type { Sandbox as NativeSandbox, Process } from "../sandbox.js";
-import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+import { CompatibilityError, type ClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 import { ManagedTasks } from "./guest-service.js";
 export { CompatibilityError };
 export declare class VMTier {
@@ -24,19 +24,39 @@ export declare class VMTier {
         diskGB?: number;
     }): VMTier | undefined;
 }
-export type CreateSandboxOpts = {
+export type StartSandboxOpts = {
+    vmTier?: VMTier;
+    hibernationTimeoutSeconds?: number;
+    /** Runtime wakes a paused sandbox on any request, preview visit, command or
+     * file call: both true or both false. */
+    automaticWakeupConfig?: {
+        http: boolean;
+        websocket: boolean;
+    };
+    ipcountry?: string;
+};
+export type CreateSandboxOpts = StartSandboxOpts & {
     id?: string;
     title?: string;
     description?: string;
     tags?: string[];
     privacy?: "private" | "public" | "public-hosts" | "unlisted";
-    vmTier?: VMTier;
-    hibernationTimeoutSeconds?: number;
 };
 export type SessionCreateOptions = {
     id?: string;
     env?: Record<string, string>;
     permission?: "read" | "write";
+    git?: {
+        provider: string;
+        username?: string;
+        accessToken?: string;
+        email: string;
+        name?: string;
+    };
+    hostToken?: {
+        token: string;
+        sandboxId: string;
+    };
 };
 export type ShellRunOpts = {
     env?: Record<string, string>;
@@ -50,11 +70,28 @@ export type ShellRunOpts = {
 };
 export declare class CodeSandbox {
     readonly sandboxes: Sandboxes;
-    constructor(apiToken?: string, options?: ClientOptions);
+    readonly hosts: HostTokens;
+    constructor(apiToken?: string, options?: ClientOptions & {
+        headers?: Record<string, string>;
+        tracer?: unknown;
+    });
+}
+/** CodeSandbox's host tokens open private previews. Runtime's private
+ * previews carry their own signed token: `sandbox.previews.create(port)`. */
+export declare class HostTokens {
+    readonly createToken: RefusedAsync;
+    readonly listTokens: RefusedAsync;
+    readonly revokeToken: RefusedAsync;
+    readonly revokeAllTokens: RefusedAsync;
+    readonly updateToken: RefusedAsync;
+    readonly getUrl: Refused;
+    readonly getHeaders: Refused;
+    readonly getCookies: Refused;
 }
 export declare class Sandboxes {
     private readonly runtime;
     constructor(runtime: Runtime);
+    get defaultTemplateId(): string;
     create(options?: CreateSandboxOpts): Promise<Sandbox>;
     resume(id: string): Promise<Sandbox>;
     hibernate(id: string): Promise<void>;
@@ -63,7 +100,24 @@ export declare class Sandboxes {
     restart(id: string, options?: {
         hibernationTimeoutSeconds?: number;
     }): Promise<Sandbox>;
-    fork(id: string, options?: Omit<CreateSandboxOpts, "id">): Promise<Sandbox>;
+    fork(id: string, options?: StartSandboxOpts & Pick<CreateSandboxOpts, "title" | "description" | "tags" | "privacy">): Promise<Sandbox>;
+    /** The account's running CodeSandbox-adapter sandboxes. Runtime has no
+     * per-account count of running machines, so the limit is null. */
+    listRunning(): Promise<{
+        concurrentVmCount: number;
+        concurrentVmLimit: number | null;
+        vms: {
+            id: string;
+            creditBasis: string | undefined;
+            lastActiveAt: Date | undefined;
+            sessionStartedAt: Date | undefined;
+            specs: {
+                cpu: number;
+                memory: number;
+                storage: number;
+            };
+        }[];
+    }>;
     get(id: string): Promise<{
         id: string;
         createdAt: Date;
@@ -108,6 +162,12 @@ export declare class Sandbox {
     constructor(native: NativeSandbox, bootupType: "RUNNING" | "CLEAN" | "RESUME" | "FORK");
     get id(): string;
     get cluster(): string;
+    /** Runtime's guest agent is updated with the host: always current. */
+    get isUpToDate(): boolean;
+    /** Resizes to the tier's CPUs and memory; a running sandbox restarts, as CodeSandbox's does. */
+    updateTier(tier: VMTier): Promise<void>;
+    readonly createSession: RefusedAsync;
+    readonly createBrowserSession: RefusedAsync;
     updateHibernationTimeout(timeoutSeconds: number): Promise<void>;
     connect(options?: SessionCreateOptions): Promise<SandboxClient>;
 }
@@ -183,6 +243,20 @@ export declare class FileSystem {
         type: string;
         isSymlink: boolean;
     }[]>;
+    /** Changes under a path, as CodeSandbox's add, change and remove events. */
+    watch(path: string, options?: {
+        recursive?: boolean;
+        excludes?: readonly string[];
+    }): Promise<{
+        onEvent: (listener: (value: {
+            paths: string[];
+            type: "add" | "change" | "remove";
+        }) => void) => {
+            dispose: () => boolean;
+        };
+        dispose: () => void;
+    }>;
+    readonly download: RefusedAsync;
     stat(path: string): Promise<{
         type: string;
         isSymlink: boolean;
@@ -192,46 +266,160 @@ export declare class FileSystem {
         ctime: number;
     }>;
 }
+type SavedCommand = {
+    version: 1;
+    /** A terminal from terminals.create; absent for a command. */
+    kind?: "terminal";
+    command: string;
+    name?: string;
+    options: Parameters<NativeSandbox["spawn"]>[1];
+    taskId?: string;
+};
+type ShellSize = {
+    cols: number;
+    rows: number;
+};
+/** A shell CodeSandbox lists: a command's name is JSON whose type is "command". */
+export declare function isCommandShell(shell: {
+    shellId?: string;
+    name: string;
+    status?: string;
+    exitCode?: number;
+    shellType?: string;
+    startCommand?: string;
+    ownerUsername?: string;
+    isSystemShell?: boolean;
+}): boolean;
+/** What the client's commands, terminals and ports share with it. */
+type Session = {
+    native: NativeSandbox;
+    env: Record<string, string>;
+    workspacePath: string;
+    assertConnected(): void;
+    start(saved: SavedCommand): Promise<Process>;
+    attach(process: Process, saved: SavedCommand): Command;
+    previewURLs: Map<number, string>;
+};
+export declare class SandboxCommands {
+    private readonly session;
+    constructor(session: Session);
+    runBackground(command: string | string[], options?: ShellRunOpts): Promise<Command>;
+    run(command: string | string[], options?: ShellRunOpts): Promise<string>;
+    getAll(): Promise<Command[]>;
+}
+export declare class Ports {
+    private readonly session;
+    private readonly opened;
+    private readonly closed;
+    private watching?;
+    private known?;
+    private polling;
+    constructor(session: Session);
+    /** A port's events start a watch of the sandbox's listening ports, once a second. */
+    get onDidPortOpen(): (listener: (port: {
+        port: number;
+        host: string;
+    }) => void) => {
+        dispose: () => void;
+    };
+    get onDidPortClose(): (listener: (port: number) => void) => {
+        dispose: () => void;
+    };
+    private subscribe;
+    /** The ports listening now. */
+    listening(): Promise<number[]>;
+    private poll;
+    dispose(): void;
+    get(port: number): Promise<{
+        port: number;
+        host: string;
+    }>;
+    getAll(): Promise<{
+        port: number;
+        host: string;
+    }[]>;
+    waitForPort(port: number, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        port: number;
+        host: string;
+    }>;
+}
+/** URLs of the ports this client exposed with ports.get or listed with ports.getAll. */
+export declare class Hosts {
+    private readonly session;
+    constructor(session: Session);
+    getUrl(port: number, protocol?: string): string;
+    /** Public previews need no token: nothing to send. */
+    getHeaders(): Record<string, string>;
+    getCookies(): Record<string, string>;
+}
+/** Interactive shells, each a process with a terminal of its own. */
+export declare class Terminals {
+    private readonly session;
+    constructor(session: Session);
+    create(command?: "bash" | "zsh" | "fish" | "ksh" | "dash", options?: ShellRunOpts): Promise<Terminal>;
+    get(shellId: string): Promise<Terminal | undefined>;
+    getAll(): Promise<Terminal[]>;
+}
+export declare class Terminal {
+    private readonly process;
+    readonly name: string;
+    private readonly outputEvent;
+    readonly onOutput: (listener: (value: string) => void) => {
+        dispose: () => boolean;
+    };
+    private output;
+    private following?;
+    constructor(process: Process, name: string);
+    get id(): string;
+    /** Its output so far, and what it prints from now on through onOutput. */
+    open(dimensions?: ShellSize): Promise<string>;
+    write(input: string, dimensions?: ShellSize): Promise<void>;
+    run(input: string, dimensions?: ShellSize): Promise<void>;
+    kill(): Promise<void>;
+}
+/** One-off JavaScript and Python snippets, run as CodeSandbox runs them: the
+ * last line's value is printed. */
+export declare class Interpreters {
+    private readonly commands;
+    constructor(commands: SandboxCommands);
+    javascript(code: string): Promise<string>;
+    python(code: string): Promise<string>;
+}
 export declare class SandboxClient {
     private readonly native;
     private readonly env;
     readonly fs: FileSystem;
-    readonly commands: {
-        runBackground: (command: string | string[], options?: ShellRunOpts) => Promise<Command>;
-        run: (command: string | string[], options?: ShellRunOpts) => Promise<string>;
-        getAll: () => Promise<Command[]>;
-    };
-    readonly ports: {
-        get: (port: number) => Promise<{
-            port: number;
-            host: string;
-        }>;
-        getAll: () => Promise<{
-            port: number;
-            host: string;
-        }[]>;
-        waitForPort: (port: number, options?: {
-            timeoutMs?: number;
-        }) => Promise<{
-            port: number;
-            host: string;
-        }>;
-    };
+    readonly commands: SandboxCommands;
+    readonly ports: Ports;
+    readonly terminals: Terminals;
+    readonly interpreters: Interpreters;
+    readonly hosts: Hosts;
     readonly tasks: Tasks;
     readonly setup: Setup;
     readonly workspacePath = "/project/sandbox";
+    static readonly create: RefusedAsync;
     private disconnected;
     private readonly attached;
     private readonly previewURLs;
+    private readonly stateEvent;
     private stopKeepAlive?;
     constructor(native: NativeSandbox, env: Record<string, string>);
+    /** Runtime's guest agent is updated with the host: always current. */
+    get isUpToDate(): boolean;
+    /** The sandbox's page in Runtime's console. */
+    get editorUrl(): string;
+    get onStateChange(): (listener: (value: "CONNECTED" | "DISCONNECTED") => void) => {
+        dispose: () => boolean;
+    };
     initialize(): Promise<void>;
     previewURL(port: number): string;
     private assertConnected;
     private start;
     private attach;
     get id(): string;
-    get state(): "DISCONNECTED" | "CONNECTED";
+    get state(): "CONNECTED" | "DISCONNECTED";
     disconnect(): Promise<void>;
     reconnect(): Promise<void>;
     keepActiveWhileConnected(enabled: boolean): void;