withruntime 0.2.2 → 0.3.0

package/dist/client.d.ts

@@ -0,0 +1,118 @@
+import type { Page } from "./page.js";
+import { type ClientExtensions } from "./products/index.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";
+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. */
+    timeoutMs?: number;
+    /** Retries of transport failures, 429, 502, 503 and 504. Default 4. */
+    maxRetries?: number;
+    /** Calls in flight at once; more wait their turn and reuse connections. Default 32. */
+    maxConnections?: number;
+};
+/** One client for every Runtime Cloud product. Create it once and reuse it:
+ * it keeps its connections open. */
+export interface Runtime extends ClientExtensions {
+}
+export declare class Runtime {
+    readonly transport: Transport;
+    readonly sandboxes: Sandboxes;
+    readonly snapshots: Snapshots;
+    readonly feedback: FeedbackApi;
+    readonly support: SupportApi;
+    constructor(options?: RuntimeOptions);
+    /** Who this key is: organization, agent and credential. */
+    me(options?: RequestOptions): Promise<{
+        orgId: string;
+        principalId: string;
+        credentialId: string | null;
+        apiVersion: string;
+    }>;
+    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, trial time and per-resource charges. */
+    usage(options?: RequestOptions): Promise<Usage>;
+}
+export declare class Sandboxes {
+    private readonly t;
+    constructor(t: Transport);
+    /** Creates a sandbox and waits until it is running. Every field is optional:
+     * with none you get the free trial while it lasts, the default region and a
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once. */
+    create(input?: CreateSandbox & {
+        wait?: boolean;
+    }, options?: RequestOptions): Promise<Sandbox>;
+    get(id: string, options?: RequestOptions): Promise<Sandbox>;
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
+    list(filter?: {
+        state?: SandboxInfo["state"][];
+        includeStopped?: boolean;
+        /** Every label must match. */
+        labels?: Record<string, string>;
+        name?: string;
+        limit?: number;
+    }): Promise<Page<Sandbox>>;
+}
+export declare class FeedbackApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** Tell the Runtime team something. Please do, generously: bugs, missing
+     * features, what another provider does better, what blocks a migration. */
+    submit(input: {
+        kind: FeedbackKind;
+        summary: string;
+        detail?: string;
+        competitor?: string;
+        resourceId?: string;
+        requestId?: string;
+        context?: Record<string, unknown>;
+    }, options?: RequestOptions): Promise<{
+        id: string;
+        duplicate: boolean;
+    }>;
+    list(options?: {
+        limit?: number;
+    }): Promise<{
+        data: Array<{
+            id: string;
+            kind: FeedbackKind;
+            summary: string;
+            status: string;
+            item: unknown;
+        }>;
+    }>;
+}
+export type SupportReply = {
+    conversationId: string;
+    status: "answered" | "working" | "escalated" | "waiting_customer" | "capped";
+    reply?: string;
+    pendingActions?: Array<{
+        id: string;
+        action: string;
+        resourceId?: string;
+        summary: string;
+        inputHash: string;
+        expiresAt: string;
+    }>;
+};
+export declare class SupportApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** Ask Runtime support. If status is "working", read() it again in a minute. */
+    message(input: {
+        message?: string;
+        conversationId?: string;
+        approveActionId?: string;
+        approveInputHash?: string;
+        denyActionId?: string;
+    }): Promise<SupportReply>;
+    read(conversationId: string): Promise<SupportReply>;
+}
+/** The client behind the static helpers, from the environment. */
+export declare function defaultClient(): Runtime;

package/dist/client.js

