feat(firehose): add exception hierarchy and depend on shared record cache

- AmplifyFirehoseException sealed hierarchy with .from() mapper
- FirehoseStorageException, FirehoseValidationException,
  FirehoseLimitExceededException, FirehoseUnknownException,
  FirehoseClientClosedException
- Depend on amplify_record_cache_dart for storage/caching infrastructure
- Re-export shared FlushStrategy, FlushData, RecordData, ClearCacheData
- Export Firehose SDK escape hatch types
- Exception mapping tests
- Slim pubspec: removed direct drift/web/db deps (now transitive via shared pkg)

Author: ekjotmultani

packages/kinesis/amplify_firehose_dart/lib/amplify_firehose_dart.dart

@@ -4,5 +4,22 @@
 /// Amplify Amazon Data Firehose client for Dart.
 library;
 
+// Re-export shared types used in the public API
+export 'package:amplify_record_cache_dart/amplify_record_cache_dart.dart'
+    show
+        FlushStrategy,
+        FlushInterval,
+        FlushNone,
+        FlushData,
+        RecordData,
+        ClearCacheData;
+
+// Exceptions
+export 'src/exception/amplify_firehose_exception.dart';
 // SDK client (for escape hatch)
-// Exports will be added as implementation PRs land.
+export 'src/sdk/firehose.dart'
+    show
+        FirehoseClient,
+        PutRecordBatchInput,
+        PutRecordBatchOutput,
+        PutRecordBatchResponseEntry;

packages/kinesis/amplify_firehose_dart/lib/src/exception/amplify_firehose_exception.dart

@@ -0,0 +1,115 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import 'package:amplify_core/amplify_core.dart';
+import 'package:amplify_record_cache_dart/amplify_record_cache_dart.dart';
+
+/// Default recovery suggestion for errors.
+const String defaultRecoverySuggestion =
+    'Inspect the underlying error for more details.';
+
+/// {@template amplify_firehose.amplify_firehose_exception}
+/// Base exception for Amplify Firehose errors.
+/// {@endtemplate}
+sealed class AmplifyFirehoseException extends AmplifyException {
+  /// {@macro amplify_firehose.amplify_firehose_exception}
+  const AmplifyFirehoseException(
+    super.message, {
+    super.recoverySuggestion,
+    super.underlyingException,
+  });
+
+  /// Maps an arbitrary error into the appropriate
+  /// [AmplifyFirehoseException] subtype.
+  static AmplifyFirehoseException from(Object error) => switch (error) {
+    final AmplifyFirehoseException e => e,
+    final RecordCacheValidationException e => FirehoseValidationException(
+      e.message,
+      recoverySuggestion: e.recoverySuggestion,
+    ),
+    final RecordCacheLimitExceededException e => FirehoseLimitExceededException(
+      message: e.message,
+      recoverySuggestion: e.recoverySuggestion,
+    ),
+    final RecordCacheDatabaseException e => FirehoseStorageException(
+      e.message,
+      recoverySuggestion: e.recoverySuggestion,
+      underlyingException: e.cause,
+    ),
+    final Exception e => FirehoseUnknownException(
+      e.toString(),
+      underlyingException: e,
+    ),
+    _ => FirehoseUnknownException(error.toString()),
+  };
+}
+
+/// {@template amplify_firehose.firehose_storage_exception}
+/// Thrown when a local cache/database error occurs.
+/// {@endtemplate}
+final class FirehoseStorageException extends AmplifyFirehoseException {
+  /// {@macro amplify_firehose.firehose_storage_exception}
+  const FirehoseStorageException(
+    super.message, {
+    super.recoverySuggestion,
+    super.underlyingException,
+  });
+
+  @override
+  String get runtimeTypeName => 'FirehoseStorageException';
+}
+
+/// {@template amplify_firehose.firehose_limit_exceeded_exception}
+/// Thrown when the local cache is full.
+/// {@endtemplate}
+final class FirehoseLimitExceededException extends AmplifyFirehoseException {
+  /// {@macro amplify_firehose.firehose_limit_exceeded_exception}
+  const FirehoseLimitExceededException({
+    String? message,
+    String? recoverySuggestion,
+  }) : super(
+         message ?? 'Cache is full',
+         recoverySuggestion:
+             recoverySuggestion ?? 'Call flush() or clearCache().',
+       );
+
+  @override
+  String get runtimeTypeName => 'FirehoseLimitExceededException';
+}
+
+/// {@template amplify_firehose.firehose_validation_exception}
+/// Thrown when record input validation fails (e.g. oversized record).
+/// {@endtemplate}
+final class FirehoseValidationException extends AmplifyFirehoseException {
+  /// {@macro amplify_firehose.firehose_validation_exception}
+  const FirehoseValidationException(super.message, {super.recoverySuggestion});
+
+  @override
+  String get runtimeTypeName => 'FirehoseValidationException';
+}
+
+/// {@template amplify_firehose.firehose_unknown_exception}
+/// Catch-all for unexpected errors.
+/// {@endtemplate}
+final class FirehoseUnknownException extends AmplifyFirehoseException {
+  /// {@macro amplify_firehose.firehose_unknown_exception}
+  const FirehoseUnknownException(super.message, {super.underlyingException});
+
+  @override
+  String get runtimeTypeName => 'FirehoseUnknownException';
+}
+
+/// {@template amplify_firehose.client_closed_exception}
+/// Thrown when an operation is attempted on a closed client.
+/// {@endtemplate}
+final class FirehoseClientClosedException extends AmplifyFirehoseException {
+  /// {@macro amplify_firehose.client_closed_exception}
+  const FirehoseClientClosedException()
+    : super(
+        'Client has been closed',
+        recoverySuggestion: 'Create a new AmplifyFirehoseClient instance.',
+      );
+
+  @override
+  String get runtimeTypeName => 'FirehoseClientClosedException';
+}

