@iflow-mcp/attio-mcp 1.3.6

package/dist/types/universal-service-types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Universal Service Type Definitions
+ *
+ * Centralized type definitions for Universal*Service classes to eliminate
+ * repeated inline type definitions and improve type safety.
+ *
+ * This file extracts common patterns found across:
+ * - UniversalDeleteService
+ * - UniversalUpdateService
+ * - UniversalRetrievalService
+ * - UniversalSearchService
+ * - UniversalMetadataService
+ */
+import { UniversalResourceType } from '../handlers/tool-configs/universal/types.js';
+/**
+ * Standardized error response structure used across Universal services
+ *
+ * @see UniversalDeleteService lines 72-77, 90-95, 112-117, etc.
+ * @see UniversalUpdateService lines 118-123, 137-142
+ * @see UniversalRetrievalService lines 384-389, 405-410
+ */
+export interface UniversalErrorResponse {
+    status: number;
+    body: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Common "not found" error response (404) used throughout Universal services
+ *
+ * **Design Decision**: Using Record<string, unknown> instead of any for type safety.
+ * This allows property access while preventing unsafe operations on unknown data.
+ */
+export interface NotFoundErrorResponse extends UniversalErrorResponse {
+    status: 404;
+    body: {
+        code: 'not_found';
+        message: string;
+    };
+}
+/**
+ * Error object structures commonly encountered in Universal services
+ *
+ * **Type Safety Note**: These interfaces use Record<string, unknown> rather than any
+ * to provide type safety while allowing dynamic property access. This prevents
+ * accidental misuse of error properties while maintaining flexibility.
+ */
+export interface ApiErrorWithResponse {
+    response?: {
+        status?: number;
+        data?: {
+            code?: string;
+            message?: string;
+        };
+    };
+    status?: number;
+    code?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Error structure for task-specific operations
+ * Used in UniversalDeleteService task handling
+ */
+export interface TaskError extends Error {
+    status?: number;
+    body?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Generic error object structure found across Universal services
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const errorObj = apiError as any;
+ *
+ * // Use:
+ * const errorObj = apiError as GenericErrorObject;
+ * ```
+ */
+export interface GenericErrorObject {
+    response?: {
+        status?: number;
+        data?: {
+            message?: string;
+            error?: {
+                message?: string;
+                detail?: string;
+                details?: unknown;
+            };
+            details?: unknown;
+        };
+    };
+    status?: number;
+    statusCode?: number;
+    code?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Attribute object structure for metadata operations
+ *
+ * **Record<string, unknown> Rationale**: Attribute objects from the API can contain
+ * arbitrary properties. Using unknown ensures we handle these safely rather than
+ * bypassing type checking with any.
+ */
+export interface AttributeObject {
+    api_slug?: string;
+    title?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Data payload structure for Universal service operations
+ *
+ * Used in update/create operations where data can be in various formats
+ */
+export interface DataPayload {
+    values?: Record<string, unknown>;
+    object?: string;
+    object_api_slug?: string;
+    [key: string]: unknown;
+}
+/**
+ * Type guards for Universal service error handling
+ */
+/**
+ * Type guard to check if an error has the expected API error structure
+ *
+ * @param error - Unknown error object
+ * @returns true if error matches ApiErrorWithResponse structure
+ */
+export declare function isApiErrorWithResponse(error: unknown): error is ApiErrorWithResponse;
+/**
+ * Type guard to check if an error is a 404 not found error
+ *
+ * **Usage Pattern**: Extracted from repeated 404 detection logic across services
+ *
+ * @param error - Unknown error object
+ * @returns true if error indicates a 404 not found condition
+ */
+export declare function is404Error(error: unknown): boolean;
+/**
+ * Type guard for checking if a value is an attribute object
+ *
+ * @param value - Unknown value to check
+ * @returns true if value has expected attribute structure
+ */
+export declare function isAttributeObject(value: unknown): value is AttributeObject;
+/**
+ * Helper to create standardized not found error responses
+ *
+ * @param resourceType - Type of resource that was not found
+ * @param recordId - ID of the record that was not found
+ * @returns Standardized not found error response
+ */
+export declare function createNotFoundError(resourceType: UniversalResourceType | string, recordId: string): NotFoundErrorResponse;
+/**
+ * Safe error status extraction utility
+ *
+ * **Type Safety**: Uses type guards to safely extract status codes from
+ * various error formats without unsafe any casting.
+ *
+ * @param error - Unknown error object
+ * @returns HTTP status code if found, undefined otherwise
+ */
+export declare function extractErrorStatus(error: unknown): number | undefined;
+/**
+ * Safe error message extraction utility
+ *
+ * @param error - Unknown error object
+ * @returns Error message if found, undefined otherwise
+ */
+export declare function extractErrorMessage(error: unknown): string | undefined;
+//# sourceMappingURL=universal-service-types.d.ts.map

package/dist/types/universal-service-types.d.ts.map

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

package/dist/types/universal-service-types.js

@@ -0,0 +1,141 @@
+/**
+ * Universal Service Type Definitions
+ *
+ * Centralized type definitions for Universal*Service classes to eliminate
+ * repeated inline type definitions and improve type safety.
+ *
+ * This file extracts common patterns found across:
+ * - UniversalDeleteService
+ * - UniversalUpdateService
+ * - UniversalRetrievalService
+ * - UniversalSearchService
+ * - UniversalMetadataService
+ */
+import { UniversalResourceType } from '../handlers/tool-configs/universal/types.js';
+/**
+ * Type guards for Universal service error handling
+ */
+/**
+ * Type guard to check if an error has the expected API error structure
+ *
+ * @param error - Unknown error object
+ * @returns true if error matches ApiErrorWithResponse structure
+ */
+export function isApiErrorWithResponse(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        ('response' in error || 'status' in error || 'message' in error));
+}
+/**
+ * Type guard to check if an error is a 404 not found error
+ *
+ * **Usage Pattern**: Extracted from repeated 404 detection logic across services
+ *
+ * @param error - Unknown error object
+ * @returns true if error indicates a 404 not found condition
+ */
+export function is404Error(error) {
+    if (!isApiErrorWithResponse(error)) {
+        return false;
+    }
+    const status = error.response?.status ?? error.status;
+    const code = error.response?.data?.code ?? error.code;
+    const message = (error.response?.data?.message ?? error.message ?? '')
+        .toString()
+        .toLowerCase();
+    return (status === 404 ||
+        code === 'not_found' ||
+        message.includes('not found') ||
+        message.includes('404'));
+}
+/**
+ * Type guard for checking if a value is an attribute object
+ *
+ * @param value - Unknown value to check
+ * @returns true if value has expected attribute structure
+ */
+export function isAttributeObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        (('api_slug' in value &&
+            typeof value.api_slug === 'string') ||
+            ('title' in value &&
+                typeof value.title === 'string') ||
+            ('name' in value &&
+                typeof value.name === 'string')));
+}
+/**
+ * Helper to create standardized not found error responses
+ *
+ * @param resourceType - Type of resource that was not found
+ * @param recordId - ID of the record that was not found
+ * @returns Standardized not found error response
+ */
+export function createNotFoundError(resourceType, recordId) {
+    const resourceName = getResourceDisplayName(resourceType);
+    return {
+        status: 404,
+        body: {
+            code: 'not_found',
+            message: `${resourceName} record with ID "${recordId}" not found.`,
+        },
+    };
+}
+/**
+ * Helper to get display name for resource types
+ *
+ * @param resourceType - Resource type enum or string
+ * @returns Human-readable resource name
+ */
+function getResourceDisplayName(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';
+        case UniversalResourceType.NOTES:
+            return 'Note';
+        default:
+            return String(resourceType);
+    }
+}
+/**
+ * Safe error status extraction utility
+ *
+ * **Type Safety**: Uses type guards to safely extract status codes from
+ * various error formats without unsafe any casting.
+ *
+ * @param error - Unknown error object
+ * @returns HTTP status code if found, undefined otherwise
+ */
+export function extractErrorStatus(error) {
+    if (!isApiErrorWithResponse(error)) {
+        return undefined;
+    }
+    const status = error.response?.status ?? error.status;
+    return typeof status === 'number' ? status : undefined;
+}
+/**
+ * Safe error message extraction utility
+ *
+ * @param error - Unknown error object
+ * @returns Error message if found, undefined otherwise
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (!isApiErrorWithResponse(error)) {
+        return typeof error === 'string' ? error : undefined;
+    }
+    return error.response?.data?.message ?? error.message ?? undefined;
+}
+//# sourceMappingURL=universal-service-types.js.map

package/dist/types/universal-service-types.js.map

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

package/dist/utils/AttioFieldMapper.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Attio Field Name Mapper
+ *
+ * Maps generic field names to Attio-specific field names
+ * Provides deprecation warnings for unsupported aliases
+ */
+export declare const FIELD_MAPPINGS: {
+    readonly timestamp: {
+        readonly created: "created_at";
+        readonly modified: "modified_at";
+        readonly updated: "modified_at";
+        readonly interacted: "interacted_at";
+    };
+    readonly system: {
+        readonly id: "record_id";
+        readonly workspace: "workspace_id";
+        readonly object: "object_id";
+    };
+};
+/**
+ * Map generic field name to Attio-specific field name
+ * Logs deprecation warnings for unsupported aliases
+ */
+export declare function mapFieldName(genericField: string): string;
+/**
+ * Get all valid timestamp field names for a given resource
+ * Different resources may support different timestamp fields
+ */
+export declare function getValidTimestampFields(resourceType: string): string[];
+/**
+ * Validate if a field name is supported for timeframe filtering
+ */
+export declare function isValidTimestampField(fieldName: string, resourceType: string): boolean;
+//# sourceMappingURL=AttioFieldMapper.d.ts.map

package/dist/utils/AttioFieldMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttioFieldMapper.d.ts","sourceRoot":"","sources":["../../src/utils/AttioFieldMapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,eAAO,MAAM,cAAc;;;;;;;;;;;;CAYjB,CAAC;AAWX;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CA2BzD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CActE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAGT"}

package/dist/utils/AttioFieldMapper.js

@@ -0,0 +1,84 @@
+/**
+ * Attio Field Name Mapper
+ *
+ * Maps generic field names to Attio-specific field names
+ * Provides deprecation warnings for unsupported aliases
+ */
+import { createScopedLogger, OperationType } from './logger.js';
+const log = createScopedLogger('utils.AttioFieldMapper', undefined, OperationType.TRANSFORMATION);
+export const FIELD_MAPPINGS = {
+    timestamp: {
+        created: 'created_at',
+        modified: 'modified_at',
+        updated: 'modified_at', // Alias - Attio uses modified_at
+        interacted: 'interacted_at',
+    },
+    system: {
+        id: 'record_id',
+        workspace: 'workspace_id',
+        object: 'object_id',
+    },
+};
+/**
+ * Deprecated field mappings that should show warnings
+ */
+const DEPRECATED_FIELDS = {
+    updated_at: 'modified_at',
+    update_date: 'modified_at',
+    last_updated: 'modified_at',
+};
+/**
+ * Map generic field name to Attio-specific field name
+ * Logs deprecation warnings for unsupported aliases
+ */
+export function mapFieldName(genericField) {
+    // Check for deprecated mappings
+    const deprecated = DEPRECATED_FIELDS[genericField];
+    if (deprecated) {
+        log.warn('Deprecated field alias used', {
+            field: genericField,
+            replacement: deprecated,
+        });
+        return deprecated;
+    }
+    // Search in timestamp mappings
+    for (const [key, value] of Object.entries(FIELD_MAPPINGS.timestamp)) {
+        if (key === genericField) {
+            return value;
+        }
+    }
+    // Search in system mappings
+    for (const [key, value] of Object.entries(FIELD_MAPPINGS.system)) {
+        if (key === genericField) {
+            return value;
+        }
+    }
+    // Return as-is if no mapping found (might be valid Attio field)
+    return genericField;
+}
+/**
+ * Get all valid timestamp field names for a given resource
+ * Different resources may support different timestamp fields
+ */
+export function getValidTimestampFields(resourceType) {
+    const baseFields = ['created_at', 'modified_at'];
+    switch (resourceType) {
+        case 'companies':
+        case 'people':
+            return [...baseFields, 'interacted_at'];
+        case 'tasks':
+            return [...baseFields, 'due_date', 'completed_at'];
+        case 'notes':
+            return baseFields; // Notes typically only have created_at/modified_at
+        default:
+            return baseFields;
+    }
+}
+/**
+ * Validate if a field name is supported for timeframe filtering
+ */
+export function isValidTimestampField(fieldName, resourceType) {
+    const validFields = getValidTimestampFields(resourceType);
+    return validFields.includes(fieldName);
+}
+//# sourceMappingURL=AttioFieldMapper.js.map

package/dist/utils/AttioFieldMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttioFieldMapper.js","sourceRoot":"","sources":["../../src/utils/AttioFieldMapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,GAAG,GAAG,kBAAkB,CAC5B,wBAAwB,EACxB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS,EAAE;QACT,OAAO,EAAE,YAAY;QACrB,QAAQ,EAAE,aAAa;QACvB,OAAO,EAAE,aAAa,EAAE,iCAAiC;QACzD,UAAU,EAAE,eAAe;KAC5B;IACD,MAAM,EAAE;QACN,EAAE,EAAE,WAAW;QACf,SAAS,EAAE,cAAc;QACzB,MAAM,EAAE,WAAW;KACpB;CACO,CAAC;AAEX;;GAEG;AACH,MAAM,iBAAiB,GAA2B;IAChD,UAAU,EAAE,aAAa;IACzB,WAAW,EAAE,aAAa;IAC1B,YAAY,EAAE,aAAa;CAC5B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB;IAC/C,gCAAgC;IAChC,MAAM,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IACnD,IAAI,UAAU,EAAE,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,6BAA6B,EAAE;YACtC,KAAK,EAAE,YAAY;YACnB,WAAW,EAAE,UAAU;SACxB,CAAC,CAAC;QACH,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,+BAA+B;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC;QACpE,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;QACjE,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAAoB;IAC1D,MAAM,UAAU,GAAG,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IAEjD,QAAQ,YAAY,EAAE,CAAC;QACrB,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ;YACX,OAAO,CAAC,GAAG,UAAU,EAAE,eAAe,CAAC,CAAC;QAC1C,KAAK,OAAO;YACV,OAAO,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;QACrD,KAAK,OAAO;YACV,OAAO,UAAU,CAAC,CAAC,mDAAmD;QACxE;YACE,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAiB,EACjB,YAAoB;IAEpB,MAAM,WAAW,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAC;IAC1D,OAAO,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC"}

package/dist/utils/AttioFilterOperators.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Attio API Filter Operators and Validation
+ *
+ * Based on official Attio API documentation (Context7 research)
+ * Provides operator normalization, validation, and 429 backoff handling
+ */
+export declare enum FilterOperator {
+    EQUALS = "$eq",
+    NOT_EMPTY = "$not_empty",
+    CONTAINS = "$contains",
+    STARTS_WITH = "$starts_with",
+    ENDS_WITH = "$ends_with",
+    GREATER_THAN = "$gt",
+    GREATER_THAN_OR_EQUAL = "$gte",
+    LESS_THAN = "$lt",
+    LESS_THAN_OR_EQUAL = "$lte",
+    IN = "$in",
+    AND = "$and",
+    OR = "$or",
+    NOT = "$not"
+}
+export declare function isValidOperator(op: string): boolean;
+/**
+ * Normalize legacy operators to proper $ prefixed format
+ * Logs deprecation warnings for legacy usage
+ */
+export declare function normalizeOperator(op: string): FilterOperator;
+/**
+ * Validate filter operator and value shape
+ */
+export declare function validateFilter(operator: string, value: unknown): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Lightweight concurrency semaphore (no external deps)
+ * Includes 429-specific backoff with jitter
+ */
+export declare class AttioRateLimitSemaphore {
+    private maxConcurrent;
+    private running;
+    private queue;
+    constructor(maxConcurrent?: number);
+    acquire<T>(fn: () => Promise<T>): Promise<T>;
+    private withRetry;
+    private processQueue;
+}
+export declare const apiSemaphore: AttioRateLimitSemaphore;
+//# sourceMappingURL=AttioFilterOperators.d.ts.map

package/dist/utils/AttioFilterOperators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttioFilterOperators.d.ts","sourceRoot":"","sources":["../../src/utils/AttioFilterOperators.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oBAAY,cAAc;IAExB,MAAM,QAAQ;IACd,SAAS,eAAe;IAGxB,QAAQ,cAAc;IACtB,WAAW,iBAAiB;IAC5B,SAAS,eAAe;IAGxB,YAAY,QAAQ;IACpB,qBAAqB,SAAS;IAC9B,SAAS,QAAQ;IACjB,kBAAkB,SAAS;IAG3B,EAAE,QAAQ;IAGV,GAAG,SAAS;IACZ,EAAE,QAAQ;IACV,GAAG,SAAS;CACb;AAoBD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAwB5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyCpC;AAED;;;GAGG;AACH,qBAAa,uBAAuB;IAOhC,OAAO,CAAC,aAAa;IANvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAyB;gBAK5B,aAAa,SAAI;IAGrB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;YAwBpC,SAAS;IA8BvB,OAAO,CAAC,YAAY;CAMrB;AAGD,eAAO,MAAM,YAAY,yBAAiC,CAAC"}

package/dist/utils/AttioFilterOperators.js

@@ -0,0 +1,173 @@
+/**
+ * Attio API Filter Operators and Validation
+ *
+ * Based on official Attio API documentation (Context7 research)
+ * Provides operator normalization, validation, and 429 backoff handling
+ */
+import { warn, OperationType } from './logger.js';
+export var FilterOperator;
+(function (FilterOperator) {
+    // Equality and existence
+    FilterOperator["EQUALS"] = "$eq";
+    FilterOperator["NOT_EMPTY"] = "$not_empty";
+    // String operations
+    FilterOperator["CONTAINS"] = "$contains";
+    FilterOperator["STARTS_WITH"] = "$starts_with";
+    FilterOperator["ENDS_WITH"] = "$ends_with";
+    // Numeric/date comparisons
+    FilterOperator["GREATER_THAN"] = "$gt";
+    FilterOperator["GREATER_THAN_OR_EQUAL"] = "$gte";
+    FilterOperator["LESS_THAN"] = "$lt";
+    FilterOperator["LESS_THAN_OR_EQUAL"] = "$lte";
+    // Array operations (resource-specific)
+    FilterOperator["IN"] = "$in";
+    // Logical combinators (filter-expression level)
+    FilterOperator["AND"] = "$and";
+    FilterOperator["OR"] = "$or";
+    FilterOperator["NOT"] = "$not";
+})(FilterOperator || (FilterOperator = {}));
+/**
+ * Legacy operator mappings for backward compatibility
+ * Logs deprecation warnings when used
+ */
+const LEGACY_OPERATOR_MAP = {
+    gte: FilterOperator.GREATER_THAN_OR_EQUAL,
+    lte: FilterOperator.LESS_THAN_OR_EQUAL,
+    gt: FilterOperator.GREATER_THAN,
+    lt: FilterOperator.LESS_THAN,
+    eq: FilterOperator.EQUALS,
+    not_empty: FilterOperator.NOT_EMPTY,
+    is_not_empty: FilterOperator.NOT_EMPTY, // Common mistake
+    contains: FilterOperator.CONTAINS,
+    starts_with: FilterOperator.STARTS_WITH,
+    ends_with: FilterOperator.ENDS_WITH,
+    in: FilterOperator.IN,
+};
+export function isValidOperator(op) {
+    return Object.values(FilterOperator).includes(op);
+}
+/**
+ * Normalize legacy operators to proper $ prefixed format
+ * Logs deprecation warnings for legacy usage
+ */
+export function normalizeOperator(op) {
+    // Already normalized
+    if (isValidOperator(op)) {
+        return op;
+    }
+    // Legacy mapping with warning
+    const normalized = LEGACY_OPERATOR_MAP[op];
+    if (normalized) {
+        warn('utils/AttioFilterOperators', `Deprecated operator '${op}' used. Use '${normalized}' instead.`, { deprecatedOperator: op, suggestedOperator: normalized }, 'normalizeFilterOperator', OperationType.VALIDATION);
+        return normalized;
+    }
+    throw new Error(`Invalid filter operator: '${op}'. Supported: ${Object.values(FilterOperator).join(', ')}`);
+}
+/**
+ * Validate filter operator and value shape
+ */
+export function validateFilter(operator, value) {
+    const normalizedOp = normalizeOperator(operator);
+    switch (normalizedOp) {
+        case FilterOperator.NOT_EMPTY:
+            if (typeof value !== 'boolean') {
+                return {
+                    valid: false,
+                    error: '$not_empty requires boolean value (true)',
+                };
+            }
+            break;
+        case FilterOperator.IN:
+            if (!Array.isArray(value)) {
+                return { valid: false, error: '$in requires array value' };
+            }
+            break;
+        case FilterOperator.GREATER_THAN:
+        case FilterOperator.GREATER_THAN_OR_EQUAL:
+        case FilterOperator.LESS_THAN:
+        case FilterOperator.LESS_THAN_OR_EQUAL:
+            if (typeof value !== 'string' && typeof value !== 'number') {
+                return {
+                    valid: false,
+                    error: `${normalizedOp} requires string or number value`,
+                };
+            }
+            break;
+        case FilterOperator.CONTAINS:
+        case FilterOperator.STARTS_WITH:
+        case FilterOperator.ENDS_WITH:
+            if (typeof value !== 'string') {
+                return { valid: false, error: `${normalizedOp} requires string value` };
+            }
+            break;
+    }
+    return { valid: true };
+}
+/**
+ * Lightweight concurrency semaphore (no external deps)
+ * Includes 429-specific backoff with jitter
+ */
+export class AttioRateLimitSemaphore {
+    maxConcurrent;
+    running = 0;
+    queue = [];
+    constructor(
+    // Conservative limit to avoid rate limiting (429) errors
+    // Attio API typically allows ~10 req/sec, we use 4 concurrent for safety margin
+    maxConcurrent = 4) {
+        this.maxConcurrent = maxConcurrent;
+    }
+    async acquire(fn) {
+        return new Promise((resolve, reject) => {
+            const execute = async () => {
+                this.running++;
+                try {
+                    const result = await this.withRetry(fn);
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+                finally {
+                    this.running--;
+                    this.processQueue();
+                }
+            };
+            if (this.running < this.maxConcurrent) {
+                execute();
+            }
+            else {
+                this.queue.push(execute);
+            }
+        });
+    }
+    async withRetry(fn, attempt = 1) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // 429 backoff with jitter
+            const maxRetries = 4;
+            if (error?.status === 429 &&
+                attempt <= maxRetries) {
+                const baseDelay = Math.pow(2, attempt - 1) * 250; // 250ms, 500ms, 1s, 2s
+                const jitter = Math.random() * 100; // 0-100ms jitter
+                const delay = baseDelay + jitter;
+                warn('utils/AttioFilterOperators', `Rate limit hit, retrying in ${Math.round(delay)}ms (attempt ${attempt})`, { delayMs: Math.round(delay), attempt, maxRetries }, 'AttioRateLimitSemaphore', OperationType.API_CALL);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this.withRetry(fn, attempt + 1);
+            }
+            throw error;
+        }
+    }
+    processQueue() {
+        if (this.queue.length > 0 && this.running < this.maxConcurrent) {
+            const next = this.queue.shift();
+            if (next)
+                next();
+        }
+    }
+}
+// Global semaphore instance
+export const apiSemaphore = new AttioRateLimitSemaphore(4);
+//# sourceMappingURL=AttioFilterOperators.js.map