@iflow-mcp/attio-mcp 1.3.6

package/dist/services/UniversalUtilityService.js

@@ -0,0 +1,300 @@
+/**
+ * UniversalUtilityService - Centralized utility functions
+ *
+ * Extracted from shared-handlers.ts as part of Issue #489 Phase 3.
+ * Provides universal utility functions for resource type formatting, validation, and data conversion.
+ */
+import { UniversalResourceType } from '../handlers/tool-configs/universal/types.js';
+/**
+ * UniversalUtilityService provides centralized utility functions
+ */
+export class UniversalUtilityService {
+    /**
+     * Utility function to format resource type for display
+     */
+    static formatResourceType(resourceType) {
+        switch (resourceType) {
+            case UniversalResourceType.COMPANIES:
+                return 'company';
+            case UniversalResourceType.PEOPLE:
+                return 'person';
+            case UniversalResourceType.LISTS:
+                return 'list';
+            case UniversalResourceType.RECORDS:
+                return 'record';
+            case UniversalResourceType.DEALS:
+                return 'deal';
+            case UniversalResourceType.TASKS:
+                return 'task';
+            default:
+                return resourceType;
+        }
+    }
+    /**
+     * Utility function to get singular form of resource type
+     */
+    static getSingularResourceType(resourceType) {
+        return this.formatResourceType(resourceType);
+    }
+    /**
+     * Utility function to validate resource type
+     */
+    static isValidResourceType(resourceType) {
+        return Object.values(UniversalResourceType).includes(resourceType);
+    }
+    /**
+     * Converts an AttioTask to an AttioRecord for universal tool compatibility.
+     *
+     * This function provides proper type conversion from the task-specific format
+     * to the generic record format used by universal tools, ensuring data integrity
+     * without unsafe type casting.
+     *
+     * @param task - The AttioTask object to convert
+     * @returns An AttioRecord representation of the task with properly mapped fields
+     *
+     * @example
+     * const task = await getTask('task-123');
+     * const record = UniversalUtilityService.convertTaskToRecord(task);
+     * // record.values now contains: content, status, assignee, due_date, linked_records
+     */
+    static convertTaskToRecord(task) {
+        // Note: Debug logging moved to development utilities
+        // More robust ID handling
+        let record_id;
+        let workspace_id = '';
+        if (task.id) {
+            // Handle different possible ID structures
+            if (typeof task.id === 'string') {
+                record_id = task.id;
+            }
+            else if (typeof task.id === 'object' && task.id !== null) {
+                if ('task_id' in task.id) {
+                    record_id = task.id.task_id;
+                }
+                else if ('id' in task.id) {
+                    record_id = task.id.id;
+                }
+                else {
+                    throw new Error(`Task ID structure not recognized: ${JSON.stringify(task.id)}`);
+                }
+                workspace_id =
+                    task.id.workspace_id || '';
+            }
+            else {
+                throw new Error(`Task ID structure not recognized: ${JSON.stringify(task.id)}`);
+            }
+        }
+        else {
+            throw new Error(`Task missing id property: ${JSON.stringify(task)}`);
+        }
+        const baseRecord = {
+            id: {
+                record_id,
+                task_id: record_id, // Issue #480: Preserve task_id for E2E test compatibility
+                object_id: 'tasks',
+                workspace_id,
+            },
+            values: {
+                // Map task properties to simple string format (corrected after API verification)
+                content: task.content,
+                status: task.status,
+                assignee: typeof task.assignee === 'string' ? task.assignee : task.assignee?.id,
+                due_date: task.due_date,
+                linked_records: task.linked_records || undefined,
+            },
+            created_at: task.created_at,
+            updated_at: task.updated_at,
+        };
+        // Add flat field compatibility for test environments (Issue #480 pattern)
+        const flatFields = {
+            content: task.content,
+            status: task.status,
+            due_date: task.due_date,
+            assignee_id: typeof task.assignee === 'string' ? task.assignee : task.assignee?.id,
+        };
+        // Add assignee as simple string (corrected after API verification)
+        if (task.assignee) {
+            flatFields.assignee =
+                typeof task.assignee === 'string' ? task.assignee : task.assignee.id;
+        }
+        return { ...baseRecord, ...flatFields };
+    }
+    /**
+     * Extract display name from AttioRecord values with proper field priority
+     *
+     * Centralizes the logic for determining display names from record field values.
+     * Handles both direct object access and array-wrapped values patterns used
+     * throughout the codebase. Eliminates code duplication between formatResult functions.
+     *
+     * Field Priority Order:
+     * 1. name (checks both 'value' and 'full_name' properties)
+     * 2. full_name
+     * 3. title
+     * 4. content
+     * 5. fallback to 'Unnamed'
+     *
+     * @param values - The record values object (can be from record.values or direct values)
+     * @returns The extracted display name string or 'Unnamed' if no suitable field found
+     *
+     * @example
+     * ```typescript
+     * const displayName = UniversalUtilityService.extractDisplayName(record.values);
+     * // For tasks: "Follow up with client" (from content field)
+     * // For companies: "Acme Corp" (from name field)
+     * // For empty record: "Unnamed"
+     * ```
+     */
+    static extractDisplayName(values) {
+        if (!values || typeof values !== 'object') {
+            return 'Unnamed';
+        }
+        // Helper function to safely extract value from field
+        const extractFieldValue = (field) => {
+            if (!field)
+                return null;
+            // Handle array values first (e.g., company names, person names)
+            if (Array.isArray(field) && field.length > 0) {
+                const firstItem = field[0];
+                // For name field, check 'value', 'full_name', and 'formatted' properties
+                return (firstItem?.value ||
+                    firstItem?.full_name ||
+                    firstItem?.formatted ||
+                    null);
+            }
+            // Handle simple string values as fallback (e.g., task content)
+            if (typeof field === 'string' && field.trim()) {
+                return field.trim();
+            }
+            return null;
+        };
+        // Check fields in priority order, collecting valid values
+        const fieldPriority = ['name', 'full_name', 'title', 'content'];
+        const validValues = [];
+        for (const fieldName of fieldPriority) {
+            const fieldValue = extractFieldValue(values[fieldName]);
+            if (fieldValue && typeof fieldValue === 'string' && fieldValue.trim()) {
+                // Prefer array-based values over string fallbacks
+                const isArrayValue = Array.isArray(values[fieldName]);
+                if (isArrayValue) {
+                    return fieldValue.trim(); // Return immediately for valid array values
+                }
+                validValues.push(fieldValue.trim());
+            }
+        }
+        // Return first valid value (including string fallbacks) or 'Unnamed'
+        return validValues[0] || 'Unnamed';
+    }
+    /**
+     * Get the plural form of a resource type (opposite of getSingularResourceType)
+     */
+    static getPluralResourceType(resourceType) {
+        return resourceType; // UniversalResourceType values are already plural
+    }
+    /**
+     * Check if a resource type supports object records API
+     */
+    static supportsObjectRecordsApi(resourceType) {
+        switch (resourceType) {
+            case UniversalResourceType.RECORDS:
+            case UniversalResourceType.DEALS:
+                return true;
+            case UniversalResourceType.TASKS:
+                return false; // Tasks use /tasks API, not /objects/tasks
+            case UniversalResourceType.COMPANIES:
+            case UniversalResourceType.PEOPLE:
+            case UniversalResourceType.LISTS:
+                return true; // These use their own specific APIs, but also support objects pattern
+            default:
+                return false;
+        }
+    }
+    /**
+     * Get the API endpoint pattern for a resource type
+     */
+    static getApiEndpoint(resourceType) {
+        switch (resourceType) {
+            case UniversalResourceType.COMPANIES:
+                return '/companies';
+            case UniversalResourceType.PEOPLE:
+                return '/people';
+            case UniversalResourceType.LISTS:
+                return '/lists';
+            case UniversalResourceType.RECORDS:
+                return '/objects/records';
+            case UniversalResourceType.DEALS:
+                return '/objects/deals';
+            case UniversalResourceType.TASKS:
+                return '/tasks';
+            default:
+                throw new Error(`Unknown resource type: ${resourceType}`);
+        }
+    }
+    /**
+     * Check if a resource type requires special handling
+     */
+    static requiresSpecialHandling(resourceType) {
+        switch (resourceType) {
+            case UniversalResourceType.TASKS:
+                return true; // Tasks have different API structure
+            case UniversalResourceType.COMPANIES:
+            case UniversalResourceType.PEOPLE:
+                return true; // Have specialized APIs with additional features
+            default:
+                return false;
+        }
+    }
+    /**
+     * Normalize resource type string (handle case variations and common aliases)
+     */
+    static normalizeResourceType(input) {
+        const normalized = input.toLowerCase().trim();
+        switch (normalized) {
+            case 'company':
+            case 'companies':
+                return UniversalResourceType.COMPANIES;
+            case 'person':
+            case 'people':
+                return UniversalResourceType.PEOPLE;
+            case 'list':
+            case 'lists':
+                return UniversalResourceType.LISTS;
+            case 'record':
+            case 'records':
+                return UniversalResourceType.RECORDS;
+            case 'deal':
+            case 'deals':
+                return UniversalResourceType.DEALS;
+            case 'task':
+            case 'tasks':
+                return UniversalResourceType.TASKS;
+            default:
+                // Check if it's already a valid UniversalResourceType
+                if (this.isValidResourceType(input)) {
+                    return input;
+                }
+                return null;
+        }
+    }
+    /**
+     * Get human-readable description of a resource type
+     */
+    static getResourceTypeDescription(resourceType) {
+        switch (resourceType) {
+            case UniversalResourceType.COMPANIES:
+                return 'Company records containing business information';
+            case UniversalResourceType.PEOPLE:
+                return 'Person records containing contact information';
+            case UniversalResourceType.LISTS:
+                return 'Lists for organizing and grouping records';
+            case UniversalResourceType.RECORDS:
+                return 'Generic object records';
+            case UniversalResourceType.DEALS:
+                return 'Deal records for sales pipeline management';
+            case UniversalResourceType.TASKS:
+                return 'Task records for activity tracking';
+            default:
+                return `${resourceType} records`;
+        }
+    }
+}
+//# sourceMappingURL=UniversalUtilityService.js.map

