🎫 ticket.api

Build your own Trello, Asana, or Jira in minutes.

A lightweight JavaScript SDK for creating task boards, ticket systems, and project trackers. No complex setup — just install and start building.

✨ What You Can Build

• Project boards — Kanban-style task management
• Bug trackers — Issue tracking with priorities and labels
• Support desks — Ticket queues with workflow states
• Sprint planners — Scrum boards with backlogs

🚀 Quick Start

1. Install

npm install ticketkit

2. Create Your First Board

const { TicketKit } = require('ticketkit');

// Initialize
const kit = await TicketKit.create();

// Create a board
const board = await kit.createBoard({ 
  name: 'My Project',
  workflow_id: 'kanban'  // or 'scrum', 'support', 'simple'
});

// Add a ticket
const ticket = await kit.createTicket({
  board_id: board.id,
  title: 'Build awesome feature',
  priority: 'high',
  labels: ['frontend']
});

// Move it through the workflow
await kit.moveTicket(ticket.id, 'in_progress');

3. Get Your Kanban View

const { columns } = await kit.getKanbanView(board.id);

// columns = {
//   backlog: [...],
//   todo: [...],
//   in_progress: [ticket],
//   review: [...],
//   done: [...]
// }

That's it! You now have a working task board.

📋 Features

| Feature | Description | |---------|-------------| | 🔄 Workflows | Kanban, Scrum, Support, or create your own | | ✅ Validation | Enforces valid status transitions | | 💬 Comments | Threaded discussions on tickets | | 📝 Activity Log | Automatic history of all changes | | 🔍 Search | Find tickets with simple queries | | 📦 Subtasks | Break tickets into smaller pieces | | 🔌 Pluggable | SQLite included, easy to swap databases | | 📤 Export | JSON import/export for backups |

🎨 Built-in Workflows

Kanban (default)

backlog → todo → in_progress → review → done

Scrum

backlog → sprint_backlog → in_progress → testing → done

Support (Zendesk-style)

new → open → pending → solved → closed

Simple (Trello-style)

todo → doing → done

Custom Workflow

await kit.createWorkflow({
  id: 'my-flow',
  name: 'Content Pipeline',
  states: ['draft', 'review', 'approved', 'published'],
  transitions: {
    draft: ['review'],
    review: ['draft', 'approved'],
    approved: ['published'],
    published: []
  }
});

📖 Common Tasks

Create a ticket with all options

const ticket = await kit.createTicket({
  board_id: board.id,
  title: 'Fix login bug',
  description: 'Users cannot login with SSO',
  status: 'todo',
  priority: 'urgent',        // low, medium, high, urgent
  labels: ['bug', 'auth'],
  assignees: ['alice', 'bob'],
  due_date: '2024-12-31',
  custom_fields: {
    estimated_hours: 4,
    sprint: 'Sprint 23'
  }
});

Move and assign tickets

// Move through workflow
await kit.moveTicket(ticket.id, 'in_progress');

// Assign to team members
await kit.assignTicket(ticket.id, ['charlie']);

Add comments

// Add a comment
const comment = await kit.addComment(
  ticket.id, 
  'Found the root cause!', 
  'alice'
);

// Reply to a comment
await kit.replyToComment(
  ticket.id, 
  comment.id, 
  'Great, can you fix it today?', 
  'bob'
);

Search tickets

// Find by status
const inProgress = await kit.search(board.id, 'status:in_progress');

// Find by label
const bugs = await kit.search(board.id, 'label:bug');

// Find by assignee
const myTickets = await kit.search(board.id, 'assignee:alice');

// Combine filters
const urgentBugs = await kit.search(board.id, 'priority:urgent label:bug');

Create subtasks

// Create a parent ticket
const epic = await kit.createTicket({
  board_id: board.id,
  title: 'User Authentication System'
});

// Add subtasks
await kit.createSubtask(epic.id, { title: 'Design login page' });
await kit.createSubtask(epic.id, { title: 'Implement OAuth' });
await kit.createSubtask(epic.id, { title: 'Add password reset' });

// Get all subtasks
const subtasks = await kit.getSubtasks(epic.id);

View activity history

const activity = await kit.getActivity(ticket.id);

