te.js 2.1.3 → 2.1.4

package/docs/ammo.md

@@ -123,16 +123,36 @@ ammo.fire('Hello, World!');
 ammo.fire(200, '<h1>Hello</h1>', 'text/html');
 ```
 
+**Response structure (default, recommended)**
+
+Tejas wraps responses in a consistent envelope so clients always get the same shape. This is **enabled by default** and applies to every `fire()` call (and to `ammo.throw()`, `ammo.unauthorized()`, and other error methods, since they use `fire()` internally):
+
+```javascript
+ammo.fire(200, { id: 1, name: 'Alice' });
+// Wire: { "data": { "id": 1, "name": "Alice" } }
+
+ammo.fire(400, 'Email is required');
+// Wire: { "error": "Email is required" }
+```
+
+- **2xx** → body is wrapped as `{ data: <payload> }`
+- **4xx/5xx** → body is wrapped as `{ error: <message> }`
+- **204** and **3xx** (e.g. redirects) → no wrapping
+
+You can disable wrapping or customize the keys (`data` / `error`) via the [response config](./configuration.md#response-structure) in `tejas.config.json` or environment variables.
+
 **All signatures:**
 
-| Call | Status | Body | Content-Type |
-|------|--------|------|-------------|
+| Call | Status | Wire Body | Content-Type |
+|------|--------|-----------|-------------|
 | `fire()` | 204 | *(empty)* | — |
-| `fire("text")` | 200 | `text` | `text/plain` |
-| `fire({ json })` | 200 | JSON string | `application/json` |
-| `fire(201)` | 201 | status message | `text/plain` |
-| `fire(201, data)` | 201 | `data` | auto-detected |
-| `fire(200, html, "text/html")` | 200 | `html` | `text/html` |
+| `fire("text")` | 200 | `{ "data": "text" }` | `application/json` |
+| `fire({ json })` | 200 | `{ "data": { ... } }` | `application/json` |
+| `fire(201)` | 201 | `{ "data": "<status message>" }` | `application/json` |
+| `fire(201, data)` | 201 | `{ "data": <data> }` | `application/json` |
+| `fire(200, html, "text/html")` | 200 | `html` *(no envelope)* | `text/html` |
+
+When response structure is disabled, the Body column matches what you pass (no envelope). The table above reflects the default behaviour.
 
 After `fire()` is called, the sent data is available as `ammo.dispatchedData`.
 
@@ -243,8 +263,8 @@ import { Target, TejError } from 'te.js';
 
 const users = new Target('/users');
 
-// GET /users - List all
-// POST /users - Create new
+// GET /users - List all  → { "data": { users, page, limit } }
+// POST /users - Create new → { "data": user }
 users.register('/', async (ammo) => {
   if (ammo.GET) {
     const { page = 1, limit = 10 } = ammo.payload;
@@ -256,7 +276,7 @@ users.register('/', async (ammo) => {
     const { name, email } = ammo.payload;
     
     if (!name || !email) {
-      throw new TejError(400, 'Name and email are required');
+      throw new TejError(400, 'Name and email are required'); // → { "error": "..." }
     }
     
     const user = await createUser({ name, email });
@@ -266,15 +286,15 @@ users.register('/', async (ammo) => {
   ammo.notAllowed();
 });
 
-// GET /users/:id - Get one
-// PUT /users/:id - Update
-// DELETE /users/:id - Delete
+// GET /users/:id - Get one → { "data": user }
+// PUT /users/:id - Update → { "data": user }
+// DELETE /users/:id - Delete → 204 (no body)
 users.register('/:id', async (ammo) => {
   const { id } = ammo.payload;
   
   if (ammo.GET) {
     const user = await getUser(id);
-    if (!user) throw new TejError(404, 'User not found');
+    if (!user) throw new TejError(404, 'User not found'); // → { "error": "User not found" }
     return ammo.fire(user);
   }
   

package/docs/configuration.md

@@ -36,7 +36,7 @@ import Tejas from 'te.js';
 
 const app = new Tejas({
   port: 3000,
-  log: { http_requests: true }
+  log: { http_requests: true },
 });
 
 app.takeoff();
@@ -46,35 +46,45 @@ app.takeoff();
 
 ### Core
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
-| `entry` | `ENTRY` | string | *(auto-resolved)* | Entry file for `tejas fly`. Falls back to `package.json` `main`, then `index.js` / `app.js` / `server.js` |
-| `port` | `PORT` | number | `1403` | Server port |
-| `dir.targets` | `DIR_TARGETS` | string | `"targets"` | Directory containing `.target.js` files for auto-discovery |
+| Config Key    | Env Variable  | Type   | Default           | Description                                                                                               |
+| ------------- | ------------- | ------ | ----------------- | --------------------------------------------------------------------------------------------------------- |
+| `entry`       | `ENTRY`       | string | _(auto-resolved)_ | Entry file for `tejas fly`. Falls back to `package.json` `main`, then `index.js` / `app.js` / `server.js` |
+| `port`        | `PORT`        | number | `1403`            | Server port                                                                                               |
+| `dir.targets` | `DIR_TARGETS` | string | `"targets"`       | Directory containing `.target.js` files for auto-discovery                                                |
 
 ### Logging
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
+| Config Key          | Env Variable        | Type    | Default | Description                                             |
+| ------------------- | ------------------- | ------- | ------- | ------------------------------------------------------- |
 | `log.http_requests` | `LOG_HTTP_REQUESTS` | boolean | `false` | Log incoming HTTP requests (method, path, status, time) |
-| `log.exceptions` | `LOG_EXCEPTIONS` | boolean | `false` | Log unhandled exceptions and errors |
+| `log.exceptions`    | `LOG_EXCEPTIONS`    | boolean | `false` | Log unhandled exceptions and errors                     |
+
+### Response Structure {#response-structure}
+
+By default, Tejas wraps all success responses in `{ data: ... }` and all error responses in `{ error: ... }`. This gives clients a consistent envelope. See [Ammo — fire()](./ammo.md#fire----send-response) for examples. Disable or customize via the options below.
+
+| Config Key                 | Env Variable                | Type    | Default   | Description                                                                              |
+| -------------------------- | --------------------------- | ------- | --------- | ---------------------------------------------------------------------------------------- |
+| `response.envelopeEnabled` | `RESPONSE_ENVELOPE_ENABLED` | boolean | `true`    | Enable response envelope: wrap success in `{ data: ... }` and errors in `{ error: ... }` |
+| `response.successKey`      | `RESPONSE_SUCCESSKEY`       | string  | `"data"`  | Key used to wrap 2xx response bodies                                                     |
+| `response.errorKey`        | `RESPONSE_ERRORKEY`         | string  | `"error"` | Key used to wrap 4xx/5xx response bodies                                                 |
 
 ### Developer warnings
 
 When an endpoint is called and it has no allowed methods defined (see [Routing — Endpoint Metadata](./routing.md#endpoint-metadata)), the framework logs a warning once per path so you can restrict methods for security (405 and `Allow` header). To disable this warning:
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
-| `warn_missing_allowed_methods` | `WARN_MISSING_ALLOWED_METHODS` | boolean/string | *(warn)* | Set to `false` to disable the runtime warning for endpoints without allowed methods. |
+| Config Key                     | Env Variable                   | Type           | Default  | Description                                                                          |
+| ------------------------------ | ------------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------ |
+| `warn_missing_allowed_methods` | `WARN_MISSING_ALLOWED_METHODS` | boolean/string | _(warn)_ | Set to `false` to disable the runtime warning for endpoints without allowed methods. |
 
 Example: in `tejas.config.json` use `"warn_missing_allowed_methods": false`, or in `.env` use `WARN_MISSING_ALLOWED_METHODS=false`.
 
 ### Request Body
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
-| `body.max_size` | `BODY_MAX_SIZE` | number | `10485760` (10 MB) | Maximum request body size in bytes. Requests exceeding this receive a 413 error |
-| `body.timeout` | `BODY_TIMEOUT` | number | `30000` (30 s) | Body parsing timeout in milliseconds. Requests exceeding this receive a 408 error |
+| Config Key      | Env Variable    | Type   | Default            | Description                                                                       |
+| --------------- | --------------- | ------ | ------------------ | --------------------------------------------------------------------------------- |
+| `body.max_size` | `BODY_MAX_SIZE` | number | `10485760` (10 MB) | Maximum request body size in bytes. Requests exceeding this receive a 413 error   |
+| `body.timeout`  | `BODY_TIMEOUT`  | number | `30000` (30 s)     | Body parsing timeout in milliseconds. Requests exceeding this receive a 408 error |
 
 ### LLM configuration (feature as parent, LLM inside each feature)
 
@@ -84,31 +94,31 @@ Tejas uses a **feature-as-parent** pattern: each feature that needs an LLM has i
 
 These options configure the `tejas generate:docs` CLI command and the auto-documentation system. The **`docs.llm`** block is the LLM configuration for this feature. See [Auto-Documentation](./auto-docs.md) for full details.
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
-| `docs.dirTargets` | `DOCS_DIR_TARGETS` | string | `"targets"` | Target directory for doc generation (can differ from `dir.targets`) |
-| `docs.output` | — | string | `"./openapi.json"` | Output path for the generated OpenAPI spec |
-| `docs.title` | — | string | `"API"` | API title in the OpenAPI `info` block |
-| `docs.version` | — | string | `"1.0.0"` | API version in the OpenAPI `info` block |
-| `docs.description` | — | string | `""` | API description |
-| `docs.level` | — | number | `1` | LLM enhancement level (1–3). Higher = better docs, more tokens |
-| `docs.llm.baseURL` | `DOCS_LLM_BASE_URL` or `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint for auto-docs |
-| `docs.llm.apiKey` | `DOCS_LLM_API_KEY` or `LLM_API_KEY` | string | — | LLM provider API key for auto-docs |
-| `docs.llm.model` | `DOCS_LLM_MODEL` or `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model for auto-docs |
-| `docs.overviewPath` | — | string | `"./API_OVERVIEW.md"` | Path for the generated overview page (level 3 only) |
-| `docs.productionBranch` | `DOCS_PRODUCTION_BRANCH` | string | `"main"` | Git branch that triggers `docs:on-push` |
+| Config Key              | Env Variable                          | Type   | Default                       | Description                                                         |
+| ----------------------- | ------------------------------------- | ------ | ----------------------------- | ------------------------------------------------------------------- |
+| `docs.dirTargets`       | `DOCS_DIR_TARGETS`                    | string | `"targets"`                   | Target directory for doc generation (can differ from `dir.targets`) |
+| `docs.output`           | —                                     | string | `"./openapi.json"`            | Output path for the generated OpenAPI spec                          |
+| `docs.title`            | —                                     | string | `"API"`                       | API title in the OpenAPI `info` block                               |
+| `docs.version`          | —                                     | string | `"1.0.0"`                     | API version in the OpenAPI `info` block                             |
+| `docs.description`      | —                                     | string | `""`                          | API description                                                     |
+| `docs.level`            | —                                     | number | `1`                           | LLM enhancement level (1–3). Higher = better docs, more tokens      |
+| `docs.llm.baseURL`      | `DOCS_LLM_BASE_URL` or `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint for auto-docs                                 |
+| `docs.llm.apiKey`       | `DOCS_LLM_API_KEY` or `LLM_API_KEY`   | string | —                             | LLM provider API key for auto-docs                                  |
+| `docs.llm.model`        | `DOCS_LLM_MODEL` or `LLM_MODEL`       | string | `"gpt-4o-mini"`               | LLM model for auto-docs                                             |
+| `docs.overviewPath`     | —                                     | string | `"./API_OVERVIEW.md"`         | Path for the generated overview page (level 3 only)                 |
+| `docs.productionBranch` | `DOCS_PRODUCTION_BRANCH`              | string | `"main"`                      | Git branch that triggers `docs:on-push`                             |
 
 ### Error handling (LLM-inferred errors)
 
 When [LLM-inferred error codes and messages](./error-handling.md#llm-inferred-errors) are enabled, the **`errors.llm`** block configures the LLM used for inferring status code and message when you call `ammo.throw()` without explicit code or message. Unset values fall back to `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`. You can also enable (and optionally set connection options) by calling **`app.withLLMErrors(config?)`** before `takeoff()` — e.g. `app.withLLMErrors()` to use env/config for baseURL, apiKey, model, or `app.withLLMErrors({ baseURL, apiKey, model, messageType })` to override in code.
 
-| Config Key | Env Variable | Type | Default | Description |
-|------------|-------------|------|---------|-------------|
-| `errors.llm.enabled` | `ERRORS_LLM_ENABLED` or `LLM_*` (for connection) | boolean | `false` | Enable LLM-inferred error code and message for `ammo.throw()` |
-| `errors.llm.baseURL` | `ERRORS_LLM_BASE_URL` or `LLM_BASE_URL` | string | `"https://api.openai.com/v1"` | LLM provider endpoint for error inference |
-| `errors.llm.apiKey` | `ERRORS_LLM_API_KEY` or `LLM_API_KEY` | string | — | LLM provider API key for error inference |
-| `errors.llm.model` | `ERRORS_LLM_MODEL` or `LLM_MODEL` | string | `"gpt-4o-mini"` | LLM model for error inference |
-| `errors.llm.messageType` | `ERRORS_LLM_MESSAGE_TYPE` or `LLM_MESSAGE_TYPE` | `"endUser"` \| `"developer"` | `"endUser"` | Default tone for LLM-generated message: `endUser` (safe for clients) or `developer` (technical detail). Overridable per `ammo.throw()` call. |
+| Config Key               | Env Variable                                     | Type                         | Default                       | Description                                                                                                                                  |
+| ------------------------ | ------------------------------------------------ | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `errors.llm.enabled`     | `ERRORS_LLM_ENABLED` or `LLM_*` (for connection) | boolean                      | `false`                       | Enable LLM-inferred error code and message for `ammo.throw()`                                                                                |
+| `errors.llm.baseURL`     | `ERRORS_LLM_BASE_URL` or `LLM_BASE_URL`          | string                       | `"https://api.openai.com/v1"` | LLM provider endpoint for error inference                                                                                                    |
+| `errors.llm.apiKey`      | `ERRORS_LLM_API_KEY` or `LLM_API_KEY`            | string                       | —                             | LLM provider API key for error inference                                                                                                     |
+| `errors.llm.model`       | `ERRORS_LLM_MODEL` or `LLM_MODEL`                | string                       | `"gpt-4o-mini"`               | LLM model for error inference                                                                                                                |
+| `errors.llm.messageType` | `ERRORS_LLM_MESSAGE_TYPE` or `LLM_MESSAGE_TYPE`  | `"endUser"` \| `"developer"` | `"endUser"`                   | Default tone for LLM-generated message: `endUser` (safe for clients) or `developer` (technical detail). Overridable per `ammo.throw()` call. |
 
 When enabled, the same behaviour applies whether you call `ammo.throw()` or the framework calls it when it catches an error — one mechanism, no separate config.
 
@@ -127,6 +137,11 @@ Create a `tejas.config.json` in your project root:
     "http_requests": true,
     "exceptions": true
   },
