@agentgrant.cash/cli 1.0.0

package/dist/lib/currency.js

@@ -0,0 +1,91 @@
+/**
+ * Display-currency + experience-mode formatting — the single source of truth
+ * shared by the CLI and the MCP server.
+ *
+ * The platform stores all monetary values internally in USD. The user's profile
+ * (GET /api/user) carries their display preferences:
+ *   - currency        ISO code of their local currency (e.g. INR, AED, EUR)
+ *   - displayCurrency  'USD' (show USD) | 'local' (convert to `currency`)
+ *   - goldDisplayUnit  'oz' | 'g'
+ *   - experienceMode   'simple' (plain language, local currency) | 'advanced'
+ *
+ * The FX rate (local units per 1 USD) comes from GET /api/prices/fiat/{currency}.
+ * Conversion is a single multiply; presentation is delegated to Intl so symbols
+ * and per-currency decimal conventions (e.g. JPY has 0) are correct and we don't
+ * hand-maintain a symbol table.
+ */
+/** 1 troy ounce = 31.1034768 grams (matches the web app's GRAMS_PER_TROY_OUNCE). */
+export const GRAMS_PER_TROY_OUNCE = 31.1034768;
+/** Safe USD-only defaults — what every caller falls back to with no profile. */
+export const DEFAULT_PREFS = {
+    currency: 'USD',
+    displayCurrency: 'USD',
+    goldUnit: 'oz',
+    mode: 'simple',
+    rate: 1,
+};
+/**
+ * Build DisplayPrefs from a raw GET /api/user payload (defensively — the field
+ * may be absent on legacy rows) plus a fetched FX rate. Unknown / malformed
+ * values fall back to the safe USD defaults rather than throwing.
+ */
+export function resolveDisplayPrefs(user, rate = 1) {
+    const u = (user && typeof user === 'object' ? user : {});
+    const currency = typeof u.currency === 'string' && u.currency.trim() ? u.currency.trim().toUpperCase() : 'USD';
+    const displayCurrency = u.displayCurrency === 'local' ? 'local' : 'USD';
+    const goldUnit = u.goldDisplayUnit === 'g' ? 'g' : 'oz';
+    const mode = u.experienceMode === 'advanced' ? 'advanced' : 'simple';
+    const safeRate = typeof rate === 'number' && Number.isFinite(rate) && rate > 0 ? rate : 1;
+    return { currency, displayCurrency, goldUnit, mode, rate: safeRate };
+}
+/** True when money should be shown in the user's local currency (not USD). */
+export function usesLocalCurrency(prefs) {
+    return (prefs.displayCurrency === 'local' &&
+        !!prefs.currency &&
+        prefs.currency.toUpperCase() !== 'USD' &&
+        prefs.rate > 0);
+}
+/**
+ * Format a USD amount for display per the user's preferences. Converts to the
+ * local currency when configured; otherwise renders USD. Always falls back to a
+ * valid USD string if the target currency code is not recognized by Intl.
+ */
+export function formatMoney(amountUsd, prefs = DEFAULT_PREFS) {
+    const usd = Number.isFinite(amountUsd) ? amountUsd : 0;
+    const local = usesLocalCurrency(prefs);
+    const code = local ? prefs.currency.toUpperCase() : 'USD';
+    const value = local ? usd * prefs.rate : usd;
+    try {
+        return new Intl.NumberFormat('en-US', { style: 'currency', currency: code }).format(value);
+    }
+    catch {
+        // Unrecognized ISO code → never crash a balance read; show USD instead.
+        return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(usd);
+    }
+}
+/** Trim a number to at most `maxDp` decimals without trailing zeros. */
+function trim(n, maxDp) {
+    if (!Number.isFinite(n))
+        return '0';
+    return Number(n.toFixed(maxDp)).toLocaleString('en-US', { maximumFractionDigits: maxDp });
+}
+export function displayDescriptor(prefs = DEFAULT_PREFS) {
+    return {
+        currency: prefs.currency,
+        displayCurrency: prefs.displayCurrency,
+        goldUnit: prefs.goldUnit,
+        rate: prefs.rate,
+        usesLocal: usesLocalCurrency(prefs),
+    };
+}
+/**
+ * Format a gold amount (given in troy ounces) per the user's unit preference.
+ * Grams are shown with more precision than ounces since 1 oz ≈ 31 g.
+ */
+export function formatGold(ounces, prefs = DEFAULT_PREFS) {
+    const oz = Number.isFinite(ounces) ? ounces : 0;
+    if (prefs.goldUnit === 'g') {
+        return `${trim(oz * GRAMS_PER_TROY_OUNCE, 2)} g`;
+    }
+    return `${trim(oz, 4)} oz`;
+}

