Kairos SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for Kairos project management API. Build applications that integrate seamlessly with Kairos task and goal management.

Features

• Full TypeScript support with complete type definitions
• Zero external dependencies (uses native fetch)
• Automatic retry on rate limits
• Comprehensive error handling with typed errors
• Support for Node.js 18+, Bun, Deno, and browsers
• Full API coverage for tasks, goals, team, and documents

Installation

npm

npm install @kairos-connect/sdk

Bun

bun add @kairos-connect/sdk

pnpm

pnpm add @kairos-connect/sdk

yarn

yarn add @kairos-connect/sdk

Quick Start

Setting up the client

import { Kairos } from '@kairos-connect/sdk';

// Initialize with API key from environment or config
const kairos = new Kairos({
  apiKey: 'kairos_sk_your_api_key_here',
});

// Or use KAIROS_API_KEY environment variable
const kairos = new Kairos();

Creating your first task

import { Kairos } from '@kairos-connect/sdk';

const kairos = new Kairos();

// Create a new task
const task = await kairos.tasks.create({
  title: 'Build user authentication',
  description: 'Implement JWT-based auth for the API',
  priority: 'high',
  estimated_hours: 8,
  due_date: '2026-04-15',
});

console.log(`Created task: ${task.id}`);

Managing goals

const kairos = new Kairos();

// Create a goal
const goal = await kairos.goals.create({
  title: 'Q2 Product Launch',
  description: 'Launch new features for Q2',
  due_date: '2026-06-30',
});

// Get goal details
const goalDetails = await kairos.goals.get(goal.id);
console.log(`Goal progress: ${goalDetails.progress}%`);

// List all active goals
const goals = await kairos.goals.list({ status: 'active' });
console.log(`Active goals: ${goals.data.length}`);

Working with tasks and comments

const kairos = new Kairos();

// List tasks with filters
const tasks = await kairos.tasks.list({
  status: 'in_progress',
  priority: 'high',
  limit: 20,
});

// Get a specific task
const task = await kairos.tasks.get('task_123');

// Update a task
const updated = await kairos.tasks.update('task_123', {
  status: 'in_review',
  actual_hours: 5,
});

// Add a comment
const comment = await kairos.tasks.addComment('task_123', {
  content: 'Implementation complete, ready for review',
});

// List task comments
const comments = await kairos.tasks.listComments('task_123');

Team information

const kairos = new Kairos();

// Get team details
const team = await kairos.team.get();
console.log(`Team: ${team.name}`);

// List team members
const members = await kairos.team.listMembers({ limit: 50 });
console.log(`Team size: ${members.pagination.total}`);

Managing documents

const kairos = new Kairos();

// List documents
const docs = await kairos.documents.list();

// Get a specific document
const doc = await kairos.documents.get('doc_123');
console.log(`Document: ${doc.title}`);

Validating your API key

const kairos = new Kairos();

// Verify API key and get user/team info
const me = await kairos.me();
console.log(`Team ID: ${me.team_id}`);
console.log(`Scopes: ${me.scopes.join(', ')}`);
console.log(`Rate limit: ${me.rate_limit_per_minute}/minute`);

API Reference

Tasks

List tasks

const response = await kairos.tasks.list({
  status: 'in_progress',
  priority: 'high',
  assigned_to: 'user_123',
  goal_id: 'goal_123',
  search: 'authentication',
  limit: 20,
  offset: 0,
});

console.log(response.data); // Task[]
console.log(response.pagination); // { page, limit, total, has_more }

Get task by ID

const task = await kairos.tasks.get('task_123');

Create task

const task = await kairos.tasks.create({
  title: 'New feature',
  description: 'Description of the feature',
  type: 'task', // 'task' | 'sub_task' | 'bug' | 'story' | 'epic'
  status: 'to_do', // 'to_do' | 'in_progress' | 'in_review' | 'completed' | 'cancelled'
  priority: 'high', // 'low' | 'medium' | 'high' | 'urgent'
  goal_id: 'goal_123', // Optional
  parent_task_id: 'task_parent', // Optional, for sub-tasks
  assigned_to: 'user_123', // Optional
  estimated_hours: 8, // Optional
  due_date: '2026-04-15', // Optional, ISO 8601
});

Update task

const updated = await kairos.tasks.update('task_123', {
  status: 'in_progress',
  actual_hours: 3,
  priority: 'urgent',
});

Delete task

await kairos.tasks.delete('task_123');

List task comments

