withruntime 0.3.1 → 0.5.0

package/dist/products/observability.d.ts

@@ -0,0 +1,186 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type MetricRange = "15m" | "1h" | "6h" | "24h" | "7d" | "30d";
+export type MetricPoint = {
+    /** Start of the bucket, ISO 8601. */
+    at: string;
+    /** Average CPU, percent of all the sandbox's vCPUs (0-100). */
+    cpuPercent: number | null;
+    /** The same average as a number of cores. */
+    cpuCores: number | null;
+    /** The busiest interval between two readings in the bucket. */
+    cpuPeakPercent: number | null;
+    /** Average resident memory, bytes. */
+    memoryBytes: number;
+    memoryPeakBytes: number;
+    /** Host readings in the bucket. */
+    samples: number;
+};
+export type SandboxMetrics = {
+    sandboxId: string;
+    range: MetricRange;
+    stepSeconds: number;
+    since: string;
+    until: string;
+    vcpu: number;
+    memoryLimitBytes: number;
+    diskLimitBytes: number;
+    state: string;
+    /** The newest reading, or null when there is none in the last 15 minutes. */
+    latest: MetricPoint | null;
+    points: MetricPoint[];
+};
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted";
+/** An event as /v1/events lists it and a webhook delivers it. */
+export type RuntimeEvent = {
+    id: string;
+    type: WebhookEventType | "webhook.test";
+    createdAt: string;
+    resourceId?: string | null;
+    /** The resource as it was: `data.sandbox`, `data.snapshot` or `data.volume`. */
+    data: Record<string, unknown>;
+};
+export type Webhook = {
+    id: string;
+    url: string;
+    description: string | null;
+    events: Array<WebhookEventType | "*">;
+    enabled: boolean;
+    /** The secret's last four characters. */
+    secretHint: string;
+    previousSecretExpiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastSuccessAt: string | null;
+    lastFailureAt: string | null;
+    /** The first failure since the last success, or null while it succeeds. */
+    failingSince: string | null;
+    /** The signing secret: only on create and rotateSecret. Keep it. */
+    secret?: string;
+};
+export type WebhookDelivery = {
+    id: string;
+    endpointId: string;
+    eventId: string;
+    eventType: string;
+    resourceId: string | null;
+    state: "pending" | "succeeded" | "failed" | "cancelled";
+    attempts: number;
+    maxAttempts: number;
+    nextAttemptAt: string | null;
+    /** The HTTP status your endpoint answered. */
+    lastStatus: number | null;
+    lastError: string | null;
+    lastDurationMs: number | null;
+    lastAttemptAt: string | null;
+    deliveredAt: string | null;
+    createdAt: string;
+};
+export type OtelExport = {
+    id: string;
+    endpoint: string;
+    /** Header names only; values are never shown back. */
+    headerNames: string[];
+    signals: Array<"logs" | "metrics">;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+    lastAttemptAt: string | null;
+    lastSuccessAt: string | null;
+    lastError: string | null;
+    failures: number;
+    exportedEvents: number;
+    exportedPoints: number;
+};
+type List<T> = {
+    data: T[];
+    nextCursor: string | null;
+};
+/** `sbx.metrics()`: this sandbox's measured CPU and memory. */
+export declare function sandboxMetrics(t: Transport, sandbox: Sandbox): (options?: {
+    range?: MetricRange;
+} & RequestOptions) => Promise<SandboxMetrics>;
+/** `runtime.events.list()`: lifecycle events, newest first. */
+export declare function events(t: Transport): {
+    list: (filter?: {
+        resourceId?: string;
+        type?: WebhookEventType;
+        cursor?: string;
+        limit?: number;
+    }, options?: RequestOptions) => Promise<List<RuntimeEvent>>;
+};
+/** `runtime.webhooks`: signed lifecycle events POSTed to your URL. */
+export declare function webhooks(t: Transport): {
+    /** Returns the webhook with `secret`, shown this once. */
+    create: (input: {
+        url: string;
+        events?: Array<WebhookEventType | "*">;
+        description?: string;
+    }, options?: RequestOptions) => Promise<Webhook>;
+    list: (options?: RequestOptions) => Promise<List<Webhook>>;
+    get: (id: string, options?: RequestOptions) => Promise<Webhook>;
+    update: (id: string, patch: {
+        url?: string;
+        events?: Array<WebhookEventType | "*">;
+        description?: string | null;
+        enabled?: boolean;
+    }, options?: RequestOptions) => Promise<Webhook>;
+    /** A new secret, returned once. The old one keeps signing beside it for
+     * `keepPreviousSeconds` (a day by default, a week at most; 0 ends it now). */
+    rotateSecret: (id: string, input?: {
+        keepPreviousSeconds?: number;
+    }, options?: RequestOptions) => Promise<Webhook>;
+    delete: (id: string, options?: RequestOptions) => Promise<Webhook>;
+    /** Sends a signed `webhook.test` now and answers how your endpoint replied. */
+    test: (id: string, options?: RequestOptions) => Promise<WebhookDelivery>;
+    deliveries: (id: string, filter?: {
+        state?: WebhookDelivery["state"];
+        cursor?: string;
+        limit?: number;
+    }, options?: RequestOptions) => Promise<List<WebhookDelivery>>;
+    /** Sends one delivery again, once, now. */
+    retry: (deliveryId: string, options?: RequestOptions) => Promise<WebhookDelivery>;
+};
+/** `runtime.otel`: push events (as logs) and CPU and memory (as metrics) to an
+ * OpenTelemetry endpoint over OTLP/HTTP. */
+export declare function otel(t: Transport): {
+    create: (input: {
+        /** The OTLP/HTTP base URL, as OTEL_EXPORTER_OTLP_ENDPOINT. */
+        endpoint: string;
+        /** For the endpoint's authentication; never shown back. */
+        headers?: Record<string, string>;
+        signals?: Array<"logs" | "metrics">;
+    }, options?: RequestOptions) => Promise<OtelExport>;
+    list: (options?: RequestOptions) => Promise<List<OtelExport>>;
+    get: (id: string, options?: RequestOptions) => Promise<OtelExport>;
+    update: (id: string, patch: {
+        endpoint?: string;
+        headers?: Record<string, string>;
+        signals?: Array<"logs" | "metrics">;
+        enabled?: boolean;
+    }, options?: RequestOptions) => Promise<OtelExport>;
+    /** Push now instead of at the next interval. */
+    flush: (id: string, options?: RequestOptions) => Promise<OtelExport>;
+    delete: (id: string, options?: RequestOptions) => Promise<OtelExport>;
+};
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+/** Checks a webhook's `Runtime-Signature` header against the raw body and
+ * your secret (or secrets, during a rotation), and returns the event. Throws
+ * `WebhookVerificationError` when the signature does not match or is older
+ * than `toleranceSeconds` (300 by default), which stops a captured delivery
+ * being replayed. Pass the body exactly as received, before any JSON parsing.
+ *
+ *   app.post("/hooks/runtime", express.raw({ type: "application/json" }), async (req, res) => {
+ *     const event = await verifyWebhook(req.body, req.get("runtime-signature"), process.env.RUNTIME_WEBHOOK_SECRET!);
+ *     if (event.type === "sandbox.stopped") ...
+ *     res.sendStatus(204);
+ *   });
+ *
+ * Works wherever Web Crypto does: Node 18+, Bun, Deno, Cloudflare Workers, browsers. */
+export declare function verifyWebhook(body: string | Uint8Array, header: string | null | undefined, secret: string | readonly string[], options?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<RuntimeEvent>;
+export {};

package/dist/products/observability.js

@@ -0,0 +1,117 @@
+/** `sbx.metrics()`: this sandbox's measured CPU and memory. */
+export function sandboxMetrics(t, sandbox) {
+    return (options = {}) => {
+        const { range, ...rest } = options;
+        return t.json({
+            method: "GET",
+            path: `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/metrics`,
+            query: { range },
+            ...rest,
+        });
+    };
+}
+/** `runtime.events.list()`: lifecycle events, newest first. */
+export function events(t) {
+    return {
+        list: (filter = {}, options) => t.json({ method: "GET", path: "/v1/events", query: filter, ...options }),
+    };
+}
+/** `runtime.webhooks`: signed lifecycle events POSTed to your URL. */
+export function webhooks(t) {
+    const one = (id, verb = "") => `/v1/webhooks/${encodeURIComponent(id)}${verb}`;
+    return {
+        /** Returns the webhook with `secret`, shown this once. */
+        create: (input, options) => t.json({ method: "POST", path: "/v1/webhooks", body: input, ...options }),
+        list: (options) => t.json({ method: "GET", path: "/v1/webhooks", ...options }),
+        get: (id, options) => t.json({ method: "GET", path: one(id), ...options }),
+        update: (id, patch, options) => t.json({ method: "POST", path: one(id, ":update"), body: patch, ...options }),
+        /** A new secret, returned once. The old one keeps signing beside it for
+         * `keepPreviousSeconds` (a day by default, a week at most; 0 ends it now). */
+        rotateSecret: (id, input = {}, options) => t.json({ method: "POST", path: one(id, ":rotate-secret"), body: input, ...options }),
+        delete: (id, options) => t.json({ method: "POST", path: one(id, ":delete"), ...options }),
+        /** Sends a signed `webhook.test` now and answers how your endpoint replied. */
+        test: (id, options) => t.json({ method: "POST", path: one(id, ":test"), wait: 10, ...options }),
+        deliveries: (id, filter = {}, options) => t.json({
+            method: "GET",
+            path: one(id, "/deliveries"),
+            query: filter,
+            ...options,
+        }),
+        /** Sends one delivery again, once, now. */
+        retry: (deliveryId, options) => t.json({
+            method: "POST",
+            path: `/v1/webhook-deliveries/${encodeURIComponent(deliveryId)}:retry`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.otel`: push events (as logs) and CPU and memory (as metrics) to an
+ * OpenTelemetry endpoint over OTLP/HTTP. */
+export function otel(t) {
+    const one = (id, verb = "") => `/v1/otel-exports/${encodeURIComponent(id)}${verb}`;
+    return {
+        create: (input, options) => t.json({ method: "POST", path: "/v1/otel-exports", body: input, ...options }),
+        list: (options) => t.json({ method: "GET", path: "/v1/otel-exports", ...options }),
+        get: (id, options) => t.json({ method: "GET", path: one(id), ...options }),
+        update: (id, patch, options) => t.json({ method: "POST", path: one(id, ":update"), body: patch, ...options }),
+        /** Push now instead of at the next interval. */
+        flush: (id, options) => t.json({ method: "POST", path: one(id, ":flush"), ...options }),
+        delete: (id, options) => t.json({ method: "POST", path: one(id, ":delete"), ...options }),
+    };
+}
+// ------------------------------------------------------------------ verify
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+const hex = (bytes) => [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+function sameText(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** Checks a webhook's `Runtime-Signature` header against the raw body and
+ * your secret (or secrets, during a rotation), and returns the event. Throws
+ * `WebhookVerificationError` when the signature does not match or is older
+ * than `toleranceSeconds` (300 by default), which stops a captured delivery
+ * being replayed. Pass the body exactly as received, before any JSON parsing.
+ *
+ *   app.post("/hooks/runtime", express.raw({ type: "application/json" }), async (req, res) => {
+ *     const event = await verifyWebhook(req.body, req.get("runtime-signature"), process.env.RUNTIME_WEBHOOK_SECRET!);
+ *     if (event.type === "sandbox.stopped") ...
+ *     res.sendStatus(204);
+ *   });
+ *
+ * Works wherever Web Crypto does: Node 18+, Bun, Deno, Cloudflare Workers, browsers. */
+export async function verifyWebhook(body, header, secret, options = {}) {
+    const text = typeof body === "string" ? body : new TextDecoder().decode(body);
+    if (!header)
+        throw new WebhookVerificationError("Missing Runtime-Signature header.");
+    const parts = header.split(",").map((part) => part.trim().split("="));
+    const t = Number(parts.find(([key]) => key === "t")?.[1]);
+    const given = parts.filter(([key, value]) => key === "v1" && value).map(([, value]) => value);
+    if (!Number.isSafeInteger(t) || !given.length)
+        throw new WebhookVerificationError("Malformed Runtime-Signature header.");
+    const now = options.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - t) > (options.toleranceSeconds ?? 300))
+        throw new WebhookVerificationError("The signature is too old; the delivery may be a replay.");
+    const encoder = new TextEncoder();
+    for (const key of typeof secret === "string" ? [secret] : secret) {
+        const hmac = await crypto.subtle.importKey("raw", encoder.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const expected = hex(await crypto.subtle.sign("HMAC", hmac, encoder.encode(`${t}.${text}`)));
+        if (given.some((value) => sameText(value, expected))) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new WebhookVerificationError("The body is not JSON.");
+            }
+        }
+    }
+    throw new WebhookVerificationError("No signature matches the secret.");
+}

package/dist/products/secrets.d.ts

@@ -0,0 +1,40 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** A secret your sandboxes use without seeing it. Every sandbox of your
+ * organization has an environment variable of the secret's name holding
+ * `placeholder`; the egress proxy puts the value into HTTPS requests to
+ * `hosts` (in the URL and headers), or sets `header` on every such request.
+ * The value is never returned. */
+export type Secret = {
+    name: string;
+    hosts: string[];
+    header?: string;
+    format?: string;
+    placeholder: string;
+    valueBytes: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type SetSecret = {
+    /** Visible ASCII and spaces, at most 8 KiB. Stored sealed; never returned. */
+    value: string;
+    /** Where the value may go: `api.openai.com`, `*.github.com`. 1 to 16. */
+    hosts: string[];
+    /** Set this header on every request to the hosts, replacing the sandbox's own. */
+    header?: string;
+    /** With `header`: its value, `{value}` where the secret goes. Default `{value}`. */
+    format?: string;
+};
+export declare function secrets(t: Transport): {
+    /** Store or replace a secret. Replacing keeps its placeholder. */
+    set: (name: string, input: SetSecret, options?: RequestOptions) => Promise<Secret & {
+        enforced: boolean;
+    }>;
+    /** Names, hosts and placeholders. Never values. */
+    list: (options?: RequestOptions) => Promise<Secret[]>;
+    /** Delete a secret: its value is erased and its placeholder stops working. */
+    delete: (name: string, options?: RequestOptions) => Promise<{
+        name: string;
+        deleted: true;
+        enforced: boolean;
+    }>;
+};

package/dist/products/secrets.js

@@ -0,0 +1,24 @@
+export function secrets(t) {
+    const path = (name) => `/v1/egress-secrets/${encodeURIComponent(name)}`;
+    return {
+        /** Store or replace a secret. Replacing keeps its placeholder. */
+        set: (name, input, options) => t.json({
+            method: "PUT",
+            path: path(name),
+            body: input,
+            ...options,
+        }),
+        /** Names, hosts and placeholders. Never values. */
+        list: async (options) => (await t.json({
+            method: "GET",
+            path: "/v1/egress-secrets",
+            ...options,
+        })).secrets,
+        /** Delete a secret: its value is erased and its placeholder stops working. */
+        delete: (name, options) => t.json({
+            method: "DELETE",
+            path: path(name),
+            ...options,
+        }),
+    };
+}

package/dist/products/switching.d.ts

@@ -0,0 +1,89 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** The rivals a comparison prices. `fly` is Sprites; `fly-machines` is
+ * Machines, priced only at the size Fly publishes a rate for here. The server
+ * prices every rival its rates table carries and names them when it refuses
+ * one, so any string is sent as it is. */
+export type CompareProvider = "e2b" | "daytona" | "vercel" | "modal" | "cloudflare" | "fly" | "fly-machines" | (string & {});
+/** The rivals a switch can be recorded from. */
+export type SwitchProvider = "e2b" | "daytona" | "vercel" | "modal" | "cloudflare" | "fly";
+export type SwitchingSummary = {
+    /** False while the programme is paused. */
+    enabled: boolean;
+    /** The most a first top-up is matched to. */
+    maxMicros: string;
+    providers: SwitchProvider[];
+    /** Whether this organization can record a switch now: none recorded, and
+     * no top-up paid yet. */
+    eligible: boolean;
+    switch: {
+        provider: SwitchProvider;
+        /** superseded: a referral matched the first top-up instead, which is
+         * never less. The two are never both paid. */
+        status: "pending" | "paid" | "superseded" | "refused" | "reversed";
+        refusedReason: "program_off" | "suspended" | "same_card" | "fraud" | null;
+        recordedAt: string;
+        /** The switching credit this organization got and kept. */
+        creditMicros: string;
+    } | null;
+};
+export type UsageComparison = {
+    provider: CompareProvider;
+    rival: {
+        name: string;
+        /** ISO date the rival's published rates were read. */
+        checked: string;
+        rates: string[];
+        planFee: string;
+        sources: {
+            label: string;
+            url: string;
+        }[];
+    };
+    /** usage: your settled sandboxes. example: none in the window yet, so a
+     * stated example workload is priced instead (see `note`). */
+    basis: "usage" | "example";
+    window: {
+        days: number;
+        from: string;
+        to: string;
+    };
+    usage: {
+        sandboxes: number;
+        runSeconds: number;
+        activeCpuSeconds: number;
+        unpricedSandboxes: number;
+    };
+    runtimeMicros: string;
+    rivalMicros: string;
+    /** Rival less Runtime: negative when the rival would cost less. */
+    savingMicros: string;
+    savingPercent: number | null;
+    /** Scaled to 30 days from the days the usage covers; null for the example. */
+    perMonth: {
+        fromDays: number;
+        runtimeMicros: string;
+        rivalMicros: string;
+        savingMicros: string;
+    } | null;
+    /** What was compared, at which rates, and what was left out. */
+    note: string;
+    switching: SwitchingSummary;
+};
+/** `runtime.switching`: compare your usage with a rival's published rates,
+ * and record the rival you are leaving so your first top-up is matched, up to
+ * $100, once the payment settles. */
+export declare function switching(t: Transport): {
+    /** Your settled sandbox usage over the last `days` (default 30, at most
+     * 90), priced on Runtime and at the rival, with the saving. */
+    compare: (input: {
+        provider: CompareProvider;
+        days?: number;
+    }, options?: RequestOptions) => Promise<UsageComparison>;
+    /** Whether a switch can still be recorded, and what it paid. */
+    get: (options?: RequestOptions) => Promise<SwitchingSummary>;
+    /** Once per organization, before its first top-up. Recording the same
+     * provider again answers the same summary; another fails with 409. */
+    record: (input: {
+        provider: SwitchProvider;
+    }, options?: RequestOptions) => Promise<SwitchingSummary>;
+};

package/dist/products/switching.js

@@ -0,0 +1,25 @@
+/** `runtime.switching`: compare your usage with a rival's published rates,
+ * and record the rival you are leaving so your first top-up is matched, up to
+ * $100, once the payment settles. */
+export function switching(t) {
+    return {
+        /** Your settled sandbox usage over the last `days` (default 30, at most
+         * 90), priced on Runtime and at the rival, with the saving. */
+        compare: (input, options) => t.json({
+            method: "GET",
+            path: "/v1/usage/compare",
+            query: { provider: input.provider, days: input.days },
+            ...options,
+        }),
+        /** Whether a switch can still be recorded, and what it paid. */
+        get: (options) => t.json({ method: "GET", path: "/v1/switching", ...options }),
+        /** Once per organization, before its first top-up. Recording the same
+         * provider again answers the same summary; another fails with 409. */
+        record: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/switching",
+            body: { provider: input.provider },
+            ...options,
+        }),
+    };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,30 @@
+type Env = Record<string, string | undefined>;
+/** How a call to an address leaves this machine. */
+export type Route = {
+    /** The proxy's address, credentials included, to connect through. */
+    proxy?: string;
+    /** The proxy as it may be shown: no user name or password. */
+    shown?: string;
+    /** The variable the proxy or the exemption came from. */
+    variable?: string;
+    /** Set when NO_PROXY exempts the host: the entry that matched. */
+    exempt?: string;
+    /** HTTP_PROXY was set but HTTPS_PROXY was not, for an HTTPS address. */
+    httpOnly?: string;
+};
+/** Whether a NO_PROXY list names this host (and port). Returns the entry. */
+export declare function exemption(list: string, hostname: string, port: string): string | undefined;
+/** The route the SDK takes to `target`, read from the environment now. */
+export declare function routeFor(target: string, env?: Env): Route;
+/** Words for a failed connection: the route it took, and what to check.
+ * `cause` is the error fetch threw, or the status a proxy answered with (Bun's
+ * fetch hands a refused tunnel back as a response). */
+export declare function describeRoute(target: string, cause: unknown, env?: Env): {
+    via: string;
+    hint?: string;
+};
+/** fetch, through the proxy the environment names for the address. */
+export declare const envFetch: typeof fetch;
+/** A WebSocket, through the proxy the environment names for the address. */
+export declare function openWebSocket(url: string, headers: Record<string, string>): Promise<WebSocket>;
+export {};