# schemas/options

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Zod schema that validates `AuditPluginOptions` at the `createAuditPlugin` factory boundary and produces the resolved `AuditPluginConfig` shape consumed by the lifecycle hooks. Centralises every default value the plugin ships with (sampling rate, exclude paths, redaction rules, dev-only secret key) so the rest of the code can rely on a fully-populated config object.

This is the single source of truth for option defaults; anything not here is either a runtime decision (sink injection, logger choice) or a per-request decision (sampling RNG draw).

## Features

- Zod 4 schema with `.transform(...)` returning a strongly-typed resolved config.
- Defaults for `samplingRate` (1), `excludePaths` (health probes + openapi doc), redaction lists (Authorization/Cookie/Token/Password/etc), `recordResponseSize` (true), `recordRequestBody` (false), `enableChainIntegrity` (false).
- `samplingRate` clamped to `[0, 1]`.
- Optional `sink`, `logger`, `rng` slots remain `unknown` here; the factory narrows them at the call site with concrete imports to avoid pulling `@suaveplan/audit-logging` into the schemas barrel as a value dep.
- Exposes `DEV_DEFAULT_SECRET_KEY` constant so callers and tests can inspect the fallback.

## Usage: Basic

```ts
import { AuditPluginOptionsSchema } from "@suaveplan/api-plugin-audit/schemas/options";

const config = AuditPluginOptionsSchema.parse({
    secretKey: process.env.AUDIT_SECRET_KEY,
});

console.log(config.samplingRate); // 1
console.log(config.excludePaths); // ["/health", "/healthz", "/ready", "/openapi.json"]
```

## Usage: Advanced

```ts
import { AuditPluginOptionsSchema } from "@suaveplan/api-plugin-audit/schemas/options";

const result = AuditPluginOptionsSchema.safeParse({
    samplingRate: 0.25,
    redactBodyFields: ["password", "ssn", "credit_card"],
    enableChainIntegrity: true,
    secretKey: process.env.AUDIT_SECRET_KEY,
});

if (!result.success) {
    // ZodError carrying every boundary violation
    throw result.error;
}

const resolved = result.data;
```

## API Reference

- `AuditPluginOptionsSchema` — Zod schema returning `AuditPluginOptionsResolved`.
- `AuditPluginOptionsInput` — `z.input<typeof AuditPluginOptionsSchema>`.
- `AuditPluginOptionsResolved` — `z.output<typeof AuditPluginOptionsSchema>`.
- `DEFAULT_REDACT_HEADERS`, `DEFAULT_REDACT_QUERY`, `DEFAULT_REDACT_BODY`, `DEFAULT_EXCLUDE_PATHS` — `readonly string[]` defaults.
- `DEV_DEFAULT_SECRET_KEY` — string fallback used when `secretKey` is omitted.

## Implementation Notes

The schema keeps the `sink` and `logger` slots as `unknown` rather than typed Zod schemas because both interfaces are runtime objects and Zod cannot validate their shape without arbitrary `z.custom` predicates. The factory passes them straight through to `new AuditLogger({ ... })`, which already validates `secretKey` and the storage adapter contract. The `secretKey` default exists so the dev path works without env wiring; the factory MUST log a warn when the default is used so operators do not ship it to production.