@promigence/sdk 0.1.0-beta.7 → 0.1.0-beta.9

package/README.md

@@ -13,8 +13,9 @@ npm i @promigence/sdk
 ```
 
 You need a Promigence account (private beta, by invite). The quickest way to create one is the CLI:
-`npm i -g promigence`, then `promigence signup`. The SDK reads the key from `PROMIGENCE_API_KEY` or
-from where the CLI stored it: the system keychain, or `~/.config/promigence/credentials`.
+`npm i -g promigence`, then `promigence signup`. The SDK uses the key you pass (`apiKey`) or
+`PROMIGENCE_API_KEY`; with neither, the key the CLI stored: the system keychain, or
+`~/.config/promigence/credentials`. A key you pass or set is used as is; the stored one is not read.
 
 ## Use it
 

package/dist/cjs/client.d.ts

@@ -420,7 +420,19 @@ export interface SnapshotBuild {
     /** `true` when the snapshot this build made has since been deleted. */
     snapshot_deleted?: boolean;
     tier_assigned?: string;
+    /**
+     * The most the build can cost, USD, said before it runs: `max_seconds` at `per_second_usd`. A build
+     * is billed per second for the time it runs; what it cost is `cost_usd` once it has ended.
+     */
     build_price?: number;
+    /** What one second of the build costs, USD: its tier's per-second rate. */
+    per_second_usd?: number;
+    /** The longest the build may run, in seconds: it is billed for at most this long. */
+    max_seconds?: number;
+    /** Once it has ended, the seconds it is billed for; 0 when it failed on our side. */
+    billable_seconds?: number;
+    /** Once it has ended, what it cost, USD; 0 when nothing was charged. */
+    cost_usd?: number;
     repo?: string;
     commit?: string;
     verification?: Record<string, unknown>;
@@ -748,6 +760,8 @@ export interface CreditOffer {
     state: string;
     credit_usd: number;
     card_bonus_usd: number;
+    /** USD charged to confirm Apple Pay, Google Pay or Amazon Pay when one is added (added to the credit). */
+    method_check_usd?: number;
     expires_at?: string | null;
     campaign?: string | null;
     message: string;
@@ -845,7 +859,10 @@ export interface PricingView {
         gib_second_usd: number;
         preemptible_vcpu_second_usd: number;
         preemptible_gib_second_usd: number;
-        /** One snapshot build, charged once it verifies. */
+        /**
+         * The most one snapshot build of the default tier can cost (`limits.build_max_s` seconds at that
+         * tier's rate). A build is billed per second at its own tier's rate for the time it runs.
+         */
         build_usd: number;
         /** Per GiB of data out above the month's allowance; `null` when not priced. */
         egress_gb_usd: number | null;
@@ -870,6 +887,8 @@ export interface PricingView {
         max_egress_gb_month: number | null;
         /** Outbound mail ports open. */
         smtp: boolean;
+        /** The longest a snapshot build may run, in seconds: the most one build is billed for. */
+        build_max_s?: number;
     };
     /** The free credit a new account gets (an account's own: `GET /credits/offer`). */
     free_credit: {
@@ -906,6 +925,16 @@ export interface BillingUsage {
         brand?: string;
         last4?: string;
     } | null;
+    /** Set when the card on file does not unlock paid limits for this organization (it already pays for another one,
+     *  it is being confirmed with a $1 charge, or that charge did not go through). */
+    card_note?: string | null;
+    /** The $1 that confirms Apple Pay, Google Pay or Amazon Pay on file: `confirming`, `paid` or `failed`. */
+    method_check?: {
+        method: string;
+        status: string;
+        amount_usd: number;
+        bonus_usd?: number | null;
+    } | null;
     suspended?: boolean;
     suspend_reason?: string | null;
     period?: {
@@ -929,6 +958,10 @@ export interface BillingUsage {
     upcoming_invoice_error?: string | null;
     [extra: string]: unknown;
 }
+/** One row of `GET /billing/history`: a credit the organization received, or a payment. */
+export type BillingHistoryEntry = M.BillingHistoryEntry;
+/** What `billing.historyPage()` lists: everything, only credits, or only payments. */
+export type BillingHistoryKind = "all" | "credits" | "payments";
 /** One metered row of `GET /me/ledger`. */
 export interface LedgerEntry {
     entry_id: string;
@@ -1431,7 +1464,11 @@ export interface PromigenceClientOpts {
      * From the CLI: `promigence --request-timeout DUR` or `PROMIGENCE_REQUEST_TIMEOUT`.
      */
     requestTimeoutMs?: number;
-    /** Retries on 429/503 only (default 3). */
+    /**
+     * How many times a request is sent again (default 3): after a 429 or a 503, and after a 502 or
+     * 504 that is not the API's own answer when sending twice is harmless (a read, a delete, or a
+     * create with its idempotency key).
+     */
     maxRetries?: number;
     /** Backoff base when the server sends no `Retry-After` (default 250 ms). */
     retryBaseMs?: number;
@@ -1869,7 +1906,7 @@ interface RequestOpts {
     signal?: AbortSignal;
     /** Skip the Authorization header (unauthenticated routes). */
     anonymous?: boolean;
-    /** Called with the response headers of the attempt that answered (not of a retried 429/503). */
+    /** Called with the response headers of the attempt that answered (not of one that was retried). */
     onHeaders?: (headers: Headers) => void;
     /** Extra request headers (e.g. `promigence-replaced-by`). Never the authorization. */
     headers?: Record<string, string>;
@@ -1944,8 +1981,10 @@ export declare class PromigenceClient {
      * rule `request()` applies, for the calls that cannot go through it (byte transfers, the
      * opening of an exec stream, the terminal handshake). Retried: a 429, and a 503 that says
      * nothing started — any 503 for a request safe to send twice, else only one carrying a
-     * `Retry-After` (every refusal at the door sets one) or a refusal code. At most `maxRetries`
-     * times, and never a `Retry-After` longer than MAX_RETRY_SLEEP_MS: that one is the caller's.
+     * `Retry-After` (every refusal at the door sets one) or a refusal code — and, for a request
+     * safe to send twice, a 502 or 504 that is not the API's own answer (it carries no error
+     * code). At most `maxRetries` times, and never a `Retry-After` longer than
+     * MAX_RETRY_SLEEP_MS: that one is the caller's.
      */
     private refusalBackoff;
     /** A long-poll request must outlive its own `wait_ms`; everything else keeps the default. */
@@ -1982,7 +2021,7 @@ export declare class PromigenceClient {
     }): Promise<StatusResponse>;
     /**
      * `GET /pricing` — your organization's price list, live: the per-second rates, every sandbox
-     * shape on sale and its price, the build price, the limits, the free credit and the plan they
+     * shape on sale and its price (a snapshot build bills at its tier's), the limits, the free credit and the plan they
      * come from, read on every call from what billing charges. Needs a key: without one this throws
      * `AuthError` and sends nothing. The published list prices are on the pricing page.
      *
@@ -2033,6 +2072,16 @@ export declare class PromigenceClient {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<LedgerEntry>>;
+        /**
+         * `GET /billing/history` — the credits the organization received and its payments, newest
+         * first (one page). `kind` narrows it to `credits` or `payments`; feed `nextCursor` back as
+         * `cursor` until it is `null`. An owner's key.
+         */
+        historyPage: (opts?: {
+            kind?: BillingHistoryKind;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<BillingHistoryEntry>>;
         /** `POST /billing/checkout` — the hosted page that puts a card on file. */
         checkout: () => Promise<{
             url: string;
@@ -2433,6 +2482,18 @@ export declare class PromigenceClient {
             onData?: (data: Uint8Array) => void;
             onExit?: (exit: PtyExit) => void;
             timeoutMs?: number;
+            /** Pick the same terminal up again when its connection drops or the service is updated;
+             *  see `PtyConnectOpts.resume`. Default: on. */
+            resume?: boolean;
+            /** Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+             *  terminal cannot be picked up again; see `PtyConnectOpts.reconnect`. Default: on without
+             *  `cmd`, off with one. */
+            reconnect?: boolean;
+            /** Called after each reconnect: `resumed` says whether it is the same terminal or a new
+             *  shell. */
+            onReconnected?: (how: {
+                resumed: boolean;
+            }) => void;
         }) => Promise<PtySession>;
         /** `GET /sandboxes/:id`. */
         get: (sandboxId: string) => Promise<SandboxRecord>;

package/dist/cjs/client.js

@@ -168,7 +168,7 @@ function decodeCredentials(buf) {
         return buf.subarray(3).toString("utf8");
     return buf.toString("utf8");
 }
-function storedCredentials(env = process.env) {
+function storedCredentials(env = process.env, platform = process.platform) {
     const path = credentialsPath(env);
     let present = true;
     try {
@@ -178,7 +178,7 @@ function storedCredentials(env = process.env) {
         present = e.code !== "ENOENT";
     }
     if (!present) {
-        const store = (0, credstore_js_1.keychainStore)(env);
+        const store = (0, credstore_js_1.keychainStore)(env, platform);
         if (store === undefined)
             return undefined;
         const r = (0, credstore_js_1.keychainReadCached)(store, path, env);
@@ -292,8 +292,6 @@ function keyOrigin(env = process.env) {
     const stored = readCredentialsWithStore(env);
     if (stored.creds.api_key)
         return stored.store === "macos-keychain" ? "macOS Keychain" : stored.store === "secret-service" ? "Secret Service keyring" : "credentials file";
-    if (compatApiKey(env["E2B_API_KEY"]))
-        return "E2B_API_KEY (compat)";
     return undefined;
 }
 function resolveCredentials(opts, env = process.env) {
@@ -302,17 +300,19 @@ function resolveCredentials(opts, env = process.env) {
         const t = u.replace(/\/+$/, "");
         return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
     };
-    const { creds, store } = readCredentialsWithStore(env);
     const envKey = set(env["PROMIGENCE_API_KEY"]?.trim());
     const envUrl = set(env["PROMIGENCE_API_URL"]);
     const optKey = opts.apiKey?.trim();
+    const given = optKey !== undefined || envKey !== undefined;
+    const { creds, store } = given
+        ? { creds: {}, store: undefined }
+        : readCredentialsWithStore(env);
     const source = optKey !== undefined ? "opts" : envKey !== undefined ? "env" : creds.api_key !== undefined ? "file" : undefined;
     const ours = optKey ?? envKey ?? creds.api_key;
-    const compat = ours === undefined ? compatApiKey(env["E2B_API_KEY"]) : undefined;
-    const compatUrl = compat === undefined
-        ? undefined
-        : apiUrlFromCompatUrl(env["E2B_API_URL"]) ?? apiUrlFromCompatDomain(env["E2B_DOMAIN"]);
-    const fromFile = trim(creds.api_url ?? compatUrl ?? core_js_1.DEFAULT_API_URL);
+    const fallback = ours === undefined ? opts.fallbackKey : undefined;
+    const fallbackKey = set(fallback?.apiKey.trim());
+    const fallbackUrl = fallbackKey === undefined ? undefined : set(fallback?.apiUrl);
+    const fromFile = trim(creds.api_url ?? fallbackUrl ?? core_js_1.DEFAULT_API_URL);
     const fromEnv = envUrl !== undefined ? trim(envUrl) : fromFile;
     const apiUrl = opts.apiUrl !== undefined ? trim(opts.apiUrl) : fromEnv;
     const paired = source === "file" ? fromFile : source === "env" ? fromEnv : apiUrl;
@@ -324,10 +324,10 @@ function resolveCredentials(opts, env = process.env) {
             : "Pass apiKey together with apiUrl, or set PROMIGENCE_API_URL to that URL instead of passing apiUrl.");
         return { apiKey: undefined, apiUrl, refusal };
     }
-    const key = ours ?? compat;
+    const key = ours ?? fallbackKey;
     if (key) {
         const from = source === "opts" ? "the apiKey option" : source === "env" ? "PROMIGENCE_API_KEY"
-            : source === "file" ? storedName(store, env) : "E2B_API_KEY";
+            : source === "file" ? storedName(store, env) : fallback.from;
         const refusal = keyRefusal(key, from);
         if (refusal)
             return { apiKey: undefined, apiUrl, refusal };
@@ -685,6 +685,7 @@ function errorFor(code, message, fix, extra = {}) {
         case "invalid_argument":
             return attach(new core_js_1.InvalidArgumentError(message, extra.cli ? fix : withoutCliHelp(fix), code));
         case "not_released": return attach(new core_js_1.NotReleasedError(message));
+        case "service_restart": return attach(new core_js_1.ServiceRestartError(message, fix));
         default:
             if (ENV_CODES.has(code) || extra.category === "env")
                 return attach(new core_js_1.EnvFailedError(code, message, fix));
@@ -869,7 +870,8 @@ class PromigenceClient {
     refusalBackoff(status, retryAfterMs, code, attempt, replayable, signal) {
         if (attempt >= this.maxRetries || signal?.aborted)
             return undefined;
-        if (status !== 429 && status !== 503)
+        const gateway = (status === 502 || status === 504) && replayable && code === undefined;
+        if (status !== 429 && status !== 503 && !gateway)
             return undefined;
         if ((retryAfterMs ?? 0) > MAX_RETRY_SLEEP_MS)
             return undefined;
@@ -992,12 +994,17 @@ class PromigenceClient {
                 throw new core_js_1.UnreachableError(`cannot reach ${url}: ${transportDetail(e)}`);
             }
             const retryAfterMs = parseRetryAfter(headerOf(res, "retry-after"));
-            let retryable = (res.status === 429 || res.status === 503) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
+            const gateway = (res.status === 502 || res.status === 504) && replayable;
+            let retryable = (res.status === 429 || res.status === 503 || gateway) && (retryAfterMs ?? 0) <= MAX_RETRY_SLEEP_MS;
             let body;
             if (retryable && res.status === 503 && !replayable && retryAfterMs === undefined) {
                 body = await res.text().catch(() => "");
                 retryable = REFUSED_503_CODES.has(errorCodeOf(body) ?? "");
             }
+            if (retryable && gateway) {
+                body = await res.text().catch(() => "");
+                retryable = errorCodeOf(body) === undefined;
+            }
             if (retryable && attempt < this.maxRetries) {
                 const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
                 const jitter = Math.random();
@@ -1005,6 +1012,8 @@ class PromigenceClient {
                     ? retryAfterMs + jitter * Math.min(250, this.retryBaseMs)
                     : backoff * (0.5 + jitter * 0.5);
                 this.stats.retries++;
+                if (gateway && opts.method === "DELETE")
+                    resentDelete = true;
                 if (body === undefined)
                     try {
                         await res.text();
@@ -1291,6 +1300,14 @@ class PromigenceClient {
             const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
             return pageOf(r, "entries", limit);
         },
+        historyPage: async (opts = {}) => {
+            const limit = opts.limit ?? 50;
+            const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
+            if (opts.kind !== undefined && opts.kind !== "all")
+                q.set("kind", opts.kind);
+            const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
+            return pageOf(r, "entries", limit);
+        },
         checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
         portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
         referrals: () => this.request({ method: "GET", path: "/referrals" }),
@@ -1785,6 +1802,10 @@ class PromigenceClient {
                             on.heartbeat?.();
                             continue;
                         }
+                        if (event === "reconnect") {
+                            reader.cancel().catch(() => { });
+                            throw new core_js_1.ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
+                        }
                         let parsed = {};
                         try {
                             parsed = JSON.parse(data);
@@ -2020,6 +2041,9 @@ class PromigenceClient {
                 ...(opts.onData ? { onData: opts.onData } : {}),
                 ...(opts.onExit ? { onExit: opts.onExit } : {}),
                 ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
+                ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
                 refuse: (status, text, retryAfter) => {
                     let payload = {};
                     try {

package/dist/cjs/core.d.ts

@@ -1,5 +1,5 @@
 /** Promigence SDK — constants, error hierarchy and shared types. */
-export declare const VERSION = "0.1.0-beta.7";
+export declare const VERSION = "0.1.0-beta.9";
 export declare const DOCS_URL = "https://promigence.ai";
 /** The error reference; each code is an anchor on it (the API's `docs` link has the same form). */
 export declare const ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
@@ -14,12 +14,14 @@ export declare const WAIT_TIMEOUT_MS = 100000;
  */
 export declare const IMAGE_BUILD_TIMEOUT_MS: number;
 /**
- * The list price of one new snapshot build this SDK was built with, in USD (charged once it
- * verifies; a dedupe or a join is free). Prices change: the live one is `client.pricing()`'s
- * `rates.build_usd` (this key's organization's), and a build's own arrives as `build_price` in
- * the `POST /snapshots` answer. This is only the fallback when the API cannot be asked.
+ * The most one new snapshot build of the default tier can cost at the list prices this SDK was
+ * built with, in USD: its time limit (an hour) at that tier's per-second rate. A build is billed per
+ * second for the time it runs; reusing or joining an identical build is free. Prices change: the
+ * live figure is `client.pricing()`'s `rates.build_usd` (this key's organization's), and a build's
+ * own arrives as `build_price` in the `POST /snapshots` answer. This is only the fallback when the
+ * API cannot be asked.
  */
-export declare const IMAGE_BUILD_LIST_PRICE = 1;
+export declare const IMAGE_BUILD_LIST_PRICE = 0.1656;
 /** Inline output budget for an exec before `truncated` + `_ref`. */
 export declare const MAX_OUTPUT_BYTES_DEFAULT: number;
 /** One request of a `files.put`. **Not a file-size limit** — `put` loops. */
@@ -190,6 +192,15 @@ export declare class TimeoutError extends PromigenceError {
         runId?: string;
     });
 }
+/**
+ * A service update may stop a command that was running while its output was streaming to you
+ * (`execStream`, `commands.run` with output callbacks); the time it ran is credited back, and the
+ * sandbox keeps running. `retryable` is `false`: the command may have done part of its work before
+ * it stopped, so run it again only if that is safe. exit 3
+ */
+export declare class ServiceRestartError extends PromigenceError {
+    constructor(message: string, fix: string);
+}
 /** An API error with no more specific class (5xx, unknown code). exit from the table. */
 export declare class ApiError extends PromigenceError {
 }

package/dist/cjs/core.js

@@ -1,20 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXIT_BY_CODE = exports.NotReleasedError = exports.ApiError = exports.TimeoutError = exports.RateLimitError = exports.UnreachableError = exports.NotFoundError = exports.AuthError = exports.NotVerifiedError = exports.SpendCapError = exports.CommandExitError = exports.EnvFailedError = exports.PreviewsUnavailableError = exports.UnsupportedError = exports.InvalidArgumentError = exports.PromigenceError = exports.PREVIEWS_UNAVAILABLE = exports.FILE_PUT_CHUNK_BYTES = exports.MAX_OUTPUT_BYTES_DEFAULT = exports.IMAGE_BUILD_LIST_PRICE = exports.IMAGE_BUILD_TIMEOUT_MS = exports.WAIT_TIMEOUT_MS = exports.KEY_CONTACT = exports.DEFAULT_API_URL = exports.ERRORS_DOCS_URL = exports.DOCS_URL = exports.VERSION = void 0;
+exports.EXIT_BY_CODE = exports.NotReleasedError = exports.ApiError = exports.ServiceRestartError = exports.TimeoutError = exports.RateLimitError = exports.UnreachableError = exports.NotFoundError = exports.AuthError = exports.NotVerifiedError = exports.SpendCapError = exports.CommandExitError = exports.EnvFailedError = exports.PreviewsUnavailableError = exports.UnsupportedError = exports.InvalidArgumentError = exports.PromigenceError = exports.PREVIEWS_UNAVAILABLE = exports.FILE_PUT_CHUNK_BYTES = exports.MAX_OUTPUT_BYTES_DEFAULT = exports.IMAGE_BUILD_LIST_PRICE = exports.IMAGE_BUILD_TIMEOUT_MS = exports.WAIT_TIMEOUT_MS = exports.KEY_CONTACT = exports.DEFAULT_API_URL = exports.ERRORS_DOCS_URL = exports.DOCS_URL = exports.VERSION = void 0;
 exports.previewsFix = previewsFix;
 exports.withPreviewsFix = withPreviewsFix;
 exports.fixBeyondMessage = fixBeyondMessage;
 exports.previewsOff = previewsOff;
 exports.exitForCode = exitForCode;
 const hint_js_1 = require("./hint.js");
-exports.VERSION = "0.1.0-beta.7";
+exports.VERSION = "0.1.0-beta.9";
 exports.DOCS_URL = "https://promigence.ai";
 exports.ERRORS_DOCS_URL = "https://www.promigence.ai/docs/errors";
 exports.DEFAULT_API_URL = "https://api.promigence.ai/v1";
 exports.KEY_CONTACT = "support@promigence.ai";
 exports.WAIT_TIMEOUT_MS = 100_000;
 exports.IMAGE_BUILD_TIMEOUT_MS = 15 * 60_000;
-exports.IMAGE_BUILD_LIST_PRICE = 1.0;
+exports.IMAGE_BUILD_LIST_PRICE = 0.1656;
 exports.MAX_OUTPUT_BYTES_DEFAULT = 64 * 1024;
 exports.FILE_PUT_CHUNK_BYTES = 16 * 1024 * 1024;
 const PREVIEWS_OFF = /^previews are not enabled on this deployment\.?$/i;
@@ -215,6 +215,12 @@ class TimeoutError extends PromigenceError {
     }
 }
 exports.TimeoutError = TimeoutError;
+class ServiceRestartError extends PromigenceError {
+    constructor(message, fix) {
+        super({ code: "service_restart", message, fix, exitCode: 3, category: "env", retryable: false });
+    }
+}
+exports.ServiceRestartError = ServiceRestartError;
 class ApiError extends PromigenceError {
 }
 exports.ApiError = ApiError;
@@ -233,6 +239,7 @@ exports.EXIT_BY_CODE = {
     invalid_argument: 2, unsupported: 2, not_released: 1, task_failed: 4,
     env_failed: 3, snapshot_rejected: 6, build_failed: 3, snapshot_failed: 4,
     not_connected: 7,
+    service_restart: 3,
     fork_failed: 3, start_timeout: 3, readiness_failed: 3, verify_too_slow: 3,
     verify_each_failed: 3, toolchain_mismatch: 3, sandbox_unresponsive: 3, oom_within_tier: 3,
     disk_full_within_tier: 3, sandbox_interrupted: 3, integrity_mismatch: 3, egress_unavailable: 3,
@@ -259,10 +266,11 @@ exports.EXIT_BY_CODE = {
     build_timeout: 4,
     image_unresolvable: 2,
     registry_unavailable: 3,
-    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 10,
+    trial_credits_exhausted: 5, card_required: 5, credit_unclaimed: 5, concurrency_limit: 5, egress_cap_reached: 5,
     billing_unavailable: 5,
     project_cap_reached: 5,
     spend_limit_reached: 5,
+    billing_hold: 5,
     tier_over_plan: 2,
     network_host_refused: 9, network_policy_unsupported: 3,
     secrets_in_snapshot: 2, secrets_unavailable: 3,

package/dist/cjs/credstore.d.ts

@@ -3,7 +3,8 @@
  * the credentials file (`~/.config/promigence/credentials`, 0600). The CLI writes it
  * (`promigence login`, `promigence auth login`, `promigence logout`); the CLI and both SDKs read it.
  *
- *   macOS            the login Keychain, through `security` (when HOME holds one)
+ *   macOS            the login Keychain, through `security` (when the user's home holds one: HOME,
+ *                    or the account's own home when the environment has no HOME)
  *   Linux and BSD    the Secret Service (GNOME Keyring, KWallet), through `secret-tool`, when a
  *                    desktop session bus is there (a CI job or an SSH shell has none: the file)
  *   Windows          the file: no tool that ships with Windows can read a stored secret back
@@ -34,7 +35,7 @@ export declare function storeLabel(store: CredentialStore, path?: string): strin
  * The keychain this process stores a sign-in in, or undefined for the file. `auto` is decided by
  * the platform and by whether its tool (and, for the Secret Service, a session bus) is there.
  */
-export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string): KeychainStore | undefined;
+export declare function keychainStore(env?: NodeJS.ProcessEnv, platform?: string, home?: () => string): KeychainStore | undefined;
 /**
  * The keychains a sign-out (or a sign-in that lands in the file) must clear for this path: the one
  * in use, and the platform's own even when `PROMIGENCE_CREDENTIAL_STORE=file` (an item a previous

package/dist/cjs/credstore.js

@@ -13,6 +13,7 @@ exports.keychainCacheSet = keychainCacheSet;
 exports.forgetKeychainReads = forgetKeychainReads;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 exports.KEYCHAIN_SERVICE = "promigence-cli";
 const KEYCHAIN_LABEL = "Promigence CLI credentials";
@@ -43,8 +44,19 @@ function sessionBus(env) {
     const run = env["XDG_RUNTIME_DIR"];
     return Boolean(run) && (0, node_fs_1.existsSync)((0, node_path_1.join)(run, "bus"));
 }
+function userHome(env, home = node_os_1.homedir) {
+    const h = env["HOME"];
+    if (h)
+        return h;
+    try {
+        return home() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const warnedSetting = new Set();
-function keychainStore(env = process.env, platform = process.platform) {
+function keychainStore(env = process.env, platform = process.platform, home = node_os_1.homedir) {
     const raw = (env["PROMIGENCE_CREDENTIAL_STORE"] ?? "").trim().toLowerCase();
     switch (raw) {
         case "file": return undefined;
@@ -59,8 +71,8 @@ function keychainStore(env = process.env, platform = process.platform) {
             }
     }
     if (platform === "darwin") {
-        const home = env["HOME"];
-        return home && (0, node_fs_1.existsSync)((0, node_path_1.join)(home, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
+        const h = userHome(env, home);
+        return h && (0, node_fs_1.existsSync)((0, node_path_1.join)(h, "Library", "Keychains")) && onPath("security", env) ? "macos-keychain" : undefined;
     }
     if (platform === "win32")
         return undefined;
@@ -107,8 +119,9 @@ function runTool(store, args, env, input, timeout) {
     const bin = onPath(toolName(store), env);
     if (bin === undefined)
         throw Object.assign(new Error(`${toolName(store)} not found`), { code: "ENOENT" });
+    const h = store === "macos-keychain" && !env["HOME"] ? userHome(env) : undefined;
     return (0, node_child_process_1.execFileSync)(bin, args, {
-        encoding: "utf8", timeout, env,
+        encoding: "utf8", timeout, env: h ? { ...env, HOME: h } : env,
         ...(input === undefined ? { stdio: ["ignore", "pipe", "pipe"] } : { input, stdio: ["pipe", "pipe", "pipe"] }),
     });
 }

package/dist/cjs/github.d.ts

@@ -34,7 +34,7 @@ export interface GithubPending {
     state: string;
     message: string;
 }
-/** A snapshot that follows a branch: every push builds it again (at the build price). */
+/** A snapshot that follows a branch: every push builds it again (each build billed per second). */
 export interface GithubTrack {
     track_id: string;
     repo: string;

package/dist/cjs/gitlab.d.ts

@@ -37,7 +37,7 @@ export interface GitlabPending {
     expires_at: string;
     message: string;
 }
-/** A snapshot that follows a GitLab branch: each new commit builds it again (at the build price). */
+/** A snapshot that follows a GitLab branch: each new commit builds it again (each build billed per second). */
 export interface GitlabTrack {
     track_id: string;
     repo: string;