{"_id":"@buywhere/paperclip","name":"@buywhere/paperclip","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@buywhere/paperclip","version":"0.1.0","description":"BuyWhere tools for Paperclip agents — search and compare products across Singapore, SEA, and US markets. Product catalog and price comparison for AI agent commerce.","license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","dev":"npx tsx src/index.ts","prepublishOnly":"npm run build"},"dependencies":{"zod":"^3.25.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.9.3"},"keywords":["buywhere","paperclip","product-search","price-comparison","deals","shopping","agent","ai","e-commerce","singapore"],"author":{"name":"BuyWhere"},"repository":{"type":"git","url":"git+https://github.com/buywhere/buywhere-site.git","directory":"npm-packages/buywhere-paperclip"},"homepage":"https://buywhere.ai","bugs":{"url":"https://github.com/buywhere/buywhere-site/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@buywhere/paperclip@0.1.0","gitHead":"4424238560ee21ee96a8d6e4dfc9d79e836fcddb","_nodeVersion":"22.22.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-n0c62UyjbFwBAIDKWy8CDx8JUUgLibB6nNjhh/aDw4/86wNy1X9rDcVvwWka6mvRB9udCBVfT8CdZF2Q897www==","shasum":"9a53243bac0454a1c9235228707c8c5f18c4f3fa","tarball":"https://registry.npmjs.org/@buywhere/paperclip/-/paperclip-0.1.0.tgz","fileCount":18,"unpackedSize":30080,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFqhfi5joga21ybCBFWYQixtCztjljTQAkeCl4SZVQ2jAiEA+7Y0M3ojwcakIF3p72kb09wom+NFavdqq/0brMLXqOw="}]},"_npmUser":{"name":"richieboyz18","email":"richmond.teo@gmail.com"},"directories":{},"maintainers":[{"name":"richieboyz18","email":"richmond.teo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip_0.1.0_1777826866852_0.8546046235333007"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T16:47:46.772Z","0.1.0":"2026-05-03T16:47:46.998Z","modified":"2026-05-03T16:47:47.598Z"},"maintainers":[{"name":"richieboyz18","email":"richmond.teo@gmail.com"}],"description":"BuyWhere tools for Paperclip agents — search and compare products across Singapore, SEA, and US markets. Product catalog and price comparison for AI agent commerce.","homepage":"https://buywhere.ai","keywords":["buywhere","paperclip","product-search","price-comparison","deals","shopping","agent","ai","e-commerce","singapore"],"repository":{"type":"git","url":"git+https://github.com/buywhere/buywhere-site.git","directory":"npm-packages/buywhere-paperclip"},"author":{"name":"BuyWhere"},"bugs":{"url":"https://github.com/buywhere/buywhere-site/issues"},"license":"MIT","readme":"# @buywhere/paperclip\n\n[![npm version](https://img.shields.io/npm/v/@buywhere/paperclip.svg)](https://www.npmjs.com/package/@buywhere/paperclip)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nBuyWhere tools for Paperclip agents — search and compare products across Singapore, SEA, and US markets. Part of the BuyWhere product catalog API for AI agent commerce.\n\n## Installation\n\n```bash\nnpm install @buywhere/paperclip\n```\n\n## Quick Start\n\n```typescript\nimport { createToolHandlers } from \"@buywhere/paperclip\";\n\n// Requires BUYWHERE_API_KEY env var\nconst tools = createToolHandlers();\n\nconst result = await tools.search_products.handler({\n  q: \"wireless headphones\",\n  limit: 5,\n});\nconsole.log(result);\n```\n\n## Using with Paperclip Agents\n\nPaperclip agents can use BuyWhere tools in two ways:\n\n### 1. Direct Function Calls (for custom agent code)\n\n```typescript\nimport { BuyWhereClient, createToolHandlers } from \"@buywhere/paperclip\";\n\nconst client = new BuyWhereClient({ apiKey: \"bw_live_xxxx\" });\nconst tools = createToolHandlers(client);\n\n// Search products\nconst results = await tools.search_products.handler({\n  q: \"mechanical keyboard\",\n  country_code: \"SG\",\n  limit: 10,\n });\n```\n\n### 2. MCP Server Integration (for any Paperclip agent)\n\nAdd this to your Paperclip agent's configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"buywhere\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@buywhere/mcp-server\"],\n      \"env\": {\n        \"BUYWHERE_API_KEY\": \"bw_live_xxxx\"\n      }\n    }\n  }\n}\n```\n\n> The `@buywhere/mcp-server` package is already published and maintained separately.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_products` | Search catalog by keyword, price range, region |\n| `get_product` | Get full product details by ID |\n| `compare_products` | Compare 2-10 products side-by-side |\n| `get_deals` | Get discounted products sorted by discount |\n| `list_categories` | List top-level product categories |\n\n## API\n\n### `BuyWhereClient`\n\n```typescript\nconst client = new BuyWhereClient({ apiKey: string, baseUrl?: string, timeout?: number });\n```\n\n### `BuyWhereClient.fromEnv()`\n\nCreates a client using `BUYWHERE_API_KEY` and optional `BUYWHERE_API_URL` environment variables.\n\n### `createToolHandlers(client?: BuyWhereClient): ToolHandlerMap`\n\nReturns an object with named `ToolHandler` entries, each having:\n- `name` — tool name\n- `description` — tool description\n- `inputSchema` — JSON Schema for input validation\n- `handler(args)` — async function that calls the BuyWhere API\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `BUYWHERE_API_KEY` | Your BuyWhere API key (required) |\n| `BUYWHERE_API_URL` | Custom API base URL (optional, default: https://api.buywhere.ai) |\n\nGet your API key at [https://buywhere.ai](https://buywhere.ai).\n\n## Requirements\n\n- Node.js >= 18\n\n## Links\n\n- [BuyWhere API Docs](https://buywhere.ai/docs)\n- [GitHub](https://github.com/buywhere/buywhere-site)\n- [npm](https://www.npmjs.com/package/@buywhere/paperclip)\n- [MCP Server](https://www.npmjs.com/package/@buywhere/mcp-server)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-2696ce32fc67577baf0c19bfd12098ee"}