import 'package:dio/dio.dart';
import 'package:networks_sdk/src/data/dto/api_requestable.dart';
import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
import 'package:networks_sdk/src/presentation/wiring/networks_sdk_wiring.dart';

/// Networks SDK 公开接口
///
/// 提供两种请求入口：
/// - [executeRequest] — 统一请求入口（标准 / Upload / 流式）
/// - [executeDownload] — 带进度的文件下载（支持断点续传）
///
/// 流式请求（SSE）也走 [executeRequest]，由业务 Request 类 override
/// `decodeResponse` 处理 SSE 解析。SDK 根据 `requestType == stream`
/// 自动切换响应类型。
///
/// 使用方式：
/// ```dart
/// final sdk = NetworksSdkApi();
/// sdk.initialize(apiConfig);
///
/// // 标准请求
/// final data = await sdk.executeRequest(LoginRequest(...));
///
/// // 流式请求（SSE）— 同一入口，Request 类 override decodeResponse
/// final result = await sdk.executeRequest(VoiceTranscribeRequest(...));
///
/// // 文件下载
/// await sdk.executeDownload(
///   url: '/files/report.pdf',
///   savePath: '/tmp/report.pdf',
///   onProgress: (received, total) => print('$received / $total'),
/// );
/// ```
abstract class NetworksSdkApi {
  factory NetworksSdkApi() => NetworksSdkWiring.build();

  Future<String?> platformVersion();

  void initialize(ApiConfig apiConfig);

  /// 执行 API 请求 — 统一入口
  ///
  /// 支持标准请求、登录、上传、流式（SSE），由 `request.requestType` 控制。
  /// 流式请求由业务 Request 类 override `decodeResponse` 处理 SSE 解析。
  ///
  /// [cancelToken] — 可选，用于取消正在进行的请求
  Future<T?> executeRequest<T>(
    ApiRequestable<T> request, {
    CancelToken? cancelToken,
  });

  /// 下载文件到本地路径
  ///
  /// [url] — 下载 URL（完整路径或相对路径）
  /// [savePath] — 本地保存路径
  /// [onProgress] — 下载进度回调
  /// [cancelToken] — 取消令牌
  /// [resume] — 是否断点续传
  /// [headers] — 额外请求头
  Future<void> executeDownload({
    required String url,
    required String savePath,
    OnDownloadProgress? onProgress,
    CancelToken? cancelToken,
    bool resume = false,
    Map<String, String>? headers,
  });
}
