aiden-shared-calculations-unified 1.0.35 → 1.0.37

package/calculations/capital_flow/historical/crowd-cash-flow-proxy.js

@@ -1,122 +1,122 @@
-/**
- * @fileoverview Estimates a proxy for net crowd cash flow (Deposits vs. Withdrawals)
- * by aggregating portfolio percentage changes across all users.
- *
- * This calculation is based on the formula:
- * Total_Change = P/L_Effect + Trading_Effect + Cash_Flow_Effect
- *
- * Where:
- * - Total_Change = avg_value_day2 - avg_value_day1
- * - P/L_Effect = avg_value_day1 - avg_invested_day1
- * - Trading_Effect = avg_invested_day2 - avg_invested_day1
- *
- * We solve for Cash_Flow_Effect, which serves as our proxy.
- * A negative value indicates a net DEPOSIT (denominator grew, shrinking all %s).
- * A positive value indicates a net WITHDRAWAL (denominator shrank, inflating all %s).
- *
- * NOTE: This file is a logical duplicate of deposit_withdrawal_percentage.js
- * to satisfy the hardcoded 'crowd-cash-flow-proxy' dependency in several
- * meta-calculations.
- */
-
-class CrowdCashFlowProxy {
-    constructor() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
-        this.user_count = 0;
-    }
-
-    /**
-     * Helper to sum a specific field from an AggregatedPositions array.
-     * @param {Array<object>} positions - The AggregatedPositions array.
-     * @param {string} field - The field to sum ('Invested' or 'Value').
-     * @returns {number} The total sum of that field.
-     */
-    _sumPositions(positions, field) {
-        if (!positions || !Array.isArray(positions)) {
-            return 0;
-        }
-        return positions.reduce((sum, pos) => sum + (pos[field] || 0), 0);
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        // This calculation requires both days' data to compare
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            return;
-        }
-
-        const invested_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Invested');
-        const value_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Value');
-        const invested_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Invested');
-        const value_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Value');
-
-        // Only include users who have some form of positions
-        if (invested_day1 === 0 && invested_day2 === 0 && value_day1 === 0 && value_day2 === 0) {
-            return;
-        }
-
-        this.total_invested_day1 += invested_day1;
-        this.total_value_day1 += value_day1;
-        this.total_invested_day2 += invested_day2;
-        this.total_value_day2 += value_day2;
-        this.user_count++;
-    }
-
-    getResult() {
-        if (this.user_count === 0) {
-            return {}; // No users processed, return empty.
-        }
-
-        // 1. Calculate the average portfolio for the crowd
-        const avg_invested_day1 = this.total_invested_day1 / this.user_count;
-        const avg_value_day1 = this.total_value_day1 / this.user_count;
-        const avg_invested_day2 = this.total_invested_day2 / this.user_count;
-        const avg_value_day2 = this.total_value_day2 / this.user_count;
-
-        // 2. Isolate the three effects
-        const total_value_change = avg_value_day2 - avg_value_day1;
-        const pl_effect = avg_value_day1 - avg_invested_day1;
-        const trading_effect = avg_invested_day2 - avg_invested_day1;
-
-        // 3. Solve for the Cash Flow Effect
-        // Total_Change = pl_effect + trading_effect + cash_flow_effect
-        const cash_flow_effect = total_value_change - pl_effect - trading_effect;
-
-        return {
-            // The final proxy value.
-            // A negative value signals a net DEPOSIT.
-            // A positive value signals a net WITHDRAWAL.
-            cash_flow_effect_proxy: cash_flow_effect,
-            
-            // Interpretation for the frontend
-            interpretation: "A negative value signals a net crowd deposit. A positive value signals a net crowd withdrawal.",
-            
-            // Debug components
-            components: {
-                total_value_change: total_value_change,
-                pl_effect: pl_effect,
-                trading_effect: trading_effect
-            },
-            // Debug averages
-            averages: {
-                avg_invested_day1: avg_invested_day1,
-                avg_value_day1: avg_value_day1,
-                avg_invested_day2: avg_invested_day2,
-                avg_value_day2: avg_value_day2
-            },
-            user_sample_size: this.user_count
-        };
-    }
-
-    reset() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
-        this.user_count = 0;
-    }
-}
-
+/**
+ * @fileoverview Estimates a proxy for net crowd cash flow (Deposits vs. Withdrawals)
+ * by aggregating portfolio percentage changes across all users.
+ *
+ * This calculation is based on the formula:
+ * Total_Change = P/L_Effect + Trading_Effect + Cash_Flow_Effect
+ *
+ * Where:
+ * - Total_Change = avg_value_day2 - avg_value_day1
+ * - P/L_Effect = avg_value_day1 - avg_invested_day1
+ * - Trading_Effect = avg_invested_day2 - avg_invested_day1
+ *
+ * We solve for Cash_Flow_Effect, which serves as our proxy.
+ * A negative value indicates a net DEPOSIT (denominator grew, shrinking all %s).
+ * A positive value indicates a net WITHDRAWAL (denominator shrank, inflating all %s).
+ *
+ * NOTE: This file is a logical duplicate of deposit_withdrawal_percentage.js
+ * to satisfy the hardcoded 'crowd-cash-flow-proxy' dependency in several
+ * meta-calculations.
+ */
+
+class CrowdCashFlowProxy {
+    constructor() {
+        this.total_invested_day1 = 0;
+        this.total_value_day1 = 0;
+        this.total_invested_day2 = 0;
+        this.total_value_day2 = 0;
+        this.user_count = 0;
+    }
+
+    /**
+     * Helper to sum a specific field from an AggregatedPositions array.
+     * @param {Array<object>} positions - The AggregatedPositions array.
+     * @param {string} field - The field to sum ('Invested' or 'Value').
+     * @returns {number} The total sum of that field.
+     */
+    _sumPositions(positions, field) {
+        if (!positions || !Array.isArray(positions)) {
+            return 0;
+        }
+        return positions.reduce((sum, pos) => sum + (pos[field] || 0), 0);
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        // This calculation requires both days' data to compare
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+
+        const invested_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Invested');
+        const value_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Value');
+        const invested_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Invested');
+        const value_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Value');
+
+        // Only include users who have some form of positions
+        if (invested_day1 === 0 && invested_day2 === 0 && value_day1 === 0 && value_day2 === 0) {
+            return;
+        }
+
+        this.total_invested_day1 += invested_day1;
+        this.total_value_day1 += value_day1;
+        this.total_invested_day2 += invested_day2;
+        this.total_value_day2 += value_day2;
+        this.user_count++;
+    }
+
+    getResult() {
+        if (this.user_count === 0) {
+            return {}; // No users processed, return empty.
+        }
+
+        // 1. Calculate the average portfolio for the crowd
+        const avg_invested_day1 = this.total_invested_day1 / this.user_count;
+        const avg_value_day1 = this.total_value_day1 / this.user_count;
+        const avg_invested_day2 = this.total_invested_day2 / this.user_count;
+        const avg_value_day2 = this.total_value_day2 / this.user_count;
+
+        // 2. Isolate the three effects
+        const total_value_change = avg_value_day2 - avg_value_day1;
+        const pl_effect = avg_value_day1 - avg_invested_day1;
+        const trading_effect = avg_invested_day2 - avg_invested_day1;
+
+        // 3. Solve for the Cash Flow Effect
+        // Total_Change = pl_effect + trading_effect + cash_flow_effect
+        const cash_flow_effect = total_value_change - pl_effect - trading_effect;
+
+        return {
+            // The final proxy value.
+            // A negative value signals a net DEPOSIT.
+            // A positive value signals a net WITHDRAWAL.
+            cash_flow_effect_proxy: cash_flow_effect,
+            
+            // Interpretation for the frontend
+            interpretation: "A negative value signals a net crowd deposit. A positive value signals a net crowd withdrawal.",
+            
+            // Debug components
+            components: {
+                total_value_change: total_value_change,
+                pl_effect: pl_effect,
+                trading_effect: trading_effect
+            },
+            // Debug averages
+            averages: {
+                avg_invested_day1: avg_invested_day1,
+                avg_value_day1: avg_value_day1,
+                avg_invested_day2: avg_invested_day2,
+                avg_value_day2: avg_value_day2
+            },
+            user_sample_size: this.user_count
+        };
+    }
+
+    reset() {
+        this.total_invested_day1 = 0;
+        this.total_value_day1 = 0;
+        this.total_invested_day2 = 0;
+        this.total_value_day2 = 0;
+        this.user_count = 0;
+    }
+}
+
 module.exports = CrowdCashFlowProxy;

package/calculations/capital_flow/historical/deposit_withdrawal_percentage.js

@@ -1,118 +1,118 @@
-/**
- * @fileoverview Estimates a proxy for net crowd cash flow (Deposits vs. Withdrawals)
- * by aggregating portfolio percentage changes across all users.
- *
- * This calculation is based on the formula:
- * Total_Change = P/L_Effect + Trading_Effect + Cash_Flow_Effect
- *
- * Where:
- * - Total_Change = avg_value_day2 - avg_value_day1
- * - P/L_Effect = avg_value_day1 - avg_invested_day1
- * - Trading_Effect = avg_invested_day2 - avg_invested_day1
- *
- * We solve for Cash_Flow_Effect, which serves as our proxy.
- * A negative value indicates a net DEPOSIT (denominator grew, shrinking all %s).
- * A positive value indicates a net WITHDRAWAL (denominator shrank, inflating all %s).
- */
-
-class CrowdCashFlowProxy {
-    constructor() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
-        this.user_count = 0;
-    }
-
-    /**
-     * Helper to sum a specific field from an AggregatedPositions array.
-     * @param {Array<object>} positions - The AggregatedPositions array.
-     * @param {string} field - The field to sum ('Invested' or 'Value').
-     * @returns {number} The total sum of that field.
-     */
-    _sumPositions(positions, field) {
-        if (!positions || !Array.isArray(positions)) {
-            return 0;
-        }
-        return positions.reduce((sum, pos) => sum + (pos[field] || 0), 0);
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        // This calculation requires both days' data to compare
-        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
-            return;
-        }
-
-        const invested_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Invested');
-        const value_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Value');
-        const invested_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Invested');
-        const value_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Value');
-
-        // Only include users who have some form of positions
-        if (invested_day1 === 0 && invested_day2 === 0 && value_day1 === 0 && value_day2 === 0) {
-            return;
-        }
-
-        this.total_invested_day1 += invested_day1;
-        this.total_value_day1 += value_day1;
-        this.total_invested_day2 += invested_day2;
-        this.total_value_day2 += value_day2;
-        this.user_count++;
-    }
-
-    getResult() {
-        if (this.user_count === 0) {
-            return {}; // No users processed, return empty.
-        }
-
-        // 1. Calculate the average portfolio for the crowd
-        const avg_invested_day1 = this.total_invested_day1 / this.user_count;
-        const avg_value_day1 = this.total_value_day1 / this.user_count;
-        const avg_invested_day2 = this.total_invested_day2 / this.user_count;
-        const avg_value_day2 = this.total_value_day2 / this.user_count;
-
-        // 2. Isolate the three effects
-        const total_value_change = avg_value_day2 - avg_value_day1;
-        const pl_effect = avg_value_day1 - avg_invested_day1;
-        const trading_effect = avg_invested_day2 - avg_invested_day1;
-
-        // 3. Solve for the Cash Flow Effect
-        // Total_Change = pl_effect + trading_effect + cash_flow_effect
-        const cash_flow_effect = total_value_change - pl_effect - trading_effect;
-
-        return {
-            // The final proxy value.
-            // A negative value signals a net DEPOSIT.
-            // A positive value signals a net WITHDRAWAL.
-            cash_flow_effect_proxy: cash_flow_effect,
-            
-            // Interpretation for the frontend
-            interpretation: "A negative value signals a net crowd deposit. A positive value signals a net crowd withdrawal.",
-            
-            // Debug components
-            components: {
-                total_value_change: total_value_change,
-                pl_effect: pl_effect,
-                trading_effect: trading_effect
-            },
-            // Debug averages
-            averages: {
-                avg_invested_day1: avg_invested_day1,
-                avg_value_day1: avg_value_day1,
-                avg_invested_day2: avg_invested_day2,
-                avg_value_day2: avg_value_day2
-            },
-            user_sample_size: this.user_count
-        };
-    }
-
-    reset() {
-        this.total_invested_day1 = 0;
-        this.total_value_day1 = 0;
-        this.total_invested_day2 = 0;
-        this.total_value_day2 = 0;
-        this.user_count = 0;
-    }
-}
-
+/**
+ * @fileoverview Estimates a proxy for net crowd cash flow (Deposits vs. Withdrawals)
+ * by aggregating portfolio percentage changes across all users.
+ *
+ * This calculation is based on the formula:
+ * Total_Change = P/L_Effect + Trading_Effect + Cash_Flow_Effect
+ *
+ * Where:
+ * - Total_Change = avg_value_day2 - avg_value_day1
+ * - P/L_Effect = avg_value_day1 - avg_invested_day1
+ * - Trading_Effect = avg_invested_day2 - avg_invested_day1
+ *
+ * We solve for Cash_Flow_Effect, which serves as our proxy.
+ * A negative value indicates a net DEPOSIT (denominator grew, shrinking all %s).
+ * A positive value indicates a net WITHDRAWAL (denominator shrank, inflating all %s).
+ */
+
+class CrowdCashFlowProxy {
+    constructor() {
+        this.total_invested_day1 = 0;
+        this.total_value_day1 = 0;
+        this.total_invested_day2 = 0;
+        this.total_value_day2 = 0;
+        this.user_count = 0;
+    }
+
+    /**
+     * Helper to sum a specific field from an AggregatedPositions array.
+     * @param {Array<object>} positions - The AggregatedPositions array.
+     * @param {string} field - The field to sum ('Invested' or 'Value').
+     * @returns {number} The total sum of that field.
+     */
+    _sumPositions(positions, field) {
+        if (!positions || !Array.isArray(positions)) {
+            return 0;
+        }
+        return positions.reduce((sum, pos) => sum + (pos[field] || 0), 0);
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        // This calculation requires both days' data to compare
+        if (!todayPortfolio || !yesterdayPortfolio || !todayPortfolio.AggregatedPositions || !yesterdayPortfolio.AggregatedPositions) {
+            return;
+        }
+
+        const invested_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Invested');
+        const value_day1 = this._sumPositions(yesterdayPortfolio.AggregatedPositions, 'Value');
+        const invested_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Invested');
+        const value_day2 = this._sumPositions(todayPortfolio.AggregatedPositions, 'Value');
+
+        // Only include users who have some form of positions
+        if (invested_day1 === 0 && invested_day2 === 0 && value_day1 === 0 && value_day2 === 0) {
+            return;
+        }
+
+        this.total_invested_day1 += invested_day1;
+        this.total_value_day1 += value_day1;
+        this.total_invested_day2 += invested_day2;
+        this.total_value_day2 += value_day2;
+        this.user_count++;
+    }
+
+    getResult() {
+        if (this.user_count === 0) {
+            return {}; // No users processed, return empty.
+        }
+
+        // 1. Calculate the average portfolio for the crowd
+        const avg_invested_day1 = this.total_invested_day1 / this.user_count;
+        const avg_value_day1 = this.total_value_day1 / this.user_count;
+        const avg_invested_day2 = this.total_invested_day2 / this.user_count;
+        const avg_value_day2 = this.total_value_day2 / this.user_count;
+
+        // 2. Isolate the three effects
+        const total_value_change = avg_value_day2 - avg_value_day1;
+        const pl_effect = avg_value_day1 - avg_invested_day1;
+        const trading_effect = avg_invested_day2 - avg_invested_day1;
+
+        // 3. Solve for the Cash Flow Effect
+        // Total_Change = pl_effect + trading_effect + cash_flow_effect
+        const cash_flow_effect = total_value_change - pl_effect - trading_effect;
+
+        return {
+            // The final proxy value.
+            // A negative value signals a net DEPOSIT.
+            // A positive value signals a net WITHDRAWAL.
+            cash_flow_effect_proxy: cash_flow_effect,
+            
+            // Interpretation for the frontend
+            interpretation: "A negative value signals a net crowd deposit. A positive value signals a net crowd withdrawal.",
+            
+            // Debug components
+            components: {
+                total_value_change: total_value_change,
+                pl_effect: pl_effect,
+                trading_effect: trading_effect
+            },
+            // Debug averages
+            averages: {
+                avg_invested_day1: avg_invested_day1,
+                avg_value_day1: avg_value_day1,
+                avg_invested_day2: avg_invested_day2,
+                avg_value_day2: avg_value_day2
+            },
+            user_sample_size: this.user_count
+        };
+    }
+
+    reset() {
+        this.total_invested_day1 = 0;
+        this.total_value_day1 = 0;
+        this.total_invested_day2 = 0;
+        this.total_value_day2 = 0;
+        this.user_count = 0;
+    }
+}
+
 module.exports = CrowdCashFlowProxy;

