@kaiban/sdk 0.4.0 → 0.4.2

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

@@ -25,6 +25,7 @@ export class ApiError extends Error {
         this.name = 'ApiError';
         this.code = shape.code;
         this.details = shape.details;
+        this.meta = shape.meta;
     }
 }
 export class BadRequestError extends ApiError {
@@ -37,6 +38,7 @@ export class ValidationError extends ApiError {
     constructor(shape) {
         super(shape);
         this.name = 'ValidationError';
+        this.details = shape.details;
     }
 }
 export class UnauthorizedError extends ApiError {
@@ -75,6 +77,18 @@ export class UnavailableError extends ApiError {
         this.name = 'UnavailableError';
     }
 }
+export class BadGatewayError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'BadGatewayError';
+    }
+}
+export class GatewayTimeoutError extends ApiError {
+    constructor(shape) {
+        super(shape);
+        this.name = 'GatewayTimeoutError';
+    }
+}
 export class ServerError extends ApiError {
     constructor(shape) {
         super(shape);
@@ -82,8 +96,38 @@ export class ServerError extends ApiError {
     }
 }
 // Map HTTP response status and body to human-friendly SDK errors
+// Uses backend error code when available, falls back to HTTP status mapping
 export 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);
@@ -100,14 +144,20 @@ export 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' };
@@ -115,12 +165,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/esm/lib/resources/AgentsClient.js

@@ -102,6 +102,34 @@ export 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/esm/lib/resources/BoardsClient.js

@@ -71,4 +71,46 @@ export 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);
+    }
 }

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

@@ -0,0 +1,98 @@
+/**
+ * Client for managing team members in the Kaiban platform
+ * @category Resources
+ */
+export 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);
+    }
+}

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

@@ -21,8 +21,6 @@ export const 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"
     A2A_TASK_STATUS_SUBMITTED: 'submitted',
     A2A_TASK_STATUS_WORKING: 'working',
     A2A_TASK_STATUS_INPUT_REQUIRED: 'required',

package/dist/types/lib/client.d.ts

@@ -6,6 +6,7 @@ import { CardsClient } from './resources/CardsClient';
 import { ExternalChannelsClient } from './resources/ExternalChannelsClient';
 import { ModelCost } from './resources/ModelCost';
 import { ResourcesClient } from './resources/ResourcesClient';
+import { TeamMembersClient } from './resources/TeamMembersClient';
 import { TeamsClient } from './resources/TeamsClient';
 /**
  * Main Kaiban SDK client interface providing access to all API resources
@@ -25,12 +26,14 @@ export interface KaibanClient {
     activities: ActivitiesClient;
     /** Client for managing teams */
     teams: TeamsClient;
+    /** Client for managing team members */
+    teamMembers: TeamMembersClient;
     /** Client for managing boards */
     boards: BoardsClient;
     /** Client for managing resources */
     resources: ResourcesClient;
     /** Client for managing external channels */
-    external_channels: ExternalChannelsClient;
+    externalChannels: ExternalChannelsClient;
     /** Client for calculate model usage costs*/
     costs: ModelCost;
 }

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

