@luckystack/core 0.10.2 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,11 @@
+# @luckystack/core — design context
+
+Core owns the shared transport contracts and registration seams used by framework packages. Register infrastructure at boot and read it at call time; do not copy config defaults into consumers or bypass registries. Source: `src/projectConfig.ts`, `src/createRegistry.ts`, `src/index.ts`, `src/client.ts`.
+
+Keep the server barrel out of browser bundles; use `@luckystack/core/client`. Extend session types in the consumer rather than editing shared base types. Do not let observability adapters break request handling; redact sensitive fields before emitting context. Source: `src/errorTrackerRegistry.ts`, `src/redactedLogKeys.ts`.
+
+Security boundaries: cookie sessions use CSRF protection; token-mode bearer credentials are supplied explicitly. Do not enable bearer fallback in cookie mode without reviewing CSRF implications (`src/extractToken.ts`). Trust forwarded IP headers only when the reverse proxy and hop count are configured (`src/resolveClientIp.ts`); rate limits depend on this identity. Never relax origin checks for convenience (`src/checkOrigin.ts`). Redis keys and socket room names must remain isolated across tenants (`src/redisKeyFormatter.ts`, `src/roomNameFormatterRegistry.ts`).
+
+Multi-instance: the per-instance socket maps must stay unreachable from consumer code by default — use the cross-instance room helper, and take the raw server only for deliberate per-instance work with a lint opt-out that says why (ADR 0061, `src/roomSockets.ts`). A room-name formatter's `userId` is context, never part of a content room's physical name (ADR 0060). The Redis-adapter key, not the Redis server, defines the socket cluster; it separates environments but not their data (`src/socketRedisAdapter.ts`).
+
+Design discussions: `docs/` in this package and repository `docs/ARCHITECTURE_AUTH.md`, `docs/ARCHITECTURE_MULTI_INSTANCE.md`. Signatures and defaults live in source, not this file.

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `@luckystack/core` 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).
 
+## [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. The `prisma` export carries an explicit `PrismaClient` type, so its declaration references `@prisma/client` instead of Prisma's generated `.prisma/client` folder.
+- 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.10.2] - 2026-10-09
 
 ### Added

package/README.md

@@ -1,91 +1,5 @@
 # @luckystack/core
 
-> Foundation package for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Socket-first transport contracts, Redis adapter, project-config registry, hooks registry, response normalization, rate limiting, and shared session types.
+Shared foundation for LuckyStack transport, configuration, session types and framework extension points. Install with `npm install @luckystack/core ioredis socket.io socket.io-client zod`. Add the optional `@prisma/client` only when using the default Prisma integration (see `package.json`). Import browser code from `@luckystack/core/client`, never the server barrel.
 
