attio-mcp 0.1.1 → 1.0.0

package/dist/utils/validation/id-validation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ID Format Validation Utilities
+ *
+ * Provides early validation of record IDs to prevent unnecessary API calls
+ * for invalid ID formats, improving performance for 404 responses.
+ */
+/**
+ * Validation result
+ */
+export interface IdValidationResult {
+    isValid: boolean;
+    format?: string;
+    message?: string;
+}
+/**
+ * Validate a record ID format
+ *
+ * @param id The ID to validate
+ * @param resourceType Optional resource type for specific validation
+ * @returns Validation result with details
+ */
+export declare function validateRecordId(id: string | undefined | null, _resourceType?: string): IdValidationResult;
+/**
+ * Validate multiple IDs at once
+ *
+ * @param ids Array of IDs to validate
+ * @param resourceType Optional resource type
+ * @returns Map of ID to validation result
+ */
+export declare function validateRecordIds(ids: string[], resourceType?: string): Map<string, IdValidationResult>;
+/**
+ * Check if all IDs in a list are valid
+ *
+ * @param ids Array of IDs to check
+ * @returns True if all IDs are valid
+ */
+export declare function areAllIdsValid(ids: string[]): boolean;
+/**
+ * Filter out invalid IDs from a list
+ *
+ * @param ids Array of IDs to filter
+ * @returns Object with valid and invalid ID arrays
+ */
+export declare function filterValidIds(ids: string[]): {
+    valid: string[];
+    invalid: Array<{
+        id: string;
+        reason: string;
+    }>;
+};
+/**
+ * Normalize an ID to a consistent format
+ *
+ * @param id The ID to normalize
+ * @returns Normalized ID or null if invalid
+ */
+export declare function normalizeId(id: string): string | null;
+/**
+ * Generate a cache key for a record ID
+ * Used for 404 response caching
+ *
+ * @param resourceType The resource type
+ * @param id The record ID
+ * @returns Cache key string
+ */
+export declare function generateIdCacheKey(resourceType: string, id: string): string;
+/**
+ * Check if an error is likely due to an invalid ID format
+ *
+ * @param error The error to check
+ * @returns True if error appears to be ID-related
+ */
+export declare function isIdFormatError(error: any): boolean;
+/**
+ * Extract IDs from various input formats
+ *
+ * @param input String that may contain IDs
+ * @returns Array of potential IDs found
+ */
+export declare function extractIds(input: string): string[];
+//# sourceMappingURL=id-validation.d.ts.map

package/dist/utils/validation/id-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-validation.d.ts","sourceRoot":"","sources":["../../../src/utils/validation/id-validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAE7B,aAAa,CAAC,EAAE,MAAM,GACrB,kBAAkB,CAiFpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EAAE,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAQjC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD,CAiBA;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAerD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM3E;AAED;;;;;GAKG;AAEH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAenD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBlD"}

package/dist/utils/validation/id-validation.js

