feat(billing): add structured JSON access logs for /api/billing [b#003]

[Stanley471]

Closes #868

Description

This PR implements structured JSON access logging for all /api/billing endpoints as part of the GrantFox FWC26 campaign ([b#003]).

Every request processed by the /api/billing router emits a structured JSON log entry containing request correlation IDs, latency metrics, HTTP status code, request/response byte counts, and actor/developer identity context on the billing Pino logger channel.

---

Key Changes

1. Enhanced Billing Access Log Middleware (src/middleware/billingAccessLog.ts)

• Added explicit access logging properties:
  • req-id: Canonical request correlation ID
  • latency & latencyMs: Request processing duration in milliseconds (3 decimal places)
  • status & statusCode: HTTP status code
  • size & responseBytes: HTTP response body size in bytes
  • requestBytes: Request payload body size in bytes
  • actor: Authenticated user ID (res.locals.authenticatedUser.id) or developer ID (req.params.developerId / req.body.developerId)
• Added stream byte tracking for incoming requestBytes.
• Guaranteed single log entry emission across finish and close response events.
• Enforced case-insensitive field-level redaction ([REDACTED]) for sensitive log fields.

2. Access Log Exports (src/middleware/accessLog.ts)

• Re-exported billingAccessLogMiddleware, createBillingAccessLogMiddleware, billingLogger, and associated types directly from accessLog.ts to provide a unified entry point for all access log middlewares.

3. Route Integration (src/routes/billing.ts)

• Mounted billingAccessLogMiddleware from accessLog.js at the root of the billing router to ensure 100% route coverage (/credits, /disputes, /deduct, /refund, /fee-abstraction, /forecast, /request/:requestId, /).

4. Comprehensive Documentation (docs/BILLING_ACCESS_LOGGING.md)

• Added schema documentation covering all payload fields, example JSON log structures, redaction settings, and import guidelines.

5. Focused Test Coverage

• Unit Tests (src/middleware/billingAccessLog.test.ts): Verified log fields (req-id, latency, status, size, actor), developer fallback, and redaction logic.
• Integration Tests (src/middleware/billingAccessLog.integration.test.ts): Validated end-to-end request/response lifecycle logging on Express routes.
• Middleware Re-export Tests (src/middleware/accessLog.test.ts): Tested re-exported billing access log middleware.

---

Log Output Example

{
  "level": 30,
  "time": 1785178800000,
  "channel": "billing",
  "correlationId": "req-98765",
  "requestId": "req-98765",
  "req-id": "req-98765",
  "method": "POST",
  "path": "/api/billing/deduct",
  "status": 200,
  "statusCode": 200,
  "ms": 12.345,
  "durationMs": 12.345,
  "latency": 12.345,
  "latencyMs": 12.345,
  "requestBytes": 128,
  "responseBytes": 84,
  "size": 84,
  "userId": "dev_user_001",
  "actor": "dev_user_001",
  "clientIp": "127.0.0.1",
  "apiId": "api_weather",
  "endpointId": "ep_forecast",
  "apiKeyId": "ak_12345",
  "amountUsdc": "0.05",
  "billingRequestId": "client_deduct_99",
  "msg": "billing request completed"
}

[drips-wave]

@Stanley471 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

[greatest0fallt1me]

Green across the board — merging. Thanks!