attio-mcp 0.1.0

package/dist/utils/domain-utils.js

@@ -0,0 +1,143 @@
+/**
+ * Utility functions for domain extraction and validation
+ */
+/**
+ * Extracts domain from various input formats
+ *
+ * @param input - Input string that may contain a domain, URL, or email
+ * @returns Extracted domain or null if no valid domain found
+ * @example
+ * ```typescript
+ * extractDomain("https://example.com/path") // Returns "example.com"
+ * extractDomain("john@example.com") // Returns "example.com"
+ * extractDomain("example.com") // Returns "example.com"
+ * extractDomain("company name") // Returns null
+ * ```
+ */
+export function extractDomain(input) {
+    if (!input || typeof input !== 'string') {
+        return null;
+    }
+    // Clean up input
+    const cleanInput = input.trim().toLowerCase();
+    // Check for email format
+    const emailMatch = cleanInput.match(/^[^\s@]+@([^\s@]+\.[^\s@]+)$/);
+    if (emailMatch) {
+        return emailMatch[1];
+    }
+    // Check for URL format
+    try {
+        const url = new URL(cleanInput.startsWith('http') ? cleanInput : `https://${cleanInput}`);
+        const hostname = url.hostname;
+        // Validate that hostname looks like a domain
+        if (isValidDomain(hostname)) {
+            return normalizeDomain(hostname);
+        }
+    }
+    catch (error) {
+        // Not a valid URL, continue with other checks
+    }
+    // Check if input is already a domain
+    if (isValidDomain(cleanInput)) {
+        return normalizeDomain(cleanInput);
+    }
+    // Try to extract domain from text that might contain a domain
+    const domainPattern = /(?:https?:\/\/)?(?:www\.)?([a-zA-Z0-9-]+\.[a-zA-Z]{2,})/;
+    const match = cleanInput.match(domainPattern);
+    if (match && isValidDomain(match[1])) {
+        return normalizeDomain(match[1]);
+    }
+    return null;
+}
+/**
+ * Validates if a string is a valid domain format
+ *
+ * @param domain - Domain string to validate
+ * @returns True if domain appears valid
+ */
+export function isValidDomain(domain) {
+    if (!domain || typeof domain !== 'string') {
+        return false;
+    }
+    // Basic domain validation
+    const domainRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+    return domainRegex.test(domain) && domain.length <= 253;
+}
+/**
+ * Normalizes domain for consistent matching
+ *
+ * @param domain - Domain to normalize
+ * @returns Normalized domain
+ */
+export function normalizeDomain(domain) {
+    if (!domain) {
+        return '';
+    }
+    return domain
+        .trim()
+        .toLowerCase()
+        .replace(/^www\./, '');
+}
+/**
+ * Checks if a query likely contains a domain
+ *
+ * @param query - Search query to analyze
+ * @returns True if query appears to contain domain information
+ */
+export function hasDomainIndicators(query) {
+    if (!query) {
+        return false;
+    }
+    const indicators = [
+        /\.(com|org|net|edu|gov|mil|io|co|ai|tech|app|dev|xyz)/i,
+        /@[a-zA-Z0-9-]+\./,
+        /https?:\/\//,
+        /www\./,
+    ];
+    return indicators.some((pattern) => pattern.test(query));
+}
+/**
+ * Extracts multiple potential domains from a query
+ *
+ * @param query - Query that may contain multiple domains
+ * @returns Array of extracted domains
+ */
+export function extractAllDomains(query) {
+    if (!query) {
+        return [];
+    }
+    const domains = [];
+    // Extract email domains
+    const emailMatches = query.match(/[^\s@]+@([^\s@]+\.[^\s@]+)/g);
+    if (emailMatches) {
+        emailMatches.forEach((email) => {
+            const domain = extractDomain(email);
+            if (domain) {
+                domains.push(domain);
+            }
+        });
+    }
+    // Extract URL domains
+    const urlMatches = query.match(/https?:\/\/[^\s]+/g);
+    if (urlMatches) {
+        urlMatches.forEach((url) => {
+            const domain = extractDomain(url);
+            if (domain) {
+                domains.push(domain);
+            }
+        });
+    }
+    // Extract standalone domains (including subdomains)
+    const domainMatches = query.match(/(?:^|\s|,)([a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,})(?=\s|,|$)/g);
+    if (domainMatches) {
+        domainMatches.forEach((match) => {
+            const domain = extractDomain(match.trim().replace(/^[,\s]+/, ''));
+            if (domain) {
+                domains.push(domain);
+            }
+        });
+    }
+    // Remove duplicates and normalize
+    return [...new Set(domains.map(normalizeDomain))];
+}
+//# sourceMappingURL=domain-utils.js.map

