@herdctl/chat 0.0.1 → 0.2.0

package/dist/dm-filter.js

@@ -0,0 +1,162 @@
+/**
+ * DM (Direct Message) filtering utilities
+ *
+ * Provides utilities for:
+ * - Checking if DMs should be processed
+ * - Filtering users via allowlist/blocklist
+ * - Determining DM mode configuration
+ *
+ * These utilities are platform-agnostic and work for any chat platform
+ * that supports direct messages with user filtering.
+ */
+// =============================================================================
+// DM Filtering Functions
+// =============================================================================
+/**
+ * Check if DMs are enabled based on configuration
+ *
+ * If no DM config is provided, DMs are enabled by default.
+ *
+ * @param dmConfig - DM configuration from agent's chat config
+ * @returns true if DMs are enabled, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isDMEnabled(agentConfig.chat.discord?.dm)) {
+ *   // Process DM
+ * }
+ * ```
+ */
+export function isDMEnabled(dmConfig) {
+    // If no DM config provided, DMs are enabled by default
+    if (!dmConfig) {
+        return true;
+    }
+    // If enabled is not specified, default to true
+    return dmConfig.enabled !== false;
+}
+/**
+ * Get the mode for DM processing
+ *
+ * DMs default to "auto" mode (no mention required).
+ *
+ * @param dmConfig - DM configuration from agent's chat config
+ * @returns The mode for DM processing
+ *
+ * @example
+ * ```typescript
+ * const mode = getDMMode(agentConfig.chat.discord?.dm);
+ * if (mode === 'auto') {
+ *   // Process all DM messages
+ * }
+ * ```
+ */
+export function getDMMode(dmConfig) {
+    // DMs default to auto mode (no mention required)
+    if (!dmConfig) {
+        return "auto";
+    }
+    return dmConfig.mode ?? "auto";
+}
+/**
+ * Check if a user is allowed to send DMs to the bot
+ *
+ * Filtering rules:
+ * 1. If DMs are disabled, no users are allowed
+ * 2. If a blocklist is defined and user is on it, they are blocked
+ * 3. If an allowlist is defined, only users on it are allowed
+ * 4. If neither list is defined, all users are allowed
+ *
+ * Note: Blocklist takes precedence over allowlist.
+ *
+ * @param userId - User ID to check
+ * @param dmConfig - DM configuration from agent's chat config
+ * @returns Filter result with allowed status and reason
+ *
+ * @example
+ * ```typescript
+ * const result = checkDMUserFilter("123456789", dmConfig);
+ * if (!result.allowed) {
+ *   console.log(`User blocked: ${result.reason}`);
+ *   return; // Don't process message
+ * }
+ * ```
+ */
+export function checkDMUserFilter(userId, dmConfig) {
+    // If DMs are disabled, no users are allowed
+    if (!isDMEnabled(dmConfig)) {
+        return {
+            allowed: false,
+            reason: "dm_disabled",
+        };
+    }
+    // If no config, all users are allowed
+    if (!dmConfig) {
+        return {
+            allowed: true,
+            reason: "allowed",
+        };
+    }
+    const { allowlist, blocklist } = dmConfig;
+    // Check blocklist first (takes precedence)
+    if (blocklist && blocklist.length > 0) {
+        if (blocklist.includes(userId)) {
+            return {
+                allowed: false,
+                reason: "in_blocklist",
+            };
+        }
+    }
+    // Check allowlist (if defined, only users on it are allowed)
+    if (allowlist && allowlist.length > 0) {
+        if (!allowlist.includes(userId)) {
+            return {
+                allowed: false,
+                reason: "not_in_allowlist",
+            };
+        }
+    }
+    // User is allowed
+    return {
+        allowed: true,
+        reason: "allowed",
+    };
+}
+/**
+ * Check if a message should be processed in the given mode
+ *
+ * In auto mode:
+ * - All non-bot messages are processed
+ * - No mention is required
+ *
+ * In mention mode:
+ * - Only messages that mention the bot are processed
+ *
+ * Bot messages are never processed in either mode.
+ *
+ * @param isBot - Whether the message author is a bot
+ * @param mode - The channel/DM mode
+ * @param wasMentioned - Whether the bot was mentioned in the message
+ * @returns true if the message should be processed
+ *
+ * @example
+ * ```typescript
+ * const mode = getDMMode(dmConfig);
+ * if (shouldProcessInMode(message.author.bot, mode, wasMentioned)) {
+ *   // Process message
+ * }
+ * ```
+ */
+export function shouldProcessInMode(isBot, mode, wasMentioned) {
+    // Never process bot messages
+    if (isBot) {
+        return false;
+    }
+    // In auto mode, process all non-bot messages
+    if (mode === "auto") {
+        return true;
+    }
+    // In mention mode, only process if mentioned
+    return wasMentioned;
+}
+//# sourceMappingURL=dm-filter.js.map

