@luckystack/core 0.1.0

package/dist/pageRouteValidation-CxZJVwZh.d.ts

@@ -0,0 +1,665 @@
+import { Socket } from 'socket.io-client';
+
+declare function sleep(ms: number): Promise<void>;
+
+declare function tryCatch<T, P>(func: (values: P) => Promise<T> | T, params?: P, context?: Record<string, unknown>): Promise<[Error | null, T | null]>;
+
+interface LoggingConfig {
+    devLogs: boolean;
+    devNotifications: boolean;
+    socketStatus: boolean;
+    socketStartup: boolean;
+    stream: boolean;
+}
+interface RateLimitingConfig {
+    /**
+     * Global kill-switch for all rate limiting. When `false`, every
+     * `checkRateLimit` call short-circuits to "allowed" and counters are not
+     * touched. Useful for local dev, load tests, or trusted internal tooling.
+     * Defaults to `true`.
+     */
+    enabled: boolean;
+    store: 'memory' | 'redis';
+    redisKeyPrefix: string;
+    defaultApiLimit: number | false;
+    defaultIpLimit: number | false;
+    windowMs: number;
+    /** How often the in-memory store evicts expired entries. */
+    cleanupIntervalMs: number;
+}
+interface SessionConfig {
+    basedToken: boolean;
+    expiryDays: number;
+    /**
+     * @deprecated Use `perUser: 'multiple'` instead. Kept for backwards
+     * compatibility; when set, maps to `perUser: 'multiple'` with no concurrent
+     * cap. The framework emits a one-shot deprecation warning at boot when
+     * `allowMultiple` is explicitly set.
+     */
+    allowMultiple: boolean;
+    /**
+     * Whether multiple parallel logins per browser are permitted.
+     * `'single'` (default): one active login per browser; opening a second tab
+     *   and logging in elsewhere replaces the first. `'multiple'`: each tab/window
+     *   can hold its own session independently.
+     */
+    perBrowser: 'single' | 'multiple';
+    /**
+     * Whether a single user can hold multiple active sessions across devices.
+     * `'single'` (default): logging in on a new device kicks the previous one.
+     * `'multiple'`: device A and device B can both be logged in concurrently.
+     */
+    perUser: 'single' | 'multiple';
+    /**
+     * Optional cap on concurrent sessions when `perUser === 'multiple'`. Null
+     * = unlimited. When the cap is reached, the policy from `onConflict`
+     * decides whether the new login is accepted (kicking oldest) or rejected.
+     */
+    maxConcurrentPerUser: number | null;
+    /**
+     * What to do when a session limit is exceeded.
+     * `'revokeOld'` (default): kick the oldest session, accept the new login.
+     * `'rejectNew'`: refuse the new login, leave existing sessions intact.
+     */
+    onConflict: 'revokeOld' | 'rejectNew';
+    /**
+     * When `onConflict === 'revokeOld'`, whether to broadcast a short UI
+     * notification ("logged in elsewhere") to the kicked device before
+     * disconnecting it. Default true.
+     */
+    notifyOldDeviceOnRevoke: boolean;
+    /**
+     * Prefix used for Redis session/activeUsers keys (e.g. `${projectName}-session:<token>`).
+     * Falls back to `process.env.PROJECT_NAME` then this default at config build time.
+     */
+    projectName: string;
+}
+interface AppConfig {
+    /**
+     * Public URL of the app — used by OAuth callback redirects, transactional
+     * email links (when `@luckystack/email` is installed), and any other
+     * framework code that needs to render an absolute link to your app.
+     * Empty default — consumers should set this to the public origin of their
+     * deployment (e.g. `https://app.example.com`).
+     */
+    publicUrl: string;
+}
+interface HttpStreamConfig {
+    /** Query-string flag clients pass to opt into SSE streaming. */
+    queryParam: string;
+    /** Value the query-string flag must have. */
+    enabledValue: string;
+    /** Initial comment line written when an SSE stream opens (keeps proxies happy). */
+    connectedComment: string;
+}
+interface SecurityHeadersConfig {
+    frameOptions: string;
+    referrerPolicy: string;
+    xssProtection: string;
+    contentTypeOptions: string;
+}
+interface CorsConfig {
+    allowedMethods: string;
+    allowedHeaders: string;
+    exposedHeaders: string;
+    /** Send `Access-Control-Allow-Credentials: true`. */
+    credentials: boolean;
+    /**
+     * Origins permitted to make cross-origin requests. The framework always
+     * permits the `SERVER_IP:SERVER_PORT` it binds to. Set `allowLocalhost`
+     * to true to also accept any `localhost` origin (useful for dev).
+     * Origins are normalized (scheme + host + port) before comparison.
+     *
+     * Static list mode: pass a `string[]`. Origins are matched exactly.
+     * Dynamic mode: pass a synchronous function `(origin) => boolean` for
+     * per-tenant / per-time-window allow-listing. Async resolvers are NOT
+     * supported here because Socket.io's CORS check is synchronous; use a
+     * pre-computed in-memory cache that the function can read from.
+     */
+    allowedOrigins: string[] | ((origin: string) => boolean);
+    /**
+     * Accept any origin matching `localhost` (any port). Convenient for local
+     * development; should be `false` in production. Defaults to `false` so
+     * production deployments fail closed.
+     */
+    allowLocalhost: boolean;
+}
+interface HttpConfig {
+    sessionCookieName: string;
+    sessionCookieSameSite: 'Strict' | 'Lax' | 'None';
+    sessionCookiePath: string;
+    /** Maximum body size accepted on `/api/*` and `/sync/*` POSTs. */
+    requestBodyMaxBytes: number;
+    /** Path of the router boot-handshake endpoint. */
+    healthEndpoint: string;
+    /**
+     * Liveness endpoint. Always returns 200 if the process is up and
+     * responsive — does NOT check dependencies. Suitable for K8s `livenessProbe`.
+     */
+    liveEndpoint: string;
+    /**
+     * Readiness endpoint. Returns 200 only when Redis + Prisma are reachable
+     * AND boot UUID is set. Suitable for K8s `readinessProbe`.
+     */
+    readyEndpoint: string;
+    /** Path of the dev-only state-reset endpoint (gated by NODE_ENV + token). */
+    testResetEndpoint: string;
+    stream: HttpStreamConfig;
+    securityHeaders: SecurityHeadersConfig;
+    cors: CorsConfig;
+}
+interface PasswordPolicyConfig {
+    /** Minimum total length. Default 8. */
+    minLength: number;
+    /** Maximum total length. Default 191 (DB column-friendly). */
+    maxLength: number;
+    /** Require at least one uppercase letter (A-Z). Default false. */
+    requireUppercase: boolean;
+    /** Require at least one lowercase letter (a-z). Default false. */
+    requireLowercase: boolean;
+    /** Require at least one digit (0-9). Default false. */
+    requireNumber: boolean;
+    /** Require at least one non-alphanumeric character. Default false. */
+    requireSpecial: boolean;
+    /**
+     * Reject the 10k most common passwords (built-in list shipped with
+     * `@luckystack/login`). Default true. Set to false in tests or when
+     * onboarding from a legacy system that allowed weak passwords.
+     */
+    forbidCommon: boolean;
+    /**
+     * Optional consumer-supplied predicate. Return null when the password is
+     * acceptable, or a string describing why it isn't (the string is used as
+     * the i18n errorCode-style key surfaced to the client).
+     */
+    customValidator?: (password: string) => string | null;
+}
+interface AuthConfig {
+    /** TTL for OAuth state tokens stored in Redis. */
+    oauthStateTtlSeconds: number;
+    /**
+     * @deprecated Read `passwordPolicy.minLength`. Kept as a top-level field
+     * for older consumer code; new code should use the structured policy.
+     */
+    passwordMinLength: number;
+    /**
+     * @deprecated Read `passwordPolicy.maxLength`. Kept as a top-level field
+     * for older consumer code; new code should use the structured policy.
+     */
+    passwordMaxLength: number;
+    /** Full credentials password policy. Replaces the deprecated min/max-length pair. */
+    passwordPolicy: PasswordPolicyConfig;
+    /** Maximum email length for credentials auth. */
+    emailMaxLength: number;
+    /** Maximum display-name length for credentials auth. */
+    nameMaxLength: number;
+    /**
+     * bcrypt cost factor used when hashing passwords (registration, password
+     * change, password reset). Default 10 matches industry guidance for 2026
+     * hardware. Bump to 12 for higher-value accounts; 4 is acceptable for tests
+     * to keep them fast.
+     */
+    bcryptRounds: number;
+    /**
+     * `'per-provider'` (default) — same email via Google and GitHub creates
+     *   two separate User rows (current behavior, no schema change).
+     * `'unified'` — same email maps to a single User; subsequent sign-ins via
+     *   different providers link an Account row to the same User. Requires a
+     *   Prisma schema change documented in @luckystack/login's README.
+     */
+    providerAccountStrategy: 'per-provider' | 'unified';
+    /**
+     * `'framework'` — login package ships the /reset-password pages + APIs and
+     *   sends the reset email. Requires a registered email sender.
+     * `'custom'` — login exposes only the primitives
+     *   (`createPasswordResetToken`, `consumePasswordResetToken`,
+     *   `updatePasswordHash`); the consumer wires their own UI and emails.
+     * `'disabled'` (default) — no forgot-password feature; the link in
+     *   `LoginForm` does not render.
+     */
+    forgotPassword: 'framework' | 'custom' | 'disabled';
+    /** Reset-token TTL in seconds when `forgotPassword === 'framework'`. */
+    passwordResetTtlSeconds: number;
+    /**
+     * Brand/display name used in framework-mode password-reset emails (subject +
+     * greeting + footer). Falls back to `'LuckyStack'` if unset; consumers should
+     * override this to their own brand.
+     */
+    passwordResetBrand?: string;
+    /** Email-change confirmation-token TTL in seconds. Default 3600 (1 hour). */
+    emailChangeTtlSeconds: number;
+}
+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. */
+    maxAgeMs: number;
+    /**
+     * What to do when the queue is full:
+     * - 'drop-oldest' (default): evict the oldest item, append the new one.
+     * - 'drop-newest': reject the new item, keep the existing queue.
+     * - 'reject': do not enqueue; caller must handle the failure.
+     */
+    dropPolicy: 'drop-oldest' | 'drop-newest' | 'reject';
+}
+interface SyncStreamThrottleConfig {
+    /** Default `flushAtChars` for `createStreamThrottle({...})`. */
+    flushAtChars: number;
+    /** Default `flushEveryMs` for `createStreamThrottle({...})`. */
+    flushEveryMs: number | false;
+    /** Default `field` (payload key) for emitted chunks. */
+    field: string;
+}
+interface SyncConfig {
+    streamThrottle: SyncStreamThrottleConfig;
+    /**
+     * Yield to the event loop every N recipients during a broadcast fanout
+     * (`receiver: 'all'` or large rooms). Lower = more responsive, higher
+     * overhead. Default 100.
+     */
+    fanoutYieldEvery: number;
+    /** Milliseconds to sleep when yielding. Default 1ms. */
+    fanoutYieldMs: number;
+}
+interface SocketConfig {
+    /** Maximum payload size for any single Socket.io message (bytes). */
+    maxHttpBufferSize: number;
+    /** ms with no pong response before the server considers the client gone. */
+    pingTimeout: number;
+    /** ms between pings. */
+    pingInterval: number;
+}
+interface DevConfig {
+    /** Debounce window for hot-reload triggers. */
+    hotReloadDebounceMs: number;
+    /** Chokidar `awaitWriteFinish.stabilityThreshold`. */
+    watcherStabilityThresholdMs: number;
+    /** Chokidar `awaitWriteFinish.pollInterval`. */
+    watcherPollIntervalMs: number;
+    /**
+     * When true, log a warning the first time an api/sync route is invoked
+     * without an `inputType` (typically because generated types haven't been
+     * regenerated since the route was added). Helps catch routes that ship
+     * with no runtime input validation. Default false (silent), set to true
+     * in dev to surface missing types.
+     */
+    warnOnMissingInputType?: boolean;
+}
+interface PathsConfig {
+    /** Frontend source root. */
+    srcDir: string;
+    /** Server-side source root. */
+    serverDir: string;
+    /** Shared (universal) source root. */
+    sharedDir: string;
+    /** Where uploaded user assets (avatars, etc.) live. */
+    uploadsDir: string;
+    /** Public static assets served as-is. */
+    publicDir: string;
+    /**
+     * @deprecated Use `serverFunctionDirs` instead. Kept for backwards
+     * compatibility with projects that set the singular form before the
+     * function-injection system grew multi-directory support. When both are
+     * present, `serverFunctionDirs` wins.
+     */
+    serverFunctionsDir: string;
+    /**
+     * Server-side function modules consumed by API/sync handlers. The
+     * codegen and runtime walk every listed directory in order and merge the
+     * results into one `Functions` interface / object. Duplicate keys
+     * (same `<dirname>.<filename>.<export>` path produced by two roots)
+     * fail the build — `shared/` is canonical, so the conflict tells the
+     * consumer to delete the override.
+     *
+     * Default: `['functions', 'shared']`.
+     *
+     * Nested subdirectories work transparently — `functions/test/helper.ts`
+     * with `export const foo = …` shows up as
+     * `functions.test.helper.foo` on the injected `functions` parameter.
+     */
+    serverFunctionDirs: string[];
+    /** Generated socket types output path (relative to project root). */
+    generatedSocketTypes: string;
+    /** Generated API input schemas output path. */
+    generatedApiSchemas: string;
+    /** Generated API docs JSON output path. */
+    generatedApiDocs: string;
+}
+interface ProjectConfig {
+    app: AppConfig;
+    logging: LoggingConfig;
+    rateLimiting: RateLimitingConfig;
+    session: SessionConfig;
+    http: HttpConfig;
+    auth: AuthConfig;
+    socket: SocketConfig;
+    sync: SyncConfig;
+    offlineQueue: OfflineQueueConfig;
+    dev: DevConfig;
+    paths: PathsConfig;
+    defaultLanguage: string;
+    /** Default theme for new users / fallback when no session preference exists. */
+    defaultTheme?: 'light' | 'dark';
+    /** Enable per-room activity broadcasting (presence). */
+    socketActivityBroadcaster?: boolean;
+    /** Show the floating socket-status indicator badge from `@luckystack/presence/client`. */
+    socketStatusIndicator?: boolean;
+    /** Enable client → server `updateLocation` syncing. */
+    locationProviderEnabled?: boolean;
+    /** Where to redirect the user after a successful OAuth callback. */
+    loginRedirectUrl?: string;
+}
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object | undefined ? DeepPartial<NonNullable<T[K]>> : T[K];
+};
+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;
+
+interface NotifyParam {
+    key: string;
+    value: string | number | boolean;
+}
+interface NotifyInput {
+    key: string;
+    params?: NotifyParam[];
+}
+interface Notifier {
+    success: (input: NotifyInput) => void;
+    error: (input: NotifyInput) => void;
+    info: (input: NotifyInput) => void;
+    warning: (input: NotifyInput) => void;
+}
+declare const registerNotifier: (notifier: Notifier) => void;
+declare const getNotifier: () => Notifier;
+declare const notify: Notifier;
+
+declare let socket: Socket | null;
+declare const setSocket: (next: Socket | null) => void;
+declare const incrementResponseIndex: () => number;
+declare const waitForSocket: () => Promise<Socket | null>;
+
+interface ApiQueueItem {
+    id: string;
+    key: string;
+    run: (socketInstance: Socket) => void;
+    createdAt: number;
+    /**
+     * Per-request override of `projectConfig.offlineQueue.dropPolicy`. See
+     * `SyncQueueItem.dropPolicy` for details.
+     */
+    dropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+}
+interface SyncQueueItem {
+    id: string;
+    key: string;
+    run: (socketInstance: Socket) => void;
+    createdAt: number;
+    /**
+     * Per-request override of `projectConfig.offlineQueue.dropPolicy`. Lets a
+     * specific sync ("editor cursor move") pick `'drop-oldest'` while the app
+     * default stays `'reject'` for safer sends. When omitted, falls back to
+     * the global config.
+     */
+    dropPolicy?: 'drop-oldest' | 'drop-newest' | 'reject';
+}
+declare const isOnline: () => boolean;
+declare const enqueueApiRequest: (item: ApiQueueItem) => boolean;
+declare const enqueueSyncRequest: (item: SyncQueueItem) => boolean;
+declare const removeApiQueueItem: (id: string) => void;
+declare const removeSyncQueueItem: (id: string) => void;
+declare const removeApiQueueItemsByKey: (key: string) => void;
+declare const flushApiQueue: (canRun: () => boolean, socketInstance: Socket) => void;
+declare const flushSyncQueue: (canRun: () => boolean, socketInstance: Socket) => void;
+declare const getApiQueueSize: () => number;
+declare const getSyncQueueSize: () => number;
+
+interface ErrorParam {
+    key: string;
+    value: string | number | boolean;
+}
+interface ErrorResponseInput {
+    status?: unknown;
+    errorCode?: unknown;
+    errorParams?: unknown;
+    httpStatus?: unknown;
+}
+interface NormalizedErrorResponse {
+    status: 'error';
+    message: string;
+    errorCode: string;
+    errorParams?: ErrorParam[];
+    httpStatus?: number;
+}
+declare const INVALID_ERROR_RESPONSE_CODE = "error.invalidResponse";
+declare const isErrorParamArray: (value: unknown) => value is ErrorParam[];
+declare const normalizeErrorResponseCore: ({ response, fallbackHttpStatus, fallbackErrorCode, resolveMessage, }: {
+    response: ErrorResponseInput;
+    fallbackHttpStatus?: number;
+    fallbackErrorCode?: string;
+    resolveMessage?: (args: {
+        errorCode: string;
+        errorParams?: ErrorParam[];
+    }) => string;
+}) => NormalizedErrorResponse;
+declare const defaultHttpStatusForResponse: ({ status, explicitHttpStatus, fallbackErrorStatus, }: {
+    status: "success" | "error";
+    explicitHttpStatus?: number;
+    fallbackErrorStatus?: number;
+}) => number;
+
+/**
+ * Fetch (or return the cached) CSRF token for the active session. Returns
+ * null in token mode or when no session exists. Callers should attach the
+ * returned value as the `X-CSRF-Token` request header.
+ */
+declare const getCsrfToken: () => Promise<string | null>;
+/** Drop the cached token. Call this on logout or when a 403 csrfMismatch is seen. */
+declare const clearCsrfToken: () => void;
+/**
+ * Drop-in replacement for `fetch` that automatically attaches the framework's
+ * `X-CSRF-Token` and `X-Request-Id` headers to state-changing requests in
+ * cookie mode. Use this for any project-side HTTP call that hits a
+ * LuckyStack `/api/*`, `/sync/*`, or `/auth/api/*` endpoint.
+ *
+ * Behavior:
+ *   - GET / OPTIONS / HEAD: passes through without CSRF (read-only).
+ *   - Token mode: passes through without CSRF (immune by design).
+ *   - Cookie mode + state-changing method: lazily fetches `/auth/csrf` once,
+ *     caches, attaches as `x-csrf-token`. On a 403 `auth.csrfMismatch`
+ *     response, clears the cache and retries once.
+ *   - `credentials: 'include'` is forced unless the caller overrode it.
+ *
+ * @example
+ *   import { httpFetch } from '@luckystack/core/client';
+ *   const res = await httpFetch('/api/system/myRoute/v1', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ ... }),
+ *   });
+ */
+declare const httpFetch: typeof fetch;
+
+interface ServiceRouteParseSuccess {
+    status: 'success';
+    normalizedRouteName: string;
+    service: string;
+    routeName: string;
+}
+interface ServiceRouteParseError {
+    status: 'error';
+    reason: string;
+}
+type ServiceRouteParseResult = ServiceRouteParseSuccess | ServiceRouteParseError;
+interface TransportRouteParseSuccess {
+    status: 'success';
+    normalizedFullName: string;
+    version: string;
+    serviceRoute: ServiceRouteParseSuccess;
+}
+interface TransportRouteParseError {
+    status: 'error';
+    reason: string;
+}
+type TransportRouteParseResult = TransportRouteParseSuccess | TransportRouteParseError;
+declare const parseServiceRouteName: (value: string) => ServiceRouteParseResult;
+declare const parseTransportRouteName: ({ value, prefix, }: {
+    value: string;
+    prefix: "api" | "sync";
+}) => TransportRouteParseResult;
+
+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 userAfk: "userAfk";
+    readonly userBack: "userBack";
+    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-";
+};
+declare const buildApiResponseEventName: (responseIndex: number | string) => string;
+declare const buildApiStreamEventName: (responseIndex: number | string) => string;
+declare const buildSyncResponseEventName: (responseIndex: number | string) => string;
+declare const buildSyncProgressEventName: (responseIndex: number | string) => string;
+declare const buildJoinRoomResponseEventName: (responseIndex: number | string) => string;
+declare const buildLeaveRoomResponseEventName: (responseIndex: number | string) => string;
+declare const buildGetJoinedRoomsResponseEventName: (responseIndex: number | string) => string;
+
+type SOCKETSTATUS = "CONNECTED" | "DISCONNECTED" | "AFK" | "RECONNECTING" | "STARTUP";
+interface statusContent {
+    status: SOCKETSTATUS;
+    reconnectAttempt?: number;
+    endTime?: number;
+}
+
+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;
+    }[];
+}
+
+type LoggerContext = Record<string, unknown>;
+interface Logger {
+    debug: (message: string, context?: LoggerContext) => void;
+    info: (message: string, context?: LoggerContext) => void;
+    warn: (message: string, context?: LoggerContext) => void;
+    error: (message: string, error?: unknown, context?: LoggerContext) => void;
+}
+declare const createDevLogger: () => Logger;
+declare const registerLogger: (logger: Logger) => void;
+declare const getLogger: () => Logger;
+declare const isLoggerRegistered: () => boolean;
+declare const resetLoggerForTests: () => void;
+
+type HttpMethodLiteral = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type ApiMethodMap = Record<string, Record<string, Record<string, HttpMethodLiteral>>>;
+declare const registerApiMethodMap: (map: ApiMethodMap) => void;
+declare const getRegisteredApiMethod: (pagePath: string, apiName: string, version: string) => HttpMethodLiteral | undefined;
+declare const isApiMethodMapRegistered: () => boolean;
+
+interface PageRouteRules {
+    /**
+     * Single-character prefix that marks a folder as **invisible-parent** for
+     * page routing. Default: `'_'`.
+     */
+    privateFolderPrefix: string;
+    /**
+     * Folder names that are reserved for framework-internal use and may NEVER
+     * host a `page.tsx`, nested or otherwise. Scaffold + page-discovery emit
+     * a hard error when a page is placed inside one.
+     */
+    scaffoldIgnoredFolders: readonly string[];
+}
+declare const DEFAULT_PAGE_ROUTE_RULES: PageRouteRules;
+interface PagePathValidationResult {
+    /** `true` when the page file produces a routeable URL. */
+    valid: boolean;
+    /** Computed URL when `valid`. Always begins with `/`. `/` for root page. */
+    route?: string;
+    /** Human-readable explanation when `!valid`. */
+    reason?: string;
+}
+/**
+ * Validate a `page.tsx` file path relative to `src/`. Accepts both
+ * forward and back slashes, with or without a leading `./` or `/`.
+ * The filename **must** be `page.tsx` (or `page.jsx`); other filenames
+ * return `valid: false`.
+ *
+ * Examples (defaults):
+ *   admin/page.tsx              -> { valid: true, route: '/admin' }
+ *   _housing/renting/page.tsx   -> { valid: true, route: '/renting' }
+ *   _housing/page.tsx           -> { valid: false, reason: 'no URL segment left after stripping underscore folders' }
+ *   _api/something/page.tsx     -> { valid: false, reason: 'page.tsx cannot live inside reserved folder _api' }
+ *   page.tsx                    -> { valid: true, route: '/' }
+ *   some/route.tsx              -> { valid: false, reason: 'not a page file (expected page.tsx)' }
+ */
+declare const validatePagePath: (srcRelativePath: string, rules?: PageRouteRules) => PagePathValidationResult;
+
+export { setSocket as $, type ApiMethodMap as A, type BaseSessionLayout as B, getProjectConfig as C, DEFAULT_PAGE_ROUTE_RULES as D, getRegisteredApiMethod as E, getSyncQueueSize as F, httpFetch as G, type HttpMethodLiteral as H, incrementResponseIndex as I, isApiMethodMapRegistered as J, isOnline as K, type Logger as L, isProjectConfigRegistered as M, type Notifier as N, normalizeErrorResponseCore as O, type PagePathValidationResult as P, notify as Q, type RateLimitingConfig as R, type SOCKETSTATUS as S, parseServiceRouteName as T, registerApiMethodMap as U, registerLogger as V, registerNotifier as W, registerProjectConfig as X, removeApiQueueItem as Y, removeApiQueueItemsByKey as Z, removeSyncQueueItem as _, type AppConfig as a, sleep as a0, socket as a1, socketEventNames as a2, type statusContent as a3, tryCatch as a4, validatePagePath as a5, waitForSocket as a6, type ErrorParam as a7, type ErrorResponseInput as a8, type NormalizedErrorResponse as a9, parseTransportRouteName as aA, resetLoggerForTests as aB, type AuthConfig as aa, type CorsConfig as ab, DEFAULT_PROJECT_CONFIG as ac, type DevConfig as ad, type HttpConfig as ae, type HttpStreamConfig as af, INVALID_ERROR_RESPONSE_CODE as ag, type OfflineQueueConfig as ah, type PasswordPolicyConfig as ai, type PathsConfig as aj, type ProjectConfigInput as ak, type SecurityHeadersConfig as al, type ServiceRouteParseError as am, type ServiceRouteParseResult as an, type ServiceRouteParseSuccess as ao, type SocketConfig as ap, type SyncConfig as aq, type SyncStreamThrottleConfig as ar, type TransportRouteParseError as as, type TransportRouteParseResult as at, type TransportRouteParseSuccess as au, createDevLogger as av, defaultHttpStatusForResponse as aw, getProjectName as ax, isErrorParamArray as ay, isLoggerRegistered as az, type AuthProps as b, type LoggerContext as c, type LoggingConfig as d, type NotifyInput as e, type NotifyParam as f, type PageRouteRules as g, type ProjectConfig as h, type SessionConfig as i, type SessionLocation as j, buildApiResponseEventName as k, buildApiStreamEventName as l, buildGetJoinedRoomsResponseEventName as m, buildJoinRoomResponseEventName as n, buildLeaveRoomResponseEventName as o, buildSyncProgressEventName as p, buildSyncResponseEventName as q, clearCsrfToken as r, enqueueApiRequest as s, enqueueSyncRequest as t, flushApiQueue as u, flushSyncQueue as v, getApiQueueSize as w, getCsrfToken as x, getLogger as y, getNotifier as z };