@obbyx/cli 0.0.0-stage → 0.1.0

package/src/lib/doctor.ts

@@ -0,0 +1,133 @@
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import obyte from 'obyte';
+import { type ObyteNetwork, toDisplay } from '@obbyx/obyte';
+import { ClientChannelStore, CoinReservations, hubCall } from '@obbyx/x402-obyte';
+import { channelStorePath } from './channels.js';
+import { obbyxHome, walletPath } from '@obbyx/obyte/wallet';
+
+/**
+ * `obbyx doctor` — checks everything a payment depends on and says what to fix.
+ * Exit code 0 when nothing failed (warnings allowed).
+ */
+type Status = 'ok' | 'warn' | 'fail';
+
+export async function doctor(
+  network: ObyteNetwork,
+  opts: { hub?: string; facilitator?: string; out: (s: string) => void },
+): Promise<number> {
+  const results: Status[] = [];
+  const report = (status: Status, what: string, detail = '') => {
+    results.push(status);
+    opts.out(
+      `${status === 'ok' ? '✓' : status === 'warn' ? '!' : '✗'} ${what}${detail ? ` — ${detail}` : ''}`,
+    );
+  };
+
+  // Wallet
+  const wallet = walletPath(network);
+  let address: string | undefined;
+  if (!existsSync(wallet)) {
+    report('fail', 'wallet', `missing; run: obbyx init --network ${network.name}`);
+  } else if ((statSync(wallet).mode & 0o077) !== 0) {
+    report('fail', 'wallet', `${wallet} is readable by others; run: chmod 600 ${wallet}`);
+  } else {
+    const { readFileSync } = await import('node:fs');
+    address = (JSON.parse(readFileSync(wallet, 'utf8')) as { address: string }).address;
+    report('ok', 'wallet', `${address} (${wallet})`);
+  }
+
+  // Hub
+  const client = new obyte.Client(opts.hub ?? network.defaultHubUrl, { testnet: network.testnet });
+  try {
+    const started = Date.now();
+    const mci = await hubCall(() => client.api.getLastMci(), 10_000);
+    if (mci.kind !== 'ok') {
+      report('fail', 'hub', `${opts.hub ?? network.defaultHubUrl}: ${mci.error}`);
+    } else {
+      report(
+        'ok',
+        'hub',
+        `${opts.hub ?? network.defaultHubUrl}, last MCI ${mci.value}, ${Date.now() - started} ms`,
+      );
+      if (address !== undefined) {
+        const b = await hubCall(() => client.api.getBalances([address]), 10_000);
+        if (b.kind === 'ok') {
+          const base = (
+            b.value as Record<string, Record<string, { stable: number; pending: number }>>
+          )[address]?.['base'];
+          const stable = BigInt(base?.stable ?? 0);
+          const pending = BigInt(base?.pending ?? 0);
+          report(
+            stable === 0n ? (network.testnet ? 'warn' : 'fail') : 'ok',
+            'balance',
+            `${toDisplay(stable, 9)} GBYTE stable, ${toDisplay(pending, 9)} pending` +
+              (stable === 0n && network.testnet ? '; run: obbyx faucet' : ''),
+          );
+        } else {
+          report('warn', 'balance', b.error);
+        }
+      }
+    }
+  } finally {
+    client.close();
+  }
+
+  // Local payment state
+  const coinsPath = join(obbyxHome(), `coins-${network.name}.db`);
+  if (existsSync(coinsPath)) {
+    const reservations = new CoinReservations(coinsPath);
+    const units = reservations.boundUnits(network.caip2);
+    reservations.close();
+    report(
+      units.length === 0 ? 'ok' : 'warn',
+      'coin reservations',
+      units.length === 0
+        ? 'none'
+        : `${units.length} unpublished payment unit(s) hold inputs; they are released once seen on the ledger or after the publication window`,
+    );
+  }
+  const channelsPath = channelStorePath(network);
+  if (existsSync(channelsPath)) {
+    const channels = new ClientChannelStore(channelsPath);
+    const list = channels.list().filter((c) => c.network === network.caip2);
+    channels.close();
+    const pending = list.filter((c) => c.pending !== null);
+    report(
+      pending.length === 0 ? 'ok' : 'warn',
+      'channels',
+      `${list.length} channel(s)` +
+        (pending.length
+          ? `, ${pending.length} with a voucher of unknown outcome (retry that request with --payment)`
+          : ''),
+    );
+  }
+
+  // Facilitator (optional)
+  if (opts.facilitator !== undefined) {
+    try {
+      const res = await fetch(new URL('/supported', opts.facilitator), {
+        signal: AbortSignal.timeout(10_000),
+      });
+      const supported = (await res.json()) as { kinds?: { scheme: string; network: string }[] };
+      const kinds = (supported.kinds ?? [])
+        .filter((k) => k.network === network.caip2)
+        .map((k) => k.scheme);
+      report(
+        kinds.length > 0 ? 'ok' : 'fail',
+        'facilitator',
+        kinds.length > 0
+          ? `${opts.facilitator}: ${kinds.join(', ')}`
+          : `does not serve ${network.caip2}`,
+      );
+    } catch (err) {
+      report(
+        'fail',
+        'facilitator',
+        `${opts.facilitator}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return results.includes('fail') ? 1 : 0;
+}

package/src/lib/logs.ts

@@ -0,0 +1,79 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+/**
+ * `obbyx logs` — follow ONE payment through the JSON logs of the seller
+ * middleware, the facilitator and the watcher (they share correlation fields:
+ * requestId, binding, proofId, aa, seq). Reads files or stdin.
+ */
+export interface LogFilter {
+  readonly binding?: string;
+  readonly proof?: string;
+  readonly aa?: string;
+  readonly request?: string;
+  readonly level?: string;
+}
+
+const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const SHOWN = [
+  'binding',
+  'proofId',
+  'aa',
+  'seq',
+  'reason',
+  'from',
+  'to',
+  'transaction',
+  'amountSpent',
+  'status',
+  'err',
+];
+
+export function matches(entry: Record<string, unknown>, f: LogFilter): boolean {
+  if (f.binding !== undefined && entry['binding'] !== f.binding) return false;
+  if (f.proof !== undefined && entry['proofId'] !== f.proof && entry['unit'] !== f.proof)
+    return false;
+  if (f.aa !== undefined && entry['aa'] !== f.aa) return false;
+  if (f.request !== undefined && entry['requestId'] !== f.request && entry['reqId'] !== f.request)
+    return false;
+  if (f.level !== undefined) {
+    const min = LEVELS.indexOf(f.level);
+    if (min >= 0 && LEVELS.indexOf(String(entry['level'])) < min) return false;
+  }
+  return true;
+}
+
+export function format(entry: Record<string, unknown>): string {
+  const time = String(entry['time'] ?? '').slice(11, 23);
+  const extra = SHOWN.filter((k) => entry[k] !== undefined)
+    .map(
+      (k) => `${k}=${typeof entry[k] === 'object' ? JSON.stringify(entry[k]) : String(entry[k])}`,
+    )
+    .join(' ');
+  return `${time} ${String(entry['level'] ?? '').padEnd(5)} ${String(entry['service'] ?? '-')}/${String(entry['module'] ?? '-')}: ${String(entry['msg'] ?? '')}${extra ? `  ${extra}` : ''}`;
+}
+
+export async function logs(
+  files: readonly string[],
+  filter: LogFilter,
+  out: (s: string) => void,
+): Promise<number> {
+  const sources = files.length > 0 ? files : ['-'];
+  const found: Record<string, unknown>[] = [];
+  for (const file of sources) {
+    const input = file === '-' ? process.stdin : createReadStream(file, 'utf8');
+    for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+      if (!line.startsWith('{')) continue;
+      try {
+        const entry = JSON.parse(line) as Record<string, unknown>;
+        if (matches(entry, filter)) found.push(entry);
+      } catch {
+        // not a JSON log line
+      }
+    }
+  }
+  // Several components' logs merged into one timeline.
+  found.sort((a, b) => String(a['time'] ?? '').localeCompare(String(b['time'] ?? '')));
+  for (const entry of found) out(format(entry));
+  return found.length > 0 ? 0 : 1;
+}

package/src/main.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { hideBin } from 'yargs/helpers';
+import { runCli } from './cli.js';
+
+runCli(hideBin(process.argv), {
+  out: (line = '') => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+}).then(
+  (code) => process.exit(code),
+  (e: unknown) => {
+    process.stderr.write(`error: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+  },
+);

package/src/runtime.ts

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import obyte from 'obyte';
+import {
+  decodePaymentRequiredHeader,
+  decodePaymentResponseHeader,
+  decodePaymentSignatureHeader,
+} from '@x402/core/http';
+import {
+  OBYTE_NETWORKS,
+  ObbyxError,
+  type ObyteNetwork,
+  explorerUnitUrl,
+  getNetwork,
+  toDisplay,
+} from '@obbyx/obyte';
+import { type Logger, createLogger } from '@obbyx/obyte/logger';
+import { obbyxHome } from '@obbyx/obyte/wallet';
+import { CoinReservations, ReservingComposer } from '@obbyx/x402-obyte';
+
+/** Helpers shared by the commands: network/hub, logger, argument parsing, output. */
+export function printPayment(
+  err: (l: string) => void,
+  network: ObyteNetwork,
+  p: {
+    success: boolean;
+    amount?: string;
+    transaction: string;
+    errorReason?: string;
+    extra?: unknown;
+  },
+): void {
+  const channel = p.extra as
+    | {
+        chargedAmount?: string;
+        channelState?: { channelId?: string; chargedCumulativeAmount?: string };
+      }
+    | undefined;
+  if (p.success && channel?.chargedAmount !== undefined) {
+    // batch-settlement: an off-chain voucher, no unit per call.
+    err(
+      `Paid: ${toDisplay(BigInt(channel.chargedAmount), 9)} GBYTE via channel ${channel.channelState?.channelId ?? ''}` +
+        ` (total in this period: ${toDisplay(BigInt(channel.channelState?.chargedCumulativeAmount ?? '0'), 9)} GBYTE)`,
+    );
+  } else if (p.success) {
+    err(
+      `Paid: ${toDisplay(BigInt(p.amount ?? '0'), 9)} GBYTE, unit ${p.transaction}\n  ${explorerUnitUrl(network, p.transaction)}`,
+    );
+  } else {
+    err(`Payment not completed: ${p.errorReason}${p.transaction ? ` (${p.transaction})` : ''}`);
+  }
+}
+
+export function cliLogger(): Logger {
+  return createLogger({
+    level: (process.env['LOG_LEVEL'] as never) ?? 'warn',
+    pretty: process.stderr.isTTY,
+  });
+}
+
+export function bytesArg(value: string, name: string): bigint {
+  if (!/^\d+$/.test(value))
+    throw new ObbyxError('usage', `--${name} must be a whole number of bytes`);
+  return BigInt(value);
+}
+
+export function seconds(value: string, name: string): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0 || n > 86_400) {
+    throw new ObbyxError('usage', `--${name} must be a whole number of seconds (1..86400)`);
+  }
+  return n;
+}
+
+/** Reserving coin picker for this wallet (inputs of unpublished units are never reused). */
+export function reservingComposer(
+  client: obyte.Client,
+  network: ObyteNetwork,
+  address: string,
+  logger: Logger,
+): ReservingComposer {
+  return new ReservingComposer({
+    client,
+    network: network.caip2,
+    address,
+    reservations: new CoinReservations(join(obbyxHome(), `coins-${network.name}.db`)),
+    logger,
+  });
+}
+
+export function resolveNetwork(name: string): ObyteNetwork {
+  if (name === 'testnet' || name === 'livenet') return OBYTE_NETWORKS[name];
+  try {
+    return getNetwork(name);
+  } catch {
+    throw new ObbyxError('usage', `Unknown --network "${name}" (use testnet or livenet)`);
+  }
+}
+
+export function connect(network: ObyteNetwork, hub: string | undefined): obyte.Client {
+  return new obyte.Client(hub ?? network.defaultHubUrl, { testnet: network.testnet });
+}
+
+export function decodeAny(value: string): unknown {
+  for (const [kind, decode] of [
+    ['PAYMENT-SIGNATURE', decodePaymentSignatureHeader],
+    ['PAYMENT-REQUIRED', decodePaymentRequiredHeader],
+    ['PAYMENT-RESPONSE', decodePaymentResponseHeader],
+  ] as const) {
+    try {
+      const decoded = decode(value) as Record<string, unknown>;
+      const looksRight =
+        kind === 'PAYMENT-SIGNATURE'
+          ? 'payload' in decoded && 'accepted' in decoded
+          : kind === 'PAYMENT-REQUIRED'
+            ? 'accepts' in decoded
+            : 'success' in decoded;
+      if (looksRight) return { header: kind, value: decoded };
+    } catch {
+      // try next
+    }
+  }
+  throw new ObbyxError('decode_failed', 'Not a recognizable x402 header');
+}