stripe-webhook.js

Go to the documentation of this file.

/**
 * @file routes/stripe-webhook.js
 * @module routes/stripe-webhook
 * @description Stripe webhook endpoint handler for processing platform and Connected Account
 * events. Verifies webhook signatures, processes payment and subscription events, and logs
 * all webhook activity to database.
 * 
 * **Architecture:**
 * - Stripe Connect platform model (one platform account, multiple connected accounts)
 * - Handles both snapshot webhooks (full event data) and thin webhooks (minimal data)
 * - Signature verification prevents unauthorized webhook calls
 * - Idempotent event processing prevents duplicate handling
 * - Comprehensive event logging for audit trails
 * 
 * **Webhook Configuration:**
 * - Endpoint URL: https://rmm-psa-backend-t9f7k.ondigitalocean.app/api/stripe/webhook
 * - Snapshot webhook secret: STRIPE_WEBHOOK_SECRET (primary, full event data)
 * - Thin webhook secret: STRIPE_WEBHOOK_SECRET_THIN (fallback, minimal data)
 * - Both secrets configured in .env file
 * 
 * **Event Types Handled:**
 * - payment_intent.succeeded - Payment completed successfully
 * - payment_intent.payment_failed - Payment failed (log + notify)
 * - customer.subscription.created - New subscription started
 * - customer.subscription.updated - Subscription modified (plan change, quantity, etc)
 * - customer.subscription.deleted - Subscription canceled
 * - invoice.payment_succeeded - Recurring invoice paid
 * - invoice.payment_failed - Recurring invoice payment failed
 * - account.updated - Connected account status changed
 * - charge.succeeded - Direct charge completed
 * - charge.failed - Direct charge failed
 * 
 * **Security:**
 * - No authenticateToken required (webhooks from Stripe, not clients)
 * - Signature verification using stripe.webhooks.constructEvent()
 * - Raw body buffer required for signature validation
 * - 401 Unauthorized for invalid signatures
 * - Rate limiting via Stripe's built-in webhook throttling
 * 
 * **Event Processing:**
 * 1. Receive webhook POST with raw body
 * 2. Extract Stripe-Signature header
 * 3. Verify signature with webhook secret
 * 4. Check for duplicate event (idempotency)
 * 5. Process event based on type
 * 6. Log event to stripe_webhook_events table
 * 7. Return 200 OK (or 400/500 on errors)
 * 
 * **Database Tables:**
 * - stripe_webhook_events - Full event log with payload, status, processing errors
 * - payments - Updated on payment_intent.succeeded/failed
 * - stripe_subscriptions - Updated on subscription lifecycle events
 * - stripe_config - Connected account status updates
 * 
 * **Idempotency:**
 * - Event ID stored in stripe_webhook_events table
 * - Duplicate events return 200 OK without reprocessing
 * - Prevents duplicate charges, double notifications, etc.
 * 
 * **Error Handling:**
 * - Signature verification failure: 401 Unauthorized
 * - Processing errors: Log to database, return 500 (Stripe will retry)
 * - Unhandled event types: Log and return 200 (not an error)
 * 
 * **Related Modules:**
 * - services/stripeService.js - Core Stripe API operations
 * - routes/invoices.js - Invoice management integration
 * - routes/contracts.js - Recurring billing subscription integration
 * 
 * @requires express
 * @requires stripe
 * @see {@link https://stripe.com/docs/webhooks|Stripe Webhooks Documentation}
 * @see {@link https://stripe.com/docs/connect/webhooks|Stripe Connect Webhooks}
 */
 
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
 
// Initialize Stripe with correct key based on mode
const stripeMode = process.env.STRIPE_MODE || 'test';
const stripeSecretKey = stripeMode === 'live' 
  ? process.env.STRIPE_LIVE_SECRET_KEY 
  : process.env.STRIPE_TEST_SECRET_KEY;
const stripe = require('stripe')(stripeSecretKey);
 
