@salesforce/capg-client 0.1.0-beta.1

package/dist/constants.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CAPG Client Library Constants
+ *
+ * Centralized constants for BPO names, field names, and query strings.
+ * These constants ensure consistency across the library and make it easier
+ * to update if Salesforce schema changes.
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ */
+/**
+ * Salesforce Business Process Object (BPO) Names
+ */
+export declare const BPO_NAMES: {
+    /**
+     * DevopsGovernancePolicy - Core governance policy object
+     *
+     * This BPO stores all CAPG governance policies. When this object does not exist
+     * in an org, governance is considered disabled for that org.
+     */
+    readonly GOVERNANCE_POLICY: "DevopsGovernancePolicy";
+};
+/**
+ * SOQL Query Templates
+ *
+ * Hardcoded SOQL queries to prevent injection vulnerabilities.
+ * All queries use string constants - NO dynamic string construction.
+ *
+ * NOTE: These must be plain string literals (not template literals) to ensure
+ * they are fully evaluated at compile time and can be verified in builds.
+ */
+export declare const SOQL_QUERIES: {
+    /**
+     * Check if governance is enabled by querying for BPO existence
+     *
+     * Returns:
+     * - Query succeeds (totalSize >= 0): governance enabled
+     * - Query throws INVALID_TYPE: governance disabled (BPO doesn't exist)
+     */
+    readonly CHECK_GOVERNANCE_ENABLED: "SELECT Id FROM DevopsGovernancePolicy LIMIT 1";
+    /**
+     * Fetch all policy fields
+     *
+     * Used by PolicyFetcher to retrieve complete policy data.
+     * WHERE clause and ORDER BY are appended dynamically but safely
+     * (using parameterized queries, not string concatenation).
+     */
+    readonly FETCH_POLICIES_BASE: "SELECT Id, PolicyCode, Name, Description, Category, Status, RuleContent, PolicySource, GlobalPolicyVersion, CreatedDate, LastModifiedDate FROM DevopsGovernancePolicy";
+};
+/**
+ * Error Codes
+ *
+ * Salesforce error codes that have special handling in the library.
+ */
+export declare const SALESFORCE_ERROR_CODES: {
+    /**
+     * INVALID_TYPE - Thrown when querying a non-existent sObject
+     *
+     * For CAPG Client, this error means the DevopsGovernancePolicy BPO does not
+     * exist in the org, indicating governance is disabled (not a real error).
+     */
+    readonly INVALID_TYPE: "INVALID_TYPE";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS;IACpB;;;;;OAKG;;CAEK,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;;OAMG;;IAGH;;;;;;OAMG;;CAGK,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;IACjC;;;;;OAKG;;CAEK,CAAC"}

package/dist/constants.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * CAPG Client Library Constants
+ *
+ * Centralized constants for BPO names, field names, and query strings.
+ * These constants ensure consistency across the library and make it easier
+ * to update if Salesforce schema changes.
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ */
+/**
+ * Salesforce Business Process Object (BPO) Names
+ */
+export const BPO_NAMES = {
+    /**
+     * DevopsGovernancePolicy - Core governance policy object
+     *
+     * This BPO stores all CAPG governance policies. When this object does not exist
+     * in an org, governance is considered disabled for that org.
+     */
+    GOVERNANCE_POLICY: 'DevopsGovernancePolicy',
+};
+/**
+ * SOQL Query Templates
+ *
+ * Hardcoded SOQL queries to prevent injection vulnerabilities.
+ * All queries use string constants - NO dynamic string construction.
+ *
+ * NOTE: These must be plain string literals (not template literals) to ensure
+ * they are fully evaluated at compile time and can be verified in builds.
+ */
+export const SOQL_QUERIES = {
+    /**
+     * Check if governance is enabled by querying for BPO existence
+     *
+     * Returns:
+     * - Query succeeds (totalSize >= 0): governance enabled
+     * - Query throws INVALID_TYPE: governance disabled (BPO doesn't exist)
+     */
+    CHECK_GOVERNANCE_ENABLED: 'SELECT Id FROM DevopsGovernancePolicy LIMIT 1',
+    /**
+     * Fetch all policy fields
+     *
+     * Used by PolicyFetcher to retrieve complete policy data.
+     * WHERE clause and ORDER BY are appended dynamically but safely
+     * (using parameterized queries, not string concatenation).
+     */
+    FETCH_POLICIES_BASE: 'SELECT Id, PolicyCode, Name, Description, Category, Status, RuleContent, PolicySource, GlobalPolicyVersion, CreatedDate, LastModifiedDate FROM DevopsGovernancePolicy',
+};
+/**
+ * Error Codes
+ *
+ * Salesforce error codes that have special handling in the library.
+ */
+export const SALESFORCE_ERROR_CODES = {
+    /**
+     * INVALID_TYPE - Thrown when querying a non-existent sObject
+     *
+     * For CAPG Client, this error means the DevopsGovernancePolicy BPO does not
+     * exist in the org, indicating governance is disabled (not a real error).
+     */
+    INVALID_TYPE: 'INVALID_TYPE',
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;;OAKG;IACH,iBAAiB,EAAE,wBAAwB;CACnC,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;;;;;OAMG;IACH,wBAAwB,EAAE,+CAA+C;IAEzE;;;;;;OAMG;IACH,mBAAmB,EACjB,uKAAuK;CACjK,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC;;;;;OAKG;IACH,YAAY,EAAE,cAAc;CACpB,CAAC"}

package/dist/errors/api.d.ts

@@ -0,0 +1,79 @@
+/**
+ * API Error Class
+ *
+ * Thrown when HTTP API calls return error responses (4xx, 5xx).
+ * This error has dynamic behavior based on the HTTP status code:
+ * - 4xx (Client Errors): Not retryable, user actionable
+ * - 5xx (Server Errors): Retryable, not user actionable
+ *
+ * Properties:
+ * - code: 'API_ERROR'
+ * - statusCode: HTTP status code (400-599)
+ * - responseBody: Optional response body for debugging
+ * - isRetryable: true for 5xx, false for 4xx
+ * - isUserActionable: true for 4xx, false for 5xx
+ * - suggestedAction: Dynamic based on status code
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGAPIError(404, 'Policy not found');
+ * throw new CAPGAPIError(500, 'Internal Server Error');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export declare class CAPGAPIError extends CAPGError {
+    /**
+     * HTTP status code (400-599)
+     *
+     * @readonly
+     */
+    readonly statusCode: number;
+    /**
+     * Optional response body for debugging
+     *
+     * @readonly
+     */
+    readonly responseBody?: unknown;
+    /**
+     * Creates a new CAPGAPIError instance
+     *
+     * @param statusCode - HTTP status code (400-599)
+     * @param message - Human-readable error message
+     * @param responseBody - Optional response body for debugging
+     * @param cause - Optional underlying error that caused this API error
+     *
+     * @example
+     * ```typescript
+     * // 404 error (client error - not retryable)
+     * const error404 = new CAPGAPIError(404, 'Policy not found');
+     * console.log(error404.isRetryable); // false
+     * console.log(error404.isUserActionable); // true
+     *
+     * // 500 error (server error - retryable)
+     * const error500 = new CAPGAPIError(500, 'Internal Server Error');
+     * console.log(error500.isRetryable); // true
+     * console.log(error500.isUserActionable); // false
+     *
+     * // With response body
+     * const errorWithBody = new CAPGAPIError(
+     *   400,
+     *   'Invalid surface',
+     *   { error: 'INVALID_SURFACE', message: 'Surface must be one of: vibes, vaas, codey' }
+     * );
+     * ```
+     */
+    constructor(statusCode: number, message: string, responseBody?: unknown, cause?: Error);
+    /**
+     * Get suggested action based on HTTP status code
+     *
+     * @param statusCode - HTTP status code
+     * @returns Suggested action string
+     */
+    private static getSuggestedAction;
+    /**
+     * Serializes the API error to JSON
+     * Includes statusCode and responseBody properties
+     */
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/errors/api.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,qBAAa,YAAa,SAAQ,SAAS;IACzC;;;;OAIG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;;;OAIG;IACH,SAAgB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;gBACgB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK;IAgC7F;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAajC;;;OAGG;IACI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAazC"}

package/dist/errors/api.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * API Error Class
+ *
+ * Thrown when HTTP API calls return error responses (4xx, 5xx).
+ * This error has dynamic behavior based on the HTTP status code:
+ * - 4xx (Client Errors): Not retryable, user actionable
+ * - 5xx (Server Errors): Retryable, not user actionable
+ *
+ * Properties:
+ * - code: 'API_ERROR'
+ * - statusCode: HTTP status code (400-599)
+ * - responseBody: Optional response body for debugging
+ * - isRetryable: true for 5xx, false for 4xx
+ * - isUserActionable: true for 4xx, false for 5xx
+ * - suggestedAction: Dynamic based on status code
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGAPIError(404, 'Policy not found');
+ * throw new CAPGAPIError(500, 'Internal Server Error');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export class CAPGAPIError extends CAPGError {
+    /**
+     * HTTP status code (400-599)
+     *
+     * @readonly
+     */
+    statusCode;
+    /**
+     * Optional response body for debugging
+     *
+     * @readonly
+     */
+    responseBody;
+    /**
+     * Creates a new CAPGAPIError instance
+     *
+     * @param statusCode - HTTP status code (400-599)
+     * @param message - Human-readable error message
+     * @param responseBody - Optional response body for debugging
+     * @param cause - Optional underlying error that caused this API error
+     *
+     * @example
+     * ```typescript
+     * // 404 error (client error - not retryable)
+     * const error404 = new CAPGAPIError(404, 'Policy not found');
+     * console.log(error404.isRetryable); // false
+     * console.log(error404.isUserActionable); // true
+     *
+     * // 500 error (server error - retryable)
+     * const error500 = new CAPGAPIError(500, 'Internal Server Error');
+     * console.log(error500.isRetryable); // true
+     * console.log(error500.isUserActionable); // false
+     *
+     * // With response body
+     * const errorWithBody = new CAPGAPIError(
+     *   400,
+     *   'Invalid surface',
+     *   { error: 'INVALID_SURFACE', message: 'Surface must be one of: vibes, vaas, codey' }
+     * );
+     * ```
+     */
+    constructor(statusCode, message, responseBody, cause) {
+        // Determine if error is retryable based on status code
+        // 5xx errors are server errors and should be retried
+        // 4xx errors are client errors and should not be retried
+        const isRetryable = statusCode >= 500 && statusCode < 600;
+        // Determine if error is user actionable based on status code
+        // 4xx errors require user action to fix (bad request, auth, etc.)
+        // 5xx errors are server issues that users cannot fix
+        const isUserActionable = statusCode >= 400 && statusCode < 500;
+        // Generate suggested action based on status code
+        const suggestedAction = CAPGAPIError.getSuggestedAction(statusCode);
+        super('API_ERROR', message, suggestedAction, cause, isRetryable, isUserActionable);
+        // Set error name to class name for better stack traces
+        this.name = 'CAPGAPIError';
+        // Store status code and response body
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, CAPGAPIError.prototype);
+        // Capture stack trace for debugging
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Get suggested action based on HTTP status code
+     *
+     * @param statusCode - HTTP status code
+     * @returns Suggested action string
+     */
+    static getSuggestedAction(statusCode) {
+        if (statusCode >= 400 && statusCode < 500) {
+            // 4xx - Client errors
+            return 'Check your request parameters and try again';
+        }
+        else if (statusCode >= 500 && statusCode < 600) {
+            // 5xx - Server errors
+            return 'The server encountered an error. Try again later';
+        }
+        else {
+            // Other status codes (shouldn't normally happen)
+            return 'Check the error details and try again';
+        }
+    }
+    /**
+     * Serializes the API error to JSON
+     * Includes statusCode and responseBody properties
+     */
+    toJSON() {
+        const json = super.toJSON();
+        // Always include statusCode
+        json.statusCode = this.statusCode;
+        // Include responseBody if present
+        if (this.responseBody !== undefined) {
+            json.responseBody = this.responseBody;
+        }
+        return json;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/errors/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/errors/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,OAAO,YAAa,SAAQ,SAAS;IACzC;;;;OAIG;IACa,UAAU,CAAS;IAEnC;;;;OAIG;IACa,YAAY,CAAW;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,YAAmB,UAAkB,EAAE,OAAe,EAAE,YAAsB,EAAE,KAAa;QAC3F,uDAAuD;QACvD,qDAAqD;QACrD,yDAAyD;QACzD,MAAM,WAAW,GAAG,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,CAAC;QAE1D,6DAA6D;QAC7D,kEAAkE;QAClE,qDAAqD;QACrD,MAAM,gBAAgB,GAAG,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,CAAC;QAE/D,iDAAiD;QACjD,MAAM,eAAe,GAAG,YAAY,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAEpE,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;QAEnF,uDAAuD;QACvD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,sCAAsC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QAEjC,wDAAwD;QACxD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;QAEpD,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;;;;;OAKG;IACK,MAAM,CAAC,kBAAkB,CAAC,UAAkB;QAClD,IAAI,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;YAC1C,sBAAsB;YACtB,OAAO,6CAA6C,CAAC;QACvD,CAAC;aAAM,IAAI,UAAU,IAAI,GAAG,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;YACjD,sBAAsB;YACtB,OAAO,kDAAkD,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,iDAAiD;YACjD,OAAO,uCAAuC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,MAAM;QACX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAE5B,4BAA4B;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAElC,kCAAkC;QAClC,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/errors/auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Authentication Error Class
+ *
+ * Thrown when authentication fails (HTTP 401 Unauthorized).
+ * This error indicates that the user needs to re-authenticate with the Hub Org.
+ *
+ * Properties:
+ * - code: 'AUTH_ERROR'
+ * - isRetryable: false (user must re-authenticate)
+ * - isUserActionable: true (user can fix by logging in)
+ * - suggestedAction: CLI command to re-authenticate
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGAuthError('Session expired');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export declare class CAPGAuthError extends CAPGError {
+    /**
+     * Creates a new CAPGAuthError instance
+     *
+     * @param message - Human-readable error message
+     * @param cause - Optional underlying error that caused this auth error
+     *
+     * @example
+     * ```typescript
+     * const httpError = new Error('401 Unauthorized');
+     * const authError = new CAPGAuthError('Authentication failed', httpError);
+     * console.error(authError.suggestedAction); // "Re-login to Hub Org: sf org login web"
+     * ```
+     */
+    constructor(message: string, cause?: Error);
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/errors/auth.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,qBAAa,aAAc,SAAQ,SAAS;IAC1C;;;;;;;;;;;;OAYG;gBACgB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAqBlD"}

package/dist/errors/auth.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Authentication Error Class
+ *
+ * Thrown when authentication fails (HTTP 401 Unauthorized).
+ * This error indicates that the user needs to re-authenticate with the Hub Org.
+ *
+ * Properties:
+ * - code: 'AUTH_ERROR'
+ * - isRetryable: false (user must re-authenticate)
+ * - isUserActionable: true (user can fix by logging in)
+ * - suggestedAction: CLI command to re-authenticate
+ *
+ * @example
+ * ```typescript
+ * throw new CAPGAuthError('Session expired');
+ * ```
+ */
+import { CAPGError } from './base.js';
+export class CAPGAuthError extends CAPGError {
+    /**
+     * Creates a new CAPGAuthError instance
+     *
+     * @param message - Human-readable error message
+     * @param cause - Optional underlying error that caused this auth error
+     *
+     * @example
+     * ```typescript
+     * const httpError = new Error('401 Unauthorized');
+     * const authError = new CAPGAuthError('Authentication failed', httpError);
+     * console.error(authError.suggestedAction); // "Re-login to Hub Org: sf org login web"
+     * ```
+     */
+    constructor(message, cause) {
+        super('AUTH_ERROR', message, 'Re-login to Hub Org: sf org login web', cause, false, // Not retryable - user must re-authenticate
+        true);
+        // Set error name to class name for better stack traces
+        this.name = 'CAPGAuthError';
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, CAPGAuthError.prototype);
+        // Capture stack trace for debugging
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/errors/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/errors/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1C;;;;;;;;;;;;OAYG;IACH,YAAmB,OAAe,EAAE,KAAa;QAC/C,KAAK,CACH,YAAY,EACZ,OAAO,EACP,uCAAuC,EACvC,KAAK,EACL,KAAK,EAAE,4CAA4C;QACnD,IAAI,CACL,CAAC;QAEF,uDAAuD;QACvD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAE5B,wDAAwD;QACxD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;QAErD,oCAAoC;QACpC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;CACF"}

package/dist/errors/base.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Base Error Class for CAPG Client
+ *
+ * This is the foundation error class for all CAPG-specific errors.
+ * All other error classes should extend this base class.
+ *
+ * Features:
+ * - Error code for programmatic error type identification
+ * - Error cause chaining for tracking root causes
+ * - Retry flags for automatic retry logic
+ * - User actionability flags for UX decisions
+ * - Request ID for distributed tracing
+ * - Suggested actions for user guidance
+ * - Stack trace preservation
+ * - JSON serialization support
+ *
+ * @example
+ * ```typescript
+ * const error = new CAPGError(
+ *   'OPERATION_FAILED',
+ *   'Failed to complete operation',
+ *   'Try again later'
+ * );
+ * console.error(error.toJSON());
+ * ```
+ */
+export declare class CAPGError extends Error {
+    /**
+     * Error code for programmatic identification
+     *
+     * @readonly
+     */
+    readonly code: string;
+    /**
+     * The underlying error that caused this error (if any)
+     *
+     * @readonly
+     */
+    readonly cause?: Error;
+    /**
+     * Whether this error is retryable (transient failure)
+     *
+     * @readonly
+     */
+    readonly isRetryable: boolean;
+    /**
+     * Whether user action can resolve this error
+     *
+     * @readonly
+     */
+    readonly isUserActionable: boolean;
+    /**
+     * Request ID for distributed tracing (optional)
+     */
+    requestId?: string;
+    /**
+     * Suggested action to resolve the error (optional)
+     *
+     * @readonly
+     */
+    readonly suggestedAction?: string;
+    /**
+     * Creates a new CAPGError instance
+     *
+     * @param code - Error code for programmatic identification
+     * @param message - Human-readable error message
+     * @param suggestedAction - Optional suggested action to resolve the error
+     * @param cause - Optional underlying error that caused this error
+     * @param isRetryable - Whether this error is retryable (default: false)
+     * @param isUserActionable - Whether user action can resolve this error (default: true)
+     *
+     * @example
+     * ```typescript
+     * const error = new CAPGError(
+     *   'CONFIG_ERROR',
+     *   'Invalid configuration',
+     *   'Check your config file',
+     *   originalError,
+     *   false,
+     *   true
+     * );
+     * ```
+     */
+    constructor(code: string, message: string, suggestedAction?: string, cause?: Error, isRetryable?: boolean, isUserActionable?: boolean);
+    /**
+     * Serializes the error to a JSON object
+     *
+     * This method is called automatically by JSON.stringify().
+     * It includes all error properties and recursively serializes
+     * the cause chain.
+     *
+     * @returns JSON representation of the error
+     *
+     * @example
+     * ```typescript
+     * const error = new CAPGError('TEST_ERROR', 'Test message');
+     * const json = error.toJSON();
+     * console.log(JSON.stringify(json, null, 2));
+     * ```
+     */
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=base.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;;;OAIG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAgB,KAAK,CAAC,EAAE,KAAK,CAAC;IAE9B;;;;OAIG;IACH,SAAgB,WAAW,EAAE,OAAO,CAAC;IAErC;;;;OAIG;IACH,SAAgB,gBAAgB,EAAE,OAAO,CAAC;IAE1C;;OAEG;IACI,SAAS,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBAED,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,eAAe,CAAC,EAAE,MAAM,EACxB,KAAK,CAAC,EAAE,KAAK,EACb,WAAW,GAAE,OAAe,EAC5B,gBAAgB,GAAE,OAAc;IA0BlC;;;;;;;;;;;;;;;OAeG;IACI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAuCzC"}