@agirails/sdk 2.0.1-beta → 2.0.2

package/src/cli/commands/tx.ts

@@ -0,0 +1,448 @@
+/**
+ * Transaction Commands - tx subcommand group
+ *
+ * Commands for managing ACTP transactions:
+ * - tx create: Create a new transaction (intermediate API)
+ * - tx status: Check transaction status
+ * - tx list: List all transactions
+ * - tx deliver: Mark transaction as delivered
+ * - tx settle: Release escrow funds
+ * - tx cancel: Cancel a transaction
+ *
+ * @module cli/commands/tx
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode, TransactionDisplay } from '../utils/output';
+import { createClient, mapError, isValidTxId } from '../utils/client';
+import { TransactionState, MockTransaction } from '../../runtime/types/MockState';
+
+// ============================================================================
+// Main tx Command
+// ============================================================================
+
+export function createTxCommand(): Command {
+  const cmd = new Command('tx')
+    .description('Transaction management commands');
+
+  cmd.addCommand(createTxCreateCommand());
+  cmd.addCommand(createTxStatusCommand());
+  cmd.addCommand(createTxListCommand());
+  cmd.addCommand(createTxDeliverCommand());
+  cmd.addCommand(createTxSettleCommand());
+  cmd.addCommand(createTxCancelCommand());
+
+  return cmd;
+}
+
+// ============================================================================
+// tx create
+// ============================================================================
+
+function createTxCreateCommand(): Command {
+  return new Command('create')
+    .description('Create a new transaction (without auto-funding)')
+    .argument('<provider>', 'Provider address')
+    .argument('<amount>', 'Amount to pay')
+    .option('-d, --deadline <deadline>', 'Deadline (+24h, +7d, or Unix timestamp)', '+24h')
+    .option('-w, --dispute-window <seconds>', 'Dispute window in seconds', '172800')
+    .option('--description <text>', 'Service description')
+    .option('--fund', 'Automatically fund the escrow after creation')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the transaction ID')
+    .action(async (provider, amount, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        const client = await createClient();
+
+        let deadline: string | number = options.deadline;
+        if (/^\d+$/.test(options.deadline)) {
+          deadline = parseInt(options.deadline, 10);
+        }
+
+        const disputeWindow = parseInt(options.disputeWindow, 10);
+
+        // Create transaction
+        const txId = await client.intermediate.createTransaction({
+          provider,
+          amount,
+          deadline,
+          disputeWindow,
+          serviceDescription: options.description,
+        });
+
+        // Optionally fund
+        let escrowId: string | undefined;
+        if (options.fund) {
+          escrowId = await client.intermediate.linkEscrow(txId);
+        }
+
+        const tx = await client.intermediate.getTransaction(txId);
+        if (!tx) throw new Error('Transaction not found after creation');
+
+        output.result(
+          {
+            txId,
+            state: tx.state,
+            provider: tx.provider,
+            requester: tx.requester,
+            amount: `${formatUsdc(tx.amount)} USDC`,
+            deadline: new Date(tx.deadline * 1000).toISOString(),
+            escrowId: escrowId || null,
+          },
+          { quietKey: 'txId' }
+        );
+
+        if (!options.fund) {
+          output.blank();
+          output.info('Transaction created but not funded.');
+          output.print('  Fund it: actp tx fund ' + txId.slice(0, 10) + '...');
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// tx status
+// ============================================================================
+
+function createTxStatusCommand(): Command {
+  return new Command('status')
+    .description('Check transaction status')
+    .argument('<txId>', 'Transaction ID')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the state')
+    .action(async (txId, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        if (!isValidTxId(txId)) {
+          throw new Error(`Invalid transaction ID format: "${txId}"`);
+        }
+
+        const client = await createClient();
+        const tx = await client.intermediate.getTransaction(txId);
+
+        if (!tx) {
+          throw new Error(`Transaction not found: ${txId}`);
+        }
+
+        const status = await client.beginner.checkStatus(txId);
+
+        if (options.quiet) {
+          output.raw(tx.state);
+          return;
+        }
+
+        const display: TransactionDisplay = {
+          txId: tx.id,
+          state: tx.state,
+          requester: tx.requester,
+          provider: tx.provider,
+          amount: `${formatUsdc(tx.amount)} USDC`,
+          deadline: new Date(tx.deadline * 1000).toISOString(),
+          escrowId: tx.escrowId,
+          createdAt: new Date(tx.createdAt * 1000).toISOString(),
+        };
+
+        if (options.json) {
+          output.result({
+            ...display,
+            actions: {
+              canAccept: status.canAccept,
+              canComplete: status.canComplete,
+              canDispute: status.canDispute,
+            },
+          });
+        } else {
+          output.transaction(display);
+          output.blank();
+          output.print('Available Actions:');
+          output.keyValue('  Can Accept', status.canAccept);
+          output.keyValue('  Can Complete', status.canComplete);
+          output.keyValue('  Can Dispute', status.canDispute);
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// tx list
+// ============================================================================
+
+function createTxListCommand(): Command {
+  return new Command('list')
+    .description('List all transactions')
+    .option('-s, --state <state>', 'Filter by state')
+    .option('-l, --limit <n>', 'Limit number of results', '50')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only transaction IDs (one per line)')
+    .action(async (options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        const client = await createClient();
+        let transactions: MockTransaction[] = await client.advanced.getAllTransactions();
+
+        // Filter by state if specified
+        if (options.state) {
+          const stateFilter = options.state.toUpperCase();
+          transactions = transactions.filter((tx: MockTransaction) => tx.state === stateFilter);
+        }
+
+        // Sort by createdAt descending (newest first)
+        transactions.sort((a: MockTransaction, b: MockTransaction) => b.createdAt - a.createdAt);
+
+        // Apply limit
+        const limit = parseInt(options.limit, 10);
+        transactions = transactions.slice(0, limit);
+
+        if (options.quiet) {
+          for (const tx of transactions) {
+            console.log(tx.id);
+          }
+          return;
+        }
+
+        if (options.json) {
+          output.result({
+            count: transactions.length,
+            transactions: transactions.map((tx: MockTransaction) => ({
+              txId: tx.id,
+              state: tx.state,
+              requester: tx.requester,
+              provider: tx.provider,
+              amount: tx.amount,
+              deadline: new Date(tx.deadline * 1000).toISOString(),
+              createdAt: new Date(tx.createdAt * 1000).toISOString(),
+            })),
+          });
+          return;
+        }
+
+        output.section(`Transactions (${transactions.length})`);
+        output.transactionTable(
+          transactions.map((tx: MockTransaction) => ({
+            txId: tx.id,
+            state: tx.state,
+            requester: tx.requester,
+            provider: tx.provider,
+            amount: `${formatUsdc(tx.amount)} USDC`,
+            deadline: new Date(tx.deadline * 1000).toISOString(),
+          }))
+        );
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// tx deliver
+// ============================================================================
+
+function createTxDeliverCommand(): Command {
+  return new Command('deliver')
+    .description('Mark transaction as delivered (provider action)')
+    .argument('<txId>', 'Transaction ID')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (txId, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        if (!isValidTxId(txId)) {
+          throw new Error(`Invalid transaction ID format: "${txId}"`);
+        }
+
+        const client = await createClient();
+
+        // Transition to DELIVERED
+        await client.intermediate.transitionState(txId, 'DELIVERED' as TransactionState);
+
+        const tx = await client.intermediate.getTransaction(txId);
+        if (!tx) throw new Error('Transaction not found');
+
+        output.result(
+          {
+            txId,
+            state: tx.state,
+            completedAt: tx.completedAt
+              ? new Date(tx.completedAt * 1000).toISOString()
+              : null,
+          },
+          { quietKey: 'state' }
+        );
+
+        output.success('Transaction marked as delivered!');
+        output.info(`Dispute window: ${tx.disputeWindow} seconds`);
+        output.print('');
+        output.print('After dispute window expires, settle with:');
+        output.print('  actp tx settle ' + txId.slice(0, 10) + '...');
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// tx settle
+// ============================================================================
+
+function createTxSettleCommand(): Command {
+  return new Command('settle')
+    .description('Release escrow funds to provider')
+    .argument('<txId>', 'Transaction ID')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (txId, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        if (!isValidTxId(txId)) {
+          throw new Error(`Invalid transaction ID format: "${txId}"`);
+        }
+
+        const client = await createClient();
+
+        // Get transaction to find escrow
+        const tx = await client.intermediate.getTransaction(txId);
+        if (!tx) throw new Error(`Transaction not found: ${txId}`);
+        if (!tx.escrowId) throw new Error('Transaction has no linked escrow');
+
+        // Release escrow
+        await client.intermediate.releaseEscrow(tx.escrowId);
+
+        // Get updated transaction
+        const updatedTx = await client.intermediate.getTransaction(txId);
+        if (!updatedTx) throw new Error('Transaction not found');
+
+        output.result(
+          {
+            txId,
+            state: updatedTx.state,
+            provider: updatedTx.provider,
+            amount: `${formatUsdc(updatedTx.amount)} USDC`,
+          },
+          { quietKey: 'state' }
+        );
+
+        output.success('Escrow released! Funds sent to provider.');
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// tx cancel
+// ============================================================================
+
+function createTxCancelCommand(): Command {
+  return new Command('cancel')
+    .description('Cancel a transaction (before delivery)')
+    .argument('<txId>', 'Transaction ID')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (txId, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        if (!isValidTxId(txId)) {
+          throw new Error(`Invalid transaction ID format: "${txId}"`);
+        }
+
+        const client = await createClient();
+
+        // Transition to CANCELLED
+        await client.intermediate.transitionState(txId, 'CANCELLED' as TransactionState);
+
+        const tx = await client.intermediate.getTransaction(txId);
+        if (!tx) throw new Error('Transaction not found');
+
+        output.result(
+          {
+            txId,
+            state: tx.state,
+            refunded: tx.escrowId !== null,
+          },
+          { quietKey: 'state' }
+        );
+
+        output.success('Transaction cancelled!');
+        if (tx.escrowId) {
+          output.info('Funds have been refunded to requester.');
+        }
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Format USDC amount from wei to decimal
+ */
+function formatUsdc(weiAmount: string): string {
+  const amount = BigInt(weiAmount);
+  const whole = amount / 1_000_000n;
+  const decimal = amount % 1_000_000n;
+  const decimalStr = decimal.toString().padStart(6, '0').slice(0, 2);
+  return `${whole}.${decimalStr}`;
+}

