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:
2025-09-14 23:21:43 +02:00
parent 6a49e00e7a
commit 74f2c99c7c
3 changed files with 80 additions and 147 deletions

183
README.md
View File

@@ -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)

View File

@@ -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()

View File

@@ -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',
}, },
}, },
{ {