@luckystack/api 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@luckystack/api` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -0,0 +1,106 @@
+# @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.

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +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).

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { apiMessage, HttpMethod } from '@luckystack/core';
+import { Socket } from 'socket.io';
+
+interface handleApiRequestType {
+    msg: apiMessage;
+    socket: Socket;
+    token: string | null;
+}
+declare function handleApiRequest({ msg, socket, token }: handleApiRequestType): Promise<boolean | void>;
+
+/**
+ * HTTP API Request Handler
+ *
+ * Handles API requests coming via HTTP (instead of WebSocket).
+ * Reuses existing API handlers but returns results as HTTP response.
+ *
+ * Payload format:
+ * ```json
+ * {
+ *   "name": "api/examples/publicApi",
+ *   "data": { "message": "hello" }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In server.ts
+ * if (pathname.startsWith('/api/')) {
+ *   const token = extractTokenFromRequest(req);
+ *   const body = await parseJsonBody(req);
+ *   const result = await handleHttpApiRequest({ name: body.name, data: body.data, token });
+ *   res.end(JSON.stringify(result));
+ * }
+ * ```
+ */
+interface HttpApiRequestParams {
+    name: string;
+    data: Record<string, unknown>;
+    token: string | null;
+    requesterIp?: string;
+    xLanguageHeader?: string | string[];
+    acceptLanguageHeader?: string | string[];
+    /** HTTP method from the request */
+    method?: HttpMethod;
+    stream?: (payload: ApiHttpStreamEvent) => void;
+    /**
+     * Optional AbortSignal. The HTTP server (`@luckystack/server`) wires this
+     * to `req.on('close', ...)` so a closed SSE/HTTP connection aborts in-flight
+     * stream emits. Handlers receive it as `abortSignal` in params.
+     */
+    abortSignal?: AbortSignal;
+}
+type ApiNetworkResponse<T = Record<string, unknown>> = ({
+    status: 'success';
+    httpStatus: number;
+} & T) | {
+    status: 'error';
+    httpStatus: number;
+    message: string;
+    errorCode: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+};
+type ApiStreamPayload = Record<string, unknown>;
+type ApiHttpStreamEvent = ApiStreamPayload;
+declare function handleHttpApiRequest(params: HttpApiRequestParams): Promise<ApiNetworkResponse>;
+
+export { type ApiHttpStreamEvent, handleApiRequest, handleHttpApiRequest };