claude-plugin-wordpress-manager 2.3.1 → 2.4.0

package/skills/wp-social-email/references/distribution-analytics.md

@@ -0,0 +1,208 @@
+# Distribution Analytics
+
+## Overview
+
+Distribution analytics measure the effectiveness of content distributed across email (Mailchimp, SendGrid) and social (Buffer) channels. Tracking performance per channel enables data-driven decisions on content strategy, send timing, and audience targeting.
+
+## Mailchimp Campaign Reports
+
+### Get campaign performance
+
+```
+Tool: mc_get_campaign_report
+Params:
+  campaign_id: "campaign_xyz"
+Returns:
+  emails_sent: 1250
+  opens:
+    total: 487
+    unique: 412
+    rate: 0.33
+  clicks:
+    total: 98
+    unique: 76
+    rate: 0.061
+  bounces:
+    hard: 3
+    soft: 12
+  unsubscribes: 2
+  forwards: 5
+  abuse_reports: 0
+```
+
+### Key Mailchimp metrics
+
+| Metric | Calculation | Benchmark |
+|--------|-------------|-----------|
+| Open rate | Unique opens / Delivered | 20-25% |
+| Click rate | Unique clicks / Delivered | 2.5-5% |
+| Click-to-open rate | Unique clicks / Unique opens | 10-15% |
+| Bounce rate | (Hard + Soft bounces) / Sent | < 2% |
+| Unsubscribe rate | Unsubscribes / Delivered | < 0.5% |
+| List growth rate | (New - Unsubscribes) / Total | > 2% monthly |
+
+### Analyzing campaign trends
+
+Compare multiple campaigns to identify patterns:
+
+```
+# Fetch reports for recent campaigns
+mc_get_campaign_report campaign_id="campaign_1" → { open_rate: 0.28, click_rate: 0.04 }
+mc_get_campaign_report campaign_id="campaign_2" → { open_rate: 0.35, click_rate: 0.07 }
+mc_get_campaign_report campaign_id="campaign_3" → { open_rate: 0.22, click_rate: 0.03 }
+
+# Campaign 2 outperformed — analyze: subject line? send time? content type?
+```
+
+## Buffer Analytics
+
+### Get social profile analytics
+
+```
+Tool: buf_get_analytics
+Params:
+  profile_id: "profile_abc123"
+Returns:
+  posts_count: 45
+  total_reach: 12500
+  total_engagement: 890
+  total_clicks: 234
+  per_post_average:
+    reach: 278
+    engagement: 19.8
+    clicks: 5.2
+```
+
+### Key Buffer metrics
+
+| Metric | Description | Benchmark |
+|--------|-------------|-----------|
+| Reach | Number of unique users who saw the post | Varies by platform |
+| Engagement | Likes + comments + shares + retweets | 1-3% of reach |
+| Engagement rate | Engagement / Reach | 1-5% (varies by platform) |
+| Clicks | Link clicks from post | 0.5-2% of reach |
+| Click-through rate | Clicks / Reach | 1-3% |
+| Best time to post | Time slot with highest engagement | Platform-specific |
+
+### Identifying top-performing content
+
+```
+Tool: buf_list_sent
+Params:
+  profile_id: "profile_abc123"
+  count: 50
+
+# Sort results by engagement metrics to find top performers
+# Re-share top content using buf_create_update with updated text
+```
+
+## SendGrid Statistics
+
+### Get email delivery stats
+
+```
+Tool: sg_get_stats
+Params:
+  start_date: "2026-03-01"
+  end_date: "2026-03-15"
+Returns:
+  - date: "2026-03-01"
+    metrics:
+      requests: 150
+      delivered: 148
+      opens: 52
+      unique_opens: 45
+      clicks: 12
+      unique_clicks: 10
+      bounces: 2
+      spam_reports: 0
+      blocks: 0
+```
+
+### Key SendGrid metrics
+
+| Metric | Calculation | Benchmark |
+|--------|-------------|-----------|
+| Delivery rate | Delivered / Requests | > 95% |
+| Open rate | Unique opens / Delivered | 15-25% (transactional: 40-60%) |
+| Click rate | Unique clicks / Delivered | 2-5% |
+| Bounce rate | Bounces / Requests | < 3% |
+| Spam complaint rate | Spam reports / Delivered | < 0.1% |
+| Block rate | Blocks / Requests | < 1% |
+
+### Transactional vs marketing benchmarks
+
+Transactional emails (welcome, order confirmation) consistently outperform marketing emails:
+
+| Type | Open Rate | Click Rate |
+|------|-----------|------------|
+| Transactional | 40-60% | 10-20% |
+| Marketing | 15-25% | 2-5% |
+
+## Cross-Channel Performance Comparison
+
+### Unified metrics dashboard
+
+Build a cross-channel view by combining data from all three services:
+
+```
+# Email (Mailchimp campaigns)
+mc_get_campaign_report → opens, clicks, unsubscribes
+
+# Social (Buffer)
+buf_get_analytics → reach, engagement, clicks
+
+# Transactional (SendGrid)
+sg_get_stats → deliveries, opens, clicks
+```
+
+### Channel comparison table
+
+| Channel | Reach | Engagement Rate | Click Rate | Cost per Click |
+|---------|-------|-----------------|------------|----------------|
+| Email (Mailchimp) | Audience size | Open rate 20-25% | 2.5-5% | Low |
+| Social (Buffer) | Follower count + viral | 1-5% | 0.5-2% | Free (organic) |
+| Transactional (SendGrid) | Per-event | 40-60% open | 10-20% | Per email |
+
+### Attribution tracking
+
+Use UTM parameters to track which channel drives conversions in WordPress/WooCommerce:
+
+| Channel | UTM Source | UTM Medium | UTM Campaign |
+|---------|-----------|------------|--------------|
+| Mailchimp | `mailchimp` | `email` | `{campaign_name}` |
+| Buffer | `buffer` | `social` | `{post_slug}` |
+| SendGrid | `sendgrid` | `email` | `{template_name}` |
+
+## KPIs and Benchmarks
+
+### Weekly KPIs to track
+
+| KPI | Target | Tool |
+|-----|--------|------|
+| Email open rate | > 22% | `mc_get_campaign_report` |
+| Email click rate | > 3% | `mc_get_campaign_report` |
+| Social engagement rate | > 2% | `buf_get_analytics` |
+| Email delivery rate | > 95% | `sg_get_stats` |
+| List growth (net) | > 50/week | `mc_get_audience_members` count delta |
+| Content distributed | 3+ posts/week | Track distribution events |
+
+### Red flags requiring action
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| Open rate drop | < 15% | Review subject lines, check deliverability |
+| High unsubscribe rate | > 0.5% | Reduce frequency, improve segmentation |
+| Bounce rate spike | > 5% | Clean list, verify new signups |
+| Spam complaints | > 0.1% | Review content, check opt-in process |
+| Social engagement decline | < 0.5% | Refresh content format, test new posting times |
+| Delivery blocks | > 1% | Check domain reputation, review SPF/DKIM |
+
+## Best Practices
+
+- **Weekly review cadence**: Pull analytics every Monday; compare to previous week and 4-week average
+- **A/B test systematically**: Test one variable at a time (subject line, send time, content format) and track results in `mc_get_campaign_report`
+- **Channel-specific goals**: Email optimizes for clicks; social optimizes for engagement; transactional optimizes for delivery
+- **Sunset inactive contacts**: After 90 days of no opens, move contacts to a re-engagement segment or suppress
+- **Document learnings**: Record what subject lines, content types, and send times produce the best results
+- **Automate reporting**: Build a weekly script that calls `mc_get_campaign_report`, `buf_get_analytics`, and `sg_get_stats` to generate a unified report

