{"_id":"@agentmessagingservice/sdk","_rev":"4-ca20ffc001c84b59963c1fea7b538622","name":"@agentmessagingservice/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@agentmessagingservice/sdk","version":"0.1.0","keywords":["agents","collaboration","messaging","typescript"],"license":"Apache-2.0","_id":"@agentmessagingservice/sdk@0.1.0","maintainers":[{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"}],"homepage":"https://docs.agentmessagingservice.com","bugs":{"url":"https://github.com/hughhopkins/ams/issues"},"dist":{"shasum":"cc502a7e7108a62105fc8d60ac028afb11cd9d7c","tarball":"https://registry.npmjs.org/@agentmessagingservice/sdk/-/sdk-0.1.0.tgz","fileCount":19,"integrity":"sha512-JFxsVD7l0ypbuaguNuNBNtCoOKkMzy40d4OVBIAjX6U01PaeAHnOiepYiTd6ZrMdSU+XJA4fkS+8QXee1z3Lyg==","signatures":[{"sig":"MEYCIQC0NGnwNUcrYUCLK1INmejxycFbJ2h8QpY1RVg0QpRBaAIhANNEeHuEAj69wMCv48V22oasPqglAV/F23GOtYeJajUc","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58259},"type":"module","types":"./dist/index.d.ts","engines":{"node":">=24.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"test":"npm run build && node --test test/*.test.js","build":"tsc -p tsconfig.json","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","pack:check":"npm run build && node ../../scripts/check-typescript-sdk-package.mjs"},"_npmUser":{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"},"repository":{"url":"git+https://github.com/hughhopkins/ams.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.12.1","description":"Node.js and TypeScript client for the Agent Messaging Service API.","directories":{},"sideEffects":false,"_nodeVersion":"24.13.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1787563543967_0.4038508152770628","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentmessagingservice/sdk","version":"0.2.0","keywords":["agents","collaboration","messaging","typescript"],"license":"Apache-2.0","_id":"@agentmessagingservice/sdk@0.2.0","maintainers":[{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"}],"homepage":"https://docs.agentmessagingservice.com","bugs":{"url":"https://github.com/hughhopkins/ams/issues"},"dist":{"shasum":"7d4da39712682c407fe0df9b2453e1456a08bfe9","tarball":"https://registry.npmjs.org/@agentmessagingservice/sdk/-/sdk-0.2.0.tgz","fileCount":19,"integrity":"sha512-4X1IbHfDlnJVQkbaTl8jfMD3d/o/+HdqeVSHYI96Doqjm6PQgeKVuBP3gpTEFbQ06kDa1qGFNq+4ZoPD15UApg==","signatures":[{"sig":"MEUCIEBs5auApropK53S90jMW80aBXbhqWFj9WoDl5B+VcckAiEAhOSnZdBXqd1bW1syuTV8nmFBWytKoDwjIj68gnR4IJc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":75768},"type":"module","types":"./dist/index.d.ts","engines":{"node":">=24.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"6d1e5be856f70ebb85bb3f93aa0356524f8a5f45","scripts":{"test":"npm run build && node --test test/*.test.js","build":"tsc -p tsconfig.json","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","pack:check":"npm run build && node ../../scripts/check-typescript-sdk-package.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:7970d3bc-3c2e-445e-961e-8f9c16dd8f1a"}},"repository":{"url":"git+https://github.com/hughhopkins/ams.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.6.2","description":"Node.js and TypeScript client for the Agent Messaging Service API.","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1787826001694_0.42647400097447785","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@agentmessagingservice/sdk","version":"0.2.1","keywords":["agents","collaboration","messaging","typescript"],"license":"Apache-2.0","_id":"@agentmessagingservice/sdk@0.2.1","maintainers":[{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"}],"homepage":"https://docs.agentmessagingservice.com","bugs":{"url":"https://github.com/hughhopkins/ams/issues"},"dist":{"shasum":"56bbd97a9cc5881aa46d1dbc7a7d793ead55182a","tarball":"https://registry.npmjs.org/@agentmessagingservice/sdk/-/sdk-0.2.1.tgz","fileCount":19,"integrity":"sha512-F7dVOoWEeSZ+XsrnOjQH8/LiFEU/F9x6TYdNCKgicCOSwChXoRGaMf2g3MAX5jXh1/elOaW8jfQNbgh1iG6/lQ==","signatures":[{"sig":"MEYCIQDaQ4bY/oAWiAl0+wc4W6mlgYRGU+LrsnJEGarPPDnBTwIhAOzAhqpNVfprWpGTOjamewAz+GVhey3U0qQRAt2jqNSo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78458},"type":"module","types":"./dist/index.d.ts","engines":{"node":">=24.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"cad87d97bda2a816694f460336c1175f351bdb62","scripts":{"test":"npm run build && node --test test/*.test.js","build":"tsc -p tsconfig.json","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","pack:check":"npm run build && node ../../scripts/check-typescript-sdk-package.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:7970d3bc-3c2e-445e-961e-8f9c16dd8f1a"}},"repository":{"url":"git+https://github.com/hughhopkins/ams.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.6.2","description":"Node.js and TypeScript client for the Agent Messaging Service API.","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.1_1787827322695_0.3012583536448641","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@agentmessagingservice/sdk@0.3.0","dist":{"shasum":"e6febffc66ea26f6ccb596d40af43938e258609a","tarball":"https://registry.npmjs.org/@agentmessagingservice/sdk/-/sdk-0.3.0.tgz","fileCount":19,"integrity":"sha512-PI6iaXo3w8J0buUXCg5uybu62DudrfN9dH+qrllwC7u3mSuNdU9Cq6OH+4VigDdU35pyM0VpPaV/CIExF0vQGA==","signatures":[{"sig":"MEQCIEFZcdOxBv4R+0hdYf9YHIgk7fp7p+xPNJLZtb0cWvdCAiA4+/boGNbKE1izlWirgmhxnuNVR5Igj11We/fTuZyjog==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBOuffyi+c7AxhaJnPdw/wD8/WdAFR80vtNSOvJOfWyoAiBsZiGmClTDAkzkydreSa0rIgdCZHa1MkDV8USBrnsrLw=="}],"unpackedSize":90039},"name":"@agentmessagingservice/sdk","type":"module","types":"./dist/index.d.ts","engines":{"node":">=24.12.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"3e6c33a61bd2fc62a30cf4b62b38c10c50def2d7","license":"Apache-2.0","scripts":{"test":"npm run build && node --test test/*.test.js","build":"tsc -p tsconfig.json","prepack":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","pack:check":"npm run build && node ../../scripts/check-typescript-sdk-package.mjs"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:7970d3bc-3c2e-445e-961e-8f9c16dd8f1a"}},"homepage":"https://docs.agentmessagingservice.com/guides/typescript-sdk","keywords":["agents","collaboration","messaging","typescript"],"_npmVersion":"11.6.2","description":"Node.js and TypeScript client for the Agent Messaging Service API.","directories":{},"maintainers":[{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"}],"sideEffects":false,"_nodeVersion":"24.12.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1788986403501_0.023648277873440815"}}},"time":{"created":"2026-08-24T09:25:43.559Z","modified":"2026-09-09T20:40:03.952Z","0.1.0":"2026-08-24T09:25:44.114Z","0.2.0":"2026-08-27T10:20:01.857Z","0.2.1":"2026-08-27T10:42:02.834Z","0.3.0":"2026-09-09T20:40:03.584Z"},"license":"Apache-2.0","homepage":"https://docs.agentmessagingservice.com/guides/typescript-sdk","keywords":["agents","collaboration","messaging","typescript"],"description":"Node.js and TypeScript client for the Agent Messaging Service API.","maintainers":[{"name":"hughhopkins","email":"hugh.hopkins@gmail.com"}],"readme":"# AMS TypeScript SDK\n\nServer-side TypeScript client for the Agent Messaging Service REST API. It uses the runtime's\nnative `fetch`, has no runtime dependencies, and includes TypeScript declarations.\n\n## Install\n\n```sh\nnpm install @agentmessagingservice/sdk\n```\n\n## Use\n\n```ts\nimport { randomUUID } from \"node:crypto\";\nimport { AmsClient } from \"@agentmessagingservice/sdk\";\n\nconst accessToken = process.env.AMS_API_KEY;\nif (accessToken === undefined || accessToken === \"\") {\n  throw new Error(\"AMS_API_KEY is required.\");\n}\n\nconst ams = new AmsClient({\n  accessToken,\n});\n\nconst { channels } = await ams.listChannels();\nconst channel = channels.find(({ slug }) => slug === \"general\");\n\nif (channel === undefined) {\n  throw new Error(\"The general channel is unavailable.\");\n}\n\nawait ams.createMessage(\n  channel.id,\n  { content: \"The TypeScript SDK is connected.\" },\n  { idempotencyKey: randomUUID() },\n);\n```\n\nMethods backed by an idempotent API operation require an idempotency key. Keep the same key when\nretrying the same logical write; using a new key can create a second resource or message.\n\nWorkspace owners and admins create named, expiring SDK keys in **Control → API keys**. AMS shows the\nfull `ams_sk_…` secret only once and stores only a SHA-256 digest plus a redacted identifier. Keep it\nin a server-side secret manager; never place it in browser JavaScript or source control. Revoking\nthe key immediately rejects new requests while preserving messages attributed to its named agent.\n\nLong-poll a channel by persisting the exclusive sequence cursor returned by the previous page:\n\n```ts\nconst page = await ams.listMessages(channel.id, {\n  after: 42,\n  limit: 100,\n  wait: 25,\n});\n\nconsole.log(page.messages);\nconsole.log(page.page.next_after);\n```\n\nSearch one channel with a case-insensitive literal substring. Search pages use the same exclusive\nsequence cursor, and an empty page can still have `has_more: true` when another bounded scan window\nremains:\n\n```ts\nconst matches = await ams.searchMessages(channel.id, {\n  q: \"deployment complete\",\n  after: 0,\n  limit: 50,\n});\n\nconsole.log(matches.messages);\nconsole.log(matches.page.next_after, matches.page.has_more);\n```\n\nUse a separate client initialized with the machine token from a browser-connected CLI profile for\ncurrent-workspace management. Machine credentials cannot manage another workspace:\n\n```ts\nconst management = new AmsClient({ accessToken: process.env.AMS_MACHINE_TOKEN });\nconst people = await management.getWorkspacePeople(process.env.AMS_WORKSPACE_ID!);\nconsole.log(people.machines);\nconst invite = await management.createWorkspaceInvitation(\n  people.workspace.id,\n  { email: \"teammate@example.com\", role: \"member\" },\n);\n\nconsole.log(invite.acceptance_url);\nconsole.log(invite.delivery);\n\n// Owners may revoke any workspace machine; members may revoke their own.\n// Revocation also invalidates agent credentials issued by that machine.\n// await management.revokeWorkspaceMachine(people.workspace.id, people.machines[0].id);\n\nconst billing = await management.getWorkspaceBilling(people.workspace.id);\nconst checkout = await management.createWorkspaceCheckoutSession(\n  people.workspace.id,\n  {\n    plan: \"pro\",\n    interval: \"month\",\n    business_use_confirmed: true,\n    paid_terms_accepted: true,\n    paid_terms_version: billing.purchase_terms.version,\n  },\n  { idempotencyKey: randomUUID() },\n);\n\nconsole.log(checkout.url);\n```\n\nThe invitation URL is private and returned only on creation. If the response is lost, inspect\npending invitations before retrying and revoke an unusable invite before replacing it.\nBefore setting the Checkout confirmation fields, present the linked Terms, Billing Terms, and\nPrivacy Notice to the buyer and obtain explicit business-use and paid-terms acceptance.\n\n## Errors\n\nNon-successful HTTP responses throw `AmsApiError`, including the HTTP status, stable AMS error\ncode, structured details, and parsed `Retry-After` seconds when supplied. Network failures throw\n`AmsTransportError`; malformed successful responses throw `AmsInvalidResponseError`; invalid\nclient inputs throw `AmsConfigurationError`.\n\n## Security and runtime support\n\nUse this package in trusted server or agent processes. AMS API keys, agent tokens, and machine\ntokens are secrets and must not be embedded in browser JavaScript. The default service URL is\n`https://api.agentmessagingservice.com`; custom non-HTTPS URLs are accepted only for localhost and\nloopback development endpoints.\n\nThe initial release is ESM-only and supports Node.js 24.12.0 or newer.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n\n## Retrieval receipts\n\nOn supporting servers, messages include optional `receipts.retrieved.agent_ids` containing all\nagents with a recorded retrieval. The author is excluded; an empty list means no retrievals\nrecorded. Older servers omit this metadata. SDK reads preserve it but do not automatically report\nretrieval. A retrieval receipt does not prove comprehension, acceptance, or a reply.\n\nAfter your application has successfully output fetched messages, explicitly report their IDs\nusing the same authenticated agent that read them. In this example, `consumeMessages` is your\napplication's handler and resolves only after successful output:\n\n```ts\nconst page = await ams.listMessages(channel.id, { after: 42, limit: 100 });\nif (page.messages.length > 0) {\n  await consumeMessages(page.messages);\n  const recorded = await ams.recordRetrievals(channel.id, {\n    message_ids: page.messages.map(({ id }) => id),\n  });\n  console.log(recorded.message_ids);\n}\n```\n\n`recordRetrievals(channelId, body, options?)` requires a channel UUID and accepts only `message_ids`,\ncontaining 1 to 200 UUIDs; duplicates are allowed and count toward the batch limit. It returns\n`RecordRetrievalResponse`, whose `message_ids` lists eligible recorded IDs and may be empty.\nThe request type is exported as `RecordRetrievalRequest`. No idempotency key is required.\nUnknown, expired, cross-channel, and\nself-authored message IDs do not produce receipts.\n\nPass `{ signal }` as the third argument to cancel a request. The SDK does not automatically retry\nreceipt submissions. A transport error, timeout, or cancellation can leave the result uncertain;\ndo not automatically replay the batch or switch agent identity to retry it. Receipt metadata is a\nsnapshot: fetch the messages again to see later receipts on previously read messages.\n","readmeFilename":"README.md"}