@luckystack/core 0.10.2 → 0.12.0

package/dist/roomNameFormatterRegistry.d.ts

@@ -0,0 +1,36 @@
+export interface RoomNameFormatterContext {
+    /**
+     * Which room FAMILY the name is being formatted for — a formatter may branch on
+     * this to isolate genuinely-separate families, but MUST NOT use it to give the
+     * same raw room code different physical names across a single family's
+     * operations. A content room is joined, left, membership-checked, broadcast to,
+     * and streamed to under the SINGLE canonical `'broadcast'` purpose (M5); the
+     * framework never varies a content room's physical name by operation, because a
+     * socket physically IN `f(R,'join')` could never receive a fanout targeting
+     * `f(R,'broadcast')`. `'presence'` is the one genuinely-separate family (its own
+     * rooms). `'join'`/`'leave'` remain in the union for backward-compat but the
+     * framework no longer emits them for room-NAME formatting — treat them, if ever
+     * seen, identically to `'broadcast'`.
+     */
+    purpose: 'join' | 'leave' | 'broadcast' | 'presence';
+    /**
+     * Session user id of whoever is performing THIS operation, when known, else
+     * null — CONTEXT ONLY. For a shared content room under `'broadcast'` the
+     * framework passes the joiner on join/rejoin, the SENDER on fan-out and the
+     * originator on `broadcastStream`, so the value differs per call for the SAME
+     * room. A formatter must therefore never fold `userId` into a content room's
+     * physical name: join and fan-out would resolve to different rooms and every
+     * broadcast would reach nobody, silently. Per-user isolation belongs in the
+     * raw room code the consumer chooses, or in the separate `'presence'` family.
+     */
+    userId?: string | null;
+}
+export type RoomNameFormatter = (rawRoomName: string, ctx: RoomNameFormatterContext) => string;
+/** Override how every framework room name is namespaced (multi-tenant prefixing). */
+export declare const registerRoomNameFormatter: (formatter: RoomNameFormatter) => void;
+/** Read the active formatter (defaults to identity). */
+export declare const getRoomNameFormatter: () => RoomNameFormatter;
+/** Apply the active formatter — the single helper framework room-sites call. */
+export declare const formatRoomName: (rawRoomName: string, ctx: RoomNameFormatterContext) => string;
+/** The built-in identity formatter (exported for tests / explicit reset). */
+export declare const defaultRoomNameFormatter: RoomNameFormatter;

package/dist/roomSockets.d.ts

@@ -0,0 +1,23 @@
+import type { Server as SocketIOServer } from 'socket.io';
+/** A recipient as returned by Socket.io's adapter-aware `fetchSockets()`. */
+export type RoomSocket = Awaited<ReturnType<SocketIOServer['fetchSockets']>>[number];
+export interface GetRoomSocketsOptions {
+    /**
+     * User id forwarded to the room-name formatter as CONTEXT. Leave it out (or
+     * pass `null`) for a shared room — the formatter contract forbids folding it
+     * into a content room's physical name, so it only matters to a formatter that
+     * logs or branches on it.
+     */
+    userId?: string | null;
+}
+/**
+ * Resolve every socket currently in `room`, on EVERY instance sharing the
+ * Redis adapter. `room` is the LOGICAL code (what the client joined); it is
+ * routed through the registered room-name formatter under the canonical
+ * `'broadcast'` purpose exactly like the sync fan-out. The `'all'` sentinel
+ * returns every connected socket everywhere.
+ *
+ * Throws when no Socket.io server is registered: a silent `[]` is precisely the
+ * failure class this helper exists to remove.
+ */
+export declare const getRoomSockets: (room: string, options?: GetRoomSocketsOptions) => Promise<RoomSocket[]>;

package/dist/routedDataQuery.d.ts

@@ -0,0 +1,7 @@
+export declare const ROUTED_DATA_QUERY_KEY = "__luckystack_data";
+/**
+ * Append `data` to `path` as the reserved `__luckystack_data` query value
+ * (JSON-encoded), plus any `extraParams`. Tolerates a `path` that already
+ * carries a query string.
+ */
+export declare const buildRoutedGetUrl: (path: string, data: unknown, extraParams?: Record<string, string>) => string;

