@run402/sdk 4.97.0 → 4.98.0

package/dist/node/lightning-wallet.js

@@ -0,0 +1,126 @@
+/**
+ * The agent's Lightning wallet on the local machine: mint the budgeted wallet
+ * on Run402's Hub, keep its pairing in the active profile's `wallet.json`
+ * beside the Base key, report its balance, revoke it. Shared by `r.init`
+ * (`run402 init lightning`) and `run402 wallets lightning …`. The pairing
+ * secret is never returned by anything here.
+ */
+import { readWallet, saveWallet } from "../../core-dist/wallet.js";
+import { LocalError } from "../errors.js";
+export const LIGHTNING_MINT_TIMEOUT_MS = 45_000;
+/** Public facts only: never the pairing. */
+export function describeLightning(localWallet, wallet = null, balance = null) {
+    const local = localWallet?.lightning ?? null;
+    if (!local && !wallet)
+        return null;
+    return {
+        wallet_id: wallet?.wallet_id ?? local?.wallet_id ?? null,
+        status: wallet?.status ?? (local ? "active" : null),
+        custody: "run402_hub",
+        custody_note: "The sats sit on Run402's Lightning Hub; this wallet is a budgeted connection to them, not self-custody.",
+        lightning_address: wallet?.lightning_address ?? local?.lightning_address ?? null,
+        budget_sats: wallet?.budget_sats ?? local?.budget_sats ?? null,
+        starter_sats: wallet?.starter_sats ?? local?.starter_sats ?? null,
+        has_pairing: Boolean(local?.nwc),
+        minted_at: local?.minted_at ?? wallet?.activated_at ?? null,
+        ...(balance ? balance : {}),
+    };
+}
+/** Balance and remaining budget over NWC, best-effort (null on any failure). */
+export async function readLightningBalance(localWallet) {
+    const nwc = localWallet?.lightning?.nwc;
+    if (!nwc)
+        return null;
+    try {
+        const { NwcWallet, closeNwcConnections } = await import("./nwc.js");
+        const wallet = new NwcWallet(nwc, { timeoutMs: 15_000 });
+        const [balance_sats, budget] = await Promise.all([wallet.getBalanceSats(), wallet.getBudgetSats().catch(() => null)]);
+        closeNwcConnections();
+        return {
+            balance_sats,
+            budget_remaining_sats: budget && budget.totalSats !== null ? budget.totalSats - budget.usedSats : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function storePairing(localWallet, wallet) {
+    const next = {
+        ...localWallet,
+        rail: "lightning",
+        lightning: {
+            wallet_id: wallet.wallet_id,
+            nwc: wallet.pairing,
+            lightning_address: wallet.lightning_address ?? null,
+            budget_sats: wallet.budget_sats,
+            starter_sats: wallet.starter_sats,
+            custody: "run402_hub",
+            minted_at: wallet.activated_at ?? new Date().toISOString(),
+        },
+    };
+    saveWallet(next);
+    return next;
+}
+/**
+ * Ensure the active profile holds an active Lightning wallet. `outcome` is
+ * `stored` (pairing just saved), `present` (already held locally), `minting`
+ * (the platform is still minting; rerun later), `unavailable` (no Hub on this
+ * gateway), `pairing_lost` (active, but its one-time pairing went to another
+ * machine: revoke and mint again), or the wallet's own non-active status.
+ */
+export async function ensureLightningWallet(agent, options = {}) {
+    let localWallet = readWallet();
+    if (!localWallet) {
+        throw new LocalError("no local wallet configured; run `run402 init` first", "ensuring the Lightning wallet", { code: "LIGHTNING_WALLET_FAILED" });
+    }
+    if (localWallet.lightning?.nwc) {
+        let wallet = null;
+        try {
+            wallet = await agent.lightningWallet.get();
+        }
+        catch { /* an offline read is fine */ }
+        if (wallet && wallet.status !== "active")
+            return { localWallet, wallet, outcome: wallet.status };
+        return { localWallet, wallet, outcome: "present" };
+    }
+    let wallet;
+    try {
+        wallet = await agent.lightningWallet.mint({ timeoutMs: options.timeoutMs ?? LIGHTNING_MINT_TIMEOUT_MS });
+    }
+    catch (err) {
+        const code = err?.body?.code ?? err?.code;
+        if (code === "LIGHTNING_WALLET_NOT_AVAILABLE")
+            return { localWallet, wallet: null, outcome: "unavailable", error: err };
+        if (code === "LIGHTNING_WALLET_STILL_MINTING")
+            return { localWallet, wallet: null, outcome: "minting", error: err };
+        throw err;
+    }
+    if (wallet.status === "minting")
+        return { localWallet, wallet, outcome: "minting" };
+    if (wallet.status !== "active")
+        return { localWallet, wallet, outcome: wallet.status };
+    if (typeof wallet.pairing !== "string")
+        return { localWallet, wallet, outcome: "pairing_lost" };
+    localWallet = storePairing(localWallet, wallet);
+    return { localWallet, wallet, outcome: "stored" };
+}
+/** Revoke on the platform and forget the pairing locally; the rail returns to x402. */
+export async function revokeLightningWallet(agent) {
+    const localWallet = readWallet();
+    let wallet = null;
+    try {
+        wallet = await agent.lightningWallet.revoke();
+    }
+    catch (err) {
+        const code = err?.body?.code ?? err?.code;
+        if (code !== "LIGHTNING_WALLET_NOT_FOUND")
+            throw err;
+    }
+    if (localWallet) {
+        const { lightning: _dropped, ...rest } = localWallet;
+        saveWallet({ ...rest, rail: rest.rail === "lightning" ? "x402" : rest.rail });
+    }
+    return wallet;
+}
+//# sourceMappingURL=lightning-wallet.js.map

package/dist/node/lightning-wallet.js.map

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

package/dist/node/local-actions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The bootstrap `next_actions` the Node SDK's local-state verbs author
+ * (`wallets.current`, `init`, `status`, `doctor`), in the one spelling every
+ * surface prints. Each is the literal CLI invocation plus why, the same shape
+ * the gateway's `next_actions` carry extended with `command`.
+ */
+import type { NextAction } from "../errors.js";
+export declare function localAction(type: string, fields?: {
+    command?: string;
+    why?: string;
+    method?: string;
+    path?: string;
+    auth?: string;
+}): NextAction;
+export declare function initializeWalletAction(): NextAction;
+export declare function deployAction(): NextAction;
+/**
+ * The cold-start deploy when the account holds no tier yet: `run402 up -y`
+ * sets the prototype tier itself as part of the first deploy, so `init`
+ * hands the agent ONE command instead of `tier set` + a separate deploy.
+ */
+export declare function upDeployAction(): NextAction;
+//# sourceMappingURL=local-actions.d.ts.map

package/dist/node/local-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-actions.d.ts","sourceRoot":"","sources":["../../src/node/local-actions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAMpJ;AAED,wBAAgB,sBAAsB,IAAI,UAAU,CAKnD;AAED,wBAAgB,YAAY,IAAI,UAAU,CAKzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAK3C"}

package/dist/node/local-actions.js

@@ -0,0 +1,38 @@
+/**
+ * The bootstrap `next_actions` the Node SDK's local-state verbs author
+ * (`wallets.current`, `init`, `status`, `doctor`), in the one spelling every
+ * surface prints. Each is the literal CLI invocation plus why, the same shape
+ * the gateway's `next_actions` carry extended with `command`.
+ */
+export function localAction(type, fields = {}) {
+    const action = { type };
+    for (const key of ["command", "method", "path", "auth", "why"]) {
+        if (fields[key] !== undefined)
+            action[key] = fields[key];
+    }
+    return action;
+}
+export function initializeWalletAction() {
+    return localAction("initialize_wallet", {
+        command: "run402 init",
+        why: "Create and fund a local wallet, then retry.",
+    });
+}
+export function deployAction() {
+    return localAction("deploy", {
+        command: "run402 deploy --manifest app.json",
+        why: "Deploy your release manifest.",
+    });
+}
+/**
+ * The cold-start deploy when the account holds no tier yet: `run402 up -y`
+ * sets the prototype tier itself as part of the first deploy, so `init`
+ * hands the agent ONE command instead of `tier set` + a separate deploy.
+ */
+export function upDeployAction() {
+    return localAction("deploy", {
+        command: "run402 up -y",
+        why: "Deploy with run402 up -y — it sets the prototype tier (free on testnet) as part of the first deploy. Or set it separately: run402 tier set prototype.",
+    });
+}
+//# sourceMappingURL=local-actions.js.map

package/dist/node/local-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-actions.js","sourceRoot":"","sources":["../../src/node/local-actions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAA4F,EAAE;IACtI,MAAM,MAAM,GAAe,EAAE,IAAI,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAU,EAAE,CAAC;QACxE,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,WAAW,CAAC,mBAAmB,EAAE;QACtC,OAAO,EAAE,aAAa;QACtB,GAAG,EAAE,6CAA6C;KACnD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,WAAW,CAAC,QAAQ,EAAE;QAC3B,OAAO,EAAE,mCAAmC;QAC5C,GAAG,EAAE,+BAA+B;KACrC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,QAAQ,EAAE;QAC3B,OAAO,EAAE,cAAc;QACvB,GAAG,EAAE,uJAAuJ;KAC7J,CAAC,CAAC;AACL,CAAC"}

package/dist/node/org-context.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Organization context, owned by the Node SDK: the ONE resolver every
+ * org-scoped command consumes, and the verbs that select, report, and bind
+ * the current organization.
+ *
+ * The org is the ownership root — it owns projects, holds memberships, and is
+ * the scope for rooms, escalations, members, grants, and audit. Precedence is
+ * four INTENT CLASSES, highest first, and inside each class an organization
+ * named directly outranks one derived from a project named in that same class:
+ *
+ *   1. flag          `org` (--org)                 else `project` (--project) -> its org
+ *   2. environment   RUN402_ORG, else the org half else RUN402_PROJECT_ID -> its org
+ *                    of RUN402_ROOM
+ *   3. binding       the `org` key of the nearest .run402(.local).json
+ *   3.5 vault pin    `r402.orgId` in this checkout's local git config
+ *   4. profile state the profile's selected org else its active project -> org
+ *
+ * Naming a project IS naming its organization, so a stale profile selection
+ * never outranks it; classes 3 and 4 are what let an org that owns no project
+ * be addressed at all.
+ *
+ * Two things this deliberately does NOT do:
+ * - Infer the org from the caller's memberships, at any count: membership is
+ *   server state that changes without the caller acting.
+ * - Validate membership locally: a well-formed id goes to the server and the
+ *   server's answer is surfaced as returned, never retried against a lower
+ *   class and never rewritten into a local not-found.
+ */
+import { LocalError, type NextAction } from "../errors.js";
+import type { Client } from "../kernel.js";
+import { Orgs } from "../namespaces/org.js";
+import { Rooms } from "../namespaces/rooms.js";
+import { Projects } from "../namespaces/projects.js";
+export declare const ORG_ENV = "RUN402_ORG";
+export declare const ROOM_ENV = "RUN402_ROOM";
+export declare const PROJECT_ENV = "RUN402_PROJECT_ID";
+/** `org_id` is a UUID at every API boundary. */
+export declare const ORG_ID_RE: RegExp;
+export type OrgSource = "flag" | "env" | "binding" | "vault_pin" | "profile";
+export interface ResolvedOrg {
+    orgId: string;
+    source: OrgSource;
+    sourceDetail: string;
+}
+export interface ResolveOrgInput {
+    /** The org named directly (the `--org` flag). */
+    org?: string | null;
+    /** A project named directly (the `--project` flag); its owning org decides. */
+    project?: string | null;
+}
+export interface ResolveOrgOptions {
+    env?: Record<string, string | undefined>;
+    /** Directory the binding walk starts from. Default `process.cwd()`. */
+    cwd?: string;
+    /** Return null instead of throwing `ORG_REQUIRED` when nothing supplies an org. */
+    optional?: boolean;
+    /** Skip the env-vs-binding `AMBIGUOUS_ORG` error (surfaces that must stay usable while ambiguous). */
+    allowConflict?: boolean;
+}
+export interface OrgProvenance {
+    org_id: string | null;
+    org_source: OrgSource | null;
+    org_source_detail: string | null;
+}
+export interface CurrentOrgResult extends OrgProvenance {
+    selected_org_id: string | null;
+}
+export interface OrgBindResult {
+    org_id: string;
+    room_key: string | null;
+    org_source: "flag" | "sole_membership";
+    file: ".run402.json";
+    path: string;
+    bound: true;
+    safe_to_commit: true;
+    note: string;
+    binding: Record<string, unknown> | null;
+}
+export interface OrgUnbindResult {
+    file: ".run402.json";
+    unbound: boolean;
+    removed: boolean;
+    binding: Record<string, unknown> | null;
+}
+export declare function listOrgsAction(): NextAction;
+/** The recovery actions an `ORG_REQUIRED` refusal carries: every way to supply an org. */
+export declare function orgRequiredActions(): NextAction[];
+/**
+ * Shape-validate an organization id from a local source. Never checks
+ * membership. A rejected value may be a pasted secret, so it is redacted.
+ */
+export declare function assertOrgIdShape(orgId: string, origin: string): string;
+/** The `ORG_REQUIRED` refusal, optionally naming a rejected positional. */
+export declare function orgRequiredError(opts?: {
+    rejectedPositional?: string;
+    positionalHint?: boolean;
+}): LocalError;
+/** Provenance triple for command output: bounded, never a resolution trace. */
+export declare function orgProvenance(resolved: ResolvedOrg | null): OrgProvenance;
+/**
+ * `r.orgs` on the Node entry: the isomorphic org collection and identity
+ * verbs plus the local organization context.
+ */
+export declare class NodeOrgs extends Orgs {
+    #private;
+    /**
+     * @param namespaces the reads the resolver makes (a project's org, the
+     *   project listing); default to fresh namespaces on `client`.
+     */
+    constructor(client: Client, namespaces?: {
+        rooms?: Pick<Rooms, "forProject">;
+        projects?: Pick<Projects, "list">;
+    });
+    /**
+     * The one resolver. Returns the org with its provenance, or null when
+     * `optional` and nothing supplies one; throws `BAD_ORG_ID`, `AMBIGUOUS_ORG`,
+     * or `ORG_REQUIRED` (each with its recovery actions) otherwise.
+     */
+    resolve(input?: ResolveOrgInput, opts?: ResolveOrgOptions): Promise<ResolvedOrg | null>;
+    /** Select the current organization for the active wallet profile (`orgs use`). */
+    use(orgId: string): Promise<{
+        org_id: string;
+        selected: true;
+        scope: "wallet_profile";
+    }>;
+    /**
+     * The organization this directory and profile resolve to, with provenance,
+     * beside the profile's own selection. An empty selection is an explicit
+     * null state. Never fails on ambiguity: the command that reports the
+     * selection stays usable while it is ambiguous.
+     */
+    current(opts?: Pick<ResolveOrgOptions, "env" | "cwd">): Promise<CurrentOrgResult>;
+    /** The profile's selected organization, without running the chain. */
+    selected(): string | null;
+    /** Clear the profile's selected organization. */
+    clear(): Promise<{
+        org_id: null;
+        selected: false;
+        previous_org_id: string | null;
+    }>;
+    /**
+     * Write this checkout's org (and room) into `.run402.json`. With no org, the
+     * caller's sole membership is used and written down: an explicit, recorded
+     * act, unlike the chain, which never infers. Two or more memberships refuse.
+     */
+    bind(orgId?: string | null, opts?: {
+        room?: string | null;
+        cwd?: string;
+    }): Promise<OrgBindResult>;
+    /** Remove the `org` and `room` keys from `./.run402.json`; the file goes when nothing else is left. */
+    unbind(opts?: {
+        cwd?: string;
+    }): Promise<OrgUnbindResult>;
+    /**
+     * Stamp a project's owning organization as the profile's selection
+     * (`projects use` does this: a project determines its org unambiguously).
+     * Best-effort: returns the org, or null, and never throws.
+     */
+    selectFromProject(projectId: string): Promise<string | null>;
+    /**
+     * The organization that OWNS a specific project, or null. Distinct from
+     * {@link resolve} (which org a command is addressed at): an `--org` override
+     * here would be a mis-binding. Remembered in the local project entry after
+     * the first lookup, so the vault scaffold adds no network read on a
+     * returning machine; an exact id match is required.
+     */
+    owningOrgOf(projectId: string): Promise<string | null>;
+}
+//# sourceMappingURL=org-context.d.ts.map

package/dist/node/org-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-context.d.ts","sourceRoot":"","sources":["../../src/node/org-context.ts"],"names":[],"mappings":"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"}