@herdctl/discord 0.0.1

package/dist/error-handler.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Error handler utilities for Discord connector
+ *
+ * Provides:
+ * - User-friendly error messages for Discord users
+ * - Detailed logging for debugging
+ * - Retry logic for transient failures
+ * - Error classification and handling
+ */
+import type { DiscordConnectorLogger } from "./types.js";
+/**
+ * Standard user-friendly error messages for Discord responses
+ */
+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.";
+};
+export type UserErrorMessageKey = keyof typeof USER_ERROR_MESSAGES;
+/**
+ * Categories of errors for handling purposes
+ */
+export declare enum ErrorCategory {
+    /** Transient errors that may succeed on retry */
+    TRANSIENT = "transient",
+    /** Permanent errors that won't succeed on retry */
+    PERMANENT = "permanent",
+    /** Rate limit errors that need backoff */
+    RATE_LIMIT = "rate_limit",
+    /** Configuration/setup errors */
+    CONFIGURATION = "configuration",
+    /** Unknown/unexpected errors */
+    UNKNOWN = "unknown"
+}
+/**
+ * Classified error with category and user-friendly message
+ */
+export interface ClassifiedError {
+    /** Original error */
+    error: Error;
+    /** Error category for handling */
+    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;
+}
+/**
+ * Classify an error for appropriate handling
+ *
+ * @param error - The error to classify
+ * @returns Classified error with category and handling info
+ */
+export declare function classifyError(error: unknown): ClassifiedError;
+/**
+ * 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?: DiscordConnectorLogger;
+    /** 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 that are classified as retryable.
+ *
+ * @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,
+ *   }
+ * );
+ *
+ * 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>>;
+/**
+ * Options for the ErrorHandler
+ */
+export interface ErrorHandlerOptions {
+    /** Logger for error logging */
+    logger: DiscordConnectorLogger;
+    /** Agent name for context in logs */
+    agentName: string;
+}
+/**
+ * Error handler that provides user-friendly messages and detailed logging
+ *
+ * Handles:
+ * - Converting errors to user-friendly messages
+ * - Logging detailed error information for debugging
+ * - Tracking error statistics
+ *
+ * @example
+ * ```typescript
+ * const errorHandler = new ErrorHandler({
+ *   logger: myLogger,
+ *   agentName: 'my-agent',
+ * });
+ *
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const userMessage = errorHandler.handleError(error, 'processing message');
+ *   await message.reply(userMessage);
+ * }
+ * ```
+ */
+export declare class ErrorHandler {
+    private readonly logger;
+    private readonly agentName;
+    private errorCounts;
+    constructor(options: ErrorHandlerOptions);
+    /**
+     * Handle an error and return a user-friendly message
+     *
+     * Logs detailed error information and returns a safe message for users.
+     *
+     * @param error - The error to handle
+     * @param context - Description of what operation was being performed
+     * @returns User-friendly error message
+     */
+    handleError(error: unknown, context: string): string;
+    /**
+     * Handle an error with custom user message
+     *
+     * @param error - The error to handle
+     * @param context - Description of what operation was being performed
+     * @param userMessage - Custom message to return to user
+     * @returns The provided user message
+     */
+    handleErrorWithMessage(error: unknown, context: string, userMessage: string): string;
+    /**
+     * Get error statistics
+     *
+     * @returns Map of error categories to counts
+     */
+    getErrorStats(): ReadonlyMap<ErrorCategory, number>;
+    /**
+     * Reset error statistics
+     */
+    resetStats(): void;
+    /**
+     * Check if an error is retryable
+     *
+     * @param error - The error to check
+     * @returns true if the error should be retried
+     */
+    isRetryable(error: unknown): boolean;
+    /**
+     * Get the appropriate user message for an error
+     *
+     * @param error - The error to get message for
+     * @returns User-friendly error message
+     */
+    getUserMessage(error: unknown): string;
+}
+/**
+ * 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 errorHandler - Error handler for logging
+ * @param context - Description of the operation
+ * @returns Result or undefined on error
+ */
+export declare function safeExecute<T>(operation: () => Promise<T>, errorHandler: ErrorHandler, context: string): Promise<T | undefined>;
+/**
+ * Execute an async function that returns a reply to the user
+ *
+ * On error, returns a user-friendly error message instead.
+ *
+ * @param operation - Async function to execute that returns a message
+ * @param errorHandler - Error handler for logging
+ * @param context - Description of the operation
+ * @returns Result message or error message
+ */
+export declare function safeExecuteWithReply(operation: () => Promise<string>, errorHandler: ErrorHandler, context: string): Promise<string>;
+//# 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,433 @@
+/**
+ * Error handler utilities for Discord connector
+ *
+ * Provides:
+ * - User-friendly error messages for Discord users
+ * - Detailed logging for debugging
+ * - Retry logic for transient failures
+ * - Error classification and handling
+ */
+import { DiscordErrorCode, isDiscordConnectorError, } from "./errors.js";
+import { isSessionManagerError, } from "./session-manager/errors.js";
+// =============================================================================
+// User-Friendly Error Messages
+// =============================================================================
+/**
+ * Standard user-friendly error messages for Discord responses
+ */
+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.",
+};
+// =============================================================================
+// Error Classification
+// =============================================================================
+/**
+ * Categories of errors for handling purposes
+ */
+export var ErrorCategory;
+(function (ErrorCategory) {
+    /** Transient errors that may succeed on retry */
+    ErrorCategory["TRANSIENT"] = "transient";
+    /** Permanent errors that won't succeed on retry */
+    ErrorCategory["PERMANENT"] = "permanent";
+    /** Rate limit errors that need backoff */
+    ErrorCategory["RATE_LIMIT"] = "rate_limit";
+    /** Configuration/setup errors */
+    ErrorCategory["CONFIGURATION"] = "configuration";
+    /** Unknown/unexpected errors */
+    ErrorCategory["UNKNOWN"] = "unknown";
+})(ErrorCategory || (ErrorCategory = {}));
+/**
+ * Classify an error for appropriate handling
+ *
+ * @param error - The error to classify
+ * @returns Classified error with category and handling info
+ */
+export function classifyError(error) {
+    // Ensure we have an Error object
+    const err = error instanceof Error ? error : new Error(String(error));
+    // Check for Discord connector errors
+    if (isDiscordConnectorError(error)) {
+        return classifyDiscordError(error);
+    }
+    // Check for session manager errors
+    if (isSessionManagerError(error)) {
+        return classifySessionError(error);
+    }
+    // Check for network/connection errors
+    if (isNetworkError(err)) {
+        return {
+            error: err,
+            category: ErrorCategory.TRANSIENT,
+            userMessage: USER_ERROR_MESSAGES.CONNECTION_ERROR,
+            shouldRetry: true,
+            retryDelayMs: 1000,
+        };
+    }
+    // Check for timeout errors
+    if (isTimeoutError(err)) {
+        return {
+            error: err,
+            category: ErrorCategory.TRANSIENT,
+            userMessage: USER_ERROR_MESSAGES.TIMEOUT_ERROR,
+            shouldRetry: true,
+            retryDelayMs: 2000,
+        };
+    }
+    // Default: unknown error
+    return {
+        error: err,
+        category: ErrorCategory.UNKNOWN,
+        userMessage: USER_ERROR_MESSAGES.PROCESSING_ERROR,
+        shouldRetry: false,
+    };
+}
+/**
+ * Classify a Discord connector error
+ */
+function classifyDiscordError(error) {
+    switch (error.code) {
+        case DiscordErrorCode.RATE_LIMITED:
+            return {
+                error,
+                category: ErrorCategory.RATE_LIMIT,
+                userMessage: USER_ERROR_MESSAGES.RATE_LIMITED,
+                shouldRetry: true,
+                retryDelayMs: 5000, // Default, actual delay comes from Discord
+            };
+        case DiscordErrorCode.CONNECTION_FAILED:
+        case DiscordErrorCode.GATEWAY_ERROR:
+            return {
+                error,
+                category: ErrorCategory.TRANSIENT,
+                userMessage: USER_ERROR_MESSAGES.CONNECTION_ERROR,
+                shouldRetry: true,
+                retryDelayMs: 2000,
+            };
+        case DiscordErrorCode.INVALID_TOKEN:
+        case DiscordErrorCode.MISSING_TOKEN:
+            return {
+                error,
+                category: ErrorCategory.CONFIGURATION,
+                userMessage: USER_ERROR_MESSAGES.PROCESSING_ERROR,
+                shouldRetry: false,
+            };
+        case DiscordErrorCode.ALREADY_CONNECTED:
+        case DiscordErrorCode.NOT_CONNECTED:
+            return {
+                error,
+                category: ErrorCategory.PERMANENT,
+                userMessage: USER_ERROR_MESSAGES.PROCESSING_ERROR,
+                shouldRetry: false,
+            };
+        default:
+            return {
+                error,
+                category: ErrorCategory.UNKNOWN,
+                userMessage: USER_ERROR_MESSAGES.PROCESSING_ERROR,
+                shouldRetry: false,
+            };
+    }
+}
+/**
+ * Classify a session manager error
+ */
+function classifySessionError(error) {
+    // Session errors are generally transient (file system issues)
+    return {
+        error,
+        category: ErrorCategory.TRANSIENT,
+        userMessage: USER_ERROR_MESSAGES.SESSION_ERROR,
+        shouldRetry: true,
+        retryDelayMs: 1000,
+    };
+}
+/**
+ * Check if an error is a network-related error
+ */
+function isNetworkError(error) {
+    const networkErrorPatterns = [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ETIMEDOUT",
+        "ENOTFOUND",
+        "EAI_AGAIN",
+        "ENETUNREACH",
+        "EHOSTUNREACH",
+        "socket hang up",
+        "network",
+        "connect ECONNREFUSED",
+        "getaddrinfo",
+        "fetch failed",
+    ];
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+    return networkErrorPatterns.some((pattern) => message.includes(pattern.toLowerCase()) ||
+        name.includes(pattern.toLowerCase()));
+}
+/**
+ * Check if an error is a timeout error
+ */
+function isTimeoutError(error) {
+    const timeoutPatterns = ["timeout", "timed out", "ETIMEDOUT", "AbortError"];
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+    return timeoutPatterns.some((pattern) => message.includes(pattern.toLowerCase()) ||
+        name.includes(pattern.toLowerCase()));
+}
+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 that are classified as retryable.
+ *
+ * @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,
+ *   }
+ * );
+ *
+ * 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;
+    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));
+            // Classify the error to determine if we should retry
+            const classified = classifyError(error);
+            // Check custom shouldRetry predicate if provided
+            const shouldRetryError = options.shouldRetry
+                ? options.shouldRetry(error, attempt)
+                : classified.shouldRetry;
+            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,
+                    category: classified.category,
+                });
+                break;
+            }
+            // Calculate delay with exponential backoff
+            const delay = Math.min(classified.retryDelayMs ?? baseDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxDelayMs);
+            logger?.info(`${operationName} failed, retrying in ${delay}ms...`, {
+                attempt,
+                maxAttempts,
+                error: lastError.message,
+                category: classified.category,
+            });
+            // Wait before retrying
+            await sleep(delay);
+        }
+    }
+    return {
+        success: false,
+        error: lastError,
+        attempts: attempt,
+    };
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Error handler that provides user-friendly messages and detailed logging
+ *
+ * Handles:
+ * - Converting errors to user-friendly messages
+ * - Logging detailed error information for debugging
+ * - Tracking error statistics
+ *
+ * @example
+ * ```typescript
+ * const errorHandler = new ErrorHandler({
+ *   logger: myLogger,
+ *   agentName: 'my-agent',
+ * });
+ *
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   const userMessage = errorHandler.handleError(error, 'processing message');
+ *   await message.reply(userMessage);
+ * }
+ * ```
+ */
+export class ErrorHandler {
+    logger;
+    agentName;
+    errorCounts = new Map();
+    constructor(options) {
+        this.logger = options.logger;
+        this.agentName = options.agentName;
+    }
+    /**
+     * Handle an error and return a user-friendly message
+     *
+     * Logs detailed error information and returns a safe message for users.
+     *
+     * @param error - The error to handle
+     * @param context - Description of what operation was being performed
+     * @returns User-friendly error message
+     */
+    handleError(error, context) {
+        const classified = classifyError(error);
+        // Increment error count for this category
+        const currentCount = this.errorCounts.get(classified.category) ?? 0;
+        this.errorCounts.set(classified.category, currentCount + 1);
+        // Log detailed error for debugging
+        this.logger.error(`Error during ${context}`, {
+            agentName: this.agentName,
+            context,
+            category: classified.category,
+            shouldRetry: classified.shouldRetry,
+            errorMessage: classified.error.message,
+            errorName: classified.error.name,
+            stack: classified.error.stack,
+        });
+        return classified.userMessage;
+    }
+    /**
+     * Handle an error with custom user message
+     *
+     * @param error - The error to handle
+     * @param context - Description of what operation was being performed
+     * @param userMessage - Custom message to return to user
+     * @returns The provided user message
+     */
+    handleErrorWithMessage(error, context, userMessage) {
+        const classified = classifyError(error);
+        // Log detailed error for debugging
+        this.logger.error(`Error during ${context}`, {
+            agentName: this.agentName,
+            context,
+            category: classified.category,
+            errorMessage: classified.error.message,
+            errorName: classified.error.name,
+            stack: classified.error.stack,
+        });
+        return userMessage;
+    }
+    /**
+     * Get error statistics
+     *
+     * @returns Map of error categories to counts
+     */
+    getErrorStats() {
+        return this.errorCounts;
+    }
+    /**
+     * Reset error statistics
+     */
+    resetStats() {
+        this.errorCounts.clear();
+    }
+    /**
+     * Check if an error is retryable
+     *
+     * @param error - The error to check
+     * @returns true if the error should be retried
+     */
+    isRetryable(error) {
+        return classifyError(error).shouldRetry;
+    }
+    /**
+     * Get the appropriate user message for an error
+     *
+     * @param error - The error to get message for
+     * @returns User-friendly error message
+     */
+    getUserMessage(error) {
+        return classifyError(error).userMessage;
+    }
+}
+// =============================================================================
+// 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 errorHandler - Error handler for logging
+ * @param context - Description of the operation
+ * @returns Result or undefined on error
+ */
+export async function safeExecute(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        errorHandler.handleError(error, context);
+        return undefined;
+    }
+}
+/**
+ * Execute an async function that returns a reply to the user
+ *
+ * On error, returns a user-friendly error message instead.
+ *
+ * @param operation - Async function to execute that returns a message
+ * @param errorHandler - Error handler for logging
+ * @param context - Description of the operation
+ * @returns Result message or error message
+ */
+export async function safeExecuteWithReply(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        return errorHandler.handleError(error, context);
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,gBAAgB,EAChB,uBAAuB,GAExB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qBAAqB,GAEtB,MAAM,6BAA6B,CAAC;AAErC,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,+BAA+B;IAC/B,gBAAgB,EACd,0EAA0E;IAC5E,+BAA+B;IAC/B,gBAAgB,EACd,wEAAwE;IAC1E,uBAAuB;IACvB,YAAY,EACV,gFAAgF;IAClF,8BAA8B;IAC9B,aAAa,EACX,4DAA4D;IAC9D,oBAAoB;IACpB,aAAa,EACX,sEAAsE;IACxE,oBAAoB;IACpB,aAAa,EACX,0DAA0D;IAC5D,uBAAuB;IACvB,gBAAgB,EACd,qDAAqD;CAC/C,CAAC;AAIX,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACvB,iDAAiD;IACjD,wCAAuB,CAAA;IACvB,mDAAmD;IACnD,wCAAuB,CAAA;IACvB,0CAA0C;IAC1C,0CAAyB,CAAA;IACzB,iCAAiC;IACjC,gDAA+B,CAAA;IAC/B,gCAAgC;IAChC,oCAAmB,CAAA;AACrB,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AAkBD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,iCAAiC;IACjC,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtE,qCAAqC;IACrC,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,mCAAmC;IACnC,IAAI,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,sCAAsC;IACtC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,aAAa,CAAC,SAAS;YACjC,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;YACjD,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,GAAG;YACV,QAAQ,EAAE,aAAa,CAAC,SAAS;YACjC,WAAW,EAAE,mBAAmB,CAAC,aAAa;YAC9C,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,OAAO;QACL,KAAK,EAAE,GAAG;QACV,QAAQ,EAAE,aAAa,CAAC,OAAO;QAC/B,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;QACjD,WAAW,EAAE,KAAK;KACnB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,KAA4B;IACxD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,gBAAgB,CAAC,YAAY;YAChC,OAAO;gBACL,KAAK;gBACL,QAAQ,EAAE,aAAa,CAAC,UAAU;gBAClC,WAAW,EAAE,mBAAmB,CAAC,YAAY;gBAC7C,WAAW,EAAE,IAAI;gBACjB,YAAY,EAAE,IAAI,EAAE,2CAA2C;aAChE,CAAC;QAEJ,KAAK,gBAAgB,CAAC,iBAAiB,CAAC;QACxC,KAAK,gBAAgB,CAAC,aAAa;YACjC,OAAO;gBACL,KAAK;gBACL,QAAQ,EAAE,aAAa,CAAC,SAAS;gBACjC,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;gBACjD,WAAW,EAAE,IAAI;gBACjB,YAAY,EAAE,IAAI;aACnB,CAAC;QAEJ,KAAK,gBAAgB,CAAC,aAAa,CAAC;QACpC,KAAK,gBAAgB,CAAC,aAAa;YACjC,OAAO;gBACL,KAAK;gBACL,QAAQ,EAAE,aAAa,CAAC,aAAa;gBACrC,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;gBACjD,WAAW,EAAE,KAAK;aACnB,CAAC;QAEJ,KAAK,gBAAgB,CAAC,iBAAiB,CAAC;QACxC,KAAK,gBAAgB,CAAC,aAAa;YACjC,OAAO;gBACL,KAAK;gBACL,QAAQ,EAAE,aAAa,CAAC,SAAS;gBACjC,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;gBACjD,WAAW,EAAE,KAAK;aACnB,CAAC;QAEJ;YACE,OAAO;gBACL,KAAK;gBACL,QAAQ,EAAE,aAAa,CAAC,OAAO;gBAC/B,WAAW,EAAE,mBAAmB,CAAC,gBAAgB;gBACjD,WAAW,EAAE,KAAK;aACnB,CAAC;IACN,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,KAA0B;IACtD,8DAA8D;IAC9D,OAAO;QACL,KAAK;QACL,QAAQ,EAAE,aAAa,CAAC,SAAS;QACjC,WAAW,EAAE,mBAAmB,CAAC,aAAa;QAC9C,WAAW,EAAE,IAAI;QACjB,YAAY,EAAE,IAAI;KACnB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,KAAY;IAClC,MAAM,oBAAoB,GAAG;QAC3B,YAAY;QACZ,cAAc;QACd,WAAW;QACX,WAAW;QACX,WAAW;QACX,aAAa;QACb,cAAc;QACd,gBAAgB;QAChB,SAAS;QACT,sBAAsB;QACtB,aAAa;QACb,cAAc;KACf,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IAEtC,OAAO,oBAAoB,CAAC,IAAI,CAC9B,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CACvC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,KAAY;IAClC,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAE5E,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IAEtC,OAAO,eAAe,CAAC,IAAI,CACzB,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CACvC,CAAC;AACJ,CAAC;AA0BD,MAAM,qBAAqB,GAEvB;IACF,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;IACjB,iBAAiB,EAAE,CAAC;IACpB,aAAa,EAAE,WAAW;CAC3B,CAAC;AAgBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAA2B,EAC3B,UAAwB,EAAE;IAE1B,MAAM,IAAI,GAAG,EAAE,GAAG,qBAAqB,EAAE,GAAG,OAAO,EAAE,CAAC;IACtD,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,EAAE,GACtF,IAAI,CAAC;IAEP,IAAI,SAA4B,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,OAAO,OAAO,GAAG,WAAW,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;QAEV,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,qDAAqD;YACrD,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YAExC,iDAAiD;YACjD,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW;gBAC1C,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC;gBACrC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;YAE3B,IAAI,CAAC,gBAAgB,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;gBAChD,yDAAyD;gBACzD,MAAM,EAAE,KAAK,CAAC,GAAG,aAAa,6BAA6B,OAAO,aAAa,EAAE;oBAC/E,KAAK,EAAE,SAAS,CAAC,OAAO;oBACxB,QAAQ,EAAE,UAAU,CAAC,QAAQ;iBAC9B,CAAC,CAAC;gBACH,MAAM;YACR,CAAC;YAED,2CAA2C;YAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,UAAU,CAAC,YAAY,IAAI,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,GAAG,CAAC,CAAC,EACjF,UAAU,CACX,CAAC;YAEF,MAAM,EAAE,IAAI,CAAC,GAAG,aAAa,wBAAwB,KAAK,OAAO,EAAE;gBACjE,OAAO;gBACP,WAAW;gBACX,KAAK,EAAE,SAAS,CAAC,OAAO;gBACxB,QAAQ,EAAE,UAAU,CAAC,QAAQ;aAC9B,CAAC,CAAC;YAEH,uBAAuB;YACvB,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE,OAAO;KAClB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAgBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAAyB;IAC/B,SAAS,CAAS;IAC3B,WAAW,GAA+B,IAAI,GAAG,EAAE,CAAC;IAE5D,YAAY,OAA4B;QACtC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAc,EAAE,OAAe;QACzC,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAExC,0CAA0C;QAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;QAE5D,mCAAmC;QACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,OAAO,EAAE,EAAE;YAC3C,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO;YACP,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,WAAW,EAAE,UAAU,CAAC,WAAW;YACnC,YAAY,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO;YACtC,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI;YAChC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK;SAC9B,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC,WAAW,CAAC;IAChC,CAAC;IAED;;;;;;;OAOG;IACH,sBAAsB,CACpB,KAAc,EACd,OAAe,EACf,WAAmB;QAEnB,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAExC,mCAAmC;QACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,OAAO,EAAE,EAAE;YAC3C,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO;YACP,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,YAAY,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO;YACtC,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI;YAChC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK;SAC9B,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,KAAc;QACxB,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,KAAc;QAC3B,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC;IAC1C,CAAC;CACF;AAED,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAA2B,EAC3B,YAA0B,EAC1B,OAAe;IAEf,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAgC,EAChC,YAA0B,EAC1B,OAAe;IAEf,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;AACH,CAAC"}