-Every other `@luckystack/*` package depends on this one.
-
-## Install
-
-```bash
-npm install @luckystack/core
-```
-
-Required peer dependencies you must install separately:
-
-```bash
-npm install ioredis socket.io socket.io-client zod
-```
-
-`@prisma/client` is an optional peer. Install it only when the project uses the default Prisma client; a registered custom database client or a DB-less project does not need it.
-
-## Quickstart
-
-The core package is mostly consumed transitively through `@luckystack/server`, `@luckystack/api`, etc. You typically only touch it directly to register your project config and to call low-level utilities.
-
-```ts
-import { registerProjectConfig, getProjectConfig, notify, redis, prisma } from '@luckystack/core';
-
-registerProjectConfig({
-  defaultLanguage: 'en',
-  session: { expiryDays: 30, basedToken: false, perUser: 'multiple' },
-  auth: {
-    emailMaxLength: 254,
-    passwordMinLength: 8,
-    passwordMaxLength: 128,
-    nameMaxLength: 64,
-    oauthStateTtlSeconds: 600,
-  },
-  // ...see ProjectConfig type for the full surface
-});
-
-const config = getProjectConfig();
-```
-
-## Subpath: `@luckystack/core/client`
-
-Browser-safe surface for the React/Vite bundle. Re-exports the pieces consumed by `@luckystack/sync`'s client transport (`projectConfig`, `notifier`, `socketState`, `offlineQueue`, `responseNormalizer`, `serviceRoute`, `socketEvents`, `socketStatusTypes`, `apiTypeStubs`, `sessionTypes`).
-
-```ts
-import { socket, isOnline, enqueueApiRequest } from '@luckystack/core/client';
-```
-
-## Public API (server entry)
-
-| Group | Exports |
-| --- | --- |
-| Project config | `registerProjectConfig`, `getProjectConfig`, `getProjectName`, `isProjectConfigRegistered`, `DEFAULT_PROJECT_CONFIG`. Types: `ProjectConfig`, `ProjectConfigInput`, `LoggingConfig`, `RateLimitingConfig`, `SessionConfig`, `SentryConfig`, `SentrySampleRates`, `HttpConfig`, `HttpStreamConfig`, `SecurityHeadersConfig`, `CorsConfig`, `AuthConfig`, `SocketConfig`, `SyncConfig`, `SyncStreamThrottleConfig`, `OfflineQueueConfig`, `DevConfig`, `PathsConfig`, `EmailConfig`, `EmailLoggingConfig`, `EmailEnvVarsConfig`, `EmailDefaultsConfig`. **`getProjectName()`** is the canonical way to read the project's Redis-prefix string — it resolves at call time in this order: (1) `projectConfig.session.projectName` if a consumer set it, (2) `process.env.PROJECT_NAME` (read after `dotenv` has loaded), (3) literal `'luckystack'` as the absolute fallback. Reach for it from any framework or project code that needs the prefix instead of duplicating the env-read pattern. |
-| Deploy + services config | `registerDeployConfig`, `getDeployConfig`, `isDeployConfigRegistered`, `registerServicesConfig`, `getServicesConfig`, `isServicesConfigRegistered`. Types: `DeployConfigShape`, `DeployResourceShape`, `DeployEnvironmentShape`, `DeployRoutingShape`, `DeployDevelopmentShape`, `ServicesConfigShape`, `ServiceDefinition`, `PresetDefinition` |
-| Runtime maps | `registerRuntimeMapsProvider`, `getRuntimeApiMaps`, `getRuntimeSyncMaps`. Types: `RuntimeMapsProvider`, `RuntimeApiMapsResult`, `RuntimeSyncMapsResult` |
-| DI clients | `registerPrismaClient`, `registerRedisClient`, `getPrismaClient`, `getRedisClient`, `isPrismaClientRegistered`, `isRedisClientRegistered` |
-| Notifier | `registerNotifier`, `getNotifier`, `notify`. Types: `Notifier`, `NotifyInput`, `NotifyParam` |
-| Email registry | `registerEmailSender`, `getEmailSender`, `isEmailSenderRegistered`. Types: `EmailSender`, `EmailMessage`, `EmailResult` (re-exported from `@luckystack/email` for convenience) |
-| Logger | `registerLogger`, `getLogger`, `isLoggerRegistered`, `resetLoggerForTests`, `createDevLogger`. Types: `Logger`, `LoggerContext`. Default logger is a thin wrapper over `console.{debug,info,warn,error}` with no color codes — safe in production. Call `registerLogger(createDevLogger())` from a dev-only entry to opt into the colored terminal output (which still depends on `initConsolelog()` to render the trailing color string). Plug in Pino / Winston / Datadog by registering an object that satisfies `Logger`. |
-| Redacted log keys | `registerRedactedLogKeys`, `getRedactedLogKeys`, `isRedactedLogKey`, `resetRedactedLogKeysForTests` |
-| Avatar / uploads | `registerAvatarConfig`, `getAvatarConfig`, `DEFAULT_AVATAR_CONFIG`, `serveAvatar`, `processUpload`. Types: `AvatarConfig`, `AvatarConfigInput`, `ProcessUploadInput`, `ProcessUploadResult`. **Path-traversal guard:** `serveAvatar` rejects any `fileId` that does not match `/^[A-Za-z0-9_-]{1,128}$/` with a 400 before touching the filesystem — `..`, slashes, and other path-separator characters cannot escape the configured upload directory. **`processUpload`** wraps the project-supplied encode/save callback with the framework's `onUploadStart` (stoppable) and `onUploadComplete` hook contract so consumer upload routes don't need to plumb the hooks themselves. Returns `{ status: 'success', sizeBytes }`, `{ status: 'rejected', errorCode }` (when `onUploadStart` returned a stop signal), or `{ status: 'error', reason, cause? }`. See [`src/settings/_api/updateUser_v1.ts`](../../src/settings/_api/updateUser_v1.ts) for the canonical avatar usage. |
-| Bind address | `registerBindAddress({ ip, port })` stores the intended pre-listen address; `registerBoundAddress({ ip, port })` stores `node:http`'s successful address; `getBindAddress() → { ip, port: string }` returns the actually-bound value. `resolveDevCallbackUrl(url)` rewrites only a stale direct loopback OAuth callback from intended → bound port, preserving explicit local router/reverse-proxy ingress. Env values remain legacy fallbacks. |
-| Locale reloader | `registerLocaleReloader`, `getLocaleReloader`. Type: `LocaleReloader` |
-| Hooks (async) | `registerHook`, `dispatchHook`, `clearAllHooks`. Types: `HookName`, `HookHandler`, `HookResult`, `HookStopSignal`, `HookPayloads`, `DispatchResult`, `HookSessionShape`. Canonical payload types: `PreApiValidatePayload`, `PostApiValidatePayload`, `PreApiExecutePayload`, `PostApiExecutePayload`, `PreApiRespondPayload`, `PostApiRespondPayload`, `ApiResponseEnvelope`, `PreSyncFanoutPayload`, `PostSyncFanoutPayload`, `ApiErrorPayload`, `SyncErrorPayload`, `RateLimitExceededPayload`, `CorsRejectedPayload`, `CsrfMismatchPayload`, `PreSessionRefreshPayload`, `PostSessionRefreshPayload`, `OnUploadStartPayload`, `OnUploadCompletePayload`. Feature-package payloads (`Pre/PostLogin`, `Pre/PostRegister`, `Pre/PostLogout`, `Pre/PostSessionCreate`, `Pre/PostSessionDelete`, `Pre/PostEmailSend`, `Pre/PostPresenceUpdate`, socket lifecycle, etc.) augment `HookPayloads` from their owning packages — see those packages' READMEs. |
-| Hooks (sync, mutators) | `registerSyncHook`, `dispatchSyncHook`. Types: `SyncHookName`, `SyncHookHandler`, `SyncHookPayloads`, `PreErrorNormalizePayload`, `PostErrorNormalizePayload`. Sync hook handlers must be synchronous (no `async`), mutate the payload object in place, and cannot stop the flow. Use them only for hot-path mutators like error-code remapping. |
-| Session types | `BaseSessionLayout`, `SessionLocation`, `AuthProps` |
-| Socket | `setIoInstance`, `getIoInstance`, `attachSocketRedisAdapter`, `socket`, `setSocket`, `incrementResponseIndex`, `waitForSocket`. Types: `SOCKETSTATUS`, `statusContent`, `apiMessage`, `syncMessage` |
-| Auth helpers | `extractTokenFromSocket`, `extractTokenFromRequest`, `validateRequest`, `isFalsy`, `allowedOrigin`. Types: `ValidationResult` |
-| Rate limiting | `checkRateLimit`, `getRateLimitStatus`, `clearRateLimit`, `clearAllRateLimits` |
-| Validation | `validateInputByType` (resolves to `@luckystack/devkit` lazily in dev) |
-| Persistence + env | `redis`, `prisma`, `db` exports, `env` exports |
-| Boot | `writeBootUuid`, `readBootUuid`, `resolveEnvKey`, `collectSynchronizedEnvKeys`, `computeSynchronizedEnvHashes`, `hashSynchronizedValue`, `initConsolelog` |
-| Offline queue | `isOnline`, `enqueueApiRequest`, `enqueueSyncRequest`, `removeApiQueueItem`, `removeSyncQueueItem`, `removeApiQueueItemsByKey`, `flushApiQueue`, `flushSyncQueue`, `getApiQueueSize`, `getSyncQueueSize` |
-| CSRF | `getCsrfToken`, `clearCsrfToken`, `httpFetch` |
-| Cookies + paths | All exports of `./cookies`, `./httpApiUtils`, and `./paths` (`getGeneratedApiDocsPath`, `getApiMethodMapPath`, etc.) |
-| Misc | `tryCatch`, `sleep`, `getParams`, response normalizers (`normalizeErrorResponse`, `extractLanguageFromHeader`, …), service-route helpers, socket-event constants |
-
-> Note: `apiRequest` is exported from `@luckystack/core/client`, not from the server entry. The server barrel does not pull React-coupled code.
-
-## Dependencies
-
-- Runtime: `@socket.io/redis-adapter`, `dotenv`
-- Required peers: `ioredis@^5.10.0`, `socket.io@^4.8.0`, `socket.io-client@^4.8.0`, `zod@^4.0.0`
-- Optional peer: `@prisma/client@^6.19.0` — only needed when the default Prisma client is used.
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+Register project infrastructure before starting the server; let `@luckystack/server` handle ordinary bootstrapping. Keep cookie and bearer session modes distinct: cookie-backed writes require origin and CSRF protection. See [design context](./AGENTS.md), [configuration rationale](./docs/config-registry.md), and [security rationale](./docs/socket-bootstrap.md). Types, exports and defaults are in `src/` and `package.json`.