+  "response": {
+    "envelopeEnabled": true,
+    "successKey": "data",
+    "errorKey": "error"
+  },
   "body": {
     "max_size": 5242880,
     "timeout": 15000
@@ -165,6 +180,11 @@ PORT=3000
 LOG_HTTP_REQUESTS=true
 LOG_EXCEPTIONS=true
 
+# Response envelope (default: enabled; 2xx → { data }, 4xx/5xx → { error })
+# RESPONSE_ENVELOPE_ENABLED=true
+# RESPONSE_SUCCESSKEY=data
+# RESPONSE_ERRORKEY=error
+
 # Body limits
 BODY_MAX_SIZE=5242880
 BODY_TIMEOUT=15000
@@ -204,12 +224,12 @@ const app = new Tejas({
   port: 3000,
   log: {
     http_requests: true,
-    exceptions: true
+    exceptions: true,
   },
   body: {
     max_size: 10 * 1024 * 1024,
-    timeout: 30000
-  }
+    timeout: 30000,
+  },
 });
 ```
 
@@ -239,7 +259,7 @@ import { env } from 'tej-env';
 target.register('/info', (ammo) => {
   ammo.fire({
     port: env('PORT'),
-    maxBodySize: env('BODY_MAX_SIZE')
+    maxBodySize: env('BODY_MAX_SIZE'),
   });
 });
 ```
