@luckystack/api 0.1.0

package/docs/generated-types.md

@@ -0,0 +1,264 @@
+# Generated Types
+
+> Last updated: 2026-05-20
+
+## Overview
+
+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 repo root contract (`.claude/CLAUDE.md` rule 16) 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 `api.invalidInputType` + `400`, surfacing the validator's `message` as `errorParams[0].value`.
+
+`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/CLAUDE.md` §16): **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/CLAUDE.md`](../../../.claude/CLAUDE.md) §16

package/docs/rate-limiting.md

@@ -0,0 +1,188 @@
+# Rate Limiting
+
+> Last updated: 2026-05-20
+
+## Overview
+
+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' : 'route'`, 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")

package/docs/routing-conventions.md

@@ -0,0 +1,164 @@
+# Routing Conventions
+
+> Last updated: 2026-05-20
+
+## Overview
+
+`@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` + Sentry 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`