@luckystack/api 0.10.2 → 0.12.0

package/docs/rate-limiting.md

@@ -1,186 +1,5 @@
-# Rate Limiting
+# API rate limiting
 
-## Overview
+Per-route and cross-route IP limits defend different abuse patterns; neither substitutes for authorization. An authenticated caller's per-route quota should be associated with a server-validated identity rather than the replaceable token string. Anonymous and global-IP quotas rely on trustworthy proxy configuration: a spoofable forwarded address defeats that control. See `../src/_shared/rateLimitIdentity.ts`, `../src/_shared/applyApiRateLimits.ts`, `../../core/src/resolveClientIp.ts`.
 
-Every API request runs through two rate-limit buckets, in order. The per-route bucket protects an individual endpoint from a single caller; the global per-IP bucket protects the server as a whole from a single source hitting many endpoints. Both buckets use the same strategy backend (configurable via `registerRateLimitStrategy` in `@luckystack/core`; defaults to memory-or-redis depending on `rateLimiting.store`), share the same `windowMs`, and emit the same `rateLimitExceeded` hook on rejection.
-
-Rate-limit logic is identical on both transports — `handleApiRequest` and `handleHttpApiRequest` apply the same buckets in the same order. The only transport-specific difference is where the IP comes from: the socket transport reads `socket.handshake.address`; the HTTP transport takes a `requesterIp` parameter (the HTTP listener in `@luckystack/server` derives it from `req.socket.remoteAddress` + optional forwarded-header parsing).
-
-Rejection responds with `api.rateLimitExceeded` + HTTP `429`, and includes `errorParams: [{ key: 'seconds', value: resetIn }]` so consumers can render a localized "try again in N seconds" message. The hook payload exposes the full key, scope, and counts for dashboards / alerting.
-
-## The two buckets
-
-### 1. Per-route bucket
-
-Keyed per-caller per-route. Drops requests that exceed `apiEntry.rateLimit` (per route) or `rateLimiting.defaultApiLimit` (fallback) within `windowMs`.
-
-**Key format:**
-
-| Caller | Key |
-| --- | --- |
-| Authenticated (`token` present) | `token:<token>:api:<resolvedName>` |
-| Anonymous (no token) | `ip:<requesterIp>:api:<resolvedName>` |
-
-The `<resolvedName>` is the normalized route name returned by `parseTransportRouteName` (e.g. `settings/updateUser/v1`). Using the token (not user ID) as the key ensures the bucket sticks to the session even if multiple sessions exist for the same user under `session.perUser === 'multiple'`.
-
-**Per-route override:** a route file can declare its own limit (or disable it):
-
-```ts
-// src/settings/_api/updateUser_v1.ts
-export const rateLimit: number | false = 30;   // 30 requests per window
-// or:
-export const rateLimit = false;                 // No per-route bucket
-```
-
-When `rateLimit === false` or `0`, the per-route bucket is skipped entirely — the global IP bucket still applies.
-
-When `rateLimit === undefined` (the export is absent), the handler falls back to `rateLimiting.defaultApiLimit`. If that is also `false`, the per-route bucket is skipped.
-
-### 2. Global per-IP bucket
-
-Keyed only by IP, shared across every route. Drops requests from a single IP that exceed `rateLimiting.defaultIpLimit` in `windowMs`, regardless of which routes they hit.
-
-**Key format:** `ip:<requesterIp>:api:all`
-
-When `defaultIpLimit === false` or `0`, the global bucket is skipped entirely. Per-route limits still apply.
-
-The global bucket runs **after** the per-route bucket — a route that has burned through its per-route allowance returns `api.rateLimitExceeded` without ever touching the global bucket, so the per-route violator does not also consume global capacity.
-
-## Bucket evaluation order
-
-Both transports execute exactly:
-
-1. Compute `effectiveApiLimit = apiEntry.rateLimit ?? rateLimiting.defaultApiLimit`.
-2. If `effectiveApiLimit !== false && effectiveApiLimit > 0`:
-   - Build the per-route key.
-   - `await checkRateLimit({ key, limit, windowMs })`.
-   - On `!allowed`, dispatch `rateLimitExceeded` with `scope: token ? 'user' : 'ip'` (the bucket is user-keyed only when a token is present; an anonymous per-route bucket is IP-keyed, so it reports `ip` — with `route` still set to distinguish it from the global `:api:all` IP bucket below), respond `api.rateLimitExceeded` + `429`, abort.
-3. Read `defaultIpLimit = rateLimiting.defaultIpLimit`.
-4. If `defaultIpLimit !== false && defaultIpLimit > 0`:
-   - Build the global IP key.
-   - `await checkRateLimit(...)`.
-   - On `!allowed`, dispatch `rateLimitExceeded` with `scope: 'ip'`, respond `api.rateLimitExceeded` + `429`, abort.
-
-The rate-limit step sits between auth and validation. Auth runs first so unauthenticated probes can't burn through anonymous IP buckets enumerating routes. Validation runs after rate limit so a flood of malformed payloads from a single caller is throttled the same way as well-formed traffic.
-
-## API Reference
-
-### `applyApiRateLimits` (internal, socket transport)
-
-**Signature** (paraphrased):
-
-```ts
-const applyApiRateLimits = async (params: {
-  apiEntry: RuntimeApiEntry;
-  resolvedName: string;
-  token: string | null;
-  socket: Socket;
-  user: SessionLayout | null;
-  emitApiError: EmitApiError;
-}): Promise<boolean>;
-```
-
-| Param | Notes |
-| --- | --- |
-| `apiEntry` | Read `rateLimit` field. |
-| `resolvedName` | Used to build the per-route key. |
-| `token` | When non-null, drives `token:<token>:...` key + `scope: 'user'`. |
-| `socket` | Read `socket.handshake.address` for the IP fallback. |
-| `user` | Surfaced as `userId` in the `rateLimitExceeded` payload. |
-| `emitApiError` | Closure that emits the localized error envelope on the response channel. |
-
-**Returns**: `Promise<boolean>` — `true` if both buckets allowed the request, `false` if either rejected.
-
-### Inline rate-limit block in `handleHttpApiRequest`
-
-Same logic, inlined rather than extracted into a helper. Reads `requesterIp` (or `'anonymous'` for the per-route bucket key, `'unknown'` for the global bucket key) instead of `socket.handshake.address`.
-
-### `checkRateLimit({ key, limit, windowMs })` (re-exported from `@luckystack/core`)
-
-The underlying strategy call.
-
-**Signature**:
-
-```ts
-async function checkRateLimit(params: {
-  key: string;
-  limit: number;
-  windowMs: number;
-}): Promise<{ allowed: boolean; resetIn: number; current: number }>;
-```
-
-**Behavior**:
-
-- Delegates to the registered strategy (`registerRateLimitStrategy`). Default strategy uses Redis when `rateLimiting.store === 'redis'`, otherwise an in-memory token-bucket.
-- `resetIn` is seconds until the window resets, used as the `seconds` error param.
-- Backend implementation lives in `@luckystack/core/src/rateLimiter.ts`; see its docs for sliding-window semantics and the `redisKeyPrefix` config option.
-
-## Hooks dispatched
-
-| Hook | When | Payload (key fields) |
-| --- | --- | --- |
-| `rateLimitExceeded` | A bucket rejects | `scope: 'user' \| 'route' \| 'ip'`, `key: string`, `limit: number`, `windowMs: number`, `count: number` (always `limit + 1` here), `route?: string`, `userId?: string`, `ip?: string` |
-
-The hook fires before the error response is emitted, so handlers that want to escalate (alerting, IP-banning) can act on the same request. Handlers run inside `void dispatchHook(...)` — they cannot block or alter the rejection.
-
-`scope` distinguishes the three cases:
-
-- `'user'` — per-route bucket rejected an authenticated caller (`token` was non-null).
-- `'route'` — per-route bucket rejected an anonymous caller (no token; keyed by IP).
-- `'ip'` — global per-IP bucket rejected.
-
-## Error response
-
-Both transports return the same envelope on rejection:
-
-```jsonc
-{
-  "status": "error",
-  "httpStatus": 429,
-  "errorCode": "api.rateLimitExceeded",
-  "errorParams": [{ "key": "seconds", "value": 42 }],
-  "message": "Too many requests. Try again in 42 seconds."
-  // message comes from the registered localized normalizer using errorCode + errorParams
-}
-```
-
-`resetIn` reflects the strategy's view of when the bucket frees up. The localized normalizer renders the message via the consumer's translate function — see [`./error-handling.md`](./error-handling.md).
-
-## Config keys
-
-All read at request time via `getProjectConfig()`.
-
-| Key | Type | Effect |
-| --- | --- | --- |
-| `rateLimiting.defaultApiLimit` | `number \| false` | Fallback per-route limit when the route does not export `rateLimit`. `false` disables. |
-| `rateLimiting.defaultIpLimit` | `number \| false` | Global per-IP limit across all routes. `false` disables. |
-| `rateLimiting.windowMs` | `number` | Window size for both buckets, in ms. Default 60000 (one minute). |
-| `rateLimiting.store` | `'memory' \| 'redis'` | Backend for the default strategy. `'redis'` is required for multi-instance consistency. |
-| `rateLimiting.redisKeyPrefix` | `string` | Prefix prepended to keys when using the Redis backend. |
-| `rateLimiting.enabled` | `boolean` | Master switch on the default strategy. When `false`, every `checkRateLimit` call returns `{ allowed: true }`. |
-
-## Disabling rate limiting
-
-| Scope | How |
-| --- | --- |
-| One route, per-route bucket only | `export const rateLimit = false;` in the route file. |
-| One route, both buckets | `export const rateLimit = false;` + run the consumer behind a load balancer that absorbs the IP bucket. There is no per-route opt-out for the global bucket. |
-| Globally, per-route bucket | `rateLimiting.defaultApiLimit: false` in `registerProjectConfig`. |
-| Globally, IP bucket | `rateLimiting.defaultIpLimit: false`. |
-| Globally, everything | `rateLimiting.enabled: false` (default strategy honors this and short-circuits). |
-| Replace backend | `registerRateLimitStrategy(myStrategy)` from `@luckystack/core` — useful for edge-KV-backed limits, per-tier quotas, or no-op test strategies. |
-
-## Edge cases
-
-- **Anonymous request with no IP** — the socket transport falls back to `'unknown'` for `socket.handshake.address`; the HTTP transport falls back to `'anonymous'` for the per-route bucket and `'unknown'` for the global bucket. All anonymous callers that lack an IP share the same bucket. Front your server with a load balancer that always supplies `X-Forwarded-For` (parsed by `@luckystack/server`'s request adapter) to avoid this collision.
-- **Token present but session deleted** — the bucket is still keyed by the token string; subsequent requests with the same expired token still throttle. Once the session is fully GC'd from `getSession`, the auth gate rejects with `auth.required` before rate-limit checks run (auth runs first).
-- **Race within `windowMs`** — `checkRateLimit` is atomic on the strategy backend (`INCR` + `EXPIRE` for Redis, lock-free counter for memory). Two requests arriving at the same millisecond both count toward the limit.
-- **Per-route `rateLimit = 0`** — equivalent to `false` (bucket skipped). The handler explicitly guards on `effectiveApiLimit > 0`.
-- **Custom strategy returns `allowed: false` with `resetIn: 0`** — the response still echoes `seconds: 0`. Renderers should treat `seconds <= 0` as "right now" / "very soon".
-
-## Related
-
-- API request lifecycle: [`./api-request-lifecycle.md`](./api-request-lifecycle.md)
-- Error handling: [`./error-handling.md`](./error-handling.md)
-- Rate-limit strategy: `@luckystack/core/docs/rate-limit-strategy.md`
-- Architecture: [`/docs/ARCHITECTURE_API.md`](../../../docs/ARCHITECTURE_API.md) (see "Rate Limiting")
+Do not present a store failure as a successfully enforced quota. Consult `../../core/src/rateLimiter.ts` and `../../core/src/projectConfig.ts` for strategy and policy instead of copying limits or error envelopes here.

package/docs/routing-conventions.md

@@ -1,162 +1,5 @@
-# Routing Conventions
+# API routing conventions
 
-## Overview
+Versioned route names allow client and server maps to agree as handlers evolve. Discovery is generated; keep declarations and generated artifacts aligned rather than maintaining a second route inventory. See `../../devkit/` and `../src/handleApiRequest.ts`.
 
-`@luckystack/api` is transport-agnostic — it does not own file-based routing. Discovery of `_api/<name>_v<N>.ts` files lives in `@luckystack/devkit`, which walks `src/`, parses each file's exports, and emits two artifacts the API handler reads at runtime: the route map (`getRuntimeApiMaps()`) and the generated type map (`apiTypes.generated.ts`). This document describes the route-name conventions both handlers enforce, the per-route exports the runtime map carries, and the HTTP-method inference contract the HTTP transport applies.
-
-If a route name on the wire does not match the conventions below, both `handleApiRequest` and `handleHttpApiRequest` reject with `routing.invalidServiceRouteName` before any other side effect. If a name parses but does not match a registered route, both return `api.notFound`.
-
-## Wire-level route names
-
-Both transports accept the same shape:
-
-```
-api/<page>/<name>/v<N>
-```
-
-| Segment | Constraints |
-| --- | --- |
-| `api/` | Literal prefix. The HTTP transport accepts `name` with or without it and normalizes; the socket transport requires the prefix to be present in `msg.name`. |
-| `<page>` | Slash-separated page path. May be deeply nested (`organization/settings`). Top-level system APIs use `system` as the page (e.g. `api/system/session/v1`). |
-| `<name>` | Endpoint name. Free-form identifier; influences HTTP method inference (see below). |
-| `v<N>` | Version token (`v1`, `v2`, ...). Required. Files that do not end in `_v<N>.ts` are skipped by the discovery walker. |
-
-`parseTransportRouteName({ value, prefix: 'api' })` (exported from `@luckystack/core`) is the single source of truth. The returned `normalizedFullName` is what the handler uses for runtime-map lookup, rate-limit keying, and hook payloads.
-
-## File-system convention
-
-Discovery is owned by `@luckystack/devkit`. Files are picked up when they live under `src/` and match `**/_api/<name>_v<N>.ts` (or any subdirectory, including `_api/<sub>/<name>_v<N>.ts` for nested routes). The marker segment `_api` is configurable via `registerRoutingRules` but defaults to `_api`.
-
-| Path | Resolved route |
-| --- | --- |
-| `src/_api/session_v1.ts` | `api/system/session/v1` (top-level APIs are mapped under the `system` service) |
-| `src/settings/_api/updateUser_v1.ts` | `api/settings/updateUser/v1` |
-| `src/organization/_api/settings/sendInvite_v1.ts` | `api/organization/settings/sendInvite/v1` |
-| `src/playground/_api/streamCounter_v1.ts` | `api/playground/streamCounter/v1` |
-
-Files that do not match the `_v<N>` suffix are not discovered. The version digit must be a positive integer. Versions are sorted numerically when emitted into the type map.
-
-Folders prefixed with `_` are private — they may sit alongside `_api/`, `_sync/`, `_components/`, etc. without being treated as page routes by the frontend router.
-
-## Per-route exports
-
-Each route file declares its behavior via exports. The discovery walker captures these via the TypeScript compiler API and emits them into the runtime map.
-
-```ts
-// src/settings/_api/updateUser_v1.ts
-import type { AuthProps } from '@luckystack/core';
-import type { ApiResponse } from 'src/_sockets/apiTypes.generated';
-
-export const rateLimit: number | false = 20;
-export const httpMethod = 'POST' as const;
-export const auth: AuthProps = { login: true };
-
-export interface ApiParams {
-  data: { name: string };
-  user: SessionLayout;
-  functions: Functions;
-}
-
-export const main = async ({ data, user, functions }: ApiParams): Promise<ApiResponse> => {
-  // ...
-  return { status: 'success', ok: true };
-};
-```
-
-| Export | Type | Default | Effect |
-| --- | --- | --- | --- |
-| `main` | `(params) => Promise<ApiResponse>` | required | Handler invoked by `executeApiHandler` inside the `tryCatch` + registered error-tracker span. |
-| `auth` | `AuthProps` | required | Auth gate (see [`./auth-flow.md`](./auth-flow.md)). |
-| `rateLimit` | `number \| false` | `rateLimiting.defaultApiLimit` from config | Per-route requests-per-window cap. `false` disables the per-route bucket; the global IP bucket still applies. See [`./rate-limiting.md`](./rate-limiting.md). |
-| `httpMethod` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` | inferred from name | Overrides `inferHttpMethod` for the HTTP transport. Socket transport ignores this field. |
-| `ApiParams` interface | `{ data, user, functions, stream? }` | required | TypeScript-only. The `data` field's type is what `validateInputByType` checks at runtime via the generated Zod schema. |
-| `validation` | `'strict' \| 'relaxed' \| { input: 'skip' \| 'strict' }` | `'strict'` | Socket-only escape hatch for public webhooks where the third-party payload is not modelable in TypeScript. See "Input validation" below. |
-
-`ApiResponse` is exact: either `{ status: 'success'; httpStatus?: number; ...payload }` or `{ status: 'error'; errorCode: string; errorParams?: [...]; httpStatus?: number }`. Returning anything else is a runtime error (`api.invalidResponseStatus`).
-
-## HTTP-method inference
-
-Used by `handleHttpApiRequest` when the route file does not export `httpMethod`. Implemented in `inferHttpMethod` (from `@luckystack/core/src/httpApiUtils.ts`):
-
-| Name prefix (case-insensitive, last `/`-segment) | Inferred method |
-| --- | --- |
-| `get*`, `fetch*`, `list*` | `GET` |
-| `delete*`, `remove*` | `DELETE` |
-| `update*`, `edit*`, `patch*` | `PUT` |
-| Everything else (`create*`, `send*`, `sync*`, bare verbs) | `POST` |
-
-The inference reads the last segment before the version token. `api/admin/users/getList/v1` infers `GET`; `api/admin/getUsers/v2` also infers `GET`.
-
-The socket transport does not validate HTTP method — only the HTTP transport does. Mismatches return `api.methodNotAllowed` + `405` with `errorParams: [{ key: 'method', value: expectedMethod }]`.
-
-## Input validation
-
-The discovery walker reads the `data` field of the `ApiParams` interface (or whatever the `main` parameter's `data` member is named) and:
-
-1. Emits the **text form** of the type into the runtime map (`apiEntry.inputType`).
-2. Emits a **Zod schema** for the same type into `apiInputSchemas.generated.ts` for runtime checking + test-runner fuzz.
-3. Emits the **structural type** into `apiTypes.generated.ts` so `apiRequest({ name, version, data })` on the client gets full autocomplete + a compile-time error if `data` does not match.
-
-At request time, `validateInputByType({ typeText, value, rootKey: 'data', filePath })` matches the payload against the stored type. The validator lazy-loads `@luckystack/devkit`'s deep resolver in dev so imported / re-exported aliases expand correctly; in production it falls back to a static resolver.
-
-The per-route `validation` flag turns the validator off:
-
-```ts
-// Public webhook receiving a payload from Stripe / Slack / GitHub
-export const validation = 'relaxed' as const;
-
-// Or, equivalent:
-export const validation = { input: 'skip' } as const;
-```
-
-Use sparingly. The skip suppresses both `api.invalidInputType` rejections and the dev-only "no inputType" warning. `postApiValidate` still fires with `{ status: 'success' }` so audit handlers see the skip.
-
-## Wire-level route examples
-
-```
-api/system/session/v1           ← src/_api/session_v1.ts
-api/system/logout/v1            ← src/_api/logout_v1.ts (built-in socket shortcut)
-api/settings/updateUser/v1      ← src/settings/_api/updateUser_v1.ts
-api/organization-settings/sendInvite/v1
-                                ← src/organization-settings/_api/sendInvite_v1.ts
-api/admin/users/listAll/v3      ← src/admin/_api/users/listAll_v3.ts
-```
-
-## Reserved routes
-
-| Route | Owner | Notes |
-| --- | --- | --- |
-| `api/system/logout/v1` | `handleApiRequest` (socket only) | Short-circuited before runtime map lookup. Calls `logout(...)` from `@luckystack/login`. HTTP requests for this route go through the normal pipeline. |
-| `api/system/session/v1` | Project | Conventional location for the session-fetch endpoint. Not framework-reserved. |
-
-Consumer routes whose final segment happens to be `logout` (`admin/logout/v1`) are NOT hijacked — the short-circuit matches the full normalized route `system/logout`, not just the trailing segment.
-
-## Hooks dispatched
-
-Discovery / route-naming hooks live in `@luckystack/devkit`. The runtime API handler does not emit routing-level hooks beyond the standard `pre/postApiValidate` / `pre/postApiExecute` / `pre/postApiRespond` / `transformApiResponse` / `rateLimitExceeded` set. See [`./api-request-lifecycle.md`](./api-request-lifecycle.md).
-
-## Config keys
-
-| Key | Effect |
-| --- | --- |
-| `paths.srcDir` | Root directory for `_api/` discovery (devkit). |
-| `paths.generatedSocketTypes` | Output path for `apiTypes.generated.ts` (devkit). |
-| `paths.generatedApiSchemas` | Output path for `apiInputSchemas.generated.ts` (devkit). |
-| `paths.generatedApiDocs` | Output path for `apiDocs.generated.json` (devkit). |
-
-No routing-specific keys are read at request time by `@luckystack/api`.
-
-## Edge cases
-
-- **Two files normalize to the same route key.** `assertNoDuplicateNormalizedRouteKeys` (devkit) throws at generation time. The runtime map will reflect whichever file was loaded last; treat the throw as a build-time guard.
-- **File saved without a version suffix.** Discovery skips the file. The route never registers; `apiRequest` calls fail with `api.notFound` at runtime.
-- **`auth` export missing.** TypeScript will not compile; if compilation is bypassed, the runtime map's `apiEntry.auth` is `undefined` and the auth gate treats it as `{ login: false }`. Do not rely on this — declare `auth` explicitly.
-- **Non-`_api/` folders matching the regex.** Discovery only descends through folders; the marker segment `_api` is required, and folders without the underscore prefix are ignored.
-
-## Related
-
-- API request lifecycle: [`./api-request-lifecycle.md`](./api-request-lifecycle.md)
-- Generated types: [`./generated-types.md`](./generated-types.md)
-- Architecture: [`/docs/ARCHITECTURE_ROUTING.md`](../../../docs/ARCHITECTURE_ROUTING.md)
-- Devkit type-map: `@luckystack/devkit/docs/type-map-generation.md`
-- Devkit loader pipeline: `@luckystack/devkit/docs/loader-pipeline.md`
+An HTTP method is an HTTP transport constraint, not permission to invoke the handler: socket events have no method. Enforce caller identity and any route predicates in auth policy on both transports. Input-validation exceptions are deliberate reductions in defense and need a reason; avoid broad skips as a type-generator workaround. See `../src/handleHttpApiRequest.ts`, `./auth-flow.md`, `./generated-types.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/api",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -32,7 +32,7 @@
     "validation"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.13.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -45,7 +45,7 @@
   "files": [
     "dist",
     "README.md",
-    "CLAUDE.md",
+    "AGENTS.md",
     "docs",
     "LICENSE",
     "CHANGELOG.md"
@@ -56,8 +56,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.10.2",
-    "@luckystack/error-tracking": "^0.10.2"
+    "@luckystack/core": "^0.12.0",
+    "@luckystack/error-tracking": "^0.12.0"
   },
   "peerDependencies": {
     "@prisma/client": "^6.19.0",

package/CLAUDE.md

@@ -1,111 +0,0 @@
-# @luckystack/api
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-`@luckystack/api` is the transport-agnostic API request layer for LuckyStack. It exposes two handler entry points — one for socket.io (`handleApiRequest`) and one for raw HTTP (`handleHttpApiRequest`) — that share an identical pipeline: route resolution against the generated runtime map, session lookup, auth check, rate limiting, input validation (Zod from generated types), hook dispatch, handler execution with `tryCatch`-wrapped error capture, and response normalization (localized error envelopes, default HTTP status inference, streaming via SSE on the HTTP side).
-
-> ✅ **Runtime input validation now runs in production** (api F1 / core CORE-01). `validateInputByType` (in `@luckystack/core`) used to short-circuit to `{ status: 'success' }` in production; it now runs the structural validator against the build-time-resolved generated type text. The expensive dev-only TypeScript-compiler RESOLVER is still skipped in prod (it can't run there), but the pre-resolved type is validated directly — so a route typed `data: { userId: string }` rejects a malformed prod payload exactly as in dev. Gated by `validation.runtimeMode` (default `'enforce'`); set `validation.runtimeMode: 'off'` to restore the old prod no-op. If the generated type still carries an `__RUNTIME_UNRESOLVED__::` marker (artifacts not regenerated before shipping), validation surfaces it as a LOUD error (regenerate artifacts) rather than silently passing. `validation: 'relaxed'` / `{ input: 'skip' }` still skips validation per-route (now honored on BOTH transports).
-
-Routes are discovered by `@luckystack/devkit` from `src/{page}/_api/{name}_v{N}.ts` files and surfaced at runtime via `getRuntimeApiMaps()` (from `@luckystack/core`). Consumers normally do not call these handlers directly — `@luckystack/server` wires them into the socket.io server and the HTTP request listener.
-
-## When to USE this package
-
-- You are building a custom transport (queue worker, gRPC bridge, Lambda adapter) and need to invoke the LuckyStack API pipeline for a registered route.
-- You are extending the framework with a new hook in the API request lifecycle (`preApiValidate`, `preApiExecute`, `preApiRespond`, `transformApiResponse`, `postApiRespond`, etc.).
-- You need to understand or document the exact ordering of auth -> rate limit -> validate -> execute -> respond.
-
-## When to NOT suggest this (yet)
-
-- Writing a new app-level API endpoint: create a file under `src/{page}/_api/{name}_v{N}.ts` instead. The handler in this package will pick it up automatically.
-- Client-side request invocation: use `apiRequest` from `@luckystack/core` (client subpath), not anything from this package.
-- Plain Express/Koa middleware: this package assumes the LuckyStack runtime maps + hook system. Do not graft it onto an unrelated server framework.
-- Changing the request envelope shape: that contract lives in `@luckystack/core` (response normalization, error codes, locale extraction). Edit there, not here.
-
-## Function Index
-
-| Function / Export | One-liner | Deep doc |
-| --- | --- | --- |
-| `handleApiRequest({ msg, socket, token })` (default export) | Socket.io transport adapter. Validates `apiMessage`, resolves the route via `getRuntimeApiMaps`, runs the full pipeline, emits the response on the `buildApiResponseEventName(responseIndex)` channel. Also handles the built-in `system/logout` shortcut. | -> docs/api-request-lifecycle.md |
-| `handleHttpApiRequest({ name, data, token, requesterIp?, xLanguageHeader?, acceptLanguageHeader?, method?, stream? })` | HTTP transport adapter for `/api/*` POST/GET/PUT/DELETE. Same pipeline as the socket variant plus HTTP-method validation (`inferHttpMethod` or route-declared `httpMethod`). Returns `ApiNetworkResponse` and optionally pipes stream events via the provided `stream` callback (SSE on the server side). | -> docs/api-request-lifecycle.md |
-| Type: `ApiHttpStreamEvent` | Shape of stream payloads emitted by streaming HTTP endpoints (alias of `Record<string, unknown>` extended with route-specific keys). Consumers writing SSE bridges import this. | -> docs/api-request-lifecycle.md |
-
-### Internal pipeline helpers (not exported, listed for AI context)
-
-These live inside `handleApiRequest.ts` / `handleHttpApiRequest.ts` and are referenced in deep docs:
-
-| Helper | Role |
-| --- | --- |
-| `validateApiMessage` | Rejects malformed socket envelopes (missing `responseIndex`, non-object/array data). |
-| `checkApiAuth` | `auth.login` gate + null-safe `validateRequest` for additional auth predicates (an anonymous caller on a public route with `additional` predicates is cleanly forbidden, not a throw — api F4). Dispatches the `apiAuthRejected` hook (`void`) on every fail path (api F9). |
-| `applyApiRateLimits` | Per-route bucket (`apiEntry.rateLimit` or `defaultApiLimit`, keyed on the validated `user.id` or the resolved IP — never the raw token; basis overridable via `rateLimiting.identity`) + global per-IP bucket (`defaultIpLimit`, skippable for loopback in dev via `rateLimiting.skipLoopbackInDev`). Fires `rateLimitExceeded` hook on reject. |
-| `applyGlobalIpRateLimit` | Shared global per-IP `ip:<ip>:api:all` bucket helper; also applied to the built-in `system/logout` shortcut so it can't be spammed uncapped. |
-| `executeApiHandler` | Wraps `apiEntry.main(...)` in `tryCatch`. Span open/close + identity propagation moved to `preApiExecute`/`postApiExecute` hook subscribers in `@luckystack/error-tracking` (no direct `startSpan` in this handler). |
-| `normalizeApiResponse` (in `_shared/responseEnvelope.ts`) | Normalizes success/error result into the wire envelope, inferring `httpStatus` via `defaultHttpStatusForResponse`. |
-| `emitApiResult` | Runs `preApiRespond` / `transformApiResponse` / `postApiRespond` hooks and emits on the socket. |
-| `warnIfInputTypeMissing` (in `_shared/inputTypeWarning.ts`) | Dev-only one-shot warning when a strict-mode route has no generated `inputType` (Zod validation effectively disabled). |
-
-## Pipeline order (authoritative)
-
-Both transports execute the same sequence. Deviating is a breaking change.
-
-1. Parse message / payload shape (`validateApiMessage` / inline checks; rejects arrays).
-2. `readSession(token)` -> resolve `user` (may be null on public routes). Identity propagation to error trackers happens later via the `preApiExecute` hook subscriber, NOT a direct `setSentryUser` here.
-3. `parseTransportRouteName` (rejects invalid `api/<page>/<name>/v<N>` shapes).
-4. Built-in `system/logout` shortcut (socket transport only; now subject to the global per-IP bucket first).
-5. `getRuntimeApiMaps()` -> reject with `api.notFound` if the route is unknown.
-6. `checkApiAuth` (login + `validateRequest`).
-7. `applyApiRateLimits` (per-route -> global IP).
-8. **HTTP-only**: method check (`inferHttpMethod` vs `method`). The `httpMethod` route export and the `inferHttpMethod` heuristic are **HTTP-only**. The socket transport does NOT enforce the declared HTTP method — all routes are callable over WebSocket regardless of method declaration (socket.io has no method concept). Do not rely on `httpMethod` for authorization; use `auth` predicates or `preSocketMessage` for socket-specific gates.
-9. `preApiValidate` hook -> `validateInputByType` (skippable on BOTH transports via `validation: 'relaxed'` or `{ input: 'skip' }`) -> `postApiValidate` hook. `validateInputByType` now runs the structural validator in production too (gated by `validation.runtimeMode`, default `'enforce'`); set `validation.runtimeMode: 'off'` to restore the old prod no-op. See the caveat at the top.
-10. `preApiExecute` hook (stop-signal aborts with localized error).
-11. `executeApiHandler` (wrapped in `tryCatch`; span/identity via the `pre/postApiExecute` hook subscribers, not a direct span here).
-12. `postApiExecute` hook (gets `result`, `error`, `durationMs`).
-13. `normalizeApiResponse` -> `preApiRespond` -> `transformApiResponse` -> emit -> `postApiRespond`.
-
-## Config keys
-
-Read at request time via `getProjectConfig()` (from `@luckystack/core`). All live under `projectConfig`:
-
-- `logging.devLogs` — gate for verbose per-request `getLogger().debug/warn/error` output.
-- `logging.stream` — gate for `emitStream` payload logging.
-- `dev.warnOnMissingInputType` — toggles the one-shot `warnIfInputTypeMissing` developer hint.
-- `rateLimiting.defaultApiLimit` — fallback per-route limit when an API file does not export `rateLimit`. `false` disables.
-- `rateLimiting.defaultIpLimit` — global per-IP bucket across all API routes. `false` disables.
-- `rateLimiting.windowMs` — window for both buckets.
-- `rateLimiting.skipLoopbackInDev` — when `true` (default `false`), skips ONLY the global per-IP ABUSE bucket for loopback IPs in non-production (per-route bucket still applies). Lets a dev / the test runner hammer localhost without tripping the cross-route cap. Gated on this explicit flag (not inferred from `NODE_ENV` + a spoofable address) and on `isLoopbackIp(resolvedIp)`.
-- `rateLimiting.identity` — optional `(params) => { scope: 'user'|'ip'|'custom'; id } | null` callback that overrides the per-route bucket BASIS (api-key / tenant). Returning `null` falls back to the default (validated `user.id`, else resolved IP — NEVER the raw token).
-
-No project env vars or secrets are read directly by this package — only the ambient `process.env.NODE_ENV` (for the dev-only loopback rate-limit skip in `handleHttpApiRequest`); all other toggles travel through `@luckystack/core`'s config layer.
-
-## Peer dependencies
-
-- **Required (runtime deps)**: `@luckystack/core`, `@luckystack/error-tracking`. **`@luckystack/login` is NOT a dependency** (0.2.0 decoupling) — sessions resolve through core's `readSession` / session-provider registry, with login as the default *provider* (optional package), not a hard runtime dep.
-- **Required peer**: `socket.io@^4.8.0` (only consumed for the `Socket` type — the HTTP entry point does not need a live socket.io instance at call time).
-- **Optional peer**: `@prisma/client@^6.19.0` — only needed when the active session/user provider uses the default Prisma client. Streaming uses an injected callback, not an external SSE library.
-
-## Hooks consumed
-
-This package only dispatches hooks (it does not register any). Consumers register handlers via `dispatchHook` / the hook registry in `@luckystack/core`. Hooks emitted, in order:
-
-- `preSocketMessage` — (socket transport only) at the very top, before session lookup / route resolution / auth. Stop signal rejects the message. Transport-level seam mirroring `preHttpRequest`; `channel: 'api'`.
-- `preApiValidate` — before Zod validation runs.
-- `postApiValidate` — after validation, with `validation: { status, message? }`.
-- `preApiExecute` — may return a stop signal (`errorCode`, `httpStatus?`) to short-circuit.
-- `postApiExecute` — observation point with `result`, `error`, `durationMs`.
-- `preApiRespond` — last chance to mutate or swap `payload.response`; stop signal converts to localized error.
-- `transformApiResponse` — purely mutative; runs between `preApiRespond` and socket/HTTP emit.
-- `postApiRespond` — observation-only; response is already on the wire.
-- `rateLimitExceeded` — fires when a bucket rejects (scope: `route` | `user` | `ip`).
-- `apiAuthRejected` — fires on every auth-fail path (login required, `additional[]` predicate failed, or a misconfigured predicate). Observational (`void`-dispatched, stop signal ignored); payload `{ routeName, reason, userId, ip?, transport?, failedKey? }`. Lets abuse-detection / audit subscribers see failed authorizations (e.g. credential-stuffing) without forking the handler.
-
-Deep behavior for each hook lives in `@luckystack/core`'s hook registry doc.
-
-## Related
-
-- Architecture deep dives: `/docs/ARCHITECTURE_API.md`, `/docs/ARCHITECTURE_ROUTING.md`.
-- Consumer quickstart: `./README.md`.
-- Generated-type contract: `/docs/ARCHITECTURE_ROUTING.md` (see "Generated maps") and repository-root `CLAUDE.md` rule 21 (no `unknown`/`any` casts).
-- Session source: `@luckystack/core`'s session-provider registry — `readSession(token)` / `performLogout(...)` (see `docs/ARCHITECTURE_SESSION.md`). `@luckystack/login` is the DEFAULT provider when installed, not a hard dep. Shared types `BaseSessionLayout` / `AuthProps` come from `@luckystack/core`.
-- Runtime map source: `@luckystack/core` `getRuntimeApiMaps()` + `@luckystack/devkit` emitter.