@yoctotta/kaman-connector

Official TypeScript/JavaScript SDK for Kaman 3.0 Platform.

Features

• Full API coverage for Kaman services
• Browser and Node.js compatible
• TypeScript-first with comprehensive type definitions
• Modular client architecture for tree-shaking
• Streaming support for real-time chat/agent calling
• UI tools support for interactive agent responses

Installation

npm install @yoctotta/kaman-connector
# or
yarn add @yoctotta/kaman-connector

Quick Start

import { KamanConnector } from '@yoctotta/kaman-connector';

const kaman = new KamanConnector({
  baseUrl: 'https://api.kaman.example.com',
  token: 'your-jwt-token'
});

// List workflows
const { data: workflows } = await kaman.workflows.list();

// Execute a workflow
const result = await kaman.workflows.execute('wf-id', {
  input: { key: 'value' }
});

// Query data lake
const queryResult = await kaman.kdl.query({
  lakeName: 'main',
  schemaName: 'public',
  tableName: 'users',
  limit: 100
});

API Clients Overview

| Client | Access Level | Operations | |--------|-------------|------------| | chat | Full | Sessions, streaming, artifacts, UI tools | | workflows | Read + Execute | List, get, execute, run history | | functions | Read + Execute | List, get, execute, search | | kdl | Read + Query | List lakes/schemas/tables, query, versions | | dataSources | Read-Only | List, get, schema preview | | plugins | Read-Only | List plugins, MCP servers, connectors | | knowledgeBases | Read + Search | List, get, semantic search (RAG) | | files | Read-Only | List, get, download | | billing | Read-Only | List plans, usage, transactions | | evaluations | Read-Only | List suites, runs, results | | templates | Read-Only | List, get, check requirements | | users | Full CRUD | Create, read, update, delete, roles | | roles | Full CRUD | Create, read, update, delete, permissions |

Chat & Agent Calling

The chat client provides full support for agent interactions including streaming, UI tools, interrupts, and artifacts.

// Basic chat streaming
for await (const msg of kaman.chat.sendMessage({
  sessionId: 'session-123',
  expertId: '1_0',  // Format: appId_expertIndex
  input: { type: 'text', text: 'Hello!' }
})) {
  if (msg.content) console.log('Text:', msg.content);
  if (msg.suggestions) console.log('Suggestions:', msg.suggestions);
  if (msg.artifacts) console.log('Artifacts:', msg.artifacts);
}

With UI Tools

UI tools allow the agent to request client-side actions:

for await (const msg of kaman.chat.sendMessage({
  sessionId: 'session-123',
  expertId: '1_0',
  input: { type: 'text', text: 'Show me a chart' },
  uiTools: [{ name: 'chartRenderer' }]
})) {
  if (msg.tool) {
    // Agent requested a UI tool - handle it on client
    const result = await myChartRenderer(msg.tool.args);
    // Send result back to agent
    await kaman.chat.respondToTool('session-123', msg.tool.id, result);
  }
}

With File Input

for await (const msg of kaman.chat.sendMessage({
  sessionId: 'session-123',
  expertId: '1_0',
  input: {
    type: 'file',
    text: 'Analyze this document',
    files: [{
      url: 'https://example.com/doc.pdf',
      mimeType: 'application/pdf',
      fileName: 'report.pdf'
    }]
  }
})) {
  console.log(msg.content);
}

Message Types

The streaming response yields ConnectorMessage objects with these properties:

| Property | Type | Description | |----------|------|-------------| | content | string | Text content from the agent | | suggestions | string[] | Suggested next actions | | artifacts | Artifact[] | Generated files/outputs | | tool | ToolCall | UI tool request | | interrupt | InterruptData | Interrupt for human input | | thought | string | Agent reasoning/thinking | | sessionName | string | Auto-generated session name | | error | string | Error message |

Workflow Execution

// List workflows
const { data: workflows } = await kaman.workflows.list({ limit: 10 });

// Get workflow details
const workflow = await kaman.workflows.get('wf-123');

// Execute workflow
const result = await kaman.workflows.execute('wf-123', {
  input: { data: 'value' },
  config: { timeout: 30000 }
});

// Get execution history
const { data: runs } = await kaman.workflows.getRuns({ limit: 20 });

// Get specific run
const run = await kaman.workflows.getRun('run-456');

Function/Tool Execution

// List functions
const { data: functions } = await kaman.functions.list();

// Search functions
const matches = await kaman.functions.search('email');

// Execute by ID
const result = await kaman.functions.execute({
  functionId: 'fn-123',
  input: { to: '[email protected]', subject: 'Hello' }
});

// Execute by name
const result = await kaman.functions.executeByName('sendEmail', {
  to: '[email protected]',
  body: 'Hello!'
});

KDL (Data Lake) Queries

// List data lakes
const lakes = await kaman.kdl.listDataLakes();

// List schemas
const schemas = await kaman.kdl.listSchemas('main');

// List tables
const tables = await kaman.kdl.listTables('main', 'public');

// Query with filters
const result = await kaman.kdl.query({
  lakeName: 'main',
  schemaName: 'public',
  tableName: 'users',
  columns: ['id', 'email', 'name'],
  where: "status = 'active'",
  orderBy: 'created_at DESC',
  limit: 100
});

// Time travel query (specific version)
const historical = await kaman.kdl.queryAtVersion(
  'main', 'public', 'users', 5, { limit: 50 }
);

