@iflow-mcp/attio-mcp 1.3.6

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

@@ -0,0 +1,53 @@
+/**
+ * Domain-specific error classes for company operations
+ */
+import { BaseWrappedError } from './BaseWrappedError.js';
+/**
+ * Base error class for company-related errors
+ */
+export declare class CompanyError extends BaseWrappedError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown when a company is not found
+ */
+export declare class CompanyNotFoundError extends CompanyError {
+    constructor(companyId: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown when company data is invalid
+ */
+export declare class InvalidCompanyDataError extends CompanyError {
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown when a company operation fails
+ */
+export declare class CompanyOperationError extends CompanyError {
+    constructor(operation: string, companyId?: string, details?: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown when a required company field is missing
+ */
+export declare class MissingCompanyFieldError extends InvalidCompanyDataError {
+    constructor(fieldName: string, opts?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown when a company field has an invalid type
+ */
+export declare class InvalidCompanyFieldTypeError extends InvalidCompanyDataError {
+    constructor(fieldName: string, expectedType: string, actualType: string, opts?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=company-errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"company-errors.d.ts","sourceRoot":"","sources":["../../src/errors/company-errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;GAEG;AACH,qBAAa,YAAa,SAAQ,gBAAgB;gBACpC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAGxD;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1D;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIxD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBAEnD,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAW7B;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,uBAAuB;gBACvD,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1D;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,uBAAuB;gBAErE,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQ7B"}

package/dist/errors/company-errors.js

@@ -0,0 +1,62 @@
+/**
+ * Domain-specific error classes for company operations
+ */
+import { BaseWrappedError } from './BaseWrappedError.js';
+/**
+ * Base error class for company-related errors
+ */
+export class CompanyError extends BaseWrappedError {
+    constructor(message, opts) {
+        super('CompanyError', message, opts);
+    }
+}
+/**
+ * Error thrown when a company is not found
+ */
+export class CompanyNotFoundError extends CompanyError {
+    constructor(companyId, opts) {
+        super(`Company with ID ${companyId} not found`, opts);
+        this.name = 'CompanyNotFoundError';
+    }
+}
+/**
+ * Error thrown when company data is invalid
+ */
+export class InvalidCompanyDataError extends CompanyError {
+    constructor(message, opts) {
+        super(`Invalid company data: ${message}`, opts);
+        this.name = 'InvalidCompanyDataError';
+    }
+}
+/**
+ * Error thrown when a company operation fails
+ */
+export class CompanyOperationError extends CompanyError {
+    constructor(operation, companyId, details, opts) {
+        const baseMessage = `Company ${operation} failed`;
+        const fullMessage = companyId
+            ? `${baseMessage} for company ${companyId}${details ? `: ${details}` : ''}`
+            : `${baseMessage}${details ? `: ${details}` : ''}`;
+        super(fullMessage, opts);
+        this.name = 'CompanyOperationError';
+    }
+}
+/**
+ * Error thrown when a required company field is missing
+ */
+export class MissingCompanyFieldError extends InvalidCompanyDataError {
+    constructor(fieldName, opts) {
+        super(`Required field '${fieldName}' is missing`, opts);
+        this.name = 'MissingCompanyFieldError';
+    }
+}
+/**
+ * Error thrown when a company field has an invalid type
+ */
+export class InvalidCompanyFieldTypeError extends InvalidCompanyDataError {
+    constructor(fieldName, expectedType, actualType, opts) {
+        super(`Field '${fieldName}' must be of type ${expectedType}, but got ${actualType}`, opts);
+        this.name = 'InvalidCompanyFieldTypeError';
+    }
+}
+//# sourceMappingURL=company-errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"company-errors.js","sourceRoot":"","sources":["../../src/errors/company-errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,gBAAgB;IAChD,YAAY,OAAe,EAAE,IAA0B;QACrD,KAAK,CAAC,cAAc,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,SAAiB,EAAE,IAA0B;QACvD,KAAK,CAAC,mBAAmB,SAAS,YAAY,EAAE,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAe,EAAE,IAA0B;QACrD,KAAK,CAAC,yBAAyB,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,YACE,SAAiB,EACjB,SAAkB,EAClB,OAAgB,EAChB,IAA0B;QAE1B,MAAM,WAAW,GAAG,WAAW,SAAS,SAAS,CAAC;QAClD,MAAM,WAAW,GAAG,SAAS;YAC3B,CAAC,CAAC,GAAG,WAAW,gBAAgB,SAAS,GACrC,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,EAC7B,EAAE;YACJ,CAAC,CAAC,GAAG,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACrD,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,wBAAyB,SAAQ,uBAAuB;IACnE,YAAY,SAAiB,EAAE,IAA0B;QACvD,KAAK,CAAC,mBAAmB,SAAS,cAAc,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,uBAAuB;IACvE,YACE,SAAiB,EACjB,YAAoB,EACpB,UAAkB,EAClB,IAA0B;QAE1B,KAAK,CACH,UAAU,SAAS,qBAAqB,YAAY,aAAa,UAAU,EAAE,EAC7E,IAAI,CACL,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF"}

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

@@ -0,0 +1,186 @@
+/**
+ * Enhanced API Error System for Consolidated Issues #415, #416, #417
+ *
+ * This module provides comprehensive error messaging with contextual information
+ * to address:
+ * - Issue #415: Poor error message quality and user experience
+ * - Issue #416: Misleading "Invalid format" vs "Not found" confusion
+ * - Issue #417: Task-specific error guidance and field mapping help
+ */
+import { AttioApiError } from './api-errors.js';
+import type { AttributeMetadata } from '../services/utils/attribute-metadata.js';
+/**
+ * Enhanced error context interface providing rich information for better UX
+ */
+export interface EnhancedApiErrorContext {
+    /** Field name that caused the error */
+    field?: string;
+    /** Type information for the problematic field */
+    fieldType?: string;
+    /**
+     * Attio field configuration snapshot for deep diagnostics.
+     * @remarks Commonly includes api_slug, field_type, title, and config.select options.
+     */
+    fieldMetadata?: AttributeMetadata;
+    /** Valid values for select fields */
+    validValues?: string[];
+    /** Suggested field names for typos */
+    suggestedFields?: string[];
+    /** Resource type being operated on */
+    resourceType?: string;
+    /** Operation being performed (create, update, get, etc.) */
+    operation?: string;
+    /** Whether the field is read-only */
+    isReadOnly?: boolean;
+    /** Documentation hint or command suggestion */
+    documentationHint?: string;
+    /** Record ID for "not found" vs "invalid format" distinction */
+    recordId?: string;
+    /** HTTP status code for precise error categorization */
+    httpStatus?: number;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** Original error for debugging */
+    originalError?: Error;
+    /** Server response data for debugging */
+    serverData?: Record<string, unknown>;
+}
+/** @deprecated Use EnhancedApiErrorContext instead */
+export type ErrorContext = EnhancedApiErrorContext;
+/**
+ * Enhanced API Error class that provides contextual error messages
+ *
+ * This class extends the base AttioApiError with rich context information
+ * to provide actionable error messages that guide users toward solutions.
+ */
+export declare class EnhancedApiError extends AttioApiError {
+    readonly context?: EnhancedApiErrorContext | undefined;
+    constructor(message: string, statusCode: number, endpoint: string, method: string, context?: EnhancedApiErrorContext | undefined);
+    /**
+     * Check if this is a user error (400-level)
+     */
+    isUserError(): boolean;
+    /**
+     * Get error category for classification
+     */
+    getErrorCategory(): 'user' | 'system' | 'network' | 'auth' | 'unknown';
+    /**
+     * Generate a contextual error message with actionable guidance
+     *
+     * This method analyzes the error context and constructs helpful messages
+     * that address the specific issues identified in the consolidated issues.
+     */
+    getContextualMessage(): string;
+    /**
+     * Generate "Record not found" error message for Issue #416
+     */
+    private getNotFoundErrorMessage;
+    /**
+     * Generate field suggestions for typos
+     */
+    private getFieldSuggestions;
+    /**
+     * Generate task-specific error guidance for Issue #417
+     */
+    private getTaskErrorMessage;
+    /**
+     * Generate field validation error messages for Issue #415
+     */
+    private getFieldValidationMessage;
+    /**
+     * Generate general guidance messages
+     */
+    private getGeneralGuidanceMessage;
+    /**
+     * Generate task-specific error guidance
+     *
+     * Addresses Issue #417 by providing clear guidance for task field mappings
+     * and common task-related errors.
+     */
+    private getTaskSpecificGuidance;
+    /**
+     * Check if this error is likely retryable
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Factory function to create enhanced API errors with proper context
+ */
+export declare function createEnhancedApiError(message: string, statusCode: number, endpoint: string, method: string, context?: Partial<EnhancedApiErrorContext>): EnhancedApiError;
+/**
+ * Enhanced error templates for common scenarios
+ *
+ * These templates provide consistent, helpful error messages across the application
+ */
+export declare const ErrorTemplates: {
+    /**
+     * Issue #415: Invalid select option template
+     */
+    INVALID_SELECT_OPTION: (field: string, value: string, validOptions: string[], resourceType?: string) => EnhancedApiError;
+    /**
+     * Issue #415: Read-only field template
+     */
+    READ_ONLY_FIELD: (field: string, resourceType: string) => EnhancedApiError;
+    /**
+     * Issue #415: Unknown field template
+     */
+    UNKNOWN_FIELD: (field: string, suggestions: string[], resourceType: string) => EnhancedApiError;
+    /**
+     * Issue #416: Record not found template (vs invalid format)
+     */
+    RECORD_NOT_FOUND: (recordId: string, resourceType: string) => EnhancedApiError;
+    /**
+     * Issue #416: Invalid UUID format template (vs not found)
+     */
+    INVALID_UUID_FORMAT: (recordId: string, resourceType: string) => EnhancedApiError;
+    /**
+     * Issue #417: Task field mapping template
+     */
+    TASK_FIELD_MAPPING: (originalField: string, correctField: string) => EnhancedApiError;
+    /**
+     * Issue #798: Phone number format error template
+     */
+    PHONE_NUMBER_FORMAT_ERROR: (field: string, resourceType: string) => EnhancedApiError;
+    /**
+     * Generic enhanced error template
+     */
+    GENERIC: (message: string, statusCode: number, endpoint: string, method: string, context?: Partial<EnhancedApiErrorContext>) => EnhancedApiError;
+};
+/**
+ * Error enhancement utilities
+ */
+export declare class ErrorEnhancer {
+    /**
+     * Enhance a standard API error with context
+     */
+    static enhance(error: Error | AttioApiError, context?: Partial<EnhancedApiErrorContext>): EnhancedApiError;
+    /**
+     * Issue #425: Safe error message extraction utility
+     * Extracts a contextual message from any error type safely
+     * Handles: EnhancedApiError, AttioApiError, UniversalValidationError, and generic errors
+     */
+    static getErrorMessage(error: Error | EnhancedApiError | AttioApiError | {
+        message?: string;
+    } | unknown): string;
+    /**
+     * Issue #425: Convert any error to EnhancedApiError
+     * Ensures all errors are properly enhanced for consistent handling
+     */
+    static ensureEnhanced(error: Error | EnhancedApiError | AttioApiError | {
+        message?: string;
+        statusCode?: number;
+        status?: number;
+        endpoint?: string;
+        path?: string;
+        method?: string;
+    } | unknown, defaultContext?: Partial<EnhancedApiErrorContext>): EnhancedApiError;
+    /**
+     * Auto-detect error type and apply appropriate enhancement
+     */
+    static autoEnhance(error: Error, resourceType?: string, operation?: string, recordId?: string): EnhancedApiError;
+    /**
+     * Get correct task field mapping
+     */
+    private static getTaskFieldMapping;
+}
+//# sourceMappingURL=enhanced-api-errors.d.ts.map

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

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