or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

comments-attachments.mdcore-client.mderror-handling.mdindex.mdissue-management.mdpagination-connections.mdproject-management.mdteam-user-management.mdwebhook-processing.mdworkflow-cycle-management.md
tile.json

tessl/npm-linear--sdk

The Linear Client SDK for interacting with the Linear GraphQL API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@linear/sdk@59.1.x

To install, run

npx @tessl/cli install tessl/npm-linear--sdk@59.1.0

index.mddocs/

Linear SDK

Linear SDK is the official TypeScript/JavaScript client library for the Linear API, providing comprehensive access to Linear's project management platform. It offers a high-level client interface with authentication, error handling, type safety, and webhook utilities for building integrations and automations with Linear.

Package Information

  • Package Name: @linear/sdk
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @linear/sdk

Core Imports

import { LinearClient } from "@linear/sdk";

For CommonJS:

const { LinearClient } = require("@linear/sdk");

For webhooks:

import { LinearWebhookClient } from "@linear/sdk/webhooks";

Deprecated webhook import (still available but not recommended):

import { LinearWebhooks } from "@linear/sdk"; // @deprecated Use LinearWebhookClient from "@linear/sdk/webhooks"

Basic Usage

import { LinearClient } from "@linear/sdk";

// Initialize client with API key
const client = new LinearClient({
  apiKey: "YOUR_API_KEY"
});

// Fetch issues
const issues = await client.issues({
  first: 10,
  filter: {
    team: {
      key: {
        eq: "ENG"
      }
    }
  }
});

// Create an issue
const newIssue = await client.createIssue({
  teamId: "team-id",
  title: "Bug: Fix login issue",
  description: "Users unable to login"
});

// Access the created issue
console.log(newIssue.issue?.title);

Architecture

The Linear SDK is built around several key components:

  • LinearClient: Main client class providing authenticated access to the Linear GraphQL API
  • Generated SDK: Type-safe operations generated from Linear's GraphQL schema (300+ operations)
  • GraphQL Layer: Low-level GraphQL client handling requests and responses
  • Error System: Comprehensive error types with Linear-specific error handling and rate limiting
  • Webhook System: Secure webhook processing with signature verification and event handling
  • Type System: Complete TypeScript definitions for all Linear API entities and operations
  • Pagination Support: Relay-spec compliant pagination with helper methods

Capabilities

Core Client Operations

Main Linear API client providing authenticated access to all Linear GraphQL operations including queries and mutations.

class LinearClient extends LinearSdk {
  constructor(options: LinearClientOptions);

  // Key properties
  options: LinearClientParsedOptions;
  client: LinearGraphQLClient;
}

interface LinearClientOptions extends RequestInit {
  apiKey?: string;
  accessToken?: string;
  apiUrl?: string;
}

Core Client Operations

Issue Management

Comprehensive issue operations including creation, updates, queries, and relationship management.

// Query operations
issue(id: string): LinearFetch<Issue>;
issues(variables?: IssuesQueryVariables): LinearFetch<IssueConnection>;

// Mutation operations
createIssue(input: IssueCreateInput): LinearFetch<IssuePayload>;
updateIssue(id: string, input: IssueUpdateInput): LinearFetch<IssuePayload>;
deleteIssue(id: string): LinearFetch<DeletePayload>;

Issue Management

Project Management

Project operations for creating, managing, and tracking projects and initiatives.

// Query operations
project(id: string): LinearFetch<Project>;
projects(variables?: ProjectsQueryVariables): LinearFetch<ProjectConnection>;

// Mutation operations
createProject(input: ProjectCreateInput): LinearFetch<ProjectPayload>;
updateProject(id: string, input: ProjectUpdateInput): LinearFetch<ProjectPayload>;

Project Management

Team & User Management

Team and user operations for managing workspace members, teams, and permissions.

// Query operations
team(id: string): LinearFetch<Team>;
teams(variables?: TeamsQueryVariables): LinearFetch<TeamConnection>;
users(variables?: UsersQueryVariables): LinearFetch<UserConnection>;

// Mutation operations
createTeam(input: TeamCreateInput): LinearFetch<TeamPayload>;
updateTeam(id: string, input: TeamUpdateInput): LinearFetch<TeamPayload>;

Team & User Management

Workflow & Cycle Management

Development cycle and workflow state management for organizing work and tracking progress.

// Query operations
cycles(variables?: CyclesQueryVariables): LinearFetch<CycleConnection>;
workflowStates(variables?: WorkflowStatesQueryVariables): LinearFetch<WorkflowStateConnection>;

// Mutation operations
createCycle(input: CycleCreateInput): LinearFetch<CyclePayload>;
updateCycle(id: string, input: CycleUpdateInput): LinearFetch<CyclePayload>;

Workflow & Cycle Management

Comments & Attachments

Comment and attachment operations for collaboration and file management.

// Query operations
comments(variables?: CommentsQueryVariables): LinearFetch<CommentConnection>;
attachments(variables?: AttachmentsQueryVariables): LinearFetch<AttachmentConnection>;

// Mutation operations
createComment(input: CommentCreateInput): LinearFetch<CommentPayload>;
updateComment(id: string, input: CommentUpdateInput): LinearFetch<CommentPayload>;

Comments & Attachments

Error Handling

Comprehensive error handling with Linear-specific error types, rate limiting support, and structured error information.

class LinearError extends Error {
  type?: LinearErrorType;
  errors?: LinearGraphQLError[];
  query?: string;
  variables?: Record<string, unknown>;
  status?: number;
  data?: unknown;
}

enum LinearErrorType {
  FeatureNotAccessible = "FeatureNotAccessible",
  InvalidInput = "InvalidInput",
  Ratelimited = "Ratelimited",
  NetworkError = "NetworkError",
  AuthenticationError = "AuthenticationError",
  Forbidden = "Forbidden"
}

Error Handling

Webhook Processing

Secure webhook handling with signature verification, event parsing, and type-safe event handlers.

class LinearWebhookClient {
  constructor(secret: string);

  createHandler(): LinearWebhookHandler;
  verify(rawBody: Buffer, signature: string, timestamp?: number): boolean;
  parseData(rawBody: Buffer, signature: string, timestamp?: number): LinearWebhookPayload;
}

interface LinearWebhookHandler {
  (request: Request): Promise<Response>;
  (request: IncomingMessage, response: ServerResponse): Promise<void>;
  on<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
  off<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
}

Webhook Processing

Pagination & Connections

Relay-spec compliant pagination with automatic page fetching and helper utilities.

class Connection<Node> extends LinearConnection<Node> {
  pageInfo: PageInfo;
  nodes: Node[];

  fetchNext(): Promise<this>;
  fetchPrevious(): Promise<this>;
}

interface LinearConnectionVariables {
  after?: string | null;
  before?: string | null;
  first?: number | null;
  last?: number | null;
}

Pagination & Connections

Core Types

// Pagination and fetching
type LinearFetch<Response> = Promise<Response>;
type LinearRequest = <Response, Variables extends Record<string, unknown>>(
  doc: DocumentNode,
  variables?: Variables
) => Promise<Response>;

// Client configuration
interface LinearClientParsedOptions extends RequestInit {
  apiUrl: string;
}

// Response structures
interface LinearRawResponse<Data> {
  data?: Data;
  extensions?: unknown;
  headers?: Headers;
  status?: number;
  error?: string;
  errors?: LinearGraphQLErrorRaw[];
}

// GraphQL context
interface GraphQLRequestContext<Variables extends Record<string, unknown>> {
  query: string;
  variables?: Variables;
}