stripeService.js

Go to the documentation of this file.

/**
 * @file services/stripeService.js
 * @module services/stripeService
 * @description Stripe Connect service for multi-tenant payment processing. Manages Connected
 * Account onboarding, payment routing, subscription creation, and payment method management.
 * 
 * **Architecture:**
 * - Stripe Connect Platform Model (one platform account, multiple connected tenant accounts)
 * - OAuth-based account onboarding (standard or express accounts)
 * - Payment routing via stripeAccount parameter
 * - Application fee collection (2-5% typical platform fee)
 * - No stored tenant API keys (only stripe_account_id)
 * 
 * **Core Functionality:**
 * - Connected Account creation and onboarding
 * - Account status monitoring (charges_enabled, payouts_enabled)
 * - Payment Intent creation with automatic routing
 * - Subscription management (create, update, cancel)
 * - Customer creation (platform or connected account level)
 * - Payment method attachment and management
 * - Webhook signature verification (handled in routes/stripe-webhook.js)
 * 
 * **Stripe Connect Flow:**
 * 1. Create Connected Account (createConnectAccount)
 * 2. Generate onboarding link (createAccountLink)
 * 3. Tenant completes onboarding via Stripe-hosted flow
 * 4. Webhook: account.updated (charges_enabled = true)
 * 5. Store stripe_account_id in stripe_config table
 * 6. Route payments via stripeAccount parameter
 * 7. Collect application fees automatically
 * 
 * **Payment Routing:**
 * - Direct charges: Use stripeAccount parameter in API calls
 * - Destination charges: Create on platform, transfer to connected account
 * - Separate charges: Create directly on connected account (our approach)
 * 
 * **Fees:**
 * - Application fee: Set per transaction (percentage or fixed)
 * - Stripe fee: ~2.9% + $0.30 per transaction (standard rates)
 * - Net to tenant: Amount - application_fee - stripe_fee
 * 
 * **Multi-Tenant Isolation:**
 * - Each tenant has unique stripe_account_id
 * - All charges route to correct connected account
 * - Tenants see only their own transactions in Stripe Dashboard
 * - Platform sees all transactions across all tenants
 * 
 * **Security:**
 * - Platform secret key stored in environment variable
 * - No tenant API keys stored (Stripe Connect handles auth)
 * - Webhook signatures verified (see routes/stripe-webhook.js)
 * - PCI compliance handled by Stripe (no card data in database)
 * 
 * **Related Modules:**
 * - routes/stripe-webhook.js - Webhook event processing
 * - routes/invoices.js - Invoice integration
 * - routes/contracts.js - Recurring billing integration
 * - services/db - PostgreSQL connection pool
 * 
 * @requires stripe
 * @see {@link https://stripe.com/docs/connect|Stripe Connect Documentation}
 * @see {@link https://stripe.com/docs/connect/charges|Stripe Connect Charges}
 * @see {@link https://stripe.com/docs/connect/enable-payment-acceptance-guide|Onboarding Guide}
 */
 
// 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);
const pool = require('./db');
 
console.log(`[Stripe] Service initialized in ${stripeMode.toUpperCase()} mode`);
 
/**
 * Stripe service class for Connect platform operations.
 * 
 * Provides methods for Connected Account management, payment processing, subscription
 * creation, and customer management. All operations support multi-tenant isolation
 * via Connected Account routing.
 * 
 * @class StripeService
 * 
 * @example
 * const stripeService = require('./services/stripeService');
 * 
 * // Create Connected Account for tenant
 * const account = await stripeService.createConnectAccount('tenant@example.com', 'US');
 * 
 * // Generate onboarding link
 * const link = await stripeService.createAccountLink(account.id);
 * 
 * // Create payment intent routed to tenant
 * const payment = await stripeService.createPaymentIntent(5000, 'usd', account.id);
 */
class StripeService {
  
  /**
   * Creates a new Stripe Connected Account for a tenant.
   * 
   * Creates either Standard or Express account type. Standard accounts give full
   * control to the tenant (own Stripe Dashboard). Express accounts are faster to
   * onboard but platform-controlled. Returns account ID to store in stripe_config table.
   * 
   * **Account Types:**
   * - **Standard**: Full Stripe Dashboard, tenant controls settings, longer onboarding
   * - **Express**: Simplified onboarding, platform controls settings, recommended
   * - **Custom**: Full platform control (not recommended for this use case)
   * 
   * @async
   * @static
   * @function createConnectAccount
   * @param {string} email - Tenant business email address
   * @param {string} [country='US'] - ISO 3166-1 alpha-2 country code (US, CA, GB, etc.)
   * @param {string} [accountType='express'] - Account type (standard, express, custom)
   * @param {Object} [businessProfile] - Optional business profile details
   * @param {string} [businessProfile.name] - Business name
   * @param {string} [businessProfile.url] - Business website URL
   * @returns {Promise<Object>} Stripe Account object with id, charges_enabled, payouts_enabled
   * @throws {Error} If account creation fails or invalid country code
   * 
   * @example
   * // Create Express account (recommended)
   * const account = await stripeService.createConnectAccount(
   *   'tenant@example.com', 
   *   'US', 
   *   'express',
   *   {
   *     name: 'Acme Corp',
   *     url: 'https://acme.example.com'
   *   }
   * );
   * 
   * console.log(account.id); // acct_1234567890
   * console.log(account.charges_enabled); // false (not yet onboarded)
   * 
   * @example
   * // Create Standard account (full control to tenant)
   * const account = await stripeService.createConnectAccount(
   *   'tenant@example.com',
   *   'GB',
   *   'standard'
   * );
   */
  static async createConnectAccount(email, country = 'US', accountType = 'express', businessProfile = {}) {
    try {
      const accountData = {
        type: accountType,
        country: country,
        email: email,
        capabilities: {
          card_payments: { requested: true },
          transfers: { requested: true },
        },
      };
 
      // Add business profile if provided
      if (businessProfile.name || businessProfile.url) {
        accountData.business_profile = {};
        if (businessProfile.name) accountData.business_profile.name = businessProfile.name;
        if (businessProfile.url) accountData.business_profile.url = businessProfile.url;
      }
 
      const account = await stripe.accounts.create(accountData);
      
      console.log(`✅ Created ${accountType} Connected Account: ${account.id} (${email})`);
      
      return account;
    } catch (error) {
      console.error('❌ Failed to create Connected Account:', error.message);
      
      // Provide helpful error for common issues
      if (error.message && error.message.includes('signed up for Connect')) {
        const enhancedError = new Error(
          'Stripe Connect is not enabled on your account. ' +
          'Please enable it at https://dashboard.stripe.com/connect before creating connected accounts.'
        );
        enhancedError.code = 'STRIPE_CONNECT_NOT_ENABLED';
        enhancedError.setupUrl = 'https://dashboard.stripe.com/connect';
        throw enhancedError;
      }
      
      throw new Error(`Stripe account creation failed: ${error.message}`);
    }
  }
 