package/dist/routedHttpInvocation.d.ts

@@ -0,0 +1,20 @@
+import type { HttpMethodLiteral } from './apiMethodMapRegistry.js';
+export type RoutedInvocationMethod = HttpMethodLiteral;
+export interface RoutedInvocationResponse<TResponse> {
+    kind: 'response';
+    response: TResponse;
+    httpStatus: number;
+}
+export interface RoutedInvocationFailure {
+    kind: 'aborted' | 'timeout' | 'network-error' | 'invalid-response';
+}
+export type RoutedInvocationResult<TResponse> = RoutedInvocationResponse<TResponse> | RoutedInvocationFailure;
+export interface RoutedHttpInvocationInput<TStream> {
+    path: string;
+    method: RoutedInvocationMethod;
+    data: Record<string, unknown>;
+    stream?: (payload: TStream) => void;
+    signals?: readonly (AbortSignal | null | undefined)[];
+    timeoutMs?: number | false;
+}
+export declare const invokeRoutedHttp: <TResponse, TStream = Record<string, unknown>>({ path, method, data, stream, signals, timeoutMs, }: RoutedHttpInvocationInput<TStream>) => Promise<RoutedInvocationResult<TResponse>>;

package/dist/runtimeMapsRegistry.d.ts

@@ -0,0 +1,18 @@
+type RuntimeMapRecord = Record<string, unknown>;
+export interface RuntimeApiMapsResult {
+    apisObject: RuntimeMapRecord;
+    functionsObject: RuntimeMapRecord;
+}
+export interface RuntimeSyncMapsResult {
+    syncObject: RuntimeMapRecord;
+    functionsObject: RuntimeMapRecord;
+}
+export interface RuntimeMapsProvider {
+    getRuntimeApiMaps: () => Promise<RuntimeApiMapsResult>;
+    getRuntimeSyncMaps: () => Promise<RuntimeSyncMapsResult>;
+}
+export declare const registerRuntimeMapsProvider: (provider: RuntimeMapsProvider) => void;
+export declare const isRuntimeMapsProviderRegistered: () => boolean;
+export declare const getRuntimeApiMaps: () => Promise<RuntimeApiMapsResult>;
+export declare const getRuntimeSyncMaps: () => Promise<RuntimeSyncMapsResult>;
+export {};

package/dist/runtimeTypeValidation.d.ts

@@ -0,0 +1,13 @@
+type ValidationResult = {
+    status: 'success';
+} | {
+    status: 'error';
+    message: string;
+};
+export declare const validateInputByType: ({ typeText, value, rootKey, filePath, }: {
+    typeText?: string;
+    value: unknown;
+    rootKey: string;
+    filePath?: string;
+}) => Promise<ValidationResult>;
+export {};

package/dist/secretsResolved.d.ts

@@ -0,0 +1,3 @@
+export type SecretsResolvedListener = (changedKeys: readonly string[] | undefined) => void;
+export declare const registerSecretsResolvedListener: (listener: SecretsResolvedListener) => (() => void);
+export declare const notifySecretsResolved: (changedKeys?: readonly string[]) => void;

package/dist/{sentrySetup-HNIURVUZ.js → sentrySetup-OLZ4BO7Q.js}

