@luckystack/api 0.10.1 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,7 @@
+# @luckystack/api — design context
+
+API is the route-adapter layer between generated runtime maps and socket/HTTP transports; server bootstraps it. Keep auth, validation, rate limiting, hooks and response normalization consistent across transports. Their implementations, not a hand-maintained step list, are authoritative: `src/handleApiRequest.ts`, `src/handleHttpApiRequest.ts`, `src/_shared/`, `src/transportParity.test.ts`.
+
+Do not use an HTTP method declaration as an authorization gate: sockets have no HTTP method. Authenticate and authorize with route auth policy on both transports. Validate input before application execution; do not expose schema-error details from a protected route to unauthorized callers. Derive per-user limiter identity from validated session identity, not an attacker-supplied token; treat forwarded IP headers as trusted only behind the configured proxy (`../core/src/resolveClientIp.ts`). Keep observational hooks observational and do not bypass error normalization.
+
+Type maps are generated contracts, not a reason for unsafe casts: regenerate artifacts and correct the generator/source when typing fails. See `docs/generated-types.md` and repository `AGENTS.md`.

package/CHANGELOG.md

@@ -5,7 +5,12 @@ 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.11.0] - 2026-10-14
+
+### Changed
+
+- Type declarations are emitted per source file by TypeScript 7 (`tsc -b`) instead of one bundled `.d.ts` per entry, so the framework build no longer runs package by package. The exported types are unchanged; relative imports inside the declarations carry `.js`, so `moduleResolution: "node16"`/`"nodenext"` projects resolve them as before.
+- Package design guidance now ships as `AGENTS.md`, not `CLAUDE.md`. Handwritten docs focus on rationale and safety; exact API contracts remain in installed declarations/source.
 
 ## [0.8.4] - 2026-08-17
 

package/README.md

@@ -1,106 +1,5 @@
 # @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.
+Type-safe API handlers for LuckyStack's socket-first transport with HTTP fallback. Install with `npm install @luckystack/api socket.io`; add optional `@prisma/client` for Prisma-backed routes (see `package.json`). The server package normally wires the handlers; route discovery and typed maps are generated by devkit.
 
