@luckystack/core 0.10.2 → 0.11.0

package/dist/eslint/rules/no-unsafe-sync-wrappers.d.ts

@@ -0,0 +1,3 @@
+import type { EslintRule } from '../internal/ruleTypes.js';
+declare const rule: EslintRule;
+export default rule;

package/dist/eslint/rules/prefer-luckystack-confirm.d.ts

@@ -0,0 +1,3 @@
+import type { EslintRule } from '../internal/ruleTypes.js';
+declare const rule: EslintRule;
+export default rule;

package/dist/eslint/rules/prefer-luckystack-dropdown.d.ts

@@ -0,0 +1,3 @@
+import type { EslintRule } from '../internal/ruleTypes.js';
+declare const rule: EslintRule;
+export default rule;

package/dist/eslint/rules/prefer-luckystack-notify.d.ts

@@ -0,0 +1,3 @@
+import type { EslintRule } from '../internal/ruleTypes.js';
+declare const rule: EslintRule;
+export default rule;

package/dist/extractToken.d.ts

@@ -0,0 +1,12 @@
+import { Socket } from 'socket.io';
+/**
+ * Extract the authentication token from a Socket.io connection.
+ *
+ * Checks `config.sessionBasedToken` to determine where to look:
+ * - `true`: Token is in `socket.handshake.auth.token` (sessionStorage on client)
+ * - `false`: Token is in cookies via `socket.handshake.headers.cookie`
+ *
+ * @param socket - The Socket.io socket instance
+ * @returns The token string or null if not found
+ */
+export declare const extractTokenFromSocket: (socket: Pick<Socket, 'handshake'>) => string | null;

package/dist/extractTokenFromRequest.d.ts

@@ -0,0 +1,12 @@
+import { IncomingMessage } from 'node:http';
+/**
+ * Extract the authentication token from an HTTP request.
+ *
+ * Supports tokens from:
+ * - `Authorization: Bearer <token>` header
+ * - the configured session cookie
+ *
+ * @param req - The HTTP incoming message
+ * @returns The token string or null if not found
+ */
+export declare const extractTokenFromRequest: (req: IncomingMessage) => string | null;

package/dist/getParams.d.ts

@@ -0,0 +1,9 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+interface getParamsType {
+    method: string;
+    req: IncomingMessage;
+    res: ServerResponse;
+    queryString?: string;
+}
+export default function getParams({ method, req, res: _res, queryString }: getParamsType): Promise<Record<string, unknown> | null>;
+export {};

package/dist/hooks/registry.d.ts

@@ -0,0 +1,12 @@
+import type { HookName, HookPayloads, HookHandler, HookStopSignal, SyncHookHandler, SyncHookName, SyncHookPayloads } from './types.js';
+export type DispatchResult = {
+    stopped: false;
+} | {
+    stopped: true;
+    signal: HookStopSignal;
+};
+export declare const registerHook: <TName extends HookName>(name: TName, handler: HookHandler<HookPayloads[TName]>) => (() => void);
+export declare const dispatchHook: <TName extends HookName>(name: TName, payload: HookPayloads[TName]) => Promise<DispatchResult>;
+export declare const clearAllHooks: () => void;
+export declare const registerSyncHook: <TName extends SyncHookName>(name: TName, handler: SyncHookHandler<SyncHookPayloads[TName]>) => (() => void);
+export declare const dispatchSyncHook: <TName extends SyncHookName>(name: TName, payload: SyncHookPayloads[TName]) => void;

package/dist/hooks/types.d.ts