@@ -4,7 +4,7 @@ import {
   initSharedSentry,
   setSentryUser,
   startSpan
-} from "./chunk-IJYNVM2W.js";
+} from "./chunk-P3SSLA3E.js";
 import "./chunk-OWMII7WC.js";
 export {
   captureException,
@@ -13,4 +13,4 @@ export {
   setSentryUser,
   startSpan
 };
-//# sourceMappingURL=sentrySetup-HNIURVUZ.js.map
+//# sourceMappingURL=sentrySetup-OLZ4BO7Q.js.map

package/dist/sentrySetup.d.ts

@@ -0,0 +1,21 @@
+interface SentryInstance {
+    captureException: (exception: unknown, ...args: unknown[]) => string;
+    captureMessage: (message: string, ...args: unknown[]) => string;
+    setUser: (user: unknown) => void;
+    setContext: (key: string, context: unknown) => void;
+    startInactiveSpan?: (context: unknown) => unknown;
+}
+/**
+ * @deprecated Use `registerErrorTracker` from `@luckystack/error-tracking` instead.
+ * Will be removed in a future major version.
+ */
+export declare const initSharedSentry: (instance: SentryInstance) => void;
+export declare const captureException: (error: unknown, context?: Record<string, unknown>) => void;
+export declare const captureMessage: (message: string, level?: 'info' | 'warning' | 'error' | 'fatal', context?: Record<string, unknown>) => void;
+export declare const setSentryUser: (user: {
+    id?: string;
+    email?: string;
+    username?: string;
+} | null) => void;
+export declare const startSpan: (name: string, op: string) => unknown;
+export {};

package/dist/serveAvatars.d.ts

@@ -0,0 +1,5 @@
+import { ServerResponse } from "node:http";
+export declare const serveAvatar: ({ routePath, res, }: {
+    routePath: string;
+    res: ServerResponse;
+}) => Promise<void>;

package/dist/serviceRoute.d.ts

@@ -0,0 +1,27 @@
+export interface ServiceRouteParseSuccess {
+    status: 'success';
+    normalizedRouteName: string;
+    service: string;
+    routeName: string;
+}
+export interface ServiceRouteParseError {
+    status: 'error';
+    reason: string;
+}
+export type ServiceRouteParseResult = ServiceRouteParseSuccess | ServiceRouteParseError;
+export interface TransportRouteParseSuccess {
+    status: 'success';
+    normalizedFullName: string;
+    version: string;
+    serviceRoute: ServiceRouteParseSuccess;
+}
+export interface TransportRouteParseError {
+    status: 'error';
+    reason: string;
+}
+export type TransportRouteParseResult = TransportRouteParseSuccess | TransportRouteParseError;
+export declare const parseServiceRouteName: (value: string) => ServiceRouteParseResult;
+export declare const parseTransportRouteName: ({ value, prefix, }: {
+    value: string;
+    prefix: 'api' | 'sync';
+}) => TransportRouteParseResult;

package/dist/servicesConfigRegistry.d.ts

@@ -0,0 +1,22 @@
+export interface ServiceDefinition {
+    /** 'root' -> reserved for the system service. Otherwise a folder name under srcDir. */
+    source: 'root' | string;
+}
+export interface PresetDefinition {
+    description?: string;
+    /** Services that are bundled together into one backend artifact. */
+    services: string[];
+}
+export interface ServicesConfigShape {
+    services: Record<string, ServiceDefinition>;
+    presets: Record<string, PresetDefinition>;
+    /**
+     * Pure-data ownership manifest for HTTP routes outside `/api/*` and `/sync/*`.
+     * Keys are absolute path prefixes; values are service keys. The router uses
+     * longest-prefix matching, so `/webhooks/admin` may override `/webhooks`.
+     */
+    customRoutes?: Record<string, string>;
+}
+export declare const registerServicesConfig: (config: ServicesConfigShape) => ServicesConfigShape;
+export declare const getServicesConfig: () => ServicesConfigShape;
+export declare const isServicesConfigRegistered: () => boolean;

package/dist/sessionProviderRegistry.d.ts

@@ -0,0 +1,46 @@
+import type { Socket } from 'socket.io';
+import type { BaseSessionLayout } from './sessionTypes.js';
+export interface SessionSaveResult {
+    ok: boolean;
+    errorCode?: string;
+}
+export interface SessionLogoutInput {
+    token: string | null;
+    socket?: Socket;
+    userId?: string | null;
+    skipSessionDelete?: boolean;
+}
+export interface SessionProvider {
+    getSession: (token: string | null) => Promise<BaseSessionLayout | null>;
+    saveSession: (token: string, data: BaseSessionLayout, newUser?: boolean, options?: {
+        supersedeToken?: string;
+    }) => Promise<SessionSaveResult>;
+    deleteSession: (token: string, options?: {
+        skipSocketLogout?: boolean;
+    }) => Promise<boolean>;
+    logout: (input: SessionLogoutInput) => Promise<void>;
+}
+export declare const registerSessionProvider: (next: SessionProvider) => void;
+export declare const getRegisteredSessionProvider: () => SessionProvider | null;
+export declare const isSessionProviderRegistered: () => boolean;
+export declare const resetSessionProviderForTests: () => void;
+export declare const readSession: (token: string | null) => Promise<BaseSessionLayout | null>;
+/**
+ * Persist a session via the registered provider, or no-op if no login provider
+ * is registered (unauthenticated-app case).
+ *
+ * **WARNING**: when no session provider is registered, this returns `{ ok: true }`
+ * as a no-op — the session is NOT actually persisted anywhere. Callers that
+ * check `result.ok` before considering a user logged in will incorrectly
+ * proceed as if the session was saved. This is intentional for apps that do not
+ * use `@luckystack/login`, but on a partial install (login package misconfigured
+ * or not yet registered) the failure is silent rather than loud.
+ * Use `isSessionProviderRegistered()` at boot to verify the provider is present.
+ */
+export declare const writeSession: (token: string, data: BaseSessionLayout, newUser?: boolean, options?: {
+    supersedeToken?: string;
+}) => Promise<SessionSaveResult>;
+export declare const removeSession: (token: string, options?: {
+    skipSocketLogout?: boolean;
+}) => Promise<boolean>;
+export declare const performLogout: (input: SessionLogoutInput) => Promise<void>;

package/dist/sessionTypes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What `T` becomes after `JSON.stringify` → `JSON.parse`, at the type level.
+ *
+ * The mirror of what the codegen does to route OUTPUTS. Use it wherever you
+ * hand-write a type for something that CROSSES THE WIRE — the client never
+ * receives your server type, it receives JSON, and JSON has no `Date`:
+ *
+ *   type ClientUser = Jsonify<User>;   // createdAt: string, not Date
+ *
+ * Without it a type says `Date`, the client gets `"2026-07-15T15:20:15.553Z"`,
+ * and `user.createdAt.getTime()` compiles and then throws at runtime.
+ *
+ * Deliberately SHALLOW — one level of properties, descending only into arrays.
+ * A fully recursive object mapper does not survive contact with Prisma's
+ * self-referential `JsonValue`. Already-JSON-stable values are therefore an
+ * identity boundary: do not recursively rebuild what JSON already represents.
+ * The NON-DISTRIBUTIVE tuple guard is load-bearing — it recognizes the complete
+ * `JsonValue` union before the Date branch distributes `Date | null` into
+ * `string | null`.
+ */
+type JsonStableValue = string | number | boolean | null | JsonStableValue[] | {
+    [key: string]: JsonStableValue | undefined;
+};
+type JsonifyValue<TValue> = [TValue] extends [JsonStableValue] ? TValue : TValue extends Date ? string : TValue extends readonly (infer TElement)[] ? JsonifyValue<TElement>[] : TValue;
+export type Jsonify<T> = {
+    [TKey in keyof T]: JsonifyValue<T[TKey]>;
+};
+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[];
+    /**
+     * CSRF token bound to this session. Generated by `saveSession` on first
+     * write. Validated by the HTTP handler on state-changing requests when
+     * the session is in cookie mode. Token-mode sessions don't need this
+     * (cross-origin requests don't auto-attach a sessionStorage value).
+     */
+    csrfToken?: string;
+    /**
+     * Most recent successful login time (set to "now" on each login). Optional
+     * — populated only when the User schema has a `lastLogin` column.
+     */
+    lastLogin?: Date | string | null;
+    /**
+     * The previous successful login time, captured at this login's moment.
+     * Useful for "Last sign-in: X ago" UI on the post-login dashboard.
+     * Null on first-ever login. Runtime-only — not persisted to the DB.
+     */
+    previousLogin?: Date | string | null;
+}
+export interface AuthProps {
+    /** If true, user must have a valid session with an ID */
+    login: boolean;
+    /** Additional validation rules for session properties */
+    additional?: {
+        /** The session property to check (e.g., 'admin', 'email') */
+        key: keyof BaseSessionLayout;
+        /** Exact value the property must equal (strict comparison) */
+        value?: unknown;
+        /** Type the property must be */
+        type?: 'string' | 'number' | 'boolean';
+        /** If true, property must be null/undefined. If false, must NOT be null/undefined */
+        nullish?: boolean;
+        /** If true, property must be falsy. If false, must be truthy */
+        mustBeFalsy?: boolean;
+    }[];
+}
+export {};