@@ -0,0 +1,222 @@
+/**
+ * ID Format Validation Utilities
+ *
+ * Provides early validation of record IDs to prevent unnecessary API calls
+ * for invalid ID formats, improving performance for 404 responses.
+ */
+/**
+ * Valid ID patterns for different resource types
+ */
+const ID_PATTERNS = {
+    // Standard MongoDB ObjectId pattern (24 hex characters)
+    OBJECT_ID: /^[a-f0-9]{24}$/,
+    // UUID v4 pattern
+    UUID: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    // Attio-specific patterns (if different from standard ObjectId)
+    ATTIO_RECORD: /^[a-f0-9]{24}$/,
+    ATTIO_WORKSPACE: /^[a-f0-9]{24}$/,
+    // Legacy or alternative formats (add as discovered)
+    LEGACY: /^[A-Za-z0-9_-]{20,30}$/,
+};
+/**
+ * Validate a record ID format
+ *
+ * @param id The ID to validate
+ * @param resourceType Optional resource type for specific validation
+ * @returns Validation result with details
+ */
+export function validateRecordId(id, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_resourceType) {
+    // Check for missing ID
+    if (!id) {
+        return {
+            isValid: false,
+            message: 'Record ID is required',
+        };
+    }
+    // Check for empty string
+    if (id.trim() === '') {
+        return {
+            isValid: false,
+            message: 'Record ID cannot be empty',
+        };
+    }
+    // Check length constraints
+    if (id.length < 20) {
+        return {
+            isValid: false,
+            message: `Invalid record ID format: ID too short (${id.length} characters)`,
+        };
+    }
+    if (id.length > 50) {
+        return {
+            isValid: false,
+            message: `Invalid record ID format: ID too long (${id.length} characters)`,
+        };
+    }
+    // Check against known patterns
+    if (ID_PATTERNS.OBJECT_ID.test(id)) {
+        return {
+            isValid: true,
+            format: 'ObjectId',
+        };
+    }
+    if (ID_PATTERNS.UUID.test(id)) {
+        return {
+            isValid: true,
+            format: 'UUID',
+        };
+    }
+    if (ID_PATTERNS.LEGACY.test(id)) {
+        return {
+            isValid: true,
+            format: 'Legacy',
+        };
+    }
+    // Check for common invalid patterns
+    if (id.includes(' ')) {
+        return {
+            isValid: false,
+            message: 'Record ID cannot contain spaces',
+        };
+    }
+    if (id.startsWith('http')) {
+        return {
+            isValid: false,
+            message: 'Record ID appears to be a URL, not a valid ID',
+        };
+    }
+    if (id.includes('@')) {
+        return {
+            isValid: false,
+            message: 'Record ID appears to be an email, not a valid ID',
+        };
+    }
+    // Default rejection for unrecognized formats
+    return {
+        isValid: false,
+        message: `Invalid record ID format: ${id}`,
+    };
+}
+/**
+ * Validate multiple IDs at once
+ *
+ * @param ids Array of IDs to validate
+ * @param resourceType Optional resource type
+ * @returns Map of ID to validation result
+ */
+export function validateRecordIds(ids, resourceType) {
+    const results = new Map();
+    for (const id of ids) {
+        results.set(id, validateRecordId(id, resourceType));
+    }
+    return results;
+}
+/**
+ * Check if all IDs in a list are valid
+ *
+ * @param ids Array of IDs to check
+ * @returns True if all IDs are valid
+ */
+export function areAllIdsValid(ids) {
+    return ids.every((id) => validateRecordId(id).isValid);
+}
+/**
+ * Filter out invalid IDs from a list
+ *
+ * @param ids Array of IDs to filter
+ * @returns Object with valid and invalid ID arrays
+ */
+export function filterValidIds(ids) {
+    const valid = [];
+    const invalid = [];
+    for (const id of ids) {
+        const result = validateRecordId(id);
+        if (result.isValid) {
+            valid.push(id);
+        }
+        else {
+            invalid.push({
+                id,
+                reason: result.message || 'Invalid format',
+            });
+        }
+    }
+    return { valid, invalid };
+}
+/**
+ * Normalize an ID to a consistent format
+ *
+ * @param id The ID to normalize
+ * @returns Normalized ID or null if invalid
+ */
+export function normalizeId(id) {
+    const validation = validateRecordId(id);
+    if (!validation.isValid) {
+        return null;
+    }
+    // Trim whitespace
+    let normalized = id.trim();
+    // Convert to lowercase for hex-based IDs
+    if (validation.format === 'ObjectId' || validation.format === 'UUID') {
+        normalized = normalized.toLowerCase();
+    }
+    return normalized;
+}
+/**
+ * Generate a cache key for a record ID
+ * Used for 404 response caching
+ *
+ * @param resourceType The resource type
+ * @param id The record ID
+ * @returns Cache key string
+ */
+export function generateIdCacheKey(resourceType, id) {
+    const normalizedId = normalizeId(id);
+    if (!normalizedId) {
+        return `${resourceType}:invalid:${id}`;
+    }
+    return `${resourceType}:${normalizedId}`;
+}
+/**
+ * Check if an error is likely due to an invalid ID format
+ *
+ * @param error The error to check
+ * @returns True if error appears to be ID-related
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Error objects come from various sources with different structures
+export function isIdFormatError(error) {
+    if (!error)
+        return false;
+    const errorMessage = error.message || error.toString() || '';
+    const lowerMessage = errorMessage.toLowerCase();
+    return (lowerMessage.includes('invalid id') ||
+        lowerMessage.includes('invalid record id') ||
+        lowerMessage.includes('malformed id') ||
+        lowerMessage.includes('objectid failed') ||
+        lowerMessage.includes('cast to objectid failed') ||
+        lowerMessage.includes('invalid uuid') ||
+        lowerMessage.includes('not a valid identifier'));
+}
+/**
+ * Extract IDs from various input formats
+ *
+ * @param input String that may contain IDs
+ * @returns Array of potential IDs found
+ */
+export function extractIds(input) {
+    const ids = [];
+    // Try to match ObjectId pattern
+    const objectIdMatches = input.match(/[a-f0-9]{24}/g);
+    if (objectIdMatches) {
+        ids.push(...objectIdMatches);
+    }
+    // Try to match UUID pattern
+    const uuidMatches = input.match(/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/gi);
+    if (uuidMatches) {
+        ids.push(...uuidMatches);
+    }
+    return Array.from(new Set(ids)); // Remove duplicates
+}
+//# sourceMappingURL=id-validation.js.map

