feat(exceptions): introduce structured exception handling for policy SDK with detailed context

Author: dgarciasquare1

lib/src/exceptions/i_policy_sdk_exceptions.dart

@@ -0,0 +1,51 @@
+/// Base exception class for all policy SDK related errors.
+///
+/// This abstract class provides a common interface for all exceptions
+/// thrown by the policy engine, ensuring consistent error handling
+/// and messaging across the SDK.
+abstract class IPolicySDKException implements Exception {
+  /// Creates a new PolicySDKException with the given error message.
+  ///
+  /// [message] should provide a clear description of what went wrong.
+  const IPolicySDKException(this.message);
+
+  /// The error message describing the exception.
+  final String message;
+
+  @override
+  String toString() => 'PolicySDKException: $message';
+}
+
+/// Abstract exception for detailed policy SDK errors with contextual information.
+///
+/// This class extends [IPolicySDKException] to provide additional context for
+/// errors that occur within the policy engine, such as the specific key involved,
+/// the original error thrown, and a map of field-specific validation errors.
+/// Subclasses should use this to represent exceptions where more granular
+/// diagnostic information is valuable for debugging or reporting.
+abstract class IDetailPolicySDKException implements IPolicySDKException {
+  /// Creates a new [IDetailPolicySDKException] with an error [message] and optional details.
+  ///
+  /// [message] provides a human-readable description of the error.
+  /// [key] optionally identifies the specific key or field related to the error.
+  /// [originalError] optionally contains the original error object that triggered this exception.
+  /// [errors] optionally provides a map of field-specific validation errors.
+  const IDetailPolicySDKException(
+    this.message, {
+    this.key,
+    this.originalError,
+    this.errors,
+  });
+
+  @override
+  final String message;
+
+  /// The specific key or field that caused the error, if applicable.
+  final String? key;
+
+  /// The original error object that led to this exception, if available.
+  final Object? originalError;
+
+  /// A map of field-specific validation errors encountered during processing, if any.
+  final Map<String, String>? errors;
+}

lib/src/exceptions/json_parse_exception.dart

@@ -0,0 +1,53 @@
+import 'package:flutter_policy_engine/src/exceptions/i_policy_sdk_exceptions.dart';
+
+/// Exception thrown when JSON parsing fails during policy evaluation.
+///
+/// This exception is raised when the policy engine encounters malformed
+/// or invalid JSON data that cannot be parsed into the expected format.
+/// It provides detailed context about the parsing failure including
+/// the specific key that failed, the original error, and any additional
+/// validation errors.
+class JsonParseException implements IDetailPolicySDKException {
+  @override
+  final String message;
+
+  /// The specific JSON key that caused the parsing failure, if applicable.
+  @override
+  final String? key;
+
+  /// The original error object from the JSON parsing library.
+  @override
+  final Object? originalError;
+
+  /// A map of field-specific validation errors encountered during parsing.
+  @override
+  final Map<String, String>? errors;
+
+  /// Creates a new JsonParseException.
+  ///
+  /// [message] should describe the parsing failure.
+  /// [key] optionally specifies which JSON key caused the failure.
+  /// [originalError] optionally provides the original parsing error.
+  /// [errors] optionally provides a map of field-specific validation errors.
+  JsonParseException(
+    this.message, {
+    this.key,
+    this.originalError,
+    this.errors,
+  });
+
+  @override
+  String toString() {
+    final buffer = StringBuffer('JsonParseException: $message');
+    if (key != null) {
+      buffer.write(' (key: $key)');
+    }
+    if (originalError != null) {
+      buffer.write(' (original: $originalError)');
+    }
+    if (errors != null && errors!.isNotEmpty) {
+      buffer.write(' (${errors!.length} total errors)');
+    }
+    return buffer.toString();
+  }
+}

lib/src/exceptions/json_serialize_exception.dart

@@ -0,0 +1,52 @@
+import 'package:flutter_policy_engine/src/exceptions/i_policy_sdk_exceptions.dart';
+
+/// Exception thrown when JSON serialization fails during policy operations.
+///
+/// This exception is raised when the policy engine cannot serialize
+/// policy objects or data structures to JSON format. This typically
+/// occurs when policy objects contain non-serializable data types
+/// or circular references.
+class JsonSerializeException implements IDetailPolicySDKException {
+  @override
+  final String message;
+
+  /// The specific object key that caused the serialization failure, if applicable.
+  @override
+  final String? key;
+
+  /// The original error object from the JSON serialization library.
+  @override
+  final Object? originalError;
+
+  /// A map of field-specific serialization errors encountered.
+  @override
+  final Map<String, String>? errors;
+
+  /// Creates a new JsonSerializeException.
+  ///
+  /// [message] should describe the serialization failure.
+  /// [key] optionally specifies which object key caused the failure.
+  /// [originalError] optionally provides the original serialization error.
+  /// [errors] optionally provides a map of field-specific serialization errors.
+  JsonSerializeException(
+    this.message, {
+    this.key,
+    this.originalError,
+    this.errors,
+  });
+
+  @override
+  String toString() {
+    final buffer = StringBuffer('JsonSerializeException: $message');
+    if (key != null) {
+      buffer.write(' (key: $key)');
+    }
+    if (originalError != null) {
+      buffer.write(' (original: $originalError)');
+    }
+    if (errors != null && errors!.isNotEmpty) {
+      buffer.write(' (${errors!.length} total errors)');
+    }
+    return buffer.toString();
+  }
+}

lib/src/exceptions/policy_not_initialized_exception.dart

@@ -0,0 +1,30 @@
+import 'package:flutter_policy_engine/src/exceptions/i_policy_sdk_exceptions.dart';
+
+/// Exception thrown when a policy engine operation is attempted before initialization.
+///
+/// This exception indicates that a policy-related operation was invoked
+/// before the policy engine or evaluator was properly initialized. This
+/// typically occurs if you attempt to evaluate policies, check permissions,
+/// or perform other policy operations before calling the required
+/// initialization or setup methods.
+///
+/// Example:
+/// ```dart
+/// if (!_isInitialized) {
+///   throw PolicyNotInitializedException('Policy engine must be initialized before use.');
+/// }
+/// ```
+class PolicyNotInitializedException implements IPolicySDKException {
+  /// A message describing the initialization error.
+  @override
+  final String message;
+
+  /// Creates a new [PolicyNotInitializedException] with the given [message].
+  const PolicyNotInitializedException(this.message);
+
+  @override
+  String toString() {
+    final buffer = StringBuffer('PolicyNotInitializedException: $message');
+    return buffer.toString();
+  }
+}

lib/src/exceptions/policy_sdk_exceptions.dart

@@ -1,4 +1,5 @@
-import 'package:flutter_policy_engine/src/exceptions/policy_sdk_exceptions.dart';
+import 'package:flutter_policy_engine/src/exceptions/json_parse_exception.dart';
+import 'package:flutter_policy_engine/src/exceptions/json_serialize_exception.dart';
 import 'package:flutter_policy_engine/src/utils/log_handler.dart';
 
 /// Utility for type-safe JSON conversions with generic support.

lib/src/utils/json_handler.dart

@@ -1,4 +1,5 @@
-import 'package:flutter_policy_engine/src/exceptions/policy_sdk_exceptions.dart';
+import 'package:flutter_policy_engine/src/exceptions/json_parse_exception.dart';
+import 'package:flutter_policy_engine/src/exceptions/json_serialize_exception.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:flutter_policy_engine/src/utils/json_handler.dart';