@xenterprises/fastify-xstripe 1.0.0

package/TESTING.md

@@ -0,0 +1,357 @@
+# 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

package/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * xStripe - Fastify Plugin for Stripe Webhook Handling
+ * TypeScript Type Definitions
+ *
+ * @module @xenterprises/fastify-xstripe
+ * @version 1.0.0
+ */
+
+import { FastifyPluginAsync, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import Stripe from 'stripe';
+
+/**
+ * Stripe Webhook Event (from Stripe SDK)
+ */
+export type StripeWebhookEvent = Stripe.Event;
+
+/**
+ * Webhook Event Handler Function
+ */
+export type WebhookEventHandler = (
+  event: StripeWebhookEvent,
+  fastify: FastifyInstance,
+  stripe: Stripe
+) => Promise<void>;
+
+/**
+ * Default Event Handlers Map
+ */
+export interface DefaultHandlers {
+  // Subscription Events
+  'customer.subscription.created': WebhookEventHandler;
+  'customer.subscription.updated': WebhookEventHandler;
+  'customer.subscription.deleted': WebhookEventHandler;
+  'customer.subscription.paused': WebhookEventHandler;
+  'customer.subscription.resumed': WebhookEventHandler;
+  'customer.subscription.trial_will_end': WebhookEventHandler;
+
+  // Invoice Events
+  'invoice.created': WebhookEventHandler;
+  'invoice.finalized': WebhookEventHandler;
+  'invoice.paid': WebhookEventHandler;
+  'invoice.payment_failed': WebhookEventHandler;
+  'invoice.upcoming': WebhookEventHandler;
+
+  // Payment Intent Events
+  'payment_intent.succeeded': WebhookEventHandler;
+  'payment_intent.payment_failed': WebhookEventHandler;
+
+  // Customer Events
+  'customer.created': WebhookEventHandler;
+  'customer.updated': WebhookEventHandler;
+  'customer.deleted': WebhookEventHandler;
+
+  // Payment Method Events
+  'payment_method.attached': WebhookEventHandler;
+  'payment_method.detached': WebhookEventHandler;
+
+  // Charge Events
+  'charge.succeeded': WebhookEventHandler;
+  'charge.failed': WebhookEventHandler;
+  'charge.refunded': WebhookEventHandler;
+
+  // Checkout Events
+  'checkout.session.completed': WebhookEventHandler;
+  'checkout.session.expired': WebhookEventHandler;
+
+  // Allow any other event type
+  [eventType: string]: WebhookEventHandler;
+}
+
+/**
+ * Plugin Configuration Options
+ */
+export interface XStripePluginOptions {
+  /** Stripe API Key (Secret Key) */
+  apiKey?: string;
+
+  /** Stripe Webhook Signing Secret */
+  webhookSecret?: string;
+
+  /** Webhook endpoint path */
+  webhookPath?: string;
+
+  /** Custom event handlers (override defaults) */
+  handlers?: Partial<DefaultHandlers>;
+
+  /** Whether to fail on handler errors */
+  failOnError?: boolean;
+
+  /** Request timeout in milliseconds */
+  requestTimeout?: number;
+
+  /** Enable event logging */
+  logEvents?: boolean;
+}
+
+/**
+ * Helper Functions
+ */
+export namespace helpers {
+  /**
+   * Format amount as currency string
+   * @param amount Amount in cents
+   * @param currency Currency code (USD, EUR, etc.)
+   * @returns Formatted currency string (e.g., "$20.00")
+   */
+  function formatAmount(amount: number, currency: string): string;
+
+  /**
+   * Get plan name from subscription
+   * @param subscription Subscription object
+   * @returns Plan name or product name
+   */
+  function getPlanName(subscription: Stripe.Subscription): string;
+
+  /**
+   * Check if subscription is active
+   * @param subscription Subscription object
+   * @returns True if subscription is active
+   */
+  function isActiveSubscription(subscription: Stripe.Subscription): boolean;
+
+  /**
+   * Get customer email from various objects
+   * @param obj Stripe object with customer reference
+   * @param stripe Stripe client instance
+   * @returns Customer email
+   */
+  function getCustomerEmail(obj: any, stripe: Stripe): Promise<string>;
+
+  /**
+   * Create idempotent request ID from event
+   * @param event Stripe webhook event
+   * @returns Idempotency key
+   */
+  function createIdempotencyKey(event: StripeWebhookEvent): string;
+}
+
+/**
+ * xStripe Service Methods (available on fastify.xStripe)
+ */
+export interface XStripeService {
+  /**
+   * Register custom event handler
+   * @param eventType Stripe event type
+   * @param handler Event handler function
+   */
+  onEvent(eventType: string, handler: WebhookEventHandler): void;
+
+  /**
+   * Get registered handler for event type
+   * @param eventType Stripe event type
+   * @returns Handler function or undefined
+   */
+  getHandler(eventType: string): WebhookEventHandler | undefined;
+
+  /**
+   * Execute event handler
+   * @param event Stripe webhook event
+   * @returns Promise that resolves when handler completes
+   */
+  executeHandler(event: StripeWebhookEvent): Promise<void>;
+}
+
+/**
+ * Fastify Instance with xStripe Decoration
+ */
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** xStripe service methods */
+    xStripe: XStripeService;
+
+    /** Stripe client instance */
+    stripe: Stripe;
+  }
+}
+
+/**
+ * Webhook Request with Stripe Event
+ */
+export interface WebhookRequest extends FastifyRequest {
+  body: {
+    /** Stripe event object */
+    id: string;
+    type: string;
+    data: any;
+    [key: string]: any;
+  };
+}
+
+/**
+ * Webhook Response
+ */
+export interface WebhookResponse {
+  /** Status message */
+  status: 'success' | 'error';
+
+  /** Event ID that was processed */
+  eventId: string;
+
+  /** Event type that was processed */
+  eventType: string;
+
+  /** Optional error message */
+  error?: string;
+
+  /** Timestamp of processing */
+  processedAt: string;
+}
+
+/**
+ * API Response Types
+ */
+export interface Plan {
+  productId: string;
+  name: string;
+  description?: string;
+  images?: string[];
+  prices: PriceInfo[];
+  metadata?: Record<string, any>;
+}
+
+export interface PriceInfo {
+  priceId: string;
+  amount: number;
+  currency: string;
+  interval?: string;
+  intervalCount?: number;
+  trialPeriodDays?: number;
+  nickname?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface PaymentMethod {
+  id: string;
+  type: string;
+  isDefault: boolean;
+  card?: {
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+  };
+  billingDetails?: Record<string, any>;
+  createdAt: Date;
+}
+
+export interface SubscriptionInfo {
+  id: string;
+  status: string;
+  planId?: string;
+  planName?: string;
+  amount?: number;
+  currency?: string;
+  interval?: string;
+  createdAt: Date;
+  currentPeriodEnd: Date;
+  cancelAtPeriodEnd: boolean;
+  canceledAt?: Date;
+}
+
+/**
+ * xStripe Plugin
+ * Registers Stripe webhook handling and provides convenient API endpoints
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import xStripe from '@xenterprises/fastify-xstripe';
+ *
+ * const fastify = Fastify();
+ *
+ * await fastify.register(xStripe, {
+ *   apiKey: process.env.STRIPE_API_KEY,
+ *   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+ *   webhookPath: '/webhooks/stripe'
+ * });
+ *
+ * // Register custom handler
+ * fastify.xStripe.onEvent('customer.subscription.created', async (event, fastify, stripe) => {
+ *   const subscription = event.data.object;
+ *   console.log('New subscription:', subscription.id);
+ * });
+ *
+ * // Webhook route automatically registered at webhookPath
+ * // POST /webhooks/stripe
+ *
+ * // Use included API endpoints
+ * // GET  /plans
+ * // GET  /plans/:productId
+ * // POST /create-checkout-session
+ * // POST /create-payment-session
+ * // GET  /customer/:customerId/subscriptions
+ * // POST /subscription/:id/update
+ * // GET  /customer/:customerId/payment-methods
+ * // POST /customer/:customerId/payment-methods
+ * // POST /customer/:customerId/payment-methods/:paymentMethodId/default
+ * // DELETE /customer/:customerId/payment-methods/:paymentMethodId
+ * ```
+ */
+declare const xStripe: FastifyPluginAsync<XStripePluginOptions>;
+
+export default xStripe;
+
+/**
+ * Re-export Stripe types for convenience
+ */
+export { Stripe };
+export type { StripeWebhookEvent as WebhookEvent };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@xenterprises/fastify-xstripe",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for Stripe webhooks with simplified, testable handlers for subscription events.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./handlers": "./src/handlers/index.js",
+    "./helpers": "./src/utils/helpers.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/handlers.test.js"
+  },
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-xstripe"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-xstripe/-/issues"
+  },
+  "homepage": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-xstripe#readme",
+  "keywords": [
+    "fastify",
+    "stripe",
+    "webhooks",
+    "subscription",
+    "billing",
+    "payments",
+    "plugin"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0",
+    "fastify-plugin": "^5.0.0",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "fastify-plugin": "^5.0.0",
+    "stripe": "^16.12.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}