withruntime 0.2.2 → 0.3.1

package/dist/products/interpreter.d.ts

@@ -0,0 +1,88 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type InterpreterLanguage = "python" | "javascript";
+export type ResultRef = {
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+/** One rich result: a MIME bundle (text/plain, text/html, image/png as base64,
+ * application/json, application/vnd.runtime.table+json for a DataFrame). */
+export type ExecutionResult = {
+    main: boolean;
+    data: Record<string, unknown>;
+    refs: Record<string, ResultRef>;
+};
+export type Execution = {
+    id: string;
+    contextId: string;
+    language: InterpreterLanguage;
+    executionCount: number | null;
+    status: "ok" | "error" | "interrupted" | "timeout" | "lost";
+    stdout: string;
+    stderr: string;
+    results: ExecutionResult[];
+    error: {
+        name: string;
+        value: string;
+        traceback: string;
+    } | null;
+    overflow: {
+        stream: "stdout" | "stderr";
+        path: string | null;
+        bytes: number;
+        dropped: number;
+    }[];
+    durationMs: number;
+    contextStarted: boolean;
+    lostBytes: number;
+};
+export type InterpreterContext = {
+    id: string;
+    language: InterpreterLanguage;
+    processId: string;
+    cwd: string;
+    state: string;
+    startedAt: number;
+};
+export type RunOptions = RequestOptions & {
+    language?: InterpreterLanguage;
+    /** A context id; "python" and "javascript" are the defaults, started on first use. */
+    context?: string;
+    timeoutMs?: number;
+    onStdout?: (text: string) => void;
+    onStderr?: (text: string) => void;
+    onResult?: (result: ExecutionResult) => void;
+    onError?: (error: {
+        name: string;
+        value: string;
+        traceback: string;
+    }) => void;
+};
+/** A stateful Python and JavaScript interpreter in the sandbox:
+ * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
+ * Variables persist between runs of the same context, like a notebook. */
+export declare function sandboxInterpreter(t: Transport, sandbox: Sandbox): {
+    /** Run a cell. With any of the on* callbacks, output streams as it happens. */
+    run(code: string, options?: RunOptions): Promise<Execution>;
+    contexts: {
+        list: (options?: RequestOptions) => Promise<InterpreterContext[]>;
+        create: (input?: {
+            id?: string;
+            language?: InterpreterLanguage;
+            cwd?: string;
+            env?: Record<string, string>;
+        }, options?: RequestOptions) => Promise<InterpreterContext>;
+        restart: (id: string, options?: RequestOptions) => Promise<InterpreterContext>;
+        interrupt: (id: string, options?: RequestOptions) => Promise<{
+            interrupted: boolean;
+        }>;
+        remove: (id: string, options?: RequestOptions) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    /** The bytes of a result too large to travel inline (a `refs` entry). */
+    result(ref: ResultRef | {
+        path: string;
+    }, options?: RequestOptions): Promise<Uint8Array>;
+};

package/dist/products/interpreter.js

@@ -0,0 +1,81 @@
+/** A stateful Python and JavaScript interpreter in the sandbox:
+ * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
+ * Variables persist between runs of the same context, like a notebook. */
+export function sandboxInterpreter(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/interpreter`;
+    return {
+        /** Run a cell. With any of the on* callbacks, output streams as it happens. */
+        async run(code, options = {}) {
+            const { language, context, timeoutMs, onStdout, onStderr, onResult, onError, ...request } = options;
+            const body = {
+                code,
+                ...(language ? { language } : {}),
+                ...(context ? { context } : {}),
+                ...(timeoutMs ? { timeoutMs } : {}),
+            };
+            if (!onStdout && !onStderr && !onResult && !onError)
+                return t.json({ method: "POST", path: `${base()}:run`, body, ...request });
+            for await (const event of t.events({
+                method: "POST",
+                path: `${base()}:run`,
+                body: { ...body, stream: true },
+                ...request,
+            })) {
+                if (event.k === "stdout")
+                    onStdout?.(event.text);
+                else if (event.k === "stderr")
+                    onStderr?.(event.text);
+                else if (event.k === "result")
+                    onResult?.({ main: event.main, data: event.data, refs: event.refs });
+                else if (event.k === "error")
+                    onError?.(event);
+                else if (event.k === "execution")
+                    return event.execution;
+                else if (event.k === "failure")
+                    throw new Error(`${event.code}: ${event.message}`);
+            }
+            throw new Error("The interpreter stream ended without a result");
+        },
+        contexts: {
+            list: async (options) => (await t.json({
+                method: "GET",
+                path: `${base()}/contexts`,
+                ...options,
+            })).data,
+            create: (input = {}, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts`,
+                body: input,
+                ...options,
+            }),
+            restart: (id, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts/${encodeURIComponent(id)}:restart`,
+                body: {},
+                ...options,
+            }),
+            interrupt: (id, options) => t.json({
+                method: "POST",
+                path: `${base()}/contexts/${encodeURIComponent(id)}:interrupt`,
+                body: {},
+                ...options,
+            }),
+            remove: (id, options) => t.json({
+                method: "DELETE",
+                path: `${base()}/contexts/${encodeURIComponent(id)}`,
+                ...options,
+            }),
+        },
+        /** The bytes of a result too large to travel inline (a `refs` entry). */
+        result(ref, options) {
+            const match = /^\/workspace\/\.runtime\/interpreter\/([a-z0-9][a-z0-9-]*)\/out\/([A-Za-z0-9][A-Za-z0-9_.-]*)$/.exec(ref.path);
+            if (!match)
+                throw new Error("Not an interpreter result path");
+            return t.bytes({
+                method: "GET",
+                path: `${base()}/contexts/${match[1]}/results/${match[2]}`,
+                ...options,
+            });
+        },
+    };
+}

package/dist/products/limits.d.ts

@@ -0,0 +1,25 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** What this key may do, and the daily spending limit on its agent. Money is
+ * integer microdollars in strings (1,000,000 = $1). */
+export type KeyLimits = {
+    /** full: every action. read: every read and nothing else (a read-only key).
+     * selected: the actions the key names. */
+    access: "full" | "read" | "selected" | null;
+    daily: {
+        /** The most this agent may commit in any 24 hours, or null for no limit. */
+        limitMicros: string | null;
+        /** Committed in the last 24 hours: charges settled plus money on hold. */
+        usedMicros: string;
+        /** What is left under the limit now, or null for no limit. */
+        remainingMicros: string | null;
+        window: "24h";
+    };
+};
+/** `runtime.limits.get()`: whether this key is read-only, and what its agent
+ * may still spend today. An owner sets the limit at
+ * https://withruntime.com/account/keys; a key can read it, never change it.
+ * Past it, a create, wake, extension or renewal fails with
+ * `spending_limit_reached` (HTTP 402). */
+export declare function limits(t: Transport): {
+    get: (options?: RequestOptions) => Promise<KeyLimits>;
+};

package/dist/products/limits.js

@@ -0,0 +1,10 @@
+/** `runtime.limits.get()`: whether this key is read-only, and what its agent
+ * may still spend today. An owner sets the limit at
+ * https://withruntime.com/account/keys; a key can read it, never change it.
+ * Past it, a create, wake, extension or renewal fails with
+ * `spending_limit_reached` (HTTP 402). */
+export function limits(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/limits", ...options }),
+    };
+}

package/dist/products/network.d.ts

@@ -0,0 +1,47 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** A sandbox's own network rules. */
+export type NetworkRules = {
+    /** false refuses every outbound connection. */
+    internet: boolean;
+    /** When not empty, only these web destinations are reachable: `example.com`,
+     * `*.example.com` (subdomains, not the apex), an address or a CIDR range. */
+    allow?: string[];
+    /** Never reachable. Wins over everything. */
+    deny?: string[];
+    /** host:port pairs beyond ports 80 and 443, such as `db.example.com:5432` or
+     * `github.com:22`. Paid sandboxes of organizations with a paid purchase
+     * only. In the sandbox, `python3 /usr/local/lib/runtime/guest-egress.py
+     * forward 5432 db.example.com:5432` gives psql a local port. */
+    connect?: string[];
+};
+export type NetworkPolicy = Required<NetworkRules> & {
+    sandboxId: string;
+    version: number;
+    /** The sandbox's host confirmed it enforces this version. */
+    enforced: boolean;
+    enforcedVersion: number;
+    /** Ports reachable without a connect entry. */
+    ports: number[];
+    connectAllowed: boolean;
+    /** paid, granted, not_paid, revoked or suspended. */
+    connectReason: string;
+    forbiddenPorts: number[];
+    updatedAt: string | null;
+};
+/** `sbx.network`: turn the sandbox's internet off or on, narrow it to a list,
+ * refuse destinations, or open host:port pairs. Changes apply at once, to open
+ * connections too.
+ *
+ *   await sbx.network.set({ internet: true, allow: ["registry.npmjs.org"] });
+ *   await sbx.network.set({ internet: false });
+ */
+export declare function sandboxNetwork(t: Transport, sandbox: Sandbox): {
+    get: (options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** Replaces the rules. */
+    set: (rules: NetworkRules, options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** No outbound connections at all. */
+    off: (options?: RequestOptions) => Promise<NetworkPolicy>;
+    /** The host's public-web policy and nothing narrower. */
+    on: (options?: RequestOptions) => Promise<NetworkPolicy>;
+};

package/dist/products/network.js

@@ -0,0 +1,19 @@
+/** `sbx.network`: turn the sandbox's internet off or on, narrow it to a list,
+ * refuse destinations, or open host:port pairs. Changes apply at once, to open
+ * connections too.
+ *
+ *   await sbx.network.set({ internet: true, allow: ["registry.npmjs.org"] });
+ *   await sbx.network.set({ internet: false });
+ */
+export function sandboxNetwork(t, sandbox) {
+    const path = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/network`;
+    return {
+        get: (options) => t.json({ method: "GET", path: path(), ...options }),
+        /** Replaces the rules. */
+        set: (rules, options) => t.json({ method: "PUT", path: path(), body: rules, ...options }),
+        /** No outbound connections at all. */
+        off: (options) => t.json({ method: "PUT", path: path(), body: { internet: false }, ...options }),
+        /** The host's public-web policy and nothing narrower. */
+        on: (options) => t.json({ method: "PUT", path: path(), body: { internet: true }, ...options }),
+    };
+}

package/dist/products/previews.d.ts

@@ -0,0 +1,54 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** A public HTTPS address for a port inside a sandbox. */
+export type Preview = {
+    id: string;
+    sandboxId: string;
+    port: number;
+    visibility: "private" | "public";
+    /** `https://<port>-<sandbox>.<preview domain>/`. A private preview also
+     * needs the token. */
+    url: string;
+    /** Private previews: a fresh signed token. Send it as the
+     * `x-runtime-preview-token` header. */
+    token: string | null;
+    tokenExpiresAt: string | null;
+    /** Private previews: a link that carries the token once, for a browser. */
+    urlWithToken: string | null;
+    /** Turned off by Runtime after a report. */
+    disabled: boolean;
+    createdAt: string;
+    /** On create only: how to share the address, and the referral link that
+     * pays you both when someone you share it with signs up. */
+    hint?: string;
+};
+export type CreatePreview = {
+    /** private (default): a token is needed. public: anyone with the address;
+     * a browser sees a one-time warning page naming Runtime. */
+    visibility?: "private" | "public";
+    /** How long the returned token lasts, 60 s to 7 days (default 1 day). */
+    ttlSeconds?: number;
+};
+/** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
+ *
+ *   const { url, token } = await sbx.previews.create(3000);
+ *   await fetch(url, { headers: { "x-runtime-preview-token": token! } });
+ *
+ * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
+export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
+    /** Shares `port`, or changes its visibility if it is shared already. */
+    create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
+    /** Every shared port, each private one with a fresh token. */
+    list: (options?: RequestOptions) => Promise<Preview[]>;
+    /** One preview, with a fresh token of `ttlSeconds` if it is private. */
+    get: (port: number, ttlSeconds?: number, options?: RequestOptions) => Promise<Preview>;
+    /** Refuses every token issued for this port so far and returns a new one. */
+    rotate: (port: number, options?: RequestOptions) => Promise<Preview>;
+    /** Stops sharing `port`. Open connections close within seconds. */
+    delete: (port: number, options?: RequestOptions) => Promise<{
+        id: string;
+        sandboxId: string;
+        port: number;
+        deleted: true;
+    }>;
+};