  /**
   * Creates account link for onboarding flow.
   * 
   * Generates time-limited URL for tenant to complete Stripe Connect onboarding.
   * Link expires after expiration time (default 5 minutes). Tenant fills out business
   * details, banking info, and identity verification. After completion, redirects to
   * refresh_url or return_url.
   * 
   * **Flow:**
   * 1. Generate account link
   * 2. Redirect tenant to link.url
   * 3. Tenant completes onboarding on Stripe
   * 4. Stripe redirects to return_url on success
   * 5. Webhook: account.updated (charges_enabled = true)
   * 
   * **Link Expiration:**
   * - Default expiration: 5 minutes (Stripe enforced)
   * - Must generate new link if expired
   * - Store link.expires_at to check validity
   * 
   * @async
   * @static
   * @function createAccountLink
   * @param {string} accountId - Stripe Connected Account ID (acct_...)
   * @param {string} [returnUrl] - URL to redirect after successful onboarding
   * @param {string} [refreshUrl] - URL to redirect if link expires (should regenerate link)
   * @param {string} [type='account_onboarding'] - Link type (account_onboarding or account_update)
   * @returns {Promise<Object>} AccountLink object with url and expires_at timestamp
   * @throws {Error} If link creation fails or account not found
   * 
   * @example
   * const link = await stripeService.createAccountLink(
   *   'acct_1234567890',
   *   'https://app.example.com/stripe/onboarding-complete',
   *   'https://app.example.com/stripe/onboarding-refresh'
   * );
   * 
   * console.log(link.url); // https://connect.stripe.com/setup/e/acct_1234567890/...
   * console.log(link.expires_at); // 1234567890 (Unix timestamp)
   * 
   * // Redirect user to link.url
   * res.redirect(link.url);
   * 
   * @example
   * // Generate link for updating existing account info
   * const updateLink = await stripeService.createAccountLink(
   *   'acct_1234567890',
   *   'https://app.example.com/settings',
   *   'https://app.example.com/settings',
   *   'account_update'
   * );
   */
  static async createAccountLink(accountId, returnUrl = null, refreshUrl = null, type = 'account_onboarding') {
    try {
      const backendUrl = process.env.BACKEND_URL || 'https://rmm-psa-backend-t9f7k.ondigitalocean.app';
      
      // Use provided URLs or defaults
      const return_url = returnUrl || `${backendUrl}/api/stripe/onboarding-complete`;
      const refresh_url = refreshUrl || `${backendUrl}/api/stripe/onboarding-refresh`;
 
      const accountLink = await stripe.accountLinks.create({
        account: accountId,
        refresh_url: refresh_url,
        return_url: return_url,
        type: type,
      });
      
      console.log(`✅ Created account link for ${accountId} (expires at ${new Date(accountLink.expires_at * 1000).toISOString()})`);
      
      return accountLink;
    } catch (error) {
      console.error('❌ Failed to create account link:', error.message);
      throw new Error(`Account link creation failed: ${error.message}`);
    }
  }
 
  /**
   * Retrieves Connected Account details.
   * 
   * Fetches current account status including charges_enabled, payouts_enabled, and
   * verification requirements. Use to monitor account status and determine if tenant
   * can accept payments. Check requirements.currently_due for missing information.
   * 
   * **Key Status Fields:**
   * - **charges_enabled**: Can accept payments (true after onboarding)
   * - **payouts_enabled**: Can receive payouts (true after bank verification)
   * - **details_submitted**: Onboarding form completed
   * - **requirements.currently_due**: Array of missing required fields
   * - **requirements.eventually_due**: Fields needed in future
   * - **requirements.past_due**: Overdue requirements (may disable account)
   * 
   * @async
   * @static
   * @function retrieveAccount
   * @param {string} accountId - Stripe Connected Account ID (acct_...)
   * @returns {Promise<Object>} Stripe Account object with full details
   * @throws {Error} If account retrieval fails or account not found
   * 
   * @example
   * const account = await stripeService.retrieveAccount('acct_1234567890');
   * 
   * console.log(account.charges_enabled); // true or false
   * console.log(account.payouts_enabled); // true or false
   * console.log(account.details_submitted); // true or false
   * console.log(account.requirements.currently_due); // ['business_profile.mcc', ...]
   * console.log(account.requirements.errors); // [{ reason: 'verification_failed', ... }]
   * 
   * if (account.charges_enabled) {
   *   console.log('✅ Account can accept payments');
   * } else {
   *   console.log('⏳ Account onboarding incomplete');
   *   console.log('Missing:', account.requirements.currently_due.join(', '));
   * }
   */
  static async retrieveAccount(accountId) {
    try {
      const account = await stripe.accounts.retrieve(accountId);
      
      console.log(`📊 Retrieved account ${accountId}: charges=${account.charges_enabled}, payouts=${account.payouts_enabled}`);
      
      return account;
    } catch (error) {
      console.error('❌ Failed to retrieve account:', error.message);
      throw new Error(`Account retrieval failed: ${error.message}`);
    }
  }
 