package/dist/sleep.d.ts

@@ -0,0 +1 @@
+export default function sleep(ms: number): Promise<void>;

package/dist/socketEvents.d.ts

@@ -0,0 +1,37 @@
+export declare const socketEventNames: {
+    readonly apiRequest: 'apiRequest';
+    readonly apiCancel: 'apiCancel';
+    readonly sync: 'sync';
+    readonly syncCancel: 'syncCancel';
+    readonly joinRoom: 'joinRoom';
+    readonly leaveRoom: 'leaveRoom';
+    readonly getJoinedRooms: 'getJoinedRooms';
+    readonly updateLocation: 'updateLocation';
+    readonly updateSession: 'updateSession';
+    readonly sessionReplaced: 'sessionReplaced';
+    readonly logout: 'logout';
+    readonly intentionalDisconnect: 'intentionalDisconnect';
+    readonly intentionalReconnect: 'intentionalReconnect';
+    readonly activity: 'activity';
+    readonly userAfk: 'userAfk';
+    readonly userBack: 'userBack';
+    readonly userLeft: 'userLeft';
+    readonly connect: 'connect';
+    readonly disconnect: 'disconnect';
+    readonly reconnectAttempt: 'reconnect_attempt';
+    readonly connectError: 'connect_error';
+    readonly apiResponsePrefix: 'apiResponse-';
+    readonly apiStreamPrefix: 'apiStream-';
+    readonly syncResponsePrefix: 'sync-';
+    readonly syncProgressPrefix: 'sync-progress-';
+    readonly joinRoomResponsePrefix: 'joinRoom-';
+    readonly leaveRoomResponsePrefix: 'leaveRoom-';
+    readonly getJoinedRoomsResponsePrefix: 'getJoinedRooms-';
+};
+export declare const buildApiResponseEventName: (responseIndex: number | string) => string;
+export declare const buildApiStreamEventName: (responseIndex: number | string) => string;
+export declare const buildSyncResponseEventName: (responseIndex: number | string) => string;
+export declare const buildSyncProgressEventName: (responseIndex: number | string) => string;
+export declare const buildJoinRoomResponseEventName: (responseIndex: number | string) => string;
+export declare const buildLeaveRoomResponseEventName: (responseIndex: number | string) => string;
+export declare const buildGetJoinedRoomsResponseEventName: (responseIndex: number | string) => string;

