Document /v1/call pricing, headers and billing timing

[greatest0fallt1me]

Summary

README mentions the proxy briefly, but nothing documents how /v1/call resolves API slugs, how endpoint prices are matched, which headers are stripped (authorization, cookie, x-forwarded-for), that only 2xx responses are billed, and that billing occurs after the response finishes.

Why this matters

API consumers are surprised by stripped Authorization headers and cannot predict charges; developers cannot configure pricing correctly.

Scope

Create docs/gateway-proxy.md covering request flow from createProxyRouter's comment, stripping rules, pricing resolution, billing trigger conditions, rate-limit layers and error responses (401/402/404/429/502/504).

Relevant code in CalloraOrg/Callora-Backend:

• README.md
• src/routes/proxyRoutes.ts
• src/data/apiRegistry.ts
• docs/gateway-api-key-auth.md

Priority

Medium

Acceptance criteria

• The strip header list matches DEFAULT_STRIP_HEADERS
• Pricing examples match resolveEndpointPrice behaviour
• Billed vs unbilled responses are listed
• The doc is linked from README

Validation

Check examples against npm test -- src/__tests__/proxy.integration.test.ts.

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

[Peolite001]

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

i would love to work on this issue

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

[Bilalishaq7]

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

After going through the issue and its requirements, I’m confident I can implement the requested changes while following the expected design and acceptance criteria. I’d appreciate the opportunity to work on it.

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

[drips-wave]

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

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