@konplit-services/common 1.0.359 → 1.0.361

package/build/helper/money.d.ts

@@ -5,7 +5,41 @@ export declare const formatMoneyToString: (money: ReturnType<typeof dinero>) =>
 export declare const formatMoneyToNumber: (money: ReturnType<typeof dinero>) => number;
 export declare const sumMoney: (a: ReturnType<typeof dinero>, b: ReturnType<typeof dinero>) => import("dinero.js").Dinero<number>;
 export declare const subtractMoney: (a: ReturnType<typeof dinero>, b: ReturnType<typeof dinero>) => import("dinero.js").Dinero<number>;
-export declare const multiplyMoney: (a: ReturnType<typeof dinero>, factor: number) => import("dinero.js").Dinero<number>;
+/**
+ * Multiplies a Dinero.js monetary amount by a factor, typically used for percentage-based calculations.
+ * The factor is scaled to an integer-based multiplier to ensure precision in Dinero.js.
+ * For example, a factor of 1.4 (representing 1.4%) is converted to { amount: 140, scale: 4 } to represent 0.014.
+ *
+ * @param a - The Dinero.js object representing the monetary amount (e.g., in the currency's smallest unit like kobo for NGN).
+ * @param factor - The multiplier, typically a percentage rate (e.g., 1.4 for 1.4%).
+ * @param scale - The scale for the multiplier, determining the decimal precision (default: 2).
+ *                For percentages, use scale = 4 for one decimal (e.g., 1.4%) or scale = 5 for two decimals (e.g., 1.45%).
+ * @returns A new Dinero.js object representing the result of the multiplication.
+ * @throws Error if the resulting amount is invalid (e.g., exceeds Number.MAX_SAFE_INTEGER or is non-integer).
+ *
+ * @example
+ * // Example 1: Calculate 1.4% fee on 7100 kobo (71.00 NGN)
+ * import { dinero, USD } from 'dinero.js';
+ * const amount = dinero({ amount: 7100, currency: USD }); // 71.00 USD (assuming USD for simplicity)
+ * const result = multiplyMoney(amount, 1.4, 4);
+ * // Result: Dinero object with amount ≈ 994 (99.4 cents, or 0.994 USD)
+ * console.log(result.toJSON()); // { amount: 994, currency: USD, scale: 2 }
+ *
+ * @example
+ * // Example 2: Calculate 0.05% fee on 10000 kobo (100.00 NGN) with higher precision
+ * const amount = dinero({ amount: 10000, currency: USD });
+ * const result = multiplyMoney(amount, 0.05, 5);
+ * // Result: Dinero object with amount ≈ 50 (5 cents, or 0.05 USD)
+ * console.log(result.toJSON()); // { amount: 50, currency: USD, scale: 2 }
+ *
+ * @example
+ * // Example 3: Using default scale (2) for a simple multiplier
+ * const amount = dinero({ amount: 500, currency: USD }); // 5.00 USD
+ * const result = multiplyMoney(amount, 2); // Multiply by 2 (200%)
+ * // Result: Dinero object with amount = 1000 (10.00 USD)
+ * console.log(result.toJSON()); // { amount: 1000, currency: USD, scale: 2 }
+ */
+export declare const multiplyMoney: (a: ReturnType<typeof dinero>, factor: number, scale?: number) => import("dinero.js").Dinero<number>;
 export declare const divideMoney: (money: ReturnType<typeof dinero>, divisor: number) => import("dinero.js").Dinero<number>;
 export declare const toSmalletUnit: (naira: number | string) => number;
 export {};

package/build/helper/money.js

@@ -27,8 +27,42 @@ const subtractMoney = (a, b) => {
     return (0, dinero_js_1.subtract)(a, b);
 };
 exports.subtractMoney = subtractMoney;
-const multiplyMoney = (a, factor) => {
-    return (0, dinero_js_1.multiply)(a, { amount: factor * 100, scale: 2 }); // Convert decimal to Dinero scale
+/**
+ * Multiplies a Dinero.js monetary amount by a factor, typically used for percentage-based calculations.
+ * The factor is scaled to an integer-based multiplier to ensure precision in Dinero.js.
+ * For example, a factor of 1.4 (representing 1.4%) is converted to { amount: 140, scale: 4 } to represent 0.014.
+ *
+ * @param a - The Dinero.js object representing the monetary amount (e.g., in the currency's smallest unit like kobo for NGN).
+ * @param factor - The multiplier, typically a percentage rate (e.g., 1.4 for 1.4%).
+ * @param scale - The scale for the multiplier, determining the decimal precision (default: 2).
+ *                For percentages, use scale = 4 for one decimal (e.g., 1.4%) or scale = 5 for two decimals (e.g., 1.45%).
+ * @returns A new Dinero.js object representing the result of the multiplication.
+ * @throws Error if the resulting amount is invalid (e.g., exceeds Number.MAX_SAFE_INTEGER or is non-integer).
+ *
+ * @example
+ * // Example 1: Calculate 1.4% fee on 7100 kobo (71.00 NGN)
+ * import { dinero, USD } from 'dinero.js';
+ * const amount = dinero({ amount: 7100, currency: USD }); // 71.00 USD (assuming USD for simplicity)
+ * const result = multiplyMoney(amount, 1.4, 4);
+ * // Result: Dinero object with amount ≈ 994 (99.4 cents, or 0.994 USD)
+ * console.log(result.toJSON()); // { amount: 994, currency: USD, scale: 2 }
+ *
+ * @example
+ * // Example 2: Calculate 0.05% fee on 10000 kobo (100.00 NGN) with higher precision
+ * const amount = dinero({ amount: 10000, currency: USD });
+ * const result = multiplyMoney(amount, 0.05, 5);
+ * // Result: Dinero object with amount ≈ 50 (5 cents, or 0.05 USD)
+ * console.log(result.toJSON()); // { amount: 50, currency: USD, scale: 2 }
+ *
+ * @example
+ * // Example 3: Using default scale (2) for a simple multiplier
+ * const amount = dinero({ amount: 500, currency: USD }); // 5.00 USD
+ * const result = multiplyMoney(amount, 2); // Multiply by 2 (200%)
+ * // Result: Dinero object with amount = 1000 (10.00 USD)
+ * console.log(result.toJSON()); // { amount: 1000, currency: USD, scale: 2 }
+ */
+const multiplyMoney = (a, factor, scale = 2) => {
+    return (0, dinero_js_1.multiply)(a, { amount: factor * 100, scale }); // Convert decimal to Dinero scale
 };
 exports.multiplyMoney = multiplyMoney;
 const divideMoney = (money, divisor) => {

package/build/swagger/config.js

@@ -55,5 +55,10 @@ const configureSwagger = (app, paths) => {
         // customCssUrl:
         //   "https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-newspaper.css",
     }));
+    // ➕ Serve raw Swagger JSON
+    app.get("/api-json", (_, res) => {
+        res.setHeader("Content-Type", "application/json");
+        res.send(swaggerSpec);
+    });
 };
 exports.configureSwagger = configureSwagger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konplit-services/common",
-  "version": "1.0.359",
+  "version": "1.0.361",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",