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

package/lib/adapters/rest/rest-api-adapter.js

@@ -0,0 +1,764 @@
+/*
+ * 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 { createSuccessResult, createFailureResult, createEmptyFailureResult } from '../../models/service-result.js';
+import { CUNEIFORM_NAMESPACE_PREFIX } from '../../constants/namespace-constants.js';
+import { AdapterErrorCodes, mapSalesforceError, mapDmlInsertError, mapDmlUpdateError, mapDmlDeleteError, extractSalesforceErrorCode, sanitizeSoqlIdentifier, } from '../errors.js';
+import { createLifecycleEmitter } from '../lifecycle.js';
+import { withRetry } from '../retry.js';
+import { getCacheTtl, warnApiVersion } from '../types.js';
+import { CuneiformQueryBuilder } from '../soql/cuneiform-query-builder.js';
+import { LruCache } from './cache.js';
+/**
+ * Standard objects allowed for specific write operations.
+ * Maps object names to the set of permitted operations.
+ * These are objects that services legitimately need to write to
+ * that don't use the pnova__ namespace prefix.
+ *
+ * - PermissionSetAssignment: insert (configure) + delete (unconfigure)
+ */
+const WRITE_ALLOWLIST = new Map([
+    ['PermissionSetAssignment', new Set(['insert', 'delete'])],
+]);
+/**
+ * Cache key prefixes for different operation types.
+ */
+const CACHE_KEYS = {
+    DESCRIBE: 'describe:',
+    GLOBAL: 'global',
+    COUNT: 'count:',
+};
+/**
+ * Adapter for REST API operations against Salesforce.
+ *
+ * Provides caching for describe operations to reduce API calls.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new RestApiAdapter(connectionFacade);
+ *
+ * // Describe an object (cached)
+ * const result = await adapter.describeObject('Account');
+ *
+ * // Get global describe (cached)
+ * const global = await adapter.describeGlobal();
+ *
+ * // Describe multiple objects
+ * const describes = await adapter.describeObjects(['Account', 'Contact', 'Opportunity']);
+ *
+ * // Invalidate cache
+ * adapter.invalidateCache('describe:Account');  // Single object
+ * adapter.invalidateCache('describe:*');         // All describes
+ * adapter.invalidateCache();                     // Everything
+ * ```
+ */
+export class RestApiAdapter {
+    connection;
+    logger;
+    cache;
+    cacheEnabled;
+    lifecycle;
+    retryConfig;
+    recordCountBatchSize;
+    /**
+     * Creates a new RestApiAdapter.
+     *
+     * @param connection - The connection facade to use for API calls
+     * @param config - Optional configuration
+     */
+    constructor(connection, config) {
+        this.connection = connection;
+        this.logger = config?.logger;
+        this.cacheEnabled = config?.cacheEnabled ?? true;
+        this.lifecycle = createLifecycleEmitter('describe', config?.emitLifecycleEvents ?? false);
+        this.retryConfig = config?.retry;
+        // CLI-1744: Raised default from 10 → 25 to reduce sequential batch count in the SOQL fallback path
+        this.recordCountBatchSize = Math.min(Math.max(config?.recordCountBatchSize ?? 25, 1), 50);
+        const ttl = getCacheTtl(config?.cacheTtl);
+        this.cache = new LruCache(100, ttl);
+        // Warn if API version is below recommended minimum
+        warnApiVersion(connection.version, 'RestApiAdapter', this.logger);
+    }
+    /**
+     * Validates that a write operation targets a permitted object.
+     *
+     * Only objects with the pnova__ namespace prefix are allowed for all write operations.
+     * A small set of standard objects (WRITE_ALLOWLIST) are allowed for specific operations.
+     *
+     * @param objectName - The API name of the target object
+     * @param operation - The write operation type
+     * @returns undefined if allowed, or an error code and message if blocked
+     */
+    static validateWriteNamespace(objectName, operation) {
+        if (objectName.startsWith(CUNEIFORM_NAMESPACE_PREFIX)) {
+            return undefined;
+        }
+        const allowedOps = WRITE_ALLOWLIST.get(objectName);
+        if (allowedOps?.has(operation)) {
+            return undefined;
+        }
+        const errorCodeMap = {
+            insert: AdapterErrorCodes.INSERT_NAMESPACE_VIOLATION,
+            update: AdapterErrorCodes.UPDATE_NAMESPACE_VIOLATION,
+            delete: AdapterErrorCodes.DELETE_NAMESPACE_VIOLATION,
+        };
+        const errorCode = errorCodeMap[operation];
+        const operationLabel = operation.charAt(0).toUpperCase() + operation.slice(1);
+        // Show allowlist hint for operations that have allowlisted objects
+        const hasAllowlistEntries = [...WRITE_ALLOWLIST.values()].some((ops) => ops.has(operation));
+        return {
+            errorCode,
+            message: `${operationLabel} blocked: object '${objectName}' must use the ${CUNEIFORM_NAMESPACE_PREFIX} namespace` +
+                (hasAllowlistEntries ? ' or be in the explicit allowlist' : ''),
+        };
+    }
+    /**
+     * Describes a single Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the describe result
+     */
+    async describeObject(objectName) {
+        const startTime = Date.now();
+        const cacheKey = `${CACHE_KEYS.DESCRIBE}${objectName}`;
+        const emptyResult = {
+            name: objectName,
+            label: '',
+            labelPlural: '',
+            custom: false,
+            createable: false,
+            updateable: false,
+            deletable: false,
+            queryable: false,
+            searchable: false,
+            fields: [],
+        };
+        try {
+            // Check cache first
+            if (this.cacheEnabled) {
+                const cached = this.cache.get(cacheKey);
+                if (cached) {
+                    this.logger?.log(`Cache hit for describe: ${objectName}`);
+                    return createSuccessResult(cached, {
+                        message: `Describe result for ${objectName} (cached)`,
+                        metadata: { duration: Date.now() - startTime, cached: true },
+                    });
+                }
+            }
+            this.logger?.log(`Describing object: ${objectName}`);
+            await this.lifecycle.start('describeObject', { objectName });
+            const executeDescribe = () => this.connection.sobject(objectName).describe();
+            const result = this.retryConfig ? await withRetry(executeDescribe, this.retryConfig) : await executeDescribe();
+            const duration = Date.now() - startTime;
+            // Cache the result
+            if (this.cacheEnabled) {
+                this.cache.set(cacheKey, result);
+            }
+            this.logger?.log(`Describe complete for ${objectName}: ${result.fields.length} fields`);
+            await this.lifecycle.complete('describeObject', startTime, { objectName, fieldCount: result.fields.length });
+            return createSuccessResult(result, {
+                message: `Describe result for ${objectName}`,
+                metadata: { duration, cached: false },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('describeObject', startTime, errorMessage, { objectName });
+            return this.handleError(error, startTime, emptyResult, objectName);
+        }
+    }
+    /**
+     * Retrieves global describe information for all accessible objects.
+     *
+     * @returns ServiceResult containing the global describe result
+     */
+    async describeGlobal() {
+        const startTime = Date.now();
+        const cacheKey = CACHE_KEYS.GLOBAL;
+        const emptyResult = { maxBatchSize: 0, sobjects: [] };
+        try {
+            // Check cache first
+            if (this.cacheEnabled) {
+                const cached = this.cache.get(cacheKey);
+                if (cached) {
+                    this.logger?.log('Cache hit for global describe');
+                    return createSuccessResult(cached, {
+                        message: `Global describe result (cached): ${cached.sobjects.length} objects`,
+                        metadata: { duration: Date.now() - startTime, cached: true },
+                    });
+                }
+            }
+            this.logger?.log('Executing global describe');
+            await this.lifecycle.start('describeGlobal', {});
+            const executeGlobal = () => this.connection.request('/sobjects');
+            const result = this.retryConfig ? await withRetry(executeGlobal, this.retryConfig) : await executeGlobal();
+            const duration = Date.now() - startTime;
+            // Cache the result
+            if (this.cacheEnabled) {
+                this.cache.set(cacheKey, result);
+            }
+            this.logger?.log(`Global describe complete: ${result.sobjects.length} objects`);
+            await this.lifecycle.complete('describeGlobal', startTime, { objectCount: result.sobjects.length });
+            return createSuccessResult(result, {
+                message: `Global describe result: ${result.sobjects.length} objects`,
+                metadata: { duration, cached: false },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('describeGlobal', startTime, errorMessage);
+            return this.handleError(error, startTime, emptyResult, 'global describe', AdapterErrorCodes.GLOBAL_DESCRIBE_FAILED);
+        }
+    }
+    /**
+     * Gets the record count for a Salesforce object.
+     *
+     * @param objectName - The API name of the object
+     * @returns ServiceResult containing the record count
+     */
+    async getRecordCount(objectName) {
+        const startTime = Date.now();
+        const cacheKey = `${CACHE_KEYS.COUNT}${objectName}`;
+        try {
+            // Check cache first
+            if (this.cacheEnabled) {
+                const cached = this.cache.get(cacheKey);
+                if (cached !== undefined) {
+                    this.logger?.log(`Cache hit for record count: ${objectName}`);
+                    return createSuccessResult(cached, {
+                        message: `Record count for ${objectName}: ${cached} (cached)`,
+                        metadata: { duration: Date.now() - startTime, cached: true },
+                    });
+                }
+            }
+            this.logger?.log(`Getting record count for: ${objectName}`);
+            // Sanitize objectName to prevent SOQL injection (validates API name format)
+            const sanitizedObjectName = sanitizeSoqlIdentifier(objectName);
+            // Build COUNT() query using CuneiformQueryBuilder for type-safe SOQL generation.
+            // SELECT COUNT() returns the count in totalSize, not as a record field.
+            // This is more efficient than SELECT COUNT(Id) which returns records.
+            const countQuery = CuneiformQueryBuilder.create().count().from(sanitizedObjectName).toSOQL();
+            const executeCount = () => this.connection.query(countQuery);
+            const result = this.retryConfig ? await withRetry(executeCount, this.retryConfig) : await executeCount();
+            const count = result.totalSize;
+            const duration = Date.now() - startTime;
+            // Cache the result
+            if (this.cacheEnabled) {
+                this.cache.set(cacheKey, count);
+            }
+            this.logger?.log(`Record count for ${objectName}: ${count}`);
+            return createSuccessResult(count, {
+                message: `Record count for ${objectName}: ${count}`,
+                metadata: { duration, cached: false },
+            });
+        }
+        catch (error) {
+            return this.handleError(error, startTime, 0, `record count for ${objectName}`);
+        }
+    }
+    /**
+     * Describes multiple Salesforce objects.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing a map of object names to describe results
+     */
+    async describeObjects(objectNames) {
+        const startTime = Date.now();
+        const results = new Map();
+        const warnings = [];
+        this.logger?.log(`Describing ${objectNames.length} objects`);
+        // Process in parallel
+        const promises = objectNames.map(async (name) => {
+            const result = await this.describeObject(name);
+            if (result.success) {
+                results.set(name, result.data);
+            }
+            else {
+                const errorInfo = result.errorCode ? `[${result.errorCode}] ` : '';
+                warnings.push(`Failed to describe ${name}: ${errorInfo}${result.message ?? 'Unknown error'}`);
+            }
+        });
+        await Promise.all(promises);
+        const duration = Date.now() - startTime;
+        this.logger?.log(`Described ${results.size}/${objectNames.length} objects`);
+        return createSuccessResult(results, {
+            message: `Described ${results.size}/${objectNames.length} objects`,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Gets record counts for multiple Salesforce objects using the bulk REST endpoint.
+     *
+     * Uses `GET /limits/recordCount` for a single API call instead of
+     * N individual SOQL `SELECT COUNT()` queries. Falls back to per-object SOQL queries
+     * if the REST endpoint is unavailable or fails.
+     *
+     * CLI-4214: the `/limits/recordCount` endpoint is a HINT — it returns ONLY objects with
+     * count > 0. Objects it omits (genuine empties and not-yet-counted recent writes) are
+     * ABSENT from the returned map, NOT fabricated as 0, so callers can distinguish a limits
+     * omission (reconcile it) from an authoritative 0. Counts present in the map (limits hits
+     * and SOQL-fallback results, including genuine 0s) are cached so subsequent
+     * `getRecordCount()` calls benefit; omitted objects leave the cache untouched.
+     *
+     * @param objectNames - Array of object API names
+     * @returns ServiceResult containing Map of object name to count (omits unknown objects)
+     */
+    async getRecordCounts(objectNames) {
+        const startTime = Date.now();
+        const results = new Map();
+        if (objectNames.length === 0) {
+            return createSuccessResult(results, {
+                message: 'Retrieved counts for 0/0 objects',
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        this.logger?.log(`Getting record counts for ${objectNames.length} objects`);
+        // Resolve cached counts first, collect uncached for bulk fetch
+        const uncached = [];
+        for (const name of objectNames) {
+            if (this.cacheEnabled) {
+                const cacheKey = `${CACHE_KEYS.COUNT}${name}`;
+                const cached = this.cache.get(cacheKey);
+                if (cached !== undefined) {
+                    results.set(name, cached);
+                    continue;
+                }
+            }
+            uncached.push(name);
+        }
+        if (uncached.length > 0) {
+            // Try the bulk /limits/recordCount REST endpoint first
+            const bulkSuccess = await this.fetchRecordCountsViaRest(uncached, results);
+            if (!bulkSuccess) {
+                // Fall back to individual SOQL COUNT() queries
+                this.logger?.log(`REST /limits/recordCount failed, falling back to individual SOQL for ${uncached.length} objects`);
+                await this.fetchRecordCountsViaSoql(uncached, results);
+            }
+        }
+        const duration = Date.now() - startTime;
+        this.logger?.log(`Retrieved counts for ${results.size}/${objectNames.length} objects`);
+        return createSuccessResult(results, {
+            message: `Retrieved counts for ${results.size}/${objectNames.length} objects`,
+            // CLI-4214: a size shortfall now means the /limits/recordCount hint OMITTED some
+            // requested objects (it only returns objects with count > 0). Those are NOT zeros —
+            // they are unknown until the caller reconciles them. The message reflects that.
+            warnings: results.size < objectNames.length
+                ? ['Some objects were omitted by /limits/recordCount (count unknown until reconciled)']
+                : undefined,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Inserts a new record into a Salesforce object.
+     *
+     * Uses the REST API POST /sobjects/{objectName} endpoint to create a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'PermissionSetAssignment')
+     * @param record - The field values for the new record
+     * @returns ServiceResult containing the created record's ID
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.insertRecord('PermissionSetAssignment', {
+     *   AssigneeId: '005xx000001234567',
+     *   PermissionSetId: '0PS000000000001'
+     * });
+     * ```
+     */
+    async insertRecord(objectName, record) {
+        const startTime = Date.now();
+        const emptyResult = { id: '' };
+        try {
+            this.logger?.log(`Inserting record into: ${objectName}`);
+            await this.lifecycle.start('insertRecord', { objectName });
+            // Sanitize objectName to prevent injection (validates API name format)
+            const sanitizedObjectName = sanitizeSoqlIdentifier(objectName);
+            // Namespace guard: only pnova__ objects and allowlisted standard objects permitted
+            const namespaceViolation = RestApiAdapter.validateWriteNamespace(sanitizedObjectName, 'insert');
+            if (namespaceViolation) {
+                this.logger?.log(`Insert blocked by namespace guard: ${objectName}`);
+                await this.lifecycle.error('insertRecord', startTime, namespaceViolation.message, { objectName });
+                return createFailureResult(emptyResult, namespaceViolation.errorCode, namespaceViolation.message);
+            }
+            // Build REST API endpoint for sObject insert
+            const endpoint = `/sobjects/${sanitizedObjectName}`;
+            const executeInsert = () => this.connection.request({
+                url: endpoint,
+                method: 'POST',
+                body: JSON.stringify(record),
+                headers: { 'content-type': 'application/json' },
+            });
+            const result = this.retryConfig ? await withRetry(executeInsert, this.retryConfig) : await executeInsert();
+            const duration = Date.now() - startTime;
+            // Check if the API returned success=false with errors
+            if (!result.success) {
+                const apiErrorMessage = Array.isArray(result.errors) ? JSON.stringify(result.errors) : 'Insert failed';
+                this.logger?.log(`Insert failed for ${objectName}: ${apiErrorMessage}`);
+                await this.lifecycle.error('insertRecord', startTime, apiErrorMessage, { objectName });
+                return createFailureResult(emptyResult, AdapterErrorCodes.INSERT_RECORD_FAILED, apiErrorMessage, {
+                    metadata: { duration },
+                });
+            }
+            this.logger?.log(`Insert complete for ${objectName}: ${result.id}`);
+            await this.lifecycle.complete('insertRecord', startTime, { objectName, recordId: result.id });
+            return createSuccessResult({ id: result.id }, {
+                message: `Inserted record into ${objectName}: ${result.id}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('insertRecord', startTime, errorMessage, { objectName });
+            return this.handleInsertError(error, startTime, emptyResult, objectName);
+        }
+    }
+    /**
+     * Updates an existing record in a Salesforce object.
+     *
+     * Uses the REST API PATCH /sobjects/{objectName}/{recordId} endpoint to update a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'Contact')
+     * @param recordId - The ID of the record to update
+     * @param record - The field values to update
+     * @returns ServiceResult containing the update result with record ID and success status
+     */
+    async updateRecord(objectName, recordId, record) {
+        const startTime = Date.now();
+        const emptyResult = { id: recordId, success: false };
+        try {
+            this.logger?.log(`Updating record ${recordId} in: ${objectName}`);
+            await this.lifecycle.start('updateRecord', { objectName, recordId });
+            // Sanitize objectName to prevent injection (validates API name format)
+            const sanitizedObjectName = sanitizeSoqlIdentifier(objectName);
+            // Namespace guard: only pnova__ objects permitted for update
+            const namespaceViolation = RestApiAdapter.validateWriteNamespace(sanitizedObjectName, 'update');
+            if (namespaceViolation) {
+                this.logger?.log(`Update blocked by namespace guard: ${objectName}`);
+                await this.lifecycle.error('updateRecord', startTime, namespaceViolation.message, { objectName, recordId });
+                return createFailureResult(emptyResult, namespaceViolation.errorCode, namespaceViolation.message);
+            }
+            // Build REST API endpoint for sObject update
+            const endpoint = `/sobjects/${sanitizedObjectName}/${recordId}`;
+            // PATCH request returns 204 No Content on success, error response on failure
+            const executeUpdate = () => this.connection.request({
+                url: endpoint,
+                method: 'PATCH',
+                body: JSON.stringify(record),
+                headers: { 'content-type': 'application/json' },
+            });
+            await (this.retryConfig ? withRetry(executeUpdate, this.retryConfig) : executeUpdate());
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Update complete for ${objectName}/${recordId}`);
+            await this.lifecycle.complete('updateRecord', startTime, { objectName, recordId });
+            return createSuccessResult({ id: recordId, success: true }, {
+                message: `Updated record in ${objectName}: ${recordId}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('updateRecord', startTime, errorMessage, { objectName, recordId });
+            return this.handleUpdateError(error, startTime, emptyResult, `${objectName}/${recordId}`);
+        }
+    }
+    /**
+     * Deletes a record from a Salesforce object.
+     *
+     * Uses the REST API DELETE /sobjects/{objectName}/{recordId} endpoint to delete a record.
+     * Does not use caching since write operations should always execute.
+     *
+     * @param objectName - The API name of the object (e.g., 'Account', 'Contact')
+     * @param recordId - The ID of the record to delete
+     * @returns ServiceResult containing the delete result with record ID and success status
+     */
+    async deleteRecord(objectName, recordId) {
+        const startTime = Date.now();
+        const emptyResult = { id: recordId, success: false };
+        try {
+            this.logger?.log(`Deleting record ${recordId} from: ${objectName}`);
+            await this.lifecycle.start('deleteRecord', { objectName, recordId });
+            // Sanitize objectName to prevent injection (validates API name format)
+            const sanitizedObjectName = sanitizeSoqlIdentifier(objectName);
+            // Namespace guard: only pnova__ objects permitted for delete
+            const namespaceViolation = RestApiAdapter.validateWriteNamespace(sanitizedObjectName, 'delete');
+            if (namespaceViolation) {
+                this.logger?.log(`Delete blocked by namespace guard: ${objectName}`);
+                await this.lifecycle.error('deleteRecord', startTime, namespaceViolation.message, { objectName, recordId });
+                return createFailureResult(emptyResult, namespaceViolation.errorCode, namespaceViolation.message);
+            }
+            // Build REST API endpoint for sObject delete
+            const endpoint = `/sobjects/${sanitizedObjectName}/${recordId}`;
+            // DELETE request returns 204 No Content on success, error response on failure
+            const executeDelete = () => this.connection.request({
+                url: endpoint,
+                method: 'DELETE',
+            });
+            await (this.retryConfig ? withRetry(executeDelete, this.retryConfig) : executeDelete());
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Delete complete for ${objectName}/${recordId}`);
+            await this.lifecycle.complete('deleteRecord', startTime, { objectName, recordId });
+            return createSuccessResult({ id: recordId, success: true }, {
+                message: `Deleted record from ${objectName}: ${recordId}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('deleteRecord', startTime, errorMessage, { objectName, recordId });
+            return this.handleDeleteError(error, startTime, emptyResult, `${objectName}/${recordId}`);
+        }
+    }
+    /**
+     * Makes a generic HTTP request to a custom Salesforce REST endpoint.
+     *
+     * Supports custom Apex REST endpoints and any other Salesforce REST API path.
+     * Does not use caching since custom endpoints have unpredictable response shapes.
+     *
+     * The namespace guard is enforced for write operations (POST, PATCH, PUT, DELETE) that
+     * target sObject endpoints (`/sobjects/{objectName}`). Custom Apex REST endpoints
+     * (e.g., `/services/apexrest/pnova/v1/...`) and GET requests are not affected.
+     *
+     * @param httpRequest - The HTTP request configuration
+     * @returns ServiceResult containing the deserialized response of type T
+     */
+    async request(httpRequest) {
+        const startTime = Date.now();
+        const SOBJECT_WRITE_METHODS = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+        try {
+            this.logger?.log(`REST request: ${httpRequest.method} ${httpRequest.url}`);
+            // Namespace guard: block write operations to non-pnova__ sObject endpoints
+            const sobjectPattern = /^\/sobjects\/([^/]+)/;
+            const sobjectMatch = sobjectPattern.exec(httpRequest.url);
+            if (sobjectMatch && SOBJECT_WRITE_METHODS.has(httpRequest.method)) {
+                const objectName = sobjectMatch[1];
+                const operation = httpRequest.method === 'POST' ? 'insert' : httpRequest.method === 'DELETE' ? 'delete' : 'update';
+                const violation = RestApiAdapter.validateWriteNamespace(objectName, operation);
+                if (violation) {
+                    this.logger?.log(`Request blocked by namespace guard: ${httpRequest.method} ${httpRequest.url}`);
+                    await this.lifecycle.error('request', startTime, violation.message, {
+                        url: httpRequest.url,
+                        method: httpRequest.method,
+                    });
+                    return createEmptyFailureResult(violation.errorCode, violation.message);
+                }
+            }
+            await this.lifecycle.start('request', { url: httpRequest.url, method: httpRequest.method });
+            const executeRequest = () => this.connection.request({
+                url: httpRequest.url,
+                method: httpRequest.method,
+                body: httpRequest.body != null
+                    ? typeof httpRequest.body === 'string'
+                        ? httpRequest.body
+                        : JSON.stringify(httpRequest.body)
+                    : undefined,
+                headers: httpRequest.headers ?? { 'content-type': 'application/json' },
+            });
+            const raw = this.retryConfig ? await withRetry(executeRequest, this.retryConfig) : await executeRequest();
+            // jsforce connection.request() may return a raw JSON string for custom REST endpoints;
+            // parse it so callers always receive a typed object.
+            const result = typeof raw === 'string' ? JSON.parse(raw) : raw;
+            const duration = Date.now() - startTime;
+            this.logger?.log(`REST request complete: ${httpRequest.method} ${httpRequest.url}`);
+            await this.lifecycle.complete('request', startTime, { url: httpRequest.url, method: httpRequest.method });
+            return createSuccessResult(result, {
+                message: `${httpRequest.method} ${httpRequest.url}`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('request', startTime, errorMessage, {
+                url: httpRequest.url,
+                method: httpRequest.method,
+            });
+            return this.handleError(error, startTime, undefined, `${httpRequest.method} ${httpRequest.url}`, AdapterErrorCodes.REQUEST_FAILED);
+        }
+    }
+    /**
+     * Invalidates cached entries.
+     *
+     * @param pattern - Optional pattern to match keys (supports * wildcard). If not provided, clears all entries.
+     */
+    invalidateCache(pattern) {
+        this.logger?.log(`Invalidating cache${pattern ? `: ${pattern}` : ' (all)'}`);
+        this.cache.invalidate(pattern);
+    }
+    /**
+     * Fetches record counts via the bulk REST endpoint `/limits/recordCount`.
+     *
+     * @param objectNames - Object API names to fetch counts for
+     * @param results - Map to populate with counts
+     * @returns true if the REST endpoint succeeded, false if it failed
+     */
+    async fetchRecordCountsViaRest(objectNames, results) {
+        try {
+            // CLI-1744: Call /limits/recordCount WITHOUT sObjects param to get ALL counts in one call.
+            // The previous approach joined all object names into the URL query string, which exceeded
+            // URL length limits (8K+) for orgs with 500+ objects and triggered the SOQL fallback (67-72s).
+            // A single parameterless call returns all org counts in ~1-2s.
+            const endpoint = '/limits/recordCount';
+            const response = await (this.retryConfig
+                ? withRetry(() => this.connection.request(endpoint), this.retryConfig)
+                : this.connection.request(endpoint));
+            // Build a lookup from the full org response
+            const countsByName = new Map();
+            for (const entry of response.sObjects) {
+                countsByName.set(entry.name, entry.count);
+            }
+            // CLI-4214: /limits/recordCount is a HINT, not authority — it returns ONLY objects
+            // with count > 0. Every empty object AND every not-yet-counted (recently written)
+            // object is OMITTED from the response. The previous `?? 0` fabricated a 0 for those
+            // omissions and cached it, poisoning later getRecordCount() cache reads and collapsing
+            // populated-but-omitted objects to 0 (the --with-records silent-skip bug).
+            //
+            // Only record/cache counts for objects ACTUALLY PRESENT in the limits response. Omitted
+            // objects are left ABSENT from the results map so the caller can distinguish a limits
+            // omission (reconcile it) from a genuine, authoritative 0 (the SOQL fallback path).
+            for (const name of objectNames) {
+                const count = countsByName.get(name);
+                if (count === undefined) {
+                    continue;
+                }
+                results.set(name, count);
+                if (this.cacheEnabled) {
+                    this.cache.set(`${CACHE_KEYS.COUNT}${name}`, count);
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`REST /limits/recordCount unavailable: ${errorMessage}, falling back to individual queries`);
+            return false;
+        }
+    }
+    /**
+     * Fallback: fetches record counts via individual SOQL COUNT() queries.
+     *
+     * @param objectNames - Object API names to fetch counts for
+     * @param results - Map to populate with counts
+     */
+    async fetchRecordCountsViaSoql(objectNames, results) {
+        /* eslint-disable no-await-in-loop -- Intentional sequential batching to avoid overwhelming Salesforce API */
+        for (let i = 0; i < objectNames.length; i += this.recordCountBatchSize) {
+            const batch = objectNames.slice(i, i + this.recordCountBatchSize);
+            const batchPromises = batch.map(async (name) => {
+                const result = await this.getRecordCount(name);
+                if (result.success) {
+                    results.set(name, result.data);
+                }
+            });
+            await Promise.all(batchPromises);
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+    /**
+     * Handles DML insert errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    handleInsertError(error, startTime, emptyResult, context) {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error
+            ? error.message
+            : typeof error === 'object' && error !== null
+                ? JSON.stringify(error)
+                : String(error);
+        const sfErrorCode = extractSalesforceErrorCode(error);
+        const adapterErrorCode = sfErrorCode ? mapDmlInsertError(sfErrorCode) : AdapterErrorCodes.INSERT_RECORD_FAILED;
+        this.logger?.log(`REST API insert failed (${context}): ${errorMessage}`);
+        return createFailureResult(emptyResult, adapterErrorCode, errorMessage, {
+            metadata: { duration, sfErrorCode },
+        });
+    }
+    /**
+     * Handles DML update errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name/record ID)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    handleUpdateError(error, startTime, emptyResult, context) {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error
+            ? error.message
+            : typeof error === 'object' && error !== null
+                ? JSON.stringify(error)
+                : String(error);
+        const sfErrorCode = extractSalesforceErrorCode(error);
+        const adapterErrorCode = sfErrorCode ? mapDmlUpdateError(sfErrorCode) : AdapterErrorCodes.UPDATE_RECORD_FAILED;
+        this.logger?.log(`REST API update failed (${context}): ${errorMessage}`);
+        return createFailureResult(emptyResult, adapterErrorCode, errorMessage, {
+            metadata: { duration, sfErrorCode },
+        });
+    }
+    /**
+     * Handles DML delete errors and maps them to appropriate error codes.
+     *
+     * @param error - The caught error
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (object name/record ID)
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    handleDeleteError(error, startTime, emptyResult, context) {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error
+            ? error.message
+            : typeof error === 'object' && error !== null
+                ? JSON.stringify(error)
+                : String(error);
+        const sfErrorCode = extractSalesforceErrorCode(error);
+        const adapterErrorCode = sfErrorCode ? mapDmlDeleteError(sfErrorCode) : AdapterErrorCodes.DELETE_RECORD_FAILED;
+        this.logger?.log(`REST API delete failed (${context}): ${errorMessage}`);
+        return createFailureResult(emptyResult, adapterErrorCode, errorMessage, {
+            metadata: { duration, sfErrorCode },
+        });
+    }
+    /**
+     * Handles errors and maps them to appropriate error codes.
+     *
+     * Accepts SfError, jsforce errors, or unknown error types. Extracts Salesforce
+     * error codes when available and maps them to adapter-specific error codes.
+     *
+     * @param error - The caught error (SfError, jsforce error, or unknown)
+     * @param startTime - The operation start time for duration calculation
+     * @param emptyResult - The empty result to return on failure
+     * @param context - Context for logging (e.g., "Account", "global describe")
+     * @param defaultErrorCode - The default error code if no SF error code is found
+     * @returns ServiceResult with success=false and mapped error code
+     */
+    handleError(error, startTime, emptyResult, context, defaultErrorCode = AdapterErrorCodes.DESCRIBE_FAILED) {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error
+            ? error.message
+            : typeof error === 'object' && error !== null
+                ? JSON.stringify(error)
+                : String(error);
+        const sfErrorCode = extractSalesforceErrorCode(error);
+        const adapterErrorCode = sfErrorCode ? mapSalesforceError(sfErrorCode, 'rest') : defaultErrorCode;
+        this.logger?.log(`REST API failed (${context}): ${errorMessage}`);
+        if (emptyResult === undefined) {
+            return createEmptyFailureResult(adapterErrorCode, errorMessage, {
+                metadata: { duration, sfErrorCode },
+            });
+        }
+        return createFailureResult(emptyResult, adapterErrorCode, errorMessage, {
+            metadata: { duration, sfErrorCode },
+        });
+    }
+}
+//# sourceMappingURL=rest-api-adapter.js.map