@salesforce/capg-client 0.1.0-beta.1

package/dist/errors/validation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Validation Error Class
+ *
+ * Thrown when client-side input validation fails.
+ * This error indicates that the user provided invalid input that must be corrected.
+ *
+ * Properties:
+ * - code: 'VALIDATION_ERROR'
+ * - isRetryable: false (bad input won't succeed on retry)
+ * - isUserActionable: true (user can fix by providing valid input)
+ * - fieldName: The field that failed validation
+ * - invalidValue: The invalid value that was provided (optional)
+ * - suggestedAction: Guidance on how to fix the validation error
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGValidationError('surface', 'Invalid surface type', 'invalid_surface');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export declare class CAPGValidationError extends CAPGError {
+    /**
+     * The field name that failed validation
+     *
+     * @readonly
+     */
+    readonly fieldName: string;
+    /**
+     * The invalid value that was provided (optional)
+     * Can be any type (string, number, object, etc.)
+     *
+     * @readonly
+     */
+    readonly invalidValue?: unknown;
+    /**
+     * Creates a new CAPGValidationError instance
+     *
+     * @param fieldName - The field name that failed validation
+     * @param message - Human-readable error message
+     * @param invalidValue - Optional invalid value that was provided
+     *
+     * @example
+     * ```typescript
+     * // Simple validation error
+     * const error1 = new CAPGValidationError('surface', 'Invalid surface type');
+     *
+     * // With invalid value
+     * const error2 = new CAPGValidationError(
+     *   'surface',
+     *   'Surface must be one of: vibes, vaas, codey',
+     *   'invalid_surface'
+     * );
+     *
+     * // With complex invalid value
+     * const error3 = new CAPGValidationError(
+     *   'options',
+     *   'Invalid options object',
+     *   { surface: 'vibes', scope: { type: 'INVALID' } }
+     * );
+     * ```
+     */
+    constructor(fieldName: string, message: string, invalidValue?: unknown);
+    /**
+     * Serializes the validation error to JSON
+     * Includes fieldName and invalidValue properties
+     */
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=validation.d.ts.map

package/dist/errors/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/errors/validation.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,qBAAa,mBAAoB,SAAQ,SAAS;IAChD;;;;OAIG;IACH,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;gBACgB,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO;IA0B7E;;;OAGG;IACI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAazC"}

package/dist/errors/validation.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Validation Error Class
+ *
+ * Thrown when client-side input validation fails.
+ * This error indicates that the user provided invalid input that must be corrected.
+ *
+ * Properties:
+ * - code: 'VALIDATION_ERROR'
+ * - isRetryable: false (bad input won't succeed on retry)
+ * - isUserActionable: true (user can fix by providing valid input)
+ * - fieldName: The field that failed validation
+ * - invalidValue: The invalid value that was provided (optional)
+ * - suggestedAction: Guidance on how to fix the validation error
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGValidationError('surface', 'Invalid surface type', 'invalid_surface');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export class CAPGValidationError extends CAPGError {
+    /**
+     * The field name that failed validation
+     *
+     * @readonly
+     */
+    fieldName;
+    /**
+     * The invalid value that was provided (optional)
+     * Can be any type (string, number, object, etc.)
+     *
+     * @readonly
+     */
+    invalidValue;
+    /**
+     * Creates a new CAPGValidationError instance
+     *
+     * @param fieldName - The field name that failed validation
+     * @param message - Human-readable error message
+     * @param invalidValue - Optional invalid value that was provided
+     *
+     * @example
+     * ```typescript
+     * // Simple validation error
+     * const error1 = new CAPGValidationError('surface', 'Invalid surface type');
+     *
+     * // With invalid value
+     * const error2 = new CAPGValidationError(
+     *   'surface',
+     *   'Surface must be one of: vibes, vaas, codey',
+     *   'invalid_surface'
+     * );
+     *
+     * // With complex invalid value
+     * const error3 = new CAPGValidationError(
+     *   'options',
+     *   'Invalid options object',
+     *   { surface: 'vibes', scope: { type: 'INVALID' } }
+     * );
+     * ```
+     */
+    constructor(fieldName, message, invalidValue) {
+        super('VALIDATION_ERROR', message, `Check the '${fieldName}' field and provide a valid value`, undefined, false, // Not retryable - bad input won't succeed on retry
+        true);
+        // Set error name to class name for better stack traces
+        this.name = 'CAPGValidationError';
+        // Store field name and invalid value
+        this.fieldName = fieldName;
+        this.invalidValue = invalidValue;
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, CAPGValidationError.prototype);
+        // Capture stack trace for debugging
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Serializes the validation error to JSON
+     * Includes fieldName and invalidValue properties
+     */
+    toJSON() {
+        const json = super.toJSON();
+        // Always include fieldName
+        json.fieldName = this.fieldName;
+        // Include invalidValue if present (even if null or undefined)
+        if (this.invalidValue !== undefined) {
+            json.invalidValue = this.invalidValue;
+        }
+        return json;
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/errors/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/errors/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,OAAO,mBAAoB,SAAQ,SAAS;IAChD;;;;OAIG;IACa,SAAS,CAAS;IAElC;;;;;OAKG;IACa,YAAY,CAAW;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,YAAmB,SAAiB,EAAE,OAAe,EAAE,YAAsB;QAC3E,KAAK,CACH,kBAAkB,EAClB,OAAO,EACP,cAAc,SAAS,mCAAmC,EAC1D,SAAS,EACT,KAAK,EAAE,mDAAmD;QAC1D,IAAI,CACL,CAAC;QAEF,uDAAuD;QACvD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAElC,qCAAqC;QACrC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QAEjC,wDAAwD;QACxD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;QAE3D,oCAAoC;QACpC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,MAAM;QACX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAE5B,2BAA2B;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAEhC,8DAA8D;QAC9D,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACxC,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @salesforce/capg-client
+ *
+ * TypeScript client library for CAPG (Coding Agent Policy Governance) data fetching
+ *
+ * @packageDocumentation
+ */
+export { CAPGClient } from './client.js';
+export type { CAPGClientOptions } from './client.js';
+export * from './types/index.js';
+export * from './errors/index.js';
+export { OrgPrefChecker } from './org-pref-checker.js';
+export { PolicyFetcher } from './policy-fetcher.js';
+export { ConnectAPIClient } from './connect-api-client.js';
+export { BPO_NAMES, SOQL_QUERIES, SALESFORCE_ERROR_CODES } from './constants.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * @salesforce/capg-client
+ *
+ * TypeScript client library for CAPG (Coding Agent Policy Governance) data fetching
+ *
+ * @packageDocumentation
+ */
+// Export main client class
+export { CAPGClient } from './client.js';
+// Export types
+export * from './types/index.js';
+// Export error classes
+export * from './errors/index.js';
+// Export OrgPrefChecker
+export { OrgPrefChecker } from './org-pref-checker.js';
+// Export PolicyFetcher
+export { PolicyFetcher } from './policy-fetcher.js';
+// Export ConnectAPIClient
+export { ConnectAPIClient } from './connect-api-client.js';
+// Export constants (BPO names, SOQL queries)
+export { BPO_NAMES, SOQL_QUERIES, SALESFORCE_ERROR_CODES } from './constants.js';
+// TODO: Export interfaces
+// export * from './interfaces/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,2BAA2B;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,eAAe;AACf,cAAc,kBAAkB,CAAC;AAEjC,uBAAuB;AACvB,cAAc,mBAAmB,CAAC;AAElC,wBAAwB;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,uBAAuB;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,0BAA0B;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,6CAA6C;AAC7C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEjF,0BAA0B;AAC1B,yCAAyC"}

package/dist/org-pref-checker.d.ts

@@ -0,0 +1,129 @@
+/**
+ * OrgPrefChecker - Check if CAPG governance is enabled for an org
+ *
+ * This module provides the first gate in the governance flow - checking if
+ * CAPG governance is enabled by querying for the DevopsGovernancePolicy BPO.
+ * When governance is disabled (BPO does not exist), this enables a 75% faster
+ * early return path.
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ */
+import { Connection } from '@salesforce/core';
+/**
+ * OrgPrefChecker - Check governance preferences for a Salesforce org
+ *
+ * Queries for the DevopsGovernancePolicy BPO to determine if governance is
+ * enabled. This is the FIRST GATE in the governance flow - when governance
+ * is disabled, consumers can skip policy/tool fetching (75% faster).
+ *
+ * @example Basic usage with org alias
+ * ```typescript
+ * const checker = new OrgPrefChecker();
+ * const enabled = await checker.checkGovernanceEnabled('myHubOrg');
+ *
+ * if (!enabled) {
+ *   console.log('Governance disabled, skipping policy fetch');
+ *   return;
+ * }
+ *
+ * // Only fetch if enabled
+ * const policies = await client.fetchPolicies(...);
+ * ```
+ *
+ * @example Usage with Connection object
+ * ```typescript
+ * import { Connection, Org } from '@salesforce/core';
+ *
+ * const org = await Org.create({ aliasOrUsername: 'myHubOrg' });
+ * const connection = org.getConnection();
+ *
+ * const checker = new OrgPrefChecker();
+ * const enabled = await checker.checkGovernanceEnabled(connection);
+ * ```
+ *
+ * @example With custom logger
+ * ```typescript
+ * const checker = new OrgPrefChecker({
+ *   logger: {
+ *     debug: (msg) => console.log('[DEBUG]', msg),
+ *     error: (msg) => console.error('[ERROR]', msg)
+ *   }
+ * });
+ *
+ * const enabled = await checker.checkGovernanceEnabled('myHubOrg');
+ * ```
+ *
+ * @since v1.0.0
+ */
+export declare class OrgPrefChecker {
+    /**
+     * Optional logger for debug/error output
+     */
+    private logger?;
+    /**
+     * Create a new OrgPrefChecker instance
+     *
+     * @param options - Configuration options
+     * @param options.logger - Optional logger with debug/error methods
+     *
+     * @example
+     * ```typescript
+     * // Without logger
+     * const checker = new OrgPrefChecker();
+     *
+     * // With logger
+     * const checker = new OrgPrefChecker({
+     *   logger: {
+     *     debug: (msg) => console.log(msg),
+     *     error: (msg) => console.error(msg)
+     *   }
+     * });
+     * ```
+     */
+    constructor(options?: {
+        logger?: {
+            debug: (message: string) => void;
+            error: (message: string) => void;
+        };
+    });
+    /**
+     * Check if CAPG governance is enabled for the specified org
+     *
+     * Queries for the DevopsGovernancePolicy BPO:
+     * - Returns true if query succeeds (BPO exists, governance enabled)
+     * - Returns false if INVALID_TYPE error (BPO does not exist, governance disabled)
+     * - Throws for auth/connection/API errors (never for governance state)
+     *
+     * **Performance**: This is the FIRST GATE - when governance is disabled,
+     * consumers can skip policy/tool fetching (75% faster session initialization).
+     *
+     * **NO HUB ORG AUTO-DETECTION**: This method requires an explicit org alias or
+     * Connection object. There is no automatic Hub Org resolution. This design aligns
+     * with Connect API architecture where org resolution is managed by the consumer
+     * framework, not the library.
+     *
+     * @param orgAliasOrConnection - Explicit org alias (string) or Connection object.
+     * REQUIRED - no auto-detection or Hub Org resolution performed.
+     * @returns true if governance enabled, false if disabled (BPO does not exist)
+     *
+     * @throws {@link CAPGAuthError} - Authentication failure (isRetryable = false)
+     * @throws {@link CAPGNetworkError} - Network/connection error (isRetryable = true)
+     * @throws {@link CAPGAPIError} - API error (isRetryable depends on status code)
+     * @throws {@link CAPGValidationError} - Invalid org alias or org not found
+     *
+     * @since v1.0.0
+     */
+    checkGovernanceEnabled(orgAliasOrConnection: string | Connection): Promise<boolean>;
+    /**
+     * Resolve org alias or Connection to a Connection object
+     *
+     * @param orgAliasOrConnection - Org alias (string) or Connection object
+     * @returns Connection object
+     * @throws CAPGValidationError if alias is invalid or org not found
+     *
+     * @internal
+     */
+    private resolveConnection;
+}
+//# sourceMappingURL=org-pref-checker.d.ts.map

package/dist/org-pref-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-pref-checker.d.ts","sourceRoot":"","sources":["../src/org-pref-checker.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,UAAU,EAAO,MAAM,kBAAkB,CAAC;AAmBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,CAGb;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;gBACgB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;YAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;SAAE,CAAA;KAAE;IAIhH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,sBAAsB,CAAC,oBAAoB,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAgChG;;;;;;;;OAQG;YACW,iBAAiB;CAsBhC"}

package/dist/org-pref-checker.js

@@ -0,0 +1,193 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * OrgPrefChecker - Check if CAPG governance is enabled for an org
+ *
+ * This module provides the first gate in the governance flow - checking if
+ * CAPG governance is enabled by querying for the DevopsGovernancePolicy BPO.
+ * When governance is disabled (BPO does not exist), this enables a 75% faster
+ * early return path.
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ */
+/* eslint-disable class-methods-use-this, @typescript-eslint/no-unsafe-call, @typescript-eslint/member-ordering */
+import { Org } from '@salesforce/core';
+import { CAPGValidationError } from './errors/index.js';
+import { classifyError } from './utils/error-classifier.js';
+import { SOQL_QUERIES, SALESFORCE_ERROR_CODES } from './constants.js';
+/**
+ * Check if an error represents an INVALID_TYPE SOQL error
+ * (indicates the BPO object does not exist in the org)
+ *
+ * @internal
+ */
+function isInvalidTypeError(error) {
+    if (error == null || typeof error !== 'object') {
+        return false;
+    }
+    const err = error;
+    return err.errorCode === SALESFORCE_ERROR_CODES.INVALID_TYPE || err.name === SALESFORCE_ERROR_CODES.INVALID_TYPE;
+}
+/**
+ * OrgPrefChecker - Check governance preferences for a Salesforce org
+ *
+ * Queries for the DevopsGovernancePolicy BPO to determine if governance is
+ * enabled. This is the FIRST GATE in the governance flow - when governance
+ * is disabled, consumers can skip policy/tool fetching (75% faster).
+ *
+ * @example Basic usage with org alias
+ * ```typescript
+ * const checker = new OrgPrefChecker();
+ * const enabled = await checker.checkGovernanceEnabled('myHubOrg');
+ *
+ * if (!enabled) {
+ *   console.log('Governance disabled, skipping policy fetch');
+ *   return;
+ * }
+ *
+ * // Only fetch if enabled
+ * const policies = await client.fetchPolicies(...);
+ * ```
+ *
+ * @example Usage with Connection object
+ * ```typescript
+ * import { Connection, Org } from '@salesforce/core';
+ *
+ * const org = await Org.create({ aliasOrUsername: 'myHubOrg' });
+ * const connection = org.getConnection();
+ *
+ * const checker = new OrgPrefChecker();
+ * const enabled = await checker.checkGovernanceEnabled(connection);
+ * ```
+ *
+ * @example With custom logger
+ * ```typescript
+ * const checker = new OrgPrefChecker({
+ *   logger: {
+ *     debug: (msg) => console.log('[DEBUG]', msg),
+ *     error: (msg) => console.error('[ERROR]', msg)
+ *   }
+ * });
+ *
+ * const enabled = await checker.checkGovernanceEnabled('myHubOrg');
+ * ```
+ *
+ * @since v1.0.0
+ */
+export class OrgPrefChecker {
+    /**
+     * Optional logger for debug/error output
+     */
+    logger;
+    /**
+     * Create a new OrgPrefChecker instance
+     *
+     * @param options - Configuration options
+     * @param options.logger - Optional logger with debug/error methods
+     *
+     * @example
+     * ```typescript
+     * // Without logger
+     * const checker = new OrgPrefChecker();
+     *
+     * // With logger
+     * const checker = new OrgPrefChecker({
+     *   logger: {
+     *     debug: (msg) => console.log(msg),
+     *     error: (msg) => console.error(msg)
+     *   }
+     * });
+     * ```
+     */
+    constructor(options) {
+        this.logger = options?.logger;
+    }
+    /**
+     * Check if CAPG governance is enabled for the specified org
+     *
+     * Queries for the DevopsGovernancePolicy BPO:
+     * - Returns true if query succeeds (BPO exists, governance enabled)
+     * - Returns false if INVALID_TYPE error (BPO does not exist, governance disabled)
+     * - Throws for auth/connection/API errors (never for governance state)
+     *
+     * **Performance**: This is the FIRST GATE - when governance is disabled,
+     * consumers can skip policy/tool fetching (75% faster session initialization).
+     *
+     * **NO HUB ORG AUTO-DETECTION**: This method requires an explicit org alias or
+     * Connection object. There is no automatic Hub Org resolution. This design aligns
+     * with Connect API architecture where org resolution is managed by the consumer
+     * framework, not the library.
+     *
+     * @param orgAliasOrConnection - Explicit org alias (string) or Connection object.
+     * REQUIRED - no auto-detection or Hub Org resolution performed.
+     * @returns true if governance enabled, false if disabled (BPO does not exist)
+     *
+     * @throws {@link CAPGAuthError} - Authentication failure (isRetryable = false)
+     * @throws {@link CAPGNetworkError} - Network/connection error (isRetryable = true)
+     * @throws {@link CAPGAPIError} - API error (isRetryable depends on status code)
+     * @throws {@link CAPGValidationError} - Invalid org alias or org not found
+     *
+     * @since v1.0.0
+     */
+    async checkGovernanceEnabled(orgAliasOrConnection) {
+        // Step 1: Resolve to Connection
+        const connection = await this.resolveConnection(orgAliasOrConnection);
+        const username = connection.getUsername() ?? 'unknown';
+        this.logger?.debug(`Checking governance via SOQL on org ${username}`);
+        try {
+            // Query for DevopsGovernancePolicy BPO existence
+            const result = await connection.query(SOQL_QUERIES.CHECK_GOVERNANCE_ENABLED);
+            // BPO exists - governance is enabled (even if no records, the object is present)
+            this.logger?.debug(`BPO exists (totalSize=${result?.totalSize ?? 0}), governance enabled`);
+            return true;
+        }
+        catch (error) {
+            // INVALID_TYPE means BPO does not exist - governance is disabled (not an error)
+            if (isInvalidTypeError(error)) {
+                this.logger?.debug('BPO does not exist (INVALID_TYPE), governance disabled');
+                return false;
+            }
+            // Real error - classify and throw
+            // Note: classifyError automatically redacts credentials from username
+            const classified = classifyError(error, {
+                username,
+                operation: 'checking governance preferences',
+            });
+            throw classified;
+        }
+    }
+    /**
+     * Resolve org alias or Connection to a Connection object
+     *
+     * @param orgAliasOrConnection - Org alias (string) or Connection object
+     * @returns Connection object
+     * @throws CAPGValidationError if alias is invalid or org not found
+     *
+     * @internal
+     */
+    async resolveConnection(orgAliasOrConnection) {
+        // If already a Connection, return it
+        if (typeof orgAliasOrConnection === 'object' && orgAliasOrConnection !== null) {
+            // Duck-type check - if it has query and getUsername, treat as Connection
+            if ('query' in orgAliasOrConnection && 'getUsername' in orgAliasOrConnection) {
+                return orgAliasOrConnection;
+            }
+        }
+        // Validate alias
+        const alias = orgAliasOrConnection.trim();
+        if (!alias) {
+            throw new CAPGValidationError('orgAlias', 'Org alias cannot be empty');
+        }
+        try {
+            const org = await Org.create({ aliasOrUsername: alias });
+            return org.getConnection();
+        }
+        catch {
+            throw new CAPGValidationError('orgAlias', `Invalid org alias '${alias}'. Ensure org is authenticated.`, alias);
+        }
+    }
+}
+//# sourceMappingURL=org-pref-checker.js.map

package/dist/org-pref-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-pref-checker.js","sourceRoot":"","sources":["../src/org-pref-checker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,kHAAkH;AAElH,OAAO,EAAc,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEtE;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,KAA8C,CAAC;IAC3D,OAAO,GAAG,CAAC,SAAS,KAAK,sBAAsB,CAAC,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,sBAAsB,CAAC,YAAY,CAAC;AACnH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,OAAO,cAAc;IACzB;;OAEG;IACK,MAAM,CAGZ;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAmB,OAA6F;QAC9G,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,KAAK,CAAC,sBAAsB,CAAC,oBAAyC;QAC3E,gCAAgC;QAChC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;QAEtE,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC;QACvD,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,uCAAuC,QAAQ,EAAE,CAAC,CAAC;QAEtE,IAAI,CAAC;YACH,iDAAiD;YACjD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,wBAAwB,CAAC,CAAC;YAE7E,iFAAiF;YACjF,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,yBAAyB,MAAM,EAAE,SAAS,IAAI,CAAC,uBAAuB,CAAC,CAAC;YAE3F,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,gFAAgF;YAChF,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,wDAAwD,CAAC,CAAC;gBAC7E,OAAO,KAAK,CAAC;YACf,CAAC;YAED,kCAAkC;YAClC,sEAAsE;YACtE,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,EAAE;gBACtC,QAAQ;gBACR,SAAS,EAAE,iCAAiC;aAC7C,CAAC,CAAC;YACH,MAAM,UAAU,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,iBAAiB,CAAC,oBAAyC;QACvE,qCAAqC;QACrC,IAAI,OAAO,oBAAoB,KAAK,QAAQ,IAAI,oBAAoB,KAAK,IAAI,EAAE,CAAC;YAC9E,yEAAyE;YACzE,IAAI,OAAO,IAAI,oBAAoB,IAAI,aAAa,IAAI,oBAAoB,EAAE,CAAC;gBAC7E,OAAO,oBAAoB,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,iBAAiB;QACjB,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,mBAAmB,CAAC,UAAU,EAAE,2BAA2B,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;YACzD,OAAO,GAAG,CAAC,aAAa,EAAE,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,mBAAmB,CAAC,UAAU,EAAE,sBAAsB,KAAK,iCAAiC,EAAE,KAAK,CAAC,CAAC;QACjH,CAAC;IACH,CAAC;CACF"}