langaro-api 1.2.3 → 1.2.4

package/lib/cli/documentation-templates/03-models.md

@@ -0,0 +1,362 @@
+# Models
+
+## Role
+
+Models are **configuration objects** — not classes. They define how the auto-generated CRUD instance for a database table should behave: which fields to hide, which relationships to load, how to validate input, what filters are available.
+
+**What models do:**
+- Define field visibility (hide sensitive fields)
+- Define relationships (append)
+- Define validation schemas (Yup)
+- Define search and filter behavior
+- Configure sorting defaults
+
+**What models do NOT do:**
+- Contain business logic (that belongs in services)
+- Define database schema (that's in migrations)
+- Handle HTTP requests (that's in controllers)
+
+---
+
+## Location & Naming
+
+```
+src/database/models/
+├── index.js                       # loadModels loader (do not modify)
+├── users.model.js                 # Config for 'users' table
+├── companies.model.js             # Config for 'companies' table
+├── products_invoices.model.js     # Config for 'products_invoices' table
+└── ...
+```
+
+**Naming convention:** `{table_name}.model.js` — must match the exact MySQL table name.
+
+**Optional:** Model files are optional. If no `.model.js` exists for a table, the loader still creates a bare CRUD instance with default configuration.
+
+---
+
+## Standard Structure
+
+```javascript
+const yup = require('yup');
+
+/** @type {ModelConfig} @generated-types */
+module.exports = {
+  // Fields never returned to the client
+  hide: ['password', 'recovery_token', 'two_fa_code'],
+
+  // Field-level configuration
+  fields: {
+    // Fields that can be omitted when creating (non-required on INSERT despite being non-nullable)
+    notRequiredOnCreate: ['id', 'created_at', 'updated_at', 'role'],
+
+    // Fields that cannot be updated after creation
+    notUpdatable: ['role', 'api_key', 'recovery_token'],
+
+    // Fields included in full-text search
+    searchableFields: ['name', 'email', 'phone'],
+
+    // Filter definitions for list endpoints
+    filterOptions: [
+      { name: 'status', type: 'select_multiple', options: ['active', 'inactive', 'blocked'] },
+      { name: 'role', type: 'select_multiple', options: ['user', 'admin'] },
+      { name: 'created_at', type: 'date' },
+      { name: 'revenue', type: 'integer' },
+      { name: 'has_subscription', column: 'subscription_id', type: 'is_not_null' },
+    ],
+  },
+
+  // Yup validation schema
+  schema: yup.object().shape({
+    email: yup.string().required().email(),
+    role: yup.string().required().oneOf(['user', 'admin']),
+    password: yup.string().required().min(6).max(20),
+    phone: yup.string().matches(/^\d{10,11}$/, 'phone must be 10-11 digits'),
+  }),
+
+  // Relationship definitions
+  append: {
+    users_permissions: 'many',   // users_permissions has user_id FK
+    companies: 'one',            // this table has company_id FK
+  },
+
+  // Default sort
+  sortBy: 'created_at',
+  sort: 'desc',
+};
+```
+
+---
+
+## Property Reference
+
+### `hide` (string[])
+
+Fields that are **always removed** from query results before returning to the client. Used for passwords, tokens, internal flags.
+
+```javascript
+hide: ['password', 'recovery_token', 'two_fa_code', 'activation_token']
+```
+
+### `fields.notRequiredOnCreate` (string[])
+
+Fields that should **not be enforced as required** during `create()` even if the database column is `NOT NULL`. Typically includes auto-generated fields.
+
+```javascript
+notRequiredOnCreate: ['id', 'created_at', 'updated_at', 'api_key', 'role']
+```
+
+**Always include:** `id`, `created_at`, `updated_at` (these are auto-set by the framework or database).
+
+### `fields.notUpdatable` (string[])
+
+Fields that **cannot be changed** via `updateWhere()` unless `allowForbiddenUpdates: true` is passed.
+
+```javascript
+notUpdatable: ['role', 'api_key', 'password_updated_at']
+```
+
+Note: `id`, `created_at`, `updated_at` are always protected — no need to list them here.
+
+### `fields.searchableFields` (string[])
+
+Fields included when the `search` query parameter is used in `get()`. If not defined, search is available on all non-hidden string fields.
+
+```javascript
+searchableFields: ['name', 'email', 'cnpj', 'phone']
+```
+
+### `fields.filterOptions` (object[])
+
+Defines which filters are available for list endpoints. Used by `parseAndValidateFilters` utility in controllers.
+
+**Filter types:**
+
+```javascript
+filterOptions: [
+  // select_multiple: filter by multiple values (IN query)
+  { name: 'status', type: 'select_multiple', options: ['active', 'inactive'] },
+
+  // date: filter by date range (between)
+  { name: 'created_at', type: 'date' },
+
+  // integer: filter by numeric comparison (>=, <=)
+  { name: 'amount', type: 'integer' },
+
+  // is_not_null: filter by presence/absence of a value
+  { name: 'has_subscription', column: 'subscription_id', type: 'is_not_null' },
+  // The 'column' property maps the filter name to an actual DB column
+]
+```
+
+### `schema` (Yup object)
+
+Yup validation schema. Validated on `create()` and per-field on `updateWhere()`.
+
+```javascript
+schema: yup.object().shape({
+  email: yup.string().required().email(),
+  cnpj: yup.string().matches(/^\d{14}$/, 'CNPJ must be 14 digits'),
+  status: yup.string().oneOf(['active', 'inactive', 'canceled']),
+  price: yup.number().positive(),
+})
+```
+
+### `append` (object)
+
+Relationship definitions. See `02-crud-layer.md` for detailed relationship types.
+
+```javascript
+append: {
+  companies: 'one',              // FK in this table → load one related record
+  products: 'many',              // FK in other table → load array of related records
+  categories: 'categories_join', // Many-to-many via join table
+}
+```
+
+### `sortBy` (string) & `sort` (string)
+
+Default sort column and direction for `get()` queries.
+
+```javascript
+sortBy: 'created_at',  // Default: 'id'
+sort: 'desc',          // Default: 'desc'. Options: 'asc', 'desc'
+```
+
+### `fieldsSpec` (object[])
+
+Per-field validation specifications that supplement schema validation:
+
+```javascript
+fieldsSpec: [
+  { column: 'cnpj', notEmpty: true },
+  { column: 'status', allowedValues: ['active', 'inactive'] },
+  { column: 'description', maxLength: 500 },
+]
+```
+
+### `forceInteger` (string[])
+
+Fields stored as integers (cents) but exposed as floats:
+
+```javascript
+forceInteger: ['price', 'amount', 'discount']
+// DB: 2999 (cents) ↔ API: 29.99 (reais)
+```
+
+### `notSearchableFields` (string[])
+
+Fields explicitly excluded from search even if they are string columns:
+
+```javascript
+notSearchableFields: ['password', 'api_key', 'recovery_token']
+```
+
+### `cacheTimeout` & `cacheEnabled`
+
+Override default cache behavior:
+
+```javascript
+cacheTimeout: 600000,  // 10 minutes (default: 300000 = 5 min)
+cacheEnabled: false,   // Disable caching entirely for this table
+```
+
+---
+
+## Flow
+
+```
+Database Table (MySQL)
+       ↓
+Model Config (.model.js) ──→ Loader reads this
+       ↓
+CRUD Instance (auto-created by loadModels)
+       ↓
+Service extends this CRUD instance
+       ↓
+Controller calls service methods
+```
+
+The model config is consumed **once** during boot when `loadModels()` runs. Changing a model file requires restarting the server.
+
+---
+
+## Patterns from Real Projects
+
+### Minimal model (just sorting):
+```javascript
+/** @type {ModelConfig} @generated-types */
+module.exports = {
+  fields: {},
+  sortBy: 'created_at',
+};
+```
+
+### Model with relationships and filters:
+```javascript
+/** @type {ModelConfig} @generated-types */
+module.exports = {
+  fields: {
+    notRequiredOnCreate: ['id', 'created_at', 'updated_at', 'notes', 'position'],
+    searchableFields: ['notes', 'contact_information'],
+    filterOptions: [
+      { name: 'pipeline_step_id', type: 'select_multiple' },
+      { name: 'responsible_user_id', type: 'select_multiple' },
+    ],
+  },
+  append: {
+    companies: 'one',
+    crm_pipeline_steps: 'one',
+    users: 'one',
+  },
+  sortBy: 'position',
+  sort: 'asc',
+};
+```
+
+### Model with comprehensive validation and security:
+```javascript
+const yup = require('yup');
+
+/** @type {ModelConfig} @generated-types */
+module.exports = {
+  hide: [
+    'password', 'recovery_token', 'recovery_token_validity',
+    'two_fa_code', 'two_fa_code_validity', 'activation_token',
+    'otp_code', 'otp_code_validity', 'login_blocked_stage',
+    'login_blocked_until',
+  ],
+  fields: {
+    notRequiredOnCreate: [
+      'id', 'created_at', 'password_updated_at', 'role', 'api_key',
+      'two_fa_enabled', 'two_fa_required', 'two_fa_code',
+      'login_blocked_stage', 'activation_token',
+    ],
+    notUpdatable: ['password_updated_at', 'role', 'api_key', 'recovery_token'],
+  },
+  append: {
+    users_permissions: 'many',
+  },
+  schema: yup.object().shape({
+    email: yup.string().required().email(),
+    role: yup.string().required().oneOf(['user', 'admin']),
+    password: yup.string().required().matches(
+      /^([a-zA-Z\d@$!%*#?&.,_+]{6,20})$/,
+      'password must be 6-20 characters'
+    ),
+  }),
+};
+```
+
+---
+
+## Creating from Scratch
+
+When creating a model for a new table:
+
+1. **Create the file:** `src/database/models/{table_name}.model.js`
+2. **Start with the minimal template:**
+   ```javascript
+   /** @type {ModelConfig} @generated-types */
+   module.exports = {
+     fields: {},
+     sortBy: 'created_at',
+   };
+   ```
+3. **Add `notRequiredOnCreate`**: Always include `['id', 'created_at', 'updated_at']` plus any auto-generated fields
+4. **Add `hide`**: List any sensitive fields (passwords, tokens, internal flags)
+5. **Add `notUpdatable`**: List fields that should be immutable after creation
+6. **Add `schema`**: Define Yup validation for fields that need format enforcement
+7. **Add `append`**: Define relationships if the table has foreign keys or is referenced by other tables
+8. **Add `searchableFields`**: List fields that should be searchable via the search parameter
+9. **Add `filterOptions`**: Define filter definitions if the list endpoint needs advanced filtering
+10. **Restart the server** to pick up the new model config
+
+---
+
+## Anti-patterns
+
+- **Do NOT put business logic in model files.** Models are configuration, not behavior.
+- **Do NOT include `table` or `knex` in the model config.** These are injected by the loader.
+- **Do NOT forget to add `id`, `created_at`, `updated_at` to `notRequiredOnCreate`.** Missing these will cause create operations to fail with "required field" errors.
+- **Do NOT add computed or virtual fields to `hide`.** Only hide fields that actually exist in the database table.
+- **Do NOT define relationships that don't have matching foreign keys.** The append system relies on actual FK constraints in the database.
+
+---
+
+## Checklist
+
+When creating or modifying a model:
+
+- [ ] File is named `{exact_table_name}.model.js`
+- [ ] File is in `src/database/models/`
+- [ ] Exports a plain object (not a class or function)
+- [ ] Has `@type {ModelConfig} @generated-types` JSDoc comment
+- [ ] `notRequiredOnCreate` includes `id`, `created_at`, `updated_at`
+- [ ] Sensitive fields are in `hide` array
+- [ ] Immutable fields are in `notUpdatable` array
+- [ ] Yup schema matches database column types
+- [ ] Relationships in `append` have matching FK constraints in DB
+- [ ] `filterOptions` types match the column data types
+- [ ] Does NOT contain `table` or `knex` properties
+- [ ] Does NOT contain business logic

package/lib/cli/documentation-templates/04-services.md

@@ -0,0 +1,355 @@
+# Services
+
+## Role
+
+Services are the **business logic layer**. They extend CRUD models with custom methods that orchestrate database operations, external API calls, and cross-table logic.
+
+**What services do:**
+- Implement business rules and workflows
+- Orchestrate multi-table transactions
+- Call external APIs via integrations
+- Validate complex business constraints
+- Provide methods that controllers delegate to
+
+**What services do NOT do:**
+- Handle HTTP request/response (that's controllers)
+- Define field visibility or validation schema (that's models)
+- Route URLs (that's routes)
+
+---
+
+## Location & Naming
+
+```
+src/database/services/
+├── index.js                         # loadServices loader (do not modify)
+├── users.services.js                # Service for 'users' table
+├── companies.services.js            # Service for 'companies' table
+├── products_invoices.services.js    # Service for 'products_invoices' table
+├── checkout.services.js             # Custom service (no DB table)
+└── ...
+```
+
+**Naming convention:** `{table_name}.services.js`
+
+**Service instance key:** `PascalCase(table_name) + 'Services'`
+- `users.services.js` → `UsersServices`
+- `products_invoices.services.js` → `ProductsInvoicesServices`
+
+**Optional:** Service files are optional. If no `.services.js` exists for a table, the loader creates a bare service that only exposes the inherited CRUD methods.
+
+---
+
+## Standard Structure
+
+### Table-Backed Service (most common)
+
+This service is bound to a specific database table and inherits all CRUD methods:
+
+```javascript
+/* eslint-disable new-cap */
+/** @param {typeof UsersServicesBase} model @param {ModelsConstructorMap} models @generated-types */
+module.exports = (model, models, io) => class extends model {
+
+  async customMethod(data) {
+    // 'this' inherits all CRUD methods: get, getWhere, create, etc.
+    // But for operations needing their own instance, create one:
+    const UsersModel = new model();
+    const CompaniesModel = new models.companies();
+
+    // Access other models for cross-table operations
+    const { data: company } = await CompaniesModel.getWhere('id', data.company_id, {
+      firstOnly: true,
+    });
+
+    // Use transactions for multi-step operations
+    const trx = await UsersModel.createTransaction();
+    try {
+      const result = await UsersModel.create(data, trx);
+      await CompaniesModel.updateWhere('id', data.company_id, {
+        user_count: company.user_count + 1,
+      }, {}, trx);
+      await trx.commit();
+      return result;
+    } catch (error) {
+      await trx.rollback();
+      throw error;
+    }
+  }
+};
+```
+
+**Factory signature:** `(model, models, io) => class extends model`
+- `model` — The CRUD class constructor for this table (e.g., the Users CRUD class)
+- `models` — Map of ALL model constructors (keyed by table name)
+- `io` — Socket.io server instance
+
+### Custom Service (no DB table)
+
+For services that orchestrate across multiple tables without having their own:
+
+```javascript
+/** @param {ModelsConstructorMap} models @generated-types */
+module.exports = (models, io) => class {
+  async processCheckout(data) {
+    const OrdersModel = new models.orders();
+    const PaymentsModel = new models.payments();
+
+    // Cross-table orchestration
+    const trx = await OrdersModel.createTransaction();
+    try {
+      const order = await OrdersModel.create(data.order, trx);
+      await PaymentsModel.create({ order_id: order.data.id, ...data.payment }, trx);
+      await trx.commit();
+      return order;
+    } catch (error) {
+      await trx.rollback();
+      throw error;
+    }
+  }
+};
+```
+
+**Factory signature:** `(models, io) => class` (only 2 arguments, no `model`)
+
+The loader detects this variant automatically by checking the function's parameter count.
+
+---
+
+## Accessing Models Inside Services
+
+**Critical rule:** Always create model instances **inside methods**, not at class level.
+
+```javascript
+// ✅ CORRECT: Create inside method
+async myMethod(data) {
+  const UsersModel = new model();
+  const CompaniesModel = new models.companies();
+  // ...
+}
+
+// ❌ WRONG: Create at class level
+module.exports = (model, models) => {
+  const UsersModel = new model();  // This gets shared across all calls!
+  return class extends model { ... };
+};
+```
+
+**Why:** Each model instance manages its own connection context. Shared instances can cause transaction leaks and race conditions.
+
+---
+
+## Transaction Patterns
+
+### Standard Transaction
+
+```javascript
+async createUserWithPermissions(data) {
+  const UsersModel = new model();
+  const PermissionsModel = new models.users_permissions();
+
+  const trx = await UsersModel.createTransaction();
+  try {
+    const user = await UsersModel.create({
+      ...data,
+      role: 'user',
+      activation_token: generateToken(),
+    }, trx);
+
+    const permissions = subjects.map(subject => ({
+      subject,
+      action: '*',
+      user_id: user.data.id,
+    }));
+    await PermissionsModel.batchCreate(permissions, trx);
+
+    await trx.commit();
+    return user;
+  } catch (error) {
+    await trx.rollback();
+    throw error;
+  }
+}
+```
+
+### Transaction with Validation
+
+```javascript
+async transferFunds(fromId, toId, amount) {
+  const AccountsModel = new model();
+  const trx = await AccountsModel.createTransaction();
+
+  try {
+    const { data: fromAccount } = await AccountsModel.getWhere('id', fromId, {
+      firstOnly: true,
+    });
+
+    if (fromAccount.balance < amount) {
+      throw ApiError(StatusCodes.UNPROCESSABLE_ENTITY, 'Insufficient funds');
+    }
+
+    await AccountsModel.updateWhere('id', fromId, {
+      balance: fromAccount.balance - amount,
+    }, { allowForbiddenUpdates: true }, trx);
+
+    await AccountsModel.updateWhere('id', toId, {
+      balance: knex.raw('balance + ?', [amount]),
+    }, { allowForbiddenUpdates: true }, trx);
+
+    await trx.commit();
+  } catch (error) {
+    await trx.rollback();
+    throw error;
+  }
+}
+```
+
+---
+
+## Socket.io Integration
+
+Services receive the Socket.io instance via the `io` parameter:
+
+```javascript
+module.exports = (model, models, io) => class extends model {
+  async updateStatus(itemId, newStatus, userId) {
+    await this.updateWhere('id', itemId, { status: newStatus });
+
+    // Notify the specific user
+    io.sockets.in(userId).emit('item:statusUpdated', {
+      id: itemId,
+      status: newStatus,
+    });
+  }
+
+  async broadcastToCompany(companyId, event, data) {
+    // Notify all users in a company
+    io.sockets.in(companyId).emit(event, data);
+  }
+};
+```
+
+**Room conventions:**
+- `io.sockets.in(userId)` — Send to a specific user
+- `io.sockets.in(companyId)` — Send to all users in a company
+
+---
+
+## Common Patterns
+
+### Data Enrichment Before Response
+
+```javascript
+async getEnrichedInvoice(invoiceId) {
+  const { data: invoice } = await this.getWhere('id', invoiceId, {
+    firstOnly: true,
+    append: ['companies', 'products'],
+  });
+
+  // Add computed fields
+  invoice.total_with_tax = invoice.total + invoice.tax_amount;
+  invoice.is_overdue = new Date(invoice.due_date) < new Date();
+
+  return invoice;
+}
+```
+
+### Batch Create
+
+```javascript
+async createMultipleItems(items, companyId) {
+  const data = items.map((item) => ({
+    ...item,
+    company_id: companyId,
+  }));
+
+  const trx = await this.createTransaction();
+  try {
+    const result = await this.batchCreate(data, trx);
+    await trx.commit();
+    return result;
+  } catch (error) {
+    await trx.rollback();
+    throw error;
+  }
+}
+```
+
+### Parallel External Data Fetching
+
+```javascript
+async syncExternalData(companyIds) {
+  const [revenueData, subscriptionData] = await Promise.all([
+    externalDb.select('*').from('revenue').whereIn('company_id', companyIds),
+    externalDb.select('*').from('subscriptions').whereIn('company_id', companyIds),
+  ]);
+
+  // Build maps for efficient lookup
+  const revenueMap = new Map(revenueData.map(r => [r.company_id, r]));
+  const subscriptionMap = new Map(subscriptionData.map(s => [s.company_id, s]));
+
+  const toUpdate = companyIds.map(id => ({
+    id,
+    revenue: revenueMap.get(id)?.amount || 0,
+    subscription_status: subscriptionMap.get(id)?.status || 'inactive',
+  }));
+
+  const trx = await this.createTransaction();
+  try {
+    await this.batchUpdate(toUpdate, undefined, trx);
+    await trx.commit();
+  } catch (error) {
+    await trx.rollback();
+    throw error;
+  }
+}
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the file:** `src/database/services/{table_name}.services.js`
+2. **Choose the pattern:**
+   - If the service maps to a DB table: use `(model, models, io) => class extends model`
+   - If no DB table: use `(models, io) => class`
+3. **Start with the template:**
+   ```javascript
+   /** @param {typeof TableServicesBase} model @param {ModelsConstructorMap} models @generated-types */
+   module.exports = (model, models, io) => class extends model {
+     // Add methods here
+   };
+   ```
+4. **Add business methods** — each method should represent a complete business operation
+5. **Use transactions** for any operation that touches multiple tables
+6. **Create model instances inside methods** (not at class level)
+7. **Regenerate types:** `npx langaro-api generate`
+
+---
+
+## Anti-patterns
+
+- **Do NOT put HTTP handling in services.** No `req`, `res`, or `next`. Services receive plain data and return plain data.
+- **Do NOT create model instances at the class level.** Always inside methods.
+- **Do NOT forget transactions** for multi-table operations. Partial writes without transactions can leave data in inconsistent states.
+- **Do NOT call other services from a service.** Services receive `models` (constructors), not `services` (instances). Cross-service calls should go through the controller.
+- **Do NOT catch and swallow errors silently.** Always re-throw or let errors bubble up for proper error handling.
+- **Do NOT mix database and HTTP concerns.** No status codes, no res.json() in services.
+
+---
+
+## Checklist
+
+When creating or modifying a service:
+
+- [ ] File is named `{table_name}.services.js`
+- [ ] File is in `src/database/services/`
+- [ ] Exports a factory function (not a plain class)
+- [ ] Factory signature matches: `(model, models, io)` for table-backed, `(models, io)` for custom
+- [ ] Has correct `@generated-types` JSDoc annotation
+- [ ] Class extends `model` (for table-backed services)
+- [ ] Model instances are created inside methods, not at class level
+- [ ] Multi-table operations use transactions with try/commit/catch/rollback
+- [ ] No HTTP concerns (req, res, status codes)
+- [ ] No direct `require()` of other services
+- [ ] Error handling follows project conventions (throw, don't swallow)