# Debug Logging Specification

## Goal
Implement comprehensive HTTP request/response logging for debugging API interactions between banks2ff and external services (GoCardless and Firefly III).

## Requirements

### Output Format
Each HTTP request-response cycle generates a single text file with the following structure:

1. **Curl Command** (at the top in comments)
   - Full `curl -v` command that reproduces the exact request
   - Includes all headers, authentication tokens, and request body
   - Properly escaped for shell execution

2. **Complete Request Data**
   - HTTP method and URL
   - All request headers (including Host header)
   - Full request body (if present)

3. **Complete Response Data**
   - HTTP status code and reason
   - All response headers
   - Full response body

### File Organization
- Files stored in `./debug_logs/{service_name}/` directories
- Timestamped filenames: `YYYYMMDD_HHMMSS_REQUESTID.txt`
- One file per HTTP request-response cycle
- Service-specific subdirectories (gocardless/, firefly/)

### Data Visibility
- **No filtering or masking** of any data
- Complete visibility of all HTTP traffic including:
  - Authentication tokens and credentials
  - Financial transaction data
  - Personal account information
  - API keys and secrets

### Activation
- Enabled via `--debug` command-line flag
- Files only created when debug mode is active
- No impact on normal operation when debug mode is disabled

### Use Case
Human debugging of API integration issues where complete visibility of all HTTP traffic is required to diagnose problems with external service interactions.</content>
<parameter name="filePath">specs/debug-logging.md