@iflow-mcp/attio-mcp 1.3.6

package/dist/utils/filters/reference-attribute-helper.js

@@ -0,0 +1,262 @@
+/**
+ * Reference Attribute Helper
+ *
+ * Utilities for detecting and handling reference attributes in filter transformations.
+ * Reference attributes (owner, assignee, company, person) require nested field specification
+ * in Attio API filter syntax.
+ */
+import { getAttributeTypeInfo } from '../../api/attribute-types.js';
+import { FilterValidationError, FilterErrorCategory, } from '../../errors/api-errors.js';
+import { warn } from '../../utils/logger.js';
+// Re-export getAttributeTypeInfo for use in translators
+export { getAttributeTypeInfo };
+/**
+ * Attio attribute types that require reference field nesting
+ */
+const REFERENCE_TYPES = [
+    'record-reference',
+    'actor-reference',
+    'workspace-member',
+];
+/**
+ * Field to use for specific attribute types that require fixed field names
+ * Only include types that ALWAYS use the same field regardless of value
+ *
+ * NOTE: actor-reference fields (like deals.owner) can accept either email OR UUID
+ * depending on the value format, so we use heuristic detection instead of forcing email.
+ * Only workspace-member typed fields must use email.
+ */
+const REFERENCE_FIELD_MAPPING = {
+    'workspace-member': 'email', // workspace members always filter by email
+};
+/**
+ * UUID v4 pattern for detecting UUID values
+ * Exported for use in filter translators (PR #904 Phase 2)
+ */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Email pattern for workspace member validation
+ *
+ * Uses permissive pattern to handle edge cases:
+ * - Test environments may use simplified emails (e.g., test@local.dev)
+ * - Some valid domains have short TLDs or special characters
+ * - Attio API performs canonical validation, so false positives fail fast
+ *
+ * Pattern validates: non-whitespace + @ + non-whitespace + . + non-whitespace
+ * Accepts: user@example.com, test@local.dev, admin@co.uk
+ * Rejects: missing @, missing domain, whitespace, no TLD
+ * Exported for use in filter translators (PR #904 Phase 2)
+ */
+export const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Known reference attribute slugs that commonly require nested field specification
+ * Used as fallback when resourceType is unavailable (e.g., list entries)
+ */
+const KNOWN_REFERENCE_SLUGS = new Set([
+    'owner',
+    'assignee',
+    'assignee_id', // workspace-member type that requires email field
+    'company',
+    'person',
+    'primary_contact',
+    'workspace_member',
+    'created_by',
+    'modified_by',
+]);
+/**
+ * Slugs that ALWAYS require email field (workspace-member type)
+ * Note: actor-reference slugs like 'owner', 'assignee' use flexible detection (UUID vs email vs name)
+ */
+const WORKSPACE_MEMBER_SLUGS = new Set(['workspace_member', 'assignee_id']);
+/**
+ * Known actor-reference slugs that require special handling in list entry context
+ * When resourceType is unavailable, these slugs with UUID values must use referenced_actor_id
+ * (not record_id) to generate correct actor-reference filter structure
+ * Exported for use in filter translators (PR #904 Phase 2)
+ */
+export const KNOWN_ACTOR_REFERENCE_SLUGS = new Set([
+    'owner',
+    'assignee',
+    'created_by',
+    'modified_by',
+]);
+/**
+ * Check if an attribute is a reference type that requires nested field specification
+ *
+ * @param resourceType - The resource type (e.g., 'deals', 'companies'), or undefined for slug-based fallback
+ * @param attributeSlug - The attribute slug (e.g., 'owner', 'assignee')
+ * @param cache - Optional per-request cache to avoid repeated getAttributeTypeInfo calls
+ * @returns True if the attribute is a reference type
+ */
+export async function isReferenceAttribute(resourceType, attributeSlug, cache) {
+    // If resourceType is unavailable (e.g., list entries), use slug-based fallback
+    if (!resourceType) {
+        return KNOWN_REFERENCE_SLUGS.has(attributeSlug);
+    }
+    try {
+        // Check cache first
+        const cacheKey = `${resourceType}:${attributeSlug}`;
+        let typeInfo = cache?.get(cacheKey);
+        if (!typeInfo) {
+            typeInfo = await getAttributeTypeInfo(resourceType, attributeSlug);
+            cache?.set(cacheKey, typeInfo);
+        }
+        return REFERENCE_TYPES.includes(typeInfo.attioType);
+    }
+    catch (error) {
+        // If metadata lookup fails, fall back to slug-based detection
+        warn('filters/reference-attribute-helper', `Metadata lookup failed for ${resourceType}.${attributeSlug}, using slug-based fallback`, {
+            resourceType,
+            attributeSlug,
+            reason: 'metadata_lookup_failed',
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return KNOWN_REFERENCE_SLUGS.has(attributeSlug);
+    }
+}
+/**
+ * Determine which field to use for a reference attribute based on the value and type
+ *
+ * @param value - The filter value (can be UUID, name, or array of UUIDs/names for in/not_in operators)
+ * @param attioType - The Attio attribute type (optional)
+ * @returns The field name to use ('record_id', 'name', or 'referenced_actor_id' for actor-reference)
+ */
+export function determineReferenceField(value, attioType) {
+    // Actor-reference attributes use referenced_actor_id (always UUID)
+    if (attioType === 'actor-reference') {
+        return 'referenced_actor_id';
+    }
+    // Handle array values (for in/not_in operators)
+    if (Array.isArray(value)) {
+        // Empty arrays default to name field
+        if (value.length === 0) {
+            return 'name';
+        }
+        // Check if all elements are UUID strings
+        const allUUIDs = value.every((v) => typeof v === 'string' && UUID_PATTERN.test(v));
+        const allNonUUIDs = value.every((v) => typeof v === 'string' && !UUID_PATTERN.test(v));
+        // Reject mixed-type arrays (some UUIDs, some names)
+        if (!allUUIDs && !allNonUUIDs) {
+            throw new FilterValidationError(`Mixed UUID and non-UUID values not supported in array filters. ` +
+                `Received array with both types. Use separate filters or ensure all values are the same type.`, FilterErrorCategory.VALUE);
+        }
+        return allUUIDs ? 'record_id' : 'name';
+    }
+    // Handle single values
+    if (typeof value === 'string' && UUID_PATTERN.test(value)) {
+        return 'record_id';
+    }
+    // Otherwise use name field
+    return 'name';
+}
+/**
+ * Get the appropriate reference field for an attribute, considering type-specific mappings
+ *
+ * @param resourceType - The resource type, or undefined for slug-based fallback
+ * @param attributeSlug - The attribute slug
+ * @param value - The filter value
+ * @param cache - Optional per-request cache to avoid repeated getAttributeTypeInfo calls
+ * @returns The field name to use for filtering
+ * @throws FilterValidationError if email validation fails for workspace-member fields
+ */
+export async function getReferenceFieldForAttribute(resourceType, attributeSlug, value, cache) {
+    // Special case: workspace_member and assignee_id slugs ALWAYS use email
+    // regardless of metadata availability
+    if (attributeSlug === 'workspace_member' || attributeSlug === 'assignee_id') {
+        // Validate email format
+        if (typeof value !== 'string' || !EMAIL_PATTERN.test(value)) {
+            throw new FilterValidationError(`Invalid email format for ${attributeSlug}: "${value}". Expected valid email address.`, FilterErrorCategory.VALUE);
+        }
+        return 'email';
+    }
+    // If resourceType is available, use metadata to determine field
+    if (resourceType) {
+        try {
+            // Check cache first
+            const cacheKey = `${resourceType}:${attributeSlug}`;
+            let typeInfo = cache?.get(cacheKey);
+            if (!typeInfo) {
+                typeInfo = await getAttributeTypeInfo(resourceType, attributeSlug);
+                cache?.set(cacheKey, typeInfo);
+            }
+            // Check for attribute-specific mapping (only workspace-member type requires fixed email)
+            if (REFERENCE_FIELD_MAPPING[typeInfo.attioType]) {
+                const field = REFERENCE_FIELD_MAPPING[typeInfo.attioType];
+                // Validate email if this is an email field
+                if (field === 'email') {
+                    if (typeof value !== 'string' || !EMAIL_PATTERN.test(value)) {
+                        throw new FilterValidationError(`Invalid email format for ${attributeSlug}: "${value}". Expected valid email address.`, FilterErrorCategory.VALUE);
+                    }
+                }
+                return field;
+            }
+            // Actor-reference fields (e.g., owner, assignee) support flexible filtering:
+            // - Email address → filter by email field
+            // - UUID (workspace member ID) → filter by referenced_actor_id (requires referenced_actor_type)
+            // - Name (plain text) → filter by name field
+            if (typeInfo.attioType === 'actor-reference') {
+                if (typeof value !== 'string') {
+                    throw new FilterValidationError(`Actor-reference attribute "${attributeSlug}" requires a string value (email, name, or UUID). Got: ${typeof value}`, FilterErrorCategory.VALUE);
+                }
+                // Detect value type and return appropriate field
+                if (EMAIL_PATTERN.test(value)) {
+                    return 'email';
+                }
+                else if (UUID_PATTERN.test(value)) {
+                    return 'referenced_actor_id';
+                }
+                else {
+                    // Plain text name
+                    return 'name';
+                }
+            }
+            // Fall back to UUID vs name detection for record-reference types
+            return determineReferenceField(value, typeInfo.attioType);
+        }
+        catch (error) {
+            // Re-throw FilterValidationError
+            if (error instanceof FilterValidationError) {
+                throw error;
+            }
+            // Fall through to slug-based detection if metadata lookup fails
+            warn('filters/reference-attribute-helper', `Metadata lookup failed in getReferenceFieldForAttribute for ${resourceType}.${attributeSlug}, using slug-based fallback`, {
+                resourceType,
+                attributeSlug,
+                reason: 'metadata_lookup_failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // ResourceType unavailable or metadata lookup failed - use slug-based detection
+    // Check if this is a known workspace member slug (requires email field)
+    if (WORKSPACE_MEMBER_SLUGS.has(attributeSlug)) {
+        // Validate email format
+        if (typeof value !== 'string' || !EMAIL_PATTERN.test(value)) {
+            throw new FilterValidationError(`Invalid email format for ${attributeSlug}: "${value}". Expected valid email address. Workspace member attributes (owner, assignee, etc.) require email addresses.`, FilterErrorCategory.VALUE);
+        }
+        return 'email';
+    }
+    // Special handling for known actor-reference slugs (owner, assignee, created_by, modified_by)
+    // When resourceType unavailable (e.g., list entries), we can't query metadata but can use slug patterns
+    if (KNOWN_ACTOR_REFERENCE_SLUGS.has(attributeSlug)) {
+        // Actor-reference attributes support email, UUID, or name filtering
+        if (typeof value !== 'string') {
+            throw new FilterValidationError(`Actor-reference attribute "${attributeSlug}" requires a string value (email, name, or UUID). Got: ${typeof value}`, FilterErrorCategory.VALUE);
+        }
+        // Detect value type and return appropriate field
+        if (EMAIL_PATTERN.test(value)) {
+            return 'email';
+        }
+        else if (UUID_PATTERN.test(value)) {
+            // UUID values must use referenced_actor_id for actor-reference structure
+            return 'referenced_actor_id';
+        }
+        else {
+            // Plain text name
+            return 'name';
+        }
+    }
+    // For other reference slugs (company, person, etc.), use basic heuristic detection (UUID vs name)
+    return determineReferenceField(value);
+}
+//# sourceMappingURL=reference-attribute-helper.js.map

package/dist/utils/filters/reference-attribute-helper.js.map

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

package/dist/utils/filters/relationship.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Relationship filtering utilities
+ * These utilities help create filters based on relationships between records
+ */
+import { ListEntryFilters, ResourceType } from './types.js';
+/**
+ * Applies rate limiting to relationship queries
+ * Throws RelationshipRateLimitError if the rate limit is exceeded
+ *
+ * @param req - Request object
+ * @param relationshipType - Type of relationship query
+ * @param isNested - Whether this is a nested relationship query
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function applyRateLimit(_req: Record<string, unknown>, _relationshipType: string, _isPrecheck?: boolean): void;
+/**
+ * Creates a filter for people based on their associated company attributes
+ * Includes rate limiting for this resource-intensive operation
+ *
+ * @param companyFilter - Filters to apply to the related companies
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding people based on company attributes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createPeopleByCompanyFilter(companyFilter: ListEntryFilters, req?: Record<string, unknown>): ListEntryFilters;
+/**
+ * Creates a filter for companies based on their associated people attributes
+ * Includes rate limiting for this resource-intensive operation
+ *
+ * @param peopleFilter - Filters to apply to the related people
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding companies based on people attributes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createCompaniesByPeopleFilter(peopleFilter: ListEntryFilters, req?: Record<string, unknown>): ListEntryFilters;
+/**
+ * Creates a filter for records that belong to a specific list
+ * Includes rate limiting for this operation and caching for better performance
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param listId - The ID of the list to filter by
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding records that belong to the list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createRecordsByListFilter(resourceType: ResourceType, listId: string, req?: Record<string, unknown>, useCache?: boolean): ListEntryFilters;
+/**
+ * Creates a filter for finding people who work at companies in a specific list
+ * This is a nested relationship query with rate limiting and caching applied
+ *
+ * @param listId - The ID of the list that contains companies
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding people who work at companies in the specified list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createPeopleByCompanyListFilter(listId: string, req?: Record<string, unknown>, useCache?: boolean): ListEntryFilters;
+/**
+ * Creates a filter for finding companies that have people in a specific list
+ * This is a nested relationship query with rate limiting and caching applied
+ *
+ * @param listId - The ID of the list that contains people
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @param useCache - Whether to use caching (default: true)
+ * @returns Filter for finding companies that have people in the specified list
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createCompaniesByPeopleListFilter(listId: string, req?: Record<string, unknown>, useCache?: boolean): ListEntryFilters;
+/**
+ * Creates a filter for records that have associated notes matching criteria
+ * Includes rate limiting for text search operations
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param textSearch - Text to search for in the notes
+ * @param req - Optional request object for rate limiting (if not provided, rate limiting is skipped)
+ * @returns Filter for finding records with matching notes
+ * @throws RelationshipRateLimitError if rate limit exceeded
+ */
+export declare function createRecordsByNotesFilter(resourceType: ResourceType, textSearch: string, req?: Record<string, unknown>): ListEntryFilters;
+//# sourceMappingURL=relationship.d.ts.map

package/dist/utils/filters/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../../../src/utils/filters/relationship.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,EACL,gBAAgB,EAGhB,YAAY,EAIb,MAAM,YAAY,CAAC;AAWpB;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAE5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE7B,iBAAiB,EAAE,MAAM,EAEzB,WAAW,CAAC,EAAE,OAAO,GACpB,IAAI,CAaN;AAiDD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,gBAAgB,EAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAgDlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,gBAAgB,EAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAgDlB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,GAAE,OAAc,GACvB,gBAAgB,CAgElB;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,GAAE,OAAc,GACvB,gBAAgB,CAkElB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,GAAE,OAAc,GACvB,gBAAgB,CAkElB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAyClB"}