withruntime 0.8.4 → 0.10.0

package/dist/client.d.ts

@@ -1,17 +1,18 @@
 import { RuntimeError } from "./errors.js";
 import type { Page } from "./page.js";
 import { type ClientExtensions } from "./products/index.js";
+import { usageExport as makeUsageExport } from "./products/observability.js";
 import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
-import type { CreateSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
+import type { CreateSandbox, DeletedSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
 export type RuntimeOptions = {
     /** Default: the RUNTIME_API_KEY environment variable. */
     apiKey?: string;
     /** Default: RUNTIME_API_URL, then https://api.withruntime.com. */
     baseUrl?: string;
     fetch?: typeof fetch;
-    /** Per call, retries included. Default 5 minutes. */
+    /** Per call, queue and retries included. Default 5 minutes; 0 disables it. */
     timeoutMs?: number;
     /** Retries of transport failures, 429, 502, 503 and 504. Default 4. */
     maxRetries?: number;
@@ -30,11 +31,16 @@ export interface Runtime extends ClientExtensions {
 }
 export declare class Runtime {
     readonly transport: Transport;
+    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
+    readonly sandbox: Sandboxes;
     readonly sandboxes: Sandboxes;
+    readonly snapshot: Snapshots;
     readonly snapshots: Snapshots;
     readonly feedback: FeedbackApi;
     readonly support: SupportApi;
     readonly account: AccountApi;
+    /** Date-range settlements, paged with exact charges and the server's CSV. */
+    readonly usageExport: ReturnType<typeof makeUsageExport>;
     constructor(options?: RuntimeOptions);
     /** Who this key is: organization, agent and credential. */
     me(options?: RequestOptions): Promise<{
@@ -50,6 +56,25 @@ export declare class Runtime {
     /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
     /** Credit, holds, trial time and per-resource charges. */
     usage(options?: RequestOptions): Promise<Usage>;
+    /** This account's authenticated API answers, in hourly windows. Counts are
+     * exact decimal strings, and an empty window has a null error percentage.
+     * A key needs usage permission. */
+    usageRequests(range?: "24h" | "7d" | "30d" | "90d", options?: RequestOptions): Promise<{
+        range: "24h" | "7d" | "30d" | "90d";
+        since: string;
+        until: string;
+        calls: string;
+        clientErrors: string;
+        serverErrors: string;
+        errorPercent: number | null;
+        operations: Array<{
+            operation: string;
+            calls: string;
+            clientErrors: string;
+            serverErrors: string;
+            errorPercent: number | null;
+        }>;
+    }>;
 }
 /** How `sandboxes.create` waits when every trial slot, the account's quota or
  * the region is full. */
@@ -80,7 +105,11 @@ export declare class Sandboxes {
         wait?: boolean;
     }, options?: CreateOptions): Promise<Sandbox>;
     get(id: string, options?: RequestOptions): Promise<Sandbox>;
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
+    /** Deletes a sandbox for good, by id, without reading it first: see
+     * `sandbox.delete()`. Deleting it again answers the same. */
+    delete(id: string, options?: RequestOptions): Promise<DeletedSandbox>;
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
+     * Request options apply to the initial request and every subsequent page. */
     list(filter?: {
         state?: SandboxInfo["state"][];
         includeStopped?: boolean;
@@ -88,7 +117,7 @@ export declare class Sandboxes {
         labels?: Record<string, string>;
         name?: string;
         limit?: number;
-    }): Promise<Page<Sandbox>>;
+    }, options?: RequestOptions): Promise<Page<Sandbox>>;
 }
 export declare class FeedbackApi {
     private readonly t;

package/dist/client.js

@@ -1,14 +1,17 @@
+import { WAIT_FOR_TIMEOUT_SECONDS } from "./api-defaults.js";
 import { RuntimeError } from "./errors.js";
-import { clientFactories } from "./products/index.js";
-import { Sandbox, sandboxPage } from "./sandbox.js";
+import { clientFactories, clientProductAliases } from "./products/index.js";
+import { usageExport as makeUsageExport } from "./products/observability.js";
+import { Sandbox, deleteSandbox, sandboxPage } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, missingKey } from "./transport.js";
-/** The key `runtime login` saved for this machine, found on first use. */
-const savedKey = async () => {
+/** The key `runtime login` saved for this machine and this API origin, found
+ * on first use. A constructor override must never receive another API's key. */
+const savedKey = async (apiOrigin) => {
     if (typeof process === "undefined" || !process.versions?.node)
         throw missingKey();
     const { resolveCredential } = await import("./credentials.js");
-    return resolveCredential(process.env);
+    return resolveCredential({ ...process.env, RUNTIME_API_URL: apiOrigin });
 };
 const env = (name) => typeof process === "undefined"
     ? undefined
@@ -16,32 +19,42 @@ const env = (name) => typeof process === "undefined"
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Runtime {
     transport;
+    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
+    sandbox;
     sandboxes;
+    snapshot;
     snapshots;
     feedback;
     support;
     account;
+    /** Date-range settlements, paged with exact charges and the server's CSV. */
+    usageExport;
     constructor(options = {}) {
         this.transport = new Transport({
             // A key given, then RUNTIME_API_KEY, then (in Node and Bun) the key
             // `runtime login` saved for this machine, read on the first call.
-            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? savedKey,
+            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? (() => savedKey(this.transport.baseUrl)),
             baseUrl: options.baseUrl ?? env("RUNTIME_API_URL"),
             ...(options.fetch ? { fetch: options.fetch } : {}),
-            ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
-            ...(options.maxConnections ? { maxConnections: options.maxConnections } : {}),
+            ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
             ...(options.waitForCapacityMs !== undefined
                 ? { waitForCapacityMs: options.waitForCapacityMs }
                 : {}),
         });
         this.sandboxes = new Sandboxes(this.transport);
+        this.sandbox = this.sandboxes;
         this.snapshots = new Snapshots(this.transport);
+        this.snapshot = this.snapshots;
         this.feedback = new FeedbackApi(this.transport);
         this.support = new SupportApi(this.transport);
         this.account = new AccountApi(this.transport);
+        this.usageExport = makeUsageExport(this.transport);
         for (const [name, make] of clientFactories())
             Object.defineProperty(this, name, { value: make(this.transport), enumerable: true });
+        for (const [alias, name] of Object.entries(clientProductAliases))
+            Object.defineProperty(this, alias, { value: this[name], enumerable: true });
     }
     /** Who this key is: organization, agent and credential. */
     me(options = {}) {
@@ -60,6 +73,17 @@ export class Runtime {
             ...options,
         });
     }
+    /** This account's authenticated API answers, in hourly windows. Counts are
+     * exact decimal strings, and an empty window has a null error percentage.
+     * A key needs usage permission. */
+    usageRequests(range = "24h", options = {}) {
+        return this.transport.json({
+            method: "GET",
+            path: "/v1/usage/requests",
+            query: { range },
+            ...options,
+        });
+    }
 }
 export class Sandboxes {
     t;
@@ -83,7 +107,12 @@ export class Sandboxes {
         });
         const sandbox = new Sandbox(this.t, info);
         if (wait !== false && info.state !== "running") {
-            await sandbox.waitFor("running", { timeoutSeconds: 60 });
+            await sandbox.waitFor("running", {
+                timeoutSeconds: WAIT_FOR_TIMEOUT_SECONDS,
+                signal: options.signal,
+                timeoutMs: options.timeoutMs,
+                idempotencyKey: options.idempotencyKey,
+            });
             if (sandbox.state !== "running")
                 throw new RuntimeError({
                     message: `Sandbox ${info.id} is ${sandbox.state}, not running.`,
@@ -108,8 +137,14 @@ export class Sandboxes {
             ...options,
         }));
     }
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
-    async list(filter = {}) {
+    /** Deletes a sandbox for good, by id, without reading it first: see
+     * `sandbox.delete()`. Deleting it again answers the same. */
+    delete(id, options = {}) {
+        return deleteSandbox(this.t, id, options);
+    }
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
+     * Request options apply to the initial request and every subsequent page. */
+    async list(filter = {}, options = {}) {
         const query = {
             ...(filter.state ? { state: filter.state } : {}),
             ...(filter.includeStopped ? { includeStopped: true } : {}),
@@ -119,7 +154,7 @@ export class Sandboxes {
             ...(filter.name ? { name: filter.name } : {}),
             ...(filter.limit ? { limit: filter.limit } : {}),
         };
-        return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query }), query);
+        return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query, ...options }), query, options);
     }
 }
 export class FeedbackApi {

package/dist/cloudflare/identity.d.ts

@@ -0,0 +1,7 @@
+/** A Durable Object ID includes its namespace; a display name does not. */
+export declare function workerSandboxIdentity(objectId: string, stored: {
+    nativeSandboxId?: string;
+    sandboxName?: {
+        name: string;
+    };
+}): string;

package/dist/cloudflare/identity.js

@@ -0,0 +1,13 @@
+/** A Durable Object ID includes its namespace; a display name does not. */
+export function workerSandboxIdentity(objectId, stored) {
+    if (stored.nativeSandboxId !== undefined) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(stored.nativeSandboxId))
+            throw new Error("The stored Runtime sandbox identity is invalid");
+        return stored.nativeSandboxId;
+    }
+    if (stored.sandboxName)
+        throw new Error("This legacy Durable Object has no namespace-safe Runtime identity. Retain its existing sandbox and migrate its identity explicitly before using it.");
+    if (!/^[a-f0-9]{64}$/.test(objectId))
+        throw new Error("The Durable Object identity is invalid");
+    return `cf-do-${objectId}`;
+}

