@kaiban/sdk 0.1.1

package/README.md

@@ -0,0 +1,225 @@
+# Kaiban TypeScript SDK
+
+Official TypeScript SDK for the Kaiban API.
+
+## Install
+
+```bash
+npm install @kaiban-sdk
+```
+
+## Quickstart
+
+```ts
+import { createKaibanClient } from '@kaiban-sdk';
+
+const client = createKaibanClient({
+  tenant: 'agi',
+  token: process.env.KAIBAN_TOKEN,
+});
+
+const agents = await client.agents.list();
+```
+
+## Auth and tenancy
+
+- Uses `Authorization: Bearer <token>` automatically when provided
+- Sends `x-tenant` with the configured tenant
+- Default base URL: `https://{tenant}.kaiban.io`
+
+## Resources
+
+- activities: list, create, updateBulk
+- agents: list, get, update, feedback
+- boards: list, get
+- cards: list, get, create, update, delete, moveToColumn
+- external-channels: list, get
+- resources: list, get, publish
+- supervisor-feedback: list by agent
+- teams: list, get
+
+## Types
+
+Types are published under the package and re-exported from `@kaiban-sdk` (e.g., `Agent`, `Card`, `BenchmarkExecution`).
+
+## Documentation
+
+The SDK includes comprehensive JSDoc documentation for all client methods and types.
+
+### Generate Documentation
+
+To generate the full API documentation:
+
+```bash
+npm run docs:generate
+```
+
+This will create a `docs` folder with HTML documentation that you can open in your browser.
+
+### Build Documentation
+
+To clean and rebuild the documentation from scratch:
+
+```bash
+npm run docs:build
+```
+
+### Serve Documentation Locally
+
+To generate and serve the documentation locally:
+
+```bash
+npm run docs:serve
+```
+
+This will generate the docs and start a local server (requires `npx serve` to be available).
+
+### Clean Documentation
+
+To remove the generated documentation:
+
+```bash
+npm run docs:clean
+```
+
+## Configuration
+
+```ts
+createKaibanClient({
+  tenant: 'agi',
+  token: '...optional...',
+  baseUrl: 'https://custom-host',
+  timeoutMs: 30000,
+});
+```
+
+## Per-call options
+
+All resource methods accept optional per-call overrides:
+
+```ts
+// Headers, query params, timeout override, and AbortSignal
+await client.cards.list({
+  headers: { 'x-request-id': 'abc-123' },
+  query: { status: 'doing' },
+  timeoutMs: 10_000,
+  signal: new AbortController().signal,
+});
+```
+
+## Error handling
+
+```ts
+import { createKaibanClient, HttpError } from '@kaiban-sdk';
+
+try {
+  await client.cards.get({ id: 'non-existent' });
+} catch (err) {
+  if (err instanceof HttpError) {
+    console.error('HTTP error', err.status, err.url, err.body);
+  } else {
+    console.error('Unexpected error', err);
+  }
+}
+```
+
+## Examples by resource
+
+### Agents
+
+```ts
+// List agents
+const agents = await client.agents.list();
+
+// Get agent by id
+const agent = await client.agents.get({ id: 'agent_123' });
+
+// Update agent
+const updated = await client.agents.update({ id: 'agent_123', body: { description: 'New desc' } });
+
+// Create agent feedback
+await client.agents.createFeedback({ id: 'agent_123', feedback: { rating: 5, comment: 'Great' } });
+```
+
+### Teams
+
+```ts
+const teams = await client.teams.list();
+const team = await client.teams.get({ id: 'team_123' });
+```
+
+### Boards
+
+```ts
+const boards = await client.boards.list();
+const board = await client.boards.get({ id: 'board_123' });
+```
+
+### Cards
+
+```ts
+import type { CreateCardInput, UpdateCardInput } from '@kaiban-sdk';
+
+// Create a card
+const createBody: CreateCardInput = {
+  team_id: 'team_123',
+  board_id: 'board_123',
+  owner_id: 'user_123',
+  agent_id: 'agent_123',
+  title: 'Investigate issue',
+  status: 'backlog',
+  column_key: 'inbox',
+  priority: 'medium',
+  member_ids: [],
+};
+const newCard = await client.cards.create({ body: createBody });
+
+// Get a card
+const card = await client.cards.get({ id: newCard.id });
+
+// Update a card
+const updateBody: UpdateCardInput = { status: 'doing', priority: 'high' };
+const updatedCard = await client.cards.update({ id: card.id, body: updateBody });
+
+// List cards
+const cards = await client.cards.list();
+
+// Delete a card
+await client.cards.delete({ id: card.id });
+
+// Activities
+const activities = await client.activities.list({ card_id: card.id });
+await client.activities.create({
+  card_id: card.id,
+  body: {
+    board_id: card.board_id,
+    team_id: card.team_id,
+    card_id: card.id,
+    type: 'card_comment_added',
+    description: 'FYI',
+    actor: { id: 'user_1', type: 'user', name: 'Alice' },
+  },
+});
+await client.activities.updateBulk({ card_id: card.id, body: activities });
+```
+
+### Resources
+
+```ts
+const resources = await client.resources.list();
+const resource = await client.resources.get({ id: 'resource_123' });
+await client.resources.publish({ resource_id: 'resource_123', userId: 'user_123' });
+```
+
+### External Channels
+
+```ts
+const channels = await client.externalChannels.list();
+const channel = await client.externalChannels.get({ id: 'ext_123' });
+```
+
+### Supervisor Feedback
+
+```ts
+const feedback = await client.supervisorFeedback.listByAgent({ agent_id: 'agent_123' });
+```

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './lib/client';
+export * from './lib/http/errors';
+export * from './lib/resources/AgentsClient';
+export * from './lib/resources/CardsClient';
+export * from './lib/resources/ActivitiesClient';
+export * from './lib/resources/TeamsClient';
+export * from './lib/resources/BoardsClient';
+export * from './lib/resources/ResourcesClient';
+export * from './lib/resources/ExternalChannelsClient';
+export * from './lib/resources/SupervisorFeedbackClient';
+export * from './lib/http/types';
+export * from './types/entities';
+export * from './types/requests';
+export * from './types/responses';
+export * from './types/a2a-data-parts';

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './lib/client';
+export * from './lib/http/errors';
+export * from './lib/resources/AgentsClient';
+export * from './lib/resources/CardsClient';
+export * from './lib/resources/ActivitiesClient';
+export * from './lib/resources/TeamsClient';
+export * from './lib/resources/BoardsClient';
+export * from './lib/resources/ResourcesClient';
+export * from './lib/resources/ExternalChannelsClient';
+export * from './lib/resources/SupervisorFeedbackClient';
+export * from './lib/http/types';
+export * from './types/entities';
+export * from './types/requests';
+export * from './types/responses';
+export * from './types/a2a-data-parts';

