attio-mcp 0.1.1 → 1.0.0

package/dist/utils/type-extraction.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Type-safe utility functions for extracting nested values from complex object structures
+ *
+ * **Issue #679 Implementation:**
+ * Addresses complex nested type assertions that appear throughout the services directory
+ * and hurt code readability. Provides clean, type-safe alternatives to patterns like:
+ * `((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id`
+ *
+ * **Performance Notes:**
+ * - Functions are optimized for readability over raw performance
+ * - For hot paths with frequent access, consider caching results
+ * - Debug logging only active in development mode for performance
+ */
+/**
+ * Safely extracts record_id from nested object structures
+ * Handles the common pattern: obj?.id?.record_id with proper type safety
+ *
+ * @param obj - Object that may contain nested id.record_id structure
+ * @returns The record_id string or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const recordId = ((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id as string;
+ *
+ * // After (clean):
+ * const recordId = safeExtractRecordId(rec);
+ * if (recordId) {
+ *   // Use recordId safely
+ * }
+ */
+export declare function safeExtractRecordId(obj: unknown): string | undefined;
+/**
+ * Safely extracts the id object from a record
+ * Handles the pattern: obj?.id with proper type safety
+ *
+ * @param obj - Object that may contain an id field
+ * @returns The id object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const idObj = (rec as Record<string, unknown>)?.id as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const idObj = safeExtractIdObject(rec);
+ * if (idObj?.record_id) {
+ *   // Use idObj safely
+ * }
+ */
+export declare function safeExtractIdObject(obj: unknown): Record<string, unknown> | undefined;
+/**
+ * Safely extracts nested property values with type safety
+ * Handles patterns like: obj?.values?.propertyName with multiple levels
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse
+ * @returns The extracted value or undefined if path is invalid
+ *
+ * @example
+ * // Before (complex):
+ * // const name = ((rec as Record<string, unknown>)?.values as Record<string, unknown>)?.name;
+ *
+ * // After (clean with type inference):
+ * const name = safeExtractNestedValue<string>(rec, 'values', 'name');
+ * const domains = safeExtractNestedValue<string[]>(rec, 'values', 'domains');
+ * const count = safeExtractNestedValue<number>(rec, 'data', 'count');
+ *
+ * // Generic type parameter provides better IntelliSense and type safety
+ */
+export declare function safeExtractNestedValue<T = unknown>(obj: unknown, ...path: string[]): T | undefined;
+/**
+ * Safely extracts values object from a record
+ * Handles the pattern: obj?.values with proper type safety
+ *
+ * @param obj - Object that may contain a values field
+ * @returns The values object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const values = (rec as Record<string, unknown>)?.values as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const values = safeExtractValuesObject(rec);
+ * if (values?.name) {
+ *   // Use values safely
+ * }
+ */
+export declare function safeExtractValuesObject(obj: unknown): Record<string, unknown> | undefined;
+/**
+ * Safely checks if a record has a valid record_id
+ * Combines existence check with type safety for common validation pattern
+ *
+ * @param obj - Object to check
+ * @returns True if object has a valid string record_id
+ *
+ * @example
+ * // Before (complex):
+ * // const isValid = !!(((record as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id);
+ *
+ * // After (clean):
+ * const isValid = hasValidRecordId(record);
+ * if (!isValid) {
+ *   // Handle missing record_id
+ * }
+ */
+export declare function hasValidRecordId(obj: unknown): boolean;
+/**
+ * Type guard to check if an object looks like an Attio record
+ * Provides runtime type checking for record-like structures
+ *
+ * @param obj - Object to check
+ * @returns True if object has the expected record structure
+ *
+ * @example
+ * if (isAttioRecordLike(response)) {
+ *   const recordId = safeExtractRecordId(response);
+ *   // TypeScript knows this is safe
+ * }
+ */
+export declare function isAttioRecordLike(obj: unknown): obj is Record<string, unknown>;
+/**
+ * Safely extracts an array from a nested object path with type safety
+ * Handles the common pattern: Array.isArray(obj?.values?.field) && obj.values.field
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse to the array field
+ * @returns The array or undefined if path is invalid or not an array
+ *
+ * @example
+ * // Before (complex):
+ * // const domains = Array.isArray(record.values?.domains) ? record.values.domains : undefined;
+ *
+ * // After (clean):
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * const tags = safeExtractArray<string>(record, 'data', 'tags');
+ */
+export declare function safeExtractArray<T = unknown>(obj: unknown, ...path: string[]): T[] | undefined;
+/**
+ * Type guard to check if a nested field is an array with optional type checking
+ * Provides runtime validation for array fields in nested objects
+ *
+ * @param obj - Object to check
+ * @param path - Array of property names to traverse to the field
+ * @returns True if the nested field is an array
+ *
+ * @example
+ * // Before (complex):
+ * // if (Array.isArray(((record as Record<string, unknown>)?.values as Record<string, unknown>)?.domains)) {
+ *
+ * // After (clean):
+ * if (safeIsArrayField(record, 'values', 'domains')) {
+ *   // TypeScript knows domains is an array
+ *   const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * }
+ */
+export declare function safeIsArrayField(obj: unknown, ...path: string[]): boolean;
+/**
+ * Safely extracts a string value from nested object with fallback
+ * Common pattern for extracting string fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The string value or fallback
+ *
+ * @example
+ * const name = safeExtractString(record, 'Unknown', 'values', 'name');
+ * const title = safeExtractString(task, 'Untitled', 'data', 'title');
+ */
+export declare function safeExtractString(obj: unknown, fallback: string, ...path: string[]): string;
+/**
+ * Safely extracts a number value from nested object with fallback
+ * Common pattern for extracting numeric fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The number value or fallback
+ *
+ * @example
+ * const count = safeExtractNumber(record, 0, 'data', 'count');
+ * const priority = safeExtractNumber(task, 1, 'values', 'priority');
+ */
+export declare function safeExtractNumber(obj: unknown, fallback: number, ...path: string[]): number;
+/**
+ * Enhanced type guard for validating object structure with specific properties
+ * Provides runtime validation for complex object structures
+ *
+ * @param obj - Object to validate
+ * @param requiredProps - Array of required property names
+ * @returns True if object has all required properties
+ *
+ * @example
+ * if (hasRequiredProperties(record, ['id', 'values'])) {
+ *   // TypeScript knows record has id and values properties
+ *   const recordId = safeExtractRecordId(record);
+ * }
+ */
+export declare function hasRequiredProperties(obj: unknown, requiredProps: string[]): obj is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a non-empty string
+ * Useful for validating string fields that shouldn't be empty
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty string
+ *
+ * @example
+ * const name = safeExtractString(record, '', 'values', 'name');
+ * if (isNonEmptyString(name)) {
+ *   // TypeScript knows name is a non-empty string
+ *   console.log(name.toUpperCase());
+ * }
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid array with minimum length
+ * Provides runtime validation for arrays with length constraints
+ *
+ * @param value - Value to check
+ * @param minLength - Minimum required length (default: 1)
+ * @returns True if value is an array with at least minLength items
+ *
+ * @example
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * if (isValidArray(domains, 1)) {
+ *   // TypeScript knows domains is a non-empty array
+ *   domains.forEach(domain => console.log(domain));
+ * }
+ */
+export declare function isValidArray<T>(value: unknown, minLength?: number): value is T[];
+/**
+ * Advanced type guard for Attio record validation with strict checking
+ * Validates that an object has the complete Attio record structure
+ *
+ * @param obj - Object to validate
+ * @returns True if object is a complete Attio record
+ *
+ * @example
+ * if (isCompleteAttioRecord(response)) {
+ *   // TypeScript knows this has id.record_id and values
+ *   const recordId = safeExtractRecordId(response); // guaranteed to be string
+ *   const values = safeExtractValuesObject(response); // guaranteed to be object
+ * }
+ */
+export declare function isCompleteAttioRecord(obj: unknown): obj is {
+    id: {
+        record_id: string;
+        [key: string]: unknown;
+    };
+    values: Record<string, unknown>;
+    [key: string]: unknown;
+};
+//# sourceMappingURL=type-extraction.d.ts.map

