@obbyx/cli 0.0.0-stage → 0.1.0

package/src/commands/channel.ts

@@ -0,0 +1,96 @@
+import type { Argv } from 'yargs';
+import { loadWallet } from '@obbyx/obyte/wallet';
+import { channelCommand } from '../lib/channels.js';
+import type { CommandContext, Cmd, GlobalArgs } from './types.js';
+import { cliLogger, connect, reservingComposer, resolveNetwork } from '../runtime.js';
+
+interface ChannelArgs {
+  target?: string;
+  deposit?: string;
+  amount?: string;
+  window?: string;
+}
+
+/** `obbyx channel <open|list|status|deposit|close|confirm>`. */
+export function channelCommands({ out, done }: CommandContext): Cmd<ChannelArgs>[] {
+  const channelRun =
+    (sub: string) =>
+    async (a: GlobalArgs & ChannelArgs): Promise<void> => {
+      const network = resolveNetwork(a.network);
+      const wallet = loadWallet(network);
+      const logger = cliLogger();
+      const client = connect(network, a.hub);
+      try {
+        done(
+          await channelCommand(
+            {
+              sub,
+              target: a.target,
+              ...(a.deposit === undefined ? {} : { deposit: a.deposit }),
+              ...(a.amount === undefined ? {} : { amount: a.amount }),
+              ...(a.window === undefined ? {} : { timeout: a.window }),
+            },
+            {
+              network,
+              client,
+              privateKey: wallet.privateKey,
+              logger,
+              out,
+              composer: reservingComposer(client, network, wallet.address, logger),
+            },
+          ),
+        );
+      } finally {
+        client.close();
+      }
+    };
+  const aaArg = (y: Argv) =>
+    y.positional('target', { type: 'string', demandOption: true, describe: 'Channel AA address' });
+
+  return [
+    {
+      command: 'open <target>',
+      describe: 'Open a payment channel to a seller (instant micropayments)',
+      builder: (y) =>
+        y
+          .positional('target', { type: 'string', demandOption: true, describe: 'Seller address' })
+          .option('deposit', { type: 'string', demandOption: true, describe: 'Deposit, GBYTE' })
+          .option('window', {
+            type: 'string',
+            default: '86400',
+            describe: 'Dispute window, seconds (sellers require a minimum)',
+          }),
+      handler: channelRun('open'),
+    },
+    { command: 'list', describe: 'List your channels', handler: channelRun('list') },
+    {
+      command: 'status <target>',
+      describe: 'Show a channel (balances, spent, period)',
+      builder: (y) => aaArg(y),
+      handler: channelRun('status'),
+    },
+    {
+      command: 'deposit <target>',
+      describe: 'Top up a channel',
+      builder: (y) =>
+        aaArg(y).option('amount', {
+          type: 'string',
+          demandOption: true,
+          describe: 'Amount, GBYTE',
+        }),
+      handler: channelRun('deposit'),
+    },
+    {
+      command: 'close <target>',
+      describe: 'Start closing a channel (the dispute window begins)',
+      builder: (y) => aaArg(y),
+      handler: channelRun('close'),
+    },
+    {
+      command: 'confirm <target>',
+      describe: 'Finish closing after the dispute window and get the rest back',
+      builder: (y) => aaArg(y),
+      handler: channelRun('confirm'),
+    },
+  ];
+}

package/src/commands/decode.ts

@@ -0,0 +1,19 @@
+import { decodeAny } from '../runtime.js';
+import type { CommandContext, Cmd } from './types.js';
+
+export function decodeCommand({ out, done }: CommandContext): Cmd<{ value: string }> {
+  return {
+    command: 'decode <value>',
+    describe: 'Decode an x402 header (PAYMENT-REQUIRED / -SIGNATURE / -RESPONSE)',
+    builder: (y) =>
+      y.positional('value', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Base64 header value',
+      }),
+    handler: (a) => {
+      out(JSON.stringify(decodeAny(a.value), null, 2));
+      done(0);
+    },
+  };
+}

package/src/commands/doctor.ts

@@ -0,0 +1,21 @@
+import { doctor } from '../lib/doctor.js';
+import { resolveNetwork } from '../runtime.js';
+import type { CommandContext, Cmd } from './types.js';
+
+export function doctorCommand({ out, done }: CommandContext): Cmd<{ facilitator?: string }> {
+  return {
+    command: 'doctor',
+    describe: 'Check wallet, hub, balance, pending payments',
+    builder: (y) =>
+      y.option('facilitator', { type: 'string', describe: 'Facilitator URL to check' }),
+    handler: async (a) => {
+      done(
+        await doctor(resolveNetwork(a.network), {
+          ...(a.hub === undefined ? {} : { hub: a.hub }),
+          ...(a.facilitator === undefined ? {} : { facilitator: a.facilitator }),
+          out,
+        }),
+      );
+    },
+  };
+}

package/src/commands/faucet.ts