  /**
   * Creates Payment Intent routed to Connected Account.
   * 
   * Creates payment with automatic routing to tenant's Connected Account. Platform
   * can collect application fee. Payment is held by Connected Account, not platform.
   * Use for one-time payments (invoices, purchases). For recurring payments, use
   * createSubscription instead.
   * 
   * **Payment Flow:**
   * 1. Create Payment Intent with stripeAccount (routes to tenant)
   * 2. Return client_secret to frontend
   * 3. Frontend confirms payment with Stripe.js
   * 4. Webhook: payment_intent.succeeded
   * 5. Update invoice payment_status = 'paid'
   * 
   * **Application Fees:**
   * - Fixed amount: application_fee_amount (cents)
   * - Percentage: Calculate before calling (e.g., amount * 0.025 for 2.5%)
   * - Fee goes to platform account
   * - Net to tenant: amount - application_fee_amount
   * 
   * @async
   * @static
   * @function createPaymentIntent
   * @param {number} amount - Payment amount in cents (e.g., 5000 = $50.00)
   * @param {string} [currency='usd'] - Currency code (usd, eur, gbp, cad, aud, etc.)
   * @param {string} stripeAccountId - Connected Account ID to route payment to
   * @param {Object} [options={}] - Additional PaymentIntent options
   * @param {number} [options.application_fee_amount] - Platform fee in cents
   * @param {string} [options.customer] - Stripe Customer ID
   * @param {string} [options.payment_method] - Payment Method ID (for auto-confirmation)
   * @param {Object} [options.metadata] - Custom metadata (invoice_id, tenant_id, etc.)
   * @param {string} [options.description] - Payment description shown to customer
   * @param {string} [options.receipt_email] - Email to send receipt to
   * @returns {Promise<Object>} PaymentIntent object with id, client_secret, status
   * @throws {Error} If Payment Intent creation fails
   * 
   * @example
   * // Basic payment intent with 2.5% application fee
   * const amount = 5000; // $50.00
   * const appFee = Math.round(amount * 0.025); // $1.25 (2.5%)
   * 
   * const paymentIntent = await stripeService.createPaymentIntent(
   *   amount,
   *   'usd',
   *   'acct_1234567890',
   *   {
   *     application_fee_amount: appFee,
   *     metadata: {
   *       invoice_id: '456',
   *       tenant_id: '789'
   *     },
   *     description: 'Invoice #INV-000456',
   *     receipt_email: 'customer@example.com'
   *   }
   * );
   * 
   * // Return client_secret to frontend for confirmation
   * res.json({ client_secret: paymentIntent.client_secret });
   * 
   * @example
   * // Payment intent with stored payment method (auto-confirm)
   * const paymentIntent = await stripeService.createPaymentIntent(
   *   10000, // $100.00
   *   'usd',
   *   'acct_1234567890',
   *   {
   *     customer: 'cus_1234567890',
   *     payment_method: 'pm_1234567890',
   *     confirm: true, // Auto-confirm with saved payment method
   *     off_session: true // For recurring charges
   *   }
   * );
   */
  static async createPaymentIntent(amount, currency = 'usd', stripeAccountId, options = {}) {
    try {
      const paymentIntentData = {
        amount: amount,
        currency: currency,
        ...options, // Merge in customer, payment_method, metadata, etc.
      };
 
      // Create PaymentIntent on connected account
      const paymentIntent = await stripe.paymentIntents.create(
        paymentIntentData,
        {
          stripeAccount: stripeAccountId, // Route to Connected Account
        }
      );
      
      console.log(`💳 Created Payment Intent ${paymentIntent.id} for ${amount} ${currency} (account: ${stripeAccountId})`);
      if (options.application_fee_amount) {
        console.log(`   Platform fee: ${options.application_fee_amount} cents`);
      }
      
      return paymentIntent;
    } catch (error) {
      console.error('❌ Failed to create Payment Intent:', error.message);
      throw new Error(`Payment Intent creation failed: ${error.message}`);
    }
  }
 
  /**
   * Creates Stripe Customer on Connected Account.
   * 
   * Creates customer record for storing payment methods and subscription management.
   * Customer created on Connected Account (tenant's account), not platform. Use for
   * recurring billing, saved payment methods, and subscription management.
   * 
   * **Customer vs PaymentIntent:**
   * - Create Customer for: Subscriptions, saved cards, recurring billing
   * - Use PaymentIntent alone for: One-time guest checkout
   * 
   * @async
   * @static
   * @function createCustomer
   * @param {string} email - Customer email address
   * @param {string} stripeAccountId - Connected Account ID
   * @param {Object} [options={}] - Additional customer options
   * @param {string} [options.name] - Customer full name
   * @param {string} [options.phone] - Customer phone number
   * @param {Object} [options.address] - Customer address object
   * @param {Object} [options.metadata] - Custom metadata (customer_id from database, etc.)
   * @param {string} [options.description] - Customer description
   * @returns {Promise<Object>} Stripe Customer object with id, email, created
   * @throws {Error} If customer creation fails
   * 
   * @example
   * const customer = await stripeService.createCustomer(
   *   'customer@example.com',
   *   'acct_1234567890',
   *   {
   *     name: 'John Doe',
   *     phone: '+1 555-123-4567',
   *     metadata: {
   *       customer_id: '456', // Link to customers table
   *       tenant_id: '789'
   *     },
   *     address: {
   *       line1: '123 Main St',
   *       city: 'San Francisco',
   *       state: 'CA',
   *       postal_code: '94111',
   *       country: 'US'
   *     }
   *   }
   * );
   * 
   * console.log(customer.id); // cus_1234567890
   * 
   * // Store customer.id in database for future charges
   * await pool.query(
   *   'UPDATE customers SET stripe_customer_id = $1 WHERE customer_id = $2',
   *   [customer.id, 456]
   * );
   */
  static async createCustomer(email, stripeAccountId, options = {}) {
    try {
      const customerData = {
        email: email,
        ...options, // Merge in name, phone, address, metadata, etc.
      };
 
      const customer = await stripe.customers.create(
        customerData,
        {
          stripeAccount: stripeAccountId, // Create on Connected Account
        }
      );
      
      console.log(`👤 Created Customer ${customer.id} on account ${stripeAccountId}`);
      
      return customer;
    } catch (error) {
      console.error('❌ Failed to create customer:', error.message);
      throw new Error(`Customer creation failed: ${error.message}`);
    }
  }
 