package/dist/products/previews.js

@@ -0,0 +1,30 @@
+/** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
+ *
+ *   const { url, token } = await sbx.previews.create(3000);
+ *   await fetch(url, { headers: { "x-runtime-preview-token": token! } });
+ *
+ * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
+export function sandboxPreviews(t, sandbox) {
+    const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/previews`;
+    return {
+        /** Shares `port`, or changes its visibility if it is shared already. */
+        create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
+        /** Every shared port, each private one with a fresh token. */
+        list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
+        /** One preview, with a fresh token of `ttlSeconds` if it is private. */
+        get: (port, ttlSeconds, options) => t.json({
+            method: "GET",
+            path: `${base()}/${port}`,
+            ...(ttlSeconds ? { query: { ttlSeconds } } : {}),
+            ...options,
+        }),
+        /** Refuses every token issued for this port so far and returns a new one. */
+        rotate: (port, options) => t.json({ method: "POST", path: `${base()}/${port}:rotate`, ...options }),
+        /** Stops sharing `port`. Open connections close within seconds. */
+        delete: (port, options) => t.json({
+            method: "DELETE",
+            path: `${base()}/${port}`,
+            ...options,
+        }),
+    };
+}

package/dist/products/referrals.d.ts

@@ -0,0 +1,36 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** Your organization's referral link and what it has earned. Money is integer
+ * microdollars in strings (1,000,000 = $1). */
+export type ReferralSummary = {
+    code: string;
+    /** Share this: https://withruntime.com/r/<code>. */
+    link: string;
+    /** The least each side gets: a first top-up is matched, never below this. */
+    rewardMicros: string;
+    /** The most each side gets: a first top-up is matched up to this. */
+    maxRewardMicros: string;
+    /** The smallest first top-up that pays a referral. */
+    minPurchaseMicros: string;
+    /** The most referral credit you can earn in one calendar year (UTC). */
+    yearlyCapMicros: string;
+    enabled: boolean;
+    year: number;
+    signedUp: number;
+    pending: number;
+    paid: number;
+    capped: number;
+    reversed: number;
+    earnedMicros: string;
+    earnedThisYearMicros: string;
+    capRemainingMicros: string;
+    referredBy: {
+        status: "pending" | "paid" | "refused" | "reversed";
+        creditMicros: string;
+    } | null;
+};
+/** `runtime.referrals.get()`: when a company that signs up with your link makes
+ * its first top-up of at least $10, you and it each get credit equal to that
+ * top-up, at least $25 and at most $500. */
+export declare function referrals(t: Transport): {
+    get: (options?: RequestOptions) => Promise<ReferralSummary>;
+};