@@ -0,0 +1,48 @@
+import { loadWallet } from '@obbyx/obyte/wallet';
+import { requestFromFaucet } from '../faucet/faucet.js';
+import { cliLogger, resolveNetwork, seconds } from '../runtime.js';
+import type { CommandContext, Cmd } from './types.js';
+
+export function faucetCommand({ out, done }: CommandContext): Cmd<{ timeout: string }> {
+  return {
+    command: 'faucet',
+    describe: 'Get free testnet bytes (once per 24 h)',
+    builder: (y) =>
+      y.option('timeout', {
+        type: 'string',
+        default: '60',
+        describe: 'How long to wait for the faucet bot, seconds',
+      }),
+    handler: async (a) => {
+      const network = resolveNetwork(a.network);
+      const wallet = loadWallet(network);
+      out(`Asking the ${network.caip2} faucet to fund ${wallet.address} ...`);
+      const result = await requestFromFaucet({
+        network,
+        address: wallet.address,
+        logger: cliLogger(),
+        timeoutMs: seconds(a.timeout, 'timeout') * 1000,
+        onBotText: (text) => out(`  faucet: ${text}`),
+      });
+      switch (result.status) {
+        case 'sent':
+          out(
+            'Bytes are on the way. They become spendable once stable (minutes, up to ~2 h on a quiet network): obbyx balance',
+          );
+          return done(0);
+        case 'rate_limited':
+          out('The faucet pays each device once per 24 hours. Try again later.');
+          return done(2);
+        case 'rejected':
+          out('The faucet rejected the request (see its message above).');
+          return done(2);
+        case 'no_answer':
+          out(
+            'No answer from the faucet yet. Check `obbyx balance` in a few minutes or retry later.',
+          );
+          return done(3);
+      }
+      done(3);
+    },
+  };
+}

package/src/commands/init.ts

@@ -0,0 +1,28 @@
+import { createWallet, walletPath } from '@obbyx/obyte/wallet';
+import { resolveNetwork } from '../runtime.js';
+import type { CommandContext, Cmd } from './types.js';
+
+export function initCommand({ out, done }: CommandContext): Cmd<{ force: boolean }> {
+  return {
+    command: 'init',
+    describe: 'Create a local wallet',
+    builder: (y) =>
+      y.option('force', {
+        type: 'boolean',
+        default: false,
+        describe: 'Overwrite an existing wallet',
+      }),
+    handler: (a) => {
+      const network = resolveNetwork(a.network);
+      const wallet = createWallet(network, { force: a.force });
+      out(`Wallet created for ${network.caip2}`);
+      out(`  address: ${wallet.address}`);
+      out(`  file:    ${walletPath(network)} (keep it private; it holds your key)`);
+      if (network.testnet) {
+        out();
+        out('Fund it with testnet bytes: obbyx faucet (then: obbyx balance)');
+      }
+      done(0);
+    },
+  };
+}

package/src/commands/logs.ts

@@ -0,0 +1,48 @@
+import { logs } from '../lib/logs.js';
+import type { CommandContext, Cmd } from './types.js';
+
+interface LogsArgs {
+  files: string[];
+  binding?: string;
+  proof?: string;
+  aa?: string;
+  request?: string;
+  level?: string;
+}
+export function logsCommand({ out, done }: CommandContext): Cmd<LogsArgs> {
+  return {
+    command: 'logs <files..>',
+    describe: 'Follow one payment through JSON log files',
+    builder: (y) =>
+      y
+        .positional('files', {
+          type: 'string',
+          array: true,
+          demandOption: true,
+          describe: 'JSON log files',
+        })
+        .option('binding', { type: 'string', describe: 'Only entries of this payment binding' })
+        .option('proof', { type: 'string', describe: 'Only entries of this proof id' })
+        .option('aa', { type: 'string', describe: 'Only entries of this channel AA' })
+        .option('request', { type: 'string', describe: 'Only entries of this request id' })
+        .option('level', {
+          type: 'string',
+          describe: 'Minimum level (debug, info, warn, ...)',
+        }),
+    handler: async (a) => {
+      done(
+        await logs(
+          a.files,
+          {
+            ...(a.binding === undefined ? {} : { binding: a.binding }),
+            ...(a.proof === undefined ? {} : { proof: a.proof }),
+            ...(a.aa === undefined ? {} : { aa: a.aa }),
+            ...(a.request === undefined ? {} : { request: a.request }),
+            ...(a.level === undefined ? {} : { level: a.level }),
+          },
+          out,
+        ),
+      );
+    },
+  };
+}

package/src/commands/pay.ts

