feat: make units clear across all commands

[rolznz]

remove any possible confusion for the AI to spend using the wrong unit or currency.

Fixes #42

Summary by CodeRabbit

• CLI Changes

  • Renamed Lightning amount flags across commands: --amount → --amount-sats; --max-amount → --max-amount-sats. Improved cross-flag validation and clearer error messages.

• Documentation

  • README and CLI examples updated to reflect new flags and version bump.

• Tests

  • Test suites updated and expanded to enforce strict sats parsing and validate new flag behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3d8cc712-5603-4f37-ae5c-5465e141533e

📥 Commits

Reviewing files that changed from the base of the PR and between a3a07c8 and 3b29788.

📒 Files selected for processing (16)

• src/commands/fetch.ts
• src/commands/fiat-to-sats.ts
• src/commands/make-hold-invoice.ts
• src/commands/make-invoice.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/test/amount-sats-parsing.test.ts
• src/test/lightning-tools.test.ts
• src/test/pay-command.test.ts
• src/test/pay-crypto.test.ts
• src/test/receive-command.test.ts
• src/utils.ts

✅ Files skipped from review due to trivial changes (1)

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

🚧 Files skipped from review as they are similar to previous changes (7)

• src/commands/make-hold-invoice.ts
• src/commands/sats-to-fiat.ts
• src/commands/pay-keysend.ts
• src/test/receive-command.test.ts
• src/test/pay-command.test.ts
• src/commands/make-invoice.ts
• src/commands/receive.ts

---

📝 Walkthrough

Walkthrough

Rename Lightning amount flags to --amount-sats across CLI commands, add strict sats parsing (parseSatsOption), update pay destination validation to distinguish sats vs crypto amounts, and update tests, README, and version to 0.8.0.

Changes

Amount flag currency suffixing refactor

Layer / File(s)	Summary
Lightning payment & invoice flags and wiring 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, src/commands/sats-to-fiat.ts	Core Lightning commands now accept --amount-sats and wire options.amountSats into amount_in_sats for invoice creation and payments.
Pay command routing and validation src/commands/pay.ts	pay now enforces --amount-sats for Lightning destinations and keeps --amount for crypto; cross-flag validation emits specific errors when flags are misapplied.
Sats parser, fetch, and utility commands src/utils.ts, src/commands/fetch.ts, src/commands/fiat-to-sats.ts, src/commands/pay-crypto.ts	Introduce exported parseSatsOption(allowZero?) for strict whole-number sats parsing; fetch uses --max-amount-sats; fiat/pay-crypto option parsing adjusted (short alias removals / Number parser changes).
Tests, docs, and version bump src/test/*, README.md, src/index.ts, package.json	All tests updated to new flags and added strict parsing tests; README and CLI help examples updated; version bumped to 0.8.0.

Sequence Diagram

sequenceDiagram
  participant User as CLI User
  participant Parser as Option Parser
  participant Utils as parseSatsOption
  participant Invoice as Invoice Service
  participant Payment as Payment Service
  User->>Parser: make-invoice --amount-sats 100
  Parser->>Utils: validate & parse "100"
  Parser->>Invoice: create(amount_in_sats: 100)
  Invoice-->>User: BOLT-11 invoice
  User->>Parser: pay <bolt11> --amount-sats 100
  Parser->>Payment: payInvoice(amount_in_sats: 100)
  Payment-->>User: payment result

Loading

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly Related PRs

• getAlby/cli#39: Touches pay-crypto --amount wiring; related to short-form/crypto amount handling changes.
• getAlby/cli#40: Earlier updates to pay/receive amount flags; closely related to this rename and validation work.

Suggested Reviewers

• bumi
• reneaaron

🐰
I hop through flags with tiny paws,
I count whole sats and fix the cause,
Now commands sing in clearer chats,
No fuzzy cents — just tidy sats! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.67% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly summarizes the main change: renaming amount flags to explicitly indicate units (sats vs currency) across CLI commands.
Linked Issues check	✅ Passed	The PR fully addresses issue #42 by renaming all lightning-related amount flags to --amount-sats to clarify units, while maintaining --amount for crypto payments, removing ambiguity about which unit applies.
Out of Scope Changes check	✅ Passed	All changes directly address the linked objective of clarifying amount units across commands; no out-of-scope changes detected.

_{✏️ 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 fix/clear-units

---

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]

Actionable comments posted: 4

🤖 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.

Inline comments:
In `@src/commands/fetch.ts`:
- Around line 16-18: The CLI currently uses parseInt for "--max-amount-sats"
which lets malformed inputs like "0.5" become 0 and bypass the cap; replace
parseInt in the fetch command option with a strict parser (e.g., a parseSats
function) that only accepts non-negative integer strings (validate /^\d+$/ or
Number.isInteger after parsing) and throws/returns an error for invalid input,
and also change the conversion in src/tools/lightning/fetch.ts that currently
uses "maxAmount: maxAmountSats || undefined" to a null/undefined check (e.g.,
"maxAmount: maxAmountSats === 0 ? undefined : maxAmountSats" or "maxAmount:
maxAmountSats == null ? undefined : maxAmountSats") so a valid 0 is treated as
"no limit" while malformed inputs are rejected.

In `@src/commands/fiat-to-sats.ts`:
- Line 10: The .requiredOption("--amount <n>", "Fiat amount", parseFloat)
currently allows partial numeric strings; replace the parseFloat parser with a
custom validator used in the same .requiredOption call that first tests the raw
input against a strict decimal regex (e.g. ^[+-]?\d+(\.\d+)?$ or a variant that
fits your allowed formats) and only then returns Number(input) /
parseFloat(input); if the input does not fully match the regex throw an
Error("Invalid value for --amount: <value>") so commander surfaces a parsing
error. Ensure you update the same .requiredOption("--amount <n>", ...)
invocation and validate the whole string before converting.

In `@src/commands/pay.ts`:
- Around line 91-95: Create a shared strict sats parser/validator (e.g.,
parseSatsStrict or validateSats) and replace all ad-hoc parsing in pay.ts and
the lightning command files (make-invoice, pay-invoice, pay-keysend,
make-hold-invoice, receive, request-invoice-from-lightning-address) so every
--amount-sats option uses that helper; the helper should accept a flag to
allowZero (for zero-amount invoice paths) and enforce whole integer sats (no
scientific notation or trailing text), return a normalized Number or throw/emit
a consistent CLI error on invalid input, and then update option definitions
(currently using Number or parseInt) and any post-parse checks (e.g.,
Number.isInteger and >0) to call this single function for identical behavior
across all commands.

In `@src/commands/sats-to-fiat.ts`:
- Line 9: Replace the loose parseInt usage for the commander option
requiredOption("--amount-sats <sats>", parseInt) with a strict parser that
validates the input matches /^\d+$/ and then returns Number(value); if the check
fails, throw an Error so the CLI exits with a clear validation message —
implement this as the option's custom parser function (e.g., function
parseSats(value) { if (!/^\d+$/.test(value)) throw new Error("amount-sats must
be a whole number of sats"); return Number(value); }) and use parseSats in place
of parseInt.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d24f416d-c9f9-45aa-987b-8fa48734c26a

📥 Commits

Reviewing files that changed from the base of the PR and between c278266 and a3a07c8.

📒 Files selected for processing (19)

• README.md
• package.json
• 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/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/receive-command.test.ts

[rolznz]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.