@gzl10/nexus-sdk 0.1.9 → 0.1.11

package/README.md

@@ -17,7 +17,7 @@ pnpm add @gzl10/nexus-sdk
 ### Define a module
 
 ```typescript
-import type { ModuleManifest } from '@gzl10/nexus-sdk'
+import type { ModuleManifest, PluginAuthRequest } from '@gzl10/nexus-sdk'
 
 export const tasksModule: ModuleManifest = {
   name: 'tasks',
@@ -37,6 +37,7 @@ export const tasksModule: ModuleManifest = {
         table.string('title').notNullable()
         table.text('description')
         table.boolean('completed').defaultTo(false)
+        table.string('created_by').references('id').inTable('users')
         helpers.addTimestamps(table, db)
       })
     }
@@ -44,10 +45,19 @@ export const tasksModule: ModuleManifest = {
 
   routes: (ctx) => {
     const router = ctx.createRouter()
+    const { abilities, services } = ctx
+
+    router.get('/', async (req: PluginAuthRequest, res) => {
+      // Check permissions with CASL
+      abilities.ForbiddenError.from(req.ability).throwUnlessCan('read', 'tasks')
 
-    router.get('/', async (req, res) => {
       const tasks = await ctx.db('tasks').select('*')
-      res.json(tasks)
+
+      // Resolve user relations
+      const userIds = [...new Set(tasks.map(t => t.created_by).filter(Boolean))]
+      const users = await services.users?.findByIds(userIds) ?? []
+
+      res.json({ tasks, users })
     })
 
     return router
@@ -90,14 +100,35 @@ export const projectPlugin: PluginManifest = {
 
 ## Main Types
 
+### Manifests & Context
+
 | 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` |
+| `ModuleContext` | Context injected by Nexus: `db`, `logger`, `helpers`, `services`, `abilities` |
 | `ModuleEntity` | Declarative entity configuration for CRUD UI |
 | `FormField` | Form field configuration with validation |
 
+### Request & Auth
+
+| Type | Description |
+|------|-------------|
+| `AuthRequest<TUser, TAbility>` | Generic authenticated request |
+| `PluginAuthRequest` | Pre-typed `AuthRequest<BaseUser, AbilityLike>` for plugins |
+| `BaseUser` | User without password for relations |
+| `AbilityLike` | Generic CASL ability interface (`can`, `cannot`) |
+
+### Services & Utilities
+
+| Type | Description |
+|------|-------------|
+| `CoreServices` | Core services container (`users`, etc.) |
+| `UsersResolver` | User lookup service (`findById`, `findByIds`) |
+| `PaginationParams` | Pagination input (`page`, `limit`) |
+| `PaginatedResult<T>` | Paginated response with metadata |
+| `ValidationSchema` | Generic Zod-compatible schema interface |
+
 ### ModuleContext
 
 The context provides access to:
@@ -106,11 +137,20 @@ The context provides access to:
 - `logger` - Pino logger
 - `helpers` - Migration utilities (`addTimestamps`, `addColumnIfMissing`)
 - `createRouter()` - Express Router factory
-- `middleware` - Registered middlewares (includes `validate`)
+- `middleware.validate()` - Request validation with Zod schemas
 - `errors` - Error classes (`AppError`, `NotFoundError`, `UnauthorizedError`, etc.)
+- `abilities` - CASL helpers (`subject`, `ForbiddenError`)
+- `services` - Core services (`users.findById`, `users.findByIds`)
 - `events` - EventEmitter for inter-module communication
 - `mail` - Email sending service
 
+### Re-exported Types
+
+For convenience, the SDK re-exports commonly used types:
+
+- **Express:** `Request`, `Response`, `NextFunction`, `RequestHandler`, `Router`, `CookieOptions`
+- **Knex:** `Knex`, `KnexCreateTableBuilder`, `KnexAlterTableBuilder`, `KnexTransaction`
+
 ## License
 
 MIT © [Gonzalo Díez](https://www.gzl10.com)

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Knex } from 'knex';
+export { Knex } from 'knex';
 import { Request, RequestHandler, Router } from 'express';
 export { CookieOptions, NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import { Logger } from 'pino';
@@ -11,6 +12,9 @@ import { Logger } from 'pino';
  * depending on the full @gzl10/nexus-backend package.
  */
 
+type KnexCreateTableBuilder = Knex.CreateTableBuilder;
+type KnexAlterTableBuilder = Knex.AlterTableBuilder;
+type KnexTransaction = Knex.Transaction;
 /**
  * Request autenticado con usuario y abilities CASL
  * El backend especializa TUser y TAbility con tipos concretos
@@ -168,16 +172,27 @@ interface MigrationHelpers {
     addAuditFieldsIfMissing: (db: Knex, tableName: string) => Promise<void>;
     addColumnIfMissing: (db: Knex, tableName: string, columnName: string, columnBuilder: (table: Knex.AlterTableBuilder) => void) => Promise<boolean>;
 }
+/**
+ * Schema de validación genérico (compatible con Zod sin depender de él)
+ * Cualquier objeto con método parse() es válido
+ */
+interface ValidationSchema {
+    parse: (data: unknown) => unknown;
+}
+/**
+ * Opciones para el middleware de validación
+ */
+interface ValidateSchemas {
+    body?: ValidationSchema;
+    query?: ValidationSchema;
+    params?: ValidationSchema;
+}
 /**
  * Middlewares disponibles en el contexto
  */
 interface ModuleMiddlewares {
-    validate: (schemas: {
-        body?: unknown;
-        query?: unknown;
-        params?: unknown;
-    }) => RequestHandler;
-    [key: string]: RequestHandler | ((...args: unknown[]) => RequestHandler) | undefined;
+    validate: (schemas: ValidateSchemas) => RequestHandler;
+    [key: string]: RequestHandler | ((...args: any[]) => RequestHandler) | undefined;
 }
 /**
  * Contexto inyectado a los módulos
@@ -191,7 +206,7 @@ interface ModuleContext {
     createRouter: () => Router;
     middleware: ModuleMiddlewares;
     registerMiddleware: (name: string, handler: RequestHandler) => void;
-    config: Record<string, unknown>;
+    config: {};
     errors: {
         AppError: new (message: string, statusCode?: number) => Error;
         NotFoundError: new (message?: string) => Error;
@@ -278,4 +293,4 @@ interface PluginManifest {
     modules: ModuleManifest[];
 }
 
-export type { AbilityLike, AuthRequest, BaseUser, CoreServices, FieldValidation, ForbiddenErrorConstructor, ForbiddenErrorInstance, FormField, FormFieldType, ListType, MigrationHelpers, ModuleAbilities, ModuleContext, ModuleEntity, ModuleManifest, ModuleMiddlewares, ModuleRequirements, PaginatedResult, PaginationParams, PluginAuthRequest, PluginCategory, PluginManifest, UsersResolver };
+export type { AbilityLike, AuthRequest, BaseUser, CoreServices, FieldValidation, ForbiddenErrorConstructor, ForbiddenErrorInstance, FormField, FormFieldType, KnexAlterTableBuilder, KnexCreateTableBuilder, KnexTransaction, ListType, MigrationHelpers, ModuleAbilities, ModuleContext, ModuleEntity, ModuleManifest, ModuleMiddlewares, ModuleRequirements, PaginatedResult, PaginationParams, PluginAuthRequest, PluginCategory, PluginManifest, UsersResolver, ValidateSchemas, ValidationSchema };

package/package.json

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