@luckystack/core 0.10.2 → 0.11.0

package/dist/lease.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Acquire an exclusive lease named `name` for `ttlMs` milliseconds. Returns an
+ * opaque owner token on success, or `null` when another owner already holds it.
+ * `SET key token PX ttl NX` is atomic, so concurrent acquirers race safely.
+ * Keep the returned token to `renewLease` / `releaseLease`.
+ */
+export declare const acquireLease: (name: string, ttlMs: number) => Promise<string | null>;
+/**
+ * Extend a held lease by `ttlMs` (sliding ownership). Returns true when the
+ * supplied `token` still owns the lease and the TTL was applied, false
+ * otherwise (lost ownership, expired, or Redis error).
+ */
+export declare const renewLease: (name: string, token: string, ttlMs: number) => Promise<boolean>;
+/**
+ * Release a held lease. Owner-checked: only succeeds (returns true) when
+ * `token` is the current holder. Returns false on mismatch or Redis error.
+ */
+export declare const releaseLease: (name: string, token: string) => Promise<boolean>;

package/dist/localSocketEnumerationGuard.d.ts

@@ -0,0 +1,22 @@
+/** Thrown (outside production) when consumer code touches a per-instance socket map. */
+export declare class LocalSocketEnumerationError extends Error {
+    constructor(surface: string);
+}
+/**
+ * Structural subset of a Socket.io `Server` the guard needs. Typed this way so
+ * the real server AND a structural test double both satisfy it without a cast.
+ */
+export interface GuardableSocketServer {
+    sockets: {
+        adapter: object;
+        sockets: Map<string, unknown>;
+    };
+}
+/**
+ * Wrap a Socket.io server so that the per-instance surfaces
+ * (`sockets.adapter.rooms`, `sockets.adapter.sids`, enumerating `sockets.sockets`)
+ * throw {@link LocalSocketEnumerationError}. Everything else — `in()`, `to()`,
+ * `fetchSockets()`, `emit()`, `sockets.sockets.get(id)` — passes through
+ * unchanged. Identity of the wrapper is NOT stable across calls; callers cache it.
+ */
+export declare const guardLocalSocketEnumeration: <T extends GuardableSocketServer>(io: T) => T;

package/dist/localeReloader.d.ts

@@ -0,0 +1,3 @@
+export type LocaleReloader = () => void | Promise<void>;
+export declare const registerLocaleReloader: (reloader: LocaleReloader) => LocaleReloader;
+export declare const getLocaleReloader: () => LocaleReloader | null;

package/dist/localesRegistry.d.ts

@@ -0,0 +1,8 @@
+export type LocalesMap = Record<string, unknown>;
+export type LanguageSource = () => string | null | undefined;
+export declare const registerLocales: (locales: LocalesMap) => void;
+export declare const getRegisteredLocales: () => LocalesMap;
+export declare const getDefaultLocale: () => string;
+export declare const registerLanguageSource: (fn: LanguageSource) => void;
+export declare const getActiveLanguage: () => string;
+export declare const getLocaleByCode: (code: string) => unknown;

package/dist/localizedNormalizer.d.ts

@@ -0,0 +1,50 @@
+import type { ErrorParam, ErrorResponseInput, NormalizedErrorResponse } from './responseNormalizer.js';
+export type LanguageCode = string;
+export interface TranslateInput {
+    language: LanguageCode;
+    key: string;
+    params?: ErrorParam[];
+}
+export type TranslateFunction = (input: TranslateInput) => string;
+export interface NormalizeErrorResponseInput {
+    response: ErrorResponseInput;
+    preferredLocale?: string | null;
+    userLanguage?: string | null;
+    fallbackHttpStatus?: number;
+}
+export interface LocalizedNormalizer {
+    normalizeErrorResponse: (input: NormalizeErrorResponseInput) => NormalizedErrorResponse;
+    resolveErrorMessage: (input: {
+        errorCode: string;
+        errorParams?: ErrorParam[];
+        preferredLocale?: string | null;
+        userLanguage?: string | null;
+    }) => string;
+    extractLanguageFromHeader: (header?: string | string[]) => LanguageCode | null;
+}
+export interface CreateLocalizedNormalizerInput {
+    translate: TranslateFunction;
+    /**
+     * Language the framework falls back to when the caller provides no
+     * language hints. Defaults to 'en'.
+     */
+    defaultLanguage?: LanguageCode;
+    /**
+     * Decide whether a given string is an acceptable language code. Defaults
+     * to accepting any non-empty short-form code (ISO 639-1 style). Projects
+     * that only support a closed set should pass a narrower predicate.
+     */
+    isSupportedLanguage?: (code: string) => boolean;
+}
+export declare const createLocalizedNormalizer: (input: CreateLocalizedNormalizerInput) => LocalizedNormalizer;
+export declare const registerLocalizedNormalizer: (normalizer: LocalizedNormalizer) => void;
+export declare const getLocalizedNormalizer: () => LocalizedNormalizer;
+export declare const isLocalizedNormalizerRegistered: () => boolean;
+export declare const normalizeErrorResponse: (input: NormalizeErrorResponseInput) => NormalizedErrorResponse;
+export declare const resolveErrorMessage: (input: {
+    errorCode: string;
+    errorParams?: ErrorParam[];
+    preferredLocale?: string | null;
+    userLanguage?: string | null;
+}) => string;
+export declare const extractLanguageFromHeader: (header?: string | string[]) => LanguageCode | null;