package/dist/lib/device.js

@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { AppError } from "./errors.js";
+const JSON_HEADERS = { "Content-Type": "application/json" };
+export async function startDevice(api, clientName, deviceName, f = fetch) {
+    const res = await f(`${api}/cli/device/start`, {
+        method: "POST",
+        headers: JSON_HEADERS,
+        body: JSON.stringify({ clientName, deviceName }),
+    });
+    const j = (await res.json().catch(() => ({})));
+    if (!res.ok || !j.success || !j.data)
+        throw new AppError(j.error || `Could not start login (HTTP ${res.status})`, {
+            status: res.status,
+        });
+    return j.data;
+}
+/**
+ * One poll tick. Resolves only on a real backend answer (HTTP 200 + success
+ * envelope) — `pending` | `denied` | `expired` | `complete`. Any transient
+ * failure (429 from the shared `/api` limiter, a 5xx, a malformed body, or a
+ * thrown fetch when the dev backend restarts) is raised as an AppError so
+ * {@link waitForDevice} can back off and retry inside the window instead of
+ * mistaking a blip for a terminal "expired" and giving up. A 429 carries
+ * `retryInMs` (from the body or the `Retry-After` header) for the backoff.
+ *
+ * This mirrors the agent side (`pollAgentDevice`/`waitForAgentDevice`); the two
+ * halves of the handshake must be equally fault-tolerant.
+ */
+export async function pollDevice(api, sid, f = fetch) {
+    let res;
+    try {
+        res = await f(`${api}/cli/device/poll`, {
+            method: "POST",
+            headers: JSON_HEADERS,
+            body: JSON.stringify({ sid }),
+        });
+    }
+    catch (e) {
+        // Network blip / dev backend mid-restart — transient, retry.
+        throw new AppError(e instanceof Error ? e.message : String(e), {
+            code: "NETWORK",
+            recoverable: true,
+        });
+    }
+    const j = (await res.json().catch(() => ({})));
+    if (res.status === 429) {
+        const retryAfter = Number(res.headers.get("retry-after"));
+        const retryInMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : undefined;
+        throw new AppError("Too many attempts — backing off.", {
+            status: 429,
+            code: "RATE_LIMITED",
+            recoverable: true,
+            details: retryInMs ? { retryInMs } : undefined,
+        });
+    }
+    // Non-2xx or a malformed/unsuccessful envelope = transient (the backend
+    // reports a genuine terminal state as 200 + success). Retry within the window.
+    if (!res.ok || !j.success || !j.data) {
+        throw new AppError(j.error || `Poll failed (HTTP ${res.status})`, {
+            status: res.status,
+            code: `HTTP_${res.status}`,
+            recoverable: true,
+        });
+    }
+    return j.data;
+}
+/**
+ * Poll until a genuine terminal status or the link expires.
+ *
+ * Never bails on a transient failure: network errors and rate-limits (honoring
+ * `retryInMs`) just back off and retry until the window closes. Only a real
+ * backend answer (`complete` / `denied` / `expired`) ends the loop early. On
+ * window exhaustion returns `{ status: "expired" }`.
+ */
+export async function waitForDevice(api, sid, intervalMs, timeoutMs, f = fetch) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const r = await pollDevice(api, sid, f);
+            if (r.status !== "pending")
+                return r;
+            await sleep(intervalMs);
+        }
+        catch (e) {
+            const err = e;
+            const retryInMs = err.details?.retryInMs ?? intervalMs;
+            // Rate-limited → wait at least the server's hint; other transients → one interval.
+            await sleep(err.code === "RATE_LIMITED" ? Math.max(intervalMs, retryInMs) : intervalMs);
+        }
+    }
+    return { status: "expired" };
+}
+function sleep(ms) {
+    return new Promise((res) => setTimeout(res, ms));
+}
+/**
+ * Resolve the money-side poll interval in MILLISECONDS.
+ *
+ * The Perfolio money backend (`cli/device/start`) reports `pollInterval` already
+ * in milliseconds (e.g. 3000) — the same contract the published @perfolio/cli
+ * consumes as-is — so it is used verbatim. This deliberately differs from the
+ * agent backend, which reports SECONDS (see {@link agentPollIntervalMs}).
+ *
+ * Multiplying this value by 1000 was the cause of the "browser connected but CLI
+ * polls forever" bug: 3000 became 3,000,000ms (~50 min), so the CLI polled once
+ * and then slept past the whole login window. Falls back to 3s.
+ */
+export function moneyPollIntervalMs(pollInterval) {
+    return typeof pollInterval === "number" && pollInterval > 0 ? pollInterval : 3000;
+}
+export async function refreshCliToken(api, refreshToken, f = fetch) {
+    const res = await f(`${api}/cli/token/refresh`, {
+        method: "POST",
+        headers: JSON_HEADERS,
+        body: JSON.stringify({ refreshToken }),
+    });
+    const j = (await res.json().catch(() => ({})));
+    if (!res.ok || !j.success || !j.data)
+        throw new AppError(j.error || "Refresh failed", { status: res.status });
+    return j.data;
+}
+/** List the devices/agents connected to this account (Bearer auth). */
+export async function listDevices(api, token, f = fetch) {
+    const res = await f(`${api}/cli/devices`, { headers: { Authorization: `Bearer ${token}` } });
+    const j = (await res.json().catch(() => ({})));
+    if (!res.ok || !j.success || !j.data)
+        throw new Error(j.error || "Could not list devices");
+    return j.data.devices;
+}
+export async function revokeDevice(api, token, deviceId, f = fetch) {
+    await f(`${api}/cli/token/revoke`, {
+        method: "POST",
+        headers: { ...JSON_HEADERS, Authorization: `Bearer ${token}` },
+        body: JSON.stringify(deviceId ? { deviceId } : {}),
+    }).catch(() => { });
+}
+/** Best-effort label for the agent/client making the connection. */
+export function detectClient(env = process.env) {
+    if (env.GRANTCASH_CLIENT)
+        return env.GRANTCASH_CLIENT;
+    if (env.CLAUDECODE || env.CLAUDE_CODE)
+        return "Claude Code";
+    if (env.CURSOR_TRACE_ID)
+        return "Cursor";
+    if (env.TERM_PROGRAM)
+        return env.TERM_PROGRAM;
+    return "Grant Cash CLI";
+}
+/** Open a URL in the user's default browser (best-effort; never throws). */
+export function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* headless — the URL is printed for manual open */
+    }
+}

