cyrus-core 0.2.2 → 0.2.4

package/dist/issue-tracker/AgentEvent.d.ts

@@ -0,0 +1,134 @@
+/**
+ * AgentEvent type alias for webhook event payloads.
+ *
+ * This module provides a platform-agnostic type alias for webhook events.
+ * The implementation uses Linear's webhook payload types, but this is hidden
+ * from consuming code through the type alias.
+ *
+ * @module issue-tracker/AgentEvent
+ */
+import type { LinearWebhookPayload } from "@linear/sdk/webhooks";
+/**
+ * Platform-agnostic webhook event type.
+ *
+ * This type represents webhook events from the issue tracking platform.
+ * Currently backed by Linear's webhook payload type, but abstracted for
+ * future multi-platform support.
+ *
+ * @example
+ * ```typescript
+ * import { AgentEvent } from '@cyrus/core/issue-tracker';
+ *
+ * function handleWebhook(event: AgentEvent) {
+ *   // Process the webhook event
+ *   console.log('Received event:', event.action);
+ * }
+ * ```
+ *
+ * @remarks
+ * This type alias hides the Linear-specific implementation detail while
+ * maintaining full type safety. When adding support for other platforms,
+ * this can be converted to a union type or more sophisticated abstraction.
+ *
+ * @see {@link LinearWebhookPayload} for the underlying Linear type structure
+ */
+export type AgentEvent = LinearWebhookPayload;
+/**
+ * Type guard to check if an event is an issue assignment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an issue assignment
+ *
+ * @example
+ * ```typescript
+ * if (isIssueAssignedEvent(event)) {
+ *   console.log('Issue assigned:', event.notification.issue.identifier);
+ * }
+ * ```
+ */
+export declare function isIssueAssignedEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    action: "issueAssignedToYou";
+}>;
+/**
+ * Type guard to check if an event is an issue unassignment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an issue unassignment
+ *
+ * @example
+ * ```typescript
+ * if (isIssueUnassignedEvent(event)) {
+ *   console.log('Issue unassigned:', event.notification.issue.identifier);
+ * }
+ * ```
+ */
+export declare function isIssueUnassignedEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    action: "issueUnassignedFromYou";
+}>;
+/**
+ * Type guard to check if an event is a comment mention event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is a comment mention
+ *
+ * @example
+ * ```typescript
+ * if (isCommentMentionEvent(event)) {
+ *   console.log('Mentioned in comment:', event.notification.comment.body);
+ * }
+ * ```
+ */
+export declare function isCommentMentionEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    action: "issueCommentMention";
+}>;
+/**
+ * Type guard to check if an event is a new comment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is a new comment
+ *
+ * @example
+ * ```typescript
+ * if (isNewCommentEvent(event)) {
+ *   console.log('New comment:', event.notification.comment.body);
+ * }
+ * ```
+ */
+export declare function isNewCommentEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    action: "issueNewComment";
+}>;
+/**
+ * Type guard to check if an event is an agent session created event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an agent session creation
+ *
+ * @example
+ * ```typescript
+ * if (isAgentSessionCreatedEvent(event)) {
+ *   console.log('Agent session created:', event.agentSession.id);
+ * }
+ * ```
+ */
+export declare function isAgentSessionCreatedEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    type: "AgentSessionEvent";
+    action: "created";
+}>;
+/**
+ * Type guard to check if an event is an agent session prompted event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an agent session prompt
+ *
+ * @example
+ * ```typescript
+ * if (isAgentSessionPromptedEvent(event)) {
+ *   console.log('Agent session prompted:', event.agentActivity.content.body);
+ * }
+ * ```
+ */
+export declare function isAgentSessionPromptedEvent(event: AgentEvent): event is Extract<AgentEvent, {
+    type: "AgentSessionEvent";
+    action: "prompted";
+}>;
+//# sourceMappingURL=AgentEvent.d.ts.map

package/dist/issue-tracker/AgentEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentEvent.d.ts","sourceRoot":"","sources":["../../src/issue-tracker/AgentEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAKhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC,CAKpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAKjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAI7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACzC,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAClB,UAAU,EACV;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAChD,CAEA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,UAAU,GACf,KAAK,IAAI,OAAO,CAClB,UAAU,EACV;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CACjD,CAEA"}

package/dist/issue-tracker/AgentEvent.js