package/dist/loggerRegistry.d.ts

@@ -0,0 +1,12 @@
+export type LoggerContext = Record<string, unknown>;
+export 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;
+}
+export declare const createDevLogger: () => Logger;
+export declare const registerLogger: (logger: Logger) => void;
+export declare const getLogger: () => Logger;
+export declare const isLoggerRegistered: () => boolean;
+export declare const resetLoggerForTests: () => void;

package/dist/middlewareRegistry.d.ts

@@ -0,0 +1,45 @@
+import type { BaseSessionLayout } from './sessionTypes.js';
+export interface MiddlewareInput {
+    location: string;
+    searchParams: Record<string, string>;
+    session: BaseSessionLayout | null;
+}
+export type MiddlewareResult = {
+    success: true;
+    redirect?: undefined;
+    status?: undefined;
+} | {
+    success: false;
+    redirect: string;
+    status?: undefined;
+} | {
+    success: false;
+    redirect?: undefined;
+    status: number;
+} | undefined;
+/** Normalized decision derived from a {@link MiddlewareResult}. */
+export type MiddlewareOutcome = {
+    kind: 'allow';
+} | {
+    kind: 'redirect';
+    to: string;
+} | {
+    kind: 'deny';
+    status: number;
+} | {
+    kind: 'fallback';
+};
+export declare const resolveMiddlewareOutcome: (result: MiddlewareResult) => MiddlewareOutcome;
+export type MiddlewareHandler = (input: MiddlewareInput) => MiddlewareResult | Promise<MiddlewareResult>;
+export declare const registerMiddlewareHandler: (handler: MiddlewareHandler) => void;
+export declare const getMiddlewareHandler: () => MiddlewareHandler;
+export type PageMiddleware<TSession extends BaseSessionLayout = BaseSessionLayout> = (input: {
+    location: string;
+    searchParams: Record<string, string>;
+    session: TSession | null;
+}) => MiddlewareResult | Promise<MiddlewareResult>;
+export declare const registerPageMiddleware: (path: string, middleware: PageMiddleware) => void;
+export declare const getPageMiddleware: (path: string) => PageMiddleware | undefined;
+export declare const hasPageMiddleware: (path: string) => boolean;
+/** Test helper — drop every registered per-page middleware. */
+export declare const clearPageMiddlewaresForTests: () => void;

package/dist/notifier.d.ts

@@ -0,0 +1,17 @@
+export interface NotifyParam {
+    key: string;
+    value: string | number | boolean;
+}
+export interface NotifyInput {
+    key: string;
+    params?: NotifyParam[];
+}
+export interface Notifier {
+    success: (input: NotifyInput) => void;
+    error: (input: NotifyInput) => void;
+    info: (input: NotifyInput) => void;
+    warning: (input: NotifyInput) => void;
+}
+export declare const registerNotifier: (notifier: Notifier) => void;
+export declare const getNotifier: () => Notifier;
+export declare const notify: Notifier;

package/dist/offlineQueue.d.ts

