@xenterprises/fastify-xstripe 1.0.0

package/src/utils/helpers.js

@@ -0,0 +1,220 @@
+// src/utils/helpers.js
+
+/**
+ * Helper utilities for working with Stripe webhooks
+ */
+
+/**
+ * Extract customer email from various Stripe objects
+ */
+export function getCustomerEmail(event, stripe) {
+  const obj = event.data.object;
+
+  // Direct email on object
+  if (obj.email) return obj.email;
+
+  // Customer object
+  if (obj.customer?.email) return obj.customer.email;
+
+  // Need to fetch customer
+  if (obj.customer && typeof obj.customer === 'string') {
+    return stripe.customers.retrieve(obj.customer)
+      .then(customer => customer.email)
+      .catch(() => null);
+  }
+
+  return null;
+}
+
+/**
+ * Format amount from cents to dollars
+ */
+export function formatAmount(cents, currency = 'USD') {
+  const amount = cents / 100;
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(amount);
+}
+
+/**
+ * Get subscription plan name from subscription object
+ */
+export function getPlanName(subscription) {
+  const firstItem = subscription.items?.data?.[0];
+  if (!firstItem) return 'Unknown Plan';
+
+  const price = firstItem.price;
+  return price.nickname || price.product?.name || price.id;
+}
+
+/**
+ * Check if subscription is in trial
+ */
+export function isInTrial(subscription) {
+  return subscription.status === 'trialing' && subscription.trial_end > Date.now() / 1000;
+}
+
+/**
+ * Check if subscription is active (including trialing)
+ */
+export function isActiveSubscription(subscription) {
+  return ['active', 'trialing'].includes(subscription.status);
+}
+
+/**
+ * Get days until trial ends
+ */
+export function getDaysUntilTrialEnd(subscription) {
+  if (!subscription.trial_end) return null;
+
+  const now = Date.now() / 1000;
+  const secondsRemaining = subscription.trial_end - now;
+  return Math.ceil(secondsRemaining / 86400);
+}
+
+/**
+ * Determine if this is a subscription renewal vs new subscription
+ */
+export function isRenewal(event) {
+  if (event.type !== 'invoice.paid') return false;
+
+  const invoice = event.data.object;
+  return invoice.billing_reason === 'subscription_cycle';
+}
+
+/**
+ * Get subscription status display text
+ */
+export function getSubscriptionStatusText(status) {
+  const statusMap = {
+    active: 'Active',
+    trialing: 'Trial',
+    past_due: 'Past Due',
+    canceled: 'Canceled',
+    unpaid: 'Unpaid',
+    incomplete: 'Incomplete',
+    incomplete_expired: 'Incomplete (Expired)',
+    paused: 'Paused',
+  };
+
+  return statusMap[status] || status;
+}
+
+/**
+ * Extract metadata from event
+ */
+export function getMetadata(event) {
+  const obj = event.data.object;
+  return obj.metadata || {};
+}
+
+/**
+ * Check if event is a test event
+ */
+export function isTestEvent(event) {
+  return event.livemode === false;
+}
+
+/**
+ * Get human-readable event description
+ */
+export function getEventDescription(event) {
+  const descriptions = {
+    'customer.subscription.created': 'New subscription started',
+    'customer.subscription.updated': 'Subscription changed',
+    'customer.subscription.deleted': 'Subscription canceled',
+    'customer.subscription.trial_will_end': 'Trial ending soon',
+    'invoice.paid': 'Payment received',
+    'invoice.payment_failed': 'Payment failed',
+    'invoice.upcoming': 'Upcoming payment',
+    'payment_intent.succeeded': 'Payment succeeded',
+    'payment_intent.payment_failed': 'Payment attempt failed',
+    'checkout.session.completed': 'Checkout completed',
+  };
+
+  return descriptions[event.type] || event.type;
+}
+
+/**
+ * Calculate MRR (Monthly Recurring Revenue) from subscription
+ */
+export function calculateMRR(subscription) {
+  const firstItem = subscription.items?.data?.[0];
+  if (!firstItem) return 0;
+
+  const price = firstItem.price;
+  const amount = price.unit_amount * (firstItem.quantity || 1);
+
+  // Convert to monthly amount
+  switch (price.recurring?.interval) {
+    case 'year':
+      return amount / 12;
+    case 'month':
+      return amount;
+    case 'week':
+      return amount * 4.33;
+    case 'day':
+      return amount * 30;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Get payment method type display text
+ */
+export function getPaymentMethodType(paymentMethod) {
+  if (!paymentMethod) return 'Unknown';
+
+  const typeMap = {
+    card: 'Card',
+    bank_account: 'Bank Account',
+    sepa_debit: 'SEPA Direct Debit',
+    us_bank_account: 'US Bank Account',
+    paypal: 'PayPal',
+  };
+
+  return typeMap[paymentMethod.type] || paymentMethod.type;
+}
+
+/**
+ * Extract line items from invoice
+ */
+export function getInvoiceLineItems(invoice) {
+  return invoice.lines?.data?.map(line => ({
+    description: line.description,
+    amount: line.amount,
+    quantity: line.quantity,
+    priceId: line.price?.id,
+  })) || [];
+}
+
+/**
+ * Check if invoice is for subscription vs one-time payment
+ */
+export function isSubscriptionInvoice(invoice) {
+  return !!invoice.subscription;
+}
+
+/**
+ * Get next billing date from subscription
+ */
+export function getNextBillingDate(subscription) {
+  if (!subscription.current_period_end) return null;
+  return new Date(subscription.current_period_end * 1000);
+}
+
+/**
+ * Format date from Unix timestamp
+ */
+export function formatDate(unixTimestamp, locale = 'en-US') {
+  if (!unixTimestamp) return null;
+
+  const date = new Date(unixTimestamp * 1000);
+  return new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(date);
+}

package/src/webhooks/webhooks.js

@@ -0,0 +1,72 @@
+// src/webhooks/webhooks.js
+import { defaultHandlers } from "../handlers/defaultHandlers.js";
+
+export async function setupWebhooks(fastify, options) {
+  const { stripe, webhookSecret, webhookPath, handlers } = options;
+
+  // Merge user handlers with default handlers
+  const eventHandlers = { ...defaultHandlers, ...handlers };
+
+  // Register webhook route
+  fastify.post(
+    webhookPath,
+    {
+      config: {
+        // Disable body parsing - we need raw body for signature verification
+        rawBody: true,
+      },
+    },
+    async (request, reply) => {
+      const sig = request.headers["stripe-signature"];
+
+      if (!sig) {
+        fastify.log.error("Missing stripe-signature header");
+        return reply.code(400).send({ error: "Missing stripe-signature header" });
+      }
+
+      let event;
+
+      try {
+        // Get raw body for signature verification
+        const rawBody = request.rawBody || request.body;
+
+        // Verify webhook signature
+        event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret);
+      } catch (err) {
+        fastify.log.error(`Webhook signature verification failed: ${err.message}`);
+        return reply.code(400).send({ error: `Webhook Error: ${err.message}` });
+      }
+
+      // Log the event
+      fastify.log.info(`Received Stripe webhook: ${event.type}`);
+
+      // Get handler for this event type
+      const handler = eventHandlers[event.type];
+
+      if (handler) {
+        try {
+          // Execute handler
+          await handler(event, fastify, stripe);
+          fastify.log.info(`Successfully processed ${event.type}`);
+        } catch (err) {
+          fastify.log.error(`Error processing ${event.type}: ${err.message}`);
+          // Return 200 to acknowledge receipt, even if processing failed
+          // This prevents Stripe from retrying immediately
+          return reply.code(200).send({
+            received: true,
+            processed: false,
+            error: err.message
+          });
+        }
+      } else {
+        fastify.log.warn(`No handler registered for event type: ${event.type}`);
+      }
+
+      // Always return 200 to acknowledge receipt
+      return reply.code(200).send({ received: true, processed: !!handler });
+    }
+  );
+
+  console.info(`   ✅ Stripe Webhooks Enabled at ${webhookPath}`);
+  console.info(`   📋 Registered ${Object.keys(eventHandlers).length} event handlers`);
+}

package/src/xStripe.js

@@ -0,0 +1,45 @@
+// src/xStripe.js
+import fp from "fastify-plugin";
+import Stripe from "stripe";
+import { setupWebhooks } from "./webhooks/webhooks.js";
+
+async function xStripe(fastify, options) {
+  const {
+    apiKey,
+    webhookSecret,
+    webhookPath = "/stripe/webhook",
+    handlers = {},
+    apiVersion = "2024-11-20.acacia",
+  } = options;
+
+  // Validate required options
+  if (!apiKey) {
+    throw new Error("Stripe apiKey is required");
+  }
+
+  console.info("\n 💳 Starting xStripe...\n");
+
+  // Initialize Stripe client
+  const stripe = new Stripe(apiKey, { apiVersion });
+
+  // Decorate Fastify with Stripe client
+  fastify.decorate("stripe", stripe);
+
+  // Setup webhook handling if webhook secret is provided
+  if (webhookSecret) {
+    await setupWebhooks(fastify, {
+      stripe,
+      webhookSecret,
+      webhookPath,
+      handlers,
+    });
+  } else {
+    fastify.log.warn("⚠️  Stripe webhook secret not provided. Webhook handling disabled.");
+  }
+
+  console.info("\n 💳 xStripe Ready!\n");
+}
+
+export default fp(xStripe, {
+  name: "xStripe",
+});