@pioneer-platform/pioneer-subscriptions 1.0.0

package/src/index.ts

@@ -0,0 +1,422 @@
+/**
+ * Pioneer Subscriptions Module
+ * 
+ * Session-based blockchain address subscription manager for real-time payment notifications.
+ * 
+ * Features:
+ * - Subscribe to blockchain addresses via blockbook websockets
+ * - Session-based: subscriptions tied to client connection lifecycle  
+ * - Automatic cleanup on disconnect
+ * - Multi-chain support
+ * - Event callbacks for payment notifications
+ * 
+ * Usage:
+ * ```ts
+ * const manager = new SubscriptionManager();
+ * await manager.init();
+ * 
+ * // Register callback for payment notifications
+ * manager.onPayment((data) => {
+ *   console.log('Payment received:', data);
+ *   // Push to client via websocket
+ * });
+ * 
+ * // Subscribe addresses for a session
+ * await manager.subscribe({
+ *   sessionId: 'socket-123',
+ *   username: 'user1',
+ *   coin: 'BTC',
+ *   addresses: ['bc1q...', '3...']
+ * });
+ * 
+ * // On disconnect
+ * await manager.unsubscribe('socket-123');
+ * ```
+ */
+
+const log = require('@pioneer-platform/loggerdog')();
+const blockbook = require('@pioneer-platform/blockbook');
+
+const TAG = ' | PioneerSubscriptions | ';
+
+export interface SubscriptionRequest {
+  sessionId: string;
+  username: string;
+  coin: string;
+  addresses: string[];
+}
+
+export interface PaymentNotification {
+  sessionId: string;
+  username: string;
+  coin: string;
+  address: string;
+  txid: string;
+  amount: string;
+  confirmations: number;
+  timestamp: number;
+}
+
+export interface SessionSubscription {
+  sessionId: string;
+  username: string;
+  coin: string;
+  addresses: string[];
+  subscribedAt: number;
+}
+
+export interface SubscriptionStats {
+  totalSessions: number;
+  totalAddresses: number;
+  sessionsByUsername: Record<string, number>;
+  addressesByCoin: Record<string, number>;
+  sessions: SessionSubscription[];
+}
+
+type PaymentCallback = (notification: PaymentNotification) => void;
+
+export class SubscriptionManager {
+  private blockbookSockets: Record<string, any>;
+  private sessions: Map<string, SessionSubscription>;
+  private addressToSessions: Map<string, Set<string>>; // "COIN:address" -> sessionIds
+  private paymentCallbacks: Set<PaymentCallback>;
+  private isInitialized: boolean;
+
+  constructor() {
+    this.blockbookSockets = {};
+    this.sessions = new Map();
+    this.addressToSessions = new Map();
+    this.paymentCallbacks = new Set();
+    this.isInitialized = false;
+  }
+
+  /**
+   * Initialize the subscription manager and blockbook connections
+   */
+  async init(): Promise<void> {
+    const tag = TAG + ' | init | ';
+    try {
+      log.info(tag, 'Initializing Subscription Manager');
+      
+      // Initialize blockbook module
+      await blockbook.init();
+      
+      // Get blockbook websocket clients
+      this.blockbookSockets = blockbook.getBlockbookSockets();
+      
+      const availableCoins = Object.keys(this.blockbookSockets);
+      log.info(tag, `Blockbook sockets available for: ${availableCoins.join(', ')}`);
+      
+      // Setup listeners for each coin's blockbook socket
+      this.setupBlockbookListeners();
+      
+      this.isInitialized = true;
+      log.info(tag, '✅ Subscription Manager initialized successfully');
+      
+      return;
+    } catch (error) {
+      log.error(tag, 'Failed to initialize Subscription Manager:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Register a callback to be called when payment notifications are received
+   */
+  onPayment(callback: PaymentCallback): void {
+    this.paymentCallbacks.add(callback);
+  }
+
+  /**
+   * Remove a payment callback
+   */
+  offPayment(callback: PaymentCallback): void {
+    this.paymentCallbacks.delete(callback);
+  }
+
+  /**
+   * Setup listeners for blockbook websocket notifications
+   */
+  private setupBlockbookListeners(): void {
+    const tag = TAG + ' | setupBlockbookListeners | ';
+    
+    for (const [coin, socket] of Object.entries(this.blockbookSockets)) {
+      if (!socket) continue;
+      
+      try {
+        log.info(tag, `Setting up listener for ${coin}`);
+        
+        // Listen for address transaction notifications
+        socket.on('notification', (data: any) => {
+          this.handleBlockbookNotification(coin, data);
+        });
+        
+        socket.on('error', (error: any) => {
+          log.error(tag, `Blockbook socket error for ${coin}:`, error);
+        });
+        
+        socket.on('connect', () => {
+          log.info(tag, `Blockbook socket connected for ${coin}`);
+        });
+        
+        socket.on('disconnect', () => {
+          log.warn(tag, `Blockbook socket disconnected for ${coin}`);
+        });
+        
+      } catch (error) {
+        log.error(tag, `Failed to setup listener for ${coin}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Handle notification from blockbook about address activity
+   */
+  private handleBlockbookNotification(coin: string, data: any): void {
+    const tag = TAG + ' | handleBlockbookNotification | ';
+    
+    try {
+      log.debug(tag, `Received notification for ${coin}:`, data);
+      
+      // Extract address from notification
+      // Blockbook notification format: { address, tx: {...} }
+      const address = data.address;
+      if (!address) {
+        log.warn(tag, 'Notification missing address:', data);
+        return;
+      }
+      
+      // Find all sessions subscribed to this address
+      const addressKey = `${coin}:${address}`;
+      const sessionIds = this.addressToSessions.get(addressKey);
+      
+      if (!sessionIds || sessionIds.size === 0) {
+        log.debug(tag, `No subscribers for ${addressKey}`);
+        return;
+      }
+      
+      log.info(tag, `💰 Payment detected on ${addressKey}, notifying ${sessionIds.size} session(s)`);
+      
+      // Notify each subscribed session
+      for (const sessionId of sessionIds) {
+        const session = this.sessions.get(sessionId);
+        if (!session) continue;
+        
+        const notification: PaymentNotification = {
+          sessionId,
+          username: session.username,
+          coin,
+          address,
+          txid: data.tx?.txid || data.txid || 'unknown',
+          amount: data.tx?.value || data.value || '0',
+          confirmations: data.tx?.confirmations || 0,
+          timestamp: Date.now()
+        };
+        
+        // Call all registered callbacks
+        this.paymentCallbacks.forEach(callback => {
+          try {
+            callback(notification);
+          } catch (error) {
+            log.error(tag, 'Error in payment callback:', error);
+          }
+        });
+      }
+      
+    } catch (error) {
+      log.error(tag, 'Error handling blockbook notification:', error);
+    }
+  }
+
+  /**
+   * Subscribe a session to monitor specific addresses
+   */
+  async subscribe(request: SubscriptionRequest): Promise<{ success: boolean; message: string }> {
+    const tag = TAG + ' | subscribe | ';
+    
+    try {
+      if (!this.isInitialized) {
+        throw new Error('Subscription Manager not initialized');
+      }
+      
+      const { sessionId, username, coin, addresses } = request;
+      const coinUpper = coin.toUpperCase();
+      const blockbookSocket = this.blockbookSockets[coinUpper];
+      
+      if (!blockbookSocket) {
+        return {
+          success: false,
+          message: `Blockbook not available for ${coinUpper}`
+        };
+      }
+      
+      log.info(tag, `Subscribing session ${sessionId} (${username}) to ${addresses.length} addresses on ${coinUpper}`);
+      
+      // Subscribe to blockbook for each address
+      const subscribedAddresses: string[] = [];
+      for (const address of addresses) {
+        try {
+          // Subscribe via blockbook-client
+          await blockbookSocket.subscribeAddresses([address]);
+          
+          // Track subscription
+          const addressKey = `${coinUpper}:${address}`;
+          if (!this.addressToSessions.has(addressKey)) {
+            this.addressToSessions.set(addressKey, new Set());
+          }
+          this.addressToSessions.get(addressKey)!.add(sessionId);
+          subscribedAddresses.push(address);
+          
+          log.debug(tag, `✅ Subscribed to ${addressKey}`);
+        } catch (error) {
+          log.error(tag, `Failed to subscribe to ${address}:`, error);
+        }
+      }
+      
+      // Store or merge session info
+      const existing = this.sessions.get(sessionId);
+      if (existing && existing.coin === coinUpper) {
+        // Merge addresses
+        existing.addresses = Array.from(new Set([...existing.addresses, ...subscribedAddresses]));
+      } else {
+        // New session subscription
+        this.sessions.set(sessionId, {
+          sessionId,
+          username,
+          coin: coinUpper,
+          addresses: subscribedAddresses,
+          subscribedAt: Date.now()
+        });
+      }
+      
+      log.info(tag, `✅ Successfully subscribed session ${sessionId} to ${subscribedAddresses.length} addresses on ${coinUpper}`);
+      
+      return {
+        success: true,
+        message: `Subscribed to ${subscribedAddresses.length} addresses on ${coinUpper}`
+      };
+      
+    } catch (error: any) {
+      log.error(tag, 'Error subscribing:', error);
+      return {
+        success: false,
+        message: error.message || 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Unsubscribe a session from all its addresses
+   */
+  async unsubscribe(sessionId: string): Promise<void> {
+    const tag = TAG + ' | unsubscribe | ';
+    
+    try {
+      const session = this.sessions.get(sessionId);
+      if (!session) {
+        log.debug(tag, `No subscription found for session ${sessionId}`);
+        return;
+      }
+      
+      log.info(tag, `Unsubscribing session ${sessionId} from ${session.addresses.length} addresses on ${session.coin}`);
+      
+      const blockbookSocket = this.blockbookSockets[session.coin];
+      
+      // Remove from address mappings and unsubscribe if no more sessions
+      for (const address of session.addresses) {
+        const addressKey = `${session.coin}:${address}`;
+        const sessions = this.addressToSessions.get(addressKey);
+        
+        if (sessions) {
+          sessions.delete(sessionId);
+          
+          // If no more sessions for this address, unsubscribe from blockbook
+          if (sessions.size === 0) {
+            try {
+              if (blockbookSocket) {
+                await blockbookSocket.unsubscribeAddresses([address]);
+              }
+              this.addressToSessions.delete(addressKey);
+              log.debug(tag, `Unsubscribed from ${addressKey} (no more sessions)`);
+            } catch (error) {
+              log.error(tag, `Failed to unsubscribe from ${addressKey}:`, error);
+            }
+          }
+        }
+      }
+      
+      // Remove session
+      this.sessions.delete(sessionId);
+      
+      log.info(tag, `✅ Successfully cleaned up session ${sessionId}`);
+      
+    } catch (error) {
+      log.error(tag, 'Error unsubscribing:', error);
+    }
+  }
+
+  /**
+   * Get subscription statistics
+   */
+  getStats(): SubscriptionStats {
+    const sessionsByUsername: Record<string, number> = {};
+    const addressesByCoin: Record<string, number> = {};
+    const sessions: SessionSubscription[] = [];
+    
+    for (const session of this.sessions.values()) {
+      sessionsByUsername[session.username] = (sessionsByUsername[session.username] || 0) + 1;
+      addressesByCoin[session.coin] = (addressesByCoin[session.coin] || 0) + session.addresses.length;
+      sessions.push(session);
+    }
+    
+    return {
+      totalSessions: this.sessions.size,
+      totalAddresses: this.addressToSessions.size,
+      sessionsByUsername,
+      addressesByCoin,
+      sessions
+    };
+  }
+
+  /**
+   * Get available coins for subscription
+   */
+  getAvailableCoins(): string[] {
+    return Object.keys(this.blockbookSockets);
+  }
+
+  /**
+   * Check if initialized
+   */
+  isReady(): boolean {
+    return this.isInitialized;
+  }
+
+  /**
+   * Cleanup and shutdown
+   */
+  async shutdown(): Promise<void> {
+    const tag = TAG + ' | shutdown | ';
+    try {
+      log.info(tag, 'Shutting down Subscription Manager');
+      
+      // Unsubscribe all sessions
+      const sessionIds = Array.from(this.sessions.keys());
+      for (const sessionId of sessionIds) {
+        await this.unsubscribe(sessionId);
+      }
+      
+      // Clear callbacks
+      this.paymentCallbacks.clear();
+      
+      this.isInitialized = false;
+      log.info(tag, '✅ Subscription Manager shut down successfully');
+    } catch (error) {
+      log.error(tag, 'Error during shutdown:', error);
+    }
+  }
+}
+
+// Export singleton instance
+export default SubscriptionManager;
+

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts", "lib"]
+}
+