# Module: `debug`

**Path:** `verae-zapier-middleware/src/debug/`  
**Phase:** 1  
**Purpose:** Runtime-toggleable failure tracing with secret redaction and correlation IDs.

## Files

| File | Role |
|------|------|
| `config.js` | Parse env into enable/namespaces/level |
| `redact.js` | Strip secrets from log metadata |
| `logger.js` | Namespaced `createDebugger` |
| `trace-context.js` | ALS store (no logger import) |
| `trace.js` | `withTrace`, Express middleware |
| `index.js` | Public barrel export |

---

## `parseDebugVeraeEnv(raw)`

| | |
|--|--|
| **For** | Interpret `DEBUG_VERAE` env string |
| **Input** | `raw: string \| undefined` |
| **Output** | `{ enabled: boolean, namespaces: Set<string>\|null }` |
| **Notes** | `1`/`*` → all namespaces; `"auth,nats"` → allow-list |

## `loadDebugConfig(env?)`

| | |
|--|--|
| **For** | Build full debug config from environment |
| **Input** | `env?: NodeJS.ProcessEnv` (default `process.env`) |
| **Output** | `DebugConfig` `{ enabled, namespaces, level, filePath }` |

## `shouldLog(config, namespace, messageLevel)`

| | |
|--|--|
| **For** | Decide if a line should emit |
| **Input** | config, namespace string, level |
| **Output** | `boolean` |

## `redact(input)`

| | |
|--|--|
| **For** | Deep-redact secrets for safe logging |
| **Input** | any JSON-like value |
| **Output** | redacted clone |

## `createDebugger(namespace)`

| | |
|--|--|
| **For** | Get `{ debug, info, warn, error }` logger for a namespace |
| **Input** | `namespace: string` |
| **Output** | `Debugger` |
| **Side effects** | Writes to stderr (or test sink) when enabled |

### `Debugger.debug|info|warn|error(message, meta?)`

| | |
|--|--|
| **Input** | `message: string`, `meta?: Record<string, unknown>` |
| **Output** | `void` |

## `withTrace(options, fn)`

| | |
|--|--|
| **For** | Run work under a correlation id |
| **Input** | `{ traceId?, span? }`, `fn: () => T\|Promise<T>` |
| **Output** | `T\|Promise<T>` |

## `getTraceId()`

| | |
|--|--|
| **For** | Read active correlation id |
| **Output** | `string\|null` |

## `traceMiddleware(req, res, next)`

| | |
|--|--|
| **For** | Per-request Express trace context |
| **Input** | Express `(req, res, next)` |
| **Output** | `void` |
| **Sets** | `req.traceId`, response header `X-Trace-Id` |

## `setDebugTestSink(sink)`

| | |
|--|--|
| **For** | Capture log lines in unit tests |
| **Input** | `((line: string) => void) \| null` |
| **Output** | `void` |

## Env reference

See [../debugging.md](../debugging.md).