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

package/dist/client.js

@@ -2,7 +2,7 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { inspect } from "node:util";
 import { dirname, join } from "node:path";
-import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, ERRORS_DOCS_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, exitForCode, previewsOff, withPreviewsFix, } from "./core.js";
+import { ApiError, AuthError, EnvFailedError, PromigenceError, InvalidArgumentError, NotFoundError, NotReleasedError, NotVerifiedError, RateLimitError, ServiceRestartError, SpendCapError, TimeoutError, UnreachableError, DEFAULT_API_URL, FILE_PUT_CHUNK_BYTES, MAX_OUTPUT_BYTES_DEFAULT, VERSION, WAIT_TIMEOUT_MS, PreviewsUnavailableError, SANDBOX_ENDED_FIX, SandboxEndedError, errorsDocsFor, exitForCode, previewsOff, sandboxEndedIn, withPreviewsFix, } from "./core.js";
 import { buildBundle } from "./bundle.js";
 import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.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)
@@ -230,30 +276,6 @@ export function readCredentials(env = process.env) {
 function storedName(store, env) {
     return store === undefined || store === "file" ? `the credentials file (${credentialsPath(env)})` : storeLabel(store);
 }
-const COMPAT_REFUSED_HOSTS = /(^|\.)e2b(-staging)?\.(app|dev|pro)$/i;
-export function apiUrlFromCompatUrl(url) {
-    const u = (url ?? "").trim();
-    if (!u)
-        return undefined;
-    let host = "";
-    try {
-        host = new URL(u.includes("://") ? u : `https://${u}`).hostname;
-    }
-    catch {
-        return undefined;
-    }
-    return COMPAT_REFUSED_HOSTS.test(host) ? undefined : u;
-}
-export function apiUrlFromCompatDomain(domain) {
-    const d = (domain ?? "").trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
-    if (!d || COMPAT_REFUSED_HOSTS.test(d))
-        return undefined;
-    return `https://api.${d}/v1`;
-}
-export function compatApiKey(key) {
-    const k = key?.trim();
-    return k && !k.startsWith("e2b_") ? k : undefined;
-}
 export function keyOrigin(env = process.env) {
     if (env["PROMIGENCE_API_KEY"]?.trim())
         return "PROMIGENCE_API_KEY";
@@ -280,12 +302,13 @@ function resolveCredentials(opts, env = process.env) {
     const inputs = optKey === undefined && envKey === undefined
         ? undefined
         : `${optKey ?? "\0"}\n${envKey ?? "\0"}\n${envUrl ?? "\0"}\n${opts.apiUrl ?? "\0"}`;
-    if (inputs !== undefined && inputs === credsLastInputs && credsLast !== undefined)
-        return { apiKey: credsLast.apiKey, apiUrl: credsLast.apiUrl };
+    if (inputs !== undefined && inputs === credsLastInputs && credsLast !== undefined) {
+        return { apiKey: credsLast.apiKey, apiUrl: credsLast.apiUrl, ...(credsLast.origin ? { origin: credsLast.origin } : {}) };
+    }
     const worked = resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl);
     if (inputs !== undefined && worked.refusal === undefined) {
         credsLastInputs = inputs;
-        credsLast = { apiKey: worked.apiKey, apiUrl: worked.apiUrl };
+        credsLast = { apiKey: worked.apiKey, apiUrl: worked.apiUrl, ...(worked.origin ? { origin: worked.origin } : {}) };
     }
     return worked;
 }
@@ -319,8 +342,15 @@ function resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl) {
         if (refusal)
             return { apiKey: undefined, apiUrl, refusal };
     }
-    return { apiKey: key, apiUrl };
+    const origin = !key ? undefined
+        : source === "opts" ? { source: "option" }
+            : source === "env" ? { source: "env" }
+                : source === "file" ? { source: "stored", ...(store === undefined ? {} : { store }) }
+                    : { source: "fallback" };
+    return { apiKey: key, apiUrl, ...(origin ? { origin } : {}) };
 }