// Execute raw SQL
const sqlResult = await kaman.kdl.executeSQL(
  'SELECT COUNT(*) FROM users WHERE status = "active"',
  'main'
);

Knowledge Base Search (RAG)

// List knowledge bases
const { data: kbs } = await kaman.knowledgeBases.list();

// Semantic search
const results = await kaman.knowledgeBases.search('kb-123', {
  query: 'How do I reset my password?',
  topK: 5,
  threshold: 0.7
});

for (const result of results) {
  console.log(`Score: ${result.score}`);
  console.log(`Content: ${result.chunk.content}`);
}

// Search across multiple KBs
const multiResults = await kaman.knowledgeBases.searchMultiple(
  ['kb-1', 'kb-2', 'kb-3'],
  { query: 'billing questions', topK: 10 }
);

User Management (Full CRUD)

// Get current user
const me = await kaman.users.getCurrentUser();

// List users
const { data: users } = await kaman.users.list({ limit: 50 });

// Create user
const newUser = await kaman.users.create({
  email: '[email protected]',
  name: 'New User',
  roles: ['user']
});

// Update user
const updated = await kaman.users.update('user-123', {
  name: 'Updated Name'
});

// Delete user
await kaman.users.remove('user-123');

// Assign role
await kaman.users.assignRole('user-123', 'role-456');

// Remove role
await kaman.users.removeRole('user-123', 'role-456');

// Sign in
const { token, user } = await kaman.users.signIn({
  email: '[email protected]',
  password: 'password'
});
kaman.updateToken(token);

Role Management (Full CRUD)

// List roles
const { data: roles } = await kaman.roles.list();

// Create role
const newRole = await kaman.roles.create({
  name: 'Editor',
  description: 'Can edit content',
  permissions: ['read', 'write']
});

// Update role
const updated = await kaman.roles.update('role-123', {
  permissions: ['read', 'write', 'delete']
});

// Delete role
await kaman.roles.remove('role-123');

// Assign resources to role
await kaman.roles.assignResources('role-123', [
  { resourceType: 'workflow', resourceId: 'wf-1', permission: 'read' }
]);

Authentication

Login with Email/Password (Two-Step Flow)

import { KamanConnector, getAccessToken } from '@yoctotta/kaman-connector';

const kaman = new KamanConnector({
  baseUrl: 'https://api.kaman.example.com'
});

// Option 1: Complete login flow
const result = await kaman.users.login('[email protected]', 'password');
const token = getAccessToken(result);
kaman.setToken(token);

// Option 2: Manual two-step flow (for multi-org users)
const organizations = await kaman.users.verifyEmail('[email protected]');
console.log('Available orgs:', organizations);

const signInResult = await kaman.users.signIn(
  '[email protected]',
  'password',
  organizations[0].id  // Select organization
);
kaman.setToken(signInResult.token.access_token);

JWT Bearer Token

const kaman = new KamanConnector({
  baseUrl: 'https://api.kaman.example.com',
  token: 'your-jwt-token'
});

API Key

const kaman = new KamanConnector({
  baseUrl: 'https://api.kaman.example.com',
  apiKey: 'your-api-key'
});

Update Authentication

// Update token after sign-in
kaman.setToken('new-token');

// Or use updateToken
kaman.updateToken('new-token');

Error Handling

import { KamanApiError } from '@yoctotta/kaman-connector';

try {
  const result = await kaman.workflows.execute('wf-123', { input: {} });
} catch (error) {
  if (error instanceof KamanApiError) {
    console.log('Status:', error.status);
    console.log('Message:', error.message);
    console.log('Details:', error.body);
  }
}

Browser Usage

The SDK works in browsers with native fetch:

<script type="module">
  import { KamanConnector } from 'https://unpkg.com/@yoctotta/kaman-connector/dist/index.js';

  const kaman = new KamanConnector({
    baseUrl: 'https://api.kaman.example.com',
    token: localStorage.getItem('token')
  });

  // Use the connector
  const experts = await kaman.chat.fetchExpertList();
</script>

Testing

# Run unit tests
npm run test:unit

# Run integration tests (requires KAMAN_BASE_URL and KAMAN_TOKEN)
KAMAN_BASE_URL=https://dev.kaman.ai KAMAN_TOKEN=your-token npm run test:integration

# Run all tests
npm run test:all

Types

All types are exported for TypeScript users:

import type {
  // Core
  ConnectorOptions,
  PaginatedResponse,

  // Chat
  ConnectorMessage,
  SendOptions,
  Session,
  Artifact,
  UITool,
  ToolCall,

  // Workflow
  WorkflowDefinition,
  WorkflowRun,
  WorkflowExecuteOptions,

  // Function
  FunctionDefinition,
  FunctionExecuteOptions,

  // KDL
  KDLDataLake,
  KDLSchema,
  KDLTable,
  KDLQueryOptions,
  KDLQueryResult,

  // User
  User,
  UserCreateOptions,

  // Role
  RoleDefinition,
  ResourcePermission,
} from '@yoctotta/kaman-connector';

Individual Client Imports

For tree-shaking, import individual clients:

import { ChatClient } from '@yoctotta/kaman-connector/chat';
import { WorkflowClient } from '@yoctotta/kaman-connector/workflow';
import { KDLClient } from '@yoctotta/kaman-connector/kdl';

Requirements

• Node.js >= 18.0.0 (for native fetch)
• TypeScript >= 5.0.0 (optional)

License

MIT