mirror of
https://github.com/xtr-dev/payload-billing.git
synced 2025-12-10 02:43:24 +00:00
Update README, switch to SQLite, and adjust ESLint/perfectionist rules
- Simplified and clarified README structure and content. - Replaced `mongooseAdapter` with `sqliteAdapter` for database configuration. - Disabled all `perfectionist` ESLint rules for consistency. - Updated `billingPlugin` import path in dev config.
This commit is contained in:
183
README.md
183
README.md
@@ -1,53 +1,38 @@
|
|||||||
# 💳 @xtr-dev/payload-billing
|
# @xtr-dev/payload-billing
|
||||||
|
|
||||||
PayloadCMS plugin for billing and payment provider integrations with comprehensive tracking and local testing support.
|
A billing and payment provider plugin for PayloadCMS 3.x. Supports Stripe, Mollie, and local testing with comprehensive tracking.
|
||||||
|
|
||||||
⚠️ **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
|
⚠️ **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
|
||||||
|
|
||||||
## 🚀 Features
|
## Features
|
||||||
|
|
||||||
### Payment Providers
|
- 💳 Multiple payment providers (Stripe, Mollie, Test)
|
||||||
- **🔶 Stripe Integration** - Full Stripe payment processing support
|
- 🧾 Invoice generation and management
|
||||||
- **🟠 Mollie Integration** - Complete Mollie payment gateway integration
|
- 👥 Customer profiles with billing information
|
||||||
- **🧪 Test Provider** - Local development and testing payment provider
|
- 📊 Complete payment tracking and history
|
||||||
- **🔧 Extensible Architecture** - Easy to add new payment providers
|
- 🪝 Secure webhook processing for all providers
|
||||||
|
- 🧪 Built-in test provider for local development
|
||||||
|
- 📱 Payment management in PayloadCMS admin
|
||||||
|
- 🔒 Full TypeScript support
|
||||||
|
|
||||||
### Payment Tracking & Management
|
## Installation
|
||||||
- **📊 Transaction History** - Complete payment tracking and history
|
|
||||||
- **🔄 Payment Status Management** - Real-time payment status updates
|
|
||||||
- **💰 Amount & Currency Handling** - Multi-currency support
|
|
||||||
- **📋 Invoice Generation** - Automatic invoice creation and management
|
|
||||||
- **🏷️ Metadata Support** - Custom metadata for payments and customers
|
|
||||||
|
|
||||||
### Developer Experience
|
|
||||||
- **🛠️ Local Development** - Test provider for local development
|
|
||||||
- **🪝 Webhook Handling** - Robust webhook processing for all providers
|
|
||||||
- **📝 TypeScript Support** - Full TypeScript definitions and type safety
|
|
||||||
- **🔍 Debugging Tools** - Built-in logging and debugging capabilities
|
|
||||||
- **📚 Documentation** - Comprehensive API documentation
|
|
||||||
|
|
||||||
### PayloadCMS Integration
|
|
||||||
- **⚡ Admin UI Extensions** - Payment management directly in Payload admin
|
|
||||||
- **🗃️ Collections** - Pre-configured payment, customer, and invoice collections
|
|
||||||
- **🔐 Access Control** - Secure payment data with proper permissions
|
|
||||||
- **🎯 Hooks & Events** - PayloadCMS lifecycle hooks for payment events
|
|
||||||
|
|
||||||
## 🏗️ Installation
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install @xtr-dev/payload-billing
|
npm install @xtr-dev/payload-billing
|
||||||
# or
|
# or
|
||||||
yarn add @xtr-dev/payload-billing
|
|
||||||
# or
|
|
||||||
pnpm add @xtr-dev/payload-billing
|
pnpm add @xtr-dev/payload-billing
|
||||||
|
# or
|
||||||
|
yarn add @xtr-dev/payload-billing
|
||||||
```
|
```
|
||||||
|
|
||||||
## ⚙️ Quick Setup
|
## Quick Start
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
|
import { buildConfig } from 'payload'
|
||||||
import { billingPlugin } from '@xtr-dev/payload-billing'
|
import { billingPlugin } from '@xtr-dev/payload-billing'
|
||||||
|
|
||||||
export default buildConfig({
|
export default buildConfig({
|
||||||
|
// ... your config
|
||||||
plugins: [
|
plugins: [
|
||||||
billingPlugin({
|
billingPlugin({
|
||||||
providers: {
|
providers: {
|
||||||
@@ -60,136 +45,78 @@ export default buildConfig({
|
|||||||
apiKey: process.env.MOLLIE_API_KEY!,
|
apiKey: process.env.MOLLIE_API_KEY!,
|
||||||
webhookUrl: process.env.MOLLIE_WEBHOOK_URL!,
|
webhookUrl: process.env.MOLLIE_WEBHOOK_URL!,
|
||||||
},
|
},
|
||||||
// Test provider for local development
|
|
||||||
test: {
|
test: {
|
||||||
enabled: process.env.NODE_ENV === 'development',
|
enabled: process.env.NODE_ENV === 'development',
|
||||||
autoComplete: true, // Automatically complete payments
|
autoComplete: true,
|
||||||
}
|
}
|
||||||
},
|
|
||||||
collections: {
|
|
||||||
payments: 'payments',
|
|
||||||
customers: 'customers',
|
|
||||||
invoices: 'invoices',
|
|
||||||
}
|
}
|
||||||
})
|
})
|
||||||
]
|
]
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📋 Collections Added
|
## Imports
|
||||||
|
|
||||||
### Payments Collection
|
|
||||||
- Payment tracking with status, amount, currency
|
|
||||||
- Provider-specific payment data
|
|
||||||
- Customer relationships
|
|
||||||
- Transaction metadata
|
|
||||||
|
|
||||||
### Customers Collection
|
|
||||||
- Customer information and billing details
|
|
||||||
- Payment method storage
|
|
||||||
- Transaction history
|
|
||||||
- Subscription management
|
|
||||||
|
|
||||||
### Invoices Collection
|
|
||||||
- Invoice generation and management
|
|
||||||
- PDF generation support
|
|
||||||
- Payment status tracking
|
|
||||||
- Line item details
|
|
||||||
|
|
||||||
## 🔌 Provider APIs
|
|
||||||
|
|
||||||
### Stripe Integration
|
|
||||||
```typescript
|
```typescript
|
||||||
|
// Main plugin
|
||||||
|
import { billingPlugin } from '@xtr-dev/payload-billing'
|
||||||
|
|
||||||
|
// Provider utilities
|
||||||
import { getPaymentProvider } from '@xtr-dev/payload-billing'
|
import { getPaymentProvider } from '@xtr-dev/payload-billing'
|
||||||
|
|
||||||
const stripe = getPaymentProvider('stripe')
|
// Types
|
||||||
|
import type { PaymentProvider, CreatePaymentOptions, Payment } from '@xtr-dev/payload-billing'
|
||||||
// Create a payment
|
|
||||||
const payment = await stripe.createPayment({
|
|
||||||
amount: 2000, // $20.00
|
|
||||||
currency: 'usd',
|
|
||||||
customer: 'customer_id',
|
|
||||||
metadata: { orderId: '12345' }
|
|
||||||
})
|
|
||||||
|
|
||||||
// Handle webhooks
|
|
||||||
await stripe.handleWebhook(request, signature)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Mollie Integration
|
## Provider Types
|
||||||
```typescript
|
|
||||||
const mollie = getPaymentProvider('mollie')
|
|
||||||
|
|
||||||
// Create a payment
|
### Stripe
|
||||||
const payment = await mollie.createPayment({
|
Credit card payments, subscriptions, webhook processing, automatic payment method storage.
|
||||||
amount: { value: '20.00', currency: 'EUR' },
|
|
||||||
description: 'Order #12345',
|
### Mollie
|
||||||
redirectUrl: 'https://example.com/return',
|
European payment methods (iDEAL, SEPA, etc.), multi-currency support, refund processing.
|
||||||
webhookUrl: 'https://example.com/webhook'
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### Test Provider
|
### Test Provider
|
||||||
```typescript
|
Local development testing with configurable scenarios, automatic completion, debug mode.
|
||||||
const testProvider = getPaymentProvider('test')
|
|
||||||
|
|
||||||
// Simulate payment scenarios
|
## Collections
|
||||||
const payment = await testProvider.createPayment({
|
|
||||||
amount: 2000,
|
|
||||||
currency: 'usd',
|
|
||||||
// Test-specific options
|
|
||||||
simulateFailure: false,
|
|
||||||
delayMs: 1000
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🪝 Webhook Handling
|
The plugin adds these collections:
|
||||||
|
|
||||||
The plugin automatically sets up webhook endpoints for all configured providers:
|
- **payments** - Payment transactions with status and provider data
|
||||||
|
- **customers** - Customer profiles with billing information
|
||||||
|
- **invoices** - Invoice generation with line items and PDF support
|
||||||
|
- **refunds** - Refund tracking and management
|
||||||
|
|
||||||
- `/api/billing/webhooks/stripe` - Stripe webhook endpoint
|
## Webhook Endpoints
|
||||||
- `/api/billing/webhooks/mollie` - Mollie webhook endpoint
|
|
||||||
- `/api/billing/webhooks/test` - Test provider webhook endpoint
|
|
||||||
|
|
||||||
## 🛠️ Development
|
Automatic webhook endpoints are created:
|
||||||
|
- `/api/billing/webhooks/stripe`
|
||||||
|
- `/api/billing/webhooks/mollie`
|
||||||
|
- `/api/billing/webhooks/test`
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- PayloadCMS ^3.37.0
|
||||||
|
- Node.js ^18.20.2 || >=20.9.0
|
||||||
|
- pnpm ^9 || ^10
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
|
||||||
git clone https://github.com/xtr-dev/payload-billing.git
|
|
||||||
cd payload-billing
|
|
||||||
|
|
||||||
# Install dependencies
|
# Install dependencies
|
||||||
pnpm install
|
pnpm install
|
||||||
|
|
||||||
# Build the plugin
|
# Build plugin
|
||||||
pnpm build
|
pnpm build
|
||||||
|
|
||||||
# Run tests
|
# Run tests
|
||||||
pnpm test
|
pnpm test
|
||||||
|
|
||||||
# Start development server
|
# Development server
|
||||||
pnpm dev
|
pnpm dev
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📚 Documentation
|
## License
|
||||||
|
|
||||||
- [API Reference](./docs/api.md)
|
MIT
|
||||||
- [Provider Integration Guide](./docs/providers.md)
|
|
||||||
- [Webhook Setup](./docs/webhooks.md)
|
|
||||||
- [Testing Guide](./docs/testing.md)
|
|
||||||
- [TypeScript Types](./docs/types.md)
|
|
||||||
|
|
||||||
## 🤝 Contributing
|
|
||||||
|
|
||||||
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
||||||
|
|
||||||
## 📄 License
|
|
||||||
|
|
||||||
MIT License - see [LICENSE](LICENSE) file for details.
|
|
||||||
|
|
||||||
## 🔗 Links
|
|
||||||
|
|
||||||
- [PayloadCMS](https://payloadcms.com)
|
|
||||||
- [Stripe Documentation](https://stripe.com/docs)
|
|
||||||
- [Mollie Documentation](https://docs.mollie.com)
|
|
||||||
- [GitHub Repository](https://github.com/xtr-dev/payload-billing)
|
|
||||||
@@ -1,9 +1,8 @@
|
|||||||
import { mongooseAdapter } from '@payloadcms/db-mongodb'
|
import { sqliteAdapter } from '@payloadcms/db-sqlite'
|
||||||
import { lexicalEditor } from '@payloadcms/richtext-lexical'
|
import { lexicalEditor } from '@payloadcms/richtext-lexical'
|
||||||
import { MongoMemoryReplSet } from 'mongodb-memory-server'
|
|
||||||
import path from 'path'
|
import path from 'path'
|
||||||
import { buildConfig } from 'payload'
|
import { buildConfig } from 'payload'
|
||||||
import { billingPlugin } from '../src/index.js'
|
import { billingPlugin } from '../dist/index.js'
|
||||||
import sharp from 'sharp'
|
import sharp from 'sharp'
|
||||||
import { fileURLToPath } from 'url'
|
import { fileURLToPath } from 'url'
|
||||||
|
|
||||||
@@ -17,18 +16,7 @@ if (!process.env.ROOT_DIR) {
|
|||||||
process.env.ROOT_DIR = dirname
|
process.env.ROOT_DIR = dirname
|
||||||
}
|
}
|
||||||
|
|
||||||
const buildConfigWithMemoryDB = async () => {
|
const buildConfigWithSQLite = () => {
|
||||||
if (process.env.NODE_ENV === 'test') {
|
|
||||||
const memoryDB = await MongoMemoryReplSet.create({
|
|
||||||
replSet: {
|
|
||||||
count: 3,
|
|
||||||
dbName: 'payloadmemory',
|
|
||||||
},
|
|
||||||
})
|
|
||||||
|
|
||||||
process.env.DATABASE_URI = `${memoryDB.getUri()}&retryWrites=true`
|
|
||||||
}
|
|
||||||
|
|
||||||
return buildConfig({
|
return buildConfig({
|
||||||
admin: {
|
admin: {
|
||||||
importMap: {
|
importMap: {
|
||||||
@@ -48,9 +36,10 @@ const buildConfigWithMemoryDB = async () => {
|
|||||||
},
|
},
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
db: mongooseAdapter({
|
db: sqliteAdapter({
|
||||||
ensureIndexes: true,
|
client: {
|
||||||
url: process.env.DATABASE_URI || '',
|
url: `file:${path.resolve(dirname, 'payload.sqlite')}`,
|
||||||
|
},
|
||||||
}),
|
}),
|
||||||
editor: lexicalEditor(),
|
editor: lexicalEditor(),
|
||||||
email: testEmailAdapter,
|
email: testEmailAdapter,
|
||||||
@@ -81,4 +70,4 @@ const buildConfigWithMemoryDB = async () => {
|
|||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
export default buildConfigWithMemoryDB()
|
export default buildConfigWithSQLite()
|
||||||
|
|||||||
@@ -27,6 +27,23 @@ export default [
|
|||||||
{
|
{
|
||||||
rules: {
|
rules: {
|
||||||
'no-restricted-exports': 'off',
|
'no-restricted-exports': 'off',
|
||||||
|
// Disable all perfectionist rules
|
||||||
|
'perfectionist/sort-array-includes': 'off',
|
||||||
|
'perfectionist/sort-classes': 'off',
|
||||||
|
'perfectionist/sort-enums': 'off',
|
||||||
|
'perfectionist/sort-exports': 'off',
|
||||||
|
'perfectionist/sort-imports': 'off',
|
||||||
|
'perfectionist/sort-interfaces': 'off',
|
||||||
|
'perfectionist/sort-jsx-props': 'off',
|
||||||
|
'perfectionist/sort-maps': 'off',
|
||||||
|
'perfectionist/sort-named-exports': 'off',
|
||||||
|
'perfectionist/sort-named-imports': 'off',
|
||||||
|
'perfectionist/sort-object-types': 'off',
|
||||||
|
'perfectionist/sort-objects': 'off',
|
||||||
|
'perfectionist/sort-sets': 'off',
|
||||||
|
'perfectionist/sort-switch-case': 'off',
|
||||||
|
'perfectionist/sort-union-types': 'off',
|
||||||
|
'perfectionist/sort-variable-declarations': 'off',
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
|||||||
Reference in New Issue
Block a user