@pioneer-platform/pioneer-subscriptions 1.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc -p .

package/IMPLEMENTATION.md

@@ -0,0 +1,275 @@
+# Blockbook Subscription Implementation
+
+## What We Built
+
+A clean, focused, **session-based subscription system** for real-time blockchain payment notifications.
+
+### Clean Architecture ✅
+
+**Before**: Bloated 1101-line WebSocketHandler doing everything  
+**After**: Modular design with separation of concerns
+
+```
+modules/pioneer/pioneer-subscriptions/
+├── package.json           # Clean dependencies
+├── tsconfig.json         # TypeScript config
+├── build.sh              # Build script
+├── README.md             # Full documentation
+├── IMPLEMENTATION.md     # This file
+├── src/
+│   └── index.ts          # ~450 lines, focused, clean
+└── __tests__/
+    └── test-module.js    # Complete test suite
+```
+
+## How It Works
+
+### 1. Session-Based Subscriptions
+
+User connects → Sends addresses → We subscribe to blockbook → On disconnect, we cleanup
+
+```typescript
+// User connects via WebSocket
+socket.on('subscribe_addresses', async (data) => {
+  await subscriptionManager.subscribe({
+    sessionId: socket.id,
+    username: 'user123',
+    coin: 'BTC',
+    addresses: ['bc1q...', '3...']
+  });
+});
+
+// Payment happens on blockchain
+// → Blockbook notifies us
+// → We push to user's socket
+subscriptionManager.onPayment((notification) => {
+  io.to(notification.sessionId).emit('payment', notification);
+});
+
+// User disconnects
+socket.on('disconnect', async () => {
+  await subscriptionManager.unsubscribe(socket.id);
+  // All addresses automatically unsubscribed
+  // No memory leaks!
+});
+```
+
+### 2. Architecture
+
+```
+┌─────────────┐
+│   Client    │  WebSocket connection
+└──────┬──────┘
+       │
+       ├─ connect
+       ├─ subscribe_addresses { coin, addresses[] }
+       ├─ disconnect
+       │
+       ▼
+┌──────────────────────┐
+│  WebSocketHandler    │  Lean & focused
+│  (pioneer-server)    │  - Handles connections
+└──────┬───────────────┘  - Routes messages
+       │                  - Auth & state
+       │
+       │ Uses
+       ▼
+┌───────────────────────┐
+│  SubscriptionManager  │  Clean module
+│  (pioneer-subscriptions)│ - Subscribe/unsubscribe
+│                       │  - Session management
+│  - Sessions Map       │  - Payment callbacks
+│  - Address → Sessions │  - Auto cleanup
+│  - Callbacks          │
+└──────┬────────────────┘
+       │
+       │ Subscribes to
+       ▼
+┌───────────────────────┐
+│  Blockbook WebSocket  │  Per-chain sockets
+│  (BTC, LTC, DOGE...)  │  - Address subscriptions
+└──────┬────────────────┘  - TX notifications
+       │
+       │ Monitors
+       ▼
+┌───────────────────────┐
+│  Blockchain Nodes     │  Real blockchain
+└───────────────────────┘
+```
+
+## Next Steps
+
+### Test the Module
+
+```bash
+cd /Users/highlander/WebstormProjects/keepkey-stack/projects/pioneer/modules/pioneer/pioneer-subscriptions
+
+# Install dependencies
+pnpm install
+
+# Build
+pnpm run build
+
+# Test
+pnpm test
+```
+
+Expected output:
+```
+🧪 Testing Pioneer Subscriptions Module
+
+Test 1: Initializing Subscription Manager...
+✅ Manager initialized
+Available coins: BTC, LTC, DOGE, DASH, ...
+
+Test 2: Registering payment callback...
+✅ Callback registered
+
+Test 3: Subscribing to Bitcoin addresses...
+Subscribe result: { success: true, message: 'Subscribed to 2 addresses on BTC' }
+
+Test 4: Getting subscription stats...
+Stats: {
+  "totalSessions": 1,
+  "totalAddresses": 2,
+  ...
+}
+
+✅ All tests passed!
+```
+
+### Integrate with Pioneer-Server
+
+Once tests pass, integrate into pioneer-server:
+
+```typescript
+// services/pioneer-server/src/app.ts
+import { SubscriptionManager } from '@pioneer-platform/pioneer-subscriptions';
+
+// Initialize
+const subscriptionManager = new SubscriptionManager();
+await subscriptionManager.init();
+
+// Setup payment forwarding
+subscriptionManager.onPayment((notification) => {
+  wsHandler.emitToSocket(notification.sessionId, 'payment', notification);
+});
+
+// In WebSocketHandler.handleConnection()
+socket.on('subscribe_addresses', async (msg) => {
+  const username = this.state.usersBySocketId[socket.id];
+  if (!username) {
+    socket.emit('error', { error: 'Not authenticated' });
+    return;
+  }
+  
+  const result = await subscriptionManager.subscribe({
+    sessionId: socket.id,
+    username,
+    coin: msg.coin,
+    addresses: msg.addresses
+  });
+  
+  socket.emit('subscribe_result', result);
+});
+
+// In WebSocketHandler.handleDisconnect()
+await subscriptionManager.unsubscribe(socket.id);
+```
+
+## Client Usage
+
+```typescript
+// Connect to pioneer-server
+const socket = io('wss://pioneers.dev');
+
+// Authenticate
+socket.emit('authenticate', { username: 'user123', queryKey: 'key...' });
+
+// Subscribe to addresses
+socket.emit('subscribe_addresses', {
+  coin: 'BTC',
+  addresses: [
+    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+    '3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy'
+  ]
+});
+
+// Listen for payments
+socket.on('payment', (notification) => {
+  console.log('💰 Payment received!', notification);
+  // {
+  //   coin: 'BTC',
+  //   address: 'bc1q...',
+  //   txid: 'abc123...',
+  //   amount: '50000',  // satoshis
+  //   confirmations: 0,
+  //   timestamp: 1234567890
+  // }
+  
+  // Show notification to user
+  showToast(`Received ${notification.amount} sats!`);
+});
+```
+
+## Benefits
+
+### ✅ Clean Code
+- **450 lines** vs 1101 lines
+- Single responsibility
+- Easy to test
+- Easy to maintain
+
+### ✅ Modular
+- Separate package
+- Reusable
+- Versionable
+- Independent deployment
+
+### ✅ No Memory Leaks
+- Automatic cleanup on disconnect
+- Session-based lifecycle
+- Proper unsubscribe from blockbook
+
+### ✅ Observable
+- Statistics API
+- Track sessions, addresses, users
+- Monitor subscription health
+
+### ✅ Type-Safe
+- Full TypeScript types
+- Clear interfaces
+- Great IDE support
+
+## Testing Checklist
+
+- [ ] Build module: `pnpm run build`
+- [ ] Run tests: `pnpm test`
+- [ ] Verify blockbook connection
+- [ ] Subscribe to test addresses
+- [ ] Trigger test payment (testnet)
+- [ ] Verify notification received
+- [ ] Test disconnect/cleanup
+- [ ] Check memory usage
+- [ ] Integrate with pioneer-server
+- [ ] End-to-end test with real client
+
+## Support
+
+For issues or questions:
+- Check logs with `@pioneer-platform/loggerdog`
+- Review `getStats()` for subscription state
+- Verify blockbook connectivity: `getAvailableCoins()`
+- Test with testnet addresses first
+
+## Future Enhancements
+
+- [ ] Support for xpub subscriptions (derive & monitor all addresses)
+- [ ] Batch subscription API
+- [ ] Subscription persistence (Redis)
+- [ ] Rate limiting
+- [ ] Subscription filters (min amount, confirmations)
+- [ ] Historical transaction notifications
+- [ ] Multi-node failover
+- [ ] Metrics & monitoring
+

