@kaiban/sdk 0.2.0 → 0.3.1

package/README.md

@@ -35,11 +35,12 @@ The SDK provides clients for the following API resources:
 
 ### Available Resource Clients
 
-- **agents**: `list`, `listAll`, `get`, `update`, `createFeedback`, `listSupervisorFeedback`
+- **agents**: `list`, `listAll`, `get`, `create`, `update`, `createFeedback`, `listSupervisorFeedback`
+- **teamMembers**: `list`, `listAll`, `get`
 - **cards**: `list`, `listAll`, `get`, `create`, `update`, `delete`, `moveToColumn`, `createActivity`, `createBatchActivities`, `listActivities`, `listAllActivities`
 - **activities**: `list`, `listAll`, `create`, `createBatch`
 - **teams**: `list`, `listAll`, `get`
-- **boards**: `list`, `listAll`, `get`
+- **boards**: `list`, `listAll`, `get`, `create`
 - **resources**: `list`, `listAll`, `get`
 - **external_channels**: `list`, `listAll`, `get`
 - **costs**: `calculateCosts` (offline utility for model cost calculations)
@@ -285,6 +286,9 @@ import {
   ValidationError,
   UnauthorizedError,
   RateLimitError,
+  BadGatewayError,
+  GatewayTimeoutError,
+  UnavailableError,
   TimeoutError,
   AbortedError,
 } from '@kaiban/sdk';
@@ -299,22 +303,44 @@ try {
 } catch (err) {
   if (err instanceof NotFoundError) {
     console.error('Card not found:', err.message);
-    console.error('Error code:', err.code); // Optional error code from API
+    console.error('Error code:', err.code); // 'not_found'
+    console.error('Request ID:', err.meta?.request_id);
+    console.error('Timestamp:', err.meta?.timestamp);
   } else if (err instanceof ValidationError) {
     console.error('Validation failed:', err.message);
-    console.error('Details:', err.details); // Additional error details from API
+    console.error('Error code:', err.code); // 'validation_error'
+    // ValidationError.details includes issues array
+    if (err.details?.issues) {
+      err.details.issues.forEach((issue) => {
+        console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+      });
+    }
   } else if (err instanceof BadRequestError) {
     console.error('Invalid request:', err.message);
+    console.error('Error code:', err.code); // 'invalid_argument'
   } else if (err instanceof UnauthorizedError) {
     console.error('Authentication required:', err.message);
+    console.error('Error code:', err.code); // 'unauthenticated'
   } else if (err instanceof RateLimitError) {
     console.error('Rate limit exceeded:', err.message);
+    console.error('Error code:', err.code); // 'rate_limit_exceeded'
+  } else if (err instanceof BadGatewayError) {
+    console.error('Bad gateway:', err.message);
+    console.error('Error code:', err.code); // 'bad_gateway'
+  } else if (err instanceof GatewayTimeoutError) {
+    console.error('Gateway timeout:', err.message);
+    console.error('Error code:', err.code); // 'gateway_timeout'
+  } else if (err instanceof UnavailableError) {
+    console.error('Service unavailable:', err.message);
+    console.error('Error code:', err.code); // 'service_unavailable'
   } 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.message);
+    console.error('Error code:', err.code);
+    console.error('Details:', err.details);
   } else {
     console.error('Unexpected error:', err);
   }