package/dist/lib/client.d.ts

@@ -0,0 +1,65 @@
+import { KaibanClientConfig } from './http/types';
+import { AgentsClient } from './resources/AgentsClient';
+import { CardsClient } from './resources/CardsClient';
+import { TeamsClient } from './resources/TeamsClient';
+import { BoardsClient } from './resources/BoardsClient';
+import { ResourcesClient } from './resources/ResourcesClient';
+import { ExternalChannelsClient } from './resources/ExternalChannelsClient';
+import { SupervisorFeedbackClient } from './resources/SupervisorFeedbackClient';
+import { ActivitiesClient } from './resources/ActivitiesClient';
+/**
+ * Main Kaiban SDK client interface providing access to all API resources
+ * @category Client
+ */
+export interface KaibanClient {
+    /**
+     * Set or clear the bearer token used for authorization
+     * @param token - Optional bearer token. If omitted, clears the current token
+     */
+    setToken: (token?: string) => void;
+    /** Client for managing agents */
+    agents: AgentsClient;
+    /** Client for managing cards */
+    cards: CardsClient;
+    /** Client for managing card activities */
+    activities: ActivitiesClient;
+    /** Client for managing teams */
+    teams: TeamsClient;
+    /** Client for managing boards */
+    boards: BoardsClient;
+    /** Client for managing resources */
+    resources: ResourcesClient;
+    /** Client for managing external channels */
+    externalChannels: ExternalChannelsClient;
+    /** Client for managing supervisor feedback */
+    supervisorFeedback: SupervisorFeedbackClient;
+}
+/**
+ * Create a Kaiban SDK client instance
+ *
+ * @param config - Client configuration object
+ * @param config.tenant - The tenant identifier for your Kaiban instance
+ * @param config.token - Optional bearer token for authentication
+ * @param config.baseUrl - Optional custom base URL for the API
+ * @param config.maxRetries - Optional maximum number of request retries (default: 3)
+ * @param config.timeout - Optional request timeout in milliseconds (default: 30000)
+ *
+ * @returns A configured Kaiban client instance
+ *
+ * @example
+ * ```typescript
+ * import { createKaibanClient } from 'kaiban-sdk';
+ *
+ * const client = createKaibanClient({
+ *   tenant: 'my-tenant',
+ *   token: 'my-auth-token',
+ *   baseUrl: 'https://api.kaiban.ai'
+ * });
+ *
+ * // List all agents
+ * const agents = await client.agents.list();
+ * ```
+ *
+ * @category Client
+ */
+export declare function createKaibanClient(config: KaibanClientConfig): KaibanClient;