package/dist/utils/validation/id-validation.js.map

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

package/dist/utils/validation/uuid-validation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * UUID Validation Utilities for Issue #416
+ *
+ * This module provides UUID format validation to properly distinguish between
+ * "Invalid format" and "Not found" errors, addressing the misleading error
+ * messages reported in Issue #416.
+ */
+import { EnhancedApiError } from '../../errors/enhanced-api-errors.js';
+/**
+ * Validate if a string is in proper UUID format
+ *
+ * @param uuid - String to validate
+ * @returns true if the string is a valid UUID format
+ */
+export declare function isValidUUID(uuid: string): boolean;
+/**
+ * Validate record ID format and throw appropriate error if invalid
+ *
+ * This function addresses Issue #416 by ensuring that format validation
+ * errors are distinct from "not found" errors.
+ *
+ * @param recordId - Record ID to validate
+ * @param resourceType - Type of resource for context
+ * @throws EnhancedApiError with proper format error message
+ */
+export declare function validateRecordId(recordId: string, resourceType: string): void;
+/**
+ * Enhanced UUID validation with detailed error context
+ *
+ * @param uuid - UUID string to validate
+ * @param context - Additional context for error messages
+ * @returns Validation result with error details
+ */
+export interface UUIDValidationResult {
+    isValid: boolean;
+    error?: string;
+    suggestion?: string;
+}
+export declare function validateUUIDWithDetails(uuid: string, _options?: {
+    resourceType?: string;
+    operation?: string;
+}): UUIDValidationResult;
+/**
+ * Create a properly formatted error for invalid UUIDs
+ *
+ * @param recordId - The invalid record ID
+ * @param resourceType - Resource type for context
+ * @param operation - Operation being performed
+ * @returns EnhancedApiError with detailed UUID format guidance
+ */
+export declare function createInvalidUUIDError(recordId: string, resourceType: string, operation?: string): EnhancedApiError;
+/**
+ * Create a properly formatted error for records not found
+ *
+ * @param recordId - The record ID that wasn't found
+ * @param resourceType - Resource type for context
+ * @returns EnhancedApiError with clear "not found" message
+ */
+export declare function createRecordNotFoundError(recordId: string, resourceType: string): EnhancedApiError;
+/**
+ * Utility to distinguish between format errors and not found errors
+ *
+ * This function encapsulates the core logic for Issue #416 - it determines
+ * whether an error should be treated as a format issue or a not found issue.
+ *
+ * @param error - Original error from API
+ * @param recordId - Record ID that was requested
+ * @param resourceType - Resource type for context
+ * @returns Appropriate EnhancedApiError
+ */
+export declare function classifyRecordError(error: Error, recordId: string, resourceType: string): EnhancedApiError;
+/**
+ * Generate example UUIDs for error messages and documentation
+ */
+export declare function generateExampleUUID(): string;
+/**
+ * Extract UUID from various input formats including URIs
+ *
+ * Handles:
+ * - Raw UUIDs: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ * - URI paths: "https://app.attio.com/records/companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ * - Custom schemes: "attio://companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ *
+ * @param input - Input string that may contain a UUID
+ * @returns Extracted UUID string or null if no valid UUID found
+ */
+export declare function extractRecordId(input: string): string | null;
+/**
+ * Common UUID validation patterns for testing
+ */
+export declare const UUIDTestPatterns: {
+    VALID: string[];
+    INVALID_FORMAT: string[];
+    EDGE_CASES: unknown[];
+};
+//# sourceMappingURL=uuid-validation.d.ts.map

