aiden-shared-calculations-unified 1.0.63 → 1.0.65

package/calculations/speculators/stop_loss_distance_by_ticker_short_long_breakdown.js

@@ -1,73 +1,120 @@
 /**
- * @fileoverview Calculates the average stop loss distance (percent and value)
- * for long and short positions, grouped by TICKER.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each ticker, what is the
+ * average stop loss distance (in % and value) for
+ * long and short positions?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
-class StopLossDistanceByTicker {
+class StopLossDistanceByTickerShortLongBreakdown {
     constructor() {
-        this.instrumentData = {};
-        this.instrumentToTicker = null;
+        // { [instrumentId]: { long_pct: [], long_val: [], short_pct: [], short_val: [] } }
+        this.assets = new Map();
+        this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (!portfolioData || !portfolioData.PublicPositions) return;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "long_avg_dist_pct": { "type": "number" },
+                "long_avg_dist_val": { "type": "number" },
+                "long_count": { "type": "number" },
+                "short_avg_dist_pct": { "type": "number" },
+                "short_avg_dist_val": { "type": "number" },
+                "short_count": { "type": "number" }
+            },
+            "required": ["long_avg_dist_pct", "long_avg_dist_val", "long_count", "short_avg_dist_pct", "short_avg_dist_val", "short_count"]
+        };
 
-        for (const position of portfolioData.PublicPositions) {
-            const { InstrumentID, Leverage, StopLossRate, CurrentRate, IsBuy } = position;
-            if (Leverage <= 1 || StopLossRate <= 0.0001 || CurrentRate <= 0) continue;
+        return {
+            "type": "object",
+            "description": "Calculates avg SL distance (% and value) for long/short positions, grouped by asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                long_pct: [], long_val: [], short_pct: [], short_val: []
+            });
+        }
+    }
+    
+    _avg(arr) {
+        if (arr.length === 0) return 0;
+        return arr.reduce((a, b) => a + b, 0) / arr.length;
+    }
 
-            const distance_value = IsBuy ? CurrentRate - StopLossRate : StopLossRate - CurrentRate;
-            const distance_percent = (distance_value / CurrentRate) * 100;
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
 
-            if (distance_percent > 0) {
-                const posType = IsBuy ? 'long' : 'short';
-                if (!this.instrumentData[InstrumentID]) this.instrumentData[InstrumentID] = {};
-                if (!this.instrumentData[InstrumentID][posType]) {
-                    this.instrumentData[InstrumentID][posType] = {
-                        distance_percent_sum: 0,
-                        distance_value_sum: 0,
-                        count: 0
-                    };
-                }
-                const agg = this.instrumentData[InstrumentID][posType];
-                agg.distance_percent_sum += distance_percent;
-                agg.distance_value_sum += distance_value;
-                agg.count++;
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            const sl_rate = pos.StopLossRate || 0;
+            const open_rate = pos.OpenRate || 0;
+            
+            if (!instrumentId || sl_rate === 0 || open_rate === 0) {
+                continue;
+            }
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            
+            const distance_val = Math.abs(open_rate - sl_rate);
+            const distance_pct = (distance_val / open_rate) * 100;
+            
+            if (pos.IsBuy) {
+                assetData.long_pct.push(distance_pct);
+                assetData.long_val.push(distance_val);
+            } else {
+                assetData.short_pct.push(distance_pct);
+                assetData.short_val.push(distance_val);
             }
         }
     }
 
     async getResult() {
-        if (Object.keys(this.instrumentData).length === 0) return {};
-        if (!this.instrumentToTicker) {
-            const mappings = await loadInstrumentMappings();
-            this.instrumentToTicker = mappings.instrumentToTicker;
+        if (!this.mappings) {
+            this.mappings = await loadInstrumentMappings();
         }
 
         const result = {};
-        for (const instrumentId in this.instrumentData) {
-            const ticker = this.instrumentToTicker[instrumentId] || `unknown_${instrumentId}`;
-            if (!result[ticker]) result[ticker] = {};
-
-            for (const posType in this.instrumentData[instrumentId]) {
-                const data = this.instrumentData[instrumentId][posType];
-                // REFACTOR: Perform final calculation and return in standardized format.
-                if (data.count > 0) {
-                    result[ticker][posType] = {
-                        average_distance_percent: data.distance_percent_sum / data.count,
-                        average_distance_value: data.distance_value_sum / data.count,
-                        count: data.count
-                    };
-                }
-            }
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            
+            result[ticker] = {
+                long_avg_dist_pct: this._avg(data.long_pct),
+                long_avg_dist_val: this._avg(data.long_val),
+                long_count: data.long_pct.length,
+                short_avg_dist_pct: this._avg(data.short_pct),
+                short_avg_dist_val: this._avg(data.short_val),
+                short_count: data.short_pct.length
+            };
         }
         return result;
     }
 
     reset() {
-        this.instrumentData = {};
+        this.assets.clear();
+        this.mappings = null;
     }
 }
 
-module.exports = StopLossDistanceByTicker;
+module.exports = StopLossDistanceByTickerShortLongBreakdown;

package/calculations/speculators/stop_loss_per_asset.js

@@ -1,26 +1,93 @@
 /**
- * @fileoverview Calculates the average stop loss level per asset.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, what is the
+ * average stop loss level and the percentage of
+ * positions that have a stop loss set?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class StopLossPerAsset {
     constructor() {
-        this.stopLossData = {};
+        // { [instrumentId]: { sl_rate_sum: 0, sl_dist_sum: 0, sl_set_count: 0, total_count: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            for (const position of portfolioData.PublicPositions) {
-                const instrumentId = position.InstrumentID;
-                const stopLoss = position.StopLossRate;
-
-                if (stopLoss > 0) {
-                    if (!this.stopLossData[instrumentId]) {
-                        this.stopLossData[instrumentId] = { sum: 0, count: 0 };
-                    }
-                    this.stopLossData[instrumentId].sum += stopLoss;
-                    this.stopLossData[instrumentId].count++;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "avg_sl_rate": {
+                    "type": "number",
+                    "description": "Average SL price level (for positions with SL)."
+                },
+                "avg_sl_pct_dist": {
+                    "type": "number",
+                    "description": "Average SL distance from open price % (for positions with SL)."
+                },
+                "sl_set_count": { "type": "number" },
+                "total_count": { "type": "number" },
+                "sl_set_rate_pct": {
+                    "type": "number",
+                    "description": "Percentage of positions that have a SL set."
+                }
+            },
+            "required": ["avg_sl_rate", "avg_sl_pct_dist", "sl_set_count", "total_count", "sl_set_rate_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the average SL level and usage rate per asset for speculators.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                sl_rate_sum: 0,
+                sl_dist_sum: 0,
+                sl_set_count: 0,
+                total_count: 0
+            });
+        }
+    }
+
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            assetData.total_count++;
+            
+            const sl_rate = pos.StopLossRate || 0;
+            if (sl_rate > 0) {
+                assetData.sl_set_count++;
+                assetData.sl_rate_sum += sl_rate;
+                
+                const open_rate = pos.OpenRate || 0;
+                if (open_rate > 0) {
+                    const distance = Math.abs(open_rate - sl_rate);
+                    assetData.sl_dist_sum += (distance / open_rate);
                 }
             }
         }
@@ -30,26 +97,27 @@ class StopLossPerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.stopLossData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            const data = this.stopLossData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const count = data.sl_set_count;
             
-            // REFACTOR: Perform final calculation directly.
-            if (data.count > 0) {
-                result[ticker] = {
-                    average_stop_loss: data.sum / data.count
-                };
-            }
+            result[ticker] = {
+                avg_sl_rate: (count > 0) ? (data.sl_rate_sum / count) : 0,
+                avg_sl_pct_dist: (count > 0) ? (data.sl_dist_sum / count) * 100 : 0,
+                sl_set_count: data.sl_set_count,
+                total_count: data.total_count,
+                sl_set_rate_pct: (data.total_count > 0) ? (data.sl_set_count / data.total_count) * 100 : 0
+            };
         }
-        
         return result;
     }
 
     reset() {
-        this.stopLossData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = StopLossPerAsset;
+module.exports = StopLossPerAsset;

package/calculations/speculators/take_profit_per_asset.js

@@ -1,26 +1,93 @@
 /**
- * @fileoverview Calculates the average take profit level per asset.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, what is the
+ * average take profit level and the percentage of
+ * positions that have a take profit set?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class TakeProfitPerAsset {
     constructor() {
-        this.takeProfitData = {};
+        // { [instrumentId]: { tp_rate_sum: 0, tp_dist_sum: 0, tp_set_count: 0, total_count: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            for (const position of portfolioData.PublicPositions) {
-                const instrumentId = position.InstrumentID;
-                const takeProfit = position.TakeProfitRate;
-
-                if (takeProfit > 0) {
-                    if (!this.takeProfitData[instrumentId]) {
-                        this.takeProfitData[instrumentId] = { sum: 0, count: 0 };
-                    }
-                    this.takeProfitData[instrumentId].sum += takeProfit;
-                    this.takeProfitData[instrumentId].count++;
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "avg_tp_rate": {
+                    "type": "number",
+                    "description": "Average TP price level (for positions with TP)."
+                },
+                "avg_tp_pct_dist": {
+                    "type": "number",
+                    "description": "Average TP distance from open price % (for positions with TP)."
+                },
+                "tp_set_count": { "type": "number" },
+                "total_count": { "type": "number" },
+                "tp_set_rate_pct": {
+                    "type": "number",
+                    "description": "Percentage of positions that have a TP set."
+                }
+            },
+            "required": ["avg_tp_rate", "avg_tp_pct_dist", "tp_set_count", "total_count", "tp_set_rate_pct"]
+        };
+
+        return {
+            "type": "object",
+            "description": "Calculates the average TP level and usage rate per asset for speculators.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                tp_rate_sum: 0,
+                tp_dist_sum: 0,
+                tp_set_count: 0,
+                total_count: 0
+            });
+        }
+    }
+
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            assetData.total_count++;
+            
+            const tp_rate = pos.TakeProfitRate || 0;
+            if (tp_rate > 0) {
+                assetData.tp_set_count++;
+                assetData.tp_rate_sum += tp_rate;
+                
+                const open_rate = pos.OpenRate || 0;
+                if (open_rate > 0) {
+                    const distance = Math.abs(tp_rate - open_rate);
+                    assetData.tp_dist_sum += (distance / open_rate);
                 }
             }
         }
@@ -30,26 +97,27 @@ class TakeProfitPerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.takeProfitData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            const data = this.takeProfitData[instrumentId];
-
-            // REFACTOR: Perform final calculation directly.
-            if (data.count > 0) {
-                result[ticker] = {
-                    average_take_profit: data.sum / data.count
-                };
-            }
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const count = data.tp_set_count;
+            
+            result[ticker] = {
+                avg_tp_rate: (count > 0) ? (data.tp_rate_sum / count) : 0,
+                avg_tp_pct_dist: (count > 0) ? (data.tp_dist_sum / count) * 100 : 0,
+                tp_set_count: data.tp_set_count,
+                total_count: data.total_count,
+                tp_set_rate_pct: (data.total_count > 0) ? (data.tp_set_count / data.total_count) * 100 : 0
+            };
         }
-
         return result;
     }
 
     reset() {
-        this.takeProfitData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }
 
-module.exports = TakeProfitPerAsset;
+module.exports = TakeProfitPerAsset;

package/calculations/speculators/tsl_per_asset.js

@@ -1,29 +1,77 @@
 /**
- * @fileoverview Counts how many users have TSL enabled vs. disabled per asset.
+ * @fileoverview Calculation (Pass 1) for speculator metric.
+ *
+ * This metric answers: "For each asset, how many
+ * speculators have Trailing Stop Loss (TSL) enabled
+ * versus disabled?"
  */
 const { loadInstrumentMappings } = require('../../utils/sector_mapping_provider');
 
 class TslPerAsset {
     constructor() {
-        this.tslData = {};
+        // { [instrumentId]: { enabled: 0, disabled: 0 } }
+        this.assets = new Map();
         this.mappings = null;
     }
 
-    process(portfolioData, yesterdayPortfolio, userId, context) {
-        if (portfolioData && portfolioData.PublicPositions) {
-            for (const position of portfolioData.PublicPositions) {
-                const instrumentId = position.InstrumentID;
-                const isTslEnabled = position.IsTslEnabled;
-
-                if (!this.tslData[instrumentId]) {
-                    this.tslData[instrumentId] = { enabled: 0, disabled: 0 };
+    /**
+     * Defines the output schema for this calculation.
+     * @returns {object} JSON Schema object
+     */
+    static getSchema() {
+        const tickerSchema = {
+            "type": "object",
+            "properties": {
+                "tsl_enabled_count": { "type": "number" },
+                "tsl_disabled_count": { "type": "number" },
+                "tsl_enabled_pct": {
+                    "type": "number",
+                    "description": "Percentage of positions with TSL enabled."
                 }
+            },
+            "required": ["tsl_enabled_count", "tsl_disabled_count", "tsl_enabled_pct"]
+        };
 
-                if (isTslEnabled) {
-                    this.tslData[instrumentId].enabled++;
-                } else {
-                    this.tslData[instrumentId].disabled++;
-                }
+        return {
+            "type": "object",
+            "description": "Calculates the TSL (Trailing Stop Loss) enabled vs. disabled rate per asset.",
+            "patternProperties": {
+                "^.*$": tickerSchema // Ticker
+            },
+            "additionalProperties": tickerSchema
+        };
+    }
+
+    _initAsset(instrumentId) {
+        if (!this.assets.has(instrumentId)) {
+            this.assets.set(instrumentId, {
+                enabled: 0,
+                disabled: 0
+            });
+        }
+    }
+
+    process(portfolioData) {
+        if (portfolioData?.context?.userType !== 'speculator') {
+            return;
+        }
+        
+        const positions = portfolioData.PublicPositions;
+        if (!positions || !Array.isArray(positions)) {
+            return;
+        }
+
+        for (const pos of positions) {
+            const instrumentId = pos.InstrumentID;
+            if (!instrumentId) continue;
+            
+            this._initAsset(instrumentId);
+            const assetData = this.assets.get(instrumentId);
+            
+            if (pos.IsTslEnabled) {
+                assetData.enabled++;
+            } else {
+                assetData.disabled++;
             }
         }
     }
@@ -32,19 +80,25 @@ class TslPerAsset {
         if (!this.mappings) {
             this.mappings = await loadInstrumentMappings();
         }
+
         const result = {};
-        for (const instrumentId in this.tslData) {
-            const ticker = this.mappings.instrumentToTicker[instrumentId] || instrumentId.toString();
-            result[ticker] = this.tslData[instrumentId];
+        for (const [instrumentId, data] of this.assets.entries()) {
+            const ticker = this.mappings.instrumentToTicker[instrumentId] || `id_${instrumentId}`;
+            const total = data.enabled + data.disabled;
+            
+            if (total > 0) {
+                result[ticker] = {
+                    tsl_enabled_count: data.enabled,
+                    tsl_disabled_count: data.disabled,
+                    tsl_enabled_pct: (data.enabled / total) * 100
+                };
+            }
         }
-        if (Object.keys(result).length === 0) return {};
-        return {
-            tsl_per_asset: result
-        };
+        return result;
     }
 
     reset() {
-        this.tslData = {};
+        this.assets.clear();
         this.mappings = null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-shared-calculations-unified",
-  "version": "1.0.63",
+  "version": "1.0.65",
   "description": "Shared calculation modules for the BullTrackers Computation System.",
   "main": "index.js",
   "files": [