From 74f2c99c7cce9b282e5f7b59c3dc8cb5c4f34970 Mon Sep 17 00:00:00 2001 From: Bas van den Aakster Date: Sun, 14 Sep 2025 23:21:43 +0200 Subject: [PATCH] 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. --- README.md | 183 +++++++++++++----------------------------- dev/payload.config.ts | 27 ++----- eslint.config.js | 17 ++++ 3 files changed, 80 insertions(+), 147 deletions(-) diff --git a/README.md b/README.md index e3df45f..736490e 100644 --- a/README.md +++ b/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. -## ๐Ÿš€ Features +## Features -### Payment Providers -- **๐Ÿ”ถ Stripe Integration** - Full Stripe payment processing support -- **๐ŸŸ  Mollie Integration** - Complete Mollie payment gateway integration -- **๐Ÿงช Test Provider** - Local development and testing payment provider -- **๐Ÿ”ง Extensible Architecture** - Easy to add new payment providers +- ๐Ÿ’ณ Multiple payment providers (Stripe, Mollie, Test) +- ๐Ÿงพ Invoice generation and management +- ๐Ÿ‘ฅ Customer profiles with billing information +- ๐Ÿ“Š Complete payment tracking and history +- ๐Ÿช Secure webhook processing for all providers +- ๐Ÿงช Built-in test provider for local development +- ๐Ÿ“ฑ Payment management in PayloadCMS admin +- ๐Ÿ”’ Full TypeScript support -### Payment Tracking & Management -- **๐Ÿ“Š 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 +## Installation ```bash npm install @xtr-dev/payload-billing # or -yarn add @xtr-dev/payload-billing -# or pnpm add @xtr-dev/payload-billing +# or +yarn add @xtr-dev/payload-billing ``` -## โš™๏ธ Quick Setup +## Quick Start ```typescript +import { buildConfig } from 'payload' import { billingPlugin } from '@xtr-dev/payload-billing' export default buildConfig({ + // ... your config plugins: [ billingPlugin({ providers: { @@ -60,136 +45,78 @@ export default buildConfig({ apiKey: process.env.MOLLIE_API_KEY!, webhookUrl: process.env.MOLLIE_WEBHOOK_URL!, }, - // Test provider for local development test: { 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 +// Main plugin +import { billingPlugin } from '@xtr-dev/payload-billing' + +// Provider utilities import { getPaymentProvider } from '@xtr-dev/payload-billing' -const stripe = getPaymentProvider('stripe') - -// 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) +// Types +import type { PaymentProvider, CreatePaymentOptions, Payment } from '@xtr-dev/payload-billing' ``` -### Mollie Integration -```typescript -const mollie = getPaymentProvider('mollie') +## Provider Types -// Create a payment -const payment = await mollie.createPayment({ - amount: { value: '20.00', currency: 'EUR' }, - description: 'Order #12345', - redirectUrl: 'https://example.com/return', - webhookUrl: 'https://example.com/webhook' -}) -``` +### Stripe +Credit card payments, subscriptions, webhook processing, automatic payment method storage. + +### Mollie +European payment methods (iDEAL, SEPA, etc.), multi-currency support, refund processing. ### Test Provider -```typescript -const testProvider = getPaymentProvider('test') +Local development testing with configurable scenarios, automatic completion, debug mode. -// Simulate payment scenarios -const payment = await testProvider.createPayment({ - amount: 2000, - currency: 'usd', - // Test-specific options - simulateFailure: false, - delayMs: 1000 -}) -``` +## Collections -## ๐Ÿช 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 -- `/api/billing/webhooks/mollie` - Mollie webhook endpoint -- `/api/billing/webhooks/test` - Test provider webhook endpoint +## Webhook Endpoints -## ๐Ÿ› ๏ธ 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 -# Clone the repository -git clone https://github.com/xtr-dev/payload-billing.git -cd payload-billing - # Install dependencies pnpm install -# Build the plugin +# Build plugin pnpm build # Run tests pnpm test -# Start development server +# Development server pnpm dev ``` -## ๐Ÿ“š Documentation +## License -- [API Reference](./docs/api.md) -- [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) +MIT \ No newline at end of file diff --git a/dev/payload.config.ts b/dev/payload.config.ts index 4b1f10f..74bbea1 100644 --- a/dev/payload.config.ts +++ b/dev/payload.config.ts @@ -1,9 +1,8 @@ -import { mongooseAdapter } from '@payloadcms/db-mongodb' +import { sqliteAdapter } from '@payloadcms/db-sqlite' import { lexicalEditor } from '@payloadcms/richtext-lexical' -import { MongoMemoryReplSet } from 'mongodb-memory-server' import path from 'path' import { buildConfig } from 'payload' -import { billingPlugin } from '../src/index.js' +import { billingPlugin } from '../dist/index.js' import sharp from 'sharp' import { fileURLToPath } from 'url' @@ -17,18 +16,7 @@ if (!process.env.ROOT_DIR) { process.env.ROOT_DIR = dirname } -const buildConfigWithMemoryDB = async () => { - if (process.env.NODE_ENV === 'test') { - const memoryDB = await MongoMemoryReplSet.create({ - replSet: { - count: 3, - dbName: 'payloadmemory', - }, - }) - - process.env.DATABASE_URI = `${memoryDB.getUri()}&retryWrites=true` - } - +const buildConfigWithSQLite = () => { return buildConfig({ admin: { importMap: { @@ -48,9 +36,10 @@ const buildConfigWithMemoryDB = async () => { }, }, ], - db: mongooseAdapter({ - ensureIndexes: true, - url: process.env.DATABASE_URI || '', + db: sqliteAdapter({ + client: { + url: `file:${path.resolve(dirname, 'payload.sqlite')}`, + }, }), editor: lexicalEditor(), email: testEmailAdapter, @@ -81,4 +70,4 @@ const buildConfigWithMemoryDB = async () => { }) } -export default buildConfigWithMemoryDB() +export default buildConfigWithSQLite() diff --git a/eslint.config.js b/eslint.config.js index 958e859..aacea9f 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -27,6 +27,23 @@ export default [ { rules: { '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', }, }, {