package/src/cli/commands/watch.ts

@@ -0,0 +1,211 @@
+/**
+ * Watch Command - Stream transaction state changes
+ *
+ * Agent-first feature: Real-time monitoring of transaction state.
+ * Outputs state changes as they happen, perfect for scripts
+ * that need to react to transaction lifecycle events.
+ *
+ * @module cli/commands/watch
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode, formatState, fmt } from '../utils/output';
+import { createClient, mapError, isValidTxId } from '../utils/client';
+import { TransactionState } from '../../runtime/types/MockState';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createWatchCommand(): Command {
+  const cmd = new Command('watch')
+    .description('Watch a transaction for state changes (agent-first feature)')
+    .argument('<txId>', 'Transaction ID to watch')
+    .option('-t, --timeout <seconds>', 'Exit after timeout (default: indefinite)', '0')
+    .option('-i, --interval <ms>', 'Polling interval in milliseconds', '1000')
+    .option('--until <state>', 'Exit when transaction reaches this state')
+    .option('--json', 'Output state changes as JSON lines (NDJSON)')
+    .option('-q, --quiet', 'Output only state names on change')
+    .action(async (txId, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runWatch(txId, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface WatchOptions {
+  timeout: string;
+  interval: string;
+  until?: string;
+}
+
+async function runWatch(
+  txId: string,
+  options: WatchOptions,
+  output: Output
+): Promise<void> {
+  if (!isValidTxId(txId)) {
+    throw new Error(`Invalid transaction ID format: "${txId}"`);
+  }
+
+  const client = await createClient();
+  const pollIntervalMs = parseInt(options.interval, 10);
+  const timeoutSeconds = parseInt(options.timeout, 10);
+  const untilState = options.until?.toUpperCase() as TransactionState | undefined;
+
+  // Validate until state if provided
+  const validStates: TransactionState[] = [
+    'INITIATED', 'QUOTED', 'COMMITTED', 'IN_PROGRESS',
+    'DELIVERED', 'SETTLED', 'DISPUTED', 'CANCELLED',
+  ];
+
+  if (untilState && !validStates.includes(untilState)) {
+    throw new Error(
+      `Invalid state: "${options.until}"\n` +
+        `Valid states: ${validStates.join(', ')}`
+    );
+  }
+
+  // Get initial state
+  const tx = await client.intermediate.getTransaction(txId);
+  if (!tx) {
+    throw new Error(`Transaction not found: ${txId}`);
+  }
+
+  let currentState = tx.state;
+  const startTime = Date.now();
+
+  // Output initial state
+  emitStateChange(output, txId, null, currentState, tx.updatedAt);
+
+  // Check if already at target state
+  if (untilState && currentState === untilState) {
+    output.info('Transaction already at target state.');
+    process.exit(ExitCode.SUCCESS);
+  }
+
+  // Terminal states
+  const terminalStates: TransactionState[] = ['SETTLED', 'CANCELLED'];
+  if (terminalStates.includes(currentState)) {
+    output.info('Transaction is in terminal state.');
+    process.exit(ExitCode.SUCCESS);
+  }
+
+  output.info('Watching for state changes... (Ctrl+C to stop)');
+
+  // Polling loop
+  const poll = async (): Promise<void> => {
+    // Check timeout
+    if (timeoutSeconds > 0) {
+      const elapsed = (Date.now() - startTime) / 1000;
+      if (elapsed >= timeoutSeconds) {
+        output.warning(`Timeout reached (${timeoutSeconds}s)`);
+        process.exit(ExitCode.TIMEOUT);
+      }
+    }
+
+    try {
+      const updatedTx = await client.intermediate.getTransaction(txId);
+      if (!updatedTx) {
+        output.warning('Transaction no longer exists');
+        process.exit(ExitCode.ERROR);
+      }
+
+      if (updatedTx.state !== currentState) {
+        const previousState = currentState;
+        currentState = updatedTx.state;
+        emitStateChange(output, txId, previousState, currentState, updatedTx.updatedAt);
+
+        // Check if reached target state
+        if (untilState && currentState === untilState) {
+          output.success(`Reached target state: ${untilState}`);
+          process.exit(ExitCode.SUCCESS);
+        }
+
+        // Check if terminal
+        if (terminalStates.includes(currentState)) {
+          output.info(`Transaction reached terminal state: ${currentState}`);
+          process.exit(ExitCode.SUCCESS);
+        }
+      }
+    } catch (error) {
+      // Non-fatal: log warning and continue
+      output.warning(`Poll error: ${(error as Error).message}`);
+    }
+
+    // Schedule next poll
+    setTimeout(poll, pollIntervalMs);
+  };
+
+  // Start polling
+  setTimeout(poll, pollIntervalMs);
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
+/**
+ * Emit a state change event in the appropriate format
+ */
+function emitStateChange(
+  output: Output,
+  txId: string,
+  fromState: TransactionState | null,
+  toState: TransactionState,
+  timestamp: number
+): void {
+  const time = new Date(timestamp * 1000).toISOString();
+
+  switch (output['mode']) {
+    case 'json':
+      // NDJSON format for easy parsing
+      console.log(
+        JSON.stringify({
+          event: 'state_change',
+          txId,
+          fromState,
+          toState,
+          timestamp: time,
+          unix: timestamp,
+        })
+      );
+      break;
+
+    case 'quiet':
+      console.log(toState);
+      break;
+
+    case 'human':
+    default:
+      if (fromState) {
+        console.log(
+          `${fmt.dim(time)} ${formatState(fromState)} ${fmt.dim('->')} ${formatState(toState)}`
+        );
+      } else {
+        console.log(
+          `${fmt.dim(time)} ${fmt.dim('Current:')} ${formatState(toState)}`
+        );
+      }
+      break;
+  }
+}
+
+export { runWatch };