{"_id":"@agnt-sdk/client","_rev":"2-747e69c6385af250699d835e3a807a52","name":"@agnt-sdk/client","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@agnt-sdk/client","version":"0.0.1","keywords":["agnt","api-client","tasks","ai-assistant","typescript"],"author":{"name":"Agnt"},"license":"MIT","_id":"@agnt-sdk/client@0.0.1","maintainers":[{"name":"anindya007","email":"anindya@skej.com"}],"homepage":"https://github.com/agnt-ai/agnt-node/tree/main/packages/client#readme","bugs":{"url":"https://github.com/agnt-ai/agnt-node/issues"},"dist":{"shasum":"3ff30940d11caed9a8a080864a4aa8e36a8ab42d","tarball":"https://registry.npmjs.org/@agnt-sdk/client/-/client-0.0.1.tgz","fileCount":110,"integrity":"sha512-46oFbWSDVTDuomRbRP7umSUmRIPQOX1YPVHVM/oopJoyNpy06Dc0WIBamHVzI9bkBImAXqSCM3/WJCRXB8XWJQ==","signatures":[{"sig":"MEUCIQCBJDzCq5nTzq0vS6DHJA4H1gfbMnVUwUplNNJxfDhFHgIgXz+sRbDAGp3c4EEKWU3WWEdaQ1pXDDG6Blrf3QNO06s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":280246},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"08e7599ad0c8f35e0897fdef91280187fffd67cc","scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist","test:live":"vitest run --config vitest.live.config.mjs","test:watch":"vitest","build:watch":"tsc --watch","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"anindya007","email":"anindya@skej.com"},"repository":{"url":"git+https://github.com/agnt-ai/agnt-node.git","type":"git","directory":"packages/client"},"_npmVersion":"11.7.0","description":"Typed API client for the Agnt platform — chats, tasks, memories, contacts, users, assistants and more","directories":{},"_nodeVersion":"22.17.0","dependencies":{"jose":"^5.9.6","@agnt-sdk/config":"*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.8","typescript":"^5.3.3","@types/node":"^20.0.0","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"tmp":"tmp/client_0.0.1_1772752460833_0.19762270153507355","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@agnt-sdk/client","version":"0.0.2","description":"Typed API client for the Agnt platform — chats, tasks, memories, contacts, users, assistants and more","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","build:watch":"tsc --watch","clean":"rm -rf dist","prepublishOnly":"npm run build","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:live":"vitest run --config vitest.live.config.mjs"},"engines":{"node":">=18.0.0"},"author":{"name":"Agnt"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/agnt-ai/agnt-node.git","directory":"packages/client"},"homepage":"https://github.com/agnt-ai/agnt-node/tree/main/packages/client#readme","bugs":{"url":"https://github.com/agnt-ai/agnt-node/issues"},"keywords":["agnt","api-client","tasks","ai-assistant","typescript"],"publishConfig":{"access":"public"},"dependencies":{"@agnt-sdk/config":"*","jose":"^5.9.6"},"devDependencies":{"@types/node":"^20.0.0","@vitest/coverage-v8":"^2.1.8","typescript":"^5.3.3","vitest":"^2.1.8"},"gitHead":"08e7599ad0c8f35e0897fdef91280187fffd67cc","_id":"@agnt-sdk/client@0.0.2","_nodeVersion":"22.17.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-M7a8gd7zrY0OSNDPDLTlDRlagUt7J2ENeOI8qLZ4pBJKYmg/P4JvEt9IILCv7CYmH0vgvK/VrfQPm37DHh3BVg==","shasum":"19949a069d67414e3507747b018a1ced9571f612","tarball":"https://registry.npmjs.org/@agnt-sdk/client/-/client-0.0.2.tgz","fileCount":54,"unpackedSize":94178,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCuxI9zmbOTzJ5tYto081dwdswskAty8hsq834jeP+9QQIhAKjQT2xzlf3pljxs40cNJrDXnqSezvHEcdKcb9Kj+7Zm"}]},"_npmUser":{"name":"anindya007","email":"anindya@skej.com"},"directories":{},"maintainers":[{"name":"anindya007","email":"anindya@skej.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client_0.0.2_1772752500876_0.22064929570667813"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T23:14:20.752Z","modified":"2026-03-05T23:15:01.456Z","0.0.1":"2026-03-05T23:14:20.984Z","0.0.2":"2026-03-05T23:15:01.021Z"},"bugs":{"url":"https://github.com/agnt-ai/agnt-node/issues"},"author":{"name":"Agnt"},"license":"MIT","homepage":"https://github.com/agnt-ai/agnt-node/tree/main/packages/client#readme","keywords":["agnt","api-client","tasks","ai-assistant","typescript"],"repository":{"type":"git","url":"git+https://github.com/agnt-ai/agnt-node.git","directory":"packages/client"},"description":"Typed API client for the Agnt platform — chats, tasks, memories, contacts, users, assistants and more","maintainers":[{"name":"anindya007","email":"anindya@skej.com"}],"readme":"# @agnt-sdk/client\n\nTyped Node.js client for the [Agnt](https://agnt.ai) REST API.\n\nCovers every SDK-facing resource — users, tasks, chats, memories, contacts, assistants, identifiers, webhooks — with full TypeScript types and a clean two-mode API: **management** (account-level) and **delegated** (user-scoped).\n\n## Installation\n\n```bash\nnpm install @agnt-sdk/client\n```\n\n## Configuration\n\nCreate `agnt.config.js` at your project root (the SDK walks up the directory tree to find it):\n\n```js\n// agnt.config.js\nexport default {\n  privateKey: `-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----`,\n  kid: 'your-key-id',         // from the Agnt dashboard → Certificates\n  apiUrl: 'https://api.agnt.ai',\n};\n```\n\nOr pass config directly — useful in serverless functions where a file isn't available:\n\n```ts\nconst client = await AgntClient.create({\n  config: { privateKey, kid, apiUrl: 'https://api.agnt.ai' }\n});\n```\n\n## Authentication\n\nThe SDK uses **RS256 certificate-based JWTs**. Generate a key pair from the Agnt dashboard under Settings → Certificates. The private key stays in your `agnt.config.js`; the public key is registered on the platform.\n\nTwo token types are issued automatically:\n\n- **Management token** — no `email` claim, account-wide scope. Used by the top-level `client.*` resources.\n- **Delegated token** — includes the user's `email` (and optional name), scoped to that user. Used by `client.as(email).*`.\n\nTokens are cached in-memory for their full 5-minute TTL, so creating many delegated clients is efficient.\n\n## Usage\n\n### Management client\n\n```ts\nimport { AgntClient } from '@agnt-sdk/client';\n\nconst client = await AgntClient.create();\n```\n\n#### Users\n\n```ts\n// Upsert (sync) a user — creates if not exists, no-ops if already exists\nawait client.users.sync({ email: 'alice@example.com', firstName: 'Alice', lastName: 'Smith' });\n\n// List users with pagination\nconst { items, total } = await client.users.list({ perPage: 50 });\n\n// Get a single user (includes nested identifiers and contacts)\nconst user = await client.users.get(userId);\n\n// Update\nawait client.users.update(userId, { firstName: 'Alicia' });\n\n// Delete (also removes all identifiers, preferences, and associated data)\nawait client.users.delete(userId);\n```\n\n#### Assistants\n\n```ts\n// List all assistants for the account\nconst assistants = await client.assistants.list();\n\n// Create\nconst assistant = await client.assistants.create({\n  name: 'travel',\n  email: 'travel@example.com',\n  personality: 'Friendly and efficient travel coordinator',\n});\n\n// Bulk sync — upsert many at once\nawait client.assistants.bulkSync([\n  { name: 'travel', email: 'travel@example.com' },\n  { name: 'finance', email: 'finance@example.com' },\n]);\n```\n\n### Delegated client\n\nSwitch to a user context by calling `.as(email)`. This returns a new `AgntClient` instance that signs all requests with a delegated JWT scoped to that user.\n\n```ts\nconst user = client.as('alice@example.com');\n\n// Optional: pass names so they appear in JWT and are used for auto-provisioning\nconst user = client.as('alice@example.com', { firstName: 'Alice', lastName: 'Smith' });\n```\n\n#### Tasks\n\n```ts\n// Create\nconst task = await user.tasks.create({\n  title: 'Book a flight to NYC next Friday',\n  assistant: assistantId,\n});\n\n// List with filters\nconst { items } = await user.tasks.list({ status: 'pending', perPage: 20 });\n\n// Get, update, delete\nconst task = await user.tasks.get(taskId);\nawait user.tasks.update(taskId, { title: 'Updated title' });\nawait user.tasks.delete(taskId);\n\n// Trigger execution\nconst { executionId } = await user.tasks.process(taskId, { message: 'Start now' });\n\n// Stop a running execution\nawait user.tasks.stop(taskId);\n\n// Feedback\nawait user.tasks.feedback(taskId, 'like');    // thumbs up\nawait user.tasks.feedback(taskId, 'dislike'); // thumbs down\nawait user.tasks.feedback(taskId, null);      // remove feedback\n```\n\n#### Chats\n\n```ts\n// Create a chat with an assistant\nconst chat = await user.chats.create({ title: 'Flight planning', assistantId });\n\n// List\nconst { items } = await user.chats.list({ perPage: 10 });\n\n// Messages\nawait user.chats.messages.add(chatId, { role: 'user', content: 'Find me a flight to NYC' });\nconst { items: messages } = await user.chats.messages.list(chatId);\nawait user.chats.messages.clear(chatId);\n\n// Trigger AI processing\nawait user.chats.process(chatId);\n\n// Delete\nawait user.chats.delete(chatId);\n```\n\n#### Memories\n\n```ts\n// Create\nconst memory = await user.memories.create({ content: 'Prefers aisle seats on flights' });\n\n// List, get, update, delete\nconst { items } = await user.memories.list({ perPage: 50 });\nawait user.memories.update(memoryId, { content: 'Prefers window seats' });\nawait user.memories.delete(memoryId);\n```\n\n#### Contacts\n\n```ts\n// Create\nconst contact = await user.contacts.create({ email: 'bob@example.com', name: 'Bob Smith' });\n\n// List with search\nconst { items } = await user.contacts.list({ search: 'bob', perPage: 20 });\n\n// Update, delete\nawait user.contacts.update(contactId, { name: 'Robert Smith' });\nawait user.contacts.delete(contactId);\n\n// Bulk import (up to 1000 contacts, upserts by email)\nconst result = await user.contacts.bulkImport([\n  { email: 'alice@example.com', name: 'Alice' },\n  { email: 'bob@example.com', name: 'Bob', company: 'Acme' },\n]);\nconsole.log(`Created: ${result.created}, Updated: ${result.updated}, Skipped: ${result.skipped}`);\n\n// Merge two contacts\nawait user.contacts.merge(contactId, mergeIntoContactId);\n```\n\n#### Identifiers\n\nAn identifier is an email address (or other channel) linked to a user. A primary email identifier is automatically provisioned when a user is first synced. Additional identifiers (secondary emails) can be added manually.\n\n```ts\n// List identifiers for the current user\nconst { items } = await user.identifiers.list();\n\n// Add a secondary email\nconst identifier = await user.identifiers.create({ type: 'email', value: 'alice+work@example.com' });\n\n// Delete a secondary identifier (primary cannot be deleted)\nawait user.identifiers.delete(identifierId);\n\n// Preferences — read and write per-skill settings\nconst prefs = await user.identifiers.preferences.list(identifierId);\nawait user.identifiers.preferences.set(identifierId, 'scheduling', {\n  defaults: { virtual: { duration: 45 } }\n});\nconst schedulingPrefs = await user.identifiers.preferences.get(identifierId, 'scheduling');\n```\n\n#### Webhooks\n\n```ts\nawait client.webhooks.update({\n  url: 'https://example.com/webhook',\n  events: ['task.completed', 'task.failed'],\n  enabled: true,\n});\n\nconst { secret } = await client.webhooks.revealSecret();\nawait client.webhooks.test();\n```\n\n## TypeScript types\n\nAll resources expose named types from the top-level export:\n\n```ts\nimport type {\n  User, Task, Chat, ChatMessage,\n  Contact, Memory, Assistant, Identifier,\n  PagedResponse, BulkImportResult,\n  CreateTaskBody, UpdateTaskBody,\n  CreateChatBody, AddMessageBody,\n} from '@agnt-sdk/client';\n```\n\n## Response shapes\n\nAll API responses follow a standard envelope:\n\n```\nList:     { ok: true, <resource>s: [...], page, perPage, total }\nSingle:   { ok: true, <resource>: { ...fields } }\nDelete:   { ok: true, <resource>: { id, deleted: true } }\n```\n\nThe SDK unwraps these automatically — `client.users.list()` returns `PagedResponse<User>`, not the raw envelope.\n\nSee [`docs/api-shapes.md`](../../docs/api-shapes.md) for the full serialized field reference for each resource.\n\n## Testing\n\n```bash\nnpm test                  # unit + dry-run integration tests (no server needed)\nnpm run test:live         # live tests against localhost:3006 (requires running API)\nnpm run test:coverage     # coverage report\n```\n\nThe dry-run tests (`src/__tests__/integration/dryrun.test.ts`) stub all HTTP calls and use a real RSA key pair generated at runtime. They exercise the full code path including JWT signing without needing an API key.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}