withruntime 0.2.1 → 0.3.0

package/dist/snapshots.js

@@ -0,0 +1,55 @@
+import { Page } from "./page.js";
+const enc = encodeURIComponent;
+/** `runtime.snapshots`. Take one with `sbx.snapshot()`, start from one with
+ * `runtime.sandboxes.create({ snapshot: id })`, or do both with `sbx.fork()`. */
+export class Snapshots {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    create(input, options = {}) {
+        const { sandboxId, ...body } = input;
+        return this.t.json({
+            method: "POST",
+            path: `/v1/sandboxes/${enc(sandboxId)}:snapshot`,
+            body,
+            ...options,
+        });
+    }
+    get(id, options = {}) {
+        return this.t.json({ method: "GET", path: `/v1/snapshots/${enc(id)}`, ...options });
+    }
+    async list(filter = {}) {
+        const query = {
+            sandboxId: filter.sandboxId,
+            name: filter.name,
+            state: filter.state,
+            limit: filter.limit,
+        };
+        const fetchPage = async (cursor) => {
+            const body = await this.t.json({
+                method: "GET",
+                path: "/v1/snapshots",
+                query: { ...query, cursor },
+            });
+            return new Page(body.data, body.nextCursor, (next) => fetchPage(next));
+        };
+        return fetchPage();
+    }
+    async delete(id, options = {}) {
+        await this.t.json({
+            method: "POST",
+            path: `/v1/snapshots/${enc(id)}:delete`,
+            body: {},
+            ...options,
+        });
+    }
+    extend(id, retentionDays, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: `/v1/snapshots/${enc(id)}:extend`,
+            body: { retentionDays },
+            ...options,
+        });
+    }
+}

package/dist/tar.d.ts

@@ -0,0 +1,3 @@
+export declare function packDirectory(root: string): Promise<Uint8Array>;
+/** Unpacks into `target`, refusing any entry that would land outside it. */
+export declare function unpackArchive(archive: Uint8Array, target: string): Promise<void>;

package/dist/tar.js