console.log(`[Stripe] Webhook handler initialized in ${stripeMode.toUpperCase()} mode`);
 
// Webhook signing secrets from .env (mode-specific)
const WEBHOOK_SECRET_SNAPSHOT = stripeMode === 'live'
  ? process.env.STRIPE_LIVE_WEBHOOK_SECRET
  : process.env.STRIPE_WEBHOOK_SECRET;
const WEBHOOK_SECRET_THIN = stripeMode === 'live'
  ? process.env.STRIPE_LIVE_WEBHOOK_SECRET_THIN
  : process.env.STRIPE_WEBHOOK_SECRET_THIN;
 
/**
 * POST /api/stripe/webhook
 * 
 * Stripe webhook endpoint for receiving platform and Connected Account events.
 * 
 * **Request Requirements:**
 * - Content-Type: application/json
 * - Stripe-Signature header (computed by Stripe)
 * - Raw body buffer (required for signature verification)
 * 
 * **Flow:**
 * 1. Extract raw body and Stripe-Signature header
 * 2. Try snapshot webhook secret, fallback to thin webhook secret
 * 3. Construct and verify event signature
 * 4. Check for duplicate event (idempotency)
 * 5. Process event based on type
 * 6. Log event to database
 * 7. Return 200 OK
 * 
 * **Response Codes:**
 * - 200 OK - Event processed successfully (or duplicate)
 * - 401 Unauthorized - Signature verification failed
 * - 400 Bad Request - Missing signature header or body
 * - 500 Internal Server Error - Processing error (Stripe will retry)
 * 
 * @route POST /api/stripe/webhook
 * @param {express.Request} req - Express request object (requires raw body buffer)
 * @param {express.Response} res - Express response object
 * @returns {Promise<void>} Returns 200 OK on success, error codes on failure
 * 
 * @example
 * // Stripe sends POST request with signature
 * POST /api/stripe/webhook
 * Headers:
 *   Stripe-Signature: t=1234567890,v1=abc123...,v0=def456...
 *   Content-Type: application/json
 * Body:
 *   {
 *     "id": "evt_1234567890",
 *     "object": "event",
 *     "type": "payment_intent.succeeded",
 *     "data": { ... }
 *   }
 * 
 * // Response:
 * HTTP 200 OK
 * { "received": true, "event_id": "evt_1234567890" }
 */
router.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const sig = req.headers['stripe-signature'];
  
  if (!sig) {
    console.error('❌ Missing Stripe-Signature header');
    return res.status(400).json({ error: 'Missing Stripe signature' });
  }
 
  let event;
 
  try {
    // Try snapshot webhook secret first (primary)
    try {
      event = stripe.webhooks.constructEvent(req.body, sig, WEBHOOK_SECRET_SNAPSHOT);
      console.log('✅ Webhook verified with snapshot secret');
    } catch (err) {
      // Fallback to thin webhook secret
      event = stripe.webhooks.constructEvent(req.body, sig, WEBHOOK_SECRET_THIN);
      console.log('✅ Webhook verified with thin secret');
    }
  } catch (err) {
    console.error('❌ Webhook signature verification failed:', err.message);
    return res.status(401).json({ error: `Webhook Error: ${err.message}` });
  }
 
  console.log(`📥 Received webhook: ${event.type} (${event.id})`);
 
  // Check for duplicate event (idempotency)
  const duplicateCheck = await pool.query(
    'SELECT event_id FROM stripe_webhook_events WHERE event_id = $1',
    [event.id]
  );
 
  if (duplicateCheck.rows.length > 0) {
    console.log(`⚠️ Duplicate event ${event.id} - already processed`);
    return res.status(200).json({ received: true, duplicate: true });
  }
 
  // Process event based on type
  try {
    await handleWebhookEvent(event);
    
    // Log successful processing
    await logWebhookEvent(event, 'processed', null);
    
    console.log(`✅ Successfully processed ${event.type}`);
    res.status(200).json({ received: true, event_id: event.id });
  } catch (error) {
    console.error(`❌ Error processing webhook ${event.id}:`, error);
    
    // Log failed processing (Stripe will retry)
    await logWebhookEvent(event, 'failed', error.message);
    
    res.status(500).json({ 
      error: 'Webhook processing failed', 
      event_id: event.id,
      message: error.message 
    });
  }
});
 
/**
 * Handles webhook event processing based on event type.
 * 
 * Routes events to appropriate handlers for payment intents, subscriptions,
 * invoices, and Connected Account events. Logs unhandled event types for monitoring.
 * 
 * **Supported Event Types:**
 * - Payment Intent: succeeded, payment_failed
 * - Subscription: created, updated, deleted
 * - Invoice: payment_succeeded, payment_failed
 * - Account: updated (Connected Account status)
 * - Charge: succeeded, failed
 * 
 * @async
 * @function handleWebhookEvent
 * @param {Object} event - Stripe event object
 * @param {string} event.id - Unique event identifier (evt_...)
 * @param {string} event.type - Event type (e.g., 'payment_intent.succeeded')
 * @param {Object} event.data - Event data payload
 * @param {string} [event.account] - Connected Account ID (for Connect events)
 * @returns {Promise<void>} Resolves when event handled
 * @throws {Error} If event processing fails
 * 
 * @example
 * await handleWebhookEvent({
 *   id: 'evt_123',
 *   type: 'payment_intent.succeeded',
 *   data: {
 *     object: {
 *       id: 'pi_123',
 *       amount: 5000,
 *       currency: 'usd',
 *       status: 'succeeded'
 *     }
 *   }
 * });
 */
async function handleWebhookEvent(event) {
  const { type, data } = event;
  const object = data.object;
 
  switch (type) {
    // Payment Intent Events
    case 'payment_intent.succeeded':
      await handlePaymentSuccess(object, event.account);
      break;
    
    case 'payment_intent.payment_failed':
      await handlePaymentFailed(object, event.account);
      break;
 
    // Subscription Events
    case 'customer.subscription.created':
      await handleSubscriptionCreated(object, event.account);
      break;
    
    case 'customer.subscription.updated':
      await handleSubscriptionUpdated(object, event.account);
      break;
    
    case 'customer.subscription.deleted':
      await handleSubscriptionDeleted(object, event.account);
      break;
 
    // Invoice Events (recurring billing)
    case 'invoice.payment_succeeded':
      await handleInvoicePaymentSuccess(object, event.account);
      break;
    
    case 'invoice.payment_failed':
      await handleInvoicePaymentFailed(object, event.account);
      break;
 
    // Connected Account Events
    case 'account.updated':
      await handleAccountUpdated(object);
      break;
 
    // Charge Events
    case 'charge.succeeded':
      await handleChargeSuccess(object, event.account);
      break;
    
    case 'charge.failed':
      await handleChargeFailed(object, event.account);
      break;
 
    default:
      console.log(`⚠️ Unhandled event type: ${type}`);
      // Not an error - just log and continue
  }
}
 
/**
 * Handles successful payment intent completion.
 * 
 * Updates payment record in database with success status, Stripe payment ID,
 * and payment timestamp. Links to invoice if metadata contains invoice_id.
 * Updates invoice payment_status to 'paid' if linked.
 * 
 * @async
 * @function handlePaymentSuccess
 * @param {Object} paymentIntent - Stripe PaymentIntent object
 * @param {string} paymentIntent.id - Payment Intent ID (pi_...)
 * @param {number} paymentIntent.amount - Amount in cents
 * @param {string} paymentIntent.currency - Currency code (usd, eur, etc)
 * @param {string} paymentIntent.status - Payment status ('succeeded')
 * @param {Object} [paymentIntent.metadata] - Custom metadata (invoice_id, tenant_id, etc)
 * @param {string} [connectedAccountId] - Connected Account ID (if Connect payment)
 * @returns {Promise<void>} Resolves when payment record updated
 * @throws {Error} If database update fails
 * 
 * @example
 * await handlePaymentSuccess({
 *   id: 'pi_123',
 *   amount: 5000,
 *   currency: 'usd',
 *   status: 'succeeded',
 *   metadata: {
 *     invoice_id: '456',
 *     tenant_id: '789'
 *   }
 * }, 'acct_abc123');
 */
