commercevault-edd-digital-commerce

# CommerceVault EDD Digital Commerce Skill > Skill by [ara.so](https://ara.so) — Data Skills collection. ## Overview CommerceVault (mcp-edd-analytics-vantage) is a middleware orchestrator that provides a unified, secure interface to Easy Digital Downloads (EDD) WordPress stores. It abstracts the EDD REST API with enhanced features including cryptographic verification, adaptive rate limiting, caching, analytics aggregation, and webhook management. The system uses hexagonal architecture with pluggable adapters, making it extensible to other e-commerce platforms while maintaining consistent interfaces. **Key Capabilities:** - Product catalog synchronization with delta updates - Order lifecycle management (creation, fulfillment, refunds) - Customer segmentation and lifetime value tracking - Real-time analytics (GMV, AOV, churn, cohort analysis) - License key and entitlement management for digital products - Multilingual support (17 languages) - HMAC payload verification for data integrity ## Installation ### Prerequisites - Node.js 18+ or Python 3.9+ (depending on client SDK) - Access to an EDD-enabled WordPress site - EDD REST API credentials (consumer key and secret) - Redis (optional, for caching layer) ### NPM Installation (Node.js) ```bash npm install @commercevault/edd-client ``` ### Python Installation ```bash pip install commercevault-edd ``` ### Docker Deployment ```bash docker pull commercevault/edd-orchestrator:latest docker run -d \ -p 8080:8080 \ -e EDD_API_URL=$EDD_API_URL \ -e EDD_CONSUMER_KEY=$EDD_CONSUMER_KEY \ -e EDD_CONSUMER_SECRET=$EDD_CONSUMER_SECRET \ -e REDIS_URL=$REDIS_URL \ commercevault/edd-orchestrator:latest ``` ### Environment Variables ```bash # Required EDD_API_URL=https://your-store.com EDD_CONSUMER_KEY=ck_xxxxxxxxxxxxx EDD_CONSUMER_SECRET=cs_xxxxxxxxxxxxx # Optional REDIS_URL=redis://localhost:6379 CACHE_TTL=3600 RATE_LIMIT_REQUESTS=100 RATE_LIMIT_WINDOW=60 HMAC_SECRET_KEY=$HMAC_SECRET_KEY LOG_LEVEL=info ``` ## Configuration ### Basic Configuration (Node.js) ```javascript const { CommerceVaultClient } = require('@commercevault/edd-client'); const client = new CommerceVaultClient({ apiUrl: process.env.EDD_API_URL, consumerKey: process.env.EDD_CONSUMER_KEY, consumerSecret: process.env.EDD_CONSUMER_SECRET, hmacSecret: process.env.HMAC_SECRET_KEY, enableCache: true, cacheTTL: 3600, timeout: 30000 }); ``` ### Advanced Configuration with Middleware ```javascript const client = new CommerceVaultClient({ apiUrl: process.env.EDD_API_URL, consumerKey: process.env.EDD_CONSUMER_KEY, consumerSecret: process.env.EDD_CONSUMER_SECRET, middleware: [ // Geo-fencing middleware { name: 'geoFilter', handler: async (request, next) => { if (request.customer.country === 'RESTRICTED') { throw new Error('Region not supported'); } return next(request); } }, // Currency normalization { name: 'currencyNormalizer', handler: async (request, next) => { const response = await next(request); response.data.amount = convertToBaseCurrency( response.data.amount, response.data.currency ); return response; } } ], rateLimiting: { maxRequests: 100, windowSeconds: 60, strategy: 'adaptive' } }); ``` ## Core API Methods ### Product Operations #### Fetch All Products ```javascript // Retrieve product catalog with pagination const products = await client.products.list({ page: 1, perPage: 50, status: 'publish', orderBy: 'date', order: 'desc' }); console.log(`Found ${products.total} products`); products.items.forEach(product => { console.log(`${product.id}: ${product.title} - $${product.price}`); }); ``` #### Get Single Product ```javascript const product = await client.products.get(12345); console.log(`Product: ${product.title}`); console.log(`SKU: ${product.sku}`); console.log(`Price: $${product.price}`); console.log(`Downloads: ${product.sales_count}`); console.log(`Licensing: ${product.licensing_enabled}`); ``` #### Delta Sync Products ```javascript // Only fetch products modified since last sync const lastSyncTime = '2026-07-01T00:00:00Z'; const changedProducts = await client.products.listDelta({ modifiedSince: lastSyncTime, includeDeleted: true }); console.log(`${changedProducts.added.length} new products`); console.log(`${changedProducts.updated.length} updated products`); console.log(`${changedProducts.deleted.length} deleted products`); ``` ### Order Operations #### Retrieve Orders ```javascript // Fetch recent orders with filtering const orders = await client.orders.list({ status: ['completed', 'processing'], dateFrom: '2026-07-01', dateTo: '2026-07-12', perPage: 100 }); let totalRevenue = 0; orders.items.forEach(order => { totalRevenue += parseFloat(order.total); console.log(`Order #${order.number}: $${order.total} - ${order.status}`); }); console.log(`Total Revenue: $${totalRevenue.toFixed(2)}`); ``` #### Get Single Order with Line Items ```javascript const order = await client.orders.get(98765, { includeLineItems: true, includeCustomer: true, includeLicenses: true }); console.log(`Order: #${order.number}`); console.log(`Customer: ${order.customer.email}`); console.log(`Total: $${order.total}`); order.lineItems.forEach(item => { console.log(` - ${item.product_name} x${item.quantity}: $${item.subtotal}`); if (item.licenses) { console.log(` License Key: ${item.licenses[0].key}`); } }); ``` #### Create Order Programmatically ```javascript const newOrder = await client.orders.create({ customer: { email: 'customer@example.com', firstName: 'Jane', lastName: 'Doe' }, lineItems: [ { productId: 123, quantity: 1, priceId: 0 // Default price } ], paymentMethod: 'stripe', status: 'pending', metadata: { source: 'api', campaign: 'summer-sale' } }); console.log(`Created order #${newOrder.number}`); console.log(`Payment URL: ${newOrder.paymentUrl}`); ``` #### Process Refund ```javascript const refund = await client.orders.refund(98765, { amount: 29.99, reason: 'Customer requested refund', revokeLicenses: true, notifyCustomer: true }); console.log(`Refund ID: ${refund.id}`); console.log(`Amount: $${refund.amount}`); console.log(`Status: ${refund.status}`); ``` ### Customer Operations #### Fetch Customer Data ```javascript const customer = await client.customers.get(4567, { includeOrders: true, includeStats: true }); console.log(`Customer: ${customer.email}`); console.log(`Total Orders: ${customer.stats.orderCount}`); console.log(`Lifetime Value: $${customer.stats.lifetimeValue}`); console.log(`Average Order Value: $${customer.stats.averageOrderValue}`); console.log(`Last Purchase: ${customer.stats.lastPurchaseDate}`); ``` #### Customer Segmentation ```javascript // Find high-value customers const segments = await client.customers.segment({ criteria: { lifetimeValueMin: 500, orderCountMin: 5, lastPurchaseDays: 90 }, limit: 100 }); console.log(`Found ${segments.customers.length} VIP customers`); // Export to CRM await client.customers.exportSegment(segments.id, { format: 'csv', destination: 's3://bucket/segments/vip-customers.csv' }); ``` ### Analytics & Reporting #### Revenue Analytics ```javascript const analytics = await client.analytics.revenue({ dateFrom: '2026-06-01', dateTo: '2026-06-30', groupBy: 'day', includeTax: true, includeRefunds: true }); console.log(`Total Revenue: $${analytics.totalRevenue}`); console.log(`Gross Merchandise Value: $${analytics.gmv}`); console.log(`Average Order Value: $${analytics.aov}`); console.log(`Order Count: ${analytics.orderCount}`); // Daily breakdown analytics.timeSeries.forEach(day => { console.log(`${day.date}: $${day.revenue} (${day.orders} orders)`); }); ``` #### Product Performance ```javascript const productStats = await client.analytics.productPerformance({ dateFrom: '2026-06-01', dateTo: '2026-06-30', limit: 10, sortBy: 'revenue' }); console.log('Top 10 Products by Revenue:'); productStats.products.forEach((product, index) => { console.log(`${index + 1}. ${product.name}`); console.log(` Revenue: $${product.revenue}`); console.log(` Units Sold: ${product.unitsSold}`); console.log(` Conversion Rate: ${product.conversionRate}%`); }); ``` #### Cohort Analysis ```javascript const cohorts = await client.analytics.cohortAnalysis({ cohortType: 'month', dateFrom: '2026-01-01', dateTo: '2026-06-30', metric: 'revenue' }); cohorts.cohorts.forEach(cohort => { console.log(`Cohort: ${cohort.period}`); console.log(`Customers: ${cohort.customerCount}`); console.log(`Month 0: $${cohort.periods[0]}`); console.log(`Month 1: $${cohort.periods[1]}`); console.log(`Month 3: $${cohort.periods[3]}`); console.log(`Retention Rate: ${cohort.retentionRate}%`); }); ``` ### License Management #### Generate License Keys ```javascript const licenses = await client.licenses.generate({ productId: 123, quantity: 50, expirationDays: 365, activationLimit: 3, metadata: { batch: 'bulk-order-2026', distributor: 'partner-xyz' } }); console.log(`Generated ${licenses.keys.length} licenses`); licenses.keys.forEach(license => { console.log(`Key: ${license.key}`); console.log(`Expires: ${license.expirationDate}`); }); ``` #### Validate License ```javascript const validation = await client.licenses.validate({ key: 'XXXX-XXXX-XXXX-XXXX', productId: 123, siteUrl: 'https://customer-site.com' }); if (validation.valid) { console.log('License is valid'); console.log(`Activations: ${validation.activationCount}/${validation.activationLimit}`);