@iflow-mcp/attio-mcp 1.3.6

package/dist/errors/api-errors.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Error class hierarchy for Attio API errors
+ * Includes specialized error types for API interactions and validation
+ */
+/**
+ * Base class for all Attio API errors
+ */
+export declare class AttioApiError extends Error {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    readonly method: string;
+    readonly details?: Record<string, unknown> | undefined;
+    /**
+     * Create an AttioApiError
+     *
+     * @param message - Error message
+     * @param statusCode - HTTP status code
+     * @param endpoint - API endpoint that was called
+     * @param details - Additional error details
+     */
+    constructor(message: string, statusCode: number, endpoint: string, method: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Get a formatted representation of the error for logging
+     */
+    toFormattedString(): string;
+}
+/**
+ * Error for authentication issues (401)
+ *
+ * Supports both API key and OAuth access token authentication (Issue #928).
+ * Provides helpful guidance for OAuth token expiration scenarios.
+ */
+export declare class AuthenticationError extends AttioApiError {
+    /** Helpful message for OAuth token expiration scenarios */
+    readonly oauthHint: string;
+    constructor(message: string | undefined, endpoint: string, method: string, details?: Record<string, unknown>);
+    /**
+     * Get a formatted representation with OAuth guidance
+     */
+    toFormattedString(): string;
+}
+/**
+ * Error for authorization issues (403)
+ */
+export declare class AuthorizationError extends AttioApiError {
+    constructor(message: string | undefined, endpoint: string, method: string, details?: Record<string, unknown>);
+}
+/**
+ * Error for resource not found issues (404)
+ */
+export declare class ResourceNotFoundError extends AttioApiError {
+    constructor(resourceType: string, resourceId: string, endpoint: string, method: string, details?: Record<string, unknown>);
+}
+/**
+ * Error for invalid request issues (400)
+ */
+export declare class InvalidRequestError extends AttioApiError {
+    constructor(message: string, endpoint: string, method: string, details?: Record<string, unknown>);
+}
+/**
+ * Error for rate limit issues (429)
+ */
+export declare class RateLimitError extends AttioApiError {
+    constructor(message: string | undefined, endpoint: string, method: string, details?: Record<string, unknown>);
+}
+/**
+ * Error for server-side issues (500, 502, 503, 504)
+ */
+export declare class ServerError extends AttioApiError {
+    constructor(statusCode: number, message: string | undefined, endpoint: string, method: string, details?: Record<string, unknown>);
+}
+/**
+ * Error for network connectivity issues (timeout, connection refused, DNS issues)
+ */
+export declare class NetworkError extends Error {
+    readonly endpoint: string;
+    readonly method: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, endpoint: string, method: string, cause?: Error | undefined);
+    /**
+     * Check if an error is a network-related error
+     */
+    static isNetworkError(error: unknown): boolean;
+    /**
+     * Create a NetworkError from a caught error
+     */
+    static fromError(error: unknown, endpoint: string, method: string): NetworkError;
+}
+/**
+ * Factory function to create the appropriate error type based on status code
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @param details - Additional error details
+ * @returns The appropriate error instance
+ */
+export declare function createApiErrorFromStatus(statusCode: number, message: string, endpoint: string, method: string, details?: Record<string, unknown>): AttioApiError;
+/**
+ * Create an appropriate error from Axios error response
+ *
+ * @param error - The caught error
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @returns The appropriate error instance
+ */
+export declare function createApiErrorFromAxiosError(error: unknown, endpoint: string, method: string): AttioApiError | NetworkError;
+/**
+ * Filter error categories for more targeted error handling
+ */
+export declare enum FilterErrorCategory {
+    STRUCTURE = "structure",// Basic structure issues (missing filters array)
+    ATTRIBUTE = "attribute",// Attribute-related issues
+    CONDITION = "condition",// Condition-related issues
+    VALUE = "value",// Value-related issues
+    TRANSFORMATION = "transformation"
+}
+/**
+ * Error class for filter validation issues
+ *
+ * Used when validating filter conditions and structures to ensure they meet
+ * the requirements of the Attio API format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Validate filter conditions
+ *   if (!isValidFilterCondition(condition)) {
+ *     throw new FilterValidationError(
+ *       `Invalid filter condition: ${condition}`,
+ *       FilterErrorCategory.CONDITION
+ *     );
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof FilterValidationError) {
+ *     // Handle filter validation error based on category
+ *     if (error.category === FilterErrorCategory.CONDITION) {
+ *       // Handle condition-specific error
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class FilterValidationError extends Error {
+    readonly category: FilterErrorCategory;
+    /**
+     * Create a new FilterValidationError
+     *
+     * @param message - Detailed error message explaining the validation issue
+     * @param category - Error category for targeted handling (default: STRUCTURE)
+     */
+    constructor(message: string, category?: FilterErrorCategory);
+}
+/**
+ * Error for relationship filter validation issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidRelationshipType(type)) {
+ *     throw new RelationshipFilterError(
+ *       `Invalid relationship type: ${type}`,
+ *       'people',
+ *       'companies'
+ *     );
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof RelationshipFilterError) {
+ *     // Handle relationship filter error
+ *     console.error(`Relationship error between ${error.sourceType} and ${error.targetType}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class RelationshipFilterError extends FilterValidationError {
+    readonly sourceType?: string | undefined;
+    readonly targetType?: string | undefined;
+    readonly relationshipType?: string | undefined;
+    /**
+     * Create a RelationshipFilterError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param targetType - The target entity type (e.g., 'companies', 'lists')
+     * @param relationshipType - The type of relationship that failed validation
+     */
+    constructor(message: string, sourceType?: string | undefined, targetType?: string | undefined, relationshipType?: string | undefined);
+}
+/**
+ * Error specifically for list relationship issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidListId(listId)) {
+ *     throw new ListRelationshipError(`Invalid list ID: ${listId}`, 'people', listId);
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof ListRelationshipError) {
+ *     // Handle list relationship error
+ *   }
+ * }
+ * ```
+ */
+export declare class ListRelationshipError extends RelationshipFilterError {
+    readonly listId?: string | undefined;
+    /**
+     * Create a ListRelationshipError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param listId - The list ID that caused the error
+     */
+    constructor(message: string, sourceType?: string, listId?: string | undefined);
+}
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/errors/api-errors.d.ts.map

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