package/dist/apiInterceptors.d.ts

@@ -0,0 +1,36 @@
+export interface ApiRequestInterceptorContext {
+    /** Resolved route name (`<page>/<api>` or `system/<api>`). */
+    name: string;
+    /** Route version literal (e.g. `'v1'`). */
+    version: string;
+    /**
+     * Outgoing request payload. Mutate this object in place to augment the
+     * request (correlation id, feature-flag context, ...). Replacing the
+     * reference has no effect — mutate keys on the existing object.
+     */
+    data: Record<string, unknown>;
+}
+export interface ApiResponseInterceptorContext {
+    name: string;
+    version: string;
+    /** The response envelope the caller is about to receive (read-only intent). */
+    response: {
+        status: 'success' | 'error';
+        [key: string]: unknown;
+    };
+}
+export type ApiRequestInterceptor = (ctx: ApiRequestInterceptorContext) => void | Promise<void>;
+export type ApiResponseInterceptor = (ctx: ApiResponseInterceptorContext) => void | Promise<void>;
+/**
+ * Register an outgoing-request interceptor. Returns an unsubscribe function.
+ * Multiple interceptors run in registration order; each may mutate `ctx.data`.
+ */
+export declare function registerApiRequestInterceptor(interceptor: ApiRequestInterceptor): () => void;
+/**
+ * Register an incoming-response interceptor. Returns an unsubscribe function.
+ */
+export declare function registerApiResponseInterceptor(interceptor: ApiResponseInterceptor): () => void;
+export declare function dispatchApiRequestInterceptors(ctx: ApiRequestInterceptorContext): Promise<void>;
+export declare function dispatchApiResponseInterceptors(ctx: ApiResponseInterceptorContext): void;
+/** Test helper — drop every registered interceptor. Not part of the public API. */
+export declare function _resetApiInterceptorsForTests(): void;

