@herdctl/discord 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Type definitions for the Discord connector
+ *
+ * Provides interfaces for Discord connector configuration,
+ * connection state, and event definitions.
+ */
+import type { AgentConfig, AgentChatDiscord } from "@herdctl/core";
+import type { FleetManager } from "@herdctl/core";
+import type { ConversationContext } from "./mention-handler.js";
+import type { ISessionManager } from "./session-manager/index.js";
+/**
+ * Logger interface for Discord connector operations
+ */
+export interface DiscordConnectorLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Options for configuring the DiscordConnector
+ *
+ * @example
+ * ```typescript
+ * const options: DiscordConnectorOptions = {
+ *   agentConfig: loadedAgentConfig,
+ *   discordConfig: loadedAgentConfig.chat.discord,
+ *   botToken: process.env.MY_BOT_TOKEN,
+ *   fleetManager: manager,
+ * };
+ * ```
+ */
+export interface DiscordConnectorOptions {
+    /**
+     * The agent configuration this connector is associated with
+     */
+    agentConfig: AgentConfig;
+    /**
+     * Discord-specific configuration from agent's chat.discord section
+     */
+    discordConfig: AgentChatDiscord;
+    /**
+     * Discord bot token for authentication
+     *
+     * This should be retrieved from the environment variable specified
+     * in discordConfig.bot_token_env. Never store tokens in config files.
+     */
+    botToken: string;
+    /**
+     * Reference to the FleetManager for job triggering
+     */
+    fleetManager: FleetManager;
+    /**
+     * Logger for connector operations
+     *
+     * Default: console-based logger with [discord:agentName] prefix
+     */
+    logger?: DiscordConnectorLogger;
+    /**
+     * Session manager for conversation context management
+     *
+     * Required for slash command support (/reset, /status)
+     */
+    sessionManager: ISessionManager;
+    /**
+     * Root path for state storage (e.g., .herdctl)
+     *
+     * Used for session persistence
+     */
+    stateDir?: string;
+}
+/**
+ * Current connection status of the Discord connector
+ */
+export type DiscordConnectionStatus = "disconnected" | "connecting" | "connected" | "reconnecting" | "disconnecting" | "error";
+/**
+ * Detailed connector state for monitoring
+ */
+export interface DiscordConnectorState {
+    /**
+     * Current connection status
+     */
+    status: DiscordConnectionStatus;
+    /**
+     * ISO timestamp of when the connector was connected
+     */
+    connectedAt: string | null;
+    /**
+     * ISO timestamp of when the connector was disconnected
+     */
+    disconnectedAt: string | null;
+    /**
+     * Number of reconnection attempts since last successful connection
+     */
+    reconnectAttempts: number;
+    /**
+     * Last error message if status is 'error'
+     */
+    lastError: string | null;
+    /**
+     * Discord user info when connected
+     */
+    botUser: {
+        id: string;
+        username: string;
+        discriminator: string;
+    } | null;
+    /**
+     * Rate limit tracking information
+     */
+    rateLimits: {
+        /**
+         * Total count of rate limits encountered since connection
+         */
+        totalCount: number;
+        /**
+         * ISO timestamp of the last rate limit encountered
+         */
+        lastRateLimitAt: string | null;
+        /**
+         * Whether currently rate limited (based on most recent rate limit)
+         */
+        isRateLimited: boolean;
+        /**
+         * Time in ms until current rate limit resets (0 if not rate limited)
+         */
+        currentResetTime: number;
+    };
+    /**
+     * Message statistics since connection
+     */
+    messageStats: {
+        /**
+         * Total messages received and processed
+         */
+        received: number;
+        /**
+         * Total messages sent (replies)
+         */
+        sent: number;
+        /**
+         * Total messages ignored (not mentioned, bot messages, etc.)
+         */
+        ignored: number;
+    };
+}
+/**
+ * Interface that all Discord connectors must implement
+ *
+ * This interface defines the contract for connecting agents to Discord.
+ * Each agent has its own DiscordConnector instance with its own bot identity.
+ */
+export interface IDiscordConnector {
+    /**
+     * Connect to Discord gateway
+     *
+     * Establishes connection and registers event handlers.
+     * Auto-reconnect is handled by discord.js on connection loss.
+     *
+     * @throws DiscordConnectorError on connection failure
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from Discord gateway
+     *
+     * Performs graceful shutdown, cleaning up resources.
+     * Does not throw on failure - logs errors and completes.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if currently connected to Discord
+     *
+     * @returns true if connected and ready, false otherwise
+     */
+    isConnected(): boolean;
+    /**
+     * Get current connector state
+     *
+     * @returns Current state including connection status and metadata
+     */
+    getState(): DiscordConnectorState;
+    /**
+     * Name of the agent this connector is for
+     */
+    readonly agentName: string;
+}
+/**
+ * Events emitted by the Discord connector
+ */
+export interface DiscordConnectorEventMap {
+    /**
+     * Emitted when connection is established and ready
+     */
+    ready: {
+        agentName: string;
+        botUser: {
+            id: string;
+            username: string;
+            discriminator: string;
+        };
+    };
+    /**
+     * Emitted when connection is lost
+     */
+    disconnect: {
+        agentName: string;
+        code: number;
+        reason: string;
+    };
+    /**
+     * Emitted on connection error
+     */
+    error: {
+        agentName: string;
+        error: Error;
+    };
+    /**
+     * Emitted when reconnecting after disconnect
+     */
+    reconnecting: {
+        agentName: string;
+        attempt: number;
+    };
+    /**
+     * Emitted when successfully reconnected
+     */
+    reconnected: {
+        agentName: string;
+    };
+    /**
+     * Emitted when a message is received that should be processed
+     *
+     * This event is emitted after mention detection and filtering.
+     * The prompt has already been stripped of the bot mention.
+     */
+    message: {
+        agentName: string;
+        /** The processed prompt (with mention stripped) */
+        prompt: string;
+        /** Conversation context including recent message history */
+        context: ConversationContext;
+        /** Discord-specific metadata */
+        metadata: {
+            /** ID of the guild (server), null for DMs */
+            guildId: string | null;
+            /** ID of the channel */
+            channelId: string;
+            /** ID of the message */
+            messageId: string;
+            /** ID of the user who sent the message */
+            userId: string;
+            /** Username of the user who sent the message */
+            username: string;
+            /** Whether this was triggered by a mention */
+            wasMentioned: boolean;
+            /** Channel mode that was applied */
+            mode: "mention" | "auto";
+        };
+        /** Function to send a reply in the same channel */
+        reply: (content: string) => Promise<void>;
+    };
+    /**
+     * Emitted when a message is ignored (e.g., in mention mode but not mentioned)
+     */
+    messageIgnored: {
+        agentName: string;
+        reason: "not_mentioned" | "bot_message" | "not_configured" | "unknown_channel";
+        /** Discord channel ID */
+        channelId: string;
+        /** Discord message ID */
+        messageId: string;
+    };
+    /**
+     * Emitted when a slash command is executed
+     */
+    commandExecuted: {
+        agentName: string;
+        /** Name of the command that was executed */
+        commandName: string;
+        /** Discord user ID who executed the command */
+        userId: string;
+        /** Discord channel ID where the command was executed */
+        channelId: string;
+    };
+    /**
+     * Emitted when a session is created, resumed, or expires
+     *
+     * This event allows FleetManager to track session lifecycle for monitoring.
+     */
+    sessionLifecycle: {
+        agentName: string;
+        /** Type of session event */
+        event: "created" | "resumed" | "expired" | "cleared";
+        /** Discord channel ID */
+        channelId: string;
+        /** Claude session ID */
+        sessionId: string;
+    };
+    /**
+     * Emitted when a rate limit is encountered
+     *
+     * Discord.js handles rate limits automatically by queuing and retrying requests.
+     * This event is emitted for monitoring and logging purposes.
+     */
+    rateLimit: {
+        agentName: string;
+        /** The time (in milliseconds) until the rate limit resets */
+        timeToReset: number;
+        /** Maximum number of requests allowed in the rate limit window */
+        limit: number;
+        /** HTTP method of the request that hit the rate limit */
+        method: string;
+        /** Route hash for the rate-limited endpoint */
+        hash: string;
+        /** The API route that hit the rate limit */
+        route: string;
+        /** Whether this is a global rate limit */
+        global: boolean;
+    };
+}
+export type DiscordConnectorEventName = keyof DiscordConnectorEventMap;
+export type DiscordConnectorEventPayload<T extends DiscordConnectorEventName> = DiscordConnectorEventMap[T];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the Discord connector
+ *
+ * Provides interfaces for Discord connector configuration,
+ * connection state, and event definitions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/utils/__tests__/formatting.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=formatting.test.d.ts.map

package/dist/utils/__tests__/formatting.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatting.test.d.ts","sourceRoot":"","sources":["../../../src/utils/__tests__/formatting.test.ts"],"names":[],"mappings":""}