package/dist/lib/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Unified error model across both backends.
+ *
+ * Carries a machine `code` and a `recoverable` flag (from the agent side's LLM
+ * playbook) plus an HTTP `status` (from the money side). `friendlyError` maps the
+ * shared connection/availability states to one plain-language line so the same
+ * 401/403/428/503 reads the same no matter which backend produced it.
+ */
+export class AppError extends Error {
+    status;
+    code;
+    recoverable;
+    details;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "AppError";
+        this.status = opts.status;
+        this.code = opts.code;
+        this.recoverable = opts.recoverable;
+        this.details = opts.details;
+    }
+}
+/** Money side returns 428 when no spending session is installed. */
+export class NoSessionError extends AppError {
+    constructor() {
+        super("No spending permission set up yet. Run `grant login` and approve the limits in your browser.", { status: 428, code: "NO_SESSION", recoverable: false });
+    }
+}
+/** No credential of the kind a command needs. */
+export class NotConnectedError extends AppError {
+    constructor(which) {
+        const msg = which === "agent"
+            ? "Not connected to your agent yet. Run `grant login`."
+            : which === "money"
+                ? "Not signed in yet. Run `grant login`."
+                : "Not connected yet. Run `grant login`.";
+        super(msg, { code: "NOT_CONNECTED", recoverable: false });
+    }
+}
+/**
+ * Plain-language override for shared connection states. Returns null when there
+ * is no special-cased message (the caller then uses the backend's own message).
+ */
+export function friendlyError(status, code) {
+    if (code === "NOT_CONNECTED" || code === "NO_SESSION")
+        return null; // already friendly
+    switch (status) {
+        case 401:
+            return "Your session expired. Run `grant login` again.";
+        case 403:
+            return "That's outside the limits you set, or the session was stopped. Nothing was charged.";
+        case 428:
+            return "No spending permission set up yet. Run `grant login` and approve the limits.";
+        case 503:
+            return "That service is briefly unavailable. Try again in a moment.";
+        default:
+            return null;
+    }
+}

package/dist/lib/format.js