package/dist/dm-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dm-filter.js","sourceRoot":"","sources":["../src/dm-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiCH,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,QAA4B;IACtD,uDAAuD;IACvD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IACD,+CAA+C;IAC/C,OAAO,QAAQ,CAAC,OAAO,KAAK,KAAK,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,QAA4B;IACpD,iDAAiD;IACjD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,IAAI,MAAM,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,QAA4B;IAE5B,4CAA4C;IAC5C,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,aAAa;SACtB,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,SAAS;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC;IAE1C,2CAA2C;IAC3C,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,cAAc;aACvB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,IAAI,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,kBAAkB;aAC3B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kBAAkB;IAClB,OAAO;QACL,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,SAAS;KAClB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAc,EACd,IAAwB,EACxB,YAAqB;IAErB,6BAA6B;IAC7B,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6CAA6C;IAC7C,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/error-handler.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Error handling utilities for chat connectors
+ *
+ * Provides:
+ * - Error classification for handling decisions
+ * - User-friendly error messages
+ * - Retry logic for transient failures
+ * - Safe execution wrappers
+ *
+ * Platform-specific error classification stays in platform packages,
+ * but the common infrastructure is here.
+ */
+import type { ChatConnectorLogger } from "./types.js";
+/**
+ * Categories of errors for handling purposes
+ *
+ * Used to determine appropriate responses and whether to retry.
+ */
+export declare enum ErrorCategory {
+    /** Transient errors that may succeed on retry (network issues, timeouts) */
+    TRANSIENT = "transient",
+    /** Permanent errors that won't succeed on retry (invalid config) */
+    PERMANENT = "permanent",
+    /** Rate limit errors that need backoff before retry */
+    RATE_LIMIT = "rate_limit",
+    /** Configuration or setup errors */
+    CONFIGURATION = "configuration",
+    /** Authentication or authorization errors */
+    AUTH = "auth",
+    /** Network connectivity errors */
+    NETWORK = "network",
+    /** API-specific errors */
+    API = "api",
+    /** Internal/unexpected errors */
+    INTERNAL = "internal",
+    /** Unknown/unexpected errors */
+    UNKNOWN = "unknown"
+}
+/**
+ * Classified error with category and handling information
+ */
+export interface ClassifiedError {
+    /** Original error */
+    error: Error;
+    /** Error category for handling decisions */
+    category: ErrorCategory;
+    /** User-friendly message to display */
+    userMessage: string;
+    /** Whether this error should be retried */
+    shouldRetry: boolean;
+    /** Suggested retry delay in milliseconds (if shouldRetry is true) */
+    retryDelayMs?: number;
+}
+/**
+ * Standard user-friendly error messages
+ *
+ * These are safe to show to end users in chat platforms.
+ */
+export declare const USER_ERROR_MESSAGES: {
+    /** Generic processing error */
+    readonly PROCESSING_ERROR: "Sorry, I encountered an error processing your request. Please try again.";
+    /** Connection/network error */
+    readonly CONNECTION_ERROR: "I'm having trouble connecting right now. Please try again in a moment.";
+    /** Rate limit error */
+    readonly RATE_LIMITED: "I'm receiving too many requests right now. Please wait a moment and try again.";
+    /** Command execution error */
+    readonly COMMAND_ERROR: "Sorry, I couldn't complete that command. Please try again.";
+    /** Session error */
+    readonly SESSION_ERROR: "I'm having trouble with your conversation session. Please try again.";
+    /** Timeout error */
+    readonly TIMEOUT_ERROR: "The request took too long to complete. Please try again.";
+    /** Permission error */
+    readonly PERMISSION_ERROR: "I don't have permission to do that in this channel.";
+    /** Authentication error */
+    readonly AUTH_ERROR: "I'm having trouble authenticating. Please contact an administrator.";
+    /** API error */
+    readonly API_ERROR: "Something went wrong with the chat API. Please try again.";
+    /** Internal error */
+    readonly INTERNAL_ERROR: "An internal error occurred. Please try again or start a new session.";
+    /** Unknown error */
+    readonly UNKNOWN_ERROR: "An unexpected error occurred. Please try again.";
+};
+export type UserErrorMessageKey = keyof typeof USER_ERROR_MESSAGES;
+/**
+ * Options for retry operations
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay between retries in ms (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay between retries in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Exponential backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Logger for retry attempts */
+    logger?: ChatConnectorLogger;
+    /** Operation name for logging */
+    operationName?: string;
+    /** Predicate to determine if error should be retried */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Result of a retry operation
+ */
+export interface RetryResult<T> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The result value (if success is true) */
+    value?: T;
+    /** The last error encountered (if success is false) */
+    error?: Error;
+    /** Number of attempts made */
+    attempts: number;
+}
+/**
+ * Execute an async operation with retry logic
+ *
+ * Uses exponential backoff for transient failures.
+ * Only retries errors when the shouldRetry predicate returns true.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Result with success status, value, or error
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error('Request failed');
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 3,
+ *     operationName: 'fetchData',
+ *     logger: myLogger,
+ *     shouldRetry: (error) => isTransientError(error),
+ *   }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Data:', result.value);
+ * } else {
+ *   console.error('Failed after', result.attempts, 'attempts:', result.error);
+ * }
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * Check if an error is a transient error (may succeed on retry)
+ *
+ * @param error - Error to check
+ * @returns true if the error appears to be transient
+ */
+export declare function isTransientError(error: unknown): boolean;
+/**
+ * Check if an error is a rate limit error
+ *
+ * @param error - Error to check
+ * @returns true if the error indicates rate limiting
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Check if an error is an authentication error
+ *
+ * @param error - Error to check
+ * @returns true if the error indicates an auth problem
+ */
+export declare function isAuthError(error: unknown): boolean;
+/**
+ * Execute an async function and handle errors safely
+ *
+ * Returns the result or undefined if an error occurs.
+ * Always logs errors for debugging.
+ *
+ * @param operation - Async function to execute
+ * @param logger - Logger for error logging
+ * @param context - Description of the operation for logging
+ * @returns Result or undefined on error
+ *
+ * @example
+ * ```typescript
+ * const result = await safeExecute(
+ *   () => fetchUserData(userId),
+ *   logger,
+ *   'fetching user data'
+ * );
+ * if (result) {
+ *   // Use result
+ * }
+ * ```
+ */
+export declare function safeExecute<T>(operation: () => Promise<T>, logger: ChatConnectorLogger, context: string): Promise<T | undefined>;
+/**
+ * Execute an async function and reply with error message on failure
+ *
+ * On error, sends a user-friendly error message to the reply function.
+ *
+ * @param operation - Async function to execute
+ * @param reply - Function to send error reply
+ * @param logger - Logger for error logging
+ * @param context - Description of the operation for logging
+ * @param userMessage - Custom error message for user (optional)
+ *
+ * @example
+ * ```typescript
+ * await safeExecuteWithReply(
+ *   () => processMessage(message),
+ *   (msg) => channel.send(msg),
+ *   logger,
+ *   'processing message'
+ * );
+ * ```
+ */
+export declare function safeExecuteWithReply(operation: () => Promise<void>, reply: (content: string) => Promise<void>, logger: ChatConnectorLogger, context: string, userMessage?: string): Promise<void>;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

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

