# `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.