@prized/sdk 0.0.0-stage → 0.1.1

package/dist/cjs/http.js

@@ -0,0 +1,618 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Polls = exports.LAST_LOOK_MAX_MS = exports.LAST_LOOK_MS = exports.MAX_RETRY_AFTER_MS = exports.MAX_BACKOFF_MS = exports.BACKOFF_FIRST_MS = exports.DEFAULT_POLL_OUTAGE_MS = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = void 0;
+exports.abortableSleep = abortableSleep;
+exports.validOutage = validOutage;
+exports.resolveConfig = resolveConfig;
+exports.toolboxBaseFor = toolboxBaseFor;
+exports.expectedEdge = expectedEdge;
+exports.warmEdge = warmEdge;
+exports.neverSent = neverSent;
+exports.retryable = retryable;
+exports.callDeadline = callDeadline;
+exports.cutByDeadline = cutByDeadline;
+exports.backoffMs = backoffMs;
+exports.outcomeOf = outcomeOf;
+exports.request = request;
+// Configuration and the one HTTP path every call takes: auth header,
+// per-request timeout, retries with backoff, and the error envelope.
+const errors_js_1 = require("./errors.js");
+const outcome_js_1 = require("./outcome.js");
+const version_js_1 = require("./version.js");
+exports.DEFAULT_BASE_URL = 'https://api.prized.dev';
+exports.DEFAULT_EDGE_URL = 'https://term.prized.dev';
+function envApiKey() {
+    try {
+        const env = globalThis.process?.env;
+        return env?.PRIZED_API_KEY;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+/**
+ * https anywhere, plain http only to this machine: the API key rides in
+ * every request's Authorization header. The same rule for the options and
+ * for an edge the API names.
+ */
+function secureEndpoint(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+}
+/** An https (or loopback http) origin, trailing slashes and a trailing /api/v1 dropped. */
+function normalizeOrigin(name, raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} is not a URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must be an http(s) URL`);
+    }
+    if (!secureEndpoint(url)) {
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must use https (plain http only for localhost, 127.0.0.1 or [::1])`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must not carry credentials, a query or a fragment`);
+    }
+    const path = url.pathname.replace(/\/+$/, '').replace(/\/api\/v1$/, '');
+    return `${url.origin}${path}`;
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new errors_js_1.PrizedError('aborted'));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new errors_js_1.PrizedError('aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
+ * while its polls fail before it gives up (pollOutageMs), and a streamed or
+ * long exec stops its command: long enough to ride out a dropped connection
+ * or an edge that restarts. The Python SDK's DEFAULT_POLL_OUTAGE.
+ */
+exports.DEFAULT_POLL_OUTAGE_MS = 120_000;
+/** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
+function validOutage(value) {
+    if (value !== undefined && !(Number.isFinite(value) && value >= 0)) {
+        throw new errors_js_1.PrizedError('invalid_argument', 'pollOutageMs must be a number of ms ≥ 0');
+    }
+    return value;
+}
+function resolveConfig(options = {}) {
+    const apiKey = (options.apiKey ?? envApiKey() ?? '').trim();
+    if (apiKey === '')
+        throw new errors_js_1.PrizedError('missing_api_key');
+    // A key is printable ASCII. Anything else (the docs' `dcp_…` placeholder,
+    // a smart quote) makes fetch throw on the header, which would read as
+    // "could not reach the API"; the key itself is never quoted back.
+    if (![...apiKey].every((c) => c.charCodeAt(0) >= 33 && c.charCodeAt(0) <= 126))
+        throw new errors_js_1.PrizedError('invalid_api_key');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new errors_js_1.PrizedError('invalid_argument', 'No global fetch: use Node 18 or newer, or pass options.fetch');
+    }
+    const maxRetries = options.maxRetries ?? 3;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+        throw new errors_js_1.PrizedError('invalid_argument', 'maxRetries must be a whole number ≥ 0');
+    }
+    const pollOutageMs = validOutage(options.pollOutageMs) ?? exports.DEFAULT_POLL_OUTAGE_MS;
+    return {
+        apiKey,
+        baseUrl: normalizeOrigin('baseUrl', options.baseUrl ?? exports.DEFAULT_BASE_URL),
+        edgeUrl: options.edgeUrl === undefined ? null : normalizeOrigin('edgeUrl', options.edgeUrl),
+        // Bound to globalThis: some runtimes throw "Illegal invocation" on an
+        // unbound fetch.
+        fetch: options.fetch ?? fetchImpl.bind(globalThis),
+        maxRetries,
+        requestTimeoutMs: options.requestTimeoutMs ?? 60_000,
+        pollIntervalMs: options.pollIntervalMs ?? 500,
+        pollOutageMs,
+        sleep: options.sleep ?? abortableSleep,
+        now: options.now ?? Date.now,
+        random: options.random ?? Math.random,
+    };
+}
+/** Prized's own domain: its API and its edges are hosts under it. */
+const PRIZED_DOMAIN = 'prized.dev';
+function under(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** A URL's hostname (lowercase, as URL gives it), or '' if it does not parse. */
+function hostOf(raw) {
+    try {
+        return new URL(raw).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Where a toolboxBase may point, given the API's host: the API host itself;
+ * prized.dev's own hosts when the API is one of them; loopback when the API
+ * is. Never a domain guessed from the API host's name (a public suffix such
+ * as co.uk would trust everyone under it). The Python SDK's _trusted_edge.
+ */
+function trustedEdge(edgeHost, apiHost) {
+    if (edgeHost === '' || apiHost === '')
+        return false;
+    if (isLoopback(apiHost) || isLoopback(edgeHost))
+        return isLoopback(apiHost) && isLoopback(edgeHost);
+    return edgeHost === apiHost || (under(apiHost, PRIZED_DOMAIN) && under(edgeHost, PRIZED_DOMAIN));
+}
+/**
+ * Where exec and files go for one sandbox. An explicit edgeUrl wins; else the
+ * API's own `toolboxBase` when it has the expected shape (https, or plain
+ * http on loopback for local development, ending /v1/sandbox/<id>) on a host
+ * trusted beside the API's (term.prized.dev beside api.prized.dev; see
+ * trustedEdge); else the default edge, for Prized's own API only. The API key
+ * is never sent anywhere else: discovery is routing, not authority.
+ */
+function toolboxBaseFor(config, sandboxId, toolboxBase) {
+    const path = `/v1/sandbox/${encodeURIComponent(sandboxId)}`;
+    if (config.edgeUrl !== null)
+        return `${config.edgeUrl}${path}`;
+    const apiHost = hostOf(config.baseUrl);
+    if (toolboxBase) {
+        try {
+            const url = new URL(toolboxBase);
+            if (secureEndpoint(url) &&
+                trustedEdge(url.hostname, apiHost) &&
+                !url.username &&
+                !url.password &&
+                !url.search &&
+                !url.hash &&
+                url.pathname.replace(/\/+$/, '') === path) {
+                return `${url.origin}${path}`;
+            }
+        }
+        catch {
+            // fall through to the default
+        }
+    }
+    // Prized's own edge only for Prized's own API: a key for another
+    // deployment is never sent to it. That deployment names its edge.
+    if (under(apiHost, PRIZED_DOMAIN))
+        return `${exports.DEFAULT_EDGE_URL}${path}`;
+    throw new errors_js_1.PrizedError('edge_unknown', `The API at ${config.baseUrl} named no command endpoint this SDK trusts for ${sandboxId}; pass edgeUrl for that deployment.`, { sandboxId });
+}
+/**
+ * The edge this config's sandboxes answer on, before the API has named one:
+ * an explicit edgeUrl, else the default edge for the default API. null for
+ * any other API, whose edge is known only from its answer.
+ */
+function expectedEdge(config) {
+    if (config.edgeUrl !== null)
+        return config.edgeUrl;
+    return config.baseUrl === exports.DEFAULT_BASE_URL ? exports.DEFAULT_EDGE_URL : null;
+}
+/** The bound on one warm-up request. */
+const WARM_EDGE_MS = 10_000;
+/**
+ * Open a connection to the edge before the first command needs it: one
+ * `GET /healthz` without the API key (the route needs none), its body read
+ * so the connection goes back to the pool. Sent beside a held create, it
+ * takes DNS, TCP and TLS off the first command after the sandbox runs. Best
+ * effort: never throws, and an edge it cannot reach costs only itself.
+ */
+async function warmEdge(config) {
+    const edge = expectedEdge(config);
+    if (edge === null)
+        return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WARM_EDGE_MS);
+    // Never what keeps a process alive.
+    timer.unref?.();
+    try {
+        const response = await config.fetch(`${edge}/healthz`, {
+            method: 'GET',
+            headers: { 'user-agent': `prized-sdk-typescript/${version_js_1.VERSION}` },
+            signal: controller.signal,
+        });
+        await response.arrayBuffer();
+    }
+    catch {
+        // The first command dials its own connection.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Refusals that will not change by waiting a few seconds. */
+const NEVER_RETRY = new Set([
+    'sandbox_quota_exceeded',
+    'sandboxes_disabled',
+    'sandbox_create_disabled',
+    'sandbox_fork_disabled',
+    'idempotency_conflict',
+    'paid_balance_required',
+    'insufficient_balance',
+]);
+const EXEC_UNDELIVERED = new Set([
+    'rate_limited',
+    'resolve_failed',
+    'sandbox_credentials_unavailable',
+    'control_plane_unavailable',
+    // A paused or starting sandbox the edge woke did not run within its wait.
+    'sandbox_not_ready',
+]);
+/** Failures to open a connection at all (Node's fetch: the cause's code or syscall): nothing was sent. */
+const NOT_CONNECTED_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT']);
+const NOT_CONNECTED_SYSCALLS = new Set(['connect', 'getaddrinfo']);
+/**
+ * Whether a fetch that threw never sent its request: the connection was
+ * refused, the name did not resolve, or connecting timed out. Anything else
+ * (a reset, a timeout once connected, a runtime that names no cause) may
+ * have been delivered.
+ */
+function neverSent(error, depth = 0) {
+    if (depth > 4 || error === null || typeof error !== 'object')
+        return false;
+    const { code, syscall, errors, cause } = error;
+    // Every address Node tried (IPv6 then IPv4, say) failed to connect: an
+    // AggregateError, whose own code is only the first member's.
+    if (Array.isArray(errors) && errors.length > 0)
+        return errors.every((member) => neverSent(member, depth + 1));
+    if ((typeof code === 'string' && NOT_CONNECTED_CODES.has(code)) || (typeof syscall === 'string' && NOT_CONNECTED_SYSCALLS.has(syscall))) {
+        return true;
+    }
+    return neverSent(cause, depth + 1);
+}
+function retryable(error, mode, method) {
+    if (NEVER_RETRY.has(error.code))
+        return false;
+    // Whatever a command may be sent again on, a request that is safe to
+    // repeat may be too, whatever its status.
+    if (EXEC_UNDELIVERED.has(error.code))
+        return true;
+    if (mode === 'exec')
+        return false;
+    // The API failing mid-request (500 internal: a database blip, say) may
+    // have done a write's work, so a write is left to its caller (a create
+    // that may have made a sandbox finds and deletes it). A GET did nothing:
+    // a poll that meets one is sent again rather than failing its create.
+    if (mode === 'safe' && error.status === 500 && method === 'GET')
+        return true;
+    return error.status === 429 || error.status === 502 || error.status === 503 || error.status === 504;
+}
+/** The first retry's backoff; each later one doubles, up to MAX_BACKOFF_MS (jittered down to half). */
+exports.BACKOFF_FIRST_MS = 500;
+exports.MAX_BACKOFF_MS = 8_000;
+/**
+ * The longest Retry-After the SDK waits for, the Python SDK's too: twice the
+ * longest the API asks for on a route the SDK calls (30 s, with 503
+ * sandbox_capacity; the edge asks for 1 s). A longer one is still on the
+ * error (`retryAfter`) if the retries run out.
+ */
+exports.MAX_RETRY_AFTER_MS = 60_000;
+/**
+ * The bound on a call the caller gives no timeout (connect, list, templates,
+ * refresh, keepAlive), retries included: twice requestTimeoutMs, room for one
+ * attempt that runs out and the retries after it.
+ */
+function callDeadline(config) {
+    return config.now() + 2 * config.requestTimeoutMs;
+}
+/** The timeouts request() threw because its deadline came first (not an attempt's own). */
+const cutShort = new WeakSet();
+/**
+ * Whether request() ended because the call's deadline came first: no time
+ * was left, or the retry it was due could not start in time. A wait relabels
+ * only these as its own timeout; an attempt that got no answer while time
+ * was left is the API not answering, and is thrown as it is.
+ */
+function cutByDeadline(error) {
+    return error instanceof errors_js_1.PrizedError && cutShort.has(error);
+}
+/** The least room a wait leaves before its deadline for its last poll to be answered. */
+exports.LAST_LOOK_MS = 100;
+/** The most: a slow read never makes a wait give up its last seconds. */
+exports.LAST_LOOK_MAX_MS = 2_000;
+/**
+ * A wait's polls, paced so the last goes out just before the deadline, with
+ * room for its answer: the slowest read of this wait so far plus
+ * LAST_LOOK_MS (at most LAST_LOOK_MAX_MS). Without it a wait whose last
+ * pause ran to the deadline gave up without looking, and one shorter than a
+ * poll interval never looked at all.
+ */
+class Polls {
+    config;
+    deadline;
+    lastLeft = Infinity;
+    sentAt = 0;
+    slowest = 0;
+    constructor(config, deadline) {
+        this.config = config;
+        this.deadline = deadline;
+    }
+    room() {
+        return Math.min(exports.LAST_LOOK_MAX_MS, this.slowest + exports.LAST_LOOK_MS);
+    }
+    /**
+     * How long to pause before the next poll: `delayMs`, cut so the poll goes
+     * out no later than the room it needs before the deadline (at once when
+     * less is left). null when the wait is over: the time is up, or the last
+     * look was taken (the previous poll went out with no more than that room).
+     */
+    pause(delayMs) {
+        const left = this.deadline - this.config.now();
+        // (A millisecond's slack: a pause too short to move the clock must not
+        // keep the last look from counting.)
+        if (left <= 0 || this.lastLeft <= this.room() + 1)
+            return null;
+        return Math.max(0, Math.min(delayMs, left - this.room()));
+    }
+    /** A poll is going out now. */
+    sent() {
+        this.sentAt = this.config.now();
+        this.lastLeft = this.deadline - this.sentAt;
+    }
+    /** Its answer came back. */
+    answered() {
+        this.slowest = Math.max(this.slowest, this.config.now() - this.sentAt);
+    }
+}
+exports.Polls = Polls;
+/** Delay before retry number `attempt` (0-based): exponential with jitter. */
+function backoffMs(config, attempt) {
+    const base = Math.min(exports.MAX_BACKOFF_MS, exports.BACKOFF_FIRST_MS * 2 ** attempt);
+    return Math.round(base / 2 + (config.random() * base) / 2);
+}
+/**
+ * One fetch, body included, under one timeout and the caller's signal. A
+ * body that stalls or breaks after the headers fails the attempt like a
+ * dropped connection, so it is timed and retried by the same rules.
+ */
+async function attemptOnce(config, spec, url, timeoutMs) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const onAbort = () => controller.abort();
+    spec.signal?.addEventListener('abort', onAbort, { once: true });
+    const headers = {
+        accept: 'application/json',
+        authorization: `Bearer ${config.apiKey}`,
+        'user-agent': `prized-sdk-typescript/${version_js_1.VERSION}`,
+        ...spec.headers,
+    };
+    let body;
+    if (spec.json !== undefined) {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(spec.json);
+    }
+    else if (spec.body !== undefined) {
+        headers['content-type'] = spec.contentType ?? 'application/octet-stream';
+        body = spec.body;
+    }
+    let status = null;
+    try {
+        const response = await config.fetch(url, {
+            method: spec.method,
+            headers,
+            body: body,
+            // Never follow a redirect with the key attached.
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        status = response.status;
+        const ok = response.status >= 200 && response.status < 300;
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel().catch(() => undefined);
+            return { answer: { status: response.status, headers: response.headers, text: '', bytes: null } };
+        }
+        if (ok && spec.read === 'bytes') {
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            return { answer: { status: response.status, headers: response.headers, text: '', bytes } };
+        }
+        return { answer: { status: response.status, headers: response.headers, text: await response.text(), bytes: null } };
+    }
+    catch (error) {
+        return { error, timedOut, status };
+    }
+    finally {
+        clearTimeout(timer);
+        spec.signal?.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * A request whose connection failed after it may have been sent: the method,
+ * the path (never the query) and the innermost error code, e.g.
+ * `POST /v1/sandbox/sbx_1/process/execute: the connection failed
+ * (UND_ERR_SOCKET)`. Not "could not reach": it may have. Never the cause's
+ * own text, which can quote a header (the key) or the whole URL; that stays
+ * in `cause`.
+ */
+function lostMessage(method, url, error) {
+    let code = null;
+    let inner = error;
+    for (let depth = 0; depth < 5 && inner !== null && typeof inner === 'object'; depth += 1) {
+        const own = inner.code;
+        if (typeof own === 'string' && /^[A-Z][A-Z0-9_]{1,40}$/.test(own))
+            code = own;
+        inner = inner.cause;
+    }
+    let path = '';
+    try {
+        path = ` ${new URL(url).pathname}`;
+    }
+    catch {
+        // no path to name
+    }
+    return `${method}${path}: the connection failed${code === null ? '' : ` (${code})`}.`;
+}
+/**
+ * What an error answer (not a 2xx: request() judges those) says about
+ * whether the sandbox acted: `never` for the codes that prove the request
+ * never arrived, `maybe` for any other 5xx, null for a refusal (4xx), whose
+ * own words say what happened.
+ */
+function outcomeOf(error) {
+    if (error.status === null)
+        return null;
+    if (EXEC_UNDELIVERED.has(error.code))
+        return 'never';
+    return error.status >= 500 ? 'maybe' : null;
+}
+/**
+ * The error a request throws. With an `effect`, it says whether the sandbox
+ * acted on the request: by this attempt, or by an earlier one that was sent
+ * again (`acted`: only a keyed request, the background start, and a staged
+ * upload are sent again after they may have arrived). `cutStatus`: the 2xx
+ * whose body broke off.
+ */
+function raised(failure, outcome, acted, effect, cutStatus = null) {
+    if (effect === undefined)
+        return failure;
+    let error = failure;
+    if (outcome === 'did' && cutStatus !== null)
+        error = (0, outcome_js_1.restate)(error, error.message, { status: cutStatus, code: 'bad_response' });
+    return (0, outcome_js_1.withOutcome)(error, effect, acted && (outcome === null || outcome === 'never') ? 'maybe' : outcome);
+}
+/** One API or edge call, retried per `spec.retry`. Throws PrizedError. */
+async function request(config, spec) {
+    const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
+    const sandboxId = spec.sandboxId ?? null;
+    const effect = spec.effect ?? (spec.retry === 'exec' ? (0, outcome_js_1.commandEffect)() : undefined);
+    // Whether an attempt that was sent again may have reached the sandbox.
+    let acted = false;
+    // Names the last attempt's failure, if any, so a call cut short by its
+    // deadline still says what it was waiting out (a 503, a rate limit).
+    const pastDeadline = (last) => {
+        const what = last === undefined ? null : last.status === null ? last.code : `${last.status} ${last.code}`;
+        const tail = what === null ? '' : ` The last attempt failed with ${what}.`;
+        let error = new errors_js_1.PrizedError('timeout', `The time allowed for this call ran out.${tail}`, { sandboxId, cause: last });
+        // A command is sent again only when it provably never arrived, so every
+        // attempt of one cut short this way never reached the sandbox. A staged
+        // upload's copies may have, unless each provably never arrived.
+        if (effect !== undefined && spec.retry !== 'safe')
+            error = (0, outcome_js_1.withOutcome)(error, effect, spec.retry === 'staged' && acted ? 'maybe' : 'never');
+        cutShort.add(error);
+        return error;
+    };
+    const failed = (error) => {
+        spec.onAttemptFailed?.(error);
+        return error;
+    };
+    let last;
+    // An abort with an `effect` says whether the sandbox may have acted:
+    // before an attempt, or while waiting to send one again, nothing was sent
+    // that might have, unless an earlier attempt of a keyed request (`acted`)
+    // did.
+    const abortedBetween = (cause) => {
+        const error = new errors_js_1.PrizedError('aborted', null, cause === undefined ? { sandboxId } : { sandboxId, cause });
+        return effect === undefined ? error : (0, outcome_js_1.withAbort)(error, effect, acted ? 'maybe' : 'never');
+    };
+    for (let attempt = 0;; attempt += 1) {
+        if (spec.signal?.aborted)
+            throw abortedBetween(last);
+        const left = spec.deadline === undefined ? Infinity : spec.deadline - config.now();
+        if (left <= 0)
+            throw pastDeadline(last);
+        const attemptMs = Math.max(1, Math.min(timeoutMs, left));
+        const url = typeof spec.url === 'string' ? spec.url : spec.url(left);
+        const outcome = await attemptOnce(config, spec, url, attemptMs);
+        let failure;
+        let waitMs = null;
+        if ('error' in outcome) {
+            if (spec.signal?.aborted) {
+                const error = failed(new errors_js_1.PrizedError('aborted', null, { sandboxId, cause: outcome.error }));
+                // An attempt cut off may have reached the sandbox; one whose 2xx
+                // status came before its body did, and the sandbox acted on it.
+                const answered = outcome.status !== null && outcome.status >= 200 && outcome.status < 300;
+                throw effect === undefined ? error : (0, outcome_js_1.withAbort)(error, effect, answered ? 'did' : 'maybe');
+            }
+            const unsentAttempt = !outcome.timedOut && neverSent(outcome.error);
+            failure = failed(outcome.timedOut
+                ? new errors_js_1.PrizedError('timeout', `No answer within ${attemptMs} ms`, { sandboxId, cause: outcome.error })
+                : unsentAttempt
+                    ? new errors_js_1.PrizedError('network_error', null, { sandboxId, cause: outcome.error })
+                    : new errors_js_1.PrizedError('network_error', lostMessage(spec.method, url, outcome.error), { sandboxId, cause: outcome.error }));
+            // The status came and the body did not: the sandbox acted on it.
+            const cut = outcome.status !== null && outcome.status >= 200 && outcome.status < 300;
+            const said = cut ? 'did' : unsentAttempt ? 'never' : 'maybe';
+            // A command is sent again only if it never left; a staged upload
+            // unless its 2xx came (its bytes are there).
+            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt) || (spec.retry === 'staged' && !cut);
+            if (!resend || attempt >= config.maxRetries)
+                throw raised(failure, said, acted, effect, cut ? outcome.status : null);
+            acted = acted || said !== 'never';
+        }
+        else {
+            const answer = outcome.answer;
+            if (answer.status >= 200 && answer.status < 300) {
+                try {
+                    return parseSuccess(answer, spec, sandboxId);
+                }
+                catch (error) {
+                    throw error instanceof errors_js_1.PrizedError ? raised(failed(error), 'did', acted, effect) : error;
+                }
+            }
+            if (answer.status >= 300 && answer.status < 400) {
+                throw failed(new errors_js_1.PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId }));
+            }
+            const retryAfter = (0, errors_js_1.parseRetryAfter)(answer.headers.get('retry-after'), config.now());
+            failure = failed((0, errors_js_1.errorFromResponse)(answer.status, answer.text, retryAfter, sandboxId, urlPath(url)));
+            const said = outcomeOf(failure);
+            if (!retryable(failure, spec.retry, spec.method) || attempt >= config.maxRetries)
+                throw raised(failure, said, acted, effect);
+            acted = acted || said === 'maybe' || said === 'did';
+            if (retryAfter !== null)
+                waitMs = Math.min(exports.MAX_RETRY_AFTER_MS, Math.ceil(retryAfter * 1000));
+        }
+        last = failure;
+        const delay = Math.max(backoffMs(config, attempt), waitMs ?? 0);
+        // A retry that could not start before the deadline is not attempted.
+        if (spec.deadline !== undefined && config.now() + delay >= spec.deadline)
+            throw pastDeadline(failure);
+        try {
+            await config.sleep(delay, spec.signal);
+        }
+        catch (error) {
+            throw error instanceof errors_js_1.PrizedError && error.code === 'aborted' ? abortedBetween(failure) : error;
+        }
+    }
+}
+/** The path of a request's URL ('' if it does not parse). */
+function urlPath(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return '';
+    }
+}
+function parseSuccess(answer, spec, sandboxId) {
+    const read = spec.read ?? 'json';
+    if (read === 'bytes')
+        return { status: answer.status, json: null, bytes: answer.bytes ?? new Uint8Array(0) };
+    if (read === 'none' || answer.status === 204 || answer.text === '') {
+        return { status: answer.status, json: null, bytes: null };
+    }
+    try {
+        return { status: answer.status, json: JSON.parse(answer.text), bytes: null };
+    }
+    catch (cause) {
+        throw new errors_js_1.PrizedError('bad_response', `HTTP ${answer.status} with a body that is not JSON`, {
+            status: answer.status,
+            sandboxId,
+            cause,
+        });
+    }
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,12 @@
+export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
+export type { CreateOptions, ForkOptions, ListOptions, WaitableOptions } from './sandbox.js';
+export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './commands.js';
+export type { CommandStatus, ExecOptions, WaitOptions } from './commands.js';
+export { Files } from './files.js';
+export type { FileData, WriteOptions } from './files.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
+export type { OutputReadErrorInit, PrizedErrorInit } from './errors.js';
+export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
+export type { ClientOptions } from './http.js';
+export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, TruncatedReason, WriteInfo, } from './types.js';
+export { VERSION } from './version.js';

package/dist/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = exports.PrizedError = exports.OutputReadError = exports.CommandTimeoutError = exports.Files = exports.MAX_BLOCKING_EXEC_MS = exports.DEFAULT_EXEC_TIMEOUT_MS = exports.CommandHandle = exports.PREVIEW_KEY_HEADER = exports.DEFAULT_TEMPLATE = exports.Sandbox = void 0;
+// Prized Sandboxes (beta) from TypeScript: the public surface.
+var sandbox_js_1 = require("./sandbox.js");
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return sandbox_js_1.Sandbox; } });
+Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return sandbox_js_1.DEFAULT_TEMPLATE; } });
+Object.defineProperty(exports, "PREVIEW_KEY_HEADER", { enumerable: true, get: function () { return sandbox_js_1.PREVIEW_KEY_HEADER; } });
+var commands_js_1 = require("./commands.js");
+Object.defineProperty(exports, "CommandHandle", { enumerable: true, get: function () { return commands_js_1.CommandHandle; } });
+Object.defineProperty(exports, "DEFAULT_EXEC_TIMEOUT_MS", { enumerable: true, get: function () { return commands_js_1.DEFAULT_EXEC_TIMEOUT_MS; } });
+Object.defineProperty(exports, "MAX_BLOCKING_EXEC_MS", { enumerable: true, get: function () { return commands_js_1.MAX_BLOCKING_EXEC_MS; } });
+var files_js_1 = require("./files.js");
+Object.defineProperty(exports, "Files", { enumerable: true, get: function () { return files_js_1.Files; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "CommandTimeoutError", { enumerable: true, get: function () { return errors_js_1.CommandTimeoutError; } });
+Object.defineProperty(exports, "OutputReadError", { enumerable: true, get: function () { return errors_js_1.OutputReadError; } });
+Object.defineProperty(exports, "PrizedError", { enumerable: true, get: function () { return errors_js_1.PrizedError; } });
+var http_js_1 = require("./http.js");
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return http_js_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "DEFAULT_EDGE_URL", { enumerable: true, get: function () { return http_js_1.DEFAULT_EDGE_URL; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });