E-Commerce Plugin for cf-cms.js

A complete, production-ready e-commerce solution for cf-cms.js with multi-store support, product management, shopping cart, order processing, payment integration, and digital downloads.

Features

🏪 Multi-Store Support

• Create and manage multiple stores
• Store-specific settings and configurations
• Isolated product catalogs per store
• Multi-currency support

📦 Product Management

• Physical and digital products
• Product variants (size, color, etc.)
• Inventory tracking
• Product categories and tags
• Featured products
• Product images and galleries

🛒 Shopping Cart

• Persistent cart storage
• Cart item management
• Automatic total calculation
• Tax calculation
• Shipping cost integration
• Coupon/discount application

📋 Order Management

• Complete order lifecycle
• Order status tracking
• Order history
• Customer information
• Shipping and billing addresses
• Order notes and metadata

💳 Payment Processing

• Stripe integration
• PayPal integration
• Multiple payment methods per store
• Payment status tracking
• Refund processing
• Webhook support

📥 Digital Downloads

• Secure file storage in R2
• Download link generation
• Download tracking
• Expiration management
• Download limits
• Automatic link generation on order completion

📊 Admin Interface

• Store management dashboard
• Product management interface
• Order management system
• Payment method configuration
• Analytics and reporting

Installation

From NPM

npm install @cf-cms/ecommerce

From Local

cf-cms plugin install ../examples/ecommerce-plugin --local

Configuration

Configure the plugin in your cf-cms.js admin panel:

1. Go to Store → Settings
2. Configure payment methods:
   • Stripe API Key
   • PayPal Client ID
3. Enable/disable digital downloads
4. Set download expiration period

Or via environment variables:

ECOMMERCE_STRIPE_KEY=sk_test_...
ECOMMERCE_PAYPAL_CLIENT_ID=...
ECOMMERCE_ENABLE_DOWNLOADS=true
ECOMMERCE_DOWNLOAD_EXPIRATION=30

API Endpoints

Stores

GET    /api/store              # List stores
POST   /api/store              # Create store
GET    /api/store/:id          # Get store
PUT    /api/store/:id          # Update store
DELETE /api/store/:id          # Delete store

Products

GET    /api/products           # List products
POST   /api/products           # Create product
GET    /api/products/:id       # Get product
PUT    /api/products/:id       # Update product
DELETE /api/products/:id       # Delete product
GET    /api/products/:id/variants    # Get variants
POST   /api/products/:id/variants    # Create variant

Shopping Cart

GET    /api/cart/:cartId       # Get cart
POST   /api/cart/:cartId/items # Add item
PUT    /api/cart/:cartId/items/:itemId  # Update item
DELETE /api/cart/:cartId/items/:itemId  # Remove item
POST   /api/cart/:cartId/checkout       # Checkout

Orders

GET    /api/orders             # List orders
POST   /api/orders             # Create order
GET    /api/orders/:id         # Get order
PUT    /api/orders/:id         # Update order
GET    /api/orders/:id/items   # Get order items
POST   /api/orders/:id/refund  # Process refund

Payments

POST   /api/payments/process   # Process payment
POST   /api/payments/webhook/stripe  # Stripe webhook
POST   /api/payments/webhook/paypal  # PayPal webhook
GET    /api/payments/methods   # Get payment methods

Digital Downloads

GET    /api/downloads/:token   # Download file
GET    /api/downloads/:token/info  # Get download info

Admin Pages

Store Management

• Path: /admin/store
• Features: Create, edit, delete stores
• Permissions: ecommerce:admin

Product Management

• Path: /admin/store/products
• Features: Manage products, variants, inventory
• Permissions: ecommerce:admin

Order Management

• Path: /admin/store/orders
• Features: View, update, fulfill orders
• Permissions: ecommerce:admin

Payment Configuration

• Path: /admin/store/payments
• Features: Configure payment methods
• Permissions: ecommerce:admin

Database Schema

The plugin creates the following tables:

• stores - Store information
• products - Product catalog
• product_variants - Product variants
• product_categories - Product categories
• carts - Shopping carts
• cart_items - Cart items
• orders - Orders
• order_items - Order items
• digital_downloads - Digital product files
• download_links - Download access links
• payment_methods - Payment gateway configuration
• payments - Payment transactions
• refunds - Refund records
• coupons - Discount codes
• shipping_methods - Shipping options

Hooks

The plugin registers hooks for:

• app:ready - Plugin initialization
• content:after:create - Track content creation
• order:after:create - Send order confirmation
• payment:after:process - Generate download links

Usage Examples

Create a Store

curl -X POST http://localhost:8787/api/store \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store",
    "slug": "my-store",
    "currency": "USD",
    "taxRate": 8.5
  }'

Create a Product

curl -X POST http://localhost:8787/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store_123",
    "name": "Awesome Product",
    "slug": "awesome-product",
    "type": "physical",
    "price": 29.99,
    "stockQuantity": 100
  }'

Add to Cart

curl -X POST http://localhost:8787/api/cart/cart_123/items \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_123",
    "quantity": 2,
    "price": 29.99
  }'

Process Payment

curl -X POST http://localhost:8787/api/payments/process \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_123",
    "amount": 59.98,
    "currency": "USD",
    "paymentMethod": "stripe"
  }'

Development

Build

npm run build

Watch Mode

npm run dev

Test

npm test

Performance Considerations

• Products are cached in KV for fast retrieval
• Cart data is stored in D1 with automatic expiration
• Digital downloads use R2 for secure storage
• Payment webhooks are processed asynchronously

Security

• All payment data is encrypted
• Download links use secure tokens
• Database access is scoped to plugin
• Input validation on all endpoints
• CORS headers configured
• Rate limiting on payment endpoints

Troubleshooting

Payment Processing Fails

• Verify Stripe/PayPal credentials
• Check webhook configuration
• Review payment logs in admin panel

Download Links Expire Too Quickly

• Adjust downloadExpirationDays setting
• Check R2 bucket permissions

Cart Not Persisting

• Verify D1 database connection
• Check cart expiration settings

Support

• Documentation: https://docs.cf-cms.js
• Issues: https://github.com/cf-cms/cf-cms/issues
• Discord: https://discord.gg/cf-cms

License

MIT

Changelog

2.0.0

• Complete rewrite for cf-cms.js 2.0
• Multi-store support
• Digital downloads
• Payment gateway integration
• Admin UI integration

1.0.0

• Initial release