@kaiban/sdk 0.1.9 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ npm install @kaiban/sdk
 import { createKaibanClient } from '@kaiban/sdk';
 
 const client = createKaibanClient({
-  tenant: 'agi',
+  tenant: 'your-tenant',
   token: process.env.KAIBAN_TOKEN,
 });
 
@@ -22,11 +22,12 @@ const result = await client.agents.list({ limit: 10 });
 console.log(result.data); // Array of agents
 ```
 
-## Auth and tenancy
+## Auth and Tenancy
 
 - Uses `Authorization: Bearer <token>` automatically when provided
-- Sends `x-tenant` with the configured tenant
+- Sends `x-tenant` header with the configured tenant
 - Default base URL: `https://{tenant}.kaiban.io`
+- Custom base URL can be configured via `baseUrl` option
 
 ## Resources
 
@@ -41,13 +42,14 @@ The SDK provides clients for the following API resources:
 - **boards**: `list`, `listAll`, `get`
 - **resources**: `list`, `listAll`, `get`
 - **external_channels**: `list`, `listAll`, `get`
+- **costs**: `calculateCosts` (offline utility for model cost calculations)
 
 ### Pagination
 
 All `list` methods return paginated results with cursor-based navigation:
 
 ```ts
-import { type Paginated, type Agent, type ListParams } from '@kaiban/sdk';
+import { type Paginated, type Agent, type Card, type ListParams } from '@kaiban/sdk';
 
 // Basic pagination
 const params: ListParams = {
@@ -76,6 +78,13 @@ if (result.pagination.prev_cursor) {
     before: result.pagination.prev_cursor,
   });
 }
+
+// Filter cards by metadata (cards only)
+const cardsResult: Paginated<Card> = await client.cards.list({
+  limit: 20,
+  metadata: { thread_id: 'thread-123', user_id: 'user-456' },
+});
+// This becomes: ?metadata.thread_id=thread-123&metadata.user_id=user-456
 ```
 
 All `listAll` methods return async generators that automatically handle pagination:
