@flink-app/flink 2.0.0-alpha.89 → 2.0.0-alpha.91

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.91
+
+## 2.0.0-alpha.90
+
+### Minor Changes
+
+-   0d84b5f: Add optional `meta` field to error responses for structured context
+
+    The `error` object in `FlinkResponse` now supports an optional `meta?: unknown`
+    field for passing structured payloads alongside an error (e.g. payment decline
+    codes, retry hints, gateway metadata). All six error helpers (`notFound`,
+    `conflict`, `badRequest`, `unauthorized`, `forbidden`, `internalServerError`)
+    accept it as an optional third argument.
+
+    The value must be JSON-serializable. If serialization fails (e.g. `BigInt`,
+    circular references), the framework silently strips `meta` and logs a warning
+    before sending the response.
+
+    ```typescript
+    return badRequest("Payment declined", "paymentDeclined", {
+        gatewayCode: "insufficient_funds",
+        attemptId: "att_123",
+    });
+    ```
+
+    Fully additive — existing callers are unaffected.
+
 ## 2.0.0-alpha.89
 
 ## 2.0.0-alpha.88

package/dist/src/FlinkApp.js

@@ -451,16 +451,17 @@ var FlinkApp = /** @class */ (function () {
             this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
                 var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, result, detail, valid, formattedErrors;
                 var _this = this;
-                return __generator(this, function (_c) {
-                    switch (_c.label) {
+                var _c;
+                return __generator(this, function (_d) {
+                    switch (_d.label) {
                         case 0:
                             if (!routeProps.permissions) return [3 /*break*/, 2];
                             return [4 /*yield*/, this.authenticate(req, routeProps.permissions)];
                         case 1:
-                            if (!(_c.sent())) {
+                            if (!(_d.sent())) {
                                 return [2 /*return*/, res.status(401).json((0, FlinkErrors_1.unauthorized)())];
                             }
-                            _c.label = 2;
+                            _d.label = 2;
                         case 2:
                             if (validateReq_1) {
                                 valid = validateReq_1(req.body);
@@ -507,9 +508,9 @@ var FlinkApp = /** @class */ (function () {
                                 req.query = normalizedQuery;
                             }
                             stream = streamFormat ? StreamWriterFactory_1.StreamWriterFactory.create(res, streamFormat) : undefined;
-                            _c.label = 3;
+                            _d.label = 3;
                         case 3:
-                            _c.trys.push([3, 5, , 6]);
+                            _d.trys.push([3, 5, , 6]);
                             flinkReq_1 = req;
                             return [4 /*yield*/, FlinkRequestContext_1.requestContext.run({
                                     reqId: flinkReq_1.reqId,
@@ -533,10 +534,10 @@ var FlinkApp = /** @class */ (function () {
                                     });
                                 }); })];
                         case 4:
-                            handlerRes = _c.sent();
+                            handlerRes = _d.sent();
                             return [3 /*break*/, 6];
                         case 5:
-                            err_1 = _c.sent();
+                            err_1 = _d.sent();
                             // Handle errors for streaming handlers
                             if (streamFormat && stream) {
                                 FlinkLog_1.log.error("Streaming handler error on ".concat(req.method.toUpperCase(), " ").concat(req.path, ": ").concat(err_1.message), {
@@ -629,6 +630,15 @@ var FlinkApp = /** @class */ (function () {
                                         .type(routeProps.responseType)
                                         .send(handlerRes.data)];
                             }
+                            if (((_c = handlerRes.error) === null || _c === void 0 ? void 0 : _c.meta) !== undefined) {
+                                try {
+                                    JSON.stringify(handlerRes.error.meta);
+                                }
+                                catch (e) {
+                                    FlinkLog_1.log.warn("[".concat(handlerRes.reqId, "] error.meta stripped from error ").concat(handlerRes.error.id, ": not JSON-serializable (").concat(e.message, ")"));
+                                    delete handlerRes.error.meta;
+                                }
+                            }
                             res.status(handlerRes.status || 200).json(handlerRes);
                             return [2 /*return*/];
                     }

package/dist/src/FlinkErrors.d.ts

@@ -6,36 +6,46 @@ export type FlinkError = undefined;
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!user) return notFound("User not found");
+ * if (!user) return notFound("User not found", "userNotFound", { userId });
  * ```
  */
-export declare function notFound(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function notFound(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 409 Conflict error response.
  * Use when a request conflicts with existing data (e.g., duplicate username/email).
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (existingUser) return conflict("Email already registered");
  * ```
  */
-export declare function conflict(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function conflict(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 400 Bad Request error response.
  * Use when the request is malformed or contains invalid data (e.g., validation errors).
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable).
+ *   Useful for domain-specific context like payment decline codes,
+ *   retry hints, or structured field errors.
  * @example
  * ```ts
  * if (!email || !password) return badRequest("Email and password are required");
+ * return badRequest("Payment declined", "paymentDeclined", {
+ *   gatewayCode: "insufficient_funds",
+ *   attemptId: "att_123",
+ * });
  * ```
  */
-export declare function badRequest(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function badRequest(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 401 Unauthorized error response.
  * Use when authentication is required but missing or invalid (e.g., no token, expired token).
@@ -43,12 +53,13 @@ export declare function badRequest(detail?: string, code?: string): FlinkRespons
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!ctx.auth?.user) return unauthorized("Authentication required");
  * ```
  */
-export declare function unauthorized(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function unauthorized(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 403 Forbidden error response.
  * Use when the user is authenticated but lacks permission to access the resource.
@@ -56,21 +67,23 @@ export declare function unauthorized(detail?: string, code?: string): FlinkRespo
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (ctx.auth?.user?.role !== "admin") return forbidden("Admin access required");
  * ```
  */
-export declare function forbidden(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function forbidden(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;
 /**
  * Returns a 500 Internal Server Error response.
  * Use when an unexpected error occurs on the server side.
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * try { ... } catch (error) { return internalServerError("Failed to process request"); }
  * ```
  */
-export declare function internalServerError(detail?: string, code?: string): FlinkResponse<FlinkError>;
+export declare function internalServerError(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError>;

package/dist/src/FlinkErrors.js

@@ -1,4 +1,15 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.notFound = notFound;
 exports.conflict = conflict;
@@ -13,20 +24,17 @@ var uuid_1 = require("uuid");
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!user) return notFound("User not found");
+ * if (!user) return notFound("User not found", "userNotFound", { userId });
  * ```
  */
-function notFound(detail, code) {
+function notFound(detail, code, meta) {
     return {
         status: 404,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Not Found",
-            detail: detail || "The requested resource does not exist",
-            code: code || "notFound"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Not Found", detail: detail || "The requested resource does not exist", code: code || "notFound" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -35,20 +43,16 @@ function notFound(detail, code) {
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (existingUser) return conflict("Email already registered");
  * ```
  */
-function conflict(detail, code) {
+function conflict(detail, code, meta) {
     return {
         status: 409,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Conflict",
-            detail: detail || "An identical entity exits",
-            code: code || "conflict"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Conflict", detail: detail || "An identical entity exits", code: code || "conflict" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -57,20 +61,22 @@ function conflict(detail, code) {
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable).
+ *   Useful for domain-specific context like payment decline codes,
+ *   retry hints, or structured field errors.
  * @example
  * ```ts
  * if (!email || !password) return badRequest("Email and password are required");
+ * return badRequest("Payment declined", "paymentDeclined", {
+ *   gatewayCode: "insufficient_funds",
+ *   attemptId: "att_123",
+ * });
  * ```
  */
-function badRequest(detail, code) {
+function badRequest(detail, code, meta) {
     return {
         status: 400,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Bad Request",
-            detail: detail || "Invalid request",
-            code: code || "badRequest"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Bad Request", detail: detail || "Invalid request", code: code || "badRequest" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -80,20 +86,16 @@ function badRequest(detail, code) {
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!ctx.auth?.user) return unauthorized("Authentication required");
  * ```
  */
-function unauthorized(detail, code) {
+function unauthorized(detail, code, meta) {
     return {
         status: 401,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Unauthorized",
-            detail: detail || "Authentication required",
-            code: code || "unauthorized"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Unauthorized", detail: detail || "Authentication required", code: code || "unauthorized" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -103,20 +105,16 @@ function unauthorized(detail, code) {
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (ctx.auth?.user?.role !== "admin") return forbidden("Admin access required");
  * ```
  */
-function forbidden(detail, code) {
+function forbidden(detail, code, meta) {
     return {
         status: 403,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Forbidden",
-            detail: detail || "You do not have permission to access this resource",
-            code: code || "forbidden"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Forbidden", detail: detail || "You do not have permission to access this resource", code: code || "forbidden" }, (meta !== undefined && { meta: meta })),
     };
 }
 /**
@@ -125,19 +123,15 @@ function forbidden(detail, code) {
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * try { ... } catch (error) { return internalServerError("Failed to process request"); }
  * ```
  */
-function internalServerError(detail, code) {
+function internalServerError(detail, code, meta) {
     return {
         status: 500,
-        error: {
-            id: (0, uuid_1.v4)(),
-            title: "Internal Server Error",
-            detail: detail || "Something unexpected went wrong",
-            code: code || "internalServerError"
-        },
+        error: __assign({ id: (0, uuid_1.v4)(), title: "Internal Server Error", detail: detail || "Something unexpected went wrong", code: code || "internalServerError" }, (meta !== undefined && { meta: meta })),
     };
 }

package/dist/src/FlinkResponse.d.ts

@@ -28,6 +28,12 @@ export interface FlinkResponse<T = any> {
         title: string;
         detail?: string;
         code?: string;
+        /**
+         * Optional structured payload with additional error context.
+         * Must be JSON-serializable; non-serializable values are stripped
+         * with a warning before sending the response.
+         */
+        meta?: unknown;
     };
     /**
      * HTTP headers, names are lower cased

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.89",
+  "version": "2.0.0-alpha.91",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",

package/src/FlinkApp.ts

@@ -865,6 +865,15 @@ export class FlinkApp<C extends FlinkContext> {
                         .send(handlerRes.data);
                 }
 
+                if (handlerRes.error?.meta !== undefined) {
+                    try {
+                        JSON.stringify(handlerRes.error.meta);
+                    } catch (e) {
+                        log.warn(`[${handlerRes.reqId}] error.meta stripped from error ${handlerRes.error.id}: not JSON-serializable (${(e as Error).message})`);
+                        delete handlerRes.error.meta;
+                    }
+                }
+
                 res.status(handlerRes.status || 200).json(handlerRes);
             });
 

package/src/FlinkErrors.ts

@@ -10,19 +10,22 @@ export type FlinkError = undefined;
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!user) return notFound("User not found");
+ * if (!user) return notFound("User not found", "userNotFound", { userId });
  * ```
  */
-export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkError> {
+export function notFound(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 404,
     error: {
       id: v4(),
       title: "Not Found",
       detail: detail || "The requested resource does not exist",
-      code : code || "notFound"
+      code : code || "notFound",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -33,19 +36,21 @@ export function notFound(detail?: string, code?: string ): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (existingUser) return conflict("Email already registered");
  * ```
  */
-export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkError> {
+export function conflict(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 409,
     error: {
       id: v4(),
       title: "Conflict",
       detail: detail || "An identical entity exits",
-      code : code || "conflict"
+      code : code || "conflict",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -58,19 +63,27 @@ export function conflict(detail?: string, code?: string ): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable).
+ *   Useful for domain-specific context like payment decline codes,
+ *   retry hints, or structured field errors.
  * @example
  * ```ts
  * if (!email || !password) return badRequest("Email and password are required");
+ * return badRequest("Payment declined", "paymentDeclined", {
+ *   gatewayCode: "insufficient_funds",
+ *   attemptId: "att_123",
+ * });
  * ```
  */
-export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function badRequest(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 400,
     error: {
       id: v4(),
       title: "Bad Request",
       detail: detail || "Invalid request",
-      code : code || "badRequest"
+      code : code || "badRequest",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -82,12 +95,13 @@ export function badRequest(detail?: string, code?: string): FlinkResponse<FlinkE
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (!ctx.auth?.user) return unauthorized("Authentication required");
  * ```
  */
-export function unauthorized(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function unauthorized(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 401,
     error: {
@@ -95,7 +109,8 @@ export function unauthorized(detail?: string, code?: string): FlinkResponse<Flin
       title: "Unauthorized",
       detail:
         detail || "Authentication required",
-      code : code || "unauthorized"
+      code : code || "unauthorized",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -107,19 +122,21 @@ export function unauthorized(detail?: string, code?: string): FlinkResponse<Flin
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * if (ctx.auth?.user?.role !== "admin") return forbidden("Admin access required");
  * ```
  */
-export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkError> {
+export function forbidden(detail?: string, code?: string, meta?: unknown): FlinkResponse<FlinkError> {
   return {
     status: 403,
     error: {
       id: v4(),
       title: "Forbidden",
       detail: detail || "You do not have permission to access this resource",
-      code : code || "forbidden"
+      code : code || "forbidden",
+      ...(meta !== undefined && { meta }),
     },
   };
 }
@@ -130,6 +147,7 @@ export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkEr
  *
  * @param detail - Optional custom error message
  * @param code - Optional custom error code
+ * @param meta - Optional structured payload (must be JSON-serializable)
  * @example
  * ```ts
  * try { ... } catch (error) { return internalServerError("Failed to process request"); }
@@ -137,7 +155,8 @@ export function forbidden(detail?: string, code?: string): FlinkResponse<FlinkEr
  */
 export function internalServerError(
   detail?: string,
-  code?: string
+  code?: string,
+  meta?: unknown
 ): FlinkResponse<FlinkError> {
   return {
     status: 500,
@@ -145,7 +164,8 @@ export function internalServerError(
       id: v4(),
       title: "Internal Server Error",
       detail: detail || "Something unexpected went wrong",
-      code : code || "internalServerError"
+      code : code || "internalServerError",
+      ...(meta !== undefined && { meta }),
     },
   };
 }

package/src/FlinkResponse.ts

@@ -34,6 +34,12 @@ export interface FlinkResponse<T = any> {
         title: string;
         detail?: string;
         code?: string;
+        /**
+         * Optional structured payload with additional error context.
+         * Must be JSON-serializable; non-serializable values are stripped
+         * with a warning before sending the response.
+         */
+        meta?: unknown;
     };
 
     /**