package/skills/wp-social-email/references/mailchimp-integration.md

@@ -0,0 +1,145 @@
+# Mailchimp Integration
+
+## Overview
+
+Mailchimp is the email marketing platform for audience management and campaign delivery. The WP REST Bridge provides 7 MCP tools (`mc_*`) that cover the full campaign lifecycle: audience management, campaign creation, content setting, sending, and reporting.
+
+## Setup
+
+### API Key Configuration
+
+Add Mailchimp credentials to `WP_SITES_CONFIG`:
+
+```json
+{
+  "sites": [{
+    "name": "my-site",
+    "url": "https://example.com",
+    "distribution": {
+      "mailchimp": {
+        "api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-us14",
+        "server_prefix": "us14"
+      }
+    }
+  }]
+}
+```
+
+The server prefix is the suffix of your API key (e.g., `us14`). All Mailchimp API requests route through `https://{server_prefix}.api.mailchimp.com/3.0/`.
+
+## Audience Management
+
+### List all audiences
+
+```
+Tool: mc_list_audiences
+Returns: Array of audiences with id, name, member count, stats
+```
+
+### Get audience members
+
+```
+Tool: mc_get_audience_members
+Params:
+  audience_id: "abc123def4"
+  count: 50
+  offset: 0
+  status: "subscribed"    # subscribed | unsubscribed | cleaned | pending
+```
+
+### Add a subscriber
+
+```
+Tool: mc_add_subscriber
+Params:
+  audience_id: "abc123def4"
+  email: "user@example.com"
+  status: "subscribed"
+  merge_fields:
+    FNAME: "Jane"
+    LNAME: "Doe"
+  tags: ["wordpress-user", "blog-subscriber"]
+```
+
+If the email already exists, the subscriber record is updated (upsert behavior).
+
+## Campaign Workflow
+
+The campaign lifecycle follows four steps: create → set content → send → report.
+
+### Step 1: Create campaign
+
+```
+Tool: mc_create_campaign
+Params:
+  type: "regular"             # regular | plaintext | absplit
+  audience_id: "abc123def4"
+  subject: "March Newsletter: New Blog Posts"
+  from_name: "My Site"
+  reply_to: "newsletter@example.com"
+Returns: campaign_id
+```
+
+### Step 2: Set campaign content
+
+```
+Tool: mc_set_campaign_content
+Params:
+  campaign_id: "campaign_xyz"
+  html: "<html><body><h1>Newsletter</h1>...</body></html>"
+```
+
+For WordPress content, fetch the post with `wp_get_post` and format the content as HTML for the campaign body.
+
+### Step 3: Send campaign
+
+```
+Tool: mc_send_campaign
+Params:
+  campaign_id: "campaign_xyz"
+  # Or schedule for later:
+  # schedule_time: "2026-03-15T10:00:00Z"
+```
+
+### Step 4: Get report
+
+```
+Tool: mc_get_campaign_report
+Params:
+  campaign_id: "campaign_xyz"
+Returns:
+  emails_sent: 1250
+  opens: { total: 487, unique: 412, rate: 0.33 }
+  clicks: { total: 98, unique: 76, rate: 0.061 }
+  bounces: { hard: 3, soft: 12 }
+  unsubscribes: 2
+```
+
+## A/B Testing
+
+Create an A/B split campaign to test subject lines, content, or send times:
+
+```
+Tool: mc_create_campaign
+Params:
+  type: "absplit"
+  audience_id: "abc123def4"
+  subject: "Version A Subject"
+  variate_settings:
+    test_size: 30           # 30% of audience gets test
+    wait_time: 4            # hours before picking winner
+    winner_criteria: "opens"
+    subject_lines:
+      - "Version A Subject"
+      - "Version B Subject"
+```
+
+## Best Practices
+
+- **Send time optimization**: Analyze `mc_get_campaign_report` data to identify peak open hours; schedule campaigns accordingly
+- **List hygiene**: Regularly check for `cleaned` status members; high bounce rates damage sender reputation
+- **Merge fields**: Use `FNAME` personalization in subject lines — personalized subjects see 20-30% higher open rates
+- **Tags over groups**: Use tags for flexible segmentation; they are easier to manage via API than interest groups
+- **Double opt-in**: Enable for GDPR compliance; set subscriber status to `pending` and let Mailchimp handle the confirmation email
+- **Unsubscribe handling**: Never re-add unsubscribed users; check status before calling `mc_add_subscriber`
+- **Frequency**: Monitor unsubscribe rate per campaign; rates above 0.5% indicate over-sending