async function handlePaymentSuccess(paymentIntent, connectedAccountId) {
  console.log(`💰 Payment succeeded: ${paymentIntent.id} ($${paymentIntent.amount / 100})`);
  
  // TODO: Update payments table
  // - Set status = 'succeeded'
  // - Set stripe_payment_intent_id = paymentIntent.id
  // - Set paid_at = NOW()
  // - Update invoice payment_status = 'paid' if metadata.invoice_id exists
  
  // TODO: Send customer receipt email
  // TODO: Trigger post-payment webhooks/notifications
}
 
/**
 * Handles failed payment intent.
 * 
 * Updates payment record with failed status and error message. Logs failure
 * reason for debugging. Triggers customer notification email. Updates invoice
 * payment_status to 'failed' if linked.
 * 
 * @async
 * @function handlePaymentFailed
 * @param {Object} paymentIntent - Stripe PaymentIntent object
 * @param {string} paymentIntent.id - Payment Intent ID (pi_...)
 * @param {number} paymentIntent.amount - Amount in cents
 * @param {string} paymentIntent.currency - Currency code
 * @param {string} paymentIntent.status - Payment status ('failed')
 * @param {Object} [paymentIntent.last_payment_error] - Error details
 * @param {string} [paymentIntent.last_payment_error.message] - Human-readable error
 * @param {Object} [paymentIntent.metadata] - Custom metadata
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when failure recorded
 * @throws {Error} If database update fails
 * 
 * @example
 * await handlePaymentFailed({
 *   id: 'pi_123',
 *   amount: 5000,
 *   status: 'failed',
 *   last_payment_error: {
 *     message: 'Your card was declined.'
 *   },
 *   metadata: { invoice_id: '456' }
 * });
 */
async function handlePaymentFailed(paymentIntent, connectedAccountId) {
  console.log(`❌ Payment failed: ${paymentIntent.id} - ${paymentIntent.last_payment_error?.message}`);
  
  // TODO: Update payments table
  // - Set status = 'failed'
  // - Set error_message = last_payment_error.message
  // - Update invoice payment_status = 'failed'
  
  // TODO: Send customer payment failure notification
  // TODO: Trigger retry logic if applicable
}
 
/**
 * Handles new subscription creation.
 * 
 * Creates record in stripe_subscriptions table with subscription details,
 * pricing, billing cycle, and status. Links to tenant via Connected Account ID
 * or metadata. Creates initial invoice record if applicable.
 * 
 * @async
 * @function handleSubscriptionCreated
 * @param {Object} subscription - Stripe Subscription object
 * @param {string} subscription.id - Subscription ID (sub_...)
 * @param {string} subscription.customer - Customer ID (cus_...)
 * @param {string} subscription.status - Subscription status (active, trialing, etc)
 * @param {Array} subscription.items - Subscription items with pricing
 * @param {number} subscription.current_period_start - Unix timestamp
 * @param {number} subscription.current_period_end - Unix timestamp
 * @param {Object} [subscription.metadata] - Custom metadata
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when subscription record created
 * @throws {Error} If database insert fails
 * 
 * @example
 * await handleSubscriptionCreated({
 *   id: 'sub_123',
 *   customer: 'cus_456',
 *   status: 'active',
 *   items: [{
 *     price: { id: 'price_789', unit_amount: 2000 }
 *   }],
 *   current_period_start: 1234567890,
 *   current_period_end: 1237159890,
 *   metadata: { contract_id: '101' }
 * }, 'acct_abc');
 */
