{"_id":"@cognethics/sdk","_rev":"4-ab5988bb05aea965c5a90f249df64053","name":"@cognethics/sdk","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@cognethics/sdk","version":"0.2.0","keywords":["cognethics","sdk","agents","platform","ai"],"author":{"name":"Cognethics","email":"noreply@cognethics.com"},"license":"SEE LICENSE IN LICENSE","_id":"@cognethics/sdk@0.2.0","maintainers":[{"name":"cognethics.com","email":"dev@cognethics.com"}],"homepage":"https://cognethics.com","bugs":{"url":"https://developers.cognethics.com"},"dist":{"shasum":"20130472ed5e0b7c40a93cc7a5089a0984617020","tarball":"https://registry.npmjs.org/@cognethics/sdk/-/sdk-0.2.0.tgz","fileCount":154,"integrity":"sha512-5aXGUekKSuUFv104P5w9fFlKDH6TgcOJx5K2F1VX4uppyRIN11v/G8I99z2AlBWhFpTQ0DTMXV67jxeT720ZSw==","signatures":[{"sig":"MEYCIQCWD5Mrsj00vuW+Z4rJBi+0n02GzRP7mdUsz8qPv2QRtQIhALEr9gKxA45mtREt8XkS84hwgtMnohg4TgKiT2g45a5f","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5345554},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"a9de01016024d22a8c2ad88045c7c713a77e82e1","private":false,"scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsup && npm run build:types && npm run build:cts-types","regen":"cd ../../backend && . venv/bin/activate && python manage.py prism_codegen --target=typescript --out=../clients/typescript/src/generated","typecheck":"tsc --noEmit","test:watch":"vitest","build:types":"tsc -p tsconfig.build.json","pack:dryrun":"npm pack --dry-run","prepublishOnly":"npm run build && npm test","publish-dryrun":"npm run typecheck && npm test && npm run build && npm pack --dry-run","build:cts-types":"cp dist/index.d.ts dist/index.d.cts"},"_npmUser":{"name":"cognethics.com","email":"dev@cognethics.com"},"repository":{"url":"git+https://github.com/cognethics/sdk-typescript.git","type":"git"},"_npmVersion":"10.9.7","description":"Official TypeScript SDK for the Cognethics platform","directories":{},"_nodeVersion":"22.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","vitest":"^1.4.0","typescript":"^5.4.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1779670678866_0.4664333785064012","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@cognethics/sdk","version":"0.2.1","keywords":["cognethics","sdk","agents","platform","ai"],"author":{"name":"Cognethics","email":"noreply@cognethics.com"},"license":"SEE LICENSE IN LICENSE","_id":"@cognethics/sdk@0.2.1","maintainers":[{"name":"cognethics.com","email":"dev@cognethics.com"}],"homepage":"https://cognethics.com","bugs":{"url":"https://developers.cognethics.com"},"dist":{"shasum":"37a0a0db376f943037656a2b9c7ec9a4cad47816","tarball":"https://registry.npmjs.org/@cognethics/sdk/-/sdk-0.2.1.tgz","fileCount":154,"integrity":"sha512-r7Hgmey/zf6fx07UXlQ5IHafHRzdsUqfjKUtLwiu+PRHoEQDuuSxUoXtVthXIyML8o6Z7D9YwpNY19qkUsSruQ==","signatures":[{"sig":"MEUCIDftY53xxYgyTt08V99QLlCPAFwTLMiHIrpTUWPJfdJmAiEA2KYtdFR8QktPo5esfFny4DLcxBL3gekp4+3bOP9W8g4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5343394},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"bb8cc2cc7019395b507289a77d5198dc0aee942d","private":false,"scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsup && npm run build:types && npm run build:cts-types","regen":"cd ../../backend && . venv/bin/activate && python manage.py prism_codegen --target=typescript --out=../clients/typescript/src/generated","typecheck":"tsc --noEmit","test:watch":"vitest","build:types":"tsc -p tsconfig.build.json","pack:dryrun":"npm pack --dry-run","prepublishOnly":"npm run build && npm test","publish-dryrun":"npm run typecheck && npm test && npm run build && npm pack --dry-run","build:cts-types":"cp dist/index.d.ts dist/index.d.cts"},"_npmUser":{"name":"cognethics.com","email":"dev@cognethics.com"},"repository":{"url":"git+https://github.com/cognethics/sdk-typescript.git","type":"git"},"_npmVersion":"10.9.7","description":"Official TypeScript SDK for the Cognethics platform","directories":{},"_nodeVersion":"22.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","vitest":"^1.4.0","typescript":"^5.4.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.1_1779738212778_0.24719278793887822","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@cognethics/sdk","version":"0.3.0","keywords":["cognethics","sdk","agents","platform","ai"],"author":{"name":"Cognethics","email":"noreply@cognethics.com"},"license":"SEE LICENSE IN LICENSE","_id":"@cognethics/sdk@0.3.0","maintainers":[{"name":"cognethics.com","email":"dev@cognethics.com"}],"homepage":"https://cognethics.com","bugs":{"url":"https://developers.cognethics.com"},"dist":{"shasum":"b556fb58109c26dc80ca3e18abb1cdca0ef5ef4a","tarball":"https://registry.npmjs.org/@cognethics/sdk/-/sdk-0.3.0.tgz","fileCount":154,"integrity":"sha512-HUALCYj4YOEeqWjFtpQPrL47azMdsGOY7a7AzCLraNL5dRYdlkUhOpJHR7xeCqt8zbkZw8goqL81IduYRzAV9Q==","signatures":[{"sig":"MEUCICg0KBFvZnY0xGi84/idD0OTQ7/vy19GupaCPdD8mdXeAiEAkC5FXzfk1QNa+UrK+wrK9sRzo+LRPnhsn0W+0O8b2T0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5845079},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"6dc67eee7f76cb6d4afa7c69fac0d9c3055ff414","private":false,"scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsup && npm run build:types && npm run build:cts-types","regen":"cd ../../backend && . venv/bin/activate && python manage.py prism_codegen --target=typescript --out=../clients/typescript/src/generated","typecheck":"tsc --noEmit","test:watch":"vitest","build:types":"tsc -p tsconfig.build.json","pack:dryrun":"npm pack --dry-run","prepublishOnly":"npm run build && npm test","publish-dryrun":"npm run typecheck && npm test && npm run build && npm pack --dry-run","build:cts-types":"cp dist/index.d.ts dist/index.d.cts"},"_npmUser":{"name":"cognethics.com","email":"dev@cognethics.com"},"repository":{"url":"git+https://github.com/cognethics/sdk-typescript.git","type":"git"},"_npmVersion":"10.9.7","description":"Official TypeScript SDK for the Cognethics platform","directories":{},"_nodeVersion":"22.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","vitest":"^1.4.0","typescript":"^5.4.0","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1780045632328_0.05333042205672989","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@cognethics/sdk","version":"0.4.0","description":"Official TypeScript SDK for the Cognethics platform","license":"SEE LICENSE IN LICENSE","author":{"name":"Cognethics","email":"noreply@cognethics.com"},"homepage":"https://cognethics.com","repository":{"type":"git","url":"git+https://github.com/cognethics/sdk-typescript.git"},"bugs":{"url":"https://developers.cognethics.com"},"keywords":["cognethics","sdk","agents","platform","ai"],"type":"module","private":false,"engines":{"node":">=18"},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"publishConfig":{"access":"public"},"scripts":{"regen":"cd ../../backend && . venv/bin/activate && python manage.py prism_codegen --target=typescript --out=../clients/typescript/src/generated","build":"tsup && npm run build:types && npm run build:cts-types","build:types":"tsc -p tsconfig.build.json","build:cts-types":"cp dist/index.d.ts dist/index.d.cts","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","typecheck:tests":"tsc -p tsconfig.test.json","lint":"tsc --noEmit && tsc -p tsconfig.test.json","pack:dryrun":"npm pack --dry-run","publish-dryrun":"npm run typecheck && npm test && npm run build && npm pack --dry-run","prepublishOnly":"npm run build && npm test"},"devDependencies":{"@types/node":"^20.11.0","tsup":"^8.0.2","typescript":"^5.4.0","vitest":"^1.4.0"},"_id":"@cognethics/sdk@0.4.0","gitHead":"8d2952a4b8b15f3145937991bd122f87da459cfb","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-ywOwKTzAq+65WpXN96MiRtRTbUhjtjpQGlkc96a+toXY4VPJ3hefe9cuTytDJA2zWOB0cVXHne6CjB14BKfitA==","shasum":"d8e9635705cd59902ac71192bc52efb7e90ef896","tarball":"https://registry.npmjs.org/@cognethics/sdk/-/sdk-0.4.0.tgz","fileCount":154,"unpackedSize":5684376,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDO+wAvPMEfydimg7AudzFqmPgUEdOWytuyoTSNU46MzAIhAJxlFNw7OT96oAvy+GTcDcNgjPae/8ewrkzJGTKGzLiu"}]},"_npmUser":{"name":"cognethics.com","email":"dev@cognethics.com"},"directories":{},"maintainers":[{"name":"cognethics.com","email":"dev@cognethics.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.4.0_1780447680340_0.10156871817633162"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T00:57:58.680Z","modified":"2026-06-03T00:48:00.691Z","0.2.0":"2026-05-25T00:57:59.059Z","0.2.1":"2026-05-25T19:43:32.987Z","0.3.0":"2026-05-29T09:07:12.499Z","0.4.0":"2026-06-03T00:48:00.553Z"},"bugs":{"url":"https://developers.cognethics.com"},"author":{"name":"Cognethics","email":"noreply@cognethics.com"},"license":"SEE LICENSE IN LICENSE","homepage":"https://cognethics.com","keywords":["cognethics","sdk","agents","platform","ai"],"repository":{"type":"git","url":"git+https://github.com/cognethics/sdk-typescript.git"},"description":"Official TypeScript SDK for the Cognethics platform","maintainers":[{"name":"cognethics.com","email":"dev@cognethics.com"}],"readme":"# @cognethics/sdk\n\n**Official TypeScript SDK for the [Cognethics](https://cognethics.com) platform.**\n\nA fully typed surface over **6,659 generated handlers across 9 mega-tools** — finance, CRM, spare parts, documents, HR, GRC, healthcare, and more — through one client. Dual **ESM + CommonJS**, **zero runtime dependencies**, TypeScript **strict** mode. The same handler tree shipped by the official [Python SDK](https://pypi.org/project/cognethics/), generated from the platform's live introspection schema.\n\nEvery call hits a real multi-tenant business database. Each handler is RBAC-scoped, bounded by per-agent budgets, and written to a tamper-evident audit chain.\n\n## Install\n\n```bash\nnpm i @cognethics/sdk\n# or\npnpm add @cognethics/sdk\n# or\nyarn add @cognethics/sdk\n```\n\nRequires **Node.js >= 18** (uses the runtime's built-in `fetch`). Runs in Node, browsers, Cloudflare Workers, Deno, Bun, and any modern JS runtime that ships `fetch`.\n\n## Quickstart\n\n```ts\nimport { Client } from \"@cognethics/sdk\";\n\nconst client = new Client({\n  apiKey: process.env.COGNETHICS_API_KEY!, // ck_...\n  baseUrl: \"https://gtm.cognethics.com\",   // your tenant subdomain\n});\n\n// 1. Liveness probe — confirms the SDK can reach the platform.\nconst status = await client.dev.ping();\n// → { service: \"cognethics-dev-api\", version: \"v1\", status: \"ok\" }\n\n// 2. List the first page of customer invoices via the generated tree.\nconst invoices = await client.entityCrud.finance.invoice.list({ page_size: 10 });\nconsole.log(invoices.data);\n```\n\n## Typed handler tree\n\nThe generated tree exposes all 6,659 handlers as nine camelCase namespaces, one per mega-tool:\n\n`entityCrud` · `workflowAction` · `reportQuery` · `smartAction` · `agentCommand` · `integrationCall` · `documentOp` · `configManage` · `notificationSend`\n\nEach namespace drills down through `app → entity → operation`, fully typed end-to-end:\n\n```ts\n// CRUD on a maintenance work order\nconst orders = await client.entityCrud.spareParts.workOrder.list({ page_size: 10 });\nconst order  = await client.entityCrud.spareParts.workOrder.read({ id: \"<uuid>\" });\n\nawait client.entityCrud.finance.invoice.update({\n  id: \"<invoice-uuid>\",\n  data: { status: \"paid\" },\n});\n```\n\nThe tree is generated from the platform's introspection schema, so new entities and operations appear automatically when the SDK is regenerated.\n\n## Generic dispatch — `callTool`\n\nAny handler — including custom tools — is reachable by name through `callTool`. It inspects the Prism response envelope and throws the correct typed error on `{ success: false }`:\n\n```ts\nconst result = await client.callTool(\"prism_entity_crud\", {\n  app: \"spare_parts\",\n  entity: \"work_order\",\n  operation: \"list\",\n  page_size: 10,\n});\n```\n\n## Pagination\n\n`paginate` is an async generator that walks every page until `pagination.has_next` is false — no cursor bookkeeping:\n\n```ts\nfor await (const row of client.paginate(\n  (p) => client.entityCrud.finance.invoice.list(p),\n  { pageSize: 50, params: { status: \"overdue\" } },\n)) {\n  console.log(row);\n}\n```\n\n## Authentication\n\nAll authenticated calls send `Authorization: Bearer <api-key>`. Mint a key from the developer dashboard at `https://<your-tenant>.cognethics.com/users/me/api-keys/`.\n\n| Prefix    | Surfaces                                 | Notes                                    |\n| --------- | ---------------------------------------- | ---------------------------------------- |\n| `ck_...`  | `/api/v1/dev/*` **and** all MCP handlers | Recommended — single key for everything. |\n| `mcp_...` | MCP handlers only                        | Existing keys keep working.              |\n\n```ts\nconst client = new Client({\n  apiKey: \"ck_...\",\n  baseUrl: \"https://gtm.cognethics.com\",\n  org: \"<org-uuid>\", // optional — sets X-Organization-Context\n});\n```\n\nSet `org` per client, or pass an org override per `callTool` to switch organization on a single call. The platform is multi-tenant and multi-org; data never crosses an organization boundary.\n\n## Errors\n\nEvery HTTP failure raises a subclass of `CognethicsError`:\n\n| Status | Class                   |\n| ------ | ----------------------- |\n| 401    | `AuthenticationError`   |\n| 403    | `PermissionDeniedError` |\n| 404    | `NotFoundError`         |\n| 422    | `ValidationError`       |\n| 429    | `RateLimitError`        |\n| 4xx    | `DevApiError`           |\n| 5xx    | `ServerError`           |\n\n```ts\nimport { PermissionDeniedError } from \"@cognethics/sdk\";\n\ntry {\n  await client.entityCrud.finance.invoice.update({\n    id: \"<invoice-uuid>\",\n    data: { status: \"paid\" },\n  });\n} catch (err) {\n  if (err instanceof PermissionDeniedError) {\n    console.error(\"This key cannot update invoices in this org.\");\n  } else {\n    throw err;\n  }\n}\n```\n\nThe SDK transparently handles both envelopes the platform uses — DRF (`{ detail }`) for auth and simple 4xx, and the Prism envelope (`{ success, error }`) returned with HTTP 200 for handler-level business failures.\n\n## Retries & timeout\n\nRequests retry automatically on `429`, `502`, `503`, `504` with exponential backoff (3 retries, 500 ms base, doubling). `Retry-After` is honored on `429` and parsed as **seconds** (per RFC 7231).\n\n| Option      | Default | Constructor field |\n| ----------- | ------- | ----------------- |\n| Timeout     | 30 s    | `timeoutMs`       |\n| Max retries | 3       | `maxRetries`      |\n\n```ts\nnew Client({ apiKey: \"ck_...\", maxRetries: 5, timeoutMs: 60_000 });\n```\n\nWhen retries are exhausted on a `429`, a `RateLimitError` carries the parsed `retryAfter` value (in seconds).\n\n## Promise-based, async-native\n\nEvery method returns a `Promise<T>` and works directly with `await`, `Promise.all`, and `for await`. The SDK uses the runtime's built-in `fetch` and ships as dual **ESM + CommonJS** with bundled `.d.ts` types — `import` and `require` both resolve, in strict TypeScript or plain JavaScript, with no transpile step.\n\n## Developer Sandbox — `client.dev`\n\nThe `dev` namespace targets `/api/v1/dev/*` and is the fastest way to verify a key end-to-end:\n\n| Method            | Endpoint                | Auth | Returns        |\n| ----------------- | ----------------------- | ---- | -------------- |\n| `dev.ping()`      | `GET /api/v1/dev/ping/` | No   | `PingResponse` |\n| `dev.me()`        | `GET /api/v1/dev/me/`   | Yes  | `MeResponse`   |\n| `dev.echo(query)` | `GET /api/v1/dev/echo/` | Yes  | `EchoResponse` |\n\n## Documentation\n\n- **For agents**: <https://developers.cognethics.com/for-agents/>\n- **Full reference**: <https://developers.cognethics.com/reference/>\n- **TypeScript SDK guide**: <https://developers.cognethics.com/sdk/typescript/>\n- **Python SDK**: [`cognethics`](https://pypi.org/project/cognethics/) on PyPI\n\n## Development\n\n```bash\nnpm install\nnpm run build      # tsup → dist/ (ESM + CJS + .d.ts)\nnpm test           # vitest\nnpm run typecheck  # tsc --noEmit\n```\n\n## License\n\nProprietary. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}