first commit

docs/foundation/flow/rate-limiter/src/schemas/rate-limiter.schemas.md

@@ -0,0 +1,64 @@
+# rate-limiter.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides Zod v4 validation schemas for all configuration objects in `@suaveplan/rate-limiter`. These schemas enable runtime validation of user-supplied configuration, safe parsing of stored state from external sources, and documentation of valid value ranges. They are tree-shakeable — import only the schemas you need.
+
+Non-serialisable fields (`clock`, `bus`, `logger`, `storage`) are intentionally omitted from `RateLimiterOptionsSchema` since they cannot be represented in Zod.
+
+## Features
+
+- `RateLimitConfigSchema` — validates `limit`, `window`, optional `id` and `description`
+- `RateLimitConditionSchema` — validates five-operator condition objects
+- `RateLimitRuleSchema` — extends config with `priority`, `conditions`, `bypass`
+- `RateLimitContextSchema` — validates per-request context objects
+- `RateLimiterOptionsSchema` — partial options schema for serialisable fields
+- `TokenBucketOptionsSchema`, `SlidingWindowOptionsSchema`, `FixedWindowOptionsSchema` — algorithm options
+- `MemoryStorageOptionsSchema` — storage options
+
+## Usage: Basic Example
+
+```ts
+import { RateLimitConfigSchema } from "@suaveplan/rate-limiter/schemas";
+
+const result = RateLimitConfigSchema.safeParse({ limit: 100, window: 60_000 });
+if (!result.success) {
+  console.error(result.error.issues);
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  RateLimiterOptionsSchema,
+  RateLimitRuleSchema,
+} from "@suaveplan/rate-limiter/schemas";
+
+const raw = JSON.parse(configJson);
+const opts = RateLimiterOptionsSchema.parse(raw);
+
+// Validate individual rules from an API payload:
+const rules = z.array(RateLimitRuleSchema).parse(payload.rules);
+```
+
+## API Reference
+
+| Schema | Validates |
+|---|---|
+| `RateLimitConfigSchema` | `{ limit, window, id?, description? }` |
+| `RateLimitConditionSchema` | `{ field, operator, value }` |
+| `RateLimitRuleSchema` | `RateLimitConfig + { priority?, conditions?, bypass? }` |
+| `RateLimitContextSchema` | `{ key, tenantId?, userId?, ip?, path?, method?, metadata? }` |
+| `RateLimiterOptionsSchema` | Serialisable subset of `RateLimiterOptions` |
+| `TokenBucketOptionsSchema` | `{ capacity, refillRate, initialTokens? }` |
+| `SlidingWindowOptionsSchema` | `{ limit, windowMs }` |
+| `FixedWindowOptionsSchema` | `{ limit, windowMs }` |
+| `MemoryStorageOptionsSchema` | `{ maxSize? }` |
+
+## Implementation Notes
+
+`z.record(z.string(), z.unknown())` is used for `metadata` and `tenantMultipliers` fields, which requires both key and value type arguments in Zod v4. All integer fields use `.int()` to prevent floating-point surprises in window calculations.