{"_id":"@agentmeshworld/sdk","_rev":"2-2e1d4f16f0b7417599ee8d1f50148a20","name":"@agentmeshworld/sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agentmeshworld/sdk","version":"0.1.0","keywords":["agentmesh","mesh","supply-chain","multi-agent","iot","sdk","websocket","mqtt","decentralized","coordination"],"author":{"url":"HiroJei","name":"Hitazurana"},"license":"MIT","_id":"@agentmeshworld/sdk@0.1.0","maintainers":[{"name":"hitazurana","email":"tadashijei@gmail.com"}],"homepage":"https://agentmesh.world","bugs":{"url":"https://github.com/Tomeku-Development/AgentMesh-SDK/issues"},"dist":{"shasum":"4b9f46751ecc19a9f589a503685ccb59300a60b1","tarball":"https://registry.npmjs.org/@agentmeshworld/sdk/-/sdk-0.1.0.tgz","fileCount":31,"integrity":"sha512-GRY9EqCnUfGYZK/ZFt3Pg0fdDFLKuRswSItxn6Y4N3P2j9FsJQjKDW8Z/JgcP12BNYgGXLap835zOAfnFDmxKA==","signatures":[{"sig":"MEUCIGSfwjT6jPgFQTc6ECJm4EoYcHPgUG10xbzDNRq1R3hbAiEAr9OjTM9ua0Ce20jc6oNKQ0EjfJnGP7GGaVSqKo+flYU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66290},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18"},"gitHead":"1e13b6958ce25e13003b39ca14ae471847b9a217","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","clean":"rm -rf dist","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"hitazurana","email":"tadashijei@gmail.com"},"repository":{"url":"git+https://github.com/Tomeku-Development/AgentMesh-SDK.git","type":"git"},"_npmVersion":"11.12.1","description":"TypeScript SDK for connecting agents to the AgentMesh network — multi-agent supply chain coordination for IoT and Enterprise","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.18.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","@types/ws":"^8.5.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1775223721467_0.005868541425692042","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentmeshworld/sdk","version":"0.2.0","description":"TypeScript SDK & CLI for connecting agents to the AgentMesh network — multi-agent supply chain coordination for IoT and Enterprise","main":"dist/index.js","types":"dist/index.d.ts","bin":{"agentmesh":"dist/cli/index.js"},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","clean":"rm -rf dist","prepublishOnly":"npm run build"},"keywords":["agentmesh","mesh","supply-chain","multi-agent","iot","sdk","cli","websocket","mqtt","decentralized","coordination"],"license":"MIT","author":{"name":"Hitazurana","url":"HiroJei"},"repository":{"type":"git","url":"git+https://github.com/Tomeku-Development/AgentMesh-SDK.git"},"bugs":{"url":"https://github.com/Tomeku-Development/AgentMesh-SDK/issues"},"homepage":"https://agentmesh.world","engines":{"node":">=18"},"dependencies":{"ws":"^8.18.0"},"devDependencies":{"typescript":"^5.7.0","@types/ws":"^8.5.0","@types/node":"^22.0.0","vitest":"^3.0.0"},"gitHead":"22ff67ee0f7d493b1a01790c7f45014922f8ec85","_id":"@agentmeshworld/sdk@0.2.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-QVvym6lUaOzrqApSZlhUV4N6ZBlBCF/x+9MewGYHnZB6Aqcv2+LUzGYOkCFi9wgJih+Ayz+794KR2yviIp1qWw==","shasum":"80c0ed7724639189ead2f95c9314148feca12009","tarball":"https://registry.npmjs.org/@agentmeshworld/sdk/-/sdk-0.2.0.tgz","fileCount":35,"unpackedSize":91008,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCl5NCNO0hn5PrBVsx+C1HEvz8yvaINjjCpuR51G2PjmAIhANqbnyepvrJnr+whePHQHkuPZeH9WqBgGyIuNqFhjgI+"}]},"_npmUser":{"name":"hitazurana","email":"tadashijei@gmail.com"},"directories":{},"maintainers":[{"name":"hitazurana","email":"tadashijei@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.0_1775224073805_0.16291915064505824"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-03T13:42:01.384Z","modified":"2026-04-03T13:47:54.110Z","0.1.0":"2026-04-03T13:42:01.616Z","0.2.0":"2026-04-03T13:47:53.961Z"},"bugs":{"url":"https://github.com/Tomeku-Development/AgentMesh-SDK/issues"},"author":{"name":"Hitazurana","url":"HiroJei"},"license":"MIT","homepage":"https://agentmesh.world","keywords":["agentmesh","mesh","supply-chain","multi-agent","iot","sdk","cli","websocket","mqtt","decentralized","coordination"],"repository":{"type":"git","url":"git+https://github.com/Tomeku-Development/AgentMesh-SDK.git"},"description":"TypeScript SDK & CLI for connecting agents to the AgentMesh network — multi-agent supply chain coordination for IoT and Enterprise","maintainers":[{"name":"hitazurana","email":"tadashijei@gmail.com"}],"readme":"<div align=\"center\">\n\n# @agentmeshworld/sdk\n\n**TypeScript SDK for the AgentMesh Network**\n\nConnect autonomous agents to the decentralized supply chain mesh.\n\n[![npm version](https://img.shields.io/npm/v/@agentmeshworld/sdk.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@agentmeshworld/sdk)\n[![npm downloads](https://img.shields.io/npm/dm/@agentmeshworld/sdk.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@agentmeshworld/sdk)\n[![npm total downloads](https://img.shields.io/npm/dt/@agentmeshworld/sdk.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@agentmeshworld/sdk)\n[![license](https://img.shields.io/npm/l/@agentmeshworld/sdk.svg?style=flat-square)](https://github.com/Tomeku-Development/AgentMesh-SDK/blob/main/LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat-square&logo=node.js)](https://nodejs.org/)\n\n<br/>\n\n[![NPM Downloads Chart](https://img.shields.io/npm/dm/@agentmeshworld/sdk?style=for-the-badge&label=Monthly%20Downloads&color=cb3837&logo=npm)](https://www.npmjs.com/package/@agentmeshworld/sdk)\n\n<br/>\n\n[Website](https://agentmesh.world) &bull; [Documentation](#quick-start) &bull; [GitHub](https://github.com/Tomeku-Development/AgentMesh-SDK) &bull; [npm](https://www.npmjs.com/package/@agentmeshworld/sdk)\n\n</div>\n\n---\n\n## What is AgentMesh?\n\nAgentMesh is a **decentralized multi-agent coordination network** for supply chain operations. It enables autonomous agents (buyers, suppliers, logistics providers, inspectors, and oracles) to discover each other, negotiate orders, coordinate shipping, inspect quality, and settle payments -- all through a real-time mesh network.\n\nThe `@agentmeshworld/sdk` package provides a TypeScript client that connects to the AgentMesh gateway via WebSocket, abstracting away the underlying MQTT/BFT protocol.\n\n```\n  Your Agent (SDK)\n       |\n       | WebSocket (wss://agentmesh.world/ws/v1/agent)\n       |\n  [ AgentMesh Gateway ]\n       |\n       | MQTT + BFT Consensus\n       |\n  [ Mesh Network ]\n       |\n  Buyers / Suppliers / Logistics / Inspectors / Oracles\n```\n\n## Install\n\n```bash\nnpm install @agentmeshworld/sdk\n```\n\n```bash\npnpm add @agentmeshworld/sdk\n```\n\n```bash\nyarn add @agentmeshworld/sdk\n```\n\n## CLI\n\nThe SDK includes a CLI for connecting agents directly from your terminal.\n\n```bash\n# Install globally\nnpm install -g @agentmeshworld/sdk\n\n# Or use directly with npx\nnpx @agentmeshworld/sdk help\n```\n\n### Commands\n\n```bash\n# Connect an agent to the mesh (interactive mode)\nagentmesh connect --key amk_your_key --role buyer --sub order:bid,order:status\n\n# Connect as a supplier listening for purchase orders\nagentmesh connect --key amk_your_key --role supplier --caps electronics --sub order:request\n\n# List all event-to-topic mappings\nagentmesh topics\n\n# Show SDK info\nagentmesh info\n```\n\n### Interactive Mode\n\nWhen connected, the CLI listens for incoming messages and lets you publish by typing JSON:\n\n```\n21:30:05 CONNECTED\n21:30:05 Agent ID:     a3f8c2e1b9d04a7c\n21:30:05 Workspace:    my-company\n21:30:06 SUBSCRIBED    orders/+/request, orders/+/bid\n\n21:30:12 MSG orders/po-001/request from=buyer-42\n{\n  \"goods\": \"microcontrollers\",\n  \"quantity\": 5000,\n  \"max_price_per_unit\": 2.50\n}\n\n> {\"topic\":\"order:bid\",\"payload\":{\"order_id\":\"po-001\",\"price_per_unit\":2.25}}\n21:30:18 PUBLISHED order:bid\n```\n\n---\n\n## Quick Start\n\n```typescript\nimport { Agent } from \"@agentmeshworld/sdk\";\n\nconst agent = new Agent({\n  url: \"wss://agentmesh.world/ws/v1/agent\",\n  apiKey: \"amk_your_api_key_here\",  // Get from dashboard\n  role: \"buyer\",\n  capabilities: [\"electronics\", \"semiconductors\"],\n});\n\n// Connect to the mesh\nconst { agentId, workspace } = await agent.connect();\nconsole.log(`Connected as ${agentId} in workspace ${workspace}`);\n\n// Subscribe to order events\nagent.subscribe([\"order:request\", \"order:bid\", \"order:status\"]);\n\n// Listen for incoming messages\nagent.on(\"message\", ({ topic, payload }) => {\n  console.log(`[${topic}]`, payload);\n});\n\n// Publish a purchase order\nagent.publish(\"order:request\", {\n  order_id: \"po-2026-001\",\n  goods: \"microcontrollers\",\n  category: \"semiconductors\",\n  quantity: 5000,\n  max_price_per_unit: 2.50,\n  quality_threshold: 0.95,\n  delivery_deadline_seconds: 3600,\n});\n```\n\n## API Reference\n\n### `Agent`\n\nThe main class for interacting with the AgentMesh network.\n\n#### Constructor\n\n```typescript\nnew Agent(options: AgentOptions)\n```\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `url` | `string` | Yes | Gateway WebSocket URL |\n| `apiKey` | `string` | Yes | API key (`amk_` prefixed) |\n| `role` | `AgentRole` | Yes | `\"buyer\"` \\| `\"supplier\"` \\| `\"logistics\"` \\| `\"inspector\"` \\| `\"oracle\"` |\n| `capabilities` | `string[]` | No | Agent capabilities (e.g., `[\"electronics\"]`) |\n| `balance` | `number` | No | Starting balance (default: 10000) |\n| `agentId` | `string` | No | Custom agent ID (auto-generated if omitted) |\n| `transport` | `object` | No | Transport options (reconnect, ping interval, etc.) |\n\n#### Methods\n\n| Method | Description |\n|--------|-------------|\n| `connect()` | Connect to the mesh. Returns `Promise<{ agentId, workspace, workspaceId }>` |\n| `subscribe(topics)` | Subscribe to topics. Accepts event names or raw topic patterns |\n| `unsubscribe(topics)` | Unsubscribe from topics |\n| `publish(topic, payload)` | Publish a message to the mesh |\n| `disconnect()` | Gracefully disconnect |\n\n#### Events\n\n```typescript\nagent.on(\"connected\", ({ agentId, workspace, workspaceId }) => { ... });\nagent.on(\"message\", ({ topic, payload, header }) => { ... });\nagent.on(\"subscribed\", ({ topics }) => { ... });\nagent.on(\"published\", ({ topic }) => { ... });\nagent.on(\"disconnected\", ({ code, reason }) => { ... });\nagent.on(\"error\", (error) => { ... });\nagent.on(\"reconnecting\", ({ attempt, delay }) => { ... });\n```\n\n### Event-to-Topic Mapping\n\nUse friendly event names instead of raw MQTT topic patterns:\n\n| Event Name | MQTT Topic |\n|------------|------------|\n| `order:request` | `orders/+/request` |\n| `order:bid` | `orders/+/bid` |\n| `order:counter` | `orders/+/counter` |\n| `order:accept` | `orders/+/accept` |\n| `order:reject` | `orders/+/reject` |\n| `order:commit` | `orders/+/commit` |\n| `order:status` | `orders/+/status` |\n| `shipping:request` | `shipping/+/request` |\n| `shipping:bid` | `shipping/+/bid` |\n| `shipping:assign` | `shipping/+/assign` |\n| `shipping:transit` | `shipping/+/transit` |\n| `inspection:request` | `inspection/+/request` |\n| `inspection:report` | `inspection/+/report` |\n| `market:prices` | `market/prices` |\n| `market:demand` | `market/demand` |\n| `ledger:transaction` | `ledger/transactions` |\n| `reputation:update` | `reputation/updates` |\n| `health:alert` | `mesh/health/alerts` |\n| `discovery:announce` | `mesh/discovery/announce` |\n| `discovery:heartbeat` | `mesh/discovery/heartbeat` |\n| `discovery:goodbye` | `mesh/discovery/goodbye` |\n\n### `Transport`\n\nLower-level WebSocket transport with auto-reconnect and exponential backoff.\n\n```typescript\nimport { Transport } from \"@agentmeshworld/sdk\";\n\nconst transport = new Transport({\n  url: \"wss://agentmesh.world/ws/v1/agent\",\n  apiKey: \"amk_your_key\",\n  autoReconnect: true,        // default: true\n  maxReconnectAttempts: 10,   // default: 10\n  reconnectBaseDelay: 1000,   // default: 1000ms\n  reconnectMaxDelay: 30000,   // default: 30000ms\n  pingInterval: 25000,        // default: 25000ms\n});\n```\n\n### Message Types\n\nThe SDK exports TypeScript interfaces for all 22 MESH protocol message types:\n\n```typescript\nimport type {\n  // Orders\n  PurchaseOrderRequest,\n  SupplierBid,\n  CounterOffer,\n  BidAcceptance,\n  BidRejection,\n  OrderCommit,\n  OrderStatus,\n  // Shipping\n  ShippingRequest,\n  ShippingBid,\n  ShippingAssign,\n  TransitUpdate,\n  // Quality\n  InspectionRequest,\n  InspectionReport,\n  // Market\n  MarketPriceUpdate,\n  MarketDemand,\n  // Discovery\n  DiscoveryAnnounce,\n  Heartbeat,\n  Goodbye,\n  // Ledger & Reputation\n  LedgerTransaction,\n  ReputationUpdate,\n  // Health\n  HealthAlert,\n  RoleRedistribution,\n} from \"@agentmeshworld/sdk\";\n```\n\n## Examples\n\n### Supplier Agent\n\n```typescript\nimport { Agent } from \"@agentmeshworld/sdk\";\n\nconst supplier = new Agent({\n  url: \"wss://agentmesh.world/ws/v1/agent\",\n  apiKey: \"amk_supplier_key\",\n  role: \"supplier\",\n  capabilities: [\"electronics\", \"semiconductors\"],\n});\n\nawait supplier.connect();\nsupplier.subscribe([\"order:request\"]);\n\nsupplier.on(\"message\", ({ topic, payload }) => {\n  if (topic.includes(\"/request\")) {\n    const order = payload as any;\n    console.log(`New order: ${order.goods} x${order.quantity}`);\n\n    // Auto-bid\n    supplier.publish(\"order:bid\", {\n      order_id: order.order_id,\n      supplier_id: supplier.agentId,\n      price_per_unit: order.max_price_per_unit * 0.9,\n      available_quantity: order.quantity,\n      estimated_fulfillment_seconds: 30,\n    });\n  }\n});\n```\n\n### IoT Device Agent\n\n```typescript\nimport { Agent } from \"@agentmeshworld/sdk\";\n\nconst sensor = new Agent({\n  url: \"wss://agentmesh.world/ws/v1/agent\",\n  apiKey: \"amk_iot_device_key\",\n  role: \"inspector\",\n  capabilities: [\"temperature-monitoring\", \"humidity-monitoring\"],\n});\n\nawait sensor.connect();\nsupplier.subscribe([\"inspection:request\"]);\n\n// Publish sensor readings as inspection reports\nsetInterval(() => {\n  sensor.publish(\"inspection:report\", {\n    inspection_id: `insp-${Date.now()}`,\n    order_id: \"active-order-id\",\n    shipment_id: \"active-shipment-id\",\n    inspector_id: sensor.agentId!,\n    quality_score: 0.97,\n    quantity_verified: 100,\n    quantity_defective: 0,\n    defect_descriptions: [],\n    passed: true,\n    recommendation: \"accept\",\n  });\n}, 60000);\n```\n\n## Architecture\n\n```\n@agentmeshworld/sdk\n├── src/\n│   ├── index.ts          # Barrel exports\n│   ├── agent.ts          # High-level Agent class + TOPIC_MAP\n│   ├── transport.ts      # WebSocket transport (reconnect, ping)\n│   ├── events.ts         # Typed EventEmitter\n│   └── types/\n│       ├── messages.ts   # 22 MESH protocol message interfaces\n│       └── protocol.ts   # WebSocket protocol types\n├── tests/\n│   ├── events.test.ts    # EventEmitter unit tests\n│   └── agent.test.ts     # Agent + mock WebSocket tests\n├── package.json\n├── tsconfig.json\n└── vitest.config.ts\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Type-check\npnpm lint\n\n# Run tests\npnpm test\n\n# Build\npnpm build\n```\n\n## Get an API Key\n\n1. Sign up at [agentmesh.world](https://agentmesh.world)\n2. Create a workspace\n3. Generate an API key from the workspace settings\n4. Use the `amk_` prefixed key in your agent configuration\n\n## Roadmap\n\n- [ ] Node.js native WebSocket support (no `ws` dependency)\n- [ ] Browser bundle (ESM)\n- [ ] Agent discovery helpers\n- [ ] Order lifecycle state machine\n- [ ] Automatic bid evaluation\n- [ ] React hooks (`useAgent`, `useOrders`)\n- [ ] CLI tool for testing agents\n\n## Contributing\n\nContributions are welcome! Please read the [contributing guidelines](https://github.com/Tomeku-Development/AgentMesh-SDK/blob/main/CONTRIBUTING.md) first.\n\n```bash\ngit clone https://github.com/Tomeku-Development/AgentMesh-SDK.git\ncd AgentMesh-SDK\npnpm install\npnpm test\n```\n\n## License\n\nMIT - see [LICENSE](./LICENSE)\n\n---\n\n<div align=\"center\">\n\nBuilt by **[Hitazurana (HiroJei)](https://tomeku.com)** at **[Tomeku Development](https://tomeku.com)**\n\n[agentmesh.world](https://agentmesh.world)\n\n</div>\n","readmeFilename":"README.md"}