@@ -0,0 +1,22 @@
+/** Display formatting. Plain money, no tickers/chains (Grant Cash house style). */
+export function money(n, currency = "USD") {
+    const symbol = currency === "USD" ? "$" : "";
+    const abs = Math.abs(n);
+    const digits = abs > 0 && abs < 100 ? 2 : 0;
+    const body = new Intl.NumberFormat("en-US", {
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+    }).format(abs);
+    return `${n < 0 ? "−" : ""}${symbol}${body}${currency === "USD" ? "" : " " + currency}`;
+}
+/** Agent-side amounts arrive as USDC minor units (1e6). */
+export function usdcMinor(minor) {
+    if (minor === undefined || minor === null)
+        return "—";
+    const n = Number(minor) / 1e6;
+    return `$${n.toFixed(n < 0.01 ? 4 : 2)}`;
+}
+export function pct(n, digits = 1) {
+    const sign = n > 0 ? "+" : n < 0 ? "−" : "";
+    return `${sign}${Math.abs(n).toFixed(digits)}%`;
+}

package/dist/lib/index.js

@@ -0,0 +1,24 @@
+export * from "./types.js";
+export * from "./config.js";
+export * from "./errors.js";
+export * from "./output.js";
+export * from "./device.js";
+export * from "./agent-device.js";
+export * from "./money-client.js";
+export * from "./agent-client.js";
+export * from "./tx-wait.js";
+export * from "./format.js";
+export * from "./currency.js";
+export * from "./portfolio-format.js";
+export * from "./context.js";
+// ── ported Perfolio money engine (full investing surface) ──
+export * from "./client.js";
+export * from "./assets.js";
+export * from "./amounts.js";
+export * from "./money-input.js";
+export * from "./kyc-status.js";
+export * from "./polygon-balance.js";
+export * from "./sign.js";
+export * from "./relay.js";
+// NOTE: ./verify.js (waitForTx for PerfolioClient) is deliberately NOT barreled
+// here — it would collide with tx-wait.js's waitForTx. Import it directly.

package/dist/lib/kyc-status.js

@@ -0,0 +1,28 @@
+/** Pure KYC status classifiers — mirror the web app's kyc-status semantics. */
+function norm(s) {
+    return typeof s === 'string' ? s.trim().toLowerCase() : '';
+}
+const APPROVED = new Set(['approved', 'verified', 'completed', 'success', 'active']);
+const REJECTED = new Set(['rejected', 'declined', 'failed', 'denied']);
+const SUBMITTED = new Set(['submitted', 'in_review', 'processing', 'pending_review', 'under_review']);
+export function isKycApproved(status) { return APPROVED.has(norm(status)); }
+export function isKycRejected(status) { return REJECTED.has(norm(status)); }
+export function isKycSubmitted(status) { return SUBMITTED.has(norm(status)); }
+export function isKycPending(status) {
+    const n = norm(status);
+    return !APPROVED.has(n) && !REJECTED.has(n) && !SUBMITTED.has(n);
+}
+/** Extract a status string from a raw value (string | {status} | {data:{status}}) and classify it. */
+export function classifyKyc(raw) {
+    let status;
+    if (typeof raw === 'string')
+        status = raw;
+    else if (raw && typeof raw === 'object') {
+        const o = raw;
+        const inner = (o.data && typeof o.data === 'object') ? o.data : o;
+        status = typeof inner.status === 'string' ? inner.status : 'unknown';
+    }
+    else
+        status = 'unknown';
+    return { status, approved: isKycApproved(status) };
+}

package/dist/lib/money-client.js

