@salesforce/capg-client 0.1.0-beta.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were last updated on March 24, 2026, and constitute a legally binding agreement between you and Salesforce. If you do not agree to these Terms of Use, do not install or use the Software. The Software may link to third-party software components licensed under various open source licenses ("Open Source Components"). These Terms of Use pertain solely to Salesforce's proprietary code in the Software. It does not alter or extend any rights or obligations regarding the Open Source Components. For clarity, your use of the Open Source Components is governed by the terms of the applicable open source license(s). You are solely responsible for complying with the terms and conditions of those open source licenses.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free copyright license to reproduce, revocable, publicly display, publicly perform, sublicense, and distribute the Software and derivative works subject to these Terms. These Terms shall be included in all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce reserves all rights, title, and interest in and to all intellectual property subsisting in the Software. No rights are granted to you hereunder other than as expressly set forth herein. Users residing in countries on the United States Office of Foreign Assets Control sanction list, or which are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you are responsible. The Software may contain bugs, errors and incompatibilities and is made available on an AS IS basis without support, updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or discontinue, the Software (or any part thereof) with or without notice. You agree that Salesforce shall not be liable to you or to any third party for any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or proceeding made or brought against Salesforce by a third party arising out of or accruing from (a) your use of the Software, and (b) any application you develop with the Software that infringes any copyright, trademark, trade secret, trade dress, patent, or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce from any damages, attorney fees, and costs finally awarded against Salesforce as a result of, or for any amounts paid by Salesforce under a settlement approved by you in writing of, a Claim Against Salesforce, provided Salesforce (x) promptly gives you written notice of the Claim Against Salesforce, (y) gives you sole control of the defense and settlement of the Claim Against Salesforce (except that you may not settle any Claim Against Salesforce unless it unconditionally releases Salesforce of all liability), and (z) gives you all reasonable assistance, at your expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA, OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of the State of California, without regard to its conflicts of laws rules. Each party hereby consents to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California to adjudicate any dispute arising out of or relating to these Terms of Use and the download, installation, and/or use of the Software. Except as expressly stated herein, these Terms of Use constitute the entire agreement between the parties, and supersede all prior and contemporaneous agreements, proposals, or representations, written or oral, concerning their subject matter. No modification, amendment, or waiver of any provision of these Terms of Use shall be effective unless it is by an update to these Terms of Use that Salesforce makes available, or is in writing and signed by the party against whom the modification, amendment, or waiver is to be asserted.
+
+Data Privacy: Salesforce may collect, process, and store device, system, and other information related to your use of the Software. This information includes, but is not limited to, IP address, user metrics, and other data ("Usage Data"). Salesforce may use Usage Data for analytics, product development, and marketing purposes. You acknowledge that files generated in conjunction with the Software may contain sensitive or confidential data, and you are solely responsible for anonymizing and protecting such data.

package/README.md

