feat(streams): client-side amount validation, list() union, forceCancel + transferRecipient wrappers

[TemiMustapha]

Summary

Four StreamsModule enhancements from the Stellar Wave program, each previously either silently wrong, unguarded, or only a prose TODO:

1. Enhancement: withdraw()/topUp() don't validate amount > 0n client-side, unlike create()'s validation #451 — withdraw() / topUp() now reject amount <= 0n client-side, before any RPC round-trip, matching the fail-fast validation create() already applies (src/builder.ts philosophy: "mandatory client-side validation prevents invalid payloads from reaching the smart contract"). Zero/negative amounts previously went straight into the contract call and only failed after a full simulate+reject cycle surfacing StreamErrorCode.InvalidAmount.

2. Enhancement: list() silently ignores recipient when both sender and recipient are provided #452 — list() no longer silently drops recipient when both sender and recipient are provided. The if (sender) { ... } else if (recipient) { ... } chain returned sender-only results with no indication anything was ignored. Both filters are now queried concurrently and merged into a de-duplicated union (streams where the address is either sender or recipient). Documented in docs/api.md and README.md.

3. Enhancement: StreamsModule has no wrapper for force_cancel(), and StreamErrorCode.PauseThresholdNotMet is unreachable through the SDK #453 — New StreamsModule.forceCancel(streamId) wrapping the contract's DripStream::force_cancel(). Recipients can now force-cancel a stream paused beyond the 30-day threshold; it settles atomically like cancel() (earned tokens → recipient, remainder → sender). This also makes StreamErrorCode.PauseThresholdNotMet reachable through the SDK for the first time — previously nothing in streams.ts invoked force_cancel, so that error code could never be thrown via a public SDK call path.

4. Enhancement: StreamsModule has no wrapper for transfer_recipient() #454 — New StreamsModule.transferRecipient(streamId, newRecipient) wrapping the contract's DripStream::transfer_recipient(). The current recipient can reassign the recipient role (including accrued withdrawable balance) without dropping to raw buildContractCallTx/invokeContract calls. Validates the new recipient address client-side.

Changes

src/streams.ts

• withdraw(): guard amount !== undefined && amount <= 0n → throws 'Invalid amount: must be greater than zero'. The omitted-amount path (defaults to full withdrawable balance) is unaffected — a zero balance there still correctly surfaces NothingToWithdraw.
• topUp(): guard amount <= 0n → throws before any RPC call (also covers topUpStream() and per-item batchWithdraw() failures).
• list(): when both filters are present, fetch streamsBySender + streamsByRecipient concurrently and return [...new Set([...senderIds, ...recipientIds])].
• forceCancel(streamId): _invoke → force_cancel (no args).
• transferRecipient(streamId, newRecipient): validates a non-empty recipient, _invoke → transfer_recipient with the new Address ScVal.
• Updated JSDoc for list().

Tests (src/tests/streams.test.ts, src/tests/streams-success.test.ts)

• Zero/negative amount rejection for withdraw, topUp, topUpStream, and per-item batchWithdraw failure reporting.
• Omitted-amount withdraw() still defaults to the withdrawable balance.
• list() with both filters: queries both factory methods with the same offset/limit, and returns the de-duplicated union.
• forceCancel() / transferRecipient(): keypair guard, success paths returning the tx hash, transfer_recipient invoked with the new recipient address, and PauseThresholdNotMet / NotPaused mapped to ConduitError codes 13 / 10.
• transferRecipient() empty / whitespace recipient rejection.

Docs

• docs/api.md: new forceCancel / transferRecipient sections, union semantics + client-side validation notes on list / withdraw / topUp.
• docs/architecture.md: module map updated; "What's not wrapped yet" now lists only streamed_total.
• README.md: new method sections, list() union note.
• CHANGELOG.md: [Unreleased] → Added (both wrappers), Fixed (Enhancement: withdraw()/topUp() don't validate amount > 0n client-side, unlike create()'s validation #451, Enhancement: list() silently ignores recipient when both sender and recipient are provided #452); removed the two completed items from Planned.

Verification

• npx tsc --noEmit — clean
• npx vitest run — 740 passed, 2 skipped (58 files)

Closes #451, Closes #452, Closes #453, Closes #454

[drips-wave]

@TemiMustapha Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Jaydbrown]

Thanks for the contribution here — squash-merging this now. Any follow-ups we'll track in a fresh issue. 🚀