package/dist/lib/client.js

@@ -0,0 +1,51 @@
+import { HttpClient } from './http/HttpClient';
+import { AgentsClient } from './resources/AgentsClient';
+import { CardsClient } from './resources/CardsClient';
+import { TeamsClient } from './resources/TeamsClient';
+import { BoardsClient } from './resources/BoardsClient';
+import { ResourcesClient } from './resources/ResourcesClient';
+import { ExternalChannelsClient } from './resources/ExternalChannelsClient';
+import { SupervisorFeedbackClient } from './resources/SupervisorFeedbackClient';
+import { ActivitiesClient } from './resources/ActivitiesClient';
+/**
+ * Create a Kaiban SDK client instance
+ *
+ * @param config - Client configuration object
+ * @param config.tenant - The tenant identifier for your Kaiban instance
+ * @param config.token - Optional bearer token for authentication
+ * @param config.baseUrl - Optional custom base URL for the API
+ * @param config.maxRetries - Optional maximum number of request retries (default: 3)
+ * @param config.timeout - Optional request timeout in milliseconds (default: 30000)
+ *
+ * @returns A configured Kaiban client instance
+ *
+ * @example
+ * ```typescript
+ * import { createKaibanClient } from 'kaiban-sdk';
+ *
+ * const client = createKaibanClient({
+ *   tenant: 'my-tenant',
+ *   token: 'my-auth-token',
+ *   baseUrl: 'https://api.kaiban.ai'
+ * });
+ *
+ * // List all agents
+ * const agents = await client.agents.list();
+ * ```
+ *
+ * @category Client
+ */
+export function createKaibanClient(config) {
+    const http = new HttpClient(config);
+    return {
+        setToken: (t) => http.setToken(t),
+        agents: new AgentsClient(http),
+        cards: new CardsClient(http),
+        activities: new ActivitiesClient(http),
+        teams: new TeamsClient(http),
+        boards: new BoardsClient(http),
+        resources: new ResourcesClient(http),
+        externalChannels: new ExternalChannelsClient(http),
+        supervisorFeedback: new SupervisorFeedbackClient(http),
+    };
+}

package/dist/lib/http/HttpClient.d.ts

@@ -0,0 +1,16 @@
+import { ListParams } from '../../types/responses';
+import { KaibanClientConfig, RequestOptions } from './types';
+export declare class HttpClient {
+    private config;
+    private _token?;
+    private retryCfg;
+    constructor(config: KaibanClientConfig);
+    setToken(token?: string): void;
+    private attempt;
+    private request;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    list<T>(path: string, listParams?: ListParams, options?: RequestOptions): Promise<T>;
+}

package/dist/lib/http/HttpClient.js

