attio-mcp 1.3.6 → 1.4.1

package/dist/services/skill-generator/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Type definitions for the Workspace Schema Skill Generator
+ *
+ * These types support the generation of Claude Skills from Attio workspace schemas,
+ * addressing the common issue where LLMs make errors due to unknown attribute values.
+ *
+ * @see Issue #983
+ */
+/**
+ * Configuration for the generate-skill CLI command
+ */
+export interface GenerateSkillConfig {
+    /** Object slugs to include in the generated skill */
+    objects: string[];
+    /** Output format: Claude Skill, plain Markdown, or JSON */
+    format: 'skill' | 'markdown' | 'json';
+    /** Output directory path */
+    outputDir: string;
+    /** Whether to package output as ZIP file */
+    zip: boolean;
+    /** Maximum options to display per attribute (default: 20) */
+    maxOptionsPerAttribute: number;
+    /** Whether to include archived options */
+    includeArchived: boolean;
+    /** Delay between attribute option fetches in milliseconds (default: 100) */
+    optionFetchDelayMs?: number;
+    /** Attio API key for authentication */
+    apiKey: string;
+}
+/**
+ * Complete workspace schema containing multiple objects
+ */
+export interface WorkspaceSchema {
+    /** Metadata about the schema generation */
+    metadata: {
+        /** ISO 8601 timestamp when schema was generated */
+        generatedAt: string;
+        /** Workspace identifier or name */
+        workspace: string;
+        /** List of object slugs included in this schema */
+        objects: string[];
+    };
+    /** Array of object schemas */
+    objects: ObjectSchema[];
+}
+/**
+ * Schema for a single Attio object (companies, people, deals, etc.)
+ */
+export interface ObjectSchema {
+    /** API slug of the object (e.g., 'companies', 'people') */
+    objectSlug: string;
+    /** Human-readable display name (e.g., 'Companies', 'People') */
+    displayName: string;
+    /** Array of attribute schemas for this object */
+    attributes: AttributeSchema[];
+}
+/**
+ * Schema for a single attribute within an object
+ */
+export interface AttributeSchema {
+    /** API slug used in API calls (e.g., 'team_size', 'industry') */
+    apiSlug: string;
+    /** Display name shown in Attio UI */
+    displayName: string;
+    /** Attribute type (e.g., 'text', 'select', 'location', 'personal-name') */
+    type: string;
+    /** Whether this attribute accepts multiple values */
+    isMultiselect: boolean;
+    /** Whether this attribute has a uniqueness constraint */
+    isUnique: boolean;
+    /** Whether this attribute is required for record creation */
+    isRequired: boolean;
+    /** Whether this attribute can be modified */
+    isWritable: boolean;
+    /** Optional description of the attribute's purpose */
+    description?: string;
+    /** For select/status attributes: array of valid options */
+    options?: AttributeOption[];
+    /** Whether options were truncated due to maxOptionsPerAttribute limit */
+    optionsTruncated?: boolean;
+    /** Total number of options available (before truncation) */
+    totalOptions?: number;
+    /** For complex types: structure definition with field types */
+    complexTypeStructure?: Record<string, unknown>;
+    /** For relationship attributes: target object and cardinality */
+    relationship?: {
+        /** Target object slug (e.g., 'companies', 'people') */
+        targetObject: string;
+        /** Relationship cardinality */
+        cardinality: string;
+    };
+}
+/**
+ * A single option for select or status attributes
+ */
+export interface AttributeOption {
+    /** Unique identifier for this option */
+    id: string;
+    /** Display title shown in Attio UI */
+    title: string;
+    /** API value used in API calls */
+    value: string;
+    /** Whether this option is archived */
+    isArchived?: boolean;
+}
+/**
+ * Formatted output ready for writing to disk
+ */
+export interface FormattedOutput {
+    /** Output format type */
+    format: 'skill' | 'markdown' | 'json';
+    /** Map of relative file paths to file contents */
+    files: Record<string, string>;
+}
+/**
+ * Result of writing skill output to disk
+ */
+export interface SkillOutput {
+    /** Output format that was written */
+    format: 'skill' | 'markdown' | 'json';
+    /** Absolute path to the output directory or file */
+    path: string;
+    /** List of files that were created */
+    files: string[];
+}
+/**
+ * Options for fetching object schema
+ */
+export interface FetchSchemaOptions {
+    /** Maximum options to retrieve per attribute */
+    maxOptionsPerAttribute: number;
+    /** Whether to include archived options */
+    includeArchived: boolean;
+    /** Delay between attribute option fetches in milliseconds (default: 100) */
+    optionFetchDelayMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/skill-generator/types.d.ts.map

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

package/dist/services/skill-generator/types.js

@@ -0,0 +1,10 @@
+/**
+ * Type definitions for the Workspace Schema Skill Generator
+ *
+ * These types support the generation of Claude Skills from Attio workspace schemas,
+ * addressing the common issue where LLMs make errors due to unknown attribute values.
+ *
+ * @see Issue #983
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/skill-generator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/skill-generator/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/services/update/FieldPersistenceHandler.d.ts

@@ -0,0 +1,101 @@
+/**
+ * FieldPersistenceHandler - Post-update field verification
+ *
+ * Extracted from UniversalUpdateService to separate verification concerns.
+ * Handles field persistence checking with configurable strictness.
+ *
+ * **Verification Modes** (controlled by `ENABLE_FIELD_VERIFICATION` env var):
+ * - **Enabled** (default): Any value except `'false'` enables verification
+ * - **Disabled**: Set to `'false'` to skip verification entirely
+ *
+ * **Strictness Modes** (controlled by `STRICT_FIELD_VALIDATION` env var):
+ * - **Strict**: `'true'` - Logs all discrepancies (cosmetic + semantic)
+ * - **Standard** (default): `'false'` - Logs only semantic mismatches
+ *
+ * **Semantic vs Cosmetic Mismatches**:
+ * - Cosmetic: Format differences with same logical value (e.g., "Demo" vs {title: "Demo"})
+ * - Semantic: Actual data loss or corruption (e.g., "Demo" vs "Qualified", missing data)
+ *
+ * @see Issue #984 - Modularize UniversalUpdateService (831→220 lines)
+ * @see PR #1006 Phase 3.2 - Enhanced JSDoc for verification behavior
+ */
+import { UniversalResourceType } from '../../handlers/tool-configs/universal/types.js';
+/**
+ * Options for field persistence verification
+ */
+export interface VerificationOptions {
+    /** Skip verification entirely (default: false) */
+    skip?: boolean;
+    /** Throw error on verification failure (default: from env STRICT_FIELD_VALIDATION) */
+    strict?: boolean;
+    /** Include cosmetic mismatches in warnings (default: false) */
+    includeCosmetic?: boolean;
+}
+/**
+ * Result of field persistence verification
+ */
+export interface VerificationResult {
+    /** Whether all fields were persisted correctly */
+    verified: boolean;
+    /** Non-blocking warnings about verification */
+    warnings: string[];
+    /** List of field discrepancies found */
+    discrepancies: string[];
+    /** Actual values retrieved from API */
+    actualValues: Record<string, unknown>;
+}
+/**
+ * FieldPersistenceHandler - Post-update verification orchestration
+ *
+ * @example
+ * ```typescript
+ * // Standard mode (semantic mismatches only)
+ * const result = await FieldPersistenceHandler.verifyPersistence(
+ *   UniversalResourceType.COMPANIES,
+ *   'company-123',
+ *   { stage: 'Demo' }
+ * );
+ * // Cosmetic mismatch "Demo" vs {title: "Demo"} → not logged
+ * // Semantic mismatch "Demo" vs "Qualified" → logged
+ *
+ * // Strict mode (all mismatches)
+ * process.env.STRICT_FIELD_VALIDATION = 'true';
+ * // Both cosmetic and semantic mismatches logged
+ * ```
+ */
+export declare class FieldPersistenceHandler {
+    /**
+     * Verify that fields were persisted correctly after update
+     *
+     * Supports three modes:
+     * 1. Disabled: ENABLE_FIELD_VERIFICATION=false (skip completely)
+     * 2. Warn-only: Default, logs discrepancies as warnings
+     * 3. Strict: STRICT_FIELD_VALIDATION=true, throws on mismatch
+     *
+     * @param resourceType - Resource type being verified
+     * @param recordId - ID of the updated record
+     * @param expectedData - Expected field values after update
+     * @param actualRecord - Optional actual record values. If not provided, will be fetched from API
+     * @param options - Verification options
+     * @returns Verification result with verified status, warnings, and discrepancies
+     * @throws UniversalValidationError if strict mode enabled and verification fails
+     */
+    static verifyPersistence(resourceType: UniversalResourceType, recordId: string, expectedData: Record<string, unknown>, actualRecord?: Record<string, unknown>, options?: VerificationOptions): Promise<VerificationResult>;
+    /**
+     * Determine if a discrepancy is semantic (real) vs cosmetic (format-only)
+     *
+     * Cosmetic mismatches occur when the same logical value is represented differently:
+     * - String vs object: "Demo" vs {title: "Demo"}
+     * - Array wrapping: "value" vs ["value"]
+     * - Type coercion: "123" vs 123
+     *
+     * Semantic mismatches indicate actual data loss or corruption:
+     * - Different values: "Demo" vs "Qualified"
+     * - Missing data: {field: "value"} vs {}
+     *
+     * @param discrepancy - Discrepancy message from verification
+     * @returns true if semantic mismatch, false if cosmetic
+     */
+    static isSemanticMismatch(discrepancy: string): boolean;
+}
+//# sourceMappingURL=FieldPersistenceHandler.d.ts.map

package/dist/services/update/FieldPersistenceHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPersistenceHandler.d.ts","sourceRoot":"","sources":["../../../src/services/update/FieldPersistenceHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AASnF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,uBAAuB;IAClC;;;;;;;;;;;;;;;OAeG;WACU,iBAAiB,CAC5B,YAAY,EAAE,qBAAqB,EACnC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC;IAoK9B;;;;;;;;;;;;;;OAcG;WACW,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAyB/D"}

package/dist/services/update/FieldPersistenceHandler.js

@@ -0,0 +1,207 @@
+/**
+ * FieldPersistenceHandler - Post-update field verification
+ *
+ * Extracted from UniversalUpdateService to separate verification concerns.
+ * Handles field persistence checking with configurable strictness.
+ *
+ * **Verification Modes** (controlled by `ENABLE_FIELD_VERIFICATION` env var):
+ * - **Enabled** (default): Any value except `'false'` enables verification
+ * - **Disabled**: Set to `'false'` to skip verification entirely
+ *
+ * **Strictness Modes** (controlled by `STRICT_FIELD_VALIDATION` env var):
+ * - **Strict**: `'true'` - Logs all discrepancies (cosmetic + semantic)
+ * - **Standard** (default): `'false'` - Logs only semantic mismatches
+ *
+ * **Semantic vs Cosmetic Mismatches**:
+ * - Cosmetic: Format differences with same logical value (e.g., "Demo" vs {title: "Demo"})
+ * - Semantic: Actual data loss or corruption (e.g., "Demo" vs "Qualified", missing data)
+ *
+ * @see Issue #984 - Modularize UniversalUpdateService (831→220 lines)
+ * @see PR #1006 Phase 3.2 - Enhanced JSDoc for verification behavior
+ */
+import { UpdateValidation } from '../../services/update/UpdateValidation.js';
+import { debug, error as logError } from '../../utils/logger.js';
+import { UniversalValidationError, ErrorType, } from '../../handlers/tool-configs/universal/schemas.js';
+import { isAttioList, isAttioRecord } from '../../types/attio.js';
+/**
+ * FieldPersistenceHandler - Post-update verification orchestration
+ *
+ * @example
+ * ```typescript
+ * // Standard mode (semantic mismatches only)
+ * const result = await FieldPersistenceHandler.verifyPersistence(
+ *   UniversalResourceType.COMPANIES,
+ *   'company-123',
+ *   { stage: 'Demo' }
+ * );
+ * // Cosmetic mismatch "Demo" vs {title: "Demo"} → not logged
+ * // Semantic mismatch "Demo" vs "Qualified" → logged
+ *
+ * // Strict mode (all mismatches)
+ * process.env.STRICT_FIELD_VALIDATION = 'true';
+ * // Both cosmetic and semantic mismatches logged
+ * ```
+ */
+export class FieldPersistenceHandler {
+    /**
+     * Verify that fields were persisted correctly after update
+     *
+     * Supports three modes:
+     * 1. Disabled: ENABLE_FIELD_VERIFICATION=false (skip completely)
+     * 2. Warn-only: Default, logs discrepancies as warnings
+     * 3. Strict: STRICT_FIELD_VALIDATION=true, throws on mismatch
+     *
+     * @param resourceType - Resource type being verified
+     * @param recordId - ID of the updated record
+     * @param expectedData - Expected field values after update
+     * @param actualRecord - Optional actual record values. If not provided, will be fetched from API
+     * @param options - Verification options
+     * @returns Verification result with verified status, warnings, and discrepancies
+     * @throws UniversalValidationError if strict mode enabled and verification fails
+     */
+    static async verifyPersistence(resourceType, recordId, expectedData, actualRecord, options = {}) {
+        const result = {
+            verified: true,
+            warnings: [],
+            discrepancies: [],
+            actualValues: {},
+        };
+        // Check if verification is disabled globally
+        if (options.skip || process.env.ENABLE_FIELD_VERIFICATION === 'false') {
+            result.warnings.push('Field persistence verification skipped (disabled via config)');
+            debug('FieldPersistenceHandler', 'Verification skipped', {
+                resourceType,
+                recordId,
+                reason: 'disabled',
+            });
+            return result;
+        }
+        // Fetch actualRecord if not provided
+        let recordData = actualRecord;
+        if (!recordData) {
+            try {
+                const record = await UpdateValidation.fetchRecordForVerification(resourceType, recordId);
+                if (!record) {
+                    result.warnings.push('Could not fetch record for verification: Record not found');
+                    debug('FieldPersistenceHandler', 'Record not found for verification', { resourceType, recordId });
+                    return result;
+                }
+                if (isAttioRecord(record)) {
+                    recordData = record.values || {};
+                }
+                else if (isAttioList(record)) {
+                    recordData = { ...record };
+                }
+                else {
+                    recordData = {};
+                }
+                debug('FieldPersistenceHandler', 'Fetched record for verification', {
+                    resourceType,
+                    recordId,
+                });
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                result.warnings.push(`Could not fetch record for verification: ${errorMessage}`);
+                debug('FieldPersistenceHandler', 'Failed to fetch record for verification', { resourceType, recordId, error: errorMessage });
+                return result;
+            }
+        }
+        result.actualValues = recordData || {};
+        try {
+            // Perform verification using existing UpdateValidation service
+            const verification = await UpdateValidation.verifyFieldPersistence(resourceType, recordId, expectedData);
+            result.verified = verification.verified;
+            result.warnings.push(...verification.warnings);
+            if (!verification.verified) {
+                const isStrictMode = options.strict !== undefined
+                    ? options.strict
+                    : process.env.STRICT_FIELD_VALIDATION === 'true';
+                const includeCosmetic = options.includeCosmetic || isStrictMode;
+                // Filter discrepancies based on mode
+                if (includeCosmetic) {
+                    // Include all discrepancies (cosmetic + semantic)
+                    result.discrepancies.push(...verification.discrepancies);
+                }
+                else {
+                    // Filter out cosmetic mismatches (e.g., "Demo" vs {title: "Demo"})
+                    const semanticMismatches = verification.discrepancies.filter((d) => this.isSemanticMismatch(d));
+                    result.discrepancies.push(...semanticMismatches);
+                }
+                // Log discrepancies
+                if (result.discrepancies.length > 0) {
+                    result.warnings.push(...result.discrepancies.map((d) => `Field persistence issue: ${d}`));
+                    logError('FieldPersistenceHandler', `Field persistence warnings for ${resourceType} ${recordId}:`, result.warnings);
+                }
+                // Throw in strict mode if semantic mismatches exist
+                if (isStrictMode && result.discrepancies.length > 0) {
+                    logError('FieldPersistenceHandler', 'Field persistence verification failed (strict mode)', new Error('Verification failed'), {
+                        resourceType,
+                        recordId,
+                        discrepancies: result.discrepancies,
+                    });
+                    throw new UniversalValidationError(`Field persistence verification failed: ${result.discrepancies.join('; ')}`, ErrorType.API_ERROR, {
+                        field: 'field_verification',
+                        suggestion: 'Check that field values are correctly formatted and supported by the API',
+                    });
+                }
+            }
+            else {
+                debug('FieldPersistenceHandler', 'Verification passed', {
+                    resourceType,
+                    recordId,
+                    fieldCount: Object.keys(expectedData).length,
+                });
+            }
+        }
+        catch (error) {
+            // Catch verification errors (network, API errors, etc.)
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            result.warnings.push(`Field verification warning: ${errorMessage}`);
+            logError('FieldPersistenceHandler', 'Field persistence verification error', error);
+            // Re-throw validation errors (strict mode failures)
+            if (error instanceof UniversalValidationError) {
+                throw error;
+            }
+        }
+        return result;
+    }
+    /**
+     * Determine if a discrepancy is semantic (real) vs cosmetic (format-only)
+     *
+     * Cosmetic mismatches occur when the same logical value is represented differently:
+     * - String vs object: "Demo" vs {title: "Demo"}
+     * - Array wrapping: "value" vs ["value"]
+     * - Type coercion: "123" vs 123
+     *
+     * Semantic mismatches indicate actual data loss or corruption:
+     * - Different values: "Demo" vs "Qualified"
+     * - Missing data: {field: "value"} vs {}
+     *
+     * @param discrepancy - Discrepancy message from verification
+     * @returns true if semantic mismatch, false if cosmetic
+     */
+    static isSemanticMismatch(discrepancy) {
+        // Extract expected and actual from: Field "X" persistence mismatch: expected Y, got Z
+        const match = discrepancy.match(/expected (.+?), got (.+?)$/);
+        if (!match) {
+            // If we can't parse, assume semantic (log for safety)
+            return true;
+        }
+        const [, expectedStr, actualStr] = match;
+        try {
+            // Check for cosmetic mismatches
+            // Case 1: String value vs object with title property
+            const isCosmetic = (expectedStr.includes('"') &&
+                actualStr.includes(expectedStr.replace(/^"|"$/g, ''))) ||
+                (actualStr.includes('"') &&
+                    expectedStr.includes(actualStr.replace(/^"|"$/g, '')));
+            return !isCosmetic; // Return true for semantic, false for cosmetic
+        }
+        catch {
+            // On parse errors, assume semantic (safety)
+            return true;
+        }
+    }
+}
+//# sourceMappingURL=FieldPersistenceHandler.js.map

package/dist/services/update/FieldPersistenceHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPersistenceHandler.js","sourceRoot":"","sources":["../../../src/services/update/FieldPersistenceHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,wBAAwB,EACxB,SAAS,GACV,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA4B9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAC5B,YAAmC,EACnC,QAAgB,EAChB,YAAqC,EACrC,YAAsC,EACtC,UAA+B,EAAE;QAEjC,MAAM,MAAM,GAAuB;YACjC,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,EAAE;YACZ,aAAa,EAAE,EAAE;YACjB,YAAY,EAAE,EAAE;SACjB,CAAC;QAEF,6CAA6C;QAC7C,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,yBAAyB,KAAK,OAAO,EAAE,CAAC;YACtE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAClB,8DAA8D,CAC/D,CAAC;YACF,KAAK,CAAC,yBAAyB,EAAE,sBAAsB,EAAE;gBACvD,YAAY;gBACZ,QAAQ;gBACR,MAAM,EAAE,UAAU;aACnB,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,qCAAqC;QACrC,IAAI,UAAU,GAAG,YAAY,CAAC;QAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,0BAA0B,CAC9D,YAAY,EACZ,QAAQ,CACT,CAAC;gBACF,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,CAAC,QAAQ,CAAC,IAAI,CAClB,2DAA2D,CAC5D,CAAC;oBACF,KAAK,CACH,yBAAyB,EACzB,mCAAmC,EACnC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAC3B,CAAC;oBACF,OAAO,MAAM,CAAC;gBAChB,CAAC;gBACD,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC1B,UAAU,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;gBACnC,CAAC;qBAAM,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC/B,UAAU,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;gBAC7B,CAAC;qBAAM,CAAC;oBACN,UAAU,GAAG,EAAE,CAAC;gBAClB,CAAC;gBACD,KAAK,CAAC,yBAAyB,EAAE,iCAAiC,EAAE;oBAClE,YAAY;oBACZ,QAAQ;iBACT,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,YAAY,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACtE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAClB,4CAA4C,YAAY,EAAE,CAC3D,CAAC;gBACF,KAAK,CACH,yBAAyB,EACzB,yCAAyC,EACzC,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,CAChD,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAED,MAAM,CAAC,YAAY,GAAG,UAAU,IAAI,EAAE,CAAC;QAEvC,IAAI,CAAC;YACH,+DAA+D;YAC/D,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAC,sBAAsB,CAChE,YAAY,EACZ,QAAQ,EACR,YAAY,CACb,CAAC;YAEF,MAAM,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;YACxC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;YAE/C,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAChB,OAAO,CAAC,MAAM,KAAK,SAAS;oBAC1B,CAAC,CAAC,OAAO,CAAC,MAAM;oBAChB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM,CAAC;gBACrD,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,YAAY,CAAC;gBAEhE,qCAAqC;gBACrC,IAAI,eAAe,EAAE,CAAC;oBACpB,kDAAkD;oBAClD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;gBAC3D,CAAC;qBAAM,CAAC;oBACN,mEAAmE;oBACnE,MAAM,kBAAkB,GAAG,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACjE,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAC3B,CAAC;oBACF,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC;gBACnD,CAAC;gBAED,oBAAoB;gBACpB,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAClB,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAC,CACpE,CAAC;oBAEF,QAAQ,CACN,yBAAyB,EACzB,kCAAkC,YAAY,IAAI,QAAQ,GAAG,EAC7D,MAAM,CAAC,QAAQ,CAChB,CAAC;gBACJ,CAAC;gBAED,oDAAoD;gBACpD,IAAI,YAAY,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpD,QAAQ,CACN,yBAAyB,EACzB,qDAAqD,EACrD,IAAI,KAAK,CAAC,qBAAqB,CAAC,EAChC;wBACE,YAAY;wBACZ,QAAQ;wBACR,aAAa,EAAE,MAAM,CAAC,aAAa;qBACpC,CACF,CAAC;oBAEF,MAAM,IAAI,wBAAwB,CAChC,0CAA0C,MAAM,CAAC,aAAa,CAAC,IAAI,CACjE,IAAI,CACL,EAAE,EACH,SAAS,CAAC,SAAS,EACnB;wBACE,KAAK,EAAE,oBAAoB;wBAC3B,UAAU,EACR,0EAA0E;qBAC7E,CACF,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,yBAAyB,EAAE,qBAAqB,EAAE;oBACtD,YAAY;oBACZ,QAAQ;oBACR,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM;iBAC7C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,wDAAwD;YACxD,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAEzD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,+BAA+B,YAAY,EAAE,CAAC,CAAC;YAEpE,QAAQ,CACN,yBAAyB,EACzB,sCAAsC,EACtC,KAAK,CACN,CAAC;YAEF,oDAAoD;YACpD,IAAI,KAAK,YAAY,wBAAwB,EAAE,CAAC;gBAC9C,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,kBAAkB,CAAC,WAAmB;QAClD,sFAAsF;QACtF,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,sDAAsD;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QAEzC,IAAI,CAAC;YACH,gCAAgC;YAChC,qDAAqD;YACrD,MAAM,UAAU,GACd,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC;gBACxB,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;gBACxD,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;oBACtB,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;YAE3D,OAAO,CAAC,UAAU,CAAC,CAAC,+CAA+C;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/services/update/FieldValidationHandler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * FieldValidationHandler - Validation orchestration with display name resolution
+ *
+ * Consolidates validation logic and integrates display name resolution
+ * for create/update operations.
+ *
+ * @see Issue #984 - Extend display name resolution to create/update operations
+ */
+import { UniversalResourceType } from '../../handlers/tool-configs/universal/types.js';
+/**
+ * Result of field validation
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Validation errors (blocking) */
+    errors: string[];
+    /** Validation warnings (non-blocking) */
+    warnings: string[];
+    /** Field suggestions for user */
+    suggestions: string[];
+    /** Map of display name → API slug resolutions */
+    resolvedFields?: Map<string, string>;
+}
+/**
+ * FieldValidationHandler - Validation and display name resolution
+ */
+export declare class FieldValidationHandler {
+    /**
+     * Validate fields and optionally resolve display names to API slugs
+     *
+     * Integrates display name resolution (previously only in get_attribute_options)
+     * to work for create/update operations.
+     *
+     * @param resourceType - Resource type being validated
+     * @param values - Field values to validate
+     * @param objectSlug - Optional object slug for display name resolution
+     * @param enableDisplayNameResolution - Whether to attempt display name resolution (default: true)
+     * @returns Validation result with warnings, suggestions, and resolved field names
+     */
+    static validateAndResolve(resourceType: UniversalResourceType, values: Record<string, unknown>, objectSlug?: string, enableDisplayNameResolution?: boolean): Promise<ValidationResult>;
+    /**
+     * Apply deal-specific validation and defaults
+     *
+     * @param values - Deal values to validate
+     * @param skipApiValidation - Whether to skip API validation
+     * @returns Deal validation result with validated data, warnings, and suggestions
+     */
+    static validateDealDefaults(values: Record<string, unknown>, skipApiValidation?: boolean): Promise<{
+        dealData: Record<string, unknown>;
+        warnings: string[];
+        suggestions: string[];
+    }>;
+    /**
+     * Attempt to resolve display names to API slugs for unknown fields
+     *
+     * This extends display name resolution (previously only in get_attribute_options)
+     * to work for create/update operations, improving UX consistency.
+     *
+     * @param values - Field values (may contain display names like "Deal stage")
+     * @param objectSlug - Object slug for attribute lookup
+     * @param result - Validation result to populate with resolutions
+     */
+    private static resolveDisplayNames;
+    /**
+     * Attempt to resolve a display name to an API slug
+     *
+     * Uses the exported resolveAttributeDisplayName from shared-handlers.ts
+     * to support user-friendly field names like "Deal stage" instead of "stage"
+     *
+     * @param objectSlug - The object slug (e.g., "deals", "companies")
+     * @param fieldName - The field name to resolve (e.g., "Deal stage")
+     * @returns The resolved API slug if found, or null
+     */
+    private static attemptDisplayNameResolution;
+}
+//# sourceMappingURL=FieldValidationHandler.d.ts.map

package/dist/services/update/FieldValidationHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldValidationHandler.d.ts","sourceRoot":"","sources":["../../../src/services/update/FieldValidationHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AAKnF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,qBAAa,sBAAsB;IACjC;;;;;;;;;;;OAWG;WACU,kBAAkB,CAC7B,YAAY,EAAE,qBAAqB,EACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,CAAC,EAAE,MAAM,EACnB,2BAA2B,GAAE,OAAc,GAC1C,OAAO,CAAC,gBAAgB,CAAC;IA2C5B;;;;;;OAMG;WACU,oBAAoB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,iBAAiB,GAAE,OAAe,GACjC,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IAoCF;;;;;;;;;OASG;mBACkB,mBAAmB;IA2CxC;;;;;;;;;OASG;mBACkB,4BAA4B;CAmBlD"}