package/skills/wp-social-email/references/sendgrid-transactional.md

@@ -0,0 +1,165 @@
+# SendGrid Transactional Email
+
+## Overview
+
+SendGrid handles transactional email delivery — messages triggered by user actions such as account creation, password resets, order confirmations, and notifications. The WP REST Bridge provides 6 MCP tools (`sg_*`) for sending email, managing templates, and tracking contacts.
+
+## Setup
+
+### API Key Configuration
+
+Add SendGrid credentials to `WP_SITES_CONFIG`:
+
+```json
+{
+  "sites": [{
+    "name": "my-site",
+    "url": "https://example.com",
+    "distribution": {
+      "sendgrid": {
+        "api_key": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "from_email": "noreply@example.com",
+        "from_name": "My Site"
+      }
+    }
+  }]
+}
+```
+
+Use a Restricted Access API key with only the permissions needed (Mail Send, Template Engine, Marketing Contacts).
+
+## Transactional Email
+
+### Send a plain email
+
+```
+Tool: sg_send_email
+Params:
+  to: "user@example.com"
+  subject: "Welcome to My Site"
+  html: "<h1>Welcome!</h1><p>Thanks for creating your account.</p>"
+```
+
+### Send with a dynamic template
+
+```
+Tool: sg_send_email
+Params:
+  to: "user@example.com"
+  template_id: "d-abc123def456"
+  dynamic_template_data:
+    first_name: "Jane"
+    order_number: "WC-1042"
+    order_total: "$49.99"
+    order_url: "https://example.com/my-account/orders/1042"
+```
+
+### Common transactional email types
+
+| Type | Trigger | Template Variables |
+|------|---------|-------------------|
+| Welcome email | User registration | `first_name`, `login_url` |
+| Password reset | Password reset request | `reset_link`, `expiry_time` |
+| Order confirmation | WooCommerce order placed | `order_number`, `items`, `total` |
+| Shipping notification | Order status → shipped | `tracking_number`, `carrier`, `eta` |
+| Review request | 7 days after delivery | `product_name`, `review_url` |
+
+## Template Management
+
+### List templates
+
+```
+Tool: sg_list_templates
+Params:
+  generations: "dynamic"    # legacy | dynamic
+Returns: Array of templates with id, name, generation, versions
+```
+
+### Get template details
+
+```
+Tool: sg_get_template
+Params:
+  template_id: "d-abc123def456"
+Returns:
+  id, name, generation
+  versions: [{ id, name, subject, html_content, active }]
+```
+
+Dynamic templates use Handlebars syntax for variable substitution:
+
+```html
+<h1>Hi {{first_name}},</h1>
+<p>Your order #{{order_number}} has been confirmed.</p>
+{{#if tracking_number}}
+  <p>Tracking: {{tracking_number}}</p>
+{{/if}}
+```
+
+## Contact Management
+
+### List contacts
+
+```
+Tool: sg_list_contacts
+Params:
+  # Optional search query using SGQL
+  query: "email LIKE '%@example.com'"
+Returns: Array of contacts with id, email, first_name, last_name, custom_fields
+```
+
+### Add or update contacts
+
+```
+Tool: sg_add_contacts
+Params:
+  list_ids: ["list_abc123"]
+  contacts:
+    - email: "user@example.com"
+      first_name: "Jane"
+      last_name: "Doe"
+      custom_fields:
+        wp_user_id: "42"
+        signup_source: "blog"
+```
+
+Contacts are upserted by email address. If the email already exists, fields are merged.
+
+## WordPress Integration Patterns
+
+### New user → Welcome email
+
+```
+1. WordPress user_register event triggers webhook
+2. Webhook handler calls sg_send_email with welcome template
+3. sg_add_contacts adds user to "New Users" contact list
+```
+
+### WooCommerce order → Confirmation email
+
+```
+1. order.created webhook fires
+2. Extract order details (number, items, total)
+3. sg_send_email with order confirmation template + dynamic data
+```
+
+### Blog subscriber → Drip sequence
+
+```
+1. Newsletter form submission adds subscriber via mc_add_subscriber
+2. sg_send_email sends immediate welcome/confirmation
+3. Scheduled follow-ups via campaign automation
+```
+
+## Best Practices
+
+- **SPF/DKIM/DMARC**: Configure DNS records for your sending domain; without these, emails land in spam
+  - SPF: Add SendGrid's include to your TXT record
+  - DKIM: Create CNAME records provided by SendGrid domain authentication
+  - DMARC: Start with `p=none` policy, move to `p=quarantine` after monitoring
+- **Dedicated IP**: For volumes above 50k emails/month, use a dedicated IP and warm it gradually (start with 100/day, increase over 4 weeks)
+- **Bounce handling**: Monitor `sg_get_stats` for bounce rates; rates above 5% trigger SendGrid compliance review
+- **Unsubscribe**: Include an unsubscribe link in every email (required by CAN-SPAM); use SendGrid's built-in unsubscribe groups
+- **Template versioning**: Keep templates in version control; use SendGrid's active version feature to deploy changes safely
+- **Rate limiting**: SendGrid enforces rate limits per API key; batch contact additions in groups of 1000
+- **From address consistency**: Use the same `from_email` across all transactional messages to build domain reputation