@@ -323,20 +349,29 @@ try {
 
 ### 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
+- **`ApiError`**: Base class for all API errors (includes `code`, `message`, `details`, `meta` properties)
+- **`BadRequestError`**: 400 - Invalid request format or parameters (`invalid_argument`)
+- **`ValidationError`**: 422 - Request validation failed (`validation_error`, includes `details.issues[]`)
+- **`UnauthorizedError`**: 401 - Authentication required or failed (`unauthenticated`)
+- **`ForbiddenError`**: 403 - Insufficient permissions (`permission_denied`)
+- **`NotFoundError`**: 404 - Resource not found (`not_found`)
+- **`ConflictError`**: 409 - Resource conflict (`conflict`)
+- **`RateLimitError`**: 429 - Too many requests (`rate_limit_exceeded`)
+- **`BadGatewayError`**: 502 - Bad gateway (`bad_gateway`)
+- **`UnavailableError`**: 503 - Service temporarily unavailable (`service_unavailable`)
+- **`GatewayTimeoutError`**: 504 - Gateway timeout (`gateway_timeout`)
+- **`ServerError`**: 500 - Internal server error (`internal`)
 - **`TimeoutError`**: Request exceeded configured timeout
 - **`AbortedError`**: Request was cancelled via AbortSignal
 - **`HttpError`**: Low-level HTTP error (includes `status`, `url`, `body` properties)
 
+All API errors include:
+
+- `code`: Backend error code (e.g., `validation_error`, `not_found`)
+- `message`: Human-readable error message
+- `details`: Optional error details (for `ValidationError`, includes `issues[]` array)
+- `meta`: Request metadata with `request_id?` and `timestamp`
+
 ## Examples by resource
 
 ### Agents
@@ -358,6 +393,19 @@ for await (const agent of client.agents.listAll({ limit: 100 })) {
 // Get agent by id
 const agent = await client.agents.get('agent-123');
 
+// Create a new agent
+const newAgent = await client.agents.create({
+  name: 'SupportAgent',
+  description: 'Handles support tickets',
+  team_id: 'team_123',
+  owner_id: 'user_123',
+  created_by: 'user_123',
+  type: 'a2a',
+  status: 'active',
+  monthly_budget: 200,
+  examples: [],
+});
+
 // Update agent
 const updated = await client.agents.update('agent-123', {
   name: 'Updated Name',
@@ -400,6 +448,24 @@ for await (const team of client.teams.listAll()) {
 const team = await client.teams.get('team-123');
 ```
 
+### Team Members
+
+```ts
+// List team members with pagination
+const result = await client.teamMembers.list({
+  limit: 20,
+  order_by: '-joined_at',
+});
+
+// Iterate through all team members
+for await (const member of client.teamMembers.listAll({ limit: 100 })) {
+  console.log(member.id, member.user_id, member.role);
+}
+
+// Get a specific team member
+const member = await client.teamMembers.get('tm-123');
+```
+
 ### Boards
 
 ```ts
@@ -413,6 +479,17 @@ for await (const board of client.boards.listAll()) {
 
 // Get a specific board
 const board = await client.boards.get('board-123');
+
+// Create a new board
+const newBoard = await client.boards.create({
+  name: 'Sales',
+  team_id: 'team_123',
+  owner_id: 'user_123',
+  created_by: 'user_123',
+  description: 'Manage pipeline',
+  columns: [],
+  // agent_ids, member_ids, and allowed_roles are optional (default to [])
+});
 ```
 
 ### Cards

package/dist/cjs/lib/client.js

@@ -9,6 +9,7 @@ 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 TeamMembersClient_1 = require("./resources/TeamMembersClient");
 const TeamsClient_1 = require("./resources/TeamsClient");
 /**
  * Create a Kaiban SDK client instance
@@ -46,6 +47,7 @@ function createKaibanClient(config) {
         cards: new CardsClient_1.CardsClient(http),
         activities: new ActivitiesClient_1.ActivitiesClient(http),
         teams: new TeamsClient_1.TeamsClient(http),
+        teamMembers: new TeamMembersClient_1.TeamMembersClient(http),
         boards: new BoardsClient_1.BoardsClient(http),
         resources: new ResourcesClient_1.ResourcesClient(http),
         external_channels: new ExternalChannelsClient_1.ExternalChannelsClient(http),

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

@@ -165,7 +165,11 @@ class HttpClient {
             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;
+                return retryCfg.retryOn?.includes(503) ?? false;
+            if (err instanceof errors_1.BadGatewayError)
+                return retryCfg.retryOn?.includes(502) ?? false;
+            if (err instanceof errors_1.GatewayTimeoutError)
+                return retryCfg.retryOn?.includes(504) ?? false;
             if (err instanceof errors_1.ServerError)
                 return retryCfg.retryOn?.includes(500) ?? false;
             return false;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServerError = exports.UnavailableError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.BadRequestError = exports.ApiError = exports.AbortedError = exports.TimeoutError = exports.HttpError = void 0;
+exports.ServerError = exports.GatewayTimeoutError = exports.BadGatewayError = exports.UnavailableError = exports.RateLimitError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.ValidationError = exports.BadRequestError = exports.ApiError = exports.AbortedError = exports.TimeoutError = exports.HttpError = void 0;
 exports.mapHttpToSdkError = mapHttpToSdkError;
 class HttpError extends Error {
     constructor(message, status, url, body) {
@@ -32,6 +32,7 @@ class ApiError extends Error {
         this.name = 'ApiError';
         this.code = shape.code;
         this.details = shape.details;
+        this.meta = shape.meta;
     }
 }
 exports.ApiError = ApiError;
@@ -46,6 +47,7 @@ class ValidationError extends ApiError {
     constructor(shape) {
         super(shape);
         this.name = 'ValidationError';
+        this.details = shape.details;
     }
 }
 exports.ValidationError = ValidationError;
@@ -91,6 +93,20 @@ class UnavailableError extends ApiError {
     }
 }
 exports.UnavailableError = UnavailableError;
+class BadGatewayError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'BadGatewayError';
+    }
+}
+exports.BadGatewayError = BadGatewayError;
+class GatewayTimeoutError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'GatewayTimeoutError';
+    }
+}
+exports.GatewayTimeoutError = GatewayTimeoutError;
 class ServerError extends ApiError {
     constructor(shape) {
         super(shape);
@@ -99,8 +115,38 @@ class ServerError extends ApiError {
 }
 exports.ServerError = ServerError;
 // Map HTTP response status and body to human-friendly SDK errors
+// Uses backend error code when available, falls back to HTTP status mapping
 function mapHttpToSdkError(status, body) {
     const shape = normalizeBody(body);
+    // If backend provided an explicit error code, use it to determine error type
+    if (shape.code) {
+        switch (shape.code) {
+            case 'invalid_argument':
+                return new BadRequestError(shape);
+            case 'unauthenticated':
+                return new UnauthorizedError(shape);
+            case 'permission_denied':
+                return new ForbiddenError(shape);
+            case 'not_found':
+                return new NotFoundError(shape);
+            case 'conflict':
+                return new ConflictError(shape);
+            case 'validation_error':
+                return new ValidationError(shape);
+            case 'rate_limit_exceeded':
+                return new RateLimitError(shape);
+            case 'bad_gateway':
+                return new BadGatewayError(shape);
+            case 'service_unavailable':
+                return new UnavailableError(shape);
+            case 'gateway_timeout':
+                return new GatewayTimeoutError(shape);
+            case 'internal':
+            default:
+                return new ServerError(shape);
+        }
+    }
+    // Fallback to HTTP status code mapping if no backend code provided
     switch (status) {
         case 400:
             return new BadRequestError(shape);
@@ -117,14 +163,20 @@ function mapHttpToSdkError(status, body) {
         case 429:
             return new RateLimitError(shape);
         case 502:
+            return new BadGatewayError(shape);
         case 503:
-        case 504:
             return new UnavailableError(shape);
+        case 504:
+            return new GatewayTimeoutError(shape);
         case 500:
         default:
             return new ServerError(shape);
     }
 }
+/**
+ * Normalizes error response body to ApiErrorShape
+ * Backend returns: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+ */
 function normalizeBody(body) {
     if (!body)
         return { message: 'Unknown error' };
@@ -132,12 +184,26 @@ function normalizeBody(body) {
         return { message: body };
     if (typeof body === 'object') {
         const anyBody = body;
-        const code = anyBody['code'] || anyBody['error'];
+        // Backend structure: { error: { code, message, details? }, meta: { request_id?, timestamp } }
+        if (anyBody['error'] && typeof anyBody['error'] === 'object') {
+            const errorObj = anyBody['error'];
+            const meta = anyBody['meta'];
+            return {
+                code: errorObj['code'],
+                message: errorObj['message'] || 'Request failed',
+                details: errorObj['details'],
+                meta,
+            };
+        }
+        // Fallback: try to extract from flat structure (legacy support)
+        const code = anyBody['code'] ||
+            anyBody['error'];
         const message = anyBody['message'] ||
             anyBody['error_description'] ||
             'Request failed';
         const details = anyBody['details'];
-        return { code, message, details };
+        const meta = anyBody['meta'];
+        return { code, message, details, meta };
     }
     return { message: 'Request failed' };
 }

package/dist/cjs/lib/resources/AgentsClient.js

@@ -105,6 +105,34 @@ class AgentsClient {
     get(id, options) {
         return this.http.get(`/agent/${encodeURIComponent(id)}`, options);
     }
+    /**
+     * Create a new agent
+     *
+     * @param data - Agent creation data
+     * @param options - Optional request configuration
+     *
+     * @returns The newly created agent object
+     *
+     * @throws {Error} If creation fails
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.create({
+     *   name: 'SupportAgent',
+     *   description: 'Handles support tickets',
+     *   team_id: 'team_123',
+     *   owner_id: 'user_123',
+     *   created_by: 'user_123',
+     *   type: 'a2a',
+     *   status: 'active',
+     *   monthly_budget: 200,
+     *   examples: []
+     * });
+     * ```
+     */
+    create(data, options) {
+        return this.http.post('/agents', data, options);
+    }
     /**
      * Update an agent's properties
      *

package/dist/cjs/lib/resources/BoardsClient.js

@@ -74,5 +74,47 @@ class BoardsClient {
     get(id, options) {
         return this.http.get(`/board/${encodeURIComponent(id)}`, options);
     }
+    /**
+     * Create a new board
+     *
+     * @param data - Board creation data
+     * @param data.name - The board name
+     * @param data.team_id - The team this board belongs to
+     * @param data.owner_id - The owner of the board
+     * @param data.created_by - The user creating the board
+     * @param data.description - Board description
+     * @param data.agent_ids - Array of agent IDs
+     * @param data.member_ids - Array of member IDs
+     * @param data.allowed_roles - Array of allowed roles
+     * @param data.columns - Array of columns
+     * @param options - Optional request configuration
+     *
+     * @returns The newly created board
+     *
+     * @throws {Error} If creation fails
+     *
+     * @example
+     * ```typescript
+     * const board = await client.boards.create({
+     *   name: 'Sales',
+     *   team_id: 'team_123',
+     *   owner_id: 'user_123',
+     *   created_by: 'user_123',
+     *   description: 'Manage pipeline',
+     *   columns: []
+     *   // agent_ids, member_ids, and allowed_roles are optional (default to [])
+     * });
+     * ```
+     */
+    create(data, options) {
+        // Default empty arrays for optional fields
+        const payload = {
+            ...data,
+            agent_ids: data.agent_ids ?? [],
+            member_ids: data.member_ids ?? [],
+            allowed_roles: data.allowed_roles ?? [],
+        };
+        return this.http.post('/boards', payload, options);
+    }
 }
 exports.BoardsClient = BoardsClient;

package/dist/cjs/lib/resources/TeamMembersClient.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamMembersClient = void 0;
+/**
+ * Client for managing team members in the Kaiban platform
+ * @category Resources
+ */
+class TeamMembersClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List team members with pagination, filters, and sorting
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.limit - Number of items per page (default: 50, max: 100)
+     * @param params.after - Cursor to navigate forwards (get items after this cursor)
+     * @param params.before - Cursor to navigate backwards (get items before this cursor)
+     * @param params.order_by - Fields to sort by (prefix with - for descending order)
+     * @param params.filters - Filter parameters to narrow results
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of team members
+     *
+     * @example
+     * ```typescript
+     * // List first page of team members
+     * const result = await client.teamMembers.list({ limit: 10 });
+     * console.log(result.data); // Array of TeamMember objects
+     * console.log(result.pagination.next_cursor); // Cursor for next page
+     *
+     * // Get next page using cursor
+     * if (result.pagination.next_cursor) {
+     *   const nextPage = await client.teamMembers.list({
+     *     limit: 10,
+     *     after: result.pagination.next_cursor
+     *   });
+     * }
+     * ```
+     */
+    list(params, options) {
+        return this.http.list('/team-members', params, options);
+    }
+    /**
+     * Iterate through all team members using async generator
+     * Automatically handles pagination by following next_cursor
+     *
+     * @param params - Optional query parameters (excluding after/before cursors)
+     * @param params.limit - Number of items per page (used internally for pagination)
+     * @param params.order_by - Fields to sort by (prefix with - for descending order)
+     * @param params.filters - Filter parameters to narrow results
+     * @param options - Optional request configuration
+     *
+     * @yields Individual TeamMember objects
+     *
+     * @example
+     * ```typescript
+     * // Iterate through all team members
+     * for await (const member of client.teamMembers.listAll()) {
+     *   console.log(member.id, member.user_id, member.role);
+     * }
+     *
+     * // With custom page size and sorting
+     * for await (const member of client.teamMembers.listAll({
+     *   limit: 100,
+     *   order_by: '-joined_at',
+     *   filters: { team_id: 'team_123' }
+     * })) {
+     *   console.log(member);
+     * }
+     * ```
+     */
+    async *listAll(params, options) {
+        let cursor = undefined;
+        do {
+            const page = await this.list({ ...(params || {}), after: cursor }, options);
+            for (const item of page.data)
+                yield item;
+            cursor = page.pagination.next_cursor;
+        } while (cursor);
+    }
+    /**
+     * Get a single team member by ID
+     *
+     * @param id - The unique identifier of the team member
+     * @param options - Optional request configuration
+     *
+     * @returns The team member object
+     *
+     * @throws {Error} If the team member is not found or request fails
+     *
+     * @example
+     * ```typescript
+     * const member = await client.teamMembers.get('tm-123');
+     * console.log(member.user_id, member.role);
+     * ```
+     */
+    get(id, options) {
+        return this.http.get(`/team-member/${encodeURIComponent(id)}`, options);
+    }
+}
+exports.TeamMembersClient = TeamMembersClient;

package/dist/cjs/types/entities/activities.js

@@ -24,19 +24,15 @@ exports.ActivityType = {
     CARD_CLONED: 'card_cloned',
     CARD_COLUMN_CHANGED: 'card_column_changed',
     // A2A task status activities
-    // "submitted" | "working" | "input-required" | "completed" | "canceled" | "failed" | "rejected"
-    // | "auth-required" | "unknown"
-    // Types for A2A task status activities
-    // TODO: Understand how to mix with the existing agent task status activities
-    // A2A_TASK_STATUS_SUBMITTED: 'submitted',
-    // A2A_TASK_STATUS_WORKING: 'working',
-    // A2A_TASK_STATUS_INPUT_REQUIRED: 'required',
-    // A2A_TASK_STATUS_COMPLETED: 'completed',
-    // A2A_TASK_STATUS_CANCELED: 'canceled',
-    // A2A_TASK_STATUS_FAILED: 'failed',
-    // A2A_TASK_STATUS_REJECTED: 'rejected',
-    // A2A_TASK_STATUS_AUTH_REQUIRED: 'auth-required',
-    // A2A_TASK_STATUS_UNKNOWN: 'unknown',
+    A2A_TASK_STATUS_SUBMITTED: 'submitted',
+    A2A_TASK_STATUS_WORKING: 'working',
+    A2A_TASK_STATUS_INPUT_REQUIRED: 'required',
+    A2A_TASK_STATUS_COMPLETED: 'completed',
+    A2A_TASK_STATUS_CANCELED: 'canceled',
+    A2A_TASK_STATUS_FAILED: 'failed',
+    A2A_TASK_STATUS_REJECTED: 'rejected',
+    A2A_TASK_STATUS_AUTH_REQUIRED: 'auth-required',
+    A2A_TASK_STATUS_UNKNOWN: 'unknown',
     // Thread activities
     THREAD_USER_MESSAGE: 'thread_user_message',
     THREAD_AGENT_MESSAGE: 'thread_agent_message',

package/dist/esm/lib/client.js

@@ -6,6 +6,7 @@ import { CardsClient } from './resources/CardsClient.js';
 import { ExternalChannelsClient } from './resources/ExternalChannelsClient.js';
 import { ModelCost } from './resources/ModelCost.js';
 import { ResourcesClient } from './resources/ResourcesClient.js';
+import { TeamMembersClient } from './resources/TeamMembersClient.js';
 import { TeamsClient } from './resources/TeamsClient.js';
 /**
  * Create a Kaiban SDK client instance
@@ -43,6 +44,7 @@ export function createKaibanClient(config) {
         cards: new CardsClient(http),
         activities: new ActivitiesClient(http),
         teams: new TeamsClient(http),
+        teamMembers: new TeamMembersClient(http),
         boards: new BoardsClient(http),
         resources: new ResourcesClient(http),
         external_channels: new ExternalChannelsClient(http),

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

@@ -1,4 +1,4 @@
-import { AbortedError, RateLimitError, ServerError, TimeoutError, UnavailableError, mapHttpToSdkError, } from './errors.js';
+import { AbortedError, BadGatewayError, GatewayTimeoutError, RateLimitError, ServerError, TimeoutError, UnavailableError, mapHttpToSdkError, } from './errors.js';
 function buildQuery(query) {
     if (!query)
         return '';
@@ -162,7 +162,11 @@ export class HttpClient {
             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;
+                return retryCfg.retryOn?.includes(503) ?? false;
+            if (err instanceof BadGatewayError)
+                return retryCfg.retryOn?.includes(502) ?? false;
+            if (err instanceof GatewayTimeoutError)
+                return retryCfg.retryOn?.includes(504) ?? false;
             if (err instanceof ServerError)
                 return retryCfg.retryOn?.includes(500) ?? false;
             return false;