@@ -0,0 +1,109 @@
+/**
+ * AgentEvent type alias for webhook event payloads.
+ *
+ * This module provides a platform-agnostic type alias for webhook events.
+ * The implementation uses Linear's webhook payload types, but this is hidden
+ * from consuming code through the type alias.
+ *
+ * @module issue-tracker/AgentEvent
+ */
+/**
+ * Type guard to check if an event is an issue assignment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an issue assignment
+ *
+ * @example
+ * ```typescript
+ * if (isIssueAssignedEvent(event)) {
+ *   console.log('Issue assigned:', event.notification.issue.identifier);
+ * }
+ * ```
+ */
+export function isIssueAssignedEvent(event) {
+    return (event.type === "AppUserNotification" &&
+        event.action === "issueAssignedToYou");
+}
+/**
+ * Type guard to check if an event is an issue unassignment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an issue unassignment
+ *
+ * @example
+ * ```typescript
+ * if (isIssueUnassignedEvent(event)) {
+ *   console.log('Issue unassigned:', event.notification.issue.identifier);
+ * }
+ * ```
+ */
+export function isIssueUnassignedEvent(event) {
+    return (event.type === "AppUserNotification" &&
+        event.action === "issueUnassignedFromYou");
+}
+/**
+ * Type guard to check if an event is a comment mention event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is a comment mention
+ *
+ * @example
+ * ```typescript
+ * if (isCommentMentionEvent(event)) {
+ *   console.log('Mentioned in comment:', event.notification.comment.body);
+ * }
+ * ```
+ */
+export function isCommentMentionEvent(event) {
+    return (event.type === "AppUserNotification" &&
+        event.action === "issueCommentMention");
+}
+/**
+ * Type guard to check if an event is a new comment event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is a new comment
+ *
+ * @example
+ * ```typescript
+ * if (isNewCommentEvent(event)) {
+ *   console.log('New comment:', event.notification.comment.body);
+ * }
+ * ```
+ */
+export function isNewCommentEvent(event) {
+    return (event.type === "AppUserNotification" && event.action === "issueNewComment");
+}
+/**
+ * Type guard to check if an event is an agent session created event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an agent session creation
+ *
+ * @example
+ * ```typescript
+ * if (isAgentSessionCreatedEvent(event)) {
+ *   console.log('Agent session created:', event.agentSession.id);
+ * }
+ * ```
+ */
+export function isAgentSessionCreatedEvent(event) {
+    return event.type === "AgentSessionEvent" && event.action === "created";
+}
+/**
+ * Type guard to check if an event is an agent session prompted event.
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event is an agent session prompt
+ *
+ * @example
+ * ```typescript
+ * if (isAgentSessionPromptedEvent(event)) {
+ *   console.log('Agent session prompted:', event.agentActivity.content.body);
+ * }
+ * ```
+ */
+export function isAgentSessionPromptedEvent(event) {
+    return event.type === "AgentSessionEvent" && event.action === "prompted";
+}
+//# sourceMappingURL=AgentEvent.js.map

package/dist/issue-tracker/AgentEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentEvent.js","sourceRoot":"","sources":["../../src/issue-tracker/AgentEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8BH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CACnC,KAAiB;IAEjB,OAAO,CACN,KAAK,CAAC,IAAI,KAAK,qBAAqB;QACpC,KAAK,CAAC,MAAM,KAAK,oBAAoB,CACrC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACrC,KAAiB;IAEjB,OAAO,CACN,KAAK,CAAC,IAAI,KAAK,qBAAqB;QACpC,KAAK,CAAC,MAAM,KAAK,wBAAwB,CACzC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,qBAAqB,CACpC,KAAiB;IAEjB,OAAO,CACN,KAAK,CAAC,IAAI,KAAK,qBAAqB;QACpC,KAAK,CAAC,MAAM,KAAK,qBAAqB,CACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAChC,KAAiB;IAEjB,OAAO,CACN,KAAK,CAAC,IAAI,KAAK,qBAAqB,IAAI,KAAK,CAAC,MAAM,KAAK,iBAAiB,CAC1E,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACzC,KAAiB;IAKjB,OAAO,KAAK,CAAC,IAAI,KAAK,mBAAmB,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CAC1C,KAAiB;IAKjB,OAAO,KAAK,CAAC,IAAI,KAAK,mBAAmB,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC;AAC1E,CAAC"}

