import 'api_exception.dart';

/// Abstract contract for all external API clients.
///
/// Defines the lifecycle, authentication, and error-handling surface that
/// every channel integration (WooCommerce, Square, etc.) must satisfy.
/// Concrete implementations live in their respective feature or integration
/// packages and are selected at runtime via `--dart-define`.
abstract class ApiClient {
  /// Performs any async initialisation required before the client can be used
  /// (e.g. token refresh, connectivity check).
  ///
  /// Callers should await [initialize] before issuing requests.
  Future<void> initialize();

  /// Releases all resources held by this client (HTTP connections, timers,
  /// stream subscriptions, etc.).
  ///
  /// After [dispose] is called the client must not be used again.
  void dispose();

  /// Returns `true` if the client has been initialised and is ready to
  /// accept requests.
  bool get isReady;

  /// Executes [request] and returns its result.
  ///
  /// Implementations are expected to:
  /// - Inject authentication headers.
  /// - Apply the configured [RetryPolicy] on transient failures.
  /// - Respect the configured [RateLimiter] before each attempt.
  /// - Translate HTTP error responses into [ApiException] subclasses.
  Future<T> execute<T>(Future<T> Function() request);
}
