feat: MisskeyApiExceptionとMisskeyHttpClientの機能強化

- MisskeyApiExceptionにretryAfterプロパティを追加し、HTTP 429エラー時の待機時間を管理
- MisskeyHttpClientのsendメソッドを改良し、リクエストオプションの柔軟性を向上
- RequestOptionsクラスにcontentType、headers、extraプロパティを追加し、リクエストのカスタマイズを強化

Author: LibraryLibrarian

lib/src/core/error/misskey_api_exception.dart

@@ -1,14 +1,24 @@
 /// Misskey API 呼び出し時の共通例外
 class MisskeyApiException implements Exception {
+  /// HTTP ステータスコード
   final int? statusCode;
-  final String? code; // Misskey固有のエラーコード等があれば格納
+
+  /// Misskey固有のエラーコード等があれば格納
+  final String? code;
+
+  /// エラーメッセージ（人間可読）
   final String message;
+
+  /// 元例外やエラーオブジェクト
   final Object? raw;
 
-  const MisskeyApiException({this.statusCode, this.code, required this.message, this.raw});
+  /// 429 Too Many Requests 時に応じるまでの推奨待機時間
+  final Duration? retryAfter;
+
+  /// 共通例外コンテナ
+  const MisskeyApiException({this.statusCode, this.code, required this.message, this.raw, this.retryAfter});
 
   @override
   String toString() =>
-      'MisskeyApiException(statusCode: '
-      '$statusCode, code: $code, message: $message)';
+      'MisskeyApiException(statusCode: $statusCode, code: $code, message: $message, retryAfter: $retryAfter)';
 }

lib/src/core/http/misskey_http_client.dart

@@ -40,7 +40,6 @@ class MisskeyHttpClient {
         ...config.defaultHeaders,
         if (config.userAgent != null) 'User-Agent': config.userAgent,
         'Accept': 'application/json',
-        'Content-Type': 'application/json',
       },
     );
     _dio = Dio(baseOptions);
@@ -58,12 +57,17 @@ class MisskeyHttpClient {
   }
 
   /// `path` は `/notes/create` のように `/api` より後のパスを渡す
+  ///
+  /// [body] には `Map<String,dynamic>`（JSON）・`FormData`（multipart）・`null` を指定可能
+  /// [options] で `contentType`/`headers`/`extra` をリクエスト単位で上書きできる
+  /// アップロード時は [onSendProgress] で進捗を受け取れる
   Future<T> send<T>(
     String path, {
     String method = 'POST',
-    Map<String, dynamic>? body,
+    dynamic body,
     ro.RequestOptions options = const ro.RequestOptions(),
     CancelToken? cancelToken,
+    void Function(int, int)? onSendProgress,
   }) async {
     final r = RetryOptions(
       maxAttempts: options.idempotent ? config.maxRetries : 1,
@@ -76,11 +80,18 @@ class MisskeyHttpClient {
     try {
       final result = await r.retry(
         () async {
+          final reqOptions = Options(
+            method: method,
+            contentType: options.contentType,
+            headers: options.headers.isEmpty ? null : Map<String, dynamic>.from(options.headers),
+            extra: {'authRequired': options.authRequired, ...options.extra},
+          );
           final Response<dynamic> res = await _dio.request(
             path.startsWith('/') ? path : '/$path',
             data: body,
-            options: Options(method: method, extra: {'authRequired': options.authRequired}),
+            options: reqOptions,
             cancelToken: cancelToken,
+            onSendProgress: onSendProgress,
           );
           return res;
         },
@@ -130,6 +141,7 @@ class MisskeyHttpClient {
     final status = e.response?.statusCode;
     String message = e.message ?? 'HTTP error';
     String? code;
+    Duration? retryAfter;
     final data = e.response?.data;
     if (data is Map) {
       final dynamic errorObj = data['error'];
@@ -145,7 +157,14 @@ class MisskeyHttpClient {
         if (m != null) message = m.toString();
       }
     }
-    return MisskeyApiException(statusCode: status, code: code, message: message, raw: e);
+    final ra = e.response?.headers.value('retry-after');
+    if (ra != null) {
+      final seconds = int.tryParse(ra.trim());
+      if (seconds != null) {
+        retryAfter = Duration(seconds: seconds);
+      }
+    }
+    return MisskeyApiException(statusCode: status, code: code, message: message, raw: e, retryAfter: retryAfter);
   }
 }
 
@@ -158,15 +177,22 @@ class _MisskeyInterceptor extends Interceptor {
 
   @override
   void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
-    // 認証付与（POSTのみ、かつ body が Map のとき）
+    // 認証付与（POSTのみ、Map/FormData/空bodyに対応）
     final extra = options.extra;
     final authRequired = (extra['authRequired'] as bool?) ?? true;
     if (authRequired && options.method.toUpperCase() == 'POST') {
       final token = await tokenProvider?.call();
       if (token != null && token.isNotEmpty) {
         final data = options.data;
         if (data is Map<String, dynamic>) {
-          options.data = <String, dynamic>{...data, 'i': token};
+          if (!data.containsKey('i')) {
+            options.data = <String, dynamic>{...data, 'i': token};
+          }
+        } else if (data is FormData) {
+          final hasI = data.fields.any((e) => e.key == 'i');
+          if (!hasI) {
+            data.fields.add(MapEntry('i', token));
+          }
         } else if (data == null) {
           options.data = <String, dynamic>{'i': token};
         }

lib/src/core/http/request_options.dart

@@ -6,5 +6,27 @@ class RequestOptions {
   /// 冪等リクエストか。true の場合のみ自動リトライ対象
   final bool idempotent;
 
-  const RequestOptions({this.authRequired = true, this.idempotent = false});
+  /// このリクエストのContent-Typeを明示的に指定する。未指定時はDioが推論する
+  final String? contentType;
+
+  /// このリクエスト固有の追加ヘッダ
+  final Map<String, String> headers;
+
+  /// Dioの`Options.extra`に引き継ぐ追加情報
+  final Map<String, dynamic> extra;
+
+  /// リクエスト単位のオプション
+  ///
+  /// - [authRequired]: 認証必須か（デフォルト: true）
+  /// - [idempotent]: 冪等なリクエストか（デフォルト: false）
+  /// - [contentType]: リクエストのContent-Type（未指定時はDioが推論）
+  /// - [headers]: リクエスト固有の追加ヘッダ
+  /// - [extra]: Dioの`Options.extra`へ渡す追加情報
+  const RequestOptions({
+    this.authRequired = true,
+    this.idempotent = false,
+    this.contentType,
+    this.headers = const {},
+    this.extra = const {},
+  });
 }