@gzl10/nexus-backend 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import http from 'node:http';
+import * as http from 'node:http';
+import http__default from 'node:http';
 import { Express, Request, Response, Router, NextFunction, RequestHandler } from 'express';
 export { Express } from 'express';
 import { AbilityBuilder, MongoAbility, RawRuleOf } from '@casl/ability';
 import * as _gzl10_nexus_sdk from '@gzl10/nexus-sdk';
-import { PluginManifest, ModuleManifest, EntityQuery, PaginatedResult, EntityDefinition, ModuleContext, CreateEntityServiceOptions, BaseEntityService as BaseEntityService$1, EntityServiceHooks, CollectionEntityDefinition, SingleEntityDefinition, ViewEntityDefinition, ExternalEntityDefinition, ComputedEntityDefinition, TreeEntityDefinition, DagEntityDefinition, EntityChangePayload, BridgeRule, ValidateSchemas, SSESender, SSEHelper } from '@gzl10/nexus-sdk';
+import { PluginManifest, ModuleManifest, LocaleConfig, SeedContext, EntityQuery, PaginatedResult, EntityDefinition, ModuleContext, CreateEntityServiceOptions, BaseEntityService as BaseEntityService$1, EntityServiceHooks, CollectionEntityDefinition, SingleEntityDefinition, ViewEntityDefinition, ExternalEntityDefinition, ComputedEntityDefinition, TreeEntityDefinition, DagEntityDefinition, EntityChangePayload, BridgeRule, ValidateSchemas, SSESender, SSEHelper } from '@gzl10/nexus-sdk';
 export { AuthRequest, AuthorizationParams, Category, ContextHelpers, CookieOptions, DomainFilterOptions, DomainFilterResult, EntityDefinition, EntityQuery, IdTokenClaims, ModuleAbilities, ModuleContext, ModuleManifest, ModuleMiddlewares, ModuleRequirements, NextFunction, OidcClient, OidcDiscoveryDocument, OidcState, OidcTokens, OidcUserInfo, PaginatedResult, PaginationParams, PluginManifest, Request, RequestHandler, Response, Router, SessionResult, StateManager, TokenExchangeParams, TokenValidationConfig, ValidateSchemas, assertAllowedDomain, checkAllowedDomain, createOidcClient, createStateManager, entityRoom, getOidcClient } from '@gzl10/nexus-sdk';
 import * as express_serve_static_core from 'express-serve-static-core';
 import * as knex from 'knex';
@@ -14,6 +15,8 @@ import pkg from 'eventemitter2';
 import { Server } from 'socket.io';
 import { Server as Server$1 } from 'http';
 import * as qs from 'qs';
+import { A as AppError } from './app-error-CKbYJQ9V.js';
+export { a as AppErrorParams, C as ConflictError, b as ErrorCode, E as ErrorCodes, F as ForbiddenError, N as NotFoundError, U as UnauthorizedError, c as ValidationDetail, V as ValidationError } from './app-error-CKbYJQ9V.js';
 
 /**
  * CASL action types (duplicated from core/abilities to avoid config/ → core/ dependency).
@@ -56,7 +59,9 @@ interface ServeSPAOptions {
  * serveSPA('/admin', '../admin/dist', { maxAge: '7d', immutable: true })
  * ```
  */
-type ServeSPAFunction = (endpoint: string, distPath: string, options?: ServeSPAOptions) => void;
+type ServeSPAFunction = (endpoint: string, distPath: string, options?: ServeSPAOptions & {
+    viteSrc?: string;
+}) => void | Promise<void>;
 /**
  * Configuration for a frontend SPA.
  *
@@ -89,6 +94,15 @@ interface SpaEntry extends ServeSPAOptions {
     path?: string;
     /** Origin URL for CORS allowlist. Required for external SPAs; optional for served SPAs with a custom domain. */
     origin?: string;
+    /**
+     * Path to frontend source directory (dev only).
+     * When set in development, mounts Vite dev server as middleware with HMR instead of serving static files.
+     * Ignored in production — uses `path` for static files.
+     * Requires `endpoint` to be set. Requires `vite` as a peer dependency.
+     *
+     * @example { endpoint: '/', viteSrc: '../ui', path: '../ui/dist' }
+     */
+    viteSrc?: string;
 }
 /**
  * Discovered plugins and modules.
@@ -110,6 +124,8 @@ interface NexusConfig {
      * Auto-discovered from src/modules/ + passed programmatically to start().
      */
     modules?: ModuleManifest[];
