attio-mcp 1.3.5 → 1.4.0

package/dist/handlers/tool-configs/universal/core/error-enhancers/record-reference-enhancer.js

@@ -0,0 +1,108 @@
+/**
+ * Record Reference Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ * Issue #997 - Enhanced record-reference attribute error handling
+ *
+ * Detects "Missing target_object on record reference value" and similar errors
+ * Provides format guidance for record-reference fields.
+ */
+import { getErrorMessage, isAxiosError } from './types.js';
+/**
+ * Enhance error messages for record-reference attribute errors
+ */
+const enhanceRecordReferenceError = (error, recordData) => {
+    const msg = getErrorMessage(error);
+    // Also check for validation_errors in axios response
+    let fullErrorText = msg;
+    if (isAxiosError(error)) {
+        const data = error.response?.data;
+        if (data?.message) {
+            fullErrorText += ' ' + data.message;
+        }
+        if (data?.validation_errors) {
+            fullErrorText +=
+                ' ' +
+                    data.validation_errors.map((e) => String(e.message || e)).join(' ');
+        }
+    }
+    // Pattern detection for record-reference errors
+    const isRecordRefError = fullErrorText.includes('Missing target_object') ||
+        fullErrorText.includes('record reference') ||
+        fullErrorText.includes('target_record_id') ||
+        (fullErrorText.includes('Invalid value was passed to attribute') &&
+            (fullErrorText.includes('company') ||
+                fullErrorText.includes('associated_people') ||
+                fullErrorText.includes('associated_company') ||
+                fullErrorText.includes('main_contact')));
+    if (!isRecordRefError)
+        return null;
+    // Try to identify which field might be the issue
+    const potentialRefFields = [
+        'company',
+        'associated_company',
+        'associated_people',
+        'main_contact',
+        'person',
+        'people',
+    ];
+    let affectedField = null;
+    if (recordData) {
+        for (const field of potentialRefFields) {
+            if (field in recordData) {
+                affectedField = field;
+                break;
+            }
+        }
+    }
+    let message = `Record reference format error`;
+    if (affectedField) {
+        message += ` on field "${affectedField}"`;
+    }
+    message += `.\n\n`;
+    message += `The Attio API expects record-reference fields in this format:\n`;
+    message += `  [{ "target_object": "object_type", "target_record_id": "uuid" }]\n\n`;
+    message += `Simplified formats (auto-transformed by this server):\n`;
+    message += `  • String: "company": "record-uuid"\n`;
+    message += `  • Legacy object: "company": {"record_id": "uuid"}\n\n`;
+    message += `If you're seeing this error, the auto-transformation may have failed.\n`;
+    message += `Ensure the record ID is valid and the field name is correct.`;
+    return message;
+};
+/**
+ * Record Reference Enhancer
+ * Handles record-reference field format errors (Issue #997)
+ */
+export const recordReferenceEnhancer = {
+    name: 'record-reference',
+    errorName: 'record_reference_error',
+    matches: (error, _context) => {
+        const msg = getErrorMessage(error);
+        // Check for axios validation errors
+        let fullText = msg;
+        if (isAxiosError(error)) {
+            const data = error.response?.data;
+            if (data?.message) {
+                fullText += ' ' + data.message;
+            }
+            // CRITICAL: Also check validation_errors array for record-reference patterns
+            if (data?.validation_errors) {
+                fullText +=
+                    ' ' +
+                        data.validation_errors.map((e) => String(e.message || e)).join(' ');
+            }
+        }
+        return (fullText.includes('Missing target_object') ||
+            fullText.includes('record reference') ||
+            fullText.includes('target_record_id') ||
+            // CRITICAL: Match "Invalid value was passed to attribute" pattern (from enhanceRecordReferenceError)
+            (fullText.includes('Invalid value was passed to attribute') &&
+                (fullText.includes('company') ||
+                    fullText.includes('associated_people') ||
+                    fullText.includes('associated_company') ||
+                    fullText.includes('main_contact'))));
+    },
+    enhance: async (error, context) => {
+        return enhanceRecordReferenceError(error, context.recordData);
+    },
+};
+//# sourceMappingURL=record-reference-enhancer.js.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/record-reference-enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-reference-enhancer.js","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/record-reference-enhancer.ts"],"names":[],"mappings":"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"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Required Fields Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ *
+ * Detects missing required fields and provides specific guidance,
+ * especially for deal-specific required fields like "stage".
+ */
+import type { ErrorEnhancer } from './types.js';
+/**
+ * Required Fields Enhancer
+ * Detects missing required field errors and provides context-specific guidance
+ */
+export declare const requiredFieldsEnhancer: ErrorEnhancer;
+//# sourceMappingURL=required-fields-enhancer.d.ts.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields-enhancer.d.ts","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAwFlE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,aA0BpC,CAAC"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.js

