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

package/lib/adapters/testing/mock-tooling-adapter.js

@@ -0,0 +1,163 @@
+/*
+ * 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 } from '../errors.js';
+/**
+ * Creates a mock Tooling API adapter for testing.
+ *
+ * @param config - Optional configuration for responses and errors
+ * @returns Mock adapter with call recording
+ *
+ * @example
+ * ```typescript
+ * const { adapter, calls, setResponse, setError } = createMockToolingApiAdapter();
+ *
+ * // Configure custom fields response
+ * setResponse('customFields:Account', [
+ *   { Id: '00N123', DeveloperName: 'Custom__c', TableEnumOrId: 'Account' }
+ * ]);
+ *
+ * // Use in test
+ * const result = await adapter.queryCustomFields('Account');
+ * expect(result.success).to.be.true;
+ * expect(calls).to.have.lengthOf(1);
+ * ```
+ */
+export function createMockToolingApiAdapter(config) {
+    const calls = [];
+    const responses = new Map(config?.responses);
+    const errors = new Map(config?.errors);
+    const throws = new Map();
+    const defaultQueryResult = {
+        done: true,
+        totalSize: 0,
+        records: [],
+    };
+    const recordCall = (method, args) => {
+        calls.push({ method, args, timestamp: Date.now() });
+    };
+    const checkThrow = (key) => {
+        const throwError = throws.get(key);
+        if (throwError) {
+            throw throwError;
+        }
+    };
+    const adapter = {
+        query: (soql) => {
+            recordCall('query', [soql]);
+            checkThrow(`query:${soql}`);
+            const error = errors.get(`query:${soql}`);
+            if (error) {
+                return Promise.resolve(createFailureResult({ done: true, totalSize: 0, records: [] }, AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            const response = responses.get(`query:${soql}`);
+            if (response) {
+                return Promise.resolve(createSuccessResult(response, { message: `Query returned ${response.records.length} records` }));
+            }
+            return Promise.resolve(createSuccessResult(defaultQueryResult, { message: 'Query returned 0 records' }));
+        },
+        queryAll: (soql) => {
+            recordCall('queryAll', [soql]);
+            checkThrow(`queryAll:${soql}`);
+            const error = errors.get(`queryAll:${soql}`);
+            if (error) {
+                return Promise.resolve(createFailureResult({ done: true, totalSize: 0, records: [] }, AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            const response = responses.get(`queryAll:${soql}`);
+            if (response) {
+                return Promise.resolve(createSuccessResult(response, { message: `QueryAll returned ${response.records.length} records` }));
+            }
+            return Promise.resolve(createSuccessResult(defaultQueryResult, { message: 'QueryAll returned 0 records' }));
+        },
+        queryCustomFields: (objectName) => {
+            recordCall('queryCustomFields', [objectName]);
+            checkThrow(`customFields:${objectName}`);
+            const error = errors.get(`customFields:${objectName}`);
+            if (error) {
+                return Promise.resolve(createFailureResult([], AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            const response = responses.get(`customFields:${objectName}`);
+            if (response) {
+                return Promise.resolve(createSuccessResult(response, { message: `Found ${response.length} custom fields` }));
+            }
+            return Promise.resolve(createSuccessResult([], { message: 'Found 0 custom fields' }));
+        },
+        queryValidationRules: (objectName) => {
+            recordCall('queryValidationRules', [objectName]);
+            checkThrow(`validationRules:${objectName}`);
+            const error = errors.get(`validationRules:${objectName}`);
+            if (error) {
+                return Promise.resolve(createFailureResult([], AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            const response = responses.get(`validationRules:${objectName}`);
+            if (response) {
+                return Promise.resolve(createSuccessResult(response, { message: `Found ${response.length} validation rules` }));
+            }
+            return Promise.resolve(createSuccessResult([], { message: 'Found 0 validation rules' }));
+        },
+        queryTabs: () => {
+            recordCall('queryTabs', []);
+            checkThrow('tabs');
+            const error = errors.get('tabs');
+            if (error) {
+                return Promise.resolve(createFailureResult([], AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            const response = responses.get('tabs');
+            if (response) {
+                return Promise.resolve(createSuccessResult(response, { message: `Found ${response.length} tabs` }));
+            }
+            return Promise.resolve(createSuccessResult([], { message: 'Found 0 tabs' }));
+        },
+        queryTabByObject: (objectName) => {
+            recordCall('queryTabByObject', [objectName]);
+            checkThrow(`tabByObject:${objectName}`);
+            const error = errors.get(`tabByObject:${objectName}`);
+            if (error) {
+                return Promise.resolve(createFailureResult(null, AdapterErrorCodes.TOOLING_QUERY_FAILED, error.message));
+            }
+            // Check for object-specific response first
+            const objectResponse = responses.get(`tabByObject:${objectName}`);
+            if (objectResponse !== undefined) {
+                if (objectResponse === null) {
+                    return Promise.resolve(createSuccessResult(null, { message: `No tab found for object: ${objectName}` }));
+                }
+                return Promise.resolve(createSuccessResult(objectResponse, { message: `Found tab for object: ${objectName}` }));
+            }
+            // Fall back to checking the tabs list (if queryTabs responses were set)
+            const allTabs = responses.get('tabs');
+            if (allTabs) {
+                const tab = allTabs.find((t) => t.SobjectName === objectName) ?? null;
+                if (tab) {
+                    return Promise.resolve(createSuccessResult(tab, { message: `Found tab for object: ${objectName}` }));
+                }
+                return Promise.resolve(createSuccessResult(null, { message: `No tab found for object: ${objectName}` }));
+            }
+            return Promise.resolve(createSuccessResult(null, { message: `No tab found for object: ${objectName}` }));
+        },
+    };
+    return {
+        adapter,
+        calls,
+        resetCalls: () => {
+            calls.length = 0;
+        },
+        setResponse: (key, response) => {
+            responses.set(key, response);
+        },
+        setError: (key, error) => {
+            errors.set(key, error);
+        },
+        setThrow: (key, error) => {
+            throws.set(key, error);
+        },
+        clearThrow: (key) => {
+            throws.delete(key);
+        },
+    };
+}
+//# sourceMappingURL=mock-tooling-adapter.js.map

package/lib/adapters/testing/mock-tooling-adapter.js.map

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

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

@@ -0,0 +1,93 @@
+import sinon from 'sinon';
+import type { IConnectionFacade } from '../connection-facade.js';
+/**
+ * Named sinon stubs for the tooling API sub-object.
+ *
+ * Each stub corresponds to a method on IToolingApi and can be configured
+ * with the full sinon stub API (.resolves, .rejects, .onFirstCall, etc.).
+ */
+export type StubTooling = {
+    /** Stub for tooling.query */
+    queryStub: sinon.SinonStub;
+    /** Stub for tooling.queryMore */
+    queryMoreStub: sinon.SinonStub;
+    /** Stub for tooling.executeAnonymous */
+    executeAnonymousStub: sinon.SinonStub;
+    /** Stub for tooling.create */
+    createStub: sinon.SinonStub;
+    /** Stub for tooling.destroy */
+    destroyStub: sinon.SinonStub;
+};
+/**
+ * Named sinon stubs for a stub-backed IConnectionFacade.
+ *
+ * Use the individual stubs to configure call behaviour directly with sinon's
+ * `.resolves()`, `.rejects()`, `.onFirstCall()`, etc. — no `as unknown as`
+ * cast is required because the `connection` property satisfies all of
+ * IConnectionFacade.
+ *
+ * @example
+ * ```typescript
+ * const stubConn = createStubConnection();
+ * stubConn.queryStub.resolves({ done: true, totalSize: 1, records: [{ Id: '001' }] });
+ * const adapter = new SoqlQueryAdapter(stubConn.connection);
+ * ```
+ */
+export type StubConnection = {
+    /** The fully-typed IConnectionFacade backed by sinon stubs */
+    connection: IConnectionFacade;
+    /** Stub for connection.query */
+    queryStub: sinon.SinonStub;
+    /** Stub for connection.queryMore */
+    queryMoreStub: sinon.SinonStub;
+    /** Stub for connection.request */
+    requestStub: sinon.SinonStub;
+    /** Stub for connection.identity */
+    identityStub: sinon.SinonStub;
+    /**
+     * Stub for connection.sobject.
+     *
+     * By default this stub returns an object whose `describe` and `find`
+     * properties are themselves sinon stubs. Access the inner stubs via
+     * `stubConn.sobjectDescribeStub` and `stubConn.sobjectFindStub`.
+     */
+    sobjectStub: sinon.SinonStub;
+    /** Stub for the describe method returned by sobject() */
+    sobjectDescribeStub: sinon.SinonStub;
+    /** Stub for the find method returned by sobject() */
+    sobjectFindStub: sinon.SinonStub;
+    /** Named stubs for the tooling API sub-object */
+    tooling: StubTooling;
+};
+/**
+ * Creates a fully-typed IConnectionFacade backed by sinon stubs.
+ *
+ * All properties required by IConnectionFacade are provided, so TypeScript
+ * accepts the return value as a valid IConnectionFacade without any type cast.
+ * Each method is a sinon stub that can be configured with the full sinon API.
+ *
+ * Prefer this factory over hand-rolling partial objects with
+ * `as unknown as IConnectionFacade` in adapter unit tests.
+ *
+ * @returns StubConnection containing the connection and all underlying stubs
+ *
+ * @example
+ * ```typescript
+ * import { createStubConnection } from '../../../src/adapters/testing/index.js';
+ *
+ * let stubConn: StubConnection;
+ *
+ * beforeEach(() => {
+ *   stubConn = createStubConnection();
+ *   adapter = new SoqlQueryAdapter(stubConn.connection);
+ * });
+ *
+ * it('returns records on success', async () => {
+ *   stubConn.queryStub.resolves({ done: true, totalSize: 1, records: [{ Id: '001' }] });
+ *   const result = await adapter.query('SELECT Id FROM Account');
+ *   expect(result.success).to.equal(true);
+ *   expect(result.data.records).to.have.lengthOf(1);
+ * });
+ * ```
+ */
+export declare function createStubConnection(): StubConnection;

package/lib/adapters/testing/stub-connection.js

@@ -0,0 +1,97 @@
+/*
+ * 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.
+ */
+// eslint-disable-next-line import/no-extraneous-dependencies -- test-only factory, sinon is a devDependency
+import sinon from 'sinon';
+/**
+ * Creates a fully-typed IConnectionFacade backed by sinon stubs.
+ *
+ * All properties required by IConnectionFacade are provided, so TypeScript
+ * accepts the return value as a valid IConnectionFacade without any type cast.
+ * Each method is a sinon stub that can be configured with the full sinon API.
+ *
+ * Prefer this factory over hand-rolling partial objects with
+ * `as unknown as IConnectionFacade` in adapter unit tests.
+ *
+ * @returns StubConnection containing the connection and all underlying stubs
+ *
+ * @example
+ * ```typescript
+ * import { createStubConnection } from '../../../src/adapters/testing/index.js';
+ *
+ * let stubConn: StubConnection;
+ *
+ * beforeEach(() => {
+ *   stubConn = createStubConnection();
+ *   adapter = new SoqlQueryAdapter(stubConn.connection);
+ * });
+ *
+ * it('returns records on success', async () => {
+ *   stubConn.queryStub.resolves({ done: true, totalSize: 1, records: [{ Id: '001' }] });
+ *   const result = await adapter.query('SELECT Id FROM Account');
+ *   expect(result.success).to.equal(true);
+ *   expect(result.data.records).to.have.lengthOf(1);
+ * });
+ * ```
+ */
+export function createStubConnection() {
+    // Top-level connection stubs
+    const queryStub = sinon.stub();
+    const queryMoreStub = sinon.stub();
+    const requestStub = sinon.stub();
+    const identityStub = sinon.stub();
+    // sobject inner stubs
+    const sobjectDescribeStub = sinon.stub();
+    const sobjectFindStub = sinon.stub();
+    const sobjectStub = sinon.stub().returns({
+        describe: sobjectDescribeStub,
+        find: sobjectFindStub,
+    });
+    // Tooling API stubs
+    const toolingQueryStub = sinon.stub();
+    const toolingQueryMoreStub = sinon.stub();
+    const toolingExecuteAnonymousStub = sinon.stub();
+    const toolingCreateStub = sinon.stub();
+    const toolingDestroyStub = sinon.stub();
+    // Assemble the fully-typed connection.  Because every required property is
+    // supplied, no `as unknown as` cast is needed.
+    const connection = {
+        version: '58.0',
+        accessToken: 'mock-access-token',
+        instanceUrl: 'https://test.salesforce.com',
+        query: queryStub,
+        queryMore: queryMoreStub,
+        sobject: sobjectStub,
+        request: requestStub,
+        identity: identityStub,
+        tooling: {
+            query: toolingQueryStub,
+            queryMore: toolingQueryMoreStub,
+            executeAnonymous: toolingExecuteAnonymousStub,
+            create: toolingCreateStub,
+            destroy: toolingDestroyStub,
+        },
+    };
+    return {
+        connection,
+        queryStub,
+        queryMoreStub,
+        requestStub,
+        identityStub,
+        sobjectStub,
+        sobjectDescribeStub,
+        sobjectFindStub,
+        tooling: {
+            queryStub: toolingQueryStub,
+            queryMoreStub: toolingQueryMoreStub,
+            executeAnonymousStub: toolingExecuteAnonymousStub,
+            createStub: toolingCreateStub,
+            destroyStub: toolingDestroyStub,
+        },
+    };
+}
+//# sourceMappingURL=stub-connection.js.map

package/lib/adapters/testing/stub-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-connection.js","sourceRoot":"","sources":["../../../src/adapters/testing/stub-connection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4GAA4G;AAC5G,OAAO,KAAK,MAAM,OAAO,CAAC;AAgE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB;IAClC,6BAA6B;IAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAElC,sBAAsB;IACtB,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC;QACvC,QAAQ,EAAE,mBAAmB;QAC7B,IAAI,EAAE,eAAe;KACS,CAAC,CAAC;IAElC,oBAAoB;IACpB,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,oBAAoB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,2BAA2B,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACjD,MAAM,iBAAiB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,kBAAkB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAExC,2EAA2E;IAC3E,+CAA+C;IAC/C,MAAM,UAAU,GAAsB;QACpC,OAAO,EAAE,MAAM;QACf,WAAW,EAAE,mBAAmB;QAChC,WAAW,EAAE,6BAA6B;QAC1C,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,aAAa;QACxB,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,WAAW;QACpB,QAAQ,EAAE,YAAY;QACtB,OAAO,EAAE;YACP,KAAK,EAAE,gBAAgB;YACvB,SAAS,EAAE,oBAAoB;YAC/B,gBAAgB,EAAE,2BAA2B;YAC7C,MAAM,EAAE,iBAAiB;YACzB,OAAO,EAAE,kBAAkB;SAC5B;KACF,CAAC;IAEF,OAAO;QACL,UAAU;QACV,SAAS;QACT,aAAa;QACb,WAAW;QACX,YAAY;QACZ,WAAW;QACX,mBAAmB;QACnB,eAAe;QACf,OAAO,EAAE;YACP,SAAS,EAAE,gBAAgB;YAC3B,aAAa,EAAE,oBAAoB;YACnC,oBAAoB,EAAE,2BAA2B;YACjD,UAAU,EAAE,iBAAiB;YAC7B,WAAW,EAAE,kBAAkB;SAChC;KACF,CAAC;AACJ,CAAC"}

package/lib/adapters/testing/stub-rest-adapter.d.ts

@@ -0,0 +1,52 @@
+import sinon from 'sinon';
+import type { IRestApiAdapter } from '../rest/rest-api-adapter.js';
+/**
+ * Named sinon stubs for a stub-backed IRestApiAdapter.
+ *
+ * Use the individual stubs to configure call behaviour directly with sinon's
+ * `.resolves()`, `.rejects()`, `.onFirstCall()`, etc. — no `as unknown as`
+ * cast is required because the `adapter` property satisfies IRestApiAdapter.
+ *
+ * @example
+ * ```typescript
+ * const stubRest = createStubRestAdapter();
+ * stubRest.describeObjectStub.resolves(createSuccessResult(mockDescribe));
+ * const service = new ContactPointService(stubRest.adapter);
+ * ```
+ */
+export type StubRestAdapter = {
+    /** The fully-typed IRestApiAdapter backed by sinon stubs */
+    adapter: IRestApiAdapter;
+    /** Stub for adapter.describeObject */
+    describeObjectStub: sinon.SinonStub;
+    /** Stub for adapter.describeGlobal */
+    describeGlobalStub: sinon.SinonStub;
+    /** Stub for adapter.getRecordCount */
+    getRecordCountStub: sinon.SinonStub;
+    /** Stub for adapter.getRecordCounts */
+    getRecordCountsStub: sinon.SinonStub;
+    /** Stub for adapter.describeObjects */
+    describeObjectsStub: sinon.SinonStub;
+    /** Stub for adapter.insertRecord */
+    insertRecordStub: sinon.SinonStub;
+    /** Stub for adapter.updateRecord */
+    updateRecordStub: sinon.SinonStub;
+    /** Stub for adapter.deleteRecord */
+    deleteRecordStub: sinon.SinonStub;
+    /** Stub for adapter.invalidateCache */
+    invalidateCacheStub: sinon.SinonStub;
+    /** Stub for adapter.request */
+    requestStub: sinon.SinonStub;
+};
+/**
+ * Creates a fully-typed IRestApiAdapter backed by sinon stubs.
+ *
+ * All methods required by IRestApiAdapter are provided as sinon stubs,
+ * so TypeScript accepts the return value without any type cast.
+ *
+ * Prefer this factory over `sinon.createStubInstance(RestApiAdapter)` or
+ * hand-rolling partial objects with `as sinon.SinonStubbedInstance<IRestApiAdapter>`.
+ *
+ * @returns StubRestAdapter containing the adapter and all underlying stubs
+ */
+export declare function createStubRestAdapter(): StubRestAdapter;

package/lib/adapters/testing/stub-rest-adapter.js

@@ -0,0 +1,58 @@
+/*
+ * 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.
+ */
+// eslint-disable-next-line import/no-extraneous-dependencies -- test-only factory, sinon is a devDependency
+import sinon from 'sinon';
+/**
+ * Creates a fully-typed IRestApiAdapter backed by sinon stubs.
+ *
+ * All methods required by IRestApiAdapter are provided as sinon stubs,
+ * so TypeScript accepts the return value without any type cast.
+ *
+ * Prefer this factory over `sinon.createStubInstance(RestApiAdapter)` or
+ * hand-rolling partial objects with `as sinon.SinonStubbedInstance<IRestApiAdapter>`.
+ *
+ * @returns StubRestAdapter containing the adapter and all underlying stubs
+ */
+export function createStubRestAdapter() {
+    const describeObjectStub = sinon.stub();
+    const describeGlobalStub = sinon.stub();
+    const getRecordCountStub = sinon.stub();
+    const getRecordCountsStub = sinon.stub();
+    const describeObjectsStub = sinon.stub();
+    const insertRecordStub = sinon.stub();
+    const updateRecordStub = sinon.stub();
+    const deleteRecordStub = sinon.stub();
+    const invalidateCacheStub = sinon.stub();
+    const requestStub = sinon.stub();
+    const adapter = {
+        describeObject: describeObjectStub,
+        describeGlobal: describeGlobalStub,
+        getRecordCount: getRecordCountStub,
+        getRecordCounts: getRecordCountsStub,
+        describeObjects: describeObjectsStub,
+        insertRecord: insertRecordStub,
+        updateRecord: updateRecordStub,
+        deleteRecord: deleteRecordStub,
+        invalidateCache: invalidateCacheStub,
+        request: requestStub,
+    };
+    return {
+        adapter,
+        describeObjectStub,
+        describeGlobalStub,
+        getRecordCountStub,
+        getRecordCountsStub,
+        describeObjectsStub,
+        insertRecordStub,
+        updateRecordStub,
+        deleteRecordStub,
+        invalidateCacheStub,
+        requestStub,
+    };
+}
+//# sourceMappingURL=stub-rest-adapter.js.map

package/lib/adapters/testing/stub-rest-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-rest-adapter.js","sourceRoot":"","sources":["../../../src/adapters/testing/stub-rest-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4GAA4G;AAC5G,OAAO,KAAK,MAAM,OAAO,CAAC;AA0C1B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,kBAAkB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,kBAAkB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,kBAAkB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAoB;QAC/B,cAAc,EAAE,kBAAkB;QAClC,cAAc,EAAE,kBAAkB;QAClC,cAAc,EAAE,kBAAkB;QAClC,eAAe,EAAE,mBAAmB;QACpC,eAAe,EAAE,mBAAmB;QACpC,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,gBAAgB;QAC9B,YAAY,EAAE,gBAAgB;QAC9B,eAAe,EAAE,mBAAmB;QACpC,OAAO,EAAE,WAAW;KACrB,CAAC;IAEF,OAAO;QACL,OAAO;QACP,kBAAkB;QAClB,kBAAkB;QAClB,kBAAkB;QAClB,mBAAmB;QACnB,mBAAmB;QACnB,gBAAgB;QAChB,gBAAgB;QAChB,gBAAgB;QAChB,mBAAmB;QACnB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/lib/adapters/testing/stub-soql-adapter.d.ts

@@ -0,0 +1,56 @@
+import sinon from 'sinon';
+import type { ISoqlQueryAdapter } from '../soql/soql-query-adapter.js';
+/**
+ * Named sinon stubs for a stub-backed ISoqlQueryAdapter.
+ *
+ * Use the individual stubs to configure call behaviour directly with sinon's
+ * `.resolves()`, `.rejects()`, `.onFirstCall()`, etc. — no `as unknown as`
+ * cast is required because the `adapter` property satisfies ISoqlQueryAdapter.
+ *
+ * @example
+ * ```typescript
+ * const stubSoql = createStubSoqlAdapter();
+ * stubSoql.queryStub.resolves(createSuccessResult({ done: true, totalSize: 1, records: [{ Id: '001' }] }));
+ * const service = new MyService(stubSoql.adapter);
+ * ```
+ */
+export type StubSoqlAdapter = {
+    /** The fully-typed ISoqlQueryAdapter backed by sinon stubs */
+    adapter: ISoqlQueryAdapter;
+    /** Stub for adapter.query */
+    queryStub: sinon.SinonStub;
+    /** Stub for adapter.queryAll */
+    queryAllStub: sinon.SinonStub;
+    /** Stub for adapter.queryChunked */
+    queryChunkedStub: sinon.SinonStub;
+};
+/**
+ * Creates a fully-typed ISoqlQueryAdapter backed by sinon stubs.
+ *
+ * All methods required by ISoqlQueryAdapter are provided as sinon stubs,
+ * so TypeScript accepts the return value without any type cast.
+ *
+ * Prefer this factory over hand-rolling `{ query: sinon.stub(), queryAll: sinon.stub(), queryChunked: sinon.stub() }`
+ * partial objects in service unit tests.
+ *
+ * @returns StubSoqlAdapter containing the adapter and all underlying stubs
+ *
+ * @example
+ * ```typescript
+ * import { createStubSoqlAdapter, type StubSoqlAdapter } from '../../../src/adapters/testing/index.js';
+ *
+ * let stubSoql: StubSoqlAdapter;
+ *
+ * beforeEach(() => {
+ *   stubSoql = createStubSoqlAdapter();
+ *   service = new ProfilingDefinitionService(stubSoql.adapter, mockApexAdapter);
+ * });
+ *
+ * it('queries definitions', async () => {
+ *   stubSoql.queryStub.resolves(createSuccessResult({ done: true, totalSize: 0, records: [] }));
+ *   const result = await service.getAll();
+ *   expect(result.success).to.equal(true);
+ * });
+ * ```
+ */
+export declare function createStubSoqlAdapter(): StubSoqlAdapter;

package/lib/adapters/testing/stub-soql-adapter.js

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ */
+// eslint-disable-next-line import/no-extraneous-dependencies -- test-only factory, sinon is a devDependency
+import sinon from 'sinon';
+/**
+ * Creates a fully-typed ISoqlQueryAdapter backed by sinon stubs.
+ *
+ * All methods required by ISoqlQueryAdapter are provided as sinon stubs,
+ * so TypeScript accepts the return value without any type cast.
+ *
+ * Prefer this factory over hand-rolling `{ query: sinon.stub(), queryAll: sinon.stub(), queryChunked: sinon.stub() }`
+ * partial objects in service unit tests.
+ *
+ * @returns StubSoqlAdapter containing the adapter and all underlying stubs
+ *
+ * @example
+ * ```typescript
+ * import { createStubSoqlAdapter, type StubSoqlAdapter } from '../../../src/adapters/testing/index.js';
+ *
+ * let stubSoql: StubSoqlAdapter;
+ *
+ * beforeEach(() => {
+ *   stubSoql = createStubSoqlAdapter();
+ *   service = new ProfilingDefinitionService(stubSoql.adapter, mockApexAdapter);
+ * });
+ *
+ * it('queries definitions', async () => {
+ *   stubSoql.queryStub.resolves(createSuccessResult({ done: true, totalSize: 0, records: [] }));
+ *   const result = await service.getAll();
+ *   expect(result.success).to.equal(true);
+ * });
+ * ```
+ */
+export function createStubSoqlAdapter() {
+    const queryStub = sinon.stub();
+    const queryAllStub = sinon.stub();
+    const queryChunkedStub = sinon.stub();
+    const adapter = {
+        query: queryStub,
+        queryAll: queryAllStub,
+        queryChunked: queryChunkedStub,
+    };
+    return { adapter, queryStub, queryAllStub, queryChunkedStub };
+}
+//# sourceMappingURL=stub-soql-adapter.js.map

package/lib/adapters/testing/stub-soql-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-soql-adapter.js","sourceRoot":"","sources":["../../../src/adapters/testing/stub-soql-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4GAA4G;AAC5G,OAAO,KAAK,MAAM,OAAO,CAAC;AA4B1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,YAAY,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAClC,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAEtC,MAAM,OAAO,GAAsB;QACjC,KAAK,EAAE,SAAS;QAChB,QAAQ,EAAE,YAAY;QACtB,YAAY,EAAE,gBAAgB;KAC/B,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1,71 @@
+/**
+ * Record of a mock adapter method call.
+ */
+export type CallRecord = {
+    /** Name of the method that was called */
+    method: string;
+    /** Arguments passed to the method */
+    args: unknown[];
+    /** Timestamp when the call was made */
+    timestamp: number;
+};
+/**
+ * Configuration for mock adapters.
+ *
+ * @template T The type of the default response
+ */
+export type MockAdapterConfig<T> = {
+    /** Map of input keys to expected responses */
+    responses?: Map<string, T>;
+    /** Map of input keys to errors that should be thrown */
+    errors?: Map<string, Error>;
+    /** Default response when no specific mapping exists */
+    defaultResponse?: T;
+};
+/**
+ * Mock adapter wrapper with call recording and configuration.
+ *
+ * @template T The type of the adapter being mocked
+ */
+export type MockAdapter<T> = {
+    /** The mock adapter instance */
+    adapter: T;
+    /** List of recorded method calls */
+    calls: CallRecord[];
+    /** Resets the call recording history */
+    resetCalls(): void;
+    /** Sets a response for a specific key */
+    setResponse(key: string, response: unknown): void;
+    /** Sets an error for a specific key (returns failure ServiceResult) */
+    setError(key: string, error: Error): void;
+    /**
+     * Sets an exception to throw for a specific key.
+     * Unlike setError (which returns a failure ServiceResult), setThrow causes
+     * the mock to throw an exception, allowing tests to verify service-level
+     * exception handling.
+     */
+    setThrow(key: string, error: Error): void;
+    /** Clears a previously configured exception for a specific key */
+    clearThrow(key: string): void;
+};
+/**
+ * Configuration for mock connection facade.
+ */
+export type MockConnectionConfig = {
+    /** API version to return */
+    version?: string;
+    /** Access token for authentication (required for connection validation) */
+    accessToken?: string;
+    /** Instance URL for the Salesforce org (required for connection validation) */
+    instanceUrl?: string;
+    /** Default query result */
+    defaultQueryResult?: unknown;
+    /** Default describe result */
+    defaultDescribeResult?: unknown;
+    /** Default identity result */
+    defaultIdentity?: {
+        user_id: string;
+        organization_id: string;
+        username: string;
+    };
+};