@salesforce/capg-client 0.1.0-beta.1

package/dist/types/result.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Result type - discriminated union representing success or failure
+ *
+ * A Result<T, E> is either:
+ * - { ok: true, value: T } - success case with value of type T
+ * - { ok: false, error: E } - failure case with error of type E
+ *
+ * The `ok` field is the discriminant that enables type narrowing.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type (defaults to Error)
+ *
+ * @example
+ * ```typescript
+ * const success: Result<number, string> = { ok: true, value: 42 };
+ * const failure: Result<number, string> = { ok: false, error: 'failed' };
+ * ```
+ */
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Creates a successful result
+ *
+ * @typeParam T - Success value type
+ * @param value - The success value
+ * @returns Result in success state
+ *
+ * @example
+ * ```typescript
+ * const result = ok(42);
+ * // result: Result<number, never>
+ * // { ok: true, value: 42 }
+ * ```
+ *
+ * @example With complex types
+ * ```typescript
+ * const result = ok({ id: 1, name: 'test' });
+ * // result: Result<{ id: number, name: string }, never>
+ * ```
+ */
+export declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Creates a failed result
+ *
+ * @typeParam E - Error type
+ * @param error - The error value
+ * @returns Result in error state
+ *
+ * @example
+ * ```typescript
+ * const result = err('Something went wrong');
+ * // result: Result<never, string>
+ * // { ok: false, error: 'Something went wrong' }
+ * ```
+ *
+ * @example With Error objects
+ * ```typescript
+ * const result = err(new Error('Network timeout'));
+ * // result: Result<never, Error>
+ * ```
+ */
+export declare function err<E>(error: E): Result<never, E>;
+/**
+ * Type guard to check if result is successful
+ *
+ * Narrows the Result type to the success case, allowing safe access to `.value`.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to check
+ * @returns True if result is successful
+ *
+ * @example
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ *
+ * if (isOk(result)) {
+ *   console.log(result.value); // TypeScript knows result.value exists
+ * }
+ * ```
+ */
+export declare function isOk<T, E>(result: Result<T, E>): result is {
+    ok: true;
+    value: T;
+};
+/**
+ * Type guard to check if result is failed
+ *
+ * Narrows the Result type to the error case, allowing safe access to `.error`.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to check
+ * @returns True if result is failed
+ *
+ * @example
+ * ```typescript
+ * const result: Result<number, string> = err('failed');
+ *
+ * if (isErr(result)) {
+ *   console.error(result.error); // TypeScript knows result.error exists
+ * }
+ * ```
+ */
+export declare function isErr<T, E>(result: Result<T, E>): result is {
+    ok: false;
+    error: E;
+};
+/**
+ * Extracts the value from a successful result or throws an error
+ *
+ * WARNING: This function throws on error results. Use `unwrapOr()` or `match()`
+ * for safer alternatives.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to unwrap
+ * @returns The success value
+ * @throws CAPGError if result is failed
+ *
+ * @example Success case
+ * ```typescript
+ * const result = ok(42);
+ * const value = unwrap(result); // 42
+ * ```
+ *
+ * @example Error case
+ * ```typescript
+ * const result = err('failed');
+ * const value = unwrap(result); // throws CAPGError
+ * ```
+ */
+export declare function unwrap<T, E>(result: Result<T, E>): T;
+/**
+ * Extracts the value from a result or returns a default value
+ *
+ * This is a safer alternative to `unwrap()` that never throws.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to unwrap
+ * @param defaultValue - Value to return if result is failed
+ * @returns The success value or default value
+ *
+ * @example
+ * ```typescript
+ * const result1 = ok(42);
+ * unwrapOr(result1, 0); // 42
+ *
+ * const result2 = err('failed');
+ * unwrapOr(result2, 0); // 0
+ * ```
+ */
+export declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * Transforms the success value of a result
+ *
+ * If the result is successful, applies the transform function to the value.
+ * If the result is failed, returns the error unchanged.
+ *
+ * @typeParam T - Input success value type
+ * @typeParam U - Output success value type
+ * @typeParam E - Error type
+ * @param result - Result to transform
+ * @param fn - Transform function
+ * @returns Result with transformed value or original error
+ *
+ * @example Basic transformation
+ * ```typescript
+ * const result = ok(42);
+ * const doubled = map(result, (x) => x * 2);
+ * // doubled: Result<number, never> = ok(84)
+ * ```
+ *
+ * @example Type transformation
+ * ```typescript
+ * const result = ok(42);
+ * const formatted = map(result, (x) => `Value: ${x}`);
+ * // formatted: Result<string, never> = ok('Value: 42')
+ * ```
+ *
+ * @example Error case (unchanged)
+ * ```typescript
+ * const result: Result<number, string> = err('failed');
+ * const doubled = map(result, (x) => x * 2);
+ * // doubled: Result<number, string> = err('failed')
+ * ```
+ */
+export declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Transforms the error value of a result
+ *
+ * If the result is failed, applies the transform function to the error.
+ * If the result is successful, returns the value unchanged.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Input error type
+ * @typeParam F - Output error type
+ * @param result - Result to transform
+ * @param fn - Transform function for errors
+ * @returns Result with original value or transformed error
+ *
+ * @example Basic error transformation
+ * ```typescript
+ * const result: Result<number, string> = err('error');
+ * const withError = mapErr(result, (e) => new Error(e));
+ * // withError: Result<number, Error> = err(Error('error'))
+ * ```
+ *
+ * @example Success case (unchanged)
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ * const mapped = mapErr(result, (e) => new Error(e));
+ * // mapped: Result<number, Error> = ok(42)
+ * ```
+ *
+ * @example Enriching errors
+ * ```typescript
+ * const result: Result<number, number> = err(404);
+ * const enriched = mapErr(result, (code) => ({
+ *   status: code,
+ *   message: 'Not Found'
+ * }));
+ * // enriched: Result<number, { status: number, message: string }>
+ * ```
+ */
+export declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/**
+ * Pattern matching for exhaustive handling of Result cases
+ *
+ * Forces explicit handling of both success and error cases. Both handlers
+ * must return the same type.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @typeParam U - Return type (must be same for both handlers)
+ * @param result - Result to match against
+ * @param handlers - Object with ok and err handler functions
+ * @returns Result of the executed handler
+ *
+ * @example Basic matching
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ * const message = match(result, {
+ *   ok: (value) => `Success: ${value}`,
+ *   err: (error) => `Error: ${error}`
+ * });
+ * // message: 'Success: 42'
+ * ```
+ *
+ * @example With side effects
+ * ```typescript
+ * match(result, {
+ *   ok: (value) => {
+ *     console.log(`Got value: ${value}`);
+ *     return value;
+ *   },
+ *   err: (error) => {
+ *     console.error(`Got error: ${error}`);
+ *     return 0;
+ *   }
+ * });
+ * ```
+ *
+ * @example Complex return types
+ * ```typescript
+ * const output = match(result, {
+ *   ok: (point) => ({ x: point.x * 2, y: point.y * 2 }),
+ *   err: () => ({ x: 0, y: 0 })
+ * });
+ * ```
+ */
+export declare function match<T, E, U>(result: Result<T, E>, handlers: {
+    ok: (value: T) => U;
+    err: (error: E) => U;
+}): U;
+//# sourceMappingURL=result.d.ts.map

