Linear Event Bus Client SDK

A TypeScript SDK for interacting with the Linear Event Bus, enabling seamless integration and automation within Linear workflows.

Features

• Real-time Events: Listen to Linear webhook events in real-time
• TypeScript Support: Full type definitions and IntelliSense support
• Event Filtering: Subscribe to specific event types (Issues, Comments, etc.)
• Easy Integration: Simple API for quick integration into existing projects
• Zero Config: Works out of the box with sensible defaults
• Type Safe: Comprehensive TypeScript interfaces for all event types

Installation

npm install @wkronmiller/linear-event-bus-client

Quick Start

import { LinearWebhookBus, LinearEventSource, ROOT_URL } from '@wkronmiller/linear-event-bus-client';

// Create a webhook bus instance (or use the default ROOT_URL)
const linearWebhookBus = new LinearWebhookBus(ROOT_URL);

// Fetch teams, projects, and issues
const teams = await linearWebhookBus.listTeams();
const projects = await linearWebhookBus.listProjects(teamId);
const issues = await linearWebhookBus.listIssues(teamId, projectId);

// Get an event source for real-time events
const eventSource: LinearEventSource = linearWebhookBus.eventSource();

// Listen to specific event types
eventSource.on('Issue', (event) => {
  console.log('Issue event:', event.action, event.data.title);
});

eventSource.on('Comment', (event) => {
  console.log('Comment event:', event.action, event.data.body);
});

// Listen to other event types
eventSource.on('Project', (event) => {
  console.log('Project event:', event.action);
});

API Reference

LinearWebhookBus

Main class for connecting to the Linear Event Bus API.

Constructor

new LinearWebhookBus(rootUrl: string)

• rootUrl: The root URL for the Linear Event Bus API

Methods

listTeams(): Promise<unknown>

Fetches all available teams.

listProjects(teamId: string): Promise<unknown>

Fetches all projects for a specific team.

listIssues(teamId: string, projectId: string): Promise<unknown>

Fetches all issues for a specific project within a team.

eventSource(): LinearEventSource

Creates and returns a new event source for listening to Linear events via Server-Sent Events.

LinearEventSource

EventEmitter-based class for handling Linear events.

Methods

on(eventType: string, listener: Function): void

Subscribe to specific event types:

• 'Issue' - Issue-related events (create, update, delete)
• 'Comment' - Comment-related events
• 'Project' - Project-related events
• Any other Linear event types as they arrive

off(eventType: string, listener: Function): void

Unsubscribe from events.

close(): void

Close the event source connection.

Event Types

IssueEvent

interface IssueEvent {
  type: 'Issue';
  action: string;
  data: {
    id: string;
    title: string;
    description: string;
    state: {
      id: string;
      name: string;
      type: string;
    };
    [key: string]: any;
  };
  [key: string]: any;
}

CommentEvent

interface CommentEvent {
  type: 'Comment';
  action: string;
  data: {
    id: string;
    body: string;
    issue: {
      id: string;
      title: string;
    };
    [key: string]: any;
  };
  [key: string]: any;
}

OtherEvent

interface OtherEvent {
  type: string;
  action: string;
  data: {
    [key: string]: any;
  };
  [key: string]: any;
}

Project Structure

src/
├── lib.ts                # Main SDK exports (entry point)
├── LinearWebhookBus.ts   # Main API client class
├── LinearEventSource.ts  # EventEmitter-based event source
├── types.ts              # TypeScript interfaces
└── constants.ts          # Configuration constants
dist/                     # Compiled JavaScript (auto-generated)
example.js                # Usage example
README.md                 # This file

Configuration

Default Configuration

The SDK includes a default ROOT_URL constant pointing to https://linear-webhook-bus.rory.technology/api/v1.

You can import and use this default URL:

import { ROOT_URL } from '@wkronmiller/linear-event-bus-client';
const client = new LinearWebhookBus(ROOT_URL);

Advanced Usage

Error Handling

eventSource.on('error', (error) => {
  console.error('Connection error:', error);
});

eventSource.on('close', () => {
  console.log('Connection closed');
});

Filtering Events

eventSource.on('Issue', (event) => {
  // Only handle issue creation events
  if (event.action === 'create') {
    console.log('New issue created:', event.data.title);
  }
});

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { LinearEvent, IssueEvent, CommentEvent } from '@wkronmiller/linear-event-bus-client';

eventSource.on('Issue', (event: IssueEvent) => {
  // Full type safety and autocomplete
  console.log(event.data.title); // TypeScript knows this exists
});

Development

Building

npm run build

Testing

npm test
npm run test:watch
npm run test:coverage

Running the Example

node example.js

Development Mode

npm run dev  # Runs the example with live reload

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• GitHub Issues
• Documentation