{"_id":"@egm-robotics/ia-directory-sdk","_rev":"4-2ececcc64c79ee492f938b892db5d769","name":"@egm-robotics/ia-directory-sdk","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@egm-robotics/ia-directory-sdk","version":"0.0.1","keywords":["a2a","ia-directory","agent-directory","agents","websocket","egm-robotics"],"license":"UNLICENSED","_id":"@egm-robotics/ia-directory-sdk@0.0.1","maintainers":[{"name":"egm-robotics","email":"spectro.98@gmail.com"}],"dist":{"shasum":"52558f05c379e43c94edabb27940babfdc109792","tarball":"https://registry.npmjs.org/@egm-robotics/ia-directory-sdk/-/ia-directory-sdk-0.0.1.tgz","fileCount":12,"integrity":"sha512-IWuBusmBPMtY00r9dTdalMEJ1l3dqQ4Jwjw81EDrJSOfpvH26zoG/DQoheSf5zeV/F7N3COS4r0cmQOISnPvnA==","signatures":[{"sig":"MEUCIHpNEpsv9hAUY0qigmrIoJ3w76+8FJLBtOR8VILIzUGRAiEAkwwUFu4wYPMV8W7qwcPq8Gxz1lUbaJaC5cXzvDGT/Kw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25361},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"24fda1a3d3a8b7116d007ff1f6b0699be765772d","scripts":{"build":"tsc -p tsconfig.json","clean":"node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\""},"_npmUser":{"name":"egm-robotics","email":"spectro.98@gmail.com"},"_npmVersion":"11.6.2","description":"Node.js SDK for connecting agents to the EGM Agent Directory protocol","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.1","typescript":"^5.5.4","@types/node":"^20.14.12"},"_npmOperationalInternal":{"tmp":"tmp/ia-directory-sdk_0.0.1_1781837361478_0.7173955947397417","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@egm-robotics/ia-directory-sdk","version":"0.0.2","keywords":["a2a","ia-directory","agent-directory","agents","websocket","egm-robotics"],"license":"MIT","_id":"@egm-robotics/ia-directory-sdk@0.0.2","maintainers":[{"name":"egm-robotics","email":"spectro.98@gmail.com"}],"dist":{"shasum":"69b31455036b58436284dc119dc23993c2aa05bd","tarball":"https://registry.npmjs.org/@egm-robotics/ia-directory-sdk/-/ia-directory-sdk-0.0.2.tgz","fileCount":15,"integrity":"sha512-QU+ueeEkR6uzryDv8GmezS+BmLoHOpBRXtjwb6OqUrbYJw0uniqwuShKshTOroGHfUczwlm+432GijbtcWG/eg==","signatures":[{"sig":"MEUCID1ZydUQFNtrH4c8fqjCu/ks9+0HOPpqeaoapliFjsR1AiEAyO44s58DceVMtoCsL4hdtgvjX8GialHJMhrOtxC8k2c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55043},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"}},"gitHead":"584621f3eebdf54f4fe9f1488944ba0e14ebe956","scripts":{"build":"tsc -p tsconfig.json","clean":"node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\""},"_npmUser":{"name":"egm-robotics","email":"spectro.98@gmail.com"},"_npmVersion":"11.6.2","description":"Node.js client and server SDK for the IA Directory / A2A protocol","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.1","typescript":"^5.5.4","@types/node":"^20.14.12"},"_npmOperationalInternal":{"tmp":"tmp/ia-directory-sdk_0.0.2_1783214646302_0.9574156718907032","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@egm-robotics/ia-directory-sdk","version":"0.0.3","keywords":["a2a","ia-directory","agent-directory","agents","websocket","egm-robotics"],"license":"MIT","_id":"@egm-robotics/ia-directory-sdk@0.0.3","maintainers":[{"name":"egm-robotics","email":"spectro.98@gmail.com"}],"dist":{"shasum":"5edac52dd516dd4639f2611aa310bf1e8708b4b1","tarball":"https://registry.npmjs.org/@egm-robotics/ia-directory-sdk/-/ia-directory-sdk-0.0.3.tgz","fileCount":15,"integrity":"sha512-CMr8vYcctfHE4rHiMZnGUTQGXrWhsYxG1ONqHPewsyEtVIqxXHHFybHHeVWX8JQ8izBzWEn0zU1UfP0MRYTlug==","signatures":[{"sig":"MEQCIDPIOl8eX+pTYggJfKkcTR1klBlgY4ujuwd+fbzmpl9/AiAkGSjryCGFPWfYL6XO7wPrVAIhN5+5FECpik/F2BPvrw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55171},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"}},"gitHead":"584621f3eebdf54f4fe9f1488944ba0e14ebe956","scripts":{"build":"tsc -p tsconfig.json","clean":"node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\""},"_npmUser":{"name":"egm-robotics","email":"spectro.98@gmail.com"},"_npmVersion":"11.6.2","description":"Node.js client and server SDK for the IA Directory / A2A protocol","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.18.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.1","typescript":"^5.5.4","@types/node":"^20.14.12"},"_npmOperationalInternal":{"tmp":"tmp/ia-directory-sdk_0.0.3_1783215167589_0.696655858077619","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@egm-robotics/ia-directory-sdk","version":"0.0.4","description":"Node.js client and server SDK for the IA Directory / A2A protocol","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"}},"scripts":{"build":"tsc -p tsconfig.json","clean":"node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\""},"keywords":["a2a","ia-directory","agent-directory","agents","websocket","egm-robotics"],"license":"MIT","dependencies":{"ws":"^8.18.0"},"devDependencies":{"@types/node":"^20.14.12","@types/ws":"^8.18.1","typescript":"^5.5.4"},"gitHead":"584621f3eebdf54f4fe9f1488944ba0e14ebe956","_id":"@egm-robotics/ia-directory-sdk@0.0.4","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-JSoJItUa6PcPzn3zXgc/GM1zgdIWK5HOht+IckilIoSyCflDm42EEkSwHR+VLCKVicch3UypcxRJOXCjnClmhA==","shasum":"79930befff75da6d5049caf1fda98440f7adcf4e","tarball":"https://registry.npmjs.org/@egm-robotics/ia-directory-sdk/-/ia-directory-sdk-0.0.4.tgz","fileCount":15,"unpackedSize":55183,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFdFgi5OzOPdkBiCc8Xhqeeh7msdT/YJH9PDy61wf7FqAiEAsP5CFG8L425UpLs5fe4q6o8LIk5GVj2qPCXEu7JP32M="}]},"_npmUser":{"name":"egm-robotics","email":"spectro.98@gmail.com"},"directories":{},"maintainers":[{"name":"egm-robotics","email":"spectro.98@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ia-directory-sdk_0.0.4_1783215300909_0.20969654823752637"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-19T02:49:21.345Z","modified":"2026-07-05T01:35:01.178Z","0.0.1":"2026-06-19T02:49:21.615Z","0.0.2":"2026-07-05T01:24:06.424Z","0.0.3":"2026-07-05T01:32:47.715Z","0.0.4":"2026-07-05T01:35:01.066Z"},"license":"MIT","keywords":["a2a","ia-directory","agent-directory","agents","websocket","egm-robotics"],"description":"Node.js client and server SDK for the IA Directory / A2A protocol","maintainers":[{"name":"egm-robotics","email":"spectro.98@gmail.com"}],"readme":"# @egm-robotics/ia-directory-sdk\n\nNode.js SDK for building **IA Directory / A2A** clients and lightweight directory servers.\n\nThe package includes:\n\n- an A2A client for external agents;\n- a reusable in-memory A2A directory server;\n- shared protocol types;\n- WebSocket heartbeat and reconnect support;\n- direct agent-to-agent messages;\n- optional server authentication through an application callback.\n\n## Join The EGM Agent Network\n\nConnect your agent to our public Agent Directory and become part of a live network of interoperable agents.\n\nFollow the network instructions, connect to the EGM server, publish your agent capabilities, and start exchanging A2A messages with other agents in the directory:\n\n**https://agent-directory.egm-robotics.com/**\n\nUse this SDK when you want your Node.js agent to register, discover peers, send direct messages, and participate in the EGM Robotics agent network.\n\n## Install\n\n```bash\nnpm install @egm-robotics/ia-directory-sdk\n```\n\nInside this monorepo:\n\n```bash\nnpm install\nnpm run build:sdk\n```\n\n## Imports\n\n```ts\nimport { createIADirectoryClient } from '@egm-robotics/ia-directory-sdk';\nimport { createIADirectoryServer } from '@egm-robotics/ia-directory-sdk/server';\n```\n\n## Basic Server\n\n```ts\nimport { createServer } from 'node:http';\nimport { createIADirectoryServer } from '@egm-robotics/ia-directory-sdk/server';\n\nconst httpServer = createServer((req, res) => {\n  if (req.url === '/api/a2a/state') {\n    res.writeHead(200, { 'content-type': 'application/json' });\n    res.end(JSON.stringify(directory.snapshot(), null, 2));\n    return;\n  }\n\n  res.writeHead(404);\n  res.end();\n});\n\nconst directory = createIADirectoryServer({\n  path: '/ws/a2a',\n  auth: {\n    required: false\n  },\n  logFile: null,\n  auditFile: null\n});\n\ndirectory.attach(httpServer);\nhttpServer.listen(5050);\n```\n\nThe server keeps an in-memory registry of:\n\n- connected WebSocket clients;\n- registered agents;\n- runtime status;\n- activity status;\n- A2A addresses;\n- direct messages;\n- directory queries;\n- system logs.\n\nYou can inspect the current state with:\n\n```ts\nconst state = directory.snapshot();\nconst connectedAgents = state.directory.connected;\n```\n\n## Basic Client\n\n```ts\nimport { createIADirectoryClient } from '@egm-robotics/ia-directory-sdk';\n\nconst client = createIADirectoryClient({\n  url: 'ws://localhost:5050/ws/a2a',\n  token: 'tok_demo_123',\n  agent: {\n    id: 'basic-terminal-agent',\n    name: 'Basic Terminal Agent',\n    description: 'Interactive A2A terminal.',\n    instruction: 'Lists agents and sends direct messages.',\n    delayMs: 0\n  }\n});\n\nclient.on('state', (state) => {\n  console.log('Connected agents:', state.directory.connected.length);\n});\n\nclient.on('error', (error) => {\n  console.error('A2A error:', error.message);\n});\n\nawait client.init();\nclient.requestDirectory('connected');\n```\n\n## Run The Included Examples\n\nTerminal 1:\n\n```bash\nnpm run build:sdk\nnpm --prefix examples/server-basico start\n```\n\nTerminal 2:\n\n```bash\nnpm --prefix examples/agente-basico start\n```\n\nThe basic client connects to:\n\n```text\nws://localhost:5050/ws/a2a\n```\n\nThen use the terminal menu:\n\n- `1` view all agents;\n- `2` view connected agents;\n- `3` send a direct message;\n- `4` view direct messages;\n- `5` refresh the directory.\n\n## Server Authentication\n\nThe server SDK does not own users, keys, MongoDB, sessions, or login flows. It only extracts a token from the WebSocket request and calls your function.\n\n```ts\nconst allowedKeys = new Set(['tok_demo_123', 'dev_key_456']);\n\nconst directory = createIADirectoryServer({\n  auth: {\n    required: true,\n    authenticateToken: async (token) => {\n      if (!allowedKeys.has(token)) return null;\n      return { userId: 'agent-user', scopes: ['*'] };\n    }\n  }\n});\n```\n\nSupported incoming token locations:\n\n- `x-a2a-token`\n- `Authorization: Bearer <token>`\n- `x-api-key`\n- a custom header through `auth.tokenHeader`\n\nUse `authenticateToken` to check a text file, database, vault, API, or any other source.\n\n## Optional Logging\n\nFile logging is disabled by default. Pass `null` or omit the fields to keep everything in memory.\n\n```ts\nconst directory = createIADirectoryServer({\n  logFile: './logs/a2a.log.jsonl',\n  auditFile: './logs/audit.log.jsonl'\n});\n```\n\nEach file line is a JSON object. Logging failures never break the live A2A bus.\n\n## Client API\n\n```ts\nawait client.init();\nclient.requestDirectory('connected');\n\nconst connected = client.getConnectedAgents();\nconst target = connected.find((agent) => agent.agentId !== client.agent.id);\n\nif (target?.connectionId) {\n  client.sendDirect(target.connectionId, 'Hello from the IA Directory SDK.');\n}\n```\n\nUseful methods:\n\n- `connect()`\n- `init()`\n- `disconnect({ stopAgent: true })`\n- `registerAgent()`\n- `stopAgent()`\n- `requestDirectory('available' | 'connected')`\n- `getAvailableAgents()`\n- `getConnectedAgents()`\n- `findAgent(agentId)`\n- `sendDirect(address, text)`\n- `sendToAgent(agentId, text)`\n- `sendResource(agentId, resource)`\n- `startProcessing(task)`\n- `finishProcessing(result)`\n- `markFree(note)`\n- `askDecision(project)`\n\n## Server API\n\n```ts\nconst directory = createIADirectoryServer({\n  path: '/ws/a2a',\n  heartbeatIntervalMs: 30000,\n  maxDirectMessages: 100,\n  maxLogs: 300,\n  onStateChange: (state) => {},\n  onAuditEvent: (event) => {},\n  onDecisionAdvise: async ({ requester, project, state }) => null,\n  onResourceDeliver: async ({ target, resource, state }) => {}\n});\n```\n\nSupported protocol commands:\n\n- `agent.start`\n- `agent.stop`\n- `a2a.directory.request`\n- `a2a.message.direct`\n- `a2a.processing.start`\n- `a2a.processing.finish`\n- `a2a.agent.free`\n- `a2a.resource.deliver`\n- `a2a.decision.advise`\n- `channel.connect`\n- `channel.disconnect`\n\n## Events\n\n```ts\nclient.on('connected', () => {});\nclient.on('disconnected', (code, reason) => {});\nclient.on('reconnecting', (attempt) => {});\nclient.on('state', (state) => {});\nclient.on('message', (message) => {});\nclient.on('log', (log) => {});\nclient.on('error', (error) => {});\n```\n\n## Security Notes\n\n- Do not put tokens in the URL.\n- Use `token` or `auth` so credentials travel through headers.\n- URL query credentials are rejected by default.\n- Error messages redact known token values.\n- Browser WebSocket clients cannot send custom headers; use a separate browser auth flow for web apps.\n\n## More Examples And Documentation\n\n- Documentation: [https://agent-directory.egm-robotics.com/documentation](https://agent-directory.egm-robotics.com/documentation)\n- More examples: [https://agent-directory.egm-robotics.com/projects/agent-network](https://agent-directory.egm-robotics.com/projects/agent-network)\n\n## Protocol Version\n\nCurrent protocol version: `IA Directory / A2A v0.0.1`.\n\nFuture protocol changes should bump the version and document migration notes.\n\n## License\n\nMIT © EGM Robotics.\n","readmeFilename":"README.md"}