+export const NO_KEY_MESSAGE = "no API key: none was given, PROMIGENCE_API_KEY is not set, and none is stored";
+export const NO_KEY_FIX = "Pass { apiKey } or set PROMIGENCE_API_KEY. No key yet: `promigence login` signs you up or in and stores one.";
 function keyRefusal(key, from) {
     if (/^[\x21-\x7E]+$/.test(key))
         return undefined;
@@ -600,6 +630,8 @@ export function snapshotCreateBody(opts) {
     }
     if (o.alias)
         body["alias"] = o.alias;
+    if (o.alias && o.moveAlias)
+        body["move_alias"] = true;
     if (o.grade) {
         if (!o.grade.cmd)
             throw new InvalidArgumentError("snapshots.create grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
@@ -634,6 +666,9 @@ const REFUSED_503_CODES = new Set([
     "builder_unavailable", "builder_busy", "overloaded", "tier_unavailable", "registry_unavailable",
     "secrets_unavailable",
 ]);
+const SDK_FIXES = {
+    cap_exceeded: "Raise `spendCap`, lower `timeoutMs` or `count`, or pass `allowPartial` to launch what fits.",
+};
 function withoutCliHelp(fix) {
     const out = fix.replace(/\s*See `promigence [^`]*--help`\.?\s*$/, "").trim();
     if (out === fix.trim())
@@ -643,7 +678,7 @@ function withoutCliHelp(fix) {
 export function errorFor(code, message, fix, extra = {}) {
     const attach = (e) => {
         const w = e;
-        w.docs = extra.docs ?? `${ERRORS_DOCS_URL}#${code}`;
+        w.docs = extra.docs !== undefined && e.code === code ? extra.docs : errorsDocsFor(e.code);
         if (extra.status !== undefined)
             w.status = extra.status;
         if (extra.requestId !== undefined)
@@ -659,6 +694,8 @@ export function errorFor(code, message, fix, extra = {}) {
     if ((code === "usage" || code === "invalid_argument" || code === "unsupported") && previewsOff(message)) {
         return attach(new PreviewsUnavailableError());
     }
+    if (!extra.cli && Object.prototype.hasOwnProperty.call(SDK_FIXES, code))
+        fix = SDK_FIXES[code];
     switch (code) {
         case "auth": return attach(new AuthError(message, fix));
         case "not_found": return attach(new NotFoundError(message, fix));
@@ -672,8 +709,13 @@ export function errorFor(code, message, fix, extra = {}) {
         case "not_verified": return attach(new NotVerifiedError(message, fix));
         case "timeout": return attach(new TimeoutError(message, fix));
         case "usage":
-        case "invalid_argument":
+        case "invalid_argument": {
+            const ended = code === "usage" ? sandboxEndedIn(message) : undefined;
+            if (ended !== undefined) {
+                return attach(new SandboxEndedError(message, ended.sandboxId, ended.state, extra.cli ? fix : SANDBOX_ENDED_FIX));
+            }
             return attach(new InvalidArgumentError(message, extra.cli ? fix : withoutCliHelp(fix), code));
+        }
         case "not_released": return attach(new NotReleasedError(message));
         case "service_restart": return attach(new ServiceRestartError(message, fix));
         default:
@@ -744,6 +786,21 @@ const WAIT_MS_CAP = 30_000;
 export const LONG_POLL_MS = 5_000;
 const BUILD_POLL_MS = 10_000;
 const PROGRESS_POLL_MS = 200;
+export const RUN_SETTLE_MS = 5_000;
+export function runWorkDone(run, endedSince, now = Date.now()) {
+    if (run.state === "completed" || run.state === "cap_killed" || run.state === "aborted")
+        return true;
+    const sbs = Array.isArray(run.sandboxes) ? run.sandboxes : [];
+    const allDone = sbs.length > 0 && sbs.every((s) => s.state === "ended" || s.command_outcome != null);
+    if (!allDone) {
+        delete endedSince.at;
+        return false;
+    }
+    if (sbs.some((s) => s.state !== "ended"))
+        return true;
+    endedSince.at ??= now;
+    return now - endedSince.at >= RUN_SETTLE_MS;
+}
 const WAITED_HEADER = "promigence-waited-ms";
 const seg = (s) => encodeURIComponent(s).replace(/%40/g, "@");
 function waitQuery(waitMs) {
@@ -781,6 +838,9 @@ export class PromigenceClient {
     apiUrl;
     #apiKey;
     #keyRefusal;
+    #keyOrigin;
+    #onKeyUse;
+    #keyUseSaid = false;
     #bearer;
     fetchImpl;
     ownFetch;
@@ -802,6 +862,8 @@ export class PromigenceClient {
         const resolved = resolveCredentials(opts);
         this.#apiKey = resolved.apiKey;
         this.#keyRefusal = resolved.refusal;
+        this.#keyOrigin = resolved.origin;
+        this.#onKeyUse = opts.onKeyUse;
         this.apiUrl = resolved.apiUrl;
         const env = opts.fetch === undefined ? transportEnv() : undefined;
         const proxy = env !== undefined ? proxyFor(this.apiUrl, env) : undefined;
@@ -867,11 +929,18 @@ export class PromigenceClient {
         catch {
         }
     }
+    get keyOrigin() {
+        return this.#keyOrigin;
+    }
     requireKey() {
         if (this.#keyRefusal)
             throw this.#keyRefusal;
         if (!this.#apiKey)
-            throw new AuthError();
+            throw this.cliErrors ? new AuthError(NO_KEY_MESSAGE) : new AuthError(NO_KEY_MESSAGE, NO_KEY_FIX);
+        if (!this.#keyUseSaid && this.#onKeyUse !== undefined && this.#keyOrigin !== undefined) {
+            this.#keyUseSaid = true;
+            this.#onKeyUse(this.#keyOrigin);
+        }
         return this.#apiKey;
     }
     bearer() {
@@ -944,7 +1013,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 +1211,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 +1221,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 +1235,7 @@ export class PromigenceClient {
                     method,
                     headers,
                     signal,
-                    ...(body === undefined ? {} : { body: body }),
+                    ...(body === undefined ? {} : { body: body.data }),
                     ...(dispatcher === undefined ? {} : { dispatcher }),
                 });
             }
@@ -1185,21 +1255,23 @@ 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);
                 continue;
             }
             const code = payload.error?.code ?? codeForStatus(res.status);
+            const rid = headerOf(res, "request-id") ?? headerOf(res, "x-request-id");
             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 }),
+                ...(rid ? { requestId: rid } : {}),
             });
         }
     }
-    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 +1280,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,10 +1347,12 @@ 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.", {
+            const rid = headerOf(res, "request-id") ?? headerOf(res, "x-request-id");
+            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 }),
+                ...(rid ? { requestId: rid } : {}),
             });
         }
     }
