@luckystack/core 0.10.2 → 0.11.0

package/dist/{sessionTypes-DanjuPaE.d.ts → projectConfig.d.ts}

@@ -1,21 +1,5 @@
-type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends object | undefined ? DeepPartial<NonNullable<T[K]>> : T[K];
-};
-/**
- * True when `value` is a plain object literal (prototype is `Object.prototype`
- * or `null`). Arrays, class instances, Maps, Dates, and `null` are rejected so
- * they are treated as opaque replacement values during a merge.
- */
-declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
-/**
- * Deep-merge a deep-partial `override` over a fully-populated `base`,
- * returning a new object. See the module header for the exact behaviour
- * contract. Arrays and non-plain-object values are replaced wholesale; nested
- * plain objects merge recursively; `undefined` override values are ignored.
- */
-declare const deepMerge: <T>(base: T, override: DeepPartial<T> | undefined) => T;
-
-interface LoggingConfig {
+import { type DeepPartial } from './configUtils.js';
+export interface LoggingConfig {
     devLogs: boolean;
     devNotifications: boolean;
     socketStatus: boolean;
@@ -32,7 +16,7 @@ interface LoggingConfig {
      */
     timestamps: boolean;
 }
-interface RateLimitingConfig {
+export interface RateLimitingConfig {
     /**
      * Global kill-switch for all rate limiting. When `false`, every
      * `checkRateLimit` call short-circuits to "allowed" and counters are not
@@ -94,7 +78,7 @@ interface RateLimitingConfig {
     auth: AuthRateLimitConfig;
 }
 /** Inputs handed to the {@link RateLimitingConfig.identity} callback. */
-interface RateLimitIdentityParams {
+export interface RateLimitIdentityParams {
     /** Resolved route name (`api/billing/getInvoice/v1`, `sync/...`). */
     routeName: string;
     /** Session user id when the request is authenticated, else null. */
@@ -105,13 +89,13 @@ interface RateLimitIdentityParams {
     transport: 'socket' | 'http';
 }
 /** Result of a {@link RateLimitingConfig.identity} callback. */
-interface RateLimitIdentity {
+export interface RateLimitIdentity {
     /** Which dimension the key is built from. */
     scope: 'user' | 'ip' | 'custom';
     /** The identity value (user id, ip, or a custom string). Never a raw token. */
     id: string;
 }
-interface AuthRateLimitConfig {
+export interface AuthRateLimitConfig {
     /** When false (default), no per-account lockout is applied. */
     enabled: boolean;
     /** Max failed attempts per account FROM ONE IP within `windowMs` before that
@@ -129,7 +113,7 @@ interface AuthRateLimitConfig {
     /** Rolling window in ms over which both caps are counted. Default 900000 (15 min). */
     windowMs: number;
 }
-interface SessionConfig {
+export interface SessionConfig {
     basedToken: boolean;
     expiryDays: number;
     /**
@@ -162,7 +146,7 @@ interface SessionConfig {
      */
     projectName: string;
 }
-interface AppConfig {
+export interface AppConfig {
     /**
      * Public URL of the app — used by OAuth callback redirects, transactional
      * email links (when `@luckystack/email` is installed), and any other
@@ -172,7 +156,7 @@ interface AppConfig {
      */
     publicUrl: string;
 }
-interface HttpStreamConfig {
+export interface HttpStreamConfig {
     /** Query-string flag clients pass to opt into SSE streaming. */
     queryParam: string;
     /** Value the query-string flag must have. */
@@ -180,13 +164,13 @@ interface HttpStreamConfig {
     /** Initial comment line written when an SSE stream opens (keeps proxies happy). */
     connectedComment: string;
 }
-interface SecurityHeadersConfig {
+export interface SecurityHeadersConfig {
     frameOptions: string;
     referrerPolicy: string;
     xssProtection: string;
     contentTypeOptions: string;
 }
-interface CorsConfig {
+export interface CorsConfig {
     allowedMethods: string;
     allowedHeaders: string;
     exposedHeaders: string;
@@ -224,7 +208,7 @@ interface CorsConfig {
      */
     allowOriginless?: boolean;
 }
-interface HttpConfig {
+export interface HttpConfig {
     sessionCookieName: string;
     sessionCookieSameSite: 'Strict' | 'Lax' | 'None';
     sessionCookiePath: string;
@@ -331,7 +315,7 @@ interface HttpConfig {
     securityHeaders: SecurityHeadersConfig;
     cors: CorsConfig;
 }
-interface HealthHashConfig {
+export interface HealthHashConfig {
     /**
      * - `'plain'` — unsalted `sha256(value)`; the pre-0.2.0 behavior, kept so an
      *   existing router boot handshake keeps comparing successfully. Opt in with
@@ -355,7 +339,7 @@ interface HealthHashConfig {
      */
     salt: string;
 }
-interface PasswordPolicyConfig {
+export interface PasswordPolicyConfig {
     /** Minimum total length. Default 8. */
     minLength: number;
     /** Maximum total length. Default 191 (DB column-friendly). */
@@ -381,7 +365,7 @@ interface PasswordPolicyConfig {
      */
     customValidator?: (password: string) => string | null;
 }
-interface AuthConfig {
+export interface AuthConfig {
     /**
      * Whether email+password (credentials) auth is enabled. When `true` (default)
      * `@luckystack/login/register` registers the credentials provider, so it shows
@@ -497,7 +481,7 @@ interface AuthConfig {
     /** Wrong-code attempts before a pending 2FA challenge is burned. DEFAULT 5. */
     twoFactorMaxAttempts: number;
 }
-interface OfflineQueueConfig {
+export interface OfflineQueueConfig {
     /** Hard cap on items per queue (api + sync are tracked separately). Default 200. */
     maxSize: number;
     /** Drop items older than this many ms when flushing/enqueuing. Default 1 hour. */
@@ -510,7 +494,7 @@ interface OfflineQueueConfig {
      */
     dropPolicy: 'drop-oldest' | 'drop-newest' | 'reject';
 }
-interface SyncStreamThrottleConfig {
+export interface SyncStreamThrottleConfig {
     /** Default `flushAtChars` for `createStreamThrottle({...})`. */
     flushAtChars: number;
     /** Default `flushEveryMs` for `createStreamThrottle({...})`. */
@@ -518,7 +502,7 @@ interface SyncStreamThrottleConfig {
     /** Default `field` (payload key) for emitted chunks. */
     field: string;
 }
-interface TransportConfig {
+export interface TransportConfig {
     /**
      * Transport used for typed API/sync invocations. Socket.io remains connected
      * in both modes for rooms, presence, reconnect state and realtime callbacks.
@@ -528,7 +512,7 @@ interface TransportConfig {
      */
     invocation: 'socket' | 'routed-http';
 }
-interface ApiConfig {
+export interface ApiConfig {
     /**
      * Default response timeout (ms) for `apiRequest`. After this elapses with no
      * response (e.g. server restart/crash between emit and reply) the request
@@ -538,7 +522,7 @@ interface ApiConfig {
      */
     requestTimeoutMs: number | false;
 }
-interface ValidationConfig {
+export interface ValidationConfig {
     /**
      * Whether runtime input validation runs in PRODUCTION (CORE-01).
      *
@@ -558,7 +542,7 @@ interface ValidationConfig {
      */
     runtimeMode: 'enforce' | 'off';
 }
-interface SyncConfig {
+export interface SyncConfig {
     streamThrottle: SyncStreamThrottleConfig;
     /**
      * Default response timeout (ms) for `syncRequest`'s acknowledgement. Same
@@ -605,7 +589,7 @@ interface SyncConfig {
      */
     flushPressure: SyncFlushPressureConfig;
 }
-interface SyncFlushPressureConfig {
+export interface SyncFlushPressureConfig {
     /** Max queued chunks before the stream applies backpressure (pauses). Default 1000. */
     highWaterMarkChunks: number;
     /** Resume emitting once the queue drains below this. Default 250. */
@@ -613,7 +597,7 @@ interface SyncFlushPressureConfig {
     /** Hard cap on bytes buffered for a single stream before dropping/erroring. Default 5_242_880 (5 MiB). */
     maxBufferedBytes: number;
 }
-interface SocketConfig {
+export interface SocketConfig {
     /**
      * Maximum payload size (bytes) for any single Socket.io message (whole-frame
      * buffer). DEFAULT 5 MiB (5 * 1024 * 1024). This is the SOCKET-transport cap; the
@@ -642,7 +626,7 @@ interface SocketConfig {
      */
     maxRoomsPerSession: number | false;
 }
-interface DevConfig {
+export interface DevConfig {
     /** Debounce window for hot-reload triggers. */
     hotReloadDebounceMs: number;
     /** Chokidar `awaitWriteFinish.stabilityThreshold`. */
@@ -658,7 +642,7 @@ interface DevConfig {
      */
     warnOnMissingInputType?: boolean;
 }
-interface PathsConfig {
+export interface PathsConfig {
     /** Frontend source root. */
     srcDir: string;
     /** Server-side source root. */
@@ -698,7 +682,7 @@ interface PathsConfig {
     /** Generated API docs JSON output path. */
     generatedApiDocs: string;
 }
-interface ProjectConfig {
+export interface ProjectConfig {
     app: AppConfig;
     logging: LoggingConfig;
     rateLimiting: RateLimitingConfig;
@@ -734,90 +718,9 @@ interface ProjectConfig {
      */
     oauthCallbackBase?: string;
 }
-type ProjectConfigInput = DeepPartial<ProjectConfig>;
-declare const DEFAULT_PROJECT_CONFIG: ProjectConfig;
-declare const registerProjectConfig: (config: ProjectConfigInput) => void;
-declare const getProjectConfig: () => ProjectConfig;
-declare const getProjectName: () => string;
-declare const isProjectConfigRegistered: () => boolean;
-
-/**
- * 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;
-type Jsonify<T> = {
-    [TKey in keyof T]: JsonifyValue<T[TKey]>;
-};
-interface SessionLocation {
-    pathName: string;
-    searchParams?: Record<string, string>;
-}
-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;
-}
-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 { type AppConfig as A, type BaseSessionLayout as B, type CorsConfig as C, type DeepPartial as D, type HealthHashConfig as H, type Jsonify as J, type LoggingConfig as L, type OfflineQueueConfig as O, type ProjectConfig as P, type RateLimitingConfig as R, type SessionConfig as S, type TransportConfig as T, type ValidationConfig as V, type AuthProps as a, type SessionLocation as b, type ApiConfig as c, type AuthConfig as d, type AuthRateLimitConfig as e, DEFAULT_PROJECT_CONFIG as f, getProjectConfig as g, type DevConfig as h, isProjectConfigRegistered as i, type HttpConfig as j, type HttpStreamConfig as k, type PasswordPolicyConfig as l, type PathsConfig as m, type ProjectConfigInput as n, type RateLimitIdentity as o, type RateLimitIdentityParams as p, type SecurityHeadersConfig as q, registerProjectConfig as r, type SocketConfig as s, type SyncConfig as t, type SyncFlushPressureConfig as u, type SyncStreamThrottleConfig as v, deepMerge as w, getProjectName as x, isPlainObject as y };
+export type ProjectConfigInput = DeepPartial<ProjectConfig>;
+export declare const DEFAULT_PROJECT_CONFIG: ProjectConfig;
+export declare const registerProjectConfig: (config: ProjectConfigInput) => void;
+export declare const getProjectConfig: () => ProjectConfig;
+export declare const getProjectName: () => string;
+export declare const isProjectConfigRegistered: () => boolean;

package/dist/rateLimiter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Rate Limiter
+ *
+ * The framework's rate-limit dispatch is pluggable via
+ * `registerRateLimitStrategy()`. The built-in `defaultRateLimitStrategy`
+ * implements in-memory counters with optional Redis backing for
+ * multi-instance deployments. Consumers can plug in alternative strategies
+ * (token-bucket, sliding-window, per-user tiers, edge-KV-backed, etc.) by
+ * implementing the `RateLimitStrategy` interface.
+ */
+export interface CheckRateLimitParams {
+    /** Unique key for rate limiting (e.g., "user:123:api:getData") */
+    key: string;
+    /** Maximum requests allowed in window */
+    limit: number;
+    /** Time window in milliseconds (default: 60_000 = 1 minute) */
+    windowMs?: number;
+}
+export interface RateLimitResult {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Seconds until rate limit resets */
+    resetIn: number;
+}
+/**
+ * Pluggable rate-limit backend. The framework calls these methods through
+ * the active strategy slot. Default implementation is memory + Redis.
+ * Replace via `registerRateLimitStrategy(...)` at boot.
+ */
+export interface RateLimitStrategy {
+    /** Human-readable identifier (used in logs/diagnostics). */
+    name: string;
+    /** Increment the counter for `key` and return whether the request is allowed. */
+    check(params: CheckRateLimitParams): Promise<RateLimitResult>;
+    /** Read current status without incrementing — useful for response headers. */
+    getStatus(key: string, limit: number): Promise<RateLimitResult>;
+    /** Reset the counter for a single key. */
+    clear(key: string): Promise<void>;
+    /** Reset all counters under this strategy's namespace. */
+    clearAll(): Promise<void>;
+}
+/**
+ * Built-in strategy: in-memory counters with optional Redis backing for
+ * multi-instance deployments. Mode is controlled by
+ * `projectConfig.rateLimiting.store` (`'memory'` or `'redis'`). When `redis`
+ * mode fails (e.g. Redis disconnect), the strategy silently degrades to
+ * in-memory and logs a one-shot warning.
+ */
+export declare const defaultRateLimitStrategy: RateLimitStrategy;
+/**
+ * Replace the active rate-limit backend. Pass a strategy that implements
+ * `RateLimitStrategy`. Common use cases:
+ *
+ *  - Token-bucket / sliding-window algorithms for smoother burst handling.
+ *  - Per-user tier limits (premium accounts get higher caps).
+ *  - Cloudflare-Workers-KV or upstash-rest-backed counters for edge.
+ *  - No-op strategy for test environments.
+ *
+ * Call this once at boot (typically from `luckystack/server/index.ts`)
+ * BEFORE the first request lands. Subsequent calls overwrite the previous
+ * registration (last-write-wins).
+ */
+export declare const registerRateLimitStrategy: (strategy: RateLimitStrategy) => void;
+/** Read the currently-active strategy (defaults to the built-in). */
+export declare const getRateLimitStrategy: () => RateLimitStrategy;
+/**
+ * Check if a request is allowed under rate limiting rules.
+ * Increments the counter for the key if allowed.
+ */
+export declare const checkRateLimit: (params: CheckRateLimitParams) => Promise<RateLimitResult>;
+/**
+ * Get current rate limit status without incrementing counter.
+ * Useful for rate limit headers in responses.
+ */
+export declare const getRateLimitStatus: (key: string, limit: number) => Promise<RateLimitResult>;
+/**
+ * Clear rate limit for a specific key.
+ * Useful for admin overrides or testing.
+ */
+export declare const clearRateLimit: (key: string) => Promise<void>;
+/**
+ * Clear all rate limits.
+ * Intended for testing or dev-mode server reset only.
+ * CORE-O8: throws in production to prevent accidental global counter wipe across
+ * all tenants. If you need a production-safe reset, pass a scoped key to
+ * `clearRateLimit` or implement a tenant-namespaced strategy.
+ */
+export declare const clearAllRateLimits: () => Promise<void>;

package/dist/react/AvatarProvider.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+export type AvatarStatus = 'avatar' | 'fallback';
+interface AvatarContextType {
+    avatarStatuses: Record<string, AvatarStatus>;
+    setAvatarStatus: (key: string, status: AvatarStatus) => void;
+}
+export declare const AvatarProvider: ({ children }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;
+export declare function useAvatarContext(): AvatarContextType;
+export {};

package/dist/react/Middleware.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+export default function Middleware({ children, denied, }: {
+    children: ReactNode;
+    /**
+     * Rendered instead of the page when middleware denies IN PLACE
+     * (`{ success: false, status }`) — the URL is kept. Pass a node, or a
+     * function to vary by status. Defaults to a minimal built-in view.
+     */
+    denied?: ReactNode | ((status: number) => ReactNode);
+}): import("react").JSX.Element | null;

package/dist/react/Router.d.ts

@@ -0,0 +1 @@
+export default function useRouter(): (path: string) => Promise<void>;

package/dist/react/TranslationProvider.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode, Dispatch, SetStateAction } from 'react';
+import { getActiveLanguage, getDefaultLocale, getRegisteredLocales } from '../localesRegistry.js';
+export type TranslationRecord = Record<string, unknown>;
+export declare function TranslationProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useTranslation(): TranslationRecord;
+export declare function useUpdateLanguage(): Dispatch<SetStateAction<string>>;
+export interface TranslateParam {
+    key: string;
+    value: string | number | boolean;
+}
+export declare function translate({ translationList, key, params }: {
+    translationList: TranslationRecord;
+    key: unknown;
+    params?: TranslateParam[];
+}): string;
+export declare const useTranslator: () => ({ key, params }: {
+    key: string;
+    params?: TranslateParam[];
+}) => string;
+export { getActiveLanguage, getDefaultLocale, getRegisteredLocales };

package/dist/react/notify.d.ts

@@ -0,0 +1,12 @@
+import { type TranslateParam } from './TranslationProvider.js';
+interface NotifyInput {
+    key: string;
+    params?: TranslateParam[];
+}
+declare const notify: {
+    success: (input: NotifyInput) => void;
+    error: (input: NotifyInput) => void;
+    info: (input: NotifyInput) => void;
+    warning: (input: NotifyInput) => void;
+};
+export default notify;

package/dist/react/sessionContext.d.ts

@@ -0,0 +1,31 @@
+import type { BaseSessionLayout } from '../sessionTypes.js';
+import { type ClientHookStopSignal } from '../clientHookBus.js';
+export interface SessionContextValue<TSession extends BaseSessionLayout = BaseSessionLayout> {
+    session: TSession | null;
+    sessionLoaded: boolean;
+}
+export declare const SessionContext: import("react").Context<SessionContextValue<BaseSessionLayout>>;
+export declare function useSession<TSession extends BaseSessionLayout = BaseSessionLayout>(): SessionContextValue<TSession>;
+export declare const setLatestSession: (session: BaseSessionLayout | null) => void;
+export declare const getCurrentSession: <TSession extends BaseSessionLayout = BaseSessionLayout>() => TSession | null;
+/**
+ * Vetoable entry point for committing a null → session transition (i.e. a
+ * fresh login or a page-load session restore). Dispatches the `preLogin`
+ * client hook to every registered handler in parallel; if any returns a
+ * stop signal, the transition is aborted and `{ committed: false, signal }`
+ * is returned. Otherwise, `setLatestSession(session)` runs synchronously
+ * (which fires `postLogin`) and `{ committed: true }` comes back.
+ *
+ * Consumer's `SessionProvider` should `await` this for non-null session
+ * commits and roll local React state back to `null` when a veto comes
+ * through, so the UI doesn't render a half-logged-in state.
+ */
+export type ProposeLoginResult = {
+    stopped: false;
+    committed: true;
+} | {
+    stopped: true;
+    signal: ClientHookStopSignal;
+    committed: false;
+};
+export declare const proposeLogin: (session: BaseSessionLayout) => Promise<ProposeLoginResult>;

package/dist/react/useTheme.d.ts

@@ -0,0 +1,5 @@
+export type Theme = 'light' | 'dark';
+export declare const useTheme: () => {
+    theme: Theme;
+    setTheme: (next: Theme) => void;
+};

package/dist/redactedLogKeys.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_REDACTED_LOG_KEYS: readonly string[];
+export declare const registerRedactedLogKeys: (keys: readonly string[]) => void;
+export declare const getRedactedLogKeys: () => readonly string[];
+export declare const isRedactedLogKey: (key: string) => boolean;
+export declare const resetRedactedLogKeysForTests: () => void;
+/** Placeholder substituted for a redacted value. */
+export declare const REDACTED_PLACEHOLDER = "[redacted]";
+export declare const DEPTH_TRUNCATED_PLACEHOLDER = "[truncated: max depth]";
+/**
+ * Recursively deep-copy `value`, replacing any property whose key matches the
+ * registered redacted-keys set (case-insensitive) with {@link REDACTED_PLACEHOLDER}
+ * (SYNC-17 defense-in-depth). Use it at raw log / `captureException` context
+ * sites so a token/password nested anywhere in a payload never lands verbatim in
+ * a logger sink or error-tracker breadcrumb.
+ *
+ * - Primitives pass through unchanged.
+ * - Arrays are mapped element-wise (array indices are never "keys", so an
+ *   element is only redacted by its own nested object keys).
+ * - Cycles / over-deep graphs are cut at {@link MAX_SANITIZE_DEPTH} with
+ *   {@link DEPTH_TRUNCATED_PLACEHOLDER}; the input is never mutated.
+ */
+export declare const sanitizeForLog: (value: unknown, depth?: number, _seen?: WeakSet<object>) => unknown;

package/dist/redis.d.ts

@@ -0,0 +1,15 @@
+import Redis from 'ioredis';
+import type { Redis as RedisClient } from 'ioredis';
+export declare const resetDefaultRedisClient: () => void;
+export declare const rebuildDefaultRedisClient: () => RedisClient;
+export interface RedisConnectionOptions {
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+}
+export declare const getRedisConnectionOptions: () => RedisConnectionOptions;
+export declare const registerStrayPrefixCommand: (...commands: string[]) => void;
+declare const redisProxy: Redis;
+export declare const redis: Redis;
+export default redisProxy;

package/dist/redisKeyFormatter.d.ts

@@ -0,0 +1,7 @@
+export type RedisKeyFormatter = (namespace: string, suffix: string) => string;
+export declare const defaultRedisKeyFormatter: RedisKeyFormatter;
+export declare const registerRedisKeyFormatter: (fn: RedisKeyFormatter) => void;
+export declare const getRedisKeyFormatter: () => RedisKeyFormatter;
+export declare const resetRedisKeyFormatterForTests: () => void;
+export declare const formatKey: (namespace: string, suffix?: string) => string;
+export declare const applyStrayKeyPrefix: (key: string) => string;

package/dist/resolveClientIp.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingHttpHeaders } from 'node:http';
+/**
+ * Stable sentinel returned when no usable client address could be resolved.
+ * Kept as a single exported constant so every rate-limit key-site funnels
+ * missing addresses into one deterministic bucket instead of ad-hoc literals.
+ */
+export declare const UNKNOWN_CLIENT_IP = "unknown";
+export interface ResolveClientIpParams {
+    /**
+     * The raw transport peer address — `socket.handshake.address` (Socket.io)
+     * or `req.socket.remoteAddress` (raw HTTP). May be `undefined`/`null` when
+     * the connection has already been torn down.
+     */
+    rawAddress: string | null | undefined;
+    /** Request / handshake headers. Only consulted when `trustProxy` is true. */
+    headers: IncomingHttpHeaders;
+    /**
+     * Whether a known reverse proxy sits in front of this server. DEFAULT false.
+     * When false the raw peer address is returned verbatim (only IPv4-mapped
+     * IPv6 canonicalization is applied), preserving historical behaviour. Only
+     * enable when a trusted proxy populates `X-Forwarded-For` / `X-Real-IP`,
+     * otherwise a client can spoof its own IP via those headers.
+     */
+    trustProxy?: boolean;
+    /**
+     * Number of proxy hops to skip from the RIGHT of `X-Forwarded-For` when
+     * `trustProxy` is on (CORE-O3). The rightmost entries are appended by your own
+     * trusted proxies; the resolved client IP is the entry that many hops in from
+     * the end. The leftmost hop is client-controlled and is never trusted. DEFAULT
+     * 1 (the immediate upstream proxy). Clamped to the list length so an over-large
+     * count falls back to the leftmost trusted hop rather than the spoofable entry.
+     */
+    trustedProxyHopCount?: number;
+}
+/**
+ * Whether a resolved client IP is a loopback / unresolved address — used by the
+ * api/sync transports to honour `rateLimiting.skipLoopbackInDev` (api F5/F11).
+ * Matches IPv4 loopback (`127.0.0.0/8`), IPv6 loopback (`::1`), the IPv4-mapped
+ * form (`::ffff:127.0.0.1`, already canonicalized away by {@link resolveClientIp}),
+ * and the {@link UNKNOWN_CLIENT_IP} sentinel. Pass an already-resolved IP.
+ */
+export declare const isLoopbackIp: (ip: string) => boolean;
+/**
+ * Derive the deterministic, non-reversible bucket component for a session
+ * token. The same token always yields the same value (bucket identity is
+ * preserved) while the raw token never appears in the returned string.
+ * Used by api AND sync rate-limit key builders — lives in core so both
+ * packages can share one implementation without a cross-package dependency.
+ */
+export declare const deriveTokenBucketId: (token: string) => string;
+export declare const resolveClientIp: ({ rawAddress, headers, trustProxy, trustedProxyHopCount }: ResolveClientIpParams) => string;

package/dist/responseNormalizer.d.ts

@@ -0,0 +1,33 @@
+export interface ErrorParam {
+    key: string;
+    value: string | number | boolean;
+}
+export interface ErrorResponseInput {
+    status?: unknown;
+    errorCode?: unknown;
+    errorParams?: unknown;
+    httpStatus?: unknown;
+}
+export interface NormalizedErrorResponse {
+    status: 'error';
+    message: string;
+    errorCode: string;
+    errorParams?: ErrorParam[];
+    httpStatus?: number;
+}
+export declare const INVALID_ERROR_RESPONSE_CODE = "error.invalidResponse";
+export declare const isErrorParamArray: (value: unknown) => value is ErrorParam[];
+export declare const normalizeErrorResponseCore: ({ response, fallbackHttpStatus, fallbackErrorCode, resolveMessage, }: {
+    response: ErrorResponseInput;
+    fallbackHttpStatus?: number;
+    fallbackErrorCode?: string;
+    resolveMessage?: (args: {
+        errorCode: string;
+        errorParams?: ErrorParam[];
+    }) => string;
+}) => NormalizedErrorResponse;
+export declare const defaultHttpStatusForResponse: ({ status, explicitHttpStatus, fallbackErrorStatus, }: {
+    status: 'success' | 'error';
+    explicitHttpStatus?: number;
+    fallbackErrorStatus?: number;
+}) => number;