first commit

docs/api-stack/api/api-tenant-resolver-jwt/src/options/options.md

@@ -0,0 +1,81 @@
+# `options`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines and validates the `JwtTenantResolverOptions` accepted by
+`createJwtTenantResolver`. The options shape is deliberately narrow — Stage 4
+adapters do almost no work — but every field is Zod-validated at construction
+time so a typo in `claimKey` or a boolean coerced from a string never reaches
+the per-request hot path. Construction-time failures throw
+`JwtTenantResolverError(INVALID_OPTIONS)` so the host surfaces a stable error
+code rather than a raw `ZodError`.
+
+The parser also fills in defaults (`id = "jwt"`, `claimKey = "tenantId"`,
+`requirePrincipal = false`), so the resolver implementation can treat its
+options as fully-resolved `Required<…>` and avoid scattering `??` defaults
+through the request path.
+
+## Features
+
+- `JwtTenantResolverOptions` — three optional fields covering the entire
+  configuration surface (`id`, `claimKey`, `requirePrincipal`).
+- `parseJwtTenantResolverOptions(input)` — strict Zod parser; rejects
+  unknown keys, empty strings, and non-boolean values.
+- Pure: no I/O, no side effects, no module-level state — safe to call from
+  module-init code.
+
+## Usage: Basic
+
+```ts
+import { parseJwtTenantResolverOptions } from "@suaveplan/api-tenant-resolver-jwt/options";
+
+const resolved = parseJwtTenantResolverOptions(undefined);
+// → { id: "jwt", claimKey: "tenantId", requirePrincipal: false }
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    parseJwtTenantResolverOptions,
+    type JwtTenantResolverOptions,
+} from "@suaveplan/api-tenant-resolver-jwt/options";
+import {
+    JwtTenantResolverError,
+    TENANT_RESOLVER_JWT_CODES,
+} from "@suaveplan/api-tenant-resolver-jwt/error-codes";
+
+function safeParse(input: JwtTenantResolverOptions): "ok" | "bad" {
+    try {
+        parseJwtTenantResolverOptions(input);
+        return "ok";
+    } catch (e) {
+        if (
+            e instanceof JwtTenantResolverError &&
+            e.code === TENANT_RESOLVER_JWT_CODES.INVALID_OPTIONS
+        ) {
+            return "bad";
+        }
+        throw e;
+    }
+}
+```
+
+## API Reference
+
+- `interface JwtTenantResolverOptions` — `{ id?: string; claimKey?: string; requirePrincipal?: boolean }`.
+- `function parseJwtTenantResolverOptions(input)` — `Required<Pick<JwtTenantResolverOptions, "id" | "claimKey" | "requirePrincipal">>`. Throws `JwtTenantResolverError(INVALID_OPTIONS)`.
+
+## Implementation Notes
+
+The Zod schema is `.strict()` — unknown keys reject at parse time. This is
+intentional: a downstream caller passing a misspelt field (e.g.
+`claim_key` instead of `claimKey`) would otherwise see the field silently
+ignored and the resolver fall back to defaults, masking the configuration
+bug behind a hard-to-trace "no tenant resolved" failure mode. The parser
+runs once at construction so the per-request hot path operates on
+fully-resolved `Required<…>` values without re-validation.