package/dist/apiMethodMapRegistry.d.ts

@@ -0,0 +1,5 @@
+export type HttpMethodLiteral = 'GET' | 'POST' | 'PUT' | 'DELETE';
+export type ApiMethodMap = Record<string, Record<string, Record<string, HttpMethodLiteral>>>;
+export declare const registerApiMethodMap: (map: ApiMethodMap) => void;
+export declare const getRegisteredApiMethod: (pagePath: string, apiName: string, version: string) => HttpMethodLiteral | undefined;
+export declare const isApiMethodMapRegistered: () => boolean;

package/dist/apiRequest.d.ts

@@ -0,0 +1,71 @@
+import type { ApiTypeMap, StreamPayload } from './apiTypeStubs.js';
+export type ApiStreamEvent<T extends StreamPayload = StreamPayload> = T;
+export declare const resolveApiRequestHttpMethod: (apiName: string, version: string) => "DELETE" | "GET" | "POST" | "PUT";
+type DataRequired<T> = Record<string, never> extends T ? false : true;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+type ApiRouteRecord = UnionToIntersection<{
+    [P in keyof ApiTypeMap]: {
+        [N in keyof ApiTypeMap[P] as P extends 'root' ? `system/${Extract<N, string>}` : `${Extract<P, string>}/${Extract<N, string>}`]: ApiTypeMap[P][N];
+    };
+}[keyof ApiTypeMap]>;
+type ApiFullName = Extract<keyof ApiRouteRecord, string>;
+type VersionsForFullName<F extends ApiFullName> = keyof ApiRouteRecord[F] & string;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type InputForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    input: infer I;
+} ? I : never;
+type OutputForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    output: infer O;
+} ? O : never;
+type StreamForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = ApiRouteRecord[F][V] extends {
+    stream: infer S;
+} ? S : never;
+type ApiStreamCallbackForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = [
+    StreamForFullName<F, V>
+] extends [never] ? never : (event: ApiStreamEvent<Prettify<StreamForFullName<F, V> extends StreamPayload ? StreamForFullName<F, V> : StreamPayload>>) => void;
+type ApiParamsForFullName<F extends ApiFullName, V extends VersionsForFullName<F>> = DataRequired<InputForFullName<F, V>> extends true ? {
+    name: F;
+    version: V;
+    data: Prettify<InputForFullName<F, V>>;
+    abortable?: boolean;
+    disableErrorMessage?: boolean;
+    onStream?: ApiStreamCallbackForFullName<F, V>;
+    signal?: AbortSignal;
+    timeoutMs?: number | false;
+} : {
+    name: F;
+    version: V;
+    data?: Prettify<InputForFullName<F, V>>;
+    abortable?: boolean;
+    disableErrorMessage?: boolean;
+    onStream?: ApiStreamCallbackForFullName<F, V>;
+    signal?: AbortSignal;
+    timeoutMs?: number | false;
+};
+export interface ApiErrorResponse extends Record<string, unknown> {
+    status: 'error';
+    httpStatus: number;
+    message: string;
+    errorCode: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+}
+/**
+ * Type-safe API request function.
+ *
+ * @example
+ * ```typescript
+ * // Full name usage - includes page in the name
+ * const result = await apiRequest({ name: 'examples/publicApi', version: 'v1', data: { message: 'hello' } });
+ * // result is typed correctly for publicApi
+ *
+ * // Global APIs use service-first naming
+ * await apiRequest({ name: 'system/session', version: 'v1' });
+ * ```
+ */
+export declare function apiRequest<F extends ApiFullName, V extends VersionsForFullName<F>>(params: ApiParamsForFullName<F, V>): Promise<Prettify<OutputForFullName<F, V>> | ApiErrorResponse>;
+export {};

