attio-mcp 0.1.0

package/dist/utils/filters/utils.js

@@ -0,0 +1,142 @@
+/**
+ * General filter utility functions
+ * Consolidates utilities from filter-utils.ts and filter-utils-additions.ts
+ */
+import { ATTRIBUTES, FilterConditionType, } from './types.js';
+import { resolveDateRange } from '../date-utils.js';
+/**
+ * Creates a filter for records based on their creation date
+ *
+ * @param dateRange - Date range specification
+ * @returns Configured filter object
+ */
+export function createCreatedDateFilter(dateRange) {
+    return createDateRangeFilter(ATTRIBUTES.CREATED_AT, dateRange);
+}
+/**
+ * Creates a filter for records based on their last modification date
+ *
+ * @param dateRange - Date range specification
+ * @returns Configured filter object
+ */
+export function createModifiedDateFilter(dateRange) {
+    return createDateRangeFilter(ATTRIBUTES.UPDATED_AT, dateRange);
+}
+/**
+ * Creates a filter for B2B Segment (type_persona)
+ *
+ * @param value - B2B Segment value to filter by
+ * @returns Configured filter object
+ */
+export function createB2BSegmentFilter(value) {
+    // Using a simple equals filter that will be transformed using the shorthand format
+    return {
+        filters: [
+            {
+                attribute: { slug: 'type_persona' },
+                condition: FilterConditionType.EQUALS, // This won't be used for type_persona due to shorthand format
+                value,
+            },
+        ],
+        matchAny: false,
+    };
+}
+/**
+ * Validates if a value falls within a numeric range
+ *
+ * @param value - The value to check
+ * @param range - The numeric range to validate against
+ * @returns True if value is within range
+ */
+export function isInNumericRange(value, range) {
+    if (range.equals !== undefined) {
+        return value === range.equals;
+    }
+    if (range.min !== undefined && value < range.min) {
+        return false;
+    }
+    if (range.max !== undefined && value > range.max) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Checks if a date string falls within a date range
+ *
+ * @param dateStr - ISO date string to check
+ * @param range - Date range to validate against
+ * @returns True if date is within range
+ */
+export function isInDateRange(dateStr, range) {
+    const date = new Date(dateStr);
+    const resolvedRange = resolveDateRange(range);
+    if (resolvedRange.start) {
+        const startDate = new Date(resolvedRange.start);
+        if (date < startDate)
+            return false;
+    }
+    if (resolvedRange.end) {
+        const endDate = new Date(resolvedRange.end);
+        if (date > endDate)
+            return false;
+    }
+    return true;
+}
+/**
+ * Debug logging for filter operations
+ *
+ * @param operation - The operation being performed
+ * @param details - Additional details to log
+ */
+export function debugFilterLog(operation, details) {
+    if (process.env.NODE_ENV === 'development') {
+        console.log(`[Filter ${operation}]`, details);
+    }
+}
+/**
+ * Determines if a filter attribute represents a date field
+ *
+ * @param attributeSlug - The attribute slug to check
+ * @returns True if the attribute is a date field
+ */
+export function isDateAttribute(attributeSlug) {
+    const dateAttributes = [
+        ATTRIBUTES.CREATED_AT,
+        ATTRIBUTES.UPDATED_AT,
+        ATTRIBUTES.LAST_INTERACTION,
+    ];
+    return dateAttributes.includes(attributeSlug);
+}
+/**
+ * Determines if a filter attribute represents a numeric field
+ *
+ * @param attributeSlug - The attribute slug to check
+ * @returns True if the attribute is a numeric field
+ */
+export function isNumericAttribute(attributeSlug) {
+    const numericAttributes = [ATTRIBUTES.REVENUE, ATTRIBUTES.EMPLOYEE_COUNT];
+    return numericAttributes.includes(attributeSlug);
+}
+/**
+ * Determines if a filter attribute represents a text field
+ *
+ * @param attributeSlug - The attribute slug to check
+ * @returns True if the attribute is a text field
+ */
+export function isTextAttribute(attributeSlug) {
+    const textAttributes = [
+        ATTRIBUTES.NAME,
+        ATTRIBUTES.EMAIL,
+        ATTRIBUTES.WEBSITE,
+        ATTRIBUTES.NOTE_CONTENT,
+        ATTRIBUTES.INDUSTRY,
+    ];
+    return textAttributes.includes(attributeSlug);
+}
+/**
+ * Helper function to extract attribute mappings as needed
+ * Re-exports builder functions as utilities for backward compatibility
+ */
+import { createDateRangeFilter, createEqualsFilter, createContainsFilter, } from './builders.js';
+export { createDateRangeFilter, createEqualsFilter, createContainsFilter };
+//# sourceMappingURL=utils.js.map

package/dist/utils/filters/utils.js.map

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

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

@@ -0,0 +1,123 @@
+/**
+ * @module validation-utils
+ *
+ * Centralized validation utilities for filter structures
+ * Provides consistent error message formatting and reusable validation functions
+ */
+import { ListEntryFilter, ListEntryFilters } from './types.js';
+import { ValidatedListEntryFilters } from '../../api/operations/types.js';
+/**
+ * Error message templates for consistent error formatting
+ */
+export declare const ERROR_MESSAGES: {
+    MISSING_FILTERS: string;
+    FILTERS_NOT_ARRAY: (type: string) => string;
+    MISSING_FILTERS_PROPERTY: string;
+    EMPTY_FILTERS_ARRAY: string;
+    INVALID_FILTER_STRUCTURE: (index: number, reason: string) => string;
+    MISSING_ATTRIBUTE: string;
+    MISSING_ATTRIBUTE_SLUG: string;
+    MISSING_CONDITION: string;
+    INVALID_CONDITION: (condition: string, validConditions: string[]) => string;
+    ALL_FILTERS_INVALID: string;
+};
+/**
+ * Standard example format for filter structures to include in error messages
+ */
+export declare const FILTER_EXAMPLES: {
+    SIMPLE: string;
+    OR_LOGIC: string;
+    MULTIPLE_CONDITIONS: string;
+};
+/**
+ * Validates the basic filter structure ensuring filters object has required properties
+ *
+ * This function performs structural validation to ensure:
+ * - The filters parameter is not null/undefined
+ * - The filters object has a 'filters' property
+ * - The 'filters' property is an array
+ *
+ * @param filters - The filters object to validate (may be undefined/null from user input)
+ * @returns Validated filters object with guaranteed filters array
+ * @throws FilterValidationError with consistent error messages and appropriate categories
+ *
+ * @example
+ * ```typescript
+ * const validated = validateFiltersObject({
+ *   filters: [{ attribute: { slug: 'name' }, condition: 'equals', value: 'test' }]
+ * });
+ * // validated.filters is guaranteed to be an array
+ * ```
+ */
+export declare function validateFiltersObject(filters: ListEntryFilters | undefined): ValidatedListEntryFilters;
+/**
+ * Validates each individual filter in a filters array
+ * Returns list of invalid filters with reasons
+ *
+ * @param filters - Array of filter objects to validate
+ * @param validateConditions - Whether to validate condition values
+ * @returns Array of objects containing invalid filter index, reason and filter object
+ */
+export declare function collectInvalidFilters(filters: ListEntryFilter[], validateConditions?: boolean): {
+    index: number;
+    reason: string;
+    filter: any;
+}[];
+/**
+ * Creates a consistently formatted error message for invalid filters
+ *
+ * @param invalidFilters - Array of invalid filter objects with reasons
+ * @returns Formatted error message with details
+ */
+export declare function formatInvalidFiltersError(invalidFilters: {
+    index: number;
+    reason: string;
+    filter: any;
+}[]): string;
+/**
+ * Full validation of filters with detailed error messages and examples
+ *
+ * This is the primary entry point for filter validation. It performs:
+ * 1. Structural validation using validateFiltersObject()
+ * 2. Individual filter validation for each filter in the array
+ * 3. Condition validation if enabled
+ * 4. Comprehensive error reporting with examples
+ *
+ * @param filters - Filter object to validate (may have optional filters array)
+ * @param validateConditions - Whether to validate condition values against known operators
+ * @returns Validated filters with guaranteed filters array and valid structure
+ * @throws FilterValidationError with detailed messages, examples, and appropriate categories
+ *
+ * @example
+ * ```typescript
+ * // Valid usage
+ * const validated = validateFilters({
+ *   filters: [
+ *     { attribute: { slug: 'name' }, condition: 'equals', value: 'John' },
+ *     { attribute: { slug: 'age' }, condition: 'greater_than', value: 18 }
+ *   ],
+ *   matchAny: false
+ * }, true);
+ *
+ * // validated.filters is guaranteed to exist and be valid
+ * ```
+ *
+ * @see validateFiltersObject For structural validation
+ * @see collectInvalidFilters For individual filter validation logic
+ */
+export declare function validateFilters(filters: ListEntryFilters | undefined, validateConditions?: boolean): ValidatedListEntryFilters;
+/**
+ * Helper function to get a descriptive reason for an invalid filter
+ *
+ * @param filter - The filter to analyze
+ * @returns A string describing what's wrong with the filter
+ */
+export declare function getInvalidFilterReason(filter: any): string;
+/**
+ * Generate examples for different filter scenarios
+ *
+ * @param filterType - The type of filter example to generate (simple, or, multiple)
+ * @returns A string with the example in JSON format
+ */
+export declare function getFilterExample(filterType?: 'simple' | 'or' | 'multiple'): string;
+//# sourceMappingURL=validation-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/filters/validation-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAG1E;;GAEG;AACH,eAAO,MAAM,cAAc;;8BAEC,MAAM;;;sCAIE,MAAM,UAAU,MAAM;;;;mCAKzB,MAAM,mBAAmB,MAAM,EAAE;;CAMjE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe;;;;CAuC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GACpC,yBAAyB,CA2B3B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EAAE,EAC1B,kBAAkB,GAAE,OAAc,GACjC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,EAAE,CAyDlD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,EAAE,GAC/D,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,kBAAkB,GAAE,OAAc,GACjC,yBAAyB,CA4C3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,CAsB1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,GAAE,QAAQ,GAAG,IAAI,GAAG,UAAqB,GAClD,MAAM,CAUR"}

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

@@ -0,0 +1,282 @@
+/**
+ * @module validation-utils
+ *
+ * Centralized validation utilities for filter structures
+ * Provides consistent error message formatting and reusable validation functions
+ */
+import { FilterValidationError, FilterErrorCategory, } from '../../errors/api-errors.js';
+import { isValidFilterCondition } from '../../types/attio.js';
+/**
+ * Error message templates for consistent error formatting
+ */
+export const ERROR_MESSAGES = {
+    MISSING_FILTERS: 'Filter object is required but was undefined or null',
+    FILTERS_NOT_ARRAY: (type) => `Invalid filter structure: 'filters' property must be an array but got ${type}`,
+    MISSING_FILTERS_PROPERTY: 'Filters must include a "filters" array property',
+    EMPTY_FILTERS_ARRAY: 'No filters provided in the filters array',
+    INVALID_FILTER_STRUCTURE: (index, reason) => `Invalid filter structure at index ${index}: ${reason}`,
+    MISSING_ATTRIBUTE: 'missing attribute object',
+    MISSING_ATTRIBUTE_SLUG: 'missing attribute.slug property',
+    MISSING_CONDITION: 'missing condition property',
+    INVALID_CONDITION: (condition, validConditions) => `Invalid filter condition '${condition}'. Valid conditions are: ${validConditions.join(', ')}`,
+    ALL_FILTERS_INVALID: 'All filters are invalid. Please provide at least one valid filter.',
+};
+/**
+ * Standard example format for filter structures to include in error messages
+ */
+export const FILTER_EXAMPLES = {
+    SIMPLE: `{
+  "filters": [
+    {
+      "attribute": { "slug": "name" },
+      "condition": "contains",
+      "value": "Company Inc"
+    }
+  ]
+}`,
+    OR_LOGIC: `{
+  "filters": [
+    {
+      "attribute": { "slug": "name" },
+      "condition": "contains",
+      "value": "Inc"
+    },
+    {
+      "attribute": { "slug": "industry" },
+      "condition": "equals",
+      "value": "Technology"
+    }
+  ],
+  "matchAny": true
+}`,
+    MULTIPLE_CONDITIONS: `{
+  "filters": [
+    {
+      "attribute": { "slug": "name" },
+      "condition": "contains", 
+      "value": "Inc"
+    },
+    {
+      "attribute": { "slug": "website" },
+      "condition": "contains",
+      "value": ".com"
+    }
+  ]
+}`,
+};
+/**
+ * Validates the basic filter structure ensuring filters object has required properties
+ *
+ * This function performs structural validation to ensure:
+ * - The filters parameter is not null/undefined
+ * - The filters object has a 'filters' property
+ * - The 'filters' property is an array
+ *
+ * @param filters - The filters object to validate (may be undefined/null from user input)
+ * @returns Validated filters object with guaranteed filters array
+ * @throws FilterValidationError with consistent error messages and appropriate categories
+ *
+ * @example
+ * ```typescript
+ * const validated = validateFiltersObject({
+ *   filters: [{ attribute: { slug: 'name' }, condition: 'equals', value: 'test' }]
+ * });
+ * // validated.filters is guaranteed to be an array
+ * ```
+ */
+export function validateFiltersObject(filters) {
+    // Check if filters is undefined or null
+    if (!filters) {
+        throw new FilterValidationError(ERROR_MESSAGES.MISSING_FILTERS, FilterErrorCategory.STRUCTURE);
+    }
+    // Check if filters has a filters property
+    if (!('filters' in filters)) {
+        throw new FilterValidationError(ERROR_MESSAGES.MISSING_FILTERS_PROPERTY, FilterErrorCategory.STRUCTURE);
+    }
+    // Check if filters.filters is an array
+    if (!Array.isArray(filters.filters)) {
+        throw new FilterValidationError(ERROR_MESSAGES.FILTERS_NOT_ARRAY(typeof filters.filters), FilterErrorCategory.STRUCTURE);
+    }
+    // Return the validated filters with the correct type
+    return filters;
+}
+/**
+ * Validates each individual filter in a filters array
+ * Returns list of invalid filters with reasons
+ *
+ * @param filters - Array of filter objects to validate
+ * @param validateConditions - Whether to validate condition values
+ * @returns Array of objects containing invalid filter index, reason and filter object
+ */
+export function collectInvalidFilters(filters, validateConditions = true) {
+    const invalidFilters = [];
+    // Check each filter in the array
+    filters.forEach((filter, index) => {
+        // Check if filter is a valid object
+        if (!filter || typeof filter !== 'object') {
+            invalidFilters.push({
+                index,
+                reason: `Filter at index ${index} is ${filter === null ? 'null' : typeof filter}`,
+                filter,
+            });
+            return;
+        }
+        // Check for required properties
+        if (!filter.attribute) {
+            invalidFilters.push({
+                index,
+                reason: ERROR_MESSAGES.MISSING_ATTRIBUTE,
+                filter,
+            });
+            return;
+        }
+        if (!filter.attribute.slug) {
+            invalidFilters.push({
+                index,
+                reason: ERROR_MESSAGES.MISSING_ATTRIBUTE_SLUG,
+                filter,
+            });
+            return;
+        }
+        if (!filter.condition) {
+            invalidFilters.push({
+                index,
+                reason: ERROR_MESSAGES.MISSING_CONDITION,
+                filter,
+            });
+            return;
+        }
+        // Validate condition if enabled
+        if (validateConditions && !isValidFilterCondition(filter.condition)) {
+            invalidFilters.push({
+                index,
+                reason: `Invalid condition '${filter.condition}'`,
+                filter,
+            });
+            return;
+        }
+    });
+    return invalidFilters;
+}
+/**
+ * Creates a consistently formatted error message for invalid filters
+ *
+ * @param invalidFilters - Array of invalid filter objects with reasons
+ * @returns Formatted error message with details
+ */
+export function formatInvalidFiltersError(invalidFilters) {
+    if (invalidFilters.length === 0) {
+        return '';
+    }
+    const errorDetails = invalidFilters
+        .map((f) => `Filter [${f.index}]: ${f.reason}`)
+        .join('; ');
+    return errorDetails;
+}
+/**
+ * Full validation of filters with detailed error messages and examples
+ *
+ * This is the primary entry point for filter validation. It performs:
+ * 1. Structural validation using validateFiltersObject()
+ * 2. Individual filter validation for each filter in the array
+ * 3. Condition validation if enabled
+ * 4. Comprehensive error reporting with examples
+ *
+ * @param filters - Filter object to validate (may have optional filters array)
+ * @param validateConditions - Whether to validate condition values against known operators
+ * @returns Validated filters with guaranteed filters array and valid structure
+ * @throws FilterValidationError with detailed messages, examples, and appropriate categories
+ *
+ * @example
+ * ```typescript
+ * // Valid usage
+ * const validated = validateFilters({
+ *   filters: [
+ *     { attribute: { slug: 'name' }, condition: 'equals', value: 'John' },
+ *     { attribute: { slug: 'age' }, condition: 'greater_than', value: 18 }
+ *   ],
+ *   matchAny: false
+ * }, true);
+ *
+ * // validated.filters is guaranteed to exist and be valid
+ * ```
+ *
+ * @see validateFiltersObject For structural validation
+ * @see collectInvalidFilters For individual filter validation logic
+ */
+export function validateFilters(filters, validateConditions = true) {
+    // First validate basic structure
+    const validatedFilters = validateFiltersObject(filters);
+    // Handle empty or undefined filters array (valid but returns no results)
+    if (!validatedFilters.filters || validatedFilters.filters.length === 0) {
+        return validatedFilters;
+    }
+    // Collect invalid filters
+    const invalidFilters = collectInvalidFilters(validatedFilters.filters, validateConditions);
+    // If all filters are invalid, throw error with examples
+    if (invalidFilters.length === validatedFilters.filters.length) {
+        const errorDetails = formatInvalidFiltersError(invalidFilters);
+        let errorMessage = `${ERROR_MESSAGES.ALL_FILTERS_INVALID} ${errorDetails}`;
+        // Add examples to help the user fix their filters
+        errorMessage +=
+            '\n\nExample of valid filter structure: \n' + FILTER_EXAMPLES.SIMPLE;
+        // Determine most appropriate error category based on invalid filters
+        let category = FilterErrorCategory.STRUCTURE;
+        // If we have specific attribute issues
+        if (invalidFilters.some((f) => f.reason.includes('attribute'))) {
+            category = FilterErrorCategory.ATTRIBUTE;
+        }
+        // If we have specific condition issues
+        else if (invalidFilters.some((f) => f.reason.includes('condition'))) {
+            category = FilterErrorCategory.CONDITION;
+        }
+        // If we have specific value issues
+        else if (invalidFilters.some((f) => f.reason.includes('value'))) {
+            category = FilterErrorCategory.VALUE;
+        }
+        throw new FilterValidationError(errorMessage, category);
+    }
+    return validatedFilters;
+}
+/**
+ * Helper function to get a descriptive reason for an invalid filter
+ *
+ * @param filter - The filter to analyze
+ * @returns A string describing what's wrong with the filter
+ */
+export function getInvalidFilterReason(filter) {
+    if (!filter || typeof filter !== 'object') {
+        return `filter is ${filter === null ? 'null' : typeof filter}`;
+    }
+    if (!filter.attribute) {
+        return ERROR_MESSAGES.MISSING_ATTRIBUTE;
+    }
+    if (!filter.attribute.slug) {
+        return ERROR_MESSAGES.MISSING_ATTRIBUTE_SLUG;
+    }
+    if (!filter.condition) {
+        return ERROR_MESSAGES.MISSING_CONDITION;
+    }
+    if (!isValidFilterCondition(filter.condition)) {
+        return `invalid condition '${filter.condition}'`;
+    }
+    return 'unknown issue';
+}
+/**
+ * Generate examples for different filter scenarios
+ *
+ * @param filterType - The type of filter example to generate (simple, or, multiple)
+ * @returns A string with the example in JSON format
+ */
+export function getFilterExample(filterType = 'simple') {
+    switch (filterType) {
+        case 'or':
+            return FILTER_EXAMPLES.OR_LOGIC;
+        case 'multiple':
+            return FILTER_EXAMPLES.MULTIPLE_CONDITIONS;
+        case 'simple':
+        default:
+            return FILTER_EXAMPLES.SIMPLE;
+    }
+}
+//# sourceMappingURL=validation-utils.js.map

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

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

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

@@ -0,0 +1,73 @@
+/**
+ * @module validators
+ *
+ * Consolidated filter validation utilities
+ * Provides functions to validate and normalize filter parameters
+ *
+ * This module provides:
+ * - Structure validation for filter objects
+ * - Date range validation and normalization
+ * - Numeric range validation
+ * - Activity filter validation
+ * - Filter condition validation
+ * - Parameter type validation and conversion
+ */
+import { DateRange, ActivityFilter, NumericRange, FilterConditionType, ListEntryFilter } from './types.js';
+/**
+ * Validates a filter structure for basic required properties
+ *
+ * @param filter - The filter to validate
+ * @returns True if filter is valid, false otherwise
+ */
+export declare function validateFilterStructure(filter: ListEntryFilter): boolean;
+/**
+ * Validates a date range object
+ *
+ * @param dateRange - The date range to validate
+ * @returns Validated and normalized date range
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateDateRange(dateRange: any): DateRange;
+/**
+ * Validates an activity filter object
+ *
+ * @param activityFilter - The activity filter to validate
+ * @returns Validated and normalized activity filter
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateActivityFilter(activityFilter: any): ActivityFilter;
+/**
+ * Validates a numeric range object
+ *
+ * @param range - The numeric range to validate
+ * @returns Validated and normalized numeric range
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateNumericRange(range: any): NumericRange;
+/**
+ * Validates a filter condition string
+ *
+ * @param condition - The condition to validate
+ * @returns The validated condition
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateFilterCondition(condition: string): FilterConditionType;
+/**
+ * Ensures a value is a number, converting if necessary
+ *
+ * @param value - The value to validate and convert
+ * @param paramName - Name of the parameter (for error messages)
+ * @param defaultValue - Optional default value if undefined
+ * @returns The validated number
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateNumericParam(value: any, paramName: string, defaultValue?: number): number;
+/**
+ * Validates filter structure and conditions
+ *
+ * @param filter - The filter to validate
+ * @param validateConditions - Whether to validate condition types (default: true)
+ * @throws FilterValidationError if validation fails
+ */
+export declare function validateFilterWithConditions(filter: ListEntryFilter, validateConditions?: boolean): void;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/utils/filters/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,EACL,SAAS,EACT,cAAc,EAEd,YAAY,EACZ,mBAAmB,EACnB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAcxE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,GAAG,GAAG,SAAS,CAoJ3D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,GAAG,GAAG,cAAc,CA2D1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,YAAY,CAgF7D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB,mBAAmB,CAerB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,eAAe,EACvB,kBAAkB,GAAE,OAAc,GACjC,IAAI,CAgBN"}