package/dist/socketMiddlewareRegistry.d.ts

@@ -0,0 +1,20 @@
+import type { Socket, Server as SocketIOServer } from 'socket.io';
+export type SocketMiddleware = (socket: Socket, next: (err?: Error) => void) => void;
+/**
+ * Register a Socket.io middleware that will be wired via `io.use(...)` when
+ * the framework boots the socket server. Multiple middlewares can be
+ * registered — they run in registration order before any `connect`
+ * handler fires.
+ */
+export declare const registerSocketMiddleware: (mw: SocketMiddleware) => void;
+/** Read the registered middleware list (read-only view). */
+export declare const getSocketMiddlewares: () => readonly SocketMiddleware[];
+/** Test-only / hot-reload helper. Drops every registered middleware. */
+export declare const clearSocketMiddlewares: () => void;
+/**
+ * Wire every registered middleware into the running Socket.io server.
+ * Called by `@luckystack/server`'s `loadSocket` after the `SocketIOServer`
+ * is constructed and before any `connect` handler is attached, so custom
+ * middlewares run before framework handlers see the socket.
+ */
+export declare const applySocketMiddlewares: (io: SocketIOServer) => void;

package/dist/socketRedisAdapter.d.ts

@@ -0,0 +1,21 @@
+import type { Server as SocketIOServer } from 'socket.io';
+import type { Redis as RedisClient } from 'ioredis';
+import type { RedisAdapterOptions } from '@socket.io/redis-adapter';
+export interface AttachSocketRedisAdapterOptions {
+    /**
+     * Options forwarded to `@socket.io/redis-adapter`'s `createAdapter`
+     * (e.g. `key` prefix, `requestsTimeout`, `publishOnSpecificResponseChannel`).
+     * `key` defaults to {@link resolveSocketAdapterKey} when omitted.
+     */
+    adapterOptions?: Partial<RedisAdapterOptions>;
+    /**
+     * Supply a pre-built pub client instead of `redis.duplicate()`. Use this for
+     * a dedicated adapter connection, custom auth, or a sentinel/cluster handle.
+     * When omitted the framework duplicates the default `redis` handle.
+     */
+    pubClient?: RedisClient;
+    /** Pre-built sub client (see `pubClient`). */
+    subClient?: RedisClient;
+}
+export declare const resolveSocketAdapterKey: () => string;
+export declare const attachSocketRedisAdapter: (io: SocketIOServer, options?: AttachSocketRedisAdapterOptions) => void;