// [
//   { actor: 'alice', action: 'created', created_at: '...' },
//   { actor: 'alice', action: 'status_changed', changes: { status: { old: 'backlog', new: 'todo' } } },
//   { actor: 'bob', action: 'assigned', changes: { assignees: ['charlie'] } },
//   { actor: 'charlie', action: 'commented', ... }
// ]

🔔 Events

Listen to changes for real-time updates:

kit.on('ticket:created', (ticket) => {
  console.log(`New ticket: ${ticket.title}`);
  // Send notification, update UI, etc.
});

kit.on('ticket:updated', ({ ticket, changes }) => {
  console.log(`Ticket updated:`, changes);
});

kit.on('comment:created', (comment) => {
  console.log(`New comment by ${comment.author}`);
});

Available events:

• ticket:created, ticket:updated, ticket:deleted
• board:created, board:updated, board:deleted
• comment:created

💾 Storage Options

SQLite (default, included)

// In-memory (great for testing)
const kit = await TicketKit.create();

// File-based (persists data)
const kit = await TicketKit.create({ dbPath: './myproject.db' });

Custom Storage Adapter

const { StorageAdapter, TicketKit } = require('ticketkit');

class PostgresAdapter extends StorageAdapter {
  async init() { /* setup */ }
  async createTicket(data) { /* INSERT INTO tickets ... */ }
  async getTicket(id) { /* SELECT * FROM tickets WHERE id = ? */ }
  // ... implement other methods
}

const kit = await TicketKit.create({
  storage: new PostgresAdapter(process.env.DATABASE_URL)
});

📤 Import & Export

// Export all data
const backup = await kit.export();
// { boards: [...], tickets: [...], version: '1.0.0' }

// Save to file
fs.writeFileSync('backup.json', JSON.stringify(backup));

// Import data
const data = JSON.parse(fs.readFileSync('backup.json'));
await kit.import(data);

📊 Data Models

Ticket

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier | | board_id | string | Parent board | | title | string | Ticket title | | description | string | Details | | status | string | Current workflow state | | priority | string | low, medium, high, urgent | | labels | string[] | Tags/categories | | assignees | string[] | Assigned users | | parent_id | string? | For subtasks | | custom_fields | object | Any extra data | | due_date | string? | ISO date | | created_at | string | ISO timestamp | | updated_at | string | ISO timestamp |

Board

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier | | name | string | Board name | | description | string | Details | | workflow_id | string | Which workflow to use | | created_at | string | ISO timestamp |

🛠️ Full API Reference

// Create
const board = await kit.createBoard({ name, description?, workflow_id? });

// Read
const board = await kit.getBoard(id);
const boards = await kit.listBoards();

// Update
await kit.updateBoard(id, { name?, description?, workflow_id? });

// Delete
await kit.deleteBoard(id);

// Create
const ticket = await kit.createTicket(data, actor?);

// Read
const ticket = await kit.getTicket(id);
const tickets = await kit.listTickets({ board_id?, status?, priority?, assignee?, label?, search?, limit?, offset? });

// Update
await kit.updateTicket(id, updates, actor?);
await kit.moveTicket(id, newStatus, actor?);
await kit.assignTicket(id, assignees, actor?);
await kit.bulkUpdateTickets(ids, updates, actor?);

// Delete
await kit.deleteTicket(id, actor?);

// Subtasks
const subtask = await kit.createSubtask(parentId, data, actor?);
const subtasks = await kit.getSubtasks(parentId);

const comment = await kit.addComment(ticketId, content, author);
const reply = await kit.replyToComment(ticketId, parentId, content, author);
const comments = await kit.listComments(ticketId);

const { board, workflow, columns } = await kit.getKanbanView(boardId);
const backlog = await kit.getBacklog(boardId);
const results = await kit.search(boardId, 'status:todo label:bug');

const workflow = await kit.getWorkflow(id);
const custom = await kit.createWorkflow({ id, name, states, transitions });

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

# Clone the repo
git clone https://github.com/Kiara-01-Lab/ticket.api-public.git

# Install dependencies
cd ticketkit && npm install

# Run the demo
npm run demo

📄 License

MIT © 2025 Kiara Lab