npm - claude-plugin-wordpress-manager - Versions diffs - 2.3.1 → 2.6.0 - Mend

claude-plugin-wordpress-manager 2.3.1 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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)