codeninja 2.0.0

package/tasks/generate-notification.task.md

@@ -0,0 +1,251 @@
+---
+type: task
+name: generate-notification
+agent: nodejs-agent
+---
+
+# File: utilities/notification.js
+
+## Purpose
+Provides all outbound notification capabilities for the service in one
+place. Covers three channels: email via nodemailer, SMS as a stubbed
+function for future integration, and push notifications via Firebase
+Cloud Messaging. Implemented as a class with all methods async. A single
+instance is exported.
+
+---
+
+## Dependencies to Import
+
+- `firebase-admin` — imported as `admin`. Used for FCM push
+  notifications.
+- `fs` — Node.js built-in. Used to read the Firebase service account
+  credentials file.
+- `nodemailer` — imported as `nodemailer`. Used for sending emails.
+- `../config/constants` — imported as `GLOBALS`. Used for APP_NAME,
+  FIREBASE_ADMIN_JSONFILE, LOGO, and other branding values.
+- `../config/common` — imported as `common`. Used for the
+  `insertNotification` helper to persist notification records.
+- `../logger/logging` — imported as `logger`. Used throughout for
+  info and error logging.
+- `../utilities/response` — imports `{ getMessage }`. Used to resolve
+  push notification message text from language keys. Never import
+  localizify or call t() directly in this file.
+
+---
+
+## Module-Level Setup
+
+### Firebase Initialization
+Before the class definition, at module level:
+
+1. Read the Firebase service account credentials file:
+   Use `fs.readFileSync(GLOBALS.FIREBASE_ADMIN_JSONFILE, 'utf8')` and
+   parse with `JSON.parse`. Store as `serviceAccount`.
+
+2. Initialize Firebase Admin SDK:
+   Call `admin.initializeApp({ credential: admin.credential.cert(serviceAccount) })`.
+
+This happens once at module load. If the service file is missing, the
+require will throw at startup — this is correct behavior. Firebase must
+be configured before the service starts.
+
+### Nodemailer Transporter
+At module level, after Firebase init, create a nodemailer transporter:
+Call `nodemailer.createTransport()` with SMTP configuration read from
+process.env:
+- `host` from `process.env.SMTP_HOST`
+- `port` from `process.env.SMTP_PORT` parsed as integer
+- `secure` — set to `true` if SMTP_PORT is 465, otherwise `false`
+- `auth` object with:
+  - `user` from `process.env.SMTP_USER`
+  - `pass` from `process.env.SMTP_PASSWORD`
+
+Store as module-level `transporter` constant.
+
+---
+
+## Class: Notification
+
+---
+
+### async sendEmail(to, subject, htmlContent)
+
+**Purpose**: Sends a transactional HTML email using the nodemailer
+transporter configured at module load.
+
+**Parameters**:
+- `to` — recipient email address string
+- `subject` — email subject line string
+- `htmlContent` — the complete HTML string, typically produced by a
+  template function from `config/template.js`
+
+**Flow**:
+
+1. Build the mail options object:
+   - `from` — constructed as `"APP_NAME <SMTP_USER>"` using GLOBALS.APP_NAME
+     and process.env.SMTP_USER. This gives the email a friendly sender name.
+   - `to` — the recipient address
+   - `subject` — the subject line
+   - `html` — the htmlContent string
+
+2. Call `transporter.sendMail(mailOptions)` inside a try/catch.
+
+3. On success — log at info level: email sent, recipient address, subject.
+   Return `true`.
+
+4. On error — log at error level: failed to send email, recipient,
+   subject, and error object. Return `false`. Never throw — callers
+   check the return value.
+
+---
+
+### async sendSMS(to, message)
+
+**Purpose**: Stub function for SMS sending. Returns true always.
+Exists so model files can call it now and the real implementation
+can be added later without changing any call sites.
+
+**Parameters**:
+- `to` — recipient phone number string including country code
+- `message` — the SMS message body string
+
+**Flow**:
+
+1. Log at info level: SMS stub called, recipient, message length.
+2. Return `true`.
+
+No actual SMS sending. No external library imported. Developer adds the
+real SMS provider integration here when needed (Twilio, AWS SNS, etc.)
+by replacing this function body.
+
+---
+
+### async send_push(notification, device_type, device_token)
+
+**Purpose**: Sends a push notification to a single device using Firebase
+Cloud Messaging via the Admin SDK's `sendEachForMulticast` method.
+
+**Parameters**:
+- `lang` — language code string for the recipient's preferred language.
+  e.g. `"en"`, `"ar"`. Used by getMessage to resolve the notification
+  message in the correct language. Defaults to DEFAULT_LANGUAGE if
+  empty or not provided.
+- `notification` — object containing the notification data with these
+  expected keys:
+  - `notification_tag` — the localizify translation key for the message
+    body text
+  - `content` — object containing interpolation values for the message
+    translation. Also stored as the notification data payload.
+  - `primary_id` — primary entity ID related to this notification
+  - `secondary_id` — secondary entity ID if applicable
+  - `sender_id` — the ID of the entity that triggered this notification
+- `device_type` — string indicating the device platform (e.g. `"ios"`,
+  `"android"`). Received but not used in routing — FCM handles
+  platform differences. Kept as parameter for logging and future use.
+- `device_token` — the FCM registration token for the target device
+
+**Flow**:
+
+1. Resolve the notification message text:
+   Call `await getMessage(lang, notification.notification_tag, notification.content)`
+   from `utilities/response.js` to get the translated and interpolated
+   message string. Store as `message`.
+
+   The `lang` parameter: push notifications are sent outside the
+   request cycle so `req.lang` is not available. The caller must
+   pass the user's preferred language. Update the `send_push` function
+   signature to accept `lang` as the first parameter:
+   `async send_push(lang, notification, device_type, device_token)`
+
+   If `lang` is not provided or is empty — default to
+   `process.env.DEFAULT_LANGUAGE`.
+
+2. Serialize notification content:
+   Replace `notification.content` with `JSON.stringify(notification.content)`.
+   FCM data payloads must be string values — objects are not accepted.
+
+3. Insert notification record:
+   If `notification.notification_tag` is not `"sendmessage"` — call
+   `await common.insertNotification(notification)` to persist the
+   notification record in the database.
+
+4. Validate the device token:
+   If `device_token` is falsy or equals the string `"0"` — log at info
+   level that the token is blank and return `true`. Do not attempt to
+   send to an invalid token.
+
+5. Build the FCM payload object with these keys:
+   - `tokens` — array containing `device_token` as the only element.
+     `sendEachForMulticast` accepts an array of tokens.
+   - `notification` object with:
+     - `title` — GLOBALS.APP_NAME
+     - `body` — the resolved `message` string
+   - `data` object with these string values (all must be strings for
+     FCM data payloads, use optional chaining and `.toString()` for
+     each):
+     - `title` — GLOBALS.APP_NAME
+     - `body` — the resolved `message` string
+     - `primary_id` — notification.primary_id as string
+     - `secondary_id` — notification.secondary_id as string
+     - `sender_id` — notification.sender_id as string
+     - `tag` — notification.notification_tag as string
+   - `apns` object for iOS-specific config:
+     - `payload.aps.sound` — `"default"`
+
+6. Call `await admin.messaging().sendEachForMulticast(pushPayload)`.
+   Store result as `pushResponse`.
+
+7. Log at info level: the responses array from pushResponse for
+   debugging.
+
+8. Check the first response: `pushResponse.responses[0]?.success`
+   - If true — log at info level: notification sent successfully.
+     Return `true`.
+   - If false — log at info level: notification failed, include the
+     error from `pushResponse.responses[0]?.error`. Return `false`.
+
+9. In the outer catch block — log at error level: exception caught,
+   include error object. Return `false`. Never throw — callers check
+   the return value.
+
+---
+
+## Export
+```
+module.exports = new Notification()
+```
+
+A single instance is created and exported. The constructor has no
+logic — all setup is at module level. Imported as:
+`const notification = require('../utilities/notification')`
+
+Then used as: `notification.sendEmail(...)`, `notification.send_push(...)`
+
+---
+
+## .env additions required by this file
+
+Add to the `.env` template in nodejs-agent:
+```
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not build email HTML — that is `config/template.js`'s job.
+  This file only sends what it receives.
+- Does not define notification content or messages — those come from
+  the caller and from language files via localizify
+- Does not handle notification preferences or user opt-outs — that
+  is business logic in model files
+- Does not implement retry logic for failed sends — callers decide
+  whether to retry
+- Does not import localizify or call t() directly — all translation
+  goes through getMessage from utilities/response.js
+- Does not touch req or res — this is a utility, not a middleware

package/tasks/generate-package-json.task.md

@@ -0,0 +1,114 @@
+---
+type: task
+name: generate-package-json
+agent: nodejs-agent
+---
+
+# File: package.json
+
+## Purpose
+Defines the Node.js project metadata and all dependencies for the
+service. Generated once during `@initialize-project`. The agent reads
+context to populate the correct name, version, description, and author,
+and includes exactly the packages used across all generated files —
+no more, no less. After generation the agent outputs the install command.
+
+---
+
+## Metadata Fields
+
+- `name` — from `context.current_init.package_name`
+- `version` — `"1.0.0"`
+- `description` — from `context.current_init.description`
+- `main` — `"app.js"`
+- `author` — from `context.current_init.author`
+- `license` — `"ISC"`
+
+---
+
+## Scripts
+```json
+"scripts": {
+  "start": "node app.js",
+  "dev": "nodemon --ignore 'logger/logs/' --ignore 'document/' --ext js app.js",
+  "test": "jest --testEnvironment=node --forceExit",
+  "docker:build": "docker build -t <service_name>:latest .",
+  "docker:run": "docker run -p <port>:<port> --env-file .env <service_name>:latest",
+  "docker:stop": "docker stop $(docker ps -q --filter ancestor=<service_name>:latest)",
+  "docker:logs": "docker logs -f $(docker ps -q --filter ancestor=<service_name>:latest)"
+}
+```
+
+Replace `<service_name>` with `context.current_init.service_name` and `<port>` with `context.current_init.port`.
+
+---
+
+## Core Dependencies (always included for all NodeJS services)
+
+These are required regardless of client_type, db_type, or any other
+choice:
+
+- `express` — web framework
+- `dotenv` — environment variable loading
+- `localizify` — i18n translation
+- `moment` — date/time formatting and manipulation
+- `jsonwebtoken` — JWT signing and verification
+- `ioredis` — Redis client
+- `nodemailer` — email sending
+- `firebase-admin` — push notifications via FCM
+- `validatorjs` — request body validation
+- `pg-format` — safe dynamic SQL query building
+- `express-rate-limit` — rate limiting middleware
+- `cors` — cross-origin resource sharing
+- `helmet` — HTTP security headers (include even if not in app.js
+  currently — standard security practice)
+- `rand-token` — random token generation used in common.js
+
+---
+
+## Conditional Dependencies
+
+Include based on context values:
+
+### Based on `context.db.type`
+- If `postgresql` → include `pg`
+- If `mysql` → include `mysql2`
+- If `mongodb` → include `mongoose`
+
+### Based on `context.services[<name>].client_type`
+- If `reactjs` → include `crypto-js`
+- If `app` → include `cryptlib`
+
+---
+
+## Dev Dependencies (always included)
+```json
+"devDependencies": {
+  "nodemon": "^3.0.0",
+  "jest": "^29.0.0",
+  "supertest": "^6.0.0"
+}
+```
+
+---
+
+## After Generation
+
+The agent outputs this command in the final summary for the developer
+to run:
+```
+cd <service_name>
+npm install
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not pin exact versions — uses `^` (caret) ranges for all
+  dependencies to allow minor/patch updates
+- Does not include a `engines` field — Node version constraint is
+  out of scope for scaffolding
+- Does not include pre/post scripts
+- Does not configure Jest in package.json — a separate jest.config.js
+  can be added later if needed

package/tasks/generate-rateLimiter.task.md

@@ -0,0 +1,125 @@
+---
+type: task
+name: generate-rateLimiter
+agent: nodejs-agent
+---
+
+# File: middleware/rateLimiter.js
+
+## Purpose
+Production-grade rate limiting middleware using express-rate-limit.
+Prevents abuse by limiting the number of requests a single IP address
+can make within a configurable time window. All configuration values
+come from environment variables — nothing is hardcoded. When the limit
+is exceeded, the response follows the same shape and language system
+as all other responses in the service.
+
+---
+
+## Dependencies to Import
+
+- `express-rate-limit` — the rate limiting library. Imported as
+  `rateLimit`.
+- `../utilities/response` — imports `sendResponse` to send the
+  limit-exceeded response in the correct format with translation support.
+- `../logger/logging` — imports `log` for logging limit violations.
+
+---
+
+## Environment Variables Required
+
+The following variables must exist in `.env` and be read by this file:
+
+- `RATE_LIMIT_WINDOW_MS` — the time window in milliseconds. Example:
+  `900000` for 15 minutes. If not set, default to `900000`.
+- `RATE_LIMIT_MAX` — maximum number of requests allowed per IP within
+  the window. Example: `100`. If not set, default to `100`.
+
+Add both of these to the `.env` template in nodejs-agent.
+
+---
+
+## Functions
+
+---
+
+### rateLimiter (exported middleware)
+
+**Purpose**: Creates and exports a configured express-rate-limit
+middleware instance. Applied globally in route_manager.js before
+all other middleware.
+
+**Configuration**:
+
+1. Read `RATE_LIMIT_WINDOW_MS` from `process.env`. Parse as integer.
+   Use default `900000` if absent or not a valid number.
+
+2. Read `RATE_LIMIT_MAX` from `process.env`. Parse as integer.
+   Use default `100` if absent or not a valid number.
+
+3. Set `standardHeaders: true` — this sends `RateLimit-*` headers in
+   responses so clients can see their remaining quota. This is the
+   modern standard header format (RFC draft).
+
+4. Set `legacyHeaders: false` — disables the older `X-RateLimit-*`
+   headers. Only one format should be active at a time.
+
+5. Set `handler` — a custom async function called when a request exceeds
+   the limit. This replaces the default express-rate-limit plain text
+   response with the service's standard response format.
+
+   The handler receives `(req, res)`.
+
+   Inside the handler:
+   - Log at warning level: the IP address (`req.ip`), the path
+     (`req.path`), and a message indicating rate limit exceeded.
+   - Call `sendResponse` from `utilities/response.js` with:
+     - `req` — pass through (req.lang must be set by extractLanguage
+       which runs before this handler fires, so translation works)
+     - `res` — pass through
+     - `statusCode` — `429`
+     - `responseCode` — `"0"`
+     - `messageKeyword` — `"rest_keywords_rate_limit_exceeded"`
+     - `messageComponents` — `{}`
+     - `responseData` — `null`
+
+6. Set `keyGenerator` to use `req.ip` as the rate limit key. This is
+   the default behavior but must be explicitly set to document intent.
+   Each unique IP address gets its own counter.
+
+7. Set `skip` to a function that always returns false. This means no
+   requests are ever skipped. If future bypass logic is needed (e.g.
+   internal health check endpoints), it goes here.
+
+---
+
+## Export
+```
+module.exports = rateLimiter
+```
+
+Exported as a single middleware function, not wrapped in an object.
+Used in route_manager.js as:
+`router.use('/', asyncHandler(rateLimiter))`
+
+---
+
+## Language File Requirement
+
+Add this key to all language files (`languages/en.js` etc.):
+```
+rest_keywords_rate_limit_exceeded: "Too many requests. Please try again later."
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not use Redis for distributed rate limiting — uses in-memory
+  store only (the default for express-rate-limit). This is correct for
+  single-instance deployments. If multi-instance is needed in future,
+  a Redis store can be plugged in here.
+- Does not apply different limits to different routes — one global limit
+  for all routes. Per-route limits are out of scope.
+- Does not whitelist any IPs — all IPs are treated equally.
+- Does not log every request — only logs when a limit is exceeded.

package/tasks/generate-react-api-client.task.md

@@ -0,0 +1,169 @@
+---
+type: task
+name: generate-react-api-client
+agent: reactjs-agent
+---
+
+# File: src/api/apiClient.js
+
+## Purpose
+The single Axios instance used by all API calls in the application.
+Handles request body encryption, session token injection, response
+decryption, logout triggering, and network error handling. No other
+file in the frontend communicates with the backend directly.
+
+This file is the frontend equivalent of the backend's `headerValidator.js`
+and `response.js` combined — it is the transport layer boundary.
+
+---
+
+## Dependencies to Import
+
+- `axios` — HTTP client
+- `crypto-js` as `CryptoJS` — AES-256-CBC encryption/decryption
+- `{ logOutRedirectCall, showErrorMessage }` from
+  `../pages/common/Utils` — developer-implemented utilities for
+  logout redirect and toast/error display. The agent generates these
+  import lines; the developer implements the functions.
+
+---
+
+## Module-Level Constants
+
+### key
+Derived once at module load from `process.env.REACT_APP_KEY`.
+Parse using `CryptoJS.enc.Hex.parse(process.env.REACT_APP_KEY)`.
+Result is a CryptoJS WordArray. Store as `key`.
+
+### iv
+Derived once at module load from `process.env.REACT_APP_IV`.
+Parse using `CryptoJS.enc.Hex.parse(process.env.REACT_APP_IV)`.
+Result is a CryptoJS WordArray. Store as `iv`.
+
+Both are module-level constants. Never re-derive inside functions.
+
+---
+
+## Axios Instance
+
+Create with `axios.create()`:
+- `baseURL` — from `process.env.REACT_APP_BASE_URL`
+- Static headers:
+  - `api-key` — from `process.env.REACT_APP_API_KEY`
+  - `Accept-Language` — `'en'`
+  - `Content-Type` — `'text/plain'`
+
+The `Content-Type: text/plain` is required because the encrypted body
+is a cipher string, not JSON. The backend's Express app is configured
+with `express.text()` to receive it this way.
+
+---
+
+## Request Interceptor
+
+Applied via `axiosClient.interceptors.request.use`.
+
+Responsibilities on the fulfilled path:
+1. Encrypt `request.data` by calling `bodyEncryption(request.data, true)`
+   and replacing `request.data` with the result. The `true` flag means
+   the data should be JSON-stringified before encryption.
+2. Read `localStorage.getItem('wa_token')`. If a value is present,
+   encrypt it by calling `bodyEncryption(JSON.stringify(storedToken), false)`
+   (the `false` flag means the value is already a string — do not
+   double-stringify it). Set the result as `request.headers['token']`.
+
+Return `request`.
+
+---
+
+## Response Interceptor — Success Path
+
+Applied via `axiosClient.interceptors.response.use` fulfilled handler.
+
+Responsibilities:
+1. Call `bodyDecryption(response.data)` to get the decrypted string.
+2. If decryption returns a falsy value, return `response.data` as-is
+   without crashing.
+3. Call `JSON.parse()` on the decrypted string to get the response object.
+4. Check `parseInt(respData.code)`:
+   - If `-1` → call `logOutRedirectCall()` and return `respData`.
+     The -1 code means the session has expired or the token is invalid.
+   - If `0` → call the internal `showMessage(respData.data.message)`.
+     The 0 code means the request failed with a user-facing message.
+5. Return `respData` for all other codes.
+6. Wrap the entire handler body in a try/catch. On any error — return
+   `response.data ?? response` without rethrowing. The UI must never
+   crash because of a decryption or parsing error.
+
+---
+
+## Response Interceptor — Error Path
+
+Applied via `axiosClient.interceptors.response.use` rejected handler.
+
+Responsibilities:
+1. Log the error to console for debugging.
+2. Extract `error.response` as `res` (default to empty object if absent).
+3. If `error.code === 'ERR_NETWORK'` → call `logOutRedirectCall()` and
+   call `showErrorMessage(\`${error.code}: ${error.message}\`)`.
+4. If `res.status` is 401 → call `logOutRedirectCall()`.
+5. Return `Promise.reject(error)`.
+
+---
+
+## Internal Helper Functions
+
+These are not exported. They are only used inside this file.
+
+### showMessage(msg)
+A minimal internal logging function. Calls `console.log(msg)`.
+Used when the backend returns response code 0 with a user message.
+The developer replaces this with a proper toast/notification call as
+the project matures.
+
+### bodyEncryption(request, isStringify)
+Encrypts a value for transmission.
+
+Parameters:
+- `request` — the value to encrypt. Can be any type.
+- `isStringify` — boolean. If true, call `JSON.stringify(request ?? {})`
+  first. If false, use `request ?? ''` as the string directly.
+
+Flow:
+1. Build the payload string based on `isStringify`.
+2. Call `CryptoJS.AES.encrypt(payload, key, { iv })`.
+3. Return `.toString()` on the result — the Base64 cipher string.
+4. Wrap in try/catch. On any error return empty string `''`.
+
+### bodyDecryption(request)
+Decrypts a cipher string received from the backend.
+
+Parameters:
+- `request` — the encrypted response string. May be null.
+
+Flow:
+1. If `request` is null or undefined, return empty string `''`.
+2. Call `CryptoJS.AES.decrypt(request.toString(), key, { iv })`.
+3. Return `.toString(CryptoJS.enc.Utf8)` on the result.
+4. Wrap in try/catch. On any error return empty string `''`.
+
+---
+
+## Export
+
+Export the Axios instance as a named export:
+`export { axiosClient }`
+
+Do not use default export. `apiHandler.js` imports it as:
+`import { axiosClient } from "./apiClient"`
+
+---
+
+## What This File Does NOT Do
+
+- Does not define any API routes or endpoint paths — those are in
+  `apiHandler.js`
+- Does not handle session storage directly beyond reading `wa_token`
+  from localStorage — session management belongs in the pages layer
+- Does not import React — this is a plain JavaScript module
+- Does not apply any retry logic — failed requests propagate to the caller