async function handleSubscriptionCreated(subscription, connectedAccountId) {
  console.log(`📅 Subscription created: ${subscription.id} (${subscription.status})`);
  
  // TODO: Insert into stripe_subscriptions table
  // - stripe_subscription_id = subscription.id
  // - customer_id = subscription.customer
  // - status = subscription.status
  // - current_period_start/end
  // - linked_account_id = connectedAccountId
  
  // TODO: Link to contracts table if metadata.contract_id exists
}
 
/**
 * Handles subscription updates.
 * 
 * Updates subscription record with new status, pricing, quantity, or billing
 * cycle. Handles plan changes, quantity adjustments, cancellations, and reactivations.
 * Logs changes for audit trail.
 * 
 * @async
 * @function handleSubscriptionUpdated
 * @param {Object} subscription - Stripe Subscription object
 * @param {string} subscription.id - Subscription ID
 * @param {string} subscription.status - New status (active, canceled, past_due, etc)
 * @param {Array} subscription.items - Updated subscription items
 * @param {number} subscription.current_period_start - Unix timestamp
 * @param {number} subscription.current_period_end - Unix timestamp
 * @param {boolean} [subscription.cancel_at_period_end] - Cancellation flag
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when subscription updated
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleSubscriptionUpdated({
 *   id: 'sub_123',
 *   status: 'active',
 *   cancel_at_period_end: true,
 *   items: [{ price: { unit_amount: 3000 } }]
 * });
 */
async function handleSubscriptionUpdated(subscription, connectedAccountId) {
  console.log(`📅 Subscription updated: ${subscription.id} (${subscription.status})`);
  
  // TODO: Update stripe_subscriptions table
  // - Update status, current_period_start/end, cancel_at_period_end
  // - Log plan/quantity changes
  
  // TODO: Update linked contracts if prices changed
}
 
/**
 * Handles subscription deletion/cancellation.
 * 
 * Updates subscription record with canceled status and cancellation timestamp.
 * Marks as ended. Triggers post-cancellation workflows (notifications, access
 * revocation, etc). Logs cancellation reason if available.
 * 
 * @async
 * @function handleSubscriptionDeleted
 * @param {Object} subscription - Stripe Subscription object
 * @param {string} subscription.id - Subscription ID
 * @param {string} subscription.status - Final status (typically 'canceled')
 * @param {number} [subscription.canceled_at] - Cancellation timestamp
 * @param {string} [subscription.cancellation_reason] - Reason for cancellation
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when cancellation processed
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleSubscriptionDeleted({
 *   id: 'sub_123',
 *   status: 'canceled',
 *   canceled_at: 1234567890,
 *   cancellation_reason: 'Customer requested'
 * });
 */
async function handleSubscriptionDeleted(subscription, connectedAccountId) {
  console.log(`🚫 Subscription deleted: ${subscription.id}`);
  
  // TODO: Update stripe_subscriptions table
  // - Set status = 'canceled'
  // - Set canceled_at = NOW()
  // - End linked contracts
  
  // TODO: Revoke customer access if applicable
  // TODO: Send cancellation confirmation email
}
 
/**
 * Handles successful recurring invoice payment.
 * 
 * Records invoice payment in database, updates invoice status to paid, and
 * creates payment record. Links to subscription if applicable. Triggers receipt
 * email and post-payment workflows.
 * 
 * @async
 * @function handleInvoicePaymentSuccess
 * @param {Object} invoice - Stripe Invoice object
 * @param {string} invoice.id - Invoice ID (in_...)
 * @param {string} invoice.subscription - Subscription ID (if recurring)
 * @param {number} invoice.amount_paid - Amount paid in cents
 * @param {string} invoice.currency - Currency code
 * @param {string} invoice.status - Invoice status ('paid')
 * @param {string} invoice.customer - Customer ID
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when invoice payment recorded
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleInvoicePaymentSuccess({
 *   id: 'in_123',
 *   subscription: 'sub_456',
 *   amount_paid: 2000,
 *   currency: 'usd',
 *   status: 'paid',
 *   customer: 'cus_789'
 * }, 'acct_abc');
 */
