From e74a2410e60fd17f3afb0fed8aa3d72ea161cd2c Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 19:40:12 +0000 Subject: [PATCH 1/2] 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 --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1d43012..5ecca38 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ # @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 - ๐Ÿ’ณ 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 - ๐Ÿช Secure webhook processing for all providers - ๐Ÿงช Built-in test provider for local development - ๐Ÿ“ฑ Payment management in PayloadCMS admin +- ๐Ÿ”„ Callback-based customer data syncing - ๐Ÿ”’ Full TypeScript support ## Installation @@ -42,6 +44,8 @@ pnpm add @mollie/api-client ## Quick Start +### Basic Configuration + ```typescript import { buildConfig } from 'payload' 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 ```typescript @@ -80,7 +129,17 @@ import { billingPlugin } from '@xtr-dev/payload-billing' import { stripeProvider, mollieProvider } from '@xtr-dev/payload-billing' // 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 @@ -99,9 +158,19 @@ Local development testing with configurable scenarios, automatic completion, deb The plugin adds these collections: - **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 +### 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 Automatic webhook endpoints are created for configured providers: From 38c8c3677d1abc580a0d092f97ef270b4d44e8a6 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 19:51:01 +0000 Subject: [PATCH 2/2] fix: remove non-existent defaultCustomerInfoExtractor from README Replace defaultCustomerInfoExtractor import and usage with a proper working example that shows how to define a CustomerInfoExtractor function. Co-authored-by: Bas --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5ecca38..3f49c53 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,24 @@ export default buildConfig({ ### With Customer Management ```typescript -import { billingPlugin, defaultCustomerInfoExtractor } from '@xtr-dev/payload-billing' +import { billingPlugin, CustomerInfoExtractor } from '@xtr-dev/payload-billing' + +// Define how to extract customer info from your customer collection +const customerExtractor: CustomerInfoExtractor = (customer) => ({ + name: customer.name, + email: customer.email, + phone: customer.phone, + company: customer.company, + taxId: customer.taxId, + billingAddress: { + line1: customer.address.line1, + line2: customer.address.line2, + city: customer.address.city, + state: customer.address.state, + postalCode: customer.address.postalCode, + country: customer.address.country, + } +}) billingPlugin({ // ... providers @@ -87,7 +104,7 @@ billingPlugin({ refunds: 'refunds', }, customerRelationSlug: 'customers', // Enable customer relationships - customerInfoExtractor: defaultCustomerInfoExtractor, // Auto-sync customer data + customerInfoExtractor: customerExtractor, // Auto-sync customer data }) ```