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

package/dist/cjs/pty.d.ts

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

package/dist/cjs/pty.js

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

package/dist/cjs/trace.d.ts

@@ -31,3 +31,5 @@ export declare function mark(s: TraceStamp | undefined, phase: string): void;
 export declare function traceEvent(name: string): void;
 /** A process event that happened at `t` (`performance.now()` terms), recorded now: one another thread reported. */
 export declare function traceEventAt(name: string, t: number): void;
+/** `fn` runs once at exit, before the trace is written (tracing on only). */
+export declare function onTraceFlush(fn: () => void): void;

package/dist/cjs/trace.js

@@ -6,6 +6,7 @@ exports.traceBegin = traceBegin;
 exports.mark = mark;
 exports.traceEvent = traceEvent;
 exports.traceEventAt = traceEventAt;
+exports.onTraceFlush = onTraceFlush;
 const node_fs_1 = require("node:fs");
 const core_js_1 = require("./core.js");
 exports.TRACE_ON = (() => {
@@ -68,7 +69,23 @@ function modulePath() {
     const m = /\((.*):\d+:\d+\)\s*$/.exec(frame) ?? /at (.*):\d+:\d+\s*$/.exec(frame);
     return m?.[1] ?? "";
 }
+const beforeFlush = [];
+function onTraceFlush(fn) {
+    if (!exports.TRACE_ON)
+        return;
+    beforeFlush.push(fn);
+    if (!hooked) {
+        hooked = true;
+        process.once("exit", flush);
+    }
+}
 function flush() {
+    for (const fn of beforeFlush.splice(0)) {
+        try {
+            fn();
+        }
+        catch { }
+    }
     const head = {
         trace: "promigence-sdk",
         version: core_js_1.VERSION,

package/dist/cjs/transport-worker.js

@@ -36,6 +36,11 @@ function start(init) {
         }
         catch { }
     };
+    const ev = (n) => {
+        if (init.trace === true)
+            post({ t: "ev", n, hr: hrNow() });
+    };
+    ev("boot");
     const live = () => sessions.filter((e) => !e.retired && !e.session.closed && !e.session.destroyed);
     const end = (reason) => {
         if (closed)
@@ -96,14 +101,14 @@ function start(init) {
     catch {
         context = undefined;
     }
-    const connect = (address) => new Promise((resolve) => {
+    const connect = (address, k) => new Promise((resolve) => {
         let done = false;
         const finish = (e) => { if (!done) {
             done = true;
             clearTimeout(timer);
             resolve(e);
         } };
-        const timer = setTimeout(() => { try {
+        const timer = setTimeout(() => { ev(`timeout${k}`); try {
             socket.destroy();
         }
         catch { } finish(null); }, init.connectTimeoutMs);
@@ -115,8 +120,11 @@ function start(init) {
             checkServerIdentity: ca_guard_js_1.guardCertChain,
             ...(context === undefined ? {} : { secureContext: context }),
         });
-        socket.once("error", () => finish(null));
+        if (init.trace === true)
+            socket.once("connect", () => { ev(`tcp${k}`); });
+        socket.once("error", (e) => { ev(`fail${k} ${e?.code ?? "error"}`); finish(null); });
         socket.once("secureConnect", () => {
+            ev(`tls${k}`);
             if (socket.alpnProtocol !== "h2") {
                 socket.destroy();
                 finish(null);
@@ -169,14 +177,66 @@ function start(init) {
             resolve(v4);
             return;
         }
-        try {
-            const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: 1 });
-            if (Array.isArray(init.servers) && init.servers.length > 0)
-                r.setServers(init.servers);
-            r.resolve4(name, (err, addrs) => resolve(!err && Array.isArray(addrs) ? addrs : []));
-        }
-        catch {
-            resolve([]);
+        const at = init.lookupAtMs.length > 0 ? init.lookupAtMs : [0];
+        const resolvers = [];
+        const timers = [];
+        let done = false;
+        let asked = 0;
+        let failed = 0;
+        const finish = (addrs) => {
+            if (done)
+                return;
+            done = true;
+            for (const t of timers)
+                clearTimeout(t);
+            for (const r of resolvers) {
+                try {
+                    r.cancel();
+                }
+                catch { }
+            }
+            resolve(addrs);
+        };
+        const gaveUp = () => {
+            if (++failed < asked)
+                return;
+            if (asked < at.length)
+                ask();
+            else
+                finish([]);
+        };
+        const ask = () => {
+            if (done || asked >= at.length)
+                return;
+            const k = asked++;
+            try {
+                const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: init.lookupTries });
+                const list = Array.isArray(init.servers) && init.servers.length > 0 ? init.servers : r.getServers();
+                if (list.length > 0)
+                    r.setServers(list.map((_, i) => list[(i + k) % list.length]));
+                resolvers.push(r);
+                ev(`lookup${k + 1}`);
+                r.resolve4(name, (err, addrs) => {
+                    if (done)
+                        return;
+                    if (!err && Array.isArray(addrs) && addrs.length > 0) {
+                        ev(`addrs${k + 1} ${addrs.length}`);
+                        finish(addrs);
+                        return;
+                    }
+                    ev(`nolookup${k + 1} ${err?.code ?? "empty"}`);
+                    gaveUp();
+                });
+            }
+            catch {
+                gaveUp();
+            }
+        };
+        for (const ms of at) {
+            if (ms <= 0)
+                ask();
+            else
+                timers.push(setTimeout(ask, ms));
         }
     });
     const limitOf = (e) => {
@@ -198,7 +258,7 @@ function start(init) {
         }
         const n = Math.max(1, init.sessions);
         pendingConnects = n;
-        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length]).then((e) => {
+        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length], i).then((e) => {
             pendingConnects--;
             if (closed) {
                 if (e)

package/dist/client.d.ts

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