@@ -0,0 +1,48 @@
+import { Socket } from "socket.io-client";
+/** Why a queued item was dropped (handed to its `onDrop` callback). */
+export 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;
+}
+export declare const isOnline: () => boolean;
+export declare const enqueueApiRequest: (item: ApiQueueItem) => boolean;
+export declare const enqueueSyncRequest: (item: SyncQueueItem) => boolean;
+export declare const removeApiQueueItem: (id: string) => void;
+export declare const removeSyncQueueItem: (id: string) => void;
+export declare const removeApiQueueItemsByKey: (key: string) => void;
+export declare const flushApiQueue: (canRun: () => boolean, socketInstance: Socket) => void;
+export declare const flushSyncQueue: (canRun: () => boolean, socketInstance: Socket) => void;
+export declare const getApiQueueSize: () => number;
+export declare const getSyncQueueSize: () => number;
+export {};

package/dist/oneTimeToken.d.ts

@@ -0,0 +1,43 @@
+/** Build the namespaced Redis key for a token's HASH (never the raw token). */
+declare const tokenKey: (namespace: string, token: string) => string;
+/**
+ * Handle returned by {@link issueOneTimeToken}. `token` is the RAW token to hand
+ * to the caller (embed in the emailed URL); call `store()` to persist its hash
+ * to Redis with the configured TTL. Persisting is a separate step so the caller
+ * can run veto logic (hooks, validation) between minting and committing without
+ * leaving an orphan Redis key.
+ */
+export interface OneTimeTokenHandle {
+    /** The raw, single-use token. Returned exactly once; never stored verbatim. */
+    token: string;
+    /** Persist `sha256(token)` -> `payload` in Redis with the issue TTL. */
+    store(): Promise<void>;
+}
+/**
+ * Mint a one-time token in `namespace` carrying `payload`, redeemable for `ttl`
+ * seconds. Returns the raw token plus a `store()` committer. The payload is
+ * serialised to a string (objects via JSON); on redemption it is returned as a
+ * string and the caller parses it (or use {@link consumeOneTimeTokenJson}).
+ *
+ * @param namespace Key namespace (e.g. `'-pwreset'`, `'-email-change'`) — routed
+ *   through `formatKey` so the active key formatter / project prefix applies.
+ * @param ttlSeconds Time-to-live in seconds for the stored hash.
+ * @param payload   Value bound to the token. A string is stored verbatim; any
+ *   other value is `JSON.stringify`-d.
+ */
+export declare const issueOneTimeToken: (namespace: string, ttlSeconds: number, payload: string | Record<string, unknown>) => OneTimeTokenHandle;
+/**
+ * Atomically validate + consume a one-time token from `namespace`. Returns the
+ * stored payload STRING on success (and deletes the entry, so it can never be
+ * reused), or `null` when the token is missing / expired / malformed / already
+ * consumed. A single `MULTI` `GET`+`DEL` guarantees at-most-once redemption.
+ */
+export declare const consumeOneTimeToken: (namespace: string, token: string) => Promise<string | null>;
+/**
+ * Convenience wrapper over {@link consumeOneTimeToken} that JSON-parses the
+ * stored payload into `T`. Returns `null` on miss OR on a malformed JSON
+ * payload. Use when the token was issued with an object payload.
+ */
+export declare const consumeOneTimeTokenJson: <T>(namespace: string, token: string) => Promise<T | null>;
+export declare const oneTimeTokenKey: typeof tokenKey;
+export {};

package/dist/pageRouteValidation.d.ts

@@ -0,0 +1,37 @@
+export 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[];
+}
+export declare const DEFAULT_PAGE_ROUTE_RULES: PageRouteRules;
+export 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)' }
+ */
+export declare const validatePagePath: (srcRelativePath: string, rules?: PageRouteRules) => PagePathValidationResult;

package/dist/paths.d.ts

@@ -0,0 +1,35 @@
+export declare const ROOT_DIR: string;
+export declare const getSrcDir: () => string;
+export declare const getServerDir: () => string;
+export declare const getSharedDir: () => string;
+export declare const getUploadsDir: () => string;
+export declare const getPublicDir: () => string;
+export declare const getServerFunctionDirs: () => string[];
+/**
+ * @deprecated Use `getServerFunctionDirs()` instead. Returns the first
+ * directory from the array, or `'functions'` resolved against the workspace
+ * root when no directories are configured.
+ */
+export declare const getServerFunctionsDir: () => string;
+export declare const getGeneratedSocketTypesPath: () => string;
+export declare const getGeneratedApiSchemasPath: () => string;
+export declare const getGeneratedApiDocsPath: () => string;
+export declare const SRC_DIR: string;
+/** @deprecated use `getServerDir()` instead. */
+export declare const SERVER_DIR: string;
+/** @deprecated use `getSharedDir()` instead. */
+export declare const SHARED_DIR: string;
+/** @deprecated use `getUploadsDir()` instead. */
+export declare const UPLOADS_DIR: string;
+/** @deprecated use `getPublicDir()` instead. */
+export declare const PUBLIC_DIR: string;
+/** @deprecated use `getServerFunctionsDir()` instead. */
+export declare const SERVER_FUNCTIONS_DIR: string;
+/** @deprecated use `getGeneratedSocketTypesPath()` instead. */
+export declare const GENERATED_SOCKET_TYPES_PATH: string;
+/** @deprecated use `getGeneratedApiSchemasPath()` instead. */
+export declare const GENERATED_API_SCHEMAS_PATH: string;
+/** @deprecated use `getGeneratedApiDocsPath()` instead. */
+export declare const GENERATED_API_DOCS_PATH: string;
+export declare const TSCONFIG_ALIAS_FILES: string[];
+export declare const resolveFromRoot: (...segments: string[]) => string;