package/skills/wp-social-email/scripts/distribution_inspect.mjs

@@ -0,0 +1,165 @@
+/**
+ * distribution_inspect.mjs — Detect social/email distribution configuration.
+ *
+ * Checks WP_SITES_CONFIG for connector API keys, WordPress plugins,
+ * and content readiness for distribution.
+ *
+ * Usage:
+ *   node distribution_inspect.mjs [--cwd=/path/to/project]
+ *
+ * Exit codes:
+ *   0 — distribution configuration found
+ *   1 — no distribution configuration found
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { argv, stdout, exit } from 'node:process';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readFileSafe(filePath) {
+  try { return readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function existsSafe(filePath) {
+  try { return existsSync(filePath); } catch { return false; }
+}
+
+function globDir(dirPath) {
+  try { return readdirSync(dirPath); } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Detectors
+// ---------------------------------------------------------------------------
+
+function detectServices() {
+  const services = {
+    mailchimp: { configured: false, indicators: [] },
+    buffer: { configured: false, indicators: [] },
+    sendgrid: { configured: false, indicators: [] },
+  };
+
+  const raw = process.env.WP_SITES_CONFIG;
+  if (!raw) return services;
+
+  let sites;
+  try { sites = JSON.parse(raw); } catch { return services; }
+  if (!Array.isArray(sites)) return services;
+
+  for (const site of sites) {
+    const label = site.name || site.url || 'unknown';
+
+    if (site.mailchimp_api_key) {
+      services.mailchimp.configured = true;
+      services.mailchimp.indicators.push(`mailchimp_api_key configured for ${label}`);
+    }
+    if (site.buffer_access_token) {
+      services.buffer.configured = true;
+      services.buffer.indicators.push(`buffer_access_token configured for ${label}`);
+    }
+    if (site.sendgrid_api_key) {
+      services.sendgrid.configured = true;
+      services.sendgrid.indicators.push(`sendgrid_api_key configured for ${label}`);
+    }
+  }
+
+  return services;
+}
+
+function detectDistributionPlugins(cwd) {
+  const indicators = [];
+  const plugins = globDir(join(cwd, 'wp-content', 'plugins'));
+
+  const distributionPlugins = [
+    'mailchimp-for-wp', 'mc4wp',
+    'jetpack',
+    'social-warfare', 'monarch', 'shared-counts',
+    'newsletter', 'email-subscribers',
+  ];
+
+  for (const plugin of plugins) {
+    if (distributionPlugins.some(dp => plugin.toLowerCase().includes(dp))) {
+      indicators.push(`distribution_plugin: ${plugin}`);
+    }
+  }
+
+  return { found: indicators.length > 0, indicators };
+}
+
+function detectContentReadiness(cwd) {
+  // Check wp-content directory exists
+  if (!existsSafe(join(cwd, 'wp-content'))) return false;
+
+  // Check for posts/content indicators
+  const uploads = globDir(join(cwd, 'wp-content', 'uploads'));
+  if (uploads.length > 0) return true;
+
+  // Check for themes (site is set up)
+  const themes = globDir(join(cwd, 'wp-content', 'themes'));
+  if (themes.length > 0) return true;
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const cwdArg = argv.find(a => a.startsWith('--cwd='));
+  const cwd = cwdArg ? resolve(cwdArg.split('=')[1]) : process.cwd();
+
+  const services = detectServices();
+  const plugins = detectDistributionPlugins(cwd);
+  const contentReady = detectContentReadiness(cwd);
+
+  const hasServices = services.mailchimp.configured ||
+                      services.buffer.configured ||
+                      services.sendgrid.configured;
+  const found = hasServices || plugins.found;
+
+  const recommendations = [];
+
+  if (services.mailchimp.configured) {
+    recommendations.push('Mailchimp configured — use distribution_send skill to create and send email campaigns');
+  }
+  if (services.buffer.configured) {
+    recommendations.push('Buffer configured — use distribution_send skill to schedule social media posts');
+  }
+  if (services.sendgrid.configured) {
+    recommendations.push('SendGrid configured — use distribution_send skill for transactional and marketing emails');
+  }
+  if (plugins.found) {
+    recommendations.push('Distribution plugins detected — check plugin settings for additional integration opportunities');
+  }
+  if (!found) {
+    recommendations.push('No distribution configuration detected — use wp-social-email skill to set up Mailchimp, Buffer, or SendGrid');
+  }
+  if (!contentReady) {
+    recommendations.push('No content detected — create posts before setting up distribution workflows');
+  }
+  if (found && contentReady) {
+    recommendations.push('Distribution services and content are ready — consider scheduling an automated campaign');
+  }
+
+  const report = {
+    tool: 'distribution_inspect',
+    version: '1.0.0',
+    timestamp: new Date().toISOString(),
+    cwd,
+    found,
+    services,
+    plugins,
+    content_ready: contentReady,
+    recommendations,
+  };
+
+  stdout.write(JSON.stringify(report, null, 2) + '\n');
+  exit(found ? 0 : 1);
+}
+
+main();

package/skills/wp-webhooks/SKILL.md

@@ -105,3 +105,4 @@ See `references/payload-formats.md`
 - **`wp-headless`** — headless revalidation webhooks and ISR triggers
 - **`wp-woocommerce`** — WooCommerce store operations (webhook source events)
 - **`wp-cicd`** — CI/CD webhooks for deployment triggers
+- **wp-social-email** — direct publishing to social/email (alternative to webhook-based distribution)