async function handleInvoicePaymentSuccess(invoice, connectedAccountId) {
  console.log(`💰 Invoice paid: ${invoice.id} ($${invoice.amount_paid / 100})`);
  
  // TODO: Create payment record in payments table
  // - Link to subscription if invoice.subscription exists
  // - Update subscription next_billing_date
  
  // TODO: Send receipt email
}
 
/**
 * Handles failed recurring invoice payment.
 * 
 * Records payment failure, updates invoice status, logs error message. Triggers
 * customer notification about failed payment. Initiates retry logic according
 * to subscription settings. May trigger subscription suspension/cancellation.
 * 
 * @async
 * @function handleInvoicePaymentFailed
 * @param {Object} invoice - Stripe Invoice object
 * @param {string} invoice.id - Invoice ID
 * @param {string} invoice.subscription - Subscription ID
 * @param {number} invoice.amount_due - Amount due in cents
 * @param {string} invoice.status - Invoice status ('open' or 'uncollectible')
 * @param {number} [invoice.attempt_count] - Number of payment attempts
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when failure recorded
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleInvoicePaymentFailed({
 *   id: 'in_123',
 *   subscription: 'sub_456',
 *   amount_due: 2000,
 *   status: 'open',
 *   attempt_count: 2
 * });
 */
async function handleInvoicePaymentFailed(invoice, connectedAccountId) {
  console.log(`❌ Invoice payment failed: ${invoice.id}`);
  
  // TODO: Log payment failure
  // - Update subscription status if multiple failures
  // - Check attempt_count and trigger suspension if needed
  
  // TODO: Send payment failure notification
  // TODO: Trigger automatic retry if configured
}
 
/**
 * Handles Connected Account updates.
 * 
 * Updates tenant's Stripe account status in stripe_config table. Monitors
 * account verification status (verified, pending, disabled). Triggers notifications
 * for status changes (account verified, verification required, account disabled).
 * 
 * @async
 * @function handleAccountUpdated
 * @param {Object} account - Stripe Account object
 * @param {string} account.id - Account ID (acct_...)
 * @param {boolean} account.details_submitted - Onboarding complete
 * @param {boolean} account.charges_enabled - Can accept charges
 * @param {boolean} account.payouts_enabled - Can receive payouts
 * @param {Object} [account.requirements] - Verification requirements
 * @param {Array} [account.requirements.currently_due] - Info needed now
 * @param {Array} [account.requirements.errors] - Verification errors
 * @returns {Promise<void>} Resolves when account status updated
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleAccountUpdated({
 *   id: 'acct_123',
 *   details_submitted: true,
 *   charges_enabled: true,
 *   payouts_enabled: true,
 *   requirements: {
 *     currently_due: [],
 *     errors: []
 *   }
 * });
 */
async function handleAccountUpdated(account) {
  console.log(`🏢 Account updated: ${account.id} (charges: ${account.charges_enabled}, payouts: ${account.payouts_enabled})`);
  
  // TODO: Update stripe_config table
  // - Find tenant by stripe_account_id = account.id
  // - Update charges_enabled, payouts_enabled flags
  // - Update verification_status based on requirements
  
  // TODO: Send notification if verification status changed
}
 
/**
 * Handles successful charge completion.
 * 
 * Records charge in payments table with success status. Logs charge details
 * including amount, fee, net amount. Links to invoice if charge.metadata contains
 * invoice_id. Updates invoice payment status if applicable.
 * 
 * @async
 * @function handleChargeSuccess
 * @param {Object} charge - Stripe Charge object
 * @param {string} charge.id - Charge ID (ch_...)
 * @param {number} charge.amount - Amount charged in cents
 * @param {string} charge.currency - Currency code
 * @param {boolean} charge.paid - Payment success flag
 * @param {string} charge.payment_intent - PaymentIntent ID (if applicable)
 * @param {Object} [charge.metadata] - Custom metadata
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when charge recorded
 * @throws {Error} If database insert fails
 * 
 * @example
 * await handleChargeSuccess({
 *   id: 'ch_123',
 *   amount: 5000,
 *   currency: 'usd',
 *   paid: true,
 *   payment_intent: 'pi_456',
 *   metadata: { invoice_id: '789' }
 * }, 'acct_abc');
 */
