feat: add permissions, DTOs, logger, filtering, Swagger, and fix email bug

Implements 6 production-readiness features across the plugin ecosystem:

1. Email bug fix: use emitAsync() for reliable async event handling,
   mark notifications as failed when queue is null
2. Filtering & sorting: add FilterableDto, ValidSortBy decorator,
   search support in paginate(), query DTOs for audit-log/notifications
3. DTOs & validation: proper class-validator DTOs for organizations,
   notifications, device tokens, preferences, and items
4. Logger module: new @bbv/nestjs-logger wrapping nestjs-pino with
   correlation IDs and pretty-print support
5. Permissions system: role field on User model, PermissionsGuard with
   wildcard matching, OrgMemberGuard for org-level authorization,
   JWT enriched with role
6. Swagger decorators: @apitags, @apioperation, @apiresponse,
   @ApiBearerAuth on all controllers and @ApiProperty on all DTOs

Author: JonatanSalas

apps/demo/package.json

@@ -26,7 +26,11 @@
     "@bbv/nestjs-pagination": "*",
     "@bbv/nestjs-prisma": "*",
     "@bbv/nestjs-response": "*",
+    "@bbv/nestjs-logger": "*",
     "@bbv/nestjs-storage": "*",
+    "nestjs-pino": "^4.0.0",
+    "pino-http": "^10.0.0",
+    "pino-pretty": "^11.0.0",
     "@nestjs/bullmq": "^10.2.0",
     "@nestjs/event-emitter": "^2.1.0",
     "@nestjs/common": "^10.0.0",

apps/demo/prisma/schema/auth.prisma

@@ -4,6 +4,7 @@ model User {
   passwordHash    String?
   emailVerified   Boolean   @default(false)
   avatarUrl       String?
+  role            String    @default("user")
   isActive        Boolean   @default(true)
   lastLoginAt     DateTime?
   createdAt       DateTime  @default(now())

apps/demo/src/app.controller.ts

@@ -1,12 +1,13 @@
 import { Controller, Get } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
 import { Public } from '@bbv/nestjs-auth';
 
 @ApiTags('Health')
 @Controller()
 export class AppController {
   @Public()
   @Get('health')
+  @ApiOperation({ summary: 'Health check' })
   health() {
     return {
       status: 'ok',

apps/demo/src/app.module.ts

@@ -3,11 +3,12 @@ import { APP_GUARD } from '@nestjs/core';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { EventEmitterModule } from '@nestjs/event-emitter';
 import { PrismaModule } from '@bbv/nestjs-prisma';
-import { AuthModule, JwtAuthGuard } from '@bbv/nestjs-auth';
+import { AuthModule, JwtAuthGuard, PermissionsGuard } from '@bbv/nestjs-auth';
 import { OtpModule } from '@bbv/nestjs-otp';
 import { StorageModule } from '@bbv/nestjs-storage';
 import { NotificationModule, AuthNotificationModule } from '@bbv/nestjs-notifications';
 import { AuditLogModule } from '@bbv/nestjs-audit-log';
+import { LoggerModule } from '@bbv/nestjs-logger';
 import { AppController } from './app.controller';
 import { ItemsModule } from './items/items.module';
 import * as path from 'path';
@@ -18,6 +19,10 @@ import * as path from 'path';
 
     EventEmitterModule.forRoot(),
 
+    LoggerModule.forRoot({
+      prettyPrint: process.env.NODE_ENV !== 'production',
+    }),
+
     PrismaModule.forRoot({ isGlobal: true }),
 
     AuthModule.forRootAsync({
@@ -53,6 +58,16 @@ import * as path from 'path';
               }
             : {}),
         },
+        permissions: {
+          rolePermissions: {
+            admin: ['*'],
+            owner: ['org:*', 'items:*', 'audit:*', 'notifications:*', 'storage:*'],
+            member: ['items:read', 'items:create', 'notifications:read', 'notifications:manage'],
+            user: ['items:read', 'items:create', 'notifications:read'],
+          },
+          superAdminRoles: ['admin'],
+        },
+        defaultAdminEmail: config.get('ADMIN_EMAIL'),
       }),
       inject: [ConfigService],
     }),
@@ -125,7 +140,14 @@ import * as path from 'path';
             },
           },
           inApp: { enabled: true },
-          sms: { enabled: false },
+          sms: {
+            enabled: true,
+            provider: 'log' as const,
+          },
+          push: {
+            enabled: true,
+            provider: 'log' as const,
+          },
         },
         features: {
           preferences: true,
@@ -170,6 +192,10 @@ import * as path from 'path';
       provide: APP_GUARD,
       useClass: JwtAuthGuard,
     },
+    {
+      provide: APP_GUARD,
+      useClass: PermissionsGuard,
+    },
   ],
   controllers: [AppController],
 })

apps/demo/src/items/dto/create-item.dto.ts

@@ -0,0 +1,14 @@
+import { IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateItemDto {
+  @ApiProperty({ description: 'Item name' })
+  @IsString()
+  @IsNotEmpty()
+  name!: string;
+
+  @ApiPropertyOptional({ description: 'Item description' })
+  @IsString()
+  @IsOptional()
+  description?: string;
+}

apps/demo/src/items/items.controller.ts

@@ -3,6 +3,7 @@ import { ApiTags, ApiBearerAuth } from '@nestjs/swagger';
 import { PaginationDto, ApiPaginatedResponse } from '@bbv/nestjs-pagination';
 import { CurrentUser, Public } from '@bbv/nestjs-auth';
 import { ItemsService } from './items.service';
+import { CreateItemDto } from './dto/create-item.dto';
 
 @ApiTags('Items')
 @ApiBearerAuth()
@@ -24,7 +25,7 @@ export class ItemsController {
 
   @Post()
   create(
-    @Body() body: { name: string; description?: string },
+    @Body() body: CreateItemDto,
     @CurrentUser('id') userId: string,
   ) {
     return this.itemsService.create({ ...body, createdBy: userId });

apps/demo/src/main.ts

@@ -1,11 +1,13 @@
 import { NestFactory, Reflector } from '@nestjs/core';
 import { ClassSerializerInterceptor, ValidationPipe } from '@nestjs/common';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { Logger } from 'nestjs-pino';
 import { AppModule } from './app.module';
 import { TransformInterceptor, HttpExceptionFilter } from '@bbv/nestjs-response';
 
 async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+  app.useLogger(app.get(Logger));
 
   app.useGlobalPipes(
     new ValidationPipe({