package/dist/types/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAEhD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEjF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CA6BpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAKvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAMpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAMvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,QAAQ,EAAE;IACR,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACpB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CACtB,GACA,CAAC,CAMH"}

package/dist/types/result.js

@@ -0,0 +1,351 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Result Type Pattern
+ *
+ * A type-safe, functional approach to error handling that makes success and
+ * failure cases explicit in the type system. This eliminates the need for
+ * try-catch blocks and forces consumers to handle both success and error cases.
+ *
+ * Benefits:
+ * - Type-safe error handling (errors are values, not exceptions)
+ * - Forces explicit handling of both success and error cases
+ * - Composable with map/mapErr for transformations
+ * - Pattern matching with match() for exhaustive case handling
+ * - No hidden control flow (no try-catch)
+ *
+ * @example Basic usage
+ * ```typescript
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return err('Division by zero');
+ *   }
+ *   return ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (isOk(result)) {
+ *   console.log(result.value); // 5
+ * } else {
+ *   console.error(result.error); // 'Division by zero'
+ * }
+ * ```
+ *
+ * @example Transformations
+ * ```typescript
+ * const result = ok(42);
+ * const doubled = map(result, (x) => x * 2); // ok(84)
+ * const formatted = map(doubled, (x) => `Value: ${x}`); // ok('Value: 84')
+ * ```
+ *
+ * @example Pattern matching
+ * ```typescript
+ * const message = match(result, {
+ *   ok: (value) => `Success: ${value}`,
+ *   err: (error) => `Error: ${error}`
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ */
+import { CAPGError } from '../errors/base.js';
+/**
+ * Creates a successful result
+ *
+ * @typeParam T - Success value type
+ * @param value - The success value
+ * @returns Result in success state
+ *
+ * @example
+ * ```typescript
+ * const result = ok(42);
+ * // result: Result<number, never>
+ * // { ok: true, value: 42 }
+ * ```
+ *
+ * @example With complex types
+ * ```typescript
+ * const result = ok({ id: 1, name: 'test' });
+ * // result: Result<{ id: number, name: string }, never>
+ * ```
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Creates a failed result
+ *
+ * @typeParam E - Error type
+ * @param error - The error value
+ * @returns Result in error state
+ *
+ * @example
+ * ```typescript
+ * const result = err('Something went wrong');
+ * // result: Result<never, string>
+ * // { ok: false, error: 'Something went wrong' }
+ * ```
+ *
+ * @example With Error objects
+ * ```typescript
+ * const result = err(new Error('Network timeout'));
+ * // result: Result<never, Error>
+ * ```
+ */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Type guard to check if result is successful
+ *
+ * Narrows the Result type to the success case, allowing safe access to `.value`.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to check
+ * @returns True if result is successful
+ *
+ * @example
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ *
+ * if (isOk(result)) {
+ *   console.log(result.value); // TypeScript knows result.value exists
+ * }
+ * ```
+ */
+export function isOk(result) {
+    return result.ok === true;
+}
+/**
+ * Type guard to check if result is failed
+ *
+ * Narrows the Result type to the error case, allowing safe access to `.error`.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to check
+ * @returns True if result is failed
+ *
+ * @example
+ * ```typescript
+ * const result: Result<number, string> = err('failed');
+ *
+ * if (isErr(result)) {
+ *   console.error(result.error); // TypeScript knows result.error exists
+ * }
+ * ```
+ */
+export function isErr(result) {
+    return result.ok === false;
+}
+/**
+ * Extracts the value from a successful result or throws an error
+ *
+ * WARNING: This function throws on error results. Use `unwrapOr()` or `match()`
+ * for safer alternatives.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to unwrap
+ * @returns The success value
+ * @throws CAPGError if result is failed
+ *
+ * @example Success case
+ * ```typescript
+ * const result = ok(42);
+ * const value = unwrap(result); // 42
+ * ```
+ *
+ * @example Error case
+ * ```typescript
+ * const result = err('failed');
+ * const value = unwrap(result); // throws CAPGError
+ * ```
+ */
+export function unwrap(result) {
+    if (result.ok) {
+        return result.value;
+    }
+    // Type assertion: we know result.ok is false, so error exists
+    const error = result.error;
+    if (error instanceof CAPGError) {
+        throw error;
+    }
+    if (error instanceof Error) {
+        throw new CAPGError('RESULT_UNWRAP_ERROR', error.message, 
+        // Suggestion: Guide developers to use safe patterns (isOk check or unwrapOr)
+        'Check the result before unwrapping or use unwrapOr()', error);
+    }
+    // Error is not an Error object (string, number, etc.)
+    throw new CAPGError('RESULT_UNWRAP_ERROR', `Unwrap failed: ${String(error)}`, 
+    // Suggestion: Guide developers to use safe patterns (isOk check or unwrapOr)
+    'Check the result before unwrapping or use unwrapOr()');
+}
+/**
+ * Extracts the value from a result or returns a default value
+ *
+ * This is a safer alternative to `unwrap()` that never throws.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @param result - Result to unwrap
+ * @param defaultValue - Value to return if result is failed
+ * @returns The success value or default value
+ *
+ * @example
+ * ```typescript
+ * const result1 = ok(42);
+ * unwrapOr(result1, 0); // 42
+ *
+ * const result2 = err('failed');
+ * unwrapOr(result2, 0); // 0
+ * ```
+ */
+export function unwrapOr(result, defaultValue) {
+    if (result.ok) {
+        return result.value;
+    }
+    return defaultValue;
+}
+/**
+ * Transforms the success value of a result
+ *
+ * If the result is successful, applies the transform function to the value.
+ * If the result is failed, returns the error unchanged.
+ *
+ * @typeParam T - Input success value type
+ * @typeParam U - Output success value type
+ * @typeParam E - Error type
+ * @param result - Result to transform
+ * @param fn - Transform function
+ * @returns Result with transformed value or original error
+ *
+ * @example Basic transformation
+ * ```typescript
+ * const result = ok(42);
+ * const doubled = map(result, (x) => x * 2);
+ * // doubled: Result<number, never> = ok(84)
+ * ```
+ *
+ * @example Type transformation
+ * ```typescript
+ * const result = ok(42);
+ * const formatted = map(result, (x) => `Value: ${x}`);
+ * // formatted: Result<string, never> = ok('Value: 42')
+ * ```
+ *
+ * @example Error case (unchanged)
+ * ```typescript
+ * const result: Result<number, string> = err('failed');
+ * const doubled = map(result, (x) => x * 2);
+ * // doubled: Result<number, string> = err('failed')
+ * ```
+ */
+export function map(result, fn) {
+    if (result.ok) {
+        return ok(fn(result.value));
+    }
+    // Type assertion: result.ok is false, so error exists
+    return err(result.error);
+}
+/**
+ * Transforms the error value of a result
+ *
+ * If the result is failed, applies the transform function to the error.
+ * If the result is successful, returns the value unchanged.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Input error type
+ * @typeParam F - Output error type
+ * @param result - Result to transform
+ * @param fn - Transform function for errors
+ * @returns Result with original value or transformed error
+ *
+ * @example Basic error transformation
+ * ```typescript
+ * const result: Result<number, string> = err('error');
+ * const withError = mapErr(result, (e) => new Error(e));
+ * // withError: Result<number, Error> = err(Error('error'))
+ * ```
+ *
+ * @example Success case (unchanged)
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ * const mapped = mapErr(result, (e) => new Error(e));
+ * // mapped: Result<number, Error> = ok(42)
+ * ```
+ *
+ * @example Enriching errors
+ * ```typescript
+ * const result: Result<number, number> = err(404);
+ * const enriched = mapErr(result, (code) => ({
+ *   status: code,
+ *   message: 'Not Found'
+ * }));
+ * // enriched: Result<number, { status: number, message: string }>
+ * ```
+ */
+export function mapErr(result, fn) {
+    if (result.ok) {
+        return ok(result.value);
+    }
+    // Type assertion: result.ok is false, so error exists
+    return err(fn(result.error));
+}
+/**
+ * Pattern matching for exhaustive handling of Result cases
+ *
+ * Forces explicit handling of both success and error cases. Both handlers
+ * must return the same type.
+ *
+ * @typeParam T - Success value type
+ * @typeParam E - Error type
+ * @typeParam U - Return type (must be same for both handlers)
+ * @param result - Result to match against
+ * @param handlers - Object with ok and err handler functions
+ * @returns Result of the executed handler
+ *
+ * @example Basic matching
+ * ```typescript
+ * const result: Result<number, string> = ok(42);
+ * const message = match(result, {
+ *   ok: (value) => `Success: ${value}`,
+ *   err: (error) => `Error: ${error}`
+ * });
+ * // message: 'Success: 42'
+ * ```
+ *
+ * @example With side effects
+ * ```typescript
+ * match(result, {
+ *   ok: (value) => {
+ *     console.log(`Got value: ${value}`);
+ *     return value;
+ *   },
+ *   err: (error) => {
+ *     console.error(`Got error: ${error}`);
+ *     return 0;
+ *   }
+ * });
+ * ```
+ *
+ * @example Complex return types
+ * ```typescript
+ * const output = match(result, {
+ *   ok: (point) => ({ x: point.x * 2, y: point.y * 2 }),
+ *   err: () => ({ x: 0, y: 0 })
+ * });
+ * ```
+ */
+export function match(result, handlers) {
+    if (result.ok) {
+        return handlers.ok(result.value);
+    }
+    // Type assertion: result.ok is false, so error exists
+    return handlers.err(result.error);
+}
+//# sourceMappingURL=result.js.map