package/dist/socketState.d.ts

@@ -0,0 +1,5 @@
+import type { Socket } from 'socket.io-client';
+export declare let socket: Socket | null;
+export declare const setSocket: (next: Socket | null) => void;
+export declare const incrementResponseIndex: () => number;
+export declare const waitForSocket: () => Promise<Socket | null>;

package/dist/socketStatusTypes.d.ts

@@ -0,0 +1,6 @@
+export type SOCKETSTATUS = "CONNECTED" | "DISCONNECTED" | "AFK" | "RECONNECTING" | "STARTUP";
+export interface statusContent {
+    status: SOCKETSTATUS;
+    reconnectAttempt?: number;
+    endTime?: number;
+}

package/dist/socketTypes.d.ts

@@ -0,0 +1,34 @@
+import type { Server as SocketIOServer } from 'socket.io';
+export interface apiMessage {
+    name: string;
+    data: object;
+    responseIndex: number;
+}
+export interface syncMessage {
+    name: string;
+    data: object;
+    cb: string;
+    receiver: string;
+    responseIndex?: number;
+    ignoreSelf?: boolean;
+}
+export declare const setIoInstance: (io: SocketIOServer | null) => void;
+export interface GetIoInstanceOptions {
+    /**
+     * Return the raw Socket.io server even outside production. Reach for this
+     * ONLY when the per-instance view is what you want (backpressure sampling, a
+     * sweep cleaning up this process's own connections) — and say why in a
+     * comment, because the lint rule `luckystack/no-local-socket-enumeration`
+     * will still flag the access.
+     */
+    raw?: boolean;
+}
+/**
+ * Read the running Socket.io server. Outside production the returned value is
+ * a guarded view that THROWS on the per-instance surfaces
+ * (`sockets.adapter.rooms`, `sockets.adapter.sids`, enumerating
+ * `sockets.sockets`) — see `localSocketEnumerationGuard.ts` for why. Pass
+ * `{ raw: true }` for the unwrapped server. In production the raw server is
+ * always returned; the guard costs nothing there.
+ */
+export declare const getIoInstance: (options?: GetIoInstanceOptions) => SocketIOServer | null;

package/dist/synchronizedEnvHashes.d.ts