package/dist/issue-tracker/IAgentEventTransport.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Platform-agnostic interface for agent event transport.
+ *
+ * This interface defines how webhook events from issue tracking platforms
+ * are received, verified, and delivered to the application. It abstracts
+ * away platform-specific details like HTTP endpoints, signature verification,
+ * and payload structures.
+ *
+ * @module issue-tracker/IAgentEventTransport
+ */
+import type { FastifyInstance } from "fastify";
+import type { AgentEvent } from "./AgentEvent.js";
+/**
+ * Base configuration shared by all event transports.
+ */
+interface AgentEventTransportConfigBase {
+    /**
+     * Fastify server instance to register webhook endpoints with.
+     */
+    fastifyServer: FastifyInstance;
+}
+/**
+ * Configuration for Linear event transport in direct mode.
+ * Uses Linear's webhook signature verification.
+ */
+export interface LinearDirectEventTransportConfig extends AgentEventTransportConfigBase {
+    platform: "linear";
+    verificationMode: "direct";
+    /**
+     * Linear webhook secret (LINEAR_WEBHOOK_SECRET) for signature verification.
+     */
+    secret: string;
+}
+/**
+ * Configuration for Linear event transport in proxy mode.
+ * Uses Bearer token authentication.
+ */
+export interface LinearProxyEventTransportConfig extends AgentEventTransportConfigBase {
+    platform: "linear";
+    verificationMode: "proxy";
+    /**
+     * API key (CYRUS_API_KEY) for Bearer token authentication.
+     */
+    secret: string;
+}
+/**
+ * Configuration for CLI event transport (in-memory mode).
+ */
+export interface CLIEventTransportConfig extends AgentEventTransportConfigBase {
+    platform: "cli";
+}
+/**
+ * Discriminated union of all event transport configurations.
+ * Platform-specific config values are only required when using that platform.
+ */
+export type AgentEventTransportConfig = LinearDirectEventTransportConfig | LinearProxyEventTransportConfig | CLIEventTransportConfig;
+/**
+ * Event handlers for agent event transport.
+ */
+export interface AgentEventTransportEvents {
+    /**
+     * Emitted when a valid agent event is received.
+     * @param event - The verified agent event
+     */
+    event: (event: AgentEvent) => void;
+    /**
+     * Emitted when an error occurs during event processing.
+     * @param error - The error that occurred
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Platform-agnostic transport for receiving and delivering agent events.
+ *
+ * This interface defines the contract for event transport implementations.
+ * Each platform (Linear, GitHub, Jira) provides its own implementation that
+ * handles platform-specific details like HTTP endpoints, authentication, and
+ * payload structures.
+ *
+ * @example
+ * ```typescript
+ * // Create transport from issue tracker service
+ * const transport = issueTracker.createEventTransport({
+ *   fastifyServer: server.getFastifyInstance(),
+ *   verificationMode: 'proxy',
+ *   secret: process.env.CYRUS_API_KEY
+ * });
+ *
+ * // Register HTTP endpoints
+ * transport.register();
+ *
+ * // Listen for events
+ * transport.on('event', (event: AgentEvent) => {
+ *   console.log('Received event:', event.action);
+ * });
+ *
+ * // Handle errors
+ * transport.on('error', (error: Error) => {
+ *   console.error('Transport error:', error);
+ * });
+ * ```
+ */
+export interface IAgentEventTransport {
+    /**
+     * Register HTTP endpoints with the Fastify server.
+     *
+     * This method mounts the necessary routes to receive webhook events
+     * from the issue tracking platform.
+     *
+     * @example
+     * ```typescript
+     * transport.register();
+     * console.log('Webhook endpoints registered');
+     * ```
+     */
+    register(): void;
+    /**
+     * Register an event listener.
+     *
+     * @param event - Event name to listen for
+     * @param listener - Callback function to handle the event
+     *
+     * @example
+     * ```typescript
+     * transport.on('event', (event: AgentEvent) => {
+     *   if (isAgentSessionCreatedEvent(event)) {
+     *     console.log('Session created:', event.agentSession.id);
+     *   }
+     * });
+     * ```
+     */
+    on<K extends keyof AgentEventTransportEvents>(event: K, listener: AgentEventTransportEvents[K]): void;
+    /**
+     * Remove all event listeners.
+     *
+     * This is typically called during cleanup when shutting down the transport.
+     *
+     * @example
+     * ```typescript
+     * transport.removeAllListeners();
+     * ```
+     */
+    removeAllListeners(): void;
+}
+export {};
+//# sourceMappingURL=IAgentEventTransport.d.ts.map

package/dist/issue-tracker/IAgentEventTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAgentEventTransport.d.ts","sourceRoot":"","sources":["../../src/issue-tracker/IAgentEventTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,UAAU,6BAA6B;IACtC;;OAEG;IACH,aAAa,EAAE,eAAe,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,gCAChB,SAAQ,6BAA6B;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,EAAE,QAAQ,CAAC;IAC3B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,+BAChB,SAAQ,6BAA6B;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,6BAA6B;IAC7E,QAAQ,EAAE,KAAK,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAClC,gCAAgC,GAChC,+BAA+B,GAC/B,uBAAuB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAEnC;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;;;;;;;;;OAcG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,yBAAyB,EAC3C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,IAAI,CAAC;IAER;;;;;;;;;OASG;IACH,kBAAkB,IAAI,IAAI,CAAC;CAC3B"}

package/dist/issue-tracker/IAgentEventTransport.js

@@ -0,0 +1,12 @@
+/**
+ * Platform-agnostic interface for agent event transport.
+ *
+ * This interface defines how webhook events from issue tracking platforms
+ * are received, verified, and delivered to the application. It abstracts
+ * away platform-specific details like HTTP endpoints, signature verification,
+ * and payload structures.
+ *
+ * @module issue-tracker/IAgentEventTransport
+ */
+export {};
+//# sourceMappingURL=IAgentEventTransport.js.map

package/dist/issue-tracker/IAgentEventTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAgentEventTransport.js","sourceRoot":"","sources":["../../src/issue-tracker/IAgentEventTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}