@xenterprises/fastify-xstripe 1.1.1 → 1.2.1

package/LICENSE

@@ -1,15 +1,100 @@
-ISC License
+PROPRIETARY SOFTWARE LICENSE
 
-Copyright (c) 2024 Tim Mushen
+Copyright (c) 2024-2026 X Enterprises LLC. All Rights Reserved.
 
-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.
+This software and associated documentation files (the "Software") are the
+exclusive property of X Enterprises LLC, a Washington limited liability
+company ("X Enterprises"). The Software is distributed through public
+package registries (including npm) for operational convenience only; such
+distribution does not grant any rights beyond those expressly stated below.
 
-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.
+TERMS AND CONDITIONS
+
+1. OWNERSHIP
+   All rights, title, and interest in and to the Software, including all
+   intellectual property rights, are and shall remain the exclusive property
+   of X Enterprises. No rights are granted except as expressly set forth in
+   this License.
+
+2. PERMITTED USE
+   Subject to the restrictions in Section 3, you are permitted to download,
+   install, and execute the Software solely as a dependency of:
+
+   (a) software developed, owned, or operated by X Enterprises;
+
+   (b) software that X Enterprises has developed, delivered, or licensed to
+       a third party ("Client") under a written engagement agreement with
+       X Enterprises, when such use is performed by or on behalf of that
+       Client; or
+
+   (c) end-user access to, or consumption of, a product or service described
+       in (a) or (b), provided that such access does not involve
+       redistribution, modification, or separate use of the Software.
+
+   Permitted Use includes automated installation and execution by continuous
+   integration systems, container builds, hosting platforms, and similar
+   infrastructure, to the extent necessary to support (a), (b), or (c).
+
+3. RESTRICTIONS
+   Except as expressly permitted in Section 2, and without the prior written
+   consent of X Enterprises, you may not:
+
+   (a) copy, modify, adapt, translate, or create derivative works of the
+       Software for any purpose outside the scope of Section 2;
+
+   (b) redistribute, republish, sublicense, sell, lease, rent, or otherwise
+       transfer the Software, in whole or in part, whether standalone or
+       bundled with other software;
+
+   (c) reverse engineer, decompile, disassemble, or attempt to derive the
+       source code or underlying ideas, algorithms, structure, or
+       organization of the Software, except to the extent such activity is
+       expressly permitted by applicable law notwithstanding this
+       restriction;
+
+   (d) use the Software, in whole or in part, to develop, operate, or
+       provide any product or service that competes with or substitutes for
+       any X Enterprises product or service;
+
+   (e) remove, obscure, or alter any copyright, trademark, license, or other
+       proprietary notice contained in or on the Software; or
+
+   (f) use the Software in violation of any applicable law or regulation.
+
+4. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   X ENTERPRISES BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT
+   OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+   THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL X ENTERPRISES BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. GOVERNING LAW
+   This License shall be governed by and construed in accordance with the
+   laws of the State of Washington, United States, without regard to its
+   conflict of law provisions. Exclusive jurisdiction for any dispute
+   arising out of this License shall lie in the state or federal courts
+   located in King County, Washington.
+
+7. TERMINATION
+   This License is effective until terminated. Your rights under this
+   License will terminate automatically and without notice if you fail to
+   comply with any term herein. Upon termination, you must cease all use of
+   the Software and destroy all copies in your possession or control.
+   Sections 1, 3, 4, 5, 6, and 7 survive termination.
+
+For licensing inquiries, contact: legal@x.enterprises
+
+---
+X Enterprises LLC
+Bothell, Washington, United States

package/README.md

@@ -1,26 +1,11 @@
-# xStripe
+# @xenterprises/fastify-xstripe
 
-Fastify v5 plugin for simplified, testable Stripe webhook handling. Focuses on subscription lifecycle management with clean, readable code.
+Fastify v5 plugin for Stripe webhook handling with built-in signature verification, 23 default event handlers, and the Stripe client decorated on the Fastify instance.
 