+    /** Supported locales. Default: DEFAULT_LOCALES (en + es) */
+    locales?: LocaleConfig[];
 }
 /**
  * Runtime options for `start()`.
@@ -147,10 +163,52 @@ interface StartOptions extends NexusConfig {
         [eventName: string]: ((data: any) => void | Promise<void>) | undefined;
     };
     /**
-     * Function to define additional CASL rules.
-     * Runs after loading permissions from the DB.
+     * Advanced CASL rules for cases not covered by `seed.roles.add({ permissions })`.
+     * Runs as step 3 in the ability factory (after entity definition permissions).
+     *
+     * **Prefer `onSeed` → `seed.roles.add({ permissions })` for simple role-based permissions.**
+     * Use `casl` only when you need:
+     * - Conditions: `can('update', 'Post', { authorId: user.id })`
+     * - Field-level: `can('read', 'User', ['name', 'email'])`
+     * - Denials: `cannot('delete', 'User')`
+     * - Dynamic logic based on user properties
+     *
+     * @example
+     * ```typescript
+     * casl: (user, { can, cannot }) => {
+     *   if ((user as any).roleNames?.includes('EDITOR')) {
+     *     can('update', 'Post', { authorId: (user as any).id })
+     *     cannot('delete', 'Post')
+     *   }
+     * }
+     * ```
      */
     casl?: CaslRulesFunction;
+    /**
+     * Callback executed after all module seeds have run.
+     * Receives a `SeedContext` with typed helpers — no direct DB access needed.
+     *
+     * - `seed.masters.register()` — lazy, flushed after callback completes
+     * - `seed.roles.add()` — eager, supports `permissions` for CASL assignment
+     * - `seed.users.add()` — eager, supports role assignment by name
+     * - `seed.plugin(name).entity(name).upsert()` — resolves table prefix automatically
+     * - `seed.raw()` — escape hatch for custom tables
+     *
+     * @example
+     * ```typescript
+     * onSeed: async (seed) => {
+     *   seed.masters.register('sources', [
+     *     { code: 'web', label: { en: 'Website', es: 'Sitio web' } }
+     *   ])
+     *   await seed.roles.add({
+     *     name: 'SALES',
+     *     permissions: { 'contacts': ['read', 'create', 'update'] }
+     *   })
+     *   await seed.users.add({ email: 'admin@acme.com', password: 'temp', roles: ['ADMIN'] })
+     * }
+     * ```
+     */
+    onSeed?: (seed: SeedContext) => void | Promise<void>;
     /**
      * Callback executed when the server is fully ready.
      * Runs after listen() and Socket.IO initialization.
@@ -198,9 +256,57 @@ interface ResolvedConfig {
     adminPassword?: string;
 }
 
-declare function start(config?: StartOptions): Promise<http.Server>;
+/**
+ * Starts the Nexus server.
+ *
+ * Lifecycle order:
+ * 1. Logger, DB, migrations
+ * 2. Module/plugin registration and seed
+ * 3. `onSeed` hook (SeedContext with typed helpers)
+ * 4. `beforeRoutes` hook → module routes → `afterRoutes` hook
+ * 5. HTTP listen + Socket.IO
+ * 6. `onReady` hook
+ *
+ * @param config - Optional startup configuration (plugins, modules, lifecycle hooks, SPAs)
+ * @returns The underlying `http.Server` instance
+ * @throws If the server is already running (call `stop()` first)
+ *
+ * @example
+ * ```typescript
+ * import { start } from '@gzl10/nexus-backend'
+ *
+ * const server = await start({
+ *   onSeed: async (seed) => {
+ *     await seed.roles.add({ name: 'SALES', permissions: { 'contacts': ['read', 'create'] } })
+ *   },
+ *   onReady: (_app, port) => console.log(`Ready on ${port}`)
+ * })
+ * ```
+ */
+declare function start(config?: StartOptions): Promise<http__default.Server>;
+/**
+ * Stops the Nexus server gracefully.
+ *
+ * Closes HTTP server, Socket.IO, database connections, and cleans up all state.
+ * Calls `beforeClose` hook if registered. Safe to call multiple times.
+ *
+ * @example
+ * ```typescript
+ * await stop() // server stopped, port freed
+ * ```
+ */
 declare function stop(): Promise<void>;