package/dist/types/result.js.map

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

package/dist/utils/error-classifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Error Classification Utility
+ *
+ * Classifies unknown errors into appropriate CAPG error types based on
+ * status codes, error codes, and other error properties.
+ *
+ * @packageDocumentation
+ * @since v1.0.0
+ * @internal
+ */
+import { CAPGError } from '../errors/index.js';
+/**
+ * Redact credentials from a string to prevent leakage in logs/errors
+ *
+ * Removes:
+ * - Bearer tokens: 'Bearer abc123...' → 'Bearer ***'
+ * - Authorization headers: 'Authorization: Bearer xyz' → 'Authorization: ***'
+ * - Access tokens: 'access_token=abc123' → 'access_token=***'
+ *
+ * @param message - String that may contain credentials
+ * @returns Redacted string with credentials replaced by ***
+ *
+ * @internal
+ */
+export declare function redactCredentials(message: string): string;
+/**
+ * Classify unknown error into appropriate CAPG error type
+ *
+ * Classifies errors by type:
+ * - 401 → CAPGAuthError (not retryable)
+ * - ETIMEDOUT, ECONNREFUSED, ENOTFOUND → CAPGNetworkError (retryable)
+ * - 4xx/5xx → CAPGAPIError with status code
+ * - Unknown → CAPGError
+ *
+ * @param error - Error from external operation (query, network, etc.)
+ * @param context - Context information (username, operation name, etc.)
+ * @returns CAPGError or subclass
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await connection.query(soql);
+ * } catch (error: unknown) {
+ *   const capgError = classifyError(error, { username: 'user@example.com' });
+ *   return err(capgError);
+ * }
+ * ```
+ *
+ * @internal
+ */
+export declare function classifyError(error: unknown, context?: {
+    username?: string;
+    operation?: string;
+}): CAPGError;
+//# sourceMappingURL=error-classifier.d.ts.map

package/dist/utils/error-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-classifier.d.ts","sourceRoot":"","sources":["../../src/utils/error-classifier.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAiD,MAAM,oBAAoB,CAAC;AAE9F;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAqD5G"}