-## Requirements
-
-- **Fastify v5.0.0+**
-- **Node.js v20+**
-
-## Features
-
-- **Simple webhook handling** - Clean event-based architecture
-- **Built-in handlers** - 20+ default handlers for common events
-- **Easy to test** - Handlers are pure functions
-- **Type-safe** - Full TypeScript support
-- **Readable** - Clear, self-documenting code
-- **Flexible** - Override any default handler
-- **Production-ready** - Signature verification, error handling, logging
-
-## Installation
+## Install
 
 ```bash
-npm install @xenterprises/fastify-xstripe fastify@5
+npm install @xenterprises/fastify-xstripe stripe
 ```
 
 ## Quick Start
@@ -34,298 +19,168 @@ const fastify = Fastify({ logger: true });
 await fastify.register(xStripe, {
   apiKey: process.env.STRIPE_API_KEY,
   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
-  webhookPath: '/stripe/webhook', // Optional, defaults to /stripe/webhook
 });
 
+// Use the Stripe client directly
+const customer = await fastify.stripe.customers.create({ email: 'user@example.com' });
+
 await fastify.listen({ port: 3000 });
 ```
 
+## Options
+
+| Name | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `apiKey` | `string` | — | Yes | Stripe secret API key (`sk_test_...` or `sk_live_...`) |
+| `webhookSecret` | `string` | — | Yes | Stripe webhook signing secret (`whsec_...`) |
+| `webhookPath` | `string` | `"/stripe/webhook"` | No | Path where the webhook POST route is registered |
+| `handlers` | `object` | `{}` | No | Custom event handlers that override the defaults |
+| `apiVersion` | `string` | `"2024-11-20.acacia"` | No | Stripe API version |
+
+All options are validated at startup. Invalid or missing required options throw with an `[xStripe]` prefix.
+
+## Decorated Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fastify.stripe` | `Stripe` | The initialized Stripe SDK client — use it to call any Stripe API |
+
 ## Custom Handlers
 
-Override default handlers with your business logic:
+Override any default handler with your business logic. Handlers receive `(event, fastify, stripe)`:
 
 ```javascript
 await fastify.register(xStripe, {
   apiKey: process.env.STRIPE_API_KEY,
   webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
   handlers: {
-    // Handle new subscription
     'customer.subscription.created': async (event, fastify, stripe) => {
       const subscription = event.data.object;
-
-      // Update your database
-      await fastify.prisma.user.update({
+      await db.users.update({
         where: { stripeCustomerId: subscription.customer },
-        data: {
-          subscriptionId: subscription.id,
-          subscriptionStatus: subscription.status,
-          planId: subscription.items.data[0]?.price.id,
-        },
+        data: { subscriptionId: subscription.id, status: subscription.status },
       });
-
-      // Send welcome email
-      await fastify.email.send(
-        subscription.customer.email,
-        'Welcome to Premium!',
-        '<h1>Thanks for subscribing!</h1>'
-      );
     },
-
-    // Handle subscription cancellation
-    'customer.subscription.deleted': async (event, fastify, stripe) => {
-      const subscription = event.data.object;
-
-      // Revoke access
-      await fastify.prisma.user.update({
-        where: { stripeSubscriptionId: subscription.id },
-        data: {
-          subscriptionStatus: 'canceled',
-          hasAccess: false,
-        },
-      });
-    },
-
-    // Handle failed payment
     'invoice.payment_failed': async (event, fastify, stripe) => {
       const invoice = event.data.object;
-
-      // Send payment failure email
       const customer = await stripe.customers.retrieve(invoice.customer);
-      await fastify.email.send(
-        customer.email,
-        'Payment Failed',
-        '<p>Please update your payment method.</p>'
-      );
+      await sendEmail(customer.email, 'Payment Failed', 'Please update your card.');
     },
   },
 });
 ```
 
-## Handler Function Signature
-
-All handlers receive three parameters:
-
-```javascript
-async function handler(event, fastify, stripe) {
-  // event - The Stripe webhook event object
-  // fastify - The Fastify instance (access to decorators)
-  // stripe - The Stripe client instance
-}
-```
+## Default Event Handlers
 
-## Supported Events
+All 23 built-in handlers log structured data via `fastify.log`. Override any of them via the `handlers` option.
 
 ### Subscription Events
