@promigence/sdk 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/cjs/pty.d.ts

@@ -1,11 +1,14 @@
 /**
  * Interactive terminals: `GET /v1/sandboxes/:id/pty` over a WebSocket (RFC 6455).
  *
- * The protocol:
+ * The protocol (`promigence.pty.v2`):
  *
- *   client → server  binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
+ *   client → server  first, one text frame `{"start":{"cmd"?,"secrets"?}}`: what to run and the secret
+ *                    names it gets, inside the connection, never in a header or the URL; then
+ *                    binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
  *   server → client  binary = terminal output; text = `{"event":"open",…}` first and
- *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame
+ *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame. A terminal that
+ *                    cannot open says so in its first frame: `{"event":"error","status",…}`, then Close.
  *
  * Zero dependencies, so this is a small client over `node:http` rather than the global
  * `WebSocket`: that one cannot send an `Authorization` header, and a key in the query string is
@@ -32,26 +35,20 @@ export interface PtyExit {
         message: string;
     };
 }
-/** The header the terminal's command travels in, base64. Never a query parameter. */
-export declare const PTY_COMMAND_HEADER = "promigence-pty-command";
-/** The header the terminal's secret **names** travel in, base64 JSON. */
-export declare const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+/** The WebSocket subprotocol a terminal speaks: its first message is `{"start": {"cmd"?, "secrets"?}}`. */
+export declare const PTY_PROTOCOL = "promigence.pty.v2";
 export interface PtyConnectOpts {
     /** `http(s)://host[:port]/v1/sandboxes/<id>/pty?cols=&rows=` — dimensions only. */
     url: string;
     apiKey: string;
     userAgent: string;
     /**
-     * The command to run, sent as a header rather than in the URL.
-     *
-     * It used to be `?cmd=`, with `envs` composed into it as `export K=v;` — so a terminal opened
-     * with an API key in its environment wrote that key into the query string of every request,
-     * and therefore into every access log along the path. Names and values both stay out of the
-     * URL now.
+     * The command to run. Sent in the terminal's first message, inside the connection: never in a
+     * header or the URL, where a log on the way could keep it.
      */
     command?: string;
     /** Stored secret names (or `{name, as}` bindings), resolved server-side into the terminal's
-     *  environment. JSON, base64, in a header. */
+     *  environment. Sent in the first message with the command. */
     secrets?: unknown[];
     /** The `promigence-caller` label, when one is set (`setCaller`). */
     caller?: string;

package/dist/cjs/pty.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PTY_RESTART_CLOSED_EXIT = exports.PTY_RESTART_EXIT = exports.PTY_RECONNECT_MAX_WAIT_MS = exports.PTY_RECONNECT_FIRST_WAIT_MS = exports.PTY_RECONNECT_FOR_MS = exports.PTY_RECONNECT_CODE = exports.PtySession = exports.FrameReader = exports.PTY_SECRETS_HEADER = exports.PTY_COMMAND_HEADER = exports.PTY_RESUME_HEADER = exports.PTY_INPUT_KEEP = exports.PTY_INPUT_CHUNK = void 0;
+exports.PTY_RESTART_CLOSED_EXIT = exports.PTY_RESTART_EXIT = exports.PTY_RECONNECT_MAX_WAIT_MS = exports.PTY_RECONNECT_FIRST_WAIT_MS = exports.PTY_RECONNECT_FOR_MS = exports.PTY_RECONNECT_CODE = exports.PtySession = exports.FrameReader = exports.PTY_PROTOCOL = exports.PTY_RESUME_HEADER = exports.PTY_INPUT_KEEP = exports.PTY_INPUT_CHUNK = void 0;
+exports.ptyStartMessage = ptyStartMessage;
 exports.wsAccept = wsAccept;
 exports.encodeFrame = encodeFrame;
 exports.connectPty = connectPty;
@@ -11,8 +12,10 @@ exports.PTY_INPUT_CHUNK = 64 * 1024;
 exports.PTY_INPUT_KEEP = 256 * 1024;
 exports.PTY_RESUME_HEADER = "promigence-resume";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-exports.PTY_COMMAND_HEADER = "promigence-pty-command";
-exports.PTY_SECRETS_HEADER = "promigence-pty-secrets";
+exports.PTY_PROTOCOL = "promigence.pty.v2";
+function ptyStartMessage(command, secrets) {
+    return JSON.stringify({ start: { ...(command ? { cmd: command } : {}), ...(secrets?.length ? { secrets } : {}) } });
+}
 function wsAccept(key) {
     return (0, node_crypto_1.createHash)("sha1").update(key + WS_GUID).digest("base64");
 }
@@ -258,15 +261,7 @@ function openLeg(opts, url, resume) {
             authorization: `Bearer ${opts.apiKey}`,
             "user-agent": opts.userAgent,
             ...(opts.caller ? { [caller_js_1.CALLER_HEADER]: opts.caller } : {}),
-            ...(resume ? { [exports.PTY_RESUME_HEADER]: resume } : {}),
-            ...(opts.command && !resume
-                ? { [exports.PTY_COMMAND_HEADER]: Buffer.from(opts.command, "utf8").toString("base64") }
-                : {}),
-            ...(opts.secrets?.length && !resume
-                ? {
-                    [exports.PTY_SECRETS_HEADER]: Buffer.from(JSON.stringify(opts.secrets), "utf8").toString("base64"),
-                }
-                : {}),
+            ...(resume ? { [exports.PTY_RESUME_HEADER]: resume } : { "sec-websocket-protocol": exports.PTY_PROTOCOL }),
         },
     });
     let resolveEnded;
