skayn-trading-sdk/src/interfaces/IPositionManager.js

Professional Bitcoin trading strategy backtesting framework with institutional-grade architecture

/**
 * Position Manager Interface
 * Defines contract for managing trading positions
 */
class IPositionManager {
  /**
   * Initialize the position manager
   * @param {Object} config - Position manager configuration
   */
  async initialize(config = {}) {
    throw new Error('IPositionManager.initialize() must be implemented');
  }

  /**
   * Open a new position
   * @param {Object} positionData - Position details
   * @param {Object} signal - Trading signal that triggered position
   * @returns {Promise<Object>} Opened position
   */
  async openPosition(positionData, signal) {
    throw new Error('IPositionManager.openPosition() must be implemented');
  }

  /**
   * Close a position
   * @param {string} positionId - Position identifier
   * @param {number} exitPrice - Exit price
   * @param {string} reason - Reason for closing
   * @returns {Promise<Object>} Closed position with P&L
   */
  async closePosition(positionId, exitPrice, reason = 'Manual close') {
    throw new Error('IPositionManager.closePosition() must be implemented');
  }

  /**
   * Update position with current market price
   * @param {string} positionId - Position identifier
   * @param {number} currentPrice - Current market price
   * @returns {Promise<Object>} Updated position
   */
  async updatePosition(positionId, currentPrice) {
    throw new Error('IPositionManager.updatePosition() must be implemented');
  }

  /**
   * Get all open positions
   * @returns {Promise<Array>} Array of open positions
   */
  async getOpenPositions() {
    throw new Error('IPositionManager.getOpenPositions() must be implemented');
  }

  /**
   * Get all closed positions
   * @returns {Promise<Array>} Array of closed positions
   */
  async getClosedPositions() {
    throw new Error('IPositionManager.getClosedPositions() must be implemented');
  }

  /**
   * Get position by ID
   * @param {string} positionId - Position identifier
   * @returns {Promise<Object>} Position details
   */
  async getPosition(positionId) {
    throw new Error('IPositionManager.getPosition() must be implemented');
  }

  /**
   * Get portfolio state summary
   * @returns {Promise<Object>} Portfolio state
   */
  async getPortfolioState() {
    throw new Error('IPositionManager.getPortfolioState() must be implemented');
  }

  /**
   * Calculate unrealized P&L for open positions
   * @param {number} currentPrice - Current market price
   * @returns {Promise<number>} Total unrealized P&L
   */
  async calculateUnrealizedPnL(currentPrice) {
    throw new Error('IPositionManager.calculateUnrealizedPnL() must be implemented');
  }

  /**
   * Calculate realized P&L from closed positions
   * @param {Object} filters - Date range, strategy filters
   * @returns {Promise<number>} Total realized P&L
   */
  async calculateRealizedPnL(filters = {}) {
    throw new Error('IPositionManager.calculateRealizedPnL() must be implemented');
  }

  /**
   * Get position performance metrics
   * @param {Object} filters - Analysis filters
   * @returns {Promise<Object>} Performance metrics
   */
  async getPerformanceMetrics(filters = {}) {
    throw new Error('IPositionManager.getPerformanceMetrics() must be implemented');
  }

  /**
   * Check if strategy can open new position (position limits)
   * @param {string} strategy - Strategy name
   * @param {Object} positionData - Proposed position
   * @returns {Promise<boolean>} Whether position can be opened
   */
  async canOpenPosition(strategy, positionData) {
    throw new Error('IPositionManager.canOpenPosition() must be implemented');
  }

  /**
   * Get total exposure (sum of all position values)
   * @returns {Promise<number>} Total exposure
   */
  async getTotalExposure() {
    throw new Error('IPositionManager.getTotalExposure() must be implemented');
  }

  /**
   * Get exposure by strategy
   * @param {string} strategy - Strategy name
   * @returns {Promise<number>} Strategy exposure
   */
  async getStrategyExposure(strategy) {
    throw new Error('IPositionManager.getStrategyExposure() must be implemented');
  }

  /**
   * Set position sizing rules
   * @param {Object} rules - Position sizing configuration
   */
  setPositionSizingRules(rules) {
    throw new Error('IPositionManager.setPositionSizingRules() must be implemented');
  }

  /**
   * Set strategy-specific position limits
   * @param {string} strategy - Strategy name
   * @param {Object} limits - Position limits
   */
  setStrategyLimits(strategy, limits) {
    throw new Error('IPositionManager.setStrategyLimits() must be implemented');
  }

  /**
   * Close all positions for a strategy
   * @param {string} strategy - Strategy name
   * @param {number} currentPrice - Current market price
   * @param {string} reason - Reason for closing
   * @returns {Promise<Array>} Array of closed positions
   */
  async closeAllPositionsForStrategy(strategy, currentPrice, reason = 'Strategy shutdown') {
    throw new Error('IPositionManager.closeAllPositionsForStrategy() must be implemented');
  }

  /**
   * Close all open positions
   * @param {number} currentPrice - Current market price
   * @param {string} reason - Reason for closing
   * @returns {Promise<Array>} Array of closed positions
   */
  async closeAllPositions(currentPrice, reason = 'Manual close all') {
    throw new Error('IPositionManager.closeAllPositions() must be implemented');
  }

  /**
   * Get positions by strategy
   * @param {string} strategy - Strategy name
   * @param {boolean} openOnly - Whether to return only open positions
   * @returns {Promise<Array>} Array of positions
   */
  async getPositionsByStrategy(strategy, openOnly = true) {
    throw new Error('IPositionManager.getPositionsByStrategy() must be implemented');
  }

  /**
   * Reset position manager state
   */
  reset() {
    throw new Error('IPositionManager.reset() must be implemented');
  }

  /**
   * Get position manager metadata
   * @returns {Object} Position manager information
   */
  getPositionManagerMetadata() {
    return {
      name: 'Unknown Position Manager',
      version: '1.0.0',
      description: 'Base position manager interface',
      maxPositions: 10,
      supportedOrderTypes: ['market', 'limit']
    };
  }

  /**
   * Cleanup resources
   */
  async cleanup() {
    // Optional cleanup - override if needed
  }
}

module.exports = IPositionManager;