TypeScript SDK

@cognethics/sdk v0.4.0 — a typed TypeScript client over the full Cognethics tool surface. Generic dispatch plus a generated, fully-typed method tree, built on the runtime’s native fetch, Node.js 18+. Async-native — every method returns a Promise — with zero runtime dependencies and dual ESM + CJS builds.

Install

npm i @cognethics/sdk
# or
pnpm add @cognethics/sdk
# or
yarn add @cognethics/sdk

Quickstart

import { Client, PermissionDeniedError, NotFoundError } from "@cognethics/sdk";

const client = new Client({
  apiKey: process.env.COGNETHICS_API_KEY!,    // ck_… key you mint from the dashboard once your workspace is provisioned
  // mcp_… keys (operator-issued via the developer dashboard) authenticate identically — substitute either prefix.
  baseUrl: "https://acme.cognethics.com",     // your tenant subdomain
  timeoutMs: 30_000,
  maxRetries: 3,
});

// 1. Generic dispatch — any governed tool
await client.callTool("prism_introspect", { dimension: "stats" });

// 2. Generated tree (typed, IDE-autocompletable)
await client.entityCrud.spareParts.workOrder.list({ page: 1, page_size: 50 });
await client.entityCrud.finance.invoice.read({ id: "<uuid>" });
await client.reportQuery.finance.agingApSummary({ date_range: { from: "...", to: "..." } });

// 3. Developer sandbox — verify your key end to end
const me = await client.dev.me();   // { authenticated: true, key, user, tenant }

// 4. Pagination — async iterator over every page
for await (const row of client.paginate(
  (p) => client.entityCrud.spareParts.workOrder.list(p),
  { pageSize: 100 },
)) {
  process(row);
}

// 5. Errors
try {
  // data is typed as InvoiceUpdateData — the compiler flags wrong or missing keys
  await client.entityCrud.finance.invoice.update({ id: "...", data: { status: "paid" } });
} catch (err) {
  if (err instanceof PermissionDeniedError) {
    console.error(err.code, err.message, err.hint, err.requestId);
  }
}

Layered access, one client

Layer	What it gives you	When to use
`client.callTool(tool, body)`	Generic dispatch to any tool	One-off calls, scripts, when you don’t want IDE autocomplete
`client.<megaTool>.<app>.<entity>.<op>()`	Codegen-typed methods with parameter hints	Production code where you want the compiler to catch bad calls
`client.dev.ping()`, `client.dev.me()`, …	Developer sandbox probes for key and connectivity	Verifying a key works end to end before you wire up the rest

Get an API key

The SDK uses bearer-token auth (Authorization: Bearer ck_…). Workspaces are provisioned and configured for your team — tell us what you're building at developers.cognethics.com/signup/ and we set yours up. Once it's live, you mint and rotate scoped ck_ keys yourself from the dashboard, each bound to one organization.

// Once your workspace is provisioned, mint a scoped key from your tenant
// dashboard, then drive the SDK with it:
import { Client } from "@cognethics/sdk";

const client = new Client({
  apiKey: "ck_…",                                  // minted from https://platform.cognethics.com/dashboard/
  baseUrl: "https://<your-tenant>.cognethics.com", // your tenant subdomain
});

// Verify the key end to end:
console.log(await client.callTool("prism_whoami", {})); // confirms identity, tenant, and scope

Operators can also mint mcp_ keys (org-scoped) via the developer dashboard or POST /api/mcp/api-keys/register/ (rate-limited 5/min). Both prefixes authenticate identically — pass the plaintext as apiKey when constructing the Client.

Capabilities

Typed methods for every Prism handler covering CRUD, search, action, report, and workflow operations — the same 7,331-handler surface as the Python SDK
12 mega-tool namespaces wrapped: entityCrud, workflowAction, reportQuery, smartAction, agentCommand, integrationCall, documentOp, configManage, notificationSend
Async-native: every method returns a Promise<T>, built on the runtime’s native fetch — no transport library to install
Pagination iterator via client.paginate(method, { pageSize }) — an async generator that walks every page lazily
Typed exceptions: CognethicsError, AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError, ServerError, plus two more
Retries with exponential backoff on 429/502/503/504 — Retry-After honored — configurable via maxRetries
Zero runtime dependencies, dual ESM + CJS, strict TypeScript — runs on Node.js 18+, browsers, Cloudflare Workers, and any modern JS runtime

Available on npm: npmjs.com/package/@cognethics/sdk. See the handler reference for every method’s parameters and permissions.