attio-mcp 0.1.0

package/dist/utils/logger.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Enhanced structured logging utility for consistent logging across the application
+ */
+/**
+ * Log level enum for controlling verbosity
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+/**
+ * Operation types for better log categorization
+ */
+export declare enum OperationType {
+    API_CALL = "api_call",
+    TOOL_EXECUTION = "tool_execution",
+    DATA_PROCESSING = "data_processing",
+    VALIDATION = "validation",
+    TRANSFORMATION = "transformation",
+    SYSTEM = "system"
+}
+/**
+ * Structured log metadata interface
+ */
+export interface LogMetadata {
+    timestamp: string;
+    level: string;
+    module: string;
+    operation?: string;
+    operationType?: OperationType;
+    correlationId?: string;
+    sessionId?: string;
+    duration?: number;
+    requestId?: string;
+    userId?: string;
+    [key: string]: any;
+}
+/**
+ * Structured log entry interface
+ */
+export interface LogEntry {
+    message: string;
+    metadata: LogMetadata;
+    data?: any;
+    error?: {
+        message: string;
+        name: string;
+        stack?: string;
+        code?: string | number;
+    };
+}
+/**
+ * Context for tracking related operations
+ */
+interface LogContext {
+    correlationId?: string;
+    sessionId?: string;
+    requestId?: string;
+    userId?: string;
+    operation?: string;
+    operationType?: OperationType;
+}
+/**
+ * Current log level based on environment
+ */
+export declare const CURRENT_LOG_LEVEL: LogLevel;
+/**
+ * Set global logging context for correlation tracking
+ */
+export declare function setLogContext(context: Partial<LogContext>): void;
+/**
+ * Get current logging context
+ */
+export declare function getLogContext(): LogContext;
+/**
+ * Clear logging context
+ */
+export declare function clearLogContext(): void;
+/**
+ * Generate a new correlation ID
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Log a debug message (only in development)
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export declare function debug(module: string, message: string, data?: any, operation?: string, operationType?: OperationType): void;
+/**
+ * Log an info message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export declare function info(module: string, message: string, data?: any, operation?: string, operationType?: OperationType): void;
+/**
+ * Log a warning message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export declare function warn(module: string, message: string, data?: any, operation?: string, operationType?: OperationType): void;
+/**
+ * Log an error message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param errorObj - Optional error object
+ * @param data - Optional additional data
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export declare function error(module: string, message: string, errorObj?: any, data?: any, operation?: string, operationType?: OperationType): void;
+/**
+ * Performance timing utility for tracking operation duration
+ */
+export declare class PerformanceTimer {
+    private startTime;
+    private module;
+    private operation;
+    private operationType;
+    constructor(module: string, operation: string, operationType?: OperationType);
+    /**
+     * End timing and log the duration
+     */
+    end(message?: string, data?: any): number;
+}
+/**
+ * Enhanced operation start logging with timing
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation being performed
+ * @param operationType - Type of operation for categorization
+ * @param params - Parameters for the operation
+ * @returns PerformanceTimer instance for tracking duration
+ */
+export declare function operationStart(module: string, operation: string, operationType?: OperationType, params?: any): PerformanceTimer;
+/**
+ * Logs the successful completion of an API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation being performed
+ * @param resultSummary - Summary of the operation result (e.g., count of items)
+ * @param operationType - Type of operation for categorization
+ * @param duration - Optional duration in milliseconds
+ */
+export declare function operationSuccess(module: string, operation: string, resultSummary?: any, operationType?: OperationType, duration?: number): void;
+/**
+ * Logs the failure of an API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation that failed
+ * @param errorObj - The error object
+ * @param context - Additional context information
+ * @param operationType - Type of operation for categorization
+ * @param duration - Optional duration in milliseconds
+ */
+export declare function operationFailure(module: string, operation: string, errorObj: any, context?: any, operationType?: OperationType, duration?: number): void;
+/**
+ * Logs the start of a fallback API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the fallback operation
+ * @param reason - Reason for falling back
+ * @param operationType - Type of operation for categorization
+ */
+export declare function fallbackStart(module: string, operation: string, reason: string, operationType?: OperationType): void;
+/**
+ * Creates a scoped logger instance with pre-configured context
+ */
+export declare function createScopedLogger(module: string, operation?: string, operationType?: OperationType): {
+    debug: (message: string, data?: any) => void;
+    info: (message: string, data?: any) => void;
+    warn: (message: string, data?: any) => void;
+    error: (message: string, errorObj?: any, data?: any) => void;
+    operationStart: (op?: string, opType?: OperationType, params?: any) => PerformanceTimer;
+    operationSuccess: (op?: string, resultSummary?: any, opType?: OperationType, duration?: number) => void;
+    operationFailure: (op?: string, errorObj?: any, context?: any, opType?: OperationType, duration?: number) => void;
+};
+/**
+ * Utility for wrapping async operations with automatic logging
+ */
+export declare function withLogging<T>(module: string, operation: string, operationType: OperationType, fn: () => Promise<T>, context?: any): Promise<T>;
+/**
+ * Safe logging function that never interferes with MCP protocol
+ * Always use this for any direct console logging that might occur during MCP operations
+ *
+ * @param message - Message to log
+ * @param args - Additional arguments to log
+ */
+export declare function safeMcpLog(message: string, ...args: any[]): void;
+declare const _default: {
+    debug: typeof debug;
+    info: typeof info;
+    warn: typeof warn;
+    error: typeof error;
+    operationStart: typeof operationStart;
+    operationSuccess: typeof operationSuccess;
+    operationFailure: typeof operationFailure;
+    fallbackStart: typeof fallbackStart;
+    setLogContext: typeof setLogContext;
+    getLogContext: typeof getLogContext;
+    clearLogContext: typeof clearLogContext;
+    generateCorrelationId: typeof generateCorrelationId;
+    createScopedLogger: typeof createScopedLogger;
+    withLogging: typeof withLogging;
+    safeMcpLog: typeof safeMcpLog;
+    PerformanceTimer: typeof PerformanceTimer;
+    LogLevel: typeof LogLevel;
+    OperationType: typeof OperationType;
+};
+export default _default;
+//# sourceMappingURL=logger.d.ts.map

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

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