@@ -0,0 +1,157 @@
+import { AppError, NoSessionError } from "./errors.js";
+import { refreshCliToken } from "./device.js";
+/**
+ * Money side — the Perfolio backend client (gold, portfolio, cash).
+ *
+ * Bearer auth with a `pfk_` device token; transparently refreshes once on a 401
+ * using the refresh token, then persists the rotated pair via onRefresh. Kept
+ * deliberately gold-focused per the product scope; adding borrow/earn/perps
+ * endpoints later is a one-line method each.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+export class MoneyClient {
+    api;
+    fiat;
+    token;
+    refreshToken;
+    onRefresh;
+    f;
+    constructor(opts) {
+        this.api = opts.api;
+        this.fiat = opts.fiat;
+        this.token = opts.token;
+        this.refreshToken = opts.refreshToken;
+        this.onRefresh = opts.onRefresh;
+        this.f = opts.fetchImpl ?? fetch;
+    }
+    get connected() {
+        return Boolean(this.token);
+    }
+    headers(auth) {
+        const h = { "Content-Type": "application/json" };
+        if (auth && this.token)
+            h.Authorization = `Bearer ${this.token}`;
+        return h;
+    }
+    async fetchWithTimeout(url, init) {
+        const attempt = async () => {
+            const ctrl = new AbortController();
+            const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+            try {
+                return await this.f(url, { ...init, signal: ctrl.signal });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        try {
+            return await attempt();
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, 800));
+            return attempt();
+        }
+    }
+    async request(base, path, init, auth, retried = false) {
+        const res = await this.fetchWithTimeout(`${base}${path}`, {
+            ...init,
+            headers: this.headers(auth),
+        });
+        // Silent refresh: an expired pfk_ access token → rotate once and retry.
+        if (res.status === 401 &&
+            auth &&
+            !retried &&
+            this.refreshToken &&
+            this.token?.startsWith("pfk_")) {
+            try {
+                const t = await refreshCliToken(this.api, this.refreshToken, this.f);
+                this.token = t.token;
+                this.refreshToken = t.refreshToken;
+                this.onRefresh?.(t.token, t.refreshToken, t.expiresAt);
+                return this.request(base, path, init, auth, true);
+            }
+            catch {
+                /* fall through to the normal error */
+            }
+        }
+        let json = {};
+        try {
+            json = (await res.json());
+        }
+        catch {
+            /* non-JSON */
+        }
+        if (res.status === 428)
+            throw new NoSessionError();
+        if (!res.ok || json.success === false) {
+            throw new AppError(json.error || json.message || `HTTP ${res.status}`, {
+                status: res.status,
+                code: json.code ?? json.error,
+                details: json.details,
+                recoverable: res.status >= 500,
+            });
+        }
+        return json.data;
+    }
+    get(base, path, auth = true) {
+        return this.request(base, path, { method: "GET" }, auth);
+    }
+    post(base, path, body, auth = true) {
+        return this.request(base, path, { method: "POST", body: JSON.stringify(body) }, auth);
+    }
+    // ── reads ──
+    getUser() {
+        return this.get(this.api, "/user");
+    }
+    /** Portfolio summary; 'full' adds the multi-asset + perps breakdown. */
+    getPortfolio(view) {
+        const q = view === "full" ? "?view=full" : "";
+        return this.get(this.api, `/portfolio/summary${q}`);
+    }
+    getBalance() {
+        return this.get(this.api, "/balances/me");
+    }
+    getGoldPrice() {
+        return this.get(this.api, "/prices/gold", false);
+    }
+    getCryptoPrices() {
+        return this.get(this.api, "/prices/crypto", false);
+    }
+    /** Local units per 1 USD, for display-currency conversion. */
+    getFiatRate(currency) {
+        return this.get(this.api, `/prices/fiat/${encodeURIComponent(currency.toUpperCase())}`, false);
+    }
+    getTxHistory(limit = 20) {
+        return this.get(this.api, `/tx/history?limit=${limit}`);
+    }
+    getTxStatus(txHash) {
+        return this.get(this.api, `/tx/status/${txHash}`);
+    }
+    // ── gold buy / sell (session-key, agent-signed) ──
+    /** Swap cash → gold (buy) or gold → cash (sell), via the DeFi session. */
+    swap(b) {
+        return this.post(this.api, "/tx/swap", b);
+    }
+    // ── extra pools the /portfolio/summary endpoint doesn't include ──
+    // The combined `portfolio` view folds these in so a user sees their WHOLE net
+    // worth (prediction balance + open bets + staked/earn) from the terminal.
+    /** Prediction deposit-wallet address + deployed status. */
+    polymarketDepositWallet() {
+        return this.get(this.api, "/polymarket/deposit-wallet");
+    }
+    /** Open prediction positions + portfolio totals (incl. spendable cashUsd). */
+    polymarketPositions() {
+        return this.get(this.api, "/polymarket/positions");
+    }
+    /** The user's earn (vault) position for an asset symbol. */
+    getEarnPosition(asset) {
+        return this.get(this.api, `/protocol/vault-position?asset=${encodeURIComponent(asset)}`);
+    }
+    // ── fiat / account (money side) ──
+    kycStatus() {
+        return this.get(this.fiat, "/kyc/status");
+    }
+    getAccounts() {
+        return this.get(this.fiat, "/accounts");
+    }
+}