  /**
   * Creates subscription for recurring billing.
   * 
   * Creates subscription with specified price/plan. Charges automatically on billing
   * cycle. Links to Stripe Price (must be created in Stripe Dashboard or via API first).
   * Use for contracts with recurring billing (monthly, yearly, etc.).
   * 
   * **Prerequisites:**
   * - Customer must exist (createCustomer first)
   * - Price must exist in Stripe (create via Dashboard or API)
   * - Payment method attached to customer (or default_payment_method specified)
   * 
   * **Billing Cycle:**
   * - Subscription starts immediately (or at trial_end if trial specified)
   * - Invoices generated automatically based on interval (month, year, etc.)
   * - Webhooks: customer.subscription.created, invoice.payment_succeeded
   * 
   * @async
   * @static
   * @function createSubscription
   * @param {string} customerId - Stripe Customer ID (cus_...)
   * @param {string} priceId - Stripe Price ID (price_...)
   * @param {string} stripeAccountId - Connected Account ID
   * @param {Object} [options={}] - Additional subscription options
   * @param {number} [options.trial_period_days] - Trial period in days (0 = no trial)
   * @param {string} [options.default_payment_method] - Payment Method ID to use
   * @param {number} [options.quantity=1] - Subscription quantity (for seat-based pricing)
   * @param {number} [options.application_fee_percent] - Platform fee percentage (0-100)
   * @param {Object} [options.metadata] - Custom metadata (contract_id, etc.)
   * @returns {Promise<Object>} Stripe Subscription object with id, status, current_period_end
   * @throws {Error} If subscription creation fails
   * 
   * @example
   * // Create monthly subscription with 14-day trial and 2.5% platform fee
   * const subscription = await stripeService.createSubscription(
   *   'cus_1234567890',
   *   'price_1234567890', // $29/month price
   *   'acct_1234567890',
   *   {
   *     trial_period_days: 14,
   *     quantity: 5, // 5 seats
   *     application_fee_percent: 2.5,
   *     metadata: {
   *       contract_id: '101',
   *       tenant_id: '789'
   *     }
   *   }
   * );
   * 
   * console.log(subscription.id); // sub_1234567890
   * console.log(subscription.status); // 'trialing' or 'active'
   * console.log(subscription.current_period_end); // Unix timestamp
   * 
   * // Store subscription.id in stripe_subscriptions table
   * await pool.query(
   *   `INSERT INTO stripe_subscriptions 
   *    (stripe_subscription_id, customer_id, contract_id, status, amount) 
   *    VALUES ($1, $2, $3, $4, $5)`,
   *   [subscription.id, customerId, 101, subscription.status, 2900]
   * );
   */
  static async createSubscription(customerId, priceId, stripeAccountId, options = {}) {
    try {
      const subscriptionData = {
        customer: customerId,
        items: [{ price: priceId, quantity: options.quantity || 1 }],
        ...options, // Merge in trial_period_days, default_payment_method, metadata, etc.
      };
 
      // Remove quantity from root options (already in items array)
      delete subscriptionData.quantity;
 
      const subscription = await stripe.subscriptions.create(
        subscriptionData,
        {
          stripeAccount: stripeAccountId, // Create on Connected Account
        }
      );
      
      console.log(`📅 Created Subscription ${subscription.id} (${subscription.status}) on account ${stripeAccountId}`);
      
      return subscription;
    } catch (error) {
      console.error('❌ Failed to create subscription:', error.message);
      throw new Error(`Subscription creation failed: ${error.message}`);
    }
  }
 
  /**
   * Attaches payment method to customer.
   * 
   * Links payment method (card, bank account) to customer for future charges. Required
   * for recurring billing and saved payment methods. Payment method must be created on
   * frontend (Stripe.js) before attaching.
   * 
   * **Frontend Flow:**
   * 1. Frontend creates PaymentMethod with Stripe.js (card details never touch server)
   * 2. Frontend sends payment_method_id to backend
   * 3. Backend attaches payment method to customer
   * 4. Optionally set as default payment method
   * 
   * @async
   * @static
   * @function attachPaymentMethod
   * @param {string} paymentMethodId - Payment Method ID (pm_...)
   * @param {string} customerId - Stripe Customer ID (cus_...)
   * @param {string} stripeAccountId - Connected Account ID
   * @param {boolean} [setAsDefault=false] - Set as default payment method for customer
   * @returns {Promise<Object>} PaymentMethod object with id, type, card details
   * @throws {Error} If attachment fails or payment method already attached
   * 
   * @example
   * // Attach card and set as default
   * const paymentMethod = await stripeService.attachPaymentMethod(
   *   'pm_1234567890', // From frontend Stripe.js
   *   'cus_1234567890',
   *   'acct_1234567890',
   *   true // Set as default
   * );
   * 
   * console.log(paymentMethod.type); // 'card'
   * console.log(paymentMethod.card.brand); // 'visa'
   * console.log(paymentMethod.card.last4); // '4242'
   * console.log(paymentMethod.card.exp_month); // 12
   * console.log(paymentMethod.card.exp_year); // 2025
   * 
   * // Store in database
   * await pool.query(
   *   `INSERT INTO payment_methods 
   *    (stripe_payment_method_id, customer_id, type, card_brand, card_last4, is_default) 
   *    VALUES ($1, $2, $3, $4, $5, $6)`,
   *   [paymentMethod.id, customerId, 'card', paymentMethod.card.brand, 
   *    paymentMethod.card.last4, true]
   * );
   */
  static async attachPaymentMethod(paymentMethodId, customerId, stripeAccountId, setAsDefault = false) {
    try {
      // Attach payment method to customer
      const paymentMethod = await stripe.paymentMethods.attach(
        paymentMethodId,
        { customer: customerId },
        { stripeAccount: stripeAccountId }
      );
      
      console.log(`💳 Attached Payment Method ${paymentMethodId} to customer ${customerId}`);
      
      // Optionally set as default payment method
      if (setAsDefault) {
        await stripe.customers.update(
          customerId,
          {
            invoice_settings: {
              default_payment_method: paymentMethodId,
            },
          },
          { stripeAccount: stripeAccountId }
        );
        console.log(`   Set as default payment method`);
      }
      
      return paymentMethod;
    } catch (error) {
      console.error('❌ Failed to attach payment method:', error.message);
      throw new Error(`Payment method attachment failed: ${error.message}`);
    }
  }
 