package/dist/utils/logger.js

@@ -0,0 +1,323 @@
+/**
+ * Enhanced structured logging utility for consistent logging across the application
+ */
+import { randomUUID } from 'crypto';
+import { safeJsonStringify } from './json-serializer.js';
+/**
+ * Log level enum for controlling verbosity
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["NONE"] = 4] = "NONE";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Operation types for better log categorization
+ */
+export var OperationType;
+(function (OperationType) {
+    OperationType["API_CALL"] = "api_call";
+    OperationType["TOOL_EXECUTION"] = "tool_execution";
+    OperationType["DATA_PROCESSING"] = "data_processing";
+    OperationType["VALIDATION"] = "validation";
+    OperationType["TRANSFORMATION"] = "transformation";
+    OperationType["SYSTEM"] = "system";
+})(OperationType || (OperationType = {}));
+/**
+ * Current log level based on environment
+ */
+export const CURRENT_LOG_LEVEL = process.env.NODE_ENV === 'production'
+    ? LogLevel.INFO // In production, only log INFO and above
+    : LogLevel.DEBUG; // In development, log everything
+/**
+ * Global log context storage
+ */
+let globalContext = {};
+/**
+ * Set global logging context for correlation tracking
+ */
+export function setLogContext(context) {
+    globalContext = { ...globalContext, ...context };
+}
+/**
+ * Get current logging context
+ */
+export function getLogContext() {
+    return { ...globalContext };
+}
+/**
+ * Clear logging context
+ */
+export function clearLogContext() {
+    globalContext = {};
+}
+/**
+ * Generate a new correlation ID
+ */
+export function generateCorrelationId() {
+    return randomUUID();
+}
+/**
+ * Create structured log metadata
+ */
+function createLogMetadata(level, module, operation, operationType, additionalMetadata) {
+    return {
+        timestamp: new Date().toISOString(),
+        level,
+        module,
+        operation: operation || globalContext.operation,
+        operationType: operationType || globalContext.operationType,
+        correlationId: globalContext.correlationId,
+        sessionId: globalContext.sessionId,
+        requestId: globalContext.requestId,
+        userId: globalContext.userId,
+        ...additionalMetadata,
+    };
+}
+/**
+ * Format and output structured log entry
+ */
+function outputLog(entry, logFunction) {
+    if (process.env.LOG_FORMAT === 'json') {
+        // Output compact JSON using safe stringify to prevent errors
+        logFunction(safeJsonStringify(entry, { indent: 0 }));
+    }
+    else {
+        // Output pretty-printed JSON to maintain human readability for console,
+        // while ensuring it's a single, valid JSON string to prevent MCP parsing errors.
+        logFunction(safeJsonStringify(entry, { indent: 2 }));
+    }
+}
+/**
+ * Log a debug message (only in development)
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export function debug(module, message, data, operation, operationType) {
+    if (CURRENT_LOG_LEVEL <= LogLevel.DEBUG) {
+        const entry = {
+            message,
+            metadata: createLogMetadata('DEBUG', module, operation, operationType),
+            ...(data && { data }),
+        };
+        outputLog(entry, console.error); // Use stderr instead of stdout to avoid interfering with MCP protocol
+    }
+}
+/**
+ * Log an info message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export function info(module, message, data, operation, operationType) {
+    if (CURRENT_LOG_LEVEL <= LogLevel.INFO) {
+        const entry = {
+            message,
+            metadata: createLogMetadata('INFO', module, operation, operationType),
+            ...(data && { data }),
+        };
+        outputLog(entry, console.error); // Use stderr instead of stdout to avoid interfering with MCP protocol
+    }
+}
+/**
+ * Log a warning message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param data - Optional data to include with the log
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export function warn(module, message, data, operation, operationType) {
+    if (CURRENT_LOG_LEVEL <= LogLevel.WARN) {
+        const entry = {
+            message,
+            metadata: createLogMetadata('WARN', module, operation, operationType),
+            ...(data && { data }),
+        };
+        outputLog(entry, console.warn);
+    }
+}
+/**
+ * Log an error message
+ *
+ * @param module - Name of the module/function logging the message
+ * @param message - Message to log
+ * @param errorObj - Optional error object
+ * @param data - Optional additional data
+ * @param operation - Optional operation name
+ * @param operationType - Optional operation type
+ */
+export function error(module, message, errorObj, data, operation, operationType) {
+    if (CURRENT_LOG_LEVEL <= LogLevel.ERROR) {
+        const entry = {
+            message,
+            metadata: createLogMetadata('ERROR', module, operation, operationType),
+            ...(data && { data }),
+            ...(errorObj && {
+                error: errorObj instanceof Error
+                    ? {
+                        message: errorObj.message,
+                        name: errorObj.name,
+                        stack: errorObj.stack,
+                        code: errorObj.code,
+                    }
+                    : { message: String(errorObj), name: 'Unknown' },
+            }),
+        };
+        outputLog(entry, console.error);
+    }
+}
+/**
+ * Performance timing utility for tracking operation duration
+ */
+export class PerformanceTimer {
+    startTime;
+    module;
+    operation;
+    operationType;
+    constructor(module, operation, operationType = OperationType.SYSTEM) {
+        this.module = module;
+        this.operation = operation;
+        this.operationType = operationType;
+        this.startTime = Date.now();
+    }
+    /**
+     * End timing and log the duration
+     */
+    end(message, data) {
+        const duration = Date.now() - this.startTime;
+        debug(this.module, message || `Operation completed: ${this.operation}`, { ...data, duration: `${duration}ms` }, this.operation, this.operationType);
+        return duration;
+    }
+}
+/**
+ * Enhanced operation start logging with timing
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation being performed
+ * @param operationType - Type of operation for categorization
+ * @param params - Parameters for the operation
+ * @returns PerformanceTimer instance for tracking duration
+ */
+export function operationStart(module, operation, operationType = OperationType.SYSTEM, params) {
+    debug(module, `Starting operation: ${operation}`, params, operation, operationType);
+    return new PerformanceTimer(module, operation, operationType);
+}
+/**
+ * Logs the successful completion of an API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation being performed
+ * @param resultSummary - Summary of the operation result (e.g., count of items)
+ * @param operationType - Type of operation for categorization
+ * @param duration - Optional duration in milliseconds
+ */
+export function operationSuccess(module, operation, resultSummary, operationType = OperationType.SYSTEM, duration) {
+    const logData = {
+        ...resultSummary,
+        ...(duration && { duration: `${duration}ms` }),
+    };
+    info(module, `Operation successful: ${operation}`, logData, operation, operationType);
+}
+/**
+ * Logs the failure of an API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the operation that failed
+ * @param errorObj - The error object
+ * @param context - Additional context information
+ * @param operationType - Type of operation for categorization
+ * @param duration - Optional duration in milliseconds
+ */
+export function operationFailure(module, operation, errorObj, context, operationType = OperationType.SYSTEM, duration) {
+    const logData = {
+        ...context,
+        ...(duration && { duration: `${duration}ms` }),
+    };
+    error(module, `Operation failed: ${operation}`, errorObj, logData, operation, operationType);
+}
+/**
+ * Logs the start of a fallback API operation
+ *
+ * @param module - Name of the module/function
+ * @param operation - Name of the fallback operation
+ * @param reason - Reason for falling back
+ * @param operationType - Type of operation for categorization
+ */
+export function fallbackStart(module, operation, reason, operationType = OperationType.API_CALL) {
+    warn(module, `Trying fallback: ${operation}. Reason: ${reason}`, { reason }, operation, operationType);
+}
+/**
+ * Creates a scoped logger instance with pre-configured context
+ */
+export function createScopedLogger(module, operation, operationType) {
+    return {
+        debug: (message, data) => debug(module, message, data, operation, operationType),
+        info: (message, data) => info(module, message, data, operation, operationType),
+        warn: (message, data) => warn(module, message, data, operation, operationType),
+        error: (message, errorObj, data) => error(module, message, errorObj, data, operation, operationType),
+        operationStart: (op, opType, params) => operationStart(module, op || operation || 'unknown', opType || operationType || OperationType.SYSTEM, params),
+        operationSuccess: (op, resultSummary, opType, duration) => operationSuccess(module, op || operation || 'unknown', resultSummary, opType || operationType || OperationType.SYSTEM, duration),
+        operationFailure: (op, errorObj, context, opType, duration) => operationFailure(module, op || operation || 'unknown', errorObj, context, opType || operationType || OperationType.SYSTEM, duration),
+    };
+}
+/**
+ * Utility for wrapping async operations with automatic logging
+ */
+export async function withLogging(module, operation, operationType, fn, context) {
+    const timer = operationStart(module, operation, operationType, context);
+    try {
+        const result = await fn();
+        const duration = timer.end();
+        operationSuccess(module, operation, { success: true }, operationType, duration);
+        return result;
+    }
+    catch (error) {
+        const duration = timer.end();
+        operationFailure(module, operation, error, context, operationType, duration);
+        throw error;
+    }
+}
+/**
+ * Safe logging function that never interferes with MCP protocol
+ * Always use this for any direct console logging that might occur during MCP operations
+ *
+ * @param message - Message to log
+ * @param args - Additional arguments to log
+ */
+export function safeMcpLog(message, ...args) {
+    // Always use console.error to avoid interfering with MCP protocol
+    console.error(`[MCP_SAFE_LOG] ${message}`, ...args);
+}
+export default {
+    debug,
+    info,
+    warn,
+    error,
+    operationStart,
+    operationSuccess,
+    operationFailure,
+    fallbackStart,
+    setLogContext,
+    getLogContext,
+    clearLogContext,
+    generateCorrelationId,
+    createScopedLogger,
+    withLogging,
+    safeMcpLog,
+    PerformanceTimer,
+    LogLevel,
+    OperationType,
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;GAEG;AACH,MAAM,CAAN,IAAY,QAMX;AAND,WAAY,QAAQ;IAClB,yCAAS,CAAA;IACT,uCAAQ,CAAA;IACR,uCAAQ,CAAA;IACR,yCAAS,CAAA;IACT,uCAAQ,CAAA;AACV,CAAC,EANW,QAAQ,KAAR,QAAQ,QAMnB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,sCAAqB,CAAA;IACrB,kDAAiC,CAAA;IACjC,oDAAmC,CAAA;IACnC,0CAAyB,CAAA;IACzB,kDAAiC,CAAA;IACjC,kCAAiB,CAAA;AACnB,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB;AA8CD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAC5B,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;IACnC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,yCAAyC;IACzD,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,iCAAiC;AAEvD;;GAEG;AACH,IAAI,aAAa,GAAe,EAAE,CAAC;AAEnC;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAA4B;IACxD,aAAa,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,GAAG,aAAa,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,aAAa,GAAG,EAAE,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CACxB,KAAa,EACb,MAAc,EACd,SAAkB,EAClB,aAA6B,EAC7B,kBAAwC;IAExC,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK;QACL,MAAM;QACN,SAAS,EAAE,SAAS,IAAI,aAAa,CAAC,SAAS;QAC/C,aAAa,EAAE,aAAa,IAAI,aAAa,CAAC,aAAa;QAC3D,aAAa,EAAE,aAAa,CAAC,aAAa;QAC1C,SAAS,EAAE,aAAa,CAAC,SAAS;QAClC,SAAS,EAAE,aAAa,CAAC,SAAS;QAClC,MAAM,EAAE,aAAa,CAAC,MAAM;QAC5B,GAAG,kBAAkB;KACtB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAChB,KAAe,EACf,WAAsD;IAEtD,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;QACtC,6DAA6D;QAC7D,WAAW,CAAC,iBAAiB,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,wEAAwE;QACxE,iFAAiF;QACjF,WAAW,CAAC,iBAAiB,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CACnB,MAAc,EACd,OAAe,EACf,IAAU,EACV,SAAkB,EAClB,aAA6B;IAE7B,IAAI,iBAAiB,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACxC,MAAM,KAAK,GAAa;YACtB,OAAO;YACP,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC;YACtE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;SACtB,CAAC;QACF,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,sEAAsE;IACzG,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,MAAc,EACd,OAAe,EACf,IAAU,EACV,SAAkB,EAClB,aAA6B;IAE7B,IAAI,iBAAiB,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAa;YACtB,OAAO;YACP,QAAQ,EAAE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC;YACrE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;SACtB,CAAC;QACF,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,sEAAsE;IACzG,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,MAAc,EACd,OAAe,EACf,IAAU,EACV,SAAkB,EAClB,aAA6B;IAE7B,IAAI,iBAAiB,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAa;YACtB,OAAO;YACP,QAAQ,EAAE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC;YACrE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;SACtB,CAAC;QACF,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CACnB,MAAc,EACd,OAAe,EACf,QAAc,EACd,IAAU,EACV,SAAkB,EAClB,aAA6B;IAE7B,IAAI,iBAAiB,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACxC,MAAM,KAAK,GAAa;YACtB,OAAO;YACP,QAAQ,EAAE,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC;YACtE,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;YACrB,GAAG,CAAC,QAAQ,IAAI;gBACd,KAAK,EACH,QAAQ,YAAY,KAAK;oBACvB,CAAC,CAAC;wBACE,OAAO,EAAE,QAAQ,CAAC,OAAO;wBACzB,IAAI,EAAE,QAAQ,CAAC,IAAI;wBACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;wBACrB,IAAI,EAAG,QAAgB,CAAC,IAAI;qBAC7B;oBACH,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;aACrD,CAAC;SACH,CAAC;QACF,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,CAAS;IAClB,MAAM,CAAS;IACf,SAAS,CAAS;IAClB,aAAa,CAAgB;IAErC,YACE,MAAc,EACd,SAAiB,EACjB,gBAA+B,aAAa,CAAC,MAAM;QAEnD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,OAAgB,EAAE,IAAU;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7C,KAAK,CACH,IAAI,CAAC,MAAM,EACX,OAAO,IAAI,wBAAwB,IAAI,CAAC,SAAS,EAAE,EACnD,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,QAAQ,IAAI,EAAE,EACtC,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,aAAa,CACnB,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,SAAiB,EACjB,gBAA+B,aAAa,CAAC,MAAM,EACnD,MAAY;IAEZ,KAAK,CACH,MAAM,EACN,uBAAuB,SAAS,EAAE,EAClC,MAAM,EACN,SAAS,EACT,aAAa,CACd,CAAC;IACF,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,SAAiB,EACjB,aAAmB,EACnB,gBAA+B,aAAa,CAAC,MAAM,EACnD,QAAiB;IAEjB,MAAM,OAAO,GAAG;QACd,GAAG,aAAa;QAChB,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,GAAG,QAAQ,IAAI,EAAE,CAAC;KAC/C,CAAC;IACF,IAAI,CACF,MAAM,EACN,yBAAyB,SAAS,EAAE,EACpC,OAAO,EACP,SAAS,EACT,aAAa,CACd,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,SAAiB,EACjB,QAAa,EACb,OAAa,EACb,gBAA+B,aAAa,CAAC,MAAM,EACnD,QAAiB;IAEjB,MAAM,OAAO,GAAG;QACd,GAAG,OAAO;QACV,GAAG,CAAC,QAAQ,IAAI,EAAE,QAAQ,EAAE,GAAG,QAAQ,IAAI,EAAE,CAAC;KAC/C,CAAC;IACF,KAAK,CACH,MAAM,EACN,qBAAqB,SAAS,EAAE,EAChC,QAAQ,EACR,OAAO,EACP,SAAS,EACT,aAAa,CACd,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,SAAiB,EACjB,MAAc,EACd,gBAA+B,aAAa,CAAC,QAAQ;IAErD,IAAI,CACF,MAAM,EACN,oBAAoB,SAAS,aAAa,MAAM,EAAE,EAClD,EAAE,MAAM,EAAE,EACV,SAAS,EACT,aAAa,CACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,SAAkB,EAClB,aAA6B;IAE7B,OAAO;QACL,KAAK,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE,CACrC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC;QACxD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE,CACpC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC;QACvD,IAAI,EAAE,CAAC,OAAe,EAAE,IAAU,EAAE,EAAE,CACpC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC;QACvD,KAAK,EAAE,CAAC,OAAe,EAAE,QAAc,EAAE,IAAU,EAAE,EAAE,CACrD,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC;QAClE,cAAc,EAAE,CAAC,EAAW,EAAE,MAAsB,EAAE,MAAY,EAAE,EAAE,CACpE,cAAc,CACZ,MAAM,EACN,EAAE,IAAI,SAAS,IAAI,SAAS,EAC5B,MAAM,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,EAC/C,MAAM,CACP;QACH,gBAAgB,EAAE,CAChB,EAAW,EACX,aAAmB,EACnB,MAAsB,EACtB,QAAiB,EACjB,EAAE,CACF,gBAAgB,CACd,MAAM,EACN,EAAE,IAAI,SAAS,IAAI,SAAS,EAC5B,aAAa,EACb,MAAM,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,EAC/C,QAAQ,CACT;QACH,gBAAgB,EAAE,CAChB,EAAW,EACX,QAAc,EACd,OAAa,EACb,MAAsB,EACtB,QAAiB,EACjB,EAAE,CACF,gBAAgB,CACd,MAAM,EACN,EAAE,IAAI,SAAS,IAAI,SAAS,EAC5B,QAAQ,EACR,OAAO,EACP,MAAM,IAAI,aAAa,IAAI,aAAa,CAAC,MAAM,EAC/C,QAAQ,CACT;KACJ,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAc,EACd,SAAiB,EACjB,aAA4B,EAC5B,EAAoB,EACpB,OAAa;IAEb,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACxE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,gBAAgB,CACd,MAAM,EACN,SAAS,EACT,EAAE,OAAO,EAAE,IAAI,EAAE,EACjB,aAAa,EACb,QAAQ,CACT,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,gBAAgB,CACd,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,aAAa,EACb,QAAQ,CACT,CAAC;QACF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,GAAG,IAAW;IACxD,kEAAkE;IAClE,OAAO,CAAC,KAAK,CAAC,kBAAkB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,eAAe;IACb,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,cAAc;IACd,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;IACb,aAAa;IACb,aAAa;IACb,eAAe;IACf,qBAAqB;IACrB,kBAAkB;IAClB,WAAW;IACX,UAAU;IACV,gBAAgB;IAChB,QAAQ;IACR,aAAa;CACd,CAAC"}

package/dist/utils/numeric-utils.d.ts

@@ -0,0 +1,27 @@
+import { ListEntryFilters } from '../api/operations/index.js';
+/**
+ * Interface for numeric range
+ */
+export interface NumericRange {
+    min?: number;
+    max?: number;
+    equals?: number;
+}
+/**
+ * Validates a numeric range specification
+ *
+ * @param range - The numeric range to validate
+ * @returns True if valid, throws an error if invalid
+ * @throws Error when range is invalid
+ */
+export declare function validateNumericRange(range: NumericRange): boolean;
+/**
+ * Creates a numeric range filter for a specific attribute
+ *
+ * @param attributeSlug - The attribute slug to filter on (e.g., 'revenue', 'employee_count')
+ * @param range - Numeric range specification
+ * @returns Configured filter object
+ * @throws Error when range is invalid
+ */
+export declare function createNumericRangeFilter(attributeSlug: string, range: NumericRange): ListEntryFilters;
+//# sourceMappingURL=numeric-utils.d.ts.map

package/dist/utils/numeric-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-utils.d.ts","sourceRoot":"","sources":["../../src/utils/numeric-utils.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CA+BjE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,YAAY,GAClB,gBAAgB,CA4ClB"}

package/dist/utils/numeric-utils.js

@@ -0,0 +1,83 @@
+/**
+ * Numeric utility functions for working with Attio numeric filters
+ * Provides functions for handling numeric ranges and comparison operations.
+ */
+import { FilterConditionType } from '../types/attio.js';
+/**
+ * Validates a numeric range specification
+ *
+ * @param range - The numeric range to validate
+ * @returns True if valid, throws an error if invalid
+ * @throws Error when range is invalid
+ */
+export function validateNumericRange(range) {
+    // Check if we have an equals value (exact match)
+    if (range.equals !== undefined) {
+        // If equals is specified, min and max should not be
+        if (range.min !== undefined || range.max !== undefined) {
+            throw new Error('Cannot specify both equals and min/max in a numeric range');
+        }
+        return true;
+    }
+    // Check if we have min or max
+    if (range.min === undefined && range.max === undefined) {
+        throw new Error('Numeric range must specify at least one of: min, max, or equals');
+    }
+    // If both min and max are specified, ensure min <= max
+    if (range.min !== undefined &&
+        range.max !== undefined &&
+        range.min > range.max) {
+        throw new Error(`Invalid numeric range: min (${range.min}) cannot be greater than max (${range.max})`);
+    }
+    return true;
+}
+/**
+ * Creates a numeric range filter for a specific attribute
+ *
+ * @param attributeSlug - The attribute slug to filter on (e.g., 'revenue', 'employee_count')
+ * @param range - Numeric range specification
+ * @returns Configured filter object
+ * @throws Error when range is invalid
+ */
+export function createNumericRangeFilter(attributeSlug, range) {
+    try {
+        // Validate the numeric range
+        validateNumericRange(range);
+        const filters = [];
+        // Handle exact match case
+        if (range.equals !== undefined) {
+            filters.push({
+                attribute: { slug: attributeSlug },
+                condition: FilterConditionType.EQUALS,
+                value: range.equals,
+            });
+            return { filters, matchAny: false };
+        }
+        // Handle min value (greater than or equal)
+        if (range.min !== undefined) {
+            filters.push({
+                attribute: { slug: attributeSlug },
+                condition: FilterConditionType.GREATER_THAN_OR_EQUALS,
+                value: range.min,
+            });
+        }
+        // Handle max value (less than or equal)
+        if (range.max !== undefined) {
+            filters.push({
+                attribute: { slug: attributeSlug },
+                condition: FilterConditionType.LESS_THAN_OR_EQUALS,
+                value: range.max,
+            });
+        }
+        return {
+            filters,
+            // When both min and max are specified, we want records that match both (AND logic)
+            matchAny: false,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to create numeric filter: ${errorMessage}`);
+    }
+}
+//# sourceMappingURL=numeric-utils.js.map