packages/kinesis/amplify_firehose_dart/pubspec.yaml

@@ -17,26 +17,20 @@ environment:
 
 dependencies:
   amplify_core: ">=2.10.0 <2.11.0"
-  amplify_db_common_dart: ">=0.4.14 <0.5.0"
-  amplify_foundation_dart: ">=2.10.0 <2.11.0"
-  amplify_foundation_dart_bridge: ">=2.10.0 <2.11.0"
+  amplify_foundation_dart: ">=2.11.0 <2.12.0"
+  amplify_foundation_dart_bridge: ">=2.11.0 <2.12.0"
+  amplify_record_cache_dart: ">=0.1.0 <0.2.0"
   aws_common: ">=0.7.12 <0.8.0"
   aws_signature_v4: ">=0.6.10 <0.7.0"
   built_collection: ^5.1.1
   built_value: ^8.10.1
-  drift: ^2.25.0
   meta: ^1.16.0
   smithy: ">=0.7.10 <0.8.0"
   smithy_aws: ">=0.7.10 <0.8.0"
-  synchronized: ^3.3.0
-  web: ^1.1.1
 
 dev_dependencies:
   amplify_lints: ">=3.1.4 <3.2.0"
-  build_runner: ^2.4.15
-  build_version: ^2.1.1
-  built_value_generator: ^8.10.1
-  drift_dev: ^2.25.1
+  drift: ^2.25.0
   fake_async: ^1.3.0
   mocktail: ^1.0.0
   test: ^1.22.1

packages/kinesis/amplify_firehose_dart/test/amplify_firehose_exception_test.dart

@@ -0,0 +1,69 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import 'package:amplify_firehose_dart/src/exception/amplify_firehose_exception.dart';
+import 'package:amplify_record_cache_dart/amplify_record_cache_dart.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('AmplifyFirehoseException.from', () {
+    test('passes through AmplifyFirehoseException unchanged', () {
+      const original = FirehoseStorageException('msg');
+      final result = AmplifyFirehoseException.from(original);
+      expect(identical(result, original), isTrue);
+    });
+
+    test('converts RecordCacheValidationException '
+        'to FirehoseValidationException', () {
+      const cause = RecordCacheValidationException('bad input', 'fix it');
+      final result = AmplifyFirehoseException.from(cause);
+      expect(result, isA<FirehoseValidationException>());
+      expect(result.message, 'bad input');
+      expect(result.recoverySuggestion, 'fix it');
+    });
+
+    test(
+      'converts RecordCacheDatabaseException to FirehoseStorageException',
+      () {
+        final underlying = Exception('sqlite error');
+        final cause = RecordCacheDatabaseException(
+          'db error',
+          'retry',
+          underlying,
+        );
+        final result = AmplifyFirehoseException.from(cause);
+        expect(result, isA<FirehoseStorageException>());
+        expect(result.message, 'db error');
+        expect(result.recoverySuggestion, 'retry');
+        expect(result.underlyingException, underlying);
+      },
+    );
+
+    test('converts RecordCacheLimitExceededException '
+        'to FirehoseLimitExceededException', () {
+      const cause = RecordCacheLimitExceededException(
+        'cache full',
+        'flush first',
+      );
+      final result = AmplifyFirehoseException.from(cause);
+      expect(result, isA<FirehoseLimitExceededException>());
+      expect(result.message, 'cache full');
+      expect(result.recoverySuggestion, 'flush first');
+    });
+
+    test('converts unknown Exception to FirehoseUnknownException', () {
+      final cause = Exception('something unexpected');
+      final result = AmplifyFirehoseException.from(cause);
+      expect(result, isA<FirehoseUnknownException>());
+      expect(result.underlyingException, cause);
+    });
+
+    test('converts non-Exception error to FirehoseUnknownException', () {
+      const error = 'a string error';
+      final result = AmplifyFirehoseException.from(error);
+      expect(result, isA<FirehoseUnknownException>());
+      expect(result.message, 'a string error');
+      expect(result.underlyingException, isNull);
+    });
+  });
+}