@@ -0,0 +1,122 @@
+# CAPG Client Library
+
+TypeScript client library for fetching governance policies from CAPG (Coding Agent Policy Governance) Hub Org.
+
+## Overview
+
+The CAPG Client Library provides a simple, type-safe interface for Salesforce coding agents (AFV, VaaS, Codey) to fetch governance policies and tool configurations from the CAPG Hub Org.
+
+## Features
+
+- Simple unified API via `CAPGClient` class
+- Fetch governance policies from Salesforce orgs via Connect API
+- Check if governance is enabled (first gate for performance)
+- Explicit org alias required for all operations (no auto-detection)
+- `Result<T, E>` pattern for type-safe error handling (no thrown exceptions)
+- AFV pattern support (early return optimization)
+- Comprehensive input validation
+- Credential redaction in logs and errors
+- 96%+ test coverage
+
+## Installation
+
+```bash
+npm install @salesforce/capg-client
+```
+
+## Quick Start
+
+The library provides a simple unified API via `CAPGClient`. All operations use the `Result<T, E>` pattern for type-safe error handling.
+
+```typescript
+import { CAPGClient, isOk, isErr } from '@salesforce/capg-client';
+
+const client = new CAPGClient();
+
+// Step 1: Check if governance is enabled (FIRST GATE - early return optimization)
+const isEnabled = await client.checkGovernanceEnabled('myHubOrg');
+
+if (!isEnabled) {
+  console.log('Governance disabled, skipping policy fetch');
+  return; // Early return - 75% faster when governance is disabled
+}
+
+// Step 2: Fetch policies (only if governance is enabled)
+const result = await client.fetchPolicies({}, 'myHubOrg');
+
+if (isOk(result)) {
+  const { policies } = result.value;
+  console.log(`Fetched ${policies.length} policies`);
+
+  // Access policy data
+  policies.forEach((policy) => {
+    console.log(`${policy.policyCode}: ${policy.name}`);
+    console.log(policy.ruleContent); // Markdown rule for LLM
+  });
+} else {
+  console.error(`Error: ${result.error.message}`);
+  console.error(`Suggested action: ${result.error.suggestedAction}`);
+}
+```
+
+### AFV Pattern (Recommended)
+
+Always check governance first to enable early returns:
+
+```typescript
+const client = new CAPGClient();
+
+// FIRST GATE: Check governance (never throws)
+const isEnabled = await client.checkGovernanceEnabled(orgAlias);
+if (!isEnabled) return; // Skip policy fetch if disabled
+
+// Only fetch if enabled
+const result = await client.fetchPolicies({}, orgAlias);
+if (isOk(result)) {
+  // Use policies
+  console.log(result.value.policies);
+}
+```
+
+### With Custom Logger
+
+```typescript
+const client = new CAPGClient({
+  logger: {
+    debug: (msg) => console.log(`[DEBUG] ${msg}`),
+    error: (msg) => console.error(`[ERROR] ${msg}`),
+  },
+});
+```
+
+## Documentation
+
+- [API Documentation](docs/api/)
+- [Architecture](docs/architecture/)
+- [Testing Guide](docs/testing/MANUAL_TESTS.md)
+- [Security Assessment](docs/architecture/SECURITY_ASSESSMENT.md)
+- [Epic & Work Items](docs/implementation/EPIC_CAPG_Client_Library.md)
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions, workflow, and contributing guidelines.
+
+### Running Tests
+
+```bash
+# Unit tests (automated, with mocks)
+npm test
+
+# Coverage report
+npm run test:coverage
+
+# Manual integration tests (requires SF CLI auth)
+npm run build
+node manual-tests/test-org-pref-checker.js
+```
+
+**Manual Tests**: Integration tests that validate library functionality against real Salesforce orgs. See [`docs/testing/MANUAL_TESTS.md`](docs/testing/MANUAL_TESTS.md) for comprehensive documentation.
+
+## License
+
+See LICENSE file.

package/dist/client.d.ts

