@iflow-mcp/attio-mcp 1.3.6

package/dist/utils/filters/relationship.js

@@ -0,0 +1,399 @@
+/**
+ * Relationship filtering utilities
+ * These utilities help create filters based on relationships between records
+ */
+// External dependencies
+import { FilterValidationError, RelationshipFilterError, ListRelationshipError, } from '../../errors/api-errors.js';
+// Internal module dependencies
+import { FilterConditionType, RelationshipType, ResourceType, ATTRIBUTES, RelationshipRateLimitError, } from './types.js';
+// import { isValidListId } from "../../validation.js";
+import { createEqualsFilter } from './builders.js';
+import { getCachedRelationshipFilter, cacheRelationshipFilter, getCachedListFilter, cacheListFilter, hashFilters, } from './cache.js';
+/**
+ * Applies rate limiting to relationship queries
+ * Throws RelationshipRateLimitError if the rate limit is exceeded
+ *
+ * @param req - Request object
+ * @param relationshipType - Type of relationship query
+ * @param isNested - Whether this is a nested relationship query
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function applyRateLimit(
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_req, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_relationshipType, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_isPrecheck) {
+    // Check the rate limit
+    // TODO: Restore when checkRelationshipQueryRateLimit is available
+    // const result = checkRelationshipQueryRateLimit(req, relationshipType, isNested);
+    // If not allowed, throw rate limit error
+    // if (!result.allowed) {
+    //   throw new RelationshipRateLimitError(
+    //     `Rate limit exceeded for ${isNested ? 'nested ' : ''}relationship query of type '${relationshipType}'. Try again in ${Math.ceil(result.msUntilReset / 1000)} seconds.`,
+    //     relationshipType,
+    //     result.resetTime,
+    //     result.msUntilReset
+    //   );
+    // }
+}
+/**
+ * Core function to create relationship-based filters
+ * This translates our internal representation to the format expected by the Attio API
+ *
+ * @param config - Relationship filter configuration
+ * @returns Filter in the format expected by Attio API
+ */
+function createRelationshipFilter(config) {
+    // Map our ResourceType to Attio API object names
+    const getObjectName = (type) => {
+        switch (type) {
+            case ResourceType.PEOPLE:
+                return 'people';
+            case ResourceType.COMPANIES:
+                return 'companies';
+            case ResourceType.LISTS:
+                return 'lists';
+            case ResourceType.RECORDS:
+                return 'records';
+            default:
+                throw new Error(`Unsupported resource type: ${type}`);
+        }
+    };
+    // The relationship field should be a custom attribute in the filter
+    return {
+        filters: [
+            {
+                attribute: {
+                    slug: ATTRIBUTES.RELATIONSHIP,
+                },
+                condition: FilterConditionType.EQUALS,
+                value: {
+                    type: config.relationshipType,
+                    target: {
+                        object: getObjectName(config.targetType),
+                        filter: config.targetFilters,
+                    },
+                },
+            },
+        ],
+        matchAny: false,
+    };
+}
+/**
+ * Creates a filter for people based on their associated company attributes
+ * Includes rate limiting for this resource-intensive operation
+ *
+ * @param companyFilter - Filters to apply to the related companies
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding people based on company attributes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createPeopleByCompanyFilter(companyFilter, req) {
+    try {
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.WORKS_AT, false);
+        }
+        // Validate company filters
+        if (!companyFilter ||
+            !companyFilter.filters ||
+            companyFilter.filters.length === 0) {
+            throw new RelationshipFilterError('Company filter must contain at least one valid filter condition', ResourceType.PEOPLE.toString(), ResourceType.COMPANIES.toString(), RelationshipType.WORKS_AT);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: ResourceType.PEOPLE,
+            targetType: ResourceType.COMPANIES,
+            relationshipType: RelationshipType.WORKS_AT,
+            targetFilters: companyFilter,
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        // Check if it's already another specialized error
+        if (error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create people-by-company filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for companies based on their associated people attributes
+ * Includes rate limiting for this resource-intensive operation
+ *
+ * @param peopleFilter - Filters to apply to the related people
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding companies based on people attributes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createCompaniesByPeopleFilter(peopleFilter, req) {
+    try {
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.EMPLOYS, false);
+        }
+        // Validate people filters
+        if (!peopleFilter ||
+            !peopleFilter.filters ||
+            peopleFilter.filters.length === 0) {
+            throw new RelationshipFilterError('People filter must contain at least one valid filter condition', ResourceType.COMPANIES.toString(), ResourceType.PEOPLE.toString(), RelationshipType.EMPLOYS);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: ResourceType.COMPANIES,
+            targetType: ResourceType.PEOPLE,
+            relationshipType: RelationshipType.EMPLOYS,
+            targetFilters: peopleFilter,
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        // Check if it's already another specialized error
+        if (error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create companies-by-people filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for records that belong to a specific list
+ * Includes rate limiting for this operation and caching for better performance
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param listId - The ID of the list to filter by
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding records that belong to the list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createRecordsByListFilter(resourceType, listId, req, useCache = true) {
+    try {
+        // Check cache first if caching is enabled
+        if (useCache) {
+            const cachedFilter = getCachedListFilter(listId, resourceType);
+            if (cachedFilter) {
+                return cachedFilter;
+            }
+        }
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.BELONGS_TO_LIST, false);
+        }
+        // Validate list ID format and security using imported function
+        // Validate list ID format and security
+        // TODO: Fix import issue with validation.js
+        if (!listId || !/^list_[a-zA-Z0-9]+$/.test(listId)) {
+            throw new ListRelationshipError('Invalid list ID format. Expected format: list_[alphanumeric]', resourceType.toString(), listId);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: resourceType,
+            targetType: ResourceType.LISTS,
+            relationshipType: RelationshipType.BELONGS_TO_LIST,
+            targetFilters: createEqualsFilter(ATTRIBUTES.LIST_ID, listId),
+        };
+        // Convert to an Attio API compatible filter
+        const result = createRelationshipFilter(relationshipConfig);
+        // Cache the result if caching is enabled
+        if (useCache) {
+            cacheListFilter(listId, resourceType, result);
+        }
+        return result;
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        // Check if it's already another specialized error
+        if (error instanceof ListRelationshipError ||
+            error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create records-by-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for finding people who work at companies in a specific list
+ * This is a nested relationship query with rate limiting and caching applied
+ *
+ * @param listId - The ID of the list that contains companies
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding people who work at companies in the specified list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createPeopleByCompanyListFilter(listId, req, useCache = true) {
+    try {
+        // Create a cache key for this nested relationship
+        const cacheKey = {
+            relationshipType: RelationshipType.WORKS_AT,
+            sourceType: ResourceType.PEOPLE,
+            targetType: ResourceType.COMPANIES,
+            targetFilterHash: '', // Will be set later
+            listId: listId,
+            isNested: true,
+        };
+        // Check cache first if caching is enabled
+        if (useCache) {
+            const cachedFilter = getCachedRelationshipFilter(cacheKey);
+            if (cachedFilter) {
+                return cachedFilter;
+            }
+        }
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.WORKS_AT, true);
+        }
+        // Validate list ID format and security using imported function
+        // Validate list ID format and security
+        // TODO: Fix import issue with validation.js
+        if (!listId || !/^list_[a-zA-Z0-9]+$/.test(listId)) {
+            throw new Error('Invalid list ID format. Expected format: list_[alphanumeric]');
+        }
+        // First, create a filter for companies in the list
+        const companiesInListFilter = createRecordsByListFilter(ResourceType.COMPANIES, listId, undefined, useCache);
+        // Update cache key with the hash of the target filter
+        cacheKey.targetFilterHash = hashFilters(companiesInListFilter);
+        // Then, create a filter for people who work at those companies
+        const result = createPeopleByCompanyFilter(companiesInListFilter);
+        // Cache the result if caching is enabled
+        if (useCache) {
+            cacheRelationshipFilter(cacheKey, result);
+        }
+        return result;
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create people-by-company-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for finding companies that have people in a specific list
+ * This is a nested relationship query with rate limiting and caching applied
+ *
+ * @param listId - The ID of the list that contains people
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding companies that have people in the specified list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createCompaniesByPeopleListFilter(listId, req, useCache = true) {
+    try {
+        // Create a cache key for this nested relationship
+        const cacheKey = {
+            relationshipType: RelationshipType.EMPLOYS,
+            sourceType: ResourceType.COMPANIES,
+            targetType: ResourceType.PEOPLE,
+            targetFilterHash: '', // Will be set later
+            listId: listId,
+            isNested: true,
+        };
+        // Check cache first if caching is enabled
+        if (useCache) {
+            const cachedFilter = getCachedRelationshipFilter(cacheKey);
+            if (cachedFilter) {
+                return cachedFilter;
+            }
+        }
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.EMPLOYS, true);
+        }
+        // Validate list ID format and security using imported function
+        // Validate list ID format and security
+        // TODO: Fix import issue with validation.js
+        if (!listId || !/^list_[a-zA-Z0-9]+$/.test(listId)) {
+            throw new Error('Invalid list ID format. Expected format: list_[alphanumeric]');
+        }
+        // First, create a filter for people in the list
+        const peopleInListFilter = createRecordsByListFilter(ResourceType.PEOPLE, listId, undefined, useCache);
+        // Update cache key with the hash of the target filter
+        cacheKey.targetFilterHash = hashFilters(peopleInListFilter);
+        // Then, create a filter for companies that have those people
+        const result = createCompaniesByPeopleFilter(peopleInListFilter);
+        // Cache the result if caching is enabled
+        if (useCache) {
+            cacheRelationshipFilter(cacheKey, result);
+        }
+        return result;
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create companies-by-people-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for records that have associated notes matching criteria
+ * Includes rate limiting for text search operations
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param textSearch - Text to search for in the notes
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding records with matching notes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export function createRecordsByNotesFilter(resourceType, textSearch, req) {
+    try {
+        // Apply rate limiting if request object is provided
+        if (req) {
+            applyRateLimit(req, RelationshipType.HAS_NOTE, false);
+        }
+        if (!textSearch || textSearch.trim() === '') {
+            throw new Error('Text search query must be provided');
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: resourceType,
+            targetType: ResourceType.LISTS, // Notes don't have a ResourceType, using LISTS as a placeholder
+            relationshipType: RelationshipType.HAS_NOTE,
+            targetFilters: {
+                filters: [
+                    {
+                        attribute: { slug: ATTRIBUTES.NOTE_CONTENT },
+                        condition: FilterConditionType.CONTAINS,
+                        value: textSearch,
+                    },
+                ],
+                matchAny: false,
+            },
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Re-throw if it's already a rate limit error
+        if (error instanceof RelationshipRateLimitError) {
+            throw error;
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create records-by-notes filter: ${errorMessage}`);
+    }
+}
+//# sourceMappingURL=relationship.js.map

package/dist/utils/filters/relationship.js.map

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

package/dist/utils/filters/timeframe-utils.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Timeframe utility functions for converting relative timeframes to date ranges
+ *
+ * This module provides type-safe date range conversion for the Attio MCP Server
+ * timeframe search functionality. All operations use UTC timezone to ensure
+ * consistent behavior across different environments.
+ *
+ * Key Features:
+ * - Type-safe relative timeframe conversion
+ * - UTC timezone handling for consistency
+ * - ISO 8601 date format output
+ * - Comprehensive validation and error handling
+ *
+ * @example
+ * ```typescript
+ * const range = getRelativeTimeframeRange('last_7_days');
+ * // Returns: { startDate: '2024-01-01T00:00:00.000Z', endDate: '2024-01-08T23:59:59.999Z' }
+ * ```
+ */
+/**
+ * Represents an absolute date range with ISO 8601 formatted dates
+ */
+export interface DateRange {
+    /** Start date in ISO 8601 format (e.g., '2024-01-01T00:00:00.000Z') */
+    readonly startDate: string;
+    /** End date in ISO 8601 format (e.g., '2024-01-01T23:59:59.999Z') */
+    readonly endDate: string;
+}
+/**
+ * Supported relative timeframe options
+ * Each timeframe is converted to an absolute date range using UTC timezone
+ */
+export type RelativeTimeframe = 'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month' | 'last_7_days' | 'last_14_days' | 'last_30_days' | 'last_90_days';
+/**
+ * Validation result for timeframe parameters
+ */
+export interface TimeframeValidation {
+    readonly isValid: boolean;
+    readonly error?: string;
+    readonly normalizedTimeframe?: RelativeTimeframe;
+}
+/**
+ * Converts a relative timeframe to an absolute date range
+ * All dates are returned in ISO 8601 format
+ *
+ * @param timeframe - The relative timeframe to convert
+ * @param timezone - Optional timezone (defaults to UTC)
+ * @returns Date range with startDate and endDate in ISO format
+ */
+export declare function getRelativeTimeframeRange(timeframe: RelativeTimeframe, _timezone?: string): DateRange;
+/**
+ * Validates if a string is a valid ISO 8601 date
+ *
+ * @param dateString - The date string to validate
+ * @returns True if valid ISO date, false otherwise
+ */
+export declare function isValidISODate(dateString: string): boolean;
+/**
+ * Validates a date range to ensure start comes before end
+ *
+ * @param startDate - Start date in ISO format
+ * @param endDate - End date in ISO format
+ * @returns True if valid range, false otherwise
+ */
+export declare function isValidDateRange(startDate: string, endDate: string): boolean;
+/**
+ * Converts user-friendly date parameters to Attio API timeframe query parameters
+ *
+ * @param params - User date parameters
+ * @returns Attio API compatible parameters
+ */
+export declare function convertDateParamsToTimeframeQuery(params: {
+    date_from?: string;
+    date_to?: string;
+    created_after?: string;
+    created_before?: string;
+    updated_after?: string;
+    updated_before?: string;
+    timeframe?: RelativeTimeframe;
+    date_field?: 'created_at' | 'updated_at';
+}): {
+    timeframe_attribute?: string;
+    start_date?: string;
+    end_date?: string;
+    date_operator?: 'greater_than' | 'less_than' | 'between' | 'equals';
+} | null;
+/**
+ * Validates a relative timeframe string against supported options
+ *
+ * @param timeframe - The timeframe string to validate
+ * @returns Validation result with error details if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateTimeframe('last_7_days');
+ * if (result.isValid) {
+ *   console.log('Valid timeframe:', result.normalizedTimeframe);
+ * } else {
+ *   console.error('Invalid timeframe:', result.error);
+ * }
+ * ```
+ */
+export declare function validateTimeframe(timeframe: string): TimeframeValidation;
+/**
+ * Validates that a date range is logical (start before end)
+ *
+ * @param startDate - Start date in ISO 8601 format
+ * @param endDate - End date in ISO 8601 format
+ * @returns true if range is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isValid = validateDateRange('2024-01-01', '2024-01-31');
+ * // Returns: true
+ * ```
+ */
+export declare function validateDateRange(startDate: string, endDate: string): boolean;
+/**
+ * Enhanced timeframe parameter conversion with comprehensive validation
+ *
+ * This function provides better error handling and type safety compared to
+ * the basic convertTimeframeParams function.
+ *
+ * @param params - Search parameters potentially containing date/timeframe fields
+ * @returns Validated timeframe query parameters or detailed error
+ *
+ * @throws {Error} With descriptive error messages for invalid parameters
+ */
+export declare function convertTimeframeParamsWithValidation(params: Record<string, unknown>): {
+    timeframe_attribute?: string;
+    start_date?: string;
+    end_date?: string;
+    date_operator?: 'greater_than' | 'less_than' | 'between' | 'equals';
+};
+//# sourceMappingURL=timeframe-utils.d.ts.map

package/dist/utils/filters/timeframe-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeframe-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/filters/timeframe-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,cAAc,GACd,cAAc,GACd,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,EAE5B,SAAS,GAAE,MAAc,GACxB,SAAS,CAwFX;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAS5E;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,UAAU,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;CAC1C,GAAG;IACF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrE,GAAG,IAAI,CAkIP;AAoCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CA4CxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAa7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IACD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrE,CAkEA"}