cyrus-core 0.2.1 → 0.2.3
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/dist/CyrusAgentSession.d.ts +4 -4
- package/dist/CyrusAgentSession.d.ts.map +1 -1
- package/dist/config-types.d.ts +3 -0
- package/dist/config-types.d.ts.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -1
- package/dist/index.js.map +1 -1
- package/dist/issue-tracker/AgentEvent.d.ts +134 -0
- package/dist/issue-tracker/AgentEvent.d.ts.map +1 -0
- package/dist/issue-tracker/AgentEvent.js +109 -0
- package/dist/issue-tracker/AgentEvent.js.map +1 -0
- package/dist/issue-tracker/IAgentEventTransport.d.ts +146 -0
- package/dist/issue-tracker/IAgentEventTransport.d.ts.map +1 -0
- package/dist/issue-tracker/IAgentEventTransport.js +12 -0
- package/dist/issue-tracker/IAgentEventTransport.js.map +1 -0
- package/dist/issue-tracker/IIssueTrackerService.d.ts +692 -0
- package/dist/issue-tracker/IIssueTrackerService.d.ts.map +1 -0
- package/dist/issue-tracker/IIssueTrackerService.js +11 -0
- package/dist/issue-tracker/IIssueTrackerService.js.map +1 -0
- package/dist/issue-tracker/index.d.ts +59 -0
- package/dist/issue-tracker/index.d.ts.map +1 -0
- package/dist/issue-tracker/index.js +61 -0
- package/dist/issue-tracker/index.js.map +1 -0
- package/dist/issue-tracker/types.d.ts +499 -0
- package/dist/issue-tracker/types.d.ts.map +1 -0
- package/dist/issue-tracker/types.js +123 -0
- package/dist/issue-tracker/types.js.map +1 -0
- package/package.json +4 -3
- package/dist/webhook-types.d.ts +0 -259
- package/dist/webhook-types.d.ts.map +0 -1
- package/dist/webhook-types.js +0 -26
- package/dist/webhook-types.js.map +0 -1
|
@@ -0,0 +1,692 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Platform-agnostic interface for issue tracking platform operations.
|
|
3
|
+
*
|
|
4
|
+
* This interface provides a unified API for interacting with issue tracking
|
|
5
|
+
* platforms like Linear, GitHub Issues, Jira, etc. It abstracts away platform-specific
|
|
6
|
+
* details while supporting all operations needed for Cyrus agent functionality.
|
|
7
|
+
*
|
|
8
|
+
* @module issue-tracker/IIssueTrackerService
|
|
9
|
+
*/
|
|
10
|
+
import type { AgentSession, AgentSessionPayload, LinearFetch } from "@linear/sdk";
|
|
11
|
+
import type { AgentEventTransportConfig, IAgentEventTransport } from "./IAgentEventTransport.js";
|
|
12
|
+
import type { AgentActivityCreateInput, AgentActivityPayload, AgentSessionCreateOnCommentInput, AgentSessionCreateOnIssueInput, Comment, CommentCreateInput, CommentWithAttachments, Connection, FetchChildrenOptions, FileUploadRequest, FileUploadResponse, Issue, IssueUpdateInput, IssueWithChildren, Label, PaginationOptions, Team, User, WorkflowState } from "./types.js";
|
|
13
|
+
/**
|
|
14
|
+
* Main interface for issue tracking platform operations.
|
|
15
|
+
*
|
|
16
|
+
* Implementations of this interface provide platform-specific logic for Linear,
|
|
17
|
+
* GitHub, or other issue tracking systems while maintaining a consistent API.
|
|
18
|
+
*
|
|
19
|
+
* @remarks
|
|
20
|
+
* This interface follows the Strategy pattern, allowing platform-specific
|
|
21
|
+
* implementations to be swapped at runtime. The interface covers:
|
|
22
|
+
*
|
|
23
|
+
* - **Read Operations**: Fetching issues, comments, teams, labels, workflow states
|
|
24
|
+
* - **Write Operations**: Creating/updating issues, comments, agent sessions, activities
|
|
25
|
+
* - **File Operations**: Uploading files and getting asset URLs
|
|
26
|
+
* - **Raw API Access**: Platform-specific GraphQL or REST API calls
|
|
27
|
+
*
|
|
28
|
+
* ## IMPORTANT: Async Properties in Linear Platform
|
|
29
|
+
*
|
|
30
|
+
* When using the **Linear platform** implementation (`LinearIssueTrackerService`),
|
|
31
|
+
* many returned objects have **async properties** that must be awaited before use.
|
|
32
|
+
* This is a characteristic of the Linear SDK's lazy-loading design.
|
|
33
|
+
*
|
|
34
|
+
* **Common async properties**:
|
|
35
|
+
* - `issue.state`, `issue.assignee`, `issue.team`, `issue.labels()`, `issue.parent`
|
|
36
|
+
* - `comment.user`, `comment.parent`, `comment.issue`
|
|
37
|
+
* - `team.states()`, `team.members()`
|
|
38
|
+
*
|
|
39
|
+
* **Correct usage**:
|
|
40
|
+
* ```typescript
|
|
41
|
+
* const issue = await service.fetchIssue('TEAM-123');
|
|
42
|
+
*
|
|
43
|
+
* // ✅ Correct - await async properties
|
|
44
|
+
* const state = await issue.state;
|
|
45
|
+
* const assignee = await issue.assignee;
|
|
46
|
+
* const team = await issue.team;
|
|
47
|
+
* const labels = await issue.labels();
|
|
48
|
+
*
|
|
49
|
+
* console.log(`Issue ${issue.identifier} is ${state?.name}`);
|
|
50
|
+
* ```
|
|
51
|
+
*
|
|
52
|
+
* **Incorrect usage (common mistake)**:
|
|
53
|
+
* ```typescript
|
|
54
|
+
* const issue = await service.fetchIssue('TEAM-123');
|
|
55
|
+
*
|
|
56
|
+
* // ❌ Wrong - returns Promise, not the actual value
|
|
57
|
+
* const state = issue.state; // This is a Promise!
|
|
58
|
+
* console.log(state.name); // Error: Cannot read property 'name' of Promise
|
|
59
|
+
* ```
|
|
60
|
+
*
|
|
61
|
+
* **Platform differences**:
|
|
62
|
+
* - **Linear Platform**: Properties are async (Promises) - must await
|
|
63
|
+
* - **CLI Platform**: Properties are synchronous - no await needed
|
|
64
|
+
*
|
|
65
|
+
* **Defensive coding pattern**:
|
|
66
|
+
* ```typescript
|
|
67
|
+
* // Check if property is a Promise before awaiting
|
|
68
|
+
* const state = issue.state instanceof Promise
|
|
69
|
+
* ? await issue.state
|
|
70
|
+
* : issue.state;
|
|
71
|
+
* ```
|
|
72
|
+
*
|
|
73
|
+
* See individual method documentation for specific async property warnings.
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* Basic usage:
|
|
77
|
+
* ```typescript
|
|
78
|
+
* const service: IIssueTrackerService = createLinearService(config);
|
|
79
|
+
*
|
|
80
|
+
* // Fetch an issue
|
|
81
|
+
* const issue = await service.fetchIssue('TEAM-123');
|
|
82
|
+
*
|
|
83
|
+
* // Create a comment
|
|
84
|
+
* const comment = await service.createComment(issue.id, {
|
|
85
|
+
* body: 'This is a comment'
|
|
86
|
+
* });
|
|
87
|
+
*
|
|
88
|
+
* // Create an agent session
|
|
89
|
+
* const session = await service.createAgentSessionOnIssue({
|
|
90
|
+
* issueId: issue.id
|
|
91
|
+
* });
|
|
92
|
+
* ```
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* Advanced usage with async properties:
|
|
96
|
+
* ```typescript
|
|
97
|
+
* const issue = await service.fetchIssue('TEAM-123');
|
|
98
|
+
*
|
|
99
|
+
* // Access async properties (Linear platform)
|
|
100
|
+
* const state = await issue.state;
|
|
101
|
+
* const assignee = await issue.assignee;
|
|
102
|
+
* const team = await issue.team;
|
|
103
|
+
*
|
|
104
|
+
* console.log(`Issue ${issue.identifier} is ${state?.name}`);
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
export interface IIssueTrackerService {
|
|
108
|
+
/**
|
|
109
|
+
* Fetch a single issue by ID or identifier.
|
|
110
|
+
*
|
|
111
|
+
* @param idOrIdentifier - Issue ID (UUID) or identifier (e.g., "TEAM-123")
|
|
112
|
+
* @returns Promise resolving to the issue
|
|
113
|
+
* @throws Error if issue not found or request fails
|
|
114
|
+
*
|
|
115
|
+
* @example
|
|
116
|
+
* ```typescript
|
|
117
|
+
* // Fetch by identifier
|
|
118
|
+
* const issue = await service.fetchIssue('TEAM-123');
|
|
119
|
+
*
|
|
120
|
+
* // Fetch by UUID
|
|
121
|
+
* const issue = await service.fetchIssue('550e8400-e29b-41d4-a716-446655440000');
|
|
122
|
+
*
|
|
123
|
+
* // Access async properties (Linear platform)
|
|
124
|
+
* const state = await issue.state;
|
|
125
|
+
* const assignee = await issue.assignee;
|
|
126
|
+
* const team = await issue.team;
|
|
127
|
+
* ```
|
|
128
|
+
*
|
|
129
|
+
* @remarks
|
|
130
|
+
* **Linear Platform Warning**: The returned issue has async properties that must be awaited:
|
|
131
|
+
* - `issue.state`, `issue.assignee`, `issue.team`, `issue.labels()`, `issue.parent`
|
|
132
|
+
*
|
|
133
|
+
* See the main interface documentation for detailed information about async properties.
|
|
134
|
+
*
|
|
135
|
+
* **CLI Platform**: All properties are synchronous (no await needed).
|
|
136
|
+
*/
|
|
137
|
+
fetchIssue(idOrIdentifier: string): Promise<Issue>;
|
|
138
|
+
/**
|
|
139
|
+
* Fetch child issues (sub-issues) for a parent issue.
|
|
140
|
+
*
|
|
141
|
+
* @param issueId - Parent issue ID or identifier
|
|
142
|
+
* @param options - Options for filtering and pagination
|
|
143
|
+
* @returns Promise resolving to issue with children
|
|
144
|
+
* @throws Error if parent issue not found or request fails
|
|
145
|
+
*
|
|
146
|
+
* @example
|
|
147
|
+
* ```typescript
|
|
148
|
+
* // Fetch all children
|
|
149
|
+
* const parent = await service.fetchIssueChildren('TEAM-123');
|
|
150
|
+
* console.log(`Found ${parent.childCount} children`);
|
|
151
|
+
*
|
|
152
|
+
* // Fetch only incomplete children
|
|
153
|
+
* const parent = await service.fetchIssueChildren('TEAM-123', {
|
|
154
|
+
* includeCompleted: false,
|
|
155
|
+
* limit: 50
|
|
156
|
+
* });
|
|
157
|
+
*
|
|
158
|
+
* // Access async properties on parent and children (Linear platform)
|
|
159
|
+
* const parentState = await parent.state;
|
|
160
|
+
* for (const child of parent.children) {
|
|
161
|
+
* const childState = await child.state;
|
|
162
|
+
* console.log(`Child ${child.identifier}: ${childState?.name}`);
|
|
163
|
+
* }
|
|
164
|
+
* ```
|
|
165
|
+
*
|
|
166
|
+
* @remarks
|
|
167
|
+
* Supports filtering by completion status and archive status.
|
|
168
|
+
* Use `limit` to control the number of children returned.
|
|
169
|
+
*
|
|
170
|
+
* **Linear Platform Warning**: The returned parent issue and all child issues
|
|
171
|
+
* have async properties that must be awaited. See `fetchIssue()` documentation for details.
|
|
172
|
+
*/
|
|
173
|
+
fetchIssueChildren(issueId: string, options?: FetchChildrenOptions): Promise<IssueWithChildren>;
|
|
174
|
+
/**
|
|
175
|
+
* Update an issue's properties.
|
|
176
|
+
*
|
|
177
|
+
* @param issueId - Issue ID to update
|
|
178
|
+
* @param updates - Fields to update
|
|
179
|
+
* @returns Promise resolving to the updated issue
|
|
180
|
+
* @throws Error if issue not found or update fails
|
|
181
|
+
*
|
|
182
|
+
* @example
|
|
183
|
+
* ```typescript
|
|
184
|
+
* // Update issue state
|
|
185
|
+
* const updated = await service.updateIssue(issue.id, {
|
|
186
|
+
* stateId: 'started-state-id'
|
|
187
|
+
* });
|
|
188
|
+
*
|
|
189
|
+
* // Update multiple fields
|
|
190
|
+
* const updated = await service.updateIssue(issue.id, {
|
|
191
|
+
* title: 'New title',
|
|
192
|
+
* assigneeId: 'user-id',
|
|
193
|
+
* priority: IssuePriority.High
|
|
194
|
+
* });
|
|
195
|
+
*
|
|
196
|
+
* // Access async properties on returned issue (Linear platform)
|
|
197
|
+
* const state = await updated.state;
|
|
198
|
+
* ```
|
|
199
|
+
*
|
|
200
|
+
* @remarks
|
|
201
|
+
* Only specified fields are updated. Omitted fields remain unchanged.
|
|
202
|
+
*
|
|
203
|
+
* **Linear Platform Warning**: The returned issue has async properties that must be awaited.
|
|
204
|
+
* See `fetchIssue()` documentation for details.
|
|
205
|
+
*/
|
|
206
|
+
updateIssue(issueId: string, updates: IssueUpdateInput): Promise<Issue>;
|
|
207
|
+
/**
|
|
208
|
+
* Fetch attachments for an issue.
|
|
209
|
+
*
|
|
210
|
+
* @param issueId - Issue ID to fetch attachments for
|
|
211
|
+
* @returns Promise resolving to array of attachment metadata
|
|
212
|
+
* @throws Error if issue not found or request fails
|
|
213
|
+
*
|
|
214
|
+
* @example
|
|
215
|
+
* ```typescript
|
|
216
|
+
* const attachments = await service.fetchIssueAttachments(issue.id);
|
|
217
|
+
* for (const attachment of attachments) {
|
|
218
|
+
* console.log(`${attachment.title}: ${attachment.url}`);
|
|
219
|
+
* }
|
|
220
|
+
* ```
|
|
221
|
+
*
|
|
222
|
+
* @remarks
|
|
223
|
+
* Attachments are typically external links (Sentry, Datadog, etc.)
|
|
224
|
+
*/
|
|
225
|
+
fetchIssueAttachments(issueId: string): Promise<Array<{
|
|
226
|
+
title: string;
|
|
227
|
+
url: string;
|
|
228
|
+
}>>;
|
|
229
|
+
/**
|
|
230
|
+
* Fetch comments for an issue with optional pagination.
|
|
231
|
+
*
|
|
232
|
+
* @param issueId - Issue ID to fetch comments for
|
|
233
|
+
* @param options - Pagination options
|
|
234
|
+
* @returns Promise resolving to connection of comments
|
|
235
|
+
* @throws Error if issue not found or request fails
|
|
236
|
+
*
|
|
237
|
+
* @example
|
|
238
|
+
* ```typescript
|
|
239
|
+
* // Fetch first 50 comments
|
|
240
|
+
* const comments = await service.fetchComments(issue.id, { first: 50 });
|
|
241
|
+
*
|
|
242
|
+
* // Fetch next page
|
|
243
|
+
* const nextPage = await service.fetchComments(issue.id, {
|
|
244
|
+
* first: 50,
|
|
245
|
+
* after: comments.pageInfo?.endCursor
|
|
246
|
+
* });
|
|
247
|
+
* ```
|
|
248
|
+
*
|
|
249
|
+
* @remarks
|
|
250
|
+
* Returns a connection object with `nodes` array and pagination info.
|
|
251
|
+
* Use cursor-based pagination with `after` and `before` parameters.
|
|
252
|
+
*/
|
|
253
|
+
fetchComments(issueId: string, options?: PaginationOptions): Promise<Connection<Comment>>;
|
|
254
|
+
/**
|
|
255
|
+
* Fetch a single comment by ID.
|
|
256
|
+
*
|
|
257
|
+
* @param commentId - Comment ID to fetch
|
|
258
|
+
* @returns Promise resolving to the comment
|
|
259
|
+
* @throws Error if comment not found or request fails
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* ```typescript
|
|
263
|
+
* const comment = await service.fetchComment('comment-id');
|
|
264
|
+
* console.log('Comment body:', comment.body);
|
|
265
|
+
*
|
|
266
|
+
* // Access async properties (Linear platform)
|
|
267
|
+
* const user = await comment.user;
|
|
268
|
+
* const parent = await comment.parent;
|
|
269
|
+
* const issue = await comment.issue;
|
|
270
|
+
* ```
|
|
271
|
+
*
|
|
272
|
+
* @remarks
|
|
273
|
+
* **Linear Platform Warning**: The returned comment has async properties that must be awaited:
|
|
274
|
+
* - `comment.user`, `comment.parent`, `comment.issue`
|
|
275
|
+
*
|
|
276
|
+
* See the main interface documentation for detailed information about async properties.
|
|
277
|
+
*
|
|
278
|
+
* **CLI Platform**: All properties are synchronous (no await needed).
|
|
279
|
+
*/
|
|
280
|
+
fetchComment(commentId: string): Promise<Comment>;
|
|
281
|
+
/**
|
|
282
|
+
* Fetch a comment with attachments using raw GraphQL.
|
|
283
|
+
*
|
|
284
|
+
* @param commentId - Comment ID to fetch
|
|
285
|
+
* @returns Promise resolving to comment with attachments
|
|
286
|
+
* @throws Error if comment not found or request fails
|
|
287
|
+
*
|
|
288
|
+
* @example
|
|
289
|
+
* ```typescript
|
|
290
|
+
* const comment = await service.fetchCommentWithAttachments('comment-id');
|
|
291
|
+
* comment.attachments?.forEach(att => {
|
|
292
|
+
* console.log('Attachment:', att.filename, att.url);
|
|
293
|
+
* });
|
|
294
|
+
* ```
|
|
295
|
+
*
|
|
296
|
+
* @remarks
|
|
297
|
+
* **LIMITATION**: This method currently returns an empty `attachments` array
|
|
298
|
+
* for comment attachments on the Linear platform because Linear's GraphQL API
|
|
299
|
+
* does not expose comment attachment metadata through their SDK or documented
|
|
300
|
+
* API endpoints.
|
|
301
|
+
*
|
|
302
|
+
* This is expected behavior, not a bug. Issue attachments (via `fetchIssueAttachments`)
|
|
303
|
+
* work correctly - only comment attachments are unavailable from the Linear API.
|
|
304
|
+
*
|
|
305
|
+
* If you need comment attachments, consider:
|
|
306
|
+
* - Using issue attachments instead
|
|
307
|
+
* - Parsing attachment URLs from comment body markdown
|
|
308
|
+
* - Waiting for Linear to expose this data in their API
|
|
309
|
+
*
|
|
310
|
+
* Other platform implementations may have different limitations.
|
|
311
|
+
*/
|
|
312
|
+
fetchCommentWithAttachments(commentId: string): Promise<CommentWithAttachments>;
|
|
313
|
+
/**
|
|
314
|
+
* Create a comment on an issue.
|
|
315
|
+
*
|
|
316
|
+
* @param issueId - Issue ID to comment on
|
|
317
|
+
* @param input - Comment creation parameters
|
|
318
|
+
* @returns Promise resolving to the created comment
|
|
319
|
+
* @throws Error if issue not found or creation fails
|
|
320
|
+
*
|
|
321
|
+
* @example
|
|
322
|
+
* ```typescript
|
|
323
|
+
* // Create a root comment
|
|
324
|
+
* const comment = await service.createComment(issue.id, {
|
|
325
|
+
* body: 'This is a comment'
|
|
326
|
+
* });
|
|
327
|
+
*
|
|
328
|
+
* // Create a reply comment
|
|
329
|
+
* const reply = await service.createComment(issue.id, {
|
|
330
|
+
* body: 'This is a reply',
|
|
331
|
+
* parentId: comment.id
|
|
332
|
+
* });
|
|
333
|
+
* ```
|
|
334
|
+
*
|
|
335
|
+
* @remarks
|
|
336
|
+
* Use `parentId` to create threaded replies to existing comments.
|
|
337
|
+
*/
|
|
338
|
+
createComment(issueId: string, input: CommentCreateInput): Promise<Comment>;
|
|
339
|
+
/**
|
|
340
|
+
* Fetch all teams in the workspace/organization.
|
|
341
|
+
*
|
|
342
|
+
* @param options - Pagination options
|
|
343
|
+
* @returns Promise resolving to connection of teams
|
|
344
|
+
* @throws Error if request fails
|
|
345
|
+
*
|
|
346
|
+
* @example
|
|
347
|
+
* ```typescript
|
|
348
|
+
* const teams = await service.fetchTeams();
|
|
349
|
+
* teams.nodes.forEach(team => {
|
|
350
|
+
* console.log(`Team ${team.key}: ${team.name}`);
|
|
351
|
+
* });
|
|
352
|
+
* ```
|
|
353
|
+
*
|
|
354
|
+
* @remarks
|
|
355
|
+
* Used for repository routing based on team keys.
|
|
356
|
+
*/
|
|
357
|
+
fetchTeams(options?: PaginationOptions): Promise<Connection<Team>>;
|
|
358
|
+
/**
|
|
359
|
+
* Fetch a single team by ID or key.
|
|
360
|
+
*
|
|
361
|
+
* @param idOrKey - Team ID or key (e.g., "TEAM")
|
|
362
|
+
* @returns Promise resolving to the team
|
|
363
|
+
* @throws Error if team not found or request fails
|
|
364
|
+
*
|
|
365
|
+
* @example
|
|
366
|
+
* ```typescript
|
|
367
|
+
* const team = await service.fetchTeam('TEAM');
|
|
368
|
+
* console.log('Team name:', team.name);
|
|
369
|
+
*
|
|
370
|
+
* // Access async properties (Linear platform)
|
|
371
|
+
* const states = await team.states();
|
|
372
|
+
* const members = await team.members();
|
|
373
|
+
* ```
|
|
374
|
+
*
|
|
375
|
+
* @remarks
|
|
376
|
+
* **Linear Platform Warning**: The returned team has async properties/methods that must be awaited:
|
|
377
|
+
* - `team.states()`, `team.members()`
|
|
378
|
+
*
|
|
379
|
+
* See the main interface documentation for detailed information about async properties.
|
|
380
|
+
*
|
|
381
|
+
* **CLI Platform**: All properties are synchronous (no await needed).
|
|
382
|
+
*/
|
|
383
|
+
fetchTeam(idOrKey: string): Promise<Team>;
|
|
384
|
+
/**
|
|
385
|
+
* Fetch all issue labels in the workspace/organization.
|
|
386
|
+
*
|
|
387
|
+
* @param options - Pagination options
|
|
388
|
+
* @returns Promise resolving to connection of labels
|
|
389
|
+
* @throws Error if request fails
|
|
390
|
+
*
|
|
391
|
+
* @example
|
|
392
|
+
* ```typescript
|
|
393
|
+
* const labels = await service.fetchLabels();
|
|
394
|
+
* labels.nodes.forEach(label => {
|
|
395
|
+
* console.log(`Label: ${label.name} (${label.color})`);
|
|
396
|
+
* });
|
|
397
|
+
* ```
|
|
398
|
+
*
|
|
399
|
+
* @remarks
|
|
400
|
+
* Used for repository routing based on label names.
|
|
401
|
+
*/
|
|
402
|
+
fetchLabels(options?: PaginationOptions): Promise<Connection<Label>>;
|
|
403
|
+
/**
|
|
404
|
+
* Fetch a single label by ID or name.
|
|
405
|
+
*
|
|
406
|
+
* @param idOrName - Label ID or name
|
|
407
|
+
* @returns Promise resolving to the label
|
|
408
|
+
* @throws Error if label not found or request fails
|
|
409
|
+
*
|
|
410
|
+
* @example
|
|
411
|
+
* ```typescript
|
|
412
|
+
* const label = await service.fetchLabel('bug');
|
|
413
|
+
* console.log('Label color:', label.color);
|
|
414
|
+
* ```
|
|
415
|
+
*/
|
|
416
|
+
fetchLabel(idOrName: string): Promise<Label>;
|
|
417
|
+
/**
|
|
418
|
+
* Fetch label names for a specific issue.
|
|
419
|
+
*
|
|
420
|
+
* @param issueId - Issue ID to fetch labels for
|
|
421
|
+
* @returns Promise resolving to array of label names
|
|
422
|
+
* @throws Error if issue not found or request fails
|
|
423
|
+
*
|
|
424
|
+
* @example
|
|
425
|
+
* ```typescript
|
|
426
|
+
* const labels = await service.getIssueLabels('TEAM-123');
|
|
427
|
+
* console.log('Labels:', labels.join(', '));
|
|
428
|
+
* ```
|
|
429
|
+
*
|
|
430
|
+
* @remarks
|
|
431
|
+
* This is a convenience method for fetching just the label names
|
|
432
|
+
* for an issue, commonly used for repository routing.
|
|
433
|
+
*/
|
|
434
|
+
getIssueLabels(issueId: string): Promise<string[]>;
|
|
435
|
+
/**
|
|
436
|
+
* Fetch workflow states for a team.
|
|
437
|
+
*
|
|
438
|
+
* @param teamId - Team ID to fetch states for
|
|
439
|
+
* @param options - Pagination options
|
|
440
|
+
* @returns Promise resolving to connection of workflow states
|
|
441
|
+
* @throws Error if team not found or request fails
|
|
442
|
+
*
|
|
443
|
+
* @example
|
|
444
|
+
* ```typescript
|
|
445
|
+
* const states = await service.fetchWorkflowStates(team.id);
|
|
446
|
+
* const startedState = states.nodes.find(s => s.type === 'started');
|
|
447
|
+
* ```
|
|
448
|
+
*
|
|
449
|
+
* @remarks
|
|
450
|
+
* Used to find specific states like "started" for issue transitions.
|
|
451
|
+
*/
|
|
452
|
+
fetchWorkflowStates(teamId: string, options?: PaginationOptions): Promise<Connection<WorkflowState>>;
|
|
453
|
+
/**
|
|
454
|
+
* Fetch a single workflow state by ID.
|
|
455
|
+
*
|
|
456
|
+
* @param stateId - Workflow state ID
|
|
457
|
+
* @returns Promise resolving to the workflow state
|
|
458
|
+
* @throws Error if state not found or request fails
|
|
459
|
+
*
|
|
460
|
+
* @example
|
|
461
|
+
* ```typescript
|
|
462
|
+
* const state = await service.fetchWorkflowState('state-id');
|
|
463
|
+
* console.log('State:', state.name, state.type);
|
|
464
|
+
* ```
|
|
465
|
+
*/
|
|
466
|
+
fetchWorkflowState(stateId: string): Promise<WorkflowState>;
|
|
467
|
+
/**
|
|
468
|
+
* Fetch a user by ID.
|
|
469
|
+
*
|
|
470
|
+
* @param userId - User ID to fetch
|
|
471
|
+
* @returns Promise resolving to the user
|
|
472
|
+
* @throws Error if user not found or request fails
|
|
473
|
+
*
|
|
474
|
+
* @example
|
|
475
|
+
* ```typescript
|
|
476
|
+
* const user = await service.fetchUser('user-id');
|
|
477
|
+
* console.log('User:', user.name, user.email);
|
|
478
|
+
* ```
|
|
479
|
+
*/
|
|
480
|
+
fetchUser(userId: string): Promise<User>;
|
|
481
|
+
/**
|
|
482
|
+
* Fetch the current authenticated user.
|
|
483
|
+
*
|
|
484
|
+
* @returns Promise resolving to the current user
|
|
485
|
+
* @throws Error if request fails
|
|
486
|
+
*
|
|
487
|
+
* @example
|
|
488
|
+
* ```typescript
|
|
489
|
+
* const me = await service.fetchCurrentUser();
|
|
490
|
+
* console.log('Logged in as:', me.email);
|
|
491
|
+
* ```
|
|
492
|
+
*/
|
|
493
|
+
fetchCurrentUser(): Promise<User>;
|
|
494
|
+
/**
|
|
495
|
+
* Create an agent session on an issue.
|
|
496
|
+
*
|
|
497
|
+
* @param input - Agent session creation parameters
|
|
498
|
+
* @returns Promise resolving to creation response
|
|
499
|
+
* @throws Error if issue not found or creation fails
|
|
500
|
+
*
|
|
501
|
+
* @example
|
|
502
|
+
* ```typescript
|
|
503
|
+
* const result = await service.createAgentSessionOnIssue({
|
|
504
|
+
* issueId: 'TEAM-123',
|
|
505
|
+
* externalLink: 'https://example.com/session/abc'
|
|
506
|
+
* });
|
|
507
|
+
* console.log('Created session:', result.agentSessionId);
|
|
508
|
+
* ```
|
|
509
|
+
*
|
|
510
|
+
* @remarks
|
|
511
|
+
* This creates a tracking session for AI/bot activity on an issue.
|
|
512
|
+
* The session can receive agent activities and user prompts.
|
|
513
|
+
*/
|
|
514
|
+
createAgentSessionOnIssue(input: AgentSessionCreateOnIssueInput): LinearFetch<AgentSessionPayload>;
|
|
515
|
+
/**
|
|
516
|
+
* Create an agent session on a comment thread.
|
|
517
|
+
*
|
|
518
|
+
* @param input - Agent session creation parameters
|
|
519
|
+
* @returns Promise resolving to creation response
|
|
520
|
+
* @throws Error if comment not found or creation fails
|
|
521
|
+
*
|
|
522
|
+
* @example
|
|
523
|
+
* ```typescript
|
|
524
|
+
* const result = await service.createAgentSessionOnComment({
|
|
525
|
+
* commentId: 'comment-id',
|
|
526
|
+
* externalLink: 'https://example.com/session/abc'
|
|
527
|
+
* });
|
|
528
|
+
* console.log('Created session:', result.agentSessionId);
|
|
529
|
+
* ```
|
|
530
|
+
*
|
|
531
|
+
* @remarks
|
|
532
|
+
* The comment must be a root comment (not a reply).
|
|
533
|
+
* This creates a tracking session for AI/bot activity on a comment thread.
|
|
534
|
+
*/
|
|
535
|
+
createAgentSessionOnComment(input: AgentSessionCreateOnCommentInput): LinearFetch<AgentSessionPayload>;
|
|
536
|
+
/**
|
|
537
|
+
* Fetch an agent session by ID.
|
|
538
|
+
*
|
|
539
|
+
* @param sessionId - Agent session ID to fetch
|
|
540
|
+
* @returns Promise resolving to the agent session
|
|
541
|
+
* @throws Error if session not found or request fails
|
|
542
|
+
*
|
|
543
|
+
* @example
|
|
544
|
+
* ```typescript
|
|
545
|
+
* const session = await service.fetchAgentSession('session-id');
|
|
546
|
+
* console.log('Session status:', session.status);
|
|
547
|
+
* ```
|
|
548
|
+
*/
|
|
549
|
+
fetchAgentSession(sessionId: string): LinearFetch<AgentSession>;
|
|
550
|
+
/**
|
|
551
|
+
* Post an agent activity to an agent session.
|
|
552
|
+
*
|
|
553
|
+
* Agent activities represent thoughts, observations, actions, responses,
|
|
554
|
+
* elicitations, and errors during agent execution.
|
|
555
|
+
*
|
|
556
|
+
* Signature matches Linear SDK's createAgentActivity exactly.
|
|
557
|
+
*
|
|
558
|
+
* @param input - Activity creation input (agentSessionId, content, ephemeral, signal, signalMetadata)
|
|
559
|
+
* @returns Promise resolving to the activity payload (success, agentActivity)
|
|
560
|
+
* @throws Error if session not found or creation fails
|
|
561
|
+
*
|
|
562
|
+
* @example
|
|
563
|
+
* ```typescript
|
|
564
|
+
* // Post a thought activity
|
|
565
|
+
* await service.createAgentActivity({
|
|
566
|
+
* agentSessionId: sessionId,
|
|
567
|
+
* content: {
|
|
568
|
+
* type: AgentActivityContentType.Thought,
|
|
569
|
+
* body: 'I need to analyze the issue requirements'
|
|
570
|
+
* }
|
|
571
|
+
* });
|
|
572
|
+
*
|
|
573
|
+
* // Post an ephemeral action activity (will be replaced by next activity)
|
|
574
|
+
* await service.createAgentActivity({
|
|
575
|
+
* agentSessionId: sessionId,
|
|
576
|
+
* content: {
|
|
577
|
+
* type: AgentActivityContentType.Action,
|
|
578
|
+
* body: 'Running tests to verify the fix'
|
|
579
|
+
* },
|
|
580
|
+
* ephemeral: true
|
|
581
|
+
* });
|
|
582
|
+
*
|
|
583
|
+
* // Post a response activity with signal
|
|
584
|
+
* await service.createAgentActivity({
|
|
585
|
+
* agentSessionId: sessionId,
|
|
586
|
+
* content: {
|
|
587
|
+
* type: AgentActivityContentType.Response,
|
|
588
|
+
* body: 'I have completed the requested changes'
|
|
589
|
+
* },
|
|
590
|
+
* signal: AgentActivitySignal.Stop
|
|
591
|
+
* });
|
|
592
|
+
* ```
|
|
593
|
+
*
|
|
594
|
+
* @remarks
|
|
595
|
+
* This is the primary method for posting agent updates to Linear.
|
|
596
|
+
* Activities are visible in the Linear UI as part of the agent session.
|
|
597
|
+
* Ephemeral activities disappear when replaced by the next activity.
|
|
598
|
+
*/
|
|
599
|
+
createAgentActivity(input: AgentActivityCreateInput): Promise<AgentActivityPayload>;
|
|
600
|
+
/**
|
|
601
|
+
* Request a file upload URL from the platform.
|
|
602
|
+
*
|
|
603
|
+
* @param request - File upload request parameters
|
|
604
|
+
* @returns Promise resolving to upload URL and asset URL
|
|
605
|
+
* @throws Error if request fails
|
|
606
|
+
*
|
|
607
|
+
* @example
|
|
608
|
+
* ```typescript
|
|
609
|
+
* // Request upload for an image
|
|
610
|
+
* const upload = await service.requestFileUpload({
|
|
611
|
+
* contentType: 'image/png',
|
|
612
|
+
* filename: 'screenshot.png',
|
|
613
|
+
* size: 1024000,
|
|
614
|
+
* makePublic: false
|
|
615
|
+
* });
|
|
616
|
+
*
|
|
617
|
+
* // Upload the file to the upload URL
|
|
618
|
+
* await fetch(upload.uploadUrl, {
|
|
619
|
+
* method: 'PUT',
|
|
620
|
+
* headers: upload.headers,
|
|
621
|
+
* body: fileBuffer
|
|
622
|
+
* });
|
|
623
|
+
*
|
|
624
|
+
* // Use the asset URL in content
|
|
625
|
+
* const comment = await service.createComment(issue.id, {
|
|
626
|
+
* body: `Screenshot: ${upload.assetUrl}`
|
|
627
|
+
* });
|
|
628
|
+
* ```
|
|
629
|
+
*
|
|
630
|
+
* @remarks
|
|
631
|
+
* This follows a two-step upload process:
|
|
632
|
+
* 1. Request upload URL from platform
|
|
633
|
+
* 2. Upload file to cloud storage using provided URL
|
|
634
|
+
* 3. Reference file using asset URL in content
|
|
635
|
+
*/
|
|
636
|
+
requestFileUpload(request: FileUploadRequest): Promise<FileUploadResponse>;
|
|
637
|
+
/**
|
|
638
|
+
* Get the platform type identifier.
|
|
639
|
+
*
|
|
640
|
+
* @returns Platform type (e.g., "linear", "github")
|
|
641
|
+
*
|
|
642
|
+
* @example
|
|
643
|
+
* ```typescript
|
|
644
|
+
* const platform = service.getPlatformType();
|
|
645
|
+
* console.log('Using platform:', platform);
|
|
646
|
+
* ```
|
|
647
|
+
*/
|
|
648
|
+
getPlatformType(): string;
|
|
649
|
+
/**
|
|
650
|
+
* Get the platform's API version or other metadata.
|
|
651
|
+
*
|
|
652
|
+
* @returns Platform metadata
|
|
653
|
+
*
|
|
654
|
+
* @example
|
|
655
|
+
* ```typescript
|
|
656
|
+
* const metadata = service.getPlatformMetadata();
|
|
657
|
+
* console.log('API version:', metadata.apiVersion);
|
|
658
|
+
* ```
|
|
659
|
+
*/
|
|
660
|
+
getPlatformMetadata(): Record<string, unknown>;
|
|
661
|
+
/**
|
|
662
|
+
* Create an event transport for receiving webhook events.
|
|
663
|
+
*
|
|
664
|
+
* This factory method creates a platform-specific transport that handles
|
|
665
|
+
* HTTP endpoints, authentication, and event delivery. The transport abstracts
|
|
666
|
+
* away platform-specific details like webhook signature verification.
|
|
667
|
+
*
|
|
668
|
+
* @param config - Transport configuration
|
|
669
|
+
* @returns Platform-specific event transport implementation
|
|
670
|
+
*
|
|
671
|
+
* @example
|
|
672
|
+
* ```typescript
|
|
673
|
+
* const transport = issueTracker.createEventTransport({
|
|
674
|
+
* fastifyServer: server.getFastifyInstance(),
|
|
675
|
+
* verificationMode: 'proxy',
|
|
676
|
+
* secret: process.env.CYRUS_API_KEY
|
|
677
|
+
* });
|
|
678
|
+
*
|
|
679
|
+
* // Register HTTP endpoints
|
|
680
|
+
* transport.register();
|
|
681
|
+
*
|
|
682
|
+
* // Listen for events
|
|
683
|
+
* transport.on('event', (event: AgentEvent) => {
|
|
684
|
+
* if (isAgentSessionCreatedEvent(event)) {
|
|
685
|
+
* console.log('Session created:', event.agentSession.id);
|
|
686
|
+
* }
|
|
687
|
+
* });
|
|
688
|
+
* ```
|
|
689
|
+
*/
|
|
690
|
+
createEventTransport(config: AgentEventTransportConfig): IAgentEventTransport;
|
|
691
|
+
}
|
|
692
|
+
//# sourceMappingURL=IIssueTrackerService.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"IIssueTrackerService.d.ts","sourceRoot":"","sources":["../../src/issue-tracker/IIssueTrackerService.ts"],"names":[],"mappings":"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"}
|