@adsim/wordpress-mcp-server 3.0.0 → 4.4.0

package/tests/unit/tools/woocommerceIntelligence.test.js

@@ -0,0 +1,341 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall, _testSetTarget } from '../../../index.js';
+import { mockSuccess, mockError, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => {
+  fetch.mockReset();
+  consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  process.env.WC_CONSUMER_KEY = 'ck_test';
+  process.env.WC_CONSUMER_SECRET = 'cs_test';
+});
+afterEach(() => {
+  consoleSpy.mockRestore();
+  _testSetTarget(null);
+  delete process.env.WC_CONSUMER_KEY;
+  delete process.env.WC_CONSUMER_SECRET;
+});
+
+// =========================================================================
+// Mock data
+// =========================================================================
+
+const instockProducts = [
+  { id: 301, name: 'Widget A', sku: 'WA-001', stock_quantity: 3, stock_status: 'instock', price: '15.00', permalink: 'https://shop.example.com/product/widget-a' },
+  { id: 302, name: 'Widget B', sku: 'WB-002', stock_quantity: 10, stock_status: 'instock', price: '25.00', permalink: 'https://shop.example.com/product/widget-b' },
+  { id: 303, name: 'Widget C', sku: 'WC-003', stock_quantity: 1, stock_status: 'instock', price: '35.00', permalink: 'https://shop.example.com/product/widget-c' },
+];
+
+const outOfStockProducts = [
+  { id: 304, name: 'Widget D', sku: 'WD-004', stock_quantity: 0, stock_status: 'outofstock', price: '45.00', permalink: 'https://shop.example.com/product/widget-d' },
+];
+
+const customerOrders = [
+  { id: 601, date_created: '2026-02-01T10:00:00', status: 'completed', total: '100.00', customer_id: 10, line_items: [{ name: 'T-Shirt', quantity: 2, total: '39.98' }, { name: 'Hoodie', quantity: 1, total: '49.99' }] },
+  { id: 602, date_created: '2026-01-15T10:00:00', status: 'completed', total: '50.00', customer_id: 10, line_items: [{ name: 'T-Shirt', quantity: 1, total: '19.99' }, { name: 'Cap', quantity: 1, total: '15.00' }] },
+  { id: 603, date_created: '2025-12-01T10:00:00', status: 'processing', total: '75.00', customer_id: 10, line_items: [{ name: 'Hoodie', quantity: 1, total: '49.99' }, { name: 'T-Shirt', quantity: 1, total: '19.99' }] },
+];
+
+const seoProductPerfect = {
+  id: 401, name: 'Premium Organic Cotton T-Shirt', slug: 'premium-organic-cotton-tshirt', status: 'publish',
+  description: '<p>This premium organic cotton t-shirt is made from 100% certified organic cotton. Sustainably sourced and ethically manufactured.</p>',
+  short_description: '<p>Premium organic cotton t-shirt, sustainably sourced.</p>',
+  images: [{ src: 'https://shop.example.com/img/tshirt.jpg', alt: 'Premium organic cotton t-shirt' }],
+  price: '29.99', permalink: 'https://shop.example.com/product/premium-organic-cotton-tshirt'
+};
+
+const seoProductBad = {
+  id: 402, name: 'Shirt', slug: 'product-12345', status: 'publish',
+  description: '<p>A shirt.</p>',
+  short_description: '',
+  images: [],
+  price: '', permalink: 'https://shop.example.com/product/product-12345'
+};
+
+const wpPost = {
+  id: 50, title: { rendered: 'Best Cotton T-Shirts for Summer' },
+  content: { rendered: '<p>Looking for the best cotton t-shirts?</p>' },
+  excerpt: { rendered: '' },
+  meta: { rank_math_focus_keyword: 'cotton t-shirt' },
+  categories: [5], tags: [], status: 'publish', slug: 'best-cotton-tshirts',
+  link: 'https://test.example.com/best-cotton-tshirts', date: '2026-02-01', modified: '2026-02-01'
+};
+
+const wpPostNoMeta = {
+  id: 51, title: { rendered: 'Summer Fashion Trends Guide' },
+  content: { rendered: '<p>Here are the latest summer fashion trends.</p>' },
+  excerpt: { rendered: '' },
+  meta: {},
+  categories: [5], tags: [], status: 'publish', slug: 'summer-fashion-trends',
+  link: 'https://test.example.com/summer-fashion-trends', date: '2026-02-01', modified: '2026-02-01'
+};
+
+const wcSearchResults = [
+  { id: 401, name: 'Premium Organic Cotton T-Shirt', description: '<p>Made from 100% cotton material for summer wear.</p>', stock_status: 'instock', images: [{ src: 'https://shop.example.com/img/tshirt.jpg' }], price: '29.99', permalink: 'https://shop.example.com/product/premium-organic-cotton-tshirt' },
+  { id: 402, name: 'Linen Summer Shirt', description: '<p>Light summer shirt.</p>', stock_status: 'instock', images: [{ src: 'https://shop.example.com/img/linen.jpg' }], price: '39.99', permalink: 'https://shop.example.com/product/linen-summer-shirt' },
+];
+
+// =========================================================================
+// wc_inventory_alert
+// =========================================================================
+
+describe('wc_inventory_alert', () => {
+  it('SUCCESS — returns products below threshold', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(instockProducts);
+    mockSuccess(outOfStockProducts);
+
+    const res = await call('wc_inventory_alert');
+    const data = parseResult(res);
+
+    expect(data.summary.total_alerts).toBe(3);
+    expect(data.summary.out_of_stock_count).toBe(1);
+    expect(data.summary.low_stock_count).toBe(2);
+    expect(data.summary.threshold_used).toBe(5);
+    // Sorted ASC: outofstock (qty 0) first, then qty 1, then qty 3
+    expect(data.products[0].id).toBe(304);
+    expect(data.products[1].id).toBe(303);
+    expect(data.products[2].id).toBe(301);
+  });
+
+  it('SUCCESS — custom threshold filters correctly', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(instockProducts);
+    mockSuccess(outOfStockProducts);
+
+    const res = await call('wc_inventory_alert', { threshold: 2 });
+    const data = parseResult(res);
+
+    // Widget C (qty 1) + Widget D (outofstock) — Widget A (qty 3) exceeds threshold 2
+    expect(data.summary.total_alerts).toBe(2);
+    expect(data.summary.threshold_used).toBe(2);
+  });
+
+  it('SUCCESS — include_out_of_stock=false excludes outofstock', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(instockProducts);
+
+    const res = await call('wc_inventory_alert', { include_out_of_stock: false });
+    const data = parseResult(res);
+
+    expect(data.summary.total_alerts).toBe(2);
+    expect(data.summary.out_of_stock_count).toBe(0);
+    expect(data.summary.low_stock_count).toBe(2);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_inventory_alert');
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+
+  it('ERROR — WC credentials missing', async () => {
+    delete process.env.WC_CONSUMER_KEY;
+    delete process.env.WC_CONSUMER_SECRET;
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+
+    const res = await call('wc_inventory_alert');
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('WC_CONSUMER_KEY');
+  });
+});
+
+// =========================================================================
+// wc_order_intelligence
+// =========================================================================
+
+describe('wc_order_intelligence', () => {
+  it('SUCCESS — calculates LTV and metrics', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(customerOrders);
+
+    const res = await call('wc_order_intelligence', { customer_id: 10 });
+    const data = parseResult(res);
+
+    expect(data.customer_id).toBe(10);
+    expect(data.total_orders).toBe(3);
+    expect(data.total_spent).toBe(225);
+    expect(data.average_order_value).toBe(75);
+    expect(data.last_order_date).toBe('2026-02-01T10:00:00');
+    expect(data.first_order_date).toBe('2025-12-01T10:00:00');
+    expect(data.order_frequency_days).toBeTypeOf('number');
+    expect(data.recent_orders).toHaveLength(3);
+    expect(data.statuses_breakdown.completed).toBe(2);
+    expect(data.statuses_breakdown.processing).toBe(1);
+  });
+
+  it('SUCCESS — favourite products ranked by frequency', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(customerOrders);
+
+    const res = await call('wc_order_intelligence', { customer_id: 10 });
+    const data = parseResult(res);
+
+    // T-Shirt: 2+1+1=4, Hoodie: 1+1=2, Cap: 1
+    expect(data.favourite_products[0].name).toBe('T-Shirt');
+    expect(data.favourite_products[0].quantity).toBe(4);
+    expect(data.favourite_products[1].name).toBe('Hoodie');
+    expect(data.favourite_products[1].quantity).toBe(2);
+  });
+
+  it('SUCCESS — customer with no orders', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess([]);
+
+    const res = await call('wc_order_intelligence', { customer_id: 99 });
+    const data = parseResult(res);
+
+    expect(data.total_orders).toBe(0);
+    expect(data.total_spent).toBe(0);
+    expect(data.average_order_value).toBe(0);
+    expect(data.first_order_date).toBeNull();
+    expect(data.favourite_products).toHaveLength(0);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_order_intelligence', { customer_id: 10 });
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+});
+
+// =========================================================================
+// wc_seo_product_audit
+// =========================================================================
+
+describe('wc_seo_product_audit', () => {
+  it('SUCCESS — audits products with scores', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess([seoProductPerfect, seoProductBad]);
+
+    const res = await call('wc_seo_product_audit');
+    const data = parseResult(res);
+
+    expect(data.total_audited).toBe(2);
+    expect(data.products).toHaveLength(2);
+    expect(data.average_score).toBeTypeOf('number');
+    expect(data.summary.perfect_score_count).toBeGreaterThanOrEqual(0);
+    expect(data.summary.needs_attention_count).toBeGreaterThanOrEqual(0);
+  });
+
+  it('SUCCESS — perfect product gets score 100', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess([seoProductPerfect]);
+
+    const res = await call('wc_seo_product_audit');
+    const data = parseResult(res);
+
+    const p = data.products.find(x => x.id === 401);
+    expect(p.score).toBe(100);
+    expect(p.issues).toHaveLength(0);
+    expect(data.summary.perfect_score_count).toBe(1);
+  });
+
+  it('SUCCESS — product with multiple issues gets low score', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess([seoProductBad]);
+
+    const res = await call('wc_seo_product_audit');
+    const data = parseResult(res);
+
+    const p = data.products.find(x => x.id === 402);
+    expect(p.score).toBeLessThan(70);
+    expect(p.issues.length).toBeGreaterThan(3);
+    expect(p.issues).toContain('description_too_short');
+    expect(p.issues).toContain('missing_short_description');
+    expect(p.issues).toContain('generic_slug');
+    expect(p.issues).toContain('missing_image');
+    expect(p.issues).toContain('missing_price');
+    expect(data.summary.needs_attention_count).toBe(1);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_seo_product_audit');
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+});
+
+// =========================================================================
+// wc_suggest_product_links
+// =========================================================================
+
+describe('wc_suggest_product_links', () => {
+  it('SUCCESS — suggests products based on post keywords', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(wpPost);          // WP API: get post
+    mockSuccess(wcSearchResults); // WC API: search keyword 1
+    mockSuccess([]);              // WC API: search keyword 2
+
+    const res = await call('wc_suggest_product_links', { post_id: 50 });
+    const data = parseResult(res);
+
+    expect(data.post_id).toBe(50);
+    expect(data.post_title).toBe('Best Cotton T-Shirts for Summer');
+    expect(data.keywords_used.length).toBeGreaterThanOrEqual(1);
+    expect(data.keywords_used[0]).toBe('cotton t-shirt');
+    expect(data.suggestions.length).toBeGreaterThanOrEqual(1);
+    expect(data.suggestions[0].product_id).toBeDefined();
+    expect(data.suggestions[0].relevance_score).toBeGreaterThan(0);
+    expect(data.suggestions[0].anchor_text).toBeDefined();
+  });
+
+  it('SUCCESS — uses title words when no SEO keywords', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(wpPostNoMeta);    // WP post with no SEO meta
+    mockSuccess(wcSearchResults); // WC search for title word 1
+    mockSuccess([]);              // WC search for title word 2
+
+    const res = await call('wc_suggest_product_links', { post_id: 51 });
+    const data = parseResult(res);
+
+    expect(data.post_id).toBe(51);
+    expect(data.keywords_used.length).toBeGreaterThan(0);
+    // Keywords from title "Summer Fashion Trends Guide" (words > 3 chars)
+    expect(data.keywords_used.some(k =>
+      ['summer', 'fashion', 'trends', 'guide'].includes(k.toLowerCase())
+    )).toBe(true);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_suggest_product_links', { post_id: 50 });
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+});

