codeninja 2.0.0

package/tasks/generate-app.task.md

@@ -0,0 +1,146 @@
+---
+type: task
+name: generate-app
+agent: nodejs-agent
+---
+
+# File: app.js
+
+## Purpose
+Express application entry point. Loads environment variables, configures
+all middleware in the correct order, registers versioned routes, and starts
+the HTTP server. This is the first file Node.js executes when the service
+starts.
+
+---
+
+## Dependencies to Import
+
+- `dotenv` — called as `require('dotenv').config()` on the very first
+  line before any other import. This ensures all process.env values are
+  available to every module that loads after it.
+- `express` — the web framework.
+- `cors` — only imported if `client_type == "reactjs"`. Mobile/app
+  clients do not use browser CORS. If `client_type == "app"` — do not
+  import or use cors at all.
+- `./logger/logging` — imported as `log`. Used for startup success and
+  startup failure messages only.
+- `./modules/v1/route_manager` — the versioned router that mounts all
+  module routes and runs the middleware chain.
+
+No other imports. app.js does not import headerValidator, encryption,
+response, or any module directly — those are all handled inside
+route_manager.
+
+---
+
+## CORS Configuration (client_type == "reactjs" only)
+
+When `client_type == "reactjs"`, CORS must be configured with an allowed
+origins list read from environment variables.
+
+The allowed origins list is built from `process.env.ALLOWED_ORIGINS`.
+This value is a comma-separated string in `.env`. Parse it by splitting
+on commas and trimming each entry. Store as an array.
+
+Always include `http://localhost:3000` and `http://127.0.0.1:3000` in
+the allowed origins list in addition to whatever is in the environment
+variable. These are development defaults and must always be present.
+
+The CORS configuration function receives `origin` and `callback`:
+- If `origin` is undefined or null — allow the request. This covers
+  server-to-server calls and tools like Postman/curl that send no Origin
+  header.
+- If `origin` is in the allowed origins array — call `callback(null, true)`.
+- If `origin` is not in the list — call `callback(new Error('Not allowed
+  by CORS'))`. Do not send a response here — Express handles the error.
+
+Set `credentials: true` in the CORS options. This allows the client to
+send cookies and authorization headers in cross-origin requests.
+
+When `client_type == "app"` — skip CORS entirely. No import, no
+configuration, no `app.use(cors(...))` line.
+
+---
+
+## Body Parser Configuration
+
+The body parser setup depends on `encrypted_transport`:
+
+If `encrypted_transport == true`:
+  The entire request body is an encrypted cipher string — it arrives as
+  plain text, not as a JSON object. Express must be configured to parse
+  it as text first so the decryption middleware receives a string.
+  Apply in this order:
+  1. `express.text()` — parses body as a raw string regardless of
+     Content-Type. This catches the encrypted payload.
+  2. `express.json()` — still included as fallback for any internal or
+     tooling requests that send JSON directly.
+  3. `express.urlencoded({ extended: false })` — for form submissions.
+
+If `encrypted_transport == false`:
+  Request bodies are plain JSON. Only apply:
+  1. `express.json()`
+  2. `express.urlencoded({ extended: false })`
+  Do not apply `express.text()` — it would interfere with JSON parsing.
+
+---
+
+## Middleware and Route Registration Order
+
+Apply middleware and routes in this exact sequence:
+
+1. Body parsers (as described above based on encrypted_transport)
+2. CORS (if client_type == "reactjs")
+3. Route registration: `app.use('/api/v1', route_manager)`
+
+The headerValidator middleware chain (extractLanguage, validateApiKey,
+validateToken, decryptRequest) is NOT applied in app.js. It is applied
+inside route_manager.js. app.js only applies global infrastructure
+middleware — body parsing and CORS.
+
+---
+
+## Server Startup
+
+Define an async function called `launchApp`. This is the only async
+function in the file.
+
+Inside `launchApp`:
+1. Read the port from `process.env.PORT`. If not set, use a fallback
+   default port from `process.env.PROJECT_NAME` context — agent reads
+   `context.services[<name>].port` and uses it as the hardcoded fallback.
+   Never use an arbitrary number like 3000 or 7001 — always use the
+   port from context.
+2. Call `app.listen(port, callback)`. In the callback — call
+   `log.info` with the service name and port number. Use
+   `process.env.PROJECT_NAME` for the service name in the log message.
+3. Wrap in try/catch. On any error — call `log.critical` with the
+   service name and error object, then call `process.exit(1)`.
+
+Call `launchApp()` at the bottom of the file. No export — this file
+is never required by another file.
+
+---
+
+## .env additions required by this file
+
+Add to the `.env` template in nodejs-agent:
+```
+ALLOWED_ORIGINS=https://yourfrontend.com,https://yourstaging.com
+```
+This key is only relevant when `client_type == "reactjs"`. When
+`client_type == "app"` this line is omitted from `.env`.
+
+---
+
+## What This File Does NOT Do
+
+- Does not import or configure helmet — security headers are not applied
+  at this level in this codebase
+- Does not define any routes directly — all routes go through route_manager
+- Does not import headerValidator — middleware chain is route_manager's
+  responsibility
+- Does not handle errors globally with `app.use((err, req, res, next)=>{})`
+  — errors propagate through the asyncHandler wrapper in route_manager
+- Does not export `app` — this file is the entry point, not a module

