feat: require currency and network for all commands

[rolznz]

Follow up from #42

examples:

• npx @getalby/cli pay hello@getalby.com --amount 5 --currency USD --network lightning
• npx @getalby/cli receive --amount 5 --currency USD --network lightning
• npx @getalby/cli receive --amount 21 --currency BTC --network lightning --unit sats
• npx @getalby/cli pay 0x78C0...67bC --amount 2 --currency USDC --network arbitrum

this change:

• removes the inconsistency in the amount vs amount-sats
• to be consistent, also requires currency and network to be passed. For BTC, unit is required, to avoid any possible confusion between BTC & sat amounts.
• enables auto-conversion to send/receive sats based on a fiat amount
• adds future network support (e.g. on-chain btc)
• also removes info from the readme you can get from the help command in the CLI directly
• updates lendaswap SDK (breaking change)

Summary by CodeRabbit

• New Features

  • Unified amount input format across all commands using --amount, --currency, --unit, and --network options instead of command-specific amount flags
  • Support for flexible denomination specifications (sats, BTC, fiat currencies) with automatic conversion

• Documentation

  • Simplified README with clearer CLI descriptions and wallet operation details
  • Updated command help text and examples

• Dependencies

  • Updated SDK dependency

• Tests

  • Added comprehensive test coverage for amount validation and denomination handling

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the Alby CLI's amount handling across payment and invoice commands. It introduces a unified src/amount.ts library for strict numeric parsing and multi-rail classification (lightning, fiat, crypto), then updates all amount-bearing commands to accept --amount, --currency, --unit, and --network flags instead of sats-only options. Tests are expanded to validate the new model, and documentation is updated accordingly.

Changes

Amount Parsing and Multi-Rail Command Refactor

Layer / File(s)	Summary
Amount parsing and rail classification library src/amount.ts	Introduces strict parseAmountNumber that rejects non-finite/non-positive values, models payment rails (bitcoin/fiat/crypto), provides classifyRail to validate currency/unit/network combinations, and exports resolveToSats and resolveLightningSats for unit/amount conversion with whole-sat enforcement and fiat rate resolution.
Lightning invoice and payment commands src/commands/make-invoice.ts, src/commands/make-hold-invoice.ts, src/commands/pay-invoice.ts, src/commands/pay-keysend.ts, src/commands/request-invoice-from-lightning-address.ts, src/commands/receive.ts	Replace --amount-sats with unified --amount/--currency/--unit/--network, resolve to sats via resolveLightningSats, and augment output with optional fiat metadata when present.
Fiat denomination and crypto payment commands src/commands/fiat-to-sats.ts, src/commands/sats-to-fiat.ts, src/commands/pay-crypto.ts, src/commands/fetch.ts	Update to use shared amount validation and rail classification: fiat commands accept --unit to convert BTC/fiat, pay-crypto enforces crypto-only rails and rejects lightning, and fetch validates --max-amount with strict sats-only denomination via classifyRail.
Unified pay command refactor src/commands/pay.ts	Refactors to validate per-destination flag requirements (lightning/lightning-address/keysend/EVM), resolve lightning amounts via resolveLightningSats, enforce destination-specific constraints (reject --unit for crypto), and augment outputs with amount_in_sats and fiat data for lightning destinations.
Amount model validation test suite src/test/amount-model.test.ts, src/test/fetch-max-amount.test.ts	Adds comprehensive tests asserting required --currency/--network, unit validation for BTC vs fiat, whole-number enforcement, BTC-to-sats conversion rules, and lightning-only network rejection; validates --max-amount strict parsing.
Test suite updates for all commands src/test/pay-command.test.ts, src/test/receive-command.test.ts, src/test/pay-crypto.test.ts, src/test/lightning-tools.test.ts, src/test/nwc-payments.test.ts, src/test/nwc-hold-invoices.test.ts	Update test invocations to use new flag scheme, adjust error-message expectations for unified parsing, and expand integration coverage for fiat conversion and multiple destination types.
Utilities cleanup, documentation, and infrastructure updates src/utils.ts, README.md, AGENTS.md, src/index.ts, src/lendaswap/swap.ts, src/tools/lightning/discover.ts, src/tools/lightning/fetch.ts, package.json	Remove old parseSatsOption utility, update README with new CLI guidance and --amount flag usage, add writing-style guidance for "lightning" casing, normalize documentation comments, update help examples, fix maxAmount passthrough, and bump @lendasat/lendaswap-sdk-pure dependency.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• getAlby/cli#40: Modifies pay/receive command implementations and CLI option wiring for amount validation and required flag handling.
• getAlby/cli#45: Introduces parseSatsOption and reverts to --amount-sats-style parsing, directly opposing this PR's amount parsing refactor.
• getAlby/cli#31: Modifies pay-invoice command wiring; changes likely interact with the unified amount/currency/unit/network refactor.

