@luckystack/core 0.10.2 → 0.12.0

package/dist/pageRouteValidation-B4Cmtfjv.d.ts

@@ -1,280 +0,0 @@
-import { Socket } from 'socket.io-client';
-
-declare function sleep(ms: number): Promise<void>;
-
-declare function tryCatchSync<T, P = void>(func: (values: P) => T, params?: P): [Error | null, T | null];
-
-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>;
-
-/** Why a queued item was dropped (handed to its `onDrop` callback). */
-type QueueDropReason = 'expired' | 'queue-full';
-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';
-    /**
-     * Optional callback invoked when THIS item is dropped (evicted for age or
-     * because the queue was full / rejected) instead of ever running (SYNC-09).
-     * The transport wires this to settle the pending `syncRequest`/`apiRequest`
-     * promise with an error envelope, so an evicted offline request resolves
-     * rather than hanging forever. Invoked at most once; failures are swallowed.
-     */
-    onDrop?: (reason: QueueDropReason) => void;
-}
-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';
-    /** See {@link ApiQueueItem.onDrop} (SYNC-09). */
-    onDrop?: (reason: QueueDropReason) => void;
-}
-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: (origin?: string) => 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;
-
-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;
-
-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.
- */
-declare const buildRoutedGetUrl: (path: string, data: unknown, extraParams?: Record<string, string>) => string;
-
-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 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-";
-};
-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;
-}
-
-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;
-
-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 { type ErrorResponseInput as $, type ApiMethodMap as A, isOnline as B, normalizeErrorResponseCore as C, DEFAULT_PAGE_ROUTE_RULES as D, notify as E, parseServiceRouteName as F, registerApiMethodMap as G, type HttpMethodLiteral as H, registerLogger as I, registerNotifier as J, removeApiQueueItem as K, type Logger as L, removeApiQueueItemsByKey as M, type Notifier as N, removeSyncQueueItem as O, type PagePathValidationResult as P, setSocket as Q, ROUTED_DATA_QUERY_KEY as R, type SOCKETSTATUS as S, sleep as T, socket as U, socketEventNames as V, type statusContent as W, tryCatchSync as X, validatePagePath as Y, waitForSocket as Z, type ErrorParam as _, type LoggerContext as a, type NormalizedErrorResponse as a0, INVALID_ERROR_RESPONSE_CODE as a1, type QueueDropReason as a2, type ServiceRouteParseError as a3, type ServiceRouteParseResult as a4, type ServiceRouteParseSuccess as a5, type TransportRouteParseError as a6, type TransportRouteParseResult as a7, type TransportRouteParseSuccess as a8, createDevLogger as a9, defaultHttpStatusForResponse as aa, isErrorParamArray as ab, isLoggerRegistered as ac, parseTransportRouteName as ad, resetLoggerForTests as ae, type NotifyInput as b, type NotifyParam as c, type PageRouteRules as d, buildApiResponseEventName as e, buildApiStreamEventName as f, buildGetJoinedRoomsResponseEventName as g, buildJoinRoomResponseEventName as h, buildLeaveRoomResponseEventName as i, buildRoutedGetUrl as j, buildSyncProgressEventName as k, buildSyncResponseEventName as l, clearCsrfToken as m, enqueueApiRequest as n, enqueueSyncRequest as o, flushApiQueue as p, flushSyncQueue as q, getApiQueueSize as r, getCsrfToken as s, getLogger as t, getNotifier as u, getRegisteredApiMethod as v, getSyncQueueSize as w, httpFetch as x, incrementResponseIndex as y, isApiMethodMapRegistered as z };