-## Install
-
-```bash
-npm install @luckystack/api socket.io
-# Optional Prisma-backed route code: npm install @prisma/client
-```
-
-## 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. **Authenticates** via `readSession` from `@luckystack/core` (the session-provider registry; `@luckystack/login` is the optional default provider, not a hard dependency) when `auth.login === true`. Auth runs first so unauthenticated probes can't enumerate routes or learn input shape from the validation message.
-2. **Rate-limits** with two buckets via `checkRateLimit` from `@luckystack/core`: a per-route bucket keyed on the validated `user.id` (anonymous callers fall back to the resolved IP — never the raw session token, so re-login can't reset the limit; the basis is overridable via `rateLimiting.identity`) plus a global per-IP abuse bucket.
-3. **Validates** the inbound payload against the Zod schema generated from your `ApiParams['data']` interface (via `@luckystack/devkit`).
-4. **Dispatches** the `preApiExecute` hook (may abort with a stop signal).
-5. **Calls** your `main(...)` and captures thrown errors via `tryCatch` (fanned out to every registered error tracker).
-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 repository-root [`CLAUDE.md`](../../CLAUDE.md) rule 21). 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/error-tracking` (`@luckystack/login` is NOT a runtime dependency — sessions resolve through core's session-provider registry; login is the optional default provider)
-- Required peer: `socket.io@^4.8.0`
-- Optional peer: `@prisma/client@^6.19.0` — only needed when the active session/user provider uses the default Prisma client.
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+Keep the same authorization and validation boundary on both transports. A declared HTTP method cannot protect a WebSocket route. When route inference fails, regenerate artifacts and fix the source type instead of casting. See [design context](./AGENTS.md), [auth rationale](./docs/auth-flow.md) and [generated types](./docs/generated-types.md). For signatures and route declarations consult `src/` and the generated map.

package/dist/_shared/apiTypes.d.ts

@@ -0,0 +1,68 @@
+import type { AuthProps, BaseSessionLayout as SessionLayout, ErrorFormatter, HttpMethod } from '@luckystack/core';
+/** Loosely-typed stream payload emitted by streaming endpoints. */
+export type ApiStreamPayload = Record<string, unknown>;
+export interface RuntimeSuccessResponse {
+    status: 'success';
+    message?: string;
+    httpStatus?: number;
+    [key: string]: unknown;
+}
+export interface RuntimeErrorResponse {
+    status: 'error';
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+    message?: string;
+    [key: string]: unknown;
+}
+/** Discriminated union returned by a registered API handler's `main`. */
+export type RuntimeApiResponse = RuntimeSuccessResponse | RuntimeErrorResponse;
+/** Narrowing guard for an object that is already a `RuntimeApiResponse`. */
+export declare const isRuntimeApiResponse: (value: unknown) => value is RuntimeApiResponse;
+export interface ApiFlushPressureOptions {
+    thresholdBytes?: number;
+}
+export type ApiFlushPressure = (options?: ApiFlushPressureOptions) => Promise<void>;
+/** Shape every registered API route exposes on the runtime map. */
+export interface RuntimeApiEntry {
+    auth: AuthProps;
+    main: (params: {
+        data: Record<string, unknown>;
+        user: SessionLayout | null;
+        functions: Record<string, unknown>;
+        stream: (payload?: ApiStreamPayload) => void;
+        abortSignal: AbortSignal;
+        flushPressure: ApiFlushPressure;
+    }) => Promise<RuntimeApiResponse> | RuntimeApiResponse;
+    inputType?: string;
+    inputTypeFilePath?: string;
+    rateLimit?: number | false;
+    httpMethod?: HttpMethod;
+    /**
+     * Per-route validation strictness.
+     * `'strict'` (default): runtime Zod validation runs, mismatched payloads
+     *   are rejected with `api.invalidInputType`.
+     * `'relaxed'` / `{ input: 'skip' }`: skip the validate step. Use for public
+     *   webhooks that receive third-party-shaped payloads you can't model in TS,
+     *   or for migration windows when input shapes are in flux.
+     */
+    validation?: 'strict' | 'relaxed' | {
+        input: 'skip' | 'strict';
+    };
+    /**
+     * Per-route error response formatter. Receives the normalized error
+     * envelope + context and returns the shape to emit. Falls back to the
+     * global formatter from `registerErrorFormatter(...)`, then to the
+     * framework default `normalizeErrorResponse`.
+     */
+    errorFormatter?: ErrorFormatter;
+}
+/** Mutable envelope shape passed between respond-phase hooks + the formatter. */
+export interface ApiResponseEnvelope {
+    status: 'success' | 'error';
+    httpStatus?: number;
+    [key: string]: unknown;
+}

package/dist/_shared/applyApiRateLimits.d.ts

@@ -0,0 +1,30 @@
+import type { BaseSessionLayout as SessionLayout } from '@luckystack/core';
+export interface ApplyApiRateLimitsArgs {
+    /** Effective client IP (already resolved by the caller's transport adapter). */
+    resolvedIp: string;
+    token: string | null;
+    user: SessionLayout | null;
+    resolvedName: string;
+    rateLimit: number | false | undefined;
+    transport: 'socket' | 'http';
+    /**
+     * When true, skip the global-IP (`ip:…:api:all`) bucket check. Used by the
+     * HTTP transport to honour `rateLimiting.skipLoopbackInDev` for loopback
+     * callers without duplicating bucket logic here. The socket transport never
+     * sets this (loopback skip is HTTP-only).
+     */
+    skipGlobalIpBucket?: boolean;
+}
+export interface ApplyApiRateLimitsResult {
+    /** True when all buckets allow the request; false when any bucket exceeded. */
+    allowed: boolean;
+    /** The error payload to emit when `allowed` is false. */
+    errorCode?: string;
+    resetIn?: number;
+}
+/**
+ * Checks per-route + global-IP rate-limit buckets for an API request.
+ * Returns `{ allowed: true }` when all buckets allow through, or
+ * `{ allowed: false, errorCode, resetIn }` when any bucket is full.
+ */
+export declare const applyApiRateLimits: ({ resolvedIp, user, resolvedName, rateLimit, transport, skipGlobalIpBucket, }: ApplyApiRateLimitsArgs) => Promise<ApplyApiRateLimitsResult>;

package/dist/_shared/backpressure.d.ts

@@ -0,0 +1,4 @@
+import type { Socket } from 'socket.io';
+import type { ApiFlushPressure } from './apiTypes.js';
+export declare const createApiFlushPressure: (socket: Socket, abortSignal: AbortSignal) => ApiFlushPressure;
+export declare const httpApiFlushPressureNoop: ApiFlushPressure;

package/dist/_shared/httpValidationStage.d.ts

@@ -0,0 +1,14 @@
+import type { BaseSessionLayout as SessionLayout } from '@luckystack/core';
+import type { RuntimeApiEntry } from './apiTypes.js';
+export declare const runHttpApiValidation: ({ resolvedName, inputType, inputTypeFilePath, requestData, user, validation, }: {
+    resolvedName: string;
+    inputType?: string;
+    inputTypeFilePath?: string;
+    requestData: Record<string, unknown>;
+    user: SessionLayout | null;
+    validation: RuntimeApiEntry['validation'];
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+}>;

package/dist/_shared/inputTypeWarning.d.ts

@@ -0,0 +1 @@
+export declare const warnIfInputTypeMissing: (resolvedName: string, inputType: string | undefined) => void;

package/dist/_shared/logFlags.d.ts

@@ -0,0 +1,4 @@
+/** Gate for verbose per-request debug/warn/error logging. */
+export declare const shouldLogDev: () => boolean;
+/** Gate for `emitStream` payload logging. */
+export declare const shouldLogStream: () => boolean;

package/dist/_shared/rateLimitIdentity.d.ts

@@ -0,0 +1 @@
+export { deriveTokenBucketId } from '@luckystack/core';

package/dist/_shared/requestLifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { Socket } from 'socket.io';
+import type { ApiStreamPayload, ApiFlushPressure } from './apiTypes.js';
+export interface ApiRequestLifecycle {
+    abortController: AbortController;
+    abortSignal: AbortSignal;
+    emitStream: (payload?: ApiStreamPayload) => void;
+    flushPressure: ApiFlushPressure;
+    cleanupRequest: () => void;
+}
+export declare const createApiRequestLifecycle: ({ socket, responseIndex, resolvedName }: {
+    socket: Socket;
+    responseIndex: number;
+    resolvedName: string;
+}) => ApiRequestLifecycle;

package/dist/_shared/responseEnvelope.d.ts

@@ -0,0 +1,9 @@
+import type { BaseSessionLayout as SessionLayout } from '@luckystack/core';
+import type { ApiResponseEnvelope, RuntimeApiResponse } from './apiTypes.js';
+export declare const normalizeApiResponse: ({ resolvedName, error, result, preferredLocale, user, }: {
+    resolvedName: string;
+    error: Error | null;
+    result: RuntimeApiResponse | undefined | null;
+    preferredLocale: string | null | undefined;
+    user: SessionLayout | null;
+}) => ApiResponseEnvelope;

package/dist/_shared/socketValidationStage.d.ts

@@ -0,0 +1,13 @@
+import type { BaseSessionLayout as SessionLayout } from '@luckystack/core';
+import type { RuntimeApiEntry } from './apiTypes.js';
+type EmitInvalidInputType = () => void | Promise<void>;
+export declare const resolveValidationMode: (validation: RuntimeApiEntry['validation']) => 'strict' | 'relaxed';
+export declare const runSocketApiValidation: ({ apiEntry, resolvedName, normalizedData, user, cleanupRequest, emitInvalidInputType, }: {
+    apiEntry: RuntimeApiEntry;
+    resolvedName: string;
+    normalizedData: Record<string, unknown>;
+    user: SessionLayout | null;
+    cleanupRequest: () => void;
+    emitInvalidInputType: EmitInvalidInputType;
+}) => Promise<boolean>;
+export {};

package/dist/handleApiRequest.d.ts

@@ -0,0 +1,9 @@
+import type { apiMessage } from '@luckystack/core';
+import { Socket } from 'socket.io';
+interface handleApiRequestType {
+    msg: apiMessage;
+    socket: Socket;
+    token: string | null;
+}
+export default function handleApiRequest(args: handleApiRequestType): Promise<void>;
+export {};

package/dist/handleHttpApiRequest.d.ts

@@ -0,0 +1,60 @@
+import { HttpMethod } from '@luckystack/core';
+import type { ApiStreamPayload } from './_shared/apiTypes.js';
+/**
+ * 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;
+    }[];
+};
+export type ApiHttpStreamEvent = ApiStreamPayload;
+export declare function handleHttpApiRequest(params: HttpApiRequestParams): Promise<ApiNetworkResponse>;
+export {};

package/dist/index.d.ts

@@ -1,72 +1,3 @@
-import { apiMessage, HttpMethod } from '@luckystack/core';
-import { Socket } from 'socket.io';
-
-interface handleApiRequestType {
-    msg: apiMessage;
-    socket: Socket;
-    token: string | null;
-}
-declare function handleApiRequest(args: handleApiRequestType): Promise<void>;
-
-/** Loosely-typed stream payload emitted by streaming endpoints. */
-type ApiStreamPayload = Record<string, unknown>;
-
-/**
- * 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 ApiHttpStreamEvent = ApiStreamPayload;
-declare function handleHttpApiRequest(params: HttpApiRequestParams): Promise<ApiNetworkResponse>;
-
-export { type ApiHttpStreamEvent, handleApiRequest, handleHttpApiRequest };
+export { default as handleApiRequest } from './handleApiRequest.js';
+export { handleHttpApiRequest } from './handleHttpApiRequest.js';
+export type { ApiHttpStreamEvent } from './handleHttpApiRequest.js';