@xenterprises/fastify-xstripe 1.1.0 → 1.2.0

package/index.d.ts

@@ -3,10 +3,10 @@
  * TypeScript Type Definitions
  *
  * @module @xenterprises/fastify-xstripe
- * @version 1.0.0
+ * @version 1.2.0
  */
 
-import { FastifyPluginAsync, FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { FastifyPluginAsync, FastifyInstance } from 'fastify';
 import Stripe from 'stripe';
 
 /**
@@ -16,6 +16,10 @@ export type StripeWebhookEvent = Stripe.Event;
 
 /**
  * Webhook Event Handler Function
+ *
+ * @param event - The Stripe webhook event object
+ * @param fastify - The Fastify instance (access to decorators)
+ * @param stripe - The Stripe client instance
  */
 export type WebhookEventHandler = (
   event: StripeWebhookEvent,
@@ -72,94 +76,20 @@ export interface DefaultHandlers {
  * Plugin Configuration Options
  */
 export interface XStripePluginOptions {
-  /** Stripe API Key (Secret Key) */
-  apiKey?: string;
+  /** Stripe API Key (Secret Key). Required. */
+  apiKey: string;
 
-  /** Stripe Webhook Signing Secret */
-  webhookSecret?: string;
+  /** Stripe Webhook Signing Secret. Required. */
+  webhookSecret: string;
 
-  /** Webhook endpoint path */
+  /** Webhook endpoint path. Defaults to "/stripe/webhook". */
   webhookPath?: string;
 
-  /** Custom event handlers (override defaults) */
+  /** 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>;
+  /** Stripe API version. Defaults to "2024-11-20.acacia". */
+  apiVersion?: string;
 }
 
 /**
@@ -167,101 +97,77 @@ export interface XStripeService {
  */
 declare module 'fastify' {
   interface FastifyInstance {
-    /** xStripe service methods */
-    xStripe: XStripeService;
-
     /** Stripe client instance */
     stripe: Stripe;
   }
 }
 
 /**
- * Webhook Request with Stripe Event
+ * Helper Functions
  */
-export interface WebhookRequest extends FastifyRequest {
-  body: {
-    /** Stripe event object */
-    id: string;
-    type: string;
-    data: any;
-    [key: string]: any;
-  };
-}
+export declare namespace helpers {
+  /** Extract customer email from various Stripe objects */
+  function getCustomerEmail(event: StripeWebhookEvent, stripe: Stripe): string | Promise<string | null> | null;
 
-/**
- * Webhook Response
- */
-export interface WebhookResponse {
-  /** Status message */
-  status: 'success' | 'error';
+  /** Format amount from cents to currency string */
+  function formatAmount(cents: number, currency?: string): string;
+
+  /** Get plan name from subscription */
+  function getPlanName(subscription: Stripe.Subscription): string;
 
-  /** Event ID that was processed */
-  eventId: string;
+  /** Check if subscription is in trial */
+  function isInTrial(subscription: Stripe.Subscription): boolean;
 
-  /** Event type that was processed */
-  eventType: string;
+  /** Check if subscription is active (including trialing) */
+  function isActiveSubscription(subscription: Stripe.Subscription): boolean;
 
-  /** Optional error message */
-  error?: string;
+  /** Get days until trial ends */
+  function getDaysUntilTrialEnd(subscription: Stripe.Subscription): number | null;
 
-  /** Timestamp of processing */
-  processedAt: string;
-}
+  /** Check if event is a subscription renewal */
+  function isRenewal(event: StripeWebhookEvent): boolean;
 
-/**
- * API Response Types
- */
-export interface Plan {
-  productId: string;
-  name: string;
-  description?: string;
-  images?: string[];
-  prices: PriceInfo[];
-  metadata?: Record<string, any>;
-}
+  /** Get subscription status display text */
+  function getSubscriptionStatusText(status: string): string;
 
-export interface PriceInfo {
-  priceId: string;
-  amount: number;
-  currency: string;
-  interval?: string;
-  intervalCount?: number;
-  trialPeriodDays?: number;
-  nickname?: string;
-  metadata?: Record<string, any>;
-}
+  /** Extract metadata from event */
+  function getMetadata(event: StripeWebhookEvent): Record<string, string>;
 
-export interface PaymentMethod {
-  id: string;
-  type: string;
-  isDefault: boolean;
-  card?: {
-    brand: string;
-    last4: string;
-    expMonth: number;
-    expYear: number;
-  };
-  billingDetails?: Record<string, any>;
-  createdAt: Date;
-}
+  /** Check if event is a test event */
+  function isTestEvent(event: StripeWebhookEvent): boolean;
+
+  /** Get human-readable event description */
+  function getEventDescription(event: StripeWebhookEvent): string;
+
+  /** Calculate MRR from subscription (in cents) */
+  function calculateMRR(subscription: Stripe.Subscription): number;
+
+  /** Get payment method type display text */
+  function getPaymentMethodType(paymentMethod: Stripe.PaymentMethod | null): string;
 
-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;
+  /** Extract line items from invoice */
+  function getInvoiceLineItems(invoice: Stripe.Invoice): Array<{
+    description: string | null;
+    amount: number;
+    quantity: number | null;
+    priceId: string | undefined;
+  }>;
+
+  /** Check if invoice is for subscription vs one-time payment */
+  function isSubscriptionInvoice(invoice: Stripe.Invoice): boolean;
+
+  /** Get next billing date from subscription */
+  function getNextBillingDate(subscription: Stripe.Subscription): Date | null;
+
+  /** Format date from Unix timestamp */
+  function formatDate(unixTimestamp: number | null, locale?: string): string | null;
 }
 
 /**
  * xStripe Plugin
- * Registers Stripe webhook handling and provides convenient API endpoints
+ *
+ * Registers Stripe webhook handling with signature verification and
+ * decorates the Fastify instance with a Stripe client.
  *
  * @example
  * ```typescript
@@ -273,37 +179,25 @@ export interface SubscriptionInfo {
  * 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);
+ *   webhookPath: '/stripe/webhook',
+ *   handlers: {
+ *     '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;
+export { xStripe };
 
-/**
- * Re-export Stripe types for convenience
- */
+/** Re-export for convenience */
 export { Stripe };
 export type { StripeWebhookEvent as WebhookEvent };
+
+/** Default handlers */
+export { defaultHandlers } from './src/handlers/defaultHandlers.js';
+export { exampleHandlers } from './src/handlers/exampleHandlers.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-xstripe",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Fastify plugin for Stripe webhooks with simplified, testable handlers for subscription events.",
   "main": "src/index.js",
   "exports": {
@@ -12,10 +12,10 @@
   "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"
+    "test": "node --test test/handlers.test.js test/xStripe.integration.test.js"
   },
   "author": "Tim Mushen",
-  "license": "ISC",
+  "license": "UNLICENSED",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -40,7 +40,6 @@
   "devDependencies": {
     "@types/node": "^22.7.4",
     "fastify": "^5.1.0",
-    "fastify-plugin": "^5.0.0",
     "typescript": "^5.6.3"
   },
   "dependencies": {

package/src/webhooks/webhooks.js

@@ -20,8 +20,8 @@ export async function setupWebhooks(fastify, options) {
       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" });
+        fastify.log.error("[xStripe] Missing stripe-signature header");
+        return reply.code(400).send({ error: "[xStripe] Missing stripe-signature header" });
       }
 
       let event;
@@ -33,12 +33,12 @@ export async function setupWebhooks(fastify, options) {
         // 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}` });
+        fastify.log.error(`[xStripe] Webhook signature verification failed: ${err.message}`);
+        return reply.code(400).send({ error: `[xStripe] Webhook signature verification failed: ${err.message}` });
       }
 
       // Log the event
-      fastify.log.info(`Received Stripe webhook: ${event.type}`);
+      fastify.log.info(`[xStripe] Received webhook: ${event.type}`);
 
       // Get handler for this event type
       const handler = eventHandlers[event.type];
@@ -47,9 +47,9 @@ export async function setupWebhooks(fastify, options) {
         try {
           // Execute handler
           await handler(event, fastify, stripe);
-          fastify.log.info(`Successfully processed ${event.type}`);
+          fastify.log.info(`[xStripe] Successfully processed ${event.type}`);
         } catch (err) {
-          fastify.log.error(`Error processing ${event.type}: ${err.message}`);
+          fastify.log.error(`[xStripe] 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({
@@ -59,7 +59,7 @@ export async function setupWebhooks(fastify, options) {
           });
         }
       } else {
-        fastify.log.warn(`No handler registered for event type: ${event.type}`);
+        fastify.log.warn(`[xStripe] No handler registered for event type: ${event.type}`);
       }
 
       // Always return 200 to acknowledge receipt
@@ -67,6 +67,6 @@ export async function setupWebhooks(fastify, options) {
     }
   );
 
-  console.info(`   ✅ Stripe Webhooks Enabled at ${webhookPath}`);
-  console.info(`   📋 Registered ${Object.keys(eventHandlers).length} event handlers`);
+  fastify.log.info(`[xStripe] Webhooks enabled at ${webhookPath}`);
+  fastify.log.info(`[xStripe] Registered ${Object.keys(eventHandlers).length} event handlers`);
 }

package/src/xStripe.js

@@ -13,11 +13,27 @@ async function xStripe(fastify, options) {
   } = options;
 
   // Validate required options
-  if (!apiKey) {
-    throw new Error("Stripe apiKey is required");
+  if (!apiKey || typeof apiKey !== "string") {
+    throw new Error("[xStripe] apiKey is required and must be a string");
   }
 
-  console.info("\n 💳 Starting xStripe...\n");
+  if (!webhookSecret || typeof webhookSecret !== "string") {
+    throw new Error("[xStripe] webhookSecret is required and must be a string");
+  }
+
+  if (typeof webhookPath !== "string") {
+    throw new Error("[xStripe] webhookPath must be a string");
+  }
+
+  if (typeof handlers !== "object" || Array.isArray(handlers)) {
+    throw new Error("[xStripe] handlers must be a plain object");
+  }
+
+  if (typeof apiVersion !== "string") {
+    throw new Error("[xStripe] apiVersion must be a string");
+  }
+
+  fastify.log.info("[xStripe] Initializing Stripe plugin...");
 
   // Initialize Stripe client
   const stripe = new Stripe(apiKey, { apiVersion });
@@ -25,21 +41,18 @@ async function xStripe(fastify, options) {
   // 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.");
-  }
+  // Setup webhook handling
+  await setupWebhooks(fastify, {
+    stripe,
+    webhookSecret,
+    webhookPath,
+    handlers,
+  });
 
-  console.info("\n 💳 xStripe Ready!\n");
+  fastify.log.info("[xStripe] Ready");
 }
 
 export default fp(xStripe, {
   name: "xStripe",
+  fastify: ">=5.0.0",
 });

package/.dockerignore

@@ -1,62 +0,0 @@
-# Git
-.git
-.gitignore
-.gitattributes
-
-# Node modules (will be installed in container)
-node_modules
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Dependencies
-.npm
-.eslintcache
-*.tsbuildinfo
-
-# Temporary files
-.DS_Store
-Thumbs.db
-*.tmp
-.env.local
-.env.*.local
-
-# IDE
-.vscode
-.idea
-*.swp
-*.swo
-*.swn
-*~
-
-# Test & Coverage
-coverage
-.nyc_output
-test
-*.test.js
-
-# Build artifacts (if any)
-dist
-build
-out
-
-# Docker files (not needed in image)
-Dockerfile*
-docker-compose*.yml
-.dockerignore
-
-# CI/CD
-.github
-.gitlab-ci.yml
-
-# Documentation (optional - include if you want docs in image)
-# *.md
-
-# Example/demo files
-examples
-demo
-
-# Logs
-logs
-*.log

package/.env.example

@@ -1,116 +0,0 @@
-# ============================================================================
-# xStripe Fastify Plugin - Environment Configuration
-# ============================================================================
-# This file defines environment variables for the xStripe module.
-# Copy this to .env and update values for your environment.
-# ============================================================================
-
-# ============================================================================
-# SERVER CONFIGURATION
-# ============================================================================
-
-# Server port (default: 3000)
-PORT=3000
-
-# Node environment (development | production | test)
-NODE_ENV=development
-
-# Server hostname/domain (used in webhook URLs and responses)
-# Update this to your actual domain in production
-DOMAIN=http://localhost:3000
-
-# ============================================================================
-# STRIPE CONFIGURATION - REQUIRED
-# ============================================================================
-
-# Stripe API Key (Secret Key)
-# Get from: https://dashboard.stripe.com/apikeys
-# Format: sk_test_... (test mode) or sk_live_... (production)
-# NEVER commit this value - use environment variables only
-STRIPE_API_KEY=sk_test_your_key_here
-
-# Stripe Webhook Signing Secret
-# Get from: https://dashboard.stripe.com/webhooks
-# Copy the "Signing secret" for your webhook endpoint
-# Format: whsec_...
-STRIPE_WEBHOOK_SECRET=whsec_your_secret_here
-
-# ============================================================================
-# WEBHOOK CONFIGURATION
-# ============================================================================
-
-# Webhook endpoint path (relative to domain)
-# Default: /webhooks/stripe
-# STRIPE_WEBHOOK_PATH=/webhooks/stripe
-
-# Webhook events to listen for (space or comma-separated)
-# Default: all supported events
-# Examples:
-#   customer.created,customer.updated,customer.deleted
-#   invoice.created,invoice.finalized,invoice.paid
-#   charge.succeeded,charge.failed
-# STRIPE_WEBHOOK_EVENTS=*
-
-# ============================================================================
-# LOGGING & MONITORING
-# ============================================================================
-
-# Fastify logger level (trace, debug, info, warn, error, fatal)
-LOG_LEVEL=info
-
-# Enable webhook event logging
-# LOG_WEBHOOK_EVENTS=true
-
-# Enable handler execution logging
-# LOG_HANDLER_EXECUTION=true
-
-# ============================================================================
-# ERROR HANDLING & RECOVERY
-# ============================================================================
-
-# Retry failed webhook handler executions
-# ENABLE_HANDLER_RETRY=false
-
-# Max retry attempts for failed handlers
-# HANDLER_RETRY_MAX_ATTEMPTS=3
-
-# Retry delay in milliseconds
-# HANDLER_RETRY_DELAY_MS=5000
-
-# ============================================================================
-# SECURITY
-# ============================================================================
-
-# Enable HTTPS enforcement (if behind reverse proxy)
-# HTTPS_ONLY=false
-
-# Rate limiting: max webhook requests per minute
-# WEBHOOK_RATE_LIMIT_WINDOW=1m
-# WEBHOOK_RATE_LIMIT_MAX=1000
-
-# Timeout for webhook handler execution (milliseconds)
-# Default: 30000 (30 seconds)
-# WEBHOOK_HANDLER_TIMEOUT=30000
-
-# ============================================================================
-# STRIPE ACCOUNT CONFIGURATION
-# ============================================================================
-
-# Stripe API Version (optional - uses account default if not set)
-# Format: YYYY-MM-DD or leave empty
-# STRIPE_API_VERSION=
-
-# Enable Stripe CLI webhooks in development
-# Set to true if using: stripe listen --forward-to localhost:3000/webhooks/stripe
-# STRIPE_CLI_MODE=false
-
-# ============================================================================
-# DATABASE/STORAGE (optional - for persisting event data)
-# ============================================================================
-
-# Database URL for event persistence (optional)
-# Example: postgresql://user:pass@localhost/stripe_events
-# DATABASE_URL=
-
-# Enable event persistence
-# PERSIST_WEBHOOK_EVENTS=false