Suggested reviewers

• bumi
• reneaaron

---

🐰 A lightning-swift refactor hops through the CLI,
With currencies flowing and units unified,
Each destination now takes what it needs—
Sats, fiat, or tokens—the rabbit succeeds! ⚡

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main objective of this PR: requiring currency and network parameters across all CLI commands as a central feature.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/required-currency-network-2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/commands/make-invoice.ts (1)

10-19: 🏗️ Heavy lift

Duplicated amount/currency/unit/network option wiring across commands.

This exact --amount/--currency/--network/--unit block (with identical descriptions and parseAmountNumber) is repeated verbatim in make-hold-invoice, pay-keysend, pay-invoice, request-invoice-from-lightning-address, and receive. Extracting a small Commander helper (e.g. addLightningAmountOptions(cmd)) would keep the descriptions and validation consistent as they evolve. Flagging here as the root; the same applies to the other five files.

♻️ Sketch of a shared helper

// src/amount.ts (or a commander-options helper)
export function addLightningAmountOptions(cmd: Command, { requireAmount = true } = {}) {
  const add = requireAmount ? cmd.requiredOption.bind(cmd) : cmd.option.bind(cmd);
  add("--amount <number>", "Invoice amount", parseAmountNumber);
  // ...currency/network/unit
  return cmd;
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/make-invoice.ts` around lines 10 - 19, The repeated
.requiredOption block for --amount/--currency/--network/--unit across commands
should be extracted into a shared helper (e.g., export function
addLightningAmountOptions(cmd: Command, { requireAmount = true } = {})) that
binds either requiredOption or option based on requireAmount, wires the same
descriptions and parseAmountNumber for --amount, and returns the cmd; replace
the duplicated blocks in make-invoice, make-hold-invoice, pay-keysend,
pay-invoice, request-invoice-from-lightning-address, and receive with calls to
addLightningAmountOptions and export the helper from a new module (e.g.,
src/amount.ts or a commander helper) so all commands share the exact option
wiring and validation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/make-invoice.ts`:
- Around line 10-19: The repeated .requiredOption block for
--amount/--currency/--network/--unit across commands should be extracted into a
shared helper (e.g., export function addLightningAmountOptions(cmd: Command, {
requireAmount = true } = {})) that binds either requiredOption or option based
on requireAmount, wires the same descriptions and parseAmountNumber for
--amount, and returns the cmd; replace the duplicated blocks in make-invoice,
make-hold-invoice, pay-keysend, pay-invoice,
request-invoice-from-lightning-address, and receive with calls to
addLightningAmountOptions and export the helper from a new module (e.g.,
src/amount.ts or a commander helper) so all commands share the exact option
wiring and validation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 08cc7b48-135b-4b35-8ba6-a86297d9cbb0

📥 Commits

Reviewing files that changed from the base of the PR and between d524d28 and f036659.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (29)

• AGENTS.md
• README.md
• package.json
• src/amount.ts
• src/commands/fetch.ts
• src/commands/fiat-to-sats.ts
• src/commands/make-hold-invoice.ts
• src/commands/make-invoice.ts
• src/commands/pay-crypto.ts
• src/commands/pay-invoice.ts
• src/commands/pay-keysend.ts
• src/commands/pay.ts
• src/commands/receive.ts
• src/commands/request-invoice-from-lightning-address.ts
• src/commands/sats-to-fiat.ts
• src/index.ts
• src/lendaswap/swap.ts
• src/test/amount-model.test.ts
• src/test/amount-sats-parsing.test.ts
• src/test/fetch-max-amount.test.ts
• src/test/lightning-tools.test.ts
• src/test/nwc-hold-invoices.test.ts
• src/test/nwc-payments.test.ts
• src/test/pay-command.test.ts
• src/test/pay-crypto.test.ts
• src/test/receive-command.test.ts
• src/tools/lightning/discover.ts
• src/tools/lightning/fetch.ts
• src/utils.ts

💤 Files with no reviewable changes (1)

• src/test/amount-sats-parsing.test.ts