@kaiban/sdk 0.1.8 → 0.2.0

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

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardsClient = void 0;
+const entities_1 = require("../../types/entities");
+// Minimal create-activity payload aligned to backend activity schema
+// Activity types are shared in entities
+/**
+ * Client for managing cards in the Kaiban platform
+ * Cards represent work items, tasks, or tickets within boards
+ * @category Resources
+ */
+class CardsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List cards with pagination, filters, and sorting
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.cursor - Cursor for the next page of results
+     * @param params.limit - Number of items per page
+     * @param params.order_by - Fields to sort by
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of cards
+     *
+     * @example
+     * ```typescript
+     * // List cards with filters
+     * const result = await client.cards.list({
+     *   limit: 20,
+     *   order_by: ['created_at']
+     * });
+     * ```
+     */
+    list(params, options) {
+        return this.http.list('/cards', params, options);
+    }
+    /**
+     * Iterate through all cards using async generator
+     * Automatically handles pagination by following next_page_token
+     *
+     * @param params - Optional query parameters (excluding cursor)
+     * @param options - Optional request configuration
+     *
+     * @yields Individual Card objects
+     *
+     * @example
+     * ```typescript
+     * // Process all cards
+     * for await (const card of client.cards.listAll()) {
+     *   console.log(card.title, card.status);
+     * }
+     * ```
+     */
+    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 card by ID
+     *
+     * @param cardId - The unique identifier of the card
+     * @param options - Optional request configuration
+     *
+     * @returns The card object
+     *
+     * @throws {Error} If the card is not found or request fails
+     *
+     * @example
+     * ```typescript
+     * const card = await client.cards.get('card-123');
+     * console.log(card.title, card.description);
+     * ```
+     */
+    get(cardId, options) {
+        return this.http.get(`/card/${encodeURIComponent(cardId)}`, options);
+    }
+    /**
+     * Create a new card with optional activity tracking
+     *
+     * @param data - Card creation data
+     * @param data.title - The card title
+     * @param data.board_id - The board this card belongs to
+     * @param data.column_key - The column where the card should be placed
+     * @param options - Optional request configuration
+     * @param options.create_activity - If true, creates a 'card_created' activity
+     *
+     * @returns The newly created card
+     *
+     * @throws {Error} If creation fails
+     *
+     * @example
+     * ```typescript
+     * const card = await client.cards.create({
+     *   title: 'New Task',
+     *   board_id: 'board-123',
+     *   team_id: 'team-456',
+     *   column_key: 'todo',
+     *   description: 'Task description'
+     * }, { create_activity: true });
+     * ```
+     */
+    async create(data, options) {
+        const card = await this.http.post('/cards', data, options);
+        if (options?.create_activity) {
+            await this.createActivity(card.id, {
+                board_id: card.board_id,
+                team_id: card.team_id,
+                type: entities_1.ActivityType.CARD_CREATED,
+                description: 'Card created',
+                actor: { id: 'sdk', type: 'system', name: 'Kaiban SDK' },
+            }, options);
+        }
+        return card;
+    }
+    /**
+     * Update a card's properties
+     *
+     * @param cardId - The unique identifier of the card to update
+     * @param data - Card data with fields to update
+     * @param options - Optional request configuration
+     *
+     * @returns The updated card object
+     *
+     * @throws {Error} If the card is not found or update fails
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.cards.update('card-123', {
+     *   title: 'Updated Title',
+     *   status: 'in_progress'
+     * });
+     * ```
+     */
+    update(cardId, data, options) {
+        return this.http.put(`/card/${encodeURIComponent(cardId)}`, data, options);
+    }
+    /**
+     * Delete a card by ID
+     *
+     * @param cardId - The unique identifier of the card to delete
+     * @param options - Optional request configuration
+     *
+     * @returns Promise that resolves when the card is deleted
+     *
+     * @throws {Error} If the card is not found or deletion fails
+     *
+     * @example
+     * ```typescript
+     * await client.cards.delete('card-123');
+     * ```
+     */
+    delete(cardId, options) {
+        return this.http.delete(`/card/${encodeURIComponent(cardId)}`, options);
+    }
+    // Activity operations moved to ActivitiesClient
+    /**
+     * Move a card to a new column and automatically record the activity
+     * This is a convenience method that combines update and activity creation
+     *
+     * @param cardId - The unique identifier of the card to move
+     * @param newColumnKey - The key of the destination column
+     * @param options - Optional request configuration
+     * @param options.actor - The actor performing the move (defaults to SDK system actor)
+     *
+     * @returns The updated card object
+     *
+     * @throws {Error} If the card is not found or move fails
+     *
+     * @example
+     * ```typescript
+     * // Move card to 'in_progress' column
+     * const card = await client.cards.moveToColumn('card-123', 'in_progress', {
+     *   actor: {
+     *     id: 'user-456',
+     *     type: 'user',
+     *     name: 'John Doe'
+     *   }
+     * });
+     * ```
+     */
+    async moveToColumn(cardId, newColumnKey, options) {
+        const current = await this.get(cardId, options);
+        const oldColumn = current.column_key;
+        const updated = await this.update(cardId, { column_key: newColumnKey }, options);
+        await this.createActivity(cardId, {
+            board_id: updated.board_id,
+            team_id: updated.team_id,
+            type: entities_1.ActivityType.CARD_COLUMN_CHANGED,
+            description: `Moved card from ${oldColumn} to ${newColumnKey}`,
+            actor: options?.actor || { id: 'sdk', type: 'system', name: 'Kaiban SDK' },
+            changes: [{ field: 'column_key', old_value: oldColumn, new_value: newColumnKey }],
+        }, options);
+        return updated;
+    }
+    /**
+     * Create a new activity for a card
+     * Activities track changes, comments, and events on cards
+     *
+     * @param cardId - The unique identifier of the card
+     * @param data - Activity creation data (card_id is automatically added)
+     * @param data.board_id - The board ID
+     * @param data.team_id - The team ID
+     * @param data.type - The type of activity (e.g., 'card_created', 'card_updated', 'comment')
+     * @param data.description - A description of the activity
+     * @param data.actor - The actor who performed the activity
+     * @param options - Optional request configuration
+     *
+     * @returns The created activity object
+     *
+     * @throws {Error} If the card is not found or creation fails
+     *
+     * @example
+     * ```typescript
+     * const activity = await client.cards.createActivity('card-123', {
+     *   board_id: 'board-456',
+     *   team_id: 'team-789',
+     *   type: 'comment',
+     *   description: 'Added a comment',
+     *   actor: {
+     *     id: 'user-001',
+     *     type: 'user',
+     *     name: 'Jane Doe'
+     *   }
+     * });
+     * ```
+     */
+    createActivity(cardId, data, options) {
+        return this.http.post(`/card/${encodeURIComponent(cardId)}/activities`, {
+            ...data,
+            card_id: cardId,
+        }, options);
+    }
+    /**
+     * Create multiple activities for a card in a single batch request
+     * This is more efficient than creating activities one by one
+     *
+     * @param cardId - The unique identifier of the card
+     * @param data - Array of activity creation data (card_id is automatically added to each)
+     * @param options - Optional request configuration
+     *
+     * @returns The batch creation result
+     *
+     * @throws {Error} If the card is not found or batch creation fails
+     *
+     * @example
+     * ```typescript
+     * const activities = await client.cards.createBatchActivities('card-123', [
+     *   {
+     *     board_id: 'board-456',
+     *     team_id: 'team-789',
+     *     type: 'comment',
+     *     description: 'First comment',
+     *     actor: { id: 'user-001', type: 'user', name: 'Jane Doe' }
+     *   },
+     *   {
+     *     board_id: 'board-456',
+     *     team_id: 'team-789',
+     *     type: 'card_updated',
+     *     description: 'Updated priority',
+     *     actor: { id: 'user-001', type: 'user', name: 'Jane Doe' }
+     *   }
+     * ]);
+     * ```
+     */
+    createBatchActivities(cardId, data, options) {
+        return this.http.post(`/activities:batch`, {
+            items: data.map((item) => ({
+                ...item,
+                card_id: cardId,
+            })),
+        }, options);
+    }
+    /**
+     * List activities for a specific card with pagination, filters, and sorting
+     *
+     * @param cardId - The unique identifier of the card
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.limit - Number of items per page
+     * @param params.after - Cursor to navigate forwards
+     * @param params.before - Cursor to navigate backwards
+     * @param params.order_by - Fields to sort by
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of activities
+     *
+     * @example
+     * ```typescript
+     * // Get first page of activities
+     * const result = await client.cards.listActivities('card-123', {
+     *   limit: 20,
+     *   order_by: '-created_at'
+     * });
+     * console.log(result.data); // Array of Activity objects
+     *
+     * // Get next page
+     * if (result.pagination.next_cursor) {
+     *   const nextPage = await client.cards.listActivities('card-123', {
+     *     limit: 20,
+     *     after: result.pagination.next_cursor
+     *   });
+     * }
+     * ```
+     */
+    listActivities(cardId, params, options) {
+        return this.http.list(`/card/${encodeURIComponent(cardId)}/activities`, params, options);
+    }
+    /**
+     * Iterate through all activities for a card using async generator
+     * Automatically handles pagination by following next_cursor
+     *
+     * @param cardId - The unique identifier of the card
+     * @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
+     * @param options - Optional request configuration
+     *
+     * @yields Individual Activity objects
+     *
+     * @example
+     * ```typescript
+     * // Process all activities for a card
+     * for await (const activity of client.cards.listAllActivities('card-123')) {
+     *   console.log(activity.type, activity.description);
+     * }
+     *
+     * // With custom page size and ordering
+     * for await (const activity of client.cards.listAllActivities('card-123', {
+     *   limit: 100,
+     *   order_by: '-created_at'
+     * })) {
+     *   console.log(activity);
+     * }
+     * ```
+     */
+    async *listAllActivities(cardId, params, options) {
+        let cursor = undefined;
+        do {
+            const page = await this.listActivities(cardId, { ...(params || {}), after: cursor }, options);
+            for (const item of page.data)
+                yield item;
+            cursor = page.pagination.next_cursor;
+        } while (cursor);
+    }
+}
+exports.CardsClient = CardsClient;

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalChannelsClient = void 0;
+/**
+ * Client for managing external channels in the Kaiban platform
+ * External channels represent integrations with external communication platforms
+ * @category Resources
+ */
+class ExternalChannelsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List external channels with pagination, filters, and sorting
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.cursor - Cursor for the next page of results
+     * @param params.limit - Number of items per page
+     * @param params.order_by - Fields to sort by
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of external channels
+     *
+     * @example
+     * ```typescript
+     * const result = await client.externalChannels.list({ limit: 15 });
+     * console.log(result.items);
+     * ```
+     */
+    list(params, options) {
+        return this.http.list('/external-channels', params, options);
+    }
+    /**
+     * Iterate through all external channels using async generator
+     * Automatically handles pagination by following next_page_token
+     *
+     * @param params - Optional query parameters (excluding cursor)
+     * @param options - Optional request configuration
+     *
+     * @yields Individual ExternalChannel objects
+     *
+     * @example
+     * ```typescript
+     * for await (const channel of client.externalChannels.listAll()) {
+     *   console.log(channel.id, channel.platform, channel.name);
+     * }
+     * ```
+     */
+    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 external channel by ID
+     *
+     * @param id - The unique identifier of the external channel
+     * @param options - Optional request configuration
+     *
+     * @returns The external channel object
+     *
+     * @throws {Error} If the channel is not found or request fails
+     *
+     * @example
+     * ```typescript
+     * const channel = await client.externalChannels.get('channel-123');
+     * console.log(channel.platform, channel.configuration);
+     * ```
+     */
+    get(id, options) {
+        return this.http.get(`/external-channel/${encodeURIComponent(id)}`, options);
+    }
+}
+exports.ExternalChannelsClient = ExternalChannelsClient;

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

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelCost = void 0;
+const MODELS_COST = {
+    'gpt-4o-mini': {
+        input_price: 0.6,
+        output_price: 2.4,
+        per_tokens: 1000000,
+    },
+    'gpt-5-mini': {
+        input_price: 0.25,
+        output_price: 2.0,
+        per_tokens: 1000000,
+    },
+    'gpt-5': {
+        input_price: 1.5,
+        output_price: 10.0,
+        per_tokens: 1000000,
+    },
+    'gpt-5-nano': {
+        input_price: 0.05,
+        output_price: 0.4,
+        per_tokens: 1000000,
+    },
+    'gpt-4o': {
+        input_price: 5.0,
+        output_price: 20.0,
+        per_tokens: 1000000,
+    },
+    'text-embedding-3-small': {
+        input_price: 0.02,
+        output_price: 0.0,
+        per_tokens: 1000000,
+    },
+};
+class ModelCost {
+    calculateCosts(costs) {
+        let totalCost = 0;
+        let totalTokens = 0;
+        const costsByModel = costs.map((line) => {
+            const modelConfig = MODELS_COST[line.model];
+            const reasoning = line.reasoningTokens ?? 0;
+            // Output tokens charged = visible output + reasoning tokens
+            const chargedOutputTokens = line.outputTokens + reasoning;
+            // If the model is not configured, return a neutral line with zero cost
+            if (!modelConfig) {
+                const modelTotalTokens = line.inputTokens + chargedOutputTokens;
+                return {
+                    model: line.model,
+                    inputTokens: line.inputTokens,
+                    outputTokens: line.outputTokens,
+                    reasoningTokens: reasoning,
+                    chargedOutputTokens,
+                    totalTokens: modelTotalTokens,
+                    inputCost: 0,
+                    outputCost: 0,
+                    totalCost: 0,
+                };
+            }
+            // Cost of input tokens
+            const inputCost = (line.inputTokens * modelConfig.input_price) / modelConfig.per_tokens;
+            // Cost of output tokens (includes reasoning)
+            const outputCost = (chargedOutputTokens * modelConfig.output_price) / modelConfig.per_tokens;
+            const modelTotalCost = inputCost + outputCost;
+            const modelTotalTokens = line.inputTokens + chargedOutputTokens;
+            totalCost += modelTotalCost;
+            totalTokens += modelTotalTokens;
+            return {
+                model: line.model,
+                inputTokens: line.inputTokens,
+                outputTokens: line.outputTokens,
+                reasoningTokens: reasoning,
+                chargedOutputTokens,
+                totalTokens: modelTotalTokens,
+                inputCost,
+                outputCost,
+                totalCost: modelTotalCost,
+            };
+        });
+        return {
+            totalCost,
+            totalTokens,
+            costsByModel,
+        };
+    }
+}
+exports.ModelCost = ModelCost;

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourcesClient = void 0;
+/**
+ * Client for managing resources in the Kaiban platform
+ * Resources can include documents, files, or other materials
+ * @category Resources
+ */
+class ResourcesClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List resources with pagination, filters, and sorting
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.cursor - Cursor for the next page of results
+     * @param params.limit - Number of items per page
+     * @param params.order_by - Fields to sort by
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of resources
+     *
+     * @example
+     * ```typescript
+     * const result = await client.resources.list({ limit: 25 });
+     * console.log(result.items);
+     * ```
+     */
+    list(params, options) {
+        return this.http.list('/resources', params, options);
+    }
+    /**
+     * Iterate through all resources using async generator
+     * Automatically handles pagination by following next_page_token
+     *
+     * @param params - Optional query parameters (excluding cursor)
+     * @param options - Optional request configuration
+     *
+     * @yields Individual Resource objects
+     *
+     * @example
+     * ```typescript
+     * for await (const resource of client.resources.listAll()) {
+     *   console.log(resource.id, resource.name);
+     * }
+     * ```
+     */
+    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 resource by ID
+     *
+     * @param id - The unique identifier of the resource
+     * @param options - Optional request configuration
+     *
+     * @returns The resource object
+     *
+     * @throws {Error} If the resource is not found or request fails
+     *
+     * @example
+     * ```typescript
+     * const resource = await client.resources.get('resource-123');
+     * console.log(resource.name, resource.type);
+     * ```
+     */
+    get(id, options) {
+        return this.http.get(`/resource/${encodeURIComponent(id)}`, options);
+    }
+}
+exports.ResourcesClient = ResourcesClient;

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

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamsClient = void 0;
+/**
+ * Client for managing teams in the Kaiban platform
+ * @category Resources
+ */
+class TeamsClient {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * List teams with pagination, filters, and sorting
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @param params.cursor - Cursor for pagination (from previous/next response)
+     * @param params.limit - Number of items per page (default: 50, max: 100)
+     * @param params.order_by - Fields to sort by. Use - prefix for descending order
+     * @param params.filters - Filter parameters (e.g., { status: 'active' })
+     * @param options - Optional request configuration
+     *
+     * @returns A paginated list of teams
+     *
+     * @example
+     * ```typescript
+     * // Basic pagination
+     * const result = await client.teams.list({ limit: 20 });
+     * console.log(result.data); // Current page items
+     * console.log(result.pagination.next_cursor); // Use for next page
+     *
+     * // With sorting
+     * const sorted = await client.teams.list({
+     *   order_by: '-created_at',
+     *   limit: 50
+     * });
+     *
+     * // With filters
+     * const filtered = await client.teams.list({
+     *   filters: { status: 'active' }
+     * });
+     *
+     * // Next page
+     * const nextPage = await client.teams.list({
+     *   cursor: result.pagination.next_cursor
+     * });
+     * ```
+     */
+    list(params, options) {
+        return this.http.list('/teams', params, options);
+    }
+    /**
+     * Iterate through all teams using async generator
+     * Automatically handles pagination by following next_page_token
+     *
+     * @param params - Optional query parameters (excluding cursor)
+     * @param options - Optional request configuration
+     *
+     * @yields Individual Team objects
+     *
+     * @example
+     * ```typescript
+     * for await (const team of client.teams.listAll()) {
+     *   console.log(team.id, team.name);
+     * }
+     * ```
+     */
+    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 by ID
+     *
+     * @param id - The unique identifier of the team
+     * @param options - Optional request configuration
+     *
+     * @returns The team object
+     *
+     * @throws {Error} If the team is not found or request fails
+     *
+     * @example
+     * ```typescript
+     * const team = await client.teams.get('team-123');
+     * console.log(team.name);
+     * ```
+     */
+    get(id, options) {
+        return this.http.get(`/team/${encodeURIComponent(id)}`, options);
+    }
+}
+exports.TeamsClient = TeamsClient;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}