@theholocron/linear-client 0.0.0-stage → 1.58.0-alpha.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Newton Koumantzelis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,41 @@
1
- # Temporary Holding Version
1
+ # `@theholocron/linear-client`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript client for the [Linear GraphQL API](https://linear.app/developers).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @theholocron/linear-client
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { createLinearClient } from "@theholocron/linear-client";
15
+
16
+ const linear = createLinearClient({ token: process.env.LINEAR_API_KEY! });
17
+
18
+ const { user, organization } = await linear.teams.viewer();
19
+ const team = await linear.teams.find("ENG");
20
+ const states = await linear.teams.states(team!.id);
21
+
22
+ const issue = await linear.issues.create({ teamId: team!.id, title: "Fix the thing", priority: 2 });
23
+ await linear.issues.comment(issue.id, "On it.");
24
+ ```
25
+
26
+ A personal API key (`lin_api_...`) is sent as is; an OAuth token (`lin_oauth_...`) is sent as a bearer.
27
+ `linear.graphql.query(document, variables)` is the raw handle for anything the groups do not cover.
28
+
29
+ ## API
30
+
31
+ | Group | Methods |
32
+ | ---------- | ------------------------------------------------------------------------------------------------- |
33
+ | `teams` | `viewer`, `list`, `find`, `automation`, `states`, `createState`, `labels`, `createLabel`, `users` |
34
+ | `issues` | `list`, `get`, `create`, `update`, `comments`, `comment`, `relate`, `attach`, `attachmentsForUrl` |
35
+ | `projects` | `list`, `statuses`, `create`, `archive`, `unarchive` |
36
+
37
+ Priority is Linear's own: 0 none, 1 urgent, 2 high, 3 medium, 4 low.
38
+
39
+ ## License
40
+
41
+ MIT
@@ -0,0 +1,419 @@
1
+ import { ErrorSink, Logger } from "@theholocron/observability/core";
2
+ /** The kinds of workflow state Linear groups its states into. */
3
+ type LinearStateType = "triage" | "backlog" | "unstarted" | "started" | "completed" | "canceled";
4
+ /** Linear's priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low. */
5
+ type LinearPriority = 0 | 1 | 2 | 3 | 4;
6
+ /** A person in the workspace. */
7
+ interface LinearUser {
8
+ /** Linear's id for the person. */
9
+ id: string;
10
+ /** The full name. */
11
+ name: string;
12
+ /** The name shown in the app. */
13
+ displayName: string;
14
+ /** The email address, when the key may read it. */
15
+ email?: string;
16
+ }
17
+ /** A team, which owns issues, workflow states and their automation. */
18
+ interface LinearTeam {
19
+ /** Linear's id for the team. */
20
+ id: string;
21
+ /** The short key that prefixes the team's issue identifiers (`ENG`). */
22
+ key: string;
23
+ /** The team's name. */
24
+ name: string;
25
+ }
26
+ /** A team's automation settings: how Linear archives and closes issues on its own. */
27
+ interface LinearTeamAutomation {
28
+ /** Months after which a closed issue is archived (`Float!` in the schema, so never null from Linear); 0 is never. */
29
+ autoArchivePeriod: number | null;
30
+ /** Months of inactivity after which an issue is closed; null (the schema: "Null/undefined means disabled") for never. */
31
+ autoClosePeriod: number | null;
32
+ /** The state an auto-closed issue is put in. */
33
+ autoCloseState: {
34
+ id: string;
35
+ name: string;
36
+ } | null;
37
+ /** Whether the team uses triage. */
38
+ triageEnabled: boolean;
39
+ }
40
+ /** Linear's own names for the moments a git integration can move an issue (`GitAutomationStates`). */
41
+ type LinearGitEvent = "draft" | "review" | "start" | "mergeable" | "merge";
42
+ /** A target branch a git automation rule is scoped to. */
43
+ interface LinearGitTargetBranch {
44
+ /** The branch id. */
45
+ id: string;
46
+ /** The branch name, or a regular expression when `isRegex` is set. */
47
+ branchPattern: string;
48
+ /** Whether `branchPattern` is a regular expression rather than an exact branch name. */
49
+ isRegex: boolean;
50
+ }
51
+ /** One git automation rule of a team: when `event` happens, linked issues move to `state`. */
52
+ interface LinearGitAutomationState {
53
+ /** The rule id. */
54
+ id: string;
55
+ /** What triggers the rule. */
56
+ event: LinearGitEvent;
57
+ /** The state issues move to; null when the rule is set to take no action. */
58
+ state: {
59
+ id: string;
60
+ name: string;
61
+ } | null;
62
+ /** The branch the rule is limited to; null for the team's default rule for the event. */
63
+ targetBranch: LinearGitTargetBranch | null;
64
+ }
65
+ /** One status an issue can be in, belonging to a team. */
66
+ interface LinearWorkflowState {
67
+ /** Linear's id for the state. */
68
+ id: string;
69
+ /** The state's name (`In Progress`). */
70
+ name: string;
71
+ /** The kind of state, which decides how it counts (started, completed, ...). */
72
+ type: LinearStateType;
73
+ /** The colour, as a hex string. */
74
+ color: string;
75
+ /** What the state means, when one was written. */
76
+ description?: string | null;
77
+ /** Where the state sits in the team's list; lower comes first. */
78
+ position: number;
79
+ }
80
+ /** A label, workspace-wide (`team` null) or a team's. */
81
+ interface LinearLabel {
82
+ /** Linear's id for the label. */
83
+ id: string;
84
+ /** The label's name. */
85
+ name: string;
86
+ /** The colour, as a hex string. */
87
+ color: string;
88
+ /** The team that owns the label, or null for a workspace label. */
89
+ team: {
90
+ id: string;
91
+ } | null;
92
+ }
93
+ /** A thing named by its id and its name. */
94
+ interface LinearNamedRef {
95
+ /** Linear's id. */
96
+ id: string;
97
+ /** The name. */
98
+ name: string;
99
+ }
100
+ /** A workflow state as an issue carries it. */
101
+ interface LinearStateRef extends LinearNamedRef {
102
+ /** The kind of state. */
103
+ type: LinearStateType;
104
+ }
105
+ /** A team as an issue or project carries it. */
106
+ interface LinearTeamRef {
107
+ /** Linear's id for the team. */
108
+ id: string;
109
+ /** The team's key. */
110
+ key: string;
111
+ }
112
+ /** The nodes of a connection, when only the list is asked for. */
113
+ interface LinearNodes<T> {
114
+ /** The items. */
115
+ nodes: T[];
116
+ }
117
+ /** An issue named by its id and its identifier. */
118
+ interface LinearIssueRef {
119
+ /** Linear's id for the issue. */
120
+ id: string;
121
+ /** `ENG-42`. */
122
+ identifier: string;
123
+ }
124
+ /** A relation from an issue to another: `type` is `blocks`, `duplicate`, `related` or `similar`. */
125
+ interface LinearRelation {
126
+ /** Linear's id for the relation. */
127
+ id: string;
128
+ /** The kind of relation. */
129
+ type: string;
130
+ /** The issue the relation points at. */
131
+ relatedIssue: LinearIssueRef;
132
+ }
133
+ /** A relation that points at the issue; `issue` is the one it starts from, so for `blocks` it is the blocker. */
134
+ interface LinearInverseRelation {
135
+ /** Linear's id for the relation. */
136
+ id: string;
137
+ /** The kind of relation. */
138
+ type: string;
139
+ /** The issue the relation starts from, with its state so a blocker that is done can be told. */
140
+ issue: LinearIssueRef & {
141
+ state: Pick<LinearStateRef, "type">;
142
+ };
143
+ }
144
+ /** An issue as Linear returns it. */
145
+ interface LinearIssue {
146
+ /** Linear's id for the issue. */
147
+ id: string;
148
+ /** `ENG-42`. */
149
+ identifier: string;
150
+ /** The number within the team (`42`). */
151
+ number: number;
152
+ /** The title. */
153
+ title: string;
154
+ /** The description in Markdown, or null when empty. */
155
+ description: string | null;
156
+ /** The priority, 0 (none) to 4 (low). */
157
+ priority: LinearPriority;
158
+ /** The priority as Linear words it (`High`). */
159
+ priorityLabel: string;
160
+ /** The estimate, in the team's scale. */
161
+ estimate: number | null;
162
+ /** The due date, `YYYY-MM-DD`. */
163
+ dueDate: string | null;
164
+ /** The issue's address in the app. */
165
+ url: string;
166
+ /** When the issue was created, ISO 8601. */
167
+ createdAt: string;
168
+ /** When the issue last changed, ISO 8601. */
169
+ updatedAt: string;
170
+ /** When the issue was completed, ISO 8601, or null. */
171
+ completedAt: string | null;
172
+ /** When the issue was canceled, ISO 8601, or null. */
173
+ canceledAt: string | null;
174
+ /** The workflow state the issue is in. */
175
+ state: LinearStateRef;
176
+ /** The team that owns the issue. */
177
+ team: LinearTeamRef;
178
+ /** Who it is assigned to. */
179
+ assignee: LinearUser | null;
180
+ /** The labels on the issue. */
181
+ labels: LinearNodes<LinearNamedRef>;
182
+ /** The project it belongs to. */
183
+ project: LinearNamedRef | null;
184
+ /** The parent issue, when it is a sub-issue. */
185
+ parent: LinearIssueRef | null;
186
+ /** The links attached to the issue; absent when the read did not ask for them. */
187
+ attachments?: LinearNodes<{
188
+ url: string;
189
+ title: string;
190
+ }>;
191
+ /** Relations that start at this issue (it `blocks` the related one). */
192
+ relations: LinearNodes<LinearRelation>;
193
+ /** Relations that point at this issue (the `issue` of a `blocks` one blocks it). */
194
+ inverseRelations: LinearNodes<LinearInverseRelation>;
195
+ }
196
+ /** A comment on an issue. */
197
+ interface LinearComment {
198
+ /** Linear's id for the comment. */
199
+ id: string;
200
+ /** The text in Markdown. */
201
+ body: string;
202
+ /** When it was written, ISO 8601. */
203
+ createdAt: string;
204
+ /** Who wrote it; null for a deleted user or an integration. */
205
+ user: {
206
+ id: string;
207
+ name: string;
208
+ displayName: string;
209
+ } | null;
210
+ }
211
+ /** What `issues.create` accepts. */
212
+ interface LinearIssueCreate {
213
+ /** The team the issue is made in. */
214
+ teamId: string;
215
+ /** The title. */
216
+ title: string;
217
+ /** The description in Markdown. */
218
+ description?: string;
219
+ /** The priority, 0 (none) to 4 (low). */
220
+ priority?: LinearPriority;
221
+ /** The workflow state; the team's default when left out. */
222
+ stateId?: string;
223
+ /** Who it is assigned to. */
224
+ assigneeId?: string;
225
+ /** The labels to put on it. */
226
+ labelIds?: string[];
227
+ /** The project to put it in. */
228
+ projectId?: string;
229
+ /** The parent issue, to make it a sub-issue. */
230
+ parentId?: string;
231
+ /** The estimate, in the team's scale. */
232
+ estimate?: number;
233
+ /** The due date, `YYYY-MM-DD`. */
234
+ dueDate?: string;
235
+ /** Backdates the issue, which a migration uses to keep the original date. */
236
+ createdAt?: string;
237
+ }
238
+ /** What `issues.update` accepts; a field left out is left alone. */
239
+ type LinearIssueUpdate = Partial<Omit<LinearIssueCreate, "teamId" | "createdAt">>;
240
+ /** What `issues.list` narrows by. */
241
+ interface LinearIssueFilter {
242
+ /** Only issues of this team. */
243
+ teamId?: string;
244
+ /** Only issues in this project. */
245
+ projectId?: string;
246
+ /** Only issues assigned to this person. */
247
+ assigneeId?: string;
248
+ /** Leave out issues that are completed or canceled. */
249
+ openOnly?: boolean;
250
+ /** Stop after this many issues. */
251
+ limit?: number;
252
+ }
253
+ /** A project, Linear's board of work. */
254
+ interface LinearProject {
255
+ /** Linear's id for the project. */
256
+ id: string;
257
+ /** The project's name. */
258
+ name: string;
259
+ /** The short description. */
260
+ description: string;
261
+ /** The project's address in the app. */
262
+ url: string;
263
+ /** Set when the project is archived. */
264
+ archivedAt: string | null;
265
+ /** The project's status. */
266
+ status: LinearProjectStatus;
267
+ /** The teams the project belongs to. */
268
+ teams: LinearNodes<LinearTeamRef>;
269
+ }
270
+ /** A project status: Linear's fixed set is backlog, planned, started, paused, completed, canceled. */
271
+ interface LinearProjectStatus {
272
+ /** Linear's id for the status. */
273
+ id: string;
274
+ /** The status's name. */
275
+ name: string;
276
+ /** The kind of status. */
277
+ type: string;
278
+ }
279
+ /** A link attached to an issue; a migration records the source issue's address this way. */
280
+ interface LinearAttachment {
281
+ /** Linear's id for the attachment. */
282
+ id: string;
283
+ /** The address it links to. */
284
+ url: string;
285
+ /** The title shown beside the link. */
286
+ title: string;
287
+ /** The issue it is attached to. */
288
+ issue: LinearIssueRef;
289
+ }
290
+ /** Sends one GraphQL document to Linear and returns its `data`. */
291
+ interface LinearGraphQL {
292
+ /** Runs a query or mutation; a response with `errors` throws a `ProviderApiError`. */
293
+ query<T>(document: string, variables?: Record<string, unknown>): Promise<T>;
294
+ }
295
+ /** Options of {@link createLinearGraphQL}. */
296
+ interface LinearGraphQLConfig {
297
+ /** A personal API key (`lin_api_...`, sent as is) or an OAuth access token (`lin_oauth_...`, sent as a bearer). */
298
+ token: string;
299
+ /** Defaults to `https://api.linear.app`; `/graphql` is appended. */
300
+ baseUrl?: string;
301
+ /** Overrides `fetch`, for tests. */
302
+ fetch?: typeof fetch;
303
+ /** Structured logger for request diagnostics. */
304
+ logger?: Logger;
305
+ /** Reports transport failures and unexpected 5xx. */
306
+ errors?: ErrorSink;
307
+ }
308
+ /**
309
+ * Linear answers a failed query with HTTP 200 (or 400) and an `errors` array, so this wrapper turns that into the same
310
+ * `ProviderApiError` the REST clients throw. Linear sends a personal key as the bare `Authorization` value and an
311
+ * OAuth token as `Bearer <token>`.
312
+ */
313
+ export declare function createLinearGraphQL(config: LinearGraphQLConfig): LinearGraphQL;
314
+ /** A page of a Linear connection. */
315
+ interface Connection<T> {
316
+ /** The nodes of this page. */
317
+ nodes: T[];
318
+ /** Where the next page starts. */
319
+ pageInfo: {
320
+ /** Whether another page follows. */
321
+ hasNextPage: boolean;
322
+ /** The cursor to pass to fetch that page. */
323
+ endCursor: string | null;
324
+ };
325
+ }
326
+ /** Reads every page of a connection; `fetchPage` receives the cursor to continue from (`null` for the first). */
327
+ export declare function paginate<T>(fetchPage: (after: string | null) => Promise<Connection<T>>): Promise<T[]>;
328
+ /** The fields every issue read returns. */
329
+ export declare const ISSUE_FIELDS = "id identifier number title description priority priorityLabel estimate dueDate url\n\tcreatedAt updatedAt completedAt canceledAt\n\tstate { id name type } team { id key }\n\tassignee { id name displayName email }\n\tlabels(first: 50) { nodes { id name } }\n\tproject { id name } parent { id identifier }\n\tattachments(first: 25) { nodes { url title } }\n\trelations(first: 50) { nodes { id type relatedIssue { id identifier } } }\n\tinverseRelations(first: 50) { nodes { id type issue { id identifier state { type } } } }";
330
+ /** Options of {@link createLinearClient}. */
331
+ export interface LinearClientOptions {
332
+ /** A personal API key (`lin_api_...`) or an OAuth access token (`lin_oauth_...`). */
333
+ token: string;
334
+ /** Overrides the API root, for tests. Defaults to `https://api.linear.app`. */
335
+ baseUrl?: string;
336
+ /** Overrides `fetch`, for tests. */
337
+ fetch?: typeof fetch;
338
+ /** Structured logger for request diagnostics. Defaults to a no-op. */
339
+ logger?: Logger;
340
+ /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
341
+ errors?: ErrorSink;
342
+ }
343
+ /** Creates a Linear client with `teams`, `issues` and `projects` groups and the raw `graphql` handle. */
344
+ export declare function createLinearClient(opts: LinearClientOptions): {
345
+ graphql: LinearGraphQL;
346
+ teams: {
347
+ viewer(): Promise<{
348
+ user: LinearUser;
349
+ organization: {
350
+ id: string;
351
+ name: string;
352
+ urlKey: string;
353
+ };
354
+ }>;
355
+ list(): Promise<LinearTeam[]>;
356
+ find(ref: string): Promise<LinearTeam | undefined>;
357
+ automation(teamId: string): Promise<LinearTeamAutomation>;
358
+ updateAutomation(teamId: string, input: {
359
+ autoArchivePeriod?: number;
360
+ autoClosePeriod?: number | null;
361
+ autoCloseStateId?: string;
362
+ }): Promise<LinearTeamAutomation>;
363
+ gitAutomation(teamId: string): Promise<LinearGitAutomationState[]>;
364
+ createGitTargetBranch(input: {
365
+ teamId: string;
366
+ branchPattern: string;
367
+ isRegex?: boolean;
368
+ }): Promise<LinearGitTargetBranch>;
369
+ createGitAutomation(input: {
370
+ teamId: string;
371
+ event: LinearGitEvent;
372
+ stateId: string;
373
+ targetBranchId?: string;
374
+ }): Promise<LinearGitAutomationState>;
375
+ updateGitAutomation(id: string, input: {
376
+ stateId: string;
377
+ }): Promise<LinearGitAutomationState>;
378
+ states(teamId: string): Promise<LinearWorkflowState[]>;
379
+ createState(teamId: string, input: {
380
+ name: string;
381
+ type: LinearStateType;
382
+ color?: string;
383
+ description?: string;
384
+ }): Promise<LinearWorkflowState>;
385
+ labels(teamId?: string): Promise<LinearLabel[]>;
386
+ createLabel(input: {
387
+ name: string;
388
+ color?: string;
389
+ teamId?: string;
390
+ }): Promise<LinearLabel>;
391
+ users(): Promise<LinearUser[]>;
392
+ };
393
+ issues: {
394
+ list(filter?: LinearIssueFilter): Promise<LinearIssue[]>;
395
+ get(ref: string): Promise<LinearIssue>;
396
+ create(input: LinearIssueCreate): Promise<LinearIssue>;
397
+ update(id: string, input: LinearIssueUpdate): Promise<LinearIssue>;
398
+ comments(issueId: string): Promise<LinearComment[]>;
399
+ comment(issueId: string, body: string, createdAt?: string): Promise<LinearComment>;
400
+ relate(issueId: string, relatedIssueId: string, type: "blocks" | "duplicate" | "related"): Promise<void>;
401
+ attach(issueId: string, url: string, title: string): Promise<void>;
402
+ attachmentsForUrl(url: string): Promise<LinearAttachment[]>;
403
+ };
404
+ projects: {
405
+ list(): Promise<LinearProject[]>;
406
+ statuses(): Promise<LinearProjectStatus[]>;
407
+ create(input: {
408
+ name: string;
409
+ teamIds: string[];
410
+ description?: string;
411
+ statusId?: string;
412
+ }): Promise<LinearProject>;
413
+ archive(id: string): Promise<void>;
414
+ unarchive(id: string): Promise<void>;
415
+ };
416
+ };
417
+ /** The client {@link createLinearClient} returns. */
418
+ export type LinearClient = ReturnType<typeof createLinearClient>;
419
+ export type { Connection, LinearAttachment, LinearComment, LinearGitAutomationState, LinearGitEvent, LinearGitTargetBranch, LinearGraphQL, LinearGraphQLConfig, LinearInverseRelation, LinearIssue, LinearIssueCreate, LinearIssueFilter, LinearIssueRef, LinearIssueUpdate, LinearLabel, LinearNamedRef, LinearNodes, LinearPriority, LinearProject, LinearProjectStatus, LinearRelation, LinearStateRef, LinearStateType, LinearTeam, LinearTeamAutomation, LinearTeamRef, LinearUser, LinearWorkflowState };
package/dist/index.mjs ADDED
@@ -0,0 +1,293 @@
1
+ import { ProviderApiError, createRestClient } from "@theholocron/http-client";
2
+ // src/graphql/graphql.ts
3
+ /**
4
+ * Linear answers a failed query with HTTP 200 (or 400) and an `errors` array, so this wrapper turns that into the same
5
+ * `ProviderApiError` the REST clients throw. Linear sends a personal key as the bare `Authorization` value and an
6
+ * OAuth token as `Bearer <token>`.
7
+ */
8
+ function createLinearGraphQL(config) {
9
+ const oauth = config.token.startsWith("lin_oauth_");
10
+ const rest = createRestClient({
11
+ baseUrl: config.baseUrl ?? "https://api.linear.app",
12
+ token: config.token,
13
+ ...oauth ? {} : {
14
+ tokenScheme: "apikey",
15
+ apiKeyHeader: "authorization"
16
+ },
17
+ vendor: "Linear",
18
+ fetch: config.fetch,
19
+ logger: config.logger,
20
+ errors: config.errors
21
+ });
22
+ return { async query(document, variables) {
23
+ const result = await rest.request("/graphql", {
24
+ method: "POST",
25
+ body: {
26
+ query: document,
27
+ variables
28
+ }
29
+ });
30
+ if (result.errors && result.errors.length > 0) throw new ProviderApiError(`Linear GraphQL → ${result.errors.map((e) => e.message).join("; ")}`, 200, result.errors);
31
+ return result.data;
32
+ } };
33
+ }
34
+ /** Reads every page of a connection; `fetchPage` receives the cursor to continue from (`null` for the first). */
35
+ async function paginate(fetchPage) {
36
+ const all = [];
37
+ let after = null;
38
+ for (;;) {
39
+ const page = await fetchPage(after);
40
+ all.push(...page.nodes);
41
+ if (!page.pageInfo.hasNextPage || !page.pageInfo.endCursor) return all;
42
+ after = page.pageInfo.endCursor;
43
+ }
44
+ }
45
+ /** The fields every issue read returns. */
46
+ const ISSUE_FIELDS = `id identifier number title description priority priorityLabel estimate dueDate url
47
+ createdAt updatedAt completedAt canceledAt
48
+ state { id name type } team { id key }
49
+ assignee { id name displayName email }
50
+ labels(first: 50) { nodes { id name } }
51
+ project { id name } parent { id identifier }
52
+ attachments(first: 25) { nodes { url title } }
53
+ relations(first: 50) { nodes { id type relatedIssue { id identifier } } }
54
+ inverseRelations(first: 50) { nodes { id type issue { id identifier state { type } } } }`;
55
+ function toFilter(f) {
56
+ return {
57
+ ...f.teamId ? { team: { id: { eq: f.teamId } } } : {},
58
+ ...f.projectId ? { project: { id: { eq: f.projectId } } } : {},
59
+ ...f.assigneeId ? { assignee: { id: { eq: f.assigneeId } } } : {},
60
+ ...f.openOnly ? { state: { type: { nin: ["completed", "canceled"] } } } : {}
61
+ };
62
+ }
63
+ /** Issues, their comments, relations and attached links. */
64
+ function issues(gql) {
65
+ return {
66
+ /** Issues matching the filter, newest update first; stops at `limit`. */
67
+ async list(filter = {}) {
68
+ const pageSize = Math.min(filter.limit ?? 100, 100);
69
+ const found = [];
70
+ let after = null;
71
+ for (;;) {
72
+ const data = await gql.query(`query($after: String, $first: Int!, $filter: IssueFilter) { issues(first: $first, after: $after, filter: $filter, orderBy: updatedAt) {
73
+ nodes { ${ISSUE_FIELDS} } pageInfo { hasNextPage endCursor } } }`, {
74
+ after,
75
+ first: pageSize,
76
+ filter: toFilter(filter)
77
+ });
78
+ found.push(...data.issues.nodes);
79
+ const { hasNextPage, endCursor } = data.issues.pageInfo;
80
+ if (!hasNextPage || !endCursor || filter.limit !== void 0 && found.length >= filter.limit) return filter.limit === void 0 ? found : found.slice(0, filter.limit);
81
+ after = endCursor;
82
+ }
83
+ },
84
+ /** One issue by `ENG-42` or by id. */
85
+ async get(ref) {
86
+ return (await gql.query(`query($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`, { id: ref })).issue;
87
+ },
88
+ /** Makes an issue. */
89
+ async create(input) {
90
+ return (await gql.query(`mutation($input: IssueCreateInput!) { issueCreate(input: $input) { issue { ${ISSUE_FIELDS} } } }`, { input })).issueCreate.issue;
91
+ },
92
+ /** Changes the fields given and leaves the rest. */
93
+ async update(id, input) {
94
+ return (await gql.query(`mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { issue { ${ISSUE_FIELDS} } } }`, {
95
+ id,
96
+ input
97
+ })).issueUpdate.issue;
98
+ },
99
+ /** Every comment on the issue, oldest first. */
100
+ async comments(issueId) {
101
+ return paginate((after) => gql.query(`query($id: String!, $after: String) { issue(id: $id) { comments(first: 100, after: $after) {
102
+ nodes { id body createdAt user { id name displayName } } pageInfo { hasNextPage endCursor } } } }`, {
103
+ id: issueId,
104
+ after
105
+ }).then((d) => d.issue.comments));
106
+ },
107
+ /** Adds a comment; `createdAt` backdates it. */
108
+ async comment(issueId, body, createdAt) {
109
+ return (await gql.query(`mutation($input: CommentCreateInput!) { commentCreate(input: $input) { comment { id body createdAt user { id name displayName } } } }`, { input: {
110
+ issueId,
111
+ body,
112
+ ...createdAt ? { createdAt } : {}
113
+ } })).commentCreate.comment;
114
+ },
115
+ /** Relates two issues: `blocks` means `issueId` blocks `relatedIssueId`. */
116
+ async relate(issueId, relatedIssueId, type) {
117
+ await gql.query(`mutation($input: IssueRelationCreateInput!) { issueRelationCreate(input: $input) { success } }`, { input: {
118
+ issueId,
119
+ relatedIssueId,
120
+ type
121
+ } });
122
+ },
123
+ /** Attaches a link to the issue. Linear keeps one attachment per issue and url. */
124
+ async attach(issueId, url, title) {
125
+ await gql.query(`mutation($issueId: String!, $url: String!, $title: String) { attachmentLinkURL(issueId: $issueId, url: $url, title: $title) { success } }`, {
126
+ issueId,
127
+ url,
128
+ title
129
+ });
130
+ },
131
+ /** The attachments with exactly this url, which is how a migration finds what it already made. */
132
+ async attachmentsForUrl(url) {
133
+ return (await gql.query(`query($url: String!) { attachmentsForURL(url: $url) { nodes { id url title issue { id identifier } } pageInfo { hasNextPage endCursor } } }`, { url })).attachmentsForURL.nodes;
134
+ }
135
+ };
136
+ }
137
+ // src/projects/projects.ts
138
+ const PROJECT_FIELDS = "id name description url archivedAt status { id name type } teams { nodes { id key } }";
139
+ /** Projects, Linear's boards of work. */
140
+ function projects(gql) {
141
+ return {
142
+ /** Every project, archived ones included. */
143
+ async list() {
144
+ return paginate((after) => gql.query(`query($after: String) { projects(first: 100, after: $after, includeArchived: true) {
145
+ nodes { ${PROJECT_FIELDS} } pageInfo { hasNextPage endCursor } } }`, { after }).then((d) => d.projects));
146
+ },
147
+ /** The project's statuses (Backlog, Planned, In Progress, Completed, Canceled, ...). */
148
+ async statuses() {
149
+ return (await gql.query(`query { projectStatuses(first: 50) { nodes { id name type } pageInfo { hasNextPage endCursor } } }`)).projectStatuses.nodes;
150
+ },
151
+ /** Makes a project for the given teams. */
152
+ async create(input) {
153
+ return (await gql.query(`mutation($input: ProjectCreateInput!) { projectCreate(input: $input) { project { ${PROJECT_FIELDS} } } }`, { input })).projectCreate.project;
154
+ },
155
+ /** Archives the project. Reversible with `unarchive`. */
156
+ async archive(id) {
157
+ await gql.query(`mutation($id: String!) { projectArchive(id: $id) { success } }`, { id });
158
+ },
159
+ /** Brings an archived project back. */
160
+ async unarchive(id) {
161
+ await gql.query(`mutation($id: String!) { projectUnarchive(id: $id) { success } }`, { id });
162
+ }
163
+ };
164
+ }
165
+ // src/teams/teams.ts
166
+ const USER_FIELDS = "id name displayName email";
167
+ /**
168
+ * A team's automation settings as Linear sends them: the close state is an id (`Team` has no `autoCloseState` field,
169
+ * only `autoCloseStateId`), so the team's states come with it to give the id a name.
170
+ */
171
+ const AUTOMATION_FIELDS = "autoArchivePeriod autoClosePeriod autoCloseStateId triageEnabled states(first: 100) { nodes { id name } }";
172
+ /** The public shape of a team's automation: the close state with its name, found among the team's states. */
173
+ function toAutomation({ autoCloseStateId, states, ...rest }) {
174
+ const autoCloseState = autoCloseStateId === null ? null : states.nodes.find((s) => s.id === autoCloseStateId) ?? {
175
+ id: autoCloseStateId,
176
+ name: autoCloseStateId
177
+ };
178
+ return {
179
+ ...rest,
180
+ autoCloseState
181
+ };
182
+ }
183
+ /** Identity, teams, workflow states, labels and automation settings. */
184
+ function teams(gql) {
185
+ return {
186
+ /** The user the token belongs to, and the workspace. */
187
+ async viewer() {
188
+ const data = await gql.query(`query { viewer { ${USER_FIELDS} } organization { id name urlKey } }`);
189
+ return {
190
+ user: data.viewer,
191
+ organization: data.organization
192
+ };
193
+ },
194
+ /** Every team the token can see. */
195
+ async list() {
196
+ return paginate((after) => gql.query(`query($after: String) { teams(first: 100, after: $after) { nodes { id key name } pageInfo { hasNextPage endCursor } } }`, { after }).then((d) => d.teams));
197
+ },
198
+ /** A team by its key (`ENG`), name or id, or undefined. */
199
+ async find(ref) {
200
+ const all = await this.list();
201
+ const lower = ref.toLowerCase();
202
+ return all.find((t) => t.id === ref || t.key.toLowerCase() === lower || t.name.toLowerCase() === lower);
203
+ },
204
+ /** The team's archive and close settings, which are the automation Linear exposes. */
205
+ async automation(teamId) {
206
+ return toAutomation((await gql.query(`query($id: String!) { team(id: $id) { ${AUTOMATION_FIELDS} } }`, { id: teamId })).team);
207
+ },
208
+ /**
209
+ * Changes the team's auto-archive and auto-close settings (`teamUpdate`); a field left out is left alone, a null
210
+ * `autoClosePeriod` switches auto-close off and a 0 `autoArchivePeriod` switches auto-archive off. Needs a key
211
+ * with admin access to the team.
212
+ */
213
+ async updateAutomation(teamId, input) {
214
+ return toAutomation((await gql.query(`mutation($id: String!, $input: TeamUpdateInput!) { teamUpdate(id: $id, input: $input) { team {
215
+ ${AUTOMATION_FIELDS} } } }`, {
216
+ id: teamId,
217
+ input
218
+ })).teamUpdate.team);
219
+ },
220
+ /** The team's git automation rules (`gitAutomationStates`), each with the state and target branch it names. */
221
+ async gitAutomation(teamId) {
222
+ return paginate((after) => gql.query(`query($id: String!, $after: String) { team(id: $id) { gitAutomationStates(first: 100, after: $after) {
223
+ nodes { id event state { id name } targetBranch { id branchPattern isRegex } }
224
+ pageInfo { hasNextPage endCursor } } } }`, {
225
+ id: teamId,
226
+ after
227
+ }).then((d) => d.team.gitAutomationStates));
228
+ },
229
+ /** Makes a target branch for the team (`gitAutomationTargetBranchCreate`); an exact name unless `isRegex`. */
230
+ async createGitTargetBranch(input) {
231
+ return (await gql.query(`mutation($input: GitAutomationTargetBranchCreateInput!) { gitAutomationTargetBranchCreate(input: $input) {
232
+ targetBranch { id branchPattern isRegex } } }`, { input })).gitAutomationTargetBranchCreate.targetBranch;
233
+ },
234
+ /** Makes a git automation rule (`gitAutomationStateCreate`); without `targetBranchId` it applies to all branches. */
235
+ async createGitAutomation(input) {
236
+ return (await gql.query(`mutation($input: GitAutomationStateCreateInput!) { gitAutomationStateCreate(input: $input) {
237
+ gitAutomationState { id event state { id name } targetBranch { id branchPattern isRegex } } } }`, { input })).gitAutomationStateCreate.gitAutomationState;
238
+ },
239
+ /** Points an existing git automation rule at another state (`gitAutomationStateUpdate`). */
240
+ async updateGitAutomation(id, input) {
241
+ return (await gql.query(`mutation($id: String!, $input: GitAutomationStateUpdateInput!) { gitAutomationStateUpdate(id: $id, input: $input) {
242
+ gitAutomationState { id event state { id name } targetBranch { id branchPattern isRegex } } } }`, {
243
+ id,
244
+ input
245
+ })).gitAutomationStateUpdate.gitAutomationState;
246
+ },
247
+ /** The team's issue statuses, in board order. */
248
+ async states(teamId) {
249
+ return (await paginate((after) => gql.query(`query($team: ID!, $after: String) { workflowStates(first: 100, after: $after, filter: { team: { id: { eq: $team } } }) {
250
+ nodes { id name type color description position } pageInfo { hasNextPage endCursor } } }`, {
251
+ team: teamId,
252
+ after
253
+ }).then((d) => d.workflowStates))).sort((a, b) => a.position - b.position);
254
+ },
255
+ /** Adds a status to the team's workflow. */
256
+ async createState(teamId, input) {
257
+ return (await gql.query(`mutation($input: WorkflowStateCreateInput!) { workflowStateCreate(input: $input) {
258
+ workflowState { id name type color description position } } }`, { input: {
259
+ teamId,
260
+ color: "#95a2b3",
261
+ ...input
262
+ } })).workflowStateCreate.workflowState;
263
+ },
264
+ /** Labels of the team and the workspace-wide ones. */
265
+ async labels(teamId) {
266
+ return paginate((after) => gql.query(`query($after: String, $filter: IssueLabelFilter) { issueLabels(first: 100, after: $after, filter: $filter) {
267
+ nodes { id name color team { id } } pageInfo { hasNextPage endCursor } } }`, {
268
+ after,
269
+ filter: teamId ? { or: [{ team: { id: { eq: teamId } } }, { team: { null: true } }] } : void 0
270
+ }).then((d) => d.issueLabels));
271
+ },
272
+ /** Makes a label; without `teamId` it is workspace-wide. */
273
+ async createLabel(input) {
274
+ return (await gql.query(`mutation($input: IssueLabelCreateInput!) { issueLabelCreate(input: $input) { issueLabel { id name color team { id } } } }`, { input })).issueLabelCreate.issueLabel;
275
+ },
276
+ /** Every active member of the workspace. */
277
+ async users() {
278
+ return paginate((after) => gql.query(`query($after: String) { users(first: 100, after: $after) { nodes { ${USER_FIELDS} } pageInfo { hasNextPage endCursor } } }`, { after }).then((d) => d.users));
279
+ }
280
+ };
281
+ }
282
+ // src/index.ts
283
+ /** Creates a Linear client with `teams`, `issues` and `projects` groups and the raw `graphql` handle. */
284
+ function createLinearClient(opts) {
285
+ const graphql = createLinearGraphQL(opts);
286
+ return {
287
+ graphql,
288
+ teams: teams(graphql),
289
+ issues: issues(graphql),
290
+ projects: projects(graphql)
291
+ };
292
+ }
293
+ export { ISSUE_FIELDS, createLinearClient, createLinearGraphQL, paginate };
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "@theholocron/linear-client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.58.0-alpha.24",
4
+ "description": "A TypeScript client for the Linear GraphQL API",
5
+ "keywords": [
6
+ "linear",
7
+ "graphql",
8
+ "issues",
9
+ "typescript",
10
+ "http-client",
11
+ "api"
12
+ ],
13
+ "homepage": "https://docs.theholocron.dev/holocron/clients/linear/",
14
+ "bugs": "https://github.com/theholocron/holocron/issues",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/theholocron/holocron.git",
18
+ "directory": "clients/linear-client"
19
+ },
20
+ "license": "MIT",
21
+ "author": "Newton Koumantzelis",
22
+ "sideEffects": false,
23
+ "type": "module",
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.mts",
27
+ "import": "./dist/index.mjs",
28
+ "default": "./dist/index.mjs"
29
+ }
30
+ },
31
+ "files": [
32
+ "dist"
33
+ ],
34
+ "dependencies": {
35
+ "@theholocron/http-client": "^1.58.0-alpha.24",
36
+ "@theholocron/observability": "^0.7.0-alpha.3"
37
+ },
38
+ "devDependencies": {
39
+ "@types/node": "^26",
40
+ "@vitest/coverage-v8": "^5.1.0",
41
+ "@vitest/eslint-plugin": "^1.6.28",
42
+ "eslint": "^10.14.0",
43
+ "eslint-plugin-n": "^18.5.0",
44
+ "globals": "^17.14.0",
45
+ "tsdown": "^0.23.5",
46
+ "typescript": "^5.9.3",
47
+ "vitest": "^5.1.0",
48
+ "@theholocron/eslint-config": "^8.9.0-alpha.14",
49
+ "@theholocron/tsconfig": "^8.9.0-alpha.14",
50
+ "@theholocron/tsdown-config": "^8.9.0-alpha.14",
51
+ "@theholocron/vitest-config": "^8.9.0-alpha.14"
52
+ },
53
+ "engines": {
54
+ "node": ">=22.0.0"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "scripts": {
60
+ "build": "tsdown && node ../scripts/check-bundle-size.mjs",
61
+ "lint:code": "eslint .",
62
+ "test:unit": "vitest run --coverage",
63
+ "test:watch": "vitest",
64
+ "typecheck": "tsc --noEmit"
65
+ }
6
66
  }