package/tasks/generate-common.task.md

@@ -0,0 +1,330 @@
+---
+type: task
+name: generate-common
+agent: nodejs-agent
+---
+
+# File: config/common.js
+
+## Purpose
+Shared utility object containing functions used across the entire service.
+Imported by model files, notification.js, and any file that needs device
+info management, generic DB operations, session generation, or OTP
+generation. All database-touching functions use the query interface from
+config/database.js. The object is named `common` and exported directly.
+
+---
+
+## Dependencies to Import
+
+- `./database` — imported as `con`. Used by all database functions.
+- `./constants` — imported as `GLOBALS`. Available for any function
+  that needs app-wide constants.
+- `pg-format` — imported as `format`. Used to safely build dynamic SQL
+  queries with variable column names and values. Never used for query
+  execution — only for building query strings that are then passed to
+  `con.query`.
+- `../logger/logging` — imported as `log`. Used for error and info
+  logging in all functions.
+- `jsonwebtoken` — imported as `jwt`. Used in `generateSessionCode` for
+  JWT signing.
+- `../utilities/ioRedis` — imported as `redis`. Used in
+  `generateSessionCode` to store the session version.
+- `moment` — imported as `moment`. Available for date formatting in
+  utility functions.
+
+---
+
+## The common Object
+
+All functions are methods of a single plain object named `common`.
+Not a class — a plain object literal. All methods are async unless
+explicitly noted as synchronous.
+
+---
+
+## Functions
+
+---
+
+### async generateSessionCode(user_id, user_type)
+
+**Purpose**: Generates a signed JWT token for a user session, persists
+device info with version to the database, and stores the version in
+Redis. This is the single function called by login and signup model
+functions to create a new session. Returns the signed JWT string.
+
+**Parameters**:
+- `user_id` — numeric user identifier
+- `user_type` — string indicating the user role or type
+
+**Flow**:
+
+1. Determine the new session version:
+   Query Redis using `redis.get(user_id.toString())`.
+   If a value exists — parse it as integer and add 1. This is the new
+   version.
+   If no value exists (first login ever) — version is 1.
+   Store the new version in the string `newVersion`.
+
+2. Build the JWT payload object with exactly three keys:
+   - `user_id` — the user_id parameter
+   - `user_type` — the user_type parameter
+   - `version` — newVersion integer
+
+3. Sign the JWT:
+   Call `jwt.sign(payload, process.env.KEY, { algorithm: 'HS256' })`.
+   Note: this uses HMAC-SHA256 with the KEY from .env as the secret —
+   not RSA PEM keys. No expiration is set — session invalidation is
+   handled entirely by the Redis version mechanism.
+   Store the signed token string as `jwtToken`.
+
+4. Store the new version in Redis:
+   Call `redis.set(user_id.toString(), newVersion.toString())`.
+   No expiry. The Redis key persists until logout increments the version.
+
+5. Check if device info already exists for this user:
+   Call `await this.checkDeviceInfo(user_id, user_type)`.
+   Store result as `deviceinfo`.
+
+6. If `deviceinfo` is not null — a record already exists:
+   Call `await this.updateDeviceInfo(user_id, user_type, { token: jwtToken, version: newVersion })`.
+
+7. If `deviceinfo` is null — no record exists yet:
+   Call `await this.addDeviceInformation({ token: jwtToken, user_id, user_type, version: newVersion })`.
+
+8. Return `jwtToken`.
+
+---
+
+### async checkDeviceInfo(user_id, user_type)
+
+**Purpose**: Checks whether a device info record exists for the given
+user_id and user_type combination in `tbl_user_deviceinfo`.
+
+**Parameters**:
+- `user_id` — numeric user identifier
+- `user_type` — string role/type
+
+**Flow**:
+
+1. Build parameterized query selecting all columns from
+   `tbl_user_deviceinfo` where `user_id = $1 AND user_type = $2`.
+   Values array: `[user_id, user_type]`.
+
+2. Call `con.query(queryText, values)` inside a try/catch.
+
+3. On success:
+   If `result.rowCount > 0` — return `result.rows[0]` (the first row
+   object).
+   If `result.rowCount === 0` — return `null`.
+
+4. On error — log at error level with function name and error. Return
+   `null`. Never throw.
+
+---
+
+### async updateDeviceInfo(user_id, user_type, params)
+
+**Purpose**: Updates the device info record for the given user_id and
+user_type with the provided field values.
+
+**Parameters**:
+- `user_id` — numeric user identifier
+- `user_type` — string role/type
+- `params` — plain object where keys are column names and values are
+  the new values to set
+
+**Flow**:
+
+1. Build the SET clause dynamically using `pg-format`:
+   Iterate `Object.entries(params)`, format each pair as
+   `format("%I = %L", key, val)`, join with `, `.
+
+2. Build the full UPDATE query using `format`:
+   `UPDATE tbl_user_deviceinfo SET <setClause> WHERE user_id = <user_id>
+   AND user_type = <user_type>`
+   Use `%L` for user_id and user_type values in the WHERE clause.
+
+3. Call `con.query(queryText)` inside a try/catch. No values array —
+   the query is fully constructed by pg-format.
+
+4. On success — return `result.rowCount`.
+
+5. On error — log at error level with function name and error. Return
+   `null`.
+
+---
+
+### async addDeviceInformation(params)
+
+**Purpose**: Inserts a new record into `tbl_user_deviceinfo` with the
+provided field values. Returns the new record's id.
+
+**Parameters**:
+- `params` — plain object where keys are column names and values are
+  the values to insert. Must include at minimum: `user_id`, `user_type`,
+  `token`, `version`.
+
+**Flow**:
+
+1. Extract keys and values from the params object.
+   Build `columns` string by joining keys with `, `.
+   Build `placeholders` string as `$1, $2, $3...` matching key count.
+
+2. Build the INSERT query using `format`:
+   `INSERT INTO tbl_user_deviceinfo (<columns>) VALUES (<placeholders>)
+   RETURNING id`
+   Use `format` only for the column names — use parameterized
+   placeholders for values.
+
+3. Call `con.query(queryText, valuesArray)` inside a try/catch.
+
+4. On success — return `result.rows[0].id`.
+
+5. On error — log at error level. Return `null`.
+
+---
+
+### async checkUpdateDeviceInfo(user_id, user_type, params)
+
+**Purpose**: Updates or creates the device info record for a user with
+device-specific fields. Used by login to persist device metadata
+separately from the token update.
+
+**Parameters**:
+- `user_id` — numeric user identifier
+- `user_type` — string role/type
+- `params` — object containing device fields from the request body
+
+**Flow**:
+
+1. Build `upd_device` object with these keys using nullish coalescing
+   for optional fields:
+   - `uuid` from `params.uuid` — default empty string
+   - `ip` from `params.ip` — default empty string
+   - `os_version` from `params.os_version` — default empty string
+   - `model_name` from `params.model_name` — default empty string
+   - `device_type` from `params.device_type` — no default, required
+   - `device_token` from `params.device_token` — default empty string
+
+2. Call `await this.checkDeviceInfo(user_id, user_type)`.
+
+3. If record exists — call `await this.updateDeviceInfo(user_id,
+   user_type, upd_device)`. Return the result.
+
+4. If record does not exist — add `user_id` and `user_type` to
+   `upd_device`, then call `await this.addDeviceInformation(upd_device)`.
+   Return the result.
+
+---
+
+### isEmptyObject(obj)
+
+**Purpose**: Synchronous helper. Returns true if the given object has
+no own enumerable keys, false otherwise.
+
+**Parameters**:
+- `obj` — any value, expected to be a plain object
+
+**Flow**:
+Return `!Object.keys(obj).length`.
+This is the only synchronous function in the object. Not async.
+
+---
+
+### async randomOtpGenerator()
+
+**Purpose**: Generates a random 4-digit integer for use as an OTP code.
+
+**Flow**:
+Return `Math.floor(1000 + Math.random() * 9000)`.
+Range is always 1000–9999 inclusive. Never returns a 3-digit number.
+
+---
+
+### async createRecords(tablename, records)
+
+**Purpose**: Generic INSERT helper. Inserts a single record into any
+table and returns the new record's id. Used by model files for simple
+single-row inserts where no special logic is needed.
+
+**Parameters**:
+- `tablename` — the target table name string
+- `records` — plain object where keys are column names and values are
+  the values to insert
+
+**Flow**:
+
+1. Extract keys and values from `records`.
+2. Build columns and parameterized placeholders the same way as
+   `addDeviceInformation`.
+3. Build query: `INSERT INTO <tablename> (<columns>) VALUES
+   (<placeholders>) RETURNING id`
+   Use `format` for column names only. Use parameterized values.
+4. Call `con.query(queryText, valuesArray)` in try/catch.
+5. On success — return `result.rows[0].id`.
+6. On error — log at error level. Return `null`.
+
+---
+
+### async updateRecords(tablename, updparams, where)
+
+**Purpose**: Generic UPDATE helper. Updates records in any table
+matching the given WHERE clause string. Returns the number of rows
+affected.
+
+**Parameters**:
+- `tablename` — the target table name string
+- `updparams` — plain object of column names and new values
+- `where` — raw SQL WHERE clause string without the WHERE keyword.
+  Example: `"user_id = 42 AND is_deleted = FALSE"`
+  Caller is responsible for constructing a safe WHERE clause.
+
+**Flow**:
+
+1. Build SET clause using `pg-format` the same way as `updateDeviceInfo`.
+2. Build query: `UPDATE <tablename> SET <setClause> WHERE <where>`
+3. Call `con.query(queryText)` in try/catch.
+4. On success — log at info level with rowCount. Return `result.rowCount`.
+5. On error — log at error level. Return `null`.
+
+---
+
+### async insertNotification(notification)
+
+**Purpose**: Stub function. Placeholder for persisting notification
+records to the database. Returns `true` always. Developer implements
+the actual insert logic when the notifications table is created.
+
+**Parameters**:
+- `notification` — the notification object. Received but not used in
+  the stub.
+
+**Flow**:
+Log at info level: insertNotification stub called.
+Return `true`.
+
+---
+
+## Export
+```
+module.exports = common
+```
+
+The plain object is exported directly. Imported everywhere as:
+`const common = require('../config/common')`
+or
+`const common = require('./common')` depending on caller depth.
+
+---
+
+## What This File Does NOT Do
+
+- Does not import encryption utilities — no crypto operations here
+- Does not import response.js — no req/res objects in any function
+- Does not define business logic — only shared infrastructure helpers
+- Does not validate input parameters — callers are responsible for
+  passing correct values
+- Does not throw from any function — all errors are caught, logged,
+  and return null

