@luckystack/api 0.1.8 → 0.2.0

package/CLAUDE.md

@@ -1,106 +1,113 @@
-# @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).
-
-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 data). |
-| `checkApiAuth` | `auth.login` gate + `validateRequest` for additional auth predicates. |
-| `applyApiRateLimits` | Per-route bucket (`apiEntry.rateLimit` or `defaultApiLimit`) + global per-IP bucket (`defaultIpLimit`). Fires `rateLimitExceeded` hook on reject. |
-| `executeApiHandler` | Wraps `apiEntry.main(...)` in `tryCatch` and a `startSpan` from `@luckystack/error-tracking`. |
-| `buildApiResponseEnvelope` | Normalizes success/error result into the wire envelope, inferring `httpStatus` via `defaultHttpStatusForResponse`. |
-| `emitApiResult` | Runs `preApiRespond` / `transformApiResponse` / `postApiRespond` hooks and emits on the socket. |
-| `warnIfInputTypeMissing` | Dev-only one-shot warning when a 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).
-2. `getSession(token)` -> `setSentryUser(...)`.
-3. `parseTransportRouteName` (rejects invalid `api/<page>/<name>/v<N>` shapes).
-4. Built-in `system/logout` shortcut (socket transport only).
-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`).
-9. `preApiValidate` hook -> `validateInputByType` (skippable on socket transport via `validation: 'relaxed'` or `{ input: 'skip' }`) -> `postApiValidate` hook.
-10. `preApiExecute` hook (stop-signal aborts with localized error).
-11. `executeApiHandler` (wrapped in `tryCatch` + Sentry span).
-12. `postApiExecute` hook (gets `result`, `error`, `durationMs`).
-13. `buildApiResponseEnvelope` -> `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.
-
-No environment variables are read directly by this package — secrets and toggles travel through `@luckystack/core`'s config layer.
-
-## Peer dependencies
-
-- **Required (runtime deps)**: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`.
-- **Required (peer)**:
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core` session storage).
-  - `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).
-- **No optional peers.** 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:
-
-- `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`).
-
-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 root `CLAUDE.md` rule 16 (no `unknown`/`any` casts).
-- Session source: `@luckystack/login` (`getSession`, `logout`, `BaseSessionLayout`, `AuthProps`).
-- Runtime map source: `@luckystack/core` `getRuntimeApiMaps()` + `@luckystack/devkit` emitter.
+# @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 environment variables are read directly by this package — secrets and 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)**:
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core` session storage).
+  - `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).
+- **No optional peers.** 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 root `CLAUDE.md` rule 16 (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.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Mathijs van Melick
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,106 +1,106 @@
-# @luckystack/api
-
-> Type-safe API request handlers for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). WebSocket-first via socket.io with HTTP fallback. File-based routing, generated route map, integrated rate limiting, validation, hooks, and error-tracking tracing.
-
-## Install
-
-```bash
-npm install @luckystack/api @luckystack/core @luckystack/login @luckystack/error-tracking socket.io
-```
-
-## Quickstart
-
-API endpoints live in `src/{page}/_api/{name}_v{N}.ts` and are picked up by the file-based router. Each file exports `main`, plus optional metadata (`auth`, `method`, `rateLimit`).
-
-```ts
-// src/settings/_api/updateUser_v1.ts
-import type { AuthProps } from '@luckystack/core';
-import type { ApiResponse } from '@luckystack/core';
-
-export const rateLimit: number | false = 20;
-export const method = '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 }: ApiParams): Promise<ApiResponse> => {
-  await prisma.user.update({ where: { id: user.id }, data: { name: data.name } });
-  return { status: 'success', result: { ok: true } };
-};
-```
-
-The package exposes the two transport adapters that `@luckystack/server` wires into Socket.io and HTTP:
-
-```ts
-import handleApiRequest from '@luckystack/api';
-import { handleHttpApiRequest } from '@luckystack/api';
-
-io.on('connection', socket => {
-  socket.on('apiRequest', msg => handleApiRequest({ msg, socket, token }));
-});
-
-httpServer.on('request', async (req, res) => {
-  if (req.url?.startsWith('/api/')) {
-    const result = await handleHttpApiRequest({ name: body.name, data: body.data, token });
-    res.end(JSON.stringify(result));
-  }
-});
-```
-
-You typically don't call these yourself — `createLuckyStackServer` does. Use this package directly only when building a custom transport.
-
-## How it integrates
-
-1. **Validates** the inbound payload against the Zod schema generated from your `ApiParams['data']` interface (via `@luckystack/devkit`).
-2. **Rate-limits** by IP + token using `checkRateLimit` from `@luckystack/core`.
-3. **Authenticates** via `getSession` from `@luckystack/login` when `auth.login === true`.
-4. **Dispatches** the `preApiExecute` hook (may abort with a stop signal).
-5. **Calls** your `main(...)` and captures errors via `tryCatch` (auto-forwarded to Sentry).
-6. **Dispatches** the `postApiExecute` hook with the result + duration.
-7. **Returns** the response via socket `ack` or HTTP body / SSE stream.
-
-## Generated types
-
-`apiRequest` (in `@luckystack/core/client`) is fully typed against the route map emitted by `@luckystack/devkit` from your `_api/*` files (default location: `src/_sockets/apiTypes.generated.ts`). Use route-name + version literals so inference works:
-
-```ts
-const result = await apiRequest({
-  name: 'settings/updateUser',
-  version: 'v1',
-  data: { name: 'Alice' },
-});
-
-if (result.status === 'success') {
-  // result is typed from the matching `main` return type.
-}
-```
-
-Do not wrap `apiRequest` in `unknown` / `any` shims (see `.claude/CLAUDE.md` rule 16). If inference fails, fix the typing source or regenerate maps instead.
-
-## Public API
-
-| Export | Purpose |
-| --- | --- |
-| `handleApiRequest({ msg, socket, token })` | Socket.io request handler (default export). |
-| `handleHttpApiRequest({ name, data, token, ... })` | HTTP fallback for `/api/*` routes; returns `Promise<ApiNetworkResponse>` and supports SSE streaming via a `stream` callback. |
-| Type: `ApiHttpStreamEvent` | SSE event shape emitted by streaming endpoints. |
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_API.md`](../../docs/ARCHITECTURE_API.md) — full request lifecycle, streaming, error contract.
-- [`docs/ARCHITECTURE_ROUTING.md`](../../docs/ARCHITECTURE_ROUTING.md) — `_api/` file conventions and method inference.
-
-## Dependencies
-
-- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
-  - `socket.io@^4.8.0`
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+# @luckystack/api
+
+> Type-safe API request handlers for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). WebSocket-first via socket.io with HTTP fallback. File-based routing, generated route map, integrated rate limiting, validation, hooks, and error-tracking tracing.
+
+## Install
+
+```bash
+npm install @luckystack/api @luckystack/core @luckystack/login @luckystack/error-tracking socket.io
+```
+
+## Quickstart
+
+API endpoints live in `src/{page}/_api/{name}_v{N}.ts` and are picked up by the file-based router. Each file exports `main`, plus optional metadata (`auth`, `method`, `rateLimit`).
+
+```ts
+// src/settings/_api/updateUser_v1.ts
+import type { AuthProps } from '@luckystack/core';
+import type { ApiResponse } from '@luckystack/core';
+
+export const rateLimit: number | false = 20;
+export const method = '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 }: ApiParams): Promise<ApiResponse> => {
+  await prisma.user.update({ where: { id: user.id }, data: { name: data.name } });
+  return { status: 'success', result: { ok: true } };
+};
+```
+
+The package exposes the two transport adapters that `@luckystack/server` wires into Socket.io and HTTP:
+
+```ts
+import handleApiRequest from '@luckystack/api';
+import { handleHttpApiRequest } from '@luckystack/api';
+
+io.on('connection', socket => {
+  socket.on('apiRequest', msg => handleApiRequest({ msg, socket, token }));
+});
+
+httpServer.on('request', async (req, res) => {
+  if (req.url?.startsWith('/api/')) {
+    const result = await handleHttpApiRequest({ name: body.name, data: body.data, token });
+    res.end(JSON.stringify(result));
+  }
+});
+```
+
+You typically don't call these yourself — `createLuckyStackServer` does. Use this package directly only when building a custom transport.
+
+## How it integrates
+
+1. **Validates** the inbound payload against the Zod schema generated from your `ApiParams['data']` interface (via `@luckystack/devkit`).
+2. **Rate-limits** by IP + token using `checkRateLimit` from `@luckystack/core`.
+3. **Authenticates** via `getSession` from `@luckystack/login` when `auth.login === true`.
+4. **Dispatches** the `preApiExecute` hook (may abort with a stop signal).
+5. **Calls** your `main(...)` and captures errors via `tryCatch` (auto-forwarded to Sentry).
+6. **Dispatches** the `postApiExecute` hook with the result + duration.
+7. **Returns** the response via socket `ack` or HTTP body / SSE stream.
+
+## Generated types
+
+`apiRequest` (in `@luckystack/core/client`) is fully typed against the route map emitted by `@luckystack/devkit` from your `_api/*` files (default location: `src/_sockets/apiTypes.generated.ts`). Use route-name + version literals so inference works:
+
+```ts
+const result = await apiRequest({
+  name: 'settings/updateUser',
+  version: 'v1',
+  data: { name: 'Alice' },
+});
+
+if (result.status === 'success') {
+  // result is typed from the matching `main` return type.
+}
+```
+
+Do not wrap `apiRequest` in `unknown` / `any` shims (see `.claude/CLAUDE.md` rule 16). If inference fails, fix the typing source or regenerate maps instead.
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `handleApiRequest({ msg, socket, token })` | Socket.io request handler (default export). |
+| `handleHttpApiRequest({ name, data, token, ... })` | HTTP fallback for `/api/*` routes; returns `Promise<ApiNetworkResponse>` and supports SSE streaming via a `stream` callback. |
+| Type: `ApiHttpStreamEvent` | SSE event shape emitted by streaming endpoints. |
+
+## Related architecture docs
+
+- [`docs/ARCHITECTURE_API.md`](../../docs/ARCHITECTURE_API.md) — full request lifecycle, streaming, error contract.
+- [`docs/ARCHITECTURE_ROUTING.md`](../../docs/ARCHITECTURE_ROUTING.md) — `_api/` file conventions and method inference.
+
+## Dependencies
+
+- Runtime: `@luckystack/core`, `@luckystack/login`, `@luckystack/error-tracking`
+- Peer (canonical ranges, standardized 2026-05-07):
+  - `@prisma/client@^6.19.0` (transitively required via `@luckystack/core`)
+  - `socket.io@^4.8.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -6,7 +6,10 @@ interface handleApiRequestType {
     socket: Socket;
     token: string | null;
 }
-declare function handleApiRequest({ msg, socket, token }: handleApiRequestType): Promise<boolean | void>;
+declare function handleApiRequest(args: handleApiRequestType): Promise<void>;
+
+/** Loosely-typed stream payload emitted by streaming endpoints. */
+type ApiStreamPayload = Record<string, unknown>;
 
 /**
  * HTTP API Request Handler
@@ -63,7 +66,6 @@ type ApiNetworkResponse<T = Record<string, unknown>> = ({
         value: string | number | boolean;
     }[];
 };
-type ApiStreamPayload = Record<string, unknown>;
 type ApiHttpStreamEvent = ApiStreamPayload;
 declare function handleHttpApiRequest(params: HttpApiRequestParams): Promise<ApiNetworkResponse>;