{"_id":"@agentvend/agent-sdk","_rev":"4-cec9d4ae1ed0e33b4ccf2ef138678ab2","name":"@agentvend/agent-sdk","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@agentvend/agent-sdk","version":"0.0.1","keywords":["agentvend","sdk","hmac"],"author":"","license":"MIT","_id":"@agentvend/agent-sdk@0.0.1","maintainers":[{"name":"agentvend","email":"support@agentvend.ai"}],"dist":{"shasum":"5bab490a6bed4c4e95d23af3a89c51f63d1e1025","tarball":"https://registry.npmjs.org/@agentvend/agent-sdk/-/agent-sdk-0.0.1.tgz","fileCount":23,"integrity":"sha512-uK/qqVeUWEtSFfG64kcDLuF7LPRxFM9PJSVjCr3fhEyjVyUbGDOzrH9d4VLKl56YzG1VXFo66IpI+Gy/YOjhbw==","signatures":[{"sig":"MEUCIQC5nzD8y4AVB/JfyXodC+RH9PwbaQceSLVPTLPXB8TlJwIgOxp0ai2hItkBmJPGNT4Ij4NUR2iVNWfMiKfS41SE50k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":128994},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"558315f799a523e60d79bec6abce14473ff422da","scripts":{"test":"jest","build":"tsup src/index.ts --format cjs,esm --dts --clean","prepublishOnly":"npm run build"},"_npmUser":{"name":"agentvend","email":"support@agentvend.ai"},"_npmVersion":"10.9.2","description":"AgentVend SDK - verify HMAC, validate keys, report usage, progress, completion","directories":{},"_nodeVersion":"22.14.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.5.0","ts-jest":"^29.1.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-sdk_0.0.1_1775042211386_0.990397271692909","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@agentvend/agent-sdk","version":"0.0.2","keywords":["agentvend","sdk","hmac"],"author":"","license":"MIT","_id":"@agentvend/agent-sdk@0.0.2","maintainers":[{"name":"agentvend","email":"support@agentvend.ai"}],"dist":{"shasum":"91ad9ce205729bef4f58ff60a735ae34d603a070","tarball":"https://registry.npmjs.org/@agentvend/agent-sdk/-/agent-sdk-0.0.2.tgz","fileCount":25,"integrity":"sha512-f24TBiOwMWFg/lel9+Wo8w2QILhy0IVKc9yDPlsGlCCvcM/Gah3uX/eYyihtU3f9FH6698h1ke9i6imVf5nj9A==","signatures":[{"sig":"MEUCIEwkfPziPfvNI2XT9sfYu9l73PkoiWZOAdND3MZS5MW0AiEA9u4saZQD6i6pWqziQoqr3gD2eIHlDWnmVwcIGskzCes=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":124974},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"558315f799a523e60d79bec6abce14473ff422da","scripts":{"test":"jest","build":"tsup src/index.ts --format cjs,esm --dts --clean","prepublishOnly":"npm run build"},"_npmUser":{"name":"agentvend","email":"support@agentvend.ai"},"_npmVersion":"10.9.2","description":"AgentVend SDK - verify HMAC, validate keys, report usage, progress, completion","directories":{},"_nodeVersion":"22.14.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.5.0","ts-jest":"^29.1.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-sdk_0.0.2_1775042972175_0.025569311860172306","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@agentvend/agent-sdk","version":"0.0.3","keywords":["agentvend","sdk","hmac"],"author":"","license":"MIT","_id":"@agentvend/agent-sdk@0.0.3","maintainers":[{"name":"agentvend","email":"support@agentvend.ai"}],"homepage":"https://github.com/agentvend/agentvend-sdk/tree/master/sdk-js#readme","bugs":{"url":"https://github.com/agentvend/agentvend-sdk/issues"},"dist":{"shasum":"21221aa0330b2cbc138443ddc28de085ea09ae33","tarball":"https://registry.npmjs.org/@agentvend/agent-sdk/-/agent-sdk-0.0.3.tgz","fileCount":6,"integrity":"sha512-x2PhCH46vJ1Aar5yfT3OBBR5cs0jjLJXbpjYoPrWD8YwP2wmElx/NkaSkXtpulyVj3+V6a1c0CF+BikPmBXD8g==","signatures":[{"sig":"MEUCIFDld0ISxQUNKQ4YP0gjc8cttrd24QAC3fLgR3zDoR8cAiEAzdhXy64PpgYBbt0mMwyYwNX7mw2XjfIkDZARVS1BG08=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68646},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"558315f799a523e60d79bec6abce14473ff422da","scripts":{"test":"jest","build":"tsup src/index.ts --format cjs,esm --dts --clean","prepublishOnly":"npm run build"},"_npmUser":{"name":"agentvend","email":"support@agentvend.ai"},"repository":{"url":"git+https://github.com/agentvend/agentvend-sdk.git","type":"git","directory":"sdk-js"},"_npmVersion":"10.9.2","description":"AgentVend SDK - verify HMAC, validate keys, report usage, progress, completion","directories":{},"_nodeVersion":"22.14.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.5.0","ts-jest":"^29.1.2","typescript":"^5.3.3","@types/jest":"^29.5.12","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-sdk_0.0.3_1775043189655_0.18051668148854239","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@agentvend/agent-sdk","version":"0.0.4","description":"AgentVend SDK - verify HMAC, validate keys, report usage, progress, completion","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean","test":"jest","prepublishOnly":"npm run build"},"keywords":["agentvend","sdk","hmac"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/agentvend/agentvend-sdk.git","directory":"sdk-js"},"bugs":{"url":"https://github.com/agentvend/agentvend-sdk/issues"},"homepage":"https://github.com/agentvend/agentvend-sdk/tree/master/sdk-js#readme","devDependencies":{"@types/jest":"^29.5.12","@types/node":"^20.11.0","jest":"^29.7.0","tsup":"^8.5.0","ts-jest":"^29.1.2","typescript":"^5.3.3"},"dependencies":{},"engines":{"node":">=18"},"_id":"@agentvend/agent-sdk@0.0.4","gitHead":"1ac9a9bd1e5dec321a5a9f0bf74974d868d02083","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-tCTxE8DsyV4M89sl+QO5l0qGzPHxf67rZkDAbZkQQ4DfNwMAOTSi+10uqD7IL/RRIeqCISKB+FMYO6cExjFlZg==","shasum":"e42533eed58a2edfcbc3ac26d98753bf489163ef","tarball":"https://registry.npmjs.org/@agentvend/agent-sdk/-/agent-sdk-0.0.4.tgz","fileCount":6,"unpackedSize":81548,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF3bQ0Dztj2rhFNi8i2hDBTGVSTNuglnR2JnkHECFgsSAiEAzj6MfEsJdNg+wk2bBLCYZmPUrPZUVFMSRv4O5YAlbcA="}]},"_npmUser":{"name":"agentvend","email":"support@agentvend.ai"},"directories":{},"maintainers":[{"name":"agentvend","email":"support@agentvend.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-sdk_0.0.4_1775393331414_0.12722183385343655"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-01T11:16:51.275Z","modified":"2026-04-05T12:48:51.738Z","0.0.1":"2026-04-01T11:16:51.516Z","0.0.2":"2026-04-01T11:29:32.330Z","0.0.3":"2026-04-01T11:33:09.798Z","0.0.4":"2026-04-05T12:48:51.612Z"},"bugs":{"url":"https://github.com/agentvend/agentvend-sdk/issues"},"license":"MIT","homepage":"https://github.com/agentvend/agentvend-sdk/tree/master/sdk-js#readme","keywords":["agentvend","sdk","hmac"],"repository":{"type":"git","url":"git+https://github.com/agentvend/agentvend-sdk.git","directory":"sdk-js"},"description":"AgentVend SDK - verify HMAC, validate keys, report usage, progress, completion","maintainers":[{"name":"agentvend","email":"support@agentvend.ai"}],"readme":"# AgentVend SDK (JavaScript/TypeScript)\r\n\r\n**Package:** `@agentvend/agent-sdk`\r\n\r\nVerify inbound HMAC, validate agent keys, run usage pre-flight checks, report usage, progress, and completion, and poll async job status.\r\n\r\n## API origin\r\n\r\nBy default, the SDK uses the production AgentVend API origin. Override when needed (non-production or private deployments):\r\n\r\n- **`AgentVendClient`:** pass `apiUrl`, or set **`AGENTVEND_API_URL`**\r\n- **Standalone helpers:** optional `baseUrl` on each call (same default when omitted)\r\n\r\n## Unified client (recommended)\r\n\r\n`AgentVendClient` uses optional **`AGENTVEND_AGENT_ID`**, required **`AGENTVEND_AGENT_SECRET`** (unless passed in the constructor), and optional **`AGENTVEND_API_URL`**.\r\n\r\n```ts\r\nimport { AgentVendClient } from '@agentvend/agent-sdk';\r\n\r\nconst client = new AgentVendClient({\r\n  agentId: 'agent-uuid',\r\n  agentSecret: 'secret',\r\n});\r\nawait client.getRequestStatus(requestId, agentKey);\r\nawait client.reportUsage(userId, agentId, 1);\r\nawait client.validateAgentKey(agentKey);\r\nconst estimate = await client.estimateUsage(agentKey, 1);\r\nif (estimate) {\r\n  const allowed = estimate.wouldAllow;\r\n  const status = estimate.httpStatus;\r\n}\r\n```\r\n\r\n### Verify signature and user context together\r\n\r\nWhen the gateway sends **`X-AgentVend-Signing-Version: 2`**, verification uses the newer user-context suffix (no quota segment in the signed material). `verifySignatureFromHeaders` reads that header automatically.\r\n\r\n```ts\r\nimport { verifySignatureFromHeadersAndGetUserContext } from '@agentvend/agent-sdk';\r\n\r\nconst ctx = verifySignatureFromHeadersAndGetUserContext(agentSecret, headers, rawBody);\r\nif (ctx) { /* trusted */ }\r\n```\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install @agentvend/agent-sdk\r\n```\r\n\r\n## API highlights\r\n\r\n- `AgentVendHeaders` — canonical `X-AgentVend-*` names (including signing-version for gateway HMAC v2)\r\n- `buildGatewayUserContextString` / `buildGatewayUserContextStringV2` — inbound suffix helpers\r\n- `verifyInboundHmac` / `verifySignatureFromHeaders` — inbound gateway HMAC\r\n- `getUserContext` — parses headers (case-insensitive keys)\r\n- `AgentVendClient` — validate key, estimate usage, usage reporting, gateway polling\r\n- `validateAgentKey` / `estimateUsage` — Core calls with response HMAC verification\r\n- `reportUsage`, `reportProgress`, `reportCompletion` — usage service\r\n- `getRequestStatus`, `getRequestResult` — async job polling\r\n\r\n## Examples\r\n\r\n### Verify HMAC (backend)\r\n\r\n```ts\r\nimport { verifySignatureFromHeaders, getUserContext } from '@agentvend/agent-sdk';\r\n\r\nconst agentSecret = 'your-agent-secret';\r\nconst valid = verifySignatureFromHeaders(agentSecret, req.headers, rawBodyString);\r\nif (valid) {\r\n  const ctx = getUserContext(req.headers);\r\n}\r\n```\r\n\r\n### Validate agent key (caller)\r\n\r\n```ts\r\nimport { validateAgentKey } from '@agentvend/agent-sdk';\r\n\r\nconst result = await validateAgentKey({\r\n  agentKey: 'bearer-token',\r\n  agentId: 'agent-id',\r\n  agentSecret: 'agent-secret',\r\n});\r\n```\r\n\r\nOptional `baseUrl` when not using the default production origin.\r\n\r\n### Usage estimate (caller)\r\n\r\nSame trust model as validate: JSON body with the agent key (no separate bearer on Core). Response HMAC is verified for success and typical denial statuses when signature headers are present.\r\n\r\n```ts\r\nimport { estimateUsage } from '@agentvend/agent-sdk';\r\n\r\nconst est = await estimateUsage({\r\n  agentKey: 'bearer-token',\r\n  agentId: 'agent-id',\r\n  agentSecret: 'agent-secret',\r\n  estimatedUnits: 1,\r\n});\r\n```\r\n\r\n### Report usage\r\n\r\n```ts\r\nimport { reportUsage } from '@agentvend/agent-sdk';\r\n\r\nawait reportUsage({\r\n  userId: 'u1',\r\n  agentId: 'a1',\r\n  unitsUsed: 1,\r\n  agentSecret: 'secret',\r\n});\r\n```\r\n\r\n### Progress and completion (async)\r\n\r\nURLs come from the platform (`progress_url`, `callback_url`).\r\n\r\n```ts\r\nimport { CompletionStatus, reportProgress, reportCompletionWithResult } from '@agentvend/agent-sdk';\r\n\r\nawait reportProgress({\r\n  progressUrl,\r\n  requestId,\r\n  stage: 'processing',\r\n  percentageComplete: 50,\r\n  agentSecret,\r\n});\r\nawait reportCompletionWithResult({\r\n  callbackUrl,\r\n  requestId,\r\n  status: CompletionStatus.Completed,\r\n  result: 'done',\r\n  agentSecret,\r\n  units: 1,\r\n});\r\n```\r\n\r\n### Job status / result (caller)\r\n\r\n```ts\r\nimport { getRequestStatus, getRequestResult } from '@agentvend/agent-sdk';\r\n\r\nconst st = await getRequestStatus({ requestId, agentKey });\r\nconst res = await getRequestResult({ requestId, agentKey });\r\n```\r\n\r\nOptional `baseUrl` on each call when not using the default origin.\r\n\r\n## Build & test\r\n\r\n```bash\r\nnpm ci\r\nnpm run build\r\nnpm test\r\n```\r\n\r\n## Release (npm)\r\n\r\nPackage name: **`@agentvend/agent-sdk`** ([npm scoped packages](https://docs.npmjs.com/about-scopes-and-packages)).\r\n\r\n1. **Version** — Bump `\"version\"` in [`package.json`](package.json) (SemVer). npm will not let you publish the same version twice.\r\n2. **Verify** — `npm ci`, `npm test`, and `npm run build` (or rely on `prepublishOnly`, which runs `build` on `npm publish`).\r\n3. **Login** — `npm login` on the machine that will publish, or use an **automation token** / `NPM_TOKEN` in CI (see [access tokens](https://docs.npmjs.com/about-access-tokens) and [CI workflows](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow)).\r\n4. **Publish** — From `sdk-js`:\r\n\r\n   ```bash\r\n   npm publish --access public\r\n   ```\r\n\r\n   The first publish of a **scoped** package to the public registry must use `--access public` (subsequent publishes can omit it if the package is already public).\r\n\r\n5. **Tag** — Tag the Git commit that matches the published version.\r\n\r\nOptional: `npm publish --dry-run` to inspect the tarball without uploading. `repository`, `files` (`dist`, `README.md`), and `prepublishOnly` are already set in `package.json`.\r\n\r\nProtocol details: [AgentVend documentation](https://agentvend.ai/docs).\r\n","readmeFilename":"README.md"}