package/dist/cloudflare/index.d.ts

@@ -0,0 +1,303 @@
+import { Runtime } from "../client.js";
+import type { Process as NativeProcess, Sandbox as NativeSandbox } from "../sandbox.js";
+import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+export { CompatibilityError };
+export declare class SandboxSecurityError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare function sanitizeSandboxId(id: string): string;
+export interface SandboxOptions {
+    sleepAfter?: string | number;
+    keepAlive?: boolean;
+    normalizeId?: boolean;
+    runtime?: ClientOptions;
+}
+export interface ExecOptions {
+    timeout?: number;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    encoding?: string;
+    stream?: boolean;
+    onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+    onComplete?: (result: ExecResult) => void;
+    onError?: (error: Error) => void;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+    duration: number;
+    timestamp: string;
+    sessionId?: string;
+}
+export interface ReadFileResult {
+    success: boolean;
+    path: string;
+    content: string;
+    encoding: "utf-8" | "base64";
+    isBinary: boolean;
+    size: number;
+    timestamp: string;
+}
+export interface ReadFileStreamResult {
+    success: true;
+    path: string;
+    content: ReadableStream<Uint8Array>;
+    size: number;
+    mimeType: string;
+    timestamp: string;
+}
+export interface SessionOptions {
+    id?: string;
+    name?: string;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    isolation?: boolean;
+    commandTimeoutMs?: number;
+}
+export interface ProcessOptions {
+    timeout?: number;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    encoding?: string;
+    sessionId?: string;
+    onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+    onExit?: (code: number | null) => void;
+    onStart?: (process: Process) => void;
+    onError?: (error: Error) => void;
+}
+export declare function validateSandboxConfiguration(options: Pick<SandboxOptions, "sleepAfter" | "keepAlive">): void;
+/** Worker bindings are deliberately not inspected or invoked. Supply Runtime credentials
+ * through options.runtime in Workers; Node also supports RUNTIME_API_KEY/login. */
+export declare function getSandbox(namespace: unknown, id: string, options?: SandboxOptions): Sandbox;
+export declare class Sandbox {
+    readonly runtime: Runtime;
+    private readonly options;
+    private pending?;
+    private existing?;
+    readonly id: string;
+    constructor(runtime: Runtime, id: string, options?: SandboxOptions);
+    configure(options: Pick<SandboxOptions, "sleepAfter" | "keepAlive">): Promise<void>;
+    /** Only a successfully initialized native handle can supply a recovery id. */
+    existingNativeId(): string | undefined;
+    /** Reconcile an uncertain update from an authoritative read, without allocation. */
+    reconcileConfiguration(nativeId?: string | undefined): Promise<{
+        sleepAfter: number;
+        keepAlive: boolean;
+    }>;
+    native(): Promise<NativeSandbox>;
+    private session;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execStream(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+    createSession(options?: SessionOptions): Promise<ExecutionSession>;
+    getSession(id: string): Promise<ExecutionSession>;
+    deleteSession(id: string): Promise<{
+        success: boolean;
+        sessionId: string;
+        timestamp: string;
+    }>;
+    destroy(): Promise<void>;
+    setEnvVars(env: Record<string, string | undefined>): Promise<void>;
+    writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+        encoding?: string;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        bytesWritten: number;
+        timestamp: string;
+    }>;
+    readFile(path: string, options: {
+        encoding: "none";
+    }): Promise<ReadFileStreamResult>;
+    readFile(path: string, options?: {
+        encoding?: "utf8" | "utf-8" | "base64";
+    }): Promise<ReadFileResult>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        timestamp: string;
+    }>;
+    deleteFile(path: string): Promise<{
+        success: boolean;
+        path: string;
+        timestamp: string;
+    }>;
+    renameFile(from: string, to: string): Promise<{
+        success: boolean;
+        path: string;
+        newPath: string;
+        timestamp: string;
+    }>;
+    moveFile(from: string, to: string): Promise<{
+        success: boolean;
+        path: string;
+        newPath: string;
+        timestamp: string;
+    }>;
+    listFiles(path: string, options?: {
+        recursive?: boolean;
+        includeHidden?: boolean;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        files: {
+            absolutePath: string;
+            relativePath: string;
+            permissions: {
+                readable: boolean;
+                writable: boolean;
+                executable: boolean;
+            };
+            name: string;
+            path: string;
+            type: "file" | "directory" | "symlink" | "other";
+            size: number;
+            mode: string;
+            modifiedAt: string;
+            uid?: number;
+            gid?: number;
+            owner?: string;
+            group?: string;
+            symlinkTarget?: string;
+        }[];
+        count: number;
+        timestamp: string;
+    }>;
+    exists(path: string): Promise<{
+        success: boolean;
+        path: string;
+        exists: boolean;
+        timestamp: string;
+    }>;
+    listProcesses(): Promise<Process[]>;
+    getProcess(id: string): Promise<Process | null>;
+    killProcess(id: string, signal?: string): Promise<void>;
+    killAllProcesses(): Promise<number>;
+    getProcessLogs(id: string): Promise<{
+        stdout: string;
+        stderr: string;
+        processId: string;
+    }>;
+    exposePort(port: number, options: {
+        name?: string;
+        hostname: string;
+        token?: string;
+    }): Promise<{
+        url: string;
+        port: number;
+        name: string | undefined;
+    }>;
+    unexposePort(port: number): Promise<void>;
+}
+export declare class ExecutionSession {
+    private readonly sandbox;
+    readonly id: string;
+    private options;
+    constructor(sandbox: Sandbox, id: string, options: SessionOptions);
+    private context;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execStream(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+    private path;
+    writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+        encoding?: string;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        bytesWritten: number;
+        timestamp: string;
+    }>;
+    readFile(path: string, options: {
+        encoding: "none";
+    }): Promise<ReadFileStreamResult>;
+    readFile(path: string, options?: {
+        encoding?: "utf8" | "utf-8" | "base64";
+    }): Promise<ReadFileResult>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        timestamp: string;
+    }>;
+    deleteFile(path: string): Promise<{
+        success: boolean;
+        path: string;
+        timestamp: string;
+    }>;
+    renameFile(path: string, newPath: string): Promise<{
+        success: boolean;
+        path: string;
+        newPath: string;
+        timestamp: string;
+    }>;
+    exists(path: string): Promise<{
+        success: boolean;
+        path: string;
+        exists: boolean;
+        timestamp: string;
+    }>;
+    listFiles(path: string, options?: {
+        recursive?: boolean;
+        includeHidden?: boolean;
+    }): Promise<{
+        success: boolean;
+        path: string;
+        files: {
+            absolutePath: string;
+            relativePath: string;
+            permissions: {
+                readable: boolean;
+                writable: boolean;
+                executable: boolean;
+            };
+            name: string;
+            path: string;
+            type: "file" | "directory" | "symlink" | "other";
+            size: number;
+            mode: string;
+            modifiedAt: string;
+            uid?: number;
+            gid?: number;
+            owner?: string;
+            group?: string;
+            symlinkTarget?: string;
+        }[];
+        count: number;
+        timestamp: string;
+    }>;
+    setEnvVars(env: Record<string, string | undefined>): Promise<void>;
+}
+export declare class Process {
+    private readonly sandbox;
+    private readonly native;
+    readonly sessionId?: string | undefined;
+    constructor(sandbox: Sandbox, native: NativeProcess, sessionId?: string | undefined);
+    get id(): string;
+    get command(): string;
+    get status(): "running" | "killed" | "unknown" | "failed" | "completed";
+    get startTime(): Date;
+    get endTime(): Date | undefined;
+    get exitCode(): number | undefined;
+    kill(signal?: string): Promise<void>;
+    getStatus(): Promise<"running" | "killed" | "unknown" | "failed" | "completed">;
+    getLogs(): Promise<{
+        stdout: string;
+        stderr: string;
+        processId: string;
+    }>;
+    waitForExit(timeout?: number): Promise<{
+        exitCode: number;
+    }>;
+    waitForLog(pattern: string | RegExp, timeout?: number): Promise<{
+        match?: true | RegExpMatchArray | undefined;
+        line: string;
+    }>;
+}