package/dist/utils/domain-utils.js.map

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

package/dist/utils/dynamic-import.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Utility for dynamically importing ES modules
+ *
+ * This module provides a wrapper around the dynamic import() function to make it easier to
+ * work with ES modules in a Node.js environment that may be transitioning from CommonJS.
+ * It helps address common compatibility issues that arise when mixing module systems,
+ * such as "require is not defined in ES module scope" errors.
+ *
+ * Use cases:
+ * 1. Loading modules at runtime based on configuration
+ * 2. Conditional loading of modules to improve startup performance
+ * 3. Handling imports that may not be available in all environments
+ * 4. Supporting both CommonJS and ES module imports in the same codebase
+ */
+/**
+ * Dynamically imports a module in an environment-agnostic way
+ *
+ * This function wraps the standard dynamic import() with error handling and logging.
+ * It can be used to load both ES modules and CommonJS modules in an ES module context.
+ *
+ * @param moduleName - Name of the module to import (e.g., 'handlebars', './config.js')
+ * @returns Promise resolving to the imported module
+ * @throws Error if the module cannot be imported
+ *
+ * @example
+ * // Load a module dynamically
+ * const handlebars = await dynamicImport('handlebars');
+ *
+ * // Use with destructuring
+ * const { compile, registerHelper } = await dynamicImport('handlebars');
+ */
+export declare function dynamicImport(moduleName: string): Promise<any>;
+//# sourceMappingURL=dynamic-import.d.ts.map

package/dist/utils/dynamic-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.d.ts","sourceRoot":"","sources":["../../src/utils/dynamic-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAWpE"}

package/dist/utils/dynamic-import.js

