first commit

docs/observability/monitor/audit-logging/src/schemas/audit-logging.schemas.md

@@ -0,0 +1,110 @@
+# audit-logging.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides Zod v4 schema definitions for all public types in `@suaveplan/audit-logging`. These schemas enable runtime validation at API boundaries, wire deserialization, and property-based testing. Every schema mirrors its corresponding TypeScript interface exactly, ensuring type inference from `z.infer<>` produces the same shape as the hand-written types in `audit-logging.types.ts`.
+
+## Features
+
+- `AuditSeveritySchema` — enum validator for the five severity levels
+- `AuditEventTypeSchema` — enum validator for all 29 built-in event types
+- `AuditActorSchema` — optional-field object schema for actors
+- `AuditTargetSchema` — required type/id with optional metadata record
+- `AuditEventSchema` — complete event record with all fields
+- `AuditQueryOptionsSchema` — query filter schema with union severity support
+- `AuditRetentionPolicySchema` — policy with positive retentionDays validation
+- `ChainVerificationResultSchema` — pass/fail result with optional broken-at index
+- `RetentionResultSchema` — counts and errors array
+
+## Usage: Basic Example
+
+```ts
+import { AuditEventSchema } from "@suaveplan/audit-logging/schemas/audit-logging.schemas";
+
+const raw = JSON.parse(apiResponse);
+const event = AuditEventSchema.parse({
+  ...raw,
+  timestamp: new Date(raw.timestamp),
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  AuditQueryOptionsSchema,
+  AuditRetentionPolicySchema,
+} from "@suaveplan/audit-logging/schemas/audit-logging.schemas";
+import { AuditLogger } from "@suaveplan/audit-logging/core/audit-logger/audit-logger";
+import { MemoryAuditAdapter } from "@suaveplan/audit-logging/adapters/memory/memory-adapter";
+
+// Validate query options from user input
+function parseQueryOptions(input: unknown) {
+  return AuditQueryOptionsSchema.parse(input);
+}
+
+// Validate policy from config file
+function parsePolicy(input: unknown) {
+  const policy = AuditRetentionPolicySchema.parse(input);
+  return new AuditLogger({
+    storage: new MemoryAuditAdapter(),
+    secretKey: "key",
+    retentionPolicy: policy,
+  });
+}
+```
+
+## API Reference
+
+### `AuditSeveritySchema`
+
+`z.enum(["debug", "info", "warning", "error", "critical"])`
+
+### `AuditEventTypeSchema`
+
+`z.enum([...all 29 values...])`
+
+### `AuditActorSchema`
+
+All fields optional: `userId`, `sessionId`, `apiKeyId`, `ipAddress`, `userAgent`, `tenantId`.
+
+### `AuditTargetSchema`
+
+- `type: string` (required)
+- `id: string` (required)
+- `metadata?: Record<string, unknown>`
+
+### `AuditEventSchema`
+
+- All AuditEvent fields with proper Zod types
+- `timestamp: z.date()` — expects a `Date` object (not a string)
+- `type: z.union([AuditEventTypeSchema, z.string()])` — accepts custom types
+
+### `AuditQueryOptionsSchema`
+
+All fields optional. `severity` accepts a single value or array.
+
+### `AuditRetentionPolicySchema`
+
+- `retentionDays: z.number().int().positive()` — must be ≥ 1
+- `archiveBeforeDelete: z.boolean()`
+- `archiveLocation?: z.string()`
+
+### `ChainVerificationResultSchema`
+
+- `valid: z.boolean()`
+- `brokenAt?: z.number().int().nonnegative()`
+- `reason?: z.string()`
+
+### `RetentionResultSchema`
+
+- `eventsDeleted: z.number().int().nonnegative()`
+- `eventsArchived: z.number().int().nonnegative()`
+- `errors: z.array(z.string())`
+
+## Implementation Notes
+
+Schemas use `z.record(z.string(), z.unknown())` (two-argument form) per Zod v4 requirements. The `AuditEventTypeSchema` enumerates all values from the `AuditEventType` enum directly rather than using `z.nativeEnum()`, which is deprecated in Zod v4 in favour of `z.enum()`. The `timestamp` field expects an actual `Date` object — callers parsing JSON should convert the ISO string first with `new Date(raw.timestamp)`.