@xenterprises/fastify-xstripe 1.0.0

package/API.md

@@ -0,0 +1,574 @@
+# xStripe API Reference
+
+Complete API documentation for xStripe example server endpoints supporting subscriptions and one-time payments.
+
+## Table of Contents
+
+1. [Customer Management](#customer-management)
+2. [Plans & Products](#plans--products)
+3. [Subscriptions](#subscriptions)
+4. [Payments](#payments)
+5. [Payment Methods](#payment-methods)
+6. [Utility Endpoints](#utility-endpoints)
+
+---
+
+## Customer Management
+
+### Create Customer
+
+**POST** `/create-customer`
+
+Create a new Stripe customer.
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+```
+
+**Response:**
+```json
+{
+  "customerId": "cus_ABC123..."
+}
+```
+
+**Status Codes:**
+- `200` - Customer created successfully
+- `500` - Error creating customer
+
+---
+
+## Plans & Products
+
+### List All Plans
+
+**GET** `/plans`
+
+Retrieve all available products with their pricing information.
+
+**Query Parameters:** None
+
+**Response:**
+```json
+{
+  "plans": [
+    {
+      "productId": "prod_ABC123...",
+      "name": "Professional Plan",
+      "description": "Best for teams",
+      "images": ["https://..."],
+      "metadata": {
+        "features": "advanced"
+      },
+      "prices": [
+        {
+          "priceId": "price_ABC123...",
+          "amount": 29.99,
+          "currency": "USD",
+          "interval": "month",
+          "intervalCount": 1,
+          "trialPeriodDays": 7,
+          "nickname": "Monthly",
+          "metadata": {}
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Status Codes:**
+- `200` - Success
+- `500` - Error retrieving plans
+
+### Get Specific Plan
+
+**GET** `/plans/:productId`
+
+Retrieve a specific product and all its prices.
+
+**URL Parameters:**
+- `productId` (string, required) - Stripe product ID (e.g., `prod_ABC123...`)
+
+**Response:**
+```json
+{
+  "productId": "prod_ABC123...",
+  "name": "Professional Plan",
+  "description": "Best for teams",
+  "images": [],
+  "metadata": {},
+  "prices": [
+    {
+      "priceId": "price_ABC123...",
+      "amount": 29.99,
+      "currency": "USD",
+      "interval": "month",
+      "intervalCount": 1,
+      "trialPeriodDays": 7,
+      "nickname": "Monthly"
+    }
+  ]
+}
+```
+
+**Status Codes:**
+- `200` - Success
+- `404` - Product not found
+- `500` - Server error
+
+---
+
+## Subscriptions
+
+### Create Subscription Checkout
+
+**POST** `/create-checkout-session`
+
+Create a checkout session for recurring subscription.
+
+**Request Body:**
+```json
+{
+  "customerId": "cus_ABC123...",
+  "priceId": "price_ABC123..."
+}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "cs_test_ABC123...",
+  "url": "https://checkout.stripe.com/..."
+}
+```
+
+**Status Codes:**
+- `200` - Session created
+- `500` - Error creating session
+
+### List Customer Subscriptions
+
+**GET** `/customer/:customerId/subscriptions`
+
+Get all subscriptions for a customer.
+
+**URL Parameters:**
+- `customerId` (string, required) - Stripe customer ID
+
+**Response:**
+```json
+{
+  "subscriptions": [
+    {
+      "id": "sub_ABC123...",
+      "status": "active",
+      "planId": "price_ABC123...",
+      "planName": "Professional Monthly",
+      "amount": 29.99,
+      "currency": "USD",
+      "interval": "month",
+      "createdAt": "2024-12-29T10:00:00Z",
+      "currentPeriodEnd": "2025-01-29T10:00:00Z",
+      "cancelAtPeriodEnd": false,
+      "canceledAt": null
+    }
+  ],
+  "total": 1
+}
+```
+
+**Subscription Status Values:**
+- `active` - Active subscription
+- `trialing` - In trial period
+- `past_due` - Payment failed
+- `canceled` - Canceled by user
+- `unpaid` - Unpaid invoices
+
+**Status Codes:**
+- `200` - Success
+- `500` - Error retrieving subscriptions
+
+### Update Subscription
+
+**POST** `/subscription/:id/update`
+
+Update a subscription (change plan, apply coupon, modify quantity).
+
+**URL Parameters:**
+- `id` (string, required) - Subscription ID
+
+**Request Body:**
+```json
+{
+  "priceId": "price_XYZ789...",
+  "quantity": 1,
+  "coupon": "SAVE20",
+  "metadata": {
+    "custom_field": "value"
+  },
+  "prorationBehavior": "create_prorations"
+}
+```
+
+**Proration Behavior Options:**
+- `create_prorations` (default) - Create prorated invoice
+- `none` - No proration
+- `always_invoice` - Always invoice immediately
+
+**Response:**
+```json
+{
+  "id": "sub_ABC123...",
+  "status": "active",
+  "priceId": "price_XYZ789...",
+  "amount": 49.99,
+  "nextBillingDate": "2025-01-29T10:00:00Z",
+  "message": "Subscription updated successfully"
+}
+```
+
+**Status Codes:**
+- `200` - Updated successfully
+- `500` - Error updating subscription
+
+### Cancel Subscription
+
+**POST** `/cancel-subscription/:id`
+
+Cancel a subscription immediately or at period end.
+
+**URL Parameters:**
+- `id` (string, required) - Subscription ID
+
+**Request Body:**
+```json
+{
+  "immediately": false
+}
+```
+
+**Parameters:**
+- `immediately` (boolean, optional, default: false)
+  - `true` - Cancel immediately
+  - `false` - Cancel at end of billing period
+
+**Response:**
+```json
+{
+  "subscriptionId": "sub_ABC123...",
+  "status": "canceled"
+}
+```
+
+**Status Codes:**
+- `200` - Canceled successfully
+- `500` - Error canceling subscription
+
+---
+
+## Payments
+
+### Create One-Time Payment Checkout
+
+**POST** `/create-payment-session`
+
+Create a checkout session for one-time payment.
+
+**Request Body:**
+```json
+{
+  "customerId": "cus_ABC123...",
+  "priceId": "price_ABC123...",
+  "quantity": 2,
+  "metadata": {
+    "order_id": "12345"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "sessionId": "cs_test_ABC123...",
+  "url": "https://checkout.stripe.com/..."
+}
+```
+
+**Status Codes:**
+- `200` - Session created
+- `500` - Error creating session
+
+---
+
+## Payment Methods
+
+### List Payment Methods
+
+**GET** `/customer/:customerId/payment-methods`
+
+Get all payment methods for a customer.
+
+**URL Parameters:**
+- `customerId` (string, required) - Stripe customer ID
+
+**Response:**
+```json
+{
+  "paymentMethods": [
+    {
+      "id": "pm_ABC123...",
+      "type": "card",
+      "isDefault": true,
+      "card": {
+        "brand": "visa",
+        "last4": "4242",
+        "expMonth": 12,
+        "expYear": 2025
+      },
+      "billingDetails": {
+        "name": "John Doe",
+        "email": "john@example.com"
+      },
+      "createdAt": "2024-12-29T10:00:00Z"
+    }
+  ],
+  "defaultPaymentMethodId": "pm_ABC123...",
+  "total": 1
+}
+```
+
+**Card Brands:**
+- `visa`
+- `mastercard`
+- `amex`
+- `discover`
+- And others...
+
+**Status Codes:**
+- `200` - Success
+- `500` - Error retrieving payment methods
+
+### Add Payment Method
+
+**POST** `/customer/:customerId/payment-methods`
+
+Attach a payment method to a customer.
+
+**Note:** The payment method must first be created on the frontend using Stripe Elements or Stripe.js.
+
+**URL Parameters:**
+- `customerId` (string, required) - Stripe customer ID
+
+**Request Body:**
+```json
+{
+  "paymentMethodId": "pm_ABC123..."
+}
+```
+
+**Response:**
+```json
+{
+  "id": "pm_ABC123...",
+  "type": "card",
+  "card": {
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2025
+  },
+  "message": "Payment method added successfully"
+}
+```
+
+**Status Codes:**
+- `200` - Added successfully
+- `500` - Error adding payment method
+
+### Set Default Payment Method
+
+**POST** `/customer/:customerId/payment-methods/:paymentMethodId/default`
+
+Set a payment method as the default for invoices and subscriptions.
+
+**URL Parameters:**
+- `customerId` (string, required) - Stripe customer ID
+- `paymentMethodId` (string, required) - Payment method ID
+
+**Request Body:** (empty)
+
+**Response:**
+```json
+{
+  "customerId": "cus_ABC123...",
+  "defaultPaymentMethodId": "pm_ABC123...",
+  "message": "Default payment method updated successfully"
+}
+```
+
+**Status Codes:**
+- `200` - Updated successfully
+- `500` - Error updating payment method
+
+### Delete Payment Method
+
+**DELETE** `/customer/:customerId/payment-methods/:paymentMethodId`
+
+Remove a payment method from a customer.
+
+**URL Parameters:**
+- `customerId` (string, required) - Stripe customer ID
+- `paymentMethodId` (string, required) - Payment method ID to delete
+
+**Request Body:** (empty)
+
+**Response:**
+```json
+{
+  "paymentMethodId": "pm_ABC123...",
+  "message": "Payment method removed successfully"
+}
+```
+
+**Status Codes:**
+- `200` - Deleted successfully
+- `500` - Error deleting payment method
+
+---
+
+## Utility Endpoints
+
+### Get Subscription
+
+**GET** `/subscription/:id`
+
+Get details of a specific subscription.
+
+**URL Parameters:**
+- `id` (string, required) - Subscription ID
+
+**Response:**
+```json
+{
+  "id": "sub_ABC123...",
+  "status": "active",
+  "currentPeriodEnd": "2025-01-29T10:00:00Z",
+  "cancelAtPeriodEnd": false
+}
+```
+
+**Status Codes:**
+- `200` - Success
+- `404` - Subscription not found
+- `500` - Server error
+
+### Health Check
+
+**GET** `/health`
+
+Check if the server and Stripe client are operational.
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "stripe": true,
+  "timestamp": "2024-12-29T10:00:00Z"
+}
+```
+
+**Status Codes:**
+- `200` - Server is healthy
+
+---
+
+## Error Handling
+
+All endpoints follow consistent error response format:
+
+```json
+{
+  "error": "Error message describing what went wrong"
+}
+```
+
+**Common HTTP Status Codes:**
+- `200` - Success
+- `400` - Bad request (invalid parameters)
+- `404` - Resource not found
+- `500` - Server error (Stripe API error or unexpected issue)
+
+---
+
+## Usage Examples
+
+### Complete Subscription Flow
+
+```bash
+# 1. Create customer
+curl -X POST http://localhost:3000/create-customer \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "name": "John Doe"
+  }'
+
+# Response: { "customerId": "cus_ABC123..." }
+
+# 2. List available plans
+curl http://localhost:3000/plans
+
+# 3. Create checkout session
+curl -X POST http://localhost:3000/create-checkout-session \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "cus_ABC123...",
+    "priceId": "price_ABC123..."
+  }'
+
+# Response: { "sessionId": "cs_test_...", "url": "https://..." }
+# User completes payment at URL
+
+# 4. List subscriptions
+curl http://localhost:3000/customer/cus_ABC123.../subscriptions
+
+# 5. Update plan
+curl -X POST http://localhost:3000/subscription/sub_ABC123.../update \
+  -H "Content-Type: application/json" \
+  -d '{
+    "priceId": "price_XYZ789..."
+  }'
+
+# 6. Manage payment methods
+curl http://localhost:3000/customer/cus_ABC123.../payment-methods
+```
+
+### One-Time Payment Flow
+
+```bash
+# 1. Create checkout for one-time payment
+curl -X POST http://localhost:3000/create-payment-session \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "cus_ABC123...",
+    "priceId": "price_ABC123...",
+    "quantity": 2
+  }'
+
+# User completes payment at returned URL
+```
+
+---
+
+## Related Documentation
+
+- [Stripe API Docs](https://stripe.com/docs/api)
+- [Stripe Webhooks](https://stripe.com/docs/webhooks)
+- [Subscription Guide](https://stripe.com/docs/billing/quickstart)
+- [Payment Methods API](https://stripe.com/docs/api/payment_methods)
+

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-29
+
+### Added
+- Initial release of xStripe Fastify v5 plugin
+- Simplified, testable Stripe webhook handling
+- 20+ built-in handlers for subscription lifecycle events
+- Pure function-based handler architecture
+- Stripe client decoration on Fastify instance
+- Webhook signature verification and validation
+- Custom handler override support
+- Error handling and logging
+- Type-safe operation with TypeScript support
+- Helper functions for common Stripe operations
+- Comprehensive error handling with graceful degradation
+- 6 comprehensive tests
+
+### Features
+- **Event-based architecture** - Clean handler separation
+- **Easy to test** - Handlers are pure functions
+- **Type-safe** - Full TypeScript support
+- **Built-in handlers** - 20+ default event handlers
+- **Production-ready** - Signature verification, error handling
+- **Flexible** - Override any handler with custom logic
+- **Readable** - Self-documenting code
+
+### Handlers Included
+- Subscription lifecycle (created, updated, deleted)
+- Invoice lifecycle (created, finalized, payment_failed, paid)
+- Customer events (created, updated, deleted)
+- Payment method events (attached, detached)
+- Charge events (succeeded, failed, refunded)
+- And 10+ more default handlers
+
+### Documentation
+- README.md with API reference
+- QUICK_START.md with step-by-step setup
+- EXAMPLES.md with 15+ real-world scenarios
+- TESTING.md with testing guide
+- MIGRATION.md with upgrade guide
+
+### Security
+- Webhook signature verification
+- Request validation
+- Error handling without data leaks
+- Secure Stripe API key handling
+
+---
+
+## [Future Versions - Planned]
+
+### [1.1.0] - Planned
+- Webhook retry logic
+- Event filtering and routing
+- Batch event handling
+- Metrics collection hooks
+- Advanced error recovery
+
+### [1.2.0] - Planned
+- Webhook event queue for reliability
+- Dead letter handling
+- Event replay capabilities
+- Audit logging
+
+### [2.0.0] - Planned (Breaking Changes)
+- Payment intent workflows
+- Connect account support
+- Advanced billing scenarios
+- Plugin ecosystem
+
+---
+
+## Dependencies
+- **stripe**: ^16.12.0 (Stripe JavaScript SDK)
+- **fastify-plugin**: ^5.0.0 (Fastify plugin wrapper)
+- **fastify**: ^5.0.0+ (peer dependency)
+
+## System Requirements
+- Node.js >= 20.0.0
+- Fastify >= 5.0.0
+- Stripe account with API keys
+
+## License
+ISC
+
+## Author
+Tim Mushen
+
+## Repository
+https://gitlab.com/x-enterprises/fastify-plugins/fastify-xstripe