@gzl10/nexus-sdk 0.8.1 → 0.10.0

package/dist/cli/index.js

@@ -150,6 +150,6 @@ New file: ${path}`));
 }
 
 // src/cli/index.ts
-var program = new Command2().name("nexus-sdk").description("Nexus SDK CLI - Code generation from EntityDefinitions").version("0.8.1");
+var program = new Command2().name("nexus-sdk").description("Nexus SDK CLI - Code generation from EntityDefinitions").version("0.10.0");
 program.addCommand(createGenerateCommand());
 program.parse();

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Knex } from 'knex';
 export { Knex } from 'knex';
-import { Request, Router, RequestHandler } from 'express';
+import { Request, Router, RequestHandler, Response } from 'express';
 export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import { Logger } from 'pino';
 
@@ -628,6 +628,8 @@ interface ContextHelpers {
     addTimestamps: (table: Knex.CreateTableBuilder, db: Knex) => void;
     addAuditFieldsIfMissing: (db: Knex, tableName: string) => Promise<void>;
     addColumnIfMissing: (db: Knex, tableName: string, columnName: string, columnBuilder: (table: Knex.AlterTableBuilder) => void) => Promise<boolean>;
+    getLibPath: () => string;
+    getProjectPath: () => string;
 }
 /**
  * Schema de validación genérico (compatible con Zod sin depender de él)
@@ -661,6 +663,255 @@ interface EventEmitterLike {
     once: (event: string, listener: (...args: unknown[]) => void) => this;
     onAny?: (listener: (event: string, ...args: unknown[]) => void) => this;
 }
+/**
+ * Reporter mínimo para errores (Sentry/GlitchTip, etc.)
+ */
+interface LoggerReporter {
+    captureException: (error: Error, context?: Record<string, unknown>) => void;
+}
+/**
+ * Query parameters for entity list operations
+ */
+interface EntityQuery {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    order?: 'asc' | 'desc';
+    search?: string;
+    filters?: Record<string, unknown>;
+}
+/**
+ * Interfaz base para sub-servicio de roles
+ * El backend extiende esto con tipos concretos
+ */
+interface BaseRolesService {
+    findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
+    findById(id: string): Promise<unknown>;
+    findByName(name: string): Promise<unknown | undefined>;
+    getPermissionsByRoleId(roleId: string): Promise<unknown[]>;
+    create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    delete(id: string): Promise<void>;
+    updatePermissions(id: string, permissions: unknown[], userId?: string): Promise<unknown>;
+}
+/**
+ * Interfaz base para servicio de usuarios
+ * El backend extiende esto con tipos concretos (UserWithRole, etc.)
+ */
+interface BaseUsersService {
+    findAll(query?: EntityQuery): Promise<PaginatedResult<unknown>>;
+    findById(id: string): Promise<unknown>;
+    findByIdWithRole(id: string): Promise<unknown | null>;
+    create(data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    update(id: string, data: Record<string, unknown>, userId?: string): Promise<unknown>;
+    delete(id: string): Promise<void>;
+    roles: BaseRolesService;
+}
+/**
+ * Opciones para envío de email
+ */
+interface SendMailOptions {
+    to: string | string[];
+    subject: string;
+    title?: string;
+    message?: string;
+    html?: string;
+    text?: string;
+    from?: string;
+    replyTo?: string;
+    actions?: Array<{
+        label: string;
+        url: string;
+    }>;
+    logoUrl?: string;
+    attachments?: Array<{
+        filename: string;
+        content: Buffer | string;
+        contentType?: string;
+    }>;
+}
+/**
+ * Resultado del envío de email
+ */
+interface SendMailResult {
+    messageId: string;
+    accepted: string[];
+    rejected: string[];
+}
+/**
+ * Interfaz base para servicio de email
+ */
+interface BaseMailService {
+    send(options: SendMailOptions): Promise<SendMailResult | null>;
+    verify(): Promise<boolean>;
+}
+/**
+ * Servicios core disponibles en ctx.services
+ * Los plugins pueden extender con servicios adicionales
+ */
+interface CoreServices {
+    logger?: LoggerReporter;
+    users?: BaseUsersService;
+    mail?: BaseMailService;
+    [key: string]: unknown;
+}
+/**
+ * Interfaz base para todos los servicios de entidades
+ */
+interface BaseEntityService<T = unknown> {
+    findAll(query?: EntityQuery): Promise<PaginatedResult<T>>;
+    findById(id: string): Promise<T | null>;
+    readonly definition: EntityDefinition;
+}
+/**
+ * Servicio para entidades Collection (CRUD completo)
+ */
+interface CollectionEntityService<T = unknown> extends BaseEntityService<T> {
+    create(data: Partial<T>, userId?: string): Promise<T>;
+    update(id: string, data: Partial<T>, userId?: string): Promise<T>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Servicio para entidades Temp (TTL auto-cleanup)
+ */
+interface TempEntityService<T = unknown> extends BaseEntityService<T> {
+    create(data: Partial<T>): Promise<T>;
+    update(id: string, data: Partial<T>, extendTtl?: boolean): Promise<T>;
+    delete(id: string): Promise<void>;
+    extendTtl(id: string, additionalSeconds?: number): Promise<T>;
+    cleanup(): Promise<number>;
+    getRemainingTtl(id: string): Promise<number | null>;
+    isValid(id: string): Promise<boolean>;
+}
+/**
+ * Servicio para entidades Event (append-only, immutable)
+ */
+interface EventEntityService<T = unknown> extends BaseEntityService<T> {
+    create(data: Partial<T>): Promise<T>;
+    append(data: Partial<T>): Promise<T>;
+    runRetentionCleanup(): Promise<number>;
+    findByDateRange(start: Date, end: Date, query?: EntityQuery): Promise<PaginatedResult<T>>;
+}
+/**
+ * Servicio para entidades Single (registro único, update/read)
+ */
+interface SingleEntityService<T = unknown> extends BaseEntityService<T> {
+    get(): Promise<T | null>;
+    update(data: Partial<T>, userId?: string): Promise<T>;
+}
+/**
+ * Servicio para entidades Config (configuración clave-valor)
+ */
+interface ConfigEntityService<T = unknown> extends BaseEntityService<T> {
+    get(key: string): Promise<T | null>;
+    set(key: string, value: unknown, userId?: string): Promise<T>;
+    getAll(): Promise<Record<string, unknown>>;
+}
+/**
+ * Servicio para entidades Reference (lectura con join automático)
+ */
+interface ReferenceEntityService<T = unknown> extends BaseEntityService<T> {
+}
+/**
+ * Servicio para entidades View (vista SQL, solo lectura)
+ */
+interface ViewEntityService<T = unknown> extends BaseEntityService<T> {
+}
+/**
+ * Servicio para entidades Computed (campos calculados, solo lectura)
+ */
+interface ComputedEntityService<T = unknown> extends BaseEntityService<T> {
+}
+/**
+ * Servicio para entidades External (datos de API externa)
+ */
+interface ExternalEntityService<T = unknown> extends BaseEntityService<T> {
+}
+/**
+ * Servicio para entidades Virtual (orquestación de múltiples fuentes)
+ */
+interface VirtualEntityService<T = unknown> extends BaseEntityService<T> {
+}
+/**
+ * Servicio para entidades Action (ejecutar acciones)
+ */
+interface ActionEntityService<T = unknown> {
+    execute(data: Partial<T>): Promise<unknown>;
+    readonly definition: EntityDefinition;
+}
+/**
+ * Hooks para personalizar comportamiento de servicios de entidad
+ * Permite a plugins añadir lógica sin necesitar herencia
+ */
+interface EntityServiceHooks<T = unknown> {
+    /**
+     * Ejecutado antes de crear un registro
+     * @param data Datos a insertar
+     * @returns Datos modificados
+     */
+    beforeCreate?: (data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
+    /**
+     * Ejecutado después de crear un registro
+     * @param record Registro creado
+     */
+    afterCreate?: (record: T) => Promise<void> | void;
+    /**
+     * Ejecutado antes de actualizar un registro
+     * @param id ID del registro
+     * @param data Datos a actualizar
+     * @returns Datos modificados
+     */
+    beforeUpdate?: (id: string, data: Partial<T>) => Promise<Partial<T>> | Partial<T>;
+    /**
+     * Ejecutado después de actualizar un registro
+     * @param record Registro actualizado
+     */
+    afterUpdate?: (record: T) => Promise<void> | void;
+    /**
+     * Ejecutado antes de eliminar un registro
+     * @param id ID del registro
+     */
+    beforeDelete?: (id: string) => Promise<void> | void;
+    /**
+     * Ejecutado después de eliminar un registro
+     * @param id ID eliminado
+     */
+    afterDelete?: (id: string) => Promise<void> | void;
+    /**
+     * Ejecutado después de obtener un registro por ID
+     * @param record Registro obtenido (o null)
+     * @returns Registro modificado
+     */
+    afterFindById?: (record: T | null) => Promise<T | null> | T | null;
+    /**
+     * Ejecutado después de obtener lista paginada
+     * @param result Resultado paginado
+     * @returns Resultado modificado
+     */
+    afterFindAll?: (result: PaginatedResult<T>) => Promise<PaginatedResult<T>> | PaginatedResult<T>;
+}
+/**
+ * Opciones para createEntityService
+ */
+interface CreateEntityServiceOptions<T = unknown> {
+    /** Hooks para personalizar comportamiento */
+    hooks?: EntityServiceHooks<T>;
+}
+/**
+ * Handler de entidad para Express
+ */
+type EntityHandler = (req: Request, res: Response) => Promise<void>;
+/**
+ * Controller de entidad con handlers CRUD
+ */
+interface EntityController {
+    list: EntityHandler;
+    get: EntityHandler;
+    create?: EntityHandler;
+    update?: EntityHandler;
+    delete?: EntityHandler;
+    execute?: EntityHandler;
+}
 /**
  * Contexto inyectado a los módulos
  */
@@ -686,7 +937,13 @@ interface ModuleContext {
     /** Sistema de eventos compatible con EventEmitter2 */
     events: EventEmitterLike;
     /** Servicios de módulos (inyectados por backend) */
-    services: Record<string, unknown>;
+    services: CoreServices;
+    /** Factory para crear servicios de entidades (detecta tipo automáticamente) */
+    createEntityService<T = unknown>(definition: EntityDefinition, options?: CreateEntityServiceOptions<T>): BaseEntityService<T>;
+    /** Factory para crear controller de entidad con CASL y validación */
+    createEntityController(service: BaseEntityService, definition: EntityDefinition): EntityController;
+    /** Factory para crear router de entidad con rutas CRUD */
+    createEntityRouter(controller: EntityController, definition: EntityDefinition): Router;
 }
 /**
  * Manifest de un módulo Nexus
@@ -749,4 +1006,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-export { type AbilityLike, type ActionEntityDefinition, type AuthRequest, type BaseUser, type CaslAction, type CollectionEntityDefinition, type ComputedEntityDefinition, type ConfigEntityDefinition, type ContextHelpers, type DbType, type EntityCaslConfig, type EntityDefinition, type EntityIndex, type EntityType, type EventEmitterLike, type EventEntityDefinition, type ExternalEntityDefinition, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, GENERATED_DIR, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntityDefinition, type RolePermission, type SingleEntityDefinition, type TempEntityDefinition, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type VirtualEntityDefinition, generateModel, generateModelsFile, generateReadOnlyModel, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };
+export { type AbilityLike, type ActionEntityDefinition, type ActionEntityService, type AuthRequest, type BaseEntityService, type BaseMailService, type BaseRolesService, type BaseUser, type BaseUsersService, type CaslAction, type CollectionEntityDefinition, type CollectionEntityService, type ComputedEntityDefinition, type ComputedEntityService, type ConfigEntityDefinition, type ConfigEntityService, type ContextHelpers, type CoreServices, type CreateEntityServiceOptions, type DbType, type EntityCaslConfig, type EntityController, type EntityDefinition, type EntityHandler, type EntityIndex, type EntityQuery, type EntityServiceHooks, type EntityType, type EventEmitterLike, type EventEntityDefinition, type EventEntityService, type ExternalEntityDefinition, type ExternalEntityService, type FieldCaslAccess, type FieldDbConfig, type FieldDefinition, type FieldMeta, type FieldOptions, type FieldRelation, type FieldStorageConfig, type FieldValidationConfig, type ForbiddenErrorConstructor, type ForbiddenErrorInstance, GENERATED_DIR, type InputType, type KnexAlterTableBuilder, type KnexCreateTableBuilder, type KnexTransaction, type LoggerReporter, type ModuleAbilities, type ModuleContext, type ModuleManifest, type ModuleMiddlewares, type ModuleRequirements, type NonPersistentEntityDefinition, type OwnershipCondition, type PaginatedResult, type PaginationParams, type PersistentEntityDefinition, type PluginAuthRequest, type PluginCategory, type PluginManifest, type ReferenceEntityDefinition, type ReferenceEntityService, type RolePermission, type SendMailOptions, type SendMailResult, type SingleEntityDefinition, type SingleEntityService, type TempEntityDefinition, type TempEntityService, type ValidateSchemas, type ValidationSchema, type ViewEntityDefinition, type ViewEntityService, type VirtualEntityDefinition, type VirtualEntityService, generateModel, generateModelsFile, generateReadOnlyModel, getEntityName, getEntitySubject, hasTable, isPersistentEntity, isSingletonEntity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gzl10/nexus-sdk",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "SDK types for creating Nexus plugins and modules",
   "type": "module",
   "main": "./dist/index.js",