Skip to content

Commit e853f67

Browse files
JonatanSalasJonatanSalas
committed
docs: add comprehensive READMEs for all packages
Rewrite root README as an index-style overview with architecture diagram, package tables, and key patterns explanation. Create detailed package-level READMEs for all 7 packages (nestjs-prisma, nestjs-auth, nestjs-notifications, nestjs-storage, nestjs-audit-log, nestjs-pagination, nestjs-response) with consistent structure: overview, installation, configuration, API reference, and architecture diagrams. All code examples verified against source.
1 parent 2436fa1 commit e853f67

8 files changed

Lines changed: 1207 additions & 366 deletions

File tree

‎README.md‎

Lines changed: 126 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,116 @@
11
# @bbv/nestjs-plugins
22

3-
Composable NestJS plugin ecosystem by [BlackBox Vision](https://github.com/BlackBoxVision). Each module is a self-contained feature with its own Prisma schema, feature flags, and provider abstractions — like NestJS plugins that bring their own DB tables, config, and toggleable capabilities.
3+
Composable NestJS plugin ecosystem by [BlackBox Vision](https://github.com/BlackBoxVision).
44

5-
Build a production-ready NestJS API by composing modules: `AuthModule`, `NotificationModule`, `StorageModule` — each bringing its schema, migrations, and feature set.
5+
Each module is a self-contained feature -- own Prisma schema, feature flags, provider abstraction -- that you compose into a production-ready NestJS API.
6+
7+
## Architecture
8+
9+
```
10+
Your NestJS App
11+
|
12+
+-- PrismaModule (@bbv/nestjs-prisma) <-- foundation, all plugins depend on this
13+
| |
14+
| +-- AuthModule (@bbv/nestjs-auth) Tier 1 plugin
15+
| +-- NotificationModule (@bbv/nestjs-notifications) Tier 1 plugin
16+
| +-- StorageModule (@bbv/nestjs-storage) Tier 1 plugin
17+
| +-- AuditLogModule (@bbv/nestjs-audit-log) Tier 1 plugin
18+
|
19+
+-- PaginationDto, paginate() (@bbv/nestjs-pagination) Tier 2 utility
20+
+-- TransformInterceptor, Filter (@bbv/nestjs-response) Tier 2 utility
21+
```
622

723
## Packages
824

9-
### Tier 1 — Plugin Modules (own Prisma schema + feature flags)
25+
### Tier 1 -- Plugin Modules
26+
27+
Own Prisma schema, feature flags, and provider abstraction.
28+
29+
| Package | Description | Docs |
30+
|---------|-------------|------|
31+
| [`@bbv/nestjs-auth`](./packages/nestjs-auth) | Email/password, social login (Google/Apple/Microsoft), organizations, RBAC, sessions | [README](./packages/nestjs-auth/README.md) |
32+
| [`@bbv/nestjs-notifications`](./packages/nestjs-notifications) | Multi-channel notifications (email, in-app, SMS) with BullMQ queues, templates, preferences | [README](./packages/nestjs-notifications/README.md) |
33+
| [`@bbv/nestjs-storage`](./packages/nestjs-storage) | File upload with provider abstraction (S3, Firebase, DO Spaces, Local) and upload tracking | [README](./packages/nestjs-storage/README.md) |
34+
| [`@bbv/nestjs-audit-log`](./packages/nestjs-audit-log) | Automatic CRUD audit logging via Prisma middleware, `@Audited()` decorator, retention policies | [README](./packages/nestjs-audit-log/README.md) |
35+
36+
### Tier 2 -- Utility Packages
37+
38+
No module registration needed. Import and use directly.
39+
40+
| Package | Description | Docs |
41+
|---------|-------------|------|
42+
| [`@bbv/nestjs-prisma`](./packages/nestjs-prisma) | Prisma lifecycle management, soft-delete middleware, `createMockPrismaService()` for testing | [README](./packages/nestjs-prisma/README.md) |
43+
| [`@bbv/nestjs-pagination`](./packages/nestjs-pagination) | `PaginationDto`, `paginate()` helper, `@ApiPaginatedResponse()` Swagger decorator | [README](./packages/nestjs-pagination/README.md) |
44+
| [`@bbv/nestjs-response`](./packages/nestjs-response) | `ApiResponse` wrapper, `TransformInterceptor`, `HttpExceptionFilter` | [README](./packages/nestjs-response/README.md) |
45+
46+
## How It Works
47+
48+
### Feature Flags
49+
50+
Every plugin module accepts a `features` config to toggle capabilities. Disabled features don't register routes, don't consume resources, and throw if called directly.
51+
52+
```typescript
53+
AuthModule.forRootAsync({
54+
useFactory: () => ({
55+
jwt: { secret: 'my-secret' },
56+
features: {
57+
emailPassword: true, // POST /auth/register, POST /auth/login
58+
google: false, // Google OAuth routes not registered
59+
organizations: true, // Full /organizations CRUD
60+
sessionManagement: false, // Session endpoints not registered
61+
},
62+
}),
63+
})
64+
```
1065

11-
| Package | Description | Version |
12-
|---------|-------------|---------|
13-
| [`@bbv/nestjs-auth`](./packages/nestjs-auth) | Authentication, social login, organizations, RBAC | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-auth.svg)](https://www.npmjs.com/package/@bbv/nestjs-auth) |
14-
| [`@bbv/nestjs-notifications`](./packages/nestjs-notifications) | Multi-channel notifications (email, in-app, SMS) | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-notifications.svg)](https://www.npmjs.com/package/@bbv/nestjs-notifications) |
15-
| [`@bbv/nestjs-storage`](./packages/nestjs-storage) | File storage with provider abstraction (S3, Firebase, DO Spaces, Local) | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-storage.svg)](https://www.npmjs.com/package/@bbv/nestjs-storage) |
16-
| [`@bbv/nestjs-audit-log`](./packages/nestjs-audit-log) | Automatic audit logging with Prisma middleware | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-audit-log.svg)](https://www.npmjs.com/package/@bbv/nestjs-audit-log) |
66+
### Provider Abstraction
1767

18-
### Tier 2 — Utility Packages
68+
Modules with swappable backends follow the same config pattern with TypeScript discriminated unions for type safety:
1969

20-
| Package | Description | Version |
21-
|---------|-------------|---------|
22-
| [`@bbv/nestjs-prisma`](./packages/nestjs-prisma) | Prisma service shell, lifecycle management, test utilities | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-prisma.svg)](https://www.npmjs.com/package/@bbv/nestjs-prisma) |
23-
| [`@bbv/nestjs-pagination`](./packages/nestjs-pagination) | Pagination DTOs, helpers, and Swagger decorators | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-pagination.svg)](https://www.npmjs.com/package/@bbv/nestjs-pagination) |
24-
| [`@bbv/nestjs-response`](./packages/nestjs-response) | API response wrapper, transform interceptor, exception filter | [![npm](https://img.shields.io/npm/v/@bbv/nestjs-response.svg)](https://www.npmjs.com/package/@bbv/nestjs-response) |
70+
```typescript
71+
StorageModule.forRoot({
72+
provider: 's3', // or 'firebase', 'do_spaces', 'local'
73+
providerOptions: { /* typed */ }, // type narrows based on provider
74+
})
75+
```
76+
77+
### Multi-File Prisma Schema
78+
79+
Each Tier 1 plugin ships a `.prisma` file. Copy them into your project's schema directory:
80+
81+
```
82+
prisma/schema/
83+
base.prisma # datasource + generator (with prismaSchemaFolder)
84+
auth.prisma # from @bbv/nestjs-auth
85+
notifications.prisma # from @bbv/nestjs-notifications
86+
storage.prisma # from @bbv/nestjs-storage
87+
audit.prisma # from @bbv/nestjs-audit-log
88+
app.prisma # your project-specific models
89+
```
90+
91+
`base.prisma`:
92+
```prisma
93+
generator client {
94+
provider = "prisma-client-js"
95+
previewFeatures = ["prismaSchemaFolder"]
96+
}
97+
98+
datasource db {
99+
provider = "postgresql"
100+
url = env("DATABASE_URL")
101+
}
102+
```
25103

26104
## Quick Start
27105

106+
### 1. Install packages
107+
28108
```bash
29-
npm install @bbv/nestjs-prisma @bbv/nestjs-auth @bbv/nestjs-storage @bbv/nestjs-notifications
109+
npm install @bbv/nestjs-prisma @bbv/nestjs-auth @bbv/nestjs-storage @bbv/nestjs-notifications @bbv/nestjs-audit-log
30110
```
31111

112+
### 2. Configure modules
113+
32114
```typescript
33115
// app.module.ts
34116
import { Module } from '@nestjs/common';
@@ -37,6 +119,7 @@ import { PrismaModule } from '@bbv/nestjs-prisma';
37119
import { AuthModule } from '@bbv/nestjs-auth';
38120
import { StorageModule } from '@bbv/nestjs-storage';
39121
import { NotificationModule } from '@bbv/nestjs-notifications';
122+
import { AuditLogModule } from '@bbv/nestjs-audit-log';
40123

41124
@Module({
42125
imports: [
@@ -46,13 +129,7 @@ import { NotificationModule } from '@bbv/nestjs-notifications';
46129
AuthModule.forRootAsync({
47130
useFactory: (config: ConfigService) => ({
48131
jwt: { secret: config.getOrThrow('JWT_SECRET') },
49-
features: {
50-
emailPassword: true,
51-
google: true,
52-
organizations: true,
53-
emailVerification: true,
54-
passwordReset: true,
55-
},
132+
features: { emailPassword: true, google: true, organizations: true },
56133
providers: {
57134
google: {
58135
clientId: config.getOrThrow('GOOGLE_CLIENT_ID'),
@@ -68,7 +145,6 @@ import { NotificationModule } from '@bbv/nestjs-notifications';
68145
useFactory: (config: ConfigService) => ({
69146
provider: 's3',
70147
providerOptions: {
71-
endpoint: config.get('S3_ENDPOINT'),
72148
accessKeyId: config.getOrThrow('S3_ACCESS_KEY'),
73149
secretAccessKey: config.getOrThrow('S3_SECRET_KEY'),
74150
bucket: config.getOrThrow('S3_BUCKET'),
@@ -82,123 +158,62 @@ import { NotificationModule } from '@bbv/nestjs-notifications';
82158
useFactory: (config: ConfigService) => ({
83159
channels: {
84160
email: {
85-
enabled: true,
86-
provider: 'smtp',
87-
providerOptions: {
88-
host: config.get('SMTP_HOST', 'localhost'),
89-
port: 587,
90-
from: 'noreply@app.com',
91-
},
161+
enabled: true, provider: 'smtp',
162+
providerOptions: { host: config.get('SMTP_HOST', 'localhost'), port: 587, from: 'noreply@app.com' },
92163
},
93164
inApp: { enabled: true },
94165
},
95166
queue: { redis: { host: config.get('REDIS_HOST', 'localhost') } },
96167
}),
97168
inject: [ConfigService],
98169
}),
170+
171+
AuditLogModule.forRoot({
172+
features: { autoTrackCrud: true, registerController: true },
173+
}),
99174
],
100175
})
101176
export class AppModule {}
102177
```
103178

104-
Then copy plugin Prisma schemas and run migrations:
179+
### 3. Copy Prisma schemas and migrate
105180

106181
```bash
107-
# Copy plugin schemas (one-time, version-control these)
108182
cp node_modules/@bbv/nestjs-auth/prisma/auth.prisma prisma/schema/
109183
cp node_modules/@bbv/nestjs-notifications/prisma/notifications.prisma prisma/schema/
110184
cp node_modules/@bbv/nestjs-storage/prisma/storage.prisma prisma/schema/
185+
cp node_modules/@bbv/nestjs-audit-log/prisma/audit.prisma prisma/schema/
111186

112-
# Generate client + migrate
113187
npx prisma generate
114188
npx prisma migrate dev
115189
```
116190

117-
## Multi-File Prisma Schema
118-
119-
Each Tier 1 plugin ships a `.prisma` file. Your project uses Prisma's native multi-file schema support:
120-
121-
```
122-
prisma/
123-
schema/
124-
base.prisma # datasource + generator (with prismaSchemaFolder)
125-
auth.prisma # from @bbv/nestjs-auth
126-
notifications.prisma # from @bbv/nestjs-notifications
127-
storage.prisma # from @bbv/nestjs-storage
128-
audit.prisma # from @bbv/nestjs-audit-log
129-
app.prisma # your project-specific models
130-
```
131-
132-
`base.prisma`:
133-
```prisma
134-
generator client {
135-
provider = "prisma-client-js"
136-
previewFeatures = ["prismaSchemaFolder"]
137-
}
138-
139-
datasource db {
140-
provider = "postgresql"
141-
url = env("DATABASE_URL")
142-
}
143-
```
144-
145-
## Feature Flags
146-
147-
Every plugin module accepts a `features` config to toggle capabilities:
191+
### 4. Set up response envelope (optional)
148192

149193
```typescript
150-
AuthModule.forRootAsync({
151-
useFactory: () => ({
152-
jwt: { secret: 'my-secret' },
153-
features: {
154-
emailPassword: true, // POST /auth/register, POST /auth/login
155-
google: false, // Google OAuth routes not registered
156-
organizations: true, // Full /organizations CRUD
157-
sessionManagement: false, // Session endpoints not registered
158-
},
159-
}),
160-
})
161-
```
162-
163-
When a feature is off:
164-
- Its routes are **not registered**
165-
- Its services **throw** if called directly
166-
- No runtime overhead
194+
// main.ts
195+
import { TransformInterceptor, HttpExceptionFilter } from '@bbv/nestjs-response';
167196

168-
## Provider Abstraction
169-
170-
All modules with swappable providers follow the same config pattern:
171-
172-
```typescript
173-
{
174-
provider: 'provider_name',
175-
providerOptions: { /* typed config for that provider */ },
176-
}
197+
app.useGlobalInterceptors(new TransformInterceptor());
198+
app.useGlobalFilters(new HttpExceptionFilter());
177199
```
178200

179-
TypeScript discriminated unions ensure type safety per provider.
180-
181201
## Development
182202

203+
| Command | Description |
204+
|---------|-------------|
205+
| `npm install` | Install all dependencies |
206+
| `npm run build` | Build all packages |
207+
| `npm run test` | Run all tests |
208+
| `npm run lint` | Lint all packages |
209+
| `npm run typecheck` | Type-check all packages |
210+
| `npm run format` | Format with Prettier |
211+
| `cd apps/demo && npm run dev` | Run demo app (Swagger at `http://localhost:3000/api`) |
212+
213+
Demo app setup:
183214
```bash
184-
# Install dependencies
185-
npm install
186-
187-
# Build all packages
188-
npm run build
189-
190-
# Run all tests
191-
npm run test
192-
193-
# Lint all packages
194-
npm run lint
195-
196-
# Type-check all packages
197-
npm run typecheck
198-
199-
# Run the demo app
200215
cd apps/demo
201-
npm run docker # start Postgres + Redis
216+
npm run docker # Start Postgres + Redis
202217
npm run setup # prisma generate + migrate
203218
npm run dev # http://localhost:3000/api (Swagger)
204219
```
@@ -215,4 +230,4 @@ We use [Changesets](https://github.com/changesets/changesets) for versioning. Ad
215230

216231
## License
217232

218-
[MIT](./LICENSE) - BlackBox Vision
233+
[MIT](./LICENSE) -- [BlackBox Vision](https://github.com/BlackBoxVision)

0 commit comments

Comments
 (0)