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

package/lib/adapters/soql/soql-query-adapter.d.ts

@@ -0,0 +1,141 @@
+import type { IConnectionFacade, QueryResult } from '../connection-facade.js';
+import type { ServiceResult } from '../../models/service-result.js';
+import type { RetryConfig } from '../retry.js';
+import type { ChunkOptions } from './types.js';
+/**
+ * Configuration for SoqlQueryAdapter.
+ */
+export type SoqlQueryAdapterConfig = {
+    /** Optional logger for debug output */
+    logger?: Console;
+    /**
+     * Whether to emit @salesforce/core Lifecycle events for telemetry.
+     * When enabled, emits events like 'adapter:query:start', 'adapter:query:complete'.
+     * Default: false
+     */
+    emitLifecycleEvents?: boolean;
+    /**
+     * Retry configuration for transient failures.
+     * If not specified, retries are disabled.
+     */
+    retry?: RetryConfig;
+};
+/**
+ * Interface for SOQL query operations.
+ *
+ * Provides methods for executing SOQL queries with pagination
+ * and chunking support.
+ */
+export type ISoqlQueryAdapter = {
+    /**
+     * Executes a SOQL query and returns the first page of results.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing query results
+     */
+    query<T>(soql: string): Promise<ServiceResult<QueryResult<T>>>;
+    /**
+     * Executes a SOQL query and retrieves all results, handling pagination automatically.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing all query results
+     */
+    queryAll<T>(soql: string): Promise<ServiceResult<QueryResult<T>>>;
+    /**
+     * Executes a SOQL query and processes results in chunks.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @param options - Chunking options including chunk size and callback
+     * @returns ServiceResult containing all query results
+     */
+    queryChunked<T>(soql: string, options?: ChunkOptions<T>): Promise<ServiceResult<QueryResult<T>>>;
+};
+/**
+ * Adapter for executing SOQL queries against Salesforce.
+ *
+ * Provides pagination handling and chunked processing for efficient
+ * retrieval of large datasets.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SoqlQueryAdapter(connectionFacade);
+ *
+ * // Simple query
+ * const result = await adapter.query<Account>('SELECT Id, Name FROM Account LIMIT 10');
+ *
+ * // Query all records with pagination
+ * const allAccounts = await adapter.queryAll<Account>('SELECT Id, Name FROM Account');
+ *
+ * // Process in chunks
+ * await adapter.queryChunked<Account>('SELECT Id, Name FROM Account', {
+ *   chunkSize: 1000,
+ *   onChunk: (records, index) => console.log(`Processing chunk ${index}`),
+ * });
+ * ```
+ */
+export declare class SoqlQueryAdapter implements ISoqlQueryAdapter {
+    private readonly connection;
+    private readonly logger?;
+    private readonly lifecycle;
+    private readonly retryConfig?;
+    /**
+     * Creates a new SoqlQueryAdapter.
+     *
+     * @param connection - The connection facade to use for API calls
+     * @param config - Optional configuration
+     */
+    constructor(connection: IConnectionFacade, config?: SoqlQueryAdapterConfig);
+    /**
+     * Executes a SOQL query and returns the first page of results.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing query results
+     */
+    query<T>(soql: string): Promise<ServiceResult<QueryResult<T>>>;
+    /**
+     * Executes a SOQL query and retrieves all results, handling pagination automatically.
+     *
+     * Uses an async generator internally for memory efficiency when dealing
+     * with large result sets.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing all query results
+     */
+    queryAll<T>(soql: string): Promise<ServiceResult<QueryResult<T>>>;
+    /**
+     * Executes a SOQL query and processes results in chunks.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @param options - Chunking options
+     * @returns ServiceResult containing all query results
+     */
+    queryChunked<T>(soql: string, options?: ChunkOptions<T>): Promise<ServiceResult<QueryResult<T>>>;
+    /**
+     * Async generator that fetches all pages of a query result.
+     *
+     * Uses retry logic for both initial query and pagination calls to handle
+     * transient failures during large result set retrieval.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @yields Each page of query results
+     */
+    private fetchAllPages;
+    /**
+     * Handles query 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 query start time for duration calculation
+     * @returns ServiceResult with success=false, empty QueryResult, and mapped error code
+     */
+    private handleQueryError;
+}