-- `customer.subscription.created` - New subscription
-- `customer.subscription.updated` - Subscription changed
-- `customer.subscription.deleted` - Subscription canceled
-- `customer.subscription.trial_will_end` - Trial ending in 3 days
-- `customer.subscription.paused` - Subscription paused
-- `customer.subscription.resumed` - Subscription resumed
+- `customer.subscription.created` — logs subscriptionId, customerId, status, planId
+- `customer.subscription.updated` — logs subscriptionId, customerId, status, previous changes
+- `customer.subscription.deleted` — logs subscriptionId, customerId, canceledAt
+- `customer.subscription.trial_will_end` — logs subscriptionId, customerId, trialEnd
+- `customer.subscription.paused` — logs subscriptionId, customerId
+- `customer.subscription.resumed` — logs subscriptionId, customerId
 
 ### Invoice Events
-- `invoice.created` - Invoice created
-- `invoice.finalized` - Invoice ready for payment
-- `invoice.paid` - Payment succeeded
-- `invoice.payment_failed` - Payment failed
-- `invoice.upcoming` - Upcoming charge notification
+- `invoice.created` — logs invoiceId, customerId, amount, status
+- `invoice.finalized` — logs invoiceId, customerId, amount
+- `invoice.paid` — logs invoiceId, customerId, subscriptionId, amount
+- `invoice.payment_failed` — logs (warn) invoiceId, customerId, amount, attemptCount
+- `invoice.upcoming` — logs customerId, subscriptionId, amount, periodEnd
 
 ### Payment Events
-- `payment_intent.succeeded` - Payment successful
-- `payment_intent.payment_failed` - Payment failed
+- `payment_intent.succeeded` — logs paymentIntentId, customerId, amount, currency
+- `payment_intent.payment_failed` — logs (warn) paymentIntentId, customerId, amount, lastPaymentError
 
 ### Customer Events
-- `customer.created` - New customer
-- `customer.updated` - Customer details changed
-- `customer.deleted` - Customer deleted
+- `customer.created` — logs customerId, email
+- `customer.updated` — logs customerId, previous changes
+- `customer.deleted` — logs customerId
 
 ### Payment Method Events
-- `payment_method.attached` - Payment method added
-- `payment_method.detached` - Payment method removed
+- `payment_method.attached` — logs paymentMethodId, customerId, type
+- `payment_method.detached` — logs paymentMethodId, type
 
 ### Checkout Events
-- `checkout.session.completed` - Checkout completed
-- `checkout.session.expired` - Checkout session expired
+- `checkout.session.completed` — logs sessionId, customerId, subscriptionId, mode, paymentStatus
+- `checkout.session.expired` — logs sessionId
 
-## Testing Webhooks Locally
+### Charge Events
+- `charge.succeeded` — logs chargeId, customerId, amount, currency, paymentMethod
+- `charge.failed` — logs (error) chargeId, customerId, amount, failureCode, failureMessage
+- `charge.refunded` — logs chargeId, customerId, amountRefunded, refundCount
 
-### 1. Use Stripe CLI
+## Helper Utilities
 
