langaro-api 1.2.2 → 1.2.4

package/lib/cli/documentation-templates/09-middlewares.md

@@ -0,0 +1,238 @@
+# Middlewares
+
+## Role
+
+Middlewares intercept requests before they reach controllers. The primary middleware is the **auth middleware** which handles authentication and authorization.
+
+**What middlewares do:**
+- Authenticate requests (JWT, API key)
+- Check user roles and permissions
+- Enrich `req` with user data
+- Gate access to routes
+
+**What middlewares do NOT do:**
+- Execute business logic
+- Return final responses (except for auth failures)
+- Access the database for business operations
+
+---
+
+## Location & Naming
+
+```
+src/middlewares/
+├── auth.middleware.js          # Authentication & authorization
+├── webhooks.middleware.js      # Webhook signature validation (if needed)
+└── ...
+```
+
+**Naming convention:** `{name}.middleware.js`
+
+---
+
+## Auth Middleware (Core)
+
+The auth middleware is the most critical middleware. It's created by `langaro-api init` and customized per project.
+
+### Factory Pattern
+
+```javascript
+const jwt = require('jsonwebtoken');
+const { ApiError, StatusCodes } = require('@/utils');
+
+/** @param {ServicesMap} services @generated-types */
+module.exports = function (services) {
+  return function auth(permissionsRequired, authorizedRoles, companyIdRequired) {
+    return async (req, res, next) => {
+      // Authentication and authorization logic
+    };
+  };
+};
+```
+
+**Structure:** Factory → returns configurator → returns Express middleware
+
+### Authentication Strategies
+
+**1. JWT Bearer Token:**
+```
+Header: Authorization: Bearer <jwt-token>
+```
+- Decoded with `jwt.verify(token, process.env.JWT_SECRET)`
+- Payload contains `user_id` (and optionally `email`)
+- Token invalidated if issued before last password change
+
+**2. API Key:**
+```
+Header: api_key: <key>
+```
+- Looked up against the users table
+- Useful for programmatic access / integrations
+
+### Authorization Flow
+
+```
+1. Extract token from Authorization header OR api_key header
+2. Validate token/key → get user
+3. Check user.role against authorizedRoles
+4. If permissionsRequired specified:
+   a. Load user's permissions (from users_permissions table)
+   b. For each required { subject, action }:
+      - Find matching permission in user's list
+      - Wildcard action '*' matches any action
+5. If companyIdRequired:
+   a. Read company_id from request headers
+   b. Verify user has access to that company
+6. Set req.user_id, req.email, req.role, req.company_id, etc.
+7. Call next()
+```
+
+### Request Properties Set
+
+After successful authentication, the middleware sets:
+
+```javascript
+req.user_id          // User's UUID
+req.email            // User's email
+req.role             // 'user' or 'admin'
+req.company_id       // Company ID (from header, if required)
+req.user_permissions // Array of { subject, action }
+req.token            // Raw JWT token string
+req.user             // { id, email, segment } for Sentry
+```
+
+---
+
+## Permission System
+
+Permissions follow a **subject + action** pattern (Attribute-Based Access Control):
+
+```javascript
+// Permission record in database
+{
+  user_id: 'uuid-123',
+  subject: 'invoices',
+  action: '*'           // Wildcard: all actions on 'invoices'
+}
+
+// Or specific action
+{
+  user_id: 'uuid-123',
+  subject: 'invoices',
+  action: 'delete'      // Only delete permission
+}
+```
+
+### In Routes
+
+```javascript
+// Require any permission on subject
+auth([{ subject: 'invoices' }])
+
+// Require specific action
+auth([{ subject: 'invoices', action: 'delete' }])
+
+// Require one of multiple permissions (OR logic between entries)
+auth([{ subject: 'invoices' }, { subject: 'admin' }])
+
+// No permission check, just authentication
+auth([])
+```
+
+A user with `action: '*'` on a subject automatically passes any action check for that subject.
+
+---
+
+## Creating Custom Middleware
+
+Follow the same factory pattern:
+
+```javascript
+/** @param {ServicesMap} services @generated-types */
+module.exports = function (services) {
+  return async (req, res, next) => {
+    try {
+      // Custom logic (e.g., rate limiting, logging, feature flags)
+      const feature = await services.FeaturesServices.getWhere(
+        'name', 'new-dashboard', { firstOnly: true }
+      );
+
+      req.featureFlags = { newDashboard: feature?.enabled || false };
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+};
+```
+
+### Webhook Signature Validation
+
+```javascript
+module.exports = function (services) {
+  return async (req, res, next) => {
+    const secret = req.headers.authorization;
+
+    if (process.env.NODE_ENV === 'development') {
+      return next(); // Skip in development
+    }
+
+    if (secret !== process.env.ENDPOINT_SECRET) {
+      ApiError(StatusCodes.FORBIDDEN, 'Invalid webhook signature', undefined, next);
+      return;
+    }
+
+    next();
+  };
+};
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the file:** `src/middlewares/{name}.middleware.js`
+2. **Use the template:**
+   ```javascript
+   /** @param {ServicesMap} services @generated-types */
+   module.exports = function (services) {
+     return async (req, res, next) => {
+       try {
+         // Middleware logic
+         next();
+       } catch (error) {
+         next(error);
+       }
+     };
+   };
+   ```
+3. **Apply in routes:**
+   ```javascript
+   const customMiddleware = require('@/middlewares/custom.middleware')(services);
+   router.get('/', customMiddleware, controller.getAll.bind(controller));
+   ```
+
+---
+
+## Anti-patterns
+
+- **Do NOT put business logic in middleware.** Keep middleware focused on cross-cutting concerns.
+- **Do NOT forget to call `next()`** — missing `next()` hangs the request.
+- **Do NOT catch errors without re-throwing or calling `next(error)`.**
+- **Do NOT duplicate auth logic.** Use the auth middleware factory, don't create parallel auth checks.
+- **Do NOT access `req.body` for auth decisions.** Auth should use headers only.
+
+---
+
+## Checklist
+
+When creating or modifying middleware:
+
+- [ ] File is named `{name}.middleware.js`
+- [ ] File is in `src/middlewares/`
+- [ ] Exports a factory function `(services) => middleware`
+- [ ] Has correct `@generated-types` JSDoc annotation
+- [ ] Always calls `next()` or `next(error)`
+- [ ] Error paths use `ApiError()` with appropriate status codes
+- [ ] Does not contain business logic
+- [ ] Auth middleware correctly validates both JWT and API key paths

package/lib/cli/documentation-templates/10-integrations.md

@@ -0,0 +1,332 @@
+# Integrations
+
+## Role
+
+Integrations are **wrappers around external services**. They abstract third-party APIs (Stripe, AWS, Postmark, Google, etc.) into clean internal interfaces.
+
+**What integrations do:**
+- Encapsulate external API calls
+- Normalize error handling
+- Manage API credentials via environment variables
+- Provide reusable methods for common operations
+
+**What integrations do NOT do:**
+- Contain business logic (that's services)
+- Handle HTTP requests (that's controllers)
+- Get auto-loaded by the framework (they're manually imported)
+
+---
+
+## Location & Naming
+
+```
+src/integrations/
+├── stripe.js                    # Payment processor
+├── aws.js                      # S3 file storage
+├── google.js                   # OAuth integration
+├── cnpj.js                     # External data lookup
+├── openai.js                   # AI API
+├── postmark/                   # Complex integration (directory)
+│   ├── index.js                # Main Postmark class
+│   └── templates/              # Email templates
+│       ├── welcome.html
+│       └── invoice.html
+├── focus-nfe/                  # Another complex integration
+│   ├── index.js
+│   └── schemas/
+└── apps/                       # Webhook handlers for multiple platforms
+    ├── webhooks/
+    │   ├── stripe.js
+    │   ├── shopify.js
+    │   └── ...
+    └── schemas/
+```
+
+**Naming convention:** `{service-name}.js` for simple integrations, `{service-name}/index.js` for complex ones with related files.
+
+---
+
+## Standard Patterns
+
+### Class-Based Integration (most common)
+
+```javascript
+const axios = require('axios');
+
+class StripeIntegration {
+  constructor() {
+    this.stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
+  }
+
+  async createCustomer(email, name) {
+    return this.stripe.customers.create({ email, name });
+  }
+
+  async createPaymentIntent(amount, currency = 'brl') {
+    return this.stripe.paymentIntents.create({
+      amount,
+      currency,
+      automatic_payment_methods: { enabled: true },
+    });
+  }
+}
+
+module.exports = new StripeIntegration();
+```
+
+### Singleton Export
+
+Most integrations export a singleton instance:
+
+```javascript
+module.exports = new StripeIntegration();
+
+// Used as:
+const stripe = require('@/integrations/stripe');
+await stripe.createCustomer(email, name);
+```
+
+### AWS S3 Pattern
+
+```javascript
+const { S3Client } = require('@aws-sdk/client-s3');
+const { Upload } = require('@aws-sdk/lib-storage');
+
+class AWS {
+  constructor() {
+    this.s3 = new S3Client({
+      region: process.env.AWS_REGION,
+      credentials: {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      },
+    });
+  }
+
+  async uploadToS3(bucket, { filename, file }) {
+    const upload = new Upload({
+      client: this.s3,
+      params: {
+        Bucket: bucket,
+        Key: filename,
+        Body: file,
+        ACL: 'public-read',
+      },
+    });
+
+    const { Location } = await upload.done();
+    return Location;  // Returns the public URL
+  }
+
+  async uploadToS3FromUrl(bucket, url, filename) {
+    const response = await axios.get(url, {
+      responseType: 'arraybuffer',
+      timeout: 240000,
+    });
+    return this.uploadToS3(bucket, { filename, file: response.data });
+  }
+}
+
+module.exports = new AWS();
+```
+
+### Email Service Pattern (Postmark)
+
+```javascript
+const postmark = require('postmark');
+
+class Postmark {
+  constructor() {
+    this.client = new postmark.ServerClient(process.env.POSTMARK_API_KEY);
+  }
+
+  filterInvalidRecipients(recipientsList) {
+    return recipientsList.filter(r => r.Email || r.email);
+  }
+
+  async sendMail(templateName, recipientsList) {
+    recipientsList = this.filterInvalidRecipients(recipientsList);
+    if (!recipientsList.length) return [];
+
+    const Messages = recipientsList.map(r => ({
+      From: 'contact@yourdomain.com',
+      To: r.Email || r.email,
+      TemplateAlias: templateName,
+      TemplateModel: r.TemplateModel || r.variables || {},
+      Attachments: r.Attachments || r.attachments || [],
+    }));
+
+    // Chunk sending (Postmark limit: 500 per batch)
+    const chunkSize = 400;
+    const responses = [];
+    for (let i = 0; i < Messages.length; i += chunkSize) {
+      const chunk = Messages.slice(i, i + chunkSize);
+      const response = await this.client.sendEmailBatchWithTemplates(chunk);
+      responses.push(...response);
+    }
+
+    return responses;
+  }
+}
+
+module.exports = new Postmark();
+```
+
+### External Database Connection
+
+```javascript
+const knex = require('knex');
+
+const externalDb = knex({
+  client: 'mysql2',
+  connection: {
+    host: process.env.EXTERNAL_DB_HOST,
+    user: process.env.EXTERNAL_DB_USER,
+    password: process.env.EXTERNAL_DB_PASSWORD,
+    database: process.env.EXTERNAL_DB_NAME,
+    port: process.env.EXTERNAL_DB_PORT,
+  },
+  pool: { min: 2, max: 10 },
+});
+
+module.exports = externalDb;
+```
+
+---
+
+## Usage in Services and Controllers
+
+Integrations are imported directly where needed:
+
+```javascript
+// In a service
+const aws = require('@/integrations/aws');
+const postmark = require('@/integrations/postmark');
+
+module.exports = (model, models, io) => class extends model {
+  async createAndNotify(data) {
+    const record = await this.create(data);
+
+    // Upload file
+    if (data.file) {
+      const url = await aws.uploadToS3(process.env.S3_BUCKET, {
+        filename: `${record.data.id}/file.pdf`,
+        file: data.file,
+      });
+      await this.updateWhere('id', record.data.id, { file_url: url });
+    }
+
+    // Send notification
+    await postmark.sendMail('record-created', [{
+      Email: data.email,
+      TemplateModel: { name: data.name },
+    }]);
+
+    return record;
+  }
+};
+```
+
+---
+
+## Error Handling
+
+Wrap external calls to provide clean error messages:
+
+```javascript
+async createCustomer(email) {
+  try {
+    return await this.stripe.customers.create({ email });
+  } catch (error) {
+    // Log the original error for debugging
+    console.error('Stripe error:', error.message);
+
+    // Throw a clean error for the service layer
+    throw new Error(`Failed to create Stripe customer: ${error.message}`);
+  }
+}
+```
+
+For errors that should stop the request with a user-facing message:
+
+```javascript
+const { ApiError, StatusCodes } = require('@/utils');
+
+async lookupCNPJ(cnpj) {
+  try {
+    const { data } = await axios.get(`https://api.example.com/cnpj/${cnpj}`);
+    return data;
+  } catch (error) {
+    if (error.response?.status === 404) {
+      ApiError(StatusCodes.NOT_FOUND, 'CNPJ not found');
+    }
+    throw error;  // Let other errors bubble up to Sentry
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+Every integration should use environment variables for credentials:
+
+```
+# .env
+STRIPE_SECRET_KEY="sk_live_..."
+AWS_ACCESS_KEY_ID="AKIA..."
+AWS_SECRET_ACCESS_KEY="..."
+AWS_REGION="us-east-1"
+POSTMARK_API_KEY="..."
+GOOGLE_CLIENT_ID="..."
+GOOGLE_CLIENT_SECRET="..."
+```
+
+Never hardcode API keys, URLs, or credentials in integration files.
+
+---
+
+## Creating from Scratch
+
+1. **Create the file:** `src/integrations/{service-name}.js`
+2. **Define the class:**
+   ```javascript
+   class ServiceName {
+     constructor() {
+       // Initialize client with env vars
+     }
+
+     async methodName(params) {
+       // Wrap API call with error handling
+     }
+   }
+
+   module.exports = new ServiceName();
+   ```
+3. **Add environment variables** to `.env` and `.env.example`
+4. **Import in services/controllers** as needed
+
+---
+
+## Anti-patterns
+
+- **Do NOT hardcode credentials.** Always use environment variables.
+- **Do NOT put business logic in integrations.** They are pure API wrappers.
+- **Do NOT expose raw external errors to clients.** Catch and wrap with clean messages.
+- **Do NOT create integrations that import services.** Integrations are lower-level — services import integrations, not the reverse.
+- **Do NOT forget timeout configuration** for HTTP calls to external services.
+
+---
+
+## Checklist
+
+When creating a new integration:
+
+- [ ] File is in `src/integrations/`
+- [ ] Uses environment variables for all credentials
+- [ ] Env vars documented in `.env.example`
+- [ ] Exports a singleton instance (or class for multiple-instance use)
+- [ ] Error handling wraps external errors cleanly
+- [ ] HTTP calls have timeout configuration
+- [ ] No business logic — pure API abstraction
+- [ ] No circular dependencies with services