0
# Linear SDK
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @linear/sdk
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @linear/sdk`
10

11
## Core Imports
12

13
```typescript
14
import { LinearClient } from "@linear/sdk";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { LinearClient } = require("@linear/sdk");
21
```
22

23
For webhooks:
24

25
```typescript
26
import { LinearWebhookClient } from "@linear/sdk/webhooks";
27
```
28

29
Deprecated webhook import (still available but not recommended):
30

31
```typescript
32
import { LinearWebhooks } from "@linear/sdk"; // @deprecated Use LinearWebhookClient from "@linear/sdk/webhooks"
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { LinearClient } from "@linear/sdk";
39

40
// Initialize client with API key
41
const client = new LinearClient({
42
  apiKey: "YOUR_API_KEY"
43
});
44

45
// Fetch issues
46
const issues = await client.issues({
47
  first: 10,
48
  filter: {
49
    team: {
50
      key: {
51
        eq: "ENG"
52
      }
53
    }
54
  }
55
});
56

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

64
// Access the created issue
65
console.log(newIssue.issue?.title);
66
```
67

68
## Architecture
69

70
The Linear SDK is built around several key components:
71

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

80
## Capabilities
81

82
### Core Client Operations
83

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

86
```typescript { .api }
87
class LinearClient extends LinearSdk {
88
  constructor(options: LinearClientOptions);
89

90
  // Key properties
91
  options: LinearClientParsedOptions;
92
  client: LinearGraphQLClient;
93
}
94

95
interface LinearClientOptions extends RequestInit {
96
  apiKey?: string;
97
  accessToken?: string;
98
  apiUrl?: string;
99
}
100
```
101

102
[Core Client Operations](./core-client.md)
103

104
### Issue Management
105

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

108
```typescript { .api }
109
// Query operations
110
issue(id: string): LinearFetch<Issue>;
111
issues(variables?: IssuesQueryVariables): LinearFetch<IssueConnection>;
112

113
// Mutation operations
114
createIssue(input: IssueCreateInput): LinearFetch<IssuePayload>;
115
updateIssue(id: string, input: IssueUpdateInput): LinearFetch<IssuePayload>;
116
deleteIssue(id: string): LinearFetch<DeletePayload>;
117
```
118

119
[Issue Management](./issue-management.md)
120

121
### Project Management
122

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

125
```typescript { .api }
126
// Query operations
127
project(id: string): LinearFetch<Project>;
128
projects(variables?: ProjectsQueryVariables): LinearFetch<ProjectConnection>;
129

130
// Mutation operations
131
createProject(input: ProjectCreateInput): LinearFetch<ProjectPayload>;
132
updateProject(id: string, input: ProjectUpdateInput): LinearFetch<ProjectPayload>;
133
```
134

135
[Project Management](./project-management.md)
136

137
### Team & User Management
138

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

141
```typescript { .api }
142
// Query operations
143
team(id: string): LinearFetch<Team>;
144
teams(variables?: TeamsQueryVariables): LinearFetch<TeamConnection>;
145
users(variables?: UsersQueryVariables): LinearFetch<UserConnection>;
146

147
// Mutation operations
148
createTeam(input: TeamCreateInput): LinearFetch<TeamPayload>;
149
updateTeam(id: string, input: TeamUpdateInput): LinearFetch<TeamPayload>;
150
```
151

152
[Team & User Management](./team-user-management.md)
153

154
### Workflow & Cycle Management
155

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

158
```typescript { .api }
159
// Query operations
160
cycles(variables?: CyclesQueryVariables): LinearFetch<CycleConnection>;
161
workflowStates(variables?: WorkflowStatesQueryVariables): LinearFetch<WorkflowStateConnection>;
162

163
// Mutation operations
164
createCycle(input: CycleCreateInput): LinearFetch<CyclePayload>;
165
updateCycle(id: string, input: CycleUpdateInput): LinearFetch<CyclePayload>;
166
```
167

168
[Workflow & Cycle Management](./workflow-cycle-management.md)
169

170
### Comments & Attachments
171

172
Comment and attachment operations for collaboration and file management.
173

174
```typescript { .api }
175
// Query operations
176
comments(variables?: CommentsQueryVariables): LinearFetch<CommentConnection>;
177
attachments(variables?: AttachmentsQueryVariables): LinearFetch<AttachmentConnection>;
178

179
// Mutation operations
180
createComment(input: CommentCreateInput): LinearFetch<CommentPayload>;
181
updateComment(id: string, input: CommentUpdateInput): LinearFetch<CommentPayload>;
182
```
183

184
[Comments & Attachments](./comments-attachments.md)
185

186
### Error Handling
187

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

190
```typescript { .api }
191
class LinearError extends Error {
192
  type?: LinearErrorType;
193
  errors?: LinearGraphQLError[];
194
  query?: string;
195
  variables?: Record<string, unknown>;
196
  status?: number;
197
  data?: unknown;
198
}
199

200
enum LinearErrorType {
201
  FeatureNotAccessible = "FeatureNotAccessible",
202
  InvalidInput = "InvalidInput",
203
  Ratelimited = "Ratelimited",
204
  NetworkError = "NetworkError",
205
  AuthenticationError = "AuthenticationError",
206
  Forbidden = "Forbidden"
207
}
208
```
209

210
[Error Handling](./error-handling.md)
211

212
### Webhook Processing
213

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

216
```typescript { .api }
217
class LinearWebhookClient {
218
  constructor(secret: string);
219

220
  createHandler(): LinearWebhookHandler;
221
  verify(rawBody: Buffer, signature: string, timestamp?: number): boolean;
222
  parseData(rawBody: Buffer, signature: string, timestamp?: number): LinearWebhookPayload;
223
}
224

225
interface LinearWebhookHandler {
226
  (request: Request): Promise<Response>;
227
  (request: IncomingMessage, response: ServerResponse): Promise<void>;
228
  on<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
229
  off<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
230
}
231
```
232

233
[Webhook Processing](./webhook-processing.md)
234

235
### Pagination & Connections
236

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

239
```typescript { .api }
240
class Connection<Node> extends LinearConnection<Node> {
241
  pageInfo: PageInfo;
242
  nodes: Node[];
243

244
  fetchNext(): Promise<this>;
245
  fetchPrevious(): Promise<this>;
246
}
247

248
interface LinearConnectionVariables {
249
  after?: string | null;
250
  before?: string | null;
251
  first?: number | null;
252
  last?: number | null;
253
}
254
```
255

256
[Pagination & Connections](./pagination-connections.md)
257

258
## Core Types
259

260
```typescript { .api }
261
// Pagination and fetching
262
type LinearFetch<Response> = Promise<Response>;
263
type LinearRequest = <Response, Variables extends Record<string, unknown>>(
264
  doc: DocumentNode,
265
  variables?: Variables
266
) => Promise<Response>;
267

268
// Client configuration
269
interface LinearClientParsedOptions extends RequestInit {
270
  apiUrl: string;
271
}
272

273
// Response structures
274
interface LinearRawResponse<Data> {
275
  data?: Data;
276
  extensions?: unknown;
277
  headers?: Headers;
278
  status?: number;
279
  error?: string;
280
  errors?: LinearGraphQLErrorRaw[];
281
}
282

283
// GraphQL context
284
interface GraphQLRequestContext<Variables extends Record<string, unknown>> {
285
  query: string;
286
  variables?: Variables;
287
}
288
```