kognitos

TypeScript SDK for the Kognitos API.

• Zero runtime dependencies (uses native fetch)
• Dual CJS/ESM output with full TypeScript declarations
• Automatic snake_case/camelCase conversion
• Built-in retry with exponential backoff
• Request timeouts via AbortController
• Async iteration for paginated endpoints
• NDJSON streaming with auto-reconnect

Installation

npm install @kognitos/node

Quick start

import Kognitos from '@kognitos/node';

const client = new Kognitos({
  token: 'pat_...',
  region: 'us', // 'us' | 'eu' | 'uk'
});

// List organizations
const { data: orgs } = await client.organizations.list();

// Get a workspace
const workspace = await client.workspaces.get({
  organizationId: 'org-123',
  workspaceId: 'ws-456',
});

// List automations with pagination
const { data: automations, nextPageToken } = await client.automations.list({
  organizationId: 'org-123',
  workspaceId: 'ws-456',
  pageSize: 10,
});

Pagination

All list endpoints return { data, nextPageToken, totalSize }. Use the built-in async iterator to auto-paginate:

import { autoPaginate } from '@kognitos/node';

const page = await client.automations.list({
  organizationId: 'org-123',
  workspaceId: 'ws-456',
});

for await (const automation of autoPaginate(page, (token) =>
  client.automations.list({
    organizationId: 'org-123',
    workspaceId: 'ws-456',
    pageToken: token,
  }),
)) {
  console.log(automation.displayName);
}

Or collect everything at once:

import { collectAll } from '@kognitos/node';

const all = await collectAll(page, (token) =>
  client.automations.list({
    organizationId: 'org-123',
    workspaceId: 'ws-456',
    pageToken: token,
  }),
);

Streaming

Stream real-time agent events over NDJSON:

for await (const event of client.agents.streamEvents({
  organizationId: 'org-123',
  workspaceId: 'ws-456',
  automationId: 'auto-789',
  runId: 'run-001',
  agentId: 'agent-abc',
})) {
  console.log(event);
}

Cancel a stream with an AbortController:

const controller = new AbortController();

for await (const event of client.agents.streamEvents({
  ...scope,
  signal: controller.signal,
})) {
  if (shouldStop(event)) {
    controller.abort();
  }
}

Error handling

All errors extend KognitosError. HTTP errors include status code and API error details:

import {
  ApiError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ConnectionError,
  TimeoutError,
} from '@kognitos/node';

try {
  await client.automations.get({ ... });
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Not found:', err.message);
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, retry after:', err.retryAfter, 'seconds');
  } else if (err instanceof AuthenticationError) {
    console.log('Bad token');
  } else if (err instanceof TimeoutError) {
    console.log('Request timed out');
  } else if (err instanceof ApiError) {
    console.log('API error:', err.status, err.code, err.details);
  }
}

Configuration

const client = new Kognitos({
  token: 'pat_...',          // Required — personal access token
  region: 'us',              // Required — 'us' | 'eu' | 'uk'
  env: 'prod',               // Optional — 'prod' (default) | 'dev'
  timeout: 30000,            // Optional — request timeout in ms (default: 30000)
  retry: {                   // Optional — retry config, or false to disable
    maxRetries: 2,           //   default: 2
    initialDelayMs: 500,     //   default: 500
    maxDelayMs: 5000,        //   default: 5000
  },
});

Per-request overrides:

await client.automations.get(
  { organizationId: 'org-123', workspaceId: 'ws-456', automationId: 'auto-789' },
  { timeout: 5000, retry: false },
);

Resources

| Resource | Methods | |---|---| | client.organizations | list, get, getPreferences, listUsers, getUser, listWorkspaces, listInvitations, countWorkspaceUsers | | client.workspaces | list, get, getPreferences, listUsers, listRoles, listInvitations | | client.automations | list, get, invoke, query, getRevision, listRevisions, getVisualization, addConnections, removeConnections, switchConnections, getConnectionUsage, traceConnectionUsage, deleteConnection, createSchedule, updateSchedule, deleteSchedule, listTriggers, createTrigger, listDefaultInputsHistory | | client.runs | list, get, getEvents, cancel, pause, getAggregates, getDailyAggregates | | client.agents | listEvents, getEvent, sendEvent, cancelGeneration, streamEvents | | client.books | list, listLatest, get, getVersions, getConcepts, getProcedures, search, listWorkspaceBooks, listWorkspaceBookConnections, createWorkspaceBookConnection, updateWorkspaceBookConnection, upgradeWorkspaceBookConnection, createWorkspaceBookConnectionTrigger, getWorkspaceBookConcepts, getWorkspaceBookProcedures, searchWorkspaceBooks, searchWorkspaceConcepts, searchWorkspaceProcedures | | client.connections | list, get, authorize, discover, listDiscoverables, listProcedures, searchProcedures, deleteTriggerInstance, getUserInfo | | client.files | upload, download, delete, getMetadata, generateUploadUrl, generateDownloadUrl | | client.exceptions | list, get, listGroups, countByAutomation, countByGroup, listGuideEntries, getGuideEntry, getExecutionOutputs | | client.triggers | list, addAutomations | | client.analytics | queryInsights, queryAutomationEstimates, queryMetrics, configureAutomationEstimates |

Development

npm install
npm run generate   # Regenerate types from OpenAPI spec
npm run build      # Build CJS + ESM + types
npm run check      # TypeScript type checking
npm run lint       # ESLint + Prettier
npm test           # Run tests

License

MIT