attio-mcp 1.3.5 → 1.4.0

package/dist/services/skill-generator/WorkspaceSchemaService.js

@@ -0,0 +1,292 @@
+/**
+ * Service for fetching and aggregating Attio workspace schema data
+ *
+ * This service orchestrates calls to existing services to build a complete
+ * workspace schema including objects, attributes, select options, and metadata.
+ *
+ * @see Issue #983
+ */
+import { getObjectAttributeMetadata } from '../../api/attribute-types.js';
+import { getLazyAttioClient } from '../../api/lazy-client.js';
+import { AttributeOptionsService } from '../../services/metadata/AttributeOptionsService.js';
+import { debug as logDebug, error as logError, warn as logWarn, } from '../../utils/logger.js';
+/**
+ * Type guard to check if an ID is a nested option ID object
+ * Attio API returns option IDs as nested objects: {workspace_id, object_id, attribute_id, option_id}
+ * @param id - The ID value to check
+ * @returns True if the ID is a nested option ID object
+ * @see Issue #1014
+ */
+function isNestedOptionId(id) {
+    return typeof id === 'object' && id !== null && 'option_id' in id;
+}
+/**
+ * Generates a slug-style value from an option title
+ * Converts "Existing Customer" → "existing_customer"
+ * @param title - The option title
+ * @returns Slug-style value
+ * @see Issue #1014
+ */
+function generateOptionValue(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_') // Replace non-alphanumeric with underscore
+        .replace(/^_+|_+$/g, ''); // Trim leading/trailing underscores
+}
+/**
+ * Service for fetching complete workspace schema data
+ *
+ * Note: API key flows through getLazyAttioClient() from environment/context,
+ * not through constructor dependency injection.
+ */
+export class WorkspaceSchemaService {
+    /**
+     * Creates a new WorkspaceSchemaService
+     */
+    constructor() {
+        // No parameters needed - API key flows through getLazyAttioClient()
+    }
+    /**
+     * Fetches the display title for an object from the Attio API
+     *
+     * @param objectSlug - Object API slug (e.g., 'companies', 'custom_prospecting_list')
+     * @returns The object title from Attio, or null if fetch fails
+     * @see Issue #1017
+     */
+    async fetchObjectTitle(objectSlug) {
+        try {
+            const client = getLazyAttioClient();
+            const response = await client.get(`/objects/${objectSlug}`);
+            const obj = response?.data?.data || response?.data;
+            return obj?.title || null;
+        }
+        catch {
+            logDebug('WorkspaceSchemaService', `Could not fetch title for ${objectSlug}, using fallback`, { objectSlug });
+            return null;
+        }
+    }
+    getOptionFetchDelayMs(options) {
+        const optionFetchDelayMs = options.optionFetchDelayMs;
+        if (optionFetchDelayMs === undefined)
+            return 100;
+        if (typeof optionFetchDelayMs !== 'number' ||
+            !Number.isFinite(optionFetchDelayMs) ||
+            optionFetchDelayMs < 0) {
+            return 100;
+        }
+        return optionFetchDelayMs;
+    }
+    /**
+     * Fetches complete workspace schema for specified objects
+     *
+     * This method implements graceful degradation:
+     * - If an object fails to fetch, it logs the error and continues with other objects
+     * - If an attribute's options fail to fetch, it includes the attribute without options
+     *
+     * @param objectSlugs - Array of object slugs to fetch (e.g., ['companies', 'people'])
+     * @param options - Fetching options (max options, include archived)
+     * @returns Complete workspace schema
+     */
+    async fetchSchema(objectSlugs, options) {
+        const objects = [];
+        for (const objectSlug of objectSlugs) {
+            try {
+                const objectSchema = await this.fetchObjectSchema(objectSlug, options);
+                objects.push(objectSchema);
+            }
+            catch (error) {
+                logError('WorkspaceSchemaService', `Failed to fetch schema for ${objectSlug}`, error instanceof Error ? error : new Error(String(error)), { objectSlug });
+                // Continue processing other objects despite error
+            }
+        }
+        return {
+            metadata: {
+                generatedAt: new Date().toISOString(),
+                workspace: 'attio', // Could be enhanced to fetch actual workspace name
+                objects: objectSlugs,
+            },
+            objects,
+        };
+    }
+    /**
+     * Fetches schema for a single object
+     *
+     * @param objectSlug - Object slug (e.g., 'companies', 'people', 'deals')
+     * @param options - Fetching options
+     * @returns Object schema with all attributes and metadata
+     */
+    async fetchObjectSchema(objectSlug, options) {
+        const optionFetchDelayMs = this.getOptionFetchDelayMs(options);
+        const PHASE1_OBJECTS = ['companies', 'people', 'deals'];
+        // 1. Fetch object title from API for custom objects (Issue #1017)
+        // Skip API call for Phase 1 objects - they have hardcoded display names
+        const objectTitle = PHASE1_OBJECTS.includes(objectSlug)
+            ? null
+            : await this.fetchObjectTitle(objectSlug);
+        // 2. Fetch attribute metadata (uses existing 15min TTL cache)
+        const metadataMap = await getObjectAttributeMetadata(objectSlug);
+        // 3. Convert metadata to AttributeSchema array
+        const attributes = [];
+        for (const [apiSlug, metadata] of metadataMap.entries()) {
+            const attributeSchema = {
+                apiSlug,
+                displayName: metadata.title,
+                type: metadata.type,
+                isMultiselect: metadata.is_multiselect || false,
+                isUnique: metadata.is_unique || false,
+                isRequired: metadata.is_required || false,
+                isWritable: metadata.is_writable !== false, // Default to true
+                description: metadata.description,
+            };
+            // 4. Fetch options for select/status attributes
+            if (this.isOptionBasedAttribute(metadata.type)) {
+                try {
+                    const optionsResult = await AttributeOptionsService.getOptions(objectSlug, apiSlug, options.includeArchived);
+                    // Apply truncation
+                    const totalOptions = optionsResult.options.length;
+                    const truncated = totalOptions > options.maxOptionsPerAttribute;
+                    attributeSchema.options = optionsResult.options
+                        .slice(0, options.maxOptionsPerAttribute)
+                        .map((opt) => ({
+                        // Handle nested ID objects from Attio API
+                        // API returns: { workspace_id, object_id, attribute_id, option_id }
+                        id: isNestedOptionId(opt.id)
+                            ? opt.id.option_id
+                            : typeof opt.id === 'string'
+                                ? opt.id
+                                : '',
+                        title: opt.title,
+                        // Generate slug-style value from title since Attio API doesn't provide it
+                        // "Existing Customer" → "existing_customer"
+                        value: generateOptionValue(opt.title),
+                        isArchived: 'is_archived' in opt ? opt.is_archived : false,
+                    }));
+                    attributeSchema.optionsTruncated = truncated;
+                    attributeSchema.totalOptions = totalOptions;
+                    // Rate limiting: Add delay between option fetches
+                    if (optionFetchDelayMs > 0) {
+                        await new Promise((resolve) => setTimeout(resolve, optionFetchDelayMs));
+                    }
+                }
+                catch (error) {
+                    // Log warning but don't fail - attribute can still be documented
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logWarn('WorkspaceSchemaService', `No options available for ${objectSlug}.${apiSlug}`, { objectSlug, attributeSlug: apiSlug, errorMessage });
+                }
+            }
+            // 5. Add complex type structures
+            if (this.isComplexType(metadata.type)) {
+                attributeSchema.complexTypeStructure = this.getComplexTypeStructure(metadata.type);
+            }
+            // 6. Add relationship metadata (only when we have real data)
+            if (metadata.relationship?.object && metadata.relationship?.cardinality) {
+                attributeSchema.relationship = {
+                    targetObject: metadata.relationship.object,
+                    cardinality: metadata.relationship.cardinality,
+                };
+            }
+            attributes.push(attributeSchema);
+        }
+        return {
+            objectSlug,
+            displayName: this.getDisplayName(objectSlug, objectTitle),
+            attributes,
+        };
+    }
+    /**
+     * Checks if an attribute type supports options (select, status, multi-select)
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute supports options
+     */
+    isOptionBasedAttribute(type) {
+        return ['select', 'status', 'multi-select'].includes(type);
+    }
+    /**
+     * Checks if an attribute type is a complex type requiring structure documentation
+     *
+     * @param type - Attribute type from Attio API
+     * @returns True if attribute is a complex type
+     */
+    isComplexType(type) {
+        return [
+            'location',
+            'personal-name',
+            'phone-number',
+            'email-address',
+        ].includes(type);
+    }
+    /**
+     * Gets the structure definition for complex attribute types
+     *
+     * @param type - Complex attribute type
+     * @returns Structure definition with field types
+     */
+    getComplexTypeStructure(type) {
+        switch (type) {
+            case 'location':
+                return {
+                    line_1: 'string | null (street address)',
+                    line_2: 'string | null (apt/suite)',
+                    line_3: 'string | null (additional)',
+                    line_4: 'string | null (additional)',
+                    locality: 'string | null (city)',
+                    region: 'string | null (state/province)',
+                    postcode: 'string | null (ZIP/postal code)',
+                    country_code: 'string | null (ISO country code)',
+                    latitude: 'number | null (coordinates)',
+                    longitude: 'number | null (coordinates)',
+                };
+            case 'personal-name':
+                return {
+                    first_name: 'string (required)',
+                    last_name: 'string | null',
+                    middle_name: 'string | null',
+                    title: 'string | null (e.g., "Dr.", "Prof.")',
+                    full_name: 'string (auto-generated, read-only)',
+                };
+            case 'phone-number':
+                return {
+                    country_code: 'string (e.g., "+1")',
+                    number: 'string (digits only)',
+                    original_number: 'string (as provided)',
+                };
+            case 'email-address':
+                return {
+                    email_address: 'string (valid email format)',
+                };
+            default:
+                return {};
+        }
+    }
+    /**
+     * Gets human-readable display name for an object slug
+     *
+     * Uses the fetched title from Attio API if available, otherwise falls back
+     * to hardcoded display names for Phase 1 objects or slug capitalization.
+     *
+     * @param objectSlug - Object API slug
+     * @param fetchedTitle - Title fetched from Attio API (optional)
+     * @returns Human-readable display name
+     * @see Issue #1017
+     */
+    getDisplayName(objectSlug, fetchedTitle) {
+        // Use API-fetched title if available
+        if (fetchedTitle) {
+            return fetchedTitle;
+        }
+        // Fallback to hardcoded display names for Phase 1 objects
+        const displayNames = {
+            companies: 'Companies',
+            people: 'People',
+            deals: 'Deals',
+        };
+        // If not in map, title-case the slug (replace underscores with spaces)
+        return (displayNames[objectSlug] ||
+            objectSlug
+                .split('_')
+                .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+                .join(' '));
+    }
+}
+//# sourceMappingURL=WorkspaceSchemaService.js.map

