@gzl10/nexus-sdk 0.1.4

package/README.md

@@ -0,0 +1,116 @@
+# @gzl10/nexus-sdk
+
+TypeScript SDK for creating plugins and modules compatible with [Nexus Backend](https://gitlab.gzl10.com/oss/nexus-backend).
+
+Define module and plugin manifests with full type safety without depending on the full `@gzl10/nexus-backend` package.
+
+## Installation
+
+```bash
+npm install @gzl10/nexus-sdk
+# or
+pnpm add @gzl10/nexus-sdk
+```
+
+## Usage
+
+### Define a module
+
+```typescript
+import type { ModuleManifest } from '@gzl10/nexus-sdk'
+
+export const tasksModule: ModuleManifest = {
+  name: 'tasks',
+  code: 'TSK',
+  label: 'Tasks',
+  icon: 'mdi:checkbox-marked-outline',
+  description: 'Task management',
+
+  dependencies: ['users'],
+
+  migrate: async (ctx) => {
+    const { db, helpers } = ctx
+    const exists = await db.schema.hasTable('tasks')
+    if (!exists) {
+      await db.schema.createTable('tasks', (table) => {
+        table.string('id').primary()
+        table.string('title').notNullable()
+        table.text('description')
+        table.boolean('completed').defaultTo(false)
+        helpers.addTimestamps(table, db)
+      })
+    }
+  },
+
+  routes: (ctx) => {
+    const router = ctx.createRouter()
+
+    router.get('/', async (req, res) => {
+      const tasks = await ctx.db('tasks').select('*')
+      res.json(tasks)
+    })
+
+    return router
+  },
+
+  entities: [
+    {
+      name: 'tasks',
+      label: 'Tasks',
+      labelField: 'title',
+      listFields: { title: 'Title', completed: 'Completed' },
+      formFields: {
+        title: { label: 'Title', type: 'text', required: true },
+        description: { label: 'Description', type: 'textarea' },
+        completed: { label: 'Completed', type: 'checkbox' }
+      }
+    }
+  ]
+}
+```
+
+### Define a plugin (groups modules)
+
+```typescript
+import type { PluginManifest } from '@gzl10/nexus-sdk'
+import { tasksModule } from './modules/tasks'
+import { projectsModule } from './modules/projects'
+
+export const projectPlugin: PluginManifest = {
+  name: '@myorg/nexus-projects',
+  code: 'PRJ',
+  label: 'Projects',
+  icon: 'mdi:folder-outline',
+  category: 'content',
+  version: '1.0.0',
+  description: 'Project management plugin',
+  modules: [tasksModule, projectsModule]
+}
+```
+
+## Main Types
+
+| Type | Description |
+|------|-------------|
+| `ModuleManifest` | Defines a module: routes, migrations, seeds, CRUD entities |
+| `PluginManifest` | Groups modules under a plugin with shared metadata |
+| `ModuleContext` | Context injected by Nexus: `db`, `logger`, `helpers`, `events`, `mail` |
+| `ModuleEntity` | Declarative entity configuration for CRUD UI |
+| `FormField` | Form field configuration with validation |
+
+### ModuleContext
+
+The context provides access to:
+
+- `db` - Knex instance for queries
+- `logger` - Pino logger
+- `helpers` - Migration utilities (`addTimestamps`, `addColumnIfMissing`)
+- `createRouter()` - Express Router factory
+- `middleware` - Registered middlewares (includes `validate`)
+- `errors` - Error classes (`AppError`, `NotFoundError`, `UnauthorizedError`, etc.)
+- `events` - EventEmitter for inter-module communication
+- `mail` - Email sending service
+
+## License
+
+MIT © [Gonzalo Díez](https://www.gzl10.com)

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+import { Knex } from 'knex';
+import { RequestHandler, Router } from 'express';
+export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
+import { Logger } from 'pino';
+
+/**
+ * @gzl10/nexus-sdk
+ *
+ * SDK types for creating Nexus plugins and modules.
+ * Use this package to define plugin/module manifests without
+ * depending on the full @gzl10/nexus-backend package.
+ */
+
+/**
+ * Tipo de campo para formularios dinámicos
+ */
+type FormFieldType = 'text' | 'email' | 'password' | 'number' | 'textarea' | 'markdown' | 'select' | 'checkbox' | 'date' | 'datetime';
+/**
+ * JSON Schema para validación de campos (subset serializable)
+ */
+interface FieldValidation {
+    type?: 'string' | 'number' | 'integer' | 'boolean';
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid';
+    errorMessage?: string;
+}
+/**
+ * Configuración de un campo de formulario
+ */
+interface FormField {
+    label: string;
+    type: FormFieldType;
+    required?: boolean;
+    placeholder?: string;
+    createOnly?: boolean;
+    disabled?: boolean;
+    hidden?: boolean;
+    optionsEndpoint?: string;
+    optionValue?: string;
+    optionLabel?: string;
+    validation?: FieldValidation;
+}
+/**
+ * Tipo de visualización de lista
+ */
+type ListType = 'table' | 'list' | 'grid' | 'masonry';
+/**
+ * Configuración de una entidad/tabla del módulo para UI CRUD
+ */
+interface ModuleEntity {
+    name: string;
+    label: string;
+    listFields: Record<string, string>;
+    formFields?: Record<string, FormField>;
+    labelField: string;
+    routePrefix?: string;
+    editMode?: 'modal' | 'page';
+    listType?: ListType;
+}
+/**
+ * Requisitos para activar un módulo
+ */
+interface ModuleRequirements {
+    env?: string[];
+    modules?: string[];
+}
+/**
+ * Helpers para migraciones de base de datos
+ */
+interface MigrationHelpers {
+    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>;
+}
+/**
+ * Middlewares disponibles en el contexto
+ */
+interface ModuleMiddlewares {
+    validate: (schemas: {
+        body?: unknown;
+        query?: unknown;
+        params?: unknown;
+    }) => RequestHandler;
+    [key: string]: RequestHandler | ((...args: unknown[]) => RequestHandler) | undefined;
+}
+/**
+ * Contexto inyectado a los módulos
+ */
+interface ModuleContext {
+    db: Knex;
+    logger: Logger;
+    generateId: () => string;
+    dbType: 'sqlite' | 'postgresql' | 'mysql';
+    helpers: MigrationHelpers;
+    createRouter: () => Router;
+    middleware: ModuleMiddlewares;
+    registerMiddleware: (name: string, handler: RequestHandler) => void;
+    config: Record<string, unknown>;
+    errors: {
+        AppError: new (message: string, statusCode?: number) => Error;
+        NotFoundError: new (message: string) => Error;
+        UnauthorizedError: new (message: string) => Error;
+        ForbiddenError: new (message: string) => Error;
+        ConflictError: new (message: string) => Error;
+    };
+    abilities: Record<string, unknown>;
+    events: {
+        emit: (event: string, ...args: unknown[]) => boolean;
+        on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    };
+    mail: {
+        send: (options: {
+            to: string | string[];
+            subject: string;
+            html?: string;
+            text?: string;
+            template?: string;
+            data?: Record<string, unknown>;
+        }) => Promise<void>;
+    };
+}
+/**
+ * Manifest de un módulo Nexus
+ */
+interface ModuleManifest {
+    /** Identificador único del módulo (ej: 'users', 'posts') */
+    name: string;
+    /** Código único del módulo (ej: 'USR', 'PST'). Opcional si pertenece a un plugin */
+    code?: string;
+    /** Nombre para mostrar en UI. Opcional si pertenece a un plugin */
+    label?: string;
+    /** Icono del módulo (Iconify MDI: 'mdi:account-group') */
+    icon?: string;
+    /** Descripción del módulo */
+    description?: string;
+    /** Tipo de módulo */
+    type?: 'core' | 'plugin' | 'auth-plugin' | 'custom';
+    /** Dependencias de otros módulos */
+    dependencies?: string[];
+    /** Requisitos para activar el módulo */
+    required?: ModuleRequirements;
+    /** Función de migración de base de datos */
+    migrate?: (ctx: ModuleContext) => Promise<void>;
+    /** Función de seed de datos iniciales */
+    seed?: (ctx: ModuleContext) => Promise<void>;
+    /** Inicialización del módulo */
+    init?: (ctx: ModuleContext) => void;
+    /** Factory de rutas del módulo */
+    routes?: (ctx: ModuleContext) => Router;
+    /** Prefijo de rutas (default: /{name}) */
+    routePrefix?: string;
+    /** Subjects CASL que expone el módulo */
+    subjects?: string[];
+    /** Entidades/tablas del módulo con config CRUD para UI */
+    entities?: ModuleEntity[];
+}
+/**
+ * Categorías disponibles para plugins
+ */
+type PluginCategory = 'content' | 'data' | 'storage' | 'messaging' | 'jobs' | 'ai' | 'analytics' | 'integrations' | 'commerce';
+/**
+ * Manifest de un plugin Nexus
+ */
+interface PluginManifest {
+    /** Nombre del plugin (normalmente el nombre del paquete npm) */
+    name: string;
+    /** Código del plugin (3-4 chars UPPERCASE). Se hereda a todos los módulos */
+    code: string;
+    /** Etiqueta para mostrar en UI. Se hereda a los módulos si no la definen */
+    label: string;
+    /** Icono del plugin (Iconify MDI). Se hereda a los módulos si no lo definen */
+    icon?: string;
+    /** Categoría del plugin para agrupar en sidebar */
+    category?: PluginCategory;
+    /** Versión del plugin (semver) */
+    version: string;
+    /** Descripción del plugin */
+    description: string;
+    /** Módulos incluidos en el plugin */
+    modules: ModuleManifest[];
+}
+
+export type { FieldValidation, FormField, FormFieldType, ListType, MigrationHelpers, ModuleContext, ModuleEntity, ModuleManifest, ModuleMiddlewares, ModuleRequirements, PluginCategory, PluginManifest };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@gzl10/nexus-sdk",
+  "version": "0.1.4",
+  "description": "SDK types for creating Nexus plugins and modules",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nexus",
+    "backend",
+    "sdk",
+    "plugin",
+    "module"
+  ],
+  "author": "Gonzalo Díez <gonzalo@gzl10.com>",
+  "license": "MIT",
+  "homepage": "https://www.gzl10.com",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.gzl10.com/oss/nexus-sdk"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/gzl10"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.2",
+    "express": "^5.0.1",
+    "knex": "^3.1.0",
+    "pino": "^9.6.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "knex": "^3.1.0",
+    "express": "^5.0.1",
+    "pino": "^9.6.0"
+  },
+  "peerDependenciesMeta": {
+    "knex": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "pino": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  }
+}