package/dist/peerDeps.d.ts

@@ -0,0 +1,23 @@
+/** Minimal shape of a Node `require` with the `.resolve` member these guards use. */
+export interface PeerRequire {
+    (id: string): unknown;
+    resolve: (id: string) => string;
+}
+/**
+ * Assert that an optional peer package is installed, throwing a consistent,
+ * actionable error when it is not. Does NOT load the module — use `loadPeer`
+ * for that. Pass `requireFn` (a `createRequire(import.meta.url)` from the
+ * calling adapter) so resolution happens from the consumer's perspective.
+ *
+ * `hint` is appended to the standard "package X is not installed" sentence —
+ * e.g. `'Run `npm install resend`, or pick a different EmailSender adapter.'`.
+ */
+export declare const ensurePeerDepInstalled: (packageName: string, hint: string, requireFn?: PeerRequire) => void;
+/**
+ * Synchronously load an optional peer package, asserting it is installed
+ * first (so a missing dependency fails with the actionable `hint` rather than
+ * a raw `MODULE_NOT_FOUND`). Returns the module typed as `T`. Pass `requireFn`
+ * (built with `createRequire(import.meta.url)` at the call site) so resolution
+ * + load happen relative to the calling module.
+ */
+export declare const loadPeer: <T>(packageName: string, hint: string, requireFn?: PeerRequire) => T;

package/dist/portOverrideRegistry.d.ts

@@ -0,0 +1,3 @@
+export declare const registerPortOverride: (port: number | null) => void;
+export declare const getPortOverride: () => number | undefined;
+export declare const resetPortOverrideForTests: () => void;

package/dist/processUpload.d.ts

@@ -0,0 +1,44 @@
+export interface ProcessUploadInput {
+    /** User the upload is associated with. */
+    userId: string;
+    /** Content type from the source (e.g. parsed from a data URL prefix). */
+    contentType: string;
+    /** Raw upload bytes — used for `sizeBytes` and passed to the encoder. */
+    buffer: Buffer;
+    /** Identifier for the upload category. Defaults to `'avatar'`. */
+    uploadKind?: string;
+    /** Final file name written to disk (used in the `onUploadComplete` payload). */
+    fileName: string;
+    /**
+     * Project-supplied encode + write step. Receives the raw buffer, does
+     * whatever encoding/resizing the installer wants (sharp, ffmpeg, raw fs
+     * write, S3 upload, etc.), and returns the final byte size on disk —
+     * pass through `buffer.byteLength` if you don't have a meaningful
+     * post-encode size.
+     */
+    encodeAndSave: (buffer: Buffer) => Promise<number>;
+}
+export type ProcessUploadResult = {
+    status: 'success';
+    sizeBytes: number;
+} | {
+    status: 'rejected';
+    errorCode: string;
+} | {
+    status: 'error';
+    reason: string;
+    cause?: unknown;
+};
+/**
+ * Run a project-side upload through the framework's hook contract.
+ *
+ * Order of operations:
+ *   1. Dispatch `onUploadStart` — handlers may return a stop signal to reject
+ *      the upload (content moderation, virus scanner, quota check).
+ *   2. Run the project-supplied `encodeAndSave` callback (wrapped in tryCatch).
+ *   3. Dispatch `onUploadComplete` with the final `sizeBytes`.
+ *
+ * Returns one of three statuses so the caller can map to its own response
+ * envelope without inspecting hook internals.
+ */
+export declare const processUpload: (input: ProcessUploadInput) => Promise<ProcessUploadResult>;