@luckystack/core 0.1.0

package/docs/session-types.md

@@ -0,0 +1,180 @@
+# Session Types
+
+> Deep specs for the foundational session/auth types plus `validateRequest`, `isFalsy`, and `validateInputByType`. Source: `packages/core/src/sessionTypes.ts`, `validateRequest.ts`, `runtimeTypeValidation.ts`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+`BaseSessionLayout` is the structural contract every project session type extends. It lives in `@luckystack/core` (not `@luckystack/login`) so `validateRequest` can consume it without creating a circular dep: login depends on core for prisma/redis, so the session shape has to live in the lower layer. `@luckystack/login` re-exports the type for ergonomics — existing `import type { BaseSessionLayout } from '@luckystack/login'` paths keep working.
+
+`AuthProps` defines the auth gate that every API/sync handler exports (`login: true/false` + an optional `additional[]` predicate list). `validateRequest({ auth, user })` is the runtime check that turns those declarations into a `ValidationResult`.
+
+`validateInputByType` is the runtime input validator used by the api/sync handlers in dev. It lazy-loads `@luckystack/devkit` (the heavy TS compiler resolver) only when running in non-production. In production it short-circuits to success because the prod esbuild bundle marks devkit as external and the validator should not need TS to validate request bodies at request time.
+
+## Types
+
+```typescript
+export interface SessionLocation {
+  pathName: string;
+  searchParams?: Record<string, string>;
+}
+
+export interface BaseSessionLayout {
+  id: string;
+  token: string;
+  email?: string | null;
+  name?: string | null;
+  avatar?: string | null;
+  avatarFallback?: string | null;
+  admin?: boolean | null;
+  language?: string | null;
+  location?: SessionLocation;
+  roomCodes?: string[];
+  csrfToken?: string;
+  lastLogin?: Date | string | null;
+  previousLogin?: Date | string | null;
+}
+
+export interface AuthProps {
+  login: boolean;
+  additional?: {
+    key: keyof BaseSessionLayout;
+    value?: unknown;
+    type?: 'string' | 'number' | 'boolean';
+    nullish?: boolean;
+    mustBeFalsy?: boolean;
+  }[];
+}
+
+export interface ValidationResult {
+  status: 'success' | 'error';
+  errorCode?: string;
+  errorParams?: { key: string; value: string | number | boolean }[];
+  httpStatus?: number;
+}
+```
+
+### Extending `BaseSessionLayout`
+
+Projects extend the type in their own `config.ts`:
+
+```typescript
+import type { BaseSessionLayout } from '@luckystack/core';
+
+export interface SessionLayout extends BaseSessionLayout {
+  organizationId?: string;
+  role?: 'member' | 'admin' | 'owner';
+}
+```
+
+The framework's `validateRequest` only inspects keys it knows from `BaseSessionLayout`; project-specific keys are checked via `additional[]`.
+
+## API Reference
+
+### `isFalsy(value: unknown): boolean`
+
+**Signature:**
+```typescript
+export const isFalsy = (value: unknown): boolean
+```
+
+**Behavior:** Returns `true` for `false`, `0`, `0n`, `''`, `null`, `undefined`, or `NaN`. Everything else is truthy.
+
+**Note:** This is a stricter "falsy" than JavaScript's coercion-based check because it ALSO treats `NaN` as falsy. Used inside `validateRequest` for the `mustBeFalsy` predicate.
+
+### `validateRequest({ auth, user }): ValidationResult`
+
+**Signature:**
+```typescript
+export const validateRequest = ({
+  auth,
+  user,
+}: {
+  auth: AuthProps;
+  user: BaseSessionLayout;
+}): ValidationResult
+```
+
+**Behavior (in order):**
+1. If `auth.additional` is undefined → returns `{ status: 'success' }` immediately. (The `login` flag is enforced by the surrounding handler, not by this function.)
+2. For each `condition` in `auth.additional`:
+   - If `condition.key` is not in `user` → returns `{ status: 'error', errorCode: 'auth.invalidCondition', errorParams: [{ key: 'key', value: condition.key }], httpStatus: 500 }`. This is a developer setup error, not a runtime auth failure.
+   - Reads `val = user[condition.key]`. Computes `isNullish = val === null || val === undefined`.
+   - `nullish: true` requires `isNullish`; `nullish: false` requires NOT `isNullish`. Mismatch → forbid.
+   - `type: 'string' | 'number' | 'boolean'` requires `typeof val === <type>` (skipped when `val` is nullish). Mismatch → forbid.
+   - `'value' in condition` requires strict equality `val === condition.value`. The membership check distinguishes "no exact-value constraint" from `value: undefined` (the latter explicitly demands `val === undefined`).
+   - `mustBeFalsy: true` requires `isFalsy(val)`; `mustBeFalsy: false` requires `!isFalsy(val)`. Mismatch → forbid.
+3. After all conditions pass → returns `{ status: 'success' }`.
+
+**Forbid shape:**
+```typescript
+{ status: 'error', errorCode: 'auth.forbidden', errorParams: [{ key: 'key', value: <key> }], httpStatus: 403 }
+```
+
+**Constraint AND-semantics:** Multiple fields on a single `additional` entry are AND'd (every specified field must pass). Entries across the array are also AND'd.
+
+**Example — admin-only endpoint:**
+```typescript
+export const auth: AuthProps = {
+  login: true,
+  additional: [{ key: 'admin', value: true, type: 'boolean' }],
+};
+```
+
+**Example — verified email required:**
+```typescript
+export const auth: AuthProps = {
+  login: true,
+  additional: [{ key: 'email', nullish: false, type: 'string' }],
+};
+```
+
+### `validateInputByType({ typeText, value, rootKey, filePath? }): Promise<ValidationResult>`
+
+**Signature:**
+```typescript
+type ValidationResult =
+  | { status: 'success' }
+  | { status: 'error'; message: string };
+
+export const validateInputByType = async ({
+  typeText,
+  value,
+  rootKey,
+  filePath,
+}: {
+  typeText?: string;
+  value: unknown;
+  rootKey: string;
+  filePath?: string;
+}): Promise<ValidationResult>
+```
+
+**Behavior:**
+1. When `typeText` is empty, whitespace, or literal `'any'` → returns `{ status: 'success' }`.
+2. When `process.env.NODE_ENV === 'production'` → returns `{ status: 'success' }` (avoids loading the TS compiler in prod).
+3. Otherwise lazy-imports `@luckystack/devkit` via an indirect module ID (`const devkitModuleId: string = '@luckystack/devkit'; await import(devkitModuleId)`) so `tsc` doesn't try to resolve devkit at build time (devkit depends on core — a literal import would be a build-time circular dep).
+4. Calls `devkit.resolveRuntimeTypeText({ typeText, filePath })`. On `status: 'error'` returns `{ status: 'error', message: '<rootKey>: <message>' }`.
+5. Otherwise calls the internal `validateType(resolvedType.typeText, value, rootKey)` recursive validator.
+
+**Supported type forms (validateType):**
+- Primitives: `string`, `number`, `boolean`, `true`, `false`, `null`, `undefined`, `Date` (accepts ISO string or `Date` instance).
+- String/number literal types (single-quoted or double-quoted).
+- Unions (`A | B`) — succeeds on first matching branch.
+- Intersections (`A & B`) — requires all branches to succeed.
+- Arrays (`T[]`) — checks every element.
+- `Record<K, V>` — accepts any non-array object.
+- Object literals `{ key?: T; key2: T2; [index: keyof IndexKey]: T }` — checks each named field, applies index signatures for unknown keys.
+- `any` / `unknown` — always succeeds.
+- Unresolved type aliases or generics return `{ status: 'error', message: '<path>: unresolved type <name>' }`.
+
+**Edge cases:**
+- The `__RUNTIME_UNRESOLVED__::<message>` sentinel from devkit surfaces as `{ status: 'error', message: '<path>: <message>' }` so a missing project type doesn't crash the request.
+- Object validation rejects unknown keys when there is no matching index signature.
+- Index-signature keys can be `string`, `number`, string-literal unions, or literal types; `number` keys require the key to match `/^-?\d+(\.\d+)?$/`.
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_SESSION.md`, `docs/ARCHITECTURE_AUTH.md`, `docs/ARCHITECTURE_API.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/sessionTypes.ts`, `validateRequest.ts`, `runtimeTypeValidation.ts`

package/docs/socket-bootstrap.md

@@ -0,0 +1,366 @@
+# Socket Bootstrap
+
+> Deep specs for socket transport bootstrap, token extraction, CORS check, offline queue, CSRF, cookies, service-route helpers and event constants. Source: `packages/core/src/`. Bijgewerkt: 2026-05-20.
+
+## Overview
+
+This topic covers the wiring around the LuckyStack socket transport:
+
+- **Server-side socket slot** — `setIoInstance` / `getIoInstance` so framework code can broadcast.
+- **Client-side socket singleton** — live binding `socket`, `setSocket`, `waitForSocket`, `incrementResponseIndex`.
+- **Token extraction** — pull the session token from a Socket.io handshake (`extractTokenFromSocket`) or a Node `IncomingMessage` (`extractTokenFromRequest`).
+- **Origin check** — `allowedOrigin` for CORS-style allow-listing, with `corsRejected` hook fan-out.
+- **Offline queue** — `enqueueApiRequest`, `enqueueSyncRequest`, flushers, and per-item `dropPolicy` overrides.
+- **CSRF + httpFetch** — lazy `/auth/csrf` token cache + drop-in fetch wrapper.
+- **Wire-protocol constants** — `socketEventNames` map + per-prefix event-name builders.
+- **Route parsers** — `parseServiceRouteName`, `parseTransportRouteName`.
+- **Cookie helpers** — `getCookieValue`, `hasCookie`.
+- **HTTP helpers** — `inferHttpMethod`, `getEffectiveHttpMethod`, `isMethodAllowed`.
+
+Token extraction respects `projectConfig.session.basedToken`: when `true` the framework prefers `socket.handshake.auth.token` / `Authorization: Bearer ...`, otherwise the configured session cookie wins (with the other transport as fallback).
+
+## API Reference — IO Instance
+
+### `setIoInstance(io: SocketIOServer | null): void`
+
+**Signature:**
+```typescript
+export const setIoInstance = (io: SocketIOServer | null): void
+```
+
+**Behavior:** Stores the running Socket.io server in a module-level slot. Framework code (`@luckystack/sync`, presence package, etc.) reads via `getIoInstance()` for broadcast paths.
+
+### `getIoInstance(): SocketIOServer | null`
+
+Returns the registered instance or `null` when no server has been set. Callers must null-check.
+
+## API Reference — Client Socket Singleton
+
+### `socket: Socket | null`
+
+A live `export let` binding — importers always see the current value after `setSocket(...)` replaces it.
+
+### `setSocket(next: Socket | null): void`
+
+Stores the project's socket.io-client instance. Called from `src/_sockets/socketInitializer.ts`.
+
+### `incrementResponseIndex(): number`
+
+**Returns:** The next monotonic response index (used to build per-request reply event names like `apiResponse-42`).
+
+**Behavior:**
+- Module-scoped counter, increments before returning so the first call returns `1`.
+- Used by `apiRequest` / `syncRequest` clients to disambiguate concurrent requests on the same socket.
+
+### `waitForSocket(): Promise<Socket | null>`
+
+**Behavior:**
+- Polls every 10 ms until `socket !== null` or 500 iterations elapse (~5 seconds).
+- Returns the socket on success, `null` on timeout.
+
+**Example:**
+```typescript
+import { waitForSocket } from '@luckystack/core/client';
+
+const s = await waitForSocket();
+if (!s) throw new Error('socket never connected');
+```
+
+## API Reference — Custom Socket Middlewares
+
+The framework lets consumers wedge their own Socket.io `io.use(...)` middlewares into the bootstrap without forking `loadSocket.ts`. Registered middlewares run in registration order, before any `connect` handler — same contract as a direct `io.use(...)` call.
+
+### `registerSocketMiddleware(mw: SocketMiddleware): void`
+
+**Signature:**
+```typescript
+export type SocketMiddleware = (socket: Socket, next: (err?: Error) => void) => void;
+export const registerSocketMiddleware = (mw: SocketMiddleware): void
+```
+
+**Behavior:** Appends the middleware to a module-level list. `@luckystack/server`'s `loadSocket` calls `applySocketMiddlewares(io)` after constructing the `SocketIOServer` and before attaching the `connect` handler, so every registered middleware runs on the handshake of every incoming socket.
+
+**Example — license-key gate:**
+```typescript
+import { registerSocketMiddleware } from '@luckystack/core';
+
+registerSocketMiddleware((socket, next) => {
+  const licenseKey = socket.handshake.auth.licenseKey;
+  if (typeof licenseKey !== 'string' || !isValidLicense(licenseKey)) {
+    return next(new Error('invalid license'));
+  }
+  next();
+});
+```
+
+**Example — observability tag (Datadog APM):**
+```typescript
+import { registerSocketMiddleware } from '@luckystack/core';
+import tracer from 'dd-trace';
+
+registerSocketMiddleware((socket, next) => {
+  const span = tracer.scope().active();
+  if (span) span.setTag('socket.id', socket.id);
+  next();
+});
+```
+
+### `getSocketMiddlewares(): readonly SocketMiddleware[]`
+
+Read the registered list (frozen view). Useful for diagnostics.
+
+### `clearSocketMiddlewares(): void`
+
+Drops every registered middleware. Test/hot-reload helper.
+
+### `applySocketMiddlewares(io: SocketIOServer): void`
+
+Framework-internal — wires every registered middleware via `io.use(...)`. Called by `@luckystack/server`'s `loadSocket`; consumers should not call this directly.
+
+## API Reference — Token Extraction
+
+### `extractTokenFromSocket(socket: Socket): string | null`
+
+**Signature:**
+```typescript
+export const extractTokenFromSocket = (socket: Socket): string | null
+```
+
+**Behavior:**
+- Reads `socket.handshake.auth.token` (when it is a string) and the configured cookie (`projectConfig.http.sessionCookieName`) from `socket.handshake.headers.cookie`.
+- When `session.basedToken === true`: returns the auth-token first, falls back to the cookie.
+- When `session.basedToken === false`: returns the cookie first, falls back to the auth-token.
+
+**Returns:** The token string or `null`.
+
+### `extractTokenFromRequest(req: IncomingMessage): string | null`
+
+**Signature:**
+```typescript
+export const extractTokenFromRequest = (req: IncomingMessage): string | null
+```
+
+**Behavior:**
+- Reads `req.headers.authorization` and extracts the bearer (`'Bearer <token>'`).
+- Reads the configured cookie from `req.headers.cookie`.
+- Picks cookie-first vs bearer-first based on `session.basedToken`.
+
+## API Reference — Origin Check
+
+### `allowedOrigin(origin: string): boolean`
+
+**Signature:**
+```typescript
+const allowedOrigin = (origin: string): boolean
+export default allowedOrigin
+```
+
+**Behavior (in execution order):**
+1. Normalizes the origin to `scheme://host[:port]`, strips default `:80` / `:443`, lowercases.
+2. Computes the same-origin bind location from `getBindAddress()` and the `SECURE` env var.
+3. When `cors.allowLocalhost` and the origin matches `/^https?:\/\/localhost(:\d+)?$/i` → returns `true`.
+4. When `cors.allowedOrigins` is a function → calls it; if it returns true (or the origin equals the bind location) → returns `true`.
+5. When `cors.allowedOrigins` is a string array → builds a normalized allowed set (bind location + configured list); returns `true` on match.
+6. Otherwise: dispatches the `corsRejected` hook (with origin + normalized origin + allowedOrigins + allowLocalhost) and returns `false`. Also logs via `getLogger().warn` when `logging.devLogs` is on.
+
+**Edge cases:**
+- An empty `origin` is treated as not-allowed.
+- The resolver-function form is sync only — async predicates are not supported because Socket.io's CORS check is sync.
+
+## API Reference — Offline Queue
+
+Per-queue items:
+```typescript
+interface QueueItem {
+  id: string;
+  key: string;
+  run: (socketInstance: Socket) => void;
+  createdAt: number;
+  dropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+}
+```
+
+### `isOnline(): boolean`
+Returns `true` in non-browser environments. In browsers, reads `navigator.onLine`.
+
+### `enqueueApiRequest(item): boolean` / `enqueueSyncRequest(item): boolean`
+
+**Behavior:**
+1. Evicts items older than `offlineQueue.maxAgeMs` from the relevant queue.
+2. If `queue.length < offlineQueue.maxSize`, pushes the new item and returns `true`.
+3. Otherwise applies the effective drop policy (per-item `dropPolicy` overrides the global default):
+   - `'drop-oldest'` — shift + push, returns `true` (logs debug).
+   - `'drop-newest'` — keep existing queue, returns `false` (logs debug).
+   - `'reject'` — returns `false` (logs warn).
+
+### `removeApiQueueItem(id)` / `removeSyncQueueItem(id)`
+Removes a single item by `id`. No-op if not found.
+
+### `removeApiQueueItemsByKey(key)`
+Removes every API queue item matching `item.key`. Used to coalesce duplicate requests.
+
+### `flushApiQueue(canRun, socketInstance)` / `flushSyncQueue(canRun, socketInstance)`
+
+**Behavior:**
+- Re-entrancy guard prevents nested flushes for the same queue.
+- Evicts expired items.
+- Drains FIFO while `canRun()` returns `true`, calling each item's `run(socketInstance)`.
+
+### `getApiQueueSize(): number` / `getSyncQueueSize(): number`
+
+Read-only sizes (after eviction triggers from enqueue/flush; reads alone do not evict).
+
+**Example:**
+```typescript
+import { enqueueApiRequest } from '@luckystack/core/client';
+
+enqueueApiRequest({
+  id: requestId,
+  key: `${routeName}:${userId}`,
+  createdAt: Date.now(),
+  dropPolicy: 'drop-newest',
+  run: (s) => s.emit('apiRequest', message),
+});
+```
+
+## API Reference — CSRF + httpFetch
+
+### `getCsrfToken(): Promise<string | null>`
+
+**Behavior:**
+- Returns `null` immediately in token-mode sessions (`session.basedToken === true`) — CSRF is unnecessary because cross-origin requests don't auto-attach sessionStorage.
+- Returns the cached token if previously fetched.
+- Otherwise fetches `/auth/csrf` with `credentials: 'include'`, caches and returns `body.csrfToken`.
+- Inflight de-duplication: concurrent callers share the same promise.
+
+### `clearCsrfToken(): void`
+
+Drops the cached token + any inflight fetch. Call on logout or when a 403 `auth.csrfMismatch` is observed.
+
+### `httpFetch(input, init?): Promise<Response>`
+
+Drop-in `fetch` replacement that:
+- Forces `credentials: 'include'` unless overridden.
+- Adds `Content-Type: application/json` when a string body is present and no content-type was set.
+- For state-changing methods (`POST`, `PUT`, `PATCH`, `DELETE`) in cookie mode: lazily fetches the CSRF token, attaches as `x-csrf-token`. On a 403 `auth.csrfMismatch` response, clears the cache and retries once with a refreshed token.
+
+**Example:**
+```typescript
+import { httpFetch } from '@luckystack/core/client';
+
+const res = await httpFetch('/api/system/myRoute/v1', {
+  method: 'POST',
+  body: JSON.stringify({ foo: 1 }),
+});
+```
+
+## API Reference — Wire Protocol Constants
+
+### `socketEventNames`
+
+A frozen record of event names:
+
+| Key | Value |
+|---|---|
+| `apiRequest` | `'apiRequest'` |
+| `sync` | `'sync'` |
+| `joinRoom` / `leaveRoom` / `getJoinedRooms` | (same literal) |
+| `updateLocation` / `updateSession` / `sessionReplaced` / `logout` | (same literal) |
+| `intentionalDisconnect` / `intentionalReconnect` / `userAfk` / `userBack` | (same literal) |
+| `connect` / `disconnect` / `reconnectAttempt` / `connectError` | underlying socket.io events |
+| `apiResponsePrefix` | `'apiResponse-'` |
+| `apiStreamPrefix` | `'apiStream-'` |
+| `syncResponsePrefix` | `'sync-'` |
+| `syncProgressPrefix` | `'sync-progress-'` |
+| `joinRoomResponsePrefix` / `leaveRoomResponsePrefix` / `getJoinedRoomsResponsePrefix` | (same prefix) |
+
+### Event name builders
+
+| Function | Behavior |
+|---|---|
+| `buildApiResponseEventName(idx)` | `'apiResponse-<idx>'` |
+| `buildApiStreamEventName(idx)` | `'apiStream-<idx>'` |
+| `buildSyncResponseEventName(idx)` | `'sync-<idx>'` |
+| `buildSyncProgressEventName(idx)` | `'sync-progress-<idx>'` |
+| `buildJoinRoomResponseEventName(idx)` | `'joinRoom-<idx>'` |
+| `buildLeaveRoomResponseEventName(idx)` | `'leaveRoom-<idx>'` |
+| `buildGetJoinedRoomsResponseEventName(idx)` | `'getJoinedRooms-<idx>'` |
+
+## API Reference — Service Route Parsers
+
+### `parseServiceRouteName(value: string): ServiceRouteParseResult`
+
+Validates `<service>/<routeName...>` strings.
+
+**Returns:**
+- `{ status: 'success', normalizedRouteName, service, routeName }` — when at least two non-empty segments are present.
+- `{ status: 'error', reason }` — for empty input, empty segments, or fewer than two segments.
+
+Normalization rules: trim, replace `\` with `/`, strip leading/trailing slashes.
+
+### `parseTransportRouteName({ value, prefix })`
+
+Validates a full transport route like `'api/system/foo/v1'`.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Raw route string. |
+| `prefix` | `'api' \| 'sync'` | yes | Determines whether the leading `'api'`/`'sync'` segment is stripped. |
+
+**Returns:**
+- `{ status: 'success', normalizedFullName, version, serviceRoute }` — when the trailing segment matches `/^v\d+$/` and the leading service/route part parses cleanly.
+- `{ status: 'error', reason }` — on length / version / segment violations.
+
+## API Reference — Cookies
+
+### `getCookieValue(cookieHeader: string | undefined, cookieName: string): string | null`
+
+Regex-escapes `cookieName`, searches for `(?:^|;\s*)<name>=<value>` in the header, URL-decodes the captured value (falls back to raw on decode failure). Returns `null` when input is missing or no match.
+
+### `hasCookie(cookieHeader, cookieName): boolean`
+
+Convenience wrapper — true when `getCookieValue` returns a non-null value.
+
+## API Reference — HTTP Method Inference
+
+### `inferHttpMethod(apiName: string): HttpMethod`
+
+Naming-convention heuristic (used as fallback when no `apiMethodMap` is registered):
+- starts with `get` / `fetch` / `list` → `GET`
+- starts with `delete` / `remove` → `DELETE`
+- starts with `update` / `edit` / `patch` → `PUT`
+- otherwise → `POST`
+
+Strips a trailing `v\d+` segment before applying the rule, so `api/examples/getUser/v1` resolves to `'GET'`.
+
+### `getEffectiveHttpMethod(apiConfig, apiName)`
+
+Prefers an explicit `apiConfig.httpMethod`; otherwise calls `inferHttpMethod(apiName)`.
+
+### `isMethodAllowed(requestMethod, allowedMethod): boolean`
+
+Returns `true` when the request method matches the allowed method or is `'OPTIONS'` (CORS preflight passthrough).
+
+## Hooks dispatched
+
+| Hook name | Payload type | When |
+|---|---|---|
+| `corsRejected` | `CorsRejectedPayload` | `allowedOrigin` is about to return `false`. |
+
+## Config keys consumed
+
+| Key | Where |
+|---|---|
+| `session.basedToken` | token extractors, `httpFetch`, `getCsrfToken` |
+| `http.sessionCookieName` | token extractors |
+| `http.cors.allowedOrigins`, `http.cors.allowLocalhost` | `allowedOrigin` |
+| `offlineQueue.maxSize`, `maxAgeMs`, `dropPolicy` | offline queue |
+| `logging.devLogs` | `allowedOrigin` warn-logs |
+
+## Related
+
+- Function INDEX: `packages/core/CLAUDE.md`
+- Architecture: `docs/ARCHITECTURE_SOCKET.md`, `docs/ARCHITECTURE_API.md`, `docs/ARCHITECTURE_SYNC.md`, `docs/ARCHITECTURE_AUTH.md`
+- README: `packages/core/README.md`
+- Source: `packages/core/src/socketTypes.ts`, `socketState.ts`, `socketEvents.ts`, `extractToken.ts`, `extractTokenFromRequest.ts`, `checkOrigin.ts`, `offlineQueue.ts`, `csrf.ts`, `cookies.ts`, `httpApiUtils.ts`, `serviceRoute.ts`

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@luckystack/core",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "LuckyStack core: socket-first transport contracts, Redis adapter, project-config registry, hooks registry, response normalization, rate limiting, and shared session types. Foundation for every other @luckystack/* package.",
+  "license": "MIT",
+  "author": "Mathijs van Melick <mathijsvanmelick3@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ItsLucky23/LuckyStack-v2.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/ItsLucky23/LuckyStack-v2/tree/master/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/ItsLucky23/LuckyStack-v2/issues"
+  },
+  "keywords": [
+    "luckystack",
+    "socket.io",
+    "realtime",
+    "framework",
+    "fullstack",
+    "prisma",
+    "typescript",
+    "redis",
+    "react",
+    "nodejs"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "import": "./dist/eslint/index.js"
+    },
+    "./typemap": {
+      "types": "./dist/apiTypeStubs.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CLAUDE.md",
+    "docs",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@socket.io/redis-adapter": "^8.3.0",
+    "dotenv": "^16.6.1"
+  },
+  "peerDependencies": {
+    "@prisma/client": "^6.19.0",
+    "eslint": "^9.0.0",
+    "ioredis": "^5.10.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.0.0",
+    "socket.io": "^4.8.0",
+    "socket.io-client": "^4.8.0",
+    "sonner": "^2.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": { "optional": true },
+    "react": { "optional": true },
+    "react-dom": { "optional": true },
+    "react-router-dom": { "optional": true },
+    "sonner": { "optional": true }
+  }
+}