package/tests/unit/tools/woocommerceWrite.test.js

@@ -0,0 +1,323 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall, _testSetTarget } from '../../../index.js';
+import { mockSuccess, mockError, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => {
+  fetch.mockReset();
+  consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  process.env.WC_CONSUMER_KEY = 'ck_test';
+  process.env.WC_CONSUMER_SECRET = 'cs_test';
+});
+afterEach(() => {
+  consoleSpy.mockRestore();
+  _testSetTarget(null);
+  delete process.env.WC_CONSUMER_KEY;
+  delete process.env.WC_CONSUMER_SECRET;
+});
+
+// =========================================================================
+// Mock data
+// =========================================================================
+
+const product1 = {
+  id: 101, name: 'T-Shirt', slug: 't-shirt', status: 'publish',
+  price: '19.99', regular_price: '24.99', sale_price: '19.99',
+  stock_status: 'instock', stock_quantity: 50,
+  categories: [{ id: 5, name: 'Clothing' }],
+  images: [{ src: 'https://shop.example.com/img/tshirt.jpg' }],
+  permalink: 'https://shop.example.com/product/t-shirt',
+  type: 'simple', variations: [], description: 'A nice shirt', short_description: 'Shirt'
+};
+
+const updatedProduct = {
+  id: 101, name: 'T-Shirt Updated', status: 'publish',
+  regular_price: '24.99', sale_price: '19.99',
+  permalink: 'https://shop.example.com/product/t-shirt'
+};
+
+const order1 = {
+  id: 500, number: '500', status: 'processing',
+  date_created: '2026-02-01T10:00:00',
+  customer_id: 10,
+  billing: { first_name: 'John', last_name: 'Doe', email: 'john@example.com' },
+  total: '69.98', currency: 'EUR',
+  line_items: [{ name: 'T-Shirt', quantity: 2, total: '39.98' }],
+  shipping: {}, payment_method: 'stripe', transaction_id: 'txn_123', meta_data: []
+};
+
+// =========================================================================
+// wc_update_product
+// =========================================================================
+
+describe('wc_update_product', () => {
+  it('SUCCESS — update without price change', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess(updatedProduct); // PUT response
+
+    const res = await call('wc_update_product', { id: 101, name: 'T-Shirt Updated' });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.product.id).toBe(101);
+    expect(data.product.name).toBe('T-Shirt Updated');
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wc_update_product');
+    expect(entry).toBeDefined();
+    expect(entry.action).toBe('update_product');
+    expect(entry.status).toBe('success');
+  });
+
+  it('SUCCESS — price within 20% threshold', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current product (for guardrail check)
+    mockSuccess({ ...product1, regular_price: '100.00' });
+    // 2. PUT update
+    mockSuccess({ ...updatedProduct, regular_price: '115.00' });
+
+    const res = await call('wc_update_product', { id: 101, regular_price: '115.00' });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.product.regular_price).toBe('115.00');
+  });
+
+  it('BLOCKED — price change >20% without confirmation', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // GET current product
+    mockSuccess({ ...product1, regular_price: '100.00' });
+
+    const res = await call('wc_update_product', { id: 101, regular_price: '150.00' });
+    expect(res.isError).toBe(true);
+
+    const data = JSON.parse(res.content[0].text);
+    expect(data.error).toBe('PRICE_GUARDRAIL_TRIGGERED');
+    expect(data.change_percent).toBe(50);
+    expect(data.current_price).toBe(100);
+    expect(data.new_price).toBe(150);
+  });
+
+  it('SUCCESS — price >20% with price_guardrail_confirmed', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current product (guardrail check)
+    mockSuccess({ ...product1, regular_price: '100.00' });
+    // 2. PUT update
+    mockSuccess({ ...updatedProduct, regular_price: '150.00' });
+
+    const res = await call('wc_update_product', { id: 101, regular_price: '150.00', price_guardrail_confirmed: true });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_update_product', { id: 101, name: 'New' });
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+
+  it('ERROR — product not found (404)', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockError(404, '{"code":"woocommerce_rest_product_invalid_id","message":"Invalid ID."}');
+
+    const res = await call('wc_update_product', { id: 999, name: 'Ghost' });
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('404');
+  });
+
+  it('ERROR — WC credentials missing', async () => {
+    delete process.env.WC_CONSUMER_KEY;
+    delete process.env.WC_CONSUMER_SECRET;
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+
+    const res = await call('wc_update_product', { id: 101, name: 'Test' });
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('WC_CONSUMER_KEY');
+  });
+});
+
+// =========================================================================
+// wc_update_stock
+// =========================================================================
+
+describe('wc_update_stock', () => {
+  it('SUCCESS — simple product stock update', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current product
+    mockSuccess({ ...product1, stock_quantity: 50 });
+    // 2. PUT update
+    mockSuccess({ ...product1, stock_quantity: 30, manage_stock: true });
+
+    const res = await call('wc_update_stock', { id: 101, stock_quantity: 30 });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.previous_stock).toBe(50);
+    expect(data.new_stock).toBe(30);
+    expect(data.variation_id).toBeNull();
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wc_update_stock');
+    expect(entry).toBeDefined();
+    expect(entry.action).toBe('update_stock');
+  });
+
+  it('SUCCESS — variation stock update', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current variation
+    mockSuccess({ id: 201, stock_quantity: 10, manage_stock: true });
+    // 2. PUT update variation
+    mockSuccess({ id: 201, stock_quantity: 25, manage_stock: true });
+
+    const res = await call('wc_update_stock', { id: 102, stock_quantity: 25, variation_id: 201 });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.previous_stock).toBe(10);
+    expect(data.new_stock).toBe(25);
+    expect(data.variation_id).toBe(201);
+  });
+
+  it('ERROR — negative stock rejected (Zod min:0)', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+
+    const res = await call('wc_update_stock', { id: 101, stock_quantity: -5 });
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('stock_quantity');
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_update_stock', { id: 101, stock_quantity: 10 });
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+});
+
+// =========================================================================
+// wc_update_order_status
+// =========================================================================
+
+describe('wc_update_order_status', () => {
+  it('SUCCESS — valid transition (processing → completed)', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current order
+    mockSuccess({ ...order1, status: 'processing' });
+    // 2. PUT update status
+    mockSuccess({ ...order1, status: 'completed' });
+
+    const res = await call('wc_update_order_status', { id: 500, status: 'completed' });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.previous_status).toBe('processing');
+    expect(data.new_status).toBe('completed');
+    expect(data.note_added).toBe(false);
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wc_update_order_status');
+    expect(entry).toBeDefined();
+    expect(entry.action).toBe('update_order_status');
+  });
+
+  it('ERROR — invalid transition rejected', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // GET current order — status pending
+    mockSuccess({ ...order1, status: 'pending' });
+
+    const res = await call('wc_update_order_status', { id: 500, status: 'completed' });
+    expect(res.isError).toBe(true);
+
+    const data = JSON.parse(res.content[0].text);
+    expect(data.error).toBe('INVALID_TRANSITION');
+    expect(data.current_status).toBe('pending');
+    expect(data.valid_transitions).toContain('processing');
+    expect(data.valid_transitions).not.toContain('completed');
+  });
+
+  it('ERROR — terminal status (cancelled → X)', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess({ ...order1, status: 'cancelled' });
+
+    const res = await call('wc_update_order_status', { id: 500, status: 'processing' });
+    expect(res.isError).toBe(true);
+
+    const data = JSON.parse(res.content[0].text);
+    expect(data.error).toBe('INVALID_TRANSITION');
+    expect(data.valid_transitions).toEqual([]);
+    expect(data.message).toContain('terminal');
+  });
+
+  it('SUCCESS — with note', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    // 1. GET current order
+    mockSuccess({ ...order1, status: 'processing' });
+    // 2. PUT update status
+    mockSuccess({ ...order1, status: 'completed' });
+    // 3. POST note
+    mockSuccess({ id: 1, note: 'Shipped via DHL' });
+
+    const res = await call('wc_update_order_status', { id: 500, status: 'completed', note: 'Shipped via DHL' });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.note_added).toBe(true);
+  });
+
+  it('BLOCKED — WP_READ_ONLY prevents access', async () => {
+    const original = process.env.WP_READ_ONLY;
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const res = await call('wc_update_order_status', { id: 500, status: 'completed' });
+      expect(res.isError).toBe(true);
+      expect(res.content[0].text).toContain('READ-ONLY');
+    } finally {
+      if (original === undefined) delete process.env.WP_READ_ONLY;
+      else process.env.WP_READ_ONLY = original;
+    }
+  });
+
+  it('ERROR — order not found (404)', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockError(404, '{"code":"woocommerce_rest_shop_order_invalid_id","message":"Invalid ID."}');
+
+    const res = await call('wc_update_order_status', { id: 999, status: 'completed' });
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('404');
+  });
+
+  it('SUCCESS — transition from failed → processing', async () => {
+    _testSetTarget('shop', { url: 'https://shop.example.com', username: 'u', password: 'p' });
+    mockSuccess({ ...order1, status: 'failed' });
+    mockSuccess({ ...order1, status: 'processing' });
+
+    const res = await call('wc_update_order_status', { id: 500, status: 'processing' });
+    const data = parseResult(res);
+
+    expect(data.success).toBe(true);
+    expect(data.previous_status).toBe('failed');
+    expect(data.new_status).toBe('processing');
+  });
+});