{"_id":"@ans-project/sdk-js","_rev":"5-a7862fd6558dc254c1f31541b8710e34","name":"@ans-project/sdk-js","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.1":{"name":"@ans-project/sdk-js","version":"0.0.1","keywords":["ans","agent","sdk","registration","decentralized-identity","ai","ai-agent"],"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","_id":"@ans-project/sdk-js@0.0.1","maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"dist":{"shasum":"6e849a3dd6c22eee88f1efec4735e54b2b13a534","tarball":"https://registry.npmjs.org/@ans-project/sdk-js/-/sdk-js-0.0.1.tgz","fileCount":7,"integrity":"sha512-9ZduMt7sWj8DNI1pcXkYi133r0ZuFGmWxGurgTQ2ZlhA7KnaqZHW2xpn0rj0YQ+n+Jdpc89fKbzeLihJE6P7GQ==","signatures":[{"sig":"MEYCIQCv+x4I1MhnrlX1oBwnFDygLaqrBPaOLl0mBPsttpowQgIhAMFgdBprpsc0rvlAU4MpltymE4IPKhOIAXBL5XQ3/lrV","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13074},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"23e4432cd4226135881317c6ac45e88c982eb059","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"},"_npmVersion":"11.0.0","description":"JavaScript/TypeScript SDK for Agent Network System (ANS) agent registration.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"joi":"^17.0.0","uuid":"^9.0.0","axios":"^1.0.0","multiformats":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/sdk-js_0.0.1_1755051948522_0.023741585425437695","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@ans-project/sdk-js","version":"0.0.2","keywords":["ans","agent","sdk","registration","decentralized-identity","ai","ai-agent"],"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","_id":"@ans-project/sdk-js@0.0.2","maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"dist":{"shasum":"f4e6766fdce0ea9780a8c88f6b194d9b9d752ee8","tarball":"https://registry.npmjs.org/@ans-project/sdk-js/-/sdk-js-0.0.2.tgz","fileCount":8,"integrity":"sha512-CHvIuzz9FEA2bKRNyMGtWarE2yphKylqAAI7Xa5mfsfWJUerd67tFb+ZNpUTTOQL87QaBy/WqZJ6n+v0v6/5TA==","signatures":[{"sig":"MEUCIHhRR6iVurIZfu/ykd7A305pzDz6NaacmxeeOoPU/jShAiEAtPr/3GrC/vAt0MXOSAsIyJ50fW8knd57qJUc3HWx7eo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15131},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"23e4432cd4226135881317c6ac45e88c982eb059","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"},"_npmVersion":"11.0.0","description":"JavaScript/TypeScript SDK for Agent Network System (ANS) agent registration.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"joi":"^17.0.0","uuid":"^9.0.0","axios":"^1.0.0","multiformats":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/sdk-js_0.0.2_1755053214840_0.2375903203898282","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@ans-project/sdk-js","version":"0.0.3","keywords":["ans","agent","sdk","registration","decentralized-identity","ai","ai-agent"],"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","_id":"@ans-project/sdk-js@0.0.3","maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"bin":{"anslookup":"bin/anslookup.js"},"dist":{"shasum":"ae798ab41cabd59dae6d272b145a428b32f540db","tarball":"https://registry.npmjs.org/@ans-project/sdk-js/-/sdk-js-0.0.3.tgz","fileCount":8,"integrity":"sha512-aThdkhuIyoD0UmCqDSanB7CM9EnPKd9BSQPi+BnpE9vY0cE7LAlgbK4gG2AJkNFTYxc4i1q5V3VP+fSbCBHvyg==","signatures":[{"sig":"MEUCIHZC/w7rf3gMn2g5qOewNNO0MQ755Q3DEAhhujE6GsW4AiEAi3r2MFqH4g7rRuudalfG9c4VnbEnn21L9VLanMhdSxc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15937},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"a5460ebbbe8931f06b439a459fa5f3c627bea94c","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"},"_npmVersion":"11.0.0","description":"JavaScript/TypeScript SDK for Agent Network System (ANS) agent registration.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"joi":"^17.0.0","uuid":"^9.0.0","axios":"^1.0.0","multiformats":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/sdk-js_0.0.3_1756095001143_0.6581563433611493","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@ans-project/sdk-js","version":"0.0.4","keywords":["ans","agent","sdk","registration","decentralized-identity","ai","verification","ai-agent"],"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","_id":"@ans-project/sdk-js@0.0.4","maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"bin":{"anslookup":"bin/anslookup.js"},"dist":{"shasum":"f102d0244182d552d7f3dbd6674dca8b76b816e1","tarball":"https://registry.npmjs.org/@ans-project/sdk-js/-/sdk-js-0.0.4.tgz","fileCount":8,"integrity":"sha512-UJ0b/ZmH/MzJmN5OC5nLZiEEvVF1ny+3rMfuyEc1gs3YIh5/YuD7TMcoVnPmvEmA6+u94xRtId9E0Lmn4yzI1w==","signatures":[{"sig":"MEUCIG/CdTtYysTn/MleF7koVbGrxyat/sTyndDYggW/+v82AiEA30bqka+TGLkCZgM1x4LWZdcTPhT3ZzQE1vIaBfV1Ymo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17662},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"d3785911329a62643a44fc33ac2765ed214426d1","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"},"_npmVersion":"11.0.0","description":"JavaScript/TypeScript SDK for Agent Network System (ANS) Client Library.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"joi":"^17.0.0","uuid":"^9.0.0","axios":"^1.0.0","multiformats":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^24.2.1"},"_npmOperationalInternal":{"tmp":"tmp/sdk-js_0.0.4_1761625282024_0.5354099870829487","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"name":"@ans-project/sdk-js","type":"module","version":"0.0.5","description":"JavaScript/TypeScript SDK for Agent Network System (ANS) Client Library.","main":"dist/index.js","types":"dist/index.d.ts","bin":{"anslookup":"bin/anslookup.js"},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"keywords":["ans","agent","sdk","registration","decentralized-identity","ai","verification","ai-agent"],"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","devDependencies":{"@types/node":"^24.2.1","typescript":"^5.0.0"},"dependencies":{"axios":"^1.0.0","joi":"^17.0.0","multiformats":"^12.0.0","uuid":"^9.0.0"},"_id":"@ans-project/sdk-js@0.0.5","gitHead":"d3785911329a62643a44fc33ac2765ed214426d1","_nodeVersion":"24.5.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-DlsK/Tqmnzq1Zb4Q4WZxl1TVzhEP/65HtmEhdCvv2fLC+BG05Xeq2TEJxAFveHGwgbeBPqcc8EoNYQigoRBnTw==","shasum":"409d061db291eee851e6b8bc5c3dda1633e9e98f","tarball":"https://registry.npmjs.org/@ans-project/sdk-js/-/sdk-js-0.0.5.tgz","fileCount":8,"unpackedSize":17662,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHPpKxbiYi28xIE+07Bs1co9eXjavTYJSaERebW4cPCoAiBhq49Ej1rpRxFxp825Io4ynVeqtyxocpNzEwOCWCAgKA=="}]},"_npmUser":{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"},"directories":{},"maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk-js_0.0.5_1761625307245_0.2477479257062538"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-13T02:25:48.413Z","modified":"2025-10-28T04:21:47.669Z","0.0.1":"2025-08-13T02:25:48.685Z","0.0.2":"2025-08-13T02:46:55.027Z","0.0.3":"2025-08-25T04:10:01.330Z","0.0.4":"2025-10-28T04:21:22.230Z","0.0.5":"2025-10-28T04:21:47.450Z"},"author":{"name":"gClouds R&D | gLabs"},"license":"Apache-2.0","keywords":["ans","agent","sdk","registration","decentralized-identity","ai","verification","ai-agent"],"description":"JavaScript/TypeScript SDK for Agent Network System (ANS) Client Library.","maintainers":[{"name":"gclouds","email":"mustafa.gulercan@gclouds.co.uk"}],"readme":"# ANS Node.js SDK: Agent Registration Guide\r\n\r\nThis guide provides instructions for end-users on how to register a new agent with the Agent Network System (ANS) using the Node.js SDK.\r\n\r\n## 1. Prerequisites\r\n\r\n*   **Node.js:** Version 16 or higher.\r\n*   **npm:** Node Package Manager (comes with Node.js).\r\n\r\n## 2. Installation\r\n\r\nThis package is published to npm, you can install it using:\r\n\r\n```bash\r\nnpm install @ans-project/sdk-js\r\n```\r\n\r\n### Using the `anslookup` Command-Line Tool\r\n\r\nThe SDK includes a convenient command-line tool, `anslookup`, for quickly querying the Agent Network System.\r\n\r\nTo use it, you can install the package globally:\r\n\r\n```bash\r\nnpm install -g @ans-project/sdk-js\r\n```\r\n\r\nOnce installed, you can run `anslookup` directly from your terminal:\r\n\r\n```bash\r\n# Get help and see all options\r\nanslookup --help\r\n\r\n# Lookup an agent by its ID\r\nanslookup translator.ans\r\n\r\n# Lookup agents by name and trust level\r\nanslookup --query \"Nia\" --trust-level \"provisional\"\r\n\r\n# Lookup agents by capabilities (use quotes for capabilities with spaces)\r\nanslookup --capabilities \"sales,lead generation\"\r\n\r\n# Lookup agents by policy requirements (pass a JSON string)\r\nanslookup --policy-requirements '{\"verification_status\":\"verified\"}'\r\n```\r\n\r\n## 3. Registering a New Agent\r\n\r\nHere's an example of how to use the SDK to register an agent. You can create a file (e.g., `register-agent.js`) and run it with `node register-agent.js`.\r\n\r\n```javascript\r\nconst { ANSClient } = require('@ans-project/sdk-js'); // If installed via npm\r\n// OR\r\n// const { ANSClient } = require('./dist/index'); // If built locally\r\n\r\nasync function registerNewAgent() {\r\n  // Replace with your actual Cloud Run service URL. Do not change if you do not have an ANS service URL. This service is hosted by gClouds ( a Google Cloud Partner )\r\n  const cloudRunUrl = \"https://ans-register-390011077376.us-central1.run.app\"; \r\n  const client = new ANSClient(cloudRunUrl);\r\n\r\n  // 1. Generate EC Key Pair\r\n  const { publicKey, privateKey } = ANSClient.generateKeyPair();\r\n  console.log(\"Generated Public Key (PEM):\\n\", publicKey);\r\n  console.log(\"Generated Private Key (PEM):\\n\", privateKey); // Keep this secure!\r\n\r\n  // 2. Construct Agent Data\r\n  const agentPayload = {\r\n    agent_id: \"my-nodejs-agent.ans\", // Customize your agent ID\r\n    name: \"My Node.js SDK Agent\",\r\n    description: \"An agent registered via Node.js SDK.\",\r\n    organization: \"Node.js SDK Test Org\",\r\n    capabilities: [\"nodejs_capability\", \"test_feature\"],\r\n    endpoints: { a2a: \"https://nodejs.test.com/a2a\", rest: \"https://nodejs.test.com/api/v1\" },\r\n    public_key: publicKey,\r\n  };\r\n\r\n  try {\r\n    // 3. Register Agent\r\n    console.log(\"Attempting to register agent...\");\r\n    const response = await client.register(agentPayload, privateKey);\r\n    console.log(\"Registration Response:\\n\", JSON.stringify(response, null, 2));\r\n\r\n  } catch (error) {\r\n    console.error(\"Error during agent registration:\", error.message);\r\n    if (error.response && error.response.data) {\r\n      console.error(\"Backend Error Details:\", JSON.stringify(error.response.data, null, 2));\r\n    }\r\n  }\r\n}\r\n\r\nregisterNewAgent();\r\n```\r\n\r\n## 4. Handling Your Cryptographic Keys (Crucial!)\r\n\r\nThe Node.js SDK generates a unique cryptographic key pair (a public key and a private key) for your agent during the registration process. **Securely managing these keys is paramount.**\r\n\r\n*   **Private Key:**\r\n    *   **Purpose:** The private key is used to generate the `signature` that proves your agent's ownership.\r\n    *   **Security:** Your private key **MUST be kept absolutely secret and secure**. If your private key is compromised, someone else could impersonate your agent.\r\n    *   **Storage:**\r\n        *   **NEVER** store private keys directly in your code, commit them to version control (like Git), or expose them in public logs.\r\n        *   For development, you might temporarily store them in secure environment variables or local configuration files (ensure these are `.gitignore`d).\r\n        *   For production, consider using dedicated secure storage solutions like:\r\n            *   **Google Cloud Secret Manager**\r\n            *   Hardware Security Modules (HSMs)\r\n            *   Key Management Systems (KMS)\r\n    *   **The current example generates a new key pair every time it runs.** For a real application, you would generate a key pair once, securely store the private key, and reuse it for subsequent registrations or updates of the same agent.\r\n\r\n*   **Public Key:**\r\n    *   **Purpose:** The public key is part of your agent's identity and is sent to the ANS backend. It allows others to verify signatures made by your private key.\r\n    *   **Security:** Public keys are, by definition, public. They do not need to be kept secret.\r\n\r\n*   **Signature:**\r\n    *   **Purpose:** The signature is a one-time proof of ownership for a specific registration payload. It is sent to the backend for verification.\r\n    *   **Security:** The signature itself is not sensitive after it has been used and verified. Its security relies entirely on the secrecy of the private key used to generate it.\r\n\r\n**Remember: The security of your agent's identity hinges on the secrecy of its private key.**\r\n\r\n---\r\n\r\n## Changelog\r\n\r\n### [0.0.5] - 2025-10-28\r\n\r\n#### Added\r\n-   **Policy Requirements Filter:** The `anslookup` CLI tool now supports a `--policy-requirements` flag. This allows users to perform lookups and filter agents based on specific policy criteria, such as requiring a `\"verified\"` status. The value should be a JSON string.\r\n-   **Public Key in Lookup Response:** The `lookup` method now includes the agent's `public_key` in the response. This is a critical addition that enables third-party verifiers to retrieve the trusted key needed for cryptographic verification of an agent's claims.\r\n\r\n#### Fixed\r\n-   **CLI Argument Parsing:** Fixed a bug in the `anslookup` tool where arguments with values (e.g., `--agent-id my-agent.ans`) were not parsed correctly, causing the value to be ignored.\r\n-   **Snake Case Conversion:** Corrected an issue where kebab-case command-line arguments (e.g., `--trust-level`) were not being correctly converted to the snake_case format (`trust_level`) required by the backend API.\r\n","readmeFilename":"README.md"}