@kaiban/sdk 0.1.1 → 0.1.2

package/README.md

@@ -5,20 +5,21 @@ Official TypeScript SDK for the Kaiban API.
 ## Install
 
 ```bash
-npm install @kaiban-sdk
+npm install @kaiban/sdk
 ```
 
 ## Quickstart
 
 ```ts
-import { createKaibanClient } from '@kaiban-sdk';
+import { createKaibanClient } from '@kaiban/sdk';
 
 const client = createKaibanClient({
   tenant: 'agi',
   token: process.env.KAIBAN_TOKEN,
 });
 
-const agents = await client.agents.list();
+const result = await client.agents.list({ limit: 10 });
+console.log(result.data); // Array of agents
 ```
 
 ## Auth and tenancy
@@ -29,18 +30,132 @@ const agents = await client.agents.list();
 
 ## Resources
 
-- activities: list, create, updateBulk
-- agents: list, get, update, feedback
-- boards: list, get
-- cards: list, get, create, update, delete, moveToColumn
-- external-channels: list, get
-- resources: list, get, publish
-- supervisor-feedback: list by agent
-- teams: list, get
+The SDK provides clients for the following API resources:
+
+### Available Resource Clients
+
+- **agents**: `list`, `listAll`, `get`, `update`, `createFeedback`, `listSupervisorFeedback`
+- **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`
+- **resources**: `list`, `listAll`, `get`
+- **external_channels**: `list`, `listAll`, `get`
+
+### Pagination
+
+All `list` methods return paginated results with cursor-based navigation:
+
+```ts
+import { type Paginated, type Agent, type ListParams } from '@kaiban/sdk';
+
+// Basic pagination
+const params: ListParams = {
+  limit: 10,
+  order_by: '-created_at',
+  filters: { status: 'active' },
+};
+
+const result: Paginated<Agent> = await client.agents.list(params);
+console.log(result.data); // Array of Agent objects
+console.log(result.pagination.next_cursor); // Cursor for next page
+console.log(result.pagination.prev_cursor); // Cursor for previous page
+
+// Navigate to next page
+if (result.pagination.next_cursor) {
+  const nextPage = await client.agents.list({
+    limit: 10,
+    after: result.pagination.next_cursor,
+  });
+}
+
+// Navigate backwards
+if (result.pagination.prev_cursor) {
+  const prevPage = await client.agents.list({
+    limit: 10,
+    before: result.pagination.prev_cursor,
+  });
+}
+```
+
+All `listAll` methods return async generators that automatically handle pagination:
+
+```ts
+// Iterate through all items automatically
+for await (const agent of client.agents.listAll({ limit: 100 })) {
+  console.log(agent.id, agent.name);
+}
+```
 
 ## Types
 
-Types are published under the package and re-exported from `@kaiban-sdk` (e.g., `Agent`, `Card`, `BenchmarkExecution`).
+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`
+- **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`
+
+### Example: Using Types
+
+```ts
+import {
+  createKaibanClient,
+  type Agent,
+  type Card,
+  type Activity,
+  type ActivityCreate,
+  type Paginated,
+  type ListParams,
+  CardStatus,
+  ActivityType,
+} from '@kaiban/sdk';
+
+const client = createKaibanClient({
+  tenant: 'my-tenant',
+  token: process.env.KAIBAN_TOKEN!,
+});
+
+// Type-safe card creation
+// Use Omit<Card, 'id' | 'created_at'> for the input type
+const cardData: Omit<Card, 'id' | 'created_at'> = {
+  team_id: 'team-123',
+  board_id: 'board-123',
+  owner_id: 'user-123',
+  agent_id: 'agent-123',
+  title: 'New task',
+  status: CardStatus.BACKLOG,
+  column_key: 'inbox',
+  priority: 'high',
+  member_ids: [],
+};
+
+const card: Card = await client.cards.create(cardData);
+
+// Type-safe card update
+// Use Partial<Omit<Card, 'id' | 'created_at' | 'updated_at'>>
+const updateData: Partial<Omit<Card, 'id' | 'created_at' | 'updated_at'>> = {
+  status: CardStatus.DOING,
+  priority: 'urgent',
+};
+
+const updatedCard: Card = await client.cards.update(card.id, updateData);
+
+// Type-safe activity creation
+const activityData: ActivityCreate = {
+  board_id: card.board_id,
+  team_id: card.team_id,
+  card_id: card.id,
+  type: ActivityType.CARD_COMMENT_ADDED,
+  description: 'Initial comment',
+  actor: { id: 'user-1', type: 'user', name: 'John' },
+};
+
+const activity: Activity = await client.activities.create(activityData);
+```
 
 ## Documentation
 
@@ -84,142 +199,323 @@ npm run docs:clean
 
 ## Configuration
 
+The client accepts the following configuration options:
+
 ```ts
