@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/adapters/errors.js

@@ -0,0 +1,937 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { SfError } from '@salesforce/core';
+/**
+ * Error codes and utilities for Salesforce API adapter operations.
+ *
+ * This module provides standardized error codes for all adapter operations,
+ * utilities for extracting Salesforce error codes from various error formats,
+ * and human-readable descriptions for error messages.
+ *
+ * @module adapters/errors
+ *
+ * @example
+ * ```typescript
+ * import { AdapterErrorCodes, mapSalesforceError, extractSalesforceErrorCode } from './errors';
+ *
+ * try {
+ *   await connection.query('INVALID SOQL');
+ * } catch (error) {
+ *   const sfCode = extractSalesforceErrorCode(error);
+ *   const adapterCode = sfCode ? mapSalesforceError(sfCode, 'soql') : AdapterErrorCodes.QUERY_FAILED;
+ *   console.log(`Error: ${adapterCode}`); // E3102 for INVALID_QUERY
+ * }
+ * ```
+ */
+/**
+ * Adapter error codes for Salesforce API operations.
+ * Uses the 3000-3999 range as defined in CLAUDE.md error code ranges.
+ *
+ * Error Code Ranges:
+ * - E3000-E3099: Connection errors
+ * - E3100-E3199: SOQL query errors
+ * - E3200-E3299: REST API errors
+ * - E3300-E3399: Tooling API errors
+ * - E3400-E3499: (Reserved — formerly Apex execution errors)
+ */
+export const AdapterErrorCodes = {
+    // Connection Errors (E3000-E3099)
+    /** Connection is not authenticated or has expired */
+    CONNECTION_NOT_AUTHENTICATED: 'E3000',
+    /** Connection is missing required configuration */
+    CONNECTION_INVALID: 'E3001',
+    // SOQL Query Errors (E3100-E3199)
+    /** Generic SOQL query failure */
+    QUERY_FAILED: 'E3100',
+    /** Query execution timed out */
+    QUERY_TIMEOUT: 'E3101',
+    /** Invalid SOQL syntax */
+    INVALID_QUERY: 'E3102',
+    /** Query returned too many rows */
+    QUERY_TOO_MANY_ROWS: 'E3103',
+    // REST API Errors (E3200-E3299)
+    /** Generic REST API describe failure */
+    DESCRIBE_FAILED: 'E3200',
+    /** Object not found */
+    OBJECT_NOT_FOUND: 'E3201',
+    /** Insufficient permissions to access object */
+    PERMISSION_DENIED: 'E3202',
+    /** Global describe failed */
+    GLOBAL_DESCRIBE_FAILED: 'E3203',
+    /** Insert record operation failed */
+    INSERT_RECORD_FAILED: 'E3204',
+    /** Insufficient access to insert record */
+    INSERT_INSUFFICIENT_ACCESS: 'E3205',
+    /** Duplicate record detected during insert */
+    INSERT_DUPLICATE_VALUE: 'E3206',
+    // UPDATE operations (E3207-E3209)
+    /** Update record operation failed */
+    UPDATE_RECORD_FAILED: 'E3207',
+    /** Insufficient access to update record */
+    UPDATE_INSUFFICIENT_ACCESS: 'E3208',
+    /** Record not found for update */
+    UPDATE_RECORD_NOT_FOUND: 'E3209',
+    // DELETE operations (E3210-E3212)
+    /** Delete record operation failed */
+    DELETE_RECORD_FAILED: 'E3210',
+    /** Insufficient access to delete record */
+    DELETE_INSUFFICIENT_ACCESS: 'E3211',
+    /** Record not found for delete */
+    DELETE_RECORD_NOT_FOUND: 'E3212',
+    // Generic REST request operations (E3213-E3219)
+    /** Generic REST request failed */
+    REQUEST_FAILED: 'E3213',
+    // Namespace security guard violations (E3220-E3222)
+    /** Insert blocked: object must use pnova__ namespace or be in the explicit allowlist */
+    INSERT_NAMESPACE_VIOLATION: 'E3220',
+    /** Update blocked: object must use pnova__ namespace */
+    UPDATE_NAMESPACE_VIOLATION: 'E3221',
+    /** Delete blocked: object must use pnova__ namespace */
+    DELETE_NAMESPACE_VIOLATION: 'E3222',
+    // Tooling API Errors (E3300-E3399)
+    /** Generic Tooling API query failure */
+    TOOLING_QUERY_FAILED: 'E3300',
+    /** Metadata not found */
+    METADATA_NOT_FOUND: 'E3301',
+    /** Tooling API access denied */
+    TOOLING_ACCESS_DENIED: 'E3302',
+};
+/**
+ * Service error codes for domain service operations.
+ * Uses the 4000-4999 range as defined in CLAUDE.md error code ranges.
+ *
+ * Error Code Ranges:
+ * - E4001:       General pagination error
+ * - E4100-E4105: ObjectFilteringService
+ * - E4200-E4203: RecordTypeService
+ * - E4300-E4302: TabDetectionService
+ * - E4400-E4409: ProfilingDefinitionService
+ * - E4500-E4506: ProfilingSummaryService
+ * - E4600-E4610: OrgInfoService
+ * - E4650-E4658: UserReadinessService
+ * - E4660-E4676: UserConfigurationService (includes REST insert/endpoint errors E4671-E4676)
+ * - E4680-E4681: Feature Gate (access gate pre-check)
+ * - E4700-E4702: ContactPointService
+ * - E4750-E4761: ObjectListService
+ * - E4800-E4809: ObjectDescribeService
+ * - E4850-E4866: ProfilingExecutionService
+ * - E4900-E4909: ProfileRequestService
+ * - E4920-E4929: DataAvailabilityService
+ */
+export const ServiceErrorCodes = {
+    // General (E4001)
+    /** Invalid pagination parameters (limit, offset) */
+    INVALID_PAGINATION: 'E4001',
+    // ObjectFilteringService (E4100-E4105)
+    /** Generic filter operation failed */
+    FILTER_FAILED: 'E4100',
+    /** Invalid type parameter (must be 'standard', 'custom', or 'all') */
+    INVALID_TYPE: 'E4101',
+    /** Invalid namespace format */
+    INVALID_NAMESPACE: 'E4102',
+    /** Invalid name filter (value required, operator must be 'startsWith', 'contains', or 'equals') */
+    INVALID_NAME_FILTER: 'E4103',
+    /** Invalid classification (must be 'customer', 'internal', or 'all') */
+    INVALID_CLASSIFICATION: 'E4104',
+    /** Invalid objectNames array (required, non-empty, max 200 items) */
+    INVALID_OBJECT_NAMES: 'E4105',
+    // RecordTypeService (E4200-E4203)
+    /** Record type query failed */
+    RECORD_TYPE_QUERY_FAILED: 'E4200',
+    /** Object not found for record type query */
+    RECORD_TYPE_OBJECT_NOT_FOUND: 'E4201',
+    /** Object name is required */
+    RECORD_TYPE_OBJECT_NAME_REQUIRED: 'E4202',
+    /** Invalid object name format */
+    RECORD_TYPE_INVALID_OBJECT_NAME: 'E4203',
+    // TabDetectionService (E4300-E4302)
+    /** Tab query failed */
+    TAB_QUERY_FAILED: 'E4300',
+    /** Object name is required */
+    TAB_OBJECT_NAME_REQUIRED: 'E4301',
+    /** Invalid object names array (empty or exceeds max) */
+    TAB_INVALID_OBJECT_NAMES: 'E4302',
+    // ProfilingDefinitionService (E4400-E4409)
+    /** Definition query failed */
+    DEFINITION_QUERY_FAILED: 'E4400',
+    /** Definition not found */
+    DEFINITION_NOT_FOUND: 'E4401',
+    /** Definition create failed */
+    DEFINITION_CREATE_FAILED: 'E4402',
+    /** Definition update failed */
+    DEFINITION_UPDATE_FAILED: 'E4403',
+    /** Definition delete failed */
+    DEFINITION_DELETE_FAILED: 'E4404',
+    /** Invalid Salesforce ID format */
+    DEFINITION_INVALID_ID: 'E4405',
+    /** Invalid definition name (required, 1-80 chars) */
+    DEFINITION_INVALID_NAME: 'E4406',
+    /** Invalid object API name */
+    DEFINITION_INVALID_OBJECT_NAME: 'E4407',
+    /** Invalid category (max 255 chars) */
+    DEFINITION_INVALID_CATEGORY: 'E4408',
+    /** Update requires at least one field */
+    DEFINITION_UPDATE_EMPTY: 'E4409',
+    // ProfilingSummaryService (E4500-E4505)
+    /** Summary query failed */
+    SUMMARY_QUERY_FAILED: 'E4500',
+    /** Summary not found */
+    SUMMARY_NOT_FOUND: 'E4501',
+    /** Summary delete failed */
+    SUMMARY_DELETE_FAILED: 'E4502',
+    /** Invalid definition ID format (for getSummaries definitionId parameter) */
+    SUMMARY_INVALID_DEFINITION_ID: 'E4503',
+    /** Invalid summary IDs array (empty or exceeds max) */
+    SUMMARY_INVALID_IDS: 'E4504',
+    /** Invalid summary ID format (for getSummaryById id parameter) */
+    SUMMARY_INVALID_ID: 'E4505',
+    /** Profiled objects query failed */
+    PROFILED_OBJECTS_QUERY_FAILED: 'E4506',
+    // SummaryPurgeOperation (E4510-E4517)
+    /** No selection criteria specified for purge */
+    SUMMARY_PURGE_NO_SELECTION: 'E4510',
+    /** Mutually exclusive flags used (--ids with filters) */
+    SUMMARY_PURGE_MUTUALLY_EXCLUSIVE: 'E4511',
+    /** Summary purge query failed */
+    SUMMARY_PURGE_QUERY_FAILED: 'E4512',
+    /** No eligible summaries found */
+    SUMMARY_PURGE_NO_ELIGIBLE: 'E4513',
+    /** Summary purge delete failed */
+    SUMMARY_PURGE_DELETE_FAILED: 'E4514',
+    /** User cancelled purge operation */
+    SUMMARY_PURGE_USER_CANCELLED: 'E4515',
+    /** Unexpected operation failure */
+    SUMMARY_PURGE_OPERATION_FAILED: 'E4516',
+    /** Invalid summary IDs provided */
+    SUMMARY_PURGE_INVALID_IDS: 'E4517',
+    // SummaryStopOperation (E4520-E4527)
+    /** No selection criteria specified for stop */
+    SUMMARY_STOP_NO_SELECTION: 'E4520',
+    /** Mutually exclusive flags used for stop */
+    SUMMARY_STOP_MUTUALLY_EXCLUSIVE: 'E4521',
+    /** Summary stop query failed */
+    SUMMARY_STOP_QUERY_FAILED: 'E4522',
+    /** No stoppable summaries found */
+    SUMMARY_STOP_NO_ELIGIBLE: 'E4523',
+    /** Summary stop REST call failed */
+    SUMMARY_STOP_FAILED: 'E4524',
+    /** User cancelled stop operation */
+    SUMMARY_STOP_USER_CANCELLED: 'E4525',
+    /** Unexpected stop operation failure */
+    SUMMARY_STOP_OPERATION_FAILED: 'E4526',
+    /** Invalid summary IDs for stop */
+    SUMMARY_STOP_INVALID_IDS: 'E4527',
+    // SummaryReprofileOperation (E4530-E4537)
+    /** No selection criteria specified for reprofile */
+    SUMMARY_REPROFILE_NO_SELECTION: 'E4530',
+    /** Mutually exclusive flags used for reprofile */
+    SUMMARY_REPROFILE_MUTUALLY_EXCLUSIVE: 'E4531',
+    /** Summary reprofile query failed */
+    SUMMARY_REPROFILE_QUERY_FAILED: 'E4532',
+    /** No reprofilable summaries found */
+    SUMMARY_REPROFILE_NO_ELIGIBLE: 'E4533',
+    /** Summary reprofile REST call failed */
+    SUMMARY_REPROFILE_FAILED: 'E4534',
+    /** User cancelled reprofile operation */
+    SUMMARY_REPROFILE_USER_CANCELLED: 'E4535',
+    /** Unexpected reprofile operation failure */
+    SUMMARY_REPROFILE_OPERATION_FAILED: 'E4536',
+    /** Invalid summary IDs for reprofile */
+    SUMMARY_REPROFILE_INVALID_IDS: 'E4537',
+    // ContactPointService (E4700-E4702)
+    /** Contact point analysis failed */
+    CONTACT_POINT_ANALYSIS_FAILED: 'E4700',
+    /** Object name is required */
+    CONTACT_POINT_OBJECT_NAME_REQUIRED: 'E4701',
+    /** Invalid object name format */
+    CONTACT_POINT_INVALID_OBJECT_NAME: 'E4702',
+    // ObjectListService (E4750-E4761)
+    /** Object list query failed */
+    OBJECT_LIST_QUERY_FAILED: 'E4750',
+    /** Global describe failed during object list operation */
+    OBJECT_LIST_GLOBAL_DESCRIBE_FAILED: 'E4751',
+    /** Invalid pagination parameters for object list */
+    OBJECT_LIST_INVALID_PAGINATION: 'E4752',
+    /** Object list filter failed */
+    OBJECT_LIST_FILTER_FAILED: 'E4753',
+    /** Tab detection failed during enrichment */
+    OBJECT_LIST_TAB_DETECTION_FAILED: 'E4754',
+    /** Contact point analysis failed during enrichment */
+    OBJECT_LIST_CONTACT_POINT_FAILED: 'E4755',
+    /** Enrichment operation timed out */
+    OBJECT_LIST_ENRICHMENT_TIMEOUT: 'E4756',
+    /** Invalid sort field or direction */
+    OBJECT_LIST_INVALID_SORT: 'E4757',
+    /** Invalid filter type */
+    OBJECT_LIST_INVALID_FILTER_TYPE: 'E4758',
+    /** Invalid namespace in filter */
+    OBJECT_LIST_INVALID_NAMESPACE: 'E4759',
+    /** Failed to get record count */
+    OBJECT_LIST_RECORD_COUNT_FAILED: 'E4760',
+    /** Empty result set */
+    OBJECT_LIST_EMPTY_RESULT: 'E4761',
+    // OrgInfoService (E4600-E4609)
+    /** Org info query failed */
+    ORG_INFO_QUERY_FAILED: 'E4600',
+    /** Org identity failed */
+    ORG_IDENTITY_FAILED: 'E4601',
+    /** Org limits failed */
+    ORG_LIMITS_FAILED: 'E4602',
+    /** Org package query failed */
+    ORG_PACKAGE_QUERY_FAILED: 'E4603',
+    /** Org namespace query failed */
+    ORG_NAMESPACE_QUERY_FAILED: 'E4604',
+    /** Org user count failed */
+    ORG_USER_COUNT_FAILED: 'E4605',
+    /** Org Cuneiform version query failed */
+    ORG_CUNEIFORM_VERSION_FAILED: 'E4606',
+    /** Org features query failed */
+    ORG_FEATURES_QUERY_FAILED: 'E4607',
+    /** Org edition query failed */
+    ORG_EDITION_QUERY_FAILED: 'E4608',
+    /** Business process query failed */
+    ORG_BUSINESS_PROCESS_QUERY_FAILED: 'E4609',
+    // UserReadinessService (E4650-E4659)
+    /** User readiness query failed */
+    USER_READINESS_QUERY_FAILED: 'E4650',
+    /** User permission set check failed */
+    USER_PERMISSION_SET_CHECK_FAILED: 'E4651',
+    /** User config profile check failed */
+    USER_CONFIG_PROFILE_CHECK_FAILED: 'E4652',
+    /** User ID is required */
+    USER_ID_REQUIRED: 'E4653',
+    /** Cuneiform namespace not found (not installed) */
+    USER_CUNEIFORM_NAMESPACE_NOT_FOUND: 'E4654',
+    /** User info query failed */
+    USER_INFO_QUERY_FAILED: 'E4655',
+    /** User lacks required permission sets for profiling access */
+    PROFILING_ACCESS_DENIED: 'E4656',
+    /** Global Profiling is not enabled in the org */
+    GLOBAL_PROFILING_NOT_ENABLED: 'E4657',
+    /** Configure operation blocked in production environment */
+    ENVIRONMENT_CONFIGURE_BLOCKED: 'E4658',
+    /** CLI self-provisioning not enabled in Configuration Profile */
+    SELF_REGISTRATION_NOT_ENABLED: 'E4659',
+    // UserConfigurationService (E4660-E4676)
+    /** User ID is required for configuration query */
+    USER_CONFIG_USER_ID_REQUIRED: 'E4660',
+    /** User configuration query failed */
+    USER_CONFIG_QUERY_FAILED: 'E4661',
+    /** Invalid user configuration settings */
+    USER_CONFIG_INVALID_SETTINGS: 'E4662',
+    /** CMT deployment via REST endpoint failed */
+    USER_CONFIG_DEPLOY_TRIGGER_FAILED: 'E4663',
+    // E4664 — RESERVED (formerly USER_CONFIG_APEX_COMPILE_ERROR, removed with Apex adapter in CLI-772)
+    /** Background job query failed */
+    USER_CONFIG_JOB_QUERY_FAILED: 'E4665',
+    /** Permission set not found in org */
+    USER_CONFIG_PERMISSION_SET_NOT_FOUND: 'E4666',
+    /** Permission set assignment failed */
+    USER_CONFIG_PERMISSION_SET_ASSIGN_FAILED: 'E4667',
+    /** Insufficient access to assign permission sets */
+    USER_CONFIG_INSUFFICIENT_ACCESS: 'E4668',
+    /** Some configuration actions failed (partial failure) */
+    USER_CONFIG_PARTIAL_FAILURE: 'E4669',
+    /** Already configured, no changes needed */
+    USER_CONFIG_ALREADY_CONFIGURED: 'E4670',
+    /** sObject insert failed via REST API */
+    REST_INSERT_FAILED: 'E4671',
+    /** Insufficient access to insert record */
+    REST_INSERT_INSUFFICIENT_ACCESS: 'E4672',
+    /** Duplicate record detected during insert */
+    REST_INSERT_DUPLICATE: 'E4673',
+    /** Configuration REST endpoint not available (ISV version too old) */
+    USER_CONFIG_ENDPOINT_UNAVAILABLE: 'E4674',
+    /** Insufficient access to the configuration REST endpoint */
+    USER_CONFIG_ENDPOINT_INSUFFICIENT_ACCESS: 'E4675',
+    /** Configuration feature is not enabled in this org */
+    USER_CONFIG_FEATURE_NOT_ENABLED: 'E4676',
+    // Feature Gate (E4680-E4681)
+    /** API-Based Profiling feature is not enabled for this organization */
+    FEATURE_NOT_ENABLED: 'E4680',
+    /** Feature status endpoint check failed */
+    FEATURE_STATUS_CHECK_FAILED: 'E4681',
+    // ObjectDescribeService (E4800-E4809)
+    /** Object describe operation failed */
+    OBJECT_DESCRIBE_FAILED: 'E4800',
+    /** Object not found for describe operation */
+    OBJECT_DESCRIBE_NOT_FOUND: 'E4801',
+    /** Insufficient permissions to access object for describe operation */
+    OBJECT_DESCRIBE_PERMISSION_DENIED: 'E4802',
+    /** Object name is required for describe operation */
+    OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED: 'E4803',
+    /** Invalid object name format for describe operation */
+    OBJECT_DESCRIBE_INVALID_OBJECT_NAME: 'E4804',
+    /** Big Objects are not supported for describe operations */
+    OBJECT_DESCRIBE_BIG_OBJECT_REJECTED: 'E4805',
+    /** External Objects are not supported for describe operations */
+    OBJECT_DESCRIBE_EXTERNAL_OBJECT_REJECTED: 'E4806',
+    /** Record type enrichment failed during describe operation */
+    OBJECT_DESCRIBE_RECORD_TYPE_ENRICHMENT_FAILED: 'E4807',
+    /** Profiling definition enrichment failed during describe operation */
+    OBJECT_DESCRIBE_DEFINITION_ENRICHMENT_FAILED: 'E4808',
+    /** Profiling summary enrichment failed during describe operation */
+    OBJECT_DESCRIBE_SUMMARY_ENRICHMENT_FAILED: 'E4809',
+    // ProfilingExecutionService (E4850-E4866)
+    /** Generic profiling execution failed */
+    PROFILING_EXECUTION_FAILED: 'E4850',
+    /** Definition ID is required for profiling execution */
+    PROFILING_DEFINITION_ID_REQUIRED: 'E4851',
+    /** Invalid profiling definition ID format */
+    PROFILING_INVALID_DEFINITION_ID: 'E4852',
+    /** Profiling definition not found */
+    PROFILING_DEFINITION_NOT_FOUND: 'E4853',
+    /** REST API trigger for profiling failed */
+    PROFILING_REST_TRIGGER_FAILED: 'E4854',
+    /** Profiling request creation failed */
+    PROFILING_REQUEST_CREATION_FAILED: 'E4855',
+    /** Profiling status poll failed */
+    PROFILING_POLL_FAILED: 'E4856',
+    /** Profiling operation timed out */
+    PROFILING_TIMEOUT: 'E4857',
+    /** Profiling request not found */
+    PROFILING_REQUEST_NOT_FOUND: 'E4859',
+    /** Failed to extract profiling request ID */
+    PROFILING_REQUEST_ID_EXTRACTION_FAILED: 'E4861',
+    /** Bulk execution requires at least one definition */
+    PROFILING_BULK_EMPTY_DEFINITIONS: 'E4862',
+    /** Invalid parallel option for bulk execution */
+    PROFILING_BULK_INVALID_PARALLEL: 'E4863',
+    /** Bulk execution failed */
+    PROFILING_BULK_EXECUTION_FAILED: 'E4864',
+    /** Request ID is required */
+    PROFILING_REQUEST_ID_REQUIRED: 'E4865',
+    /** Invalid profiling request ID format */
+    PROFILING_INVALID_REQUEST_ID: 'E4866',
+    // ProfileRequestService (E4900-E4909)
+    /** Profile request list query failed */
+    REQUEST_LIST_QUERY_FAILED: 'E4900',
+    /** Profile request not found */
+    REQUEST_NOT_FOUND: 'E4901',
+    /** Profile request cancel failed */
+    REQUEST_CANCEL_FAILED: 'E4902',
+    /** Invalid request IDs provided */
+    REQUEST_INVALID_IDS: 'E4903',
+    /** No cancellable requests found */
+    REQUEST_NO_CANCELLABLE: 'E4904',
+    /** Request cancel partial failure */
+    REQUEST_CANCEL_PARTIAL_FAILURE: 'E4905',
+    /** Request delete failed */
+    REQUEST_DELETE_FAILED: 'E4906',
+    /** Request query failed (SOQL query for active requests) */
+    REQUEST_QUERY_FAILED: 'E4907',
+    /** No deletable requests found */
+    REQUEST_NO_DELETABLE: 'E4908',
+    /** Request delete partial failure */
+    REQUEST_DELETE_PARTIAL_FAILURE: 'E4909',
+    // DataAvailabilityService (E4920-E4929)
+    /** Data availability grid build failed */
+    DATA_AVAILABILITY_GRID_BUILD_FAILED: 'E4920',
+};
+/**
+ * Maps a Salesforce error code to a SOQL adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific error type:
+ * - INVALID/MALFORMED → INVALID_QUERY (E3102)
+ * - TIMEOUT/TIME_OUT → QUERY_TIMEOUT (E3101)
+ * - TOO_MANY → QUERY_TOO_MANY_ROWS (E3103)
+ * - Other → QUERY_FAILED (E3100)
+ *
+ * @param upperCode - The uppercased Salesforce error code to map
+ * @returns The corresponding adapter error code
+ */
+function mapSoqlError(upperCode) {
+    if (upperCode.includes('INVALID') || upperCode.includes('MALFORMED')) {
+        return AdapterErrorCodes.INVALID_QUERY;
+    }
+    if (upperCode.includes('TIMEOUT') || upperCode.includes('TIME_OUT')) {
+        return AdapterErrorCodes.QUERY_TIMEOUT;
+    }
+    if (upperCode.includes('TOO_MANY')) {
+        return AdapterErrorCodes.QUERY_TOO_MANY_ROWS;
+    }
+    return AdapterErrorCodes.QUERY_FAILED;
+}
+/**
+ * Maps a Salesforce error code to a REST API adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific error type:
+ * - NOT_FOUND/INVALID_TYPE → OBJECT_NOT_FOUND (E3201)
+ * - PERMISSION/INSUFFICIENT_ACCESS/NO_ACCESS → PERMISSION_DENIED (E3202)
+ * - Other → DESCRIBE_FAILED (E3200)
+ *
+ * @param upperCode - The uppercased Salesforce error code to map
+ * @returns The corresponding adapter error code
+ */
+function mapRestError(upperCode) {
+    if (upperCode.includes('NOT_FOUND') || upperCode.includes('INVALID_TYPE')) {
+        return AdapterErrorCodes.OBJECT_NOT_FOUND;
+    }
+    if (upperCode.includes('PERMISSION') ||
+        upperCode.includes('INSUFFICIENT_ACCESS') ||
+        upperCode.includes('NO_ACCESS')) {
+        return AdapterErrorCodes.PERMISSION_DENIED;
+    }
+    return AdapterErrorCodes.DESCRIBE_FAILED;
+}
+/**
+ * Maps a Salesforce error code to a Tooling API adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific error type:
+ * - NOT_FOUND → METADATA_NOT_FOUND (E3301)
+ * - PERMISSION/ACCESS → TOOLING_ACCESS_DENIED (E3302)
+ * - Other → TOOLING_QUERY_FAILED (E3300)
+ *
+ * @param upperCode - The uppercased Salesforce error code to map
+ * @returns The corresponding adapter error code
+ */
+function mapToolingError(upperCode) {
+    if (upperCode.includes('NOT_FOUND')) {
+        return AdapterErrorCodes.METADATA_NOT_FOUND;
+    }
+    if (upperCode.includes('PERMISSION') || upperCode.includes('ACCESS')) {
+        return AdapterErrorCodes.TOOLING_ACCESS_DENIED;
+    }
+    return AdapterErrorCodes.TOOLING_QUERY_FAILED;
+}
+/**
+ * Maps a Salesforce DML error code to an insert-specific adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific DML error type:
+ * - INSUFFICIENT_ACCESS/NO_ACCESS/PERMISSION → INSERT_INSUFFICIENT_ACCESS (E3205)
+ * - DUPLICATE_VALUE/ALREADY_EXISTS → INSERT_DUPLICATE_VALUE (E3206)
+ * - Other → INSERT_RECORD_FAILED (E3204)
+ *
+ * @param sfErrorCode - The Salesforce error code to map
+ * @returns The corresponding adapter error code for insert operations
+ *
+ * @example
+ * ```typescript
+ * const adapterCode = mapDmlInsertError('INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY');
+ * // Returns 'E3205' (INSERT_INSUFFICIENT_ACCESS)
+ * ```
+ */
+export function mapDmlInsertError(sfErrorCode) {
+    const upperCode = sfErrorCode.toUpperCase();
+    if (upperCode.includes('INSUFFICIENT_ACCESS') ||
+        upperCode.includes('NO_ACCESS') ||
+        upperCode.includes('PERMISSION')) {
+        return AdapterErrorCodes.INSERT_INSUFFICIENT_ACCESS;
+    }
+    if (upperCode.includes('DUPLICATE_VALUE') || upperCode.includes('ALREADY_EXISTS')) {
+        return AdapterErrorCodes.INSERT_DUPLICATE_VALUE;
+    }
+    return AdapterErrorCodes.INSERT_RECORD_FAILED;
+}
+/**
+ * Maps a Salesforce DML error code to an update-specific adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific DML error type:
+ * - INSUFFICIENT_ACCESS/NO_ACCESS/PERMISSION → UPDATE_INSUFFICIENT_ACCESS (E3208)
+ * - NOT_FOUND/INVALID_ID → UPDATE_RECORD_NOT_FOUND (E3209)
+ * - Other → UPDATE_RECORD_FAILED (E3207)
+ *
+ * @param sfErrorCode - The Salesforce error code to map
+ * @returns The corresponding adapter error code for update operations
+ *
+ * @example
+ * ```typescript
+ * const adapterCode = mapDmlUpdateError('INSUFFICIENT_ACCESS_OR_READONLY');
+ * // Returns 'E3208' (UPDATE_INSUFFICIENT_ACCESS)
+ * ```
+ */
+export function mapDmlUpdateError(sfErrorCode) {
+    const upperCode = sfErrorCode.toUpperCase();
+    if (upperCode.includes('INSUFFICIENT_ACCESS') ||
+        upperCode.includes('NO_ACCESS') ||
+        upperCode.includes('PERMISSION')) {
+        return AdapterErrorCodes.UPDATE_INSUFFICIENT_ACCESS;
+    }
+    if (upperCode.includes('NOT_FOUND') || upperCode.includes('INVALID_ID')) {
+        return AdapterErrorCodes.UPDATE_RECORD_NOT_FOUND;
+    }
+    return AdapterErrorCodes.UPDATE_RECORD_FAILED;
+}
+/**
+ * Maps a Salesforce DML error code to a delete-specific adapter error code.
+ *
+ * Checks for patterns in the error code to determine the specific DML error type:
+ * - INSUFFICIENT_ACCESS/NO_ACCESS/PERMISSION → DELETE_INSUFFICIENT_ACCESS (E3211)
+ * - NOT_FOUND/INVALID_ID/ENTITY_IS_DELETED → DELETE_RECORD_NOT_FOUND (E3212)
+ * - Other → DELETE_RECORD_FAILED (E3210)
+ *
+ * @param sfErrorCode - The Salesforce error code to map
+ * @returns The corresponding adapter error code for delete operations
+ *
+ * @example
+ * ```typescript
+ * const adapterCode = mapDmlDeleteError('ENTITY_IS_DELETED');
+ * // Returns 'E3212' (DELETE_RECORD_NOT_FOUND)
+ * ```
+ */
+export function mapDmlDeleteError(sfErrorCode) {
+    const upperCode = sfErrorCode.toUpperCase();
+    if (upperCode.includes('INSUFFICIENT_ACCESS') ||
+        upperCode.includes('NO_ACCESS') ||
+        upperCode.includes('PERMISSION')) {
+        return AdapterErrorCodes.DELETE_INSUFFICIENT_ACCESS;
+    }
+    if (upperCode.includes('NOT_FOUND') || upperCode.includes('INVALID_ID') || upperCode.includes('ENTITY_IS_DELETED')) {
+        return AdapterErrorCodes.DELETE_RECORD_NOT_FOUND;
+    }
+    return AdapterErrorCodes.DELETE_RECORD_FAILED;
+}
+/**
+ * Maps Salesforce error codes to adapter error codes.
+ *
+ * @param sfErrorCode - The Salesforce error code or error name
+ * @param category - The error category to use for mapping
+ * @returns The mapped adapter error code
+ *
+ * @example
+ * ```typescript
+ * const adapterCode = mapSalesforceError('INVALID_QUERY', 'soql');
+ * // Returns 'E3102'
+ * ```
+ */
+export function mapSalesforceError(sfErrorCode, category) {
+    const upperCode = sfErrorCode.toUpperCase();
+    switch (category) {
+        case 'soql':
+            return mapSoqlError(upperCode);
+        case 'rest':
+            return mapRestError(upperCode);
+        case 'tooling':
+            return mapToolingError(upperCode);
+    }
+}
+/**
+ * Error code description map for user-friendly messages.
+ * Includes both adapter and service error codes.
+ */
+export const ErrorCodeDescriptions = {
+    [AdapterErrorCodes.CONNECTION_NOT_AUTHENTICATED]: 'Connection is not authenticated or session has expired',
+    [AdapterErrorCodes.CONNECTION_INVALID]: 'Connection is missing required configuration',
+    [AdapterErrorCodes.QUERY_FAILED]: 'SOQL query execution failed',
+    [AdapterErrorCodes.QUERY_TIMEOUT]: 'SOQL query timed out',
+    [AdapterErrorCodes.INVALID_QUERY]: 'Invalid SOQL query syntax',
+    [AdapterErrorCodes.QUERY_TOO_MANY_ROWS]: 'Query returned more rows than the limit allows',
+    [AdapterErrorCodes.DESCRIBE_FAILED]: 'Failed to describe Salesforce object',
+    [AdapterErrorCodes.OBJECT_NOT_FOUND]: 'Salesforce object not found',
+    [AdapterErrorCodes.PERMISSION_DENIED]: 'Insufficient permissions to access this object',
+    [AdapterErrorCodes.GLOBAL_DESCRIBE_FAILED]: 'Failed to retrieve global object list',
+    [AdapterErrorCodes.INSERT_RECORD_FAILED]: 'Failed to insert sObject record',
+    [AdapterErrorCodes.INSERT_INSUFFICIENT_ACCESS]: 'Insufficient access to insert record',
+    [AdapterErrorCodes.INSERT_DUPLICATE_VALUE]: 'Duplicate record detected during insert',
+    [AdapterErrorCodes.UPDATE_RECORD_FAILED]: 'Failed to update sObject record',
+    [AdapterErrorCodes.UPDATE_INSUFFICIENT_ACCESS]: 'Insufficient access to update record',
+    [AdapterErrorCodes.UPDATE_RECORD_NOT_FOUND]: 'Record not found for update operation',
+    [AdapterErrorCodes.DELETE_RECORD_FAILED]: 'Failed to delete sObject record',
+    [AdapterErrorCodes.DELETE_INSUFFICIENT_ACCESS]: 'Insufficient access to delete record',
+    [AdapterErrorCodes.DELETE_RECORD_NOT_FOUND]: 'Record not found for delete operation',
+    [AdapterErrorCodes.REQUEST_FAILED]: 'Generic REST API request failed',
+    [AdapterErrorCodes.INSERT_NAMESPACE_VIOLATION]: 'Insert blocked: object must use pnova__ namespace or be in the explicit allowlist',
+    [AdapterErrorCodes.UPDATE_NAMESPACE_VIOLATION]: 'Update blocked: object must use pnova__ namespace',
+    [AdapterErrorCodes.DELETE_NAMESPACE_VIOLATION]: 'Delete blocked: object must use pnova__ namespace',
+    [AdapterErrorCodes.TOOLING_QUERY_FAILED]: 'Tooling API query failed',
+    [AdapterErrorCodes.METADATA_NOT_FOUND]: 'Metadata record not found',
+    [AdapterErrorCodes.TOOLING_ACCESS_DENIED]: 'Insufficient permissions for Tooling API access',
+    // Service Error Codes
+    [ServiceErrorCodes.INVALID_PAGINATION]: 'Invalid pagination parameters',
+    // ObjectFilteringService
+    [ServiceErrorCodes.FILTER_FAILED]: 'Object filter operation failed',
+    [ServiceErrorCodes.INVALID_TYPE]: "Invalid type parameter (must be 'standard', 'custom', or 'all')",
+    [ServiceErrorCodes.INVALID_NAMESPACE]: 'Invalid namespace format',
+    [ServiceErrorCodes.INVALID_NAME_FILTER]: "Invalid name filter (value required, operator must be 'startsWith', 'contains', or 'equals')",
+    [ServiceErrorCodes.INVALID_CLASSIFICATION]: "Invalid classification (must be 'customer', 'internal', or 'all')",
+    [ServiceErrorCodes.INVALID_OBJECT_NAMES]: 'Invalid objectNames array (required, non-empty, max 200 items)',
+    // RecordTypeService
+    [ServiceErrorCodes.RECORD_TYPE_QUERY_FAILED]: 'Record type query failed',
+    [ServiceErrorCodes.RECORD_TYPE_OBJECT_NOT_FOUND]: 'Object not found for record type query',
+    [ServiceErrorCodes.RECORD_TYPE_OBJECT_NAME_REQUIRED]: 'Object name is required',
+    [ServiceErrorCodes.RECORD_TYPE_INVALID_OBJECT_NAME]: 'Invalid object name format',
+    // TabDetectionService
+    [ServiceErrorCodes.TAB_QUERY_FAILED]: 'Tab query failed',
+    [ServiceErrorCodes.TAB_OBJECT_NAME_REQUIRED]: 'Object name is required',
+    [ServiceErrorCodes.TAB_INVALID_OBJECT_NAMES]: 'Invalid object names array (empty or exceeds max)',
+    // ProfilingDefinitionService
+    [ServiceErrorCodes.DEFINITION_QUERY_FAILED]: 'Definition query failed',
+    [ServiceErrorCodes.DEFINITION_NOT_FOUND]: 'Definition not found',
+    [ServiceErrorCodes.DEFINITION_CREATE_FAILED]: 'Definition create failed',
+    [ServiceErrorCodes.DEFINITION_UPDATE_FAILED]: 'Definition update failed',
+    [ServiceErrorCodes.DEFINITION_DELETE_FAILED]: 'Definition delete failed',
+    [ServiceErrorCodes.DEFINITION_INVALID_ID]: 'Invalid Salesforce ID format',
+    [ServiceErrorCodes.DEFINITION_INVALID_NAME]: 'Invalid definition name (required, 1-80 characters)',
+    [ServiceErrorCodes.DEFINITION_INVALID_OBJECT_NAME]: 'Invalid object API name',
+    [ServiceErrorCodes.DEFINITION_INVALID_CATEGORY]: 'Invalid category (max 255 characters)',
+    [ServiceErrorCodes.DEFINITION_UPDATE_EMPTY]: 'Update requires at least one field',
+    // ProfilingSummaryService
+    [ServiceErrorCodes.SUMMARY_QUERY_FAILED]: 'Summary query failed',
+    [ServiceErrorCodes.SUMMARY_NOT_FOUND]: 'Summary not found',
+    [ServiceErrorCodes.SUMMARY_DELETE_FAILED]: 'Summary delete failed',
+    [ServiceErrorCodes.SUMMARY_INVALID_DEFINITION_ID]: 'Invalid definition ID format',
+    [ServiceErrorCodes.SUMMARY_INVALID_IDS]: 'Invalid summary IDs array (empty or exceeds max)',
+    [ServiceErrorCodes.SUMMARY_INVALID_ID]: 'Invalid summary ID format',
+    [ServiceErrorCodes.PROFILED_OBJECTS_QUERY_FAILED]: 'Profiled objects query failed',
+    // SummaryPurgeOperation
+    [ServiceErrorCodes.SUMMARY_PURGE_NO_SELECTION]: 'No selection criteria specified for purge',
+    [ServiceErrorCodes.SUMMARY_PURGE_MUTUALLY_EXCLUSIVE]: 'Mutually exclusive flags: --ids cannot be combined with filter flags',
+    [ServiceErrorCodes.SUMMARY_PURGE_QUERY_FAILED]: 'Summary purge query failed',
+    [ServiceErrorCodes.SUMMARY_PURGE_NO_ELIGIBLE]: 'No eligible summaries found',
+    [ServiceErrorCodes.SUMMARY_PURGE_DELETE_FAILED]: 'Summary purge delete failed',
+    [ServiceErrorCodes.SUMMARY_PURGE_USER_CANCELLED]: 'Purge cancelled by user',
+    [ServiceErrorCodes.SUMMARY_PURGE_OPERATION_FAILED]: 'Summary purge operation failed',
+    [ServiceErrorCodes.SUMMARY_PURGE_INVALID_IDS]: 'Invalid summary IDs provided',
+    // SummaryStopOperation
+    [ServiceErrorCodes.SUMMARY_STOP_NO_SELECTION]: 'No selection criteria specified for stop',
+    [ServiceErrorCodes.SUMMARY_STOP_MUTUALLY_EXCLUSIVE]: 'Mutually exclusive flags: --ids cannot be combined with --all or --objects',
+    [ServiceErrorCodes.SUMMARY_STOP_QUERY_FAILED]: 'Summary stop query failed',
+    [ServiceErrorCodes.SUMMARY_STOP_NO_ELIGIBLE]: 'No stoppable summaries found',
+    [ServiceErrorCodes.SUMMARY_STOP_FAILED]: 'Summary stop REST call failed',
+    [ServiceErrorCodes.SUMMARY_STOP_USER_CANCELLED]: 'Stop cancelled by user',
+    [ServiceErrorCodes.SUMMARY_STOP_OPERATION_FAILED]: 'Summary stop operation failed',
+    [ServiceErrorCodes.SUMMARY_STOP_INVALID_IDS]: 'Invalid summary IDs for stop',
+    // SummaryReprofileOperation
+    [ServiceErrorCodes.SUMMARY_REPROFILE_NO_SELECTION]: 'No selection criteria specified for reprofile',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_MUTUALLY_EXCLUSIVE]: 'Mutually exclusive flags: --ids cannot be combined with --all or --objects',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_QUERY_FAILED]: 'Summary reprofile query failed',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_NO_ELIGIBLE]: 'No reprofilable summaries found',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_FAILED]: 'Summary reprofile REST call failed',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_USER_CANCELLED]: 'Reprofile cancelled by user',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_OPERATION_FAILED]: 'Summary reprofile operation failed',
+    [ServiceErrorCodes.SUMMARY_REPROFILE_INVALID_IDS]: 'Invalid summary IDs for reprofile',
+    // ContactPointService
+    [ServiceErrorCodes.CONTACT_POINT_ANALYSIS_FAILED]: 'Contact point analysis failed',
+    [ServiceErrorCodes.CONTACT_POINT_OBJECT_NAME_REQUIRED]: 'Object name is required',
+    [ServiceErrorCodes.CONTACT_POINT_INVALID_OBJECT_NAME]: 'Invalid object name format',
+    // ObjectListService
+    [ServiceErrorCodes.OBJECT_LIST_QUERY_FAILED]: 'Object list query failed',
+    [ServiceErrorCodes.OBJECT_LIST_GLOBAL_DESCRIBE_FAILED]: 'Global describe failed during object list operation',
+    [ServiceErrorCodes.OBJECT_LIST_INVALID_PAGINATION]: 'Invalid pagination parameters (limit, offset)',
+    [ServiceErrorCodes.OBJECT_LIST_FILTER_FAILED]: 'Object list filter operation failed',
+    [ServiceErrorCodes.OBJECT_LIST_TAB_DETECTION_FAILED]: 'Tab detection failed during enrichment',
+    [ServiceErrorCodes.OBJECT_LIST_CONTACT_POINT_FAILED]: 'Contact point analysis failed during enrichment',
+    [ServiceErrorCodes.OBJECT_LIST_ENRICHMENT_TIMEOUT]: 'Enrichment operation timed out',
+    [ServiceErrorCodes.OBJECT_LIST_INVALID_SORT]: "Invalid sort field or direction (must be 'name', 'label', or 'recordCount' and 'asc' or 'desc')",
+    [ServiceErrorCodes.OBJECT_LIST_INVALID_FILTER_TYPE]: "Invalid filter type (must be 'standard', 'custom', or 'all')",
+    [ServiceErrorCodes.OBJECT_LIST_INVALID_NAMESPACE]: 'Invalid namespace in filter',
+    [ServiceErrorCodes.OBJECT_LIST_RECORD_COUNT_FAILED]: 'Failed to get record count',
+    [ServiceErrorCodes.OBJECT_LIST_EMPTY_RESULT]: 'Empty result set',
+    // OrgInfoService
+    [ServiceErrorCodes.ORG_INFO_QUERY_FAILED]: 'Org info query failed',
+    [ServiceErrorCodes.ORG_IDENTITY_FAILED]: 'Failed to retrieve org identity',
+    [ServiceErrorCodes.ORG_LIMITS_FAILED]: 'Failed to retrieve org limits',
+    [ServiceErrorCodes.ORG_PACKAGE_QUERY_FAILED]: 'Failed to query installed packages',
+    [ServiceErrorCodes.ORG_NAMESPACE_QUERY_FAILED]: 'Failed to query org namespaces',
+    [ServiceErrorCodes.ORG_USER_COUNT_FAILED]: 'Failed to retrieve user count',
+    [ServiceErrorCodes.ORG_CUNEIFORM_VERSION_FAILED]: 'Failed to retrieve Cuneiform version',
+    [ServiceErrorCodes.ORG_FEATURES_QUERY_FAILED]: 'Failed to query org features',
+    [ServiceErrorCodes.ORG_EDITION_QUERY_FAILED]: 'Failed to query org edition',
+    [ServiceErrorCodes.ORG_BUSINESS_PROCESS_QUERY_FAILED]: 'Failed to query business processes',
+    // UserReadinessService
+    [ServiceErrorCodes.USER_READINESS_QUERY_FAILED]: 'User readiness query failed',
+    [ServiceErrorCodes.USER_PERMISSION_SET_CHECK_FAILED]: 'Failed to check user permission sets',
+    [ServiceErrorCodes.USER_CONFIG_PROFILE_CHECK_FAILED]: 'Failed to check user configuration profile',
+    [ServiceErrorCodes.USER_ID_REQUIRED]: 'User ID is required',
+    [ServiceErrorCodes.USER_CUNEIFORM_NAMESPACE_NOT_FOUND]: 'Cuneiform namespace not found (package not installed)',
+    [ServiceErrorCodes.USER_INFO_QUERY_FAILED]: 'User info query failed',
+    [ServiceErrorCodes.PROFILING_ACCESS_DENIED]: 'User lacks required permission sets for profiling access',
+    [ServiceErrorCodes.GLOBAL_PROFILING_NOT_ENABLED]: 'Global Profiling is not enabled in the org',
+    [ServiceErrorCodes.ENVIRONMENT_CONFIGURE_BLOCKED]: 'Configure operation blocked in production environment',
+    [ServiceErrorCodes.SELF_REGISTRATION_NOT_ENABLED]: 'CLI self-provisioning not enabled in Configuration Profile',
+    // UserConfigurationService
+    [ServiceErrorCodes.USER_CONFIG_USER_ID_REQUIRED]: 'User ID is required for configuration query',
+    [ServiceErrorCodes.USER_CONFIG_QUERY_FAILED]: 'User configuration query failed',
+    [ServiceErrorCodes.USER_CONFIG_INVALID_SETTINGS]: 'Invalid user configuration settings',
+    [ServiceErrorCodes.USER_CONFIG_DEPLOY_TRIGGER_FAILED]: 'CMT deployment via REST endpoint failed',
+    [ServiceErrorCodes.USER_CONFIG_JOB_QUERY_FAILED]: 'Background job query failed during configuration',
+    [ServiceErrorCodes.USER_CONFIG_PERMISSION_SET_NOT_FOUND]: 'Permission set not found in org',
+    [ServiceErrorCodes.USER_CONFIG_PERMISSION_SET_ASSIGN_FAILED]: 'Permission set assignment failed',
+    [ServiceErrorCodes.USER_CONFIG_INSUFFICIENT_ACCESS]: 'Insufficient access to assign permission sets',
+    [ServiceErrorCodes.USER_CONFIG_PARTIAL_FAILURE]: 'Some configuration actions failed (partial failure)',
+    [ServiceErrorCodes.USER_CONFIG_ALREADY_CONFIGURED]: 'Already configured, no changes needed',
+    [ServiceErrorCodes.REST_INSERT_FAILED]: 'sObject insert operation failed via REST API',
+    [ServiceErrorCodes.REST_INSERT_INSUFFICIENT_ACCESS]: 'Insufficient access to insert record',
+    [ServiceErrorCodes.REST_INSERT_DUPLICATE]: 'Duplicate record detected during insert',
+    [ServiceErrorCodes.USER_CONFIG_ENDPOINT_UNAVAILABLE]: 'Configuration REST endpoint not available — ISV upgrade required',
+    [ServiceErrorCodes.USER_CONFIG_ENDPOINT_INSUFFICIENT_ACCESS]: 'Insufficient access to the Cuneiform configuration REST endpoint',
+    [ServiceErrorCodes.USER_CONFIG_FEATURE_NOT_ENABLED]: 'Configuration feature is not enabled in this org',
+    // Feature Gate
+    [ServiceErrorCodes.FEATURE_NOT_ENABLED]: 'API-Based Profiling feature is not enabled for this organization',
+    [ServiceErrorCodes.FEATURE_STATUS_CHECK_FAILED]: 'Feature status endpoint check failed',
+    // ObjectDescribeService
+    [ServiceErrorCodes.OBJECT_DESCRIBE_FAILED]: 'Object describe operation failed',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_NOT_FOUND]: 'Object not found for describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_PERMISSION_DENIED]: 'Insufficient permissions to access object for describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED]: 'Object name is required for describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_INVALID_OBJECT_NAME]: 'Invalid object name format for describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_BIG_OBJECT_REJECTED]: 'Big Objects are not supported for describe operations',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_EXTERNAL_OBJECT_REJECTED]: 'External Objects are not supported for describe operations',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_RECORD_TYPE_ENRICHMENT_FAILED]: 'Record type enrichment failed during describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_DEFINITION_ENRICHMENT_FAILED]: 'Profiling definition enrichment failed during describe operation',
+    [ServiceErrorCodes.OBJECT_DESCRIBE_SUMMARY_ENRICHMENT_FAILED]: 'Profiling summary enrichment failed during describe operation',
+    // ProfilingExecutionService
+    [ServiceErrorCodes.PROFILING_EXECUTION_FAILED]: 'Profiling execution failed',
+    [ServiceErrorCodes.PROFILING_DEFINITION_ID_REQUIRED]: 'Definition ID is required for profiling execution',
+    [ServiceErrorCodes.PROFILING_INVALID_DEFINITION_ID]: 'Invalid profiling definition ID format',
+    [ServiceErrorCodes.PROFILING_DEFINITION_NOT_FOUND]: 'Profiling definition not found',
+    [ServiceErrorCodes.PROFILING_REST_TRIGGER_FAILED]: 'REST API trigger for profiling failed',
+    [ServiceErrorCodes.PROFILING_REQUEST_CREATION_FAILED]: 'Profiling request creation failed',
+    [ServiceErrorCodes.PROFILING_POLL_FAILED]: 'Profiling status poll failed',
+    [ServiceErrorCodes.PROFILING_TIMEOUT]: 'Profiling operation timed out',
+    [ServiceErrorCodes.PROFILING_REQUEST_NOT_FOUND]: 'Profiling request not found',
+    [ServiceErrorCodes.PROFILING_REQUEST_ID_EXTRACTION_FAILED]: 'Failed to extract profiling request ID',
+    [ServiceErrorCodes.PROFILING_BULK_EMPTY_DEFINITIONS]: 'Bulk execution requires at least one definition',
+    [ServiceErrorCodes.PROFILING_BULK_INVALID_PARALLEL]: 'Invalid parallel option for bulk execution (must be 1-10)',
+    [ServiceErrorCodes.PROFILING_BULK_EXECUTION_FAILED]: 'Bulk profiling execution failed',
+    [ServiceErrorCodes.PROFILING_REQUEST_ID_REQUIRED]: 'Request ID is required',
+    [ServiceErrorCodes.PROFILING_INVALID_REQUEST_ID]: 'Invalid profiling request ID format',
+    // ProfileRequestService
+    [ServiceErrorCodes.REQUEST_LIST_QUERY_FAILED]: 'Profile request list query failed',
+    [ServiceErrorCodes.REQUEST_NOT_FOUND]: 'Profile request not found',
+    [ServiceErrorCodes.REQUEST_CANCEL_FAILED]: 'Profile request cancel failed',
+    [ServiceErrorCodes.REQUEST_INVALID_IDS]: 'Invalid request IDs provided',
+    [ServiceErrorCodes.REQUEST_NO_CANCELLABLE]: 'No cancellable requests found',
+    [ServiceErrorCodes.REQUEST_CANCEL_PARTIAL_FAILURE]: 'Some requests failed to cancel (partial failure)',
+    [ServiceErrorCodes.REQUEST_DELETE_FAILED]: 'Profiling request deletion failed',
+    [ServiceErrorCodes.REQUEST_QUERY_FAILED]: 'Failed to query active profiling requests',
+    [ServiceErrorCodes.REQUEST_NO_DELETABLE]: 'No deletable requests found',
+    [ServiceErrorCodes.REQUEST_DELETE_PARTIAL_FAILURE]: 'Some requests failed to delete (partial failure)',
+    // DataAvailabilityService
+    [ServiceErrorCodes.DATA_AVAILABILITY_GRID_BUILD_FAILED]: 'Data availability grid build failed',
+};
+/**
+ * Extracts the Salesforce error code from an error object.
+ *
+ * This utility parses various error formats from jsforce and the Salesforce API
+ * to extract the underlying error code for proper error mapping.
+ *
+ * @param error - The error to extract from
+ * @returns The Salesforce error code or undefined
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await connection.query('INVALID SOQL');
+ * } catch (error) {
+ *   const sfErrorCode = extractSalesforceErrorCode(error);
+ *   // Returns 'INVALID_QUERY' or similar
+ * }
+ * ```
+ */
+export function extractSalesforceErrorCode(error) {
+    if (error && typeof error === 'object') {
+        const errorObj = error;
+        // Priority 1: jsforce error pattern (most specific)
+        if ('errorCode' in errorObj && typeof errorObj.errorCode === 'string') {
+            return errorObj.errorCode;
+        }
+        // Priority 2: API response error pattern (body.errorCode)
+        if ('body' in errorObj && typeof errorObj.body === 'object' && errorObj.body !== null) {
+            const body = errorObj.body;
+            if ('errorCode' in body && typeof body.errorCode === 'string') {
+                return body.errorCode;
+            }
+        }
+        // Priority 3: SfError pattern (name - but only if it looks like an error code)
+        if ('name' in errorObj && typeof errorObj.name === 'string') {
+            const name = errorObj.name;
+            // Only use name if it looks like a Salesforce error code (contains underscore or is all caps)
+            if (name.includes('_') || (name === name.toUpperCase() && name !== 'ERROR')) {
+                return name;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Regular expression for valid Salesforce API names.
+ * Salesforce object and field names must:
+ * - Start with a letter
+ * - Contain only letters, numbers, and underscores
+ * - Custom objects/fields may end with __c, __mdt, __e, __b, __x, __r, etc.
+ * - Namespaced names follow pattern: Namespace__ObjectName__c
+ *
+ * This pattern allows:
+ * - Standard objects: Account, Contact
+ * - Custom objects: Custom_Object__c
+ * - Namespaced objects: MyNamespace__Object__c
+ * - Custom metadata: Config__mdt
+ * - Platform events: Order_Event__e
+ * - Relationships: Account__r
+ */
+const SALESFORCE_API_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]*$/;
+/**
+ * Validates and sanitizes a Salesforce API name for use in SOQL queries.
+ *
+ * This function prevents SOQL injection by validating that the input
+ * matches the expected pattern for Salesforce API names.
+ *
+ * @param value - The value to sanitize (object name, field name, etc.)
+ * @returns The validated value
+ * @throws {SfError} InvalidApiName if the value contains invalid characters
+ *
+ * @example
+ * ```typescript
+ * sanitizeSoqlIdentifier('Account');           // Returns 'Account'
+ * sanitizeSoqlIdentifier('Custom_Object__c');  // Returns 'Custom_Object__c'
+ * sanitizeSoqlIdentifier("Account' OR '1'='1"); // Throws Error
+ * ```
+ */
+export function sanitizeSoqlIdentifier(value) {
+    if (!SALESFORCE_API_NAME_REGEX.test(value)) {
+        throw new SfError(`Invalid Salesforce API name: "${value}". ` +
+            'API names must start with a letter and contain only letters, numbers, and underscores.', 'InvalidApiName');
+    }
+    return value;
+}
+/**
+ * Escapes a string value for use in SOQL string literals.
+ *
+ * This function escapes single quotes and backslashes to prevent
+ * SOQL injection when the value must be used as a string literal.
+ *
+ * @param value - The string value to escape
+ * @returns The escaped string (without surrounding quotes)
+ *
+ * @example
+ * ```typescript
+ * escapeSoqlString("O'Brien");  // Returns "O\\'Brien"
+ * escapeSoqlString('Test\\Path'); // Returns 'Test\\\\Path'
+ * ```
+ */
+export function escapeSoqlString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/**
+ * Detects whether an error message indicates an org connectivity issue
+ * (unreachable org, expired session, HTML response instead of JSON, etc.).
+ *
+ * jsforce and the Salesforce REST API return HTML responses (login pages, error pages)
+ * when an org is unreachable, expired, or the session is invalid. These produce
+ * cryptic error messages like "HTTP response contains html content" that are
+ * unhelpful to CLI users.
+ *
+ * @param message - The error message string to check
+ * @returns true if the message indicates an org connectivity problem
+ */
+export function isOrgConnectivityError(message) {
+    if (!message)
+        return false;
+    const lower = message.toLowerCase();
+    return (lower.includes('html content') ||
+        lower.includes('html response') ||
+        lower.includes('enotfound') ||
+        lower.includes('econnrefused') ||
+        lower.includes('econnreset') ||
+        lower.includes('etimedout') ||
+        lower.includes('session expired') ||
+        lower.includes('invalid_session_id') ||
+        lower.includes('request_limit_exceeded'));
+}
+//# sourceMappingURL=errors.js.map