@@ -274,7 +294,7 @@ Database connections are configured via `takeoff()` options, not through the con
 ```javascript
 app.takeoff({
   withRedis: { url: 'redis://localhost:6379' },
-  withMongo: { uri: 'mongodb://localhost:27017/myapp' }
+  withMongo: { uri: 'mongodb://localhost:27017/myapp' },
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "te.js",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "AI Native Node.js Framework",
   "type": "module",
   "main": "te.js",

package/server/ammo/dispatch-helper.js

@@ -1,4 +1,5 @@
 import status from 'statuses';
+import { getResponseConfig } from '../../utils/response-config.js';
 
 const formattedData = (data) => {
   if (data === null || data === undefined) return '';
@@ -17,64 +18,72 @@ const formattedData = (data) => {
   return String(data);
 };
 
+/**
+ * Apply response structure envelope when enabled.
+ * 2xx → { [successKey]: data }; 4xx/5xx → { [errorKey]: data }; 204 and when disabled → pass through.
+ * @param {number} statusCode
+ * @param {unknown} data
+ * @returns {unknown}
+ */
+const applyResponseStructure = (statusCode, data) => {
+  const { enabled, successKey, errorKey } = getResponseConfig();
+  if (!enabled) return data;
+  if (statusCode === 204) return data;
+  if (statusCode >= 200 && statusCode < 300) {
+    return { [successKey]: data };
+  }
+  if (statusCode >= 400) {
+    return { [errorKey]: data };
+  }
+  return data;
+};
+
 const statusAndData = (args) => {
+  let statusCode;
+  let rawData;
+  let customContentType = null;
+
   // Handle no arguments
   if (!args || args.length === 0) {
-    return {
-      statusCode: 204,
-      data: status(204),
-      contentType: 'text/plain',
-    };
-  }
-
-  // Handle single argument
-  if (args.length === 1) {
+    statusCode = 204;
+    rawData = status(204);
+  } else if (args.length === 1) {
     const arg = args[0];
 
     // If it's a number, treat as status code
     if (typeof arg === 'number') {
-      return {
-        statusCode: arg,
-        data: status(arg) || String(arg),
-        contentType: 'text/plain',
-      };
+      statusCode = arg;
+      rawData = status(arg) || String(arg);
+    } else {
+      // Otherwise treat as data
+      statusCode = 200;
+      rawData = arg;
     }
-
-    // Otherwise treat as data
-    return {
-      statusCode: 200,
-      data: formattedData(arg),
-      contentType: contentType(arg),
-    };
-  }
-
-  // Handle multiple arguments
-  let statusCode = 200;
-  let data = args[0];
-
-  // If first argument is a number, treat as status code
-  if (typeof args[0] === 'number') {
-    statusCode = args[0];
-    data = args[1];
   } else {
-    // If first argument is not a number, check if second is
-    if (typeof args[1] === 'number') {
+    // Handle multiple arguments
+    statusCode = 200;
+    rawData = args[0];
+
+    if (typeof args[0] === 'number') {
+      statusCode = args[0];
+      rawData = args[1];
+    } else if (typeof args[1] === 'number') {
       statusCode = args[1];
     }
-  }
 
-  // If data is undefined, use status message
-  if (data === undefined) {
-    data = status[statusCode] || String(statusCode);
+    if (rawData === undefined) {
+      rawData = status[statusCode] || String(statusCode);
+    }
+
+    customContentType = args.length > 2 ? args[2] : null;
   }
 
-  // If third argument is provided, it's the content type
-  const customContentType = args.length > 2 ? args[2] : null;
+  const wrapped = applyResponseStructure(statusCode, rawData);
 
   return {
     statusCode,
-    data: formattedData(data),
-    contentType: customContentType || contentType(data),
+    data: formattedData(wrapped),
+    contentType: customContentType || contentType(wrapped),
   };
 };
 

package/utils/response-config.js

@@ -0,0 +1,38 @@
+/**
+ * Resolve response structure configuration.
+ * Uses RESPONSE_* env vars (populated from tejas.config.json response section).
+ */
+
+import { env } from 'tej-env';
+
+/**
+ * Resolve response config from env.
+ * @returns {{ enabled: boolean, successKey: string, errorKey: string }}
+ */
+export function getResponseConfig() {
+  // Response envelope: from .env use RESPONSE_ENVELOPE_ENABLED; from config file → RESPONSE_ENVELOPEENABLED; legacy names supported
+  const enabledRaw =
+    env('RESPONSE_ENVELOPE_ENABLED') ??
+    env('RESPONSE_ENVELOPEENABLED') ??
+    env('RESPONSE_FORMAT_ENABLED') ??
+    env('RESPONSE_FORMATENABLED') ??
+    env('RESPONSE_ENABLED') ??
+    '';
+  const enabled =
+    enabledRaw === true ||
+    enabledRaw === 'true' ||
+    enabledRaw === '1' ||
+    enabledRaw === 1;
+
+  const successKey =
+    env('RESPONSE_SUCCESSKEY') ?? env('RESPONSE_SUCCESS_KEY') ?? 'data';
+  const errorKey =
+    env('RESPONSE_ERRORKEY') ?? env('RESPONSE_ERROR_KEY') ?? 'error';
+
+  return {
+    enabled:
+      enabledRaw === undefined || enabledRaw === '' ? true : Boolean(enabled),
+    successKey: String(successKey ?? 'data').trim() || 'data',
+    errorKey: String(errorKey ?? 'error').trim() || 'error',
+  };
+}