@xenterprises/fastify-xstripe 1.0.0

package/src/handlers/defaultHandlers.js

@@ -0,0 +1,355 @@
+// src/handlers/defaultHandlers.js
+
+/**
+ * Default webhook event handlers
+ * These provide basic logging and can be overridden by user-provided handlers
+ */
+
+export const defaultHandlers = {
+  // ========== Subscription Events ==========
+
+  /**
+   * customer.subscription.created
+   * Fired when a subscription is created
+   */
+  "customer.subscription.created": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    fastify.log.info({
+      event: "subscription.created",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+      status: subscription.status,
+      planId: subscription.items.data[0]?.price.id,
+    });
+  },
+
+  /**
+   * customer.subscription.updated
+   * Fired when a subscription is updated (plan change, status change, etc.)
+   */
+  "customer.subscription.updated": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    const previousAttributes = event.data.previous_attributes;
+
+    fastify.log.info({
+      event: "subscription.updated",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+      status: subscription.status,
+      changes: previousAttributes,
+    });
+  },
+
+  /**
+   * customer.subscription.deleted
+   * Fired when a subscription is canceled/deleted
+   */
+  "customer.subscription.deleted": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    fastify.log.info({
+      event: "subscription.deleted",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+      canceledAt: subscription.canceled_at,
+      cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    });
+  },
+
+  /**
+   * customer.subscription.trial_will_end
+   * Fired 3 days before trial ends
+   */
+  "customer.subscription.trial_will_end": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    fastify.log.info({
+      event: "subscription.trial_will_end",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+      trialEnd: subscription.trial_end,
+    });
+  },
+
+  /**
+   * customer.subscription.paused
+   * Fired when a subscription is paused
+   */
+  "customer.subscription.paused": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    fastify.log.info({
+      event: "subscription.paused",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+    });
+  },
+
+  /**
+   * customer.subscription.resumed
+   * Fired when a subscription is resumed
+   */
+  "customer.subscription.resumed": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    fastify.log.info({
+      event: "subscription.resumed",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+    });
+  },
+
+  // ========== Invoice Events ==========
+
+  /**
+   * invoice.created
+   * Fired when invoice is created
+   */
+  "invoice.created": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    fastify.log.info({
+      event: "invoice.created",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      amount: invoice.amount_due,
+      status: invoice.status,
+    });
+  },
+
+  /**
+   * invoice.finalized
+   * Fired when invoice is finalized and ready to pay
+   */
+  "invoice.finalized": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    fastify.log.info({
+      event: "invoice.finalized",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      amount: invoice.amount_due,
+    });
+  },
+
+  /**
+   * invoice.paid
+   * Fired when invoice payment succeeds
+   */
+  "invoice.paid": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    fastify.log.info({
+      event: "invoice.paid",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      subscriptionId: invoice.subscription,
+      amount: invoice.amount_paid,
+    });
+  },
+
+  /**
+   * invoice.payment_failed
+   * Fired when invoice payment fails
+   */
+  "invoice.payment_failed": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    fastify.log.warn({
+      event: "invoice.payment_failed",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      subscriptionId: invoice.subscription,
+      amount: invoice.amount_due,
+      attemptCount: invoice.attempt_count,
+    });
+  },
+
+  /**
+   * invoice.upcoming
+   * Fired a few days before invoice is created
+   */
+  "invoice.upcoming": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    fastify.log.info({
+      event: "invoice.upcoming",
+      customerId: invoice.customer,
+      subscriptionId: invoice.subscription,
+      amount: invoice.amount_due,
+      periodEnd: invoice.period_end,
+    });
+  },
+
+  // ========== Payment Events ==========
+
+  /**
+   * payment_intent.succeeded
+   * Fired when payment succeeds
+   */
+  "payment_intent.succeeded": async (event, fastify, stripe) => {
+    const paymentIntent = event.data.object;
+    fastify.log.info({
+      event: "payment_intent.succeeded",
+      paymentIntentId: paymentIntent.id,
+      customerId: paymentIntent.customer,
+      amount: paymentIntent.amount,
+      currency: paymentIntent.currency,
+    });
+  },
+
+  /**
+   * payment_intent.payment_failed
+   * Fired when payment fails
+   */
+  "payment_intent.payment_failed": async (event, fastify, stripe) => {
+    const paymentIntent = event.data.object;
+    fastify.log.warn({
+      event: "payment_intent.payment_failed",
+      paymentIntentId: paymentIntent.id,
+      customerId: paymentIntent.customer,
+      amount: paymentIntent.amount,
+      lastPaymentError: paymentIntent.last_payment_error?.message,
+    });
+  },
+
+  // ========== Customer Events ==========
+
+  /**
+   * customer.created
+   * Fired when customer is created
+   */
+  "customer.created": async (event, fastify, stripe) => {
+    const customer = event.data.object;
+    fastify.log.info({
+      event: "customer.created",
+      customerId: customer.id,
+      email: customer.email,
+    });
+  },
+
+  /**
+   * customer.updated
+   * Fired when customer is updated
+   */
+  "customer.updated": async (event, fastify, stripe) => {
+    const customer = event.data.object;
+    const previousAttributes = event.data.previous_attributes;
+    fastify.log.info({
+      event: "customer.updated",
+      customerId: customer.id,
+      changes: previousAttributes,
+    });
+  },
+
+  /**
+   * customer.deleted
+   * Fired when customer is deleted
+   */
+  "customer.deleted": async (event, fastify, stripe) => {
+    const customer = event.data.object;
+    fastify.log.info({
+      event: "customer.deleted",
+      customerId: customer.id,
+    });
+  },
+
+  // ========== Payment Method Events ==========
+
+  /**
+   * payment_method.attached
+   * Fired when payment method is attached to customer
+   */
+  "payment_method.attached": async (event, fastify, stripe) => {
+    const paymentMethod = event.data.object;
+    fastify.log.info({
+      event: "payment_method.attached",
+      paymentMethodId: paymentMethod.id,
+      customerId: paymentMethod.customer,
+      type: paymentMethod.type,
+    });
+  },
+
+  /**
+   * payment_method.detached
+   * Fired when payment method is detached from customer
+   */
+  "payment_method.detached": async (event, fastify, stripe) => {
+    const paymentMethod = event.data.object;
+    fastify.log.info({
+      event: "payment_method.detached",
+      paymentMethodId: paymentMethod.id,
+      type: paymentMethod.type,
+    });
+  },
+
+  // ========== Checkout Events ==========
+
+  /**
+   * checkout.session.completed
+   * Fired when checkout session is completed
+   */
+  "checkout.session.completed": async (event, fastify, stripe) => {
+    const session = event.data.object;
+    fastify.log.info({
+      event: "checkout.session.completed",
+      sessionId: session.id,
+      customerId: session.customer,
+      subscriptionId: session.subscription,
+      mode: session.mode,
+      paymentStatus: session.payment_status,
+    });
+  },
+
+  /**
+   * checkout.session.expired
+   * Fired when checkout session expires
+   */
+  "checkout.session.expired": async (event, fastify, stripe) => {
+    const session = event.data.object;
+    fastify.log.info({
+      event: "checkout.session.expired",
+      sessionId: session.id,
+    });
+  },
+
+  // ========== Charge Events ==========
+
+  /**
+   * charge.succeeded
+   * Fired when a charge succeeds
+   */
+  "charge.succeeded": async (event, fastify, stripe) => {
+    const charge = event.data.object;
+    fastify.log.info({
+      event: "charge.succeeded",
+      chargeId: charge.id,
+      customerId: charge.customer,
+      amount: charge.amount,
+      currency: charge.currency,
+      paymentMethod: charge.payment_method_details?.type,
+    });
+  },
+
+  /**
+   * charge.failed
+   * Fired when a charge fails
+   */
+  "charge.failed": async (event, fastify, stripe) => {
+    const charge = event.data.object;
+    fastify.log.error({
+      event: "charge.failed",
+      chargeId: charge.id,
+      customerId: charge.customer,
+      amount: charge.amount,
+      failureCode: charge.failure_code,
+      failureMessage: charge.failure_message,
+    });
+  },
+
+  /**
+   * charge.refunded
+   * Fired when a charge is refunded
+   */
+  "charge.refunded": async (event, fastify, stripe) => {
+    const charge = event.data.object;
+    fastify.log.info({
+      event: "charge.refunded",
+      chargeId: charge.id,
+      customerId: charge.customer,
+      amountRefunded: charge.amount_refunded,
+      refundCount: charge.refunds?.data?.length || 0,
+    });
+  },
+};

package/src/handlers/exampleHandlers.js

@@ -0,0 +1,278 @@
+// src/handlers/exampleHandlers.js
+
+/**
+ * Example custom handlers showing how to override default handlers
+ * and implement business logic for subscription events
+ */
+
+export const exampleHandlers = {
+  /**
+   * Handle new subscription - example with database update
+   */
+  "customer.subscription.created": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+
+    // Example: Update user in database
+    // if (fastify.prisma) {
+    //   await fastify.prisma.user.update({
+    //     where: { stripeCustomerId: subscription.customer },
+    //     data: {
+    //       subscriptionId: subscription.id,
+    //       subscriptionStatus: subscription.status,
+    //       planId: subscription.items.data[0]?.price.id,
+    //       subscriptionStartDate: new Date(subscription.current_period_start * 1000),
+    //       subscriptionEndDate: new Date(subscription.current_period_end * 1000),
+    //     },
+    //   });
+    // }
+
+    fastify.log.info({
+      msg: "New subscription created",
+      customerId: subscription.customer,
+      subscriptionId: subscription.id,
+      plan: subscription.items.data[0]?.price.product,
+    });
+  },
+
+  /**
+   * Handle subscription updates - track plan changes, status changes
+   */
+  "customer.subscription.updated": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    const previousAttributes = event.data.previous_attributes || {};
+
+    // Check what changed
+    const statusChanged = "status" in previousAttributes;
+    const planChanged = "items" in previousAttributes;
+
+    if (statusChanged) {
+      fastify.log.info({
+        msg: "Subscription status changed",
+        subscriptionId: subscription.id,
+        oldStatus: previousAttributes.status,
+        newStatus: subscription.status,
+      });
+
+      // Handle specific status changes
+      if (subscription.status === "active" && previousAttributes.status === "trialing") {
+        // Trial converted to paid subscription
+        fastify.log.info("Trial converted to paid subscription");
+      }
+
+      if (subscription.status === "past_due") {
+        // Send email to customer about failed payment
+        fastify.log.warn("Subscription past due - payment failed");
+      }
+    }
+
+    if (planChanged) {
+      fastify.log.info({
+        msg: "Subscription plan changed",
+        subscriptionId: subscription.id,
+      });
+    }
+
+    // Example: Update database
+    // if (fastify.prisma) {
+    //   await fastify.prisma.user.update({
+    //     where: { stripeSubscriptionId: subscription.id },
+    //     data: {
+    //       subscriptionStatus: subscription.status,
+    //       planId: subscription.items.data[0]?.price.id,
+    //       subscriptionEndDate: new Date(subscription.current_period_end * 1000),
+    //     },
+    //   });
+    // }
+  },
+
+  /**
+   * Handle subscription cancellation
+   */
+  "customer.subscription.deleted": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+
+    fastify.log.info({
+      msg: "Subscription canceled",
+      subscriptionId: subscription.id,
+      customerId: subscription.customer,
+      canceledAt: new Date(subscription.canceled_at * 1000),
+    });
+
+    // Example: Update user access
+    // if (fastify.prisma) {
+    //   await fastify.prisma.user.update({
+    //     where: { stripeSubscriptionId: subscription.id },
+    //     data: {
+    //       subscriptionStatus: "canceled",
+    //       subscriptionId: null,
+    //       canceledAt: new Date(),
+    //     },
+    //   });
+    // }
+
+    // Example: Send cancellation email
+    // if (fastify.email) {
+    //   const customer = await stripe.customers.retrieve(subscription.customer);
+    //   await fastify.email.send(
+    //     customer.email,
+    //     "We're sorry to see you go",
+    //     "<p>Your subscription has been canceled.</p>"
+    //   );
+    // }
+  },
+
+  /**
+   * Handle trial ending soon
+   */
+  "customer.subscription.trial_will_end": async (event, fastify, stripe) => {
+    const subscription = event.data.object;
+    const trialEndDate = new Date(subscription.trial_end * 1000);
+
+    fastify.log.info({
+      msg: "Trial ending soon",
+      subscriptionId: subscription.id,
+      trialEnd: trialEndDate,
+    });
+
+    // Example: Send reminder email
+    // const customer = await stripe.customers.retrieve(subscription.customer);
+    // if (fastify.email && customer.email) {
+    //   await fastify.email.send(
+    //     customer.email,
+    //     "Your trial is ending soon",
+    //     `<p>Your trial ends on ${trialEndDate.toLocaleDateString()}</p>`
+    //   );
+    // }
+  },
+
+  /**
+   * Handle successful payment
+   */
+  "invoice.paid": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+
+    fastify.log.info({
+      msg: "Invoice paid successfully",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      amount: invoice.amount_paid / 100, // Convert from cents
+      currency: invoice.currency,
+    });
+
+    // Reset failed payment count
+    // if (fastify.prisma && invoice.subscription) {
+    //   await fastify.prisma.user.update({
+    //     where: { stripeSubscriptionId: invoice.subscription },
+    //     data: {
+    //       failedPaymentCount: 0,
+    //       lastPaymentDate: new Date(),
+    //     },
+    //   });
+    // }
+
+    // Send receipt email
+    // const customer = await stripe.customers.retrieve(invoice.customer);
+    // if (fastify.email && customer.email) {
+    //   await fastify.email.send(
+    //     customer.email,
+    //     "Payment Receipt",
+    //     `<p>Thank you for your payment of $${invoice.amount_paid / 100}</p>`
+    //   );
+    // }
+  },
+
+  /**
+   * Handle failed payment
+   */
+  "invoice.payment_failed": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+
+    fastify.log.error({
+      msg: "Invoice payment failed",
+      invoiceId: invoice.id,
+      customerId: invoice.customer,
+      attemptCount: invoice.attempt_count,
+      nextPaymentAttempt: invoice.next_payment_attempt,
+    });
+
+    // Track failed payments
+    // if (fastify.prisma && invoice.subscription) {
+    //   await fastify.prisma.user.update({
+    //     where: { stripeSubscriptionId: invoice.subscription },
+    //     data: {
+    //       failedPaymentCount: { increment: 1 },
+    //       lastFailedPaymentDate: new Date(),
+    //     },
+    //   });
+    // }
+
+    // Send payment failure email
+    // const customer = await stripe.customers.retrieve(invoice.customer);
+    // if (fastify.email && customer.email) {
+    //   await fastify.email.send(
+    //     customer.email,
+    //     "Payment Failed",
+    //     "<p>Your payment failed. Please update your payment method.</p>"
+    //   );
+    // }
+  },
+
+  /**
+   * Handle upcoming invoice (send reminder)
+   */
+  "invoice.upcoming": async (event, fastify, stripe) => {
+    const invoice = event.data.object;
+    const billingDate = new Date(invoice.period_end * 1000);
+
+    fastify.log.info({
+      msg: "Upcoming invoice",
+      customerId: invoice.customer,
+      amount: invoice.amount_due / 100,
+      billingDate,
+    });
+
+    // Send upcoming charge notification
+    // const customer = await stripe.customers.retrieve(invoice.customer);
+    // if (fastify.email && customer.email) {
+    //   await fastify.email.send(
+    //     customer.email,
+    //     "Upcoming Charge Notification",
+    //     `<p>Your card will be charged $${invoice.amount_due / 100} on ${billingDate.toLocaleDateString()}</p>`
+    //   );
+    // }
+  },
+
+  /**
+   * Handle completed checkout session
+   */
+  "checkout.session.completed": async (event, fastify, stripe) => {
+    const session = event.data.object;
+
+    if (session.mode === "subscription") {
+      fastify.log.info({
+        msg: "Checkout completed - subscription",
+        sessionId: session.id,
+        customerId: session.customer,
+        subscriptionId: session.subscription,
+      });
+
+      // Provision access to user
+      // if (fastify.prisma) {
+      //   await fastify.prisma.user.update({
+      //     where: { stripeCustomerId: session.customer },
+      //     data: {
+      //       subscriptionId: session.subscription,
+      //       onboardingComplete: true,
+      //     },
+      //   });
+      // }
+    } else if (session.mode === "payment") {
+      fastify.log.info({
+        msg: "Checkout completed - one-time payment",
+        sessionId: session.id,
+        customerId: session.customer,
+        paymentIntentId: session.payment_intent,
+      });
+    }
+  },
+};

package/src/handlers/index.js

@@ -0,0 +1,8 @@
+// src/handlers/index.js
+
+/**
+ * Export all handlers for easy importing
+ */
+
+export { defaultHandlers } from './defaultHandlers.js';
+export { exampleHandlers } from './exampleHandlers.js';

package/src/index.js

@@ -0,0 +1,10 @@
+// src/index.js
+
+/**
+ * Main exports for xStripe plugin
+ */
+
+export { default } from './xStripe.js';
+export { default as xStripe } from './xStripe.js';
+export * from './handlers/index.js';
+export * as helpers from './utils/helpers.js';