@xenterprises/fastify-xstripe 1.1.0 → 1.2.0

package/TESTING.md

@@ -1,357 +0,0 @@
-# Testing Guide for xStripe
-
-This guide shows how to test your Stripe webhook handlers locally and in production.
-
-## Local Testing with Stripe CLI
-
-### 1. Install Stripe CLI
-
-**macOS:**
-```bash
-brew install stripe/stripe-cli/stripe
-```
-
-**Other platforms:**
-Download from https://stripe.com/docs/stripe-cli
-
-### 2. Login to Stripe
-
-```bash
-stripe login
-```
-
-This will open your browser for authentication.
-
-### 3. Forward Webhooks to Local Server
-
-Start your local server first:
-```bash
-npm run dev
-```
-
-Then forward webhooks:
-```bash
-stripe listen --forward-to localhost:3000/stripe/webhook
-```
-
-This will output a webhook signing secret. Copy it to your `.env` file:
-```
-STRIPE_WEBHOOK_SECRET=whsec_...
-```
-
-### 4. Trigger Test Events
-
-In a new terminal, trigger specific events:
-
-```bash
-# Test subscription creation
-stripe trigger customer.subscription.created
-
-# Test payment failure
-stripe trigger invoice.payment_failed
-
-# Test subscription cancellation
-stripe trigger customer.subscription.deleted
-
-# Test trial ending
-stripe trigger customer.subscription.trial_will_end
-```
-
-## Testing Specific Scenarios
-
-### Subscription Lifecycle
-
-```bash
-# 1. Create subscription
-stripe trigger customer.subscription.created
-
-# 2. Update subscription (plan change)
-stripe trigger customer.subscription.updated
-
-# 3. Trial ending soon
-stripe trigger customer.subscription.trial_will_end
-
-# 4. Cancel subscription
-stripe trigger customer.subscription.deleted
-```
-
-### Payment Scenarios
-
-```bash
-# Successful payment
-stripe trigger invoice.paid
-
-# Failed payment
-stripe trigger invoice.payment_failed
-
-# Upcoming payment reminder
-stripe trigger invoice.upcoming
-```
-
-### Customer Events
-
-```bash
-# New customer
-stripe trigger customer.created
-
-# Customer updated
-stripe trigger customer.updated
-
-# Payment method attached
-stripe trigger payment_method.attached
-```
-
-## Testing Handlers Directly
-
-Since handlers are pure functions, you can test them in isolation:
-
-### Example Test File
-
-```javascript
-// test/handlers.test.js
-import { test } from 'node:test';
-import assert from 'node:assert';
-
-test('subscription created handler updates database', async () => {
-  const mockEvent = {
-    type: 'customer.subscription.created',
-    data: {
-      object: {
-        id: 'sub_123',
-        customer: 'cus_123',
-        status: 'active',
-        items: {
-          data: [{
-            price: {
-              id: 'price_123',
-              product: 'prod_123',
-            },
-          }],
-        },
-      },
-    },
-  };
-
-  let updatedUser = null;
-
-  const mockFastify = {
-    log: {
-      info: () => {},
-      error: () => {},
-      warn: () => {},
-    },
-    prisma: {
-      user: {
-        update: async (data) => {
-          updatedUser = data;
-          return { id: 1 };
-        },
-      },
-    },
-  };
-
-  const mockStripe = {};
-
-  // Import your handler
-  const handler = customHandlers['customer.subscription.created'];
-  await handler(mockEvent, mockFastify, mockStripe);
-
-  // Assert database was updated
-  assert.equal(updatedUser.where.stripeCustomerId, 'cus_123');
-  assert.equal(updatedUser.data.subscriptionId, 'sub_123');
-});
-
-test('payment failure handler sends notification', async () => {
-  const mockEvent = {
-    type: 'invoice.payment_failed',
-    data: {
-      object: {
-        id: 'in_123',
-        customer: 'cus_123',
-        subscription: 'sub_123',
-        attempt_count: 2,
-        amount_due: 2000,
-      },
-    },
-  };
-
-  let emailSent = false;
-
-  const mockFastify = {
-    log: {
-      info: () => {},
-      error: () => {},
-      warn: () => {},
-    },
-    email: {
-      send: async (to, subject, body) => {
-        emailSent = true;
-        assert.equal(subject, 'Payment Failed');
-        return { success: true };
-      },
-    },
-  };
-
-  const mockStripe = {
-    customers: {
-      retrieve: async (id) => ({
-        id,
-        email: 'test@example.com',
-      }),
-    },
-  };
-
-  const handler = customHandlers['invoice.payment_failed'];
-  await handler(mockEvent, mockFastify, mockStripe);
-
-  assert.equal(emailSent, true);
-});
-```
-
-Run tests:
-```bash
-node --test test/**/*.test.js
-```
-
-## Manual Testing with cURL
-
-You can also send webhook events manually (useful for CI/CD):
-
-```bash
-# Get a test event from Stripe
-stripe events list --limit 1
-
-# Send it to your local server
-curl -X POST http://localhost:3000/stripe/webhook \
-  -H "Content-Type: application/json" \
-  -H "Stripe-Signature: YOUR_SIGNATURE" \
-  -d @test-event.json
-```
-
-## Testing in Production
-
-### 1. Configure Webhook Endpoint
-
-In your Stripe Dashboard:
-1. Go to Developers → Webhooks
-2. Click "Add endpoint"
-3. Enter your production URL: `https://yourdomain.com/stripe/webhook`
-4. Select events to listen for (or select "Select all events")
-5. Copy the signing secret to your production environment
-
-### 2. Monitor Webhook Deliveries
-
-In Stripe Dashboard:
-- View webhook delivery attempts
-- See request/response details
-- Retry failed deliveries
-
-### 3. Set Up Alerts
-
-Monitor for:
-- Failed webhook deliveries
-- Handler errors in your logs
-- Unusual event patterns
-
-## Common Test Scenarios
-
-### Test New Subscriber Flow
-
-1. Create customer
-2. Create checkout session
-3. Complete checkout (use test card `4242 4242 4242 4242`)
-4. Verify `customer.subscription.created` handler runs
-5. Verify `invoice.paid` handler runs
-6. Check database for new subscription
-
-### Test Failed Payment Flow
-
-1. Update payment method to failing card (`4000 0000 0000 0341`)
-2. Wait for billing date or trigger manually
-3. Verify `invoice.payment_failed` handler runs
-4. Check email notifications sent
-5. Verify retry logic
-
-### Test Subscription Cancellation
-
-1. Cancel subscription via API
-2. Verify `customer.subscription.updated` handler runs
-3. If `cancel_at_period_end=false`, verify `customer.subscription.deleted` runs
-4. Check access revoked in database
-
-## Debugging Tips
-
-### Enable Verbose Logging
-
-```javascript
-const fastify = Fastify({
-  logger: {
-    level: 'debug',
-    transport: {
-      target: 'pino-pretty',
-    },
-  },
-});
-```
-
-### Log All Webhook Events
-
-Add this to see raw events:
-
-```javascript
-handlers: {
-  '*': async (event, fastify, stripe) => {
-    fastify.log.debug({
-      event: event.type,
-      data: event.data.object,
-    });
-  },
-}
-```
-
-### Check Webhook Signatures
-
-If signatures fail:
-1. Verify webhook secret matches Stripe Dashboard
-2. Check raw body is being used (not parsed JSON)
-3. Verify headers are forwarded correctly (if using proxy)
-
-### Test Mode vs Live Mode
-
-- Use `sk_test_` keys for development
-- Use `sk_live_` keys for production
-- Test and live webhooks are separate endpoints
-- Events don't cross between modes
-
-## Best Practices
-
-1. **Test all critical paths** - Subscription creation, payment failures, cancellations
-2. **Use idempotency** - Handlers should be safe to run multiple times
-3. **Log everything** - You can't debug what you can't see
-4. **Monitor production** - Set up alerts for failed handlers
-5. **Test error cases** - What happens if database is down?
-6. **Verify async operations** - Do emails actually send?
-7. **Check edge cases** - What if customer has no email?
-
-## Troubleshooting
-
-### Webhooks Not Received
-
-- Check webhook endpoint is accessible publicly
-- Verify webhook secret is correct
-- Check firewall/security group allows Stripe IPs
-- Review Stripe Dashboard for delivery attempts
-
-### Handler Errors
-
-- Check logs for error messages
-- Verify database connections
-- Test handler functions in isolation
-- Ensure all required services are available
-
-### Signature Verification Fails
-
-- Verify using raw body, not parsed JSON
-- Check webhook secret matches exactly
-- Ensure no middleware modifies the body
-- Verify Content-Type header is correct