@@ -0,0 +1,446 @@
+/**
+ * Core hook contract: framework-generic payload shapes + augmentable registry.
+ *
+ * Feature packages (login/sync/api/presence/...) extend `HookPayloads` via
+ * TypeScript module augmentation:
+ *
+ * ```ts
+ * // packages/<feature>/src/hookPayloads.ts
+ * declare module '@luckystack/core' {
+ *   interface HookPayloads {
+ *     myFeatureHook: { ... };
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * Module-augmentation files MUST be in a tsconfig `include` path for TS to
+ * pick up the merge; a side-effect import from the package's `index.ts`
+ * (`import './hookPayloads';`) guarantees this.
+ */
+import type { ErrorResponseInput, NormalizedErrorResponse } from '../responseNormalizer.js';
+/**
+ * Minimal session shape used inside core-owned hook payloads. Defined here
+ * (instead of imported from `@luckystack/login`) so `@luckystack/core` stays
+ * independent of login. Any concrete session type (`BaseSessionLayout`,
+ * project-level `SessionLayout` extending Prisma User, etc.) is structurally
+ * assignable to this shape.
+ */
+export interface HookSessionShape {
+    id: string;
+    token?: string;
+    email?: string | null;
+    name?: string | null;
+    avatar?: string | null;
+    avatarFallback?: string | null;
+    admin?: boolean | null;
+    language?: string | null;
+    roomCodes?: string[];
+}
+export interface HookStopSignal {
+    stop: true;
+    errorCode: string;
+    httpStatus?: number;
+    /**
+     * Optional output override for per-recipient hooks (`preSyncRecipient`).
+     * When present on a stop signal the framework DOES NOT skip the recipient —
+     * instead it sends this value in place of the full `serverOutput`. Use to
+     * redact PII before delivery without excluding the socket from the fanout.
+     * Ignored by all other hook dispatch sites.
+     */
+    overrideOutput?: unknown;
+}
+/** Handlers return undefined / void to continue, or a stop signal to abort the main flow. */
+export type HookResult = void | undefined | HookStopSignal;
+export type HookHandler<TPayload> = (payload: TPayload) => Promise<HookResult> | HookResult;
+export interface PreApiValidatePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    /**
+     * Optional transport tag — populated by the framework's socket/HTTP API
+     * handlers so hook subscribers can branch on it (e.g. open span with a
+     * different op name). Optional so consumer-side dispatchers don't have to
+     * set it explicitly.
+     */
+    transport?: 'socket' | 'http';
+}
+export interface PostApiValidatePayload extends PreApiValidatePayload {
+    validation: {
+        status: 'success';
+    } | {
+        status: 'error';
+        message: string;
+    };
+}
+export interface PreApiExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostApiExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    result: unknown;
+    error: Error | null;
+    durationMs: number;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface ApiResponseEnvelope {
+    status: 'success' | 'error';
+    httpStatus?: number;
+    errorCode?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface PreApiRespondPayload {
+    routeName: string;
+    user: HookSessionShape | null;
+    response: ApiResponseEnvelope;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostApiRespondPayload {
+    routeName: string;
+    user: HookSessionShape | null;
+    response: ApiResponseEnvelope;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PreSyncAuthorizePayload {
+    routeName: string;
+    /** Raw (un-validated) data payload. May be reshape-able by the consumer. */
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    /** Room code / receiver token — the sync's intended audience. */
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostSyncAuthorizePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PreSyncValidatePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostSyncValidatePayload extends PreSyncValidatePayload {
+    validation: {
+        status: 'success';
+    } | {
+        status: 'error';
+        message: string;
+    };
+}
+export interface PreSyncExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostSyncExecutePayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    result: unknown;
+    error: Error | null;
+    durationMs: number;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PreSyncFanoutPayload {
+    routeName: string;
+    data: Record<string, unknown>;
+    user: HookSessionShape | null;
+    receiver: string;
+    serverOutput: unknown;
+    /** Optional transport tag — see {@link PreApiValidatePayload.transport}. */
+    transport?: 'socket' | 'http';
+}
+export interface PostSyncFanoutPayload extends PreSyncFanoutPayload {
+    recipientCount: number;
+}
+export interface PreSyncStreamPayload {
+    routeName: string;
+    /** Stream chunk being sent (already serialised by the framework). */
+    chunk: unknown;
+    /** Final recipient — socket id when known, room code otherwise. */
+    recipient: string;
+}
+export interface PostSyncStreamPayload extends PreSyncStreamPayload {
+    /** Total chunks streamed so far in this sync invocation. */
+    chunkIndex: number;
+}
+export interface ApiErrorPayload {
+    route: string;
+    method?: string;
+    requestId?: string;
+    user?: HookSessionShape | null;
+    error: Error;
+}
+export interface SyncErrorPayload {
+    route: string;
+    method?: string;
+    requestId?: string;
+    user?: HookSessionShape | null;
+    error: Error;
+}
+export interface RateLimitExceededPayload {
+    /** Where the limit was hit — IP, user, or route. */
+    scope: 'ip' | 'user' | 'route' | 'auth';
+    /** The key that exceeded its limit (sanitized — no tokens). */
+    key: string;
+    /** Configured limit count for this key. */
+    limit: number;
+    /** Window in milliseconds. */
+    windowMs: number;
+    /** Current bucket count after the rejected request. */
+    count: number;
+    /** Optional route or transport context. */
+    route?: string;
+    ip?: string;
+    userId?: string;
+}
+export interface CorsRejectedPayload {
+    /** Origin header sent by the client. */
+    origin: string;
+    /** Origin after framework normalization (scheme + host[:port]). */
+    normalizedOrigin: string;
+    /** Effective allowed-origins set at the time of rejection. */
+    allowedOrigins: string[];
+    /** Whether `allowLocalhost` was on. */
+    allowLocalhost: boolean;
+    /** Optional route the rejected request was for. */
+    route?: string;
+    /**
+     * Why the request was rejected (server HOK-27). Distinguishes a present-but-
+     * disallowed Origin (`'origin-not-allowed'`) from a MISSING Origin header
+     * (`'origin-missing'`, the 403 dispatched by the server's origin gate) and the
+     * normalization-failure case. Optional so existing `allowedOrigin()` callers
+     * that don't set it stay source-compatible.
+     */
+    reason?: 'origin-not-allowed' | 'origin-missing' | 'origin-malformed';
+}
+export interface PreSessionRefreshPayload {
+    token: string;
+    userId: string | null;
+    oldTtl: number | null;
+    newTtl: number;
+}
+export interface PostSessionRefreshPayload {
+    token: string;
+    userId: string | null;
+    oldTtl: number | null;
+    newTtl: number;
+    /** True if Redis EXPIRE succeeded; false on failure or non-existent key. */
+    applied: boolean;
+}
+export interface SessionCreatedPayload {
+    token: string;
+    userId: string;
+    /** How the session came to exist (credentials login, OAuth, refresh-mint, ...). */
+    via?: string;
+}
+export interface SessionRevokedPayload {
+    token: string;
+    userId: string | null;
+    /** Why the session was revoked (logout, kicked-by-new-device, admin, expiry, ...). */
+    reason?: string;
+}
+export interface OnUploadStartPayload {
+    userId: string;
+    contentType: string;
+    sizeBytes: number;
+    uploadKind: 'avatar' | string;
+}
+export interface OnUploadCompletePayload {
+    userId: string;
+    fileName: string;
+    sizeBytes: number;
+    uploadKind: 'avatar' | string;
+}
+export interface PreAvatarServePayload {
+    /** The route path requested (`/avatars/:fileId`). */
+    routePath: string;
+    /** The allowlisted file id resolved from the route path. */
+    fileId: string;
+}
+export interface PostAvatarServePayload {
+    routePath: string;
+    fileId: string;
+    /** Disk extension of the format that was served (e.g. `'webp'`). */
+    extension: string;
+    /** Content-Type header sent for the served file. */
+    contentType: string;
+}
+export interface CsrfMismatchPayload {
+    /** Path of the rejected request. */
+    route: string;
+    /** HTTP method of the rejected request. */
+    method?: string;
+    /** Request id (X-Request-Id) for log correlation. */
+    requestId?: string;
+    /** User id from the session that the request claimed, if any. */
+    userId?: string;
+    /** Whether a token was provided in `x-csrf-token` (presence only — never the value). */
+    providedToken: boolean;
+}
+export interface PreSocketMessagePayload {
+    /** Which socket pipeline received the message. */
+    channel: 'api' | 'sync';
+    /** Socket.io connection id of the originator. */
+    socketId: string;
+    /** Handshake address of the originator (best-effort; honours no proxy trust). */
+    ip: string;
+    /** Whether the originating socket carried a session token (presence only — never the value). */
+    authenticated: boolean;
+    /** Raw route name from the message envelope, when present (un-parsed, un-trusted). */
+    routeName?: string;
+}
+export interface PreHttpRequestPayload {
+    /** HTTP method (always uppercase: GET/POST/...). */
+    method: string;
+    /** Request URL (path + query). */
+    url: string;
+    /** Caller-supplied or framework-generated `X-Request-Id`. */
+    requestId: string;
+    /** Origin header value (or empty string when absent). */
+    origin: string;
+    /**
+     * Subset of headers — `authorization`, `cookie`, etc. are NOT included
+     * to keep payloads safe for logging. Use the full request object via
+     * a custom route if you need raw access.
+     */
+    headers: Record<string, string>;
+}
+export interface PostHttpRequestPayload {
+    /** HTTP method (always uppercase). */
+    method: string;
+    /** Request URL (path + query). */
+    url: string;
+    /** Caller-supplied or framework-generated `X-Request-Id`. */
+    requestId: string;
+    /** Final HTTP status code written to the response. */
+    statusCode: number;
+    /** Wall-clock duration from request receipt to response, in ms. */
+    durationMs: number;
+}
+export interface ApiAuthRejectedPayload {
+    /** Resolved route name (`api/billing/getInvoice/v1`). */
+    routeName: string;
+    /** Why auth failed. `'login-required'` = no/invalid session on a login route;
+     *  `'additional-failed'` = a session existed but an `additional[]` predicate
+     *  rejected; `'invalid-condition'` = a misconfigured predicate (setup error). */
+    reason: 'login-required' | 'additional-failed' | 'invalid-condition';
+    /** Session user id when a (insufficient) session was present, else null. */
+    userId: string | null;
+    /** Resolved client IP (honours `http.trustProxy`). */
+    ip?: string;
+    /** Transport the request arrived on. */
+    transport?: 'socket' | 'http';
+    /** The specific `additional[]` key that failed, when `reason === 'additional-failed'`. */
+    failedKey?: string;
+}
+export interface PreSyncRecipientPayload {
+    /** Resolved route name (`sync/board/moveCard/v1`). */
+    routeName: string;
+    /** Room code / receiver this fanout is for. */
+    receiver: string;
+    /** Socket id of THIS recipient. */
+    recipientSocketId: string;
+    /**
+     * Session token of THIS recipient, as read from its socket handshake — the
+     * same value the fan-out uses for `ignoreSelf`. `null` for an anonymous
+     * socket. Cheap: no session read is performed to produce it.
+     */
+    recipientToken: string | null;
+    /**
+     * Always `null`. Kept on the payload for backward compatibility; resolve the
+     * user from `recipientToken` when you need it.
+     */
+    recipientUserId: string | null;
+    /** The server-validated output about to be sent. */
+    serverOutput: unknown;
+}
+export interface PreServerStopPayload {
+    /** Why the server is stopping — the signal name, or `'manual'` for a programmatic stop. */
+    reason: 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'manual';
+    /**
+     * Soft budget (ms) the server intends to wait for shutdown handlers + in-flight
+     * requests to drain before forcing exit. Handlers should not block longer than
+     * this. `undefined` when the server applies no deadline.
+     */
+    timeoutMs?: number;
+}
+export interface HookPayloads {
+    preHttpRequest: PreHttpRequestPayload;
+    postHttpRequest: PostHttpRequestPayload;
+    preSocketMessage: PreSocketMessagePayload;
+    preApiValidate: PreApiValidatePayload;
+    postApiValidate: PostApiValidatePayload;
+    preApiExecute: PreApiExecutePayload;
+    postApiExecute: PostApiExecutePayload;
+    preApiRespond: PreApiRespondPayload;
+    transformApiResponse: PreApiRespondPayload;
+    postApiRespond: PostApiRespondPayload;
+    preSyncAuthorize: PreSyncAuthorizePayload;
+    postSyncAuthorize: PostSyncAuthorizePayload;
+    preSyncValidate: PreSyncValidatePayload;
+    postSyncValidate: PostSyncValidatePayload;
+    preSyncExecute: PreSyncExecutePayload;
+    postSyncExecute: PostSyncExecutePayload;
+    preSyncFanout: PreSyncFanoutPayload;
+    postSyncFanout: PostSyncFanoutPayload;
+    preSyncRecipient: PreSyncRecipientPayload;
+    preSyncStream: PreSyncStreamPayload;
+    postSyncStream: PostSyncStreamPayload;
+    apiError: ApiErrorPayload;
+    syncError: SyncErrorPayload;
+    apiAuthRejected: ApiAuthRejectedPayload;
+    rateLimitExceeded: RateLimitExceededPayload;
+    corsRejected: CorsRejectedPayload;
+    csrfMismatch: CsrfMismatchPayload;
+    preSessionRefresh: PreSessionRefreshPayload;
+    postSessionRefresh: PostSessionRefreshPayload;
+    sessionCreated: SessionCreatedPayload;
+    sessionRevoked: SessionRevokedPayload;
+    onUploadStart: OnUploadStartPayload;
+    onUploadComplete: OnUploadCompletePayload;
+    preAvatarServe: PreAvatarServePayload;
+    postAvatarServe: PostAvatarServePayload;
+    preServerStop: PreServerStopPayload;
+}
+export interface PreErrorNormalizePayload {
+    response: ErrorResponseInput;
+    preferredLocale?: string | null;
+    userLanguage?: string | null;
+    fallbackHttpStatus?: number;
+}
+export interface PostErrorNormalizePayload {
+    normalized: NormalizedErrorResponse;
+    preferredLocale?: string | null;
+    userLanguage?: string | null;
+}
+export interface SyncHookPayloads {
+    preErrorNormalize: PreErrorNormalizePayload;
+    postErrorNormalize: PostErrorNormalizePayload;
+}
+export type SyncHookName = keyof SyncHookPayloads;
+export type SyncHookHandler<TPayload> = (payload: TPayload) => void;
+export type HookName = keyof HookPayloads;

package/dist/httpApiUtils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * HTTP API Utilities
+ *
+ * Helpers for HTTP API request handling including:
+ * - Smart HTTP method detection based on API name
+ * - Method validation
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Single source of truth for the GET-prefix naming heuristic
+ * (`get` / `fetch` / `list`). Used by both `inferHttpMethod` here and the
+ * client transport's `isGetMethod` fallback in `apiRequest.ts`, so the two
+ * prefix heuristics can't drift apart. Expects an already-lowercased leaf name.
+ */
+export declare const isGetMethodName: (methodNameLower: string) => boolean;
+/**
+ * Infer the HTTP method from an API name based on common naming conventions.
+ *
+ * - Names starting with "get" → GET
+ * - Names starting with "delete" or "remove" → DELETE
+ * - Names starting with "update" or "edit" → PUT
+ * - Everything else → POST (create operations, actions)
+ *
+ * @example
+ * ```typescript
+ * inferHttpMethod('getUserData')   // → 'GET'
+ * inferHttpMethod('deleteAccount') // → 'DELETE'
+ * inferHttpMethod('updateProfile') // → 'PUT'
+ * inferHttpMethod('createUser')    // → 'POST'
+ * inferHttpMethod('sendEmail')     // → 'POST'
+ * ```
+ */
+export declare const inferHttpMethod: (apiName: string) => HttpMethod;
+/**
+ * Get the effective HTTP method for an API.
+ * Uses explicit export if available, otherwise infers from name.
+ */
+export declare const getEffectiveHttpMethod: (apiConfig: {
+    httpMethod?: HttpMethod;
+}, apiName: string) => HttpMethod;
+/**
+ * Check if an HTTP method is valid for an API.
+ *
+ * @param requestMethod - The method from the HTTP request
+ * @param allowedMethod - The method the API accepts
+ * @returns true only when the method matches the route's allowed method.
+ *
+ * NOTE: `OPTIONS` is intentionally NOT treated as allowed here. A custom-route
+ * author wiring this into their dispatch must answer CORS preflights BEFORE the
+ * route check — letting `OPTIONS` through would execute the handler on a request
+ * the CSRF middleware treats as non-state-changing (CSRF-exempt), opening a
+ * bypass on method-locked routes.
+ */
+export declare const isMethodAllowed: (requestMethod: string, allowedMethod: HttpMethod) => boolean;