@@ -0,0 +1,237 @@
+import { TimeoutError, AbortedError, RateLimitError, UnavailableError, ServerError, mapHttpToSdkError, } from './errors';
+function buildQuery(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null)
+            params.append(k, String(v));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export class HttpClient {
+    constructor(config) {
+        const defaultRetry = {
+            maxAttempts: 3,
+            backoffMs: 250,
+            maxBackoffMs: 4000,
+            jitter: true,
+            retryOn: [429, 500, 502, 503, 504],
+            retryMethods: ['GET', 'PUT', 'DELETE'],
+        };
+        const baseUrl = config.baseUrl || `https://${config.tenant}.kaiban.io`;
+        this.config = {
+            tenant: config.tenant,
+            token: config.token,
+            baseUrl,
+            timeoutMs: config.timeoutMs ?? 30000,
+            retry: {
+                ...defaultRetry,
+                ...(config.retry || {}),
+                retryOn: [
+                    ...(Array.isArray((config.retry || {}).retryOn)
+                        ? (config.retry || {}).retryOn
+                        : defaultRetry.retryOn),
+                ],
+                retryMethods: [
+                    ...(Array.isArray((config.retry || {}).retryMethods)
+                        ? (config.retry || {}).retryMethods
+                        : defaultRetry.retryMethods),
+                ],
+            },
+            fetch: config.fetch || fetch,
+            onRequest: config.onRequest || (() => { }),
+            onResponse: config.onResponse || (() => { }),
+        };
+        this._token = config.token;
+        // Normalize retry config with required fields for internal use
+        const r = this.config.retry;
+        this.retryCfg = {
+            maxAttempts: r.maxAttempts ?? defaultRetry.maxAttempts,
+            backoffMs: r.backoffMs ?? defaultRetry.backoffMs,
+            maxBackoffMs: r.maxBackoffMs ?? defaultRetry.maxBackoffMs,
+            jitter: r.jitter ?? defaultRetry.jitter,
+            retryOn: Array.isArray(r.retryOn) ? r.retryOn : defaultRetry.retryOn,
+            retryMethods: Array.isArray(r.retryMethods) ? r.retryMethods : defaultRetry.retryMethods,
+        };
+    }
+    setToken(token) {
+        this._token = token;
+    }
+    async attempt(fn, retryCfg) {
+        const { maxAttempts = 3, backoffMs = 250, maxBackoffMs = 4000, jitter = true } = retryCfg;
+        let attempt = 0;
+        let delay = backoffMs;
+        while (true) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                attempt++;
+                if (attempt >= maxAttempts)
+                    throw err;
+                const wait = jitter ? Math.min(maxBackoffMs, delay * (1 + Math.random())) : delay;
+                await sleep(wait);
+                delay = Math.min(maxBackoffMs, delay * 2);
+            }
+        }
+    }
+    async request(method, path, body, options) {
+        const normalizedPath = path.startsWith('/v1') ? path : `/v1${path}`;
+        const url = `${this.config.baseUrl}${normalizedPath}${buildQuery(options?.query)}`;
+        const headers = {
+            'content-type': 'application/json',
+            'x-tenant': this.config.tenant,
+            ...(this._token ? { authorization: `Bearer ${this._token}` } : {}),
+            ...(options?.headers || {}),
+        };
+        // Compose abort signals: user-provided and timeout
+        const combinedController = new AbortController();
+        const userSignal = options?.signal;
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            combinedController.abort();
+        }, options?.timeoutMs ?? this.config.timeoutMs);
+        const onUserAbort = () => combinedController.abort();
+        if (userSignal) {
+            if (userSignal.aborted) {
+                // propagate immediately
+                combinedController.abort();
+            }
+            else {
+                userSignal.addEventListener('abort', onUserAbort);
+            }
+        }
+        const init = {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+            signal: combinedController.signal,
+        };
+        this.config.onRequest({ method, url, init });
+        const doFetch = async () => {
+            try {
+                const res = await this.config.fetch(url, init);
+                this.config.onResponse({ status: res.status, url, response: res });
+                let parsed;
+                const contentType = res.headers.get('content-type') || '';
+                if (contentType.includes('application/json')) {
+                    try {
+                        parsed = await res.json();
+                    }
+                    catch {
+                        parsed = undefined;
+                    }
+                }
+                else {
+                    parsed = await res.text();
+                }
+                if (!res.ok) {
+                    throw mapHttpToSdkError(res.status, parsed);
+                }
+                return parsed;
+            }
+            catch (e) {
+                if (isAbortError(e)) {
+                    if (timedOut)
+                        throw new TimeoutError();
+                    throw new AbortedError();
+                }
+                throw e;
+            }
+            finally {
+                clearTimeout(timeout);
+                if (userSignal)
+                    userSignal.removeEventListener('abort', onUserAbort);
+            }
+        };
+        const retryCfg = mergeRetryConfig(this.retryCfg, options?.retry);
+        const shouldRetry = (err) => {
+            const methodUpper = method.toUpperCase();
+            const retryableByMethod = retryCfg.retryMethods?.includes(methodUpper);
+            if (!retryableByMethod)
+                return false;
+            if (err instanceof TimeoutError)
+                return true;
+            // Retry on known transient SDK errors
+            if (err instanceof RateLimitError)
+                return retryCfg.retryOn?.includes(429) ?? false;
+            if (err instanceof UnavailableError)
+                return retryCfg.retryOn?.some((c) => c === 502 || c === 503 || c === 504) ?? false;
+            if (err instanceof ServerError)
+                return retryCfg.retryOn?.includes(500) ?? false;
+            return false;
+        };
+        return await this.attempt(async () => {
+            try {
+                return await doFetch();
+            }
+            catch (err) {
+                if (shouldRetry(err))
+                    throw err;
+                throw err;
+            }
+        }, retryCfg);
+    }
+    get(path, options) {
+        return this.request('GET', path, undefined, options);
+    }
+    post(path, body, options) {
+        return this.request('POST', path, body, options);
+    }
+    put(path, body, options) {
+        return this.request('PUT', path, body, options);
+    }
+    delete(path, options) {
+        return this.request('DELETE', path, undefined, options);
+    }
+    list(path, listParams, options) {
+        const queryParams = {};
+        if (listParams) {
+            // Handle pagination
+            if (listParams.cursor)
+                queryParams.cursor = listParams.cursor;
+            if (listParams.limit)
+                queryParams.limit = listParams.limit;
+            // Handle sorting (already a string)
+            if (listParams.order_by)
+                queryParams.order_by = listParams.order_by;
+            // Handle filters
+            if (listParams.filters) {
+                Object.entries(listParams.filters).forEach(([key, value]) => {
+                    queryParams[key] = value;
+                });
+            }
+            // Handle metadata filters for cards
+            if (listParams.metadata) {
+                Object.entries(listParams.metadata).forEach(([key, value]) => {
+                    queryParams[`metadata.${key}`] = value;
+                });
+            }
+        }
+        return this.request('GET', path, undefined, { ...options, query: queryParams });
+    }
+}
+function isAbortError(e) {
+    if (!e)
+        return false;
+    const anyErr = e;
+    return anyErr && anyErr.name === 'AbortError';
+}
+function mergeRetryConfig(base, override) {
+    if (!override)
+        return base;
+    return {
+        maxAttempts: override.maxAttempts ?? base.maxAttempts,
+        backoffMs: override.backoffMs ?? base.backoffMs,
+        maxBackoffMs: override.maxBackoffMs ?? base.maxBackoffMs,
+        jitter: override.jitter ?? base.jitter,
+        retryOn: override.retryOn ? [...override.retryOn] : base.retryOn,
+        retryMethods: override.retryMethods ? [...override.retryMethods] : base.retryMethods,
+    };
+}

package/dist/lib/http/errors.d.ts

@@ -0,0 +1,50 @@
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly body?: unknown;
+    constructor(message: string, status: number, url: string, body?: unknown);
+}
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+export declare class AbortedError extends Error {
+    constructor(message?: string);
+}
+export interface ApiErrorShape {
+    code?: string;
+    message: string;
+    details?: unknown;
+}
+export declare class ApiError extends Error {
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(shape: ApiErrorShape);
+}
+export declare class BadRequestError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class ValidationError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class UnauthorizedError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class ForbiddenError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class NotFoundError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class ConflictError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class RateLimitError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class UnavailableError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class ServerError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare function mapHttpToSdkError(status: number, body: unknown): ApiError;