Annotate BillingService public methods with TSDoc

[greatest0fallt1me]

Summary

BillingService.deduct, deductBulk and getByRequestId in src/services/billing.ts carry long inline comments but no TSDoc describing parameters, returned flags, thrown errors and concurrency guarantees.

Why this matters

Callers such as the deduct and bulk routes interpret result flags differently, which leads to bugs like reporting pending rows as successes.

Scope

Add TSDoc to each public method and exported helper (parseUsdcToContractUnits, formatContractUnitsToUsdc, isTransientSorobanError) with @PARAM, @returns, @throws and examples.

Relevant code in CalloraOrg/Callora-Backend:

• src/services/billing.ts
• docs/billing-idempotency.md

Priority

Low

Acceptance criteria

• Each public BillingService method has TSDoc
• Result flags are described consistently with docs/billing-idempotency.md
• Exported helpers document precision rules
• npm run lint passes

Validation

Run npm run lint and npm run typecheck.

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]

Hello! I would like to work on this issue.

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Build out the handlers for Annotate BillingService public methods with TSDoc ensuring proper HTTP status codes and error propagation.
• Testing: Add integration test suites for standard invocations and boundary/error conditions.

Looking forward to contributing—please assign whenever convenient!

[Emmzydice1]

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

Hi Maintainer, I’m interested in taking on this issue. I have relevant experience handling similar tasks and am confident I can deliver an effective solution. I’m available to begin immediately and would appreciate the opportunity to work on it. Kindly assign it to me.

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

[drips-wave]

Congratulations, @Emmzydice1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Emmzydice1: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