-createKaibanClient({
-  tenant: 'agi',
-  token: '...optional...',
-  baseUrl: 'https://custom-host',
-  timeoutMs: 30000,
-});
+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
+  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)
+    jitter: true, // Add randomness to backoff (default: true)
+  },
+};
+
+const client = createKaibanClient(config);
 ```
 
 ## Per-call options
 
-All resource methods accept optional per-call overrides:
+All resource methods accept an optional `RequestOptions` parameter for per-call overrides:
 
 ```ts
-// Headers, query params, timeout override, and AbortSignal
-await client.cards.list({
-  headers: { 'x-request-id': 'abc-123' },
-  query: { status: 'doing' },
-  timeoutMs: 10_000,
-  signal: new AbortController().signal,
-});
+import { type RequestOptions } from '@kaiban/sdk';
+
+const options: RequestOptions = {
+  headers: { 'x-request-id': 'abc-123' }, // Custom headers
+  timeoutMs: 10_000, // Override timeout for this request
+  signal: new AbortController().signal, // AbortSignal for cancellation
+  retry: {
+    // Override retry behavior
+    maxAttempts: 5,
+  },
+};
+
+await client.cards.list({ limit: 20 }, options);
+await client.agents.get('agent-123', options);
 ```
 
 ## Error handling
 
+The SDK provides typed error classes for different HTTP status codes:
+
 ```ts
