JavaScript / TypeScript SDK

# npm
npm install @kairos-connect/sdk

# yarn
yarn add @kairos-connect/sdk

# pnpm
pnpm add @kairos-connect/sdk

# bun
bun add @kairos-connect/sdk

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

// Initialize the client
const kairos = new Kairos({
  apiKey: process.env.KAIROS_API_KEY,
});

// List tasks
const { data: tasks, pagination } = await kairos.tasks.list({
  status: 'in_progress',
  limit: 10,
});

console.log(`Found ${pagination.total} tasks`);
tasks.forEach(task => {
  console.log(`- ${task.title} (${task.status})`);
});

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

const kairos = new Kairos({
  // Required: Your API key (use environment variable)
  apiKey: process.env.KAIROS_API_KEY,

  // Optional: Custom base URL (for enterprise/self-hosted)
  baseUrl: 'https://gateway.thekairos.app/v1',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 60000,

  // Optional: Custom fetch implementation
  fetch: customFetch,

  // Optional: Retry configuration
  retry: {
    maxRetries: 3,
    retryDelay: 1000, // Base delay in ms
  },
});

// List all tasks with filters
const { data: tasks } = await kairos.tasks.list({
  status: 'in_progress',
  priority: 'high',
  assigned_to: 'user-id',
  goal_id: 'goal-id',
  page: 1,
  limit: 50,
  sort_by: 'due_date',
  sort_order: 'asc',
});

const task = await kairos.tasks.get('task-id');
console.log(task.title, task.status);

const newTask = await kairos.tasks.create({
  title: 'Implement new feature',
  description: 'Add user authentication',
  goal_id: 'goal-id',
  priority: 'high',
  due_date: '2024-01-15',
  assigned_to: 'user-id',
  story_points: 5,
});

const updatedTask = await kairos.tasks.update('task-id', {
  status: 'completed',
  actual_hours: 6,
});

await kairos.tasks.delete('task-id');

// List goals
const { data: goals } = await kairos.goals.list({
  status: 'in_progress',
  include_tasks: true,
});

// Get a single goal with its tasks
const goal = await kairos.goals.get('goal-id', {
  include_tasks: true,
  include_comments: true,
});

console.log(`Goal: ${goal.title}`);
console.log(`Progress: ${goal.progress}%`);
goal.tasks?.forEach(task => {
  console.log(`  - ${task.title}`);
});

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

// List team members (teamId required)
const { data: members } = await kairos.team.listMembers(team.id);

members.forEach(member => {
  console.log(`${member.name} (${member.role})`);
});

// List documents
const { data: docs } = await kairos.documents.list({
  doc_type: 'page',
  visibility: 'team',
});

// Get document with content
const doc = await kairos.documents.get('doc-id', {
  include_content: true,
  include_children: true,
});

console.log(doc.title);
console.log(doc.plain_text); // Plain text content
console.log(doc.content);    // Rich text JSON

import {
  Kairos,
  KairosError,
  KairosAuthError,
  KairosNotFoundError,
  KairosValidationError,
  KairosRateLimitError,
} from '@kairos-connect/sdk';

try {
  const task = await kairos.tasks.get('invalid-id');
} catch (error) {
  if (error instanceof KairosNotFoundError) {
    console.log('Task not found');
  } else if (error instanceof KairosValidationError) {
    console.log('Validation error:', error.message);
  } else if (error instanceof KairosRateLimitError) {
    console.log('Rate limited. Retry after:', error.retryAfter, 'seconds');
    // Wait and retry
    await new Promise(r => setTimeout(r, error.retryAfter * 1000));
  } else if (error instanceof KairosAuthError) {
    console.log('Authentication failed');
  } else if (error instanceof KairosError) {
    console.log('API error:', error.code, error.message);
  }
}

import type {
  Task,
  Goal,
  Comment,
  Team,
  TeamMember,
  Document,
  TaskStatus,
  TaskPriority,
  GoalStatus,
  PaginatedResponse,
} from '@kairos-connect/sdk';

// All methods are fully typed
const task: Task = await kairos.tasks.get('id');
const result: PaginatedResponse<Task> = await kairos.tasks.list();

// Next.js API Route (pages/api/kairos/[...path].ts)
import { Kairos } from '@kairos-connect/sdk';

const kairos = new Kairos({
  apiKey: process.env.KAIROS_API_KEY,
});

export default async function handler(req, res) {
  // Proxy requests to Kairos API
  // Add your own authentication logic here
}