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

package/dist/caller.js

@@ -3,7 +3,7 @@ export const CALLER_ENV = "PROMIGENCE_CALLER";
 export const CALLER_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
 export const CALLER_VERSION_RE = /^[A-Za-z0-9.+_~-]{0,31}$/;
 export const RESERVED_CALLERS = [
-    "cli", "harbor", "inspect", "e2b-compat", "computesdk", "mcp",
+    "cli", "harbor", "inspect", "computesdk", "mcp",
 ];
 let globalCaller;
 let defaultCaller;

package/dist/cjs/caller.js

@@ -13,7 +13,7 @@ exports.CALLER_ENV = "PROMIGENCE_CALLER";
 exports.CALLER_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
 exports.CALLER_VERSION_RE = /^[A-Za-z0-9.+_~-]{0,31}$/;
 exports.RESERVED_CALLERS = [
-    "cli", "harbor", "inspect", "e2b-compat", "computesdk", "mcp",
+    "cli", "harbor", "inspect", "computesdk", "mcp",
 ];
 let globalCaller;
 let defaultCaller;

package/dist/cjs/client.d.ts

@@ -2,6 +2,7 @@
 import { inspect, type InspectOptions } from "node:util";
 import { PromigenceError, type CommandResult, type NetworkMode, type OptimizeFor, type Tier } from "./core.js";
 import { type Bundle } from "./bundle.js";
+import { type CredentialStore } from "./credstore.js";
 import { type PtyExit, type PtySession } from "./pty.js";
 import { type SshTunnel } from "./ssh.js";
 import type * as M from "./models.gen.js";
