claude-plugin-wordpress-manager 2.3.0 → 2.4.0

package/servers/wp-rest-bridge/build/tools/sendgrid.js

@@ -0,0 +1,255 @@
+import { makeSendGridRequest, hasSendGrid } from '../wordpress.js';
+import { z } from 'zod';
+// ── Zod Schemas ─────────────────────────────────────────────────
+const sgSendEmailSchema = z.object({
+    to_email: z.string().describe('Recipient email address'),
+    to_name: z.string().optional().describe('Recipient name'),
+    from_email: z.string().describe('Sender email address'),
+    from_name: z.string().optional().describe('Sender name'),
+    subject: z.string().describe('Email subject line'),
+    content_type: z.string().optional().default('text/html')
+        .describe('Content MIME type (default: text/html)'),
+    content_value: z.string().describe('Email body content'),
+    template_id: z.string().optional()
+        .describe('SendGrid dynamic template ID (overrides content)'),
+}).strict();
+const sgListTemplatesSchema = z.object({
+    generations: z.enum(['legacy', 'dynamic']).optional()
+        .describe('Filter by template generation type'),
+    page_size: z.number().optional()
+        .describe('Number of templates per page'),
+}).strict();
+const sgGetTemplateSchema = z.object({
+    template_id: z.string().describe('SendGrid template ID'),
+}).strict();
+const sgListContactsSchema = z.object({
+    query: z.string().optional()
+        .describe('SGQL query string for filtering contacts'),
+}).strict();
+const sgAddContactsSchema = z.object({
+    contacts: z.array(z.object({
+        email: z.string().describe('Contact email address'),
+        first_name: z.string().optional().describe('Contact first name'),
+        last_name: z.string().optional().describe('Contact last name'),
+        custom_fields: z.record(z.any()).optional().describe('Custom field key-value pairs'),
+    })).describe('Array of contacts to add or update'),
+}).strict();
+const sgGetStatsSchema = z.object({
+    start_date: z.string().describe('Start date in YYYY-MM-DD format'),
+    end_date: z.string().optional().describe('End date in YYYY-MM-DD format'),
+    aggregated_by: z.enum(['day', 'week', 'month']).optional()
+        .describe('Aggregation period for stats'),
+}).strict();
+// ── Tool Definitions ────────────────────────────────────────────
+export const sendgridTools = [
+    {
+        name: "sg_send_email",
+        description: "Sends a transactional email via SendGrid (DESTRUCTIVE — sends real email)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to_email: { type: "string", description: "Recipient email address" },
+                to_name: { type: "string", description: "Recipient name" },
+                from_email: { type: "string", description: "Sender email address" },
+                from_name: { type: "string", description: "Sender name" },
+                subject: { type: "string", description: "Email subject line" },
+                content_type: { type: "string", description: "Content MIME type (default: text/html)" },
+                content_value: { type: "string", description: "Email body content" },
+                template_id: { type: "string", description: "SendGrid dynamic template ID (overrides content)" },
+            },
+            required: ["to_email", "from_email", "subject", "content_value"],
+        },
+    },
+    {
+        name: "sg_list_templates",
+        description: "Lists all SendGrid email templates",
+        inputSchema: {
+            type: "object",
+            properties: {
+                generations: {
+                    type: "string",
+                    enum: ["legacy", "dynamic"],
+                    description: "Filter by template generation type",
+                },
+                page_size: { type: "number", description: "Number of templates per page" },
+            },
+        },
+    },
+    {
+        name: "sg_get_template",
+        description: "Gets a specific SendGrid template with its versions",
+        inputSchema: {
+            type: "object",
+            properties: {
+                template_id: { type: "string", description: "SendGrid template ID" },
+            },
+            required: ["template_id"],
+        },
+    },
+    {
+        name: "sg_list_contacts",
+        description: "Lists SendGrid Marketing contacts with optional search",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "SGQL query string for filtering contacts" },
+            },
+        },
+    },
+    {
+        name: "sg_add_contacts",
+        description: "Adds or updates contacts in SendGrid Marketing",
+        inputSchema: {
+            type: "object",
+            properties: {
+                contacts: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            email: { type: "string", description: "Contact email address" },
+                            first_name: { type: "string", description: "Contact first name" },
+                            last_name: { type: "string", description: "Contact last name" },
+                            custom_fields: { type: "object", description: "Custom field key-value pairs" },
+                        },
+                        required: ["email"],
+                    },
+                    description: "Array of contacts to add or update",
+                },
+            },
+            required: ["contacts"],
+        },
+    },
+    {
+        name: "sg_get_stats",
+        description: "Gets email delivery statistics for a date range",
+        inputSchema: {
+            type: "object",
+            properties: {
+                start_date: { type: "string", description: "Start date in YYYY-MM-DD format" },
+                end_date: { type: "string", description: "End date in YYYY-MM-DD format" },
+                aggregated_by: {
+                    type: "string",
+                    enum: ["day", "week", "month"],
+                    description: "Aggregation period for stats",
+                },
+            },
+            required: ["start_date"],
+        },
+    },
+];
+// ── Handlers ────────────────────────────────────────────────────
+export const sendgridHandlers = {
+    sg_send_email: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { to_email, to_name, from_email, from_name, subject, content_type, content_value, template_id } = params;
+            const body = {
+                personalizations: [{ to: [{ email: to_email, ...(to_name ? { name: to_name } : {}) }], subject }],
+                from: { email: from_email, ...(from_name ? { name: from_name } : {}) },
+                subject,
+                content: [{ type: content_type || 'text/html', value: content_value }],
+            };
+            if (template_id)
+                body.template_id = template_id;
+            const response = await makeSendGridRequest("POST", "mail/send", body);
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response ?? { success: true, message: "Email sent successfully" }, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error sending email: ${errorMessage}` }] } };
+        }
+    },
+    sg_list_templates: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { generations, page_size } = params;
+            const query = {};
+            if (generations)
+                query.generations = generations;
+            if (page_size !== undefined)
+                query.page_size = page_size;
+            const qs = Object.entries(query).map(([k, v]) => `${k}=${v}`).join('&');
+            const endpoint = `templates${qs ? '?' + qs : ''}`;
+            const response = await makeSendGridRequest("GET", endpoint);
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error listing templates: ${errorMessage}` }] } };
+        }
+    },
+    sg_get_template: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { template_id } = params;
+            const response = await makeSendGridRequest("GET", `templates/${template_id}`);
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error getting template: ${errorMessage}` }] } };
+        }
+    },
+    sg_list_contacts: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { query } = params;
+            let response;
+            if (query) {
+                response = await makeSendGridRequest("POST", "marketing/contacts/search", { query });
+            }
+            else {
+                response = await makeSendGridRequest("GET", "marketing/contacts");
+            }
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error listing contacts: ${errorMessage}` }] } };
+        }
+    },
+    sg_add_contacts: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { contacts } = params;
+            const response = await makeSendGridRequest("PUT", "marketing/contacts", { contacts });
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error adding contacts: ${errorMessage}` }] } };
+        }
+    },
+    sg_get_stats: async (params) => {
+        if (!hasSendGrid()) {
+            return { toolResult: { isError: true, content: [{ type: "text", text: "SendGrid not configured. Add sendgrid_api_key to WP_SITES_CONFIG." }] } };
+        }
+        try {
+            const { start_date, end_date, aggregated_by } = params;
+            const query = { start_date };
+            if (end_date)
+                query.end_date = end_date;
+            if (aggregated_by)
+                query.aggregated_by = aggregated_by;
+            const qs = Object.entries(query).map(([k, v]) => `${k}=${v}`).join('&');
+            const endpoint = `stats?${qs}`;
+            const response = await makeSendGridRequest("GET", endpoint);
+            return { toolResult: { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] } };
+        }
+        catch (error) {
+            const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
+            return { toolResult: { isError: true, content: [{ type: "text", text: `Error getting stats: ${errorMessage}` }] } };
+        }
+    },
+};

package/servers/wp-rest-bridge/build/types.d.ts

@@ -258,4 +258,126 @@ export interface WPNetworkSite {
     spam: boolean;
     deleted: boolean;
 }
+export interface MCMailchimpAudience {
+    id: string;
+    name: string;
+    member_count: number;
+    campaign_defaults: {
+        from_name: string;
+        from_email: string;
+        subject: string;
+    };
+    stats: {
+        member_count: number;
+        unsubscribe_count: number;
+        open_rate: number;
+        click_rate: number;
+    };
+    date_created: string;
+}
+export interface MCCampaign {
+    id: string;
+    type: string;
+    status: string;
+    emails_sent: number;
+    send_time: string;
+    settings: {
+        subject_line: string;
+        from_name: string;
+        reply_to: string;
+    };
+    report_summary?: {
+        opens: number;
+        unique_opens: number;
+        clicks: number;
+        subscriber_clicks: number;
+    };
+}
+export interface MCCampaignReport {
+    id: string;
+    campaign_title: string;
+    emails_sent: number;
+    opens: {
+        opens_total: number;
+        unique_opens: number;
+        open_rate: number;
+    };
+    clicks: {
+        clicks_total: number;
+        unique_clicks: number;
+        click_rate: number;
+    };
+    unsubscribed: number;
+    bounces: {
+        hard_bounces: number;
+        soft_bounces: number;
+    };
+}
+export interface BufProfile {
+    id: string;
+    service: string;
+    formatted_username: string;
+    avatar: string;
+    counts: {
+        sent: number;
+        pending: number;
+    };
+}
+export interface BufUpdate {
+    id: string;
+    text: string;
+    profile_id: string;
+    status: string;
+    sent_at?: number;
+    due_at?: number;
+    statistics?: {
+        clicks: number;
+        reach: number;
+        impressions: number;
+    };
+}
+export interface SGEmailRequest {
+    personalizations: {
+        to: {
+            email: string;
+            name?: string;
+        }[];
+        subject?: string;
+    }[];
+    from: {
+        email: string;
+        name?: string;
+    };
+    subject: string;
+    content: {
+        type: string;
+        value: string;
+    }[];
+    template_id?: string;
+}
+export interface SGTemplate {
+    id: string;
+    name: string;
+    generation: string;
+    updated_at: string;
+    versions: {
+        id: string;
+        name: string;
+        active: number;
+        subject: string;
+    }[];
+}
+export interface SGStats {
+    date: string;
+    stats: {
+        metrics: {
+            requests: number;
+            delivered: number;
+            opens: number;
+            clicks: number;
+            bounces: number;
+            spam_reports: number;
+        };
+    }[];
+}
 export {};

package/servers/wp-rest-bridge/build/wordpress.d.ts

@@ -11,6 +11,9 @@ interface SiteConfig {
     ssh_key?: string;
     ssh_port?: number;
     is_multisite?: boolean;
+    mailchimp_api_key?: string;
+    buffer_access_token?: string;
+    sendgrid_api_key?: string;
 }
 /**
  * Parse WP_SITES_CONFIG JSON and initialize all site clients
@@ -69,6 +72,12 @@ export declare function hasWooCommerce(siteId?: string): boolean;
  * Uses Consumer Key/Secret auth and wc/v3 namespace by default.
  */
 export declare function makeWooCommerceRequest(method: string, endpoint: string, data?: any, options?: WordPressRequestOptions): Promise<any>;
+export declare function hasMailchimp(siteId?: string): boolean;
+export declare function makeMailchimpRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
+export declare function hasBuffer(siteId?: string): boolean;
+export declare function makeBufferRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
+export declare function hasSendGrid(siteId?: string): boolean;
+export declare function makeSendGridRequest(method: string, endpoint: string, data?: any, siteId?: string): Promise<any>;
 /**
  * Search the WordPress.org Plugin Repository
  */

package/servers/wp-rest-bridge/build/wordpress.js

@@ -32,6 +32,9 @@ class ConcurrencyLimiter {
 const siteClients = new Map();
 const siteLimiters = new Map();
 const wcSiteClients = new Map();
+const mcSiteClients = new Map();
+const bufSiteClients = new Map();
+const sgSiteClients = new Map();
 let activeSiteId = '';
 const parsedSiteConfigs = new Map();
 const MAX_CONCURRENT_PER_SITE = 5;
@@ -84,6 +87,18 @@ export async function initWordPress() {
             await initWcClient(site.id, site.url, site.wc_consumer_key, site.wc_consumer_secret);
             logToStderr(`Initialized WooCommerce for site: ${site.id}`);
         }
+        if (site.mailchimp_api_key) {
+            await initMailchimpClient(site.id, site.mailchimp_api_key);
+            logToStderr(`Initialized Mailchimp for site: ${site.id}`);
+        }
+        if (site.buffer_access_token) {
+            await initBufferClient(site.id, site.buffer_access_token);
+            logToStderr(`Initialized Buffer for site: ${site.id}`);
+        }
+        if (site.sendgrid_api_key) {
+            await initSendGridClient(site.id, site.sendgrid_api_key);
+            logToStderr(`Initialized SendGrid for site: ${site.id}`);
+        }
     }
     activeSiteId = defaultSite || sites[0].id;
     logToStderr(`Active site: ${activeSiteId}`);
@@ -152,6 +167,40 @@ async function initWcClient(id, url, consumerKey, consumerSecret) {
     }
     wcSiteClients.set(id, client);
 }
+async function initMailchimpClient(id, apiKey) {
+    const dc = apiKey.split('-').pop() || 'us21';
+    const client = axios.create({
+        baseURL: `https://${dc}.api.mailchimp.com/3.0/`,
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Basic ${Buffer.from(`anystring:${apiKey}`).toString('base64')}`,
+        },
+        timeout: DEFAULT_TIMEOUT_MS,
+    });
+    mcSiteClients.set(id, client);
+}
+async function initBufferClient(id, accessToken) {
+    const client = axios.create({
+        baseURL: 'https://api.bufferapp.com/1/',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        params: { access_token: accessToken },
+        timeout: DEFAULT_TIMEOUT_MS,
+    });
+    bufSiteClients.set(id, client);
+}
+async function initSendGridClient(id, apiKey) {
+    const client = axios.create({
+        baseURL: 'https://api.sendgrid.com/v3/',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+        },
+        timeout: DEFAULT_TIMEOUT_MS,
+    });
+    sgSiteClients.set(id, client);
+}
 // ── Site Management ──────────────────────────────────────────────────
 /**
  * Get the active site's client, or a specific site's client
@@ -357,6 +406,69 @@ export async function makeWooCommerceRequest(method, endpoint, data, options) {
         limiter.release();
     }
 }
+// ── Mailchimp Request Interface ──────────────────────────────────
+export function hasMailchimp(siteId) {
+    const id = siteId || activeSiteId;
+    return mcSiteClients.has(id);
+}
+export async function makeMailchimpRequest(method, endpoint, data, siteId) {
+    const id = siteId || activeSiteId;
+    const client = mcSiteClients.get(id);
+    if (!client) {
+        throw new Error(`Mailchimp not configured for site "${id}". Add mailchimp_api_key to WP_SITES_CONFIG.`);
+    }
+    const limiter = getLimiter(id);
+    await limiter.acquire();
+    try {
+        const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
+        return response.data;
+    }
+    finally {
+        limiter.release();
+    }
+}
+// ── Buffer Request Interface ─────────────────────────────────────
+export function hasBuffer(siteId) {
+    const id = siteId || activeSiteId;
+    return bufSiteClients.has(id);
+}
+export async function makeBufferRequest(method, endpoint, data, siteId) {
+    const id = siteId || activeSiteId;
+    const client = bufSiteClients.get(id);
+    if (!client) {
+        throw new Error(`Buffer not configured for site "${id}". Add buffer_access_token to WP_SITES_CONFIG.`);
+    }
+    const limiter = getLimiter(id);
+    await limiter.acquire();
+    try {
+        const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
+        return response.data;
+    }
+    finally {
+        limiter.release();
+    }
+}
+// ── SendGrid Request Interface ───────────────────────────────────
+export function hasSendGrid(siteId) {
+    const id = siteId || activeSiteId;
+    return sgSiteClients.has(id);
+}
+export async function makeSendGridRequest(method, endpoint, data, siteId) {
+    const id = siteId || activeSiteId;
+    const client = sgSiteClients.get(id);
+    if (!client) {
+        throw new Error(`SendGrid not configured for site "${id}". Add sendgrid_api_key to WP_SITES_CONFIG.`);
+    }
+    const limiter = getLimiter(id);
+    await limiter.acquire();
+    try {
+        const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
+        return response.data;
+    }
+    finally {
+        limiter.release();
+    }
+}
 // ── Plugin Repository (External API) ────────────────────────────────
 /**
  * Search the WordPress.org Plugin Repository

package/skills/wordpress-router/references/decision-tree.md

@@ -1,4 +1,4 @@
-# Router decision tree (v10 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network)
+# Router decision tree (v11 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network + social/email distribution)
 
 This routing guide covers WordPress **development**, **local environment**, and **operations** workflows.
 
@@ -14,7 +14,7 @@ Keywords that indicate **local environment**:
 local site, Studio, LocalWP, Local by Flywheel, wp-env, local WordPress, start site, stop site, create local site, local development, symlink plugin, local database, switch PHP version, localhost, local preview, detect environment, WASM, SQLite local
 
 Keywords that indicate **operations**:
-deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content
+deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content, social publish, schedule post, Buffer, email campaign, Mailchimp, SendGrid, transactional email, content distribution, newsletter send
 
 Keywords that indicate **development**:
 create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold, i18n, translation, accessibility, a11y, headless, decoupled, WPGraphQL, CI, CD, pipeline, GitHub Actions, GitLab CI, deploy automatico, workflow, quality gate
@@ -104,6 +104,8 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
   → `wp-content-attribution` skill + `wp-ecommerce-manager` agent
 - **Multi-language / multilingual / hreflang / international SEO / language sites / translate network**
   → `wp-multilang-network` skill + `wp-site-manager` agent
+- **Social/email distribution / publish to social / schedule post / email campaign / Mailchimp / Buffer / SendGrid / newsletter / transactional email / content distribution**
+  → `wp-social-email` skill + `wp-distribution-manager` agent
 
 ## Step 2c: route by local environment intent (keywords)
 

package/skills/wp-content/SKILL.md

@@ -105,3 +105,4 @@ Tool: assign_terms_to_content — assign terms to content
 ### Related Skills
 - **`wp-content-repurposing`** — transform existing content for social media, email, and multi-channel distribution
 - **`wp-content-attribution`** — measure which content drives WooCommerce sales (UTM tracking, attribution models, ROI)
+- **wp-social-email** — distribute content to social media and email after creation

package/skills/wp-content-repurposing/SKILL.md

@@ -94,3 +94,4 @@ See `references/platform-specs.md`
 - **`wp-content`** — content creation and lifecycle management (source content)
 - **`wp-headless`** — headless content delivery for multi-channel architectures
 - **`wp-woocommerce`** — product content for e-commerce repurposing
+- **wp-social-email** — publish repurposed content to social and email channels