{"_id":"@agentojs/woocommerce","name":"@agentojs/woocommerce","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentojs/woocommerce","version":"0.1.0","description":"Connect WooCommerce to AI agents (Claude, ChatGPT, Gemini) — MCP, UCP, ACP protocols","license":"MIT","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"repository":{"type":"git","url":"git+https://github.com/agentojs/agentojs.git","directory":"packages/woocommerce"},"homepage":"https://agentojs.com","keywords":["mcp","ucp","acp","woocommerce","woo","wordpress","ai-agent","ai-commerce","agentic-middleware","claude","chatgpt","gemini","model-context-protocol"],"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run","prepublishOnly":"pnpm build"},"engines":{"node":">=20.0.0"},"peerDependencies":{"@agentojs/core":"^0.1.0"},"devDependencies":{"@agentojs/core":"workspace:*","typescript":"^5.7.0","vitest":"^3.0.0"},"gitHead":"6eb2940ae91a170e4b2630169bd0a2e504b9bd9e","bugs":{"url":"https://github.com/agentojs/agentojs/issues"},"_id":"@agentojs/woocommerce@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"8.11.0","dist":{"integrity":"sha512-tIMUZDdyR3Kz6qq7lrKPOiXEETk0MxGQ6YUKlpNMAPih4gQ7cvcG6q+n+O8PrjKN/6DAlLTR77xE94FDvk0Aeg==","shasum":"0e7f790d00a414bce0637723ef55255bd436a834","tarball":"https://registry.npmjs.org/@agentojs/woocommerce/-/woocommerce-0.1.0.tgz","fileCount":10,"unpackedSize":68910,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDTxQ/6s8AY5GwjTwoK9zT3enk8tbygHYEPR/UnEI4T/wIgFxR3BgKWh9OsGuyMD4La1B6Gz9lXHj9IKjPzukXm2xQ="}]},"_npmUser":{"name":"agentojs","email":"agentojs@gmail.com"},"directories":{},"maintainers":[{"name":"agentojs","email":"agentojs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/woocommerce_0.1.0_1773322464353_0.7014244134423466"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-12T13:34:24.294Z","0.1.0":"2026-03-12T13:34:24.478Z","modified":"2026-03-12T13:34:24.651Z"},"maintainers":[{"name":"agentojs","email":"agentojs@gmail.com"}],"description":"Connect WooCommerce to AI agents (Claude, ChatGPT, Gemini) — MCP, UCP, ACP protocols","homepage":"https://agentojs.com","keywords":["mcp","ucp","acp","woocommerce","woo","wordpress","ai-agent","ai-commerce","agentic-middleware","claude","chatgpt","gemini","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/agentojs/agentojs.git","directory":"packages/woocommerce"},"bugs":{"url":"https://github.com/agentojs/agentojs/issues"},"license":"MIT","readme":"# @agentojs/woocommerce\r\n\r\n[![npm version](https://img.shields.io/npm/v/@agentojs/woocommerce.svg)](https://www.npmjs.com/package/@agentojs/woocommerce)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/agentojs/agentojs/blob/main/LICENSE)\r\n\r\nWooCommerce adapter for AI commerce agents. Implements the `CommerceBackend` interface from `@agentojs/core` using WooCommerce's dual API surface.\r\n\r\nPart of the [AgentOJS](https://github.com/agentojs/agentojs) monorepo.\r\n\r\n## Features\r\n\r\n- Dual API architecture (Store API + REST API) -- handled transparently\r\n- Cart-Token JWT management with in-memory state\r\n- Automatic price conversion from minor units to decimals\r\n- Variable product support (fetches variations)\r\n- Native `fetch()` -- zero runtime dependencies\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @agentojs/woocommerce @agentojs/core\r\n```\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { WooCommerceBackend } from '@agentojs/woocommerce';\r\n\r\nconst backend = new WooCommerceBackend({\r\n  baseUrl: 'https://your-store.com',\r\n  consumerKey: 'ck_your_consumer_key',\r\n  consumerSecret: 'cs_your_consumer_secret',\r\n});\r\n\r\nconst { data: products } = await backend.searchProducts({ q: 'hoodie' });\r\nconsole.log(products[0].title);\r\n```\r\n\r\nGenerate API keys in WooCommerce: **Settings > Advanced > REST API > Add Key** (Read/Write permissions).\r\n\r\n## Configuration\r\n\r\n```typescript\r\ninterface WooCommerceBackendConfig {\r\n  /** WooCommerce site URL (e.g., \"https://store.example.com\") */\r\n  baseUrl: string;\r\n  /** WooCommerce REST API consumer key (starts with ck_) */\r\n  consumerKey: string;\r\n  /** WooCommerce REST API consumer secret (starts with cs_) */\r\n  consumerSecret: string;\r\n}\r\n```\r\n\r\n## Dual API Architecture\r\n\r\nWooCommerce exposes two APIs with different capabilities. This adapter transparently routes calls to the correct one:\r\n\r\n| Feature | Store API (`wc/store/v1`) | REST API (`wc/v3`) |\r\n|---------|--------------------------|---------------------|\r\n| Auth | None / Cart-Token JWT | Basic Auth (key + secret) |\r\n| Products | Read (public) | Read + Write |\r\n| Cart | Full CRUD | Not available |\r\n| Checkout | Full flow | Not available |\r\n| Orders | Not available | Full CRUD |\r\n| Categories | Not available | Full CRUD |\r\n| Shipping Zones | Not available | Read |\r\n\r\n## Cart-Token Flow\r\n\r\nWooCommerce carts are identified by a JWT token returned in the `Cart-Token` response header. This adapter:\r\n\r\n1. Creates a UUID as the public `cartId`\r\n2. Maps it internally to the real Cart-Token JWT\r\n3. Stores cart state (email, addresses, payment method) in memory\r\n\r\n> Cart state is in-memory and lost on process restart. This is acceptable for stateless AI agent interactions.\r\n\r\n## Full Example\r\n\r\n```typescript\r\nimport { WooCommerceBackend } from '@agentojs/woocommerce';\r\n\r\nconst backend = new WooCommerceBackend({\r\n  baseUrl: 'https://your-store.com',\r\n  consumerKey: 'ck_key',\r\n  consumerSecret: 'cs_secret',\r\n});\r\n\r\n// Browse products\r\nconst { data: products } = await backend.searchProducts({ q: 'hoodie' });\r\nconsole.log(`Found ${products.length} products`);\r\n\r\n// Create a cart\r\nconst cart = await backend.createCart('default', [\r\n  { variant_id: '42', quantity: 2 },\r\n]);\r\nconsole.log(`Cart total: ${cart.total} ${cart.currency_code}`);\r\n\r\n// Update shipping address\r\nawait backend.updateCart(cart.id, {\r\n  email: 'customer@example.com',\r\n  shipping_address: {\r\n    first_name: 'John',\r\n    last_name: 'Doe',\r\n    address_1: '123 Main St',\r\n    city: 'New York',\r\n    province: 'NY',\r\n    postal_code: '10001',\r\n    country_code: 'US',\r\n  },\r\n});\r\n\r\n// Shipping and checkout\r\nconst shippingOptions = await backend.getShippingOptions(cart.id);\r\nawait backend.addShippingMethod(cart.id, shippingOptions[0].id);\r\nconst order = await backend.completeCart(cart.id);\r\nconsole.log(`Order #${order.display_id} placed!`);\r\n```\r\n\r\n## API Reference\r\n\r\n### Products\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `searchProducts(filters)` | Search products via Store API with pagination |\r\n| `getProduct(id)` | Get single product with variations (if variable) |\r\n| `getCollections()` | List product categories with products |\r\n| `getCollection(id)` | Get single category with its products |\r\n\r\n### Cart\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `createCart(regionId, items)` | Create cart and add initial items |\r\n| `getCart(cartId)` | Retrieve cart by ID |\r\n| `updateCart(cartId, updates)` | Update email, shipping/billing address |\r\n| `addLineItem(cartId, variantId, quantity)` | Add item to cart |\r\n| `removeLineItem(cartId, lineItemId)` | Remove item by key |\r\n\r\n### Shipping\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `getShippingOptions(cartId)` | Get available shipping rates |\r\n| `addShippingMethod(cartId, optionId)` | Select a shipping rate |\r\n\r\n### Checkout\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `createPaymentSessions(cartId)` | Get available payment methods |\r\n| `selectPaymentSession(cartId, providerId)` | Select payment method |\r\n| `completeCart(cartId)` | Complete checkout, returns Order |\r\n\r\n> `initializePayment()` is not supported for WooCommerce and throws an error.\r\n\r\n### Orders\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `getOrder(orderId)` | Fetch order by ID (REST API) |\r\n| `listOrders(filters)` | List orders with filters (email, status) |\r\n\r\n### Regions & Health\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `getRegions()` | Get shipping zones as regions |\r\n| `healthCheck()` | Check if WP REST API is accessible |\r\n\r\n## Price Handling\r\n\r\nWooCommerce Store API returns prices in **minor units** (e.g., `\"2999\"` for $29.99). This adapter automatically converts them to decimal format using the `currency_minor_unit` field from the API response.\r\n\r\n## Error Handling\r\n\r\n```typescript\r\nimport { WooCommerceApiError } from '@agentojs/woocommerce';\r\n\r\ntry {\r\n  await backend.getProduct('999');\r\n} catch (err) {\r\n  if (err instanceof WooCommerceApiError) {\r\n    console.error(`HTTP ${err.status}: ${err.body}`);\r\n    console.error(`URL: ${err.url}`);\r\n  }\r\n}\r\n```\r\n\r\n## Exported Types\r\n\r\nThe package exports all internal WooCommerce API types for advanced use:\r\n\r\n```typescript\r\nimport type {\r\n  WcStoreProduct,\r\n  WcVariation,\r\n  WcCart,\r\n  WcCartItem,\r\n  WcOrder,\r\n  WcAddress,\r\n  WcShippingRate,\r\n  WcPaymentMethod,\r\n  WcCategory,\r\n  WcShippingZone,\r\n} from '@agentojs/woocommerce';\r\n```\r\n\r\n## License\r\n\r\n[MIT](https://github.com/agentojs/agentojs/blob/main/LICENSE)\r\n","readmeFilename":"README.md","_rev":"1-177a50e41cee9b452fc9b7df39191238"}