@rotateprotocol/sdk 1.0.0

package/src/webhooks.ts

@@ -0,0 +1,506 @@
+/**
+ * Rotate Protocol Webhooks
+ * 
+ * Listen to on-chain payment events and receive notifications.
+ * This does NOT change the P2P nature - webhooks are notifications only.
+ * 
+ * @packageDocumentation
+ */
+
+import { Connection, PublicKey } from '@solana/web3.js';
+import { BorshCoder } from '@coral-xyz/anchor';
+import { PROGRAM_ID, Network } from './index';
+import IDL from './idl/rotate_connect.json';
+
+// ==================== TYPES ====================
+
+export type WebhookEventType =
+  | 'protocol.initialized'
+  | 'protocol.updated'
+  | 'platform.created'
+  | 'platform.updated'
+  | 'merchant.created'
+  | 'merchant.updated'
+  | 'payment.completed'
+  | 'payment.pending'
+  | 'link.created'
+  | 'link.created.usd'
+  | 'link.paid'
+  | 'link.paid.usd'
+  | 'link.cancelled'
+  | 'link.closed'
+  | 'link.expired';
+
+export interface WebhookEvent {
+  /** Unique event ID */
+  id: string;
+  /** Event type */
+  type: WebhookEventType;
+  /** Timestamp */
+  timestamp: number;
+  /** Transaction signature */
+  transactionSignature: string;
+  /** Event data */
+  data: WebhookEventData;
+}
+
+export interface WebhookEventData {
+  linkId?: number;
+  merchantId?: number;
+  platformId?: number;
+  payerWallet?: string;
+  merchantWallet?: string;
+  platformWallet?: string;
+  treasuryWallet?: string;
+  amountUsd?: number;
+  amountLamports?: number;
+  amountTokens?: number;
+  protocolFee?: number;
+  platformFee?: number;
+  tipAmount?: number;
+  currency?: 'SOL' | 'USDC' | 'USDT' | 'USD';
+  tokenType?: string;
+  orderRef?: string;
+  status?: string;
+  active?: boolean;
+  feeBps?: number;
+}
+
+export interface WebhookConfig {
+  /** Webhook endpoint URL */
+  url: string;
+  /** Events to subscribe to */
+  events: WebhookEventType[];
+  /** Filter by merchant ID (optional) */
+  merchantId?: number;
+  /** Filter by platform ID (optional) */
+  platformId?: number;
+  /** Secret for HMAC signature verification */
+  secret: string;
+}
+
+export type EventHandler = (event: WebhookEvent) => void | Promise<void>;
+
+// ==================== SIGNATURE VERIFICATION ====================
+
+/**
+ * Verify webhook signature (for webhook receivers)
+ */
+export async function verifyWebhookSignature(
+  payload: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+  
+  const expectedSig = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+  const expectedHex = Array.from(new Uint8Array(expectedSig))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+  
+  return signature === expectedHex;
+}
+
+/**
+ * Create webhook signature (for webhook senders)
+ */
+export async function createWebhookSignature(payload: string, secret: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+  
+  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+  return Array.from(new Uint8Array(signature))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+// ==================== EVENT LISTENER ====================
+
+export interface EventListenerOptions {
+  /** Solana network */
+  network: Network;
+  /** Custom RPC endpoint */
+  rpcEndpoint?: string;
+  /** Poll interval in ms (default: 5000) */
+  pollIntervalMs?: number;
+  /** Filter by merchant ID */
+  merchantId?: number;
+  /** Filter by platform ID */
+  platformId?: number;
+}
+
+/**
+ * On-chain event listener
+ * Polls the blockchain for new transactions and emits events
+ */
+export class EventListener {
+  private connection: Connection;
+  private programId: PublicKey;
+  private options: EventListenerOptions;
+  private handlers: Map<WebhookEventType, EventHandler[]> = new Map();
+  private lastSignature: string | null = null;
+  private isRunning = false;
+  private pollInterval: NodeJS.Timeout | null = null;
+  private coder: BorshCoder;
+  
+  constructor(options: EventListenerOptions) {
+    this.options = options;
+    this.programId = PROGRAM_ID;
+    this.coder = new BorshCoder(IDL as any);
+    
+    const endpoint = options.rpcEndpoint ||
+      (options.network === 'mainnet-beta'
+        ? 'https://api.mainnet-beta.solana.com'
+        : 'https://api.devnet.solana.com');
+    
+    this.connection = new Connection(endpoint, 'confirmed');
+  }
+  
+  /**
+   * Subscribe to an event type
+   */
+  on(eventType: WebhookEventType, handler: EventHandler): void {
+    const handlers = this.handlers.get(eventType) || [];
+    handlers.push(handler);
+    this.handlers.set(eventType, handlers);
+  }
+  
+  /**
+   * Unsubscribe from an event type
+   */
+  off(eventType: WebhookEventType, handler: EventHandler): void {
+    const handlers = this.handlers.get(eventType) || [];
+    const index = handlers.indexOf(handler);
+    if (index > -1) {
+      handlers.splice(index, 1);
+      this.handlers.set(eventType, handlers);
+    }
+  }
+  
+  /**
+   * Subscribe to all events
+   */
+  onAny(handler: EventHandler): void {
+    const allTypes: WebhookEventType[] = [
+      'protocol.initialized',
+      'protocol.updated',
+      'platform.created',
+      'platform.updated',
+      'merchant.created',
+      'merchant.updated',
+      'payment.completed',
+      'payment.pending',
+      'link.created',
+      'link.created.usd',
+      'link.paid',
+      'link.paid.usd',
+      'link.cancelled',
+      'link.closed',
+      'link.expired',
+    ];
+    allTypes.forEach(type => this.on(type, handler));
+  }
+  
+  /**
+   * Start listening for events
+   */
+  start(): void {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    
+    this.poll();
+    this.pollInterval = setInterval(
+      () => this.poll(),
+      this.options.pollIntervalMs || 5000
+    );
+  }
+  
+  /**
+   * Stop listening for events
+   */
+  stop(): void {
+    this.isRunning = false;
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = null;
+    }
+  }
+  
+  /**
+   * Poll for new transactions
+   */
+  private async poll(): Promise<void> {
+    try {
+      const signatures = await this.connection.getSignaturesForAddress(
+        this.programId,
+        {
+          limit: 20,
+          until: this.lastSignature || undefined,
+        }
+      );
+      
+      if (signatures.length === 0) return;
+      
+      // Update last signature
+      this.lastSignature = signatures[0].signature;
+      
+      // Process transactions in order (oldest first)
+      for (const sig of signatures.reverse()) {
+        await this.processTransaction(sig.signature);
+      }
+    } catch (error) {
+      console.error('Error polling for events:', error);
+    }
+  }
+  
+  /**
+   * Process a transaction and emit decoded events
+   */
+  private async processTransaction(signature: string): Promise<void> {
+    try {
+      const tx = await this.connection.getParsedTransaction(signature, {
+        maxSupportedTransactionVersion: 0,
+      });
+      
+      if (!tx?.meta?.logMessages) return;
+      
+      const events: WebhookEvent[] = [];
+      const timestamp = tx.blockTime ? tx.blockTime * 1000 : Date.now();
+      
+      // Decode Anchor events from "Program data:" log entries
+      for (const log of tx.meta.logMessages) {
+        if (!log.startsWith('Program data: ')) continue;
+        
+        try {
+          const base64Data = log.slice('Program data: '.length);
+          const decoded = this.coder.events.decode(base64Data);
+          if (!decoded) continue;
+          
+          const webhookType = this.anchorEventToWebhookType(decoded.name);
+          if (!webhookType) continue;
+          
+          events.push({
+            id: `evt_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            type: webhookType,
+            timestamp,
+            transactionSignature: signature,
+            data: this.mapEventData(decoded.name, decoded.data),
+          });
+        } catch {
+          // Skip events that can't be decoded
+        }
+      }
+      
+      for (const event of events) {
+        // Apply filters
+        if (this.options.merchantId && event.data.merchantId !== this.options.merchantId) {
+          continue;
+        }
+        if (this.options.platformId && event.data.platformId !== this.options.platformId) {
+          continue;
+        }
+        
+        // Emit to handlers
+        await this.emit(event);
+      }
+    } catch (error) {
+      console.error('Error processing transaction:', error);
+    }
+  }
+  
+  /** Map Anchor event name to webhook event type */
+  private anchorEventToWebhookType(name: string): WebhookEventType | null {
+    const map: Record<string, WebhookEventType> = {
+      'ProtocolInitialized': 'protocol.initialized',
+      'ProtocolUpdated': 'protocol.updated',
+      'PlatformCreated': 'platform.created',
+      'PlatformUpdated': 'platform.updated',
+      'MerchantCreated': 'merchant.created',
+      'MerchantUpdated': 'merchant.updated',
+      'PaymentProcessed': 'payment.completed',
+      'LinkCreated': 'link.created',
+      'LinkCreatedUsd': 'link.created.usd',
+      'LinkPaid': 'link.paid',
+      'LinkPaidUsd': 'link.paid.usd',
+      'LinkCancelled': 'link.cancelled',
+      'LinkClosed': 'link.closed',
+    };
+    return map[name] || null;
+  }
+  
+  /** Map decoded Anchor event data to WebhookEventData */
+  private mapEventData(eventName: string, data: any): WebhookEventData {
+    const result: WebhookEventData = {};
+    
+    // ID field: link ID for Link* events, platform/merchant ID for others
+    if (data.id !== undefined) {
+      if (eventName.startsWith('Link')) {
+        result.linkId = Number(data.id);
+      } else if (eventName.startsWith('Platform')) {
+        result.platformId = Number(data.id);
+      } else if (eventName.startsWith('Merchant')) {
+        result.merchantId = Number(data.id);
+      }
+    }
+    
+    // Common entity IDs (Anchor camelCases snake_case fields)
+    if (data.merchantId !== undefined) result.merchantId = Number(data.merchantId);
+    if (data.platformId !== undefined) result.platformId = Number(data.platformId);
+    
+    // Wallet addresses
+    if (data.payer) result.payerWallet = data.payer.toString();
+    if (data.wallet) result.merchantWallet = data.wallet.toString();
+    if (data.admin) result.platformWallet = data.admin.toString();
+    if (data.treasury) result.treasuryWallet = data.treasury.toString();
+    
+    // Amounts
+    if (data.amount !== undefined) result.amountLamports = Number(data.amount);
+    if (data.amountUsd !== undefined) result.amountUsd = Number(data.amountUsd) / 1_000_000;
+    if (data.usdAmount !== undefined) result.amountUsd = Number(data.usdAmount) / 1_000_000;
+    if (data.merchantAmount !== undefined) result.amountTokens = Number(data.merchantAmount);
+    
+    // Fees
+    if (data.protocolFee !== undefined) result.protocolFee = Number(data.protocolFee);
+    if (data.platformFee !== undefined) result.platformFee = Number(data.platformFee);
+    if (data.feeBps !== undefined) result.feeBps = Number(data.feeBps);
+    
+    // Tips
+    if (data.tip !== undefined) result.tipAmount = Number(data.tip);
+    if (data.tipUsd !== undefined) result.tipAmount = Number(data.tipUsd) / 1_000_000;
+    
+    // Order reference
+    if (data.orderRef !== undefined) result.orderRef = data.orderRef.toString();
+    
+    // Token type (Anchor deserializes enums as { variant: {} })
+    if (data.tokenType !== undefined) {
+      const variant = typeof data.tokenType === 'object' ? Object.keys(data.tokenType)[0] : String(data.tokenType);
+      result.tokenType = variant;
+      if (variant === 'sol' || variant === 'Sol') result.currency = 'SOL';
+      else if (variant === 'usdc' || variant === 'Usdc') result.currency = 'USDC';
+      else if (variant === 'usdt' || variant === 'Usdt') result.currency = 'USDT';
+      else if (variant === 'usd' || variant === 'Usd') result.currency = 'USD';
+    }
+    
+    // Status (same enum pattern)
+    if (data.status !== undefined) {
+      result.status = typeof data.status === 'object' ? Object.keys(data.status)[0] : String(data.status);
+    }
+    
+    // Active flag
+    if (data.active !== undefined) result.active = Boolean(data.active);
+    
+    return result;
+  }
+  
+  /**
+   * Emit event to handlers
+   */
+  private async emit(event: WebhookEvent): Promise<void> {
+    const handlers = this.handlers.get(event.type) || [];
+    
+    for (const handler of handlers) {
+      try {
+        await handler(event);
+      } catch (error) {
+        console.error('Error in event handler:', error);
+      }
+    }
+  }
+}
+
+// ==================== WEBHOOK SENDER ====================
+
+export interface WebhookSenderOptions {
+  /** Retry failed webhooks */
+  retryCount?: number;
+  /** Retry delay in ms */
+  retryDelayMs?: number;
+  /** Timeout in ms */
+  timeoutMs?: number;
+}
+
+/**
+ * Send webhooks to registered endpoints
+ */
+export class WebhookSender {
+  private options: WebhookSenderOptions;
+  
+  constructor(options: WebhookSenderOptions = {}) {
+    this.options = {
+      retryCount: options.retryCount ?? 3,
+      retryDelayMs: options.retryDelayMs ?? 1000,
+      timeoutMs: options.timeoutMs ?? 10000,
+    };
+  }
+  
+  /**
+   * Send webhook to endpoint
+   */
+  async send(config: WebhookConfig, event: WebhookEvent): Promise<boolean> {
+    const payload = JSON.stringify(event);
+    const signature = await createWebhookSignature(payload, config.secret);
+    
+    for (let attempt = 0; attempt <= this.options.retryCount!; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+        
+        const response = await fetch(config.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Rotate-Signature': signature,
+            'X-Rotate-Event': event.type,
+            'X-Rotate-Timestamp': event.timestamp.toString(),
+            'X-Rotate-Delivery-Attempt': attempt.toString(),
+          },
+          body: payload,
+          signal: controller.signal,
+        });
+        
+        clearTimeout(timeout);
+        
+        if (response.ok) {
+          return true;
+        }
+        
+        // Retry on 5xx errors
+        if (response.status >= 500 && attempt < this.options.retryCount!) {
+          await this.delay(this.options.retryDelayMs! * Math.pow(2, attempt));
+          continue;
+        }
+        
+        return false;
+      } catch (error) {
+        if (attempt < this.options.retryCount!) {
+          await this.delay(this.options.retryDelayMs! * Math.pow(2, attempt));
+          continue;
+        }
+        return false;
+      }
+    }
+    
+    return false;
+  }
+  
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+// ==================== EXPORTS ====================
+
+export default EventListener;