@@ -0,0 +1,41 @@
+/**
+ * Utility for dynamically importing ES modules
+ *
+ * This module provides a wrapper around the dynamic import() function to make it easier to
+ * work with ES modules in a Node.js environment that may be transitioning from CommonJS.
+ * It helps address common compatibility issues that arise when mixing module systems,
+ * such as "require is not defined in ES module scope" errors.
+ *
+ * Use cases:
+ * 1. Loading modules at runtime based on configuration
+ * 2. Conditional loading of modules to improve startup performance
+ * 3. Handling imports that may not be available in all environments
+ * 4. Supporting both CommonJS and ES module imports in the same codebase
+ */
+/**
+ * Dynamically imports a module in an environment-agnostic way
+ *
+ * This function wraps the standard dynamic import() with error handling and logging.
+ * It can be used to load both ES modules and CommonJS modules in an ES module context.
+ *
+ * @param moduleName - Name of the module to import (e.g., 'handlebars', './config.js')
+ * @returns Promise resolving to the imported module
+ * @throws Error if the module cannot be imported
+ *
+ * @example
+ * // Load a module dynamically
+ * const handlebars = await dynamicImport('handlebars');
+ *
+ * // Use with destructuring
+ * const { compile, registerHelper } = await dynamicImport('handlebars');
+ */
+export async function dynamicImport(moduleName) {
+    try {
+        return await import(moduleName);
+    }
+    catch (error) {
+        console.error(`Error importing module ${moduleName}:`, error);
+        throw new Error(`Failed to import module "${moduleName}": ${error.message || 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=dynamic-import.js.map

package/dist/utils/dynamic-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.js","sourceRoot":"","sources":["../../src/utils/dynamic-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,UAAkB;IACpD,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,0BAA0B,UAAU,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,4BAA4B,UAAU,MACpC,KAAK,CAAC,OAAO,IAAI,eACnB,EAAE,CACH,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/utils/error-enhancer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Enhance an API error with value suggestions if applicable
+ */
+export declare function enhanceApiError(error: any): Error;
+/**
+ * Check if an error is a value mismatch that we can enhance
+ */
+export declare function isValueMismatchError(error: any): {
+    isMismatch: boolean;
+    fieldSlug?: string;
+    searchValue?: string;
+    errorMessage?: string;
+};
+/**
+ * Get valid values for a field (if known)
+ */
+export declare function getKnownFieldValues(fieldSlug: string): string[] | null;
+/**
+ * Add or update known field values
+ * This could be populated from Attio API discovery
+ */
+export declare function updateKnownFieldValues(fieldSlug: string, values: string[]): void;
+//# sourceMappingURL=error-enhancer.d.ts.map

package/dist/utils/error-enhancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-enhancer.d.ts","sourceRoot":"","sources":["../../src/utils/error-enhancer.ts"],"names":[],"mappings":"AAmLA;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,CAiEjD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAiCA;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CAEN"}

package/dist/utils/error-enhancer.js

@@ -0,0 +1,188 @@
+/**
+ * Enhances API errors with helpful suggestions for value mismatches
+ */
+import { ValueMatchError } from '../errors/value-match-error.js';
+import { findBestValueMatch, } from './value-matcher.js';
+import axios from 'axios';
+// Known valid values for select fields - this should ideally come from Attio API
+const KNOWN_FIELD_VALUES = {
+    type_persona: [
+        'Plastic Surgeon',
+        'Medical Spa/Aesthetics',
+        'Dermatologist',
+        'Medical Practice',
+        'Wellness Center',
+        'Cosmetic Surgery',
+        'Aesthetic Medicine',
+        'Primary Care',
+        'Specialist',
+        'Hospital',
+        'Clinic',
+    ],
+    industry: [
+        'Healthcare',
+        'Technology',
+        'Finance',
+        'Education',
+        'Retail',
+        'Manufacturing',
+        'Hospitality',
+        'Real Estate',
+        'Professional Services',
+    ],
+    stage: [
+        'Lead',
+        'Prospect',
+        'Opportunity',
+        'Customer',
+        'Churned',
+        'Qualified',
+        'Engaged',
+        'Negotiation',
+    ],
+};
+/**
+ * Parse API error to extract context
+ */
+function parseApiError(error) {
+    console.error(`[enhancer-parseApiError] --- ENTERING parseApiError ---`);
+    console.error(`[enhancer-parseApiError] error type: ${typeof error}, constructor: ${error
+        ?.constructor?.name}`);
+    if (error && typeof error === 'object') {
+        console.error(`[enhancer-parseApiError] error keys: ${JSON.stringify(Object.keys(error))}`);
+        console.error(`[enhancer-parseApiError] error.message from input: ${error.message}`);
+    }
+    const isAxios = axios.isAxiosError(error);
+    console.error(`[enhancer-parseApiError] Step 1: axios.isAxiosError(error) result: ${isAxios}`);
+    let responseExists = false;
+    let responseDataExists = false;
+    let responseDataContent = 'N/A';
+    if (isAxios && error.response) {
+        responseExists = true;
+        console.error(`[enhancer-parseApiError] Step 2: error.response exists. Keys: ${JSON.stringify(Object.keys(error.response))}`);
+        if (error.response.data) {
+            responseDataExists = true;
+            try {
+                responseDataContent = JSON.stringify(error.response.data);
+            }
+            catch (e) {
+                responseDataContent = 'Error stringifying response.data';
+            }
+            console.error(`[enhancer-parseApiError] Step 3: error.response.data exists. Type: ${typeof error
+                .response.data}, Content: ${responseDataContent}`);
+        }
+        else {
+            console.error(`[enhancer-parseApiError] Step 3: error.response.data is FALSY.`);
+        }
+    }
+    else {
+        console.error(`[enhancer-parseApiError] Step 2: error.response is FALSY or not an Axios error for this check.`);
+        console.error(`[enhancer-parseApiError] Step 3: error.response.data is FALSY (because error.response was not available).`);
+    }
+    console.error(`[enhancer-parseApiError] FINAL CHECK BEFORE CONDITION: isAxios=${isAxios}, responseExists=${responseExists}, responseDataExists=${responseDataExists}`);
+    if (isAxios &&
+        responseExists &&
+        responseDataExists &&
+        error.response &&
+        error.response.data) {
+        console.error(`[enhancer-parseApiError] --- CONDITION MET --- Processing error.response.data...`);
+        const data = error.response.data;
+        const message = typeof data.message === 'string' ? data.message : '';
+        const pathArray = Array.isArray(data.path) && data.path.length > 0 ? data.path : [];
+        const path = typeof pathArray[0] === 'string' ? pathArray[0] : undefined;
+        console.error(`[enhancer-parseApiError] Extracted from data: message='${message}', path='${path}'`);
+        if (message.includes('Unknown select option name') ||
+            message.includes('Unknown multi-select option names')) {
+            const valueMatch = message.match(/constraint: (.*)/);
+            const extractedValue = valueMatch && typeof valueMatch[1] === 'string'
+                ? valueMatch[1].split(',')[0].trim()
+                : undefined;
+            console.error(`[enhancer-parseApiError] --- RETURNING ValueMismatch context: field='${path}', value='${extractedValue}' ---`);
+            return {
+                fieldSlug: path,
+                searchValue: extractedValue,
+                errorMessage: message,
+            };
+        }
+        console.error(`[enhancer-parseApiError] --- RETURNING Non-ValueMismatch Axios context: field='${path}' ---`);
+        return { fieldSlug: path, errorMessage: message };
+    }
+    console.error(`[enhancer-parseApiError] --- CONDITION NOT MET ---`);
+    const genericErrorMessage = error && typeof error.message === 'string'
+        ? error.message
+        : 'Unknown error';
+    console.error(`[enhancer-parseApiError] Returning generic message: '${genericErrorMessage}'`);
+    return { errorMessage: genericErrorMessage };
+}
+/**
+ * Enhance an API error with value suggestions if applicable
+ */
+export function enhanceApiError(error) {
+    console.error('[enhancer] Called with error type:', error?.constructor?.name, '. Is Axios Error:', error?.isAxiosError);
+    console.error('[enhancer] Attempting to enhance error. Message property:', error?.message, '. ResponseData property:', JSON.stringify(error?.response?.data));
+    const mismatchCheck = isValueMismatchError(error);
+    console.error('[enhancer] Mismatch check result:', JSON.stringify(mismatchCheck));
+    if (mismatchCheck.isMismatch &&
+        mismatchCheck.fieldSlug &&
+        mismatchCheck.searchValue) {
+        const fieldSlug = mismatchCheck.fieldSlug;
+        const searchValue = mismatchCheck.searchValue;
+        const knownValues = KNOWN_FIELD_VALUES[fieldSlug]; // Already checked in isValueMismatchError, but good for clarity
+        console.error(`[enhancer] Value mismatch confirmed for field: ${fieldSlug}, value: ${searchValue}.`);
+        if (knownValues) {
+            console.error(`[enhancer] Attempting to find best match for '${searchValue}' in known values for '${fieldSlug}'.`);
+            const matchResult = findBestValueMatch(searchValue, knownValues);
+            console.error('[enhancer] Match result from findBestValueMatch:', JSON.stringify(matchResult));
+            console.error('[enhancer] Returning NEW ValueMatchError');
+            return new ValueMatchError(fieldSlug, searchValue, matchResult, error // Pass original Axios error for reference
+            );
+        }
+    }
+    else {
+        console.error('[enhancer] No value mismatch, or field/value not actionable. Error message from mismatchCheck:', mismatchCheck.errorMessage);
+    }
+    console.error('[enhancer] No specific enhancement applied. Returning original error.');
+    return error; // Fallback: return original error if not enhanced
+}
+/**
+ * Check if an error is a value mismatch that we can enhance
+ */
+export function isValueMismatchError(error) {
+    const context = parseApiError(error);
+    console.error('[enhancer-isValueMismatchError] Context from parseApiError:', JSON.stringify(context));
+    if (context.fieldSlug &&
+        context.searchValue &&
+        KNOWN_FIELD_VALUES[context.fieldSlug]) {
+        const knownValues = KNOWN_FIELD_VALUES[context.fieldSlug];
+        if (knownValues &&
+            !knownValues.some((v) => v.toLowerCase() === context.searchValue?.toLowerCase())) {
+            console.error(`[enhancer-isValueMismatchError] Mismatch found for field '${context.fieldSlug}', value '${context.searchValue}'.`);
+            return {
+                isMismatch: true,
+                fieldSlug: context.fieldSlug,
+                searchValue: context.searchValue,
+                errorMessage: context.errorMessage,
+            };
+        }
+    }
+    console.error('[enhancer-isValueMismatchError] No mismatch or field/value not in KNOWN_FIELD_VALUES.');
+    return { isMismatch: false, errorMessage: context.errorMessage };
+}
+/**
+ * Get valid values for a field (if known)
+ */
+export function getKnownFieldValues(fieldSlug) {
+    return KNOWN_FIELD_VALUES[fieldSlug] || null;
+}
+/**
+ * Add or update known field values
+ * This could be populated from Attio API discovery
+ */
+export function updateKnownFieldValues(fieldSlug, values) {
+    KNOWN_FIELD_VALUES[fieldSlug] = values;
+}
+// Remove locally defined ValueMatchResult and similarity functions if they were causing issues
+// interface ValueMatchResult { ... }
+// function similarity(...) { ... }
+// function editDistance(...) { ... }
+//# sourceMappingURL=error-enhancer.js.map

package/dist/utils/error-enhancer.js.map

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

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

@@ -0,0 +1,89 @@
+/**
+ * Error handling utility for creating consistent error responses
+ */
+import { AttioErrorResponse } from '../types/attio.js';
+/**
+ * Enum for categorizing different types of errors
+ */
+export declare enum ErrorType {
+    VALIDATION_ERROR = "validation_error",
+    API_ERROR = "api_error",
+    AUTHENTICATION_ERROR = "authentication_error",
+    RATE_LIMIT_ERROR = "rate_limit_error",
+    NETWORK_ERROR = "network_error",
+    NOT_FOUND_ERROR = "not_found_error",
+    SERVER_ERROR = "server_error",
+    PARAMETER_ERROR = "parameter_error",
+    SERIALIZATION_ERROR = "serialization_error",
+    FORMAT_ERROR = "format_error",
+    UNKNOWN_ERROR = "unknown_error"
+}
+/**
+ * Interface for error details with improved type safety
+ */
+export interface ErrorDetails {
+    code: number;
+    message: string;
+    type: ErrorType;
+    details?: {
+        status?: number;
+        method?: string;
+        path?: string;
+        detail?: string;
+        responseData?: Record<string, any>;
+        originalError?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Custom error class for Attio API errors
+ */
+export declare class AttioApiError extends Error {
+    status: number;
+    detail: string;
+    path: string;
+    method: string;
+    responseData: any;
+    type: ErrorType;
+    constructor(message: string, status: number, detail: string, path: string, method: string, type?: ErrorType, responseData?: any);
+}
+/**
+ * Creates a specific API error based on status code and context
+ *
+ * @param status - HTTP status code
+ * @param path - API path
+ * @param method - HTTP method
+ * @param responseData - Response data from API
+ * @returns Appropriate error instance
+ */
+export declare function createAttioError(error: any): Error;
+/**
+ * Creates a specific API error based on status code and context
+ *
+ * @param status - HTTP status code
+ * @param path - API path
+ * @param method - HTTP method
+ * @param responseData - Response data from API
+ * @returns Appropriate error instance
+ */
+export declare function createApiError(status: number, path: string, method: string, responseData?: any): Error;
+/**
+ * Format an error into a standardized response based on error type
+ *
+ * @param error - The error to format
+ * @param type - The error type
+ * @param details - Additional error details
+ * @returns Formatted error response
+ */
+export declare function formatErrorResponse(error: Error, type?: ErrorType, details?: any): any;
+/**
+ * Creates a detailed error response for API errors, suitable for returning to MCP clients
+ *
+ * @param error - The caught error
+ * @param url - The API URL that was called
+ * @param method - The HTTP method used
+ * @param responseData - Any response data received
+ * @returns Formatted error result
+ */
+export declare function createErrorResult(error: Error | any, url: string, method: string, responseData?: AttioErrorResponse): any;
+//# sourceMappingURL=error-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGvD;;GAEG;AACH,oBAAY,SAAS;IACnB,gBAAgB,qBAAqB;IACrC,SAAS,cAAc;IACvB,oBAAoB,yBAAyB;IAC7C,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;IAC/B,eAAe,oBAAoB;IACnC,YAAY,iBAAiB;IAC7B,eAAe,oBAAoB;IACnC,mBAAmB,wBAAwB;IAC3C,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACnC,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,GAAG,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;gBAGd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,SAA+B,EACrC,YAAY,GAAE,GAAQ;CAWzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,CAgBlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,GAAQ,GACrB,KAAK,CA6GP;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,IAAI,GAAE,SAAmC,EACzC,OAAO,CAAC,EAAE,GAAG,OAoGd;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,GAAG,GAAG,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,YAAY,GAAE,kBAAuB,OA8FtC"}