@run402/sdk 4.93.2 → 4.95.0

package/dist/namespaces/{operator-session.js → session.js}

@@ -1,37 +1,124 @@
 /**
- * `operator.session` — the hosted/browser control-plane **session** surface
- * (gateway v1.78 `passkey-principals-onboarding`). The write-capable human
- * principal: log in (email magic-link / passkey / Google / GitHub), manage the
- * session (whoami / refresh / revoke), enrol a passkey, run a step-up ceremony,
- * and manage authenticators + recovery codes.
+ * `session` — a person's **sign-in session** (wire token class
+ * `control_plane_session`). One session, bound to the principal, graded by how
+ * it was minted (`grade` on every mint response and on `GET /agent/v1/whoami`):
  *
- * Reached as `r.operator.session.*`. Distinct from the read-only operator
- * overview session (`r.operator.deviceStart`/`overview`) and from the CLI
- * loopback-PKCE write-login (`r.operator.buildCliAuthorizeUrl`/`exchangeCliToken`,
- * which is the headless variant of this same browser ceremony). All three are
- * the one human principal; this group is the browser/console front door that the
- * hosted login pages and `@run402/sdk` consumers call.
+ * - `browser` — the console: email magic link, passkey, Google, or GitHub.
+ * - `loopback` — `run402 login`: the loopback-PKCE browser ceremony
+ *   ({@link Session.buildCliAuthorizeUrl} + {@link Session.exchangeCliToken}).
+ *   Full and step-up-able.
+ * - `device` — `run402 login --device`: RFC 8628 device authorization
+ *   ({@link Session.deviceStart} + {@link Session.devicePoll}). Read-only: the
+ *   gateway refuses every mutation with `403 SESSION_READ_ONLY`.
  *
- * Isomorphic — no Node APIs. The token model mirrors {@link Operator.overview}:
- * the public *mint* methods (`email`/`verifyEmail`/`passkey*`/`consumeRecoveryCode`)
- * send no auth (the body or the magic-link token IS the credential); the
- * *session-bound* methods take `opts.token` to send the `control_plane_session`
- * bearer explicitly, and fall back to the credential provider's default auth
- * (e.g. {@link controlPlaneSessionCredentials} or a SIWX wallet) when omitted.
+ * Reached as `r.session.*`. Isomorphic — no Node APIs; the loopback server and
+ * PKCE generation live in the Node CLI. The public *mint* methods send no auth
+ * (the body, the magic-link token, or the code + verifier is the credential);
+ * the *session-bound* methods take `opts.token` to send the bearer explicitly,
+ * and fall back to the credential provider's default auth (e.g.
+ * {@link controlPlaneSessionCredentials} or a SIWX wallet) when omitted.
  *
  * WebAuthn option/assertion payloads are opaque passthroughs (`unknown`) — the
  * browser runs the actual ceremony; a headless client cannot.
  *
- * High-stakes writes (invite, membership, handoff, delete) require a **fresh
+ * High-stakes writes (invite, membership, transfer, delete) require a **fresh
  * passkey** — a magic-link/OAuth session does NOT satisfy step-up, so the
  * gateway returns {@link StepUpRequiredError}; `stepUpOptions`/`stepUpVerify`
- * are how a long-lived session re-establishes that freshness.
+ * are how a long-lived session re-establishes that freshness. A write approval
+ * ({@link WriteApproval}) never satisfies step-up.
  */