package/dist/services/skill-generator/WorkspaceSchemaService.js.map

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

package/dist/services/skill-generator/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Workspace Schema Skill Generator
+ *
+ * Exports services and types for generating Claude Skills from Attio workspace schemas.
+ *
+ * @see Issue #983
+ */
+export { WorkspaceSchemaService } from './WorkspaceSchemaService.js';
+export { SchemaFormatterService } from './SchemaFormatterService.js';
+export { OutputWriterService } from './OutputWriterService.js';
+export type { GenerateSkillConfig, WorkspaceSchema, ObjectSchema, AttributeSchema, AttributeOption, FormattedOutput, SkillOutput, FetchSchemaOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/skill-generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/skill-generator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,WAAW,EACX,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/services/skill-generator/index.js

@@ -0,0 +1,11 @@
+/**
+ * Workspace Schema Skill Generator
+ *
+ * Exports services and types for generating Claude Skills from Attio workspace schemas.
+ *
+ * @see Issue #983
+ */
+export { WorkspaceSchemaService } from './WorkspaceSchemaService.js';
+export { SchemaFormatterService } from './SchemaFormatterService.js';
+export { OutputWriterService } from './OutputWriterService.js';
+//# sourceMappingURL=index.js.map

package/dist/services/skill-generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/skill-generator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/services/skill-generator/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Type definitions for the Workspace Schema Skill Generator
+ *
+ * These types support the generation of Claude Skills from Attio workspace schemas,
+ * addressing the common issue where LLMs make errors due to unknown attribute values.
+ *
+ * @see Issue #983
+ */
+/**
+ * Configuration for the generate-skill CLI command
+ */
+export interface GenerateSkillConfig {
+    /** Object slugs to include in the generated skill */
+    objects: string[];
+    /** Output format: Claude Skill, plain Markdown, or JSON */
+    format: 'skill' | 'markdown' | 'json';
+    /** Output directory path */
+    outputDir: string;
+    /** Whether to package output as ZIP file */
+    zip: boolean;
+    /** Maximum options to display per attribute (default: 20) */
+    maxOptionsPerAttribute: number;
+    /** Whether to include archived options */
+    includeArchived: boolean;
+    /** Delay between attribute option fetches in milliseconds (default: 100) */
+    optionFetchDelayMs?: number;
+    /** Attio API key for authentication */
+    apiKey: string;
+}
+/**
+ * Complete workspace schema containing multiple objects
+ */
+export interface WorkspaceSchema {
+    /** Metadata about the schema generation */
+    metadata: {
+        /** ISO 8601 timestamp when schema was generated */
+        generatedAt: string;
+        /** Workspace identifier or name */
+        workspace: string;
+        /** List of object slugs included in this schema */
+        objects: string[];
+    };
+    /** Array of object schemas */
+    objects: ObjectSchema[];
+}
+/**
+ * Schema for a single Attio object (companies, people, deals, etc.)
+ */
+export interface ObjectSchema {
+    /** API slug of the object (e.g., 'companies', 'people') */
+    objectSlug: string;
+    /** Human-readable display name (e.g., 'Companies', 'People') */
+    displayName: string;
+    /** Array of attribute schemas for this object */
+    attributes: AttributeSchema[];
+}
+/**
+ * Schema for a single attribute within an object
+ */
+export interface AttributeSchema {
+    /** API slug used in API calls (e.g., 'team_size', 'industry') */
+    apiSlug: string;
+    /** Display name shown in Attio UI */
+    displayName: string;
+    /** Attribute type (e.g., 'text', 'select', 'location', 'personal-name') */
+    type: string;
+    /** Whether this attribute accepts multiple values */
+    isMultiselect: boolean;
+    /** Whether this attribute has a uniqueness constraint */
+    isUnique: boolean;
+    /** Whether this attribute is required for record creation */
+    isRequired: boolean;
+    /** Whether this attribute can be modified */
+    isWritable: boolean;
+    /** Optional description of the attribute's purpose */
+    description?: string;
+    /** For select/status attributes: array of valid options */
+    options?: AttributeOption[];
+    /** Whether options were truncated due to maxOptionsPerAttribute limit */
+    optionsTruncated?: boolean;
+    /** Total number of options available (before truncation) */
+    totalOptions?: number;
+    /** For complex types: structure definition with field types */
+    complexTypeStructure?: Record<string, unknown>;
+    /** For relationship attributes: target object and cardinality */
+    relationship?: {
+        /** Target object slug (e.g., 'companies', 'people') */
+        targetObject: string;
+        /** Relationship cardinality */
+        cardinality: string;
+    };
+}
+/**
+ * A single option for select or status attributes
+ */
+export interface AttributeOption {
+    /** Unique identifier for this option */
+    id: string;
+    /** Display title shown in Attio UI */
+    title: string;
+    /** API value used in API calls */
+    value: string;
+    /** Whether this option is archived */
+    isArchived?: boolean;
+}
+/**
+ * Formatted output ready for writing to disk
+ */
+export interface FormattedOutput {
+    /** Output format type */
+    format: 'skill' | 'markdown' | 'json';
+    /** Map of relative file paths to file contents */
+    files: Record<string, string>;
+}
+/**
+ * Result of writing skill output to disk
+ */
+export interface SkillOutput {
+    /** Output format that was written */
+    format: 'skill' | 'markdown' | 'json';
+    /** Absolute path to the output directory or file */
+    path: string;
+    /** List of files that were created */
+    files: string[];
+}
+/**
+ * Options for fetching object schema
+ */
+export interface FetchSchemaOptions {
+    /** Maximum options to retrieve per attribute */
+    maxOptionsPerAttribute: number;
+    /** Whether to include archived options */
+    includeArchived: boolean;
+    /** Delay between attribute option fetches in milliseconds (default: 100) */
+    optionFetchDelayMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/skill-generator/types.d.ts.map

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

package/dist/services/skill-generator/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for the Workspace Schema Skill Generator
+ *
+ * These types support the generation of Claude Skills from Attio workspace schemas,
+ * addressing the common issue where LLMs make errors due to unknown attribute values.
+ *
+ * @see Issue #983
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/skill-generator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/skill-generator/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/services/update/FieldPersistenceHandler.d.ts

@@ -0,0 +1,101 @@
+/**
+ * FieldPersistenceHandler - Post-update field verification
+ *
+ * Extracted from UniversalUpdateService to separate verification concerns.
+ * Handles field persistence checking with configurable strictness.
+ *
+ * **Verification Modes** (controlled by `ENABLE_FIELD_VERIFICATION` env var):
+ * - **Enabled** (default): Any value except `'false'` enables verification
+ * - **Disabled**: Set to `'false'` to skip verification entirely
+ *
+ * **Strictness Modes** (controlled by `STRICT_FIELD_VALIDATION` env var):
+ * - **Strict**: `'true'` - Logs all discrepancies (cosmetic + semantic)
+ * - **Standard** (default): `'false'` - Logs only semantic mismatches
+ *
+ * **Semantic vs Cosmetic Mismatches**:
+ * - Cosmetic: Format differences with same logical value (e.g., "Demo" vs {title: "Demo"})
+ * - Semantic: Actual data loss or corruption (e.g., "Demo" vs "Qualified", missing data)
+ *
+ * @see Issue #984 - Modularize UniversalUpdateService (831→220 lines)
+ * @see PR #1006 Phase 3.2 - Enhanced JSDoc for verification behavior
+ */
+import { UniversalResourceType } from '../../handlers/tool-configs/universal/types.js';
+/**
+ * Options for field persistence verification
+ */
+export interface VerificationOptions {
+    /** Skip verification entirely (default: false) */
+    skip?: boolean;
+    /** Throw error on verification failure (default: from env STRICT_FIELD_VALIDATION) */
+    strict?: boolean;
+    /** Include cosmetic mismatches in warnings (default: false) */
+    includeCosmetic?: boolean;
+}
+/**
+ * Result of field persistence verification
+ */
+export interface VerificationResult {
+    /** Whether all fields were persisted correctly */
+    verified: boolean;
+    /** Non-blocking warnings about verification */
+    warnings: string[];
+    /** List of field discrepancies found */
+    discrepancies: string[];
+    /** Actual values retrieved from API */
+    actualValues: Record<string, unknown>;
+}
+/**
+ * FieldPersistenceHandler - Post-update verification orchestration
+ *
+ * @example
+ * ```typescript
+ * // Standard mode (semantic mismatches only)
+ * const result = await FieldPersistenceHandler.verifyPersistence(
+ *   UniversalResourceType.COMPANIES,
+ *   'company-123',
+ *   { stage: 'Demo' }
+ * );
+ * // Cosmetic mismatch "Demo" vs {title: "Demo"} → not logged
+ * // Semantic mismatch "Demo" vs "Qualified" → logged
+ *
+ * // Strict mode (all mismatches)
+ * process.env.STRICT_FIELD_VALIDATION = 'true';
+ * // Both cosmetic and semantic mismatches logged
+ * ```
+ */
+export declare class FieldPersistenceHandler {
+    /**
+     * Verify that fields were persisted correctly after update
+     *
+     * Supports three modes:
+     * 1. Disabled: ENABLE_FIELD_VERIFICATION=false (skip completely)
+     * 2. Warn-only: Default, logs discrepancies as warnings
+     * 3. Strict: STRICT_FIELD_VALIDATION=true, throws on mismatch
+     *
+     * @param resourceType - Resource type being verified
+     * @param recordId - ID of the updated record
+     * @param expectedData - Expected field values after update
+     * @param actualRecord - Optional actual record values. If not provided, will be fetched from API
+     * @param options - Verification options
+     * @returns Verification result with verified status, warnings, and discrepancies
+     * @throws UniversalValidationError if strict mode enabled and verification fails
+     */
+    static verifyPersistence(resourceType: UniversalResourceType, recordId: string, expectedData: Record<string, unknown>, actualRecord?: Record<string, unknown>, options?: VerificationOptions): Promise<VerificationResult>;
+    /**
+     * Determine if a discrepancy is semantic (real) vs cosmetic (format-only)
+     *
+     * Cosmetic mismatches occur when the same logical value is represented differently:
+     * - String vs object: "Demo" vs {title: "Demo"}
+     * - Array wrapping: "value" vs ["value"]
+     * - Type coercion: "123" vs 123
+     *
+     * Semantic mismatches indicate actual data loss or corruption:
+     * - Different values: "Demo" vs "Qualified"
+     * - Missing data: {field: "value"} vs {}
+     *
+     * @param discrepancy - Discrepancy message from verification
+     * @returns true if semantic mismatch, false if cosmetic
+     */
+    static isSemanticMismatch(discrepancy: string): boolean;
+}
+//# sourceMappingURL=FieldPersistenceHandler.d.ts.map

package/dist/services/update/FieldPersistenceHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPersistenceHandler.d.ts","sourceRoot":"","sources":["../../../src/services/update/FieldPersistenceHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AAQnF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAuB;IAClC;;;;;;;;;;;;;;;OAeG;WACU,iBAAiB,CAC5B,YAAY,EAAE,qBAAqB,EACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC;IA4J9B;;;;;;;;;;;;;;OAcG;WACW,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAyB/D"}