package/dist/error-handler.js

@@ -0,0 +1,313 @@
+/**
+ * Error handling utilities for chat connectors
+ *
+ * Provides:
+ * - Error classification for handling decisions
+ * - User-friendly error messages
+ * - Retry logic for transient failures
+ * - Safe execution wrappers
+ *
+ * Platform-specific error classification stays in platform packages,
+ * but the common infrastructure is here.
+ */
+// =============================================================================
+// Error Categories
+// =============================================================================
+/**
+ * Categories of errors for handling purposes
+ *
+ * Used to determine appropriate responses and whether to retry.
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Transient errors that may succeed on retry (network issues, timeouts) */
+    ErrorCategory["TRANSIENT"] = "transient";
+    /** Permanent errors that won't succeed on retry (invalid config) */
+    ErrorCategory["PERMANENT"] = "permanent";
+    /** Rate limit errors that need backoff before retry */
+    ErrorCategory["RATE_LIMIT"] = "rate_limit";
+    /** Configuration or setup errors */
+    ErrorCategory["CONFIGURATION"] = "configuration";
+    /** Authentication or authorization errors */
+    ErrorCategory["AUTH"] = "auth";
+    /** Network connectivity errors */
+    ErrorCategory["NETWORK"] = "network";
+    /** API-specific errors */
+    ErrorCategory["API"] = "api";
+    /** Internal/unexpected errors */
+    ErrorCategory["INTERNAL"] = "internal";
+    /** Unknown/unexpected errors */
+    ErrorCategory["UNKNOWN"] = "unknown";
+})(ErrorCategory || (ErrorCategory = {}));
+// =============================================================================
+// User Error Messages
+// =============================================================================
+/**
+ * Standard user-friendly error messages
+ *
+ * These are safe to show to end users in chat platforms.
+ */
+export const USER_ERROR_MESSAGES = {
+    /** Generic processing error */
+    PROCESSING_ERROR: "Sorry, I encountered an error processing your request. Please try again.",
+    /** Connection/network error */
+    CONNECTION_ERROR: "I'm having trouble connecting right now. Please try again in a moment.",
+    /** Rate limit error */
+    RATE_LIMITED: "I'm receiving too many requests right now. Please wait a moment and try again.",
+    /** Command execution error */
+    COMMAND_ERROR: "Sorry, I couldn't complete that command. Please try again.",
+    /** Session error */
+    SESSION_ERROR: "I'm having trouble with your conversation session. Please try again.",
+    /** Timeout error */
+    TIMEOUT_ERROR: "The request took too long to complete. Please try again.",
+    /** Permission error */
+    PERMISSION_ERROR: "I don't have permission to do that in this channel.",
+    /** Authentication error */
+    AUTH_ERROR: "I'm having trouble authenticating. Please contact an administrator.",
+    /** API error */
+    API_ERROR: "Something went wrong with the chat API. Please try again.",
+    /** Internal error */
+    INTERNAL_ERROR: "An internal error occurred. Please try again or start a new session.",
+    /** Unknown error */
+    UNKNOWN_ERROR: "An unexpected error occurred. Please try again.",
+};
+/**
+ * Default retry options
+ */
+const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    backoffMultiplier: 2,
+    operationName: "operation",
+};
+/**
+ * Execute an async operation with retry logic
+ *
+ * Uses exponential backoff for transient failures.
+ * Only retries errors when the shouldRetry predicate returns true.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Result with success status, value, or error
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     const response = await fetch(url);
+ *     if (!response.ok) throw new Error('Request failed');
+ *     return response.json();
+ *   },
+ *   {
+ *     maxAttempts: 3,
+ *     operationName: 'fetchData',
+ *     logger: myLogger,
+ *     shouldRetry: (error) => isTransientError(error),
+ *   }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Data:', result.value);
+ * } else {
+ *   console.error('Failed after', result.attempts, 'attempts:', result.error);
+ * }
+ * ```
+ */
+export async function withRetry(operation, options = {}) {
+    const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    const { maxAttempts, baseDelayMs, maxDelayMs, backoffMultiplier, operationName, logger, } = opts;
+    // Default shouldRetry: retry transient errors
+    const shouldRetryFn = options.shouldRetry ?? ((error) => isTransientError(error));
+    let lastError;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+        attempt++;
+        try {
+            const value = await operation();
+            return { success: true, value, attempts: attempt };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry
+            const shouldRetryError = shouldRetryFn(error, attempt);
+            if (!shouldRetryError || attempt >= maxAttempts) {
+                // Don't retry: either permanent error or out of attempts
+                logger?.debug(`${operationName} failed permanently after ${attempt} attempt(s)`, {
+                    error: lastError.message,
+                });
+                break;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(baseDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxDelayMs);
+            logger?.info(`${operationName} failed, retrying in ${delay}ms...`, {
+                attempt,
+                maxAttempts,
+                error: lastError.message,
+            });
+            // Wait before retrying
+            await sleep(delay);
+        }
+    }
+    return {
+        success: false,
+        error: lastError,
+        attempts: attempt,
+    };
+}
+// =============================================================================
+// Error Classification Helpers
+// =============================================================================
+/**
+ * Check if an error is a transient error (may succeed on retry)
+ *
+ * @param error - Error to check
+ * @returns true if the error appears to be transient
+ */
+export function isTransientError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+    // Network errors
+    const networkPatterns = [
+        "econnreset",
+        "econnrefused",
+        "etimedout",
+        "enotfound",
+        "eai_again",
+        "enetunreach",
+        "ehostunreach",
+        "socket hang up",
+        "network",
+        "connect econnrefused",
+        "getaddrinfo",
+        "fetch failed",
+    ];
+    if (networkPatterns.some((pattern) => message.includes(pattern.toLowerCase()) ||
+        name.includes(pattern.toLowerCase()))) {
+        return true;
+    }
+    // Timeout errors
+    const timeoutPatterns = ["timeout", "timed out", "etimedout", "aborterror"];
+    if (timeoutPatterns.some((pattern) => message.includes(pattern.toLowerCase()) ||
+        name.includes(pattern.toLowerCase()))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if an error is a rate limit error
+ *
+ * @param error - Error to check
+ * @returns true if the error indicates rate limiting
+ */
+export function isRateLimitError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return message.includes("rate_limit") || message.includes("ratelimited");
+}
+/**
+ * Check if an error is an authentication error
+ *
+ * @param error - Error to check
+ * @returns true if the error indicates an auth problem
+ */
+export function isAuthError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const message = error.message.toLowerCase();
+    return (message.includes("invalid_auth") ||
+        message.includes("token_revoked") ||
+        message.includes("token_expired") ||
+        message.includes("not_authed") ||
+        message.includes("unauthorized") ||
+        message.includes("forbidden"));
+}
+// =============================================================================
+// Safe Execution Helpers
+// =============================================================================
+/**
+ * Execute an async function and handle errors safely
+ *
+ * Returns the result or undefined if an error occurs.
+ * Always logs errors for debugging.
+ *
+ * @param operation - Async function to execute
+ * @param logger - Logger for error logging
+ * @param context - Description of the operation for logging
+ * @returns Result or undefined on error
+ *
+ * @example
+ * ```typescript
+ * const result = await safeExecute(
+ *   () => fetchUserData(userId),
+ *   logger,
+ *   'fetching user data'
+ * );
+ * if (result) {
+ *   // Use result
+ * }
+ * ```
+ */
+export async function safeExecute(operation, logger, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Error in ${context}: ${errorMessage}`);
+        return undefined;
+    }
+}
+/**
+ * Execute an async function and reply with error message on failure
+ *
+ * On error, sends a user-friendly error message to the reply function.
+ *
+ * @param operation - Async function to execute
+ * @param reply - Function to send error reply
+ * @param logger - Logger for error logging
+ * @param context - Description of the operation for logging
+ * @param userMessage - Custom error message for user (optional)
+ *
+ * @example
+ * ```typescript
+ * await safeExecuteWithReply(
+ *   () => processMessage(message),
+ *   (msg) => channel.send(msg),
+ *   logger,
+ *   'processing message'
+ * );
+ * ```
+ */
+export async function safeExecuteWithReply(operation, reply, logger, context, userMessage) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        logger.error(`Error in ${context}: ${err.message}`);
+        try {
+            const message = userMessage ?? USER_ERROR_MESSAGES.PROCESSING_ERROR;
+            await reply(message);
+        }
+        catch (replyError) {
+            logger.error(`Failed to send error reply: ${replyError.message}`);
+        }
+    }
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=error-handler.js.map