package/dist/utils/validation/uuid-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-validation.d.ts","sourceRoot":"","sources":["../../../src/utils/validation/uuid-validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,qCAAqC,CAAC;AAS7C;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAI7E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EAEZ,QAAQ,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,oBAAoB,CAgDtB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAAc,GACxB,gBAAgB,CAmBlB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAalB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAgClB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAc5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmC5D;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;CAqB5B,CAAC"}

package/dist/utils/validation/uuid-validation.js

@@ -0,0 +1,227 @@
+/**
+ * UUID Validation Utilities for Issue #416
+ *
+ * This module provides UUID format validation to properly distinguish between
+ * "Invalid format" and "Not found" errors, addressing the misleading error
+ * messages reported in Issue #416.
+ */
+import { EnhancedApiError, ErrorTemplates, } from '../../errors/enhanced-api-errors.js';
+/**
+ * UUID format validation regex
+ * Matches standard UUID v4 format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+ */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Validate if a string is in proper UUID format
+ *
+ * @param uuid - String to validate
+ * @returns true if the string is a valid UUID format
+ */
+export function isValidUUID(uuid) {
+    return UUID_REGEX.test(uuid);
+}
+/**
+ * Validate record ID format and throw appropriate error if invalid
+ *
+ * This function addresses Issue #416 by ensuring that format validation
+ * errors are distinct from "not found" errors.
+ *
+ * @param recordId - Record ID to validate
+ * @param resourceType - Type of resource for context
+ * @throws EnhancedApiError with proper format error message
+ */
+export function validateRecordId(recordId, resourceType) {
+    if (!isValidUUID(recordId)) {
+        throw ErrorTemplates.INVALID_UUID_FORMAT(recordId, resourceType);
+    }
+}
+export function validateUUIDWithDetails(uuid, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_options) {
+    if (!uuid || typeof uuid !== 'string') {
+        return {
+            isValid: false,
+            error: 'Record ID is required and must be a string',
+            suggestion: 'Provide a valid UUID format (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")',
+        };
+    }
+    if (uuid.length !== 36) {
+        return {
+            isValid: false,
+            error: `Invalid UUID length: ${uuid.length} characters (expected 36)`,
+            suggestion: 'UUIDs must be exactly 36 characters long with dashes at positions 8, 13, 18, 23',
+        };
+    }
+    if (!UUID_REGEX.test(uuid)) {
+        // Analyze what's wrong with the format
+        const issues = [];
+        if (uuid.charAt(8) !== '-' ||
+            uuid.charAt(13) !== '-' ||
+            uuid.charAt(18) !== '-' ||
+            uuid.charAt(23) !== '-') {
+            issues.push('incorrect dash positions (should be at 8, 13, 18, 23)');
+        }
+        const nonHexChars = uuid.replace(/-/g, '').match(/[^0-9a-fA-F]/g);
+        if (nonHexChars) {
+            issues.push(`invalid characters: ${Array.from(new Set(nonHexChars)).join(', ')}`);
+        }
+        return {
+            isValid: false,
+            error: `Invalid UUID format: ${issues.join('; ')}`,
+            suggestion: 'Use hexadecimal characters (0-9, a-f) with dashes at positions 8, 13, 18, 23',
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Create a properly formatted error for invalid UUIDs
+ *
+ * @param recordId - The invalid record ID
+ * @param resourceType - Resource type for context
+ * @param operation - Operation being performed
+ * @returns EnhancedApiError with detailed UUID format guidance
+ */
+export function createInvalidUUIDError(recordId, resourceType, operation = 'GET') {
+    const validation = validateUUIDWithDetails(recordId, {
+        resourceType,
+        operation,
+    });
+    return new EnhancedApiError(`Invalid record identifier format: '${recordId}'`, 400, `/objects/${resourceType}`, operation, {
+        field: 'record_id',
+        resourceType,
+        documentationHint: validation.suggestion ||
+            'Expected UUID format (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")',
+    });
+}
+/**
+ * Create a properly formatted error for records not found
+ *
+ * @param recordId - The record ID that wasn't found
+ * @param resourceType - Resource type for context
+ * @returns EnhancedApiError with clear "not found" message
+ */
+export function createRecordNotFoundError(recordId, resourceType) {
+    return new EnhancedApiError(`Record not found`, 404, `/objects/${resourceType}/${recordId}`, 'GET', {
+        recordId,
+        resourceType,
+        httpStatus: 404,
+        documentationHint: `Use search-records to find valid ${resourceType} IDs.`,
+    });
+}
+/**
+ * Utility to distinguish between format errors and not found errors
+ *
+ * This function encapsulates the core logic for Issue #416 - it determines
+ * whether an error should be treated as a format issue or a not found issue.
+ *
+ * @param error - Original error from API
+ * @param recordId - Record ID that was requested
+ * @param resourceType - Resource type for context
+ * @returns Appropriate EnhancedApiError
+ */
+export function classifyRecordError(error, recordId, resourceType) {
+    const errorMessage = error.message.toLowerCase();
+    // If the UUID format is invalid, it's definitely a format error
+    if (!isValidUUID(recordId)) {
+        return createInvalidUUIDError(recordId, resourceType);
+    }
+    // If UUID format is valid but we got an error, check the error type
+    const statusLike = error;
+    if (errorMessage.includes('not found') ||
+        errorMessage.includes('does not exist') ||
+        statusLike.status === 404 ||
+        statusLike.statusCode === 404) {
+        return createRecordNotFoundError(recordId, resourceType);
+    }
+    // For other errors with valid UUIDs, preserve the original error but enhance it
+    const statusCode = statusLike.statusCode || statusLike.status || 500;
+    return new EnhancedApiError(error.message, statusCode, `/objects/${resourceType}/${recordId}`, 'GET', {
+        recordId,
+        resourceType,
+        originalError: error,
+    });
+}
+/**
+ * Generate example UUIDs for error messages and documentation
+ */
+export function generateExampleUUID() {
+    // Generate a valid UUID v4 for examples
+    const hex = '0123456789abcdef';
+    let uuid = '';
+    for (let i = 0; i < 36; i++) {
+        if (i === 8 || i === 13 || i === 18 || i === 23) {
+            uuid += '-';
+        }
+        else {
+            uuid += hex[Math.floor(Math.random() * 16)];
+        }
+    }
+    return uuid;
+}
+/**
+ * Extract UUID from various input formats including URIs
+ *
+ * Handles:
+ * - Raw UUIDs: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ * - URI paths: "https://app.attio.com/records/companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ * - Custom schemes: "attio://companies/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+ *
+ * @param input - Input string that may contain a UUID
+ * @returns Extracted UUID string or null if no valid UUID found
+ */
+export function extractRecordId(input) {
+    if (!input || typeof input !== 'string') {
+        return null;
+    }
+    // First try direct UUID matching
+    const directMatch = input.match(UUID_REGEX);
+    if (directMatch) {
+        return directMatch[0];
+    }
+    // Try URL parsing for URI-style inputs
+    try {
+        const url = new URL(input);
+        const pathSegments = url.pathname.split('/').filter(Boolean);
+        // Check each path segment for a UUID
+        for (const segment of pathSegments) {
+            if (UUID_REGEX.test(segment)) {
+                return segment;
+            }
+        }
+    }
+    catch {
+        // Not a valid URL, continue with other strategies
+    }
+    // Try extracting UUID from anywhere in the string as fallback
+    const anyMatch = input.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+    if (anyMatch) {
+        return anyMatch[0];
+    }
+    return null;
+}
+/**
+ * Common UUID validation patterns for testing
+ */
+export const UUIDTestPatterns = {
+    VALID: [
+        'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+        '123e4567-e89b-12d3-a456-426614174000',
+        '00000000-0000-0000-0000-000000000000',
+    ],
+    INVALID_FORMAT: [
+        'not-a-uuid',
+        'a1b2c3d4e5f6-7890-abcd-ef1234567890', // Missing dash
+        'a1b2c3d4-e5f6-7890-abcd-ef1234567890x', // Too long
+        'a1b2c3d4-e5f6-7890-abcd-ef123456789', // Too short
+        'g1b2c3d4-e5f6-7890-abcd-ef1234567890', // Invalid character
+        '12345678901234567890123456789012345678', // No dashes
+    ],
+    EDGE_CASES: [
+        '', // Empty string
+        null, // Null
+        undefined, // Undefined
+        123, // Number
+        {},
+    ],
+};
+//# sourceMappingURL=uuid-validation.js.map

package/dist/utils/validation/uuid-validation.js.map

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