package/lib/adapters/soql/soql-query-adapter.js

@@ -0,0 +1,259 @@
+/*
+ * 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 } from '../../models/service-result.js';
+import { AdapterErrorCodes, mapSalesforceError, extractSalesforceErrorCode } from '../errors.js';
+import { createLifecycleEmitter } from '../lifecycle.js';
+import { withRetry } from '../retry.js';
+import { warnApiVersion } from '../types.js';
+import { DEFAULT_CHUNK_SIZE } from './types.js';
+/**
+ * Adapter for executing SOQL queries against Salesforce.
+ *
+ * Provides pagination handling and chunked processing for efficient
+ * retrieval of large datasets.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SoqlQueryAdapter(connectionFacade);
+ *
+ * // Simple query
+ * const result = await adapter.query<Account>('SELECT Id, Name FROM Account LIMIT 10');
+ *
+ * // Query all records with pagination
+ * const allAccounts = await adapter.queryAll<Account>('SELECT Id, Name FROM Account');
+ *
+ * // Process in chunks
+ * await adapter.queryChunked<Account>('SELECT Id, Name FROM Account', {
+ *   chunkSize: 1000,
+ *   onChunk: (records, index) => console.log(`Processing chunk ${index}`),
+ * });
+ * ```
+ */
+export class SoqlQueryAdapter {
+    connection;
+    logger;
+    lifecycle;
+    retryConfig;
+    /**
+     * Creates a new SoqlQueryAdapter.
+     *
+     * @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.lifecycle = createLifecycleEmitter('query', config?.emitLifecycleEvents ?? false);
+        this.retryConfig = config?.retry;
+        // Warn if API version is below recommended minimum
+        warnApiVersion(connection.version, 'SoqlQueryAdapter', this.logger);
+    }
+    /**
+     * Executes a SOQL query and returns the first page of results.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing query results
+     */
+    async query(soql) {
+        const startTime = Date.now();
+        try {
+            this.logger?.log(`Executing SOQL query: ${soql.substring(0, 100)}...`);
+            await this.lifecycle.start('query', { soqlLength: soql.length });
+            const executeQuery = () => this.connection.query(soql);
+            const result = this.retryConfig ? await withRetry(executeQuery, this.retryConfig) : await executeQuery();
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Query returned ${result.records.length} of ${result.totalSize} records`);
+            await this.lifecycle.complete('query', startTime, { recordCount: result.records.length });
+            return createSuccessResult(result, {
+                message: `Query returned ${result.records.length} records`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('query', startTime, errorMessage);
+            return this.handleQueryError(error, startTime);
+        }
+    }
+    /**
+     * Executes a SOQL query and retrieves all results, handling pagination automatically.
+     *
+     * Uses an async generator internally for memory efficiency when dealing
+     * with large result sets.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @returns ServiceResult containing all query results
+     */
+    async queryAll(soql) {
+        const startTime = Date.now();
+        try {
+            this.logger?.log(`Executing queryAll: ${soql.substring(0, 100)}...`);
+            await this.lifecycle.start('queryAll', { soqlLength: soql.length });
+            const allRecords = [];
+            let totalSize = 0;
+            // Use the async generator to fetch all pages
+            // eslint-disable-next-line no-await-in-loop -- Intentional: async generator requires sequential iteration
+            for await (const page of this.fetchAllPages(soql)) {
+                allRecords.push(...page.records);
+                totalSize = page.totalSize;
+            }
+            const duration = Date.now() - startTime;
+            this.logger?.log(`QueryAll retrieved ${allRecords.length} total records`);
+            await this.lifecycle.complete('queryAll', startTime, { recordCount: allRecords.length });
+            const result = {
+                done: true,
+                totalSize,
+                records: allRecords,
+            };
+            return createSuccessResult(result, {
+                message: `Retrieved all ${allRecords.length} records`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('queryAll', startTime, errorMessage);
+            return this.handleQueryError(error, startTime);
+        }
+    }
+    /**
+     * Executes a SOQL query and processes results in chunks.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @param options - Chunking options
+     * @returns ServiceResult containing all query results
+     */
+    async queryChunked(soql, options) {
+        const startTime = Date.now();
+        const chunkSize = options?.chunkSize ?? DEFAULT_CHUNK_SIZE;
+        const maxRecords = options?.maxRecords;
+        try {
+            this.logger?.log(`Executing queryChunked with chunkSize=${chunkSize}: ${soql.substring(0, 100)}...`);
+            await this.lifecycle.start('queryChunked', { soqlLength: soql.length, chunkSize });
+            const allRecords = [];
+            let totalSize = 0;
+            let chunkIndex = 0;
+            let currentChunk = [];
+            // Use the async generator to fetch all pages
+            // eslint-disable-next-line no-await-in-loop -- Intentional: async generator requires sequential iteration
+            for await (const page of this.fetchAllPages(soql)) {
+                totalSize = page.totalSize;
+                for (const record of page.records) {
+                    // Check if we've hit maxRecords
+                    if (maxRecords !== undefined && allRecords.length >= maxRecords) {
+                        break;
+                    }
+                    currentChunk.push(record);
+                    allRecords.push(record);
+                    // Process chunk when it reaches chunkSize
+                    if (currentChunk.length >= chunkSize) {
+                        if (options?.onChunk) {
+                            // eslint-disable-next-line no-await-in-loop -- Intentional: chunks must be processed sequentially
+                            await options.onChunk(currentChunk, chunkIndex);
+                        }
+                        chunkIndex++;
+                        currentChunk = [];
+                    }
+                }
+                // Check if we've hit maxRecords
+                if (maxRecords !== undefined && allRecords.length >= maxRecords) {
+                    break;
+                }
+            }
+            // Process any remaining records in the final chunk
+            if (currentChunk.length > 0 && options?.onChunk) {
+                await options.onChunk(currentChunk, chunkIndex);
+            }
+            const duration = Date.now() - startTime;
+            const chunksProcessed = chunkIndex + (currentChunk.length > 0 ? 1 : 0);
+            this.logger?.log(`QueryChunked processed ${allRecords.length} records in ${chunksProcessed} chunks`);
+            await this.lifecycle.complete('queryChunked', startTime, {
+                recordCount: allRecords.length,
+                chunksProcessed,
+            });
+            const result = {
+                done: true,
+                totalSize,
+                records: allRecords,
+            };
+            return createSuccessResult(result, {
+                message: `Processed ${allRecords.length} records in chunks`,
+                metadata: {
+                    duration,
+                    chunksProcessed,
+                },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await this.lifecycle.error('queryChunked', startTime, errorMessage);
+            return this.handleQueryError(error, startTime);
+        }
+    }
+    /**
+     * Async generator that fetches all pages of a query result.
+     *
+     * Uses retry logic for both initial query and pagination calls to handle
+     * transient failures during large result set retrieval.
+     *
+     * @template T The type of records being queried
+     * @param soql - The SOQL query string
+     * @yields Each page of query results
+     */
+    async *fetchAllPages(soql) {
+        // Initial query with retry
+        const executeInitialQuery = () => this.connection.query(soql);
+        let result = this.retryConfig
+            ? await withRetry(executeInitialQuery, this.retryConfig)
+            : await executeInitialQuery();
+        yield result;
+        /* eslint-disable no-await-in-loop -- Intentional: pagination requires sequential API calls */
+        while (!result.done && result.nextRecordsUrl) {
+            // Capture locator for closure
+            const locator = result.nextRecordsUrl;
+            const executeQueryMore = () => this.connection.queryMore(locator);
+            result = this.retryConfig ? await withRetry(executeQueryMore, this.retryConfig) : await executeQueryMore();
+            yield result;
+        }
+        /* eslint-enable no-await-in-loop */
+    }
+    /**
+     * Handles query 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 query start time for duration calculation
+     * @returns ServiceResult with success=false, empty QueryResult, and mapped error code
+     */
+    handleQueryError(error, startTime) {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Extract Salesforce error code if present
+        const sfErrorCode = extractSalesforceErrorCode(error);
+        const adapterErrorCode = sfErrorCode ? mapSalesforceError(sfErrorCode, 'soql') : AdapterErrorCodes.QUERY_FAILED;
+        this.logger?.log(`Query failed: ${errorMessage}`);
+        // Create empty QueryResult - type-safe since T is the record type
+        const emptyResult = {
+            done: true,
+            totalSize: 0,
+            records: [],
+        };
+        return createFailureResult(emptyResult, adapterErrorCode, errorMessage, {
+            metadata: {
+                duration,
+                sfErrorCode,
+            },
+        });
+    }
+}
+//# sourceMappingURL=soql-query-adapter.js.map

package/lib/adapters/soql/soql-query-adapter.js.map

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

package/lib/adapters/soql/types.d.ts

@@ -0,0 +1,37 @@
+export type { QueryResult } from '../connection-facade.js';
+/**
+ * Options for chunked query processing.
+ *
+ * @template T The type of records being queried
+ */
+export type ChunkOptions<T> = {
+    /**
+     * Number of records per chunk.
+     * Defaults to 2000.
+     */
+    chunkSize?: number;
+    /**
+     * Callback invoked for each chunk of records.
+     * Can be async for processing operations.
+     *
+     * @param records - The records in this chunk
+     * @param chunkIndex - Zero-based index of this chunk
+     */
+    onChunk?: (records: T[], chunkIndex: number) => void | Promise<void>;
+    /**
+     * Maximum total records to retrieve.
+     * If not specified, retrieves all matching records.
+     */
+    maxRecords?: number;
+};
+/**
+ * Default chunk size for queryChunked operations.
+ *
+ * The value of 2000 is chosen to balance:
+ * - Memory efficiency: Small enough to process without excessive memory use
+ * - Performance: Large enough to minimize callback overhead
+ * - Salesforce alignment: Within typical Salesforce API batch limits
+ *
+ * Override via `chunkSize` option in queryChunked() for different use cases.
+ */
+export declare const DEFAULT_CHUNK_SIZE = 2000;

package/lib/adapters/soql/types.js

@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+/**
+ * Default chunk size for queryChunked operations.
+ *
+ * The value of 2000 is chosen to balance:
+ * - Memory efficiency: Small enough to process without excessive memory use
+ * - Performance: Large enough to minimize callback overhead
+ * - Salesforce alignment: Within typical Salesforce API batch limits
+ *
+ * Override via `chunkSize` option in queryChunked() for different use cases.
+ */
+export const DEFAULT_CHUNK_SIZE = 2000;
+//# sourceMappingURL=types.js.map

package/lib/adapters/soql/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/soql/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiCH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC"}

package/lib/adapters/testing/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Test utilities for Salesforce API adapters.
+ *
+ * This module provides mock factories for all adapters, enabling isolated
+ * unit testing without making real Salesforce API calls.
+ *
+ * @module adapters/testing
+ *
+ * @example
+ * ```typescript
+ * import { createMockConnection, createMockSoqlQueryAdapter } from './adapters/testing';
+ *
+ * // Using mock connection with real adapter
+ * const { connection } = createMockConnection();
+ * const adapter = new SoqlQueryAdapter(connection);
+ *
+ * // Using mock adapter directly
+ * const { adapter: mockAdapter, calls } = createMockSoqlQueryAdapter();
+ * myService.setAdapter(mockAdapter);
+ *
+ * // After test, verify calls
+ * expect(calls).to.have.lengthOf(1);
+ * expect(calls[0].method).to.equal('query');
+ * ```
+ */
+export type { CallRecord, MockAdapterConfig, MockAdapter, MockConnectionConfig } from './types.js';
+export { createMockConnection, type MockConnectionFacade } from './mock-connection.js';
+export { createMockSoqlQueryAdapter } from './mock-soql-adapter.js';
+export { createMockRestApiAdapter } from './mock-rest-adapter.js';
+export { createMockToolingApiAdapter } from './mock-tooling-adapter.js';
+export { createMockLogger, type MockLogger } from './mock-logger.js';
+export { createStubConnection, type StubConnection, type StubTooling } from './stub-connection.js';
+export { createStubSoqlAdapter, type StubSoqlAdapter } from './stub-soql-adapter.js';
+export { createStubRestAdapter, type StubRestAdapter } from './stub-rest-adapter.js';
+export { createMockSalesforceConnection, type MockSalesforceConnectionConfig } from './mock-salesforce-connection.js';
+export { createMockAdapters, type MockMcpAdaptersConfig } from './mock-mcp-adapters.js';
+export { createMockOclifConfig } from './mock-oclif-config.js';

package/lib/adapters/testing/index.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+// Mock factories
+export { createMockConnection } from './mock-connection.js';
+export { createMockSoqlQueryAdapter } from './mock-soql-adapter.js';
+export { createMockRestApiAdapter } from './mock-rest-adapter.js';
+export { createMockToolingApiAdapter } from './mock-tooling-adapter.js';
+export { createMockLogger } from './mock-logger.js';
+export { createStubConnection } from './stub-connection.js';
+export { createStubSoqlAdapter } from './stub-soql-adapter.js';
+export { createStubRestAdapter } from './stub-rest-adapter.js';
+export { createMockSalesforceConnection } from './mock-salesforce-connection.js';
+export { createMockAdapters } from './mock-mcp-adapters.js';
+export { createMockOclifConfig } from './mock-oclif-config.js';
+//# sourceMappingURL=index.js.map

package/lib/adapters/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA+BH,iBAAiB;AACjB,OAAO,EAAE,oBAAoB,EAA6B,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAmB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAyC,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAwB,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,8BAA8B,EAAuC,MAAM,iCAAiC,CAAC;AACtH,OAAO,EAAE,kBAAkB,EAA8B,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}

package/lib/adapters/testing/mock-connection.d.ts

@@ -0,0 +1,77 @@
+import type { IConnectionFacade, DescribeSObjectResult, ExecuteAnonymousResult } from '../connection-facade.js';
+import type { CallRecord, MockConnectionConfig } from './types.js';
+/**
+ * Mock connection facade with call recording.
+ *
+ * @example
+ * ```typescript
+ * const { connection, calls, setQueryResult, setError } = createMockConnection();
+ *
+ * // Configure response
+ * setQueryResult('SELECT Id FROM Account', {
+ *   done: true,
+ *   totalSize: 1,
+ *   records: [{ Id: '001xx000001ABC' }]
+ * });
+ *
+ * // Use in adapter
+ * const adapter = new SoqlQueryAdapter(connection);
+ * const result = await adapter.query('SELECT Id FROM Account');
+ *
+ * // Assert calls were made
+ * expect(calls).to.have.lengthOf(1);
+ * expect(calls[0].method).to.equal('query');
+ * ```
+ */
+export type MockConnectionFacade = {
+    /** The mock connection instance */
+    connection: IConnectionFacade;
+    /** Recorded method calls */
+    calls: CallRecord[];
+    /** Reset call history */
+    resetCalls(): void;
+    /** Set a query result for a specific SOQL query */
+    setQueryResult(soql: string, result: unknown): void;
+    /** Set a describe result for a specific object */
+    setDescribeResult(objectName: string, result: DescribeSObjectResult): void;
+    /** Set an error for a specific method call (returns error via checkError) */
+    setError(method: string, key: string, error: Error): void;
+    /** Set the identity result */
+    setIdentity(identity: {
+        user_id: string;
+        organization_id: string;
+        username: string;
+    }): void;
+    /** Set an execute anonymous result */
+    setExecuteAnonymousResult(apex: string, result: ExecuteAnonymousResult): void;
+    /** Set a request result for a specific URL */
+    setRequestResult(url: string, result: unknown): void;
+    /**
+     * Set an exception to throw for a specific method/key combination.
+     * Unlike setError (which throws via checkError internally), setThrow allows
+     * testing of code that catches exceptions at a higher level.
+     */
+    setThrow(method: string, key: string, error: Error): void;
+    /** Clear a previously configured exception */
+    clearThrow(method: string, key: string): void;
+};
+/**
+ * Creates a mock connection facade for testing adapters.
+ *
+ * @param config - Optional configuration
+ * @returns Mock connection facade with call recording
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { connection } = createMockConnection();
+ * const adapter = new SoqlQueryAdapter(connection);
+ *
+ * // With configuration
+ * const { connection, calls } = createMockConnection({
+ *   version: '58.0',
+ *   defaultQueryResult: { done: true, totalSize: 0, records: [] }
+ * });
+ * ```
+ */
+export declare function createMockConnection(config?: MockConnectionConfig): MockConnectionFacade;