@gzl10/nexus-backend 0.11.1 → 0.12.1

package/README.md

@@ -1,16 +1,14 @@
 # @gzl10/nexus-backend
 
-[![pipeline status](https://gitlab.gzl10.com/oss/nexus-backend/badges/main/pipeline.svg)](https://gitlab.gzl10.com/oss/nexus-backend/-/pipelines)
 [![npm version](https://img.shields.io/npm/v/@gzl10/nexus-backend.svg)](https://www.npmjs.com/package/@gzl10/nexus-backend)
 [![npm downloads](https://img.shields.io/npm/dm/@gzl10/nexus-backend.svg)](https://www.npmjs.com/package/@gzl10/nexus-backend)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 
 > **Warning**: This project is currently in testing/experimental phase. Use at your own risk.
 
-Backend as a Service (BaaS) with Express 5, Knex and CASL. Ready to use as an npm library.
+Backend as a Service (BaaS) with Express 5, Knex and CASL. Build modular, type-safe backends with authentication, authorization, and real-time features.
 
-**Repository**: [https://gitlab.gzl10.com/oss/nexus-backend](https://gitlab.gzl10.com/oss/nexus-backend)
+**Repository**: [https://gitlab.gzl10.com/oss/nexus](https://gitlab.gzl10.com/oss/nexus)
 
 ## Installation
 
@@ -18,187 +16,84 @@ Backend as a Service (BaaS) with Express 5, Knex and CASL. Ready to use as an np
 pnpm add @gzl10/nexus-backend
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { start, stop, nexusEvents } from '@gzl10/nexus-backend'
+import { start } from '@gzl10/nexus-backend'
 
-// Required auth secret (env)
-process.env.AUTH_SECRET = 'your-secret-at-least-32-characters'
-
-// Start server
-await start({
-  port: 3000,
-  database: { url: 'file:./data.db' }
-})
+start()
+```
 
-// Listen to CRUD events
-nexusEvents.on('db.users.created', ({ data }) => {
-  console.log('User created:', data)
-})
+## Features
 
-// Stop server
-await stop()
-```
+| Feature | Description |
+| ------- | ----------- |
+| Express 5 | Modern async error handling |
+| Knex ORM | SQLite, PostgreSQL, MySQL support |
+| CASL | Attribute-based access control |
+| JWT Auth | Access + refresh tokens with rotation |
+| Socket.IO | Real-time events and notifications |
+| Modular | Plugin architecture for extensions |
+| Storage | Local and S3-compatible storage |
+| Rate Limiting | Built-in rate limiting middleware |
 
 ## Configuration
 
-### Programmatic Options
-
-| Option         | Description         | Default                 |
-| -------------- | ------------------- | ----------------------- |
-| `port`         | Server port         | `3000`                  |
-| `host`         | Server host         | `0.0.0.0`               |
-| `homePath`     | Home path (redirect `/`) | `/ui`              |
-| `database.url` | Database URL             | `file:./dev.db`     |
-| `cors.origin`  | Allowed CORS origin       | `http://localhost:3001` |
-| `timezone`     | Server timezone           | `Europe/Madrid`     |
-| `admin.email`  | Admin email (seed)        | Optional            |
-| `admin.password` | Admin password (seed)   | Optional            |
-
-### Environment Variables (Core)
-
-| Variable         | Description                | Default                |
-| ---------------- | -------------------------- | ---------------------- |
-| `NODE_ENV`       | Environment                | `development`          |
-| `PORT`           | Server port                | `3000`                 |
-| `HOME_PATH`      | Home path (redirect `/`)   | `/ui`                  |
-| `CORS_ORIGIN`    | Allowed CORS origin        | `http://localhost:3001`|
-| `DATABASE_URL`   | Database URL               | `file:./dev.db`        |
-| `ADMIN_EMAIL`    | Admin email (seed)         | Optional               |
-| `ADMIN_PASSWORD` | Admin password (seed)      | Optional               |
-| `BACKEND_URL`    | Base URL for logs/CLI       | Optional               |
-| `TZ`             | Server timezone            | `Europe/Madrid`        |
-
-### Environment Variables (Auth)
-
-| Variable               | Description                    | Default   |
-| ---------------------- | ------------------------------ | --------- |
-| `AUTH_SECRET`          | JWT secret (min 32 chars)      | Required  |
-| `AUTH_ACCESS_EXPIRES`  | Access token expiration        | `15m`     |
-| `AUTH_REFRESH_EXPIRES` | Refresh token expiration       | `7d`      |
-
-### Supported Databases
-
-- **SQLite**: `file:./data.db`
-- **PostgreSQL**: `postgresql://user:pass@host:5432/db`
-- **MySQL**: `mysql://user:pass@host:3306/db`
-
-## API Endpoints
-
-- `POST /api/v1/auth/login` - Login
-- `POST /api/v1/auth/refresh` - Refresh token
-- `POST /api/v1/auth/logout` - Logout
-- `GET /api/v1/users` - List users
-- `GET /api/v1/users/roles` - List roles
-- `GET /api/v1/system/modules` - List modules
-- `GET /api/v1/storage/files` - List files
-- `GET /health` - Health check
-- `GET /api/openapi.json` - OpenAPI spec
-
-## Architecture
-
-```text
-┌──────────────────────────────────────────────────────────────────────────┐
-│                            NEXUS-BACKEND                                 │
-├──────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  ┌────────────────────────────────────────────────────────────────────┐  │
-│  │                            ENGINE                                  │  │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐ │  │
-│  │  │   Registry   │  │    Loader    │  │        Queries           │ │  │
-│  │  │  (modules &  │  │  (core mods) │  │  (getModules, getPlugins)│ │  │
-│  │  │   plugins)   │  │              │  │                          │ │  │
-│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘ │  │
-│  └────────────────────────────────────────────────────────────────────┘  │
-│                                    │                                     │
-│                                    ▼                                     │
-│  ┌────────────────────────────────────────────────────────────────────┐  │
-│  │                           RUNTIME                                  │  │
-│  │         EntityDefinition ──► Service ──► Controller ──► Routes     │  │
-│  │                                                                    │  │
-│  │  Para cada entity en module.definitions[]:                         │  │
-│  │  ┌─────────────────┐    ┌─────────────────┐    ┌────────────────┐ │  │
-│  │  │ CollectionService│    │EntityController │    │ GET /items     │ │  │
-│  │  │ SingleService    │ ──►│ (findAll,       │ ──►│ GET /items/:id │ │  │
-│  │  │ EventService     │    │  findById,      │    │ POST /items    │ │  │
-│  │  │ ActionService    │    │  create, ...)   │    │ PUT /items/:id │ │  │
-│  │  │ ...              │    │                 │    │ DELETE /...    │ │  │
-│  │  └─────────────────┘    └─────────────────┘    └────────────────┘ │  │
-│  └────────────────────────────────────────────────────────────────────┘  │
-│                                    ▲                                     │
-│         ┌──────────────────────────┼──────────────────────────┐          │
-│         │                          │                          │          │
-│  ┌──────┴───────┐          ┌───────┴───────┐          ┌───────┴───────┐  │
-│  │    MODULE    │          │    MODULE     │          │    PLUGIN     │  │
-│  │    (core)    │          │    (core)     │          │   (external)  │  │
-│  ├──────────────┤          ├───────────────┤          ├───────────────┤  │
-│  │ name: auth   │          │ name: users   │          │ name: cms     │  │
-│  │ definitions: │          │ definitions:  │          │ definitions:  │  │
-│  │  - tokens    │          │  - users      │          │  - posts      │  │
-│  │    (temp)    │          │    (collection│          │    (collection│  │
-│  │  - audit     │          │  - roles      │          │  - pages      │  │
-│  │    (event)   │          │    (collection│          │    (collection│  │
-│  └──────────────┘          └───────────────┘          └───────────────┘  │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
-```
+Create a `.env` file:
 
-### Entity Types
-
-| Type       | Operations        | Use Case                                      |
-| ---------- | ----------------- | --------------------------------------------- |
-| collection | CRUD              | Users, posts, products, orders                |
-| single     | GET, PUT          | App settings, site config, preferences        |
-| reference  | GET (read-only)   | Countries, currencies, status codes           |
-| event      | GET, POST         | Audit logs, activity history, notifications   |
-| action     | POST /execute     | Send email, process payment, generate report  |
-| temp       | CRUD + TTL        | Sessions, OTP codes, temporary tokens         |
-| config     | GET, PUT (scoped) | Module settings, feature flags per tenant     |
-| view       | GET (query)       | Dashboard stats, aggregated reports           |
-| computed   | GET (on-demand)   | Real-time metrics, calculated fields          |
-| external   | GET (adapter)     | Third-party APIs, external databases          |
-| virtual    | GET (combine)     | Unified search, merged data from sources      |
+```env
+PORT=3000
+CORS_ORIGIN=http://localhost:5173
+DATABASE_URL=file:./data/nexus.db
+JWT_SECRET=your-secret-key
+```
 
-## Development
+## CLI
 
 ```bash
-pnpm dev          # Server with hot reload
-pnpm build        # Production build
-pnpm typecheck    # Type check
-pnpm lint         # Linting
-pnpm db:migrate   # Run migrations
-pnpm db:seed      # Initial seed
-```
+# Start server
+npx nexus start
 
-## Testing
+# Run migrations
+npx nexus migrate
 
-```bash
-pnpm test              # Run all tests
-pnpm test:coverage     # Run tests with coverage
+# Seed database
+npx nexus seed
 ```
 
-### Coverage Summary
-
-| Metric     | Coverage |
-| ---------- | -------- |
-| Statements | 76%      |
-| Branches   | 65%      |
-| Functions  | 79%      |
-| Lines      | 77%      |
+## Exported Functions
 
-### Test Structure
+| Function | Description |
+| -------- | ----------- |
+| `start()` | Start the server |
+| `stop()` | Stop the server |
+| `createApp()` | Create Express app instance |
+| `registerModule()` | Register a custom module |
+| `registerPlugin()` | Register a plugin |
+| `defineAbilityFor()` | Create CASL abilities |
+| `getIO()` | Get Socket.IO instance |
 
-| Directory              | Description                      |
-| ---------------------- | -------------------------------- |
-| `test/runtime/`        | Unit tests for entity services   |
-| `test/runtime/routes/` | Integration tests with supertest |
+## Development
 
-All 11 entity types are tested (see [Entity Types](#entity-types)).
+```bash
+pnpm dev           # Start dev server with watch
+pnpm build         # Build for production
+pnpm start         # Start production server
+pnpm typecheck     # Type check
+pnpm lint          # Linting
+pnpm test          # Run tests
+pnpm test:coverage # Tests with coverage
+```
 
-## Support
+## Stack
 
-<a href="https://www.buymeacoffee.com/gzl10g" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+- **Express 5** - Web framework
+- **Knex** - SQL query builder
+- **CASL** - Authorization
+- **JWT** - Authentication
+- **Socket.IO** - Real-time
+- **Zod** - Validation
+- **Pino** - Logging
 
 ## License
 

package/package.json

@@ -1,22 +1,10 @@
 {
   "name": "@gzl10/nexus-backend",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Backend as a Service (BaaS) with Express 5, Knex and CASL",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "homepage": "https://www.gzl10.com",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.gzl10.com/oss/nexus-backend.git"
-  },
-  "bugs": {
-    "url": "https://gitlab.gzl10.com/oss/nexus-backend/-/issues"
-  },
-  "funding": {
-    "type": "buymeacoffee",
-    "url": "https://www.buymeacoffee.com/gzl10g"
-  },
   "bin": {
     "nexus": "./dist/cli.js"
   },
@@ -28,10 +16,23 @@
   },
   "files": [
     "dist",
-    "ui/dist",
     "public"
   ],
   "license": "MIT",
+  "author": "Gonzalo Díez <gonzalo@gzl10.com>",
+  "homepage": "https://gitlab.gzl10.com/oss/nexus",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.gzl10.com/oss/nexus.git",
+    "directory": "packages/backend"
+  },
+  "bugs": {
+    "url": "https://gitlab.gzl10.com/oss/nexus/-/issues"
+  },
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://www.buymeacoffee.com/gzl10g"
+  },
   "keywords": [
     "baas",
     "backend",
@@ -52,7 +53,6 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.962.0",
     "@casl/ability": "^6.7.5",
-    "@gzl10/nexus-sdk": "*",
     "@sentry/node": "^10.32.1",
     "bcryptjs": "^2.4.3",
     "better-sqlite3": "^11.0.0",
@@ -78,10 +78,10 @@
     "pino": "^10.1.0",
     "sharp": "^0.34.5",
     "socket.io": "^4.8.3",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@gzl10/nexus-sdk": "0.12.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
     "@types/bcryptjs": "^2.4.0",
     "@types/better-sqlite3": "^7.6.0",
     "@types/compression": "^1.7.0",
@@ -95,24 +95,19 @@
     "@types/nodemailer": "^7.0.4",
     "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^4.0.16",
-    "concurrently": "^9.2.1",
-    "cross-env": "^10.1.0",
-    "eslint": "^9.17.0",
     "pino-pretty": "^13.1.3",
     "supertest": "^7.1.4",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "typescript-eslint": "^8.51.0",
     "vitest": "^4.0.16"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "scripts": {
-    "dev": "concurrently -n backend,ui -c blue,green \"pnpm dev:backend\" \"pnpm dev:ui\"",
-    "dev:tunnel": "cross-env BACKEND_URL=https://nexus.tunnel.gzl10.com TRUST_PROXY=true concurrently -n backend,ui,tunnel -c blue,green,magenta \"pnpm dev:backend\" \"pnpm dev:ui\" \"frpc -c frpc.toml\"",
-    "dev:backend": "tsx watch src/index.ts",
-    "dev:ui": "pnpm --filter nexus-ui build:watch",
-    "build": "tsup && pnpm run build:ui",
-    "build:ui": "pnpm --filter nexus-ui build",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup",
     "start": "node dist/index.js",
     "db:migrate": "tsx src/db/migrate.ts",
     "db:seed": "tsx src/db/seed.ts",
@@ -121,8 +116,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "generate": "nexus-sdk generate",
-    "kill:dev": "pkill -9 -f 'tsx.*watch' || true",
-    "clean": "rm -rf node_modules pnpm-lock.yaml dist"
+    "clean": "rm -rf dist node_modules coverage"
   }
 }

package/dist/cli.d.ts

@@ -1 +0,0 @@
-#!/usr/bin/env node

package/dist/cli.js

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-
-// src/cli.ts
-import { existsSync } from "fs";
-import { Command } from "commander";
-import { consola } from "consola";
-if (existsSync(".env")) {
-  process.loadEnvFile(".env");
-}
-var program = new Command();
-program.name("nexus").description("Nexus Backend CLI").version("0.1.0");
-program.command("ui").description("Open UI in browser").option("-p, --port <port>", "Nexus backend port").action(async (options) => {
-  const port = parseInt(options.port || process.env["PORT"] || "3000", 10);
-  const baseUrl = (process.env["BACKEND_URL"] || `http://localhost:${port}`).replace(/\/$/, "");
-  const url = `${baseUrl}/ui`;
-  try {
-    const res = await fetch(`${baseUrl}/health`);
-    if (!res.ok) throw new Error();
-  } catch {
-    consola.error(`Nexus no est\xE1 corriendo en ${baseUrl}`);
-    consola.info("Inicia el servidor primero con: pnpm dev");
-    process.exit(1);
-  }
-  const { exec } = await import("child_process");
-  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  exec(`${cmd} ${url}`);
-  consola.success(`Abriendo: ${url}`);
-});
-program.parse();
-//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { existsSync } from 'fs'\nimport { Command } from 'commander'\nimport { consola } from 'consola'\n\n// Cargar .env si existe (Node 20+)\nif (existsSync('.env')) {\n  process.loadEnvFile('.env')\n}\n\nconst program = new Command()\n\nprogram\n  .name('nexus')\n  .description('Nexus Backend CLI')\n  .version('0.1.0')\n\nprogram\n  .command('ui')\n  .description('Open UI in browser')\n  .option('-p, --port <port>', 'Nexus backend port')\n  .action(async (options) => {\n    const port = parseInt(options.port || process.env['PORT'] || '3000', 10)\n    const baseUrl = (process.env['BACKEND_URL'] || `http://localhost:${port}`).replace(/\\/$/, '')\n    const url = `${baseUrl}/ui`\n\n    // Verificar que Nexus está corriendo\n    try {\n      const res = await fetch(`${baseUrl}/health`)\n      if (!res.ok) throw new Error()\n    } catch {\n      consola.error(`Nexus no está corriendo en ${baseUrl}`)\n      consola.info('Inicia el servidor primero con: pnpm dev')\n      process.exit(1)\n    }\n\n    // Abrir navegador\n    const { exec } = await import('child_process')\n    const cmd = process.platform === 'darwin' ? 'open'\n              : process.platform === 'win32' ? 'start'\n              : 'xdg-open'\n\n    exec(`${cmd} ${url}`)\n    consola.success(`Abriendo: ${url}`)\n  })\n\nprogram.parse()\n"],"mappings":";;;AACA,SAAS,kBAAkB;AAC3B,SAAS,eAAe;AACxB,SAAS,eAAe;AAGxB,IAAI,WAAW,MAAM,GAAG;AACtB,UAAQ,YAAY,MAAM;AAC5B;AAEA,IAAM,UAAU,IAAI,QAAQ;AAE5B,QACG,KAAK,OAAO,EACZ,YAAY,mBAAmB,EAC/B,QAAQ,OAAO;AAElB,QACG,QAAQ,IAAI,EACZ,YAAY,oBAAoB,EAChC,OAAO,qBAAqB,oBAAoB,EAChD,OAAO,OAAO,YAAY;AACzB,QAAM,OAAO,SAAS,QAAQ,QAAQ,QAAQ,IAAI,MAAM,KAAK,QAAQ,EAAE;AACvE,QAAM,WAAW,QAAQ,IAAI,aAAa,KAAK,oBAAoB,IAAI,IAAI,QAAQ,OAAO,EAAE;AAC5F,QAAM,MAAM,GAAG,OAAO;AAGtB,MAAI;AACF,UAAM,MAAM,MAAM,MAAM,GAAG,OAAO,SAAS;AAC3C,QAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM;AAAA,EAC/B,QAAQ;AACN,YAAQ,MAAM,iCAA8B,OAAO,EAAE;AACrD,YAAQ,KAAK,0CAA0C;AACvD,YAAQ,KAAK,CAAC;AAAA,EAChB;AAGA,QAAM,EAAE,KAAK,IAAI,MAAM,OAAO,eAAe;AAC7C,QAAM,MAAM,QAAQ,aAAa,WAAW,SAChC,QAAQ,aAAa,UAAU,UAC/B;AAEZ,OAAK,GAAG,GAAG,IAAI,GAAG,EAAE;AACpB,UAAQ,QAAQ,aAAa,GAAG,EAAE;AACpC,CAAC;AAEH,QAAQ,MAAM;","names":[]}