-import { createKaibanClient, HttpError } from '@kaiban-sdk';
+import { createKaibanClient, ApiError, NotFoundError, BadRequestError } from '@kaiban/sdk';
 
 try {
-  await client.cards.get({ id: 'non-existent' });
+  await client.cards.get('non-existent-id');
 } catch (err) {
-  if (err instanceof HttpError) {
-    console.error('HTTP error', err.status, err.url, err.body);
+  if (err instanceof NotFoundError) {
+    console.error('Card not found:', err.message);
+  } else if (err instanceof BadRequestError) {
+    console.error('Invalid request:', err.message);
+  } else if (err instanceof ApiError) {
+    console.error('API error:', err.status, err.message);
   } else {
-    console.error('Unexpected error', err);
+    console.error('Unexpected error:', err);
   }
 }
 ```
 
+Available error classes: `ApiError`, `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `TooManyRequestsError`, `InternalServerError`, `TimeoutError`, `AbortedError`.
+
 ## Examples by resource
 
 ### Agents
 
 ```ts
-// List agents
-const agents = await client.agents.list();
+// List agents with pagination
+const result = await client.agents.list({
+  limit: 20,
+  order_by: '-created_at',
+});
+console.log(result.data); // Array of agents
+console.log(result.pagination.next_cursor);
+
+// Iterate through all agents
+for await (const agent of client.agents.listAll({ limit: 100 })) {
+  console.log(agent.id, agent.name);
+}
 
 // Get agent by id
-const agent = await client.agents.get({ id: 'agent_123' });
+const agent = await client.agents.get('agent-123');
 
 // Update agent
-const updated = await client.agents.update({ id: 'agent_123', body: { description: 'New desc' } });
+const updated = await client.agents.update('agent-123', {
+  name: 'Updated Name',
+  description: 'New description',
+});
 
 // Create agent feedback
-await client.agents.createFeedback({ id: 'agent_123', feedback: { rating: 5, comment: 'Great' } });
+await client.agents.createFeedback('agent-123', {
+  team_id: 'team-123',
+  activity_id: 'activity-456',
+  status: 'unprocessed',
+  type: 'user_conversation_feedback',
+  evaluation: 'positive',
+  comment: 'Excellent performance',
+  created_by: 'user-001',
+});
+
+// List supervisor feedback for an agent
+const feedback = await client.agents.listSupervisorFeedback('agent-123', {
+  limit: 10,
+  order_by: '-created_at',
+});
 ```
 
 ### Teams
 
 ```ts
-const teams = await client.teams.list();
-const team = await client.teams.get({ id: 'team_123' });
+// List teams with pagination
+const result = await client.teams.list({
+  limit: 20,
+  filters: { status: 'active' },
+});
+
+// Iterate through all teams
+for await (const team of client.teams.listAll()) {
+  console.log(team.id, team.name);
+}
+
+// Get a specific team
+const team = await client.teams.get('team-123');
 ```
 
 ### Boards
 
 ```ts
-const boards = await client.boards.list();
-const board = await client.boards.get({ id: 'board_123' });
+// List boards
+const result = await client.boards.list({ limit: 10 });
+
+// Iterate through all boards
+for await (const board of client.boards.listAll()) {
+  console.log(board.id, board.name, board.columns);
+}
+
+// Get a specific board
+const board = await client.boards.get('board-123');
 ```
 
 ### Cards
 
 ```ts
-import type { CreateCardInput, UpdateCardInput } from '@kaiban-sdk';
-
-// Create a card
-const createBody: CreateCardInput = {
-  team_id: 'team_123',
-  board_id: 'board_123',
-  owner_id: 'user_123',
-  agent_id: 'agent_123',
-  title: 'Investigate issue',
-  status: 'backlog',
-  column_key: 'inbox',
-  priority: 'medium',
-  member_ids: [],
-};
-const newCard = await client.cards.create({ body: createBody });
+import { CardStatus, ActivityType } from '@kaiban/sdk';
+
+// List cards with pagination and filters
+const result = await client.cards.list({
+  limit: 20,
+  filters: { status: 'doing', board_id: 'board-123' },
+  order_by: '-created_at',
+});
+
+// Iterate through all cards
+for await (const card of client.cards.listAll({ limit: 100 })) {
+  console.log(card.id, card.title);
+}
+
+// Create a card with optional activity tracking
+const newCard = await client.cards.create(
+  {
+    team_id: 'team-123',
+    board_id: 'board-123',
+    owner_id: 'user-123',
+    agent_id: 'agent-123',
+    title: 'Investigate issue',
+    status: CardStatus.BACKLOG,
+    column_key: 'inbox',
+    priority: 'medium',
+    member_ids: [],
+  },
+  { create_activity: true } // Automatically creates a 'card_created' activity
+);
 
 // Get a card
-const card = await client.cards.get({ id: newCard.id });
+const card = await client.cards.get(newCard.id);
 
 // Update a card
-const updateBody: UpdateCardInput = { status: 'doing', priority: 'high' };
-const updatedCard = await client.cards.update({ id: card.id, body: updateBody });
+const updatedCard = await client.cards.update(card.id, {
+  status: CardStatus.DOING,
+  priority: 'high',
+});
 
-// List cards
-const cards = await client.cards.list();
+// Move card to a different column (with automatic activity tracking)
+const movedCard = await client.cards.moveToColumn(card.id, 'in_progress', {
+  actor: {
+    id: 'user-123',
+    type: 'user',
+    name: 'John Doe',
+  },
+});
 
 // Delete a card
-await client.cards.delete({ id: card.id });
+await client.cards.delete(card.id);
+
+// Create an activity for a card
+await client.cards.createActivity(card.id, {
+  board_id: card.board_id,
+  team_id: card.team_id,
+  type: ActivityType.CARD_COMMENT_ADDED,
+  description: 'Added a comment',
+  actor: { id: 'user-1', type: 'user', name: 'Alice' },
+});
 
-// Activities
-const activities = await client.activities.list({ card_id: card.id });
-await client.activities.create({
-  card_id: card.id,
-  body: {
+// Create multiple activities in batch
+await client.cards.createBatchActivities(card.id, [
+  {
     board_id: card.board_id,
     team_id: card.team_id,
-    card_id: card.id,
-    type: 'card_comment_added',
-    description: 'FYI',
-    actor: { id: 'user_1', type: 'user', name: 'Alice' },
+    type: ActivityType.CARD_COMMENT_ADDED,
+    description: 'First comment',
+    actor: { id: 'user-1', type: 'user', name: 'Alice' },
   },
+  {
+    board_id: card.board_id,
+    team_id: card.team_id,
+    type: ActivityType.CARD_PRIORITY_CHANGED,
+    description: 'Changed priority',
+    actor: { id: 'user-1', type: 'user', name: 'Alice' },
+    changes: [{ field: 'priority', old_value: 'medium', new_value: 'high' }],
+  },
+]);
+
+// List activities for a card
+const activities = await client.cards.listActivities(card.id, {
+  limit: 50,
+  order_by: '-created_at',
 });
-await client.activities.updateBulk({ card_id: card.id, body: activities });
+
+// Iterate through all activities for a card
+for await (const activity of client.cards.listAllActivities(card.id, { limit: 100 })) {
+  console.log(activity.type, activity.description);
+}
 ```
 
-### Resources
+### Activities
 
 ```ts
-const resources = await client.resources.list();
-const resource = await client.resources.get({ id: 'resource_123' });
-await client.resources.publish({ resource_id: 'resource_123', userId: 'user_123' });
+import { ActivityType, type ActivityCreate } from '@kaiban/sdk';
+
+// List all activities with filters
+const result = await client.activities.list({
+  limit: 50,
+  filters: { card_id: 'card-123' },
+  order_by: '-created_at',
+});
+
+// Iterate through all activities
+for await (const activity of client.activities.listAll({ limit: 100 })) {
+  console.log(activity.id, activity.type);
+}
+
+// Create a single activity
+await client.activities.create({
+  board_id: 'board-123',
+  team_id: 'team-123',
+  card_id: 'card-123',
+  type: ActivityType.CARD_PRIORITY_CHANGED,
+  description: 'Updated priority',
+  actor: { id: 'user-1', type: 'user', name: 'Alice' },
+  changes: [{ field: 'priority', old_value: 'low', new_value: 'high' }],
+});
+
+// Create multiple activities in batch
+await client.activities.createBatch([
+  {
+    board_id: 'board-123',
+    team_id: 'team-123',
+    card_id: 'card-123',
+    type: ActivityType.CARD_COMMENT_ADDED,
+    description: 'First comment',
+    actor: { id: 'user-1', type: 'user', name: 'Alice' },
+  },
+  {
+    board_id: 'board-123',
+    team_id: 'team-123',
+    card_id: 'card-123',
+    type: ActivityType.CARD_COMMENT_ADDED,
+    description: 'Second comment',
+    actor: { id: 'user-2', type: 'user', name: 'Bob' },
+  },
+]);
 ```
 
-### External Channels
+### Resources
 
 ```ts
-const channels = await client.externalChannels.list();
-const channel = await client.externalChannels.get({ id: 'ext_123' });
+// List resources
+const result = await client.resources.list({
+  limit: 25,
+  order_by: '-created_at',
+});
+
+// Iterate through all resources
+for await (const resource of client.resources.listAll()) {
+  console.log(resource.id, resource.title, resource.status);
+}
+
+// Get a specific resource
+const resource = await client.resources.get('resource-123');
 ```
 
-### Supervisor Feedback
+### External Channels
 
 ```ts
-const feedback = await client.supervisorFeedback.listByAgent({ agent_id: 'agent_123' });
+// List external channels
+const result = await client.external_channels.list({ limit: 15 });
+
+// Iterate through all channels
+for await (const channel of client.external_channels.listAll()) {
+  console.log(channel.id, channel.type, channel.name);
+}
+
+// Get a specific channel
+const channel = await client.external_channels.get('channel-123');
 ```

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lib/client.d.ts

@@ -1,12 +1,11 @@
 import { KaibanClientConfig } from './http/types';
+import { ActivitiesClient } from './resources/ActivitiesClient';
 import { AgentsClient } from './resources/AgentsClient';
-import { CardsClient } from './resources/CardsClient';
-import { TeamsClient } from './resources/TeamsClient';
 import { BoardsClient } from './resources/BoardsClient';
-import { ResourcesClient } from './resources/ResourcesClient';
+import { CardsClient } from './resources/CardsClient';
 import { ExternalChannelsClient } from './resources/ExternalChannelsClient';
-import { SupervisorFeedbackClient } from './resources/SupervisorFeedbackClient';
-import { ActivitiesClient } from './resources/ActivitiesClient';
+import { ResourcesClient } from './resources/ResourcesClient';
+import { TeamsClient } from './resources/TeamsClient';
 /**
  * Main Kaiban SDK client interface providing access to all API resources
  * @category Client
@@ -30,9 +29,7 @@ export interface KaibanClient {
     /** Client for managing resources */
     resources: ResourcesClient;
     /** Client for managing external channels */
-    externalChannels: ExternalChannelsClient;
-    /** Client for managing supervisor feedback */
-    supervisorFeedback: SupervisorFeedbackClient;
+    external_channels: ExternalChannelsClient;
 }
 /**
  * Create a Kaiban SDK client instance

package/dist/lib/client.js

@@ -1,12 +1,11 @@
 import { HttpClient } from './http/HttpClient';
+import { ActivitiesClient } from './resources/ActivitiesClient';
 import { AgentsClient } from './resources/AgentsClient';
-import { CardsClient } from './resources/CardsClient';
-import { TeamsClient } from './resources/TeamsClient';
 import { BoardsClient } from './resources/BoardsClient';
-import { ResourcesClient } from './resources/ResourcesClient';
+import { CardsClient } from './resources/CardsClient';
 import { ExternalChannelsClient } from './resources/ExternalChannelsClient';
-import { SupervisorFeedbackClient } from './resources/SupervisorFeedbackClient';
-import { ActivitiesClient } from './resources/ActivitiesClient';
+import { ResourcesClient } from './resources/ResourcesClient';
+import { TeamsClient } from './resources/TeamsClient';
 /**
  * Create a Kaiban SDK client instance
  *
@@ -45,7 +44,6 @@ export function createKaibanClient(config) {
         teams: new TeamsClient(http),
         boards: new BoardsClient(http),
         resources: new ResourcesClient(http),
-        externalChannels: new ExternalChannelsClient(http),
-        supervisorFeedback: new SupervisorFeedbackClient(http),
+        external_channels: new ExternalChannelsClient(http),
     };
 }

package/dist/lib/http/HttpClient.js

@@ -1,4 +1,4 @@
-import { TimeoutError, AbortedError, RateLimitError, UnavailableError, ServerError, mapHttpToSdkError, } from './errors';
+import { AbortedError, RateLimitError, ServerError, TimeoutError, UnavailableError, mapHttpToSdkError, } from './errors';
 function buildQuery(query) {
     if (!query)
         return '';
@@ -194,10 +194,12 @@ export class HttpClient {
         const queryParams = {};
         if (listParams) {
             // Handle pagination
-            if (listParams.cursor)
-                queryParams.cursor = listParams.cursor;
             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;