Specify usage SSE event schema and reconnect behaviour

[greatest0fallt1me]

Summary

docs/usage-sse.md does not match UsageSseEventPayload (fields, amountUsdc as number, the 'connected' event) and says nothing about heartbeats, reconnection or per-user limits.

Why this matters

Frontend developers building live usage dashboards must reverse-engineer the stream.

Scope

Document each event name, payload fields with types, id semantics, current lack of heartbeat/replay, and authentication requirements, with a browser EventSource example.

Relevant code in CalloraOrg/Callora-Backend:

• docs/usage-sse.md
• src/routes/usage/sse.ts

Priority

Low

Acceptance criteria

• Every field in UsageSseEventPayload is documented
• The 'connected' event is described
• Reconnect behaviour is stated accurately
• A working client snippet is included

Validation

Compare with npm test -- src/routes/usage/sse.test.ts fixtures.

Non-goals

• Typo-only, formatting-only, or cosmetic changes.
• Unrelated refactors, dependency upgrades, or broad rewrites.
• Removing safeguards or weakening validation to make tests pass.

Contributor application

Before coding, describe the affected modules, proposed state/invariant changes, test strategy, compatibility considerations, and an estimate. Wait for assignment before starting implementation.

PR requirements

Use a feature branch and include Closes #<issue-number>. Address every criterion, map criteria to code and tests, explain security and failure-mode handling, and ensure CI passes.

Quality review

A maintainer will assess correctness, completeness, test depth, compatibility, observability, and adverse-case handling. A substantive implementation is required; merge or CI status alone does not guarantee reward eligibility.

---

Generated by Claude Code

[shobhamerabacha-star]

Hi there,

I would love to take this on. My planned approach:

• Implement backend logic for Specify usage SSE event schema and reconnect behaviour with strict schema validation and idempotent execution.
• Cover route handlers with automated endpoint integration tests.

Happy to pick this up today—please assign to me!

[Praiz089017]

@Praiz089017 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I would love to resolve this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Praiz089017 to this issue.

[onyekachi66]

@onyekachi66 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I would like to work on this issue having worked on similar issues in the past. Please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @onyekachi66 to this issue.

[Zikrullah001]

@Zikrullah001 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I’d like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Zikrullah001 to this issue.

[sksneh]

@sksneh has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Please sir assign me this issue. Thanks for your consideration

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sksneh to this issue.