-```bash
-# Install Stripe CLI
-brew install stripe/stripe-cli/stripe
-
-# Login to Stripe
-stripe login
-
-# Forward webhooks to your local server
-stripe listen --forward-to localhost:3000/stripe/webhook
-
-# Trigger test events
-stripe trigger customer.subscription.created
-stripe trigger invoice.payment_failed
-```
-
-### 2. Test Handlers Directly
-
-Since handlers are pure functions, they're easy to test:
-
-```javascript
-import { test } from 'node:test';
-import assert from 'node:assert';
-
-test('subscription.created handler', async () => {
-  const mockEvent = {
-    type: 'customer.subscription.created',
-    data: {
-      object: {
-        id: 'sub_123',
-        customer: 'cus_123',
-        status: 'active',
-      },
-    },
-  };
-
-  const mockFastify = {
-    log: { info: () => {} },
-    prisma: {
-      user: {
-        update: async (data) => {
-          assert.equal(data.where.stripeCustomerId, 'cus_123');
-          return {};
-        },
-      },
-    },
-  };
-
-  const mockStripe = {};
-
-  await handlers['customer.subscription.created'](
-    mockEvent,
-    mockFastify,
-    mockStripe
-  );
-});
-```
-
-## Common Patterns
-
-### Update Database on Subscription Change
-
-```javascript
-'customer.subscription.updated': async (event, fastify, stripe) => {
-  const subscription = event.data.object;
-  const previous = event.data.previous_attributes || {};
-
-  // Check what changed
-  if ('status' in previous) {
-    await fastify.prisma.user.update({
-      where: { stripeSubscriptionId: subscription.id },
-      data: { subscriptionStatus: subscription.status },
-    });
-
-    // Handle specific status changes
-    if (subscription.status === 'past_due') {
-      // Send payment reminder
-    }
-  }
-}
-```
-
-### Send Notification Emails
+Import from `@xenterprises/fastify-xstripe/helpers`:
 
 ```javascript
-'customer.subscription.trial_will_end': async (event, fastify, stripe) => {
-  const subscription = event.data.object;
-  const customer = await stripe.customers.retrieve(subscription.customer);
-
-  await fastify.email.send(
-    customer.email,
-    'Your trial ends soon!',
-    '<p>Convert to a paid plan to keep access.</p>'
-  );
-}
+import { helpers } from '@xenterprises/fastify-xstripe';
+
+helpers.formatAmount(2000, 'USD');           // "$20.00"
+helpers.getPlanName(subscription);            // "Pro Plan"
+helpers.isActiveSubscription(subscription);   // true
+helpers.isInTrial(subscription);              // true/false
+helpers.getDaysUntilTrialEnd(subscription);   // 3
+helpers.isRenewal(event);                     // true/false
+helpers.calculateMRR(subscription);           // 2000 (cents)
+helpers.getSubscriptionStatusText('active');   // "Active"
+helpers.getEventDescription(event);           // "Payment received"
+helpers.getCustomerEmail(event, stripe);      // "user@example.com"
+helpers.isTestEvent(event);                   // true/false
+helpers.getMetadata(event);                   // { key: "value" }
+helpers.getPaymentMethodType(pm);             // "Card"
+helpers.getInvoiceLineItems(invoice);         // [{ description, amount, ... }]
+helpers.isSubscriptionInvoice(invoice);       // true/false
+helpers.getNextBillingDate(subscription);     // Date
+helpers.formatDate(1700000000);               // "November 14, 2023"
 ```
 
-### Track Failed Payments
-
-```javascript
-'invoice.payment_failed': async (event, fastify, stripe) => {
-  const invoice = event.data.object;
-
-  await fastify.prisma.user.update({
-    where: { stripeSubscriptionId: invoice.subscription },
-    data: {
-      failedPaymentCount: { increment: 1 },
-      lastFailedPayment: new Date(),
-    },
-  });
-
-  // After 3 failed payments, suspend account
-  const user = await fastify.prisma.user.findUnique({
-    where: { stripeSubscriptionId: invoice.subscription },
-  });
-
-  if (user.failedPaymentCount >= 3) {
-    await fastify.prisma.user.update({
-      where: { id: user.id },
-      data: { accountSuspended: true },
-    });
-  }
-}
-```
+## Environment Variables
 
-## Configuration Options
+| Name | Required | Description |
+|------|----------|-------------|
+| `STRIPE_API_KEY` | Yes | Stripe secret key (`sk_test_...` or `sk_live_...`) |
+| `STRIPE_WEBHOOK_SECRET` | Yes | Webhook signing secret from Stripe Dashboard or CLI (`whsec_...`) |
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `apiKey` | string | Yes | - | Stripe API key |
-| `webhookSecret` | string | No | - | Stripe webhook signing secret |
-| `webhookPath` | string | No | `/stripe/webhook` | Webhook endpoint path |
-| `handlers` | object | No | `{}` | Custom event handlers |
-| `apiVersion` | string | No | `2024-11-20.acacia` | Stripe API version |
+## Error Reference
 
-## Security
+All errors use the `[xStripe]` prefix for easy identification in logs.
 