@@ -1346,6 +1428,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 +1509,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),
+                }),
             },
         };
     }
@@ -1620,12 +1728,8 @@ export class PromigenceClient {
                 return { sandboxes: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
             },
             waitDone: async (runId, opts = {}) => {
-                const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => {
-                    const terminal = run.state === "completed" || run.state === "cap_killed" || run.state === "aborted";
-                    const allDone = Array.isArray(run.sandboxes) && run.sandboxes.length > 0 &&
-                        run.sandboxes.every((s) => s.state === "ended" || s.command_outcome != null);
-                    return terminal || allDone;
-                });
+                const endedSince = {};
+                const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => runWorkDone(run, endedSince));
                 return { run: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
             },
         };
@@ -2034,10 +2138,19 @@ export class PromigenceClient {
                     }), sandboxId);
                     return r.ports ?? [];
                 },
-                revoke: (sandboxId, tokenOrPort) => this.request({
-                    method: "DELETE",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${encodeURIComponent(String(tokenOrPort))}`,
-                }),
+                revoke: (sandboxId, tokenOrPort) => {
+                    const which = String(tokenOrPort).trim();
+                    return /^[0-9]+$/.test(which)
+                        ? this.request({
+                            method: "DELETE",
+                            path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${which}`,
+                        })
+                        : this.request({
+                            method: "POST",
+                            path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/revoke`,
+                            body: { token: which },
+                        });
+                },
             },
             ssh: {
                 open: (sandboxId, opts) => {
@@ -2152,6 +2265,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 +2336,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 +2428,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 +2444,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 +2453,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 +2467,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 = {}) => {
@@ -2523,10 +2647,10 @@ export class PromigenceClient {
                     throw new InvalidArgumentError("snapshots.delete needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
                 return this.request({ method: "DELETE", path: `/snapshots/${seg(idOrAlias)}` });
             },
-            alias: (idOrAlias, alias) => this.request({
+            alias: (idOrAlias, alias, opts = {}) => this.request({
                 method: "PUT",
                 path: `/snapshots/${seg(idOrAlias)}/alias`,
-                body: { alias },
+                body: { alias, ...(alias !== null && opts.moveAlias ? { move_alias: true } : {}) },
             }),
             waitBuild: async (buildId, opts = {}) => {
                 const r = await this.waitLoop(opts, BUILD_POLL_MS, { build_id: buildId, state: "running" }, (read) => this.snapshots.status(buildId, read), (b) => b.state !== "running" && b.state !== "queued");

package/dist/command-errors.d.ts

@@ -18,6 +18,7 @@ export declare class CommandTimeoutError extends CommandExitError {
     readonly code: string;
     readonly fix: string;
     readonly guide: string;
+    readonly docs: string;
     constructor(result: CommandResult, timeoutMs: number | undefined);
 }
 /**

package/dist/command-errors.js

@@ -1,4 +1,4 @@
-import { CommandExitError } from "./core.js";
+import { CommandExitError, errorsDocsFor } from "./core.js";
 import { hintArg } from "./hint.js";
 export function secondsText(ms) {
     const s = ms / 1000;
@@ -10,9 +10,11 @@ export class CommandTimeoutError extends CommandExitError {
     code;
     fix;
     guide;
+    docs;
     constructor(result, timeoutMs) {
         super(result);
         this.code = "task_timeout";
+        this.docs = errorsDocsFor(this.code);
         this.timeoutMs = timeoutMs;
         this.message = timeoutMs === undefined
             ? `command timed out (killed at its timeout, exit ${result.exitCode})`

package/dist/context.d.ts

@@ -15,9 +15,11 @@
  * - Empty directories and permission bits travel as they are on disk; a set-user-ID or
  *   set-group-ID bit is cleared, with a note.
  * - Files that look like credentials (`.env`, private keys, cloud credentials, ...) are refused,
- *   by name, unless `allowSecrets` says otherwise. The check goes by file name: it is
- *   best-effort and cannot see what a file holds, so look over the list (`listContext`) before
- *   you send a directory.
+ *   by name, unless `allowSecretFiles` names them (each one) or `allowSecrets` says otherwise. The
+ *   check goes by file name and reads only two kinds of file, to clear the plain false
+ *   positives: a `.pem` holding certificates or public keys and no private key, and an `.npmrc`
+ *   with no token or password in it. It is best-effort, so look over the list (`listContext`)
+ *   before you send a directory.
  * - Symbolic links travel as links, never as the file they point at.
  */
 /** The prefix a packed directory travels under in `dockerfile.context`. */
@@ -65,9 +67,17 @@ export declare function dockerignoreMatcher(text: string): {
 /**
  * Does this path look like a credential (`.env`, a private key, cloud or registry credentials, a
  * token file, ...)? By name only: best-effort, it cannot see what a file holds. Templates such as
- * `.env.example` are not.
+ * `.env.example` are not. [`secretLikeFile`] also reads the few files whose contents can clear them.
  */
 export declare function secretLike(path: string): boolean;
+/** The most of a file [`secretLikeFile`] reads; a larger one is judged by its name alone. */
+export declare const CONTENT_CHECK_MAX_BYTES: number;
+/**
+ * [`secretLike`] for a file on disk at `abs` (`rel` is its path in the upload): a name that looks
+ * like a credential, unless what the file holds clears it ([`clearedByContent`]). A link, a file
+ * over [`CONTENT_CHECK_MAX_BYTES`] and a file that cannot be read keep the name's verdict.
+ */
+export declare function secretLikeFile(rel: string, abs: string): boolean;
 /** What a build context is packed from and sent with. */
 export interface ContextOptions {
     /**
@@ -84,6 +94,11 @@ export interface ContextOptions {
      * nothing is sent.
      */
     allowSecrets?: boolean;
+    /**
+     * Send these files that look like credentials, and only these: paths inside the context,
+     * `/`-separated, as `listContext` names them. Every other one is still refused.
+     */
+    allowSecretFiles?: readonly string[];
     /** Called with each note: what was left out by default, or changed on the way. */
     onNote?: (note: string) => void;
 }