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

package/lib/adapters/errors.d.ts

@@ -0,0 +1,547 @@
+/**
+ * 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 declare const AdapterErrorCodes: {
+    /** Connection is not authenticated or has expired */
+    readonly CONNECTION_NOT_AUTHENTICATED: "E3000";
+    /** Connection is missing required configuration */
+    readonly CONNECTION_INVALID: "E3001";
+    /** Generic SOQL query failure */
+    readonly QUERY_FAILED: "E3100";
+    /** Query execution timed out */
+    readonly QUERY_TIMEOUT: "E3101";
+    /** Invalid SOQL syntax */
+    readonly INVALID_QUERY: "E3102";
+    /** Query returned too many rows */
+    readonly QUERY_TOO_MANY_ROWS: "E3103";
+    /** Generic REST API describe failure */
+    readonly DESCRIBE_FAILED: "E3200";
+    /** Object not found */
+    readonly OBJECT_NOT_FOUND: "E3201";
+    /** Insufficient permissions to access object */
+    readonly PERMISSION_DENIED: "E3202";
+    /** Global describe failed */
+    readonly GLOBAL_DESCRIBE_FAILED: "E3203";
+    /** Insert record operation failed */
+    readonly INSERT_RECORD_FAILED: "E3204";
+    /** Insufficient access to insert record */
+    readonly INSERT_INSUFFICIENT_ACCESS: "E3205";
+    /** Duplicate record detected during insert */
+    readonly INSERT_DUPLICATE_VALUE: "E3206";
+    /** Update record operation failed */
+    readonly UPDATE_RECORD_FAILED: "E3207";
+    /** Insufficient access to update record */
+    readonly UPDATE_INSUFFICIENT_ACCESS: "E3208";
+    /** Record not found for update */
+    readonly UPDATE_RECORD_NOT_FOUND: "E3209";
+    /** Delete record operation failed */
+    readonly DELETE_RECORD_FAILED: "E3210";
+    /** Insufficient access to delete record */
+    readonly DELETE_INSUFFICIENT_ACCESS: "E3211";
+    /** Record not found for delete */
+    readonly DELETE_RECORD_NOT_FOUND: "E3212";
+    /** Generic REST request failed */
+    readonly REQUEST_FAILED: "E3213";
+    /** Insert blocked: object must use pnova__ namespace or be in the explicit allowlist */
+    readonly INSERT_NAMESPACE_VIOLATION: "E3220";
+    /** Update blocked: object must use pnova__ namespace */
+    readonly UPDATE_NAMESPACE_VIOLATION: "E3221";
+    /** Delete blocked: object must use pnova__ namespace */
+    readonly DELETE_NAMESPACE_VIOLATION: "E3222";
+    /** Generic Tooling API query failure */
+    readonly TOOLING_QUERY_FAILED: "E3300";
+    /** Metadata not found */
+    readonly METADATA_NOT_FOUND: "E3301";
+    /** Tooling API access denied */
+    readonly 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 declare const ServiceErrorCodes: {
+    /** Invalid pagination parameters (limit, offset) */
+    readonly INVALID_PAGINATION: "E4001";
+    /** Generic filter operation failed */
+    readonly FILTER_FAILED: "E4100";
+    /** Invalid type parameter (must be 'standard', 'custom', or 'all') */
+    readonly INVALID_TYPE: "E4101";
+    /** Invalid namespace format */
+    readonly INVALID_NAMESPACE: "E4102";
+    /** Invalid name filter (value required, operator must be 'startsWith', 'contains', or 'equals') */
+    readonly INVALID_NAME_FILTER: "E4103";
+    /** Invalid classification (must be 'customer', 'internal', or 'all') */
+    readonly INVALID_CLASSIFICATION: "E4104";
+    /** Invalid objectNames array (required, non-empty, max 200 items) */
+    readonly INVALID_OBJECT_NAMES: "E4105";
+    /** Record type query failed */
+    readonly RECORD_TYPE_QUERY_FAILED: "E4200";
+    /** Object not found for record type query */
+    readonly RECORD_TYPE_OBJECT_NOT_FOUND: "E4201";
+    /** Object name is required */
+    readonly RECORD_TYPE_OBJECT_NAME_REQUIRED: "E4202";
+    /** Invalid object name format */
+    readonly RECORD_TYPE_INVALID_OBJECT_NAME: "E4203";
+    /** Tab query failed */
+    readonly TAB_QUERY_FAILED: "E4300";
+    /** Object name is required */
+    readonly TAB_OBJECT_NAME_REQUIRED: "E4301";
+    /** Invalid object names array (empty or exceeds max) */
+    readonly TAB_INVALID_OBJECT_NAMES: "E4302";
+    /** Definition query failed */
+    readonly DEFINITION_QUERY_FAILED: "E4400";
+    /** Definition not found */
+    readonly DEFINITION_NOT_FOUND: "E4401";
+    /** Definition create failed */
+    readonly DEFINITION_CREATE_FAILED: "E4402";
+    /** Definition update failed */
+    readonly DEFINITION_UPDATE_FAILED: "E4403";
+    /** Definition delete failed */
+    readonly DEFINITION_DELETE_FAILED: "E4404";
+    /** Invalid Salesforce ID format */
+    readonly DEFINITION_INVALID_ID: "E4405";
+    /** Invalid definition name (required, 1-80 chars) */
+    readonly DEFINITION_INVALID_NAME: "E4406";
+    /** Invalid object API name */
+    readonly DEFINITION_INVALID_OBJECT_NAME: "E4407";
+    /** Invalid category (max 255 chars) */
+    readonly DEFINITION_INVALID_CATEGORY: "E4408";
+    /** Update requires at least one field */
+    readonly DEFINITION_UPDATE_EMPTY: "E4409";
+    /** Summary query failed */
+    readonly SUMMARY_QUERY_FAILED: "E4500";
+    /** Summary not found */
+    readonly SUMMARY_NOT_FOUND: "E4501";
+    /** Summary delete failed */
+    readonly SUMMARY_DELETE_FAILED: "E4502";
+    /** Invalid definition ID format (for getSummaries definitionId parameter) */
+    readonly SUMMARY_INVALID_DEFINITION_ID: "E4503";
+    /** Invalid summary IDs array (empty or exceeds max) */
+    readonly SUMMARY_INVALID_IDS: "E4504";
+    /** Invalid summary ID format (for getSummaryById id parameter) */
+    readonly SUMMARY_INVALID_ID: "E4505";
+    /** Profiled objects query failed */
+    readonly PROFILED_OBJECTS_QUERY_FAILED: "E4506";
+    /** No selection criteria specified for purge */
+    readonly SUMMARY_PURGE_NO_SELECTION: "E4510";
+    /** Mutually exclusive flags used (--ids with filters) */
+    readonly SUMMARY_PURGE_MUTUALLY_EXCLUSIVE: "E4511";
+    /** Summary purge query failed */
+    readonly SUMMARY_PURGE_QUERY_FAILED: "E4512";
+    /** No eligible summaries found */
+    readonly SUMMARY_PURGE_NO_ELIGIBLE: "E4513";
+    /** Summary purge delete failed */
+    readonly SUMMARY_PURGE_DELETE_FAILED: "E4514";
+    /** User cancelled purge operation */
+    readonly SUMMARY_PURGE_USER_CANCELLED: "E4515";
+    /** Unexpected operation failure */
+    readonly SUMMARY_PURGE_OPERATION_FAILED: "E4516";
+    /** Invalid summary IDs provided */
+    readonly SUMMARY_PURGE_INVALID_IDS: "E4517";
+    /** No selection criteria specified for stop */
+    readonly SUMMARY_STOP_NO_SELECTION: "E4520";
+    /** Mutually exclusive flags used for stop */
+    readonly SUMMARY_STOP_MUTUALLY_EXCLUSIVE: "E4521";
+    /** Summary stop query failed */
+    readonly SUMMARY_STOP_QUERY_FAILED: "E4522";
+    /** No stoppable summaries found */
+    readonly SUMMARY_STOP_NO_ELIGIBLE: "E4523";
+    /** Summary stop REST call failed */
+    readonly SUMMARY_STOP_FAILED: "E4524";
+    /** User cancelled stop operation */
+    readonly SUMMARY_STOP_USER_CANCELLED: "E4525";
+    /** Unexpected stop operation failure */
+    readonly SUMMARY_STOP_OPERATION_FAILED: "E4526";
+    /** Invalid summary IDs for stop */
+    readonly SUMMARY_STOP_INVALID_IDS: "E4527";
+    /** No selection criteria specified for reprofile */
+    readonly SUMMARY_REPROFILE_NO_SELECTION: "E4530";
+    /** Mutually exclusive flags used for reprofile */
+    readonly SUMMARY_REPROFILE_MUTUALLY_EXCLUSIVE: "E4531";
+    /** Summary reprofile query failed */
+    readonly SUMMARY_REPROFILE_QUERY_FAILED: "E4532";
+    /** No reprofilable summaries found */
+    readonly SUMMARY_REPROFILE_NO_ELIGIBLE: "E4533";
+    /** Summary reprofile REST call failed */
+    readonly SUMMARY_REPROFILE_FAILED: "E4534";
+    /** User cancelled reprofile operation */
+    readonly SUMMARY_REPROFILE_USER_CANCELLED: "E4535";
+    /** Unexpected reprofile operation failure */
+    readonly SUMMARY_REPROFILE_OPERATION_FAILED: "E4536";
+    /** Invalid summary IDs for reprofile */
+    readonly SUMMARY_REPROFILE_INVALID_IDS: "E4537";
+    /** Contact point analysis failed */
+    readonly CONTACT_POINT_ANALYSIS_FAILED: "E4700";
+    /** Object name is required */
+    readonly CONTACT_POINT_OBJECT_NAME_REQUIRED: "E4701";
+    /** Invalid object name format */
+    readonly CONTACT_POINT_INVALID_OBJECT_NAME: "E4702";
+    /** Object list query failed */
+    readonly OBJECT_LIST_QUERY_FAILED: "E4750";
+    /** Global describe failed during object list operation */
+    readonly OBJECT_LIST_GLOBAL_DESCRIBE_FAILED: "E4751";
+    /** Invalid pagination parameters for object list */
+    readonly OBJECT_LIST_INVALID_PAGINATION: "E4752";
+    /** Object list filter failed */
+    readonly OBJECT_LIST_FILTER_FAILED: "E4753";
+    /** Tab detection failed during enrichment */
+    readonly OBJECT_LIST_TAB_DETECTION_FAILED: "E4754";
+    /** Contact point analysis failed during enrichment */
+    readonly OBJECT_LIST_CONTACT_POINT_FAILED: "E4755";
+    /** Enrichment operation timed out */
+    readonly OBJECT_LIST_ENRICHMENT_TIMEOUT: "E4756";
+    /** Invalid sort field or direction */
+    readonly OBJECT_LIST_INVALID_SORT: "E4757";
+    /** Invalid filter type */
+    readonly OBJECT_LIST_INVALID_FILTER_TYPE: "E4758";
+    /** Invalid namespace in filter */
+    readonly OBJECT_LIST_INVALID_NAMESPACE: "E4759";
+    /** Failed to get record count */
+    readonly OBJECT_LIST_RECORD_COUNT_FAILED: "E4760";
+    /** Empty result set */
+    readonly OBJECT_LIST_EMPTY_RESULT: "E4761";
+    /** Org info query failed */
+    readonly ORG_INFO_QUERY_FAILED: "E4600";
+    /** Org identity failed */
+    readonly ORG_IDENTITY_FAILED: "E4601";
+    /** Org limits failed */
+    readonly ORG_LIMITS_FAILED: "E4602";
+    /** Org package query failed */
+    readonly ORG_PACKAGE_QUERY_FAILED: "E4603";
+    /** Org namespace query failed */
+    readonly ORG_NAMESPACE_QUERY_FAILED: "E4604";
+    /** Org user count failed */
+    readonly ORG_USER_COUNT_FAILED: "E4605";
+    /** Org Cuneiform version query failed */
+    readonly ORG_CUNEIFORM_VERSION_FAILED: "E4606";
+    /** Org features query failed */
+    readonly ORG_FEATURES_QUERY_FAILED: "E4607";
+    /** Org edition query failed */
+    readonly ORG_EDITION_QUERY_FAILED: "E4608";
+    /** Business process query failed */
+    readonly ORG_BUSINESS_PROCESS_QUERY_FAILED: "E4609";
+    /** User readiness query failed */
+    readonly USER_READINESS_QUERY_FAILED: "E4650";
+    /** User permission set check failed */
+    readonly USER_PERMISSION_SET_CHECK_FAILED: "E4651";
+    /** User config profile check failed */
+    readonly USER_CONFIG_PROFILE_CHECK_FAILED: "E4652";
+    /** User ID is required */
+    readonly USER_ID_REQUIRED: "E4653";
+    /** Cuneiform namespace not found (not installed) */
+    readonly USER_CUNEIFORM_NAMESPACE_NOT_FOUND: "E4654";
+    /** User info query failed */
+    readonly USER_INFO_QUERY_FAILED: "E4655";
+    /** User lacks required permission sets for profiling access */
+    readonly PROFILING_ACCESS_DENIED: "E4656";
+    /** Global Profiling is not enabled in the org */
+    readonly GLOBAL_PROFILING_NOT_ENABLED: "E4657";
+    /** Configure operation blocked in production environment */
+    readonly ENVIRONMENT_CONFIGURE_BLOCKED: "E4658";
+    /** CLI self-provisioning not enabled in Configuration Profile */
+    readonly SELF_REGISTRATION_NOT_ENABLED: "E4659";
+    /** User ID is required for configuration query */
+    readonly USER_CONFIG_USER_ID_REQUIRED: "E4660";
+    /** User configuration query failed */
+    readonly USER_CONFIG_QUERY_FAILED: "E4661";
+    /** Invalid user configuration settings */
+    readonly USER_CONFIG_INVALID_SETTINGS: "E4662";
+    /** CMT deployment via REST endpoint failed */
+    readonly USER_CONFIG_DEPLOY_TRIGGER_FAILED: "E4663";
+    /** Background job query failed */
+    readonly USER_CONFIG_JOB_QUERY_FAILED: "E4665";
+    /** Permission set not found in org */
+    readonly USER_CONFIG_PERMISSION_SET_NOT_FOUND: "E4666";
+    /** Permission set assignment failed */
+    readonly USER_CONFIG_PERMISSION_SET_ASSIGN_FAILED: "E4667";
+    /** Insufficient access to assign permission sets */
+    readonly USER_CONFIG_INSUFFICIENT_ACCESS: "E4668";
+    /** Some configuration actions failed (partial failure) */
+    readonly USER_CONFIG_PARTIAL_FAILURE: "E4669";
+    /** Already configured, no changes needed */
+    readonly USER_CONFIG_ALREADY_CONFIGURED: "E4670";
+    /** sObject insert failed via REST API */
+    readonly REST_INSERT_FAILED: "E4671";
+    /** Insufficient access to insert record */
+    readonly REST_INSERT_INSUFFICIENT_ACCESS: "E4672";
+    /** Duplicate record detected during insert */
+    readonly REST_INSERT_DUPLICATE: "E4673";
+    /** Configuration REST endpoint not available (ISV version too old) */
+    readonly USER_CONFIG_ENDPOINT_UNAVAILABLE: "E4674";
+    /** Insufficient access to the configuration REST endpoint */
+    readonly USER_CONFIG_ENDPOINT_INSUFFICIENT_ACCESS: "E4675";
+    /** Configuration feature is not enabled in this org */
+    readonly USER_CONFIG_FEATURE_NOT_ENABLED: "E4676";
+    /** API-Based Profiling feature is not enabled for this organization */
+    readonly FEATURE_NOT_ENABLED: "E4680";
+    /** Feature status endpoint check failed */
+    readonly FEATURE_STATUS_CHECK_FAILED: "E4681";
+    /** Object describe operation failed */
+    readonly OBJECT_DESCRIBE_FAILED: "E4800";
+    /** Object not found for describe operation */
+    readonly OBJECT_DESCRIBE_NOT_FOUND: "E4801";
+    /** Insufficient permissions to access object for describe operation */
+    readonly OBJECT_DESCRIBE_PERMISSION_DENIED: "E4802";
+    /** Object name is required for describe operation */
+    readonly OBJECT_DESCRIBE_OBJECT_NAME_REQUIRED: "E4803";
+    /** Invalid object name format for describe operation */
+    readonly OBJECT_DESCRIBE_INVALID_OBJECT_NAME: "E4804";
+    /** Big Objects are not supported for describe operations */
+    readonly OBJECT_DESCRIBE_BIG_OBJECT_REJECTED: "E4805";
+    /** External Objects are not supported for describe operations */
+    readonly OBJECT_DESCRIBE_EXTERNAL_OBJECT_REJECTED: "E4806";
+    /** Record type enrichment failed during describe operation */
+    readonly OBJECT_DESCRIBE_RECORD_TYPE_ENRICHMENT_FAILED: "E4807";
+    /** Profiling definition enrichment failed during describe operation */
+    readonly OBJECT_DESCRIBE_DEFINITION_ENRICHMENT_FAILED: "E4808";
+    /** Profiling summary enrichment failed during describe operation */
+    readonly OBJECT_DESCRIBE_SUMMARY_ENRICHMENT_FAILED: "E4809";
+    /** Generic profiling execution failed */
+    readonly PROFILING_EXECUTION_FAILED: "E4850";
+    /** Definition ID is required for profiling execution */
+    readonly PROFILING_DEFINITION_ID_REQUIRED: "E4851";
+    /** Invalid profiling definition ID format */
+    readonly PROFILING_INVALID_DEFINITION_ID: "E4852";
+    /** Profiling definition not found */
+    readonly PROFILING_DEFINITION_NOT_FOUND: "E4853";
+    /** REST API trigger for profiling failed */
+    readonly PROFILING_REST_TRIGGER_FAILED: "E4854";
+    /** Profiling request creation failed */
+    readonly PROFILING_REQUEST_CREATION_FAILED: "E4855";
+    /** Profiling status poll failed */
+    readonly PROFILING_POLL_FAILED: "E4856";
+    /** Profiling operation timed out */
+    readonly PROFILING_TIMEOUT: "E4857";
+    /** Profiling request not found */
+    readonly PROFILING_REQUEST_NOT_FOUND: "E4859";
+    /** Failed to extract profiling request ID */
+    readonly PROFILING_REQUEST_ID_EXTRACTION_FAILED: "E4861";
+    /** Bulk execution requires at least one definition */
+    readonly PROFILING_BULK_EMPTY_DEFINITIONS: "E4862";
+    /** Invalid parallel option for bulk execution */
+    readonly PROFILING_BULK_INVALID_PARALLEL: "E4863";
+    /** Bulk execution failed */
+    readonly PROFILING_BULK_EXECUTION_FAILED: "E4864";
+    /** Request ID is required */
+    readonly PROFILING_REQUEST_ID_REQUIRED: "E4865";
+    /** Invalid profiling request ID format */
+    readonly PROFILING_INVALID_REQUEST_ID: "E4866";
+    /** Profile request list query failed */
+    readonly REQUEST_LIST_QUERY_FAILED: "E4900";
+    /** Profile request not found */
+    readonly REQUEST_NOT_FOUND: "E4901";
+    /** Profile request cancel failed */
+    readonly REQUEST_CANCEL_FAILED: "E4902";
+    /** Invalid request IDs provided */
+    readonly REQUEST_INVALID_IDS: "E4903";
+    /** No cancellable requests found */
+    readonly REQUEST_NO_CANCELLABLE: "E4904";
+    /** Request cancel partial failure */
+    readonly REQUEST_CANCEL_PARTIAL_FAILURE: "E4905";
+    /** Request delete failed */
+    readonly REQUEST_DELETE_FAILED: "E4906";
+    /** Request query failed (SOQL query for active requests) */
+    readonly REQUEST_QUERY_FAILED: "E4907";
+    /** No deletable requests found */
+    readonly REQUEST_NO_DELETABLE: "E4908";
+    /** Request delete partial failure */
+    readonly REQUEST_DELETE_PARTIAL_FAILURE: "E4909";
+    /** Data availability grid build failed */
+    readonly DATA_AVAILABILITY_GRID_BUILD_FAILED: "E4920";
+};
+/**
+ * Type for service error code values.
+ */
+export type ServiceErrorCode = (typeof ServiceErrorCodes)[keyof typeof ServiceErrorCodes];
+/**
+ * Type for adapter error code values.
+ */
+export type AdapterErrorCode = (typeof AdapterErrorCodes)[keyof typeof AdapterErrorCodes];
+/**
+ * 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 declare function mapDmlInsertError(sfErrorCode: string): AdapterErrorCode;
+/**
+ * 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 declare function mapDmlUpdateError(sfErrorCode: string): AdapterErrorCode;
+/**
+ * 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 declare function mapDmlDeleteError(sfErrorCode: string): AdapterErrorCode;
+/**
+ * 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 declare function mapSalesforceError(sfErrorCode: string, category: 'soql' | 'rest' | 'tooling'): AdapterErrorCode;
+/**
+ * Error code description map for user-friendly messages.
+ * Includes both adapter and service error codes.
+ */
+export declare const ErrorCodeDescriptions: Record<AdapterErrorCode | ServiceErrorCode, string>;
+/**
+ * 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 declare function extractSalesforceErrorCode(error: unknown): string | undefined;
+/**
+ * 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 declare function sanitizeSoqlIdentifier(value: string): string;
+/**
+ * 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 declare function escapeSoqlString(value: string): string;
+/**
+ * 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 declare function isOrgConnectivityError(message: string): boolean;