fix: keep proxy usage recording and billing consistent

[samueloyibodevv]

Overview

This PR fixes the /v1/call proxy metering flow so usage recording and billing deduction stay consistent instead of diverging under partial failure. It anchors recordable proxy charging to the request ID, ensures a successful recordable call yields one matching usage event and one deduction or neither, and logs reconciliation paths explicitly when follow-up repair may be needed.

Related Issue

Closes #322

Changes

⚙️ Proxy Usage/Billing Consistency

• [MODIFY] src/routes/proxyRoutes.ts
• Reworked the post-proxy charging flow to anchor billing on requestId when the billing backend supports it.
• Records the in-memory usage view only after a matching charge succeeds.
• Prevents the old drift path where usage could be recorded before a later deduction failure.
• Added explicit reconciliation logging for post-charge view write failures.

💳 Billing Surface

• [MODIFY] src/types/gateway.ts

• Added requestId-anchored usage charge request/result types.

• Extended the billing interface with optional chargeUsage(...) support for consistent proxy charging.

• [MODIFY] src/services/billingService.ts

• Added requestId-aware chargeUsage(...) support to the in-memory/mock billing implementation.

• Added deterministic failure injection helpers for integration tests.

• Preserved idempotent behavior when the same request is charged more than once.

• [MODIFY] src/services/billing.ts

• Surfaced richer billing deduction outcome metadata, including whether reconciliation is required.

• Preserved the durable usage-event anchor behavior for requestId-backed billing flows.

🔐 Auth and Header Handling

• [MODIFY] src/middleware/gatewayApiKeyAuth.ts
• Prioritized explicit x-api-key extraction over bearer auth when both are present so proxy auth and header-safety scenarios behave consistently.

🧪 Tests

• [MODIFY] src/__tests__/proxy.integration.test.ts

• Added coverage for anchored charging failure leaving both usage and balance untouched.

• Updated proxy response assertions to match the standardized error payload shape.

• Kept request/response proxy safety coverage aligned with current transport behavior.

• [MODIFY] src/__tests__/usageMetering.test.ts

• Added coverage for anchored charging failure yielding neither usage nor deduction.

• Added coverage for the reconciliation log path when billing succeeds but the in-memory usage view write fails.

📚 Documentation

• [MODIFY] README.md
• Documented the new requestId-anchored proxy charging behavior and reconciliation logging path.

Verification Results

Acceptance Criteria	Status
A recordable call yields one usage event and one deduction, or neither	✅
Deduction failure after recording is logged and retryable	✅
Integration tests cover the failure path	✅
Proxy metering remains idempotent by requestId when supported	✅
Targeted proxy integration tests pass successfully	✅
Typecheck passes successfully	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Run the proxy consistency tests
npm test -- src/__tests__/proxy.integration.test.ts src/__tests__/usageMetering.test.ts

# 3. Verify TypeScript types
npm run typecheck

# 4. Optional: inspect the changed files
git diff -- src/routes/proxyRoutes.ts src/services/billing.ts src/services/billingService.ts src/types/gateway.ts src/middleware/gatewayApiKeyAuth.ts README.md

Screenshots

✅ Proxy consistency tests pass

A screenshot of:

npm test -- src/__tests__/proxy.integration.test.ts src/__tests__/usageMetering.test.ts

[drips-wave]

@samueloyibodevv Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits