@xenterprises/fastify-xstripe 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Tim Mushen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,374 @@
+# Migration Guide
+
+How to migrate from raw Stripe webhook handling to xStripe.
+
+## Before: Raw Webhook Handling
+
+### Typical raw implementation:
+
+```javascript
+// Before - Manual webhook handling
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env.STRIPE_API_KEY);
+
+fastify.post('/webhook', async (request, reply) => {
+  const sig = request.headers['stripe-signature'];
+  let event;
+
+  try {
+    event = stripe.webhooks.constructEvent(
+      request.rawBody,
+      sig,
+      process.env.STRIPE_WEBHOOK_SECRET
+    );
+  } catch (err) {
+    return reply.code(400).send(`Webhook Error: ${err.message}`);
+  }
+
+  // Handle the event
+  switch (event.type) {
+    case 'customer.subscription.created':
+      const subscription = event.data.object;
+
+      try {
+        await prisma.user.update({
+          where: { stripeCustomerId: subscription.customer },
+          data: {
+            subscriptionId: subscription.id,
+            subscriptionStatus: subscription.status,
+            planId: subscription.items.data[0]?.price.id,
+          },
+        });
+
+        console.log('Subscription created:', subscription.id);
+      } catch (error) {
+        console.error('Error processing subscription:', error);
+      }
+      break;
+
+    case 'invoice.payment_failed':
+      const invoice = event.data.object;
+
+      try {
+        const customer = await stripe.customers.retrieve(invoice.customer);
+
+        await sendEmail(
+          customer.email,
+          'Payment Failed',
+          'Please update your payment method'
+        );
+
+        await prisma.user.update({
+          where: { stripeCustomerId: invoice.customer },
+          data: { failedPaymentCount: { increment: 1 } },
+        });
+
+        console.log('Payment failed for:', invoice.customer);
+      } catch (error) {
+        console.error('Error handling payment failure:', error);
+      }
+      break;
+
+    case 'customer.subscription.deleted':
+      const deletedSub = event.data.object;
+
+      try {
+        await prisma.user.update({
+          where: { stripeSubscriptionId: deletedSub.id },
+          data: {
+            subscriptionStatus: 'canceled',
+            hasAccess: false,
+          },
+        });
+
+        console.log('Subscription canceled:', deletedSub.id);
+      } catch (error) {
+        console.error('Error canceling subscription:', error);
+      }
+      break;
+
+    // ... 20+ more event types
+    default:
+      console.log(`Unhandled event type: ${event.type}`);
+  }
+
+  reply.send({ received: true });
+});
+```
+
+### Problems with this approach:
+
+1. ❌ **Hundreds of lines in one file** - Hard to read and maintain
+2. ❌ **Difficult to test** - Everything coupled together
+3. ❌ **Error handling scattered** - Try/catch everywhere
+4. ❌ **No separation of concerns** - Business logic mixed with webhook handling
+5. ❌ **Hard to debug** - Console.log statements everywhere
+6. ❌ **Not reusable** - Can't share handler logic
+
+## After: xStripe
+
+### Same functionality with xStripe:
+
+```javascript
+// After - Clean, testable handlers
+import xStripe from '@xenterprises/fastify-xstripe';
+
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  handlers: {
+    'customer.subscription.created': async (event, fastify, stripe) => {
+      const subscription = event.data.object;
+
+      await fastify.prisma.user.update({
+        where: { stripeCustomerId: subscription.customer },
+        data: {
+          subscriptionId: subscription.id,
+          subscriptionStatus: subscription.status,
+          planId: subscription.items.data[0]?.price.id,
+        },
+      });
+
+      fastify.log.info('Subscription created:', subscription.id);
+    },
+
+    'invoice.payment_failed': async (event, fastify, stripe) => {
+      const invoice = event.data.object;
+      const customer = await stripe.customers.retrieve(invoice.customer);
+
+      await fastify.email.send(
+        customer.email,
+        'Payment Failed',
+        'Please update your payment method'
+      );
+
+      await fastify.prisma.user.update({
+        where: { stripeCustomerId: invoice.customer },
+        data: { failedPaymentCount: { increment: 1 } },
+      });
+
+      fastify.log.info('Payment failed for:', invoice.customer);
+    },
+
+    'customer.subscription.deleted': async (event, fastify, stripe) => {
+      const subscription = event.data.object;
+
+      await fastify.prisma.user.update({
+        where: { stripeSubscriptionId: subscription.id },
+        data: {
+          subscriptionStatus: 'canceled',
+          hasAccess: false,
+        },
+      });
+
+      fastify.log.info('Subscription canceled:', subscription.id);
+    },
+  },
+});
+```
+
+### Benefits:
+
+1. ✅ **Clean, readable code** - Each handler is self-contained
+2. ✅ **Easy to test** - Pure functions with clear inputs/outputs
+3. ✅ **Error handling built-in** - Automatic error catching and logging
+4. ✅ **Separation of concerns** - Business logic separate from webhook mechanics
+5. ✅ **Better debugging** - Structured logging with Fastify
+6. ✅ **Reusable** - Can extract handlers to separate files
+
+## Step-by-Step Migration
+
+### Step 1: Install xStripe
+
+```bash
+npm install @xenterprises/fastify-xstripe
+```
+
+### Step 2: Extract Your Handlers
+
+Create a file for your handlers:
+
+```javascript
+// handlers/stripeHandlers.js
+export const stripeHandlers = {
+  'customer.subscription.created': async (event, fastify, stripe) => {
+    // Copy your logic from the switch case
+  },
+
+  'invoice.payment_failed': async (event, fastify, stripe) => {
+    // Copy your logic from the switch case
+  },
+
+  // ... other handlers
+};
+```
+
+### Step 3: Register xStripe
+
+```javascript
+import xStripe from '@xenterprises/fastify-xstripe';
+import { stripeHandlers } from './handlers/stripeHandlers.js';
+
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  handlers: stripeHandlers,
+});
+```
+
+### Step 4: Remove Old Webhook Route
+
+Delete your old `/webhook` endpoint - xStripe handles this now.
+
+### Step 5: Update Stripe Dashboard
+
+Update your webhook endpoint URL if it changed:
+- Old: `https://yourdomain.com/webhook`
+- New: `https://yourdomain.com/stripe/webhook` (or custom path)
+
+### Step 6: Test
+
+```bash
+# Test with Stripe CLI
+stripe listen --forward-to localhost:3000/stripe/webhook
+stripe trigger customer.subscription.created
+```
+
+## Migration Checklist
+
+- [ ] Install xStripe package
+- [ ] Create handlers file
+- [ ] Move business logic to handlers
+- [ ] Register xStripe plugin
+- [ ] Remove old webhook endpoint
+- [ ] Update Stripe webhook URL
+- [ ] Test all event types
+- [ ] Update environment variables
+- [ ] Deploy to production
+- [ ] Monitor webhook deliveries
+
+## Common Migration Issues
+
+### Issue: Signature Verification Fails
+
+**Before:**
+```javascript
+const event = stripe.webhooks.constructEvent(request.rawBody, sig, secret);
+```
+
+**After:**
+xStripe handles this automatically. Make sure:
+1. `webhookSecret` is set correctly
+2. Fastify has `rawBody: true` option
+
+### Issue: Can't Access Database
+
+**Before:**
+```javascript
+const prisma = new PrismaClient();
+await prisma.user.update(...);
+```
+
+**After:**
+Use Fastify decorator:
+```javascript
+await fastify.prisma.user.update(...);
+```
+
+### Issue: Custom Logging
+
+**Before:**
+```javascript
+console.log('Subscription created');
+```
+
+**After:**
+Use Fastify logger:
+```javascript
+fastify.log.info('Subscription created');
+```
+
+### Issue: Accessing Stripe Client
+
+**Before:**
+```javascript
+const stripe = new Stripe(apiKey);
+const customer = await stripe.customers.retrieve(id);
+```
+
+**After:**
+Stripe client is passed to handler:
+```javascript
+'my.event': async (event, fastify, stripe) => {
+  const customer = await stripe.customers.retrieve(id);
+}
+```
+
+## Gradual Migration
+
+You can migrate gradually by handling some events with xStripe and others with your old code:
+
+```javascript
+// Keep old endpoint for some events
+fastify.post('/old-webhook', oldWebhookHandler);
+
+// Use xStripe for new events
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  webhookPath: '/new-webhook',
+  handlers: {
+    'customer.subscription.created': newHandler,
+  },
+});
+```
+
+Then gradually move handlers over and update Stripe webhook configuration.
+
+## Testing After Migration
+
+1. **Test locally with Stripe CLI**
+   ```bash
+   stripe listen --forward-to localhost:3000/stripe/webhook
+   ```
+
+2. **Trigger test events**
+   ```bash
+   stripe trigger customer.subscription.created
+   stripe trigger invoice.payment_failed
+   ```
+
+3. **Check logs**
+   ```bash
+   # Should see structured logs from Fastify
+   {"level":30,"msg":"Received Stripe webhook: customer.subscription.created"}
+   {"level":30,"msg":"Successfully processed customer.subscription.created"}
+   ```
+
+4. **Verify database changes**
+   - Check that database updates happen correctly
+   - Verify emails are sent
+   - Confirm business logic runs
+
+## Rollback Plan
+
+If issues arise, you can quickly rollback:
+
+1. Keep old webhook handler in a separate file
+2. Comment out xStripe registration
+3. Re-enable old endpoint
+4. Update Stripe webhook URL back
+
+```javascript
+// Rollback: Re-enable old handler
+// await fastify.register(xStripe, { ... });
+fastify.post('/webhook', oldWebhookHandler);
+```
+
+## Need Help?
+
+- Check the [README](./README.md) for full documentation
+- See [TESTING.md](./TESTING.md) for testing guide
+- Review example handlers in `src/handlers/exampleHandlers.js`
+- Open an issue on GitHub

package/QUICK_START.md

@@ -0,0 +1,179 @@
+# Quick Start Guide
+
+Get up and running with xStripe in 5 minutes.
+
+## 1. Install
+
+```bash
+npm install @xenterprises/fastify-xstripe stripe
+```
+
+## 2. Setup
+
+```javascript
+import Fastify from 'fastify';
+import xStripe from '@xenterprises/fastify-xstripe';
+
+const fastify = Fastify({
+  logger: true,
+  rawBody: true, // Important for webhook signature verification
+});
+
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+## 3. Environment Variables
+
+Create `.env`:
+
+```bash
+STRIPE_API_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+PORT=3000
+```
+
+## 4. Add Custom Handlers
+
+```javascript
+await fastify.register(xStripe, {
+  apiKey: process.env.STRIPE_API_KEY,
+  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+  handlers: {
+    // New subscription
+    'customer.subscription.created': async (event, fastify, stripe) => {
+      const sub = event.data.object;
+      console.log(`New subscriber: ${sub.customer}`);
+
+      // Your business logic here
+      // await fastify.prisma.user.update(...)
+      // await fastify.email.send(...)
+    },
+
+    // Payment failed
+    'invoice.payment_failed': async (event, fastify, stripe) => {
+      const invoice = event.data.object;
+      console.log(`Payment failed: ${invoice.customer}`);
+
+      // Send notification
+      // await fastify.email.send(...)
+    },
+  },
+});
+```
+
+## 5. Test Locally
+
+Install Stripe CLI:
+```bash
+brew install stripe/stripe-cli/stripe
+```
+
+Forward webhooks:
+```bash
+stripe listen --forward-to localhost:3000/stripe/webhook
+```
+
+Trigger test events:
+```bash
+stripe trigger customer.subscription.created
+stripe trigger invoice.payment_failed
+```
+
+## 6. Deploy
+
+1. Deploy your app
+2. Add webhook endpoint in Stripe Dashboard:
+   - URL: `https://yourdomain.com/stripe/webhook`
+   - Events: Select events you handle
+3. Copy webhook signing secret to production env
+
+## Common Use Cases
+
+### Update Database on New Subscription
+
+```javascript
+'customer.subscription.created': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+
+  await fastify.prisma.user.update({
+    where: { stripeCustomerId: subscription.customer },
+    data: {
+      subscriptionId: subscription.id,
+      subscriptionStatus: subscription.status,
+      planId: subscription.items.data[0]?.price.id,
+    },
+  });
+}
+```
+
+### Send Email on Payment Failure
+
+```javascript
+'invoice.payment_failed': async (event, fastify, stripe) => {
+  const invoice = event.data.object;
+  const customer = await stripe.customers.retrieve(invoice.customer);
+
+  await fastify.email.send(
+    customer.email,
+    'Payment Failed',
+    'Please update your payment method'
+  );
+}
+```
+
+### Revoke Access on Cancellation
+
+```javascript
+'customer.subscription.deleted': async (event, fastify, stripe) => {
+  const subscription = event.data.object;
+
+  await fastify.prisma.user.update({
+    where: { stripeSubscriptionId: subscription.id },
+    data: {
+      hasAccess: false,
+      subscriptionStatus: 'canceled',
+    },
+  });
+}
+```
+
+## Handler Function Signature
+
+```javascript
+async function handler(event, fastify, stripe) {
+  // event - Stripe webhook event
+  // fastify - Fastify instance (access decorators)
+  // stripe - Stripe client
+}
+```
+
+## Supported Events
+
+- **Subscriptions**: created, updated, deleted, paused, resumed, trial_will_end
+- **Invoices**: created, finalized, paid, payment_failed, upcoming
+- **Payments**: payment_intent.succeeded, payment_intent.payment_failed
+- **Customers**: created, updated, deleted
+- **Payment Methods**: attached, detached
+- **Checkout**: session.completed, session.expired
+
+See [README.md](./README.md) for full list.
+
+## Next Steps
+
+- [Full Documentation](./README.md)
+- [Testing Guide](./TESTING.md)
+- [Migration Guide](./MIGRATION.md)
+- [Example Handlers](./src/handlers/exampleHandlers.js)
+
+## Tips
+
+1. **Use structured logging**: `fastify.log.info()` instead of `console.log()`
+2. **Make handlers idempotent**: Safe to run multiple times
+3. **Return 200 quickly**: Do heavy work async
+4. **Test locally first**: Use Stripe CLI before deploying
+5. **Monitor webhooks**: Check Stripe Dashboard for failures