docs: update README to reflect current codebase features

- Update version info from v0.0.x to v0.1.x
- Add comprehensive customer management documentation
- Include customer info extractor examples and configuration
- Document flexible customer data handling modes
- Add missing TypeScript exports to imports section
- Update features list with callback-based syncing and embedded customer info

Co-authored-by: Bas <bvdaakster@users.noreply.github.com>
This commit is contained in:
claude[bot]
2025-09-18 19:40:12 +00:00
parent 27b86132e9
commit e74a2410e6

View File

@@ -1,17 +1,19 @@
# @xtr-dev/payload-billing # @xtr-dev/payload-billing
A billing and payment provider plugin for PayloadCMS 3.x. Supports Stripe, Mollie, and local testing with comprehensive tracking. A billing and payment provider plugin for PayloadCMS 3.x. Supports Stripe, Mollie, and local testing with comprehensive tracking and flexible customer data management.
⚠️ **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.1.x). Breaking changes may occur before v1.0.0. Not recommended for production use.
## Features ## Features
- 💳 Multiple payment providers (Stripe, Mollie, Test) - 💳 Multiple payment providers (Stripe, Mollie, Test)
- 🧾 Invoice generation and management - 🧾 Invoice generation and management with embedded customer info
- 👥 Flexible customer data management with relationship support
- 📊 Complete payment tracking and history - 📊 Complete payment tracking and history
- 🪝 Secure webhook processing for all providers - 🪝 Secure webhook processing for all providers
- 🧪 Built-in test provider for local development - 🧪 Built-in test provider for local development
- 📱 Payment management in PayloadCMS admin - 📱 Payment management in PayloadCMS admin
- 🔄 Callback-based customer data syncing
- 🔒 Full TypeScript support - 🔒 Full TypeScript support
## Installation ## Installation
@@ -42,6 +44,8 @@ pnpm add @mollie/api-client
## Quick Start ## Quick Start
### Basic Configuration
```typescript ```typescript
import { buildConfig } from 'payload' import { buildConfig } from 'payload'
import { billingPlugin, stripeProvider, mollieProvider } from '@xtr-dev/payload-billing' import { billingPlugin, stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
@@ -70,6 +74,51 @@ export default buildConfig({
}) })
``` ```
### With Customer Management
```typescript
import { billingPlugin, defaultCustomerInfoExtractor } from '@xtr-dev/payload-billing'
billingPlugin({
// ... providers
collections: {
payments: 'payments',
invoices: 'invoices',
refunds: 'refunds',
},
customerRelationSlug: 'customers', // Enable customer relationships
customerInfoExtractor: defaultCustomerInfoExtractor, // Auto-sync customer data
})
```
### Custom Customer Data Extraction
```typescript
import { CustomerInfoExtractor } from '@xtr-dev/payload-billing'
const customExtractor: CustomerInfoExtractor = (customer) => ({
name: customer.fullName,
email: customer.contactEmail,
phone: customer.phoneNumber,
company: customer.companyName,
taxId: customer.vatNumber,
billingAddress: {
line1: customer.billing.street,
line2: customer.billing.apartment,
city: customer.billing.city,
state: customer.billing.state,
postalCode: customer.billing.zip,
country: customer.billing.countryCode,
}
})
billingPlugin({
// ... other config
customerRelationSlug: 'clients',
customerInfoExtractor: customExtractor,
})
```
## Imports ## Imports
```typescript ```typescript
@@ -80,7 +129,17 @@ import { billingPlugin } from '@xtr-dev/payload-billing'
import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing' import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing'
// Types // Types
import type { PaymentProvider, Payment, Invoice, Refund } from '@xtr-dev/payload-billing' import type {
PaymentProvider,
Payment,
Invoice,
Refund,
BillingPluginConfig,
CustomerInfoExtractor,
MollieProviderConfig,
StripeProviderConfig,
ProviderData
} from '@xtr-dev/payload-billing'
``` ```
## Provider Types ## Provider Types
@@ -99,9 +158,19 @@ Local development testing with configurable scenarios, automatic completion, deb
The plugin adds these collections: The plugin adds these collections:
- **payments** - Payment transactions with status and provider data - **payments** - Payment transactions with status and provider data
- **invoices** - Invoice generation with line items and PDF support - **invoices** - Invoice generation with line items and embedded customer info
- **refunds** - Refund tracking and management - **refunds** - Refund tracking and management
### Customer Data Management
The plugin supports flexible customer data handling:
1. **With Customer Relationship + Extractor**: Customer relationship required, customer info auto-populated and read-only, syncs automatically when customer changes
2. **With Customer Relationship (no extractor)**: Customer relationship optional, customer info manually editable, either relationship OR customer info required
3. **No Customer Collection**: Customer info fields always required and editable, no relationship field available
## Webhook Endpoints ## Webhook Endpoints
Automatic webhook endpoints are created for configured providers: Automatic webhook endpoints are created for configured providers: