@prized/sdk 0.0.0-stage → 0.1.0

package/dist/esm/http.js

@@ -0,0 +1,553 @@
+// Configuration and the one HTTP path every call takes: auth header,
+// per-request timeout, retries with backoff, and the error envelope.
+import { errorFromResponse, parseRetryAfter, PrizedError } from './errors.js';
+import { commandEffect, restate, withAbort, withOutcome } from './outcome.js';
+import { VERSION } from './version.js';
+export const DEFAULT_BASE_URL = 'https://api.prized.dev';
+export const 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]';
+}
+/** An http(s) origin, trailing slashes and a trailing /api/v1 dropped. */
+function normalizeOrigin(name, raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new PrizedError('invalid_argument', `${name} is not a URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new PrizedError('invalid_argument', `${name} must be an http(s) URL`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new 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}`;
+}
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new PrizedError('aborted'));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new PrizedError('aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * How long a streamed or long exec keeps polling while its polls fail
+ * before it stops the command (pollOutageMs): long enough to ride out a
+ * dropped connection or an edge that restarts. The Python SDK's
+ * DEFAULT_POLL_OUTAGE.
+ */
+export const DEFAULT_POLL_OUTAGE_MS = 120_000;
+/** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
+export function validOutage(value) {
+    if (value !== undefined && !(Number.isFinite(value) && value >= 0)) {
+        throw new PrizedError('invalid_argument', 'pollOutageMs must be a number of ms ≥ 0');
+    }
+    return value;
+}
+export function resolveConfig(options = {}) {
+    const apiKey = (options.apiKey ?? envApiKey() ?? '').trim();
+    if (apiKey === '')
+        throw new 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 PrizedError('invalid_api_key');
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new 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 PrizedError('invalid_argument', 'maxRetries must be a whole number ≥ 0');
+    }
+    const pollOutageMs = validOutage(options.pollOutageMs) ?? DEFAULT_POLL_OUTAGE_MS;
+    return {
+        apiKey,
+        baseUrl: normalizeOrigin('baseUrl', options.baseUrl ?? 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,
+    };
+}
+/**
+ * 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); else the default edge.
+ */
+export function toolboxBaseFor(config, sandboxId, toolboxBase) {
+    const path = `/v1/sandbox/${encodeURIComponent(sandboxId)}`;
+    if (config.edgeUrl !== null)
+        return `${config.edgeUrl}${path}`;
+    if (toolboxBase) {
+        try {
+            const url = new URL(toolboxBase);
+            const secure = url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+            if (secure &&
+                !url.username &&
+                !url.password &&
+                !url.search &&
+                !url.hash &&
+                url.pathname.replace(/\/+$/, '') === path) {
+                return `${url.origin}${path}`;
+            }
+        }
+        catch {
+            // fall through to the default
+        }
+    }
+    return `${DEFAULT_EDGE_URL}${path}`;
+}
+/**
+ * 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.
+ */
+export function expectedEdge(config) {
+    if (config.edgeUrl !== null)
+        return config.edgeUrl;
+    return config.baseUrl === DEFAULT_BASE_URL ? 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.
+ */
+export 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}` },
+            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.
+ */
+export 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);
+}
+export 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 (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). */
+export const BACKOFF_FIRST_MS = 500;
+export const 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.
+ */
+export const 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.
+ */
+export 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.
+ */
+export function cutByDeadline(error) {
+    return error instanceof PrizedError && cutShort.has(error);
+}
+/** The least room a wait leaves before its deadline for its last poll to be answered. */
+export const LAST_LOOK_MS = 100;
+/** The most: a slow read never makes a wait give up its last seconds. */
+export const 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.
+ */
+export class Polls {
+    config;
+    deadline;
+    lastLeft = Infinity;
+    sentAt = 0;
+    slowest = 0;
+    constructor(config, deadline) {
+        this.config = config;
+        this.deadline = deadline;
+    }
+    room() {
+        return Math.min(LAST_LOOK_MAX_MS, this.slowest + 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);
+    }
+}
+/** Delay before retry number `attempt` (0-based): exponential with jitter. */
+export function backoffMs(config, attempt) {
+    const base = Math.min(MAX_BACKOFF_MS, 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}`,
+        ...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.
+ */
+export 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, is sent again
+ * after it 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 = restate(error, error.message, { status: cutStatus, code: 'bad_response' });
+    return withOutcome(error, effect, acted && (outcome === null || outcome === 'never') ? 'maybe' : outcome);
+}
+/** One API or edge call, retried per `spec.retry`. Throws PrizedError. */
+export async function request(config, spec) {
+    const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
+    const sandboxId = spec.sandboxId ?? null;
+    const effect = spec.effect ?? (spec.retry === 'exec' ? commandEffect() : undefined);
+    const unsent = spec.retry === 'exec' ? effect : undefined;
+    // 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 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.
+        if (unsent !== undefined)
+            error = withOutcome(error, unsent, 'never');
+        cutShort.add(error);
+        return error;
+    };
+    const failed = (error) => {
+        spec.onAttemptFailed?.(error);
+        return error;
+    };
+    let last;
+    // Whether an attempt that was sent again may have reached the sandbox.
+    let acted = false;
+    // 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 PrizedError('aborted', null, cause === undefined ? { sandboxId } : { sandboxId, cause });
+        return effect === undefined ? error : 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 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 : withAbort(error, effect, answered ? 'did' : 'maybe');
+            }
+            const unsentAttempt = !outcome.timedOut && neverSent(outcome.error);
+            failure = failed(outcome.timedOut
+                ? new PrizedError('timeout', `No answer within ${attemptMs} ms`, { sandboxId, cause: outcome.error })
+                : unsentAttempt
+                    ? new PrizedError('network_error', null, { sandboxId, cause: outcome.error })
+                    : new 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 or upload is sent again only if it never left.
+            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt);
+            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 PrizedError ? raised(failed(error), 'did', acted, effect) : error;
+                }
+            }
+            if (answer.status >= 300 && answer.status < 400) {
+                throw failed(new PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId }));
+            }
+            const retryAfter = parseRetryAfter(answer.headers.get('retry-after'), config.now());
+            failure = failed(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(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 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 PrizedError('bad_response', `HTTP ${answer.status} with a body that is not JSON`, {
+            status: answer.status,
+            sandboxId,
+            cause,
+        });
+    }
+}