@@ -0,0 +1,66 @@
+import type { HealthHashConfig } from './projectConfig.js';
+/**
+ * Hash a synchronized value under an EXPLICIT `{ mode, salt }` (SEC-13). The
+ * shared primitive the router calls with the same config the backend used, so
+ * the cross-env compare still holds:
+ *   - `'plain'`  → `sha256(value)` (today's behavior; `salt` ignored).
+ *   - `'salted'` → `sha256(salt + value)`.
+ *   - `'hmac'`   → `HMAC-SHA256(key=salt, value)`.
+ * A `'salted'`/`'hmac'` mode with an empty resolved salt falls back to `'plain'`
+ * (and is the caller's responsibility to avoid) rather than silently hashing
+ * with an empty key.
+ */
+export declare const hashSynchronizedValueWith: (config: Pick<HealthHashConfig, 'mode'> & {
+    salt: string;
+}, value: string) => string;
+/**
+ * Resolve the effective health-hash config from `http.healthHash`, expanding the
+ * `'@bootUuid'` salt sentinel to the supplied boot UUID. Honoured for BOTH
+ * `'salted'` and `'hmac'` (the 0.2.0 default is `hmac` + `'@bootUuid'`, so the
+ * per-boot UUID becomes the HMAC key — the synchronized-env fingerprint rotates
+ * every restart instead of being a stable, dictionary-attackable `sha256`). The
+ * server passes its current boot UUID; the router, comparing, passes the same
+ * value it read from the backend's handshake. When the sentinel is in play but
+ * no boot UUID is available the config collapses to `'plain'` so the cross-env
+ * compare never silently diverges.
+ */
+export declare const resolveHealthHashConfig: (bootUuid?: string | null) => {
+    mode: HealthHashConfig['mode'];
+    salt: string;
+};
+/**
+ * Safe-to-expose descriptor of the resolved health-hash config. The router needs
+ * to hash with the SAME `{ mode, salt }` the backend used, but a static `salt`
+ * (mode `'salted'`/`'hmac'` with a non-sentinel salt) is a SECRET and must never
+ * leave the backend. So `/_health` exposes only the `mode` + whether the salt is
+ * the `'@bootUuid'` sentinel (the bootUuid itself is already in the response).
+ * From this the router can reproduce the hash for `'plain'` and `'@bootUuid'`
+ * configs, and KNOWS it cannot reproduce a static-salt config (so it skips the
+ * compare instead of reporting a false drift).
+ */
+export interface HealthHashDescriptor {
+    mode: HealthHashConfig['mode'];
+    bootUuidSalt: boolean;
+}
+/** Describe the active health-hash config for the `/_health` payload (no secret salt). */
+export declare const describeHealthHashConfig: () => HealthHashDescriptor;
+/**
+ * Reproduce the backend's resolved `{ mode, salt }` from its `/_health`
+ * descriptor + the shared boot UUID. Returns `null` when the backend uses a
+ * STATIC salt the router cannot see — the caller must then skip the compare
+ * rather than hash with a different (default) config and report a false drift.
+ */
+export declare const resolveHealthHashConfigFromDescriptor: (descriptor: HealthHashDescriptor, bootUuid: string) => {
+    mode: HealthHashConfig['mode'];
+    salt: string;
+} | null;
+export declare const collectSynchronizedEnvKeys: () => string[];
+/**
+ * Compute the `/_health` hash map for every synchronized env var. Reads
+ * `http.healthHash` (call-time) so a consumer's salt/HMAC opt-in applies;
+ * `bootUuid` is consulted only when the salt is the `'@bootUuid'` sentinel.
+ * The 0.2.0 DEFAULT (`{ mode: 'hmac', salt: '@bootUuid' }`) HMAC-keys the output
+ * on `bootUuid`; pass `mode: 'plain'` to restore the historical unsalted output.
+ */
+export declare const computeSynchronizedEnvHashes: (bootUuid?: string | null) => Record<string, string | null>;
+export declare const hashSynchronizedValue: (value: string, bootUuid?: string | null) => string;

package/dist/testFileConvention.d.ts