  /**
   * Updates Connected Account configuration in database.
   * 
   * Syncs Stripe account status to stripe_config table. Call after account.updated
   * webhook or after retrieving account details. Updates charges_enabled, payouts_enabled,
   * verification_status, and requirements.
   * 
   * @async
   * @static
   * @function updateAccountConfig
   * @param {number} tenantId - Tenant ID from tenants table
   * @param {Object} account - Stripe Account object from retrieveAccount()
   * @returns {Promise<void>} Resolves when database updated
   * @throws {Error} If database update fails
   * 
   * @example
   * // After receiving account.updated webhook
   * const account = await stripeService.retrieveAccount('acct_1234567890');
   * await stripeService.updateAccountConfig(789, account);
   * 
   * console.log('✅ Account config synced to database');
   */
  static async updateAccountConfig(tenantId, account) {
    try {
      // Determine account status
      let accountStatus = 'pending';
      if (!account.details_submitted) {
        accountStatus = 'pending';
      } else if (account.charges_enabled && account.payouts_enabled) {
        accountStatus = 'verified';
      } else if (account.requirements.disabled_reason) {
        accountStatus = 'disabled';
      }
 
      // Determine verification status
      let verificationStatus = 'unverified';
      if (account.charges_enabled && account.payouts_enabled) {
        verificationStatus = 'verified';
      } else if (account.details_submitted && account.requirements.currently_due.length > 0) {
        verificationStatus = 'pending';
      } else if (account.requirements.disabled_reason) {
        verificationStatus = 'failed';
      }
 
      await pool.query(
        `UPDATE stripe_config SET
          account_status = $1,
          charges_enabled = $2,
          payouts_enabled = $3,
          details_submitted = $4,
          verification_status = $5,
          requirements_currently_due = $6,
          requirements_eventually_due = $7,
          requirements_disabled_reason = $8,
          updated_at = NOW()
        WHERE tenant_id = $9 AND stripe_account_id = $10`,
        [
          accountStatus,
          account.charges_enabled,
          account.payouts_enabled,
          account.details_submitted,
          verificationStatus,
          account.requirements.currently_due || [],
          account.requirements.eventually_due || [],
          account.requirements.disabled_reason || null,
          tenantId,
          account.id,
        ]
      );
 
      console.log(`✅ Updated account config for tenant ${tenantId} (status: ${accountStatus})`);
    } catch (error) {
      console.error('❌ Failed to update account config:', error.message);
      throw error;
    }
  }
}
 
module.exports = StripeService;