Add a contract-test suite that verifies billing/deduct OpenAPI matches implementation

[greatest0fallt1me]

Description

This is a backend issue for the GrantFox campaign. Use express-openapi-validator to assert that runtime responses match openapi.yaml for /api/billing/deduct.

Requirements and Context

• express-openapi-validator wired
• Test cases for 200/400/409/429
• CI gate
• docs link
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b task/openapi-contract-tests

2. Implement changes
   • tests/contract/billing.test.ts (new)
   • src/openapi.yaml
3. Test and commit
   • Run the repo's standard test suite and lint
   • Cover edge cases; include output in the PR

Example commit message

test: OpenAPI contract tests for /billing/deduct

Acceptance Criteria

• Validator integrated
• Cases pass
• CI gate active
• Docs updated

Guidelines

• Minimum 90% test coverage on changed lines
• Input validation at the boundary; standardized error envelope
• Structured logging with correlation IDs
• Clear documentation and inline comments
• Timeframe: 96 hours

[ositaemmanuel653-netizen]

@ositaemmanuel653-netizen has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I’m a smart contract and full-stack developer who turns complex ideas into secure, production-ready blockchain code.
With strong skills in Rust and Solidity, I build systems that are fast, safe, and built to last.
My experience with the Stellar SDK lets me ship real-world Web3 solutions that actually move value.

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

[Babigdk]

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

I'd like to work on this issue.

I'll begin by reviewing the existing /api/billing/deduct implementation, current test infrastructure, CI workflow, and openapi.yaml definitions to ensure the contract tests validate the actual runtime behavior. Then I'll integrate OpenAPI response validation and build a dedicated contract test suite around the endpoint.

Planned work:

• Integrate express-openapi-validator into the test environment.
• Add contract tests for the expected 200, 400, 409, and 429 responses.
• Verify response payloads conform to the OpenAPI schema, including standardized error envelopes.
• Ensure input validation occurs at the API boundary.
• Add structured logging assertions where applicable, including correlation IDs.
• Configure CI to fail when contract validation tests fail.
• Update documentation with instructions for running contract tests locally and understanding failures.
• Target high coverage on modified code paths and include edge-case scenarios around billing deductions.

This will provide automated protection against API contract drift and ensure /api/billing/deduct remains aligned with the published OpenAPI specification.

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

[drips-wave]

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

🧑‍💻 @Babigdk: 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 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Babigdk's PR #529 was approved and merged by @greatest0fallt1me.

🏆 @Babigdk: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (471 total points). Track your full progress on GrantFox.

👏 Great work, @Babigdk! Keep contributing to CalloraOrg.

[drips-wave]

This issue has been completed by @Babigdk as part of the Stellar Wave Program's 6th Wave 🥳

😎 @Babigdk: You earned 100 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.