@@ -0,0 +1,116 @@
+import { mkdir, readdir, readFile, lstat, writeFile, symlink, chmod } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+/* A small ustar writer and reader for directory uploads and downloads, so the
+   SDK needs no dependency. Regular files, directories and symbolic links;
+   names up to 255 bytes through the ustar prefix field. */
+function header(name, size, mode, type, link = "", mtime = 0) {
+    const block = new Uint8Array(512);
+    const bytes = new TextEncoder().encode(name);
+    let prefix = new Uint8Array();
+    let short = bytes;
+    if (bytes.length > 100) {
+        const split = name.lastIndexOf("/", 155);
+        if (split <= 0 || new TextEncoder().encode(name.slice(split + 1)).length > 100)
+            throw new Error(`Path too long for a tar archive: ${name}`);
+        prefix = new TextEncoder().encode(name.slice(0, split));
+        short = new TextEncoder().encode(name.slice(split + 1));
+    }
+    const put = (offset, value, length) => {
+        const data = typeof value === "string" ? new TextEncoder().encode(value) : value;
+        block.set(data.subarray(0, length), offset);
+    };
+    const octal = (value, length) => value.toString(8).padStart(length - 1, "0") + "\0";
+    put(0, short, 100);
+    put(100, octal(mode & 0o7777, 8), 8);
+    put(108, octal(0, 8), 8);
+    put(116, octal(0, 8), 8);
+    put(124, octal(size, 12), 12);
+    put(136, octal(mtime, 12), 12);
+    put(148, "        ", 8);
+    put(156, type, 1);
+    put(157, link, 100);
+    put(257, "ustar\u000000", 8);
+    put(345, prefix, 155);
+    let sum = 0;
+    for (const byte of block)
+        sum += byte;
+    put(148, sum.toString(8).padStart(6, "0") + "\0 ", 8);
+    return block;
+}
+export async function packDirectory(root) {
+    const parts = [];
+    const base = resolve(root);
+    async function walk(directory) {
+        for (const name of (await readdir(directory)).sort()) {
+            const full = join(directory, name);
+            const path = relative(base, full).split(sep).join("/");
+            const info = await lstat(full);
+            const mtime = Math.floor(info.mtimeMs / 1000);
+            if (info.isDirectory()) {
+                parts.push(header(`${path}/`, 0, info.mode, "5", "", mtime));
+                await walk(full);
+            }
+            else if (info.isSymbolicLink()) {
+                const { readlink } = await import("node:fs/promises");
+                parts.push(header(path, 0, info.mode, "2", await readlink(full), mtime));
+            }
+            else if (info.isFile()) {
+                const data = await readFile(full);
+                parts.push(header(path, data.length, info.mode, "0", "", mtime), data);
+                const pad = (512 - (data.length % 512)) % 512;
+                if (pad)
+                    parts.push(new Uint8Array(pad));
+            }
+        }
+    }
+    await walk(base);
+    parts.push(new Uint8Array(1024));
+    return gzipSync(Buffer.concat(parts));
+}
+/** Unpacks into `target`, refusing any entry that would land outside it. */
+export async function unpackArchive(archive, target) {
+    const data = gunzipSync(archive);
+    const root = resolve(target);
+    await mkdir(root, { recursive: true });
+    const text = (start, length) => {
+        const slice = data.subarray(start, start + length);
+        const end = slice.indexOf(0);
+        return new TextDecoder().decode(end < 0 ? slice : slice.subarray(0, end));
+    };
+    let longName;
+    for (let offset = 0; offset + 512 <= data.length;) {
+        if (data.subarray(offset, offset + 512).every((byte) => byte === 0))
+            break;
+        const size = parseInt(text(offset + 124, 12).trim() || "0", 8);
+        const type = String.fromCharCode(data[offset + 156] ?? 48);
+        const prefix = text(offset + 345, 155);
+        let name = longName ?? (prefix ? `${prefix}/${text(offset, 100)}` : text(offset, 100));
+        longName = undefined;
+        const mode = parseInt(text(offset + 100, 8).trim() || "644", 8);
+        const link = text(offset + 157, 100);
+        const body = data.subarray(offset + 512, offset + 512 + size);
+        offset += 512 + Math.ceil(size / 512) * 512;
+        if (type === "L") {
+            longName = new TextDecoder().decode(body).replace(/\0.*$/s, "");
+            continue;
+        }
+        name = name.replace(/^\.\//, "");
+        if (!name || name === "." || name === "./")
+            continue;
+        const destination = resolve(root, name);
+        if (destination !== root && !destination.startsWith(root + sep))
+            throw new Error(`Refusing an archive entry outside the target: ${name}`);
+        if (type === "5")
+            await mkdir(destination, { recursive: true });
+        else if (type === "2") {
+            await mkdir(resolve(destination, ".."), { recursive: true });
+            await symlink(link, destination).catch(() => undefined);
+        }
+        else if (type === "0" || type === "\0" || type === "7") {
+            await mkdir(resolve(destination, ".."), { recursive: true });
+            await writeFile(destination, body);
+            await chmod(destination, mode & 0o777);
+        }
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,65 @@
+import { RuntimeError } from "./errors.js";
+export declare const VERSION = "0.3.0";
+export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
+export type RequestOptions = {
+    /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps
+     * it across its own retries, so a retried write never happens twice. Pass
+     * your own only to retry a call yourself after the process restarted. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    /** Deadline for this call, retries included. */
+    timeoutMs?: number;
+};
+export type Query = Record<string, string | number | boolean | readonly string[] | undefined>;
+export type Call = RequestOptions & {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    query?: Query;
+    body?: unknown;
+    /** Raw bytes instead of JSON. */
+    bytes?: Uint8Array;
+    /** Seconds the server may hold the answer for a long-running result. */
+    wait?: number;
+    accept?: string;
+    /** Whether retrying after an unknown outcome is safe. Default: true for
+     * reads and for writes (the key makes them safe); false only for calls
+     * the server cannot deduplicate. */
+    retry?: boolean;
+};
+export declare function apiOrigin(value: string): string;
+export declare function encodeQuery(query: Query | undefined): string;
+/** One connection pool, one retry policy, one error shape for every product.
+ * Node's and Bun's fetch keep connections alive, so a client reused across
+ * calls pays TLS once. Over HTTP/1.1 every call in flight holds its own
+ * connection, so a hundred calls at once would open a hundred, past what one
+ * address may hold at the edge (64). Answers read whole are therefore held to
+ * `maxConnections` at once and the rest queue here, reusing those
+ * connections; streams and terminals are long-lived and do not wait behind
+ * them. */
+export declare class Transport {
+    #private;
+    readonly baseUrl: string;
+    constructor(options: {
+        /** A key, or where to find one when the first call is made. */
+        apiKey: string | (() => Promise<string>);
+        baseUrl?: string;
+        fetch?: typeof fetch;
+        timeoutMs?: number;
+        maxRetries?: number;
+        client?: string;
+        /** Calls read whole that may be in flight at once. Default 32. */
+        maxConnections?: number;
+    });
+    /** Sends a call and returns the raw Response once it succeeded. Retries
+     * transport failures, 429, 502, 503 and 504 with backoff and jitter, with
+     * the same key every time. */
+    send(call: Call): Promise<Response>;
+    json<T>(call: Call): Promise<T>;
+    bytes(call: Call): Promise<Uint8Array>;
+    /** Newline-delimited JSON events, as they arrive. */
+    events<T>(call: Call): AsyncGenerator<T>;
+    /** A WebSocket to an API path, authenticated with the same key. */
+    websocket(path: string, query?: Query): Promise<WebSocket>;
+}
+/** No key given, none in RUNTIME_API_KEY, and none saved by `runtime login`. */
+export declare function missingKey(): RuntimeError;

package/dist/transport.js

@@ -0,0 +1,261 @@
+import { ConnectionError, errorFor, RuntimeError } from "./errors.js";
+export const VERSION = "0.3.0";
+export const DEFAULT_BASE_URL = "https://api.withruntime.com";
+export function apiOrigin(value) {
+    const url = new URL(value);
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        url.pathname !== "/")
+        throw new Error("Use an HTTPS API origin (or http://localhost for tests).");
+    return url.origin;
+}
+export function encodeQuery(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                params.append(key, item);
+        else
+            params.set(key, String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : "";
+}
+/** 503s that are a deliberate state, not a passing one: a product switched
+ * off here, or paused on purpose. Retrying cannot change them, so they fail
+ * at once with their own words. host_unavailable and busy are still retried. */
+const DELIBERATE = new Set(["fork_unavailable", "previews_unavailable", "unavailable"]);
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+        signal?.removeEventListener("abort", abort);
+        resolve();
+    }
+    function abort() {
+        clearTimeout(timer);
+        reject(signal?.reason instanceof Error ? signal.reason : new Error("Aborted"));
+    }
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+});
+/** At most `maximum` holders at once; the rest wait their turn, first come
+ * first served. */
+function slots(maximum) {
+    let active = 0;
+    const waiting = [];
+    return {
+        async take() {
+            if (active < maximum) {
+                active++;
+                return;
+            }
+            await new Promise((resolve) => waiting.push(resolve));
+        },
+        give() {
+            const next = waiting.shift();
+            if (next)
+                next();
+            else
+                active--;
+        },
+    };
+}
+/** One connection pool, one retry policy, one error shape for every product.
+ * Node's and Bun's fetch keep connections alive, so a client reused across
+ * calls pays TLS once. Over HTTP/1.1 every call in flight holds its own
+ * connection, so a hundred calls at once would open a hundred, past what one
+ * address may hold at the edge (64). Answers read whole are therefore held to
+ * `maxConnections` at once and the rest queue here, reusing those
+ * connections; streams and terminals are long-lived and do not wait behind
+ * them. */
+export class Transport {
+    baseUrl;
+    #apiKey;
+    #findKey;
+    #fetch;
+    #timeoutMs;
+    #maxRetries;
+    #client;
+    #slots;
+    constructor(options) {
+        if (typeof options.apiKey === "function")
+            this.#findKey = options.apiKey;
+        else if (!options.apiKey || /\s/.test(options.apiKey))
+            throw missingKey();
+        else
+            this.#apiKey = options.apiKey;
+        this.baseUrl = apiOrigin(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.#fetch = options.fetch ?? fetch;
+        this.#timeoutMs = options.timeoutMs ?? 300_000;
+        this.#maxRetries = options.maxRetries ?? 4;
+        this.#client = options.client ?? `sdk-js/${VERSION}`;
+        this.#slots = slots(Math.max(1, options.maxConnections ?? 32));
+    }
+    /** The key, found once on first use when it was not given. */
+    async #key() {
+        if (this.#apiKey === undefined) {
+            const found = await this.#findKey();
+            if (!found || /\s/.test(found))
+                throw missingKey();
+            this.#apiKey = found;
+        }
+        return this.#apiKey;
+    }
+    #headers(call, key, apiKey) {
+        return {
+            authorization: `Bearer ${apiKey}`,
+            accept: call.accept ?? "application/json",
+            "x-runtime-client": this.#client,
+            ...(call.bytes
+                ? { "content-type": "application/octet-stream" }
+                : call.body === undefined
+                    ? {}
+                    : { "content-type": "application/json" }),
+            ...(key ? { "idempotency-key": key } : {}),
+            ...(call.wait ? { prefer: `wait=${Math.min(120, Math.ceil(call.wait))}` } : {}),
+        };
+    }
+    /** Sends a call and returns the raw Response once it succeeded. Retries
+     * transport failures, 429, 502, 503 and 504 with backoff and jitter, with
+     * the same key every time. */
+    async send(call) {
+        const apiKey = await this.#key();
+        const write = call.method !== "GET";
+        const key = write ? (call.idempotencyKey ?? crypto.randomUUID()) : undefined;
+        const deadline = AbortSignal.timeout(call.timeoutMs ?? this.#timeoutMs);
+        const signal = call.signal ? AbortSignal.any([call.signal, deadline]) : deadline;
+        const url = `${this.baseUrl}${call.path}${encodeQuery(call.query)}`;
+        const body = call.bytes ?? (call.body === undefined ? undefined : JSON.stringify(call.body));
+        const retry = call.retry ?? true;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.#fetch(url, {
+                    method: call.method,
+                    headers: this.#headers(call, key, apiKey),
+                    redirect: "error",
+                    signal,
+                    ...(body === undefined ? {} : { body: body }),
+                });
+            }
+            catch (cause) {
+                if (signal.aborted || !retry || attempt >= this.#maxRetries)
+                    throw new ConnectionError({
+                        message: signal.aborted
+                            ? "The call was cancelled or ran past its deadline."
+                            : write
+                                ? `No answer from Runtime at ${this.baseUrl}. The change may have happened; retrying with the same idempotencyKey is safe.`
+                                : `No answer from Runtime at ${this.baseUrl}.`,
+                        hint: signal.aborted
+                            ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
+                            : "Check the network, and RUNTIME_API_URL if you set it.",
+                        code: signal.aborted ? "timeout" : "connection_error",
+                        status: 0,
+                        ...(key ? { idempotencyKey: key } : {}),
+                        cause,
+                    });
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            if (response.ok)
+                return response;
+            const text = await response.text();
+            let parsed = null;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = { error: { message: text.slice(0, 500) || `HTTP ${response.status}` } };
+            }
+            const error = errorFor(response.status, parsed, key);
+            const retryable = [429, 502, 503, 504].includes(response.status) && !DELIBERATE.has(error.code);
+            if (!retry || !retryable || attempt >= this.#maxRetries)
+                throw error;
+            const header = Number(response.headers.get("retry-after"));
+            const wait = error.retryAfterMs ??
+                (Number.isFinite(header) && header > 0 ? header * 1000 : backoff(attempt));
+            await sleep(Math.min(30_000, wait) * (0.9 + Math.random() * 0.2), signal);
+        }
+    }
+    async json(call) {
+        await this.#slots.take();
+        try {
+            const text = await (await this.send(call)).text();
+            return (text ? JSON.parse(text) : null);
+        }
+        finally {
+            this.#slots.give();
+        }
+    }
+    async bytes(call) {
+        await this.#slots.take();
+        try {
+            return new Uint8Array(await (await this.send(call)).arrayBuffer());
+        }
+        finally {
+            this.#slots.give();
+        }
+    }
+    /** Newline-delimited JSON events, as they arrive. */
+    async *events(call) {
+        const response = await this.send({ ...call, accept: "application/x-ndjson" });
+        if (!response.body)
+            return;
+        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += value;
+                let newline = buffer.indexOf("\n");
+                while (newline >= 0) {
+                    const line = buffer.slice(0, newline).trim();
+                    buffer = buffer.slice(newline + 1);
+                    if (line)
+                        yield JSON.parse(line);
+                    newline = buffer.indexOf("\n");
+                }
+            }
+            if (buffer.trim())
+                yield JSON.parse(buffer);
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /** A WebSocket to an API path, authenticated with the same key. */
+    async websocket(path, query) {
+        const apiKey = await this.#key();
+        const url = `${this.baseUrl.replace(/^http/, "ws")}${path}${encodeQuery(query)}`;
+        const Socket = globalThis.WebSocket;
+        if (!Socket)
+            throw new Error("This runtime has no WebSocket; use Node 22+ or Bun.");
+        return new Socket(url, {
+            headers: { authorization: `Bearer ${apiKey}`, "x-runtime-client": this.#client },
+        });
+    }
+}
+/** No key given, none in RUNTIME_API_KEY, and none saved by `runtime login`. */
+export function missingKey() {
+    return new RuntimeError({
+        message: "No Runtime key found: RUNTIME_API_KEY is not set and this machine is not connected.",
+        code: "missing_api_key",
+        status: 0,
+        hint: "Run `npx -y withruntime login` (a browser approval; nothing to copy), set RUNTIME_API_KEY to a key from https://withruntime.com/account/keys, or pass { apiKey }.",
+    });
+}
+function backoff(attempt) {
+    return Math.min(8000, 250 * 2 ** attempt) * (0.5 + Math.random());
+}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/** A sandbox as the API answers it. Times are ISO 8601 strings, money is
+ * integer microdollars (1,000,000 = $1). */
+export type SandboxInfo = {
+    id: string;
+    kind: "sandbox";
+    name: string | null;
+    labels: Record<string, string>;
+    status: "pending" | "active" | "paused" | "stopping" | "stopped";
+    state: "starting" | "running" | "pausing" | "paused" | "resuming" | "stopping" | "stopped";
+    region: string;
+    funding: "trial" | "paid";
+    vcpu: number;
+    memoryMiB: number;
+    diskMiB: number;
+    cpu: "shared" | "reserved";
+    cpuFloorMillis: number;
+    pausable: boolean;
+    timeoutSeconds: number;
+    onLeaseEnd: "pause" | "stop";
+    createdAt: string;
+    readyAt: string | null;
+    expiresAt: string;
+    endedAt: string | null;
+    stopReason: string | null;
+    pausedAt: string | null;
+    pausedExpiresAt: string | null;
+    chargedMicros: number;
+    heldMicros: number;
+    simulated?: boolean;
+    replayed?: boolean;
+    [key: string]: unknown;
+};
+export type CreateSandbox = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** Omit to use the free trial while it lasts, then prepaid credit. */
+    funding?: "trial" | "paid";
+    region?: string;
+    vcpu?: number;
+    memoryMiB?: number;
+    diskMiB?: number;
+    cpu?: "shared" | "reserved";
+    cpuFloorMillis?: number;
+    /** How long it may run before its lease ends. Default 1800. */
+    timeoutSeconds?: number;
+    pausable?: boolean;
+    /** What happens when timeoutSeconds runs out: "pause" (default) or "stop". */
+    onLeaseEnd?: "pause" | "stop";
+    maxCostMicros?: number;
+    /** Network rules from the first start; the same shape as sandbox.network.set.
+     * Omit for the public web on ports 80 and 443. */
+    network?: {
+        internet: boolean;
+        allow?: string[];
+        deny?: string[];
+        connect?: string[];
+    };
+    /** A ready image's id (runtime.images.build); the sandbox starts from it. */
+    image?: string;
+    /** A ready snapshot's id: the sandbox starts as a copy of it, with its shape. Not with image. */
+    snapshot?: string;
+    /** Up to four volumes: read-write ("rw", one sandbox at a time) or a
+     * read-only "snapshot" copy. */
+    volumes?: {
+        volumeId: string;
+        path: string;
+        mode?: "rw" | "snapshot";
+    }[];
+    /** Anything a newer server accepts (image, snapshotId, volumes, network...). */
+    [field: string]: unknown;
+};
+export type CommandResult = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    durationMs?: number | null;
+    processId?: string;
+    replayed?: boolean;
+};
+export type ExecOptions = {
+    cwd?: string;
+    /** Merged over the sandbox's environment. Put secrets here, never in the command. */
+    env?: Record<string, string>;
+    /** Given to standard input, then closed. */
+    stdin?: string | Uint8Array;
+    /** Default 60 000; up to 24 hours. A timeout is a result (timedOut), not an error. */
+    timeoutMs?: number;
+    onStdout?: (text: string) => void;
+    onStderr?: (text: string) => void;
+    /** Throw CommandError when the exit code is not 0. */
+    check?: boolean;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+};
+export type ProcessInfo = {
+    id: string;
+    kind: "process";
+    state: "running" | "exited" | "killed" | "timed_out" | "unknown";
+    exitCode: number | null;
+    command: string;
+    cwd: string;
+    pty: boolean;
+    stdinOpen: boolean;
+    stdinOffset: number;
+    startedAt: string;
+    endedAt: string | null;
+    timeoutMs: number | null;
+    outputBytes: number;
+    firstOffset: number;
+};
+export type OutputEvent = {
+    type: "start";
+    processId: string;
+    replayed?: boolean;
+} | {
+    type: "stdout" | "stderr";
+    data: string;
+    offset: number;
+} | {
+    type: "exit";
+    exitCode: number | null;
+    state: string;
+    timedOut: boolean;
+    durationMs?: number;
+} | {
+    type: "truncated";
+    droppedBytes: number;
+    resumeAt: number;
+} | {
+    type: "continue";
+    processId: string;
+    cursor: number;
+} | {
+    type: "error";
+    error: {
+        code: string;
+        message: string;
+        requestId?: string;
+    };
+};
+export type FileEntry = {
+    name: string;
+    path: string;
+    type: "file" | "directory" | "symlink" | "other";
+    size: number;
+    mode: string;
+    modifiedAt: string;
+};
+/** GET /v1/usage. Money is integer microdollars in strings (1,000,000 = $1),
+ * exact past 2^53: available = credited - spent - expired - held. */
+export type Usage = {
+    orgId: string;
+    unit: "microdollars";
+    credited: string;
+    spent: string;
+    held: string;
+    /** Credit that expired, or grant credit taken back. */
+    expired: string;
+    /** What can still be spent. */
+    available: string;
+    /** The part of spent that refunds and disputes took. */
+    takenBack: string;
+    trial: {
+        totalMs: number;
+        usedMs: number;
+        reservedMs: number;
+        availableMs: number;
+    } | null;
+    resources: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+};
+export type FeedbackKind = "bug" | "missing_feature" | "competitor_gap" | "migration_blocker" | "docs" | "pricing" | "praise" | "other";

package/dist/types.js

@@ -0,0 +1 @@
+export {};