@xenterprises/fastify-xstripe 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,883 @@
+# Event Handler Examples
+
+Real-world examples for each Stripe webhook event type.
+
+## Table of Contents
+
+- [Subscription Events](#subscription-events)
+- [Invoice Events](#invoice-events)
+- [Payment Events](#payment-events)
+- [Customer Events](#customer-events)
+- [Payment Method Events](#payment-method-events)
+- [Checkout Events](#checkout-events)
+- [Complete Use Cases](#complete-use-cases)
+
+---
+
+## Subscription Events
+
+### `customer.subscription.created`
+
+**When it fires:** A new subscription is created (via Checkout or API).
+
+**Common use cases:**
+- Grant user access to premium features
+- Send welcome email
+- Start onboarding flow
+- Track conversion metrics
+
+```javascript
+'customer.subscription.created': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+  const customer = await stripe.customers.retrieve(subscription.customer);
+
+  // Update database
+  await fastify.prisma.user.update({
+    where: { email: customer.email },
+    data: {
+      stripeCustomerId: subscription.customer,
+      stripeSubscriptionId: subscription.id,
+      subscriptionStatus: subscription.status,
+      planId: subscription.items.data[0]?.price.id,
+      trialEndsAt: subscription.trial_end
+        ? new Date(subscription.trial_end * 1000)
+        : null,
+      subscriptionStartedAt: new Date(),
+    },
+  });
+
+  // Send welcome email
+  await fastify.email.send(
+    customer.email,
+    'Welcome to Premium!',
+    `
+      <h1>Welcome aboard! 🎉</h1>
+      <p>Your subscription is now active.</p>
+      <p>Plan: ${subscription.items.data[0]?.price.nickname}</p>
+    `
+  );
+
+  // Send Slack notification
+  await fastify.slack.send(`New subscriber: ${customer.email}`);
+
+  fastify.log.info({
+    event: 'subscription_created',
+    customerId: subscription.customer,
+    plan: subscription.items.data[0]?.price.id,
+  });
+}
+```
+
+---
+
+### `customer.subscription.updated`
+
+**When it fires:** Subscription changes (status, plan, quantity, etc.).
+
+**Common use cases:**
+- Handle plan upgrades/downgrades
+- Update feature access
+- Track status changes
+- Handle trial conversions
+
+```javascript
+'customer.subscription.updated': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+  const previous = event.data.previous_attributes || {};
+
+  // Check what changed
+  const statusChanged = 'status' in previous;
+  const planChanged = 'items' in previous;
+
+  // Update database
+  await fastify.prisma.user.update({
+    where: { stripeSubscriptionId: subscription.id },
+    data: {
+      subscriptionStatus: subscription.status,
+      planId: subscription.items.data[0]?.price.id,
+    },
+  });
+
+  // Handle status changes
+  if (statusChanged) {
+    const oldStatus = previous.status;
+    const newStatus = subscription.status;
+
+    // Trial converted to paid
+    if (newStatus === 'active' && oldStatus === 'trialing') {
+      await fastify.email.send(
+        subscription.customer.email,
+        'Trial Converted!',
+        '<p>Your trial has successfully converted to a paid subscription.</p>'
+      );
+
+      fastify.log.info('Trial converted to paid', {
+        subscriptionId: subscription.id,
+      });
+    }
+
+    // Subscription past due
+    if (newStatus === 'past_due') {
+      await fastify.email.send(
+        subscription.customer.email,
+        'Payment Issue',
+        '<p>We had trouble processing your payment. Please update your payment method.</p>'
+      );
+
+      await fastify.sms.send(
+        subscription.customer.phone,
+        'Payment failed for your subscription. Please update your card.'
+      );
+
+      fastify.log.warn('Subscription past due', {
+        subscriptionId: subscription.id,
+      });
+    }
+
+    // Subscription canceled
+    if (newStatus === 'canceled') {
+      await fastify.prisma.user.update({
+        where: { stripeSubscriptionId: subscription.id },
+        data: { hasAccess: false },
+      });
+
+      fastify.log.info('Subscription canceled', {
+        subscriptionId: subscription.id,
+      });
+    }
+  }
+
+  // Handle plan changes (upgrade/downgrade)
+  if (planChanged) {
+    const oldPlan = previous.items?.data[0]?.price.id;
+    const newPlan = subscription.items.data[0]?.price.id;
+
+    await fastify.email.send(
+      subscription.customer.email,
+      'Plan Updated',
+      `<p>Your plan has been updated from ${oldPlan} to ${newPlan}.</p>`
+    );
+
+    fastify.log.info('Plan changed', {
+      subscriptionId: subscription.id,
+      oldPlan,
+      newPlan,
+    });
+  }
+}
+```
+
+---
+
+### `customer.subscription.deleted`
+
+**When it fires:** Subscription is canceled (immediately or at period end).
+
+**Common use cases:**
+- Revoke access to features
+- Send cancellation feedback survey
+- Trigger win-back campaign
+- Clean up resources
+
+```javascript
+'customer.subscription.deleted': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+  const customer = await stripe.customers.retrieve(subscription.customer);
+
+  // Revoke access
+  await fastify.prisma.user.update({
+    where: { stripeSubscriptionId: subscription.id },
+    data: {
+      subscriptionStatus: 'canceled',
+      hasAccess: false,
+      canceledAt: new Date(),
+      subscriptionId: null,
+    },
+  });
+
+  // Send cancellation email with feedback survey
+  await fastify.email.send(
+    customer.email,
+    "We're sorry to see you go",
+    `
+      <h1>Subscription Canceled</h1>
+      <p>Your subscription has been canceled and will end on
+         ${new Date(subscription.current_period_end * 1000).toLocaleDateString()}.</p>
+
+      <p>We'd love your feedback:</p>
+      <a href="https://example.com/feedback?user=${customer.id}">
+        Take our 2-minute survey
+      </a>
+
+      <p>You can reactivate anytime at https://example.com/billing</p>
+    `
+  );
+
+  // Schedule win-back email for 7 days later
+  await fastify.scheduleEmail({
+    to: customer.email,
+    subject: 'Special offer to return',
+    sendAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+  });
+
+  // Notify team
+  await fastify.slack.send(
+    `Customer canceled: ${customer.email} - Plan: ${subscription.items.data[0]?.price.nickname}`
+  );
+
+  fastify.log.info({
+    event: 'subscription_canceled',
+    customerId: subscription.customer,
+    reason: subscription.cancellation_details?.reason,
+  });
+}
+```
+
+---
+
+### `customer.subscription.trial_will_end`
+
+**When it fires:** 3 days before trial ends.
+
+**Common use cases:**
+- Send trial ending reminder
+- Encourage conversion
+- Highlight value
+
+```javascript
+'customer.subscription.trial_will_end': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+  const customer = await stripe.customers.retrieve(subscription.customer);
+  const trialEnd = new Date(subscription.trial_end * 1000);
+  const daysRemaining = Math.ceil(
+    (subscription.trial_end * 1000 - Date.now()) / (1000 * 60 * 60 * 24)
+  );
+
+  // Send email reminder
+  await fastify.email.send(
+    customer.email,
+    `Your trial ends in ${daysRemaining} days`,
+    `
+      <h1>Your trial is ending soon!</h1>
+      <p>Your trial ends on ${trialEnd.toLocaleDateString()}.</p>
+
+      <h2>What happens next?</h2>
+      <p>Your card will be charged ${subscription.items.data[0]?.price.unit_amount / 100}
+         ${subscription.currency.toUpperCase()} to continue your subscription.</p>
+
+      <p><a href="https://example.com/billing">Manage your subscription</a></p>
+      <p><a href="https://example.com/cancel">Cancel anytime</a></p>
+    `
+  );
+
+  // Send SMS reminder
+  if (customer.phone) {
+    await fastify.sms.send(
+      customer.phone,
+      `Your trial ends in ${daysRemaining} days. Keep your access by doing nothing, or cancel anytime.`
+    );
+  }
+
+  // Track conversion intent
+  await fastify.analytics.track(customer.id, 'trial_ending_soon', {
+    daysRemaining,
+    plan: subscription.items.data[0]?.price.id,
+  });
+
+  fastify.log.info({
+    event: 'trial_ending_soon',
+    customerId: subscription.customer,
+    daysRemaining,
+  });
+}
+```
+
+---
+
+### `customer.subscription.paused` / `customer.subscription.resumed`
+
+**When it fires:** Subscription is paused or resumed.
+
+**Common use cases:**
+- Update user access
+- Send confirmation
+- Track churn prevention
+
+```javascript
+'customer.subscription.paused': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+
+  await fastify.prisma.user.update({
+    where: { stripeSubscriptionId: subscription.id },
+    data: {
+      subscriptionStatus: 'paused',
+      hasAccess: false,
+    },
+  });
+
+  fastify.log.info('Subscription paused', {
+    subscriptionId: subscription.id,
+  });
+},
+
+'customer.subscription.resumed': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+
+  await fastify.prisma.user.update({
+    where: { stripeSubscriptionId: subscription.id },
+    data: {
+      subscriptionStatus: 'active',
+      hasAccess: true,
+    },
+  });
+
+  const customer = await stripe.customers.retrieve(subscription.customer);
+  await fastify.email.send(
+    customer.email,
+    'Subscription Resumed',
+    '<p>Welcome back! Your subscription has been resumed.</p>'
+  );
+
+  fastify.log.info('Subscription resumed', {
+    subscriptionId: subscription.id,
+  });
+}
+```
+
+---
+
+## Invoice Events
+
+### `invoice.paid`
+
+**When it fires:** Invoice payment succeeds.
+
+**Common use cases:**
+- Send receipt
+- Reset failed payment counters
+- Grant/extend access
+- Track revenue
+
+```javascript
+'invoice.paid': async (event, fastify, stripe) => {
+  const invoice = event.data.object;
+  const customer = await stripe.customers.retrieve(invoice.customer);
+
+  // Update database
+  await fastify.prisma.user.update({
+    where: { stripeCustomerId: invoice.customer },
+    data: {
+      failedPaymentCount: 0,
+      lastSuccessfulPayment: new Date(),
+    },
+  });
+
+  // For subscription invoices
+  if (invoice.subscription) {
+    const isFirstPayment = invoice.billing_reason === 'subscription_create';
+    const isRenewal = invoice.billing_reason === 'subscription_cycle';
+
+    if (isRenewal) {
+      // Track renewal
+      await fastify.analytics.track(customer.id, 'subscription_renewed', {
+        amount: invoice.amount_paid / 100,
+        plan: invoice.lines.data[0]?.price?.id,
+      });
+
+      // Send renewal confirmation
+      await fastify.email.send(
+        customer.email,
+        'Payment Received - Subscription Renewed',
+        `
+          <h1>Thank you for your payment!</h1>
+          <p>Amount: $${invoice.amount_paid / 100}</p>
+          <p>Your subscription has been renewed for another billing period.</p>
+          <a href="${invoice.hosted_invoice_url}">View Receipt</a>
+        `
+      );
+    }
+  }
+
+  // Track revenue
+  await fastify.analytics.revenue({
+    customerId: customer.id,
+    amount: invoice.amount_paid / 100,
+    currency: invoice.currency,
+    invoiceId: invoice.id,
+  });
+
+  fastify.log.info({
+    event: 'payment_successful',
+    customerId: invoice.customer,
+    amount: invoice.amount_paid / 100,
+    billingReason: invoice.billing_reason,
+  });
+}
+```
+
+---
+
+### `invoice.payment_failed`
+
+**When it fires:** Invoice payment fails.
+
+**Common use cases:**
+- Send payment failure notification
+- Track failed payment attempts
+- Suspend access after multiple failures
+- Update payment method
+
+```javascript
+'invoice.payment_failed': async (event, fastify, stripe) => {
+  const invoice = event.data.object;
+  const customer = await stripe.customers.retrieve(invoice.customer);
+
+  // Track failed payment
+  const user = await fastify.prisma.user.update({
+    where: { stripeCustomerId: invoice.customer },
+    data: {
+      failedPaymentCount: { increment: 1 },
+      lastFailedPayment: new Date(),
+    },
+  });
+
+  // Send email notification
+  await fastify.email.send(
+    customer.email,
+    'Payment Failed - Action Required',
+    `
+      <h1>We couldn't process your payment</h1>
+      <p>Amount: $${invoice.amount_due / 100}</p>
+      <p>Attempt: ${invoice.attempt_count} of 4</p>
+
+      ${invoice.next_payment_attempt
+        ? `<p>We'll retry on ${new Date(invoice.next_payment_attempt * 1000).toLocaleDateString()}</p>`
+        : '<p>No more automatic retries.</p>'
+      }
+
+      <a href="https://example.com/billing/update">Update Payment Method</a>
+    `
+  );
+
+  // Send SMS for urgent notification
+  if (customer.phone) {
+    await fastify.sms.send(
+      customer.phone,
+      `Payment failed for your subscription. Update your payment method: https://example.com/billing`
+    );
+  }
+
+  // Suspend access after 3 failed attempts
+  if (user.failedPaymentCount >= 3) {
+    await fastify.prisma.user.update({
+      where: { id: user.id },
+      data: {
+        hasAccess: false,
+        accountSuspended: true,
+      },
+    });
+
+    await fastify.email.send(
+      customer.email,
+      'Account Suspended',
+      '<p>Your account has been suspended due to multiple failed payments.</p>'
+    );
+
+    fastify.log.warn('Account suspended', {
+      customerId: invoice.customer,
+      failedAttempts: user.failedPaymentCount,
+    });
+  }
+
+  // Notify team for high-value customers
+  if (invoice.amount_due > 10000) { // $100+
+    await fastify.slack.send(
+      `⚠️ Payment failed for high-value customer: ${customer.email} - $${invoice.amount_due / 100}`
+    );
+  }
+
+  fastify.log.error({
+    event: 'payment_failed',
+    customerId: invoice.customer,
+    amount: invoice.amount_due / 100,
+    attemptCount: invoice.attempt_count,
+  });
+}
+```
+
+---
+
+### `invoice.upcoming`
+
+**When it fires:** 7 days before invoice is finalized.
+
+**Common use cases:**
+- Send billing reminder
+- Allow payment method update
+- Prevent surprise charges
+
+```javascript
+'invoice.upcoming': async (event, fastify, stripe) => {
+  const invoice = event.data.object;
+  const customer = await stripe.customers.retrieve(invoice.customer);
+  const billingDate = new Date(invoice.period_end * 1000);
+  const daysUntilBilling = Math.ceil(
+    (invoice.period_end * 1000 - Date.now()) / (1000 * 60 * 60 * 24)
+  );
+
+  // Send upcoming charge email
+  await fastify.email.send(
+    customer.email,
+    `Upcoming Charge: $${invoice.amount_due / 100}`,
+    `
+      <h1>Upcoming Charge Notification</h1>
+      <p>Your card will be charged <strong>$${invoice.amount_due / 100}</strong>
+         on ${billingDate.toLocaleDateString()} (in ${daysUntilBilling} days).</p>
+
+      <h2>Billing Details:</h2>
+      <ul>
+        ${invoice.lines.data.map(line => `
+          <li>${line.description}: $${line.amount / 100}</li>
+        `).join('')}
+      </ul>
+
+      <p><a href="https://example.com/billing">Manage Billing</a></p>
+      <p><a href="https://example.com/billing/update">Update Payment Method</a></p>
+    `
+  );
+
+  // Check for usage-based pricing and notify if high
+  const usageLineItems = invoice.lines.data.filter(
+    line => line.price?.billing_scheme === 'tiered'
+  );
+
+  if (usageLineItems.length > 0) {
+    const usageAmount = usageLineItems.reduce((sum, item) => sum + item.amount, 0);
+
+    if (usageAmount > 5000) { // $50+ in usage
+      await fastify.email.send(
+        customer.email,
+        'High Usage Alert',
+        `<p>Your usage this period is higher than usual: $${usageAmount / 100}</p>`
+      );
+    }
+  }
+
+  fastify.log.info({
+    event: 'upcoming_invoice',
+    customerId: invoice.customer,
+    amount: invoice.amount_due / 100,
+    daysUntilBilling,
+  });
+}
+```
+
+---
+
+## Payment Events
+
+### `payment_intent.succeeded`
+
+**When it fires:** One-time payment succeeds.
+
+**Common use cases:**
+- Fulfill order
+- Send confirmation
+- Grant access to purchased item
+
+```javascript
+'payment_intent.succeeded': async (event, fastify, stripe) => {
+  const paymentIntent = event.data.object;
+  const metadata = paymentIntent.metadata;
+
+  // Different handling based on what was purchased
+  if (metadata.type === 'course_purchase') {
+    await fastify.prisma.enrollment.create({
+      data: {
+        userId: metadata.userId,
+        courseId: metadata.courseId,
+        paymentIntentId: paymentIntent.id,
+        amount: paymentIntent.amount / 100,
+      },
+    });
+
+    const customer = await stripe.customers.retrieve(paymentIntent.customer);
+    await fastify.email.send(
+      customer.email,
+      'Course Access Granted!',
+      `
+        <h1>Welcome to the course!</h1>
+        <p>Your payment of $${paymentIntent.amount / 100} has been received.</p>
+        <a href="https://example.com/courses/${metadata.courseId}">Start Learning</a>
+      `
+    );
+  }
+
+  if (metadata.type === 'credit_purchase') {
+    await fastify.prisma.user.update({
+      where: { id: metadata.userId },
+      data: {
+        credits: { increment: parseInt(metadata.credits) },
+      },
+    });
+  }
+
+  fastify.log.info({
+    event: 'payment_succeeded',
+    paymentIntentId: paymentIntent.id,
+    amount: paymentIntent.amount / 100,
+    type: metadata.type,
+  });
+}
+```
+
+---
+
+## Customer Events
+
+### `customer.created`
+
+**When it fires:** New customer created in Stripe.
+
+**Common use cases:**
+- Sync customer to CRM
+- Create user record
+- Send welcome message
+
+```javascript
+'customer.created': async (event, fastify, stripe) => {
+  const customer = event.data.object;
+
+  // Create or update user in database
+  await fastify.prisma.user.upsert({
+    where: { email: customer.email },
+    update: {
+      stripeCustomerId: customer.id,
+    },
+    create: {
+      email: customer.email,
+      name: customer.name,
+      stripeCustomerId: customer.id,
+    },
+  });
+
+  // Sync to CRM
+  await fastify.crm.createContact({
+    email: customer.email,
+    name: customer.name,
+    stripeId: customer.id,
+  });
+
+  fastify.log.info({
+    event: 'customer_created',
+    customerId: customer.id,
+    email: customer.email,
+  });
+}
+```
+
+---
+
+## Checkout Events
+
+### `checkout.session.completed`
+
+**When it fires:** Checkout session completes successfully.
+
+**Common use cases:**
+- Provision access
+- Send welcome email
+- Track conversion
+
+```javascript
+'checkout.session.completed': async (event, fastify, stripe) => {
+  const session = event.data.object;
+
+  if (session.mode === 'subscription') {
+    // Subscription checkout
+    const subscription = await stripe.subscriptions.retrieve(session.subscription);
+
+    await fastify.prisma.user.update({
+      where: { email: session.customer_details.email },
+      data: {
+        stripeCustomerId: session.customer,
+        stripeSubscriptionId: session.subscription,
+        subscriptionStatus: subscription.status,
+        hasAccess: true,
+        onboardedAt: new Date(),
+      },
+    });
+
+    // Send welcome email
+    await fastify.email.send(
+      session.customer_details.email,
+      'Welcome to Premium!',
+      `
+        <h1>Welcome aboard! 🎉</h1>
+        <p>Your subscription is now active.</p>
+        <a href="https://example.com/dashboard">Get Started</a>
+      `
+    );
+
+    // Track conversion
+    await fastify.analytics.track(session.customer, 'subscription_started', {
+      plan: subscription.items.data[0]?.price.id,
+      amount: subscription.items.data[0]?.price.unit_amount / 100,
+    });
+  }
+
+  if (session.mode === 'payment') {
+    // One-time payment
+    const paymentIntent = await stripe.paymentIntents.retrieve(session.payment_intent);
+
+    // Handle based on metadata
+    // ... (similar to payment_intent.succeeded)
+  }
+
+  fastify.log.info({
+    event: 'checkout_completed',
+    sessionId: session.id,
+    customerId: session.customer,
+    mode: session.mode,
+  });
+}
+```
+
+---
+
+## Complete Use Cases
+
+### SaaS Subscription Flow
+
+```javascript
+const saasHandlers = {
+  // 1. User subscribes
+  'checkout.session.completed': async (event, fastify, stripe) => {
+    const session = event.data.object;
+
+    await fastify.prisma.user.update({
+      where: { email: session.customer_details.email },
+      data: {
+        stripeCustomerId: session.customer,
+        stripeSubscriptionId: session.subscription,
+        plan: session.metadata.plan,
+        hasAccess: true,
+      },
+    });
+
+    await fastify.email.sendTemplate(
+      session.customer_details.email,
+      'Welcome Email',
+      'd-welcome123',
+      { name: session.customer_details.name }
+    );
+  },
+
+  // 2. Monthly renewal
+  'invoice.paid': async (event, fastify, stripe) => {
+    if (event.data.object.billing_reason === 'subscription_cycle') {
+      await fastify.analytics.track(event.data.object.customer, 'subscription_renewed');
+    }
+  },
+
+  // 3. Payment fails
+  'invoice.payment_failed': async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+
+    if (invoice.attempt_count >= 3) {
+      await fastify.prisma.user.update({
+        where: { stripeCustomerId: invoice.customer },
+        data: { hasAccess: false },
+      });
+    }
+  },
+
+  // 4. User cancels
+  'customer.subscription.deleted': async (event, fastify, stripe) => {
+    await fastify.prisma.user.update({
+      where: { stripeSubscriptionId: event.data.object.id },
+      data: {
+        hasAccess: false,
+        canceledAt: new Date(),
+      },
+    });
+  },
+};
+```
+
+### Course Platform
+
+```javascript
+const courseHandlers = {
+  'payment_intent.succeeded': async (event, fastify, stripe) => {
+    const pi = event.data.object;
+    const { courseId, userId } = pi.metadata;
+
+    // Grant access
+    await fastify.prisma.enrollment.create({
+      data: {
+        userId,
+        courseId,
+        enrolledAt: new Date(),
+      },
+    });
+
+    // Send course materials
+    const user = await fastify.prisma.user.findUnique({ where: { id: userId } });
+    const course = await fastify.prisma.course.findUnique({ where: { id: courseId } });
+
+    await fastify.email.send(
+      user.email,
+      `Welcome to ${course.title}!`,
+      `<a href="https://example.com/courses/${courseId}/lesson/1">Start Lesson 1</a>`
+    );
+  },
+};
+```
+
+### Usage-Based Billing
+
+```javascript
+const usageHandlers = {
+  'invoice.upcoming': async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+
+    // Alert customer about high usage
+    const usageItems = invoice.lines.data.filter(
+      line => line.type === 'subscription' && line.proration === false
+    );
+
+    const totalUsage = usageItems.reduce((sum, item) => sum + item.amount, 0);
+
+    if (totalUsage > 10000) {
+      const customer = await stripe.customers.retrieve(invoice.customer);
+
+      await fastify.email.send(
+        customer.email,
+        'High Usage Alert',
+        `Your usage this month is $${totalUsage / 100}. Review your usage to avoid surprises.`
+      );
+    }
+  },
+};
+```
+
+---
+
+## Import and Use Examples
+
+```javascript
+// In your server setup
+import xStripe from '@xenterprises/fastify-xstripe';
+import { formatAmount, getPlanName } from '@xenterprises/fastify-xstripe/helpers';
+
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  handlers: {
+    // Mix and match from examples above
+    ...saasHandlers,
+    ...customHandlers,
+  },
+});
+```