package/dist/esm/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, PrizedError } from './errors.js';
+export type { 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, WriteInfo, } from './types.js';
+export { VERSION } from './version.js';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// Prized Sandboxes (beta) from TypeScript: the public surface.
+export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
+export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './commands.js';
+export { Files } from './files.js';
+export { CommandTimeoutError, PrizedError } from './errors.js';
+export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
+export { VERSION } from './version.js';

package/dist/esm/outcome.d.ts

@@ -0,0 +1,75 @@
+import { PrizedError } from './errors.js';
+/**
+ * What one request does in the sandbox, in the words its errors use: `maybe`
+ * when no clear answer came back (a lost connection, a timeout, a 5xx other
+ * than the ones that prove it never arrived), `did` when a 2xx came back that
+ * could not be read (the sandbox acted on it), and `check`, how to find out
+ * which.
+ */
+export interface Effect {
+    readonly maybe: string;
+    readonly did: string;
+    readonly check: string;
+    /** What the sandbox does once the connection closes, said when the caller aborts after it may have been sent (withAbort). */
+    readonly onClose?: string;
+}
+export declare function commandEffect(): Effect;
+export declare function writeEffect(path: string): Effect;
+export declare function removeEffect(path: string): Effect;
+/** For CommandHandle.kill (`signal` without its SIG prefix). */
+export declare function signalEffect(runId: string, signal: string): Effect;
+/** For a background start (or a streamed or long exec, which runs as one): said before what the SDK did about it (startAbandoned). A 2xx proves only that the start ran. */
+export declare function startEffect(): Effect;
+/** For an SDK helper sent in `exec` mode that names no effect of its own. */
+export declare function helperEffect(): Effect;
+/**
+ * How a request that is not sent again ended: `never` reached the sandbox,
+ * `maybe` acted (no clear answer), `did` act (a 2xx that could not be read),
+ * or null for a refusal whose own words say what happened.
+ */
+export type Outcome = 'never' | 'maybe' | 'did' | null;
+/** Whether withOutcome said the sandbox may have acted on the request. */
+export declare function mayHaveActed(error: unknown): error is PrizedError;
+/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+export declare function restate(error: PrizedError, message: string, init?: {
+    status?: number;
+    code?: string;
+    sandboxId?: string;
+    cause?: unknown;
+}): PrizedError;
+/** `error` (same code, status and body), its message saying what it means for `effect`. */
+export declare function withOutcome(error: PrizedError, effect: Effect, outcome: Outcome): PrizedError;
+/**
+ * `error` (code `aborted`) for a request with an `effect`: `never` when
+ * nothing that may have reached the sandbox was sent (the signal was
+ * aborted before an attempt, or while the SDK waited to send one again
+ * after attempts that never arrived), `did` when a 2xx status came before
+ * the abort cut its body, else `maybe`, with what the sandbox does once a
+ * connection closes. TypeScript only: the Python SDK takes no signal.
+ */
+export declare function withAbort(error: PrizedError, effect: Effect, outcome: 'never' | 'maybe' | 'did'): PrizedError;
+/**
+ * A background start that may have started (`error`, from withOutcome or
+ * withAbort) and that the SDK then stopped by its run id (`stopped`: the
+ * abandon script answered exit 0, so the run can no longer start, was
+ * killed with its group, or had already ended), or could not confirm it did
+ * (no answer, or exit 3: no pid came, so the command may yet run). The
+ * Python SDK's start_abandoned.
+ */
+export declare function startAbandoned(error: PrizedError, runId: string, stopped: boolean): PrizedError;
+/**
+ * A streamed or long exec the caller aborted after its run started
+ * (`error`, code `aborted`, from `sandboxId`), saying whether the SDK then
+ * stopped the run by its id (`stopped`: its KILL was sent, or the run had
+ * already ended), or could not confirm it did.
+ */
+export declare function runAborted(error: PrizedError, runId: string, stopped: boolean, sandboxId: string): PrizedError;
+/**
+ * A streamed or long exec whose poll failed after its run started (`error`:
+ * a lost connection, a 5xx, an answer that could not be read, a refused
+ * key), saying whether the SDK then stopped the run by its id (`stopped`),
+ * or could not confirm it did: with the network down, the command may still
+ * be running. Same code, status and body (and `sandboxId` when it names
+ * none); `error` itself is the cause. The Python SDK's poll_failed.
+ */
+export declare function pollFailed(error: PrizedError, runId: string, stopped: boolean, sandboxId: string): PrizedError;