@iflow-mcp/attio-mcp 1.3.6

package/dist/services/value-transformer/multi-select-transformer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Multi-select transformer - wraps single values in arrays for multi-select fields
+ *
+ * Problem: LLMs commonly pass multi-select values as single strings (e.g., "Inbound")
+ * but Attio API requires array format (e.g., ["Inbound"]).
+ *
+ * Solution: Auto-detect multi-select attributes and wrap single values in arrays.
+ */
+import { TransformContext, TransformResult, AttributeMetadata } from './types.js';
+/**
+ * Check if an attribute type name indicates multi-select (legacy check)
+ * @internal Use isMultiSelectAttribute() for proper detection
+ */
+export declare function isMultiSelectTypeName(type: string): boolean;
+/**
+ * Check if an attribute is multi-select based on metadata
+ *
+ * CRITICAL: Attio's actual API format for multi-select attributes is:
+ *   { type: "select", is_multiselect: true }
+ *
+ * NOT { type: "multi_select" } as one might expect.
+ *
+ * This function checks the is_multiselect flag FIRST because:
+ * 1. Custom workspace attributes (e.g., lead_type, inbound_outbound) use type="select"
+ * 2. The is_multiselect flag is the authoritative source from Attio's API
+ * 3. Type name matching is only for backward compatibility with older schemas
+ *
+ * Issue #992: Without flag-first detection, custom multi-select attributes were
+ * not being auto-wrapped to arrays, causing API errors.
+ *
+ * @param meta - Attribute metadata from Attio API
+ * @returns true if the attribute accepts multiple values
+ */
+export declare function isMultiSelectAttribute(meta: AttributeMetadata): boolean;
+/**
+ * Check if an attribute type is multi-select
+ * @deprecated Use isMultiSelectAttribute() instead for proper detection with metadata
+ */
+export declare function isMultiSelectType(type: string): boolean;
+/**
+ * Transform a multi-select value from single string to array format
+ *
+ * @param value - The value to transform
+ * @param attributeSlug - The attribute slug
+ * @param context - Transformation context
+ * @param attributeMeta - Attribute metadata
+ * @returns Transform result
+ */
+export declare function transformMultiSelectValue(value: unknown, attributeSlug: string, context: TransformContext, attributeMeta: AttributeMetadata): Promise<TransformResult>;
+/**
+ * Check if a value needs to be wrapped for multi-select
+ * (Useful for validation without transformation)
+ * @deprecated Use needsArrayWrappingForAttribute() instead for proper detection
+ */
+export declare function needsArrayWrapping(value: unknown, attributeType: string): boolean;
+/**
+ * Check if a value needs to be wrapped for multi-select based on attribute metadata
+ * @param value - The value to check
+ * @param attributeMeta - Attribute metadata
+ * @returns true if the value needs to be wrapped in an array
+ */
+export declare function needsArrayWrappingForAttribute(value: unknown, attributeMeta: AttributeMetadata): boolean;
+//# sourceMappingURL=multi-select-transformer.d.ts.map

package/dist/services/value-transformer/multi-select-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-select-transformer.d.ts","sourceRoot":"","sources":["../../../src/services/value-transformer/multi-select-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CASvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AASD;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,gBAAgB,EACzB,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAqD1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAKT"}

package/dist/services/value-transformer/multi-select-transformer.js

