@respira/wordpress-mcp-server 7.2.18 → 7.4.0

package/dist/wordpress-client.js

@@ -6,7 +6,7 @@
 import axios from 'axios';
 import FormData from 'form-data';
 import { readFileSync, existsSync, statSync } from 'node:fs';
-import { dirname, resolve, extname, basename } from 'node:path';
+import { dirname, resolve, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Agent as HttpAgent } from 'node:http';
 import { getRespiraAgentHeaders } from './agent-signature.js';
@@ -37,15 +37,6 @@ export class WordPressClient {
     insecureTLS = false;
     negotiatedApiVersion = null;
     negotiationPromise = null;
-    /**
-     * The real error from the last failed `/wp-json/respira/v2/status` probe.
-     * Bug 8d2c3331: getApiVersion() used to swallow this entirely, so a 401
-     * (missing/invalid API key) or 403 (missing v2 scope) — both of which prove
-     * the route IS live and reachable — looked identical to a genuine 404 /
-     * network failure. ensureV2() reads this to surface the real cause instead
-     * of a misleading "not available" boilerplate.
-     */
-    negotiationError = null;
     // Version compatibility check — populated lazily on first API call.
     compatibilityChecked = false;
     compatibilityPromise = null;
@@ -555,20 +546,11 @@ export class WordPressClient {
                     const response = await this.rootClient.get('/wp-json/respira/v2/status');
                     if (response.status >= 200 && response.status < 300) {
                         this.negotiatedApiVersion = 'v2';
-                        this.negotiationError = null;
                         return 'v2';
                     }
                 }
-                catch (err) {
-                    // Bug 8d2c3331: capture the real reason instead of discarding it.
-                    // The response interceptor (errorInterceptor -> handleError) has
-                    // already turned this into a descriptive Error by this point (e.g.
-                    // "Authentication failed: No API key provided..." for a 401, or a
-                    // scope-denied message for a 403) — both of which mean the v2 route
-                    // IS live and reachable, which is the opposite of what
-                    // ensureV2()'s old generic message implied. Fall back to v1 either
-                    // way (so genuinely v1-only sites keep working) but remember why.
-                    this.negotiationError = err instanceof Error ? err : new Error(String(err));
+                catch {
+                    // Ignore and fall back to v1.
                 }
                 this.negotiatedApiVersion = 'v1';
                 return 'v1';
@@ -588,29 +570,7 @@ export class WordPressClient {
     async ensureV2() {
         const version = await this.getApiVersion();
         if (version !== 'v2') {
-            const err = this.negotiationError;
-            const errName = err instanceof Error ? err.name : undefined;
-            // Bug 8d2c3331: a 401/403 from the v2 status probe means the route IS
-            // live and reachable — WordPress itself rejected the request's
-            // credentials/scope. That is a completely different failure than
-            // "route not found" (404, HTML-instead-of-JSON, DNS/network errors),
-            // so it needs a different message: none of the permalinks/WAF/plugin-
-            // version causes below apply, and repeating them just sends the next
-            // person chasing the wrong fix.
-            const looksLikeAuthOrScopeRejection = typeof errName === 'string' &&
-                (errName.startsWith('respira_') || errName === 'http_401' || errName === 'http_403');
-            if (err && looksLikeAuthOrScopeRejection) {
-                throw new Error(`respira/v2 rejected this request's credentials: ${err.message}\n\n` +
-                    'The v2 route is live and reachable on this site — this is an authentication or ' +
-                    'permission problem, not a permalinks/WAF/plugin-version problem. v1 tools may still ' +
-                    'work because some v1 routes have looser permission checks.\n\n' +
-                    `To confirm: open ${this.siteConfig.url}/wp-json/respira/v2/status in a browser with no ` +
-                    'headers. A JSON 401/403 response (not a 404 or an HTML page) confirms the route works ' +
-                    'and this is an auth/scope issue — check that the configured API key is correct, active, ' +
-                    'and has write permission for this site.');
-            }
             throw new Error('respira/v2 is not available on this site.\n\n' +
-                (err ? `Underlying error from the v2 status probe: ${err.message}\n\n` : '') +
                 'Common causes:\n' +
                 '• A security plugin (Wordfence, Sucuri, iThemes Security) is blocking the /wp-json/respira/v2/ path — whitelist that path in the plugin settings.\n' +
                 '• WordPress permalinks are set to "Plain" — go to Settings → Permalinks and choose any option except Plain.\n' +
@@ -805,13 +765,7 @@ export class WordPressClient {
                     return new Error(`Site not reachable: ${this.siteConfig.url} returned a ${status} response from the web server (not WordPress).\n\n${hint}`);
                 }
                 const reason = data?.message || data?.code || 'Invalid API key';
-                const authError = new Error(`Authentication failed: ${reason}`);
-                // Bug 8d2c3331: stamp the WP_Error code (e.g. respira_missing_api_key)
-                // onto .name so callers like ensureV2() can tell "the route rejected my
-                // auth" (the route IS live) apart from "the route doesn't exist"
-                // instead of collapsing both into the same generic message.
-                authError.name = typeof data?.code === 'string' && data.code ? data.code.slice(0, 80) : 'http_401';
-                return authError;
+                return new Error(`Authentication failed: ${reason}`);
             }
             else if (status === 429) {
                 return new Error(`Rate limit exceeded. Please wait before making more requests.`);
@@ -906,6 +860,13 @@ export class WordPressClient {
                 if (detail) {
                     apiError.message = `${apiError.message} [attempted: ${detail}]`;
                 }
+                // Woo add-on v3.0 added many routes (brands, variations, coupons,
+                // customers, refunds, ai-readiness). A missing /woocommerce/ route
+                // on a licensed site almost always means the installed add-on
+                // predates the tool.
+                if (reqUrl.includes('/woocommerce/')) {
+                    apiError.message = `${apiError.message} This tool may require a newer Respira WooCommerce Add-on (v3.0+). Update it in wp-admin under Plugins.`;
+                }
             }
             return apiError;
         }
@@ -1558,19 +1519,10 @@ export class WordPressClient {
                     clearTimeout(killer);
                 }
             }
-            else if (file.startsWith('/') ||
-                file.startsWith('./') ||
-                file.startsWith('../') ||
-                file.startsWith('~') ||
-                /^[A-Za-z]:[\\/]/.test(file) || // Windows drive path: C:\... or C:/...
-                file.startsWith('\\\\') // Windows UNC path: \\server\share\...
-            ) {
-                // Local file path — preflight size before reading the whole file into memory.
-                // Without the Windows branches above, a path like C:\Users\me\img.jpeg fell
-                // through to the base64 branch below and was decoded into garbage bytes,
-                // surfacing to the agent as "Could not connect — no response received".
+            else if (file.startsWith('/') || file.startsWith('./') || file.startsWith('../') || file.startsWith('~')) {
+                // Local file path — preflight size before reading the whole file into memory
                 const resolvedPath = file.startsWith('~')
-                    ? file.replace(/^~/, process.env.HOME || process.env.USERPROFILE || '')
+                    ? file.replace(/^~/, process.env.HOME || '')
                     : resolve(file);
                 if (!existsSync(resolvedPath)) {
                     throw new Error(`File not found: ${resolvedPath}`);
@@ -1592,11 +1544,6 @@ export class WordPressClient {
                 catch (err) {
                     throw new Error(`Failed to read ${resolvedPath}: ${err?.message || String(err)}`);
                 }
-                if (!filename) {
-                    // Caller passed only a file path (e.g. upload_media({ file: "C:\\...\\img.jpg" }))
-                    // with no separate filename — derive it from the path basename.
-                    filename = basename(resolvedPath);
-                }
                 if (!mimeType) {
                     const ext = extname(resolvedPath).toLowerCase();
                     const mimeMap = {
@@ -1960,7 +1907,7 @@ export class WordPressClient {
     /**
      * Inject page builder content
      */
-    async injectBuilderContent(builder, pageId, content, diviVersion, editTarget, mode, confirmReplace, targetPath, position) {
+    async injectBuilderContent(builder, pageId, content, diviVersion, editTarget, mode, confirmReplace) {
         if (builder.toLowerCase() === 'divi') {
             if (!diviVersion) {
                 const existing = await this.extractBuilderContent('divi', pageId);
@@ -2002,46 +1949,13 @@ export class WordPressClient {
         // here so every downstream caller sees the same shape: pass the inner
         // array when the caller wrapped it, otherwise pass through verbatim.
         const normalisedContent = this.unwrapBuilderContent(content);
-        // inject is the heaviest write Respira makes (full complexify tree-walk +
-        // CSS regen + a render-validation loopback), so on a large page behind a
-        // host/edge request-time limit it can run well past the 30s default and
-        // hang to the MCP client's multi-minute ceiling. Match the restoreSnapshot
-        // precedent: allow a 90s window, and on timeout surface an actionable error
-        // (the write may have landed server-side) instead of a bare hang. Reported
-        // on a WP Engine + Cloudflare site, a 12-section Elementor inject (9a8fc2fd).
-        try {
-            const response = await this.client.post(`/builder/${builder}/inject/${pageId}`, {
-                content: normalisedContent,
-                editTarget,
-                mode: mode || 'replace',
-                confirm_replace: confirmReplace === true,
-                // Chunked build: when target_path is given, the plugin inserts the
-                // content as children of the container at that bracket path
-                // (e.g. "sections[0].rows[1].columns[0]") instead of at page top
-                // level. Lets an agent build a large section in small calls when the
-                // whole tree exceeds the AI client's per-tool-call payload cap.
-                // Only forwarded when set, so default behaviour is unchanged.
-                ...(targetPath && targetPath.trim() !== ''
-                    ? { target_path: targetPath.trim(), position: typeof position === 'number' ? position : -1 }
-                    : {}),
-            }, { timeout: 90_000 });
-            return response.data;
-        }
-        catch (err) {
-            const isTimeout = err?.code === 'ECONNABORTED' ||
-                err?.code === 'ETIMEDOUT' ||
-                /timeout/i.test(String(err?.message || ''));
-            if (!isTimeout) {
-                throw err;
-            }
-            throw new Error(`inject_builder_content exceeded 90s on the "${builder}" page ${pageId}. This is almost ` +
-                `always a large page hitting a host or edge request-time limit (for example Cloudflare or ` +
-                `WP Engine), not a Respira error, and the write may have completed on the server — verify with ` +
-                `extract_builder_content before retrying. To stay under the limit, build the page in smaller ` +
-                `pieces: send the first section with mode:"append", then append the rest one or two sections ` +
-                `per call (or use add_section / add_html). If it must go in one call, ask the host to confirm ` +
-                `/wp-json/respira/* is not CDN-cached or WAF-challenged and to raise PHP max_execution_time.`);
-        }
+        const response = await this.client.post(`/builder/${builder}/inject/${pageId}`, {
+            content: normalisedContent,
+            editTarget,
+            mode: mode || 'replace',
+            confirm_replace: confirmReplace === true,
+        });
+        return response.data;
     }
     /**
      * Unwrap the common `{content: array}` shape that round-tripped extracts
@@ -2134,24 +2048,17 @@ export class WordPressClient {
     /**
      * Update a specific module in a page builder page
      */
-    async updateModule(builder, pageId, moduleIdentifier, updates, editTarget, confirmLiveEdit) {
+    async updateModule(builder, pageId, moduleIdentifier, updates, editTarget) {
         try {
             // Increase timeout for large content updates
             const timeout = updates.content && updates.content.length > 50000
                 ? 60000 // 60 seconds for large content
                 : 30000; // 30 seconds default
-            const payload = {
+            const response = await this.client.put(`/builder/${builder}/modules/${pageId}`, {
                 module_identifier: moduleIdentifier,
                 updates,
                 editTarget,
-            };
-            // e402506e (Christian): forward the live-edit confirmation so the
-            // confirmation_required handshake completes through MCP. snake_case to
-            // match the plugin's element/module write gate.
-            if (confirmLiveEdit !== undefined) {
-                payload.confirm_live_edit = confirmLiveEdit;
-            }
-            const response = await this.client.put(`/builder/${builder}/modules/${pageId}`, payload, { timeout });
+            }, { timeout });
             return response.data;
         }
         catch (error) {
@@ -2279,7 +2186,7 @@ export class WordPressClient {
     /**
      * Apply v2 builder patch operations.
      */
-    async applyBuilderPatch(builder, postId, operations, include, editTarget, confirmLiveEdit) {
+    async applyBuilderPatch(builder, postId, operations, include, editTarget) {
         await this.ensureV2();
         const payload = { operations };
         if (include) {
@@ -2288,10 +2195,6 @@ export class WordPressClient {
         if (editTarget) {
             payload.editTarget = editTarget;
         }
-        // e402506e (Christian): forward live-edit confirmation for the handshake.
-        if (confirmLiveEdit !== undefined) {
-            payload.confirm_live_edit = confirmLiveEdit;
-        }
         const response = await this.rootClient.post(`/wp-json/respira/v2/builder/${builder}/patch/${postId}`, payload);
         return response.data;
     }
@@ -2336,24 +2239,6 @@ export class WordPressClient {
         const response = await this.rootClient.request({ method: 'PATCH', url, data: { content } });
         return response.data;
     }
-    /**
-     * Tail wp-content/debug.log (or the site's configured WP_DEBUG_LOG path)
-     * via GET /respira/v2/debug-log. Read-only, no path parameter accepted —
-     * the plugin resolves the log location itself and rejects anything
-     * outside wp-content / the configured custom path.
-     */
-    async readDebugLog(opts = {}) {
-        const params = {};
-        if (typeof opts.lines === 'number')
-            params.lines = opts.lines;
-        if (opts.level)
-            params.level = opts.level;
-        if (opts.since)
-            params.since = opts.since;
-        if (opts.grep)
-            params.grep = opts.grep;
-        return await this.callRestV2('GET', '/debug-log', params);
-    }
     /**
      * Get site name (for logging)
      */
@@ -2366,13 +2251,6 @@ export class WordPressClient {
     getSiteUrl() {
         return this.siteConfig.url;
     }
-    /**
-     * Get the site's API key. Used by the account site-list refresh to pick a
-     * live `respira_site_` token to authenticate the refresh call with.
-     */
-    getApiKey() {
-        return this.siteConfig.apiKey;
-    }
     /**
      * Get approvals URL in WordPress admin.
      *
@@ -3127,6 +3005,251 @@ export class WordPressClient {
         const response = await this.client.get('/woocommerce/reports/sales', { params: params || {} });
         return response.data;
     }
+    // WooCommerce Add-on v3.0 — brands
+    async woocommerceListBrands(params) {
+        const response = await this.client.get('/woocommerce/brands', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceGetBrand(id) {
+        const response = await this.client.get(`/woocommerce/brands/${id}`);
+        return response.data;
+    }
+    async woocommerceCreateBrand(data) {
+        const response = await this.client.post('/woocommerce/brands', data);
+        return response.data;
+    }
+    async woocommerceUpdateBrand(id, data) {
+        const response = await this.client.put(`/woocommerce/brands/${id}`, data);
+        return response.data;
+    }
+    async woocommerceDeleteBrand(id) {
+        const response = await this.client.delete(`/woocommerce/brands/${id}`);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — catalog operations
+    async woocommerceListProductsAdvanced(params) {
+        const response = await this.client.get('/woocommerce/products/advanced', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceFindProduct(params) {
+        const response = await this.client.get('/woocommerce/products/search', { params });
+        return response.data;
+    }
+    async woocommerceCatalogHealth() {
+        const response = await this.client.get('/woocommerce/catalog/health');
+        return response.data;
+    }
+    async woocommerceBulkUpdateProducts(data) {
+        const response = await this.client.post('/woocommerce/products/bulk-update', data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — pricing
+    async woocommerceBulkUpdatePrices(data) {
+        const response = await this.client.post('/woocommerce/pricing/bulk-update', data);
+        return response.data;
+    }
+    async woocommerceScheduleSale(data) {
+        const response = await this.client.post('/woocommerce/pricing/schedule-sale', data);
+        return response.data;
+    }
+    async woocommerceRevertPricing(data) {
+        const response = await this.client.post('/woocommerce/pricing/revert', data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — inventory
+    async woocommerceBulkUpdateStock(data) {
+        const response = await this.client.post('/woocommerce/inventory/bulk-update', data);
+        return response.data;
+    }
+    async woocommerceFindLowStock(params) {
+        const response = await this.client.get('/woocommerce/inventory/low-stock', { params: params || {} });
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — storefront intelligence
+    async woocommerceAnalyzeShopPage(params) {
+        const response = await this.client.get('/woocommerce/storefront/analyze-shop', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceAnalyzeProductPage(params) {
+        const response = await this.client.get('/woocommerce/storefront/analyze-product', { params });
+        return response.data;
+    }
+    async woocommerceUpdateProductCardLayout(data) {
+        const response = await this.client.post('/woocommerce/storefront/update-card-layout', data);
+        return response.data;
+    }
+    async woocommerceAddLowStockBadge(data) {
+        const response = await this.client.post('/woocommerce/storefront/add-low-stock-badge', data);
+        return response.data;
+    }
+    async woocommerceAddSaleBadge(data) {
+        const response = await this.client.post('/woocommerce/storefront/add-sale-badge', data);
+        return response.data;
+    }
+    async woocommerceUpdateCheckoutLayout(data) {
+        const response = await this.client.post('/woocommerce/storefront/update-checkout-layout', data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — variations and attributes
+    async woocommerceSetProductAttributes(id, data) {
+        const response = await this.client.post(`/woocommerce/products/${id}/attributes`, data);
+        return response.data;
+    }
+    async woocommerceGenerateVariations(id, data) {
+        const response = await this.client.post(`/woocommerce/products/${id}/variations/generate`, data);
+        return response.data;
+    }
+    async woocommerceCreateVariation(id, data) {
+        const response = await this.client.post(`/woocommerce/products/${id}/variations`, data);
+        return response.data;
+    }
+    async woocommerceCreateGlobalAttribute(data) {
+        const response = await this.client.post('/woocommerce/attributes', data);
+        return response.data;
+    }
+    async woocommerceSetVariationGallery(id, data) {
+        const response = await this.client.put(`/woocommerce/variations/${id}/gallery`, data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — coupons and customers
+    async woocommerceListCoupons(params) {
+        const response = await this.client.get('/woocommerce/coupons', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceCreateCoupon(data) {
+        const response = await this.client.post('/woocommerce/coupons', data);
+        return response.data;
+    }
+    async woocommerceUpdateCoupon(id, data) {
+        const response = await this.client.put(`/woocommerce/coupons/${id}`, data);
+        return response.data;
+    }
+    async woocommerceCreateCustomer(data) {
+        const response = await this.client.post('/woocommerce/customers', data);
+        return response.data;
+    }
+    async woocommerceUpdateCustomer(id, data) {
+        const response = await this.client.put(`/woocommerce/customers/${id}`, data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — order notes and refunds
+    async woocommerceAddOrderNote(id, data) {
+        const response = await this.client.post(`/woocommerce/orders/${id}/notes`, data);
+        return response.data;
+    }
+    async woocommerceGetOrderRefunds(id) {
+        const response = await this.client.get(`/woocommerce/orders/${id}/refunds`);
+        return response.data;
+    }
+    async woocommerceCreateOrderRefund(id, data) {
+        const response = await this.client.post(`/woocommerce/orders/${id}/refunds`, data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.1 — Subscriptions / Bookings / Memberships
+    async woocommerceListSubscriptions(params) {
+        const response = await this.client.get('/woocommerce/subscriptions', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceGetSubscription(id) {
+        const response = await this.client.get(`/woocommerce/subscriptions/${id}`);
+        return response.data;
+    }
+    async woocommerceUpdateSubscriptionStatus(id, data) {
+        const response = await this.client.put(`/woocommerce/subscriptions/${id}/status`, data || {});
+        return response.data;
+    }
+    async woocommerceUpdateSubscriptionDates(id, data) {
+        const response = await this.client.put(`/woocommerce/subscriptions/${id}/dates`, data || {});
+        return response.data;
+    }
+    async woocommerceAddSubscriptionNote(id, data) {
+        const response = await this.client.post(`/woocommerce/subscriptions/${id}/notes`, data || {});
+        return response.data;
+    }
+    async woocommerceListBookings(params) {
+        const response = await this.client.get('/woocommerce/bookings', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceGetBooking(id) {
+        const response = await this.client.get(`/woocommerce/bookings/${id}`);
+        return response.data;
+    }
+    async woocommerceUpdateBookingStatus(id, data) {
+        const response = await this.client.put(`/woocommerce/bookings/${id}/status`, data || {});
+        return response.data;
+    }
+    async woocommerceRescheduleBooking(id, data) {
+        const response = await this.client.put(`/woocommerce/bookings/${id}/reschedule`, data || {});
+        return response.data;
+    }
+    async woocommerceListMembershipPlans(params) {
+        const response = await this.client.get('/woocommerce/membership-plans', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceListMemberships(params) {
+        const response = await this.client.get('/woocommerce/memberships', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceGetMembership(id) {
+        const response = await this.client.get(`/woocommerce/memberships/${id}`);
+        return response.data;
+    }
+    async woocommerceUpdateMembershipStatus(id, data) {
+        const response = await this.client.put(`/woocommerce/memberships/${id}/status`, data || {});
+        return response.data;
+    }
+    async woocommerceSetMembershipEndDate(id, data) {
+        const response = await this.client.put(`/woocommerce/memberships/${id}/end-date`, data || {});
+        return response.data;
+    }
+    // WooCommerce Add-on v3.1 — assisted checkout
+    async woocommerceCreateCartLink(data) {
+        const response = await this.client.post('/woocommerce/cart-links', data);
+        return response.data;
+    }
+    async woocommerceAgentOrdersReport(params) {
+        const response = await this.client.get('/woocommerce/reports/agent-orders', { params: params || {} });
+        return response.data;
+    }
+    // WooCommerce Add-on v3.1 — readiness autofix
+    async woocommerceReadinessFixlist(params) {
+        const response = await this.client.get('/woocommerce/catalog/readiness-fixlist', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceSetImageAlt(id, data) {
+        const response = await this.client.post(`/woocommerce/products/${id}/image-alt`, data);
+        return response.data;
+    }
+    // WooCommerce Add-on v3.1 — product feeds
+    async woocommerceConfigureFeed(data) {
+        const response = await this.client.post('/woocommerce/feeds/config', data || {});
+        return response.data;
+    }
+    async woocommerceGenerateFeed(data) {
+        const response = await this.client.post('/woocommerce/feeds/generate', data || {});
+        return response.data;
+    }
+    async woocommerceGetFeedStatus() {
+        const response = await this.client.get('/woocommerce/feeds/status');
+        return response.data;
+    }
+    async woocommerceValidateFeed(params) {
+        const response = await this.client.get('/woocommerce/feeds/validate', { params: params || {} });
+        return response.data;
+    }
+    async woocommerceSetFeedCategoryMapping(data) {
+        const response = await this.client.post('/woocommerce/feeds/category-mapping', data || {});
+        return response.data;
+    }
+    // WooCommerce Add-on v3.0 — AI readiness
+    async woocommerceProductAiReadiness(id) {
+        const response = await this.client.get(`/woocommerce/products/${id}/ai-readiness`);
+        return response.data;
+    }
+    async woocommerceCatalogAiReadiness(params) {
+        const response = await this.client.get('/woocommerce/catalog/ai-readiness', { params: params || {} });
+        return response.data;
+    }
     // --- Accessibility ---
     async listAccessibilityScans(opts) {
         const response = await this.client.get('/accessibility/scans', {