feat(utils): findCashuPayload to locate tokens and payment requests in text

[KvngMikey]

TL;DR

Adds findCashuPayload(text), which locates the first cashu token or payment request inside arbitrary text and returns the encoded payload verbatim. Wallets can drop their hand-rolled URL-prefix tables and regexes.

Fixes #849

Why

Wallets receive payloads buried in whatever the user pasted: chat messages, clipboard blobs, bitcoin: URI parameters, wallet-site URLs. getDecodedToken already handles the clean cases (it strips cashu:, cashu://, web+cashu://), but nothing in the library locates a payload inside text that contains other content. Every wallet ends up maintaining its own curated table of known wallet URL prefixes plus a regex, and those tables rot as the ecosystem churns. Scanning for the payload itself subsumes every wrapper form, so there is no per-wallet knowledge to maintain.

Changes

Two-stage, exactly as specced in #849:

1. Candidate scan: one scanner per prefix (cashuA/cashuB, creqA, creqb1), each a literal prefix plus a single character-class quantifier. No alternation, no nested quantifiers, so no catastrophic backtracking. creqb1 (NUT-26) is matched case-insensitively because QR alphanumeric mode emits the uppercase form.
2. Decode to validate: handleTokens for tokens, PaymentRequest.fromEncodedRequest for requests. A regex alone false-positives; the decoder is the authority. First candidate that decodes, by position, wins.

Notes for review:

• The charset is base64url only ([A-Za-z0-9=_-]), not base64. This is the one place the implementation departs from the issue text, which says "base64/base64url charset". Including + and / is actively wrong: a token in a URL path (example.com/cashuB…/more) has the trailing segment swallowed into the candidate, and base64 decoding ignores what follows the padding while CBOR ignores trailing bytes, so the candidate decodes successfully and the payload comes back as cashuB…/more. The decoders validate the prefix, not the boundary. The cashu specs are base64url throughout (NUT-00 tokens, NUT-18 creqA), so nothing spec-compliant is lost. Regression test pins all three payload types. Happy to revisit if you want the wider charset back.
• Re-entry on failed decode resumes at matchIndex + 1, not match end, so a payload swallowed inside a failed greedy span is still found, the cashuB-inside-cashuA example is a test case.
• Decode-attempt cap: MAX_PAYLOAD_DECODE_ATTEMPTS = 16 in utils/limits.ts, following the house pattern there. Bounds the adversarial prefix-stuffed case to linear total work. The number is a suggestion and is a one-integer change if needed.
• Token validation uses the module-private handleTokens via removePrefix: keyset-free, and avoids getDecodedToken's 5.0 keysetIds requirement, which the finder has no business needing.
• CashuPayloadKind is exported as a named alias for 'token' | 'paymentRequest' so consumers can type against it. Structurally identical to the inline signature in the issue.
• Non-goals honored: no wallet URL table, no multi-match variant, no clipboard/DOM integration, and the returned payload is never normalized (uppercase CREQB1… comes back uppercase — test case).

Docs: new section on the Helpers page; the usage-index Helpers row previously named mint URL normalization as the page's only content, so it is broadened.

Impact

Purely additive, one new function and one new exported type, no existing behavior touched. The API report diff is those two entries and nothing else.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.97%. Comparing base (59d36b1) to head (c4b50dd).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #967      +/-   ##
==========================================
+ Coverage   95.92%   95.97%   +0.04%     
==========================================
  Files          56       56              
  Lines        5961     5984      +23     
  Branches     1516     1521       +5     
==========================================
+ Hits         5718     5743      +25     
+ Misses        103      102       -1     
+ Partials      140      139       -1     

Flag	Coverage Δ
integration	37.29% <13.04%> (-0.10%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a new public helper findCashuPayload(text) to locate the first embedded Cashu token (cashuA/cashuB) or payment request (creqA/creqb1/CREQB1) inside arbitrary text, validate it by decoding, and return the encoded payload verbatim for wallets to process.

Changes:

• Implement findCashuPayload + exported CashuPayloadKind in src/utils/core.ts with a capped number of decode attempts.
• Add MAX_PAYLOAD_DECODE_ATTEMPTS limit in src/utils/limits.ts.
• Add tests and documentation for token/payment-request detection in pasted text and URLs.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/utils/core.test.ts	Adds test coverage for findCashuPayload behavior (wrappers, punctuation, ordering, cap behavior, and URL-path regression).
src/utils/limits.ts	Introduces MAX_PAYLOAD_DECODE_ATTEMPTS to cap decode validations during scanning.
src/utils/core.ts	Implements CashuPayloadKind, scanner regexes, and the findCashuPayload decode-to-validate search loop.
etc/cashu-ts.api.md	Updates API report to include the new exported type and function.
docs-src/usage/usage_index.md	Updates Helpers page description to include token detection.
docs-src/usage/helpers.md	Documents findCashuPayload and shows a basic usage example.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[robwoodgate]

Adversarial pass with executed probes; details inline (this supersedes my earlier summary comment, now removed). Sequencing note: #986 is queued ahead of this PR and makes junk-suffixed candidates fail uniformly on both platforms. Previously they were returned with the junk included (v4/creqA), missed entirely (v3), or platform-dependent (Node Buffer vs browser atob). Please rebase once it merges.

[robwoodgate]

Awesome job, great utility, thanks @KvngMikey .

This will be v5 only, as it may change decoding experience on some platforms, throwing cases that previously passed etc.

[KvngMikey]

Awesome job, great utility, thanks @KvngMikey .

This will be v5 only, as it may change decoding experience on some platforms, throwing cases that previously passed etc.

no problem, as soon as V5 lands, i can make the downstream PRs to capture this.