@prized/sdk 0.1.2 → 0.1.3

package/README.md

@@ -13,6 +13,10 @@ console.log(stdout); // 42
 await sandbox.delete();
 ```
 
+Save it as `hello.mjs` and run `node hello.mjs` (Node 18 or later) with
+`PRIZED_API_KEY` set ([Authentication](#authentication)). Top-level `await`
+needs an ES module, so a `.js` file needs `"type": "module"` in package.json.
+
 Sandboxes are in beta. A workspace on free credit alone runs them on the
 free tier: up to 10 at once, each up to 2 vCPU and 4 GB of memory and 60
 minutes of running. A top-up or a paid plan lifts the limits: a sandbox then
@@ -301,9 +305,9 @@ Python's buffering), so a Python program's output arrives as it prints.
 Commands run as the user `prized` (home `/home/prized`, no sudo). The
 templates come with git, curl, Python 3 with pip and venv, Node 22 with npm
 and pnpm; `prized-agent-v1` adds Claude Code and Codex. Install what else
-you need into your home: Python packages into a venv
-(`python3 -m venv ~/.venv && ~/.venv/bin/pip install numpy`; plain
-`pip install`, `--user` too, is refused), and `npm` with a user prefix.
+you need into your home: `pip install numpy` goes to `~/.local` (or use a
+venv: `python3 -m venv ~/.venv && ~/.venv/bin/pip install numpy`), and
+`npm install -g` to `~/.local` too.
 
 ## Background commands
 
@@ -423,11 +427,6 @@ prized sandbox timeout sbx_0123456789abcdef --in 30m  # deleted 30 minutes from
 On a paid plan an extend stops at 7 days from now; on the free tier neither
 moves the end later.
 
-<!-- Held while sandbox ports at a URL are switched off: this section stays
-out of the rendered README until they are on. In the change that turns them
-on, delete these five lines and the closing line after the section, take
-"a sandbox's ports at a URL" out of "Not yet" under Limits, and delete the
-test "the README holds A port at a URL" (test/preview.test.ts).
 ## A port at a URL
 
 `sandbox.previewUrl(port)` is the https URL a port of the sandbox answers at:
@@ -454,15 +453,47 @@ the preview URL, and one that points anywhere else comes back as
 `Prized-Location` instead, which no client follows. To follow a redirect,
 resolve its `Location` against the preview URL and send `previewHeaders()`
 again only when the result has the preview URL's origin, scheme included.
-Call preview URLs from server-side code: a browser hides `Location` from
-`'manual'`.
+Call preview URLs with the key from server-side code: a browser hides
+`Location` from `'manual'`.
 
 Nothing is created: the URL is the sandbox's own, and every port has one
-(but 22 and 81). A request to a paused sandbox resumes it and waits up to 10
-seconds for it, as `exec` does; send `Prized-Auto-Resume: false` to get
-`503` instead. `previewUrl` throws `preview_unavailable` where this is not
-turned on.
--->
+(but 22 and 81). A request with the key to a paused sandbox resumes it and
+waits up to 10 seconds for it, as `exec` does; send
+`Prized-Auto-Resume: false` to get `503` instead. `previewUrl` throws
+`preview_unavailable` where this is not turned on.
+
+A person in a browser, or a client that cannot send the key in a header (a
+WebSocket from a browser page, a program you hand one port to and not your
+key), takes a short-lived token in the URL instead:
+
+```ts
+const { browserUrl, url, expiresAt } = await sandbox.previewToken(3000, { expiresIn: 600 });
+// browserUrl: https://3000-sbx-….prized.link/?prized_token=… opens in a tab or an iframe
+const socket = new WebSocket(url.replace('https:', 'wss:'));
+```
+
+`browserUrl` is the port on `prized.link`, a domain of its own for pages your
+sandboxes serve: open it in a tab or embed it in an iframe. The browser swaps
+the token for a cookie for that one host, so the page's own assets, fetches
+and WebSockets work, and a tab's first visit shows a short notice that the
+page is hosted by a Prized user. `url` is the same token on the preview URL,
+for programs. The token opens that one port until `expiresAt` (an hour by
+default, a day at most), or until your key is revoked; the app never sees
+it. To let anyone reach a port with no credential at all, make it public:
+
+```ts
+const { browserUrl } = await sandbox.setPortPublic(3000, true, { expiresIn: 7 * 86400 });
+await sandbox.setPortPublic(3000, false); // private again
+```
+
+Tokens and public ports need a paid workspace (`share_links_need_payment`
+otherwise), and making a port public takes the workspace owner's key. On the
+preview URL they answer programs, `fetch` and WebSockets but not a page
+opened in a browser tab (`403 ingress_browser_page`, which names the
+`browserUrl`); on `browserUrl` they open in a browser too. Neither wakes a
+paused sandbox: a request gets `503` with `error: 'sandbox_not_running'`
+until something with the key resumes it. Making a port public or private
+again ends the tokens made for it.
 
 ## Fork
 
@@ -538,7 +569,7 @@ try {
 | `sandbox_not_running` | 409 | The sandbox is not running and the call could not wake it: it is resizing (`refresh()` until it leaves `resizing`, then retry), failed, or being deleted. A paused sandbox is resumed by any command or file call. The SDK never turns waking off; a request that carries `Prized-Auto-Resume: false` (added by a custom `fetch`, say) gets this for a paused or starting sandbox too: drop the header to let the call wake it and wait. |
 | `sandbox_not_ready` | 503 | A paused or starting sandbox did not reach running within the edge's 10-second wait. The wait starts when the edge, having checked the key, finds the sandbox not running, and calls with the same key arriving during it share it, so a later call may wait less. Nothing ran; retry. |
 | `parent_not_running` | 409 | Only a running or paused sandbox can be forked. |
-| `parent_not_forkable` | 409 | This sandbox cannot be forked. `reason` `resized_while_paused`: it has no memory to copy; resume it, then fork it. `reason` `parent_too_big`: its machine cannot hold even one copy beside it; fork a smaller sandbox. |
+| `parent_not_forkable` | 409 | This sandbox cannot be forked. `reason` `resized_while_paused` or `memory_discarded`: it has no memory to copy; resume it, then fork it. `reason` `parent_too_big`: its machine cannot hold even one copy beside it; fork a smaller sandbox. |
 | `fork_capacity` | 409 | The parent's machine has room for only `fits` more copies (`err.body?.fits`). If `fits` is above 0, fork that many or fewer; or try again later, or start a new sandbox and fork that one, keeping the parent until it runs. The new sandbox and each copy count toward your quota: at the limit, delete sandboxes you no longer need with `delete({ wait: true })` (a deleting sandbox still counts), or top up on the free tier. Copy out what you need first, and never delete a parent while a copy forked from it is still starting. |
 | `fork_unsupported_host` | 409 | The parent's machine cannot start copies of it. With `reason` `host_retiring` (`err.reason`), the machine is being replaced: it keeps the parent but starts no new sandboxes, so no retry or smaller `count` helps. Create a new sandbox, set it up again, and fork that one. |
 | `sandbox_capacity` | 503 | No sandbox capacity is free right now. Nothing was created or billed; the SDK retries it after `Retry-After`. |
@@ -666,8 +697,8 @@ runtime) are on the pricing and docs pages at prized.dev; a create or resume
 past one fails with `sandbox_quota_exceeded`.
 
 Not yet: custom templates (from a Dockerfile), egress allow and deny lists,
-a sandbox's ports at a URL, more than 32 vCPU or 128 GB, GPUs, and regions
-other than US West.
+a port URL that opens without an API key (for a browser or a webhook), more
+than 32 vCPU or 128 GB, GPUs, and regions other than US West.
 
 ## Runtimes
 

package/dist/cjs/http.d.ts

@@ -130,7 +130,7 @@ export type RetryMode = 'safe' | 'exec' | 'staged';
 export declare function neverSent(error: unknown, depth?: number): boolean;
 export declare function retryable(error: PrizedError, mode: RetryMode, method: RequestSpec['method']): boolean;
 export interface RequestSpec {
-    method: 'GET' | 'POST' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** The URL, or one built per attempt from the ms left before `deadline`
      *  (Infinity without one): a held request asks only for what is left. */
     url: string | ((leftMs: number) => string);

package/dist/cjs/http.js

@@ -248,6 +248,8 @@ const NEVER_RETRY = new Set([
     'idempotency_conflict',
     'paid_balance_required',
     'insufficient_balance',
+    // A 503 that says preview links are off on this deployment: no wait turns them on.
+    'preview_unavailable',
 ]);
 const EXEC_UNDELIVERED = new Set([
     'rate_limited',

package/dist/cjs/index.d.ts

@@ -1,5 +1,5 @@
 export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
-export type { CreateOptions, ForkOptions, ListOptions, WaitableOptions } from './sandbox.js';
+export type { CreateOptions, ForkOptions, ListOptions, PortPreview, PreviewToken, PreviewTokenOptions, SetPortPublicOptions, 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';

package/dist/cjs/sandbox.d.ts

@@ -4,6 +4,42 @@ import { type ClientOptions } from './http.js';
 import { type ExecResult, type Resources, type ResourcesInput, type SandboxInfo, type SandboxState, type Template } from './types.js';
 /** The header a request to a sandbox port's URL carries the API key in. */
 export declare const PREVIEW_KEY_HEADER = "Prized-Key";
+/** A sandbox port's preview link (`setPortPublic`): its URL, and whether
+ *  it is public, until when. */
+export interface PortPreview {
+    sandboxId: string;
+    port: number;
+    /** The port's URL for a program with the API key (`previewUrl`). */
+    url: string;
+    /** The same port on prized.link, which opens in a browser tab once the
+     *  port is public; null where the deployment has no browser domain. */
+    browserUrl: string | null;
+    /** Anyone with the URL reaches the port, no credential needed. */
+    public: boolean;
+    /** When the port goes private again on its own; null while private. */
+    publicExpiresAt: Date | null;
+}
+/** A short-lived URL token for a sandbox port (`previewToken`). */
+export interface PreviewToken {
+    /** The preview URL with the token in its `prized_token` query parameter. */
+    url: string;
+    /** The same on prized.link, to open in a browser tab or a frame; null
+     *  where the deployment has no browser domain. */
+    browserUrl: string | null;
+    token: string;
+    expiresAt: Date;
+}
+export interface PreviewTokenOptions {
+    /** How long the token opens the port, in seconds: 60 to 86 400. Default 3600 (an hour). */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
+export interface SetPortPublicOptions {
+    /** With `true`: how long the port stays public, in seconds: 300 to
+     *  2 592 000 (30 days). Default 7 days. */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
 /** The template a create uses when it names none. */
 export declare const DEFAULT_TEMPLATE = "prized-base-v1";
 /** How long create, resume and fork wait for `running` by default. */
@@ -194,6 +230,35 @@ export declare class Sandbox {
      *  `redirect: 'manual'`: fetch resends custom headers to whatever host a
      *  redirect names, so only ever send them to the sandbox's preview URL. */
     previewHeaders(): Record<string, string>;
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    previewToken(port: number, options?: PreviewTokenOptions): Promise<PreviewToken>;
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    setPortPublic(port: number, isPublic: boolean, options?: SetPortPublicOptions): Promise<PortPreview>;
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    private previewPort;
     /** POST the verb, the call and its retries within `deadline`; with `hold`,
      *  held by the API until the sandbox is that (each attempt asks only for
      *  what is left). */

package/dist/cjs/sandbox.js

@@ -76,6 +76,13 @@ function wholeMinutes(name, value, allowZero) {
     }
     return value;
 }
+function wholeSeconds(name, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value <= 0)
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must be a whole number of seconds > 0`);
+    return value;
+}
 function apiUrl(config, path) {
     return `${config.baseUrl}/api/v1${path}`;
 }