package/dist/apiTypeStubs.d.ts

@@ -1,7 +1,5 @@
-interface ApiTypeMap {
+export interface ApiTypeMap {
 }
-interface SyncTypeMap {
+export interface SyncTypeMap {
 }
-type StreamPayload = Record<string, unknown>;
-
-export type { ApiTypeMap, StreamPayload, SyncTypeMap };
+export type StreamPayload = Record<string, unknown>;

package/dist/avatarConfig.d.ts

@@ -0,0 +1,22 @@
+import { type DeepPartial } from './configUtils.js';
+export interface AvatarConfig {
+    /**
+     * File format(s) the framework will look for on disk, in order. The first
+     * one that exists wins. Each entry is `{ extension, contentType }` so the
+     * `Content-Type` response header matches what the file actually is.
+     * Default: `[{ extension: 'webp', contentType: 'image/webp' }]`.
+     */
+    formats: {
+        extension: string;
+        contentType: string;
+    }[];
+    /**
+     * `Cache-Control` value sent with the avatar response.
+     * Default: `'public, max-age=86400'` (24 hours).
+     */
+    cacheControl: string;
+}
+export declare const DEFAULT_AVATAR_CONFIG: AvatarConfig;
+export type AvatarConfigInput = DeepPartial<AvatarConfig>;
+export declare const registerAvatarConfig: (config: AvatarConfigInput) => void;
+export declare const getAvatarConfig: () => AvatarConfig;

package/dist/bindAddress.d.ts

@@ -0,0 +1,15 @@
+interface BindAddress {
+    ip: string;
+    port: number;
+}
+interface IntendedBindAddress extends BindAddress {
+    configuredPort?: number;
+}
+export declare const registerBindAddress: (address: IntendedBindAddress) => void;
+export declare const registerBoundAddress: (address: BindAddress) => void;
+export declare const getBindAddress: () => {
+    ip: string;
+    port: string;
+};
+export declare const resolveDevCallbackUrl: (callbackUrl: string) => string;
+export {};

package/dist/bootUuid.d.ts

@@ -0,0 +1,24 @@
+export declare const BOOT_KEY_PREFIX = "luckystack:boot:";
+export declare const resolveEnvKey: () => string;
+export declare const writeBootUuid: (envKey?: string) => Promise<string>;
+export declare const readBootUuid: (envKey?: string) => Promise<string | null>;
+/**
+ * Extends the current environment boot UUID without rotating its value.
+ *
+ * Every healthy backend may renew the environment-level key, so multi-instance
+ * deployments do not depend on whichever process happened to write it last. If
+ * Redis recovered after the key expired, the first refresher writes a new UUID.
+ */
+export declare const refreshBootUuid: (envKey?: string) => Promise<void>;
+export interface BootUuidHeartbeat {
+    stop: () => void;
+}
+/**
+ * Keeps the Redis boot UUID alive for as long as this backend is running.
+ *
+ * The self-rescheduling timeout waits for each Redis operation to settle before
+ * scheduling another, so an outage cannot accumulate overlapping refreshes.
+ * The timer is unref'd and therefore never keeps an otherwise-finished process
+ * alive. Failures are logged and retried on the next interval.
+ */
+export declare const startBootUuidHeartbeat: (envKey?: string) => BootUuidHeartbeat;

package/dist/cancelRegistry.d.ts

@@ -0,0 +1,7 @@
+export declare const registerSyncAbortController: (socketId: string, cb: string, controller: AbortController) => string;
+export declare const unregisterSyncAbortController: (key: string) => void;
+export declare const abortSyncByCb: (socketId: string, cb: string) => boolean;
+export declare const registerApiAbortController: (socketId: string, responseIndex: number | string, controller: AbortController) => string;
+export declare const unregisterApiAbortController: (key: string) => void;
+export declare const abortApiByResponseIndex: (socketId: string, responseIndex: number | string) => boolean;
+export declare const abortAllForSocket: (socketId: string) => void;

package/dist/checkOrigin.d.ts

@@ -0,0 +1,6 @@
+export declare const normalizeOrigin: ({ value, secure }: {
+    value: string;
+    secure: boolean;
+}) => string;
+declare const allowedOrigin: (origin: string) => boolean;
+export default allowedOrigin;