aws-amplify
diff --git a/‎packages/kinesis/amplify_firehose_dart/lib/amplify_firehose_dart.dart‎
Lines changed: 22 additions & 1 deletion b/‎packages/kinesis/amplify_firehose_dart/lib/amplify_firehose_dart.dart‎
Lines changed: 22 additions & 1 deletion
diff --git a/‎packages/kinesis/amplify_firehose_dart/lib/src/amplify_firehose_client.dart‎
Lines changed: 220 additions & 0 deletions b/‎packages/kinesis/amplify_firehose_dart/lib/src/amplify_firehose_client.dart‎
Lines changed: 220 additions & 0 deletions
diff --git a/‎packages/kinesis/amplify_firehose_dart/lib/src/amplify_firehose_client_options.dart‎
Lines changed: 33 additions & 0 deletions b/‎packages/kinesis/amplify_firehose_dart/lib/src/amplify_firehose_client_options.dart‎
Lines changed: 33 additions & 0 deletions
diff --git a/‎packages/kinesis/amplify_firehose_dart/lib/src/exception/amplify_firehose_exception.dart‎
Lines changed: 111 additions & 0 deletions b/‎packages/kinesis/amplify_firehose_dart/lib/src/exception/amplify_firehose_exception.dart‎
Lines changed: 111 additions & 0 deletions
@@ -4,5 +4,26 @@
 /// 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
