[Feldspar] Add error handling to donate flow

[mellelieuwes]

Summary

• Add error/success feedback from donate_via_api back to Feldspar iframe via MessageChannel
• Handle network errors, HTTP errors, and invalid server responses
• Send DonateSuccess or DonateError messages with status and error details

Context

The donate flow was "fire and forget" - users received no feedback when donations failed. A client (Wouter from VU) was experiencing missing data and couldn't determine if errors occurred client-side or server-side.

Changes

• Modified donate_via_api() to capture fetch response
• Added sendDonateResponse() helper to send messages through the channel
• Response types: DonateSuccess and DonateError with __type__, key, status, and error fields

Test plan

• Test successful donation - should receive DonateSuccess message
• Test network failure (offline) - should receive DonateError with network error
• Test server error (e.g., 422) - should receive DonateError with server error message
• Deploy to test server for Wouter to verify

Fixes: Feldspar issue "Error feedback" (ID: 9521654246)
Milestone: Hotfix 20.3 - Feldspar Error Handling

🤖 Generated with Claude Code

[mellelieuwes]

Architecture Review

Overall, this is a solid implementation that addresses the core problem.

What I like:

• Consistent use of __type__ for message typing - matches the existing Feldspar protocol pattern
• Clean separation of error scenarios: network errors vs HTTP errors vs parse errors
• Including key in responses allows the Feldspar app to correlate requests with responses
• The sendDonateResponse helper properly guards against missing channel

Minor considerations:

• Status code semantics: Using status: 0 for network errors is a reasonable convention (similar to XMLHttpRequest), but consider documenting this contract for the Feldspar team
• JSON parse failure: If the server returns a 200 with non-JSON body (unlikely but possible), we'd report an error despite success. This is acceptable for now - better to over-report errors than hide them

Future improvements (not blocking):

• Consider adding a timestamp field to responses for debugging timing issues
• The Feldspar app could implement retry logic for transient network errors

Verdict: ✅ Approve - This change is minimal, focused, and solves the immediate debugging problem. Ship it.

— Theo (Software Architect)

[mellelieuwes]

Thanks @theo for the review!

I've addressed the documentation feedback - added a comment block above donate_via_api that documents:

• The response contract (DonateSuccess and DonateError message shapes)
• The status=0 convention for network errors

The future improvements (timestamp field, retry logic) make sense but I agree they're not blocking for this hotfix. We can revisit those when we work on the Feldspar app side.

— Alex (Full-Stack Developer)