package/calculations/capital_flow/historical/new_allocation_percentage.js

@@ -1,49 +1,49 @@
-/**
- * @fileoverview Calculates the average percentage of total portfolio value
- * newly allocated to assets not held on the previous day.
- */
-
-class NewAllocationPercentage {
-    constructor() {
-        this.accumulatedNewAllocationPercentage = 0;
-        this.userCount = 0;
-    }
-
-    process(todayPortfolio, yesterdayPortfolio, userId) {
-        const todayPositions = todayPortfolio?.AggregatedPositions;
-        const yesterdayPositions = yesterdayPortfolio?.AggregatedPositions || [];
-
-        if (!todayPositions || todayPositions.length === 0) return;
-
-        const yesterdayIds = new Set(yesterdayPositions.map(p => p.InstrumentID));
-        let userNewAllocation = 0;
-
-        for (const pos of todayPositions) {
-            if (!yesterdayIds.has(pos.InstrumentID)) {
-                const invested = typeof pos.Invested === 'number' ? pos.Invested : 0;
-                userNewAllocation += invested;
-            }
-        }
-
-        // Guard against data rounding or eToro API drift
-        if (userNewAllocation > 100) userNewAllocation = 100;
-
-        this.accumulatedNewAllocationPercentage += userNewAllocation;
-        this.userCount++;
-    }
-
-    getResult() {
-        if (this.userCount === 0) return {};
-        return {
-            average_new_allocation_percentage:
-                this.accumulatedNewAllocationPercentage / this.userCount
-        };
-    }
-
-    reset() {
-        this.accumulatedNewAllocationPercentage = 0;
-        this.userCount = 0;
-    }
-}
-
-module.exports = NewAllocationPercentage;
+/**
+ * @fileoverview Calculates the average percentage of total portfolio value
+ * newly allocated to assets not held on the previous day.
+ */
+
+class NewAllocationPercentage {
+    constructor() {
+        this.accumulatedNewAllocationPercentage = 0;
+        this.userCount = 0;
+    }
+
+    process(todayPortfolio, yesterdayPortfolio, userId) {
+        const todayPositions = todayPortfolio?.AggregatedPositions;
+        const yesterdayPositions = yesterdayPortfolio?.AggregatedPositions || [];
+
+        if (!todayPositions || todayPositions.length === 0) return;
+
+        const yesterdayIds = new Set(yesterdayPositions.map(p => p.InstrumentID));
+        let userNewAllocation = 0;
+
+        for (const pos of todayPositions) {
+            if (!yesterdayIds.has(pos.InstrumentID)) {
+                const invested = typeof pos.Invested === 'number' ? pos.Invested : 0;
+                userNewAllocation += invested;
+            }
+        }
+
+        // Guard against data rounding or eToro API drift
+        if (userNewAllocation > 100) userNewAllocation = 100;
+
+        this.accumulatedNewAllocationPercentage += userNewAllocation;
+        this.userCount++;
+    }
+
+    getResult() {
+        if (this.userCount === 0) return {};
+        return {
+            average_new_allocation_percentage:
+                this.accumulatedNewAllocationPercentage / this.userCount
+        };
+    }
+
+    reset() {
+        this.accumulatedNewAllocationPercentage = 0;
+        this.userCount = 0;
+    }
+}
+
+module.exports = NewAllocationPercentage;