package/README.md

@@ -0,0 +1,233 @@
+# @pioneer-platform/pioneer-subscriptions
+
+Session-based blockchain address subscription manager for real-time payment notifications.
+
+## Features
+
+- 🔔 **Real-time notifications** - Receive instant alerts when addresses receive payments
+- 🔄 **Session-based** - Subscriptions automatically tied to client connection lifecycle
+- 🧹 **Auto-cleanup** - Subscriptions removed when clients disconnect
+- ⛓️ **Multi-chain** - Support for all blockbook-enabled blockchains (BTC, LTC, DOGE, DASH, etc.)
+- 🎯 **Event-driven** - Simple callback API for handling payment notifications
+- 📊 **Statistics** - Track active subscriptions and sessions
+
+## Installation
+
+```bash
+pnpm add @pioneer-platform/pioneer-subscriptions
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { SubscriptionManager } from '@pioneer-platform/pioneer-subscriptions';
+
+// Initialize
+const manager = new SubscriptionManager();
+await manager.init();
+
+// Register callback for payment notifications
+manager.onPayment((notification) => {
+  console.log('Payment received:', notification);
+  // {
+  //   sessionId: 'socket-123',
+  //   username: 'user1',
+  //   coin: 'BTC',
+  //   address: 'bc1q...',
+  //   txid: 'abc123...',
+  //   amount: '50000',
+  //   confirmations: 0,
+  //   timestamp: 1234567890
+  // }
+  
+  // Push to client via WebSocket
+  io.to(notification.sessionId).emit('payment:notification', notification);
+});
+```
+
+### Subscribe to Addresses
+
+```typescript
+// When client connects and sends addresses to monitor
+const result = await manager.subscribe({
+  sessionId: socket.id,
+  username: 'user123',
+  coin: 'BTC',
+  addresses: [
+    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
+    '3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy'
+  ]
+});
+
+console.log(result);
+// { success: true, message: 'Subscribed to 2 addresses on BTC' }
+```
+
+### Unsubscribe on Disconnect
+
+```typescript
+// When client disconnects
+socket.on('disconnect', async () => {
+  await manager.unsubscribe(socket.id);
+  console.log('Session cleaned up');
+});
+```
+
+### Get Statistics
+
+```typescript
+const stats = manager.getStats();
+console.log(stats);
+// {
+//   totalSessions: 5,
+//   totalAddresses: 12,
+//   sessionsByUsername: { 'user1': 2, 'user2': 3 },
+//   addressesByCoin: { 'BTC': 8, 'LTC': 4 },
+//   sessions: [...]
+// }
+```
+
+## WebSocket Integration Example
+
+```typescript
+import { SubscriptionManager } from '@pioneer-platform/pioneer-subscriptions';
+import { Server } from 'socket.io';
+
+const io = new Server(server);
+const subscriptionManager = new SubscriptionManager();
+await subscriptionManager.init();
+
+// Setup payment notification forwarding
+subscriptionManager.onPayment((notification) => {
+  // Send to specific session
+  io.to(notification.sessionId).emit('payment', notification);
+  
+  // Also log for monitoring
+  console.log(`💰 Payment: ${notification.amount} ${notification.coin} to ${notification.address}`);
+});
+
+// Handle client connections
+io.on('connection', (socket) => {
+  console.log('Client connected:', socket.id);
+  
+  // Client sends addresses to monitor
+  socket.on('subscribe_addresses', async (data) => {
+    const { coin, addresses } = data;
+    const username = socket.data.username; // From auth
+    
+    const result = await subscriptionManager.subscribe({
+      sessionId: socket.id,
+      username,
+      coin,
+      addresses
+    });
+    
+    socket.emit('subscribe_result', result);
+  });
+  
+  // Cleanup on disconnect
+  socket.on('disconnect', async () => {
+    await subscriptionManager.unsubscribe(socket.id);
+    console.log('Client disconnected and unsubscribed:', socket.id);
+  });
+});
+```
+
+## API
+
+### `SubscriptionManager`
+
+#### Methods
+
+- **`init(): Promise<void>`** - Initialize the manager and connect to blockbook
+- **`subscribe(request): Promise<{success, message}>`** - Subscribe a session to addresses
+- **`unsubscribe(sessionId): Promise<void>`** - Unsubscribe a session and cleanup
+- **`onPayment(callback): void`** - Register a payment notification callback
+- **`offPayment(callback): void`** - Remove a payment callback
+- **`getStats(): SubscriptionStats`** - Get subscription statistics
+- **`getAvailableCoins(): string[]`** - Get list of supported coins
+- **`isReady(): boolean`** - Check if manager is initialized
+- **`shutdown(): Promise<void>`** - Cleanup and shutdown
+
+#### Types
+
+```typescript
+interface SubscriptionRequest {
+  sessionId: string;    // Unique session/socket ID
+  username: string;     // Username for tracking
+  coin: string;         // Coin symbol (BTC, LTC, etc.)
+  addresses: string[];  // Array of addresses to monitor
+}
+
+interface PaymentNotification {
+  sessionId: string;
+  username: string;
+  coin: string;
+  address: string;
+  txid: string;
+  amount: string;       // In satoshis/smallest unit
+  confirmations: number;
+  timestamp: number;
+}
+
+interface SubscriptionStats {
+  totalSessions: number;
+  totalAddresses: number;
+  sessionsByUsername: Record<string, number>;
+  addressesByCoin: Record<string, number>;
+  sessions: SessionSubscription[];
+}
+```
+
+## Architecture
+
+```
+┌─────────────┐
+│   Client    │
+│  (Browser)  │
+└──────┬──────┘
+       │ WebSocket
+       │ subscribe_addresses
+       ▼
+┌─────────────────┐
+│   WebSocket     │
+│    Server       │
+└────────┬────────┘
+         │
+         │ manager.subscribe()
+         ▼
+┌─────────────────────┐
+│ SubscriptionManager │
+│                     │
+│  - Sessions Map     │
+│  - Address Map      │
+│  - Callbacks        │
+└──────────┬──────────┘
+           │
+           │ subscribeAddresses()
+           ▼
+┌─────────────────────┐
+│   Blockbook WS      │
+│   (per chain)       │
+└──────────┬──────────┘
+           │
+           │ TX notifications
+           ▼
+┌─────────────────────┐
+│  Blockchain Node    │
+└─────────────────────┘
+```
+
+## Testing
+
+```bash
+pnpm run build
+pnpm test
+```
+
+## License
+
+MIT
+