package/dist/errors/api-errors.js

@@ -0,0 +1,406 @@
+/**
+ * Error class hierarchy for Attio API errors
+ * Includes specialized error types for API interactions and validation
+ */
+import { sanitizeErrorMessage } from '../utils/error-sanitizer.js';
+/**
+ * Base class for all Attio API errors
+ */
+export class AttioApiError extends Error {
+    statusCode;
+    endpoint;
+    method;
+    details;
+    /**
+     * Create an AttioApiError
+     *
+     * @param message - Error message
+     * @param statusCode - HTTP status code
+     * @param endpoint - API endpoint that was called
+     * @param details - Additional error details
+     */
+    constructor(message, statusCode, endpoint, method, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.method = method;
+        this.details = details;
+        this.name = 'AttioApiError';
+        // This line is needed to properly capture the stack trace in derived classes
+        Object.setPrototypeOf(this, AttioApiError.prototype);
+    }
+    /**
+     * Get a formatted representation of the error for logging
+     */
+    toFormattedString() {
+        // In production, sanitize the output
+        if (process.env.NODE_ENV === 'production') {
+            return `${this.name} (${this.statusCode}): ${sanitizeErrorMessage(this.message)}`;
+        }
+        // In development, include more details but still sanitize sensitive data
+        const sanitizedEndpoint = this.endpoint.replace(/\/[a-f0-9-]{20,}/gi, '/[ID_REDACTED]');
+        return (`${this.name} (${this.statusCode}): ${this.message}\n` +
+            `Endpoint: ${this.method} ${sanitizedEndpoint}\n` +
+            `Details: ${JSON.stringify(this.details || {}, null, 2)}`);
+    }
+}
+/**
+ * Error for authentication issues (401)
+ *
+ * Supports both API key and OAuth access token authentication (Issue #928).
+ * Provides helpful guidance for OAuth token expiration scenarios.
+ */
+export class AuthenticationError extends AttioApiError {
+    /** Helpful message for OAuth token expiration scenarios */
+    oauthHint;
+    constructor(message = 'Authentication failed. Please check your credentials.', endpoint, method, details) {
+        // Sanitize the message to avoid exposing API key/token format
+        const sanitizedMessage = message
+            .replace(/api[_-]?key[\s:=]*["']?[a-zA-Z0-9_-]{20,}["']?/gi, '[CREDENTIAL_REDACTED]')
+            .replace(/access[_-]?token[\s:=]*["']?[a-zA-Z0-9_-]{20,}["']?/gi, '[TOKEN_REDACTED]');
+        super(sanitizedMessage, 401, endpoint, method, details);
+        this.name = 'AuthenticationError';
+        // Helpful message for OAuth users (Issue #928)
+        this.oauthHint =
+            'If using an OAuth access token, it may have expired. ' +
+                'Run `npm run oauth:refresh` to obtain a new token, or check your ATTIO_API_KEY/ATTIO_ACCESS_TOKEN configuration.';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+    /**
+     * Get a formatted representation with OAuth guidance
+     */
+    toFormattedString() {
+        const baseMessage = super.toFormattedString();
+        return `${baseMessage}\n\nTip: ${this.oauthHint}`;
+    }
+}
+/**
+ * Error for authorization issues (403)
+ */
+export class AuthorizationError extends AttioApiError {
+    constructor(message = 'Authorization failed. You lack the necessary permissions.', endpoint, method, details) {
+        // Sanitize the message to avoid exposing permission details
+        const sanitizedMessage = message.replace(/permission[s]?[\s:]+["']?[a-z_.]+["']?/gi, '[PERMISSION_REDACTED]');
+        super(sanitizedMessage, 403, endpoint, method, details);
+        this.name = 'AuthorizationError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, AuthorizationError.prototype);
+    }
+}
+/**
+ * Error for resource not found issues (404)
+ */
+export class ResourceNotFoundError extends AttioApiError {
+    constructor(resourceType, resourceId, endpoint, method, details) {
+        // Sanitize resource ID to avoid exposing internal identifiers
+        const sanitizedId = resourceId.length > 10 ? '[ID_REDACTED]' : resourceId;
+        super(`${resourceType} ${sanitizedId} not found`, 404, endpoint, method, details);
+        this.name = 'ResourceNotFoundError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ResourceNotFoundError.prototype);
+    }
+}
+/**
+ * Error for invalid request issues (400)
+ */
+export class InvalidRequestError extends AttioApiError {
+    constructor(message, endpoint, method, details) {
+        super(message, 400, endpoint, method, details);
+        this.name = 'InvalidRequestError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, InvalidRequestError.prototype);
+    }
+}
+/**
+ * Error for rate limit issues (429)
+ */
+export class RateLimitError extends AttioApiError {
+    constructor(message = 'Rate limit exceeded. Please try again later.', endpoint, method, details) {
+        super(message, 429, endpoint, method, details);
+        this.name = 'RateLimitError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+/**
+ * Error for server-side issues (500, 502, 503, 504)
+ */
+export class ServerError extends AttioApiError {
+    constructor(statusCode, message = 'Server error occurred', endpoint, method, details) {
+        super(`Server error (${statusCode}): ${message}`, statusCode, endpoint, method, details);
+        this.name = 'ServerError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ServerError.prototype);
+    }
+}
+/**
+ * Error for network connectivity issues (timeout, connection refused, DNS issues)
+ */
+export class NetworkError extends Error {
+    endpoint;
+    method;
+    cause;
+    constructor(message, endpoint, method, cause) {
+        super(message);
+        this.endpoint = endpoint;
+        this.method = method;
+        this.cause = cause;
+        this.name = 'NetworkError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+    /**
+     * Check if an error is a network-related error
+     */
+    static isNetworkError(error) {
+        if (error instanceof NetworkError)
+            return true;
+        // Check for error codes that indicate network issues
+        const errorObj = error;
+        if (errorObj.code) {
+            const networkCodes = [
+                'ECONNREFUSED',
+                'ENOTFOUND',
+                'ECONNRESET',
+                'ETIMEDOUT',
+                'ECONNABORTED',
+                'EHOSTUNREACH',
+                'ENETUNREACH',
+            ];
+            if (networkCodes.includes(errorObj.code))
+                return true;
+        }
+        // Check for specific network-related messages
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const networkKeywords = [
+            'Network Error',
+            'fetch failed',
+            'connection refused',
+            'dns lookup failed',
+            'timeout',
+        ];
+        // Only match if the message starts with or contains these specific patterns
+        return networkKeywords.some((keyword) => errorMessage.toLowerCase().includes(keyword.toLowerCase()));
+    }
+    /**
+     * Create a NetworkError from a caught error
+     */
+    static fromError(error, endpoint, method) {
+        const originalError = error instanceof Error ? error : new Error(String(error));
+        return new NetworkError(`Network error occurred: ${originalError.message}`, endpoint, method, originalError);
+    }
+}
+/**
+ * Factory function to create the appropriate error type based on status code
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @param details - Additional error details
+ * @returns The appropriate error instance
+ */
+export function createApiErrorFromStatus(statusCode, message, endpoint, method, details) {
+    switch (statusCode) {
+        case 400:
+            return new InvalidRequestError(message, endpoint, method, details);
+        case 401:
+            return new AuthenticationError(message, endpoint, method, details);
+        case 403:
+            return new AuthorizationError(message, endpoint, method, details);
+        case 404:
+            // This is a generic case - for specific resources, use ResourceNotFoundError constructor directly
+            return new ResourceNotFoundError('Resource', 'unknown', endpoint, method, details);
+        case 429:
+            return new RateLimitError(message, endpoint, method, details);
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return new ServerError(statusCode, message, endpoint, method, details);
+        default:
+            return new AttioApiError(message, statusCode, endpoint, method, details);
+    }
+}
+/**
+ * Create an appropriate error from Axios error response
+ *
+ * @param error - The caught error
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @returns The appropriate error instance
+ */
+export function createApiErrorFromAxiosError(error, endpoint, method) {
+    const axiosError = error;
+    // Check if this is a network error first (no response = network issue)
+    if (!axiosError.response) {
+        // No response means network connectivity issue
+        if (NetworkError.isNetworkError(error)) {
+            return NetworkError.fromError(error, endpoint, method);
+        }
+        // If no response but not a recognized network error, treat as generic API error
+        const message = axiosError.message || 'Unknown API error';
+        return new AttioApiError(message, 500, endpoint, method, {});
+    }
+    const statusCode = axiosError.response.status || 500;
+    const message = axiosError.response?.data?.message ||
+        axiosError.message ||
+        'Unknown API error';
+    const details = axiosError.response?.data || {};
+    // Special case for ResourceNotFoundError with object types
+    if (statusCode === 404 && endpoint.includes('/objects/')) {
+        // Extract resource type and ID from endpoint
+        // Assuming endpoint format like /objects/{type}/records/{id}
+        const matches = endpoint.match(/\/objects\/([^/]+)\/records\/([^/]+)/);
+        if (matches && matches.length >= 3) {
+            const [, resourceType, resourceId] = matches;
+            // Format resource type properly: 'people' -> 'Person', 'companies' -> 'Company'
+            let formattedType;
+            if (resourceType === 'people') {
+                formattedType = 'Person';
+            }
+            else if (resourceType === 'companies') {
+                formattedType = 'Company';
+            }
+            else {
+                // Default formatting for other types
+                formattedType =
+                    resourceType.charAt(0).toUpperCase() + resourceType.slice(1, -1);
+            }
+            return new ResourceNotFoundError(formattedType, resourceId, endpoint, method, details);
+        }
+    }
+    return createApiErrorFromStatus(statusCode, message, endpoint, method, details);
+}
+/**
+ * Filter error categories for more targeted error handling
+ */
+export var FilterErrorCategory;
+(function (FilterErrorCategory) {
+    FilterErrorCategory["STRUCTURE"] = "structure";
+    FilterErrorCategory["ATTRIBUTE"] = "attribute";
+    FilterErrorCategory["CONDITION"] = "condition";
+    FilterErrorCategory["VALUE"] = "value";
+    FilterErrorCategory["TRANSFORMATION"] = "transformation";
+})(FilterErrorCategory || (FilterErrorCategory = {}));
+/**
+ * Error class for filter validation issues
+ *
+ * Used when validating filter conditions and structures to ensure they meet
+ * the requirements of the Attio API format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Validate filter conditions
+ *   if (!isValidFilterCondition(condition)) {
+ *     throw new FilterValidationError(
+ *       `Invalid filter condition: ${condition}`,
+ *       FilterErrorCategory.CONDITION
+ *     );
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof FilterValidationError) {
+ *     // Handle filter validation error based on category
+ *     if (error.category === FilterErrorCategory.CONDITION) {
+ *       // Handle condition-specific error
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FilterValidationError extends Error {
+    category;
+    /**
+     * Create a new FilterValidationError
+     *
+     * @param message - Detailed error message explaining the validation issue
+     * @param category - Error category for targeted handling (default: STRUCTURE)
+     */
+    constructor(message, category = FilterErrorCategory.STRUCTURE) {
+        super(message);
+        this.category = category;
+        this.name = 'FilterValidationError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, FilterValidationError.prototype);
+    }
+}
+/**
+ * Error for relationship filter validation issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidRelationshipType(type)) {
+ *     throw new RelationshipFilterError(
+ *       `Invalid relationship type: ${type}`,
+ *       'people',
+ *       'companies'
+ *     );
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof RelationshipFilterError) {
+ *     // Handle relationship filter error
+ *     console.error(`Relationship error between ${error.sourceType} and ${error.targetType}`);
+ *   }
+ * }
+ * ```
+ */
+export class RelationshipFilterError extends FilterValidationError {
+    sourceType;
+    targetType;
+    relationshipType;
+    /**
+     * Create a RelationshipFilterError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param targetType - The target entity type (e.g., 'companies', 'lists')
+     * @param relationshipType - The type of relationship that failed validation
+     */
+    constructor(message, sourceType, targetType, relationshipType) {
+        // Relationships are a special type of filter condition
+        super(message, FilterErrorCategory.CONDITION);
+        this.sourceType = sourceType;
+        this.targetType = targetType;
+        this.relationshipType = relationshipType;
+        this.name = 'RelationshipFilterError';
+        // This line is needed to properly capture the stack trace in derived classes
+        Object.setPrototypeOf(this, RelationshipFilterError.prototype);
+    }
+}
+/**
+ * Error specifically for list relationship issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidListId(listId)) {
+ *     throw new ListRelationshipError(`Invalid list ID: ${listId}`, 'people', listId);
+ *   }
+ * } catch (error: unknown) {
+ *   if (error instanceof ListRelationshipError) {
+ *     // Handle list relationship error
+ *   }
+ * }
+ * ```
+ */
+export class ListRelationshipError extends RelationshipFilterError {
+    listId;
+    /**
+     * Create a ListRelationshipError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param listId - The list ID that caused the error
+     */
+    constructor(message, sourceType, listId) {
+        super(message, sourceType, 'lists', 'in_list');
+        this.listId = listId;
+        this.name = 'ListRelationshipError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ListRelationshipError.prototype);
+    }
+}
+//# sourceMappingURL=api-errors.js.map

package/dist/errors/api-errors.js.map

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