{"_id":"@agent_vaults/api-client","_rev":"2-6acf2956997961369f23a341e0b9c3a8","name":"@agent_vaults/api-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agent_vaults/api-client","version":"0.1.0","keywords":["agentvault","filecoin","x402","usdfc","agent-memory","agent-identity","sdk","typescript"],"author":{"name":"AgentVault"},"license":"MIT","_id":"@agent_vaults/api-client@0.1.0","maintainers":[{"name":"xpanvictor","email":"xpanvictor@gmail.com"}],"homepage":"https://github.com/xpanvictor/agentvault/tree/master/packages/agentvault-api","bugs":{"url":"https://github.com/xpanvictor/agentvault/issues"},"dist":{"shasum":"f8fa0a2a2c26964c1351f3ec45cc33b166df377c","tarball":"https://registry.npmjs.org/@agent_vaults/api-client/-/api-client-0.1.0.tgz","fileCount":22,"integrity":"sha512-OeXMFxe/elLDBg8IsNqnWlkp6C7oCV06S7n0Zl2Zxpr9jjTgWeO7KGAyl68gMjFeoxLLcHJMTPn3yLAJxO2Cpw==","signatures":[{"sig":"MEUCIQDuFQ/j3OdCCM0lqEjz5QDpTEC0J+z93WcIfhBlUEC3NAIgL0m+o0hI79itxQl9oHqW8qRc6iT/K6eQPPiFDLwQPAQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43164},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"cb0fd89609d424f7bf7e8bea88ae6d51f85929c3","scripts":{"dev":"tsx watch src/index.ts","test":"vitest run --config vitest.config.ts","build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepare":"npm run build","test:demo":"AGENTVAULT_TEST_DEMO_LOGS=true vitest run --config vitest.config.ts --reporter verbose --testNamePattern end-to-end","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest --config vitest.config.ts"},"_npmUser":{"name":"xpanvictor","email":"xpanvictor@gmail.com"},"repository":{"url":"git+https://github.com/xpanvictor/agentvault.git","type":"git","directory":"packages/agentvault-api"},"_npmVersion":"11.6.1","description":"Type-safe AgentVault SDK for identity, verifiable memory, and x402 payment flows","directories":{},"sideEffects":false,"_nodeVersion":"24.11.0","dependencies":{"viem":"2.x"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.15.0","dotenv":"^16.4.7","vitest":"^2.1.9","typescript":"^5.5.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/api-client_0.1.0_1774374472580_0.6840500961103595","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-03-24T17:47:52.520Z","modified":"2026-03-24T19:04:34.383Z","0.1.0":"2026-03-24T17:47:52.760Z"},"bugs":{"url":"https://github.com/xpanvictor/agentvault/issues"},"author":{"name":"AgentVault"},"license":"MIT","homepage":"https://github.com/xpanvictor/agentvault/tree/master/packages/agentvault-api","keywords":["agentvault","filecoin","x402","usdfc","agent-memory","agent-identity","sdk","typescript"],"repository":{"url":"git+https://github.com/xpanvictor/agentvault.git","type":"git","directory":"packages/agentvault-api"},"description":"Type-safe AgentVault SDK for identity, verifiable memory, and x402 payment flows","maintainers":[{"email":"mercybomanaps@gmail.com","name":"bomanaps"},{"email":"xpanvictor@gmail.com","name":"xpanvictor"}],"readme":"# @agent_vaults/api-client\n\nType-safe JavaScript/TypeScript SDK for AgentVault.\n\nThis package is designed as a product SDK interface (identity, verifiable memory, payment-assisted storage flow).\n\n## Install\n\n```bash\nnpm install @agent_vaults/api-client\n```\n\n## Exposed Interface\n\n- `AgentVaultClient`: main SDK client\n- `AgentVaultError`: structured SDK errors\n- `ViemX402PaymentSigner`: drop-in signer for paid operations\n- Signing utilities for registration and payment payload creation\n\n## Quick Start\n\n```ts\nimport {\n  AgentVaultClient,\n  ViemX402PaymentSigner,\n} from \"@agentvault/api-client\";\n\nconst client = new AgentVaultClient({\n  baseUrl: \"http://localhost:3500\",\n  paymentSigner: new ViemX402PaymentSigner(process.env.PRIVATE_KEY as `0x${string}`),\n});\n\nconst health = await client.getHealth();\nconsole.log(health.status);\n```\n\n## Core Interface\n\n### 1) Agent identity\n\n```ts\nimport {\n  AgentVaultClient,\n  createSignedRegisterAgentRequest,\n} from \"@agentvault/api-client\";\n\nconst client = new AgentVaultClient({ baseUrl: \"http://localhost:3500\" });\n\nconst registration = await createSignedRegisterAgentRequest(\n  process.env.PRIVATE_KEY as `0x${string}`,\n  {\n    name: \"ResearchAgent\",\n    version: \"1.0.0\",\n    x402Support: true,\n    capabilities: [\"analyze\", \"store\"],\n  },\n);\n\nconst agent = await client.registerAgent(registration);\n```\n\n### 2) Store and retrieve memory\n\n```ts\nconst stored = await client.store({\n  agentId: agent.agentId,\n  data: JSON.stringify({ summary: \"daily run\", ts: Date.now() }),\n  metadata: { type: \"state\", tags: [\"daily\", \"ops\"] },\n});\n\nconst recalled = await client.retrieve(stored.vaultId);\nconsole.log(recalled.data);\n```\n\n### 3) Verification and audit\n\n```ts\nconst verify = await client.verify(stored.pieceCid);\nconst vaults = await client.listVaults(agent.agentId);\nconst audit = await client.getAuditTrail(agent.agentId);\n```\n\n### 4) Settlement visibility\n\n```ts\nconst settlements = await client.listSettlements();\n```\n\n## Signer Utilities\n\n### Registration helpers\n\n- `createRegistrationMessage(address)`\n- `signRegistrationMessage(privateKey)`\n- `createSignedRegisterAgentRequest(privateKey, agentCard)`\n\n### Payment helpers\n\n- `signX402Payment(requirements, privateKey, options)`\n- `toPaymentHeader(payment)`\n- `ViemX402PaymentSigner`\n\nUse signer options if your verifier expects custom domain values:\n\n```ts\nconst signer = new ViemX402PaymentSigner(PRIVATE_KEY, {\n  tokenName: \"USDFC\",\n  tokenVersion: \"1\",\n});\n```\n\n## Error Handling\n\nThe SDK throws `AgentVaultError` for non-success responses.\n\n```ts\nimport { AgentVaultError } from \"@agentvault/api-client\";\n\ntry {\n  await client.store({ agentId, data: \"payload\" });\n} catch (error) {\n  if (error instanceof AgentVaultError) {\n    console.error(error.status, error.code, error.reason);\n  }\n}\n```\n\n## Environment Notes\n\n`AgentVaultClient` resolves base URL in this order:\n\n1. `config.baseUrl`\n2. `process.env.BaseAgentVaultUrl`\n3. `http://localhost:3500`\n\n## Demo-Style E2E Run\n\nThis package includes an integration flow test with optional narrated logs.\n\n```bash\ncd packages/agentvault-api\nnpm install\nnpm run test:demo\n```\n\nTest env template:\n\n- `.env.example` in this package\n\n## API Surface\n\nMain exports from this package:\n\n- `AgentVaultClient`\n- `AgentVaultError`\n- `ViemX402PaymentSigner`\n- `createRegistrationMessage`\n- `signRegistrationMessage`\n- `createSignedRegisterAgentRequest`\n- `signX402Payment`\n- `toPaymentHeader`\n\nBackward-compatible aliases are also exported:\n\n- `AgentVaultApiClient`\n- `AgentVaultApiError`\n\n## Build and Publish\n\n```bash\ncd packages/agentvault-api\nnpm run clean\nnpm run typecheck\nnpm run build\nnpm pack\n```\n\nThen publish from this directory:\n\n```bash\nnpm publish --access public\n```\n","readmeFilename":"README.md"}