Stripe Integration: SaaS Billing & Subscription Management

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const subscriptionConfig = {
  plans: {
    starter: {
      priceId: 'price_starter_monthly',
      features: ['5_projects', '10gb_storage', 'basic_support'],
      limits: { api_calls: 1000, users: 5 }
    },
    professional: {
      priceId: 'price_professional_monthly', 
      features: ['50_projects', '100gb_storage', 'priority_support', 'advanced_analytics'],
      limits: { api_calls: 5000, users: 25 }
    },
    enterprise: {
      priceId: 'price_enterprise_monthly',
      features: ['unlimited_projects', '1tb_storage', 'dedicated_support', 'custom_integrations'],
      limits: { api_calls: 50000, users: 'unlimited' }
    }
  },
  
  webhookEndpoints: [
    'invoice.payment_succeeded',
    'invoice.payment_failed', 
    'customer.subscription.updated',
    'customer.subscription.deleted',
    'payment_method.attached'
  ]
};

async function createSubscription(customerId, priceId, paymentMethodId) {
  try {
    const subscription = await stripe.subscriptions.create({
      customer: customerId,
      items: [{ price: priceId }],
      default_payment_method: paymentMethodId,
      expand: ['latest_invoice.payment_intent'],
      metadata: {
        platform: 'taskflow_pro',
        created_by: 'billing_system'
      }
    });
    
    await updateUserSubscriptionData(customerId, subscription);
    await createBillingHistoryRecord(subscription);
    
    return subscription;
  } catch (error) {
    await logBillingError(error, customerId);
    throw error;
  }
}

async function handleSubscriptionChange(customerId, newPriceId, changeType) {
  const customer = await getCustomerData(customerId);
  const currentSubscription = await stripe.subscriptions.retrieve(customer.subscription_id);
  
  const prorationDate = Math.floor(Date.now() / 1000);
  
  if (changeType === 'upgrade') {
    await stripe.subscriptions.update(currentSubscription.id, {
      items: [{
        id: currentSubscription.items.data[0].id,
        price: newPriceId,
      }],
      proration_behavior: 'create_prorations',
      proration_date: prorationDate
    });
    
    await applyCreditForUpgrade(customerId, currentSubscription, newPriceId);
  } else if (changeType === 'downgrade') {
    await scheduleDowngrade(currentSubscription.id, newPriceId);
    await calculateDowngradeCredit(customerId, currentSubscription, newPriceId);
  }
  
  await updateFeatureAccess(customerId, newPriceId);
  await sendSubscriptionChangeEmail(customerId, changeType);
}

CREATE TABLE credit_transactions (
  id SERIAL PRIMARY KEY,
  customer_id VARCHAR(255) NOT NULL,
  stripe_customer_id VARCHAR(255) NOT NULL,
  transaction_type ENUM('credit', 'debit', 'refund', 'promotional', 'overage') NOT NULL,
  amount DECIMAL(10,2) NOT NULL,
  description TEXT,
  reference_id VARCHAR(255),
  stripe_invoice_id VARCHAR(255),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  processed_at TIMESTAMP,
  metadata JSON
);

CREATE TABLE customer_credit_balances (
  customer_id VARCHAR(255) PRIMARY KEY,
  current_balance DECIMAL(10,2) DEFAULT 0.00,
  lifetime_credits DECIMAL(10,2) DEFAULT 0.00,
  lifetime_debits DECIMAL(10,2) DEFAULT 0.00,
  last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  auto_apply_enabled BOOLEAN DEFAULT true
);

async function applyCreditToInvoice(invoiceId, customerId) {
  const creditBalance = await getCreditBalance(customerId);
  
  if (creditBalance > 0) {
    const invoice = await stripe.invoices.retrieve(invoiceId);
    const creditToApply = Math.min(creditBalance, invoice.amount_due / 100);
    
    if (creditToApply > 0) {
      await stripe.invoiceItems.create({
        customer: invoice.customer,
        invoice: invoiceId,
        amount: -(creditToApply * 100),
        currency: invoice.currency,
        description: `Credit balance applied: $${creditToApply.toFixed(2)}`
      });
      
      await deductCreditBalance(customerId, creditToApply, 'invoice_credit_application');
    }
  }
}

const PDFDocument = require('pdfkit');

async function generateInvoicePDF(invoiceData) {
  const doc = new PDFDocument({ margin: 50 });
  
  doc.fontSize(20).text('TaskFlow Pro', 50, 50);
  doc.fontSize(16).text('INVOICE', 400, 50);
  
  doc.fontSize(12).text(`Invoice #: ${invoiceData.invoice_number}`, 400, 80);
  doc.text(`Date: ${formatDate(invoiceData.date)}`, 400, 95);
  doc.text(`Due Date: ${formatDate(invoiceData.due_date)}`, 400, 110);
  
  let yPosition = 150;
  
  doc.fontSize(14).text('Bill To:', 50, yPosition);
  yPosition += 20;
  doc.fontSize(11).text(invoiceData.customer.name, 50, yPosition);
  yPosition += 15;
  doc.text(invoiceData.customer.email, 50, yPosition);
  
  yPosition = 220;
  doc.fontSize(12).text('Description', 50, yPosition);
  doc.text('Amount', 450, yPosition);
  
  yPosition += 30;
  invoiceData.line_items.forEach(item => {
    doc.fontSize(10).text(item.description, 50, yPosition);
    doc.text(`$${item.amount.toFixed(2)}`, 450, yPosition);
    yPosition += 20;
  });
  
  yPosition += 20;
  doc.fontSize(12).text(`Total: $${invoiceData.total.toFixed(2)}`, 400, yPosition);
  
  return doc;
}

async function emailInvoiceToCustomer(customerId, invoicePDF) {
  const customer = await getCustomerData(customerId);
  
  const emailData = {
    to: customer.email,
    subject: `Your TaskFlow Pro Invoice - ${new Date().toLocaleDateString()}`,
    template: 'invoice_email',
    attachments: [{
      filename: `TaskFlow-Pro-Invoice-${Date.now()}.pdf`,
      content: invoicePDF,
      contentType: 'application/pdf'
    }]
  };
  
  await sendEmail(emailData);
  await logInvoiceEmailSent(customerId);
}

async function handleFailedPayment(invoice) {
  const customer = await getCustomerData(invoice.customer);
  const failureReason = invoice.payment_intent.last_payment_error?.decline_code;
  
  const dunningStrategy = {
    'insufficient_funds': {
      retryDays: [3, 5, 7],
      emailTemplate: 'insufficient_funds_recovery',
      gracePeriod: 7
    },
    'expired_card': {
      retryDays: [1, 3],
      emailTemplate: 'expired_card_update',
      gracePeriod: 3,
      useCardUpdater: true
    },
    'generic_decline': {
      retryDays: [1, 3, 7],
      emailTemplate: 'payment_failed_generic',
      gracePeriod: 5
    }
  };
  
  const strategy = dunningStrategy[failureReason] || dunningStrategy['generic_decline'];
  
  await schedulePaymentRetries(invoice.id, strategy.retryDays);
  await sendFailureRecoveryEmail(customer, strategy.emailTemplate, {
    invoice_url: `${process.env.APP_URL}/billing/invoice/${invoice.id}`,
    update_payment_url: `${process.env.APP_URL}/billing/payment-methods`,
    grace_period: strategy.gracePeriod
  });
  
  if (strategy.useCardUpdater) {
    await requestCardUpdaterRefresh(customer.default_payment_method);
  }
  
  await updateSubscriptionStatus(customer.subscription_id, 'past_due');
  await logDunningEvent(customer.id, failureReason, strategy);
}

async function processSuccessfulRecovery(customerId, invoiceId) {
  await updateSubscriptionStatus(customer.subscription_id, 'active');
  await sendRecoverySuccessEmail(customerId);
  await applyAvailableCredits(customerId);
  await logSuccessfulRecovery(customerId, invoiceId);
}

class RevenueAnalytics {
  async calculateMRR(date = new Date()) {
    const subscriptions = await getActiveSubscriptions(date);
    
    let mrr = 0;
    for (const subscription of subscriptions) {
      const monthlyValue = this.normalizeToMonthly(
        subscription.amount, 
        subscription.interval
      );
      mrr += monthlyValue;
    }
    
    return mrr;
  }
  
  async calculateChurnRate(startDate, endDate) {
    const startSubscriptions = await getActiveSubscriptions(startDate);
    const churned = await getChurnedSubscriptions(startDate, endDate);
    
    return (churned.length / startSubscriptions.length) * 100;
  }
  
  async generateCohortAnalysis(startDate, months = 12) {
    const cohorts = {};
    
    for (let i = 0; i < months; i++) {
      const cohortDate = new Date(startDate);
      cohortDate.setMonth(cohortDate.getMonth() + i);
      
      const newCustomers = await getNewCustomers(cohortDate);
      const retentionData = await calculateRetention(newCustomers, months - i);
      
      cohorts[cohortDate.toISOString().slice(0, 7)] = {
        customers: newCustomers.length,
        retention: retentionData
      };
    }
    
    return cohorts;
  }
  
  async trackSubscriptionLifecycle(customerId) {
    return {
      acquisition_date: await getCustomerAcquisitionDate(customerId),
      plan_changes: await getPlanChangeHistory(customerId),
      payment_history: await getPaymentHistory(customerId),
      support_interactions: await getSupportHistory(customerId),
      lifetime_value: await calculateLTV(customerId)
    };
  }
}