package/dist/products/referrals.js

@@ -0,0 +1,8 @@
+/** `runtime.referrals.get()`: when a company that signs up with your link makes
+ * its first top-up of at least $10, you and it each get credit equal to that
+ * top-up, at least $25 and at most $500. */
+export function referrals(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/referrals", ...options }),
+    };
+}

package/dist/products/volumes.d.ts

@@ -0,0 +1,47 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type VolumeState = "creating" | "ready" | "failed" | "deleting" | "deleted";
+export type Volume = {
+    id: string;
+    kind: "volume";
+    status: string;
+    state: VolumeState;
+    name: string | null;
+    labels: Record<string, string>;
+    region: string;
+    sizeMiB: number;
+    filesystem: "ext4";
+    usedMiB: number | null;
+    measuredAt: string | null;
+    /** Always false: a volume lives on one host and is not copied off it. */
+    backedUp: false;
+    attachments: {
+        sandboxId: string;
+        mode: "rw" | "snapshot";
+        path: string;
+        attachedAt: string;
+    }[];
+    error: string | null;
+    createdAt: string;
+    readyAt: string | null;
+};
+export type CreateVolume = {
+    sizeMiB: number;
+    name?: string;
+    labels?: Record<string, string>;
+    region?: string;
+};
+/** Persistent disks: create once, attach when creating a sandbox with
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+export declare function volumes(t: Transport): {
+    /** Create and wait (up to 10 s) until it is ready. */
+    create: (input: CreateVolume, options?: RequestOptions) => Promise<Volume>;
+    get: (id: string, options?: RequestOptions) => Promise<Volume>;
+    list: (query?: {
+        state?: VolumeState;
+        name?: string;
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<Page<Volume>>;
+    delete: (id: string, options?: RequestOptions) => Promise<Volume>;
+};

package/dist/products/volumes.js

@@ -0,0 +1,27 @@
+import { Page } from "../page.js";
+/** Persistent disks: create once, attach when creating a sandbox with
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+export function volumes(t) {
+    const get = (id, options) => t.json({ method: "GET", path: `/v1/volumes/${encodeURIComponent(id)}`, ...options });
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/volumes",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    return {
+        /** Create and wait (up to 10 s) until it is ready. */
+        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`,
+            body: {},
+            ...options,
+        }),
+    };
+}