+        ClearCacheData,
+        FlushData,
+        FlushInterval,
+        FlushNone,
+        FlushStrategy,
+        RecordData;
+
+// Main client
+export 'src/amplify_firehose_client.dart';
+// Options
+export 'src/amplify_firehose_client_options.dart';
+// 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;
@@ -0,0 +1,220 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import 'dart:async';
+import 'dart:typed_data';
+
+import 'package:amplify_firehose_dart/src/amplify_firehose_client_options.dart';
+import 'package:amplify_firehose_dart/src/exception/amplify_firehose_exception.dart';
+import 'package:amplify_firehose_dart/src/firehose_limits.dart' as limits;
+import 'package:amplify_firehose_dart/src/impl/firehose_sender.dart';
+import 'package:amplify_firehose_dart/src/sdk/firehose.dart' as sdk;
+import 'package:amplify_firehose_dart/src/version.dart';
+import 'package:amplify_foundation_dart/amplify_foundation_dart.dart'
+    as foundation
+    show packageVersion;
+import 'package:amplify_foundation_dart/amplify_foundation_dart.dart'
+    hide packageVersion;
+import 'package:amplify_foundation_dart_bridge/amplify_foundation_dart_bridge.dart';
+import 'package:amplify_record_cache_dart/amplify_record_cache_dart.dart';
+import 'package:smithy/smithy.dart' show WithUserAgent;
+
+/// User agent component identifying this library.
+const _userAgentComponent =
+    'md/amplify-firehose#$packageVersion '
+    'lib/amplify-flutter#${foundation.packageVersion}';
+
+/// {@template amplify_firehose.amplify_firehose_client}
+/// Client for recording and streaming data to Amazon Data Firehose.
+///
+/// Provides offline-capable data streaming with:
+/// - Local persistence for offline support (SQLite on VM, IndexedDB on web)
+/// - Automatic retry for failed records
+/// - Configurable batching (up to 500 records or 4 MB per batch)
+/// - Interval-based automatic flushing
+///
+/// This is the Dart-only implementation. For Flutter apps, use the
+/// `amplify_firehose` package which resolves the storage path
+/// automatically via `path_provider`.
+/// {@endtemplate}
+class AmplifyFirehoseClient {
+  AmplifyFirehoseClient._({
+    required String region,
+    required AmplifyFirehoseClientOptions options,
+    required RecordClient recordClient,
+    required sdk.FirehoseClient firehoseClient,
+    AutoFlushScheduler? scheduler,
+  }) : _region = region,
+       _options = options,
+       _recordClient = recordClient,
+       _firehoseClient = firehoseClient,
+       _scheduler = scheduler,
+       _logger = AmplifyLogging.logger('AmplifyFirehoseClient');
+
+  /// Creates a client with a pre-configured [RecordClient] (for testing).
+  AmplifyFirehoseClient.withRecordClient({
+    required RecordClient recordClient,
+    String region = 'us-east-1',
+    AmplifyFirehoseClientOptions? options,
+  }) : _region = region,
+       _options = options ?? const AmplifyFirehoseClientOptions(),
+       _recordClient = recordClient,
+       _firehoseClient = null,
+       _scheduler = null,
+       _logger = AmplifyLogging.logger('AmplifyFirehoseClient');
+
+  /// {@macro amplify_firehose.amplify_firehose_client}
+  static Future<AmplifyFirehoseClient> create({
+    required String region,
+    required AWSCredentialsProvider credentialsProvider,
+    required FutureOr<String>? storagePath,
+    AmplifyFirehoseClientOptions? options,
+  }) async {
+    final opts = options ?? const AmplifyFirehoseClientOptions();
+
+    final storage = await createPlatformRecordStorage(
+      identifier: region,
+      storagePath: storagePath,
+      maxCacheBytes: opts.cacheMaxBytes,
+      maxRecordsPerBatch: limits.maxRecordsPerBatch,
+      maxBytesPerBatch: limits.maxBatchSizeBytes,
+      maxRecordSizeBytes: limits.maxRecordSizeBytes,
+      dbPrefix: 'amplify_firehose_',
+      storeName: 'firehose_records',
+    );
+
+    final firehoseClient = sdk.FirehoseClient(
+      region: region,
+      credentialsProvider: SmithyCredentialsProviderBridge(credentialsProvider),
+      requestInterceptors: [const WithUserAgent(_userAgentComponent)],
+    );
+
+    final recordClient = RecordClient(
+      storage: storage,
+      sender: FirehoseSender(
+        firehoseClient: firehoseClient,
+        maxRetries: opts.maxRetries,
+      ),
+      maxRetries: opts.maxRetries,
+    );
+
+    final scheduler = switch (opts.flushStrategy) {
+      FlushInterval(:final interval) => AutoFlushScheduler(
+        interval: interval,
+        client: recordClient,
+      )..start(),
+      FlushNone() => null,
+    };
+
+    return AmplifyFirehoseClient._(
+      region: region,
+      options: opts,
+      recordClient: recordClient,
+      firehoseClient: firehoseClient,
+      scheduler: scheduler,
+    );
+  }
+
+  final String _region;
+  final AmplifyFirehoseClientOptions _options;
+  final RecordClient _recordClient;
+  final sdk.FirehoseClient? _firehoseClient;
+  final Logger _logger;
+  final AutoFlushScheduler? _scheduler;
+  bool _enabled = true;
+  bool _closed = false;
+
+  /// The AWS region for this client.
+  String get region => _region;
+
+  /// The configuration options for this client.
+  AmplifyFirehoseClientOptions get options => _options;
+
+  /// Whether the client is currently enabled.
+  bool get isEnabled => _enabled;
+
+  /// Whether the client has been closed.
+  bool get isClosed => _closed;
+
+  /// Direct access to the underlying Firehose SDK client.
+  sdk.FirehoseClient get firehoseClient {
+    final client = _firehoseClient;
+    if (client == null) {
+      throw StateError(
+        'firehoseClient is not available on clients created with '
+        'withRecordClient.',
+      );
+    }
+    return client;
+  }
+
+  /// Records data to be sent to a Firehose delivery stream.
+  ///
+  /// Returns [Result.ok] with [RecordData] on success, or [Result.error] with:
+  /// - [FirehoseValidationException] for invalid input (e.g. oversized record)
+  /// - [FirehoseLimitExceededException] if the cache is full
+  /// - [FirehoseStorageException] for database errors
+  Future<Result<RecordData>> record({
+    required Uint8List data,
+    required String streamName,
+  }) async {
+    if (_closed) return const Result.error(FirehoseClientClosedException());
+    if (!isEnabled) {
+      _logger.debug('Record collection is disabled, dropping record');
+      return const Result.ok(RecordData());
+    }
+    _logger.verbose('Recording to stream: $streamName');
+    final input = RecordInput.now(
+      data: data,
+      streamName: streamName,
+      dataSize: data.length,
+    );
+    return _wrapError(() => _recordClient.record(input));
+  }
+
+  /// Flushes cached records to their respective Firehose streams.
+  Future<Result<FlushData>> flush() async {
+    if (_closed) return const Result.error(FirehoseClientClosedException());
+    _logger.verbose('Starting flush');
+    return _wrapError(_recordClient.flush);
+  }
+
+  /// Clears all cached records from local storage.
+  Future<Result<ClearCacheData>> clearCache() async {
+    if (_closed) return const Result.error(FirehoseClientClosedException());
+    _logger.verbose('Clearing cache');
+    return _wrapError(_recordClient.clearCache);
+  }
+
+  /// Enables the client to accept and flush records.
+  void enable() {
+    _logger.info('Enabling record collection and automatic flushing');
+    _enabled = true;
+    _scheduler?.start();
+  }
+
+  /// Disables record collection and automatic flushing.
+  void disable() {
+    _logger.info('Disabling record collection and automatic flushing');
+    _enabled = false;
+    _scheduler?.stop();
+  }
+
+  /// Closes the client and releases all resources.
+  Future<void> close() async {
+    _closed = true;
+    _scheduler?.stop();
+    await _recordClient.close();
+  }
+
+  Future<Result<T>> _wrapError<T>(Future<T> Function() operation) async {
+    try {
+      final value = await operation();
+      return Result.ok(value);
+    } on Object catch (e) {
+      final wrapped = AmplifyFirehoseException.from(e);
+      _logger.warn('Operation failed: ${wrapped.message}', e);
+      return Result.error(wrapped);
+    }
+  }
+}
@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import 'package:amplify_firehose_dart/src/amplify_firehose_client.dart'
+    show AmplifyFirehoseClient;
+import 'package:amplify_record_cache_dart/amplify_record_cache_dart.dart';
+
+/// {@template amplify_firehose.amplify_firehose_client_options}
+/// Configuration options for [AmplifyFirehoseClient].
+/// {@endtemplate}
+final class AmplifyFirehoseClientOptions {
+  /// {@macro amplify_firehose.amplify_firehose_client_options}
+  const AmplifyFirehoseClientOptions({
+    this.cacheMaxBytes = 5 * 1024 * 1024,
+    this.maxRetries = 5,
+    this.flushStrategy = const FlushInterval(),
+  });
+
+  /// Maximum size of the local cache in bytes.
+  ///
+  /// Defaults to 5 MB.
+  final int cacheMaxBytes;
+
+  /// Maximum number of retry attempts for failed records.
+  ///
+  /// Defaults to 5.
+  final int maxRetries;
+
+  /// Strategy for automatic flushing of cached records.
+  ///
+  /// Defaults to [FlushInterval] with a 30-second interval.
+  final FlushStrategy flushStrategy;
+}
@@ -0,0 +1,111 @@
+// 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';
+
+/// {@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';
+}