Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ylstack-dev/cf-cms-ecommerce) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

Go to Store → Settings
Configure payment methods:
- Stripe API Key
- PayPal Client ID
Enable/disable digital downloads
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