package/tasks/generate-constants.task.md

@@ -0,0 +1,123 @@
+---
+type: task
+name: generate-constants
+agent: nodejs-agent
+---
+
+# File: config/constants.js
+
+## Purpose
+Defines all application-wide constant values in a single frozen object
+exported as GLOBALS. Every file in the service that needs a shared
+constant imports this module. No magic strings or hardcoded values exist
+anywhere else in the codebase — they all live here. The object is frozen
+using Object.freeze so no file can accidentally mutate it at runtime.
+
+---
+
+## Dependencies
+
+No imports from within the service. Only reads from process.env which
+is already loaded by dotenv in app.js before this module is required.
+
+Two intermediate variables are derived from process.env before the
+GLOBALS object is built, because multiple keys inside GLOBALS depend
+on them:
+
+### BASE_URL
+Read from `process.env.BASE_URL`. Default to empty string if absent.
+Used to construct all image URL constants that are served from the
+base domain.
+
+### S3_BUCKET_ROOT
+Read from `process.env.S3_BUCKET_ROOT`. Default to empty string if
+absent. Used to construct all S3-hosted asset path constants.
+
+---
+
+## GLOBALS Object
+
+Built as a single Object.freeze call. Keys and their values:
+
+### Identity
+- `APP_NAME` — the human-readable name of the service. Read from
+  `process.env.PROJECT_NAME`. This is the same value as the service
+  name set during `@initialize-project`. Used in email templates,
+  log messages, and push notification titles.
+
+### Security
+- `API_KEY` — the expected API key value for incoming request validation.
+  Read from `process.env.API_KEY`.
+- `KEY` — the AES encryption key. Read from `process.env.KEY`.
+- `IV` — the AES initialization vector. Read from `process.env.IV`.
+
+### URLs
+- `BASE_URL` — the intermediate variable value. The base domain URL
+  for this service. Used to construct asset URLs.
+- `S3_BUCKET_ROOT` — the intermediate variable value. Root path for
+  all S3-hosted assets.
+
+### Image Paths
+- `LOGO` — constructed as `BASE_URL + 'images/logo_white.png'`. Used
+  in email templates as the header logo.
+- `MESSAGE_LOGO` — constructed as `BASE_URL + 'images/email.png'`.
+  Used as a secondary email image asset.
+- `ARROW_IMAGE` — constructed as `BASE_URL + 'images/arrow-right.gif'`.
+  Used in email templates for directional visual elements.
+- `USER_IMAGE` — constructed as `S3_BUCKET_ROOT + 'users/'`. The S3
+  prefix path for all user-uploaded profile images.
+
+### Pagination
+- `PER_PAGE` — default page size for all paginated queries. Value is
+  the string `'100'`. Stored as a string, not a number, for direct
+  use in query parameter comparisons.
+
+### Firebase
+- `FIREBASE_ADMIN_JSONFILE` — the relative path to the Firebase service
+  account credentials file. Value is `'./pem/service-file.json'`.
+  This file is gitignored and must be manually placed by the developer.
+
+### App Store Links
+- `ANDROID_APP` — URL to the Android app store listing. Default value
+  is `'#'` as a placeholder. Developer replaces when the app is
+  published.
+- `IOS_APP` — URL to the iOS app store listing. Default value is `'#'`.
+
+### Legal and Email Links
+- `UNSUBSCRIBE` — base URL for the email unsubscribe endpoint. Default
+  `'#'`. The full unsubscribe URL is constructed in templates by
+  appending the encoded user ID.
+- `TERMS_OF_USE` — URL to the terms of use page. Default `'#'`.
+- `PRIVACY_POLICY` — URL to the privacy policy page. Default `'#'`.
+
+---
+
+## .env additions required by this file
+
+Add to the `.env` template in nodejs-agent:
+```
+BASE_URL=https://yourservice.com/
+S3_BUCKET_ROOT=https://yourbucket.s3.amazonaws.com/
+```
+
+---
+
+## Export
+```
+module.exports = Globals;
+```
+
+The frozen object is exported directly. Imported everywhere as:
+`const GLOBALS = require('../config/constants')`
+
+---
+
+## What This File Does NOT Do
+
+- Does not import from any other file in the service
+- Does not contain any functions or logic — values only
+- Does not define HTTP status codes — those belong in a separate
+  constants section if needed, not in this file
+- Does not define route paths — those are defined inline in route.js
+  files
+- Does not mutate after load — Object.freeze enforces this