@@ -91,13 +100,19 @@ for await (const agent of client.agents.listAll({ limit: 100 })) {
 
 All types are published and re-exported from `@kaiban/sdk`. Available types include:
 
-- **Entities**: `Agent`, `Card`, `Activity`, `Team`, `Board`, `Resource`, `ExternalChannel`
-- **Request/Response**: `ActivityCreate`, `ListParams`, `Paginated`, `PaginationMeta`
-- **Configuration**: `KaibanClientConfig`, `RequestOptions`
-- **Actors & Changes**: `ActivityActor`, `ActivityChange`
+- **Entities**: `Agent`, `Card`, `Activity`, `Team`, `Board`, `Resource`, `ExternalChannel`, `TeamMember`, `Column`
+- **Agent Types**: `AgentFeedback`, `AgentSupervisorFeedback`, `AgentType`, `AgentStatus`, `AgentFeedbackStatus`, `AgentFeedbackType`, `AgentFeedbackEvaluation`
+- **Activity Types**: `ActivityCreate`, `ActivityActor`, `ActivityChange`, `ActivityType`
 - **Card Types**: `CardStatus`, `CardPart`
-- **Enums/Constants**: `AgentType`, `AgentStatus`, `ActivityType`, `ResourceStatus`, `ExternalChannelType`, `ExternalChannelStatus`, `AgentFeedbackType`, `AgentFeedbackEvaluation`
-- **Error classes**: `ApiError`, `NotFoundError`, `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `ConflictError`, `TooManyRequestsError`, `InternalServerError`, `TimeoutError`, `AbortedError`
+- **Board Types**: `Column`
+- **Resource Types**: `ResourceStatus`
+- **External Channel Types**: `ExternalChannelType`, `ExternalChannelStatus`, `ExternalChannelPriority`
+- **Cost Types**: `ModelCostInput`, `ModelCostOutput`
+- **A2A Data Parts**: `A2ADataPartType`, `ToolCallStartPart`, `ToolCallArgsPart`, `ToolCallEndPart`, `ToolCallResultPart`, `TaskInfoMessagePart`, `TaskStepOutputPart`, `UserEvaluationPart`, `UserThreadFeedbackPart`, `UserCloseThreadPart`, `GenerateReportPart`, `KaibanActivityPart`, `AgentStatusPart`
+- **Request/Response**: `ListParams`, `Paginated`, `PaginationMeta`
+- **Configuration**: `KaibanClientConfig`, `RequestOptions`
+- **Shared Types**: `ISODate`
+- **Error classes**: `HttpError`, `ApiError`, `BadRequestError`, `ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `UnavailableError`, `ServerError`, `TimeoutError`, `AbortedError`
 
 ### Example: Using Types
 
@@ -207,21 +222,36 @@ import { createKaibanClient, type KaibanClientConfig } from '@kaiban/sdk';
 const config: KaibanClientConfig = {
   tenant: 'your-tenant', // Required: Your tenant identifier
   token: 'your-api-token', // Required: Your API authentication token
-  baseUrl: 'https://custom-host', // Optional: Custom API base URL
+  baseUrl: 'https://custom-host', // Optional: Custom API base URL (default: https://{tenant}.kaiban.io)
   timeoutMs: 30000, // Optional: Request timeout in milliseconds (default: 30000)
   retry: {
     // Optional: Retry configuration
     maxAttempts: 3, // Maximum number of retry attempts (default: 3)
-    backoffMs: 1000, // Initial backoff delay (default: 1000)
-    maxBackoffMs: 30000, // Maximum backoff delay (default: 30000)
+    backoffMs: 1000, // Initial backoff delay in ms (default: 1000)
+    maxBackoffMs: 30000, // Maximum backoff delay in ms (default: 30000)
     jitter: true, // Add randomness to backoff (default: true)
+    retryOn: [429, 502, 503, 504], // Optional: HTTP status codes to retry on
+    retryMethods: ['GET', 'PUT', 'DELETE'], // Optional: HTTP methods to retry
+  },
+  fetch: globalThis.fetch, // Optional: Custom fetch implementation
+  onRequest: ({ method, url, init }) => {
+    // Optional: Hook called before each request
+    console.log(`Making ${method} request to ${url}`);
+  },
+  onResponse: ({ status, url, response }) => {
+    // Optional: Hook called after each response
+    console.log(`Received ${status} from ${url}`);
   },
 };
 
 const client = createKaibanClient(config);
+
+// You can also update the token dynamically after client creation
+client.setToken('new-token'); // Set a new token
+client.setToken(); // Clear the token
 ```
 
-## Per-call options
+## Per-call Options
 
 All resource methods accept an optional `RequestOptions` parameter for per-call overrides:
 
@@ -242,29 +272,70 @@ await client.cards.list({ limit: 20 }, options);
 await client.agents.get('agent-123', options);
 ```
 
-## Error handling
+## Error Handling
 
-The SDK provides typed error classes for different HTTP status codes:
+The SDK provides typed error classes for different HTTP status codes and network errors:
 
 ```ts
-import { createKaibanClient, ApiError, NotFoundError, BadRequestError } from '@kaiban/sdk';
+import {
+  createKaibanClient,
+  ApiError,
+  NotFoundError,
+  BadRequestError,
+  ValidationError,
+  UnauthorizedError,
+  RateLimitError,
+  TimeoutError,
+  AbortedError,
+} from '@kaiban/sdk';
+
+const client = createKaibanClient({
+  tenant: 'your-tenant',
+  token: process.env.KAIBAN_TOKEN!,
+});
 
 try {
   await client.cards.get('non-existent-id');
 } catch (err) {
   if (err instanceof NotFoundError) {
     console.error('Card not found:', err.message);
+    console.error('Error code:', err.code); // Optional error code from API
+  } else if (err instanceof ValidationError) {
+    console.error('Validation failed:', err.message);
+    console.error('Details:', err.details); // Additional error details from API
   } else if (err instanceof BadRequestError) {
     console.error('Invalid request:', err.message);
+  } else if (err instanceof UnauthorizedError) {
+    console.error('Authentication required:', err.message);
+  } else if (err instanceof RateLimitError) {
+    console.error('Rate limit exceeded:', err.message);
+  } else if (err instanceof TimeoutError) {
+    console.error('Request timed out');
+  } else if (err instanceof AbortedError) {
+    console.error('Request was cancelled');
   } else if (err instanceof ApiError) {
-    console.error('API error:', err.status, err.message);
+    console.error('API error:', err.message);
   } else {
     console.error('Unexpected error:', err);
   }
 }
 ```
 
-Available error classes: `ApiError`, `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `TooManyRequestsError`, `InternalServerError`, `TimeoutError`, `AbortedError`.
+### Available Error Classes
+
+- **`ApiError`**: Base class for all API errors (includes `code`, `message`, `details` properties)
+- **`BadRequestError`**: 400 - Invalid request format or parameters
+- **`ValidationError`**: 422 - Request validation failed
+- **`UnauthorizedError`**: 401 - Authentication required or failed
+- **`ForbiddenError`**: 403 - Insufficient permissions
+- **`NotFoundError`**: 404 - Resource not found
+- **`ConflictError`**: 409 - Resource conflict
+- **`RateLimitError`**: 429 - Too many requests
+- **`UnavailableError`**: 502, 503, 504 - Service temporarily unavailable
+- **`ServerError`**: 500 or other server errors
+- **`TimeoutError`**: Request exceeded configured timeout
+- **`AbortedError`**: Request was cancelled via AbortSignal
+- **`HttpError`**: Low-level HTTP error (includes `status`, `url`, `body` properties)
 
 ## Examples by resource
 
@@ -519,3 +590,55 @@ for await (const channel of client.external_channels.listAll()) {
 // Get a specific channel
 const channel = await client.external_channels.get('channel-123');
 ```
+
+### Model Costs
+
+The `costs` client provides an offline utility to calculate costs for LLM usage based on token counts:
+
+```ts
+import { type ModelCostInput } from '@kaiban/sdk';
+
+// Calculate costs for multiple model usages
+const usages: ModelCostInput[] = [
+  {
+    model: 'gpt-4o',
+    inputTokens: 1500,
+    outputTokens: 500,
+    reasoningTokens: 200, // Optional: reasoning tokens for models that support it
+  },
+  {
+    model: 'gpt-4o-mini',
+    inputTokens: 3000,
+    outputTokens: 1000,
+  },
+];
+
+const result = client.costs.calculateCosts(usages);
+
+console.log('Total cost:', result.totalCost); // Total cost in dollars
+console.log('Total tokens:', result.totalTokens); // Total tokens used
+
+// Get detailed costs per model
+result.costsByModel.forEach((modelCost) => {
+  console.log(`Model: ${modelCost.model}`);
+  console.log(`  Input tokens: ${modelCost.inputTokens}`);
+  console.log(`  Output tokens: ${modelCost.outputTokens}`);
+  console.log(`  Reasoning tokens: ${modelCost.reasoningTokens}`);
+  console.log(`  Charged output tokens: ${modelCost.chargedOutputTokens}`); // output + reasoning
+  console.log(`  Total tokens: ${modelCost.totalTokens}`);
+  console.log(`  Input cost: $${modelCost.inputCost.toFixed(6)}`);
+  console.log(`  Output cost: $${modelCost.outputCost.toFixed(6)}`);
+  console.log(`  Total cost: $${modelCost.totalCost.toFixed(6)}`);
+});
+```
+
+Supported models and their pricing (per 1M tokens):
+
+- **gpt-4o**: $5.00 input, $20.00 output
+- **gpt-4o-mini**: $0.60 input, $2.40 output
+- **gpt-5**: $1.50 input, $10.00 output
+- **gpt-5-mini**: $0.25 input, $2.00 output
+- **gpt-5-nano**: $0.05 input, $0.40 output
+- **text-embedding-3-small**: $0.02 input, $0.00 output
+
+**Note:** Reasoning tokens (when provided) are billed as output tokens.

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/client"), exports);
+__exportStar(require("./lib/http/errors"), exports);
+__exportStar(require("./lib/http/types"), exports);
+__exportStar(require("./types/entities"), exports);
+__exportStar(require("./types/responses"), exports);

package/dist/cjs/lib/client.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKaibanClient = createKaibanClient;
+const HttpClient_1 = require("./http/HttpClient");
+const ActivitiesClient_1 = require("./resources/ActivitiesClient");
+const AgentsClient_1 = require("./resources/AgentsClient");
+const BoardsClient_1 = require("./resources/BoardsClient");
+const CardsClient_1 = require("./resources/CardsClient");
+const ExternalChannelsClient_1 = require("./resources/ExternalChannelsClient");
+const ModelCost_1 = require("./resources/ModelCost");
+const ResourcesClient_1 = require("./resources/ResourcesClient");
+const TeamsClient_1 = require("./resources/TeamsClient");
+/**
+ * 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
+ */
+function createKaibanClient(config) {
+    const http = new HttpClient_1.HttpClient(config);
+    return {
+        setToken: (t) => http.setToken(t),
+        agents: new AgentsClient_1.AgentsClient(http),
+        cards: new CardsClient_1.CardsClient(http),
+        activities: new ActivitiesClient_1.ActivitiesClient(http),
+        teams: new TeamsClient_1.TeamsClient(http),
+        boards: new BoardsClient_1.BoardsClient(http),
+        resources: new ResourcesClient_1.ResourcesClient(http),
+        external_channels: new ExternalChannelsClient_1.ExternalChannelsClient(http),
+        costs: new ModelCost_1.ModelCost(),
+    };
+}

package/dist/cjs/lib/http/HttpClient.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("./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));
+}
+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/api`;
+        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 (0, errors_1.mapHttpToSdkError)(res.status, parsed);
+                }
+                return parsed;
+            }
+            catch (e) {
+                if (isAbortError(e)) {
+                    if (timedOut)
+                        throw new errors_1.TimeoutError();
+                    throw new errors_1.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 errors_1.TimeoutError)
+                return true;
+            // Retry on known transient SDK errors
+            if (err instanceof errors_1.RateLimitError)
+                return retryCfg.retryOn?.includes(429) ?? false;
+            if (err instanceof errors_1.UnavailableError)
+                return retryCfg.retryOn?.some((c) => c === 502 || c === 503 || c === 504) ?? false;
+            if (err instanceof errors_1.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.limit)
+                queryParams.limit = listParams.limit;
+            if (listParams.before)
+                queryParams.before = listParams.before;
+            if (listParams.after)
+                queryParams.after = listParams.after;
+            // 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 });
+    }
+}
+exports.HttpClient = HttpClient;
+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,
+    };
+}