{"_id":"@agentvend/service-sdk","_rev":"2-9ec8d92a826b1ee55760b38514a198d5","name":"@agentvend/service-sdk","dist-tags":{"latest":"0.0.7"},"versions":{"0.0.6":{"name":"@agentvend/service-sdk","version":"0.0.6","keywords":["agentvend","sdk","hmac"],"author":"","license":"MIT","_id":"@agentvend/service-sdk@0.0.6","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":"3e4c7a0b995f8fb8fcf5908b3872815b71cefdda","tarball":"https://registry.npmjs.org/@agentvend/service-sdk/-/service-sdk-0.0.6.tgz","fileCount":6,"integrity":"sha512-2kbRlMXFwMiwr0uGz8aS3sQMudOCJcsABjv8l8+VE3KlI+G1m466SDXvZL2qLTjSStO7xL0RzN3PtdkHNtmT8g==","signatures":[{"sig":"MEYCIQDAqQGsgbt1Dafk5cFJE4WAfeCdpHkcJY3YeY881hRdiAIhAPtobNy7/Bp0OKmH+svCKjHybIFpMp7e1dzXmE+Y86Pe","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":97985},"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":"977246f37a5f829c0bee6667ea77ce10239e8327","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/service-sdk_0.0.6_1778184167762_0.17951007036839717","host":"s3://npm-registry-packages-npm-production"}},"0.0.7":{"name":"@agentvend/service-sdk","version":"0.0.7","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/service-sdk@0.0.7","gitHead":"03eef3aedbd23948a50d84f41903ea932123641a","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-VjK9J/z3Jzu/zGN5b3m0C1XcGtt5rCmrJCuOOMf0yX/WrtNRy3UorgV4qlIE/bdmB4cGuIx1eoI4YXXUOjG0vA==","shasum":"3f72430b195d0fa31ab5e1620574319d3cff9c91","tarball":"https://registry.npmjs.org/@agentvend/service-sdk/-/service-sdk-0.0.7.tgz","fileCount":6,"unpackedSize":99122,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFebvBgUCh+ZDymvh3z1+9v5VfupKvvtvh3wXazDSlnKAiEAnXQqdkRA1FAOnHgnr/QGa6f0IopDB4flLtn1Ui26YRo="}]},"_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/service-sdk_0.0.7_1778256876137_0.5873205357306532"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-07T20:02:47.661Z","modified":"2026-05-08T16:14:36.439Z","0.0.6":"2026-05-07T20:02:47.950Z","0.0.7":"2026-05-08T16:14:36.327Z"},"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/service-sdk` (version **0.0.7** in this repo)\r\n\r\nVerify inbound HMAC, validate **service keys**, run usage pre-flight (service-key **and** JWT paths), **gateway invoke** (sync/async), report usage, progress, completion, and poll async job status.\r\n\r\nThis README covers the public SDK contract and usage examples.\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\r\n## AgentVend client (recommended)\r\n\r\n`AgentVendClient` uses optional **`AGENTVEND_SERVICE_ID`** (service UUID), required **`AGENTVEND_SERVICE_SECRET`** (unless passed as `serviceSecret`), and optional **`AGENTVEND_API_URL`**.\r\n\r\n```ts\r\nimport { AgentVendClient } from '@agentvend/service-sdk';\r\n\r\nconst client = new AgentVendClient({\r\n  serviceId: 'service-uuid',\r\n  serviceSecret: 'secret',\r\n});\r\nawait client.getRequestStatus(requestId, serviceKey);\r\nawait client.reportUsage(userId, serviceId, 1);\r\nawait client.validateServiceKey(serviceKey);\r\nconst estimate = await client.estimateUsage(serviceKey, 1);\r\nif (estimate) {\r\n  const allowed = estimate.wouldAllow;\r\n  const status = estimate.httpStatus;\r\n}\r\n\r\n// JWT usage estimate (unsigned Core response): internal Core user id + service id + units\r\n// await client.estimateUsageWithJwt(bearerJwt, coreUserId, serviceId, 1);\r\n\r\n// Gateway invoke (Bearer = service key): method, serviceId, endpointId, serviceKey, optional body + async flag\r\n// await client.invokeService('POST', serviceId, endpointId, serviceKey, { body: '{}', async: false });\r\n```\r\n\r\n### Verify signature and user context together\r\n\r\nVerification defaults to signing version **v2** (newer user-context suffix, no quota segment in the signed material). `verifySignatureFromHeaders` also reads `X-AgentVend-Signing-Version` when present.\r\n\r\n```ts\r\nimport { verifySignatureFromHeadersAndGetUserContext } from '@agentvend/service-sdk';\r\n\r\nconst ctx = verifySignatureFromHeadersAndGetUserContext(serviceSecret, headers, rawBody);\r\nif (ctx) { /* trusted */ }\r\n```\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install @agentvend/service-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, estimates, invoke, usage reporting, gateway polling\r\n- `validateServiceKey` / `estimateUsage` — Core **service-key** paths; response HMAC verified when headers present\r\n- `estimateUsageWithJwt` — Core `POST …/billing/usage/estimate` with Bearer JWT (unsigned response)\r\n- `invokeService` — gateway `…/service/{serviceId}/endpoint/…/invoke` and `…/invoke/async`\r\n- `reportUsage`, `reportProgress`, `reportCompletion` — usage service (**report** body uses ISO `timestamp`; `X-AgentVend-Timestamp` = epoch **seconds** for HMAC)\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/service-sdk';\r\n\r\nconst serviceSecret = 'your-service-shared-secret';\r\nconst valid = verifySignatureFromHeaders(serviceSecret, req.headers, rawBodyString);\r\nif (valid) {\r\n  const ctx = getUserContext(req.headers);\r\n}\r\n```\r\n\r\n### Validate service key (caller)\r\n\r\n```ts\r\nimport { validateServiceKey } from '@agentvend/service-sdk';\r\n\r\nconst result = await validateServiceKey({\r\n  serviceKey: 'bearer-token',\r\n  serviceId: 'service-id',\r\n  serviceSecret: 'service-secret',\r\n});\r\n```\r\n\r\nOptional `baseUrl` when not using the default production origin. Successful validate results include **`serviceKeyId`** when Core returns it (§2.1).\r\n\r\n### Usage estimate (caller)\r\n\r\nSame trust model as validate: JSON body with the service 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/service-sdk';\r\n\r\nconst est = await estimateUsage({\r\n  serviceKey: 'bearer-token',\r\n  serviceId: 'service-id',\r\n  serviceSecret: 'service-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/service-sdk';\r\n\r\nawait reportUsage({\r\n  userId: 'u1',\r\n  serviceId: 'a1',\r\n  unitsUsed: 1,\r\n  serviceSecret: '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/service-sdk';\r\n\r\nawait reportProgress({\r\n  progressUrl,\r\n  requestId,\r\n  stage: 'processing',\r\n  percentageComplete: 50,\r\n  serviceSecret,\r\n});\r\nawait reportCompletionWithResult({\r\n  callbackUrl,\r\n  requestId,\r\n  status: CompletionStatus.Completed,\r\n  result: 'done',\r\n  serviceSecret,\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/service-sdk';\r\n\r\nconst st = await getRequestStatus({ requestId, serviceKey });\r\nconst res = await getRequestResult({ requestId, serviceKey });\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/service-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\nContract reference: this README and the package API surface.\r\n","readmeFilename":"README.md"}