-export class OperatorSession {
+import { ApiError, NetworkError } from "../errors.js";
+const POLL_ERROR_CODES = new Set([
+    "authorization_pending",
+    "slow_down",
+    "access_denied",
+    "expired_token",
+]);
+export class Session {
     client;
     constructor(client) {
         this.client = client;
     }
+    // ── command-line login (public — no auth) ──
+    /**
+     * Build the loopback-PKCE authorize URL `run402 login` opens in the browser
+     * (`GET /agent/v1/control-plane/cli/authorize`). Pure — no network. The
+     * caller generates `codeChallenge`/`state`/`nonce` and runs the redirect
+     * server on `127.0.0.1`.
+     */
+    buildCliAuthorizeUrl(params) {
+        const q = new URLSearchParams({
+            redirect_uri: params.redirectUri,
+            code_challenge: params.codeChallenge,
+            code_challenge_method: "S256",
+            state: params.state,
+            nonce: params.nonce,
+        });
+        return `${this.client.apiBase}/agent/v1/control-plane/cli/authorize?${q.toString()}`;
+    }
+    /**
+     * Exchange the loopback authorization code (+ PKCE verifier) for a
+     * `loopback`-grade sign-in session (`POST …/cli/token`). Unauthenticated —
+     * the code + verifier are the credential.
+     */
+    async exchangeCliToken(params) {
+        return this.client.request("/agent/v1/control-plane/cli/token", {
+            method: "POST",
+            body: {
+                code: params.code,
+                code_verifier: params.codeVerifier,
+                redirect_uri: params.redirectUri,
+                state: params.state,
+            },
+            withAuth: false,
+            context: "exchanging CLI authorization code",
+        });
+    }
+    /**
+     * Begin RFC 8628 device authorization (`POST …/cli/device`) for
+     * `run402 login --device`. Unauthenticated. Returns the codes the CLI prints
+     * (`user_code` + `verification_uri`) plus the poll `interval` and
+     * `expires_in`. The person approves in the console, which needs a recent
+     * sign-in (`403 RECENT_SIGN_IN_REQUIRED` otherwise).
+     */
+    async deviceStart() {
+        return this.client.request("/agent/v1/control-plane/cli/device", {
+            method: "POST",
+            body: {},
+            withAuth: false,
+            context: "starting device authorization",
+        });
+    }
+    /**
+     * Poll once for approval (`POST …/cli/device/token`). Bypasses the kernel's
+     * error mapping on purpose: the RFC 8628 error codes (`authorization_pending`,
+     * `slow_down`, ...) are normal polling states returned as data, not
+     * exceptions. Only an unexpected response shape throws. The approved session
+     * is `device` grade (read-only).
+     */
+    async devicePoll(deviceCode) {
+        const url = `${this.client.apiBase}/agent/v1/control-plane/cli/device/token`;
+        let res;
+        try {
+            res = await this.client.fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ device_code: deviceCode }),
+            });
+        }
+        catch (err) {
+            throw new NetworkError(`Network error while polling device token: ${err.message}`, err, "polling device token");
+        }
+        const body = (await res.json().catch(() => null));
+        if (res.ok && body && typeof body.control_plane_session_token === "string") {
+            return { kind: "approved", session: body };
+        }
+        const error = body && typeof body.error === "string" ? body.error : null;
+        if (error && POLL_ERROR_CODES.has(error)) {
+            return { kind: error };
+        }
+        throw new ApiError(`Unexpected device-token response (HTTP ${res.status})`, res.status, body, "polling device token");
+    }
     // ── login / mint (public — no auth; the body or link token is the credential) ──
     /**
      * Send a control-plane sign-in magic link to `email`
@@ -47,7 +134,7 @@ export class OperatorSession {
         });
     }
     /**
-     * Exchange a magic-link token for a control-plane session
+     * Exchange a magic-link token for a sign-in session
      * (`POST …/session/email/verify`). Verifies the email, resolves/creates the
      * principal, **auto-claims any pending invites**, and mints the session
      * (`amr: ["email"]`).
@@ -113,14 +200,15 @@ export class OperatorSession {
     }
     // ── session lifecycle (bearer; falls back to credential provider) ──
     /**
-     * Resolve the current session's principal + memberships + freshness
-     * (`GET /agent/v1/control-plane/session`). The `memberships` reflect any
-     * invites auto-claimed at login.
+     * Resolve the session's principal, memberships, and `session` —
+     * `{ grade, amr, amr_times }` (`GET /agent/v1/whoami`). The `memberships`
+     * reflect any invites auto-claimed at sign-in. With no `token` the request
+     * uses the credential provider, and `session` is `null` for a wallet caller.
      */
     async whoami(opts = {}) {
-        return this.client.request("/agent/v1/control-plane/session", {
+        return this.client.request("/agent/v1/whoami", {
             ...authFor(opts),
-            context: "resolving control-plane session",
+            context: "resolving sign-in session",
         });
     }
     /** Rotate the access token (`POST …/session/refresh`). */
@@ -128,7 +216,7 @@ export class OperatorSession {
         return this.client.request("/agent/v1/control-plane/session/refresh", {
             method: "POST",
             ...authFor(opts),
-            context: "refreshing control-plane session",
+            context: "refreshing sign-in session",
         });
     }
     /** Sign out — revoke the session server-side (`POST …/session/revoke`). Idempotent. */
@@ -136,7 +224,7 @@ export class OperatorSession {
         return this.client.request("/agent/v1/control-plane/session/revoke", {
             method: "POST",
             ...authFor(opts),
-            context: "revoking control-plane session",
+            context: "revoking sign-in session",
         });
     }
     // ── passkey enrollment (bearer + step-up, enforced by the gateway) ──
@@ -249,11 +337,11 @@ export class OperatorSession {
 /**
  * Build the auth half of a request: explicit `Authorization: Bearer <token>`
  * (and `withAuth: false`) when a token is passed, else fall through to the
- * credential provider (`withAuth` defaults true). Mirrors {@link Operator.overview}.
+ * credential provider (`withAuth` defaults true).
  */
 function authFor(opts) {
     return opts.token
         ? { headers: { Authorization: `Bearer ${opts.token}` }, withAuth: false }
         : {};
 }
-//# sourceMappingURL=operator-session.js.map
+//# sourceMappingURL=session.js.map

package/dist/namespaces/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/namespaces/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAwEtD,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,uBAAuB;IACvB,WAAW;IACX,eAAe;IACf,eAAe;CAChB,CAAC,CAAC;AAuFH,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C,8CAA8C;IAE9C;;;;;OAKG;IACH,oBAAoB,CAAC,MAA0B;QAC7C,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC;YAC5B,YAAY,EAAE,MAAM,CAAC,WAAW;YAChC,cAAc,EAAE,MAAM,CAAC,aAAa;YACpC,qBAAqB,EAAE,MAAM;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,yCAAyC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;IACvF,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,gBAAgB,CAAC,MAAwB;QAC7C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,mCAAmC,EAAE;YACnF,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,aAAa,EAAE,MAAM,CAAC,YAAY;gBAClC,YAAY,EAAE,MAAM,CAAC,WAAW;gBAChC,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB;YACD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,mCAAmC;SAC7C,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAkB,oCAAoC,EAAE;YAChF,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE;YACR,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,+BAA+B;SACzC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,UAAkB;QACjC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,0CAA0C,CAAC;QAC7E,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;gBACjC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;aAClD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,YAAY,CACpB,6CAA8C,GAAa,CAAC,OAAO,EAAE,EACrE,GAAG,EACH,sBAAsB,CACvB,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAmC,CAAC;QACpF,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,2BAA2B,KAAK,QAAQ,EAAE,CAAC;YAC3E,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,IAAsC,EAAE,CAAC;QAC/E,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,IAAI,KAAK,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO,EAAE,IAAI,EAAE,KAAsD,EAAE,CAAC;QAC1E,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,0CAA0C,GAAG,CAAC,MAAM,GAAG,EACvD,GAAG,CAAC,MAAM,EACV,IAAI,EACJ,sBAAsB,CACvB,CAAC;IACJ,CAAC;IAED,kFAAkF;IAElF;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,KAAwB;QAClC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,uCAAuC,EAAE;YACvF,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YAC5B,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,kCAAkC;SAC5C,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CAAC,KAAwB;QACxC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,8CAA8C,EAAE;YAC9F,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YAC5B,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,oCAAoC;SAC9C,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,KAAwB;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAwB,iDAAiD,EAAE;YACnG,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YAC5B,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,gDAAgD;SAC1D,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,aAAa,CAAC,KAA2C;QAC7D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,gDAAgD,EAAE;YAChG,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;YACtD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,uCAAuC;SACjD,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAmC;QAC1C,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,iCAAiC,kBAAkB,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACrG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,mBAAmB,CAAC,KAAuB;QAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAwB,0CAA0C,EAAE;YAC5F,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;YAC1B,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,uCAAuC;SACjD,CAAC,CAAC;IACL,CAAC;IAED,sEAAsE;IAEtE;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,OAAyB,EAAE;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAe,kBAAkB,EAAE;YAC3D,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,2BAA2B;SACrC,CAAC,CAAC;IACL,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,OAAO,CAAC,OAAyB,EAAE;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAA4B,yCAAyC,EAAE;YAC/F,MAAM,EAAE,MAAM;YACd,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,4BAA4B;SACtC,CAAC,CAAC;IACL,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,MAAM,CAAC,OAAyB,EAAE;QACtC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAqB,wCAAwC,EAAE;YACvF,MAAM,EAAE,MAAM;YACd,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,0BAA0B;SACpC,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IAEvE,yFAAyF;IACzF,KAAK,CAAC,oBAAoB,CAAC,OAAyB,EAAE;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAwB,gDAAgD,EAAE;YAClG,MAAM,EAAE,MAAM;YACd,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,qDAAqD;SAC/D,CAAC,CAAC;IACL,CAAC;IAED,uGAAuG;IACvG,KAAK,CAAC,mBAAmB,CACvB,KAAsE;QAEtE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,+CAA+C,EAAE;YAC/F,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YAC7D,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;YACrB,OAAO,EAAE,4CAA4C;SACtD,CAAC,CAAC;IACL,CAAC;IAED,kCAAkC;IAElC;;;;OAIG;IACH,KAAK,CAAC,aAAa,CAAC,QAAiD,EAAE;QACrE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAwB,yCAAyC,EAAE;YAC3F,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;YAC1C,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;YACrB,OAAO,EAAE,0CAA0C;SACpD,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAChB,KAKoB;QAEpB,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;QACjE,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAqB,wCAAwC,EAAE;YACvF,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACJ,QAAQ;gBACR,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D;YACD,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;YACrB,OAAO,EAAE,iCAAiC;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAE1C,uEAAuE;IACvE,KAAK,CAAC,kBAAkB,CAAC,OAAyB,EAAE;QAClD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAsB,wCAAwC,EAAE;YACxF,MAAM,EAAE,MAAM;YACd,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,sCAAsC;SAChD,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAE1C,mFAAmF;IACnF,KAAK,CAAC,kBAAkB,CAAC,OAAyB,EAAE;QAClD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CACnC,wCAAwC,EACxC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CACtE,CAAC;QACF,OAAO,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,mBAAmB,CAAC,KAAwC;QAChE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CACxB,0CAA0C,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAClE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAC7F,CAAC;IACJ,CAAC;IAED,kEAAkE;IAElE;;;;;;OAMG;IACH,KAAK,CAAC,oBAAoB,CAAC,OAAyB,EAAE;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAA6B,kCAAkC,EAAE;YACzF,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,gCAAgC;SAC1C,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,0BAA0B,CAAC,OAAyB,EAAE;QAC1D,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAmC,yCAAyC,EAAE;YACtG,GAAG,OAAO,CAAC,IAAI,CAAC;YAChB,OAAO,EAAE,yCAAyC;SACnD,CAAC,CAAC;IACL,CAAC;CACF;AA6CD;;;;GAIG;AACH,SAAS,OAAO,CAAC,IAAsB;IACrC,OAAO,IAAI,CAAC,KAAK;QACf,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE;QACzE,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/namespaces/subdomains.d.ts

@@ -1,7 +1,7 @@
 /**
  * `subdomains` namespace — `*.run402.com` subdomain claims pointing at
  * deployments or releases (defaulting to the project's live release).
- * `claim` and `delete` accept an optional `projectId` for ownership
+ * `add` and `delete` accept an optional `projectId` for ownership
  * tracking; `list` requires one.
  */
 import type { Client } from "../kernel.js";
@@ -9,7 +9,7 @@ export interface SubdomainClaimOptions {
     /** Optional project ID. If omitted, falls back to the active project (set with `r.projects.use(id)`). The SDK sends the project's service key as bearer auth. */
     projectId?: string;
 }
-export interface SubdomainClaimInput extends SubdomainClaimOptions {
+export interface SubdomainAddInput extends SubdomainClaimOptions {
     name: string;
     /**
      * Target to bind: a legacy `dpl_…` deployment id, or a `rel_…` / `op_…`
@@ -20,7 +20,7 @@ export interface SubdomainClaimInput extends SubdomainClaimOptions {
     /** A `rel_…` release id to bind. Omit both this and `deploymentId` to bind the project's live release. */
     releaseId?: string;
 }
-export interface SubdomainClaimResult {
+export interface SubdomainAddResult {
     name: string;
     deployment_id: string;
     url: string;
@@ -54,10 +54,10 @@ export declare class Subdomains {
      * the gateway resolves it, and answers 404 only when the project has no
      * live release with a site.
      */
-    claim(input: SubdomainClaimInput): Promise<SubdomainClaimResult>;
+    add(input: SubdomainAddInput): Promise<SubdomainAddResult>;
     /** Release a subdomain. */
     delete(name: string, opts?: SubdomainClaimOptions): Promise<SubdomainDeleteResult>;
-    /** List all subdomains claimed by a project. */
+    /** List a project's subdomains. */
     list(projectId: string): Promise<SubdomainSummary[]>;
 }
 //# sourceMappingURL=subdomains.d.ts.map

package/dist/namespaces/subdomains.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subdomains.d.ts","sourceRoot":"","sources":["../../src/namespaces/subdomains.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,MAAM,WAAW,qBAAqB;IACpC,iKAAiK;IACjK,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,UAAU;;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAkB3C;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmBtE,2BAA2B;IACrB,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IAcjC,gDAAgD;IAC1C,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAc3D"}
+{"version":3,"file":"subdomains.d.ts","sourceRoot":"","sources":["../../src/namespaces/subdomains.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,MAAM,WAAW,qBAAqB;IACpC,iKAAiK;IACjK,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,UAAU;;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAkB3C;;;;;OAKG;IACG,GAAG,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmBhE,2BAA2B;IACrB,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,qBAAqB,CAAC;IAcjC,mCAAmC;IAC7B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAc3D"}

package/dist/namespaces/subdomains.js

@@ -1,7 +1,7 @@
 /**
  * `subdomains` namespace — `*.run402.com` subdomain claims pointing at
  * deployments or releases (defaulting to the project's live release).
- * `claim` and `delete` accept an optional `projectId` for ownership
+ * `add` and `delete` accept an optional `projectId` for ownership
  * tracking; `list` requires one.
  */
 import { LocalError } from "../errors.js";
@@ -28,11 +28,11 @@ export class Subdomains {
      * the gateway resolves it, and answers 404 only when the project has no
      * live release with a site.
      */
-    async claim(input) {
+    async add(input) {
         const name = input.name;
         const options = { projectId: input.projectId };
-        const projectId = await this.#resolveProjectId(options, "claiming subdomain");
-        const project = await requireProjectCredentials(this.client, projectId, "claiming subdomain");
+        const projectId = await this.#resolveProjectId(options, "adding subdomain");
+        const project = await requireProjectCredentials(this.client, projectId, "adding subdomain");
         return this.client.request("/subdomains/v1", {
             method: "POST",
             headers: { Authorization: `Bearer ${project.service_key}` },
@@ -41,7 +41,7 @@ export class Subdomains {
                 ...(input.deploymentId ? { deployment_id: input.deploymentId } : {}),
                 ...(input.releaseId ? { release_id: input.releaseId } : {}),
             },
-            context: "claiming subdomain",
+            context: "adding subdomain",
         });
     }
     /** Release a subdomain. */
@@ -54,7 +54,7 @@ export class Subdomains {
             context: "deleting subdomain",
         });
     }
-    /** List all subdomains claimed by a project. */
+    /** List a project's subdomains. */
     async list(projectId) {
         const project = await requireProjectCredentials(this.client, projectId, "listing subdomains");
         // Gateway responds `{ subdomains: [...] }`; unwrap so callers get the

package/dist/namespaces/subdomains.js.map

@@ -1 +1 @@
-{"version":3,"file":"subdomains.js","sourceRoot":"","sources":["../../src/namespaces/subdomains.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subdomains.js","sourceRoot":"","sources":["../../src/namespaces/subdomains.ts"],"names":[],"mappings":"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"}

package/dist/namespaces/tier.d.ts

@@ -1,6 +1,6 @@
 /**
- * `tier` namespace — tier subscription / renewal / upgrade against
- * `/tiers/v1*`. Requires allowance SIWX auth; `set` flows through x402
+ * `tier` namespace — set (start / renew / upgrade) the organization's tier
+ * lease against `/tiers/v1*`. Requires wallet SIWX auth; `set` flows through x402
  * for the actual payment.
  */
 import type { Client } from "../kernel.js";
@@ -55,7 +55,7 @@ export interface TierStatusProject {
  * v1.59 (add-project-transfer): summary of a pending transfer OFFERED TO the
  * authenticated wallet. Exposed at the top level of `TierStatusResult` so the
  * inbox is visible without a separate API call. Each entry carries
- * `preview_path` for deep-linking into `GET /agent/v1/transfers/<id>`.
+ * `preview_path` for deep-linking into `GET /agent/v1/transfers/<transfer_id>`.
  */
 export interface TierStatusIncomingTransfer {
     transfer_id: string;
@@ -81,17 +81,33 @@ export interface TierStatusResult {
      */
     organization_lifecycle_state: "active" | "past_due" | "frozen" | "dormant" | "purged" | null;
     /**
-     * Operator escape hatch flag on the owning organization. When `true`,
+     * Staff escape hatch flag on the owning organization. When `true`,
      * the organization never advances past `active` regardless of lease expiry.
      * `null` only for orphan wallets with no organization row.
      */
     lease_perpetual: boolean | null;
+    /**
+     * Organization-pooled usage against the tier limits. Every byte count sits
+     * beside its human string under the same name with `_bytes` removed
+     * (`storage_bytes_limit: 250000000` + `storage_limit: "250 MB"`); quotas are
+     * decimal, derived from the tier constant.
+     */
     pool_usage: {
         projects: number;
         total_api_calls: number;
+        /** Project bytes PLUS `gitvault_source_bytes` — what the storage limit applies to. */
         total_storage_bytes: number;
+        total_storage: string;
+        /** The vault half of `total_storage_bytes`, compared against `source_bytes_limit`. */
+        gitvault_source_bytes: number;
+        gitvault_source: string;
         api_calls_limit: number;
         storage_bytes_limit: number;
+        storage_limit: string;
+        /** The vault pool's own limit, separate from `storage_bytes_limit`. */
+        source_bytes_limit: number;
+        source_limit: string;
+        [key: string]: unknown;
     };
     /**
      * Per-project summary across all projects on the wallet's organization.
@@ -116,14 +132,14 @@ export interface TierStatusResult {
     };
     /**
      * Org-level advisories (recovery-event-reachability). Present only when at
-     * least one applies; absent on older gateways. `operator_unreachable`
+     * least one applies; absent on older gateways. `owner_unreachable`
      * means the owning organization resolves to ZERO verified notification
      * recipients — mandatory recovery/security events currently reach nobody —
      * with the registration remedy carried in `next_actions[]`
-     * (`POST /agent/v1/contact`).
+     * (`register_contact`, `POST /agent/v1/contact`).
      */
     advisories?: Array<{
-        type: "operator_unreachable" | (string & {});
+        type: "owner_unreachable" | "contact_email_stale" | (string & {});
         summary: string;
         next_actions: Array<{
             type: string;
@@ -133,30 +149,37 @@ export interface TierStatusResult {
         }>;
     }>;
 }
+/**
+ * What `set` did: `start` begins a lease (or activates the free prototype
+ * tier), `renew` extends the same tier from its current expiry, `upgrade`
+ * moves to a higher tier with a prorated refund to the allowance. The open
+ * tail keeps a future action the gateway may report (a downgrade it accepts)
+ * from being a type error.
+ */
+export type TierSetAction = "start" | "renew" | "upgrade" | (string & {});
 export interface TierSetResult {
     wallet: string;
-    action: string;
+    action: TierSetAction;
     tier: string;
     previous_tier: string | null;
     lease_started_at: string;
     lease_expires_at: string;
+    /** The organization's allowance after this purchase. */
     allowance_remaining_usd_micros: number;
     /**
-     * What settled the purchase. `credit` means the organization's prepaid
-     * balance paid, ahead of the paywall: no 402, no signed authorization, and
-     * no USDC needed in the wallet. Absent on gateways older than 2026-09-20.
+     * What settled the purchase. `allowance` means the organization's allowance
+     * paid, ahead of the paywall: no 402, no signed authorization, and no USDC
+     * needed in the wallet.
      */
-    paid_with?: "credit" | "x402" | "mpp";
-    /** Prepaid credit consumed by this purchase (0 unless `paid_with` is `credit`). */
-    credit_used_usd_micros?: number;
-    /** The organization's prepaid credit after this purchase. */
-    credit_remaining_usd_micros?: number;
+    paid_with?: "allowance" | "x402" | "mpp";
+    /** Allowance consumed by this purchase (0 unless `paid_with` is `allowance`). */
+    allowance_used_usd_micros?: number;
 }
 export interface TierSetOptions {
     /**
      * Idempotency key for safe retries (durable-side-effects doctrine). When set,
      * the SDK sends it as the `Idempotency-Key` header so retrying the same
-     * subscribe/renew intent does not double-charge. The key is caller-supplied:
+     * start/renew intent does not double-charge. The key is caller-supplied:
      * it represents one payment intent, a boundary only the caller knows (a
      * deliberate second renewal must use a fresh key). The SDK does not
      * auto-derive one — that cannot distinguish a retry from a new renewal.
@@ -166,12 +189,12 @@ export interface TierSetOptions {
 export declare class Tier {
     private readonly client;
     constructor(client: Client);
-    /** Check current tier subscription — tier name, status, and expiry. */
+    /** Check the organization's current tier — tier name, status, and lease expiry. */
     status(): Promise<TierStatusResult>;
     /**
-     * Subscribe, renew, or upgrade a tier. Auto-detects the action based on
-     * allowance state. Payment flows through the injected fetch (x402 in
-     * Node with an allowance). Throws {@link PaymentRequired} when the
+     * Set the organization's tier: start, renew, or upgrade the lease. The
+     * gateway auto-detects the action from the current tier state. Payment flows through the injected fetch (x402 in
+     * Node with a wallet). Throws {@link PaymentRequired} when the
      * wrapper cannot fund the call.
      */
     set(tier: TierName, opts?: TierSetOptions): Promise<TierSetResult>;

package/dist/namespaces/tier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tier.d.ts","sourceRoot":"","sources":["../../src/namespaces/tier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,SAAS,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,4BAA4B,EACxB,QAAQ,GACR,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,IAAI,CAAC;IACT;;;;OAIG;IACH,eAAe,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAClD;+EAC2E;IAC3E,eAAe,CAAC,EAAE,kBAAkB,CAAC;IACrC,6EAA6E;IAC7E,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,kBAAkB,CAAC;QAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,sBAAsB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACrF,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,8BAA8B,EAAE,MAAM,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IACtC,mFAAmF;IACnF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,IAAI;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C,uEAAuE;IACjE,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAMzC;;;;;OAKG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;CAU7E"}
+{"version":3,"file":"tier.d.ts","sourceRoot":"","sources":["../../src/namespaces/tier.ts"],"names":[],"mappings":"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"}

package/dist/namespaces/tier.js

@@ -1,6 +1,6 @@
 /**
- * `tier` namespace — tier subscription / renewal / upgrade against
- * `/tiers/v1*`. Requires allowance SIWX auth; `set` flows through x402
+ * `tier` namespace — set (start / renew / upgrade) the organization's tier
+ * lease against `/tiers/v1*`. Requires wallet SIWX auth; `set` flows through x402
  * for the actual payment.
  */
 export class Tier {
@@ -8,23 +8,23 @@ export class Tier {
     constructor(client) {
         this.client = client;
     }
-    /** Check current tier subscription — tier name, status, and expiry. */
+    /** Check the organization's current tier — tier name, status, and lease expiry. */
     async status() {
         return this.client.request("/tiers/v1/status", {
             context: "checking tier status",
         });
     }
     /**
-     * Subscribe, renew, or upgrade a tier. Auto-detects the action based on
-     * allowance state. Payment flows through the injected fetch (x402 in
-     * Node with an allowance). Throws {@link PaymentRequired} when the
+     * Set the organization's tier: start, renew, or upgrade the lease. The
+     * gateway auto-detects the action from the current tier state. Payment flows through the injected fetch (x402 in
+     * Node with a wallet). Throws {@link PaymentRequired} when the
      * wrapper cannot fund the call.
      */
     async set(tier, opts = {}) {
         return this.client.request(`/tiers/v1/${tier}`, {
             method: "POST",
             body: {},
-            // Retry-safety: a caller-supplied key collapses a retried subscribe/renew
+            // Retry-safety: a caller-supplied key collapses a retried start/renew
             // onto one charge. Omitted by default — tier renewal is not auto-keyed.
             ...(opts.idempotencyKey ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : {}),
             context: "setting tier",

package/dist/namespaces/tier.js.map

@@ -1 +1 @@
-{"version":3,"file":"tier.js","sourceRoot":"","sources":["../../src/namespaces/tier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2KH,MAAM,OAAO,IAAI;IACc;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C,uEAAuE;IACvE,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAmB,kBAAkB,EAAE;YAC/D,OAAO,EAAE,sBAAsB;SAChC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAC,IAAc,EAAE,OAAuB,EAAE;QACjD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAgB,aAAa,IAAI,EAAE,EAAE;YAC7D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE;YACR,0EAA0E;YAC1E,wEAAwE;YACxE,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,OAAO,EAAE,cAAc;SACxB,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"tier.js","sourceRoot":"","sources":["../../src/namespaces/tier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmMH,MAAM,OAAO,IAAI;IACc;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C,mFAAmF;IACnF,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAmB,kBAAkB,EAAE;YAC/D,OAAO,EAAE,sBAAsB;SAChC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAC,IAAc,EAAE,OAAuB,EAAE;QACjD,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAgB,aAAa,IAAI,EAAE,EAAE;YAC7D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,EAAE;YACR,sEAAsE;YACtE,wEAAwE;YACxE,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvF,OAAO,EAAE,cAAc;SACxB,CAAC,CAAC;IACL,CAAC;CACF"}