@@ -0,0 +1,86 @@
+import { Result } from './types/result.js';
+import type { FetchPoliciesOptions, PolicyResponse } from './types/index.js';
+import { CAPGError } from './errors/index.js';
+/**
+ * Logger interface for optional logging integration
+ * All sensitive data (access tokens, credentials) is automatically redacted.
+ */
+export type Logger = {
+    debug: (msg: string) => void;
+    error: (msg: string) => void;
+};
+/**
+ * Options for constructing CAPGClient
+ */
+export type CAPGClientOptions = {
+    /** Optional logger for debug and error messages */
+    logger?: Logger;
+    /** Optional timeout for HTTP requests in milliseconds (default: 30000) */
+    timeout?: number;
+};
+/**
+ * CAPGClient - Main client for fetching CAPG governance data
+ *
+ * Provides two primary operations:
+ * 1. checkGovernanceEnabled() - First gate check (returns boolean, never throws)
+ * 2. fetchPolicies() - Fetch policies via Connect API (returns Result, never throws)
+ *
+ * @example Recommended usage pattern
+ * ```typescript
+ * const client = new CAPGClient();
+ * const isEnabled = await client.checkGovernanceEnabled('myHubOrg');
+ * if (!isEnabled) return; // Early return if disabled
+ *
+ * const result = await client.fetchPolicies({}, 'myHubOrg');
+ * if (isOk(result)) console.log(result.value.policies);
+ * ```
+ *
+ * @since v0.2.0
+ */
+export declare class CAPGClient {
+    private logger?;
+    /**
+     * Create a new CAPGClient instance
+     *
+     * @param options - Configuration options (logger, timeout)
+     */
+    constructor(options?: CAPGClientOptions);
+    /**
+     * Check if CAPG governance is enabled for the specified org
+     *
+     * **FIRST GATE**: Call this BEFORE fetchPolicies() for 75% faster early return.
+     * **NEVER THROWS**: Catches ALL errors and returns false (logs errors if logger provided).
+     *
+     * @param orgAlias - Org alias or username (e.g., 'myHubOrg', 'devhub@example.com')
+     * @returns true if governance enabled, false if disabled or error
+     *
+     * @since v0.2.0
+     */
+    checkGovernanceEnabled(orgAlias: string): Promise<boolean>;
+    /**
+     * Fetch governance policies from Connect API
+     *
+     * Makes HTTP POST to /services/data/v62.0/connect/governance/policies via ConnectAPIClient.
+     * Defaults includeDisabled to false (only ENABLED policies). Never throws - returns Result.
+     *
+     * @param options - Fetch options (includeDisabled, defaults to false)
+     * @param orgAlias - Org alias or username (e.g., 'myHubOrg', 'devhub@example.com')
+     * @returns Result containing PolicyResponse on success, or CAPGError on failure
+     *
+     * @since v0.2.0
+     */
+    fetchPolicies(options: FetchPoliciesOptions, orgAlias: string): Promise<Result<PolicyResponse, CAPGError>>;
+    /**
+     * Create a Connection object from an org alias
+     *
+     * Validates the alias, creates an Org object using Org.create(), and returns
+     * the Connection. Returns Result type for consistent error handling.
+     *
+     * @param orgAlias - Org alias or username
+     * @returns Result with Connection or CAPGValidationError
+     *
+     * @internal
+     */
+    private createConnection;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,MAAM,EAAW,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAuB,MAAM,mBAAmB,CAAC;AAInE;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAC,CAAS;IAExB;;;;OAIG;gBACgB,OAAO,CAAC,EAAE,iBAAiB;IAM9C;;;;;;;;;;OAUG;IACU,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgCvE;;;;;;;;;;;OAWG;IACU,aAAa,CACxB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IA4C7C;;;;;;;;;;OAUG;YAEW,gBAAgB;CAgB/B"}

package/dist/client.js

@@ -0,0 +1,167 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * CAPGClient - Main client class for CAPG (Coding Agent Policy Governance)
+ *
+ * This is the primary entry point for fetching governance policies from Salesforce orgs.
+ * Provides a simple, type-safe API that combines org preference checking and policy fetching.
+ *
+ * Epic: EPIC_CAPG_Client_Library_Refactor_Named_Credential, Work Item: WI-6
+ *
+ * @packageDocumentation
+ * @since v0.2.0
+ */
+import { Org } from '@salesforce/core';
+import { ok, err } from './types/result.js';
+import { CAPGValidationError } from './errors/index.js';
+import { ConnectAPIClient } from './connect-api-client.js';
+import { OrgPrefChecker } from './org-pref-checker.js';
+/**
+ * CAPGClient - Main client for fetching CAPG governance data
+ *
+ * Provides two primary operations:
+ * 1. checkGovernanceEnabled() - First gate check (returns boolean, never throws)
+ * 2. fetchPolicies() - Fetch policies via Connect API (returns Result, never throws)
+ *
+ * @example Recommended usage pattern
+ * ```typescript
+ * const client = new CAPGClient();
+ * const isEnabled = await client.checkGovernanceEnabled('myHubOrg');
+ * if (!isEnabled) return; // Early return if disabled
+ *
+ * const result = await client.fetchPolicies({}, 'myHubOrg');
+ * if (isOk(result)) console.log(result.value.policies);
+ * ```
+ *
+ * @since v0.2.0
+ */
+export class CAPGClient {
+    logger;
+    /**
+     * Create a new CAPGClient instance
+     *
+     * @param options - Configuration options (logger, timeout)
+     */
+    constructor(options) {
+        this.logger = options?.logger;
+        // Note: timeout option is reserved for future use with ConnectAPIClient
+        // Currently not used but kept in the API for forward compatibility
+    }
+    /**
+     * Check if CAPG governance is enabled for the specified org
+     *
+     * **FIRST GATE**: Call this BEFORE fetchPolicies() for 75% faster early return.
+     * **NEVER THROWS**: Catches ALL errors and returns false (logs errors if logger provided).
+     *
+     * @param orgAlias - Org alias or username (e.g., 'myHubOrg', 'devhub@example.com')
+     * @returns true if governance enabled, false if disabled or error
+     *
+     * @since v0.2.0
+     */
+    async checkGovernanceEnabled(orgAlias) {
+        try {
+            // Validate orgAlias
+            const trimmedAlias = orgAlias.trim();
+            if (!trimmedAlias) {
+                // Empty alias - return false, don't call Org.create
+                return false;
+            }
+            this.logger?.debug(`Checking governance enabled for org: ${trimmedAlias}`);
+            // Create connection
+            const connectionResult = await this.createConnection(trimmedAlias);
+            if (!connectionResult.ok) {
+                // Connection creation failed - return false
+                return false;
+            }
+            const connection = connectionResult.value;
+            // Use OrgPrefChecker to check governance
+            const checker = new OrgPrefChecker({ logger: this.logger });
+            const isEnabled = await checker.checkGovernanceEnabled(connection);
+            return isEnabled;
+        }
+        catch (error) {
+            // Catch ALL errors - never throw
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.error(`Failed to check governance enabled: ${errorMessage}`);
+            return false;
+        }
+    }
+    /**
+     * Fetch governance policies from Connect API
+     *
+     * Makes HTTP POST to /services/data/v62.0/connect/governance/policies via ConnectAPIClient.
+     * Defaults includeDisabled to false (only ENABLED policies). Never throws - returns Result.
+     *
+     * @param options - Fetch options (includeDisabled, defaults to false)
+     * @param orgAlias - Org alias or username (e.g., 'myHubOrg', 'devhub@example.com')
+     * @returns Result containing PolicyResponse on success, or CAPGError on failure
+     *
+     * @since v0.2.0
+     */
+    async fetchPolicies(options, orgAlias) {
+        try {
+            // Validate orgAlias
+            const trimmedAlias = orgAlias.trim();
+            if (!trimmedAlias) {
+                const validationError = new CAPGValidationError('orgAlias', 'orgAlias cannot be empty');
+                this.logger?.error(`Failed to fetch policies: ${validationError.message}`);
+                return err(validationError);
+            }
+            this.logger?.debug(`Fetching policies for org: ${trimmedAlias}`);
+            // Create connection
+            const connectionResult = await this.createConnection(trimmedAlias);
+            if (!connectionResult.ok) {
+                this.logger?.error(`Failed to fetch policies: ${connectionResult.error.message}`);
+                return err(connectionResult.error);
+            }
+            const connection = connectionResult.value;
+            // Create ConnectAPIClient and fetch policies
+            const client = new ConnectAPIClient(connection, { logger: this.logger });
+            const fetchOptions = {
+                includeDisabled: options.includeDisabled ?? false,
+            };
+            const result = await client.fetchPolicies(fetchOptions);
+            // Log result
+            if (result.ok) {
+                this.logger?.debug(`Successfully fetched ${result.value.policies.length} policies`);
+            }
+            else {
+                this.logger?.error(`Failed to fetch policies: ${result.error.message}`);
+            }
+            return result;
+        }
+        catch (error) {
+            // Catch unexpected errors and convert to CAPGValidationError
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const validationError = new CAPGValidationError('orgAlias', `Unexpected error: ${errorMessage}`);
+            this.logger?.error(`Failed to fetch policies: ${validationError.message}`);
+            return err(validationError);
+        }
+    }
+    /**
+     * Create a Connection object from an org alias
+     *
+     * Validates the alias, creates an Org object using Org.create(), and returns
+     * the Connection. Returns Result type for consistent error handling.
+     *
+     * @param orgAlias - Org alias or username
+     * @returns Result with Connection or CAPGValidationError
+     *
+     * @internal
+     */
+    // eslint-disable-next-line class-methods-use-this
+    async createConnection(orgAlias) {
+        try {
+            const org = await Org.create({ aliasOrUsername: orgAlias });
+            const connection = org.getConnection();
+            return ok(connection);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return err(new CAPGValidationError('orgAlias', `Invalid org alias '${orgAlias}'. Ensure org is authenticated. ${errorMessage}`, orgAlias));
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAc,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAU,EAAE,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAa,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAqBvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,UAAU;IACb,MAAM,CAAU;IAExB;;;;OAIG;IACH,YAAmB,OAA2B;QAC5C,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;QAC9B,wEAAwE;QACxE,mEAAmE;IACrE,CAAC;IAED;;;;;;;;;;OAUG;IACI,KAAK,CAAC,sBAAsB,CAAC,QAAgB;QAClD,IAAI,CAAC;YACH,oBAAoB;YACpB,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,oDAAoD;gBACpD,OAAO,KAAK,CAAC;YACf,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,wCAAwC,YAAY,EAAE,CAAC,CAAC;YAE3E,oBAAoB;YACpB,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;YACnE,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,CAAC;gBACzB,4CAA4C;gBAC5C,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC;YAE1C,yCAAyC;YACzC,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5D,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC;YAEnE,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,iCAAiC;YACjC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,uCAAuC,YAAY,EAAE,CAAC,CAAC;YAC1E,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,aAAa,CACxB,OAA6B,EAC7B,QAAgB;QAEhB,IAAI,CAAC;YACH,oBAAoB;YACpB,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,MAAM,eAAe,GAAG,IAAI,mBAAmB,CAAC,UAAU,EAAE,0BAA0B,CAAC,CAAC;gBACxF,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC3E,OAAO,GAAG,CAAC,eAAe,CAAC,CAAC;YAC9B,CAAC;YAED,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,8BAA8B,YAAY,EAAE,CAAC,CAAC;YAEjE,oBAAoB;YACpB,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;YACnE,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,CAAC;gBACzB,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;gBAClF,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACrC,CAAC;YACD,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC;YAE1C,6CAA6C;YAC7C,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACzE,MAAM,YAAY,GAAyB;gBACzC,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,KAAK;aAClD,CAAC;YACF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;YAExD,aAAa;YACb,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,wBAAwB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,WAAW,CAAC,CAAC;YACtF,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,6DAA6D;YAC7D,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,MAAM,eAAe,GAAG,IAAI,mBAAmB,CAAC,UAAU,EAAE,qBAAqB,YAAY,EAAE,CAAC,CAAC;YACjG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;YAC3E,OAAO,GAAG,CAAC,eAAe,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,kDAAkD;IAC1C,KAAK,CAAC,gBAAgB,CAAC,QAAgB;QAC7C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC5D,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE,CAAC;YACvC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5E,OAAO,GAAG,CACR,IAAI,mBAAmB,CACrB,UAAU,EACV,sBAAsB,QAAQ,mCAAmC,YAAY,EAAE,EAC/E,QAAQ,CACT,CACF,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/connect-api-client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ConnectAPIClient - Connect API Client for fetching CAPG policies
+ *
+ * REST API client for fetching DevOps Governance policies from Salesforce Connect API endpoints.
+ * Handles authentication, error classification, and provides cache metadata for consumers.
+ *
+ * Epic: EPIC_CAPG_Client_Library_Refactor_Named_Credential, Work Item: WI-4
+ *
+ * @packageDocumentation
+ * @since v0.2.0
+ */
+import { Connection } from '@salesforce/core';
+import { Result } from './types/result.js';
+import { FetchPoliciesOptions, PolicyResponse } from './types/index.js';
+import { CAPGError } from './errors/index.js';
+/**
+ * Logger interface for optional logging integration
+ * All sensitive data (access tokens, credentials) is automatically redacted.
+ */
+export type Logger = {
+    debug: (msg: string) => void;
+    error: (msg: string) => void;
+};
+/**
+ * Options for constructing ConnectAPIClient
+ */
+export type ConnectAPIClientOptions = {
+    /** Optional logger for debug and error messages */
+    logger?: Logger;
+};
+/**
+ * ConnectAPIClient - Client for fetching policies via Connect API
+ *
+ * @example Basic usage
+ * ```typescript
+ * const connection = await Connection.create({ authInfo });
+ * const client = new ConnectAPIClient(connection);
+ * const result = await client.fetchPolicies({ includeDisabled: false });
+ * if (isOk(result)) {
+ *   console.log(`Fetched ${result.value.policies.length} policies`);
+ * }
+ * ```
+ */
+export declare class ConnectAPIClient {
+    private connection;
+    private logger?;
+    constructor(connection: Connection, options?: ConnectAPIClientOptions);
+    /**
+     * Fetch DevOps Governance policies from Connect API
+     *
+     * Makes POST request to: {instanceUrl}/services/data/v62.0/connect/governance/policies
+     *
+     * @param options - Fetch options (includeDisabled)
+     * @returns Result containing PolicyResponse on success, or CAPGError on failure
+     *
+     * @throws Never throws - all errors returned as Result.err()
+     *
+     * **Error Types**:
+     * - `CAPGAuthError` (401/403) - Authentication/authorization failed, re-login required (non-retryable)
+     * - `CAPGNetworkError` (ETIMEDOUT/ECONNREFUSED) - Network issue (retryable)
+     * - `CAPGAPIError` (4xx/5xx) - API error with status code
+     *
+     * @example
+     * ```typescript
+     * const result = await client.fetchPolicies({ includeDisabled: false });
+     * if (isOk(result)) {
+     *   console.log(`Fetched ${result.value.policies.length} policies`);
+     * } else if (result.error instanceof CAPGAuthError) {
+     *   console.error('Re-authentication required');
+     * }
+     * ```
+     */
+    fetchPolicies(options: FetchPoliciesOptions): Promise<Result<PolicyResponse, CAPGError>>;
+    /**
+     * Generate stable cache key for consumer caching
+     * Format: connect_policies_{username}_{includeDisabled}
+     *
+     * @internal
+     */
+    private generateCacheKey;
+}
+//# sourceMappingURL=connect-api-client.d.ts.map

package/dist/connect-api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-api-client.d.ts","sourceRoot":"","sources":["../src/connect-api-client.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAW,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEL,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAK5E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAgDrG;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAMzB"}

package/dist/connect-api-client.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { ok, err } from './types/result.js';
+import { classifyError } from './utils/error-classifier.js';
+/**
+ * ConnectAPIClient - Client for fetching policies via Connect API
+ *
+ * @example Basic usage
+ * ```typescript
+ * const connection = await Connection.create({ authInfo });
+ * const client = new ConnectAPIClient(connection);
+ * const result = await client.fetchPolicies({ includeDisabled: false });
+ * if (isOk(result)) {
+ *   console.log(`Fetched ${result.value.policies.length} policies`);
+ * }
+ * ```
+ */
+export class ConnectAPIClient {
+    connection;
+    logger;
+    constructor(connection, options) {
+        this.connection = connection;
+        this.logger = options?.logger;
+    }
+    /**
+     * Fetch DevOps Governance policies from Connect API
+     *
+     * Makes POST request to: {instanceUrl}/services/data/v62.0/connect/governance/policies
+     *
+     * @param options - Fetch options (includeDisabled)
+     * @returns Result containing PolicyResponse on success, or CAPGError on failure
+     *
+     * @throws Never throws - all errors returned as Result.err()
+     *
+     * **Error Types**:
+     * - `CAPGAuthError` (401/403) - Authentication/authorization failed, re-login required (non-retryable)
+     * - `CAPGNetworkError` (ETIMEDOUT/ECONNREFUSED) - Network issue (retryable)
+     * - `CAPGAPIError` (4xx/5xx) - API error with status code
+     *
+     * @example
+     * ```typescript
+     * const result = await client.fetchPolicies({ includeDisabled: false });
+     * if (isOk(result)) {
+     *   console.log(`Fetched ${result.value.policies.length} policies`);
+     * } else if (result.error instanceof CAPGAuthError) {
+     *   console.error('Re-authentication required');
+     * }
+     * ```
+     */
+    async fetchPolicies(options) {
+        try {
+            const username = this.connection.getUsername();
+            const usernameStr = username ?? 'unknown';
+            const includeDisabled = options.includeDisabled ?? false;
+            const endpoint = `/services/data/v67.0/connect/governance/policies?includeDisabled=${includeDisabled}`;
+            this.logger?.debug(`Fetching policies from Connect API: ${endpoint}`);
+            // Make REAL HTTP call to Connect API using Salesforce Connection
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const response = await this.connection.request({
+                method: 'GET',
+                url: endpoint,
+            });
+            // Extract policies from response (empty array if not present)
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+            const policies = Array.isArray(response.policies) ? response.policies : [];
+            const policyResponse = {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                policies,
+                fetchedAt: new Date(),
+                source: 'rest',
+                cacheKey: this.generateCacheKey(options),
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+                totalCount: policies.length,
+                expiresAt: undefined, // Connection.request() doesn't expose headers
+                etag: undefined,
+            };
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            this.logger?.debug(`Successfully fetched ${policies.length} policies from Connect API for org: ${usernameStr}`);
+            return ok(policyResponse);
+        }
+        catch (error) {
+            // Classify and return error
+            const capgError = classifyError(error, {
+                username: this.connection.getUsername(),
+                operation: 'fetching policies via Connect API',
+            });
+            this.logger?.error(`Failed to fetch policies: ${capgError.message}`);
+            return err(capgError);
+        }
+    }
+    /**
+     * Generate stable cache key for consumer caching
+     * Format: connect_policies_{username}_{includeDisabled}
+     *
+     * @internal
+     */
+    generateCacheKey(options) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const username = this.connection.getUsername() ?? 'unknown';
+        const includeDisabled = options.includeDisabled ?? false;
+        return `connect_policies_${username}_${includeDisabled}`;
+    }
+}
+//# sourceMappingURL=connect-api-client.js.map

package/dist/connect-api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-api-client.js","sourceRoot":"","sources":["../src/connect-api-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,OAAO,EAAU,EAAE,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAmB5D;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,gBAAgB;IACnB,UAAU,CAAa;IACvB,MAAM,CAAU;IAExB,YAAmB,UAAsB,EAAE,OAAiC;QAC1E,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,aAAa,CAAC,OAA6B;QACtD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,WAAW,GAAG,QAAQ,IAAI,SAAS,CAAC;YAC1C,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;YACzD,MAAM,QAAQ,GAAG,oEAAoE,eAAe,EAAE,CAAC;YAEvG,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,uCAAuC,QAAQ,EAAE,CAAC,CAAC;YAEtE,iEAAiE;YACjE,mEAAmE;YACnE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAC7C,MAAM,EAAE,KAAK;gBACb,GAAG,EAAE,QAAQ;aACd,CAAC,CAAC;YAEH,8DAA8D;YAC9D,mJAAmJ;YACnJ,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAE,QAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,QAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAE7F,MAAM,cAAc,GAAmB;gBACrC,mEAAmE;gBACnE,QAAQ;gBACR,SAAS,EAAE,IAAI,IAAI,EAAE;gBACrB,MAAM,EAAE,MAAe;gBACvB,QAAQ,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC;gBACxC,+GAA+G;gBAC/G,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,SAAS,EAAE,SAAS,EAAE,8CAA8C;gBACpE,IAAI,EAAE,SAAS;aAChB,CAAC;YAEF,sEAAsE;YACtE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,wBAAwB,QAAQ,CAAC,MAAM,uCAAuC,WAAW,EAAE,CAAC,CAAC;YAEhH,OAAO,EAAE,CAAC,cAAc,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,4BAA4B;YAC5B,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE;gBACrC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE;gBACvC,SAAS,EAAE,mCAAmC;aAC/C,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,6BAA6B,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;YACrE,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,gBAAgB,CAAC,OAA6B;QACpD,mEAAmE;QACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC;QAC5D,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC;QACzD,OAAO,oBAAoB,QAAQ,IAAI,eAAe,EAAE,CAAC;IAC3D,CAAC;CACF"}