@@ -299,6 +294,8 @@ function openLeg(opts, url, resume) {
                 return;
             }
             socket.setNoDelay(true);
+            if (!resume)
+                socket.write(encodeFrame(0x1, Buffer.from(ptyStartMessage(opts.command, opts.secrets), "utf8")));
             const reader = new FrameReader();
             let exit;
             let closeCode;
@@ -336,6 +333,12 @@ function openLeg(opts, url, resume) {
                                 ...(typeof v["wall_ms"] === "number" ? { wallMs: v["wall_ms"] } : {}),
                             };
                         }
+                        else if (v["event"] === "error" && !wasOpen && typeof v["status"] === "number") {
+                            const e = (v["error"] && typeof v["error"] === "object" ? v["error"] : { code: v["code"], message: v["message"] });
+                            fail(v["status"], JSON.stringify({ error: e }), typeof v["retry_after"] === "string" ? v["retry_after"] : undefined);
+                            socket.destroy();
+                            return;
+                        }
                         else if (v["event"] === "error" || v["event"] === "closed") {
                             exit = {
                                 exitCode: null, signal: null,

package/dist/client.d.ts

@@ -727,6 +727,10 @@ export interface OrgRecord {
     projects: number;
     members: number;
     created_at: string;
+    /** Days command output is kept after a sandbox ends; `null` = the default, 7. */
+    output_retention_days?: number | null;
+    /** Keep a failed sandbox to reopen where it broke, when a run does not say; absent or `null` = the default. */
+    failure_captures?: boolean | null;
 }
 export interface ProjectRecord {
     project_id: string;
@@ -736,8 +740,14 @@ export interface ProjectRecord {
     keys: number;
     /** The most the project may bill in a calendar month (UTC); `null` = no cap. */
     monthly_cap_usd?: number | null;
+    /** Days this project's command output is kept after a sandbox ends; `null` = the organization's. */
+    output_retention_days?: number | null;
+    /** Keep this project's failed sandboxes to reopen, when a run does not say; absent or `null` = the organization's. */
+    failure_captures?: boolean | null;
     created_at: string;
 }
+/** The longest command output may be kept after a sandbox ends, in days. */
+export declare const OUTPUT_RETENTION_MAX_DAYS = 30;
 export interface MemberRecord {
     user_id: string;
     email: string;
@@ -905,8 +915,10 @@ export interface PricingView {
         invite_required: boolean;
     };
     monthly_fee_usd: number;
-    /** Usage the monthly fee includes each month, USD. */
+    /** Credits the plan adds each paid month, USD. */
     included_credits_usd: number;
+    /** For how many paid months the plan adds `included_credits_usd`; `null` when it adds them every paid month. */
+    included_credits_promo_months?: number | null;
     monthly_minimum_usd: number;
 }
 export interface BillingUsage {
@@ -957,6 +969,20 @@ export interface BillingUsage {
         period_end?: string | null;
     } | null;
     upcoming_invoice_error?: string | null;
+    /** What the organization's credits can pay for: balance, held, available, the next to expire. */
+    credits?: M.BillingCredits;
+    /** Auto-reload: when available credits fall below `threshold_usd`, `amount_usd` is added from `card`. */
+    auto_reload?: M.AutoReload;
+    /** The plan in force, and a renewal payment in trouble. */
+    plan_status?: M.PlanStatus;
+    /** `credits` (paid from credits bought in advance) or `postpaid` (billed after use, until `switch.at`). */
+    model?: string;
+    /** For a `postpaid` organization: when it moves to credits, and the credits ready then. */
+    switch?: M.BillingSwitch | null;
+    /** What this organization can buy now. */
+    trust?: M.TrustLimits;
+    /** A hold that refuses new work, and the page that lifts it; `null` when there is none. */
+    hold?: M.BillingHold | null;
     [extra: string]: unknown;
 }
 /** One row of `GET /billing/history`: a credit the organization received, or a payment. */
@@ -1150,7 +1176,7 @@ export interface SnapshotVerifyResponse {
         state: string;
     }>;
 }
-/** `GET /sandboxes/:id/files/stat`. */
+/** `POST /sandboxes/:id/files/stat`. */
 export interface FileStat {
     path: string;
     size: number;
@@ -1178,7 +1204,7 @@ export interface DirEntry {
 }
 /** An opaque label of how a file request was answered, passed through for support. */
 export type ServedBy = string;
-/** `GET /sandboxes/:id/files/list?path=`. */
+/** `POST /sandboxes/:id/files/list`. */
 export interface DirListing {
     sandbox_id: string;
     path: string;
@@ -1187,7 +1213,7 @@ export interface DirListing {
     truncated: boolean;
     served_by?: ServedBy;
 }
-/** `?recursive=&depth=&limit=&hidden=` on `files/list`. */
+/** `recursive`, `depth`, `limit` and `hidden` on `files/list` (sent in the request body). */
 export interface DirListOpts {
     recursive?: boolean;
     /** With `recursive`: how many levels below `path`. Unset = no bound. */
@@ -1207,7 +1233,7 @@ export interface FileInfo {
     is_symlink: boolean;
     served_by?: ServedBy;
 }
-/** One hit of `GET /sandboxes/:id/files/search`. `line`/`text` only for a `contains` search. */
+/** One hit of `POST /sandboxes/:id/files/search`. `line`/`text` only for a `contains` search. */
 export interface FileMatch {
     path: string;
     line?: number | null;
@@ -1906,6 +1932,8 @@ interface RequestOpts {
     onHeaders?: (headers: Headers) => void;
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
+    /** A `POST` that changes nothing (a file read): safe to send twice, so it is retried as a `GET` is. */
+    replayable?: boolean;
 }
 /** One answer's timing ([`PromigenceClient.lastTiming`]). */
 export interface Timing {
@@ -2011,13 +2039,16 @@ export declare class PromigenceClient {
      * artefact must not go through: it would corrupt binary and cost a second copy of a file that
      * can be gigabytes. This reads the body as an `ArrayBuffer` and hands it back untouched.
      * Errors still arrive as JSON, so a non-2xx answer is decoded and mapped the same way.
+     *
+     * `body` is sent as given with its content type (a JSON question, or a `files put` form).
+     * `read`: the request changes nothing, so a refusal is sent again as a `GET` would be.
      */
     private bytes;
     /**
-     * `GET` a byte body **without holding it**: each chunk goes to `onChunk` as it arrives, and
+     * Read a byte body **without holding it**: each chunk goes to `onChunk` as it arrives, and
      * the next is not read until `onChunk` has finished with it, so a 10 GiB artefact costs one
-     * chunk of memory. Errors arrive
-     * as JSON and are mapped exactly as [`bytes`] maps them; a door refusal is sent again.
+     * chunk of memory. A read only (a `POST` carries its question as `body`), so a door refusal
+     * is sent again. Errors arrive as JSON and are mapped exactly as [`bytes`] maps them.
      */
     private stream;
     /**
@@ -2075,7 +2106,7 @@ export declare class PromigenceClient {
         signal?: AbortSignal;
     }): Promise<Outcomes>;
     readonly billing: {
-        /** `GET /billing` — plan, card, period, usage, trial, upcoming invoice. */
+        /** `GET /billing` — plan, credits, auto-reload, card, period, usage, trial, the next plan invoice. */
         usage: () => Promise<BillingUsage>;
         /** `GET /me/ledger?limit=N` — the metered rows the month's total is the sum of (one page). */
         ledger: (limit?: number) => Promise<LedgerEntry[]>;
@@ -2097,6 +2128,29 @@ export declare class PromigenceClient {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<BillingHistoryEntry>>;
+        /** `GET /billing/holds` — what each running or paused sandbox holds of the organization's credits. */
+        holds: () => Promise<M.CreditHolds>;
+        /**
+         * `POST /billing/credits` — a payment page to buy credits, from $5, in whole dollars. The credits are
+         * added when the payment goes through: `settleCredits(session_id)` checks it. An owner's full-access key.
+         */
+        buyCredits: (amountUsd: number) => Promise<M.PaymentPage>;
+        /** `POST /billing/credits/:session_id/settle` — check a credits payment and add its credits if it went through. */
+        settleCredits: (sessionId: string) => Promise<M.CreditsSettled>;
+        /** `GET /billing/auto-reload` — the auto-reload settings, and the authorization turning it on asks for. */
+        autoReload: () => Promise<M.AutoReload>;
+        /**
+         * `PUT /billing/auto-reload` — turn auto-reload on or off, or change it. Turning it on, or changing the level or
+         * the amount, needs `authorizationVersion`: the version of the authorization the owner accepted.
+         */
+        setAutoReload: (opts: {
+            on: boolean;
+            thresholdUsd?: number;
+            amountUsd?: number;
+            authorizationVersion?: string;
+        }) => Promise<M.AutoReload>;
+        /** `POST /billing/disputes/:dispute_id/repay` — a payment page to repay a disputed payment. */
+        repayDispute: (disputeId: string) => Promise<M.PaymentPage>;
         /** `POST /billing/checkout` — the hosted page that puts a card on file. */
         checkout: () => Promise<{
             url: string;
@@ -2109,7 +2163,7 @@ export declare class PromigenceClient {
         }>;
         /** `GET /referrals` — your code and its offer, your referrals by status, what they earned. */
         referrals: () => Promise<ReferralStatus>;
-        /** `POST /referrals/apply` — apply a referral code (an owner's key, before the first paid invoice). */
+        /** `POST /referrals/apply` — apply a referral code (an owner's key, before the first payment of at least the reward). */
         applyReferral: (code: string) => Promise<ReferralApplied>;
     };
     private group_billing;
@@ -2173,6 +2227,15 @@ export declare class PromigenceClient {
             create: (org: string, name: string) => Promise<ProjectRecord>;
             /** `PATCH /orgs/:org/projects/:project {name}` — rename it (the `default` project keeps its name). */
             rename: (org: string, project: string, name: string) => Promise<ProjectRecord>;
+            /**
+             * `PATCH /orgs/:org/projects/:project` — rename it, set how long its command output is kept, or
+             * whether its failed sandboxes are kept to reopen (that one on its own). The settings need an owner signed in.
+             */
+            update: (org: string, project: string, update: {
+                name?: string;
+                outputRetentionDays?: number | null;
+                failureCaptures?: boolean | null;
+            }) => Promise<ProjectRecord>;
         };
     };
     private group_orgs;
@@ -2499,7 +2562,7 @@ export declare class PromigenceClient {
             rows?: number;
             cmd?: string;
             /** Stored secret names, or `{name, as}` bindings, put into the terminal's environment
-             *  by the server. Names travel in a header; values never leave the service. */
+             *  by the server. Names travel inside the terminal's connection; values never leave the service. */
             secrets?: SecretBinding[];
             onData?: (data: Uint8Array) => void;
             onExit?: (exit: PtyExit) => void;
@@ -2544,6 +2607,12 @@ export declare class PromigenceClient {
             optimizeFor?: OptimizeFor;
             spendCap?: number;
         }) => Promise<ResumeResult>;
+        /**
+         * `POST /sandboxes/resume {paused_for: "credits"}` — resume every sandbox paused because credits
+         * ran out. Each resume is checked like new work: the answer lists the sandboxes that resumed and
+         * those that still need credits.
+         */
+        resumePausedForCredits: () => Promise<M.SandboxesResumed>;
         /**
          * `POST /sandboxes/:id/snapshot` — photograph a running sandbox and keep it running.
          *
@@ -2656,8 +2725,9 @@ export declare class PromigenceClient {
         }) => Promise<SandboxPatchResponse>;
         /**
          * `get` streams: the body is handed back as bytes and never parsed, because an eval
-         * artefact, a trace or a run log is exactly what this is for. `put` sends the file as the
-         * body rather than base64 inside JSON.
+         * artefact, a trace or a run log is exactly what this is for. `put` sends the file's bytes
+         * as they are rather than base64 inside JSON. A file's path, a name pattern and a search
+         * text travel in the request body, never in the URL.
          */
         files: {
             /**
@@ -2744,7 +2814,7 @@ export declare class PromigenceClient {
             /**
              * Write a file of **any size**, in [`FILE_PUT_CHUNK_BYTES`] requests.
              *
-             * Chunk 0 goes without `?offset=`, which means "this is the file" (create, truncate);
+             * Chunk 0 goes without an `offset`, which means "this is the file" (create, truncate);
              * every later chunk carries one, which appends, so a file has no size limit here.
              *
              * A failure mid-loop leaves a **prefix** in the sandbox, not a corrupt file. Re-running the

package/dist/client.js

@@ -42,6 +42,26 @@ function bytesToB64(b) {
 function modeParam(mode) {
     return typeof mode === "number" ? mode.toString(8) : mode;
 }
+function jsonBody(value) {
+    return { data: new TextEncoder().encode(JSON.stringify(value)), contentType: "application/json" };
+}
+function fileForm(fields, data) {
+    const boundary = `promigence-${globalThis.crypto.randomUUID().replace(/-/g, "")}`;
+    let head = "";
+    for (const [name, value] of fields) {
+        head += `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`;
+    }
+    head += `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="blob"\r\n`
+        + "Content-Type: application/octet-stream\r\n\r\n";
+    const enc = new TextEncoder();
+    const pre = enc.encode(head);
+    const post = enc.encode(`\r\n--${boundary}--\r\n`);
+    const out = new Uint8Array(pre.length + data.length + post.length);
+    out.set(pre, 0);
+    out.set(data, pre.length);
+    out.set(post, pre.length + data.length);
+    return { data: out, contentType: `multipart/form-data; boundary=${boundary}` };
+}
 export function execOutputBytes(r, stream = "stdout") {
     const b64 = r[`${stream}_b64`];
     if (typeof b64 === "string")
@@ -71,6 +91,32 @@ function pageQuery(limit, max, cursor) {
         q.set("cursor", cursor);
     return q.toString();
 }
+export const OUTPUT_RETENTION_MAX_DAYS = 30;
+function projectUpdateBody(u) {
+    const body = {};
+    if (u.name !== undefined)
+        body["name"] = u.name;
+    if (u.outputRetentionDays !== undefined) {
+        const d = u.outputRetentionDays;
+        if (d !== null && (!Number.isInteger(d) || d < 1 || d > OUTPUT_RETENTION_MAX_DAYS)) {
+            throw new InvalidArgumentError(`outputRetentionDays must be a whole number from 1 to ${OUTPUT_RETENTION_MAX_DAYS}, or null, not ${String(d)}`, "Pass null for the organization's setting.");
+        }
+        body["output_retention_days"] = d;
+    }
+    if (u.failureCaptures !== undefined) {
+        if (u.failureCaptures !== null && typeof u.failureCaptures !== "boolean") {
+            throw new InvalidArgumentError("failureCaptures must be true, false or null", "Pass null for the organization's setting.");
+        }
+        if (Object.keys(body).length) {
+            throw new InvalidArgumentError("failureCaptures is set on its own", "Change it in a call of its own, without name or outputRetentionDays.");
+        }
+        body["failure_captures"] = u.failureCaptures;
+    }
+    if (!Object.keys(body).length) {
+        throw new InvalidArgumentError("projects.update needs something to change", "Pass name, outputRetentionDays or failureCaptures.");
+    }
+    return body;
+}
 function expiryFields(o) {
     const body = {};
     if (o.expiresInDays !== undefined)
@@ -944,7 +990,8 @@ export class PromigenceClient {
         const idempotencyKey = opts.idempotencyKey ?? (keyedCreate ? newIdempotencyKey() : undefined);
         if (idempotencyKey)
             headers["idempotency-key"] = idempotencyKey;
-        const replayable = opts.method === "GET" || opts.method === "DELETE" || (keyedCreate && Boolean(idempotencyKey));
+        const replayable = opts.method === "GET" || opts.method === "DELETE" || opts.replayable === true
+            || (keyedCreate && Boolean(idempotencyKey));
         const timeoutMs = opts.timeoutMs ?? this.requestTimeoutMs;
         let dispatcher;
         let resentDelete = false;
@@ -1141,7 +1188,7 @@ export class PromigenceClient {
             }
         }
     }
-    async bytes(method, path, body, opts = {}) {
+    async bytes(method, path, body, opts = {}, read = method === "GET") {
         const url = `${this.apiUrl}${path}`;
         const headers = {
             accept: "application/octet-stream, application/json",
@@ -1151,7 +1198,7 @@ export class PromigenceClient {
         if (this.caller)
             headers[CALLER_HEADER] = this.caller;
         if (body !== undefined)
-            headers["content-type"] = "application/octet-stream";
+            headers["content-type"] = body.contentType;
         const signals = [AbortSignal.timeout(opts.timeoutMs ?? FILE_TIMEOUT_MS)];
         if (opts.signal)
             signals.push(opts.signal);
@@ -1165,7 +1212,7 @@ export class PromigenceClient {
                     method,
                     headers,
                     signal,
-                    ...(body === undefined ? {} : { body: body }),
+                    ...(body === undefined ? {} : { body: body.data }),
                     ...(dispatcher === undefined ? {} : { dispatcher }),
                 });
             }
@@ -1185,7 +1232,7 @@ export class PromigenceClient {
             }
             catch { }
             const retryAfterMs = parseRetryAfter(res.headers.get("retry-after"));
-            const wait = this.refusalBackoff(res.status, retryAfterMs, payload.error?.code, attempt, method === "GET", opts.signal);
+            const wait = this.refusalBackoff(res.status, retryAfterMs, payload.error?.code, attempt, read, opts.signal);
             if (wait !== undefined) {
                 this.stats.retries++;
                 await sleep(wait);
@@ -1199,7 +1246,7 @@ export class PromigenceClient {
             });
         }
     }
-    async stream(path, onChunk, opts = {}) {
+    async stream(method, path, onChunk, opts = {}, body) {
         const url = `${this.apiUrl}${path}`;
         const headers = {
             accept: "application/octet-stream, application/json",
@@ -1208,17 +1255,25 @@ export class PromigenceClient {
         };
         if (this.caller)
             headers[CALLER_HEADER] = this.caller;
+        if (body !== undefined)
+            headers["content-type"] = body.contentType;
         const signals = [AbortSignal.timeout(opts.timeoutMs ?? FILE_TIMEOUT_MS)];
         if (opts.signal)
             signals.push(opts.signal);
         const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
-        const timedOut = () => new TimeoutError(`GET ${path} timed out after ${opts.timeoutMs ?? FILE_TIMEOUT_MS} ms`, "Retry; for a large artefact raise timeoutMs.");
+        const timedOut = () => new TimeoutError(`${method} ${path} timed out after ${opts.timeoutMs ?? FILE_TIMEOUT_MS} ms`, "Retry; for a large artefact raise timeoutMs.");
         const dispatcher = this.guardDispatcher();
         for (let attempt = 0;; attempt++) {
             let res;
             this.stats.requests++;
             try {
-                res = await this.fetchImpl(url, { method: "GET", headers, signal, ...(dispatcher === undefined ? {} : { dispatcher }) });
+                res = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    signal,
+                    ...(body === undefined ? {} : { body: body.data }),
+                    ...(dispatcher === undefined ? {} : { dispatcher }),
+                });
             }
             catch (err) {
                 const e = err;
@@ -1267,7 +1322,7 @@ export class PromigenceClient {
                 continue;
             }
             const code = payload.error?.code ?? codeForStatus(res.status);
-            throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from GET ${path}`, payload.error?.fix ?? "See the API response for details.", {
+            throw errorFor(code, payload.error?.message ?? `HTTP ${res.status} from ${method} ${path}`, payload.error?.fix ?? "See the API response for details.", {
                 status: res.status,
                 ...bodyExtra(payload),
                 ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
@@ -1346,6 +1401,29 @@ export class PromigenceClient {
                 const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
                 return pageOf(r, "entries", limit);
             },
+            holds: () => this.request({ method: "GET", path: "/billing/holds" }),
+            buyCredits: (amountUsd) => this.request({ method: "POST", path: "/billing/credits", body: { amount_usd: amountUsd } }),
+            settleCredits: (sessionId) => {
+                if (!sessionId?.trim())
+                    throw new InvalidArgumentError("billing.settleCredits needs a session id", "Pass the session_id buyCredits() answered.");
+                return this.request({ method: "POST", path: `/billing/credits/${encodeURIComponent(sessionId)}/settle`, body: {} });
+            },
+            autoReload: () => this.request({ method: "GET", path: "/billing/auto-reload" }),
+            setAutoReload: (opts) => this.request({
+                method: "PUT",
+                path: "/billing/auto-reload",
+                body: {
+                    on: opts.on,
+                    ...(opts.thresholdUsd === undefined ? {} : { threshold_usd: opts.thresholdUsd }),
+                    ...(opts.amountUsd === undefined ? {} : { amount_usd: opts.amountUsd }),
+                    ...(opts.authorizationVersion === undefined ? {} : { authorization_version: opts.authorizationVersion }),
+                },
+            }),
+            repayDispute: (disputeId) => {
+                if (!disputeId?.trim())
+                    throw new InvalidArgumentError("billing.repayDispute needs a dispute id", "Pass the hold's dispute_id from billing.usage().");
+                return this.request({ method: "POST", path: `/billing/disputes/${encodeURIComponent(disputeId)}/repay`, body: {} });
+            },
             checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
             portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
             referrals: () => this.request({ method: "GET", path: "/referrals" }),
@@ -1404,6 +1482,9 @@ export class PromigenceClient {
                 rename: (org, project, name) => this.request({
                     method: "PATCH", path: `/orgs/${orgSeg(org)}/projects/${encodeURIComponent(project)}`, body: { name },
                 }),
+                update: async (org, project, update) => this.request({
+                    method: "PATCH", path: `/orgs/${orgSeg(org)}/projects/${encodeURIComponent(project)}`, body: projectUpdateBody(update),
+                }),
             },
         };
     }
@@ -2152,6 +2233,7 @@ export class PromigenceClient {
                     ...(opts.spendCap === undefined ? {} : { spend_cap: checkSpendCap(opts.spendCap) }),
                 },
             }),
+            resumePausedForCredits: () => this.request({ method: "POST", path: "/sandboxes/resume", body: { paused_for: "credits" } }),
             snapshot: (sandboxId, opts = {}) => this.request({
                 method: "POST",
                 path: `/sandboxes/${encodeURIComponent(sandboxId)}/snapshot`,
@@ -2222,38 +2304,42 @@ export class PromigenceClient {
             },
             files: {
                 list: (sandboxId, path = "/", opts = {}) => {
-                    const q = [`path=${encodeURIComponent(path)}`];
+                    const body = { path };
                     if (opts.recursive)
-                        q.push("recursive=1");
+                        body.recursive = true;
                     if (opts.depth !== undefined)
-                        q.push(`depth=${Math.max(0, Math.floor(opts.depth))}`);
+                        body.depth = Math.max(0, Math.floor(opts.depth));
                     if (opts.limit !== undefined)
-                        q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                        body.limit = Math.max(1, Math.floor(opts.limit));
                     if (opts.hidden === false)
-                        q.push("hidden=0");
+                        body.hidden = false;
                     return this.request({
-                        method: "GET",
-                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/list?${q.join("&")}`,
+                        method: "POST",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/list`,
+                        body,
+                        replayable: true,
                     });
                 },
                 search: (sandboxId, path, opts = {}) => {
                     if (!opts.pattern && !opts.contains) {
                         throw new InvalidArgumentError("files.search needs `pattern`, `contains`, or both", "Pass { pattern: '*.py' } for a name glob, { contains: 'TODO' } for text inside files.");
                     }
-                    const q = [`path=${encodeURIComponent(path)}`];
+                    const body = { path };
                     if (opts.pattern)
-                        q.push(`pattern=${encodeURIComponent(opts.pattern)}`);
+                        body.pattern = opts.pattern;
                     if (opts.contains)
-                        q.push(`contains=${encodeURIComponent(opts.contains)}`);
+                        body.contains = opts.contains;
                     if (opts.ignoreCase)
-                        q.push("ignore_case=1");
+                        body.ignore_case = true;
                     if (opts.limit !== undefined)
-                        q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                        body.limit = Math.max(1, Math.floor(opts.limit));
                     if (opts.hidden === false)
-                        q.push("hidden=0");
+                        body.hidden = false;
                     return this.request({
-                        method: "GET",
-                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/search?${q.join("&")}`,
+                        method: "POST",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/search`,
+                        body,
+                        replayable: true,
                     });
                 },
                 mkdir: (sandboxId, path, opts = {}) => this.request({
@@ -2310,11 +2396,13 @@ export class PromigenceClient {
                     body: { archive, into, ...(opts.strip === undefined ? {} : { strip: Math.max(0, Math.floor(opts.strip)) }) },
                 }),
                 stat: (sandboxId, path) => this.request({
-                    method: "GET",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/stat?path=${encodeURIComponent(path)}`,
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/stat`,
+                    body: { path },
+                    replayable: true,
                 }),
-                get: (sandboxId, path, opts = {}) => this.bytes("GET", `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, undefined, opts),
-                download: (sandboxId, path, onChunk, opts = {}) => this.stream(`/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, onChunk, opts),
+                get: (sandboxId, path, opts = {}) => this.bytes("POST", `/sandboxes/${encodeURIComponent(sandboxId)}/files/read`, jsonBody({ path }), opts, true),
+                download: (sandboxId, path, onChunk, opts = {}) => this.stream("POST", `/sandboxes/${encodeURIComponent(sandboxId)}/files/read`, onChunk, opts, jsonBody({ path })),
                 text: async (sandboxId, path, opts = {}) => new TextDecoder().decode(await this.sandboxes.files.get(sandboxId, path, opts)),
                 put: async (sandboxId, path, data, opts = {}) => {
                     const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
@@ -2324,8 +2412,7 @@ export class PromigenceClient {
                     }, opts);
                 },
                 putFrom: async (sandboxId, path, source, opts = {}) => {
-                    const mode = opts.mode === undefined ? "" : `&mode=${opts.mode.toString(8)}`;
-                    const base = `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}${mode}`;
+                    const url = `/sandboxes/${encodeURIComponent(sandboxId)}/files`;
                     let sent = 0;
                     let chunks = 0;
                     let last;
@@ -2334,7 +2421,12 @@ export class PromigenceClient {
                         if (slice.length === 0 && sent < source.size) {
                             throw new InvalidArgumentError(`the source of ${path} ended at ${sent} of ${source.size} bytes`, "The file shrank while it was being sent; send it again once nothing is writing it.");
                         }
-                        const raw = await this.bytes("PUT", sent === 0 ? base : `${base}&offset=${sent}`, slice, opts);
+                        const fields = [["path", path]];
+                        if (opts.mode !== undefined)
+                            fields.push(["mode", opts.mode.toString(8)]);
+                        if (sent > 0)
+                            fields.push(["offset", String(sent)]);
+                        const raw = await this.bytes("PUT", url, fileForm(fields, slice), opts);
                         last = JSON.parse(new TextDecoder().decode(raw));
                         sent += slice.length;
                         chunks += 1;
@@ -2343,8 +2435,8 @@ export class PromigenceClient {
                 },
                 delete: (sandboxId, path, opts = {}) => this.request({
                     method: "DELETE",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`
-                        + (opts.recursive ? "&recursive=1" : ""),
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files`,
+                    body: { path, ...(opts.recursive ? { recursive: true } : {}) },
                 }),
             },
             output: async (execId, opts = {}) => {