@xenterprises/fastify-xstripe 1.1.0 → 1.2.0

package/LICENSE

@@ -1,15 +1,60 @@
-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.
 
-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 LLC.
+
+2. RESTRICTIONS
+   Without the prior written consent of X Enterprises LLC, you may not:
+   - Copy, modify, or distribute the Software
+   - Reverse engineer, decompile, or disassemble the Software
+   - Sublicense, sell, lease, or otherwise transfer the Software
+   - Remove or alter any proprietary notices or labels
+
+3. AUTHORIZED USE
+   Use of this Software is limited to authorized employees, contractors, and
+   agents of X Enterprises LLC, solely for purposes approved by X Enterprises
+   LLC.
+
+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 LLC 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 LLC 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.
+
+7. TERMINATION
+   This license is effective until terminated. X Enterprises LLC may terminate
+   this license at any time without notice. Upon termination, you must destroy
+   all copies of the Software in your possession.
+
+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