cyrus-core 0.2.2 → 0.2.4

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.
Files changed (46) hide show
  1. package/dist/CyrusAgentSession.d.ts +11 -8
  2. package/dist/CyrusAgentSession.d.ts.map +1 -1
  3. package/dist/CyrusAgentSession.js +1 -1
  4. package/dist/StreamingPrompt.d.ts +21 -0
  5. package/dist/StreamingPrompt.d.ts.map +1 -0
  6. package/dist/StreamingPrompt.js +76 -0
  7. package/dist/StreamingPrompt.js.map +1 -0
  8. package/dist/agent-runner-types.d.ts +324 -0
  9. package/dist/agent-runner-types.d.ts.map +1 -0
  10. package/dist/agent-runner-types.js +2 -0
  11. package/dist/agent-runner-types.js.map +1 -0
  12. package/dist/config-types.d.ts +4 -1
  13. package/dist/config-types.d.ts.map +1 -1
  14. package/dist/index.d.ts +5 -2
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +5 -1
  17. package/dist/index.js.map +1 -1
  18. package/dist/issue-tracker/AgentEvent.d.ts +134 -0
  19. package/dist/issue-tracker/AgentEvent.d.ts.map +1 -0
  20. package/dist/issue-tracker/AgentEvent.js +109 -0
  21. package/dist/issue-tracker/AgentEvent.js.map +1 -0
  22. package/dist/issue-tracker/IAgentEventTransport.d.ts +146 -0
  23. package/dist/issue-tracker/IAgentEventTransport.d.ts.map +1 -0
  24. package/dist/issue-tracker/IAgentEventTransport.js +12 -0
  25. package/dist/issue-tracker/IAgentEventTransport.js.map +1 -0
  26. package/dist/issue-tracker/IIssueTrackerService.d.ts +692 -0
  27. package/dist/issue-tracker/IIssueTrackerService.d.ts.map +1 -0
  28. package/dist/issue-tracker/IIssueTrackerService.js +11 -0
  29. package/dist/issue-tracker/IIssueTrackerService.js.map +1 -0
  30. package/dist/issue-tracker/index.d.ts +59 -0
  31. package/dist/issue-tracker/index.d.ts.map +1 -0
  32. package/dist/issue-tracker/index.js +61 -0
  33. package/dist/issue-tracker/index.js.map +1 -0
  34. package/dist/issue-tracker/types.d.ts +499 -0
  35. package/dist/issue-tracker/types.d.ts.map +1 -0
  36. package/dist/issue-tracker/types.js +123 -0
  37. package/dist/issue-tracker/types.js.map +1 -0
  38. package/dist/simple-agent-runner-types.d.ts +206 -0
  39. package/dist/simple-agent-runner-types.d.ts.map +1 -0
  40. package/dist/simple-agent-runner-types.js +2 -0
  41. package/dist/simple-agent-runner-types.js.map +1 -0
  42. package/package.json +4 -3
  43. package/dist/webhook-types.d.ts +0 -259
  44. package/dist/webhook-types.d.ts.map +0 -1
  45. package/dist/webhook-types.js +0 -26
  46. 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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"}