-declare function restart(config?: StartOptions): Promise<http.Server>;
+/**
+ * Restarts the Nexus server. Calls `stop()` then `start()`.
+ *
+ * If no config is provided, reuses the config from the previous `start()` call.
+ * Plugins, hooks, and SPAs are preserved across restarts.
+ *
+ * @param config - Optional new config. If omitted, reuses previous config.
+ * @returns The new `http.Server` instance
+ */
+declare function restart(config?: StartOptions): Promise<http__default.Server>;
+/** Returns `true` if the server is currently running. */
 declare function isRunning(): boolean;
 
 interface CreateAppOptions {
@@ -208,6 +314,8 @@ interface CreateAppOptions {
     afterRoutes?: (app: Express, serveSPA: ServeSPAFunction) => void | Promise<void>;
     /** Declarative SPA entries (served + CORS). Passed from StartOptions.spas. */
     spas?: SpaEntry[];
+    /** HTTP server for Vite HMR WebSocket (shared with Socket.IO) */
+    httpServer?: http.Server;
 }
 declare function createApp(options?: CreateAppOptions): Promise<express_serve_static_core.Express>;
 
@@ -2012,140 +2120,6 @@ declare function createBatchReporter(sender: SSESender): BatchReporter;
  */
 declare function createSSEHelper(): SSEHelper;
 
-/**
- * Error codes for i18n-friendly error handling.
- * Frontend translates these codes to localized messages.
- *
- * Format: CATEGORY_ACTION_REASON
- *
- * Categories: AUTH, USER, ROLE, VALIDATION, STORAGE, PERMISSION, RESOURCE, SYSTEM
- */
-declare const ErrorCodes: {
-    readonly AUTH_INVALID_CREDENTIALS: "AUTH_INVALID_CREDENTIALS";
-    readonly AUTH_TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED";
-    readonly AUTH_TOKEN_INVALID: "AUTH_TOKEN_INVALID";
-    readonly AUTH_TOKEN_REQUIRED: "AUTH_TOKEN_REQUIRED";
-    readonly AUTH_OTP_REQUIRED: "AUTH_OTP_REQUIRED";
-    readonly AUTH_OTP_INVALID: "AUTH_OTP_INVALID";
-    readonly AUTH_REFRESH_TOKEN_REQUIRED: "AUTH_REFRESH_TOKEN_REQUIRED";
-    readonly AUTH_REFRESH_TOKEN_INVALID: "AUTH_REFRESH_TOKEN_INVALID";
-    readonly AUTH_REFRESH_TOKEN_EXPIRED: "AUTH_REFRESH_TOKEN_EXPIRED";
-    readonly AUTH_SESSION_NOT_FOUND: "AUTH_SESSION_NOT_FOUND";
-    readonly AUTH_SESSION_SELF_REVOKE: "AUTH_SESSION_SELF_REVOKE";
-    readonly AUTH_VERIFICATION_CODE_INVALID: "AUTH_VERIFICATION_CODE_INVALID";
-    readonly AUTH_REGISTRATION_DISABLED: "AUTH_REGISTRATION_DISABLED";
-    readonly AUTH_AUTO_CREATE_DISABLED: "AUTH_AUTO_CREATE_DISABLED";
-    readonly USER_NOT_FOUND: "USER_NOT_FOUND";
-    readonly USER_EMAIL_EXISTS: "USER_EMAIL_EXISTS";
-    readonly USER_NOT_AUTHENTICATED: "USER_NOT_AUTHENTICATED";
-    readonly ROLE_NOT_FOUND: "ROLE_NOT_FOUND";
-    readonly ROLE_NAME_EXISTS: "ROLE_NAME_EXISTS";
-    readonly ROLE_SYSTEM_PROTECTED: "ROLE_SYSTEM_PROTECTED";
-    readonly ROLE_HAS_USERS: "ROLE_HAS_USERS";
-    readonly ROLE_DEFAULT_NOT_FOUND: "ROLE_DEFAULT_NOT_FOUND";
-    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
-    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-    readonly VALIDATION_FIELD_REQUIRED: "VALIDATION_FIELD_REQUIRED";
-    readonly VALIDATION_FIELD_INVALID: "VALIDATION_FIELD_INVALID";
-    readonly VALIDATION_JSON_MALFORMED: "VALIDATION_JSON_MALFORMED";
-    readonly STORAGE_FILE_NOT_FOUND: "STORAGE_FILE_NOT_FOUND";
-    readonly STORAGE_FILE_TOO_LARGE: "STORAGE_FILE_TOO_LARGE";
-    readonly STORAGE_FILE_TYPE_NOT_ALLOWED: "STORAGE_FILE_TYPE_NOT_ALLOWED";
-    readonly STORAGE_PAYLOAD_TOO_LARGE: "STORAGE_PAYLOAD_TOO_LARGE";
-    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
-    readonly RESOURCE_CONFLICT: "RESOURCE_CONFLICT";
-    readonly RESOURCE_CREATE_NOT_SUPPORTED: "RESOURCE_CREATE_NOT_SUPPORTED";
-    readonly RESOURCE_UPDATE_NOT_SUPPORTED: "RESOURCE_UPDATE_NOT_SUPPORTED";
-    readonly RESOURCE_DELETE_NOT_SUPPORTED: "RESOURCE_DELETE_NOT_SUPPORTED";
-    readonly MODULE_NOT_FOUND: "MODULE_NOT_FOUND";
-    readonly NOT_FOUND: "NOT_FOUND";
-    readonly AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED";
-    readonly DB_CONSTRAINT_UNIQUE: "DB_CONSTRAINT_UNIQUE";
-    readonly DB_CONSTRAINT_FK: "DB_CONSTRAINT_FK";
-    readonly DB_CONNECTION_ERROR: "DB_CONNECTION_ERROR";
-    readonly SYSTEM_INTERNAL_ERROR: "SYSTEM_INTERNAL_ERROR";
-};
-type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
-
-/**
- * Parameters for creating an AppError with i18n support
- */
-interface AppErrorParams {
-    /** Error code for i18n translation (e.g., 'AUTH_INVALID_CREDENTIALS') */
-    code: ErrorCode;
-    /** Fallback message in English (used if frontend doesn't have translation) */
-    message?: string;
-    /** Interpolation values for the translated message (e.g., { resource: 'User' }) */
-    interpolation?: Record<string, string | number>;
-}
-/**
- * Base application error with i18n support.
- *
- * Can be created with:
- * - String message (legacy, backward compatible)
- * - AppErrorParams object (new, with code and interpolation)
- *
- * @example
- * // Legacy usage
- * throw new AppError('Something went wrong', 400)
- *
- * // New usage with i18n
- * throw new AppError({
- *   code: ErrorCodes.USER_NOT_FOUND,
- *   message: 'User not found',
- *   interpolation: { resource: 'User' }
- * }, 404)
- */
-declare class AppError extends Error {
-    readonly statusCode: number;
-    readonly code: ErrorCode;
-    readonly interpolation?: Record<string, string | number>;
-    readonly details?: unknown;
-    constructor(params: AppErrorParams | string, statusCode?: number, details?: unknown);
-}
-/**
- * Resource not found error (404)
- */
-declare class NotFoundError$1 extends AppError {
-    constructor(resource?: string);
-}
-/**
- * Authentication required error (401)
- */
-declare class UnauthorizedError$1 extends AppError {
-    constructor(codeOrMessage?: ErrorCode | string, message?: string);
-}
-/**
- * Access denied error (403)
- */
-declare class ForbiddenError$1 extends AppError {
-    constructor(codeOrMessage?: ErrorCode | string, message?: string);
-}
-/**
- * Resource conflict error (409)
- */
-declare class ConflictError$1 extends AppError {
-    constructor(codeOrMessage?: ErrorCode | string, message?: string);
-}
-/**
- * Standard validation error detail
- */
-interface ValidationDetail {
-    path: string;
-    message: string;
-    /** Error code for i18n translation */
-    code?: string;
-    /** Interpolation values */
-    interpolation?: Record<string, string | number>;
-}
-/**
- * Validation error with field-level details (400)
- */
-declare class ValidationError extends AppError {
-    readonly details: ValidationDetail[];
-    constructor(messageOrCode?: string | ErrorCode, details?: ValidationDetail[]);
-}
-
 /**
  * Query filter helpers.
  *
@@ -2576,4 +2550,4 @@ declare const core: {
 
 declare const version: string;
 
-export { type Actions, type AppAbility, AppError, type AppErrorParams, type AppManifest, type AuditEntry, type AuditLogRow, type AuditQuery, type AuditService, BaseEntityService, type BatchReporter, type CaslRulesFunction, CollectionService, ComputedService, SingleService as ConfigService, ConflictError$1 as ConflictError, DagService, type DbEventPayload, type EntityController, type EntityHandler, type EntityRuntime, type EntityService, type ErrorCode, ErrorCodes, CollectionService as EventService, ExternalService, ForbiddenError$1 as ForbiddenError, type JwtPayload, NEXUS_CLIENT_HEADER, NXBadRequestError, NXConflictError, NXForbiddenError, NXNotFoundError, NXUnauthorizedError, type NexusConfig, type NexusEventName, type NexusEventPayload, type NexusEvents, NotFoundError$1 as NotFoundError, NxSettingsService, type RateLimitOptions, CollectionService as ReferenceService, type RefreshToken, type ResolvedConfig, type Role, type RoleWithCounts, type ServeSPAFunction, type ServeSPAOptions, SingleService, type SpaEntry, type StartOptions, type SubjectRegistry, type SubjectStrings, type Subjects, CollectionService as TempService, type TokenPair, TreeService, UnauthorizedError$1 as UnauthorizedError, type User, type UserPresence, type UserWithRoles, type UserWithoutPassword, type ValidationDetail, ValidationError, ViewService, ComputedService as VirtualService, applyFilters, asyncHandler, authAdmin, authorize, checkAbility, closeSocketIO, core, createApp, createBatchReporter, createChildLogger, createEntityRuntime, createEntityService, createLogger, createModuleRouters, createModuleServices, createNexusClientMiddleware, createRateLimit, createSSEHelper, db, defineAbilityFor, destroyDb, discoverModules, discoverPlugins, e, eventBridge, extractModuleManifests, extractPluginManifest, findEnvFile, getConfig, getConnectedUsers, getCoreManifest, getCoreModules, getDatabaseType, getDb, getIO, getLibPath, getModule, getModules, getOrderedModules, getPlugin, getPlugins, getPrismaClient, getProjectPath, getRegisteredSubjects, getServiceKey, getUserManifest, getUserModules, getUserSocketCount, hasModule, hasPlugin, hasUserApp, initSocketIO, isEntityRoom, isModuleManifest, isPluginManifest, isRunning, isSocketIOInitialized, isUserConnected, isValidSubject, loadCoreModules, loadNexusConfig, logger, m, nexusEvents, nxFeatureService, packRules, parseEntityRoom, rateLimiter, registerModule, registerPlugin, requireNexusClient, restart, serializePrisma, start, stop, unpackRules, validate, version };
+export { type Actions, type AppAbility, AppError, type AppManifest, type AuditEntry, type AuditLogRow, type AuditQuery, type AuditService, BaseEntityService, type BatchReporter, type CaslRulesFunction, CollectionService, ComputedService, SingleService as ConfigService, DagService, type DbEventPayload, type EntityController, type EntityHandler, type EntityRuntime, type EntityService, CollectionService as EventService, ExternalService, type JwtPayload, NEXUS_CLIENT_HEADER, NXBadRequestError, NXConflictError, NXForbiddenError, NXNotFoundError, NXUnauthorizedError, type NexusConfig, type NexusEventName, type NexusEventPayload, type NexusEvents, NxSettingsService, type RateLimitOptions, CollectionService as ReferenceService, type RefreshToken, type ResolvedConfig, type Role, type RoleWithCounts, type ServeSPAFunction, type ServeSPAOptions, SingleService, type SpaEntry, type StartOptions, type SubjectRegistry, type SubjectStrings, type Subjects, CollectionService as TempService, type TokenPair, TreeService, type User, type UserPresence, type UserWithRoles, type UserWithoutPassword, ViewService, ComputedService as VirtualService, applyFilters, asyncHandler, authAdmin, authorize, checkAbility, closeSocketIO, core, createApp, createBatchReporter, createChildLogger, createEntityRuntime, createEntityService, createLogger, createModuleRouters, createModuleServices, createNexusClientMiddleware, createRateLimit, createSSEHelper, db, defineAbilityFor, destroyDb, discoverModules, discoverPlugins, e, eventBridge, extractModuleManifests, extractPluginManifest, findEnvFile, getConfig, getConnectedUsers, getCoreManifest, getCoreModules, getDatabaseType, getDb, getIO, getLibPath, getModule, getModules, getOrderedModules, getPlugin, getPlugins, getPrismaClient, getProjectPath, getRegisteredSubjects, getServiceKey, getUserManifest, getUserModules, getUserSocketCount, hasModule, hasPlugin, hasUserApp, initSocketIO, isEntityRoom, isModuleManifest, isPluginManifest, isRunning, isSocketIOInitialized, isUserConnected, isValidSubject, loadCoreModules, loadNexusConfig, logger, m, nexusEvents, nxFeatureService, packRules, parseEntityRoom, rateLimiter, registerModule, registerPlugin, requireNexusClient, restart, serializePrisma, start, stop, unpackRules, validate, version };