@@ -0,0 +1,160 @@
+import { RuntimeError } from "./errors.js";
+import { clientFactories } from "./products/index.js";
+import { Sandbox, 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 () => {
+    if (typeof process === "undefined" || !process.versions?.node)
+        throw missingKey();
+    const { resolveCredential } = await import("./credentials.js");
+    return resolveCredential(process.env);
+};
+const env = (name) => typeof process === "undefined"
+    ? undefined
+    : process.env[name];
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class Runtime {
+    transport;
+    sandboxes;
+    snapshots;
+    feedback;
+    support;
+    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,
+            baseUrl: options.baseUrl ?? env("RUNTIME_API_URL"),
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+            ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+            ...(options.maxConnections ? { maxConnections: options.maxConnections } : {}),
+        });
+        this.sandboxes = new Sandboxes(this.transport);
+        this.snapshots = new Snapshots(this.transport);
+        this.feedback = new FeedbackApi(this.transport);
+        this.support = new SupportApi(this.transport);
+        for (const [name, make] of clientFactories())
+            Object.defineProperty(this, name, { value: make(this.transport), enumerable: true });
+    }
+    /** Who this key is: organization, agent and credential. */
+    me(options = {}) {
+        return this.transport.json({
+            method: "GET",
+            path: "/v1/me",
+            ...options,
+        });
+    }
+    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, trial time and per-resource charges. */
+    usage(options = {}) {
+        return this.transport.json({
+            method: "GET",
+            path: "/v1/usage",
+            ...options,
+        });
+    }
+}
+export class Sandboxes {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    /** Creates a sandbox and waits until it is running. Every field is optional:
+     * with none you get the free trial while it lasts, the default region and a
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once. */
+    async create(input = {}, options = {}) {
+        const { wait, ...body } = input;
+        const info = await this.t.json({
+            method: "POST",
+            path: "/v1/sandboxes",
+            body,
+            wait: wait === false ? 0 : 60,
+            ...options,
+        });
+        const sandbox = new Sandbox(this.t, info);
+        if (wait !== false && info.state !== "running") {
+            await sandbox.waitFor("running", { timeoutSeconds: 60 });
+            if (sandbox.state !== "running")
+                throw new RuntimeError({
+                    message: `Sandbox ${info.id} is ${sandbox.state}, not running.`,
+                    code: "start_failed",
+                    status: 0,
+                    hint: "Read it with runtime.sandboxes.get(id); stopReason says why.",
+                });
+        }
+        return sandbox;
+    }
+    async get(id, options = {}) {
+        return new Sandbox(this.t, await this.t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${encodeURIComponent(id)}`,
+            ...options,
+        }));
+    }
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
+    async list(filter = {}) {
+        const query = {
+            ...(filter.state ? { state: filter.state } : {}),
+            ...(filter.includeStopped ? { includeStopped: true } : {}),
+            ...(filter.labels
+                ? { label: Object.entries(filter.labels).map(([k, v]) => `${k}:${v}`) }
+                : {}),
+            ...(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);
+    }
+}
+export class FeedbackApi {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    /** Tell the Runtime team something. Please do, generously: bugs, missing
+     * features, what another provider does better, what blocks a migration. */
+    submit(input, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: "/v1/feedback",
+            body: input,
+            ...options,
+        });
+    }
+    list(options = {}) {
+        return this.t.json({
+            method: "GET",
+            path: "/v1/feedback",
+            query: { limit: options.limit },
+        });
+    }
+}
+export class SupportApi {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    /** Ask Runtime support. If status is "working", read() it again in a minute. */
+    message(input) {
+        return this.t.json({
+            method: "POST",
+            path: "/v1/support/messages",
+            body: input,
+            retry: false,
+            timeoutMs: 120_000,
+        });
+    }
+    read(conversationId) {
+        return this.t.json({
+            method: "GET",
+            path: `/v1/support/conversations/${encodeURIComponent(conversationId)}`,
+        });
+    }
+}
+let shared;
+/** The client behind the static helpers, from the environment. */
+export function defaultClient() {
+    shared ??= new Runtime();
+    return shared;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,44 @@
+import { missingKey } from "./transport.js";
+export type SavedConnection = {
+    version: 1;
+    apiOrigin: string;
+    authOrigin: string;
+    key: string;
+    connectionId: string;
+    orgId: string;
+    agentName: string;
+};
+export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
+    api: string;
+    auth: string;
+};
+/** Private user storage, outside project files. Nothing reading this module
+ * returns a secret to CLI output. Store names bind credentials to both origins. */
+export declare function connectionStore(env: NodeJS.ProcessEnv, directory?: string): {
+    read(): Promise<SavedConnection | null>;
+    save(connection: SavedConnection): Promise<void>;
+    remove(): Promise<void>;
+    /** A browser approval that was started and not yet answered, so a command
+     * that was stopped while it waited picks up the same link and code rather
+     * than asking the person to approve a new one. Unreadable or stale ones
+     * read as none. */
+    readPending(): Promise<PendingConnection | null>;
+    savePending(pending: PendingConnection): Promise<void>;
+    removePending(): Promise<void>;
+};
+/** What `readPending` keeps: the private half of the key pair the approved
+ * key is encrypted to, and the request it answers. */
+export type PendingConnection = {
+    version: 1;
+    apiOrigin: string;
+    authOrigin: string;
+    privateKey: string;
+    deviceCode: string;
+    url: string;
+    userCode: string;
+    agentName: string;
+    expiresAt: number;
+};
+export declare function resolveCredential(env: NodeJS.ProcessEnv): Promise<string>;
+/** No key in the environment and none saved on this machine. */
+export declare const notConnected: typeof missingKey;

package/dist/credentials.js

@@ -0,0 +1,180 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { apiOrigin } from "./index.js";
+import { missingKey } from "./transport.js";
+export function connectionOrigins(env) {
+    return {
+        api: apiOrigin(env.RUNTIME_API_URL ?? "https://api.withruntime.com"),
+        auth: apiOrigin(env.RUNTIME_AUTH_URL ?? "https://withruntime.com"),
+    };
+}
+function defaultDirectory(env) {
+    const root = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    if (!isAbsolute(root))
+        throw new Error("XDG_CONFIG_HOME must be an absolute path.");
+    return join(root, "runtime-cloud");
+}
+/** Private user storage, outside project files. Nothing reading this module
+ * returns a secret to CLI output. Store names bind credentials to both origins. */
+export function connectionStore(env, directory = defaultDirectory(env)) {
+    const origins = connectionOrigins(env);
+    const name = createHash("sha256").update(`${origins.auth}\n${origins.api}`).digest("hex");
+    const file = join(directory, `${name}.json`);
+    async function privateDirectory(create) {
+        if (create)
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+        try {
+            const info = await lstat(directory);
+            if (!info.isDirectory() ||
+                info.isSymbolicLink() ||
+                (process.platform !== "win32" &&
+                    ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.())))
+                throw new Error("Runtime's credential directory must be private to your user.");
+        }
+        catch (error) {
+            if (!create && error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        return true;
+    }
+    /** One private file in the private directory: its text, or null. */
+    async function readPrivate(path, limit, label) {
+        if (!(await privateDirectory(false)))
+            return null;
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw new Error(`Could not safely open Runtime's ${label}.`);
+        }
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() ||
+                info.size > limit ||
+                (process.platform !== "win32" &&
+                    ((info.mode & 0o077) !== 0 || info.uid !== process.getuid?.())))
+                throw new Error(`Runtime's ${label} must be private to your user.`);
+            return await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async function writePrivate(path, text) {
+        await privateDirectory(true);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            const handle = await open(temporary, "wx", 0o600);
+            try {
+                await handle.writeFile(text);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, path);
+        }
+        finally {
+            await unlink(temporary).catch(() => undefined);
+        }
+    }
+    async function removePrivate(path) {
+        if (await privateDirectory(false))
+            await unlink(path).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+    }
+    const pendingFile = join(directory, `${name}.pending.json`);
+    return {
+        async read() {
+            const text = await readPrivate(file, 4096, "saved connection");
+            if (text === null)
+                return null;
+            let saved;
+            try {
+                saved = JSON.parse(text);
+            }
+            catch {
+                throw new Error("Runtime's saved connection is invalid. Connect again.");
+            }
+            if (saved.version !== 1 ||
+                saved.apiOrigin !== origins.api ||
+                saved.authOrigin !== origins.auth ||
+                typeof saved.key !== "string" ||
+                !/^rtcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}$/.test(saved.key) ||
+                typeof saved.connectionId !== "string" ||
+                typeof saved.orgId !== "string" ||
+                typeof saved.agentName !== "string")
+                throw new Error("Runtime's saved connection is invalid. Connect again.");
+            return saved;
+        },
+        async save(connection) {
+            if (connection.apiOrigin !== origins.api || connection.authOrigin !== origins.auth)
+                throw new Error("Connection origins do not match.");
+            await writePrivate(file, JSON.stringify(connection));
+        },
+        async remove() {
+            await removePrivate(file);
+        },
+        /** A browser approval that was started and not yet answered, so a command
+         * that was stopped while it waited picks up the same link and code rather
+         * than asking the person to approve a new one. Unreadable or stale ones
+         * read as none. */
+        async readPending() {
+            let text;
+            try {
+                text = await readPrivate(pendingFile, 8192, "pending connection");
+            }
+            catch {
+                return null;
+            }
+            if (text === null)
+                return null;
+            try {
+                const pending = JSON.parse(text);
+                if (pending.version !== 1 ||
+                    pending.apiOrigin !== origins.api ||
+                    pending.authOrigin !== origins.auth ||
+                    typeof pending.privateKey !== "string" ||
+                    typeof pending.deviceCode !== "string" ||
+                    typeof pending.url !== "string" ||
+                    typeof pending.userCode !== "string" ||
+                    typeof pending.agentName !== "string" ||
+                    typeof pending.expiresAt !== "number" ||
+                    pending.expiresAt <= Date.now())
+                    return null;
+                return pending;
+            }
+            catch {
+                return null;
+            }
+        },
+        async savePending(pending) {
+            await writePrivate(pendingFile, JSON.stringify(pending));
+        },
+        async removePending() {
+            await removePrivate(pendingFile);
+        },
+    };
+}
+export async function resolveCredential(env) {
+    if (env.RUNTIME_API_KEY) {
+        if (/\s/.test(env.RUNTIME_API_KEY))
+            throw new Error("RUNTIME_API_KEY is invalid.");
+        return env.RUNTIME_API_KEY;
+    }
+    const saved = await connectionStore(env).read();
+    if (!saved)
+        throw notConnected();
+    return saved.key;
+}
+/** No key in the environment and none saved on this machine. */
+export const notConnected = missingKey;

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+/** Every failure the SDK raises. `code` is stable and machine-readable,
+ * `hint` says what to do next, and `requestId` is what to quote in a report
+ * (runtime.feedback.submit, `runtime feedback`, or support). */
+export declare class RuntimeError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string;
+    readonly hint?: string;
+    readonly details?: Record<string, unknown>;
+    /** The key the SDK sent. A retry with it never repeats the effect. */
+    readonly idempotencyKey?: string;
+    readonly retryAfterMs?: number;
+    constructor(init: {
+        message: string;
+        code: string;
+        status: number;
+        requestId?: string;
+        hint?: string;
+        details?: Record<string, unknown>;
+        idempotencyKey?: string;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+    /** Retrying this exact call (the SDK keeps the key) is safe and may work. */
+    get retryable(): boolean;
+    toString(): string;
+}
+export declare class AuthenticationError extends RuntimeError {
+}
+export declare class PermissionDeniedError extends RuntimeError {
+}
+export declare class NotFoundError extends RuntimeError {
+}
+export declare class ConflictError extends RuntimeError {
+}
+export declare class InvalidRequestError extends RuntimeError {
+}
+export declare class RateLimitError extends RuntimeError {
+}
+export declare class ServiceUnavailableError extends RuntimeError {
+}
+/** No answer arrived. A write may or may not have happened; retrying with the
+ * same idempotencyKey (the SDK does, automatically) settles it safely. */
+export declare class ConnectionError extends RuntimeError {
+}
+/** Raised by exec({ check: true }) when a command exits non-zero. */
+export declare class CommandError extends RuntimeError {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(result: {
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+        timedOut?: boolean;
+    });
+}
+export declare function errorFor(status: number, body: unknown, idempotencyKey?: string): RuntimeError;

package/dist/errors.js

@@ -0,0 +1,106 @@
+/** Every failure the SDK raises. `code` is stable and machine-readable,
+ * `hint` says what to do next, and `requestId` is what to quote in a report
+ * (runtime.feedback.submit, `runtime feedback`, or support). */
+export class RuntimeError extends Error {
+    code;
+    status;
+    requestId;
+    hint;
+    details;
+    /** The key the SDK sent. A retry with it never repeats the effect. */
+    idempotencyKey;
+    retryAfterMs;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = new.target.name;
+        this.code = init.code;
+        this.status = init.status;
+        if (init.requestId !== undefined)
+            this.requestId = init.requestId;
+        if (init.hint !== undefined)
+            this.hint = init.hint;
+        if (init.details !== undefined)
+            this.details = init.details;
+        if (init.idempotencyKey !== undefined)
+            this.idempotencyKey = init.idempotencyKey;
+        if (init.retryAfterMs !== undefined)
+            this.retryAfterMs = init.retryAfterMs;
+    }
+    /** Retrying this exact call (the SDK keeps the key) is safe and may work. */
+    get retryable() {
+        return (this.status === 0 ||
+            this.status === 429 ||
+            this.status === 502 ||
+            this.status === 503 ||
+            this.status === 504);
+    }
+    toString() {
+        return `${this.name} [${this.code}${this.status ? ` ${this.status}` : ""}]: ${this.message}${this.hint ? `\nHint: ${this.hint}` : ""}${this.requestId ? `\nRequest: ${this.requestId}` : ""}`;
+    }
+}
+export class AuthenticationError extends RuntimeError {
+}
+export class PermissionDeniedError extends RuntimeError {
+}
+export class NotFoundError extends RuntimeError {
+}
+export class ConflictError extends RuntimeError {
+}
+export class InvalidRequestError extends RuntimeError {
+}
+export class RateLimitError extends RuntimeError {
+}
+export class ServiceUnavailableError extends RuntimeError {
+}
+/** No answer arrived. A write may or may not have happened; retrying with the
+ * same idempotencyKey (the SDK does, automatically) settles it safely. */
+export class ConnectionError extends RuntimeError {
+}
+/** Raised by exec({ check: true }) when a command exits non-zero. */
+export class CommandError extends RuntimeError {
+    exitCode;
+    stdout;
+    stderr;
+    constructor(result) {
+        super({
+            message: result.timedOut
+                ? "Command timed out."
+                : `Command exited with ${result.exitCode}.${result.stderr ? ` ${result.stderr.trim().slice(-500)}` : ""}`,
+            code: result.timedOut ? "command_timeout" : "command_failed",
+            status: 0,
+        });
+        this.exitCode = result.exitCode;
+        this.stdout = result.stdout;
+        this.stderr = result.stderr;
+    }
+}
+export function errorFor(status, body, idempotencyKey) {
+    const error = body?.error ?? {};
+    const init = {
+        message: typeof error.message === "string" ? error.message : `Runtime request failed (${status}).`,
+        code: typeof error.code === "string" ? error.code : "request_failed",
+        status,
+        ...(typeof error.requestId === "string" ? { requestId: error.requestId } : {}),
+        ...(typeof error.hint === "string" ? { hint: error.hint } : {}),
+        ...(error.details && typeof error.details === "object"
+            ? { details: error.details }
+            : {}),
+        ...(typeof error.retryAfterMs === "number" ? { retryAfterMs: error.retryAfterMs } : {}),
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+    };
+    if (status === 401)
+        return new AuthenticationError(init);
+    if (status === 403)
+        return new PermissionDeniedError(init);
+    if (status === 404)
+        return new NotFoundError(init);
+    if (status === 409)
+        return new ConflictError(init);
+    if (status === 400 || status === 422 || status === 413)
+        return new InvalidRequestError(init);
+    if (status === 429)
+        return new RateLimitError(init);
+    if (status >= 500)
+        return new ServiceUnavailableError(init);
+    return new RuntimeError(init);
+}