Support app deep-link via URL hash

[pietro909]

Summary by CodeRabbit

• New Features
  • Deep linking via URL hash to open specific apps and pass query data.
  • Startup flow honors deep links to route users directly to wallet redemption, Boltz, Lendasat, or Lendaswap.
  • Deep links and legacy voucher note handling coexist: both sharing direct app routes and redeeming notes are supported.

[coderabbitai]

Walkthrough

Adds a URL hash deep-link parser and threads deep-link state through FlowContext; WalletProvider reads the parsed deep link on startup, clears the hash, stores it in context, and adjusts initial navigation to prefer voucher redemption, then app-specific routes, otherwise default Wallet.

Changes

Cohort / File(s)	Summary
Deep link utility src/lib/deepLink.ts	New exported function deepLinkInUrl() that reads window.location.hash (without #), expects app+{app_id}?{query}, and returns { appId: string; query: string } or undefined on parse failure.
Flow context state management src/providers/flow.tsx	Added DeepLinkInfo interface (appId, optional query). Extended FlowContextProps and default FlowContext to include `deepLinkInfo: DeepLinkInfo
Wallet provider integration src/providers/wallet.tsx	On load, calls deepLinkInUrl(), clears the hash, calls setDeepLinkInfo with result. Startup navigation: if voucher (noteInfo.satoshis) present → navigate to redeem; else if deepLinkInfo present → route to app pages (boltz, lendasat, lendaswap) based on appId; otherwise navigate to Wallet. Consumes deepLinkInfo and setDeepLinkInfo from FlowContext.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant WalletProvider
    participant FlowContext
    participant deepLink as deepLinkInUrl()

    Browser->>WalletProvider: Page load (URL may contain hash)
    activate WalletProvider

    WalletProvider->>deepLink: deepLinkInUrl()
    activate deepLink
    deepLink->>deepLink: Read hash, parse "app+{appId}?{query}"
    deepLink-->>WalletProvider: Return {appId, query} or undefined
    deactivate deepLink

    WalletProvider->>FlowContext: clear URL hash
    opt Deep link parsed
        WalletProvider->>FlowContext: setDeepLinkInfo({appId, query})
    end

    WalletProvider->>WalletProvider: Inspect noteInfo.satoshis
    alt Voucher present
        WalletProvider->>Browser: Navigate -> Redeem
    else No voucher, deep link present
        WalletProvider->>Browser: Navigate -> app route (boltz/lendasat/lendaswap)
    else No voucher, no deep link
        WalletProvider->>Browser: Navigate -> Wallet
    end

    deactivate WalletProvider

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Inspect deepLinkInUrl for edge cases (missing/malformed hash, empty appId, query absent).
• Verify FlowContext typing and default value shape match usage sites.
• Review WalletProvider startup routing precedence and that the URL hash is reliably cleared after processing.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Support app deep-link via URL hash' directly describes the main change: adding deep-link support functionality via URL hash parsing. It is concise, specific, and accurately represents the primary purpose of the changeset across all three modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 291e8ad and f013afa.

📒 Files selected for processing (1)

• src/lib/deepLink.ts (1 hunks)

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

• src/lib/deepLink.ts

---

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: 1

🧹 Nitpick comments (1)

src/providers/wallet.tsx (1)

93-109: Update comment to reflect both deep link and ark note handling.

The comment on line 93 only mentions ark notes, but this effect now handles both deep links and ark notes from the URL hash.

Consider updating the comment to:

-  // if ark note is present in the URL, decode it and set the note info
+  // if deep link or ark note is present in the URL, parse and set the respective info

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b2393aa and 291e8ad.

📒 Files selected for processing (3)

• src/lib/deepLink.ts (1 hunks)
• src/providers/flow.tsx (5 hunks)
• src/providers/wallet.tsx (3 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-06-30T18:33:29.839Z

Learnt from: bordalix
Repo: arkade-os/wallet PR: 114
File: src/lib/asp.ts:0-0
Timestamp: 2025-06-30T18:33:29.839Z
Learning: In src/lib/asp.ts, only the collaborativeExit function should accept both IWallet and ServiceWorkerWallet types. Other wallet functions (getBalance, getTxHistory, getReceivingAddresses, redeemNotes, sendOnChain, settleVtxos) should maintain their original IWallet-only signatures and not be updated for consistency.

Applied to files:

• src/providers/wallet.tsx

🧬 Code graph analysis (1)

src/providers/wallet.tsx (4)

src/providers/flow.tsx (1)

• FlowContext (89-104)

src/lib/deepLink.ts (1)

• deepLinkInUrl (1-9)

src/lib/arknote.ts (1)

• arkNoteInUrl (8-11)

src/lib/logs.ts (1)

• consoleError (40-44)

🪛 Biome (2.1.2)

src/lib/deepLink.ts

[error] 6-6: Unsafe usage of optional chaining.

If it short-circuits with 'undefined' the evaluation will throw TypeError here:

(lint/correctness/noUnsafeOptionalChaining)

🔇 Additional comments (2)

src/providers/wallet.tsx (1)

111-133: Verify navigation effect should re-run on state changes.

This effect will re-trigger navigation whenever noteInfo.satoshis or deepLinkInfo change, even after the initial load. Since the URL hash parsing only runs once (lines 94-109), this is probably fine in practice. However, if these context values are modified elsewhere in the app for other purposes, it could cause unexpected navigation.

Consider whether this effect should only run once on initial load:

const hasNavigated = useRef(false)

useEffect(() => {
  if (!initialized || hasNavigated.current) return
  hasNavigated.current = true
  
  if (noteInfo.satoshis) {
    navigate(Pages.NotesRedeem)
    return
  }
  // ... rest of navigation logic
}, [initialized])

Or confirm that the current behavior of re-navigating on state changes is intentional.

src/providers/flow.tsx (1)

16-19: LGTM! Clean context additions for deep link support.

The DeepLinkInfo interface and context integration follow the established patterns in this file. The optional query field correctly matches the behavior of deepLinkInUrl() where query parameters may not be present.

Also applies to: 50-50, 57-57, 92-92, 99-99, 109-109, 120-120, 127-127