@@ -0,0 +1,135 @@
+import { ObbyxError, fromDisplay } from '@obbyx/obyte';
+import { loadWallet } from '@obbyx/obyte/wallet';
+import { BatchObyteClient, ClientChannelStore, ExactObyteClient } from '@obbyx/x402-obyte';
+import { PaymentPendingError, payingFetch } from '@obbyx/sdk';
+import { channelStorePath } from '../lib/channels.js';
+import {
+  bytesArg,
+  cliLogger,
+  connect,
+  printPayment,
+  reservingComposer,
+  resolveNetwork,
+  seconds,
+} from '../runtime.js';
+import type { CommandContext, Cmd } from './types.js';
+
+interface PayArgs {
+  url: string;
+  max: string;
+  method?: string;
+  data?: string;
+  header?: string[];
+  payment?: string;
+  wait: string;
+  'max-fee': string;
+}
+export function payCommand({ out, err, done }: CommandContext): Cmd<PayArgs> {
+  return {
+    command: 'pay <url>',
+    describe: 'Call a paid API, paying at most --max',
+    builder: (y) =>
+      y
+        .positional('url', { type: 'string', demandOption: true, describe: 'URL of the paid API' })
+        .option('max', {
+          type: 'string',
+          demandOption: 'pay needs --max <GBYTE>: the most you allow this call to cost',
+          describe: 'Spending limit for this call, in GBYTE (e.g. 0.00002)',
+        })
+        .option('method', {
+          type: 'string',
+          describe: 'HTTP method (default GET, or POST with --data)',
+        })
+        .option('data', { type: 'string', describe: 'Request body (JSON by default)' })
+        .option('header', {
+          type: 'string',
+          array: true,
+          describe: "Extra header 'Name: value' (repeatable)",
+        })
+        .option('payment', {
+          type: 'string',
+          describe: 'Retry a pending request with the same payment (printed by pay)',
+        })
+        .option('wait', {
+          type: 'string',
+          default: '600',
+          describe:
+            'How long to wait for the payment to become final, seconds (testnet can take minutes). It never pays twice meanwhile.',
+        })
+        .option('max-fee', {
+          type: 'string',
+          default: '10000',
+          describe: 'Most network fee (bytes) an on-chain (exact) payment may cost',
+        }),
+    handler: async (a) => {
+      const network = resolveNetwork(a.network);
+      // Validate every argument before touching the wallet or the network.
+      const max = fromDisplay(a.max, 9);
+      const maxFee = bytesArg(a['max-fee'], 'max-fee');
+      const waitMs = seconds(a.wait, 'wait') * 1000;
+      const wallet = loadWallet(network);
+      const logger = cliLogger();
+      const client = connect(network, a.hub);
+      try {
+        const composer = reservingComposer(client, network, wallet.address, logger);
+        const mechanism = new ExactObyteClient({
+          client,
+          network: network.caip2,
+          privateKey: wallet.privateKey,
+          logger,
+          composer,
+          maxFee,
+        });
+        // Use a payment channel to this seller when one is open (instant, no fee per call).
+        const batch = new BatchObyteClient({
+          client,
+          network,
+          privateKey: wallet.privateKey,
+          store: new ClientChannelStore(channelStorePath(network)),
+          logger,
+          maxAmount: new Map([['base', max]]),
+          composer,
+        });
+        const headers: Record<string, string> = {};
+        for (const h of a.header ?? []) {
+          const i = h.indexOf(':');
+          if (i <= 0) throw new ObbyxError('usage', `Bad --header "${h}" (expected "Name: value")`);
+          headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+        }
+        if (a.data !== undefined) headers['content-type'] ??= 'application/json';
+        const method = a.method ?? (a.data === undefined ? 'GET' : 'POST');
+        try {
+          const result = await payingFetch(
+            a.url,
+            {
+              method,
+              headers,
+              ...(a.data === undefined ? {} : { body: a.data }),
+              ...(a.payment === undefined ? {} : { paymentHeader: a.payment }),
+            },
+            {
+              mechanisms: { exact: mechanism, batch },
+              network: network.caip2,
+              maxAmount: new Map([['base', max]]),
+              logger,
+              pendingTimeoutMs: waitMs,
+            },
+          );
+          err(`HTTP ${result.response.status}`);
+          if (result.payment) printPayment(err, network, result.payment);
+          out(await result.response.text());
+          return done(result.response.ok ? 0 : 2);
+        } catch (e) {
+          if (e instanceof PaymentPendingError) {
+            err(`Payment ${e.transaction} is not final yet. Retry the same request later with:`);
+            err(`  --payment ${e.paymentHeader}`);
+            return done(3);
+          }
+          throw e;
+        }
+      } finally {
+        client.close();
+      }
+    },
+  };
+}

package/src/commands/types.ts

@@ -0,0 +1,31 @@
+import type { Argv } from 'yargs';
+
+/** Output of the CLI (stdout / stderr), injectable for tests. */
+export interface CliIo {
+  out(line?: string): void;
+  err(line: string): void;
+}
+
+/** Options every command accepts. */
+export interface GlobalArgs {
+  network: string;
+  hub: string | undefined;
+}
+
+/** What a command needs from the runner: output and a way to set the exit code. */
+export interface CommandContext {
+  readonly out: (line?: string) => void;
+  readonly err: (line: string) => void;
+  /** yargs handlers cannot return a value: the exit code is set here. */
+  readonly done: (code: number) => void;
+}
+
+/** One command; the builder declares the options/positionals that `A` describes. */
+export interface Cmd<A = object> {
+  readonly command: string;
+  readonly describe: string;
+  readonly builder?: (y: Argv) => Argv;
+  readonly handler: (args: GlobalArgs & A) => void | Promise<void>;
+}
+
+export type AnyCmd = Cmd<never>;