const comments = await kairos.tasks.listComments('task_123', {
  limit: 10,
  offset: 0,
});

Add comment

const comment = await kairos.tasks.addComment('task_123', {
  content: 'Task complete!',
});

Goals

List goals

const response = await kairos.goals.list({
  status: 'active', // 'active' | 'completed' | 'archived'
  limit: 20,
  offset: 0,
});

Get goal by ID

const goal = await kairos.goals.get('goal_123');

Create goal

const goal = await kairos.goals.create({
  title: 'Q2 Launch',
  description: 'Launch new features',
  due_date: '2026-06-30', // Optional
});

Update goal

const updated = await kairos.goals.update('goal_123', {
  status: 'completed',
  description: 'Updated description',
});

List tasks in goal

const tasks = await kairos.goals.listTasks('goal_123', {
  status: 'completed',
  limit: 20,
});

Team

Get team info

const team = await kairos.team.get();
// { id, name, slug, description, avatar_url, created_at }

List team members

const members = await kairos.team.listMembers({
  limit: 50,
  offset: 0,
});
// { data: TeamMember[], pagination: Pagination }

Documents

List documents

const docs = await kairos.documents.list({
  limit: 20,
  offset: 0,
});

Get document

const doc = await kairos.documents.get('doc_123');

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  Kairos,
  AuthError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  InternalError,
} from '@kairos-connect/sdk';

const kairos = new Kairos();

try {
  const task = await kairos.tasks.create({
    title: 'New task',
  });
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.message);
  } else if (error instanceof ForbiddenError) {
    console.error('Access denied:', error.message);
  } else if (error instanceof InternalError) {
    console.error('Server error:', error.message);
  } else {
    console.error('Unknown error:', error);
  }
}

Error properties

All errors have the following properties:

error.code; // 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | etc.
error.message; // Human-readable error message
error.statusCode; // HTTP status code
error.requestId; // Unique request ID for debugging

// RateLimitError has additional property:
error.retryAfter; // Seconds to wait before retrying

Rate Limiting

The SDK automatically handles rate limit responses (429) by retrying with exponential backoff. You can configure the maximum number of retries:

const kairos = new Kairos({
  apiKey: 'kairos_sk_...',
  maxRetries: 3, // Default is 3
  timeout: 30000, // Default is 30 seconds
});

To check current rate limit status after a request:

const task = await kairos.tasks.get('task_123');

// Access rate limit info through the HTTP client
// (This is internal, but available if needed)
const rateLimit = await kairos.me(); // Includes rate_limit_per_minute and rate_limit_per_hour

Environment Variables

Set your API key via the KAIROS_API_KEY environment variable:

export KAIROS_API_KEY=kairos_sk_your_api_key_here

Then initialize without passing the API key:

import { Kairos } from '@kairos-connect/sdk';

const kairos = new Kairos(); // Reads from KAIROS_API_KEY

Configuration

interface KairosConfig {
  apiKey?: string; // Defaults to KAIROS_API_KEY env var
  baseUrl?: string; // Defaults to https://gateway.thekairos.app/v1
  timeout?: number; // Request timeout in ms, defaults to 30000
  maxRetries?: number; // Max retries for rate limits, defaults to 3
}

Advanced Usage

Custom base URL (for on-premise deployments)

const kairos = new Kairos({
  apiKey: 'kairos_sk_...',
  baseUrl: 'https://kairos.company.com/api/v1',
});

Longer timeout for slow networks

const kairos = new Kairos({
  apiKey: 'kairos_sk_...',
  timeout: 60000, // 60 seconds
});

Disable automatic retries

const kairos = new Kairos({
  apiKey: 'kairos_sk_...',
  maxRetries: 0,
});

Type Definitions

All types are exported for TypeScript development:

import {
  Task,
  Goal,
  Comment,
  Team,
  TeamMember,
  Document,
  CreateTaskInput,
  UpdateTaskInput,
  CreateGoalInput,
  UpdateGoalInput,
  ListTasksOptions,
  ListGoalsOptions,
  PaginatedResponse,
  SingleResponse,
  MeResponse,
} from '@kairos-connect/sdk';

Browser Usage

The SDK works in modern browsers with support for fetch:

<script type="module">
  import { Kairos } from 'https://cdn.example.com/@kairos-connect/sdk/dist/index.js';

  const kairos = new Kairos({
    apiKey: 'kairos_sk_...',
  });

  const tasks = await kairos.tasks.list();
  console.log(tasks);
</script>

License

MIT