@@ -280,6 +281,10 @@ export interface ReportSandbox extends QueuedInfo {
     sandbox_id: string;
     state: SandboxState;
     attempt?: number;
+    /** `PROMIGENCE_INDEX`: its place in the run, from 0. Absent when the run's command set it itself. */
+    index?: number;
+    /** `PROMIGENCE_SEED`: the number its commands were given. Absent when the run's command set it itself. */
+    seed?: number;
     queued_ms?: number;
     ready_ms?: number;
     e2e_ms?: number;
@@ -319,11 +324,16 @@ export interface RunReport {
     snapshot_id?: string;
     alias?: string;
     labels?: Record<string, string>;
+    /**
+     * What the run asked for. `network` is `"allow"` for a run behind an allowlist, whose hosts are
+     * `allow` (a service before it said `"egress"` for one).
+     */
     requested?: {
         count: number;
         timeout_ms: number;
         verify_each: boolean;
-        network: NetworkMode;
+        network: NetworkMode | "allow";
+        allow?: string[];
         allow_partial: boolean;
         secrets?: string[];
         grade?: GradeSpec;
@@ -437,13 +447,19 @@ export interface SnapshotBuild {
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
-    /** A rejected build names the guard and the measured value; nothing was stored. */
+    /**
+     * A rejected build names the guard and the measured value; nothing was stored. `log_tail` is
+     * your build's own output: for a step of yours that failed (its start command, a setup step, its
+     * verify), that step's last lines. `fix`, when present, is what to change.
+     */
     error?: {
         code?: string;
         guard?: string;
         message?: string;
         values?: number[];
         stored?: boolean;
+        log_tail?: string[];
+        fix?: string;
     } | null;
     /** Set when an identical build already existed. */
     deduped?: boolean;
@@ -727,6 +743,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 +756,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 +931,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 +985,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. */
@@ -1127,8 +1169,9 @@ export interface SandboxPatchResponse {
 /**
  * What the idle rule counts as idle. `"requests"` (the default): nobody has called the sandbox
  * for the window and no command, terminal or SSH session is open. `"activity"`: all of that, and
- * for the whole window nothing inside used CPU or sent or received a byte, and no network
- * connection to the outside is open — for an agent that runs inside the sandbox on its own.
+ * for the whole window the sandbox used under 5% of one core, sent and received no network byte
+ * (disk writes do not count), and no network connection to the outside is open — for an agent
+ * that runs inside the sandbox on its own.
  */
 export type AutoPauseMode = M.AutoPauseMode;
 /** `POST /snapshots/:id/verify` — re-run the recorded `verify` in a fresh fork. */
@@ -1150,7 +1193,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 +1221,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 +1230,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 +1250,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;
@@ -1346,6 +1389,8 @@ export interface PortRecord {
     /** The same token as a DNS label, for a wildcard-DNS deployment (`<label>.<suffix>`). */
     host_url_label?: string;
     created_unix_ns?: number;
+    /** When the URL stops working on its own (`ttl_s`); `null` for one that works until revoked. */
+    expires_unix_ns?: number | null;
 }
 /** A key named without its secret (`/me`'s `key`, the key lists). */
 export interface KeyRef {
@@ -1492,6 +1537,12 @@ export interface PromigenceClientOpts {
      */
     onTiming?: (timing: Timing) => void;
 }
+/** Where a client's key came from: the option, PROMIGENCE_API_KEY (`env`), the stored sign-in, or a fallback. */
+export interface KeyOrigin {
+    source: "option" | "env" | "stored" | "fallback";
+    /** The stored sign-in's store, for `stored`. */
+    store?: CredentialStore;
+}
 /** `GET /sandboxes/:id/network`. */
 export interface SandboxNetwork {
     sandbox_id: string;
@@ -1730,6 +1781,11 @@ export interface SnapshotCreateOpts {
      */
     setupUser?: string;
     alias?: string;
+    /**
+     * With `alias`: take the name from the snapshot that has it, which stays, unnamed. Without it, an
+     * alias another snapshot has is refused (`usage`, 400) and nothing is built.
+     */
+    moveAlias?: boolean;
     /**
      * A DEFAULT grader for this snapshot: a run on it with no `grade` of its own uses this one.
      * The same shape as `runs.start({ grade })`.
@@ -1815,11 +1871,12 @@ export declare function credentialsExposure(path: string): string | undefined;
  * `credentialsTrustProblem`).
  */
 export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials;
-export declare function apiUrlFromCompatUrl(url: string | undefined): string | undefined;
-export declare function apiUrlFromCompatDomain(domain: string | undefined): string | undefined;
-export declare function compatApiKey(key: string | undefined): string | undefined;
 /** Which variable a key came from, for `promigence doctor`. */
 export declare function keyOrigin(env?: NodeJS.ProcessEnv): string | undefined;
+/** A request with no key found anywhere: none passed, none in the environment, none stored. */
+export declare const NO_KEY_MESSAGE = "no API key: none was given, PROMIGENCE_API_KEY is not set, and none is stored";
+/** What a caller of this SDK does about it. */
+export declare const NO_KEY_FIX = "Pass { apiKey } or set PROMIGENCE_API_KEY. No key yet: `promigence login` signs you up or in and stores one.";
 /** `name@sha256:<64 hex>`, optionally with a tag before the `@`: a reference already pinned. */
 export declare const IMAGE_DIGEST_RE: RegExp;
 /**
@@ -1906,6 +1963,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 +2070,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 +2137,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 +2159,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 +2194,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 +2258,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;
@@ -2447,6 +2541,10 @@ export declare class PromigenceClient {
         /**
          * Preview URLs for ports inside the sandbox. A URL is a capability — anyone holding it reaches
          * that port — and dies with `revoke`, with a pause, or with the sandbox.
+         *
+         * If your account's preview URLs aren't on, `expose` throws `PreviewsUnavailableError`; write to
+         * support@promigence.ai to have them turned on, and meanwhile reach the port with
+         * `promigence sandbox ssh <sid> -- -N -L <port>:localhost:<port>`.
          */
         ports: {
             expose: (sandboxId: string, port: number) => Promise<PortRecord>;
@@ -2499,7 +2597,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 +2642,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 +2760,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 +2849,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
@@ -2979,8 +3084,14 @@ export declare class PromigenceClient {
             alias?: string | null;
             deleted: boolean;
         }>;
-        /** `PUT /snapshots/:id/alias` — the sidecar's one mutable field. */
-        alias: (idOrAlias: string, alias: string | null) => Promise<SnapshotRecord>;
+        /**
+         * `PUT /snapshots/:id/alias` — the sidecar's one mutable field. A name another snapshot
+         * has is refused (`usage`, 400) unless `moveAlias: true`, which takes it; that one stays,
+         * unnamed.
+         */
+        alias: (idOrAlias: string, alias: string | null, opts?: {
+            moveAlias?: boolean;
+        }) => Promise<SnapshotRecord>;
         /**
          * Wait for a build to leave `running`, bounded by `waitTimeoutMs` (default 100 s).
          *