package/dist/utils/type-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-extraction.d.ts","sourceRoot":"","sources":["../../src/utils/type-extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2BH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAwCpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAarC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAChD,GAAG,EAAE,OAAO,EACZ,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,CAAC,GAAG,SAAS,CAef;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAarC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,GACX,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAchC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,GAAG,EAAE,OAAO,EACZ,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,CAAC,EAAE,GAAG,SAAS,CAGjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAGzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAGR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,MAAM,EAAE,GACtB,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOhC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,SAAI,GAAG,KAAK,IAAI,CAAC,EAAE,CAE3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAC1D,EAAE,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAYA"}

package/dist/utils/type-extraction.js

@@ -0,0 +1,358 @@
+/**
+ * Type-safe utility functions for extracting nested values from complex object structures
+ *
+ * **Issue #679 Implementation:**
+ * Addresses complex nested type assertions that appear throughout the services directory
+ * and hurt code readability. Provides clean, type-safe alternatives to patterns like:
+ * `((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id`
+ *
+ * **Performance Notes:**
+ * - Functions are optimized for readability over raw performance
+ * - For hot paths with frequent access, consider caching results
+ * - Debug logging only active in development mode for performance
+ */
+/**
+ * Debug logger for type extraction operations
+ * Only logs in development environment to avoid performance impact
+ */
+function debugTypeExtraction(operation, input, result, error) {
+    /* istanbul ignore next */
+    if (process.env.NODE_ENV === 'development' &&
+        process.env.TYPE_EXTRACTION_DEBUG === 'true') {
+        console.warn(`[TypeExtraction] ${operation}:`, {
+            inputType: typeof input,
+            resultType: typeof result,
+            hasResult: result !== undefined,
+            error,
+            timestamp: Date.now(),
+        });
+    }
+}
+/**
+ * Safely extracts record_id from nested object structures
+ * Handles the common pattern: obj?.id?.record_id with proper type safety
+ *
+ * @param obj - Object that may contain nested id.record_id structure
+ * @returns The record_id string or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const recordId = ((rec as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id as string;
+ *
+ * // After (clean):
+ * const recordId = safeExtractRecordId(rec);
+ * if (recordId) {
+ *   // Use recordId safely
+ * }
+ */
+export function safeExtractRecordId(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        debugTypeExtraction('safeExtractRecordId', obj, undefined, 'Input not an object');
+        return undefined;
+    }
+    const record = obj;
+    const idField = record.id;
+    if (typeof idField !== 'object' || idField === null) {
+        debugTypeExtraction('safeExtractRecordId', obj, undefined, 'id field not an object');
+        return undefined;
+    }
+    const idObject = idField;
+    const recordId = idObject.record_id;
+    const result = typeof recordId === 'string' ? recordId : undefined;
+    if (result === undefined && recordId !== undefined) {
+        debugTypeExtraction('safeExtractRecordId', obj, undefined, `record_id is ${typeof recordId}, not string`);
+    }
+    else {
+        debugTypeExtraction('safeExtractRecordId', obj, result);
+    }
+    return result;
+}
+/**
+ * Safely extracts the id object from a record
+ * Handles the pattern: obj?.id with proper type safety
+ *
+ * @param obj - Object that may contain an id field
+ * @returns The id object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const idObj = (rec as Record<string, unknown>)?.id as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const idObj = safeExtractIdObject(rec);
+ * if (idObj?.record_id) {
+ *   // Use idObj safely
+ * }
+ */
+export function safeExtractIdObject(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return undefined;
+    }
+    const record = obj;
+    const idField = record.id;
+    if (typeof idField !== 'object' || idField === null) {
+        return undefined;
+    }
+    return idField;
+}
+/**
+ * Safely extracts nested property values with type safety
+ * Handles patterns like: obj?.values?.propertyName with multiple levels
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse
+ * @returns The extracted value or undefined if path is invalid
+ *
+ * @example
+ * // Before (complex):
+ * // const name = ((rec as Record<string, unknown>)?.values as Record<string, unknown>)?.name;
+ *
+ * // After (clean with type inference):
+ * const name = safeExtractNestedValue<string>(rec, 'values', 'name');
+ * const domains = safeExtractNestedValue<string[]>(rec, 'values', 'domains');
+ * const count = safeExtractNestedValue<number>(rec, 'data', 'count');
+ *
+ * // Generic type parameter provides better IntelliSense and type safety
+ */
+export function safeExtractNestedValue(obj, ...path) {
+    if (typeof obj !== 'object' || obj === null) {
+        return undefined;
+    }
+    let current = obj;
+    for (const key of path) {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Safely extracts values object from a record
+ * Handles the pattern: obj?.values with proper type safety
+ *
+ * @param obj - Object that may contain a values field
+ * @returns The values object or undefined if not found
+ *
+ * @example
+ * // Before (complex):
+ * // const values = (rec as Record<string, unknown>)?.values as Record<string, unknown>;
+ *
+ * // After (clean):
+ * const values = safeExtractValuesObject(rec);
+ * if (values?.name) {
+ *   // Use values safely
+ * }
+ */
+export function safeExtractValuesObject(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return undefined;
+    }
+    const record = obj;
+    const valuesField = record.values;
+    if (typeof valuesField !== 'object' || valuesField === null) {
+        return undefined;
+    }
+    return valuesField;
+}
+/**
+ * Safely checks if a record has a valid record_id
+ * Combines existence check with type safety for common validation pattern
+ *
+ * @param obj - Object to check
+ * @returns True if object has a valid string record_id
+ *
+ * @example
+ * // Before (complex):
+ * // const isValid = !!(((record as Record<string, unknown>)?.id as Record<string, unknown>)?.record_id);
+ *
+ * // After (clean):
+ * const isValid = hasValidRecordId(record);
+ * if (!isValid) {
+ *   // Handle missing record_id
+ * }
+ */
+export function hasValidRecordId(obj) {
+    const recordId = safeExtractRecordId(obj);
+    return typeof recordId === 'string' && recordId.length > 0;
+}
+/**
+ * Type guard to check if an object looks like an Attio record
+ * Provides runtime type checking for record-like structures
+ *
+ * @param obj - Object to check
+ * @returns True if object has the expected record structure
+ *
+ * @example
+ * if (isAttioRecordLike(response)) {
+ *   const recordId = safeExtractRecordId(response);
+ *   // TypeScript knows this is safe
+ * }
+ */
+export function isAttioRecordLike(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const record = obj;
+    if (!('id' in record)) {
+        return false;
+    }
+    const idField = record.id;
+    return (typeof idField === 'object' && idField !== null && !Array.isArray(idField));
+}
+/**
+ * Safely extracts an array from a nested object path with type safety
+ * Handles the common pattern: Array.isArray(obj?.values?.field) && obj.values.field
+ *
+ * @param obj - Object to extract from
+ * @param path - Array of property names to traverse to the array field
+ * @returns The array or undefined if path is invalid or not an array
+ *
+ * @example
+ * // Before (complex):
+ * // const domains = Array.isArray(record.values?.domains) ? record.values.domains : undefined;
+ *
+ * // After (clean):
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * const tags = safeExtractArray<string>(record, 'data', 'tags');
+ */
+export function safeExtractArray(obj, ...path) {
+    const value = safeExtractNestedValue(obj, ...path);
+    return Array.isArray(value) ? value : undefined;
+}
+/**
+ * Type guard to check if a nested field is an array with optional type checking
+ * Provides runtime validation for array fields in nested objects
+ *
+ * @param obj - Object to check
+ * @param path - Array of property names to traverse to the field
+ * @returns True if the nested field is an array
+ *
+ * @example
+ * // Before (complex):
+ * // if (Array.isArray(((record as Record<string, unknown>)?.values as Record<string, unknown>)?.domains)) {
+ *
+ * // After (clean):
+ * if (safeIsArrayField(record, 'values', 'domains')) {
+ *   // TypeScript knows domains is an array
+ *   const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * }
+ */
+export function safeIsArrayField(obj, ...path) {
+    const value = safeExtractNestedValue(obj, ...path);
+    return Array.isArray(value);
+}
+/**
+ * Safely extracts a string value from nested object with fallback
+ * Common pattern for extracting string fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The string value or fallback
+ *
+ * @example
+ * const name = safeExtractString(record, 'Unknown', 'values', 'name');
+ * const title = safeExtractString(task, 'Untitled', 'data', 'title');
+ */
+export function safeExtractString(obj, fallback, ...path) {
+    const value = safeExtractNestedValue(obj, ...path);
+    return typeof value === 'string' ? value : fallback;
+}
+/**
+ * Safely extracts a number value from nested object with fallback
+ * Common pattern for extracting numeric fields with default values
+ *
+ * @param obj - Object to extract from
+ * @param fallback - Default value if extraction fails
+ * @param path - Array of property names to traverse
+ * @returns The number value or fallback
+ *
+ * @example
+ * const count = safeExtractNumber(record, 0, 'data', 'count');
+ * const priority = safeExtractNumber(task, 1, 'values', 'priority');
+ */
+export function safeExtractNumber(obj, fallback, ...path) {
+    const value = safeExtractNestedValue(obj, ...path);
+    return typeof value === 'number' ? value : fallback;
+}
+/**
+ * Enhanced type guard for validating object structure with specific properties
+ * Provides runtime validation for complex object structures
+ *
+ * @param obj - Object to validate
+ * @param requiredProps - Array of required property names
+ * @returns True if object has all required properties
+ *
+ * @example
+ * if (hasRequiredProperties(record, ['id', 'values'])) {
+ *   // TypeScript knows record has id and values properties
+ *   const recordId = safeExtractRecordId(record);
+ * }
+ */
+export function hasRequiredProperties(obj, requiredProps) {
+    if (typeof obj !== 'object' || obj === null) {
+        return false;
+    }
+    const record = obj;
+    return requiredProps.every((prop) => prop in record);
+}
+/**
+ * Type guard to check if a value is a non-empty string
+ * Useful for validating string fields that shouldn't be empty
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty string
+ *
+ * @example
+ * const name = safeExtractString(record, '', 'values', 'name');
+ * if (isNonEmptyString(name)) {
+ *   // TypeScript knows name is a non-empty string
+ *   console.log(name.toUpperCase());
+ * }
+ */
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Type guard to check if a value is a valid array with minimum length
+ * Provides runtime validation for arrays with length constraints
+ *
+ * @param value - Value to check
+ * @param minLength - Minimum required length (default: 1)
+ * @returns True if value is an array with at least minLength items
+ *
+ * @example
+ * const domains = safeExtractArray<string>(record, 'values', 'domains');
+ * if (isValidArray(domains, 1)) {
+ *   // TypeScript knows domains is a non-empty array
+ *   domains.forEach(domain => console.log(domain));
+ * }
+ */
+export function isValidArray(value, minLength = 1) {
+    return Array.isArray(value) && value.length >= minLength;
+}
+/**
+ * Advanced type guard for Attio record validation with strict checking
+ * Validates that an object has the complete Attio record structure
+ *
+ * @param obj - Object to validate
+ * @returns True if object is a complete Attio record
+ *
+ * @example
+ * if (isCompleteAttioRecord(response)) {
+ *   // TypeScript knows this has id.record_id and values
+ *   const recordId = safeExtractRecordId(response); // guaranteed to be string
+ *   const values = safeExtractValuesObject(response); // guaranteed to be object
+ * }
+ */
+export function isCompleteAttioRecord(obj) {
+    if (!isAttioRecordLike(obj)) {
+        return false;
+    }
+    const record = obj;
+    const recordId = safeExtractRecordId(record);
+    const values = safeExtractValuesObject(record);
+    return (isNonEmptyString(recordId) && typeof values === 'object' && values !== null);
+}
+//# sourceMappingURL=type-extraction.js.map

package/dist/utils/type-extraction.js.map

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

package/dist/utils/types/common.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Common reusable type aliases for data handling and API operations
+ */
+/**
+ * Generic object with unknown values - safe alternative to 'any'
+ * Use for API responses, configuration objects, and data transformation
+ */
+export type UnknownObject = Record<string, unknown>;
+/**
+ * Filter object used in API queries and data filtering operations
+ * Typically contains field names as keys with filter criteria as values
+ */
+export type FilterObject = Record<string, unknown>;
+/**
+ * API response data structure with unknown content
+ * Use for raw API responses before type validation
+ */
+export type ApiResponseData = Record<string, unknown>;
+/**
+ * Configuration object with string keys and unknown values
+ * Use for settings, options, and configuration parameters
+ */
+export type ConfigObject = Record<string, unknown>;
+/**
+ * Generic data transformation input/output
+ * Use in normalization and mapping functions
+ */
+export type DataObject = Record<string, unknown>;
+/**
+ * Error context object for error handling and enhancement
+ * Contains error metadata and debugging information
+ */
+export type ErrorContext = Record<string, unknown>;
+/**
+ * Logging metadata object for structured logging
+ * Contains additional context for log entries
+ */
+export type LogMetadata = Record<string, unknown>;
+//# sourceMappingURL=common.d.ts.map

package/dist/utils/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/utils/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/utils/types/common.js

@@ -0,0 +1,5 @@
+/**
+ * Common reusable type aliases for data handling and API operations
+ */
+export {};
+//# sourceMappingURL=common.js.map

package/dist/utils/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/utils/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG"}