docs: explain Bitcoin Connect payment flow lifecycle #24

[naveendhaterwal]

Summary

This PR improves the Bitcoin Connect documentation by adding a clear "Payment Flow Lifecycle" section. It explains how UI components transition during the payment process, addressing the gap identified in #24.

Changes

• Added a Mermaid diagram visualizing the 4-stage lifecycle:
  Start → Requesting Invoice → Paying → Success
• Clearly defined each stage:
  • Start (Idle): Default button state
  • Requesting Invoice: Fetch BOLT-11 invoice after user click
  • Paying: Opens payment modal (Extension, NWC, or Scanner)
  • Success: Auto-detection via WebLN or manual setPaid() for external payments
• Included implementation examples for both Web Components and React to demonstrate programmatic state management

Goal

Provide developers with a clear mental model of the full payment lifecycle to reduce friction when building e-commerce or donation flows.

Fixes #24

Summary by CodeRabbit

• Documentation
  • Added Payment Flow Lifecycle documentation detailing the 4-stage payment process
  • Clarified UI transitions across payment button, invoice request, modal, and success screen states
  • Documented WebLN, NWC, and QR code payment methods and workflows
  • Explained paid status handling for different payment paths
  • Added units clarification (sats vs millisats)

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a "Payment Flow Lifecycle" documentation section to Bitcoin Connect explaining the four-stage user flow: Start/Idle, Requesting Invoice, Paying, and Showing Success Screen. Included details on UI transitions, WebLN/NWC/QR code paths, and paid status surfacing behavior. Also added a clarification on sats vs millisats under Units.

Changes

Cohort / File(s)	Summary
Documentation references/bitcoin-connect/bitcoin-connect.md	Added "Payment Flow Lifecycle" section with 4-stage user flow diagram and explanations for button states, invoice requests, payment modals, and success screens; documented WebLN, NWC, and QR code payment paths; clarified automatic vs. manual paid status updates; added sats vs millisats note under Units section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A button clicks, invoices bloom,
Payment flows dispel the gloom,
From idle start to success displayed,
The rabbit's guide—no path dismayed! 📖✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding documentation for Bitcoin Connect payment flow lifecycle, matching the primary objective of explaining button and modal states.
Linked Issues check	✅ Passed	The PR fully addresses issue #24 by documenting the complete payment flow (start → request invoice → pay → success) with a Mermaid diagram, state explanations, and implementation examples.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #24: documentation additions to bitcoin-connect.md include payment flow lifecycle, state transitions, and a note about sats vs millisats units.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

[naveendhaterwal]

@rolznz sir could you please check this

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@references/bitcoin-connect/bitcoin-connect.md`:
- Around line 76-79: Update the documentation text to state that setPaid
requires a SendPaymentResponse object rather than being called without
arguments; specifically, replace the phrase "call setPaid()" with guidance to
call setPaid(...) passing a SendPaymentResponse (e.g., { preimage: "..." }) so
it matches the API signature and aligns with the example and the onPaid /
bc:onpaid event behavior.

🧹 Nitpick comments (1)

references/bitcoin-connect/bitcoin-connect.md (1)

46-80: Consider noting cancel/error paths in the lifecycle.

The flow is clear for the happy path; adding a brief note about cancellation or failures (e.g., user closes modal, payment rejected) would round out the mental model without adding much complexity.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, let's check if the file exists and read the relevant section
if [ -f "references/bitcoin-connect/bitcoin-connect.md" ]; then
  cat -n "references/bitcoin-connect/bitcoin-connect.md" | sed -n '70,85p'
else
  find . -name "*bitcoin-connect*" -type f | head -20
fi

Repository: getAlby/alby-agent-skill

Length of output: 941

---

🏁 Script executed:

# Search for all setPaid usage patterns in the repository
rg "setPaid" --context 3 -A 2 -B 2

Repository: getAlby/alby-agent-skill

Length of output: 2604

---

🏁 Script executed:

# Look for TypeScript definitions or type files that might define the API
fd -e "\.d\.ts" -e "\.ts" | xargs rg "setPaid" 2>/dev/null | head -20

Repository: getAlby/alby-agent-skill

Length of output: 686

---

🏁 Script executed:

# Search for SendPaymentResponse definition to understand the required payload
rg "SendPaymentResponse" --context 5

Repository: getAlby/alby-agent-skill

Length of output: 14945

---

🏁 Script executed:

# Check the full API documentation section in bitcoin-connect.md to see all examples
cat -n references/bitcoin-connect/bitcoin-connect.md | sed -n '40,120p'

Repository: getAlby/alby-agent-skill

Length of output: 3414

---

Clarify setPaid() requires a payload to match the API signature.

Line 78 says "call setPaid()," but the API requires passing a SendPaymentResponse object. The example at line 122 correctly shows setPaid({ preimage: "..." }). Update the text to match:

Suggested change

-- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid()` to show the success screen in the modal.
+- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid({ preimage })` to show the success screen in the modal.

🤖 Prompt for AI Agents

In `@references/bitcoin-connect/bitcoin-connect.md` around lines 76 - 79, Update
the documentation text to state that setPaid requires a SendPaymentResponse
object rather than being called without arguments; specifically, replace the
phrase "call setPaid()" with guidance to call setPaid(...) passing a
SendPaymentResponse (e.g., { preimage: "..." }) so it matches the API signature
and aligns with the example and the onPaid / bc:onpaid event behavior.