@pioneer-platform/pioneer-subscriptions 1.0.0

package/lib/index.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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');
+ * ```
+ */
+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 declare class SubscriptionManager {
+    private blockbookSockets;
+    private sessions;
+    private addressToSessions;
+    private paymentCallbacks;
+    private isInitialized;
+    constructor();
+    /**
+     * Initialize the subscription manager and blockbook connections
+     */
+    init(): Promise<void>;
+    /**
+     * Register a callback to be called when payment notifications are received
+     */
+    onPayment(callback: PaymentCallback): void;
+    /**
+     * Remove a payment callback
+     */
+    offPayment(callback: PaymentCallback): void;
+    /**
+     * Setup listeners for blockbook websocket notifications
+     */
+    private setupBlockbookListeners;
+    /**
+     * Handle notification from blockbook about address activity
+     */
+    private handleBlockbookNotification;
+    /**
+     * Subscribe a session to monitor specific addresses
+     */
+    subscribe(request: SubscriptionRequest): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Unsubscribe a session from all its addresses
+     */
+    unsubscribe(sessionId: string): Promise<void>;
+    /**
+     * Get subscription statistics
+     */
+    getStats(): SubscriptionStats;
+    /**
+     * Get available coins for subscription
+     */
+    getAvailableCoins(): string[];
+    /**
+     * Check if initialized
+     */
+    isReady(): boolean;
+    /**
+     * Cleanup and shutdown
+     */
+    shutdown(): Promise<void>;
+}
+export default SubscriptionManager;

package/lib/index.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * 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');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionManager = void 0;
+const log = require('@pioneer-platform/loggerdog')();
+const blockbook = require('@pioneer-platform/blockbook');
+const TAG = ' | PioneerSubscriptions | ';
+class SubscriptionManager {
+    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() {
+        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) {
+        this.paymentCallbacks.add(callback);
+    }
+    /**
+     * Remove a payment callback
+     */
+    offPayment(callback) {
+        this.paymentCallbacks.delete(callback);
+    }
+    /**
+     * Setup listeners for blockbook websocket notifications
+     */
+    setupBlockbookListeners() {
+        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) => {
+                    this.handleBlockbookNotification(coin, data);
+                });
+                socket.on('error', (error) => {
+                    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
+     */
+    handleBlockbookNotification(coin, data) {
+        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 = {
+                    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) {
+        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 = [];
+            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) {
+            log.error(tag, 'Error subscribing:', error);
+            return {
+                success: false,
+                message: error.message || 'Unknown error'
+            };
+        }
+    }
+    /**
+     * Unsubscribe a session from all its addresses
+     */
+    async unsubscribe(sessionId) {
+        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() {
+        const sessionsByUsername = {};
+        const addressesByCoin = {};
+        const sessions = [];
+        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() {
+        return Object.keys(this.blockbookSockets);
+    }
+    /**
+     * Check if initialized
+     */
+    isReady() {
+        return this.isInitialized;
+    }
+    /**
+     * Cleanup and shutdown
+     */
+    async shutdown() {
+        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);
+        }
+    }
+}
+exports.SubscriptionManager = SubscriptionManager;
+// Export singleton instance
+exports.default = SubscriptionManager;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pioneer-platform/pioneer-subscriptions",
+  "version": "1.0.0",
+  "description": "Session-based blockchain address subscription manager for real-time payment notifications",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "test": "pnpm run build && node __tests__/test-module.js",
+    "build": "tsc -p .",
+    "prepublish": "tsc -p .",
+    "build:live": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' src/index.ts"
+  },
+  "dependencies": {
+    "@pioneer-platform/loggerdog": "^8.11.0",
+    "@pioneer-platform/blockbook": "^8.12.0"
+  },
+  "keywords": [
+    "blockchain",
+    "subscriptions",
+    "websocket",
+    "payments",
+    "notifications",
+    "pioneer"
+  ],
+  "author": "highlander",
+  "license": "MIT"
+}
+