@@ -0,0 +1,91 @@
+/**
+ * Required Fields Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ *
+ * Detects missing required fields and provides specific guidance,
+ * especially for deal-specific required fields like "stage".
+ */
+import { UniversalResourceType } from '../../../../../handlers/tool-configs/universal/types.js';
+import { sanitizedLog } from '../pii-sanitizer.js';
+import { createScopedLogger } from '../../../../../utils/logger.js';
+const logger = createScopedLogger('required-fields-enhancer');
+/**
+ * Normalize field names for comparison
+ */
+const normalizeFieldName = (field) => field.trim().toLowerCase();
+/**
+ * Check if recordData contains a stage field (for deals)
+ */
+const hasStageField = (recordData) => {
+    const directKeys = Object.keys(recordData).map(normalizeFieldName);
+    if (directKeys.includes('stage') ||
+        directKeys.includes('deal stage') ||
+        directKeys.includes('status')) {
+        return true;
+    }
+    const values = recordData.values &&
+        typeof recordData.values === 'object' &&
+        recordData.values !== null
+        ? recordData.values
+        : null;
+    if (!values)
+        return false;
+    const valueKeys = Object.keys(values).map(normalizeFieldName);
+    return (valueKeys.includes('stage') ||
+        valueKeys.includes('deal stage') ||
+        valueKeys.includes('status'));
+};
+/**
+ * Build enhanced error message for missing deal stage
+ */
+const buildMissingDealStageMessage = async (recordData) => {
+    if (hasStageField(recordData))
+        return null;
+    try {
+        const { AttributeOptionsService } = await import('../../../../../services/metadata/index.js');
+        const { options } = await AttributeOptionsService.getOptions('deals', 'stage');
+        const preview = options
+            .slice(0, 5)
+            .map((option) => `"${option.title}"`)
+            .join(', ');
+        const hasMore = options.length > 5 ? ` (+${options.length - 5} more)` : '';
+        return (`Required field "stage" is missing for deals.\n\n` +
+            `Common stage values: ${preview}${hasMore}\n\n` +
+            `For the full list, call: records_get_attribute_options(resource_type="deals", attribute="stage").`);
+    }
+    catch (err) {
+        sanitizedLog(logger, 'debug', 'Failed to fetch stage options for enhanced error message', {
+            enhancerName: 'required-fields',
+            resourceType: 'deals',
+            attribute: 'stage',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return (`Required field "stage" is missing for deals.\n\n` +
+            `Call records_get_attribute_options(resource_type="deals", attribute="stage") to retrieve valid stage values, then retry.`);
+    }
+};
+/**
+ * Required Fields Enhancer
+ * Detects missing required field errors and provides context-specific guidance
+ */
+export const requiredFieldsEnhancer = {
+    name: 'required-fields',
+    errorName: 'validation_error',
+    matches: (error, _context) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        return msg.includes('required field') || msg.includes('Missing required');
+    },
+    enhance: async (_error, context) => {
+        const { resourceType, recordData } = context;
+        // Deal-specific required field handling
+        if (resourceType === UniversalResourceType.DEALS && recordData) {
+            const stageMessage = await buildMissingDealStageMessage(recordData);
+            if (stageMessage) {
+                return stageMessage;
+            }
+        }
+        // Generic required field message
+        return 'Missing required fields. Please check that all mandatory fields are provided.';
+    },
+};
+//# sourceMappingURL=required-fields-enhancer.js.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields-enhancer.js","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/required-fields-enhancer.ts"],"names":[],"mappings":"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"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Select/Status Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ *
+ * Detects "Cannot find select option" or "Cannot find Status" errors
+ * and provides valid options from AttributeOptionsService.
+ */
+import type { ErrorEnhancer } from './types.js';
+/**
+ * Select/Status Enhancer
+ * Provides valid options for select and status field errors
+ */
+export declare const selectStatusEnhancer: ErrorEnhancer;
+//# sourceMappingURL=select-status-enhancer.d.ts.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-status-enhancer.d.ts","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAqIlE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAqBlC,CAAC"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.js

@@ -0,0 +1,118 @@
+/**
+ * Select/Status Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ *
+ * Detects "Cannot find select option" or "Cannot find Status" errors
+ * and provides valid options from AttributeOptionsService.
+ */
+import { getErrorMessage, isAxiosError } from './types.js';
+import { sanitizedLog } from '../pii-sanitizer.js';
+import { createScopedLogger } from '../../../../../utils/logger.js';
+const logger = createScopedLogger('select-status-enhancer');
+/**
+ * Enhance error messages for select/status attribute errors
+ */
+const enhanceSelectStatusError = async (error, resourceType, recordData) => {
+    const msg = getErrorMessage(error);
+    // Attempt to extract validation_errors array for better detail on select fields
+    if (isAxiosError(error)) {
+        const validationErrors = error.response?.data?.validation_errors;
+        if (validationErrors) {
+            const selectErr = validationErrors.find((ve) => String(ve?.message || '').includes('select option'));
+            if (selectErr?.field) {
+                try {
+                    const { AttributeOptionsService } = await import('../../../../../services/metadata/index.js');
+                    const { options, attributeType } = await AttributeOptionsService.getOptions(resourceType, selectErr.field);
+                    const validList = options
+                        .slice(0, 8)
+                        .map((o) => o.title)
+                        .join(', ');
+                    const hasMore = options.length > 8 ? ` (+${options.length - 8} more)` : '';
+                    return `Value is not valid for ${attributeType} attribute "${selectErr.field}" on ${resourceType}.
+Expected one of: ${validList}${hasMore}
+
+Next step: Call records_get_attribute_options with
+  resource_type: "${resourceType}"
+  attribute: "${selectErr.field}"
+to list all valid values, then retry.`;
+                }
+                catch (err) {
+                    sanitizedLog(logger, 'debug', 'Failed to fetch select/status options for enhanced error message', {
+                        enhancerName: 'select-status',
+                        resourceType,
+                        attribute: selectErr.field,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    return `Value is not valid for attribute "${selectErr.field}" on ${resourceType}.
+Next step: Call records_get_attribute_options with
+  resource_type: "${resourceType}"
+  attribute: "${selectErr.field}"
+to see valid options, then retry.`;
+                }
+            }
+        }
+    }
+    // Pattern: "Cannot find select option with title 'X'" or "Cannot find Status with title 'X'"
+    const selectMatch = msg.match(/Cannot find (?:select option|Status) with title "(.+?)"/);
+    if (!selectMatch)
+        return null;
+    const invalidValue = selectMatch[1];
+    // Try to identify which field has the problem by checking record data
+    for (const [fieldName, fieldValue] of Object.entries(recordData)) {
+        if (fieldValue === invalidValue ||
+            (Array.isArray(fieldValue) && fieldValue.includes(invalidValue))) {
+            try {
+                const { AttributeOptionsService } = await import('../../../../../services/metadata/index.js');
+                const { options, attributeType } = await AttributeOptionsService.getOptions(resourceType, fieldName);
+                const validList = options
+                    .slice(0, 8)
+                    .map((o) => o.title)
+                    .join(', ');
+                const hasMore = options.length > 8 ? ` (+${options.length - 8} more)` : '';
+                return (`Value "${invalidValue}" is not valid for ${attributeType} attribute "${fieldName}" on ${resourceType}.\n\n` +
+                    `Valid options: ${validList}${hasMore}\n\n` +
+                    `Next step: Call records_get_attribute_options with\n` +
+                    `  resource_type: "${resourceType}"\n` +
+                    `  attribute: "${fieldName}"\n` +
+                    `to list all valid values, then retry.`);
+            }
+            catch (err) {
+                sanitizedLog(logger, 'debug', 'Failed to fetch attribute options (no invalid value extracted)', {
+                    enhancerName: 'select-status',
+                    resourceType,
+                    attribute: fieldName,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return (`Value "${invalidValue}" is not valid for attribute "${fieldName}" on ${resourceType}.\n\n` +
+                    `Next step: Call records_get_attribute_options with\n` +
+                    `  resource_type: "${resourceType}"\n` +
+                    `  attribute: "${fieldName}"\n` +
+                    `to see valid options, then retry.`);
+            }
+        }
+    }
+    // Couldn't match to a specific field, return generic hint
+    return (`Value "${invalidValue}" is not valid for an attribute on ${resourceType}.\n\n` +
+        `Next step: Use records_get_attribute_options to discover valid options for the attribute.`);
+};
+/**
+ * Select/Status Enhancer
+ * Provides valid options for select and status field errors
+ */
+export const selectStatusEnhancer = {
+    name: 'select-status',
+    errorName: 'value_not_found',
+    matches: (error, _context) => {
+        const msg = getErrorMessage(error);
+        return (msg.includes('Cannot find select option') ||
+            msg.includes('Cannot find Status') ||
+            msg.includes('select option'));
+    },
+    enhance: async (error, context) => {
+        const { resourceType, recordData } = context;
+        if (!recordData)
+            return null;
+        return enhanceSelectStatusError(error, resourceType, recordData);
+    },
+};
+//# sourceMappingURL=select-status-enhancer.js.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-status-enhancer.js","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/select-status-enhancer.ts"],"names":[],"mappings":"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"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Error Enhancer Strategy Pattern Types
+ * Issue #1001 - Refactoring crud-error-handlers.ts
+ */
+import type { ValidationMetadata } from '../../../../../handlers/tool-configs/universal/core/utils.js';
+/**
+ * Context passed to error enhancers
+ */
+export interface CrudErrorContext {
+    readonly operation: 'create' | 'update' | 'delete' | 'search';
+    readonly resourceType: string;
+    readonly recordData?: Readonly<Record<string, unknown>>;
+    readonly recordId?: string;
+    readonly validationMetadata?: Readonly<ValidationMetadata>;
+}
+/**
+ * Strategy interface for error enhancement
+ * Each enhancer implements pattern matching and message enhancement
+ */
+export interface ErrorEnhancer {
+    /** Unique name for the enhancer */
+    readonly name: string;
+    /** Check if this enhancer can handle the error */
+    readonly matches: (error: unknown, context: CrudErrorContext) => boolean;
+    /** Enhance the error message with context-specific details */
+    readonly enhance: (error: unknown, context: CrudErrorContext) => Promise<string | null>;
+    /** Error name to use when throwing the enhanced error */
+    readonly errorName: string;
+}
+/**
+ * Extract error message from Error instances, axios-style errors, or test mocks
+ *
+ * Handles three cases:
+ * 1. Real Error instances: returns error.message
+ * 2. Error-like objects (axios/mocks): extracts message property
+ * 3. Primitive values: converts to string
+ *
+ * This helper was added to fix test compatibility issues where test mocks
+ * aren't true Error instances but have message properties. It provides a
+ * consistent way to extract error messages across production code and tests.
+ *
+ * @param error - Any error value (Error, axios error object, string, etc.)
+ * @returns Error message as string (never null/undefined)
+ *
+ * @example
+ * getErrorMessage(new Error("test")) // "test"
+ * getErrorMessage({ message: "axios error" }) // "axios error"
+ * getErrorMessage("string error") // "string error"
+ */
+export declare const getErrorMessage: (error: unknown) => string;
+/**
+ * Axios-style error response structure
+ * Used for type-safe extraction of validation errors from Attio API responses
+ */
+export interface AxiosErrorResponse {
+    data?: {
+        message?: string;
+        validation_errors?: Array<{
+            field?: string;
+            path?: string;
+            message?: string;
+        }>;
+    };
+}
+/**
+ * Axios error with response
+ * Allows type-safe access to error.response.data.validation_errors
+ */
+export interface AxiosError extends Error {
+    response?: AxiosErrorResponse;
+}
+/**
+ * Type guard to check if error is an Axios error
+ */
+export declare function isAxiosError(error: unknown): error is AxiosError;
+export type { ValidationMetadata };
+//# sourceMappingURL=types.d.ts.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAEzE,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,MAMhD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,KAAK,CAAC;YACxB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC,CAAC;KACJ,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,KAAK;IACvC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAOhE;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/types.js

@@ -0,0 +1,42 @@
+/**
+ * Error Enhancer Strategy Pattern Types
+ * Issue #1001 - Refactoring crud-error-handlers.ts
+ */
+/**
+ * Extract error message from Error instances, axios-style errors, or test mocks
+ *
+ * Handles three cases:
+ * 1. Real Error instances: returns error.message
+ * 2. Error-like objects (axios/mocks): extracts message property
+ * 3. Primitive values: converts to string
+ *
+ * This helper was added to fix test compatibility issues where test mocks
+ * aren't true Error instances but have message properties. It provides a
+ * consistent way to extract error messages across production code and tests.
+ *
+ * @param error - Any error value (Error, axios error object, string, etc.)
+ * @returns Error message as string (never null/undefined)
+ *
+ * @example
+ * getErrorMessage(new Error("test")) // "test"
+ * getErrorMessage({ message: "axios error" }) // "axios error"
+ * getErrorMessage("string error") // "string error"
+ */
+export const getErrorMessage = (error) => {
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+};
+/**
+ * Type guard to check if error is an Axios error
+ */
+export function isAxiosError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'response' in error &&
+        typeof error.response === 'object');
+}
+//# sourceMappingURL=types.js.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoCH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAc,EAAU,EAAE;IACxD,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACjD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAC7D,OAAO,MAAM,CAAE,KAAiC,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC,CAAC;AAyBF;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,UAAU,IAAI,KAAK;QACnB,OAAQ,KAAgC,CAAC,QAAQ,KAAK,QAAQ,CAC/D,CAAC;AACJ,CAAC"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Uniqueness Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ * Issue #990 - Enhanced uniqueness constraint violation handling
+ *
+ * Detects uniqueness/duplicate errors and attempts to find the
+ * conflicting record to provide actionable guidance.
+ */
+import type { ErrorEnhancer } from './types.js';
+/**
+ * Uniqueness Enhancer
+ * Detects duplicate/uniqueness constraint violations and finds the conflicting record
+ */
+export declare const uniquenessEnhancer: ErrorEnhancer;
+//# sourceMappingURL=uniqueness-enhancer.d.ts.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniqueness-enhancer.d.ts","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAuHlE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAiChC,CAAC"}

package/dist/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.js

@@ -0,0 +1,109 @@
+/**
+ * Uniqueness Error Enhancer
+ * Issue #1001 - Strategy Pattern for CRUD error handling
+ * Issue #990 - Enhanced uniqueness constraint violation handling
+ *
+ * Detects uniqueness/duplicate errors and attempts to find the
+ * conflicting record to provide actionable guidance.
+ */
+import { getSingularResourceType } from '../../../../../handlers/tool-configs/universal/shared-handlers.js';
+import { sanitizedLog } from '../../../../../handlers/tool-configs/universal/core/pii-sanitizer.js';
+import { createScopedLogger } from '../../../../../utils/logger.js';
+const logger = createScopedLogger('uniqueness-enhancer');
+/**
+ * Searches for conflicting record when uniqueness constraint violation occurs
+ */
+async function enhanceUniquenessErrorWithSearch(resourceType, recordData) {
+    const UNIQUE_FIELD_SEARCHERS = {
+        companies: {
+            fields: ['domains', 'domain'],
+            search: async (value) => {
+                const { searchCompaniesByDomain } = await import('../../../../../objects/companies/search.js');
+                return searchCompaniesByDomain(value);
+            },
+        },
+        people: {
+            fields: ['email_addresses', 'email', 'emails'],
+            search: async (value) => {
+                const { searchPeopleByEmail } = await import('../../../../../objects/people/search.js');
+                return searchPeopleByEmail(value);
+            },
+        },
+    };
+    const searcher = UNIQUE_FIELD_SEARCHERS[resourceType.toLowerCase()];
+    if (!searcher)
+        return null;
+    // Find which unique field has a value in recordData
+    for (const field of searcher.fields) {
+        let searchValue = recordData[field];
+        // Handle array format (e.g., domains: ["example.com"])
+        if (Array.isArray(searchValue) && searchValue.length > 0) {
+            searchValue = searchValue[0];
+        }
+        // Handle object format for emails (e.g., email_addresses: [{email_address: "..."}])
+        if (searchValue &&
+            typeof searchValue === 'object' &&
+            !Array.isArray(searchValue)) {
+            const obj = searchValue;
+            searchValue = obj.email_address || obj.email || obj.value;
+        }
+        if (searchValue && typeof searchValue === 'string') {
+            try {
+                const existing = await searcher.search(searchValue);
+                if (existing && existing.length > 0) {
+                    const recordId = existing[0]?.id?.record_id;
+                    if (recordId) {
+                        return formatUniquenessErrorMessage(resourceType, field, searchValue, recordId);
+                    }
+                }
+            }
+            catch (err) {
+                // Search failed, log and continue to fallback
+                sanitizedLog(logger, 'debug', 'Uniqueness search failed', {
+                    resourceType,
+                    field,
+                    error: String(err),
+                });
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Formats actionable error message for uniqueness constraint violations
+ */
+function formatUniquenessErrorMessage(resourceType, field, value, recordId) {
+    const singular = getSingularResourceType(resourceType);
+    return (`Uniqueness conflict on "${field}": value "${value}" already exists on ${singular} record.\n\n` +
+        `EXISTING RECORD ID: ${recordId}\n\n` +
+        `OPTIONS:\n` +
+        `1. Update existing: update-record(resource_type="${resourceType}", record_id="${recordId}", record_data={...})\n` +
+        `2. View existing: records_get_details(resource_type="${resourceType}", record_id="${recordId}")\n` +
+        `3. Use a different ${field} value`);
+}
+/**
+ * Uniqueness Enhancer
+ * Detects duplicate/uniqueness constraint violations and finds the conflicting record
+ */
+export const uniquenessEnhancer = {
+    name: 'uniqueness',
+    errorName: 'duplicate_error',
+    matches: (error, _context) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        return (msg.includes('duplicate') ||
+            msg.toLowerCase().includes('uniqueness constraint'));
+    },
+    enhance: async (_error, context) => {
+        const { resourceType, recordData } = context;
+        if (!recordData)
+            return null;
+        // Try to find and identify the conflicting record
+        const enhancedMessage = await enhanceUniquenessErrorWithSearch(resourceType, recordData);
+        if (enhancedMessage) {
+            return enhancedMessage;
+        }
+        // Fallback message if we couldn't find the specific record
+        return 'A record with similar data already exists. Check unique fields like domains or email_addresses.';
+    },
+};
+//# sourceMappingURL=uniqueness-enhancer.js.map

package/dist/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniqueness-enhancer.js","sourceRoot":"","sources":["../../../../../../src/handlers/tool-configs/universal/core/error-enhancers/uniqueness-enhancer.ts"],"names":[],"mappings":"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"}