async function handleChargeSuccess(charge, connectedAccountId) {
  console.log(`💳 Charge succeeded: ${charge.id} ($${charge.amount / 100})`);
  
  // TODO: Record charge in payments table
  // - Link to payment_intent if exists
  // - Store charge fees (application_fee_amount)
}
 
/**
 * Handles failed charge.
 * 
 * Records charge failure with error details. Logs failure reason and outcome.
 * Triggers customer notification. Updates invoice payment status to failed if
 * linked. May trigger retry logic depending on failure type.
 * 
 * @async
 * @function handleChargeFailed
 * @param {Object} charge - Stripe Charge object
 * @param {string} charge.id - Charge ID
 * @param {number} charge.amount - Attempted amount in cents
 * @param {string} charge.currency - Currency code
 * @param {boolean} charge.paid - Always false for failed charges
 * @param {string} charge.failure_code - Machine-readable failure code
 * @param {string} charge.failure_message - Human-readable failure message
 * @param {Object} [charge.metadata] - Custom metadata
 * @param {string} [connectedAccountId] - Connected Account ID
 * @returns {Promise<void>} Resolves when failure recorded
 * @throws {Error} If database update fails
 * 
 * @example
 * await handleChargeFailed({
 *   id: 'ch_123',
 *   amount: 5000,
 *   paid: false,
 *   failure_code: 'card_declined',
 *   failure_message: 'Your card was declined.',
 *   metadata: { invoice_id: '789' }
 * });
 */
async function handleChargeFailed(charge, connectedAccountId) {
  console.log(`❌ Charge failed: ${charge.id} - ${charge.failure_message}`);
  
  // TODO: Record charge failure
  // - Store failure_code and failure_message
  // - Update invoice payment_status = 'failed'
}
 
/**
 * Logs webhook event to database for audit trail and idempotency.
 * 
 * Inserts event record with full payload, processing status, and error message
 * (if failed). Used for duplicate detection (idempotency check), debugging,
 * and compliance audit trails. Stores complete event data for replay if needed.
 * 
 * @async
 * @function logWebhookEvent
 * @param {Object} event - Stripe event object
 * @param {string} event.id - Unique event ID (evt_...)
 * @param {string} event.type - Event type (e.g., 'payment_intent.succeeded')
 * @param {Object} event.data - Event data payload
 * @param {number} event.created - Event creation timestamp (Unix)
 * @param {string} [event.account] - Connected Account ID (if applicable)
 * @param {string} status - Processing status ('processed' or 'failed')
 * @param {string|null} errorMessage - Error message if status is 'failed'
 * @returns {Promise<void>} Resolves when event logged
 * @throws {Error} If database insert fails
 * 
 * @example
 * await logWebhookEvent({
 *   id: 'evt_123',
 *   type: 'payment_intent.succeeded',
 *   data: { object: {...} },
 *   created: 1234567890
 * }, 'processed', null);
 * 
 * @example
 * // Failed event logging
 * await logWebhookEvent(event, 'failed', 'Database connection timeout');
 */
async function logWebhookEvent(event, status, errorMessage) {
  try {
    await pool.query(
      `INSERT INTO stripe_webhook_events 
       (event_id, event_type, payload, status, error_message, processed_at)
       VALUES ($1, $2, $3, $4, $5, NOW())`,
      [event.id, event.type, JSON.stringify(event), status, errorMessage]
    );
  } catch (err) {
    console.error('❌ Failed to log webhook event to database:', err);
    // Don't throw - logging failure shouldn't break webhook processing
  }
}
 
module.exports = router;