@luckystack/api 0.10.1 → 0.11.0

package/docs/error-handling.md

@@ -1,244 +1,5 @@
-# Error Handling
+# API error handling
 
-## Overview
+Normalize failures at the transport boundary: clients need stable, localizable errors, not raw exceptions, stack traces or protected validation detail. Error tracking is for operators and must not make a failed tracker crash a request. See `../src/_shared/responseEnvelope.ts`, `../src/handleApiRequest.ts`, `../src/handleHttpApiRequest.ts`, `../../core/src/responseNormalizer.ts`.
 
-`@luckystack/api` produces a strict, two-shape response envelope. Every code path through the handler — malformed input, auth failure, rate-limit rejection, handler throw, handler return — ends in either `{ status: 'success', ... }` or `{ status: 'error', errorCode, errorParams?, httpStatus, message }`. The transformation from raw failure to wire envelope flows through three layers:
-
-1. **`tryCatch`** wraps the handler's `main(...)` call. Thrown errors are captured (fanned out to every registered tracker with context), and the tuple `[error, result]` is returned to the pipeline. Raw exceptions never reach the client.
-2. **`buildApiResponseEnvelope`** (socket) / **`buildNetworkError`** (HTTP) maps the raw handler result to a wire envelope, inferring `httpStatus` via `defaultHttpStatusForResponse` and routing the error fields through `normalizeErrorResponse`.
-3. **`normalizeErrorResponse`** renders the localized `message` field from the `errorCode` + `errorParams`, using the project-registered translate function. Locale is extracted in priority order: `x-language` header → `accept-language` header → `user.language`.
-
-This means: a handler can return `{ status: 'error', errorCode: 'organization.notFound', errorParams: [{ key: 'id', value: orgId }] }` and the framework renders `Organization "abc123" not found` (or its translation) automatically. Business-logic errors and framework-emitted errors share the same envelope shape.
-
-Logging is uniform: every handler exception is logged via `getLogger().error(...)` with the route name and transport in the context tag, plus a stack via `tryCatch`'s capture. Dev-only warn logs are gated by `logging.devLogs`.
-
-## API Reference
-
-### `executeApiHandler` (internal, socket transport)
-
-**Signature**:
-
-```ts
-const executeApiHandler = async (params: {
-  apiEntry: RuntimeApiEntry;
-  normalizedData: Record<string, unknown>;
-  user: SessionLayout | null;
-  functionsObject: Record<string, unknown>;
-  resolvedName: string;
-  name: string;
-  emitStream: (payload?: ApiStreamPayload) => void;
-}): Promise<{
-  error: Error | null;
-  result: RuntimeApiResponse | undefined;
-  durationMs: number;
-}>;
-```
-
-**Behavior**:
-
-- Calls `apiEntry.main({ data, user, functions, stream })` inside `tryCatch(..., undefined, { handler, api, userId, transport })`.
-- The third argument to `tryCatch` is the auto-capture context — recorded on the registered error tracker alongside the exception.
-- Span open/close is handled by hook subscribers in `@luckystack/error-tracking` (registered on `preApiExecute` / `postApiExecute`) — NOT by a direct `startSpan` call here.
-- Returns `{ error, result, durationMs }`. Caller decides what to do with each.
-
-The HTTP transport has no extracted helper — the same flow is inlined.
-
-### `tryCatch` (re-exported from `@luckystack/core`)
-
-**Signature** (paraphrased):
-
-```ts
-async function tryCatch<T>(
-  fn: () => Promise<T>,
-  fallback?: T,
-  captureContext?: Record<string, unknown>,
-): Promise<[Error | null, T | null]>;
-```
-
-**Behavior**: invokes `fn`; on throw, captures the error via `captureExceptionAcrossTrackers(error, captureContext)`, and returns `[error, null]`. On success, returns `[null, result]`. Used as the universal error boundary across the framework — never use raw `try / catch`.
-
-### `buildApiResponseEnvelope` (internal, socket transport)
-
-**Signature**:
-
-```ts
-const buildApiResponseEnvelope = (params: {
-  resolvedName: string;
-  error: Error | null;
-  result: RuntimeApiResponse | undefined;
-  preferredLocale: string | undefined;
-  user: SessionLayout | null;
-}): { status: 'success' | 'error'; httpStatus?: number; [key: string]: unknown };
-```
-
-**Behavior**:
-
-| Condition | Returns |
-| --- | --- |
-| `error` is non-null | Localized error envelope with `errorCode: 'api.internalServerError'`, `httpStatus: 500`. |
-| `result` is `null` or `undefined` | Localized error envelope with `errorCode: 'api.emptyResponse'`, `httpStatus: 500`. |
-| `result.status` is neither `'success'` nor `'error'` | Localized error envelope with `errorCode: 'api.invalidResponseStatus'`, `httpStatus: 500`. |
-| `result.status === 'error'` | Pass through `normalizeErrorResponse({ response: result, ..., fallbackHttpStatus: defaultHttpStatusForResponse(...) })`. |
-| `result.status === 'success'` | Spread `result`, set `httpStatus` via `defaultHttpStatusForResponse({ status: 'success', explicitHttpStatus: result.httpStatus })`. |
-
-All four error branches and the success branch produce a fully-formed envelope ready to emit.
-
-### `buildNetworkError` (internal closure in `handleHttpApiRequest`)
-
-The HTTP-side equivalent. Same shape as the socket's localized-error path, but the return is typed `ApiNetworkResponse` (which has a non-optional `httpStatus: number`). Used at every HTTP early-return.
-
-### `normalizeErrorResponse` (re-exported from `@luckystack/core`)
-
-**Signature**:
-
-```ts
-function normalizeErrorResponse(params: {
-  response: { status: 'error'; errorCode?: string; errorParams?: [...]; httpStatus?: number; message?: string };
-  preferredLocale?: string | null;
-  userLanguage?: string | null;
-  fallbackHttpStatus?: number;
-}): {
-  status: 'error';
-  httpStatus: number;
-  errorCode: string;
-  errorParams?: [...];
-  message: string;
-};
-```
-
-**Behavior**:
-
-- Dispatches the `preErrorNormalize` sync hook so consumers can remap `errorCode` (e.g. rewrite `auth.required` → `session.expired`).
-- Resolves the locale: `preferredLocale ?? userLanguage ?? defaultLanguage`.
-- Calls the registered localized normalizer (set by `registerLocalizedNormalizer` from the project's `server/utils/responseNormalizer.ts`) with the `errorCode` + `errorParams` to render `message`.
-- Falls back to the raw `errorCode` string when no normalizer is registered or the key is missing from the locale.
-- Sets `httpStatus` to `response.httpStatus ?? fallbackHttpStatus ?? 500`.
-- Dispatches the `postErrorNormalize` sync hook so consumers can rewrite the final shape (e.g. strip stack details, add a correlation ID).
-- Returns the localized envelope.
-
-### `defaultHttpStatusForResponse` (re-exported from `@luckystack/core`)
-
-**Signature**:
-
-```ts
-function defaultHttpStatusForResponse(params: {
-  status: 'success' | 'error';
-  explicitHttpStatus?: number;
-}): number;
-```
-
-**Behavior**: returns `explicitHttpStatus` when present; otherwise `200` for `'success'` and `500` for `'error'`. The handler's per-response `httpStatus` (set inside `main`) always wins.
-
-### Error-tracker identity + tracing spans (hook-based, via `@luckystack/error-tracking`)
-
-These are no longer direct calls inside the handler. As of 0.2.x:
-
-- **Identity**: `setCurrentErrorTrackerIdentity({ id, email, username })` is called immediately after `readSession` to populate the per-request ALS scope opened by `runWithErrorTrackerIdentityScope`. Hook subscribers registered by `@luckystack/error-tracking` (on `preApiValidate` or `preApiExecute`) read this scope and forward it to the underlying tracker (Sentry, Datadog, etc.) — there is no direct `setSentryUser` call in the handler.
-- **Spans**: tracing spans are opened and closed by hook subscribers registered on `preApiExecute` / `postApiExecute`. The handler no longer calls `startSpan` or `span.end()` directly. This decouples the transport from the instrumentation library.
-
-## Framework-emitted error codes
-
-| Code | Origin | HTTP status | Notes |
-| --- | --- | --- | --- |
-| `api.invalidRequest` | `validateApiMessage` (socket) | 400 | Malformed socket envelope. |
-| `api.invalidName` | HTTP entry validation | 400 | `name` missing or not a string. |
-| `api.invalidDataObject` | HTTP entry validation | 400 | `data` missing, null, or not an object. |
-| `routing.invalidServiceRouteName` | `parseTransportRouteName` | 400 | Route name does not match `api/<page>/<name>/v<N>`. `errorParams[0].value` echoes the original name. |
-| `api.notFound` | runtime map lookup | 404 | Route not registered. `errorParams[0].value` echoes the name. |
-| `auth.required` | `checkApiAuth` | 401 | `auth.login: true` and no session. |
-| `auth.forbidden` | `validateRequest` predicate | 403 | Predicate rejected. May carry custom `errorCode` from a future custom validator. |
-| `auth.invalidCondition` | `validateRequest` | 500 | `auth.additional[].key` is not on the session shape. Setup error. |
-| `api.rateLimitExceeded` | `applyApiRateLimits` | 429 | `errorParams[0]` is `{ key: 'seconds', value: resetIn }`. |
-| `api.methodNotAllowed` | HTTP method check | 405 | `errorParams[0]` is `{ key: 'method', value: expectedMethod }`. |
-| `api.invalidInputType` | `validateInputByType` | 400 | Generic code only — the raw validator message is NOT echoed to the client (it would leak the input schema to unauthenticated callers). The detailed message is routed to the `postApiValidate` hook + dev logs. |
-| `api.internalServerError` | `tryCatch` caught a throw | 500 | The original exception is on the registered tracker; not in the wire envelope. |
-| `api.emptyResponse` | `normalizeApiResponse` | 500 | Handler returned `null` or `undefined`. |
-| `api.invalidResponseStatus` | `normalizeApiResponse` | 500 | Handler returned an object whose `status` is not `'success'` / `'error'`. |
-
-Consumer-emitted error codes (returned from `main(...)`) flow through `normalizeErrorResponse` unchanged. Consumers should register translations for the framework codes above plus their own.
-
-## Stop signals
-
-`preApiExecute` and `preApiRespond` hook handlers may return a `HookStopSignal`:
-
-```ts
-return { stop: true, errorCode: 'organization.disabled', httpStatus: 403 };
-```
-
-When the dispatcher sees a stop signal:
-
-- `preApiExecute`: the handler short-circuits before `main(...)` runs. The envelope is built as `normalizeErrorResponse({ response: { errorCode }, fallbackHttpStatus: signal.httpStatus ?? 403 })`.
-- `preApiRespond`: the already-built envelope is discarded; a fresh localized envelope is built from the signal. `transformApiResponse` and `postApiRespond` still fire on the replacement.
-
-Other lifecycle hooks (`preApiValidate`, `postApiValidate`, `postApiExecute`, `transformApiResponse`, `postApiRespond`) do not honor stop signals — they are pre-validation observation, post-execution observation, or pure mutation slots.
-
-## Locale extraction
-
-Order of precedence for the `preferredLocale` argument that flows into `normalizeErrorResponse`:
-
-1. **Socket transport**: `extractLanguageFromHeader(socket.handshake.headers['x-language'])` → `extractLanguageFromHeader(socket.handshake.headers['accept-language'])`.
-2. **HTTP transport**: `extractLanguageFromHeader(params.xLanguageHeader)` → `extractLanguageFromHeader(params.acceptLanguageHeader)`. The HTTP listener in `@luckystack/server` is responsible for passing these headers in.
-3. **Fallback**: `user.language` (from the session) when both headers are absent.
-4. **Final fallback**: `defaultLanguage` from `projectConfig` when there is no session.
-
-`extractLanguageFromHeader` returns the first valid locale token (`en`, `nl`, `de`, `fr`) from a possibly multi-value header, or `undefined`. The localized normalizer also implements its own fallback chain.
-
-## Logging
-
-Every error path logs at the appropriate level:
-
-| Level | When |
-| --- | --- |
-| `getLogger().debug(...)` | Successful route completion, when `logging.devLogs` is on. |
-| `getLogger().warn(...)` | Auth failures, rate-limit exceeded, method mismatch, validation failures, empty returns, malformed envelopes. All gated by `logging.devLogs`. |
-| `getLogger().error(...)` | Handler exceptions caught by `tryCatch`. Always logged regardless of `devLogs`. Carries `{ route, transport }` context. |
-
-The error tracker (registered via `@luckystack/error-tracking`) receives every `tryCatch` capture automatically with the context tags (`handler`, `api`, `userId`, `transport`).
-
-## What is NOT handled here
-
-- **Business-logic errors inside `main(...)`.** Routes return `{ status: 'error', errorCode: '...' }` directly. The envelope normalizer renders them — no thrown exception, no error-tracker capture. This is by design: business outcomes (validation failures in domain code, "user already exists") are not "errors" in the tracking sense.
-- **Localization of `errorCode` strings.** That is the consumer's responsibility — `registerLocalizedNormalizer` from the project's `server/utils/responseNormalizer.ts` provides the translate function backed by JSON locale files in `src/_locales/`.
-- **Frontend error rendering.** The client's `apiRequest` returns the normalized envelope. UI code consumes `result.errorCode` + `result.message` and decides how to render (toast via `notify`, inline form error, redirect).
-- **Hook handler errors.** Failures inside a `dispatchHook` handler are isolated by the hook bus — they log via `getLogger()` + the tracker but do not affect the main pipeline.
-
-## Hooks dispatched
-
-The error-handling layer fires:
-
-| Hook | Stoppable | Payload |
-| --- | --- | --- |
-| `preApiRespond` | yes (becomes localized error) | `{ routeName, user, response }` — last chance to mutate or replace the envelope. |
-| `transformApiResponse` | no (mutate `response`) | `{ routeName, user, response }` — pure mutation slot. |
-| `postApiRespond` | no | `{ routeName, user, response }` — observation after emit. |
-| `preErrorNormalize` | no (sync; mutate `response`) | `{ response: ErrorResponseInput }` — fires inside `normalizeErrorResponse`. |
-| `postErrorNormalize` | no (sync; mutate `normalized`) | `{ normalized: NormalizedErrorResponse }` — fires before `normalizeErrorResponse` returns. |
-
-See [`./api-request-lifecycle.md`](./api-request-lifecycle.md) for the full hook order and `@luckystack/core/docs/hooks.md` for hook bus semantics.
-
-## Config keys
-
-| Key | Effect |
-| --- | --- |
-| `logging.devLogs` | Gates verbose per-request `debug` / `warn` logs. Handler-exception `error` logs always emit. |
-| `defaultLanguage` | Final fallback locale for `normalizeErrorResponse`. |
-| (registered via DI) | The localized normalizer is registered by the project's boot code. Without one, error responses still carry `errorCode` but `message` falls back to the raw key. |
-
-## Edge cases
-
-- **Handler returns `{ status: 'error' }` with no `errorCode`.** `normalizeErrorResponse` treats it as having a missing key — the rendered `message` falls back to the raw value (an empty string or the key literal). Always include `errorCode`.
-- **Handler returns `httpStatus: 0` or a non-number.** `defaultHttpStatusForResponse` only treats `typeof === 'number'` as explicit; non-numbers fall back to 200/500 per the success/error branch.
-- **Stop signal with no `httpStatus`.** Falls back to `403` for both `preApiExecute` and `preApiRespond` stops.
-- **`tryCatch` caught a non-Error throw.** The framework wraps non-Error throws into an Error before capture; the client always gets `api.internalServerError`. The tracker receives the wrapped Error with the original `cause`.
-- **`preApiRespond` stop on an already-error envelope.** The original error envelope is replaced by the stop signal's error envelope. Use this pattern to remap error codes (`auth.required` → `session.expired`) — but prefer the sync `preErrorNormalize` hook for code remapping since it runs in a single place.
-- **HTTP request with no `requesterIp` and no token.** The per-route bucket keys on `ip:anonymous:...` (per route) and `ip:unknown:...` (global). All such requests share these buckets. Front your server with a load balancer that always sets `X-Forwarded-For`.
-
-## Related
-
-- API request lifecycle: [`./api-request-lifecycle.md`](./api-request-lifecycle.md)
-- Auth flow: [`./auth-flow.md`](./auth-flow.md)
-- Rate limiting: [`./rate-limiting.md`](./rate-limiting.md)
-- Generated types: [`./generated-types.md`](./generated-types.md)
-- Architecture: [`/docs/ARCHITECTURE_API.md`](../../../docs/ARCHITECTURE_API.md) (see "Error Code Rules", "Framework-emitted error codes", "Response Contract")
-- Hooks: `@luckystack/core/docs/hooks.md`
-- Error-tracker registry: `@luckystack/core/docs/error-tracker-registry.md`
+Observe the distinction between a pre-execution veto and a post-execution hook: a late hook cannot undo a committed mutation. Per-request tracking identity prevents cross-request attribution; log/capture contexts need credential redaction. See `../../core/src/errorTrackerIdentity.ts`, `../../core/src/redactedLogKeys.ts`, `./api-request-lifecycle.md`.

package/docs/generated-types.md

@@ -1,262 +1,5 @@
-# Generated Types
+# Generated types
 
-## Overview
+Typed route maps bridge consumer route files and client calls. Keep generation as the source of type inference and runtime input schemas; a cast at the call site hides a broken map or unsupported payload and forfeits validation. When inference fails, regenerate the artifacts first, then fix the generator or declaration rather than wrapping calls in `any`/`unknown`. See repository `AGENTS.md`, `../src/_shared/inputTypeWarning.ts`, and generator code in `../../devkit/`.
 
-LuckyStack's API layer is fully type-safe end-to-end. Every `src/{page}/_api/{name}_v{N}.ts` file is read by `@luckystack/devkit` via the TypeScript compiler API, its `ApiParams['data']` and `main` return types are extracted, and three artifacts are emitted: `apiTypes.generated.ts` (the static type map), `apiInputSchemas.generated.ts` (runtime Zod schemas), and `apiDocs.generated.json` (introspection JSON used by `@luckystack/docs-ui`). `@luckystack/api` reads the runtime map at request time and uses the input-type text to drive `validateInputByType`. The client-side `apiRequest` from `@luckystack/core` reads the static type map to infer payload + response shapes from the route-name + version literals you pass it.
-
-This means: any change to an API file's `ApiParams['data']` interface or `main` return type propagates to the client at the next regeneration. The hot-reload watcher (devkit) triggers regeneration on save. The strict typing policy in the repository-root contract (`CLAUDE.md` rule 21) requires this inference chain to remain intact — `unknown` / `any` casts around `apiRequest` defeat the whole pipeline.
-
-This doc covers the generated type surface, the runtime validation flow that consumes it, and the per-route opt-out for cases where strict input typing is impossible (third-party webhooks).
-
-## The two generated files
-
-| Artifact | Default path | Purpose | Consumer |
-| --- | --- | --- | --- |
-| `apiTypes.generated.ts` | `src/_sockets/apiTypes.generated.ts` | Static TS type map. Declares `ApiTypeMap`, `PagePath`, `ApiName`, `ApiVersion`, `ApiInput`, `ApiOutput`, `ApiStream`, `ApiMethod`, `FullApiPath`, plus `apiMethodMap` / `apiMetaMap` runtime tables. | Client autocomplete + compile-time `apiRequest` typing. Also module-augments `@luckystack/core`'s `ApiTypeMap` interface so framework code resolves the same shapes without deep-relative imports. |
-| `apiInputSchemas.generated.ts` | `src/_sockets/apiInputSchemas.generated.ts` | Runtime Zod schemas (one per route + version), keyed by `[pagePath][apiName][version]`. Falls back to `z.any()` with a TODO comment when the input type cannot be converted. | Test runner's input fuzzer. Available for consumers that want pre-handler Zod validation in custom transports. The default runtime validator (`validateInputByType`) uses the type text, not the Zod file. |
-
-Paths are resolved through `@luckystack/core`'s path registry (`getGeneratedSocketTypesPath()`, `getGeneratedApiSchemasPath()`). Override via `projectConfig.paths.*` if you ship the generated files somewhere else.
-
-## Type Map structure
-
-`apiTypes.generated.ts` produces a nested object type, one entry per `<page>` → `<name>` → `<version>`:
-
-```ts
-type _ProjectApiTypeMap = {
-  'settings': {
-    'updateUser': {
-      'v1': {
-        input: { name: string };
-        output: { status: 'success'; ok: true; httpStatus?: number } | { status: 'error'; errorCode: string; httpStatus?: number };
-        stream: never;
-        method: 'POST';
-        rateLimit: 20;
-      };
-    };
-    // ...
-  };
-  // ...
-};
-
-export interface ApiTypeMap extends _ProjectApiTypeMap {}
-```
-
-The file also augments `@luckystack/core` so framework code can rely on the same map:
-
-```ts
-declare module '@luckystack/core' {
-  interface ApiTypeMap extends _ProjectApiTypeMap {}
-  interface SyncTypeMap extends _ProjectSyncTypeMap {}
-}
-```
-
-`@luckystack/core` ships a stub `interface ApiTypeMap {}` in `apiTypeStubs.ts` — the module-augmentation above replaces it with the project's concrete map on any import of the generated file.
-
-## Helper types
-
-All exported from `apiTypes.generated.ts` (and re-exported transitively from `@luckystack/core` for framework use):
-
-| Type | Definition (paraphrased) | Use |
-| --- | --- | --- |
-| `PagePath` | `keyof ApiTypeMap` | Union of every page path with at least one route. |
-| `ApiName<P>` | `keyof ApiTypeMap[P]` | Union of every API name registered under page `P`. |
-| `ApiVersion<P, N>` | `keyof ApiTypeMap[P][N]` | Union of every version registered for route `P/N`. |
-| `ApiInput<P, N, V>` | `ApiTypeMap[P][N][V]['input']` | Payload shape (`data` parameter of `apiRequest`). |
-| `ApiOutput<P, N, V>` | `ApiTypeMap[P][N][V]['output']` | Discriminated success/error union returned by `apiRequest`. |
-| `ApiStream<P, N, V>` | `ApiTypeMap[P][N][V]['stream']` | Union of every `stream(...)` payload shape emitted by `main`. `never` when the route does not stream. |
-| `ApiMethod<P, N, V>` | `ApiTypeMap[P][N][V]['method']` | HTTP method literal (`'GET' \| 'POST' \| 'PUT' \| 'DELETE'`). |
-| `FullApiPath<P, N, V>` | `` `api/${P}/${N}/${V}` `` | Wire-format route string. Used internally — most code uses `name + version` literals. |
-| `ApiResponse<T>` | `{ status: 'success'; ...T } \| { status: 'error'; errorCode; errorParams?; httpStatus? }` | Return type for `main(...)`. |
-| `ApiStreamEmitter<T>` | `(payload?: T) => void \| Promise<void>` | Type of `stream` parameter passed into `main`. |
-| `Functions` | Project-emitted interface | The injected functions registry available to every route (`db`, `redis`, `notify`, ...). |
-
-`ApiInput` / `ApiOutput` / `ApiStream` are what `apiRequest` uses to type its arguments and return value:
-
-```ts
-import { apiRequest } from '@luckystack/core/client';
-
-const result = await apiRequest({
-  name: 'settings/updateUser',   // ApiName<'settings'>
-  version: 'v1',                 // ApiVersion<'settings', 'updateUser'>
-  data: { name: 'Alice' },       // ApiInput<'settings', 'updateUser', 'v1'>
-});
-
-if (result.status === 'success') {
-  // result is narrowed to ApiOutput<'settings', 'updateUser', 'v1'> success branch
-}
-```
-
-The discriminated `status` field on `ApiOutput` lets TypeScript narrow success / error branches without `as` casts. Branch-specific literal properties (`submitted: true` vs `submitted: false`) stay discriminated in the union.
-
-## Runtime input validation
-
-At request time, the API handler reads two fields from the runtime map:
-
-```ts
-interface RuntimeApiEntry {
-  // ...
-  inputType?: string;          // The text form of the `data` interface ("{ name: string }")
-  inputTypeFilePath?: string;  // The source file path, for cross-file type resolution
-  // ...
-}
-```
-
-`validateInputByType` (re-exported from `@luckystack/core`) is called with:
-
-```ts
-const inputValidation = await validateInputByType({
-  typeText: apiEntry.inputType,
-  value: normalizedData,
-  rootKey: 'data',
-  filePath: apiEntry.inputTypeFilePath,
-});
-```
-
-| Field | Type | Purpose |
-| --- | --- | --- |
-| `typeText` | `string \| undefined` | The TypeScript type text captured at generation time. May reference imports — `filePath` lets the resolver expand them. |
-| `value` | `unknown` | The wire-level payload. |
-| `rootKey` | `string` | Label used in error messages (`data` for API, `clientInput` for sync). |
-| `filePath` | `string \| undefined` | Source file path. The dev-mode resolver lazy-loads `@luckystack/devkit` to re-walk imports / re-exports. |
-
-**Return shape**: `{ status: 'success' } | { status: 'error'; message: string }`. On error the handler responds with the generic `api.invalidInputType` + `400`. The validator's `message` is NOT surfaced to the client (echoing it would let unauthenticated callers enumerate the input schema); it is routed to the `postApiValidate` hook payload (`validation.message`) and the dev logs instead.
-
-`validateInputByType` lazy-loads `@luckystack/devkit`'s deep resolver in development so types defined across files (re-exported aliases, utility wrappers like `Partial`/`Pick`/`Omit`/`Record`) expand correctly. In production it relies on the resolver's last-known cache — regenerate before shipping.
-
-## Missing `inputType`
-
-When a route's input cannot be extracted (the type erased to `any`, the generator hit an unresolvable symbol), `inputType` is empty or `'any'`. Strict-mode generation will throw at devkit time — but if you have it disabled or are running on a stale build, runtime validation is effectively a no-op.
-
-The dev-only `warnIfInputTypeMissing(resolvedName, inputType)` helper emits a one-shot warning per route:
-
-```
-api: route settings/updateUser/v1 has no inputType — runtime input validation is disabled. Regenerate types or set the inputType on the handler.
-```
-
-Gated by `projectConfig.dev.warnOnMissingInputType`. Each route warns once per process; the module-level `warnedMissingInputType: Set<string>` prevents log spam.
-
-## `validation: 'relaxed'` / `{ input: 'skip' }`
-
-Some endpoints receive payloads that cannot reasonably be modeled in TypeScript — public webhooks (Stripe, Slack, GitHub), legacy clients in a migration window, or untyped third-party integrations. For these, the route file can opt out:
-
-```ts
-// src/integrations/_api/stripeWebhook_v1.ts
-export const validation = 'relaxed' as const;
-// or
-export const validation = { input: 'skip' } as const;
-```
-
-When set, the socket transport skips `validateInputByType` entirely:
-
-- `warnIfInputTypeMissing` is **not** called.
-- `preApiValidate` still fires (handlers can inspect raw `data`).
-- `validateInputByType` is **not** called.
-- `postApiValidate` fires with `{ status: 'success' }` so audit handlers see the skip.
-
-The HTTP transport does **not** honor the flag — relax-mode endpoints typically live on the socket transport (where webhook payloads still parse as `Record<string, unknown>`). If you need relax-mode on HTTP, structure the input as `Record<string, unknown>` and validate inside `main(...)`.
-
-## Strict typing policy
-
-Repository rule (root `CLAUDE.md` §21): **NEVER** cast typed API/sync payloads to `unknown`, `any`, or `unsafe*` wrappers when calling `apiRequest`, `syncRequest`, or `upsertSyncEventCallback`.
-
-```ts
-// Bad — defeats the entire generated-types pipeline
-const unsafeApi = async (name: string, version: string, data: unknown) =>
-  apiRequest({ name: name as any, version: version as any, data: data as any });
-
-// Good — direct typed call with literal route + version
-const response = await apiRequest({
-  name: 'organization/settings/sendInvite',
-  version: 'v1',
-  data: { email: 'a@b.com' },
-});
-```
-
-The AI workflow allows temporary casts during generator-lag windows (after a save, before types refresh), but they must be local, minimal, and removed once regeneration completes.
-
-## Regenerating types
-
-| Trigger | What happens |
-| --- | --- |
-| Save an `_api/` file in dev | `setupWatchers` (devkit) coalesces a hot-reload + type-map regeneration. The route is re-imported into `devApis`; the type map writes if its content changed. |
-| `npm run build` | The build script invokes `generateTypeMapFile()` once before bundling. |
-| Manual: `npm run ai:index` (or the project's equivalent) | Forces a full regeneration. |
-| `postinstall` (in this repo) | Regenerates `apiInputSchemas.generated.ts` so fresh clones never miss the runtime Zod schemas. |
-
-If the generator throws `[TypeMapGenerator] Generated type map has unresolved type identifiers: <symbols>`, an `ApiParams['data']` or `main` return type references a symbol the resolver could not expand. Common causes: a renamed file, a barrel re-export missing the type, an import cycle. Fix the typing source — do not add casts.
-
-## API Reference
-
-### `validateInputByType` (re-exported from `@luckystack/core`)
-
-**Signature**
-
-```ts
-async function validateInputByType(params: {
-  typeText: string | undefined;
-  value: unknown;
-  rootKey: string;
-  filePath?: string;
-}): Promise<{ status: 'success' } | { status: 'error'; message: string }>;
-```
-
-**Behavior**
-
-- Returns `{ status: 'success' }` when `typeText` is falsy (validation effectively disabled).
-- In dev, lazy-loads `@luckystack/devkit`'s `resolveRuntimeTypeText` to expand cross-file aliases.
-- Walks the type AST recursively. Records the first mismatch and returns a path-level message (`data.users[0].email: expected string, got number`).
-- Caches resolved types per `filePath`; cache is invalidated by devkit on hot reload.
-
-### `warnIfInputTypeMissing` (internal to both handlers)
-
-**Signature**
-
-```ts
-const warnIfInputTypeMissing = (resolvedName: string, inputType: string | undefined): void;
-```
-
-**Behavior**
-
-- No-op when `projectConfig.dev.warnOnMissingInputType` is `false`.
-- No-op when `inputType` is non-empty and not `'any'`.
-- Otherwise, logs once per route via `getLogger().warn(...)` and adds the route to a module-level `Set` so subsequent requests stay quiet.
-
-### `RuntimeApiEntry` (internal type)
-
-The shape `getRuntimeApiMaps()` returns for each route:
-
-```ts
-interface RuntimeApiEntry {
-  auth: AuthProps;
-  main: (params: { data, user, functions, stream }) => Promise<RuntimeApiResponse>;
-  inputType?: string;
-  inputTypeFilePath?: string;
-  rateLimit?: number | false;
-  httpMethod?: HttpMethod;
-  validation?: 'strict' | 'relaxed' | { input: 'skip' | 'strict' };
-}
-```
-
-Devkit emits these. The handler reads them.
-
-## Hooks dispatched
-
-This package does not own hooks specific to type generation. The runtime validation step fires `preApiValidate` / `postApiValidate` — see [`./api-request-lifecycle.md`](./api-request-lifecycle.md).
-
-## Config keys
-
-| Key | Effect |
-| --- | --- |
-| `dev.warnOnMissingInputType` | Toggle the dev-only `warnIfInputTypeMissing` log. |
-| `paths.generatedSocketTypes` | Output path for `apiTypes.generated.ts`. |
-| `paths.generatedApiSchemas` | Output path for `apiInputSchemas.generated.ts`. |
-| `paths.generatedApiDocs` | Output path for `apiDocs.generated.json`. |
-
-## Related
-
-- API request lifecycle: [`./api-request-lifecycle.md`](./api-request-lifecycle.md)
-- Routing conventions: [`./routing-conventions.md`](./routing-conventions.md)
-- Error handling: [`./error-handling.md`](./error-handling.md)
-- Architecture: [`/docs/ARCHITECTURE_ROUTING.md`](../../../docs/ARCHITECTURE_ROUTING.md) (see "Generated maps")
-- Devkit type-map generation: `@luckystack/devkit/docs/type-map-generation.md`
-- Root rule on casts: [`CLAUDE.md`](../../../CLAUDE.md) §21
+Runtime validation is a security boundary independent of TypeScript. An intentional skip for a dynamic payload must be explicit and reviewed; it should not become a blanket response to missing generated schemas. Inspect the route declaration, generated schema and `../src/_shared/socketValidationStage.ts` / `httpValidationStage.ts` together.