@@ -0,0 +1,11 @@
+/** Matches `<name>.test|tests|spec.<ts|tsx|js|jsx|mts|cts|mjs|cjs>`. */
+export declare const TEST_FILE_PATTERN: RegExp;
+/** Directory names that conventionally hold tests and never runtime modules. */
+export declare const TEST_DIRECTORY_NAMES: Set<string>;
+/**
+ * True when the given file name (or path — only the last segment is examined)
+ * is a test file by the conventions above.
+ */
+export declare const isTestFile: (fileNameOrPath: string) => boolean;
+/** True when a directory name conventionally holds tests rather than runtime modules. */
+export declare const isTestDirectory: (directoryName: string) => boolean;

package/dist/testResetTargets.d.ts

@@ -0,0 +1,5 @@
+export declare const TEST_RESET_TARGETS: readonly ['rateLimits', 'sessions', 'activeUsers', 'hooks'];
+export type TestResetTarget = typeof TEST_RESET_TARGETS[number];
+/** Query parameter that limits a reset to the listed targets (comma-separated). */
+export declare const TEST_RESET_ONLY_PARAM = "only";
+export declare const isTestResetTarget: (value: string) => value is TestResetTarget;

package/dist/tryCatch.d.ts

@@ -0,0 +1 @@
+export default function tryCatch<T, P = void>(func: (values: P) => Promise<T> | T, params?: P, context?: Record<string, unknown>): Promise<[Error | null, T | null]>;

package/dist/tryCatchClient.d.ts

@@ -0,0 +1 @@
+export default function tryCatch<T, P = void>(func: (values: P) => Promise<T> | T, params?: P, context?: Record<string, unknown>): Promise<[Error | null, T | null]>;

package/dist/tryCatchSync.d.ts

@@ -0,0 +1 @@
+export default function tryCatchSync<T, P = void>(func: (values: P) => T, params?: P): [Error | null, T | null];

package/dist/validateRequest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared validation utilities for API and Sync request handlers.
+ * Extracted to avoid code duplication between handleApiRequest and handleSyncRequest.
+ */
+import type { AuthProps, BaseSessionLayout } from './sessionTypes.js';
+/**
+ * Check if a value is falsy (false, 0, 0n, '', null, undefined, or NaN)
+ */
+export declare const isFalsy: (value: unknown) => boolean;
+export interface ValidationResult {
+    status: 'success' | 'error';
+    errorCode?: string;
+    errorParams?: {
+        key: string;
+        value: string | number | boolean;
+    }[];
+    httpStatus?: number;
+}
+/**
+ * Validate a request against authentication requirements.
+ *
+ * Multiple constraints on a single `additional` entry are AND'd: every
+ * specified field (`nullish`, `type`, `value`, `mustBeFalsy`) must pass
+ * for that entry to validate. Each entry across the array is also AND'd:
+ * the request must pass every entry to succeed.
+ *
+ * Constraint semantics:
+ *   - `nullish: true`     — `val` must be `null` or `undefined`.
+ *   - `nullish: false`    — `val` must NOT be `null` or `undefined`.
+ *   - `type: 'string'`    — `typeof val === 'string'` (skipped when val is null/undefined).
+ *   - `value: <x>`        — strict equality `val === x`. Omit the field entirely if you
+ *                           don't want this check; setting `value: undefined`
+ *                           explicitly means "val must be undefined".
+ *   - `mustBeFalsy: true`  — `isFalsy(val)`.
+ *   - `mustBeFalsy: false` — `!isFalsy(val)`.
+ *
+ * **SECURITY CONTRACT**: this function does NOT check `auth.login`. Login
+ * enforcement is the responsibility of the surrounding API/sync handler — it
+ * must verify the session exists before calling `validateRequest`. Callers
+ * that omit the login check will allow unauthenticated requests through the
+ * `additional[]` predicates even when `auth.login: true` is declared, because
+ * `validateRequest` short-circuits to success when `additional` is empty.
+ * The expected call pattern is:
+ *   1. Check session exists (enforce `auth.login`).
+ *   2. Call `validateRequest({ auth, user })` to enforce `auth.additional[]`.
+ */
+export declare const validateRequest: ({ auth, user }: {
+    auth: AuthProps;
+    user?: BaseSessionLayout | null;
+}) => ValidationResult;