@@ -10,20 +10,38 @@ export declare class TimeoutError extends Error {
 export declare class AbortedError extends Error {
     constructor(message?: string);
 }
+export type ApiErrorCode = 'invalid_argument' | 'not_found' | 'internal' | 'validation_error' | 'permission_denied' | 'unauthenticated' | 'conflict' | 'rate_limit_exceeded' | 'bad_gateway' | 'service_unavailable' | 'gateway_timeout';
+export interface ValidationIssue {
+    code: string;
+    path: Array<string | number>;
+    message: string;
+}
 export interface ApiErrorShape {
-    code?: string;
+    code?: ApiErrorCode;
     message: string;
     details?: unknown;
+    meta?: {
+        request_id?: string;
+        timestamp: string;
+    };
 }
 export declare class ApiError extends Error {
-    readonly code?: string;
+    readonly code?: ApiErrorCode;
     readonly details?: unknown;
+    readonly meta?: {
+        request_id?: string;
+        timestamp: string;
+    };
     constructor(shape: ApiErrorShape);
 }
 export declare class BadRequestError extends ApiError {
     constructor(shape: ApiErrorShape);
 }
 export declare class ValidationError extends ApiError {
+    readonly details?: {
+        issues?: ValidationIssue[];
+        [key: string]: unknown;
+    };
     constructor(shape: ApiErrorShape);
 }
 export declare class UnauthorizedError extends ApiError {
@@ -44,6 +62,12 @@ export declare class RateLimitError extends ApiError {
 export declare class UnavailableError extends ApiError {
     constructor(shape: ApiErrorShape);
 }
+export declare class BadGatewayError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
+export declare class GatewayTimeoutError extends ApiError {
+    constructor(shape: ApiErrorShape);
+}
 export declare class ServerError extends ApiError {
     constructor(shape: ApiErrorShape);
 }

package/dist/types/lib/resources/AgentsClient.d.ts

@@ -93,6 +93,32 @@ export declare class AgentsClient {
      * ```
      */
     get(id: string, options?: RequestOptions): Promise<Agent>;
+    /**
+     * 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: Omit<Agent, 'id' | 'created_at' | 'updated_at' | 'last_active'>, options?: RequestOptions): Promise<Agent>;
     /**
      * Update an agent's properties
      *

package/dist/types/lib/resources/BoardsClient.d.ts

@@ -1,4 +1,4 @@
-import { Board } from '../../types/entities';
+import { Board, CreateBoardInput } from '../../types/entities';
 import { ListParams, Paginated } from '../../types/responses';
 import { HttpClient } from '../http/HttpClient';
 import { RequestOptions } from '../http/types';
@@ -62,4 +62,37 @@ export declare class BoardsClient {
      * ```
      */
     get(id: string, options?: RequestOptions): Promise<Board>;
+    /**
+     * 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: CreateBoardInput, options?: RequestOptions): Promise<Board>;
 }

package/dist/types/lib/resources/TeamMembersClient.d.ts

@@ -0,0 +1,89 @@
+import { TeamMember } from '../../types/entities';
+import { ListParams, Paginated } from '../../types/responses';
+import { HttpClient } from '../http/HttpClient';
+import { RequestOptions } from '../http/types';
+/**
+ * Client for managing team members in the Kaiban platform
+ * @category Resources
+ */
+export declare class TeamMembersClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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?: ListParams, options?: RequestOptions): Promise<Paginated<TeamMember>>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    listAll(params?: Omit<ListParams, 'after' | 'before'>, options?: RequestOptions): AsyncGenerator<TeamMember, void, unknown>;
+    /**
+     * 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: string, options?: RequestOptions): Promise<TeamMember>;
+}

package/dist/types/types/entities/activities.d.ts

@@ -68,16 +68,18 @@ export interface ActivityChange {
     new_value: unknown;
 }
 export interface Activity {
-    id: string;
+    id?: string;
     board_id: string;
-    team_id: string;
     card_id: string;
     type: (typeof ActivityType)[keyof typeof ActivityType];
     description: string;
     actor: ActivityActor;
     changes?: ActivityChange[];
+    created_at?: ISODate;
+    created_by_session_id?: string;
     metadata?: Record<string, unknown>;
     user_id?: string;
-    created_at: ISODate;
+    team_id: string;
+    marked_for_display?: boolean;
 }
 export type ActivityCreate = Omit<Activity, 'id' | 'created_at'>;

package/dist/types/types/entities/agent.d.ts

@@ -16,22 +16,22 @@ export interface AgentExample {
 }
 export interface Agent {
     id: string;
-    name: string;
-    description: string;
-    team_id: string;
-    status: (typeof AgentStatus)[keyof typeof AgentStatus];
-    type: (typeof AgentType)[keyof typeof AgentType];
-    roles: string[];
-    owner_id: string;
     created_by: string;
-    monthly_budget: number;
-    config?: Record<string, unknown>;
-    created_at: ISODate;
-    updated_at?: ISODate;
-    last_active: ISODate;
+    description: string;
     examples: AgentExample[];
     integrations?: string[];
+    last_active: ISODate;
+    monthly_budget: number;
+    name: string;
+    owner_id: string;
+    roles?: string[];
+    status: (typeof AgentStatus)[keyof typeof AgentStatus];
+    team_id: string;
+    type: (typeof AgentType)[keyof typeof AgentType];
+    updated_at: ISODate;
     active_cards?: number;
+    created_at?: ISODate;
+    config?: Record<string, unknown>;
 }
 export declare const AgentFeedbackStatus: {
     readonly UNPROCESSED: "unprocessed";
@@ -61,10 +61,10 @@ export interface AgentFeedback {
 }
 export interface AgentSupervisorFeedback {
     id: string;
-    agent_id: string;
-    team_id: string;
     activity_id: string;
+    team_id: string;
     board_id: string;
+    agent_id: string;
     feedback: string;
     created_by: string;
     created_at: ISODate;

package/dist/types/types/entities/board.d.ts

@@ -9,17 +9,23 @@ export interface Column {
 }
 export interface Board {
     id: string;
-    name: string;
-    description: string;
-    team_id: string;
-    owner_id: string;
-    created_by: string;
-    created_at: ISODate;
     agent_ids: string[];
+    created_at: ISODate;
+    created_by: string;
+    description: string;
     member_ids: string[];
-    allowed_roles: string[];
+    name: string;
+    owner_id: string;
+    team_id: string;
     columns: Column[];
-    tags: string[];
-    dashboard_id?: string | null;
-    is_favorite?: boolean;
+    allowed_roles: string[];
 }
+/**
+ * Input type for creating a new board
+ * Fields agent_ids, member_ids, and allowed_roles are optional and default to []
+ */
+export type CreateBoardInput = Omit<Board, 'id' | 'created_at'> & {
+    agent_ids?: string[];
+    member_ids?: string[];
+    allowed_roles?: string[];
+};