{"_id":"@agentojs/medusa","name":"@agentojs/medusa","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentojs/medusa","version":"0.1.0","description":"Connect Medusa.js v2 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/medusa"},"homepage":"https://agentojs.com","keywords":["mcp","ucp","acp","medusa","medusajs","medusa-v2","ai-agent","ai-commerce","agentic-middleware","claude","chatgpt","gemini","headless-commerce","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/medusa@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"8.11.0","dist":{"integrity":"sha512-KFnyCXbip8jvXw3kFyW5/AQXwhwaFJD2hyFXXZNyFtpyrAvOkZv1S4CWNJN2K30a1W3rMK1Y6bg/gY3BfgOgRw==","shasum":"73b23e908cf0cbdb60a6f64efa53c1b8eee0a3ab","tarball":"https://registry.npmjs.org/@agentojs/medusa/-/medusa-0.1.0.tgz","fileCount":10,"unpackedSize":28830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCV0hBkGHloDgNWuUP59QGAkknuyAt9kravvl3M7EH7JgIgelneO6j6fWCAADH0xS7ecIdroE4zfd9FJ72cAc1KKB8="}]},"_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/medusa_0.1.0_1773322449333_0.04571927586720226"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-12T13:34:09.249Z","0.1.0":"2026-03-12T13:34:09.547Z","modified":"2026-03-12T13:34:09.744Z"},"maintainers":[{"name":"agentojs","email":"agentojs@gmail.com"}],"description":"Connect Medusa.js v2 to AI agents (Claude, ChatGPT, Gemini) — MCP, UCP, ACP protocols","homepage":"https://agentojs.com","keywords":["mcp","ucp","acp","medusa","medusajs","medusa-v2","ai-agent","ai-commerce","agentic-middleware","claude","chatgpt","gemini","headless-commerce","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/agentojs/agentojs.git","directory":"packages/medusa"},"bugs":{"url":"https://github.com/agentojs/agentojs/issues"},"license":"MIT","readme":"# @agentojs/medusa\r\n\r\n[![npm version](https://img.shields.io/npm/v/@agentojs/medusa.svg)](https://www.npmjs.com/package/@agentojs/medusa)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/agentojs/agentojs/blob/main/LICENSE)\r\n\r\nMedusa.js v2 adapter for AI commerce agents. Implements the `CommerceBackend` interface from `@agentojs/core` using Medusa's Store API.\r\n\r\nPart of the [AgentOJS](https://github.com/agentojs/agentojs) monorepo.\r\n\r\n## Features\r\n\r\n- Full Medusa.js v2 Store API support (products, carts, checkout, orders)\r\n- Auto-region detection -- resolves the first available region when none provided\r\n- Native `fetch()` -- zero runtime dependencies\r\n- x-publishable-api-key authentication\r\n- Medusa v2 payment-collections flow for checkout\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @agentojs/medusa @agentojs/core\r\n```\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { MedusaBackend } from '@agentojs/medusa';\r\n\r\nconst backend = new MedusaBackend({\r\n  backendUrl: 'https://your-medusa-store.com',\r\n  apiKey: 'pk_your_publishable_key',\r\n});\r\n\r\nconst results = await backend.searchProducts({ q: 'shirt', limit: 10 });\r\nconsole.log(results.data); // Product[]\r\n```\r\n\r\nThat's it. Three lines to connect, one line to search.\r\n\r\n## Configuration\r\n\r\n```typescript\r\ninterface MedusaBackendConfig {\r\n  /** Medusa server URL (e.g., \"https://medusa.example.com\") */\r\n  backendUrl: string;\r\n  /** Publishable API key (sent as x-publishable-api-key header) */\r\n  apiKey: string;\r\n  /** Region ID -- auto-detected from first available region if omitted */\r\n  regionId?: string;\r\n}\r\n```\r\n\r\nThe `regionId` controls which currency and country settings are used for product pricing. If omitted, the adapter calls `getRegions()` once and caches the first region's ID.\r\n\r\n## Full Example\r\n\r\n```typescript\r\nimport { MedusaBackend } from '@agentojs/medusa';\r\n\r\nconst backend = new MedusaBackend({\r\n  backendUrl: 'https://your-medusa-store.com',\r\n  apiKey: 'pk_your_publishable_key',\r\n  regionId: 'reg_01ABC', // optional\r\n});\r\n\r\n// Search products\r\nconst results = await backend.searchProducts({ q: 'shirt', limit: 10 });\r\nconsole.log(results.data);\r\n\r\n// Get a single product\r\nconst product = await backend.getProduct('prod_01ABC');\r\n\r\n// Create a cart and add items\r\nconst cart = await backend.createCart('reg_01ABC', [\r\n  { variant_id: 'variant_01ABC', quantity: 1 },\r\n]);\r\n\r\n// Add more items\r\nconst updated = await backend.addLineItem(cart.id, 'variant_02DEF', 2);\r\n\r\n// Checkout flow\r\nconst withShipping = await backend.addShippingMethod(cart.id, 'so_01ABC');\r\nconst payment = await backend.initializePayment(cart.id, 'stripe');\r\nconst order = await backend.completeCart(cart.id);\r\nconsole.log(`Order ${order.display_id} created!`);\r\n```\r\n\r\n## API Reference\r\n\r\n| Method | Description |\r\n|--------|-------------|\r\n| `searchProducts(filters)` | Search products with text query, category/collection filters, pagination |\r\n| `getProduct(id)` | Get a single product by ID with pricing |\r\n| `getCollections()` | List all product collections |\r\n| `getCollection(id)` | Get a single collection by ID |\r\n| `createCart(regionId, items)` | Create a new cart with initial items |\r\n| `getCart(cartId)` | Retrieve cart by ID |\r\n| `updateCart(cartId, updates)` | Update cart (email, addresses, metadata) |\r\n| `addLineItem(cartId, variantId, qty)` | Add a line item to cart |\r\n| `removeLineItem(cartId, lineItemId)` | Remove a line item from cart |\r\n| `getShippingOptions(cartId)` | Get available shipping options for cart |\r\n| `addShippingMethod(cartId, optionId)` | Select a shipping method |\r\n| `createPaymentSessions(cartId)` | Create payment sessions for cart |\r\n| `selectPaymentSession(cartId, providerId)` | Select a payment provider |\r\n| `initializePayment(cartId, providerId)` | Initialize payment (creates payment collection + session) |\r\n| `completeCart(cartId)` | Complete checkout -- returns Order |\r\n| `getOrder(orderId)` | Get order by ID |\r\n| `listOrders(filters)` | List orders with email/status filters |\r\n| `getRegions()` | List all store regions |\r\n| `healthCheck()` | Check if the Medusa server is reachable |\r\n\r\n## Error Handling\r\n\r\nAll API errors throw `MedusaApiError` with `status`, `body`, and `url` properties:\r\n\r\n```typescript\r\nimport { MedusaApiError } from '@agentojs/medusa';\r\n\r\ntry {\r\n  await backend.getProduct('nonexistent');\r\n} catch (err) {\r\n  if (err instanceof MedusaApiError) {\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## Exports\r\n\r\n```typescript\r\nimport { MedusaBackend, MedusaApiError } from '@agentojs/medusa';\r\nimport type { MedusaBackendConfig } from '@agentojs/medusa';\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-fcbeb8973c3b431f98bba09b9f58742b"}