package/dist/services/UniversalUtilityService.js.map

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

package/dist/services/ValidationService.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ValidationService - Centralized validation utilities for universal handlers
+ *
+ * Extracted from shared-handlers.ts as part of Issue #489 Phase 2.
+ * Provides parameter validation, UUID validation, field validation, and email validation.
+ */
+import { UniversalResourceType } from '../handlers/tool-configs/universal/types.js';
+/**
+ * ValidationService provides centralized validation functionality for universal handlers
+ */
+export declare class ValidationService {
+    /**
+     * Create a standardized validation error object
+     *
+     * @param message - Error message
+     * @param resourceType - Type of resource being validated (default: 'resource')
+     * @returns Validation error object with timestamp
+     */
+    static createValidationError(message: string, resourceType?: string): {
+        error: boolean;
+        message: string;
+        details: string;
+        timestamp: string;
+    };
+    /**
+     * Validate limit parameter for pagination
+     *
+     * @param limit - Limit value to validate
+     * @param perfId - Performance tracking ID for error reporting
+     * @param maxLimit - Maximum allowed limit (default: 100)
+     * @throws Error if validation fails
+     */
+    static validateLimitParameter(limit: number | undefined, perfId?: string, maxLimit?: number): void;
+    /**
+     * Validate offset parameter for pagination
+     *
+     * @param offset - Offset value to validate
+     * @param perfId - Performance tracking ID for error reporting
+     * @param maxOffset - Maximum allowed offset (default: 10000)
+     * @throws Error if validation fails
+     */
+    static validateOffsetParameter(offset: number | undefined, perfId?: string, maxOffset?: number): void;
+    /**
+     * Validate pagination parameters (limit and offset together)
+     *
+     * @param params - Object containing limit and offset
+     * @param perfId - Performance tracking ID for error reporting
+     * @param maxLimit - Maximum allowed limit (default: 100)
+     * @param maxOffset - Maximum allowed offset (default: 10000)
+     */
+    static validatePaginationParameters(params: {
+        limit?: number;
+        offset?: number;
+    }, perfId?: string, maxLimit?: number, maxOffset?: number): void;
+    /**
+     * Validate UUID format for record IDs
+     *
+     * @param recordId - Record ID to validate
+     * @param resourceType - Type of resource
+     * @param operation - Operation being performed (for error context)
+     * @param perfId - Performance tracking ID for error reporting
+     * @throws Error if UUID validation fails
+     */
+    static validateUUID(recordId: string, resourceType: string, operation?: string, perfId?: string): void;
+    /**
+     * Truncate suggestions to prevent buffer overflow in MCP protocol
+     *
+     * @param suggestions - Array of suggestion strings
+     * @param maxCount - Maximum number of suggestions to return (default: 3)
+     * @returns Truncated suggestions array
+     */
+    static truncateSuggestions(suggestions: string[], maxCount?: number): string[];
+    /**
+     * Validate fields for a resource and build comprehensive error messages
+     *
+     * @param resourceType - Type of resource being validated
+     * @param recordData - Record data to validate
+     * @param throwOnInvalid - Whether to throw error on validation failure (default: true)
+     * @returns Validation result with formatted error message if invalid
+     */
+    static validateFieldsWithErrorHandling(resourceType: UniversalResourceType | string, recordData: Record<string, unknown>, throwOnInvalid?: boolean): {
+        valid: boolean;
+        errorMessage?: string;
+    };
+    /**
+     * Validate email addresses in record data for consistent validation across create/update
+     *
+     * @param recordData - Record data containing potential email fields
+     * @throws UniversalValidationError if email validation fails
+     */
+    static validateEmailAddresses(recordData: Record<string, unknown>): void;
+    /**
+     * Validate record ID using the appropriate validation method
+     *
+     * @param recordId - Record ID to validate
+     * @param allowGeneric - Whether to allow generic ID validation (default: true)
+     * @returns True if valid, false otherwise
+     */
+    static isValidRecordId(recordId: string, allowGeneric?: boolean): boolean;
+    /**
+     * Validate UUID for search operations with lenient validation
+     * Returns false for invalid UUIDs instead of throwing (used for filters)
+     *
+     * @param uuid - UUID string to validate
+     * @returns True if valid UUID, false otherwise
+     */
+    static validateUUIDForSearch(uuid: string): boolean;
+    /**
+     * Validate filter schema for search operations
+     *
+     * @param filters - Filter object to validate
+     * @throws UniversalValidationError for malformed filter schemas
+     */
+    static validateFiltersSchema(filters: unknown): void;
+    /**
+     * Comprehensive validation for universal operations
+     *
+     * @param params - Validation parameters
+     * @returns Validation result
+     */
+    static validateUniversalOperation(params: {
+        resourceType: string;
+        recordId?: string;
+        recordData?: Record<string, unknown>;
+        limit?: number;
+        offset?: number;
+        operation?: string;
+        perfId?: string;
+    }): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+//# sourceMappingURL=ValidationService.d.ts.map

package/dist/services/ValidationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationService.d.ts","sourceRoot":"","sources":["../../src/services/ValidationService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6CAA6C,CAAC;AAMpF;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAO,EAAE,MAAM,EACf,YAAY,GAAE,MAAmB,GAChC;QACD,KAAK,EAAE,OAAO,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB;IASD;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,GAAE,MAAY,GACrB,IAAI;IA4BP;;;;;;;OAOG;IACH,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,GAAE,MAAc,GACxB,IAAI;IA4BP;;;;;;;OAOG;IACH,MAAM,CAAC,4BAA4B,CACjC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAC3C,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,GAAE,MAAY,EACtB,SAAS,GAAE,MAAc,GACxB,IAAI;IAKP;;;;;;;;OAQG;IACH,MAAM,CAAC,YAAY,CACjB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAoB,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAiCP;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CACxB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,GAAE,MAAU,GACnB,MAAM,EAAE;IAQX;;;;;;;OAOG;IACH,MAAM,CAAC,+BAA+B,CACpC,YAAY,EAAE,qBAAqB,GAAG,MAAM,EAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,cAAc,GAAE,OAAc,GAC7B;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAyD5C;;;;;OAKG;IACH,MAAM,CAAC,sBAAsB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IA+FxE;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CACpB,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,OAAc,GAC3B,OAAO;IAcV;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQnD;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IA8CpD;;;;;OAKG;IACH,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE;QACxC,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;CAiDzC"}