@reeboot/strapi-payment-plugin 0.0.0 → 0.0.2

package/README.md

@@ -1,112 +1,444 @@
-# Strapi v5 Payment Plugin (Stripe & PayPal)
+# Strapi Payment Plugin
 
-This plugin provides a unified interface for processing payments through Stripe and PayPal in Strapi v5.
+A comprehensive Stripe integration plugin for Strapi v5 that provides complete payment processing capabilities, customer management, order handling, and webhook management for modern e-commerce applications.
 
-## Features
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![Strapi](https://img.shields.io/badge/Strapi-v5.33.1-green.svg)
+![Stripe](https://img.shields.io/badge/Stripe-v16.0.0-purple.svg)
+![License](https://img.shields.io/badge/license-MIT-yellow.svg)
 
-- Payment initiation (Stripe Payment Intents, PayPal Orders)
-- Webhook handling for payment status updates
-- Refund processing
-- Payment details retrieval
-- Admin panel configuration interface
+## 🚀 Features
 
-## Installation
+### Core Payment Processing
+- **Payment Intent Creation & Management** - Secure payment processing with Stripe Payment Intents
+- **Customer Management** - Create and manage Stripe customers with automatic Strapi synchronization
+- **Order Processing** - Complete order lifecycle management with payment integration
+- **Refund Processing** - Full and partial refund capabilities with audit trails
+- **Webhook Handling** - Automatic webhook processing with signature verification
 
-1. Install the plugin:
+### Advanced Features
+- **Real-time Payment Tracking** - Live payment status updates via webhooks
+- **Admin Dashboard** - Comprehensive admin interface for payment management
+- **Analytics & Reporting** - Payment analytics, revenue tracking, and customer insights
+- **Multi-currency Support** - Support for multiple currencies and payment methods
+- **Security First** - PCI-compliant payment handling with encrypted data storage
+
+### Developer Experience
+- **TypeScript Support** - Full TypeScript typing for all operations
+- **RESTful API** - Clean, documented API endpoints following REST conventions
+- **Rate Limiting** - Built-in rate limiting for sensitive operations
+- **Error Handling** - Comprehensive error handling with detailed logging
+- **Admin Interface** - Modern React-based admin panel with responsive design
+
+## 📋 Prerequisites
+
+- **Strapi v5.33.1+** - Latest Strapi v5 version
+- **Node.js 18+** - Node.js runtime environment
+- **Stripe Account** - Active Stripe account with API keys
+- **Database** - PostgreSQL, MySQL, or SQLite database
+
+## 🔧 Installation
+
+### Method 1: Copy Plugin to Project
+
+1. Copy the `payment-plugin` folder to your Strapi project's plugins directory:
    ```bash
-   npm install @reeboot/payment-plugin
+   cp -r payment-plugin /path/to/your/strapi-project/src/plugins/
    ```
 
-2. Add the plugin to your Strapi configuration:
-   ```javascript
-   // config/plugins.js
-   module.exports = {
+2. Install dependencies:
+   ```bash
+   npm install @stripe/stripe-js stripe
+   ```
+
+3. Configure the plugin in `config/plugins.ts`:
+   ```typescript
+   export default () => ({
      'payment-plugin': {
        enabled: true,
+       resolve: './src/plugins/payment-plugin',
+       config: {
+         stripe: {
+           apiVersion: '2024-06-20',
+         },
+         payment: {
+           defaultCurrency: 'usd',
+           successUrl: 'http://localhost:3000/payment/success',
+           cancelUrl: 'http://localhost:3000/payment/cancel',
+         },
+       },
      },
-   };
+   });
    ```
 
-## Configuration
+### Method 2: Development Setup
 
-1. Set up environment variables:
+1. Navigate to the plugin directory:
+   ```bash
+   cd src/plugins/payment-plugin
    ```
-   STRIPE_SECRET_KEY=your_stripe_secret_key
-   STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key
-   STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
-   PAYPAL_CLIENT_ID=your_paypal_client_id
-   PAYPAL_CLIENT_SECRET=your_paypal_client_secret
-   PAYPAL_WEBHOOK_ID=your_paypal_webhook_id
+
+2. Install dependencies:
+   ```bash
+   npm install
    ```
 
-2. Configure the plugin through the admin panel:
-   - Go to the "Payment Plugin Configuration" page
-   - Enter your API keys and secrets
-   - Save the configuration
+3. Build the plugin:
+   ```bash
+   npm run build
+   ```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```env
+# Stripe API Configuration
+STRIPE_API_KEY=sk_test_... # Your Stripe secret key
+STRIPE_WEBHOOK_SECRET=whsec_... # Your Stripe webhook endpoint secret
+
+# Alternative configuration
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# Optional: Plugin Configuration
+PAYMENT_PLUGIN_LOG_LEVEL=info
+PAYMENT_PLUGIN_ENABLE_WEBHOOK_LOGGING=true
+```
+
+### Plugin Configuration
+
+Update `config/plugins.ts` with your settings:
+
+```typescript
+export default () => ({
+  'payment-plugin': {
+    enabled: true,
+    resolve: './src/plugins/payment-plugin',
+    config: {
+      stripe: {
+        apiVersion: '2024-06-20',
+        apiKey: process.env.STRIPE_API_KEY,
+        webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+      },
+      payment: {
+        defaultCurrency: 'usd',
+        successUrl: 'https://yourapp.com/payment/success',
+        cancelUrl: 'https://yourapp.com/payment/cancel',
+        webhookEndpoint: '/api/payment-plugin/webhook',
+      },
+      logging: {
+        level: 'info',
+        enableWebhookLogging: true,
+        enableDebugLogging: false,
+      },
+    },
+  },
+});
+```
 
-## API Usage
+## 🚀 Quick Start
 
-### Initiate Payment
+### 1. Create a Payment Intent
 
 ```javascript
-// POST /payment-plugin/initiate-payment
-const response = await fetch('/payment-plugin/initiate-payment', {
+const paymentData = {
+  amount: 2500, // $25.00 in cents
+  currency: 'usd',
+  customerId: 1, // Optional: Strapi customer ID
+  orderId: 1,    // Optional: Strapi order ID
+  metadata: {
+    product_id: 'prod_123',
+    subscription_type: 'premium'
+  }
+};
+
+const response = await fetch('/api/payment-plugin/payments/create-intent', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_JWT_TOKEN'
   },
-  body: JSON.stringify({
-    gateway: 'stripe', // or 'paypal'
-    amount: 1000, // in cents
-    currency: 'usd',
-    orderId: 'order_123',
-    options: {
-      // gateway-specific options
-    },
-  }),
+  body: JSON.stringify(paymentData)
 });
-const payment = await response.json();
+
+const result = await response.json();
+console.log(result.data.client_secret); // Use this for Stripe Elements
 ```
 
-### Process Webhook
+### 2. Handle Payment on Frontend
 
 ```javascript
-// POST /payment-plugin/webhook/:gateway
-// The webhook URL should be configured in your Stripe/PayPal dashboard
+import { loadStripe } from '@stripe/stripe-js';
+
+const stripe = await loadStripe('pk_test_...');
+
+const { error } = await stripe.confirmCardPayment(clientSecret, {
+  payment_method: {
+    card: cardElement,
+    billing_details: {
+      name: 'John Doe',
+      email: 'john@example.com'
+    }
+  }
+});
+
+if (error) {
+  console.error('Payment failed:', error);
+} else {
+  console.log('Payment succeeded!');
+}
 ```
 
-### Refund Payment
+### 3. Create a Customer
 
 ```javascript
-// POST /payment-plugin/refund
-const response = await fetch('/payment-plugin/refund', {
+const customerData = {
+  email: 'customer@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  phone: '+1234567890',
+  address: {
+    line1: '123 Main St',
+    city: 'New York',
+    postal_code: '10001'
+  }
+};
+
+const response = await fetch('/api/payment-plugin/customers', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_JWT_TOKEN'
   },
-  body: JSON.stringify({
-    gateway: 'stripe', // or 'paypal'
-    transactionId: 'pi_123', // or PayPal transaction ID
-    amount: 500, // refund amount in cents
-    options: {
-      // gateway-specific options
-    },
-  }),
+  body: JSON.stringify(customerData)
 });
-const refund = await response.json();
 ```
 
-### Get Payment Details
+### 4. Process Refunds
 
 ```javascript
-// GET /payment-plugin/payments/:id
-const response = await fetch('/payment-plugin/payments/pi_123');
-const paymentDetails = await response.json();
+const refundData = {
+  paymentIntentId: 'pi_1234567890',
+  amount: 500, // Optional: partial refund
+  reason: 'requested_by_customer',
+  metadata: {
+    reason: 'customer_request'
+  }
+};
+
+const response = await fetch('/api/payment-plugin/refunds', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer YOUR_JWT_TOKEN'
+  },
+  body: JSON.stringify(refundData)
+});
+```
+
+## 📚 API Documentation
+
+The plugin provides comprehensive REST API endpoints:
+
+### Content API Routes
+- `POST /api/payment-plugin/payments/create-intent` - Create payment intent
+- `POST /api/payment-plugin/payments/confirm/:id` - Confirm payment
+- `GET /api/payment-plugin/payments/:id` - Get payment details
+- `GET /api/payment-plugin/payments` - List payments
+- `POST /api/payment-plugin/customers` - Create customer
+- `GET /api/payment-plugin/customers/:id` - Get customer details
+- `GET /api/payment-plugin/customers` - List customers
+- `POST /api/payment-plugin/orders` - Create order
+- `GET /api/payment-plugin/orders/:id` - Get order details
+- `GET /api/payment-plugin/orders` - List orders
+- `POST /api/payment-plugin/refunds` - Process refund
+- `GET /api/payment-plugin/status` - Service status
+- `GET /api/payment-plugin/health` - Health check
+
+### Admin API Routes
+- `POST /admin/api/payment-plugin/webhook` - Handle Stripe webhooks
+- `GET /admin/api/payment-plugin/admin/dashboard` - Dashboard data
+- `GET /admin/api/payment-plugin/admin/reports` - Payment reports
+- `GET /admin/api/payment-plugin/admin/analytics` - Analytics data
+- `GET /admin/api/payment-plugin/admin/config` - Plugin configuration
+- `PUT /admin/api/payment-plugin/admin/config` - Update configuration
+
+For complete API documentation, see [API_REFERENCE.md](./docs/API_REFERENCE.md).
+
+## 🔐 Security
+
+### Payment Security
+- **PCI Compliance** - Stripe handles all sensitive payment data
+- **Webhook Verification** - All webhooks are cryptographically verified
+- **Data Encryption** - Sensitive data is encrypted at rest and in transit
+- **Audit Logging** - All payment operations are logged for compliance
+
+### Access Control
+- **JWT Authentication** - All API endpoints require valid authentication
+- **Role-based Access** - User-specific data filtering
+- **Rate Limiting** - Protection against abuse
+- **Input Validation** - Comprehensive input sanitization
+
+### Security Best Practices
+- Never log sensitive payment information
+- Use HTTPS for all webhook endpoints
+- Implement proper error handling
+- Regular security audits and updates
+
+See [SECURITY.md](./docs/SECURITY.md) for detailed security guidelines.
+
+## 🛠️ Development
+
+### Project Structure
+
+```
+src/plugins/payment-plugin/
+├── admin/                 # Admin panel React components
+├── server/               # Server-side code
+│   ├── src/
+│   │   ├── controllers/   # API controllers
+│   │   ├── services/      # Business logic services
+│   │   ├── routes/        # API routes configuration
+│   │   ├── content-types/ # Database schemas
+│   │   └── types/         # TypeScript type definitions
+├── docs/                 # Documentation
+├── package.json          # Plugin dependencies
+└── README.md            # This file
+```
+
+### Building and Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+
+# Watch for changes during development
+npm run watch
+
+# Verify plugin structure
+npm run verify
+
+# Type checking
+npm run test:ts:front  # Frontend TypeScript
+npm run test:ts:back   # Backend TypeScript
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run specific test suite
+npm run test:unit
+npm run test:integration
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### "Stripe API key not found"
+- Ensure `STRIPE_API_KEY` is set in your environment variables
+- Check that the key starts with `sk_test_` (test) or `sk_live_` (live)
+- Verify the key has the correct permissions
+
+#### "Webhook signature verification fails"
+- Ensure `STRIPE_WEBHOOK_SECRET` is configured
+- Verify the webhook endpoint URL matches Stripe configuration
+- Check that your webhook endpoint is publicly accessible
+
+#### "Failed to create Strapi payment record"
+- Ensure content types are properly registered
+- Check database permissions and connectivity
+- Verify all required fields are provided
+
+### Debug Mode
+
+Enable detailed logging:
+
+```typescript
+// config/plugins.ts
+'payment-plugin': {
+  config: {
+    logging: {
+      level: 'debug',
+      enableWebhookLogging: true,
+      enableDebugLogging: true,
+    },
+  },
+},
 ```
 
-## Development
+### Health Checks
+
+Monitor service health:
+- `GET /api/payment-plugin/health` - Basic health check
+- `GET /api/payment-plugin/status` - Detailed service status
+
+## 📖 Documentation
+
+Complete documentation is available in the `docs/` directory:
+
+- [Installation Guide](./docs/INSTALLATION.md) - Detailed installation instructions
+- [Configuration Guide](./docs/CONFIGURATION.md) - Configuration options and examples
+- [API Reference](./docs/API_REFERENCE.md) - Complete API documentation
+- [Usage Guide](./docs/USAGE.md) - Usage examples and best practices
+- [Security Guide](./docs/SECURITY.md) - Security considerations and guidelines
+- [Deployment Guide](./docs/DEPLOYMENT.md) - Production deployment checklist
+
+## 🔄 Migration
+
+For migration from older versions or different payment systems, see:
+- [Strapi v5 Migration Guide](./STRAPI_V5_MIGRATION_GUIDE.md)
+- [Stripe Service Documentation](./STRIPE_SERVICE_README.md)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our contributing guidelines:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+### Development Guidelines
+
+- Follow TypeScript best practices
+- Add JSDoc comments for all public methods
+- Include unit tests for new features
+- Update documentation for any API changes
+- Follow the existing code style and formatting
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Strapi](https://strapi.io/) - The Headless CMS we all love
+- [Stripe](https://stripe.com/) - Payment processing made simple
+- [Stripe Elements](https://stripe.com/elements) - Beautiful payment UI components
+
+## 📞 Support
+
+- **Documentation**: Check the `docs/` folder for detailed guides
+- **Issues**: Report bugs and feature requests on GitHub
+- **Community**: Join our Discord community for discussions
+- **Email**: Contact support for enterprise inquiries
+
+---
+
+**Made with ❤️ by the Strapi Community**
 
-1. Clone the repository
-2. Install dependencies: `npm install`
-3. Build the plugin: `npm run build`
-4. Link the plugin to your Strapi project: `npm link`
+For the latest updates and announcements, follow us on [Twitter](https://twitter.com/strapijs) and join our [Discord](https://discord.gg/strapi) community.