package/__tests__/test-module.js

@@ -0,0 +1,83 @@
+/**
+ * Test Pioneer Subscriptions Module
+ */
+
+const { SubscriptionManager } = require('../lib/index');
+
+async function runTest() {
+  console.log('🧪 Testing Pioneer Subscriptions Module\n');
+  
+  try {
+    // Test 1: Initialize
+    console.log('Test 1: Initializing Subscription Manager...');
+    const manager = new SubscriptionManager();
+    await manager.init();
+    console.log('✅ Manager initialized');
+    console.log('Available coins:', manager.getAvailableCoins().join(', '));
+    console.log('');
+    
+    // Test 2: Register payment callback
+    console.log('Test 2: Registering payment callback...');
+    manager.onPayment((notification) => {
+      console.log('💰 Payment notification received:', notification);
+    });
+    console.log('✅ Callback registered');
+    console.log('');
+    
+    // Test 3: Subscribe to addresses
+    console.log('Test 3: Subscribing to Bitcoin addresses...');
+    const result = await manager.subscribe({
+      sessionId: 'test-session-1',
+      username: 'test-user',
+      coin: 'BTC',
+      addresses: [
+        'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', // Example BTC address
+        '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'  // Genesis block address
+      ]
+    });
+    console.log('Subscribe result:', result);
+    console.log('');
+    
+    // Test 4: Get stats
+    console.log('Test 4: Getting subscription stats...');
+    const stats = manager.getStats();
+    console.log('Stats:', JSON.stringify(stats, null, 2));
+    console.log('');
+    
+    // Test 5: Subscribe another session
+    console.log('Test 5: Subscribing another session...');
+    await manager.subscribe({
+      sessionId: 'test-session-2',
+      username: 'test-user-2',
+      coin: 'BTC',
+      addresses: [
+        '3J98t1WpEZ73CNmYviecrnyiWrnqRhWNLy'
+      ]
+    });
+    console.log('✅ Second session subscribed');
+    console.log('Updated stats:', JSON.stringify(manager.getStats(), null, 2));
+    console.log('');
+    
+    // Test 6: Unsubscribe
+    console.log('Test 6: Unsubscribing first session...');
+    await manager.unsubscribe('test-session-1');
+    console.log('✅ Session unsubscribed');
+    console.log('Stats after unsubscribe:', JSON.stringify(manager.getStats(), null, 2));
+    console.log('');
+    
+    // Test 7: Cleanup
+    console.log('Test 7: Shutting down...');
+    await manager.shutdown();
+    console.log('✅ Manager shut down');
+    console.log('');
+    
+    console.log('✅ All tests passed!');
+    
+  } catch (error) {
+    console.error('❌ Test failed:', error);
+    process.exit(1);
+  }
+}
+
+runTest();
+

package/build.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+echo "Building @pioneer-platform/pioneer-subscriptions..."
+pnpm run build
+echo "Build complete!"
+