@@ -561,9 +568,13 @@ class Sandbox {
             body.maxRuntimeMin = maxRuntimeMin;
         const idempotencyKey = options.idempotencyKey ?? randomKey();
         const wire = snapshot(body); // as in create
+        const path = `${sandboxPathFor(this.id)}/fork`;
+        // Held by the API until every copy runs (or its bound), as create is,
+        // instead of polled; the cleanup's replay only wants the ids.
+        const held = options.wait !== false;
         const send = (deadline, attempts) => (0, http_js_1.request)(this.config, {
             method: 'POST',
-            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/fork`),
+            url: (leftMs) => apiUrl(this.config, held && attempts !== undefined ? `${path}${holdQuery(this.config, 'running', leftMs)}` : path),
             json: wire,
             headers: { 'idempotency-key': idempotencyKey },
             retry: 'safe',
@@ -686,9 +697,7 @@ class Sandbox {
      * `preview_unavailable` when the deployment has sandbox ingress off.
      */
     previewUrl(port) {
-        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
-            throw new errors_js_1.PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
-        }
+        this.previewPort(port);
         const template = this.current.raw.previewUrlTemplate;
         if (typeof template !== 'string' || !template.includes('{port}')) {
             throw new errors_js_1.PrizedError('preview_unavailable', 'sandbox ports at a URL are not turned on for this deployment', { sandboxId: this.id });
@@ -702,6 +711,93 @@ class Sandbox {
     previewHeaders() {
         return { [exports.PREVIEW_KEY_HEADER]: this.config.apiKey };
     }
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    async previewToken(port, options = {}) {
+        this.previewPort(port);
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        const result = await (0, http_js_1.request)(this.config, {
+            method: 'POST',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}/token`),
+            json: expiresIn === undefined ? {} : { expiresIn },
+            // A second copy mints a second token nobody holds, which expires on its own.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: (0, http_js_1.callDeadline)(this.config),
+            sandboxId: this.id,
+        });
+        const body = result.json;
+        const expiresAt = (0, types_js_1.parseTime)(body?.expiresAt);
+        if (typeof body?.url !== 'string' || typeof body.token !== 'string' || expiresAt === null) {
+            throw new errors_js_1.PrizedError('bad_response', 'the API answered a preview token without its url, token or expiry', { sandboxId: this.id });
+        }
+        return {
+            url: body.url,
+            browserUrl: typeof body.browserUrl === 'string' ? body.browserUrl : null,
+            token: body.token,
+            expiresAt,
+        };
+    }
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    async setPortPublic(port, isPublic, options = {}) {
+        this.previewPort(port);
+        if (typeof isPublic !== 'boolean')
+            throw new errors_js_1.PrizedError('invalid_argument', 'isPublic must be true or false', { sandboxId: this.id });
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        if (expiresIn !== undefined && !isPublic) {
+            throw new errors_js_1.PrizedError('invalid_argument', 'expiresIn applies only when making a port public', { sandboxId: this.id });
+        }
+        const result = await (0, http_js_1.request)(this.config, {
+            method: 'PUT',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}`),
+            json: isPublic ? { public: true, ...(expiresIn === undefined ? {} : { expiresIn }) } : { public: false },
+            // Setting the same state again changes nothing.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: (0, http_js_1.callDeadline)(this.config),
+            sandboxId: this.id,
+        });
+        const doc = result.json?.preview;
+        if (doc === undefined || typeof doc.url !== 'string' || typeof doc.public !== 'boolean') {
+            throw new errors_js_1.PrizedError('bad_response', 'the API answered a port without its url or public setting', { sandboxId: this.id });
+        }
+        return {
+            sandboxId: typeof doc.sandboxId === 'string' ? doc.sandboxId : this.id,
+            port: typeof doc.port === 'number' ? doc.port : port,
+            url: doc.url,
+            browserUrl: typeof doc.browserUrl === 'string' ? doc.browserUrl : null,
+            public: doc.public,
+            publicExpiresAt: (0, types_js_1.parseTime)(doc.publicExpiresAt),
+        };
+    }
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    previewPort(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
+            throw new errors_js_1.PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
+        }
+    }
     // --- internals ------------------------------------------------------------------
     /** POST the verb, the call and its retries within `deadline`; with `hold`,
      *  held by the API until the sandbox is that (each attempt asks only for

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.1.3";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-exports.VERSION = '0.1.2';
+exports.VERSION = '0.1.3';

package/dist/esm/http.d.ts

@@ -130,7 +130,7 @@ export type RetryMode = 'safe' | 'exec' | 'staged';
 export declare function neverSent(error: unknown, depth?: number): boolean;
 export declare function retryable(error: PrizedError, mode: RetryMode, method: RequestSpec['method']): boolean;
 export interface RequestSpec {
-    method: 'GET' | 'POST' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** The URL, or one built per attempt from the ms left before `deadline`
      *  (Infinity without one): a held request asks only for what is left. */
     url: string | ((leftMs: number) => string);

package/dist/esm/http.js

@@ -232,6 +232,8 @@ const NEVER_RETRY = new Set([
     'idempotency_conflict',
     'paid_balance_required',
     'insufficient_balance',
+    // A 503 that says preview links are off on this deployment: no wait turns them on.
+    'preview_unavailable',
 ]);
 const EXEC_UNDELIVERED = new Set([
     'rate_limited',

package/dist/esm/index.d.ts

@@ -1,5 +1,5 @@
 export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
-export type { CreateOptions, ForkOptions, ListOptions, WaitableOptions } from './sandbox.js';
+export type { CreateOptions, ForkOptions, ListOptions, PortPreview, PreviewToken, PreviewTokenOptions, SetPortPublicOptions, 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';

package/dist/esm/sandbox.d.ts

@@ -4,6 +4,42 @@ import { type ClientOptions } from './http.js';
 import { type ExecResult, type Resources, type ResourcesInput, type SandboxInfo, type SandboxState, type Template } from './types.js';
 /** The header a request to a sandbox port's URL carries the API key in. */
 export declare const PREVIEW_KEY_HEADER = "Prized-Key";
+/** A sandbox port's preview link (`setPortPublic`): its URL, and whether
+ *  it is public, until when. */
+export interface PortPreview {
+    sandboxId: string;
+    port: number;
+    /** The port's URL for a program with the API key (`previewUrl`). */
+    url: string;
+    /** The same port on prized.link, which opens in a browser tab once the
+     *  port is public; null where the deployment has no browser domain. */
+    browserUrl: string | null;
+    /** Anyone with the URL reaches the port, no credential needed. */
+    public: boolean;
+    /** When the port goes private again on its own; null while private. */
+    publicExpiresAt: Date | null;
+}
+/** A short-lived URL token for a sandbox port (`previewToken`). */
+export interface PreviewToken {
+    /** The preview URL with the token in its `prized_token` query parameter. */
+    url: string;
+    /** The same on prized.link, to open in a browser tab or a frame; null
+     *  where the deployment has no browser domain. */
+    browserUrl: string | null;
+    token: string;
+    expiresAt: Date;
+}
+export interface PreviewTokenOptions {
+    /** How long the token opens the port, in seconds: 60 to 86 400. Default 3600 (an hour). */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
+export interface SetPortPublicOptions {
+    /** With `true`: how long the port stays public, in seconds: 300 to
+     *  2 592 000 (30 days). Default 7 days. */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
 /** The template a create uses when it names none. */
 export declare const DEFAULT_TEMPLATE = "prized-base-v1";
 /** How long create, resume and fork wait for `running` by default. */
@@ -194,6 +230,35 @@ export declare class Sandbox {
      *  `redirect: 'manual'`: fetch resends custom headers to whatever host a
      *  redirect names, so only ever send them to the sandbox's preview URL. */
     previewHeaders(): Record<string, string>;
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    previewToken(port: number, options?: PreviewTokenOptions): Promise<PreviewToken>;
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    setPortPublic(port: number, isPublic: boolean, options?: SetPortPublicOptions): Promise<PortPreview>;
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    private previewPort;
     /** POST the verb, the call and its retries within `deadline`; with `hold`,
      *  held by the API until the sandbox is that (each attempt asks only for
      *  what is left). */

package/dist/esm/sandbox.js

@@ -4,7 +4,7 @@ import { execCommand } from './commands.js';
 import { PrizedError } from './errors.js';
 import { Files } from './files.js';
 import { callDeadline, cutByDeadline, MAX_RETRY_AFTER_MS, Polls, request, resolveConfig, toolboxBaseFor, warmEdge, } from './http.js';
-import { parseSandbox, parseTemplate, resourcesToWire, } from './types.js';
+import { parseSandbox, parseTemplate, parseTime, resourcesToWire, } from './types.js';
 /** The header a request to a sandbox port's URL carries the API key in. */
 export const PREVIEW_KEY_HEADER = 'Prized-Key';
 /** The template a create uses when it names none. */
@@ -73,6 +73,13 @@ function wholeMinutes(name, value, allowZero) {
     }
     return value;
 }
+function wholeSeconds(name, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value <= 0)
+        throw new PrizedError('invalid_argument', `${name} must be a whole number of seconds > 0`);
+    return value;
+}
 function apiUrl(config, path) {
     return `${config.baseUrl}/api/v1${path}`;
 }
@@ -558,9 +565,13 @@ export class Sandbox {
             body.maxRuntimeMin = maxRuntimeMin;
         const idempotencyKey = options.idempotencyKey ?? randomKey();
         const wire = snapshot(body); // as in create
+        const path = `${sandboxPathFor(this.id)}/fork`;
+        // Held by the API until every copy runs (or its bound), as create is,
+        // instead of polled; the cleanup's replay only wants the ids.
+        const held = options.wait !== false;
         const send = (deadline, attempts) => request(this.config, {
             method: 'POST',
-            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/fork`),
+            url: (leftMs) => apiUrl(this.config, held && attempts !== undefined ? `${path}${holdQuery(this.config, 'running', leftMs)}` : path),
             json: wire,
             headers: { 'idempotency-key': idempotencyKey },
             retry: 'safe',
@@ -683,9 +694,7 @@ export class Sandbox {
      * `preview_unavailable` when the deployment has sandbox ingress off.
      */
     previewUrl(port) {
-        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
-            throw new PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
-        }
+        this.previewPort(port);
         const template = this.current.raw.previewUrlTemplate;
         if (typeof template !== 'string' || !template.includes('{port}')) {
             throw new PrizedError('preview_unavailable', 'sandbox ports at a URL are not turned on for this deployment', { sandboxId: this.id });
@@ -699,6 +708,93 @@ export class Sandbox {
     previewHeaders() {
         return { [PREVIEW_KEY_HEADER]: this.config.apiKey };
     }
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    async previewToken(port, options = {}) {
+        this.previewPort(port);
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        const result = await request(this.config, {
+            method: 'POST',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}/token`),
+            json: expiresIn === undefined ? {} : { expiresIn },
+            // A second copy mints a second token nobody holds, which expires on its own.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: callDeadline(this.config),
+            sandboxId: this.id,
+        });
+        const body = result.json;
+        const expiresAt = parseTime(body?.expiresAt);
+        if (typeof body?.url !== 'string' || typeof body.token !== 'string' || expiresAt === null) {
+            throw new PrizedError('bad_response', 'the API answered a preview token without its url, token or expiry', { sandboxId: this.id });
+        }
+        return {
+            url: body.url,
+            browserUrl: typeof body.browserUrl === 'string' ? body.browserUrl : null,
+            token: body.token,
+            expiresAt,
+        };
+    }
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    async setPortPublic(port, isPublic, options = {}) {
+        this.previewPort(port);
+        if (typeof isPublic !== 'boolean')
+            throw new PrizedError('invalid_argument', 'isPublic must be true or false', { sandboxId: this.id });
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        if (expiresIn !== undefined && !isPublic) {
+            throw new PrizedError('invalid_argument', 'expiresIn applies only when making a port public', { sandboxId: this.id });
+        }
+        const result = await request(this.config, {
+            method: 'PUT',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}`),
+            json: isPublic ? { public: true, ...(expiresIn === undefined ? {} : { expiresIn }) } : { public: false },
+            // Setting the same state again changes nothing.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: callDeadline(this.config),
+            sandboxId: this.id,
+        });
+        const doc = result.json?.preview;
+        if (doc === undefined || typeof doc.url !== 'string' || typeof doc.public !== 'boolean') {
+            throw new PrizedError('bad_response', 'the API answered a port without its url or public setting', { sandboxId: this.id });
+        }
+        return {
+            sandboxId: typeof doc.sandboxId === 'string' ? doc.sandboxId : this.id,
+            port: typeof doc.port === 'number' ? doc.port : port,
+            url: doc.url,
+            browserUrl: typeof doc.browserUrl === 'string' ? doc.browserUrl : null,
+            public: doc.public,
+            publicExpiresAt: parseTime(doc.publicExpiresAt),
+        };
+    }
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    previewPort(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
+            throw new PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
+        }
+    }
     // --- internals ------------------------------------------------------------------
     /** POST the verb, the call and its retries within `deadline`; with `hold`,
      *  held by the API until the sandbox is that (each attempt asks only for

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.1.3";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-export const VERSION = '0.1.2';
+export const VERSION = '0.1.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prized/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Prized Sandboxes (beta): create microVM sandboxes, run commands, move files, pause, resume and fork them from TypeScript.",
   "homepage": "https://prized.dev/docs/sandboxes",
   "license": "Apache-2.0",