@@ -0,0 +1,144 @@
+/**
+ * Multi-select transformer - wraps single values in arrays for multi-select fields
+ *
+ * Problem: LLMs commonly pass multi-select values as single strings (e.g., "Inbound")
+ * but Attio API requires array format (e.g., ["Inbound"]).
+ *
+ * Solution: Auto-detect multi-select attributes and wrap single values in arrays.
+ */
+import { debug, OperationType } from '../../utils/logger.js';
+/**
+ * Multi-select attribute types that require array values (legacy type names)
+ */
+const MULTI_SELECT_TYPES = ['multi_select', 'multi-select', 'multiselect'];
+/**
+ * Check if an attribute type name indicates multi-select (legacy check)
+ * @internal Use isMultiSelectAttribute() for proper detection
+ */
+export function isMultiSelectTypeName(type) {
+    return MULTI_SELECT_TYPES.includes(type.toLowerCase().replace(/[_-]/g, ''));
+}
+/**
+ * Check if an attribute is multi-select based on metadata
+ *
+ * CRITICAL: Attio's actual API format for multi-select attributes is:
+ *   { type: "select", is_multiselect: true }
+ *
+ * NOT { type: "multi_select" } as one might expect.
+ *
+ * This function checks the is_multiselect flag FIRST because:
+ * 1. Custom workspace attributes (e.g., lead_type, inbound_outbound) use type="select"
+ * 2. The is_multiselect flag is the authoritative source from Attio's API
+ * 3. Type name matching is only for backward compatibility with older schemas
+ *
+ * Issue #992: Without flag-first detection, custom multi-select attributes were
+ * not being auto-wrapped to arrays, causing API errors.
+ *
+ * @param meta - Attribute metadata from Attio API
+ * @returns true if the attribute accepts multiple values
+ */
+export function isMultiSelectAttribute(meta) {
+    // IMPORTANT: Check is_multiselect flag first - this is Attio's authoritative format
+    // Custom workspace attributes have type="select" but is_multiselect=true
+    if (meta.is_multiselect === true) {
+        return true;
+    }
+    // Fallback to type name matching for backward compatibility only
+    // (handles edge cases where schema lacks the is_multiselect field)
+    return isMultiSelectTypeName(meta.type);
+}
+/**
+ * Check if an attribute type is multi-select
+ * @deprecated Use isMultiSelectAttribute() instead for proper detection with metadata
+ */
+export function isMultiSelectType(type) {
+    return isMultiSelectTypeName(type);
+}
+/**
+ * Check if a value is already an array
+ */
+function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * Transform a multi-select value from single string to array format
+ *
+ * @param value - The value to transform
+ * @param attributeSlug - The attribute slug
+ * @param context - Transformation context
+ * @param attributeMeta - Attribute metadata
+ * @returns Transform result
+ */
+export async function transformMultiSelectValue(value, attributeSlug, context, attributeMeta) {
+    // Only transform multi-select attributes (check is_multiselect flag OR type name)
+    if (!isMultiSelectAttribute(attributeMeta)) {
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Skip if already an array
+    if (isArray(value)) {
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Skip null/undefined values
+    if (value === null || value === undefined) {
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Wrap single value in array
+    const transformedValue = [value];
+    debug('multi-select-transformer', `Wrapped single value in array for multi-select`, {
+        attribute: attributeSlug,
+        from: value,
+        to: transformedValue,
+        resourceType: context.resourceType,
+        detectedVia: attributeMeta.is_multiselect
+            ? 'is_multiselect flag'
+            : 'type name',
+    }, 'transformMultiSelectValue', OperationType.DATA_PROCESSING);
+    return {
+        transformed: true,
+        originalValue: value,
+        transformedValue,
+        description: `Wrapped single value "${value}" in array for multi-select field ${attributeSlug}`,
+    };
+}
+/**
+ * Check if a value needs to be wrapped for multi-select
+ * (Useful for validation without transformation)
+ * @deprecated Use needsArrayWrappingForAttribute() instead for proper detection
+ */
+export function needsArrayWrapping(value, attributeType) {
+    if (!isMultiSelectTypeName(attributeType))
+        return false;
+    if (isArray(value))
+        return false;
+    if (value === null || value === undefined)
+        return false;
+    return true;
+}
+/**
+ * Check if a value needs to be wrapped for multi-select based on attribute metadata
+ * @param value - The value to check
+ * @param attributeMeta - Attribute metadata
+ * @returns true if the value needs to be wrapped in an array
+ */
+export function needsArrayWrappingForAttribute(value, attributeMeta) {
+    if (!isMultiSelectAttribute(attributeMeta))
+        return false;
+    if (isArray(value))
+        return false;
+    if (value === null || value === undefined)
+        return false;
+    return true;
+}
+//# sourceMappingURL=multi-select-transformer.js.map

package/dist/services/value-transformer/multi-select-transformer.js.map

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

package/dist/services/value-transformer/record-reference-transformer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Record-reference transformer - formats record IDs to Attio's expected format
+ *
+ * Issue #997: Record-reference attributes like people.company or deals.associated_people
+ * require a specific format: [{ target_object: "companies", target_record_id: "uuid" }]
+ *
+ * Problem: Users commonly pass:
+ * - Simple string ID: "company-uuid"
+ * - Legacy object: { record_id: "uuid" }
+ * - Incomplete object: { target_record_id: "uuid" } (missing target_object)
+ *
+ * Solution: Auto-detect record-reference attributes and format to Attio's expected structure.
+ */
+import { TransformContext, TransformResult, AttributeMetadata, RecordReferenceValue } from './types.js';
+/**
+ * Check if an attribute type is a record-reference
+ */
+export declare function isRecordReferenceType(type: string): boolean;
+/**
+ * Check if a value is already in the correct Attio record-reference format
+ * Exported for reuse in mayNeedTransformation() to avoid duplication
+ */
+export declare function isCorrectRecordReferenceFormat(value: unknown): value is RecordReferenceValue[];
+/**
+ * Transform a record-reference value to Attio API format
+ *
+ * @param value - The value to transform
+ * @param field - The field/attribute slug
+ * @param context - Transformation context
+ * @param attrMeta - Attribute metadata
+ * @returns Transform result
+ */
+export declare function transformRecordReferenceValue(value: unknown, field: string, context: TransformContext, attrMeta: AttributeMetadata): Promise<TransformResult>;
+/**
+ * Check if a value needs record-reference formatting
+ * Useful for validation without transformation
+ *
+ * @param value - The value to check
+ * @param attrMeta - Attribute metadata
+ * @returns true if the value needs formatting
+ */
+export declare function needsRecordReferenceFormatting(value: unknown, attrMeta: AttributeMetadata): boolean;
+//# sourceMappingURL=record-reference-transformer.d.ts.map

package/dist/services/value-transformer/record-reference-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-reference-transformer.d.ts","sourceRoot":"","sources":["../../../src/services/value-transformer/record-reference-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAoBpB;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,EAAE,CAcjC;AA2FD;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA2H1B;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAKT"}

package/dist/services/value-transformer/record-reference-transformer.js

@@ -0,0 +1,245 @@
+/**
+ * Record-reference transformer - formats record IDs to Attio's expected format
+ *
+ * Issue #997: Record-reference attributes like people.company or deals.associated_people
+ * require a specific format: [{ target_object: "companies", target_record_id: "uuid" }]
+ *
+ * Problem: Users commonly pass:
+ * - Simple string ID: "company-uuid"
+ * - Legacy object: { record_id: "uuid" }
+ * - Incomplete object: { target_record_id: "uuid" } (missing target_object)
+ *
+ * Solution: Auto-detect record-reference attributes and format to Attio's expected structure.
+ */
+import { debug, OperationType } from '../../utils/logger.js';
+/**
+ * Mapping from field names to their target object types
+ * Used as fallback when relationship metadata is not available
+ */
+const FIELD_TO_TARGET_OBJECT = {
+    company: 'companies',
+    associated_company: 'companies',
+    associated_companies: 'companies',
+    main_contact: 'people',
+    associated_people: 'people',
+    associated_person: 'people',
+    person: 'people',
+    people: 'people',
+    owner: 'workspace-members', // Note: owner might be workspace-member, not people
+    assignee: 'workspace-members',
+};
+/**
+ * Check if an attribute type is a record-reference
+ */
+export function isRecordReferenceType(type) {
+    return type === 'record-reference';
+}
+/**
+ * Check if a value is already in the correct Attio record-reference format
+ * Exported for reuse in mayNeedTransformation() to avoid duplication
+ */
+export function isCorrectRecordReferenceFormat(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length === 0)
+        return true; // Empty array is valid (clears the field)
+    // Check first element has both required fields
+    const first = value[0];
+    return (first &&
+        typeof first === 'object' &&
+        'target_object' in first &&
+        'target_record_id' in first &&
+        typeof first.target_object === 'string' &&
+        typeof first.target_record_id === 'string');
+}
+/**
+ * Infer the target object type from field name or metadata
+ */
+function inferTargetObject(field, metadata) {
+    // Priority 1: Use relationship.object from metadata (authoritative)
+    if (metadata.relationship?.object) {
+        return metadata.relationship.object;
+    }
+    // Priority 2: Infer from field name (fallback - log for monitoring)
+    const fieldLower = field.toLowerCase();
+    for (const [pattern, target] of Object.entries(FIELD_TO_TARGET_OBJECT)) {
+        if (fieldLower === pattern || fieldLower.includes(pattern)) {
+            // Log when using fallback inference to help identify fields that
+            // should have relationship metadata added to the Attio schema
+            debug('record-reference-transformer', `Using fallback field-name inference: ${field} → ${target}`, { field, pattern, inferredTarget: target }, 'inferTargetObject', OperationType.DATA_PROCESSING);
+            return target;
+        }
+    }
+    return null;
+}
+/**
+ * Extract record ID from various input formats
+ *
+ * Returns null for:
+ * - null/undefined values
+ * - Empty strings or whitespace-only strings
+ * - Objects without recognizable ID fields (record_id, target_record_id, id)
+ *
+ * Returning null causes the item to be filtered out of arrays or
+ * triggers a "Could not extract record ID" error for single values,
+ * rather than creating invalid record references.
+ */
+function extractRecordId(item) {
+    // String: "uuid" → "uuid"
+    if (typeof item === 'string') {
+        return item.trim() || null;
+    }
+    // Object formats
+    if (item && typeof item === 'object') {
+        const obj = item;
+        // Already correct format: { target_record_id: "uuid" }
+        if (typeof obj.target_record_id === 'string') {
+            return obj.target_record_id;
+        }
+        // Legacy format: { record_id: "uuid" }
+        if (typeof obj.record_id === 'string') {
+            return obj.record_id;
+        }
+        // Sometimes: { id: "uuid" }
+        if (typeof obj.id === 'string') {
+            return obj.id;
+        }
+    }
+    return null;
+}
+/**
+ * Transform a single value to record-reference format
+ */
+function transformSingleValue(item, targetObject) {
+    const recordId = extractRecordId(item);
+    if (!recordId)
+        return null;
+    return {
+        target_object: targetObject,
+        target_record_id: recordId,
+    };
+}
+/**
+ * Transform a record-reference value to Attio API format
+ *
+ * @param value - The value to transform
+ * @param field - The field/attribute slug
+ * @param context - Transformation context
+ * @param attrMeta - Attribute metadata
+ * @returns Transform result
+ */
+export async function transformRecordReferenceValue(value, field, context, attrMeta) {
+    // Only transform record-reference attributes
+    if (!isRecordReferenceType(attrMeta.type)) {
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Skip null/undefined values
+    if (value === null || value === undefined) {
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Skip if already in correct format
+    if (isCorrectRecordReferenceFormat(value)) {
+        debug('record-reference-transformer', `Value already in correct format, skipping`, {
+            field,
+            resourceType: context.resourceType,
+        }, 'transformRecordReferenceValue', OperationType.DATA_PROCESSING);
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+        };
+    }
+    // Determine target object type
+    const targetObject = inferTargetObject(field, attrMeta);
+    if (!targetObject) {
+        debug('record-reference-transformer', `Could not determine target object for field ${field}, skipping transformation`, {
+            field,
+            resourceType: context.resourceType,
+            metadataRelationship: attrMeta.relationship,
+        }, 'transformRecordReferenceValue', OperationType.DATA_PROCESSING);
+        return {
+            transformed: false,
+            originalValue: value,
+            transformedValue: value,
+            description: `Could not determine target object for record-reference field ${field}`,
+        };
+    }
+    // Transform based on input type
+    let transformedValue;
+    if (Array.isArray(value)) {
+        // Array of values (strings or objects)
+        const transformed = [];
+        for (const item of value) {
+            const ref = transformSingleValue(item, targetObject);
+            if (ref) {
+                transformed.push(ref);
+            }
+        }
+        // CRITICAL (Issue #997): Don't silently clear on all-invalid input
+        // If user passes [null, '', {}], we should NOT return [] and clear the field.
+        // Instead, return transformed: false with an error message.
+        // User must pass [] explicitly to clear a record-reference field.
+        if (transformed.length === 0 && value.length > 0) {
+            return {
+                transformed: false,
+                originalValue: value,
+                transformedValue: value,
+                description: `Could not extract any valid record IDs from array for field ${field}. ` +
+                    `Received ${value.length} item(s), all invalid. Pass [] explicitly to clear the field.`,
+            };
+        }
+        transformedValue = transformed;
+    }
+    else {
+        // Single value (string or object)
+        const ref = transformSingleValue(value, targetObject);
+        if (!ref) {
+            return {
+                transformed: false,
+                originalValue: value,
+                transformedValue: value,
+                description: `Could not extract record ID from value for field ${field}`,
+            };
+        }
+        transformedValue = [ref];
+    }
+    debug('record-reference-transformer', `Transformed record-reference value`, {
+        field,
+        targetObject,
+        originalType: Array.isArray(value) ? 'array' : typeof value,
+        transformedCount: transformedValue.length,
+        resourceType: context.resourceType,
+    }, 'transformRecordReferenceValue', OperationType.DATA_PROCESSING);
+    return {
+        transformed: true,
+        originalValue: value,
+        transformedValue,
+        description: `Formatted ${field} as record-reference array with target_object="${targetObject}"`,
+    };
+}
+/**
+ * Check if a value needs record-reference formatting
+ * Useful for validation without transformation
+ *
+ * @param value - The value to check
+ * @param attrMeta - Attribute metadata
+ * @returns true if the value needs formatting
+ */
+export function needsRecordReferenceFormatting(value, attrMeta) {
+    if (!isRecordReferenceType(attrMeta.type))
+        return false;
+    if (value === null || value === undefined)
+        return false;
+    if (isCorrectRecordReferenceFormat(value))
+        return false;
+    return true;
+}
+//# sourceMappingURL=record-reference-transformer.js.map

package/dist/services/value-transformer/record-reference-transformer.js.map

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

package/dist/services/value-transformer/select-transformer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Select transformer - converts select option titles to ["title"] array format
+ *
+ * Problem: LLMs commonly pass select values as human-readable strings
+ * (e.g., "Technology", "Potential Customer") but Attio API requires
+ * array format: ["title"]
+ *
+ * Solution: Auto-detect single-select attributes (type="select" AND
+ * is_multiselect !== true) and transform string titles to title arrays.
+ *
+ * NOTE: Attio API accepts ["title"] format and silently rejects ["uuid"] format
+ * despite returning HTTP 200 OK (Issue #1045). This transformer uses titles.
+ *
+ * @see Issue #1019, #1045
+ */
+import { TransformContext, TransformResult, AttributeMetadata } from './types.js';
+/**
+ * Clear all cached select options (for testing)
+ */
+export declare function clearSelectCache(): void;
+/**
+ * Transform a select value from string title to ["title"] array format
+ *
+ * Supports:
+ * - Case-insensitive title matching: "technology" → ["Technology"]
+ * - Partial matching: "Tech" → ["Technology"] (if matches "Technology")
+ * - UUID pass-through: "uuid-string" → ["uuid-string"] (no API lookup)
+ * - Error suggestions: Lists valid options on invalid input
+ *
+ * NOTE: Uses ["title"] format not ["uuid"] because Attio API silently
+ * rejects UUID arrays despite returning HTTP 200 OK (Issue #1045).
+ *
+ * @param value - The value to transform
+ * @param attributeSlug - The attribute slug
+ * @param context - Transformation context
+ * @param attributeMeta - Attribute metadata (must be single-select)
+ * @returns Transform result with ["title"] array format
+ */
+export declare function transformSelectValue(value: unknown, attributeSlug: string, context: TransformContext, attributeMeta: AttributeMetadata): Promise<TransformResult>;
+/**
+ * Get valid select options for error messages
+ *
+ * @param objectSlug - Object slug
+ * @param attributeSlug - Attribute slug
+ * @returns Array of valid option titles
+ */
+export declare function getValidSelectOptions(objectSlug: string, attributeSlug: string): Promise<string[]>;
+//# sourceMappingURL=select-transformer.d.ts.map

package/dist/services/value-transformer/select-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-transformer.d.ts","sourceRoot":"","sources":["../../../src/services/value-transformer/select-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAgCpB;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAqKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,gBAAgB,EACzB,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAoF1B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB"}