bsv-pay-cli 0.2.0

package/dist/commands/watch.d.ts

@@ -0,0 +1,10 @@
+import type { ChainProvider } from '../chain/provider.js';
+import type { Ctx } from '../context.js';
+export interface WatchOptions {
+    interval?: string;
+}
+/**
+ * Poll all tracked addresses; emit one event per incoming payment (pending at
+ * 0-conf, then a confirmation event). `maxCycles` exists for tests.
+ */
+export declare function cmdWatch(ctx: Ctx, opts: WatchOptions, provider?: ChainProvider, maxCycles?: number): Promise<void>;

package/dist/commands/watch.js

@@ -0,0 +1,163 @@
+import chalk from 'chalk';
+import { WhatsOnChainProvider } from '../chain/whatsonchain.js';
+import { usageError } from '../errors.js';
+import { appendLedger, readLedger, trackedAddressesFromLedger } from '../ledger.js';
+import { formatSats } from '../units.js';
+import { brc100ReceiveNotSupported } from '../wallet/brc100.js';
+import { readWalletFile } from '../wallet/wallet.js';
+import { explorerTxUrl } from './send.js';
+const MIN_INTERVAL_SECS = 5;
+const MAX_BACKOFF_MULTIPLIER = 8;
+function interruptibleSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const t = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(t);
+            resolve();
+        }, { once: true });
+    });
+}
+/** memo per request address, from the ledger (memos are local-only). */
+function memosByAddress(network) {
+    const map = new Map();
+    for (const e of readLedger(network)) {
+        if (e.type === 'address_issued' && e.memo)
+            map.set(e.address, e.memo);
+    }
+    return map;
+}
+function receivedTxids(network) {
+    const set = new Set();
+    for (const e of readLedger(network)) {
+        if (e.type === 'receive')
+            set.add(`${e.txid}:${e.address}`);
+    }
+    return set;
+}
+/**
+ * Poll all tracked addresses; emit one event per incoming payment (pending at
+ * 0-conf, then a confirmation event). `maxCycles` exists for tests.
+ */
+export async function cmdWatch(ctx, opts, provider, maxCycles = Infinity) {
+    const chain = provider ?? new WhatsOnChainProvider(ctx.network);
+    const file = readWalletFile(ctx.network); // exit 2 with guidance when no wallet
+    if (file.backend === 'brc100')
+        throw brc100ReceiveNotSupported();
+    let intervalSecs = ctx.config.pollIntervalSecs;
+    if (opts.interval !== undefined) {
+        const n = Number(opts.interval);
+        if (!Number.isFinite(n) || n <= 0) {
+            throw usageError('invalid_interval', `--interval must be a positive number of seconds (got "${opts.interval}").`);
+        }
+        intervalSecs = n;
+    }
+    if (intervalSecs < MIN_INTERVAL_SECS) {
+        process.stderr.write(chalk.yellow(`Interval raised to the ${MIN_INTERVAL_SECS}s floor (public API rate limits).`) +
+            '\n');
+        intervalSecs = MIN_INTERVAL_SECS;
+    }
+    // Clean Ctrl-C: abort the current sleep, then fall through to the summary.
+    const abort = new AbortController();
+    let stopping = false;
+    const onSigint = () => {
+        stopping = true;
+        abort.abort();
+    };
+    process.once('SIGINT', onSigint);
+    /** address -> txid -> confirmed? */
+    const known = new Map();
+    const alreadyLedgered = receivedTxids(ctx.network);
+    let sessionTotal = 0;
+    let baselined = false;
+    let backoff = 1;
+    ctx.out.info(chalk.bold(`Watching ${ctx.network === 'test' ? 'testnet' : 'mainnet'} wallet (every ${intervalSecs}s) — Ctrl-C to stop.`));
+    const emit = (obj, human) => {
+        ctx.out.info(human);
+        if (ctx.json)
+            process.stdout.write(JSON.stringify(obj) + '\n');
+    };
+    for (let cycle = 0; cycle < maxCycles && !stopping; cycle++) {
+        try {
+            const memos = memosByAddress(ctx.network);
+            // refresh each cycle: requests issued mid-session get watched too
+            for (const address of trackedAddressesFromLedger(ctx.network)) {
+                if (stopping)
+                    break;
+                const utxos = await chain.getUtxos(address);
+                const forAddr = known.get(address) ?? new Map();
+                known.set(address, forAddr);
+                // group this address's UTXOs by txid
+                const byTxid = new Map();
+                for (const u of utxos) {
+                    const cur = byTxid.get(u.txid) ?? { sats: 0, confirmed: false };
+                    cur.sats += u.satoshis;
+                    cur.confirmed = (u.height ?? 0) > 0;
+                    byTxid.set(u.txid, cur);
+                }
+                for (const [txid, info] of byTxid) {
+                    const prior = forAddr.get(txid);
+                    if (prior === undefined) {
+                        forAddr.set(txid, info.confirmed);
+                        if (!baselined)
+                            continue; // pre-existing funds are not session events
+                        sessionTotal += info.sats;
+                        const memo = memos.get(address);
+                        const status = info.confirmed ? 'confirmed' : 'pending';
+                        emit({
+                            event: 'payment',
+                            status,
+                            address,
+                            txid,
+                            amount_sats: info.sats,
+                            ...(memo ? { memo } : {}),
+                            session_total_sats: sessionTotal,
+                            explorer_url: explorerTxUrl(ctx.network, txid),
+                        }, `${chalk.green('+' + formatSats(info.sats))} ${status === 'pending' ? chalk.yellow('[pending]') : chalk.green('[confirmed]')}` +
+                            `${memo ? ` "${memo}"` : ''}  ${explorerTxUrl(ctx.network, txid)}  (session total ${formatSats(sessionTotal)})`);
+                        if (!alreadyLedgered.has(`${txid}:${address}`)) {
+                            appendLedger(ctx.network, {
+                                type: 'receive',
+                                txid,
+                                amount_sats: info.sats,
+                                address,
+                                memo,
+                                timestamp: new Date().toISOString(),
+                                status,
+                            });
+                            alreadyLedgered.add(`${txid}:${address}`);
+                        }
+                    }
+                    else if (prior === false && info.confirmed) {
+                        forAddr.set(txid, true);
+                        emit({
+                            event: 'confirmed',
+                            address,
+                            txid,
+                            amount_sats: info.sats,
+                            session_total_sats: sessionTotal,
+                            explorer_url: explorerTxUrl(ctx.network, txid),
+                        }, `${chalk.green('✓ confirmed')} ${formatSats(info.sats)}  ${explorerTxUrl(ctx.network, txid)}`);
+                    }
+                }
+            }
+            baselined = true;
+            backoff = 1; // healthy cycle resets any rate-limit backoff
+        }
+        catch (e) {
+            // Never crash the session on API trouble: back off and keep going.
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MULTIPLIER);
+            process.stderr.write(chalk.yellow(`watch: chain query failed (${e instanceof Error ? e.message.split('.')[0] : String(e)}); backing off to ${intervalSecs * backoff}s.`) + '\n');
+        }
+        if (cycle + 1 < maxCycles && !stopping) {
+            await interruptibleSleep(intervalSecs * backoff * 1000, abort.signal);
+        }
+    }
+    process.removeListener('SIGINT', onSigint);
+    if (ctx.json) {
+        process.stdout.write(JSON.stringify({ event: 'watch_stopped', session_total_sats: sessionTotal }) + '\n');
+    }
+    ctx.out.info('');
+    ctx.out.info(`Watch stopped. Session total received: ${formatSats(sessionTotal)}.`);
+}

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import { type Network } from './paths.js';
+export interface Config {
+    /** Default network; --testnet always wins. */
+    network: Network;
+    /** Fee rate in satoshis per kilobyte. */
+    feeRateSatsPerKb: number;
+    /** watch/request --wait poll interval, seconds (floor 5). */
+    pollIntervalSecs: number;
+    /** Per-transaction spend limit in satoshis. */
+    spendLimitSats: number;
+    /** Show fiat equivalents in human output. */
+    fiatDisplay: boolean;
+}
+export declare const DEFAULT_CONFIG: Config;
+/** Load ~/.bsv-pay/config.toml, falling back to defaults when absent. */
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import { parse as parseToml } from 'smol-toml';
+import { usageError } from './errors.js';
+import { configPath } from './paths.js';
+export const DEFAULT_CONFIG = {
+    network: 'main',
+    feeRateSatsPerKb: 50,
+    pollIntervalSecs: 10,
+    spendLimitSats: 100_000,
+    fiatDisplay: false,
+};
+function asNumber(v, key) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+        throw usageError('invalid_config', `Config key "${key}" must be a non-negative number. Fix ${configPath()}.`);
+    }
+    return v;
+}
+/** Load ~/.bsv-pay/config.toml, falling back to defaults when absent. */
+export function loadConfig() {
+    const file = configPath();
+    if (!fs.existsSync(file))
+        return { ...DEFAULT_CONFIG };
+    let doc;
+    try {
+        doc = parseToml(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        throw usageError('invalid_config', `Cannot parse ${file}: ${e instanceof Error ? e.message : String(e)}. Fix the TOML syntax or delete the file to use defaults.`);
+    }
+    const cfg = { ...DEFAULT_CONFIG };
+    if ('network' in doc) {
+        if (doc.network !== 'main' && doc.network !== 'test') {
+            throw usageError('invalid_config', `Config "network" must be "main" or "test" (got ${JSON.stringify(doc.network)}). Fix ${file}.`);
+        }
+        cfg.network = doc.network;
+    }
+    if ('fee_rate_sats_per_kb' in doc)
+        cfg.feeRateSatsPerKb = asNumber(doc.fee_rate_sats_per_kb, 'fee_rate_sats_per_kb');
+    if ('poll_interval_secs' in doc) {
+        cfg.pollIntervalSecs = Math.max(5, asNumber(doc.poll_interval_secs, 'poll_interval_secs'));
+    }
+    if ('spend_limit_sats' in doc)
+        cfg.spendLimitSats = asNumber(doc.spend_limit_sats, 'spend_limit_sats');
+    if ('fiat_display' in doc) {
+        if (typeof doc.fiat_display !== 'boolean') {
+            throw usageError('invalid_config', `Config "fiat_display" must be true or false. Fix ${file}.`);
+        }
+        cfg.fiatDisplay = doc.fiat_display;
+    }
+    return cfg;
+}

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import { type Config } from './config.js';
+import { Output } from './output.js';
+import type { Network } from './paths.js';
+export interface Ctx {
+    out: Output;
+    json: boolean;
+    network: Network;
+    config: Config;
+}
+export declare function buildCtx(opts: {
+    json?: boolean;
+    testnet?: boolean;
+}): Ctx;

package/dist/context.js

@@ -0,0 +1,12 @@
+import { loadConfig } from './config.js';
+import { Output } from './output.js';
+export function buildCtx(opts) {
+    const config = loadConfig();
+    const network = opts.testnet ? 'test' : config.network;
+    return {
+        out: new Output(Boolean(opts.json)),
+        json: Boolean(opts.json),
+        network,
+        config,
+    };
+}

package/dist/core/balance.d.ts

@@ -0,0 +1,24 @@
+import { type CoreOptions } from './context.js';
+export interface AddressBalanceResult {
+    address: string;
+    confirmedSats: number;
+    unconfirmedSats: number;
+}
+export interface BalanceResult {
+    confirmedSats: number;
+    unconfirmedSats: number;
+    addresses: AddressBalanceResult[];
+    /** BRC-100 custody (additive, M12): the external wallet reported the total. */
+    backend?: 'brc100';
+}
+/**
+ * Aggregate balance across every address the wallet has issued. Addresses
+ * come from the ledger, so no passphrase or unlock is needed (read-only
+ * commands don't unlock — see DECISIONS.md M3). Throws code 2 `no_wallet`
+ * when no wallet exists.
+ *
+ * BRC-100 custody: the external wallet reports one spendable total — it
+ * does not expose per-address detail or a confirmed/unconfirmed split, so
+ * the total lands in confirmedSats and `addresses` is empty.
+ */
+export declare function getBalance(opts: CoreOptions): Promise<BalanceResult>;

package/dist/core/balance.js

@@ -0,0 +1,34 @@
+import { trackedAddressesFromLedger } from '../ledger.js';
+import { connectBrc100 } from '../wallet/brc100.js';
+import { readWalletFile } from '../wallet/wallet.js';
+import { resolveCore } from './context.js';
+/**
+ * Aggregate balance across every address the wallet has issued. Addresses
+ * come from the ledger, so no passphrase or unlock is needed (read-only
+ * commands don't unlock — see DECISIONS.md M3). Throws code 2 `no_wallet`
+ * when no wallet exists.
+ *
+ * BRC-100 custody: the external wallet reports one spendable total — it
+ * does not expose per-address detail or a confirmed/unconfirmed split, so
+ * the total lands in confirmedSats and `addresses` is empty.
+ */
+export async function getBalance(opts) {
+    const { network, provider } = resolveCore(opts);
+    const file = readWalletFile(network); // throws no_wallet with guidance when absent
+    if (file.backend === 'brc100') {
+        const brc100 = await connectBrc100(network, { url: file.brc100_url, wallet: opts.brc100 });
+        const totalSats = await brc100.getBalanceSats();
+        return { confirmedSats: totalSats, unconfirmedSats: 0, addresses: [], backend: 'brc100' };
+    }
+    const addresses = trackedAddressesFromLedger(network);
+    let confirmedSats = 0;
+    let unconfirmedSats = 0;
+    const perAddress = [];
+    for (const address of addresses) {
+        const b = await provider.getBalance(address);
+        confirmedSats += b.confirmed;
+        unconfirmedSats += b.unconfirmed;
+        perAddress.push({ address, confirmedSats: b.confirmed, unconfirmedSats: b.unconfirmed });
+    }
+    return { confirmedSats, unconfirmedSats, addresses: perAddress };
+}

package/dist/core/context.d.ts

@@ -0,0 +1,27 @@
+import type { ChainProvider } from '../chain/provider.js';
+import { type Config } from '../config.js';
+import type { Network } from '../paths.js';
+import type { Brc100Interface } from '../wallet/brc100.js';
+/**
+ * Options every core function accepts. Config is loaded from
+ * ~/.bsv-pay/config.toml (like the CLI) and merged with any overrides, so
+ * library and CLI behavior stay consistent. The provider defaults to
+ * WhatsOnChain; tests and the local e2e mock inject their own.
+ */
+export interface CoreOptions {
+    network: Network;
+    config?: Partial<Config>;
+    provider?: ChainProvider;
+    /**
+     * Inject a connected BRC-100 wallet interface (tests, embedders). Used
+     * only when the wallet file delegates to BRC-100 custody; the default is
+     * an HTTP connection to the wallet app recorded at init.
+     */
+    brc100?: Brc100Interface;
+}
+export interface ResolvedCore {
+    network: Network;
+    config: Config;
+    provider: ChainProvider;
+}
+export declare function resolveCore(opts: CoreOptions): ResolvedCore;

package/dist/core/context.js

@@ -0,0 +1,9 @@
+import { WhatsOnChainProvider } from '../chain/whatsonchain.js';
+import { loadConfig } from '../config.js';
+export function resolveCore(opts) {
+    return {
+        network: opts.network,
+        config: { ...loadConfig(), ...opts.config },
+        provider: opts.provider ?? new WhatsOnChainProvider(opts.network),
+    };
+}

package/dist/core/history.d.ts

@@ -0,0 +1,18 @@
+import { type LedgerEntry } from '../ledger.js';
+import type { CoreOptions } from './context.js';
+export type MoneyMovement = Extract<LedgerEntry, {
+    type: 'send' | 'receive';
+}>;
+export interface HistoryParams {
+    /** Maximum entries to return (after filtering), newest first. */
+    limit?: number;
+    /** Restrict to sends or receives; default both. */
+    type?: 'send' | 'receive';
+}
+/**
+ * Money movements from the local append-only ledger, newest first. This is
+ * deliberately ledger-backed — no chain scan — so it is fast, offline, and
+ * reflects exactly what this wallet recorded (including memos, which exist
+ * only locally). Throws code 2 `no_wallet` when no wallet exists.
+ */
+export declare function getHistory(opts: CoreOptions, params?: HistoryParams): MoneyMovement[];

package/dist/core/history.js

@@ -0,0 +1,15 @@
+import { readLedger } from '../ledger.js';
+import { readWalletFile } from '../wallet/wallet.js';
+/**
+ * Money movements from the local append-only ledger, newest first. This is
+ * deliberately ledger-backed — no chain scan — so it is fast, offline, and
+ * reflects exactly what this wallet recorded (including memos, which exist
+ * only locally). Throws code 2 `no_wallet` when no wallet exists.
+ */
+export function getHistory(opts, params = {}) {
+    readWalletFile(opts.network); // throws no_wallet with guidance when absent
+    const movements = readLedger(opts.network).filter((e) => e.type === 'send' || e.type === 'receive');
+    const filtered = params.type ? movements.filter((e) => e.type === params.type) : movements;
+    filtered.reverse(); // ledger is append-only, so reversed = newest first
+    return params.limit !== undefined ? filtered.slice(0, params.limit) : filtered;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * bsv-pay/core — programmatic API over the same engine the CLI uses.
+ *
+ * Contract: typed results, typed errors (BsvPayError carries the same code
+ * numbers the CLI maps to exit codes), no process.exit, no console output,
+ * and no key material in any return value (invariant 1). This file is the
+ * only supported import path; everything else under core/ is internal.
+ */
+export { CliError as BsvPayError, EXIT, type ExitCode } from '../errors.js';
+export type { Network } from '../paths.js';
+export type { Config } from '../config.js';
+export type { ChainProvider, Utxo, AddressBalance, HistoryItem, BroadcastResult, } from '../chain/provider.js';
+export type { CoreOptions } from './context.js';
+export { openWallet, CoreWallet, type OpenWalletOptions } from './wallet.js';
+export { getBalance, type BalanceResult, type AddressBalanceResult } from './balance.js';
+export { planSend, executeSend, send, explorerTxUrl, type SendParams, type SendPlan, type SendResult, } from './send.js';
+export { getHistory, type HistoryParams, type MoneyMovement } from './history.js';
+export { getPolicyStatus, type PolicyStatusResult, type PendingApprovalStatus, } from './policy-status.js';
+export { createRequest, awaitPayment, buildPaymentUri, type RequestParams, type RequestResult, type AwaitPaymentParams, type PaymentResult, } from './request.js';
+export { paidFetch, type PaidFetchParams, type PaidFetchResult, type PaidFetchPayment, } from '../http402/client.js';
+export { requirePayment, type RequirePaymentOptions, type PaymentReceipt, type PaidRequest, type PaidRequestHandler, } from '../http402/middleware.js';
+export type { LedgerEntry } from '../ledger.js';

package/dist/core/index.js

@@ -0,0 +1,17 @@
+/**
+ * bsv-pay/core — programmatic API over the same engine the CLI uses.
+ *
+ * Contract: typed results, typed errors (BsvPayError carries the same code
+ * numbers the CLI maps to exit codes), no process.exit, no console output,
+ * and no key material in any return value (invariant 1). This file is the
+ * only supported import path; everything else under core/ is internal.
+ */
+export { CliError as BsvPayError, EXIT } from '../errors.js';
+export { openWallet, CoreWallet } from './wallet.js';
+export { getBalance } from './balance.js';
+export { planSend, executeSend, send, explorerTxUrl, } from './send.js';
+export { getHistory } from './history.js';
+export { getPolicyStatus, } from './policy-status.js';
+export { createRequest, awaitPayment, buildPaymentUri, } from './request.js';
+export { paidFetch, } from '../http402/client.js';
+export { requirePayment, } from '../http402/middleware.js';

package/dist/core/internal.d.ts

@@ -0,0 +1,22 @@
+import type { Brc100Wallet } from '../wallet/brc100.js';
+import type { Wallet } from '../wallet/wallet.js';
+import type { CoreWallet } from './wallet.js';
+/**
+ * Module-private bridge between the public CoreWallet (addresses/metadata
+ * only — invariant 1) and the custody backend behind it: the local signing
+ * Wallet, or the BRC-100 external-wallet handle (key-capable by proxy, so
+ * it stays behind the same boundary). Core modules register and unwrap
+ * here; this file is deliberately NOT exported from core/index.ts, so
+ * key-capable objects never cross the public library boundary.
+ */
+export type InnerBackend = {
+    kind: 'local';
+    wallet: Wallet;
+} | {
+    kind: 'brc100';
+    wallet: Brc100Wallet;
+};
+export declare function registerWallet(pub: CoreWallet, backend: InnerBackend): void;
+export declare function unwrapBackend(pub: CoreWallet): InnerBackend;
+/** The local signing wallet. Callers must branch on backend kind first. */
+export declare function unwrapWallet(pub: CoreWallet): Wallet;

package/dist/core/internal.js

@@ -0,0 +1,19 @@
+const inner = new WeakMap();
+export function registerWallet(pub, backend) {
+    inner.set(pub, backend);
+}
+export function unwrapBackend(pub) {
+    const backend = inner.get(pub);
+    if (!backend) {
+        throw new Error('CoreWallet is not registered; obtain it from openWallet().');
+    }
+    return backend;
+}
+/** The local signing wallet. Callers must branch on backend kind first. */
+export function unwrapWallet(pub) {
+    const backend = unwrapBackend(pub);
+    if (backend.kind !== 'local') {
+        throw new Error('Internal misuse: this code path needs the local signing wallet but the CoreWallet delegates to BRC-100 custody.');
+    }
+    return backend.wallet;
+}

package/dist/core/policy-status.d.ts

@@ -0,0 +1,55 @@
+import type { Network } from '../paths.js';
+import type { CoreOptions } from './context.js';
+export interface PendingApprovalStatus {
+    approvalId: string;
+    address: string;
+    amountSats: number;
+    memo?: string;
+    confirmedOnly?: boolean;
+    queuedAt: string;
+}
+/**
+ * A point-in-time view of the active policy and how much headroom is left.
+ * Limits that are not configured are absent (absent = unlimited, except the
+ * per-tx pair where absent means "only the other one applies"). Remaining
+ * values are clamped at 0 — they are planning hints, not promises: the
+ * binding check is the policy gate at spend time.
+ */
+export interface PolicyStatusResult {
+    source: 'defaults' | 'file';
+    network: Network;
+    /** Hard per-transaction cap (policy.toml). No override exists. */
+    perTxLimitSats?: number;
+    /** Legacy confirmable limit from config.toml (pre-policy behavior). */
+    softPerTxLimitSats?: number;
+    dailyBudgetSats?: number;
+    dailyRemainingSats?: number;
+    sessionBudgetSats?: number;
+    sessionRemainingSats?: number;
+    rateLimitPerMinute?: number;
+    remainingThisMinute?: number;
+    rateLimitPerHour?: number;
+    remainingThisHour?: number;
+    /** At/above this, spends queue for human approval instead of sending. */
+    approvalThresholdSats?: number;
+    /** False with a threshold set means queued payments cannot be approved. */
+    approvalSecretConfigured: boolean;
+    /** When non-empty, only these recipients are allowed. */
+    allowlist: string[];
+    /** Always wins over everything else. */
+    denylist: string[];
+    usage: {
+        dailySpentSats: number;
+        sessionSpentSats: number;
+        sendsLastMinute: number;
+        sendsLastHour: number;
+    };
+    pendingApprovals: PendingApprovalStatus[];
+}
+/**
+ * Read the active policy, current usage (recomputed from the ledger), and
+ * the pending-approval queue. No wallet unlock, no network I/O — works
+ * before init and never touches keys. This is what agents should call to
+ * plan within their allowance instead of discovering denials by failing.
+ */
+export declare function getPolicyStatus(opts: CoreOptions): PolicyStatusResult;

package/dist/core/policy-status.js

@@ -0,0 +1,49 @@
+import { loadConfig } from '../config.js';
+import { approvalSecretConfigured, listPendingApprovals } from '../policy/approvals.js';
+import { readUsage } from '../policy/budget.js';
+import { loadPolicy } from '../policy/policy.js';
+/**
+ * Read the active policy, current usage (recomputed from the ledger), and
+ * the pending-approval queue. No wallet unlock, no network I/O — works
+ * before init and never touches keys. This is what agents should call to
+ * plan within their allowance instead of discovering denials by failing.
+ */
+export function getPolicyStatus(opts) {
+    const config = { ...loadConfig(), ...opts.config };
+    const policy = loadPolicy(opts.network, config);
+    const usage = readUsage(opts.network);
+    const pending = listPendingApprovals(opts.network);
+    const remaining = (budget, used) => budget === undefined ? undefined : Math.max(0, budget - used);
+    return {
+        source: policy.source,
+        network: opts.network,
+        perTxLimitSats: policy.perTxLimitSats,
+        softPerTxLimitSats: policy.softPerTxLimitSats,
+        dailyBudgetSats: policy.dailyBudgetSats,
+        dailyRemainingSats: remaining(policy.dailyBudgetSats, usage.dailySpentSats),
+        sessionBudgetSats: policy.sessionBudgetSats,
+        sessionRemainingSats: remaining(policy.sessionBudgetSats, usage.sessionSpentSats),
+        rateLimitPerMinute: policy.rateLimitPerMinute,
+        remainingThisMinute: remaining(policy.rateLimitPerMinute, usage.sendsLastMinute),
+        rateLimitPerHour: policy.rateLimitPerHour,
+        remainingThisHour: remaining(policy.rateLimitPerHour, usage.sendsLastHour),
+        approvalThresholdSats: policy.approvalThresholdSats,
+        approvalSecretConfigured: approvalSecretConfigured(),
+        allowlist: [...policy.allowlist],
+        denylist: [...policy.denylist],
+        usage: {
+            dailySpentSats: usage.dailySpentSats,
+            sessionSpentSats: usage.sessionSpentSats,
+            sendsLastMinute: usage.sendsLastMinute,
+            sendsLastHour: usage.sendsLastHour,
+        },
+        pendingApprovals: pending.map((p) => ({
+            approvalId: p.approvalId,
+            address: p.address,
+            amountSats: p.amountSats,
+            memo: p.memo,
+            confirmedOnly: p.confirmedOnly,
+            queuedAt: p.queuedAt,
+        })),
+    };
+}

package/dist/core/request.d.ts

@@ -0,0 +1,43 @@
+import type { Network } from '../paths.js';
+import { type CoreOptions } from './context.js';
+import type { CoreWallet } from './wallet.js';
+/** BIP-21-style URI with the BSV `sv` discriminator. Amount is in BSV. */
+export declare function buildPaymentUri(address: string, amountSats: number, memo?: string): string;
+export interface RequestParams {
+    amountSats: number;
+    memo?: string;
+}
+export interface RequestResult {
+    address: string;
+    amountSats: number;
+    memo?: string;
+    uri: string;
+    network: Network;
+}
+/**
+ * Issue a fresh receiving address (one per request, so matching is
+ * unambiguous) and build the BIP-21 URI. The address is persisted to the
+ * wallet counter and ledger immediately.
+ */
+export declare function createRequest(wallet: CoreWallet, params: RequestParams): RequestResult;
+export interface AwaitPaymentParams {
+    address: string;
+    timeoutMs: number;
+    /** Default: config poll_interval_secs. */
+    pollIntervalMs?: number;
+    /** Recorded on the ledger receive entry (memos are local-only). */
+    memo?: string;
+}
+export interface PaymentResult {
+    address: string;
+    txid: string;
+    receivedSats: number;
+    confirmed: boolean;
+}
+/**
+ * Poll an address until the first incoming payment appears at 0-conf, then
+ * record the receive in the ledger (invariant 6) and return it. Transient
+ * chain failures keep polling until the deadline. Timeout throws code 4
+ * `request_timeout`.
+ */
+export declare function awaitPayment(opts: CoreOptions, params: AwaitPaymentParams): Promise<PaymentResult>;