langaro-api 1.2.3 → 1.2.5

package/lib/cli/documentation-templates/05-controllers.md

@@ -0,0 +1,395 @@
+# Controllers
+
+## Role
+
+Controllers are **request handlers**. They receive HTTP requests, validate input, delegate business logic to services, trigger background jobs, and return responses.
+
+**What controllers do:**
+- Extract and validate data from `req.body`, `req.query`, `req.params`
+- Call service methods for business logic
+- Trigger background jobs via `this.Queue`
+- Emit real-time events via `this.io`
+- Return JSON responses
+
+**What controllers do NOT do:**
+- Contain business logic (that belongs in services)
+- Execute database queries directly (use services/CRUD methods)
+- Define routes (that's in routers)
+
+---
+
+## Location & Naming
+
+```
+src/controllers/
+├── index.js                              # loadControllers loader (do not modify)
+├── users/
+│   └── users.controller.js               # Controller for 'users'
+├── auth/
+│   └── auth.controller.js                # Controller for 'auth' (no DB table)
+├── products_invoices/
+│   └── products_invoices.controller.js   # Controller for 'products_invoices'
+└── ...
+```
+
+**Naming convention:** `{name}/{name}.controller.js` (subdirectory pattern, preferred)
+
+The loader also supports flat files: `{name}.controller.js` (without subdirectory).
+
+**Controller instance key:** `PascalCase(name) + 'Controller'`
+- `users.controller.js` → `UsersController`
+- `products_invoices.controller.js` → `ProductsInvoicesController`
+
+---
+
+## Standard Structure
+
+```javascript
+/** @param {typeof UsersControllerBase} ServicesClass @generated-types */
+module.exports = (ServicesClass) => class extends ServicesClass {
+
+  /**
+   * GET / — List all records
+   */
+  async getAll(req, res) {
+    const {
+      perPage, currentPage, search, searchExactMatch, searchFields,
+      sortBy, sort, append,
+    } = req.query;
+
+    const data = await this.service.get({
+      perPage,
+      currentPage,
+      search,
+      searchExactMatch,
+      searchFields,
+      sortBy,
+      sort,
+      append: append ? append.split(',') : undefined,
+    });
+
+    res.status(200).json(data);
+  }
+
+  /**
+   * GET /:id — Get single record
+   */
+  async getById(req, res) {
+    const { id } = req.params;
+
+    const { data: item } = await this.service.getWhere('id', id, {
+      firstOnly: true,
+      append: ['related_table'],
+    });
+
+    if (!item) {
+      ApiError(StatusCodes.NOT_FOUND, 'Item not found');
+    }
+
+    res.status(200).json({ success: true, data: item });
+  }
+
+  /**
+   * POST / — Create new record
+   */
+  async create(req, res) {
+    const data = req.body;
+    validateRequiredFields(data, ['name', 'email']);
+
+    const result = await this.service.create({
+      ...data,
+      company_id: req.company_id,
+    });
+
+    res.status(201).json(result);
+  }
+
+  /**
+   * PUT /:id — Update record
+   */
+  async update(req, res) {
+    const { id } = req.params;
+    const data = req.body;
+
+    const result = await this.service.updateWhere('id', id, data, {
+      andWhere: [['company_id', req.company_id]],
+    });
+
+    res.status(200).json(result);
+  }
+
+  /**
+   * DELETE /:id — Delete record
+   */
+  async remove(req, res) {
+    const { id } = req.params;
+
+    await this.service.deleteWhere('id', id, {
+      andWhere: [['company_id', req.company_id]],
+    });
+
+    res.status(200).json({ success: true });
+  }
+};
+```
+
+---
+
+## Available Properties via ServicesClass
+
+Every controller method has access to these via `this`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `this.service` | Service instance | The service matching this controller's table. Has all CRUD methods + custom service methods. |
+| `this.services` | ServicesMap | Map of ALL service instances. Access via `this.services.UsersServices`, `this.services.CompaniesServices`, etc. |
+| `this.Queue` | `{ add(name, data, options) }` | BullMQ queue interface for adding background jobs. |
+| `this.io` | Socket.io Server | Socket.io instance for real-time events. |
+
+---
+
+## Request Properties (set by auth middleware)
+
+After the auth middleware runs, these are available on `req`:
+
+| Property | Description |
+|----------|-------------|
+| `req.user_id` | Authenticated user's ID |
+| `req.email` | User's email |
+| `req.role` | User's role (`'user'` or `'admin'`) |
+| `req.company_id` | Company ID from headers (if `companyIdRequired`) |
+| `req.company` | Full company object (in some projects) |
+| `req.user_permissions` | Array of `{ subject, action }` permission objects |
+| `req.token` | Raw JWT token string |
+| `req.files` | Uploaded files (multer) |
+| `req.rawBody` | Raw request body (for webhook signature verification) |
+
+---
+
+## Input Validation Pattern
+
+Controllers validate input before passing to services:
+
+```javascript
+const { validateRequiredFields } = require('@/utils');
+const { validateFieldsFormat } = require('@/utils');
+const { ApiError, StatusCodes } = require('@/utils');
+
+async create(req, res) {
+  const data = req.body;
+
+  // 1. Required fields
+  validateRequiredFields(data, ['name', 'email', 'company_id']);
+
+  // 2. Field format validation
+  validateFieldsFormat([
+    ['email', data.email, 'email field'],
+    ['phone', data.phone, 'phone field'],
+    ['array', data.items, 'items field'],
+  ]);
+
+  // 3. Business validation
+  if (data.amount < 0) {
+    ApiError(StatusCodes.BAD_REQUEST, 'Amount cannot be negative');
+  }
+
+  // 4. Delegate to service
+  const result = await this.service.create(data);
+  res.status(201).json(result);
+}
+```
+
+---
+
+## Queue Integration
+
+Trigger background jobs from controllers:
+
+```javascript
+async createInvoice(req, res) {
+  const invoice = await this.service.create(req.body);
+
+  // Fire-and-forget job
+  await this.Queue.add('send-mail', {
+    templateName: 'invoice-created',
+    recipientsList: [{ Email: req.email, TemplateModel: { invoiceId: invoice.data.id } }],
+  });
+
+  // Job with delay
+  await this.Queue.add('process-invoice', {
+    invoiceId: invoice.data.id,
+  }, { delay: 5000 });  // Wait 5 seconds
+
+  // Job with group (per-company isolation)
+  await this.Queue.add('sync-data', {
+    companyId: req.company_id,
+  }, { groupId: req.company_id });
+
+  res.status(201).json(invoice);
+}
+```
+
+---
+
+## Socket.io Integration
+
+Emit real-time events from controllers:
+
+```javascript
+async updateStatus(req, res) {
+  const { id } = req.params;
+  const { status } = req.body;
+
+  const result = await this.service.updateWhere('id', id, { status });
+
+  // Notify the specific user
+  this.io.sockets.in(req.user_id).emit('item:updated', { id, status });
+
+  // Notify all users in the company
+  this.io.sockets.in(req.company_id).emit('item:updated', { id, status });
+
+  res.status(200).json(result);
+}
+```
+
+---
+
+## Controllers Without DB Tables
+
+Valid pattern for orchestration endpoints (auth, checkout, webhooks):
+
+```javascript
+// src/controllers/auth/auth.controller.js
+module.exports = (ServicesClass) => class extends ServicesClass {
+  // this.service will be a pseudo-service (no CRUD methods)
+  // Use this.services to access other services
+
+  async login(req, res) {
+    const { email, password } = req.body;
+    const result = await this.services.UsersServices.authenticate(email, password);
+    res.status(200).json(result);
+  }
+};
+```
+
+The loader creates a minimal `ServicesClass` with `this.services`, `this.Queue`, and `this.io` even when there's no matching database table.
+
+---
+
+## List Endpoint with Filters Pattern
+
+The most common controller pattern for list endpoints:
+
+```javascript
+async getAll(req, res) {
+  const {
+    perPage, currentPage, search, searchExactMatch, searchFields,
+    sortBy, sort, append,
+  } = req.query;
+
+  // Parse and validate filter parameters from query string
+  const andWhereFilters = parseAndValidateFilters(
+    req.query,
+    this.service.fields.filterOptions  // From model config
+  );
+
+  const data = await this.service.get({
+    perPage,
+    currentPage,
+    search,
+    searchExactMatch,
+    searchFields,
+    sortBy,
+    sort,
+    append: append ? append.split(',') : undefined,
+    andWhere: [
+      ['company_id', req.company_id],  // Always scope by company
+      ...andWhereFilters,               // Dynamic filters
+    ],
+  });
+
+  res.status(200).json(data);
+}
+```
+
+---
+
+## File Upload Pattern
+
+```javascript
+async uploadFile(req, res) {
+  const file = req.files?.[0];
+
+  if (!file) {
+    ApiError(StatusCodes.BAD_REQUEST, 'File is required');
+  }
+
+  // Validate file
+  validateFiles(file, {
+    maxSize: 5 * 1024 * 1024,  // 5MB
+    allowedTypes: ['image/jpeg', 'image/png'],
+  });
+
+  // Upload to S3
+  const aws = require('@/integrations/aws');
+  const location = await aws.uploadToS3(process.env.S3_BUCKET_DOCUMENTS, {
+    filename: `${req.user_id}/${Date.now()}-${file.originalname}`,
+    file: file.buffer,
+  });
+
+  // Update record with file URL
+  const result = await this.service.updateWhere('id', req.params.id, {
+    file_url: location,
+  });
+
+  res.status(200).json(result);
+}
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the directory:** `src/controllers/{table_name}/`
+2. **Create the file:** `src/controllers/{table_name}/{table_name}.controller.js`
+3. **Use the template:**
+   ```javascript
+   /** @param {typeof TableControllerBase} ServicesClass @generated-types */
+   module.exports = (ServicesClass) => class extends ServicesClass {
+     async getAll(req, res) {
+       const data = await this.service.get();
+       res.status(200).json(data);
+     }
+   };
+   ```
+4. **Add methods** for each endpoint the resource needs
+5. **Create corresponding route** in `src/routes/{table_name}.router.js`
+6. **Regenerate types:** `npx langaro-api generate`
+
+---
+
+## Anti-patterns
+
+- **Do NOT put business logic in controllers.** If it involves more than validation and delegation, move it to the service.
+- **Do NOT access `knex` directly in controllers.** Use `this.service` or `this.services`.
+- **Do NOT forget `.bind(controller)` in routes.** Without it, `this` is undefined inside the controller method.
+- **Do NOT return raw error messages** from external services. Use `ApiError()` with safe, user-facing messages.
+- **Do NOT mix async patterns.** Use `async/await` consistently, never mix callbacks.
+- **Do NOT forget to scope queries by `company_id`** when the endpoint is company-scoped.
+
+---
+
+## Checklist
+
+When creating or modifying a controller:
+
+- [ ] File is in `src/controllers/{name}/{name}.controller.js`
+- [ ] Exports a factory function `(ServicesClass) => class extends ServicesClass`
+- [ ] Has correct `@generated-types` JSDoc annotation
+- [ ] Each method receives `(req, res)` — standard Express handler signature
+- [ ] Input validation happens before service delegation
+- [ ] Business logic is in the service, not the controller
+- [ ] Company-scoped queries include `company_id` in filters
+- [ ] Background jobs use `this.Queue.add()`, not inline processing
+- [ ] Error responses use `ApiError()` with appropriate status codes
+- [ ] Corresponding route file exists in `src/routes/`

package/lib/cli/documentation-templates/06-routes.md

@@ -0,0 +1,268 @@
+# Routes
+
+## Role
+
+Routes define the **HTTP API surface**. They map URL paths to controller methods and apply middleware (authentication, permissions).
+
+**What routes do:**
+- Map HTTP methods + paths to controller methods
+- Apply auth middleware with permissions
+- Define the public API contract
+
+**What routes do NOT do:**
+- Contain business logic
+- Execute database queries
+- Validate request bodies (that's in controllers)
+
+---
+
+## Location & Naming
+
+```
+src/routes/
+├── index.js                          # attachRouters loader (do not modify)
+├── users.router.js                   # Routes for /users
+├── auth.router.js                    # Routes for /auth
+├── products_invoices.router.js       # Routes for /products-invoices
+└── ...
+```
+
+**Naming convention:** `{table_name}.router.js`
+
+**URL path conversion:** The loader converts `snake_case` filenames to `kebab-case` URL paths:
+- `users.router.js` → `/users`
+- `products_invoices.router.js` → `/products-invoices`
+- `auth.router.js` → `/auth`
+
+---
+
+## Standard Structure
+
+```javascript
+const createAuthMiddleware = require('@/middlewares/auth.middleware');
+
+/** @param {ControllersMap} controllers @param {ServicesMap} services @generated-types */
+module.exports = (controllers, services) => {
+  const auth = createAuthMiddleware(services);
+  const router = require('express').Router();
+  const controller = controllers.UsersController;
+  const subject = 'users';
+
+  // List all
+  router.get('/',
+    auth([{ subject }]),
+    controller.getAll.bind(controller)
+  );
+
+  // Get by ID
+  router.get('/:id',
+    auth([{ subject }]),
+    controller.getById.bind(controller)
+  );
+
+  // Create
+  router.post('/',
+    auth([{ subject, action: 'create' }]),
+    controller.create.bind(controller)
+  );
+
+  // Update
+  router.put('/:id',
+    auth([{ subject, action: 'update' }]),
+    controller.update.bind(controller)
+  );
+
+  // Delete
+  router.delete('/:id',
+    auth([{ subject, action: 'delete' }]),
+    controller.remove.bind(controller)
+  );
+
+  return router;
+};
+```
+
+---
+
+## Auth Middleware Usage
+
+```javascript
+const auth = createAuthMiddleware(services);
+```
+
+### Signature
+
+```javascript
+auth(permissionsRequired, authorizedRoles, companyIdRequired)
+```
+
+### Parameters
+
+**`permissionsRequired`** (array) — Required permissions. Each entry is `{ subject, action? }`:
+```javascript
+// Require any permission on 'users' subject
+auth([{ subject: 'users' }])
+
+// Require specific action
+auth([{ subject: 'users', action: 'delete' }])
+
+// Require one of multiple permissions (OR logic)
+auth([{ subject: 'users' }, { subject: 'admin' }])
+
+// No permission check (just authentication)
+auth([])
+```
+
+**`authorizedRoles`** (array, default: `['user', 'admin']`) — Allowed roles:
+```javascript
+// Default: both users and admins
+auth([{ subject: 'users' }])
+
+// Admin only
+auth([{ subject: 'users' }], ['admin'])
+```
+
+**`companyIdRequired`** (boolean, default: varies by project) — Whether `company_id` header is required:
+```javascript
+// Route works without company context
+auth([{ subject: 'users' }], undefined, false)
+
+// Route requires company context (company_id header)
+auth([{ subject: 'users' }], undefined, true)
+```
+
+### Public Routes (no auth)
+
+Simply omit the auth middleware:
+
+```javascript
+router.post('/register', controller.register.bind(controller));
+router.post('/login', controller.login.bind(controller));
+router.get('/health', (req, res) => res.status(200).json({ status: 'ok' }));
+```
+
+---
+
+## Binding Convention
+
+**Always use `.bind(controller)`** when passing controller methods to routes:
+
+```javascript
+// ✅ CORRECT
+router.get('/', auth([{ subject }]), controller.getAll.bind(controller));
+
+// ❌ WRONG — 'this' will be undefined in the controller method
+router.get('/', auth([{ subject }]), controller.getAll);
+```
+
+**Why:** Express calls the handler without a `this` context. `.bind()` ensures the controller instance is preserved.
+
+---
+
+## Common Route Patterns
+
+### Standard CRUD Routes
+
+```javascript
+router.get('/', auth([{ subject }]), controller.getAll.bind(controller));
+router.get('/:id', auth([{ subject }]), controller.getById.bind(controller));
+router.post('/', auth([{ subject }]), controller.create.bind(controller));
+router.put('/:id', auth([{ subject }]), controller.update.bind(controller));
+router.delete('/:id', auth([{ subject }]), controller.remove.bind(controller));
+```
+
+### Action Routes
+
+```javascript
+// Export data
+router.get('/export',
+  auth([{ subject, action: 'export' }]),
+  controller.exportData.bind(controller)
+);
+
+// Batch operations
+router.post('/batch-update',
+  auth([{ subject, action: 'update' }]),
+  controller.batchUpdate.bind(controller)
+);
+
+// Status changes
+router.put('/:id/cancel',
+  auth([{ subject, action: 'cancel' }]),
+  controller.cancel.bind(controller)
+);
+```
+
+### Mixed Auth Routes
+
+```javascript
+// Public route
+router.post('/register', controller.register.bind(controller));
+
+// Authenticated but no permission check
+router.get('/me', auth([]), controller.getProfile.bind(controller));
+
+// Full permission check
+router.put('/settings',
+  auth([{ subject: 'settings' }]),
+  controller.updateSettings.bind(controller)
+);
+
+// Admin only
+router.get('/admin/stats',
+  auth([{ subject: 'admin' }], ['admin']),
+  controller.getStats.bind(controller)
+);
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the file:** `src/routes/{table_name}.router.js`
+2. **Use the template:**
+   ```javascript
+   const createAuthMiddleware = require('@/middlewares/auth.middleware');
+
+   /** @param {ControllersMap} controllers @param {ServicesMap} services @generated-types */
+   module.exports = (controllers, services) => {
+     const auth = createAuthMiddleware(services);
+     const router = require('express').Router();
+     const controller = controllers.TableNameController;
+     const subject = 'table_name';
+
+     router.get('/', auth([{ subject }]), controller.getAll.bind(controller));
+
+     return router;
+   };
+   ```
+3. **Add routes** for each controller method
+4. **Apply auth** with appropriate permissions and roles
+5. **Regenerate types:** `npx langaro-api generate`
+
+---
+
+## Anti-patterns
+
+- **Do NOT put logic in route files.** Routes are pure wiring — no validation, no database calls.
+- **Do NOT forget `.bind(controller)`.** This is the most common bug.
+- **Do NOT use inline middleware functions** for complex logic. Create separate middleware files.
+- **Do NOT hardcode URL paths.** The loader auto-generates them from the filename.
+- **Do NOT create multiple router files for the same resource.** One file per resource.
+
+---
+
+## Checklist
+
+When creating or modifying a route:
+
+- [ ] File is named `{table_name}.router.js`
+- [ ] File is in `src/routes/`
+- [ ] Exports a factory function `(controllers, services) => Router`
+- [ ] Has correct `@generated-types` JSDoc annotation
+- [ ] Controller accessed via `controllers.PascalCaseController`
+- [ ] Auth middleware applied to all protected routes
+- [ ] All controller methods use `.bind(controller)`
+- [ ] Returns the Express router
+- [ ] Corresponding controller exists in `src/controllers/`
+- [ ] Permission subjects match the resource name