-- **Signature Verification**: All webhooks are verified using Stripe's signature
-- **Raw Body Required**: Plugin automatically handles raw body parsing
-- **Error Isolation**: Handler errors don't prevent webhook acknowledgment
-- **Logging**: All events and errors are logged
+| Error | When |
+|-------|------|
+| `[xStripe] apiKey is required and must be a string` | Missing or non-string `apiKey` option |
+| `[xStripe] webhookSecret is required and must be a string` | Missing or non-string `webhookSecret` option |
+| `[xStripe] webhookPath must be a string` | Non-string `webhookPath` option |
+| `[xStripe] handlers must be a plain object` | `handlers` is not an object or is an array |
+| `[xStripe] apiVersion must be a string` | Non-string `apiVersion` option |
+| `[xStripe] Missing stripe-signature header` | Webhook request without signature header (HTTP 400) |
+| `[xStripe] Webhook signature verification failed: ...` | Invalid webhook signature (HTTP 400) |
 
-## Best Practices
+## How It Works
 
-1. **Always acknowledge webhooks quickly** - Do heavy processing async
-2. **Make handlers idempotent** - Stripe may send events multiple times
-3. **Log everything** - Use structured logging for debugging
-4. **Test with Stripe CLI** - Test all event types before production
-5. **Monitor failed handlers** - Set up alerts for handler errors
+1. **Registration** — Validates all options, initializes the Stripe SDK client, and decorates it as `fastify.stripe`.
+2. **Webhook Route** — Registers a POST route at `webhookPath` that reads the raw body, verifies the Stripe signature using `stripe.webhooks.constructEvent()`, and dispatches to the matching handler.
+3. **Handler Dispatch** — User-provided handlers override defaults via object spread (`{ ...defaultHandlers, ...userHandlers }`). If a handler throws, the error is logged but the webhook still returns HTTP 200 to prevent Stripe retries.
+4. **Stripe Client** — The `fastify.stripe` decorator gives full access to the Stripe SDK for any API call (customers, subscriptions, invoices, etc.).
 
-## Environment Variables
+## Testing Webhooks Locally
 
 ```bash
-STRIPE_API_KEY=sk_test_...
-STRIPE_WEBHOOK_SECRET=whsec_...
-```
-
-## Integration with Other xPlugins
+# Install Stripe CLI
+brew install stripe/stripe-cli/stripe
 
-Works seamlessly with other x-series plugins:
+# Login and forward webhooks
+stripe login
+stripe listen --forward-to localhost:3000/stripe/webhook
 
-```javascript
-await fastify.register(xStripe, { /* ... */ });
-await fastify.register(xTwilio, { /* ... */ });  // Send SMS notifications
-await fastify.register(xConfig, { /* ... */ });  // Email notifications
-
-// In your handlers:
-'invoice.payment_failed': async (event, fastify, stripe) => {
-  // Send email via xConfig/SendGrid
-  await fastify.email.send(/* ... */);
-
-  // Send SMS via xTwilio
-  await fastify.sms.send(/* ... */);
-}
+# Trigger test events
+stripe trigger customer.subscription.created
+stripe trigger invoice.payment_failed
+stripe trigger checkout.session.completed
 ```
 
 ## License
 
-ISC
+UNLICENSED

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.1",
+  "version": "1.2.1",
   "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": "SEE LICENSE IN LICENSE",
   "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": {
@@ -49,5 +48,8 @@
   },
   "peerDependencies": {
     "fastify": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

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

package/.gitlab-ci.yml

@@ -1,45 +0,0 @@
-# ============================================================================
-# GitLab CI/CD Pipeline - xStripe
-# ============================================================================
-# Runs tests on merge requests and commits to main/master
-
-stages:
-  - test
-
-variables:
-  NODE_ENV: test
-
-# ============================================================================
-# Shared Configuration
-# ============================================================================
-.shared_rules: &shared_rules
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_BRANCH == "main"'
-    - if: '$CI_COMMIT_BRANCH == "master"'
-    - if: '$CI_COMMIT_TAG'
-
-# ============================================================================
-# STAGE: TEST
-# ============================================================================
-test:
-  stage: test
-  image: node:20-alpine
-  <<: *shared_rules
-
-  cache:
-    key: ${CI_COMMIT_REF_SLUG}
-    paths:
-      - node_modules/
-
-  before_script:
-    - npm ci
-
-  script:
-    - echo "Running xStripe tests..."
-    - npm test
-    - npm audit --audit-level=high || true
-
-  retry:
-    max: 2
-    when: runner_system_failure