JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 29
  • Score
    100M100P100Q60218F
  • License MIT

TypeScript client SDK for Nokan Taskboard Public API

Package Exports

  • nokan-client

Readme

@nokan/client

TypeScript SDK for integrating with Nokan Taskboard Public API.

Installation

npm install @nokan/client

Quick Start

import { NokanClient } from '@nokan/client';

const client = new NokanClient({
    token: 'nkn_live_xxx', // Get this from Board Settings > API
    baseUrl: 'https://your-app.vercel.app'
});

// Connect and discover board info
const info = await client.connect();
console.log('Connected to board:', info.boardTitle);
console.log('Permissions:', info.permissions);
console.log('Available columns:', info.columns);

// List tickets
const { data: tickets, meta } = await client.listTickets({ page: 1, limit: 20 });
console.log(`Found ${meta.pagination.total} tickets`);

// Create a ticket
const newTicket = await client.createTicket({
    title: 'Bug report',
    column_id: info.columns[0].id,
    description: 'Something is not working correctly',
    priority: 'high'
});

// Add a comment
await client.addComment(newTicket.id, {
    content: 'This needs immediate attention!'
});

API Reference

Constructor

const client = new NokanClient({
    token: string,       // Required: API token from board settings
    baseUrl?: string,    // Optional: API base URL (default: current origin)
    timeout?: number     // Optional: Request timeout in ms (default: 30000)
});

Methods

connect(): Promise<ApiTokenInfo>

Connect to the API and discover board information. Must be called before using other methods.

Returns:

  • boardId - Board UUID
  • boardTitle - Board name
  • permissions - { read, write, delete } booleans
  • columns - Array of { id, title, order }
  • statuses - Array of { id, label, color }

getBoard(): Promise<Board>

Get current board information. Requires read permission.

listTickets(options?): Promise<PaginatedResponse<Ticket>>

List tickets with pagination and filtering.

Options:

  • page - Page number (default: 1)
  • limit - Items per page, max 100 (default: 50)
  • column_id - Filter by column
  • status_id - Filter by status
  • completed - Filter by completion status

getTicket(ticketId): Promise<TicketDetail>

Get ticket details including comments and attachments.

createTicket(input): Promise<Ticket>

Create a new ticket. Requires write permission.

Input:

  • title - Required
  • column_id - Required
  • description - Optional
  • priority - 'low' | 'medium' | 'high' | 'urgent' (default: 'medium')
  • status_id - Optional

updateTicket(ticketId, input): Promise<Ticket>

Update an existing ticket. Requires write permission.

deleteTicket(ticketId): Promise<void>

Delete a ticket. Requires delete permission.

addComment(ticketId, input): Promise<Comment>

Add a comment to a ticket. Requires write permission.

listComments(ticketId): Promise<Comment[]>

List comments for a ticket. Requires read permission.

addAttachment(ticketId, file, fileName?): Promise<Attachment>

Upload an attachment. Requires write permission. Max 10MB.

listAttachments(ticketId): Promise<Attachment[]>

List attachments for a ticket. Requires read permission.

Error Handling

import {
    NokanClient,
    AuthenticationError,
    PermissionError,
    RateLimitError,
    NotFoundError,
    ValidationError
} from '@nokan/client';

try {
    const ticket = await client.createTicket({ ... });
} catch (error) {
    if (error instanceof AuthenticationError) {
        // Token is invalid or expired
        console.error('Please check your API token');
    } else if (error instanceof PermissionError) {
        // Token doesn't have required permission
        console.error('Missing write permission');
    } else if (error instanceof RateLimitError) {
        // Too many requests
        console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
    } else if (error instanceof NotFoundError) {
        // Resource not found
        console.error('Ticket not found');
    } else if (error instanceof ValidationError) {
        // Invalid input
        console.error(`Validation error: ${error.message}`);
    }
}

Permissions

When creating a token, you can set these permissions:

Permission Allows
read GET endpoints (list, get details)
write POST, PUT endpoints (create, update, comments, attachments)
delete DELETE endpoints (delete tickets)

Rate Limiting

Default rate limit is 60 requests per minute per token. When exceeded, the API returns a 429 status with Retry-After header.

The SDK throws a RateLimitError with:

  • retryAfter - Seconds until rate limit resets
  • resetAt - Date when rate limit resets

License

MIT