@superdurable/connector-linear 0.0.0-stage → 0.1.1

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 Super Durable
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,17 @@
1
- # Temporary Holding Version
1
+ # Linear TypeScript connector
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
+ `@superdurable/connector-linear` provides the seven Linear GraphQL operations declared in `connector.yaml` for Dex TypeScript Flows: `searchIssues`, `getIssue`, `createIssue`, `updateIssue`, `addComment`, `findUserByEmail`, and `listWorkflowStates`. The signed `issueEventReceived` webhook Trigger remains Go only.
4
+
5
+ Install with `npm install @superdurable/connector-linear@0.1.1`. The package requires `@superdurable/connectors-sdk@0.5.0` and Node.js 22 or 24. Generated models, Step factories, mock outcomes, OAuth refresh declarations, and credential decoders are under `src/generated/`; edit the manifest or Go source and rerun `connectorctl generate` instead of editing those files.
6
+
7
+ ## Connection and example
8
+
9
+ Create a Linear personal API key at <https://linear.app/settings/account/security> under **Personal API keys > New API key**, or configure a Linear OAuth application at <https://linear.app/settings/api/applications/new>. In Dex Web **Connections**, follow the manifest's authorization guide, select the static connection name `linear-issue-search`, and leave the optional configuration fields blank for their displayed defaults. OAuth refresh, rotating refresh token storage, and reauthorization use the generated manifest refresh declaration. The personal key is sent as a raw `Authorization` header; OAuth uses `Bearer`.
10
+
11
+ The runnable [issue search example](examples/issue-search/README.md) opens `newProjectConnection(project, ConnectionName)` in [main.ts](examples/issue-search/main.ts), binds `newSearchIssuesStep`, persists the page, and completes. Only its happy `searched` branch is wired. Other optional branches fail the Flow. The same package exports typed factories and `newConnection` for applications that supply a client directly.
12
+
13
+ ## Provider and retry behavior
14
+
15
+ Queries use bounded named GraphQL documents and classify HTTP 429 or 5xx as Retry. Writes use the Dex Call ID to derive stable client UUIDs for creates and comments; updates set absolute values. Create and comment operations read back by those IDs after an ambiguous answer. A conclusive provider rejection chooses its optional branch. Credentials, provider response text, and OAuth refresh tokens never enter Flow state or receipts.
16
+
17
+ Run `npm ci && npm run check` for the TypeScript package, then `make test-connector-conformance CONNECTOR_DIRECTORY=connectors/linear` from the repository root for Go-recorded provider replay. For the real Dex integration test, start `dexcli dev` and set `DEX_FLOW_SERVICE_ADDRESS` before `npm run test:integration`. The provider stand-in listens on an OS-assigned port. Live Linear workspace authorization, issue writes, token refresh, and webhook delivery have not been verified by this TypeScript package.
@@ -0,0 +1,574 @@
1
+ {
2
+ "connectorId": "linear",
3
+ "releaseTag": "connectors/linear/go/v0.24.1",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-linear",
7
+ "version": "0.1.1"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newSearchIssuesStep",
12
+ "kind": "query",
13
+ "operationId": "searchIssues",
14
+ "inputType": "SearchIssuesInput",
15
+ "description": "List one bounded page of issue summaries that match a typed filter, such as a team, workflow state types, an assignee email, labels, a title, or changes after a time, continuing with Linear's pagination cursor.",
16
+ "fields": {
17
+ "stepType": "stepType",
18
+ "annotations": "annotations",
19
+ "connectionName": "connectionName",
20
+ "resultAttribute": "resultAttribute"
21
+ },
22
+ "branches": [
23
+ {
24
+ "id": "searched",
25
+ "field": "searched",
26
+ "optional": false
27
+ },
28
+ {
29
+ "id": "providerRejected",
30
+ "field": "providerRejected",
31
+ "optional": true
32
+ },
33
+ {
34
+ "id": "invalidResponse",
35
+ "field": "invalidResponse",
36
+ "optional": true
37
+ },
38
+ {
39
+ "id": "defect",
40
+ "field": "defect",
41
+ "optional": true
42
+ }
43
+ ],
44
+ "inputSchema": {
45
+ "$defs": {
46
+ "IssueSearchFilter": {
47
+ "additionalProperties": false,
48
+ "description": "IssueSearchFilter selects issues; every set field must match, and an empty filter matches every issue the connection can see. Lists match any of their values.",
49
+ "properties": {
50
+ "assigneeEmail": {
51
+ "description": "AssigneeEmail keeps issues assigned to the user with this email, compared without case.",
52
+ "type": "string"
53
+ },
54
+ "assigneeId": {
55
+ "description": "AssigneeID keeps issues assigned to this user UUID.",
56
+ "type": "string"
57
+ },
58
+ "createdAfter": {
59
+ "description": "CreatedAfter keeps issues created strictly after this time.",
60
+ "format": "date-time",
61
+ "type": [
62
+ "string",
63
+ "null"
64
+ ]
65
+ },
66
+ "labelIds": {
67
+ "description": "LabelIDs keeps issues that carry at least one of these labels.",
68
+ "items": {
69
+ "type": "string"
70
+ },
71
+ "type": "array"
72
+ },
73
+ "labelNames": {
74
+ "description": "LabelNames keeps issues that carry a label with one of these exact names, such as Bug.",
75
+ "items": {
76
+ "type": "string"
77
+ },
78
+ "type": "array"
79
+ },
80
+ "projectId": {
81
+ "description": "ProjectID keeps issues of this project UUID.",
82
+ "type": "string"
83
+ },
84
+ "stateIds": {
85
+ "description": "StateIDs keeps issues in one of these workflow states.",
86
+ "items": {
87
+ "type": "string"
88
+ },
89
+ "type": "array"
90
+ },
91
+ "stateTypes": {
92
+ "description": "StateTypes keeps issues whose workflow state has one of these types, such as started.",
93
+ "items": {
94
+ "enum": [
95
+ "backlog",
96
+ "canceled",
97
+ "completed",
98
+ "duplicate",
99
+ "started",
100
+ "triage",
101
+ "unstarted"
102
+ ],
103
+ "type": "string"
104
+ },
105
+ "type": "array"
106
+ },
107
+ "teamId": {
108
+ "description": "TeamID limits the search to one team's UUID, such as the teamPicker unit's teamId.",
109
+ "type": "string"
110
+ },
111
+ "teamKey": {
112
+ "description": "TeamKey limits the search to the team with this key, such as ENG; set at most one of TeamID and TeamKey.",
113
+ "type": "string"
114
+ },
115
+ "title": {
116
+ "description": "Title keeps issues whose title is exactly this text.",
117
+ "type": "string"
118
+ },
119
+ "titleContains": {
120
+ "description": "TitleContains keeps issues whose title contains this text, compared without case.",
121
+ "type": "string"
122
+ },
123
+ "unassigned": {
124
+ "description": "IsUnassigned keeps only unassigned issues; it excludes AssigneeID and AssigneeEmail.",
125
+ "type": "boolean"
126
+ },
127
+ "updatedAfter": {
128
+ "description": "UpdatedAfter keeps issues changed strictly after this time; it is the changed-since watermark.",
129
+ "format": "date-time",
130
+ "type": [
131
+ "string",
132
+ "null"
133
+ ]
134
+ }
135
+ },
136
+ "type": "object"
137
+ }
138
+ },
139
+ "additionalProperties": false,
140
+ "description": "SearchIssuesInput requests one page. A later page repeats the same Filter, Order, and IncludesArchived with the previous page's NextCursor.",
141
+ "properties": {
142
+ "cursor": {
143
+ "description": "Cursor continues after a previous page's NextCursor; blank reads the first page.",
144
+ "type": "string"
145
+ },
146
+ "filter": {
147
+ "$ref": "#/$defs/IssueSearchFilter",
148
+ "description": "Filter selects the issues."
149
+ },
150
+ "includesArchived": {
151
+ "description": "IncludesArchived also returns archived issues.",
152
+ "type": "boolean"
153
+ },
154
+ "order": {
155
+ "description": "Order is createdAt or updatedAt; blank uses createdAt.",
156
+ "enum": [
157
+ "createdAt",
158
+ "updatedAt"
159
+ ],
160
+ "type": "string"
161
+ },
162
+ "pageSize": {
163
+ "description": "PageSize is 1 to MaxSearchPageSize; zero requests DefaultSearchPageSize.",
164
+ "type": "integer"
165
+ }
166
+ },
167
+ "required": [
168
+ "filter"
169
+ ],
170
+ "type": "object"
171
+ }
172
+ },
173
+ {
174
+ "name": "newGetIssueStep",
175
+ "kind": "query",
176
+ "operationId": "getIssue",
177
+ "inputType": "GetIssueInput",
178
+ "description": "Read one issue by UUID or identifier, such as ENG-123, with its description, workflow state, team, assignee, labels, project, cycle, and timestamps.",
179
+ "fields": {
180
+ "stepType": "stepType",
181
+ "annotations": "annotations",
182
+ "connectionName": "connectionName",
183
+ "resultAttribute": "resultAttribute"
184
+ },
185
+ "branches": [
186
+ {
187
+ "id": "found",
188
+ "field": "found",
189
+ "optional": false
190
+ },
191
+ {
192
+ "id": "notFound",
193
+ "field": "notFound",
194
+ "optional": true
195
+ },
196
+ {
197
+ "id": "providerRejected",
198
+ "field": "providerRejected",
199
+ "optional": true
200
+ },
201
+ {
202
+ "id": "invalidResponse",
203
+ "field": "invalidResponse",
204
+ "optional": true
205
+ },
206
+ {
207
+ "id": "defect",
208
+ "field": "defect",
209
+ "optional": true
210
+ }
211
+ ],
212
+ "inputSchema": {
213
+ "additionalProperties": false,
214
+ "description": "GetIssueInput names the issue to read.",
215
+ "properties": {
216
+ "issueId": {
217
+ "description": "IssueID is the issue's UUID or its identifier, such as ENG-123. An identifier finds the issue only under its current team key; after a move to another team, use the UUID.",
218
+ "type": "string"
219
+ }
220
+ },
221
+ "required": [
222
+ "issueId"
223
+ ],
224
+ "type": "object"
225
+ }
226
+ },
227
+ {
228
+ "name": "newCreateIssueStep",
229
+ "kind": "mutation",
230
+ "operationId": "createIssue",
231
+ "inputType": "CreateIssueInput",
232
+ "description": "Create one issue in a team with a title, Markdown description, workflow state, assignee, labels, priority, and due date; every attempt of the Step sends the same client-supplied issue UUID, so a repeated dispatch finds the first issue instead of creating another.",
233
+ "fields": {
234
+ "stepType": "stepType",
235
+ "annotations": "annotations",
236
+ "connectionName": "connectionName",
237
+ "resultAttribute": "resultAttribute"
238
+ },
239
+ "branches": [
240
+ {
241
+ "id": "created",
242
+ "field": "created",
243
+ "optional": false
244
+ },
245
+ {
246
+ "id": "providerRejected",
247
+ "field": "providerRejected",
248
+ "optional": true
249
+ },
250
+ {
251
+ "id": "defect",
252
+ "field": "defect",
253
+ "optional": true
254
+ }
255
+ ],
256
+ "inputSchema": {
257
+ "additionalProperties": false,
258
+ "description": "CreateIssueInput describes one new issue.",
259
+ "properties": {
260
+ "assigneeId": {
261
+ "description": "AssigneeID is the assignee's user UUID from findUserByEmail; blank leaves the issue unassigned.",
262
+ "type": "string"
263
+ },
264
+ "description": {
265
+ "description": "Description is optional Markdown of at most MaxMarkdownCharacters characters.",
266
+ "type": "string"
267
+ },
268
+ "dueDate": {
269
+ "description": "DueDate is an optional YYYY-MM-DD date.",
270
+ "type": "string"
271
+ },
272
+ "labelIds": {
273
+ "description": "LabelIDs are up to MaxLabelIDs label UUIDs of the team or workspace.",
274
+ "items": {
275
+ "type": "string"
276
+ },
277
+ "type": "array"
278
+ },
279
+ "parentId": {
280
+ "description": "ParentID makes the issue a sub-issue of this issue UUID or identifier, such as ENG-123.",
281
+ "type": "string"
282
+ },
283
+ "priority": {
284
+ "description": "Priority is 0 (none), 1 (urgent), 2 (high), 3 (medium), or 4 (low); nil leaves Linear's default.",
285
+ "type": "integer"
286
+ },
287
+ "projectId": {
288
+ "description": "ProjectID is an optional project UUID.",
289
+ "type": "string"
290
+ },
291
+ "stateId": {
292
+ "description": "StateID is a workflow state of the team from listWorkflowStates; blank uses the team's default state.",
293
+ "type": "string"
294
+ },
295
+ "teamId": {
296
+ "description": "TeamID is the UUID of the team that owns the issue, such as the teamPicker unit's teamId.",
297
+ "type": "string"
298
+ },
299
+ "title": {
300
+ "description": "Title is the issue title, 1 to MaxIssueTitleCharacters characters on one line.",
301
+ "type": "string"
302
+ }
303
+ },
304
+ "required": [
305
+ "teamId",
306
+ "title"
307
+ ],
308
+ "type": "object"
309
+ }
310
+ },
311
+ {
312
+ "name": "newUpdateIssueStep",
313
+ "kind": "mutation",
314
+ "operationId": "updateIssue",
315
+ "inputType": "UpdateIssueInput",
316
+ "description": "Move one issue to a workflow state, assign or unassign it, add or remove labels, and set its priority, due date, or title with absolute values, so a repeated update leaves the issue unchanged.",
317
+ "fields": {
318
+ "stepType": "stepType",
319
+ "annotations": "annotations",
320
+ "connectionName": "connectionName",
321
+ "resultAttribute": "resultAttribute"
322
+ },
323
+ "branches": [
324
+ {
325
+ "id": "updated",
326
+ "field": "updated",
327
+ "optional": false
328
+ },
329
+ {
330
+ "id": "notFound",
331
+ "field": "notFound",
332
+ "optional": true
333
+ },
334
+ {
335
+ "id": "providerRejected",
336
+ "field": "providerRejected",
337
+ "optional": true
338
+ },
339
+ {
340
+ "id": "invalidResponse",
341
+ "field": "invalidResponse",
342
+ "optional": true
343
+ },
344
+ {
345
+ "id": "defect",
346
+ "field": "defect",
347
+ "optional": true
348
+ }
349
+ ],
350
+ "inputSchema": {
351
+ "additionalProperties": false,
352
+ "description": "UpdateIssueInput changes one issue. Every field is optional, but at least one change is required. Values are absolute and labels are added or removed as sets, so repeating the update changes nothing.",
353
+ "properties": {
354
+ "addedLabelIds": {
355
+ "description": "AddedLabelIDs adds these label UUIDs and keeps the issue's other labels.",
356
+ "items": {
357
+ "type": "string"
358
+ },
359
+ "type": "array"
360
+ },
361
+ "assigneeId": {
362
+ "description": "AssigneeID assigns the issue to this user UUID, from findUserByEmail.",
363
+ "type": "string"
364
+ },
365
+ "clearsDueDate": {
366
+ "description": "ClearsDueDate removes the due date; it excludes DueDate.",
367
+ "type": "boolean"
368
+ },
369
+ "dueDate": {
370
+ "description": "DueDate sets a YYYY-MM-DD due date; blank keeps it.",
371
+ "type": "string"
372
+ },
373
+ "issueId": {
374
+ "description": "IssueID is the issue's UUID or its identifier, such as ENG-123.",
375
+ "type": "string"
376
+ },
377
+ "priority": {
378
+ "description": "Priority sets 0 (none), 1 (urgent), 2 (high), 3 (medium), or 4 (low); nil keeps it.",
379
+ "type": "integer"
380
+ },
381
+ "removedLabelIds": {
382
+ "description": "RemovedLabelIDs removes these label UUIDs; it cannot repeat an added label.",
383
+ "items": {
384
+ "type": "string"
385
+ },
386
+ "type": "array"
387
+ },
388
+ "stateId": {
389
+ "description": "StateID moves the issue to this workflow state of its team, from listWorkflowStates.",
390
+ "type": "string"
391
+ },
392
+ "title": {
393
+ "description": "Title replaces the title with 1 to MaxIssueTitleCharacters characters on one line; blank keeps it.",
394
+ "type": "string"
395
+ },
396
+ "unassigns": {
397
+ "description": "Unassigns removes the assignee; it excludes AssigneeID.",
398
+ "type": "boolean"
399
+ }
400
+ },
401
+ "required": [
402
+ "issueId"
403
+ ],
404
+ "type": "object"
405
+ }
406
+ },
407
+ {
408
+ "name": "newAddCommentStep",
409
+ "kind": "mutation",
410
+ "operationId": "addComment",
411
+ "inputType": "AddCommentInput",
412
+ "description": "Add one Markdown comment to an issue; every attempt of the Step sends the same client-supplied comment UUID, so a repeated dispatch finds the first comment instead of posting another.",
413
+ "fields": {
414
+ "stepType": "stepType",
415
+ "annotations": "annotations",
416
+ "connectionName": "connectionName",
417
+ "resultAttribute": "resultAttribute"
418
+ },
419
+ "branches": [
420
+ {
421
+ "id": "added",
422
+ "field": "added",
423
+ "optional": false
424
+ },
425
+ {
426
+ "id": "notFound",
427
+ "field": "notFound",
428
+ "optional": true
429
+ },
430
+ {
431
+ "id": "providerRejected",
432
+ "field": "providerRejected",
433
+ "optional": true
434
+ },
435
+ {
436
+ "id": "defect",
437
+ "field": "defect",
438
+ "optional": true
439
+ }
440
+ ],
441
+ "inputSchema": {
442
+ "additionalProperties": false,
443
+ "description": "AddCommentInput describes one comment.",
444
+ "properties": {
445
+ "body": {
446
+ "description": "Body is the comment's Markdown, 1 to MaxMarkdownCharacters characters.",
447
+ "type": "string"
448
+ },
449
+ "issueId": {
450
+ "description": "IssueID is the issue's UUID or its identifier, such as ENG-123.",
451
+ "type": "string"
452
+ }
453
+ },
454
+ "required": [
455
+ "body",
456
+ "issueId"
457
+ ],
458
+ "type": "object"
459
+ }
460
+ },
461
+ {
462
+ "name": "newFindUserByEmailStep",
463
+ "kind": "query",
464
+ "operationId": "findUserByEmail",
465
+ "inputType": "FindUserByEmailInput",
466
+ "description": "Find the workspace user with an email address, compared without case, to resolve an assignee.",
467
+ "fields": {
468
+ "stepType": "stepType",
469
+ "annotations": "annotations",
470
+ "connectionName": "connectionName",
471
+ "resultAttribute": "resultAttribute"
472
+ },
473
+ "branches": [
474
+ {
475
+ "id": "found",
476
+ "field": "found",
477
+ "optional": false
478
+ },
479
+ {
480
+ "id": "notFound",
481
+ "field": "notFound",
482
+ "optional": true
483
+ },
484
+ {
485
+ "id": "providerRejected",
486
+ "field": "providerRejected",
487
+ "optional": true
488
+ },
489
+ {
490
+ "id": "invalidResponse",
491
+ "field": "invalidResponse",
492
+ "optional": true
493
+ },
494
+ {
495
+ "id": "defect",
496
+ "field": "defect",
497
+ "optional": true
498
+ }
499
+ ],
500
+ "inputSchema": {
501
+ "additionalProperties": false,
502
+ "description": "FindUserByEmailInput names the email address to resolve.",
503
+ "properties": {
504
+ "email": {
505
+ "description": "Email is the user's address, such as alice@example.com, compared without case.",
506
+ "type": "string"
507
+ },
508
+ "includesDisabled": {
509
+ "description": "IncludesDisabled also finds a suspended or deactivated user; false finds only active users.",
510
+ "type": "boolean"
511
+ }
512
+ },
513
+ "required": [
514
+ "email"
515
+ ],
516
+ "type": "object"
517
+ }
518
+ },
519
+ {
520
+ "name": "newListWorkflowStatesStep",
521
+ "kind": "query",
522
+ "operationId": "listWorkflowStates",
523
+ "inputType": "ListWorkflowStatesInput",
524
+ "description": "List a team's workflow states, Linear's issue statuses, with their names and types such as backlog, unstarted, started, completed, and canceled, so a Flow can choose the state to move an issue to.",
525
+ "fields": {
526
+ "stepType": "stepType",
527
+ "annotations": "annotations",
528
+ "connectionName": "connectionName",
529
+ "resultAttribute": "resultAttribute"
530
+ },
531
+ "branches": [
532
+ {
533
+ "id": "listed",
534
+ "field": "listed",
535
+ "optional": false
536
+ },
537
+ {
538
+ "id": "notFound",
539
+ "field": "notFound",
540
+ "optional": true
541
+ },
542
+ {
543
+ "id": "providerRejected",
544
+ "field": "providerRejected",
545
+ "optional": true
546
+ },
547
+ {
548
+ "id": "invalidResponse",
549
+ "field": "invalidResponse",
550
+ "optional": true
551
+ },
552
+ {
553
+ "id": "defect",
554
+ "field": "defect",
555
+ "optional": true
556
+ }
557
+ ],
558
+ "inputSchema": {
559
+ "additionalProperties": false,
560
+ "description": "ListWorkflowStatesInput names the team whose workflow states to list.",
561
+ "properties": {
562
+ "teamId": {
563
+ "description": "TeamID is the team's UUID, such as the teamPicker unit's teamId.",
564
+ "type": "string"
565
+ }
566
+ },
567
+ "required": [
568
+ "teamId"
569
+ ],
570
+ "type": "object"
571
+ }
572
+ }
573
+ ]
574
+ }