Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart
196 KB
Raw Blame
import 'dart:async';
import 'dart:convert';
import 'dart:math' as math;
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';
import 'package:package_info_plus/package_info_plus.dart';
import 'achievements.dart';
import 'auth_tokens.dart';
import 'book_dock.dart';
import 'book_requests.dart';
import 'bookorbit_admin.dart';
import 'bookorbit_email.dart';
import 'bookorbit_match.dart';
import 'bookorbit_mapper.dart';
import 'media_overlay.dart';
import 'narrated_books.dart';
import 'narration_stream.dart';
import 'bookorbit_media_proxy_stub.dart'
    if (dart.library.io) 'bookorbit_media_proxy.dart';
import 'player_settings.dart';
import 'bookorbit_chapters.dart';
import 'read_along_jobs.dart';
import 'scoped_prefs.dart';
import 'server_notifications.dart';
import 'server_backend.dart';
import 'socket_service.dart';
import '../models/auth_session.dart';
import '../utils/server_url.dart';
import '../utils/percent_escapes.dart';

part 'bookorbit_api_service.dart';
part 'bookorbit_admin_api.dart';
part 'bookorbit_email_api.dart';

/// Outcome of a local-session upsert. [serverTooOld] flags a 404/501 (the
/// server predates /api/session/local) so the caller can fall back to the
/// legacy /play flush instead of stranding the session in the replay queue.
class LocalSessionResult {
  final bool ok;
  final bool serverTooOld;
  const LocalSessionResult({required this.ok, required this.serverTooOld});
}

class MediaUploadFile {
  final String name;
  final int size;
  final String? path;
  final Uint8List? bytes;
  final Stream<List<int>>? readStream;

  const MediaUploadFile({
    required this.name,
    required this.size,
    this.path,
    this.bytes,
    this.readStream,
  });
}

class MediaUploadRequest {
  final String libraryId;
  final String folderId;
  final String mediaType;
  final String title;
  final String? author;
  final String? series;
  final List<MediaUploadFile> files;

  const MediaUploadRequest({
    required this.libraryId,
    required this.folderId,
    required this.mediaType,
    required this.title,
    this.author,
    this.series,
    required this.files,
  });

  String get directory {
    final parts = mediaType == 'podcast'
        ? <String?>[title]
        : <String?>[author, series, title];
    return parts
        .map((part) => part?.trim() ?? '')
        .where((part) => part.isNotEmpty)
        .join('/');
  }
}

class UploadPathCheckResult {
  final bool success;
  final bool exists;
  final String? libraryItemTitle;
  final String? error;

  const UploadPathCheckResult({
    required this.success,
    this.exists = false,
    this.libraryItemTitle,
    this.error,
  });
}

class MediaUploadResult {
  final bool success;
  final String? error;

  const MediaUploadResult({required this.success, this.error});
}

class AuthorQuickMatchResult {
  final int statusCode;
  final bool updated;
  final Map<String, dynamic>? author;

  const AuthorQuickMatchResult({
    required this.statusCode,
    this.updated = false,
    this.author,
  });

  bool get found => statusCode == 200;
}

class LibraryMetadataRemovalResult {
  final int found;
  final int removed;

  const LibraryMetadataRemovalResult({
    required this.found,
    required this.removed,
  });
}

enum _RefreshOutcome {
  refreshed,
  rejected,
  transientFailure,
}

enum PasswordChangeStatus {
  success,
  invalidPassword,
  unsupported,
  failed,
}

class PasswordChangeResult {
  final PasswordChangeStatus status;
  final String? message;

  const PasswordChangeResult(this.status, {this.message});
}

class ApiService {
  /// Remove sidecar metadata files from every item in a library (admin only).
  /// [extension] is the server-supported sidecar type: `json` or `abs`.
  Future<LibraryMetadataRemovalResult?> removeLibraryMetadataFiles(
    String libraryId,
    String extension,
  ) async {
    if (extension != 'json' && extension != 'abs') {
      throw ArgumentError.value(extension, 'extension', 'Must be json or abs');
    }
    try {
      final uri = Uri.parse(
        '$_cleanBaseUrl/api/libraries/$libraryId/remove-metadata',
      ).replace(queryParameters: {'ext': extension});
      final r = await _authPost(uri, timeout: const Duration(minutes: 30));
      if (r.statusCode != 200) {
        debugPrint('[API] removeLibraryMetadataFiles failed: ${r.statusCode}');
        return null;
      }
      final data = jsonDecode(r.body) as Map<String, dynamic>;
      return LibraryMetadataRemovalResult(
        found: (data['found'] as num?)?.toInt() ?? 0,
        removed: (data['removed'] as num?)?.toInt() ?? 0,
      );
    } catch (e) {
      debugPrint('[API] removeLibraryMetadataFiles error: $e');
      return null;
    }
  }

  Future<String?> validateCronExpression(String expression) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/validate-cron'),
        body: jsonEncode({'expression': expression}),
      );
      if (r.statusCode == 200) return null;
      final message = r.body.trim();
      return message.isEmpty ? 'Invalid cron expression' : message;
    } catch (e) {
      debugPrint('[API] validateCronExpression error: $e');
      return 'Could not validate the cron expression';
    }
  }

  /// Get the server's current daily log entries (admin only).
  ///
  /// GET /api/logger-data returns `{ currentDailyLogs: [...] }`. A nullable
  /// result distinguishes a request failure from a valid empty log file.
  Future<List<Map<String, dynamic>>?> getServerLogs() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/logger-data'));
      if (r.statusCode != 200) {
        debugPrint('[API] getServerLogs failed: ${r.statusCode}');
        return null;
      }
      final decoded = jsonDecode(r.body);
      if (decoded is! Map) return const <Map<String, dynamic>>[];
      final rawLogs = decoded['currentDailyLogs'];
      if (rawLogs is! List) return const <Map<String, dynamic>>[];
      return rawLogs
          .whereType<Map>()
          .map(
            (log) => log.map((key, value) => MapEntry(key.toString(), value)),
          )
          .toList(growable: false);
    } catch (e) {
      debugPrint('[API] getServerLogs error: $e');
      return null;
    }
  }

  static String appVersion = '1.3.0'; // fallback; overwritten by initVersion()
  static String appBuild = ''; // build number; set by initVersion()
  // The installed application id. The dev flavor installs beside the stable
  // app under its own id, so anything that names the package at runtime (the
  // cover content provider's authority) reads this rather than assuming.
  static String packageName = 'com.barnabas.absorb'; // set by initVersion()

  /// Version plus build (e.g. "1.9.1+198") for logs. `appVersion` stays clean
  /// because it's also sent to the server as clientVersion.
  static String get appVersionFull =>
      appBuild.isEmpty ? appVersion : '$appVersion+$appBuild';

  /// Audible region code derived from device locale.
  static String get _region {
    final locale = PlatformDispatcher.instance.locale;
    final code = (locale.countryCode ?? 'us').toLowerCase();
    return code == 'gb' ? 'uk' : code;
  }

  /// Current Audible region/TLD for default region in series discovery UI.
  static String get debugRegion => _region;
  static String get debugTld => _audibleTld;

  /// Call once at startup to read the real version from pubspec via package_info_plus.
  static Future<void> initVersion() async {
    try {
      final info = await PackageInfo.fromPlatform();
      appVersion = info.version;
      appBuild = info.buildNumber;
      if (info.packageName.isNotEmpty) packageName = info.packageName;
    } catch (_) {}
  }

  final String baseUrl;
  String _accessToken;
  String? _refreshToken;
  final bool _isLegacyToken;
  final Map<String, String> customHeaders;
  final http.Client? _httpClient;

  /// Called after a successful token refresh so the auth layer can persist.
  /// Returns whether the pair actually reached storage - a rotation that only
  /// lives in memory dies with the process and leaves a spent refresh token
  /// behind, so callers must be able to tell the difference.
  FutureOr<bool> Function(String newAccessToken, String? newRefreshToken)? onTokensRefreshed;

  /// Loads the latest persisted tokens before refreshing. Background isolates
  /// can rotate tokens while this instance is still alive, so the store is the
  /// only source of truth shared by every ApiService holder.
  Future<AuthTokens?> Function()? loadPersistedTokens;

  /// Called when refresh fails and the user must re-login.
  VoidCallback? onAuthExpired;

  final Duration _refreshRetryDelay;

  // Each ApiService instance already deduplicates its own refreshes. This lock
  // also serializes token rotation across the short-lived instances created by
  // providers, widgets, and the background browse service.
  Completer<_RefreshOutcome>? _refreshCompleter;
  static Completer<void>? _tokenMutationCompleter;

  // Device info - set once at app start
  static String deviceManufacturer = '';
  static String deviceModel = '';
  static String deviceId = '';
  static int deviceSdkInt = 0;

  /// Generate or load a persistent unique device ID
  static Future<void> initDeviceId() async {
    final prefs = await SharedPreferences.getInstance();
    var id = prefs.getString('absorb_device_id');
    if (id == null || id.isEmpty) {
      id = 'absorb-${DateTime.now().millisecondsSinceEpoch.toRadixString(36)}-${(DateTime.now().microsecond * 31337).toRadixString(36)}';
      await prefs.setString('absorb_device_id', id);
    }
    deviceId = id;
  }

  ApiService({
    required this.baseUrl,
    required String token,
    String? refreshToken,
    bool isLegacyToken = false,
    this.customHeaders = const {},
    this.onTokensRefreshed,
    this.loadPersistedTokens,
    this.onAuthExpired,
    Duration refreshRetryDelay = const Duration(milliseconds: 250),
    http.Client? httpClient,
  })  : _accessToken = token,
        _refreshToken = refreshToken,
        _isLegacyToken = isLegacyToken,
        _refreshRetryDelay = refreshRetryDelay,
        _httpClient = httpClient {
    _loadCachedServerVersion(baseUrl);
  }

  /// The ApiService for a signed-in session: the plain Audiobookshelf client,
  /// or the BookOrbit one that answers in Audiobookshelf shapes. [backend]
  /// defaults to the active session's.
  factory ApiService.forSession({
    required String baseUrl,
    required String token,
    String? refreshToken,
    bool isLegacyToken = false,
    Map<String, String> customHeaders = const {},
    FutureOr<bool> Function(String newAccessToken, String? newRefreshToken)?
        onTokensRefreshed,
    Future<AuthTokens?> Function()? loadPersistedTokens,
    VoidCallback? onAuthExpired,
    ServerBackend? backend,
  }) {
    if ((backend ?? ServerBackend.active).isBookOrbit) {
      return BookOrbitApiService(
        baseUrl: baseUrl,
        token: token,
        refreshToken: refreshToken,
        isLegacyToken: isLegacyToken,
        customHeaders: customHeaders,
        onTokensRefreshed: onTokensRefreshed,
        loadPersistedTokens: loadPersistedTokens,
        onAuthExpired: onAuthExpired,
      );
    }
    return ApiService(
      baseUrl: baseUrl,
      token: token,
      refreshToken: refreshToken,
      isLegacyToken: isLegacyToken,
      customHeaders: customHeaders,
      onTokensRefreshed: onTokensRefreshed,
      loadPersistedTokens: loadPersistedTokens,
      onAuthExpired: onAuthExpired,
    );
  }

  ServerBackend get backend => ServerBackend.audiobookshelf;
  bool get isBookOrbit => backend.isBookOrbit;

  /// Await before handing media URLs to something that fetches them right
  /// away. Only BookOrbit has anything to wait for (its media proxy).
  Future<void> ensureMediaReady() async {}

  Future<ApiService> withMediaReady() async {
    await ensureMediaReady();
    return this;
  }

  /// URL for downloading an ebook file for the reader.
  String buildEbookUrl(String itemId, String ino) =>
      '$_cleanBaseUrl/api/items/$itemId/file/$ino?token=$token';

  /// The ebook the reader caches, which may leave out what reading doesn't
  /// need (BookOrbit's narrated EPUBs come without their audio).
  String buildReaderEbookUrl(String itemId, String ino) => buildEbookUrl(itemId, ino);

  /// How many pages a comic file has, when the server hands them out one at
  /// a time (BookOrbit, which opens CBR and CB7 too). Null means the archive
  /// has to be opened on the phone.
  Future<int?> comicPageCount(String fileId) async => null;

  /// Image of comic page [index] (from 0), when [comicPageCount] answered.
  String? comicPageUrl(String fileId, int index) => null;

  /// The server's ebook bookmarks for an item, as {id, cfi, title, note},
  /// or null when the server keeps none (Audiobookshelf) or can't be reached.
  Future<List<Map<String, dynamic>>?> ebookBookmarks(String itemId) async => null;

  /// One page of a collection's books, for a server whose collection listing
  /// holds only the first ones. Audiobookshelf sends every book up front.
  Future<List<Map<String, dynamic>>?> collectionBooksPage(String collectionId,
          {required int page, int size = 100}) async =>
      null;

  /// Saves an ebook bookmark at [cfi] on the server. Returns its server id,
  /// or null when the server keeps none or the save failed.
  Future<String?> addEbookBookmark(String itemId, {required String cfi, required String title}) async => null;

  /// Removes a server ebook bookmark. True when it's gone (or never existed).
  Future<bool> deleteEbookBookmark(String itemId, String bookmarkId) async => false;

  /// Whether the server keeps ebook highlights too, so they sync both ways.
  bool get keepsEbookHighlights => false;

  /// The server's highlights in a book, as {id, cfi, fileId, text, color,
  /// note, chapter, at}, or null when it keeps none or can't be reached.
  /// With [fileId], a server that can also places highlights made in other
  /// copies of the book (a Kobo's or KOReader's) on that file.
  Future<List<Map<String, dynamic>>?> ebookHighlights(String itemId, {String? fileId}) async => null;

  /// Saves a highlight in the book file [fileId] on the server. Returns its
  /// server id, or null when the server keeps none or the save failed.
  Future<String?> addEbookHighlight(String itemId, String fileId,
          {required String cfi, required String text, required String color, String? note, String? chapter}) async =>
      null;

  /// Sets a server highlight's color and note. True when saved, or when the
  /// highlight is already gone there.
  Future<bool> updateEbookHighlight(String itemId, String highlightId, {required String color, String? note}) async =>
      false;

  /// Removes a server highlight. True when it's gone (or never existed).
  Future<bool> deleteEbookHighlight(String itemId, String highlightId) async => false;

  /// The cover slots a book uses on BookOrbit ('audio', 'ebook'). Empty on
  /// Audiobookshelf, which has one cover per item.
  Future<List<String>> coverSlots(String itemId) async => const [];

  /// The cover search source the user picked as default on the server.
  Future<String?> defaultCoverSearchProvider() async => null;

  /// Books the server thinks are like [itemId], as {id, title, authorName,
  /// hasCover, isAudiobook, finished}. Only BookOrbit has this.
  Future<List<Map<String, dynamic>>> getSimilarBooks(String itemId) async => const [];

  /// BookOrbit's per-user reading status (want_to_read, on_hold, ...).
  Future<bool> setReadStatus(String itemId, String status) async => false;

  /// A private note on a book, or null to remove it. Only BookOrbit has this.
  Future<bool> setPersonalNote(String itemId, String? note) async => false;

  /// The metadata providers the server has turned on, as {key, label}, when
  /// it can say. Null means the app's own list applies.
  Future<List<Map<String, String>>?> bookMatchProviders() async => null;

  /// URL a background download fetches [ino] from. Same as [buildFileUrl]
  /// on Audiobookshelf.
  String buildDownloadFileUrl(String itemId, String ino) => buildFileUrl(itemId, ino);

  /// Headers for a download of [url] built by [buildDownloadFileUrl].
  Map<String, String> downloadHeadersFor(String url) => mediaHeaders;

  /// Sign-in headers for a download the server turned away because the ones
  /// it started with ran out.
  Future<Map<String, String>> renewedMediaHeaders() async {
    await _ensureFreshAccessToken();
    return mediaHeaders;
  }

  /// The access token, renewed first when it is about to run out, for a
  /// connection that signs in with the token itself.
  Future<String> freshAccessToken() async {
    await _ensureFreshAccessToken();
    return _accessToken;
  }

  /// Where a narrated EPUB downloads whole from, and the headers it needs,
  /// for the download that takes its audio out on the phone.
  Future<({String url, Map<String, String> headers})> narratedEpubDownload(String itemId, String ino) async {
    final url = buildDownloadFileUrl(itemId, ino);
    return (url: url, headers: downloadHeadersFor(url));
  }

  /// Called once before a book's files are queued for download.
  Future<void> prepareDownload(String itemId) async {}

  /// Where a download fetches a narrated EPUB's audio file from, for track
  /// [contentUrl]; null when this server has no such tracks.
  String? buildNarrationDownloadUrl(String itemId, String contentUrl) => null;

  /// Show a collection to everyone on the server or only its owner. Only
  /// BookOrbit has this; Audiobookshelf collections are always shared.
  Future<bool> setCollectionPublic(String collectionId, bool isPublic) async => false;

  /// BookOrbit's Book Dock (its import inbox) shows as a library with this
  /// id for accounts allowed to use it. Its items are dock files, not books:
  /// they can be edited, filed into a real library or removed, not played.
  static const bookDockLibraryId = 'book-dock';
  static bool isBookDockItem(String itemId) => itemId.startsWith('dock-');

  /// The library folders a dock file can be filed into; empty when this
  /// account may not add books to a library.
  Future<List<BookDockDestination>> bookDockDestinations() async => const [];

  /// File dock item [itemId] into [destination].
  Future<BookDockFileResult> fileBookDockItem(
          String itemId, BookDockDestination destination) async =>
      const BookDockFileResult(success: false);

  /// Remove a dock item and its file from the server.
  Future<bool> removeBookDockItem(String itemId) async => false;

  /// Copy the details the server found online over the dock item's own.
  Future<bool> useFoundBookDockDetails(String itemId) async => false;

  /// Ask the server to look the dock item's details up online again.
  Future<bool> lookUpBookDockDetails(String itemId) async => false;

  /// BookOrbit's metadata search over every source it has turned on, as
  /// results arrive. Empty on Audiobookshelf.
  Stream<MatchSearchEvent> searchMatches(
    String itemId, {
    String? title,
    String? author,
    String? isbn,
    bool? isAudiobook,
    String? mediaKind,
    List<String>? mediaKinds,
  }) =>
      const Stream.empty();

  /// What the account may do with BookOrbit book requests. Nothing on
  /// Audiobookshelf.
  Future<BookRequestAccess> bookRequestAccess() async => BookRequestAccess.none;

  /// Whether the account has a notification list on the server. Only
  /// BookOrbit keeps one.
  Future<bool> hasServerNotifications() async => false;

  /// A page of the account's notifications, newest first.
  Future<({List<ServerNotification> items, int total})?> serverNotifications({int limit = 20, int offset = 0}) async =>
      null;

  Future<int?> unreadNotificationCount() async => null;
  Future<bool> markNotificationRead(int id) async => false;
  Future<bool> markAllNotificationsRead() async => false;
  Future<bool> dismissNotification(int id) async => false;
  Future<bool> clearNotifications() async => false;

  /// The level each notification category is set to, by category.
  Future<Map<String, String>?> notificationLevels() async => null;
  Future<bool> setNotificationLevels(Map<String, String> levels) async => false;

  /// Whether the account keeps achievements, null where there are none.
  /// BookOrbit's own account switch, so it reads the same everywhere.
  Future<bool?> achievementsEnabled() async => null;
  Future<bool> setAchievementsEnabled(bool enabled) async => false;

  /// The account's achievements. Only BookOrbit has them.
  Future<AchievementCatalogue?> achievements({bool fresh = false}) async => null;
  Future<List<AchievementHint>> achievementHints() async => const [];

  /// One page of the account's own requests, or everyone's with [all].
  Future<({List<BookRequest> items, int total})?> bookRequests({
    bool all = false,
    int page = 1,
    int limit = 25,
    bool includeDismissed = false,
  }) async =>
      null;

  /// Whether each record is already in a library or asked for, in order.
  Future<List<BookRequestAvailability?>> bookRequestAvailability(
    List<MatchCandidate> records,
    String mediaKind,
  ) async =>
      [for (final _ in records) null];

  Future<BookRequestSubmitResult> submitBookRequest(Map<String, dynamic> body) async =>
      const BookRequestSubmitResult();

  /// Asks for the e-book and the audiobook together, on servers whose
  /// [BookRequestAccess.pairs] is set.
  Future<BookRequestPairResult> submitBookRequestPair(Map<String, dynamic> body) async =>
      const BookRequestPairResult();

  Future<({bool ok, BookRequest? request, String? error})> bookRequestAction(
    int id,
    BookRequestAction action, {
    String? note,
    int? libraryId,
    int? downloadId,
  }) async =>
      (ok: false, request: null, error: null);

  /// Releases the indexers offer for request [id]. [terms] searches with
  /// other words than the request's own; a null ISBN searches by title and
  /// author.
  Future<({BookRequestReleases? releases, String? error})> bookRequestReleases(
    int id, {
    bool refresh = false,
    ({String title, String author, String? isbn})? terms,
  }) async =>
      (releases: null, error: null);

  /// What a release holds. 'no_supported_file' means nothing in it can be
  /// filed into a library.
  Future<({String? status, String? error})> inspectBookRequestRelease(int id, int indexerId, String guid) async =>
      (status: null, error: null);

  /// Sends the picked release to the download client.
  Future<({BookRequest? request, String? error})> grabBookRequestRelease(int id, int indexerId, String guid) async =>
      (request: null, error: null);

  /// Why a downloaded request is waiting for a manual check.
  Future<({BookRequestReview? review, String? error})> bookRequestReview(int id) async =>
      (review: null, error: null);

  /// The library each kind of request lands in when nobody picks one.
  Future<Map<String, int>> bookRequestDefaultLibraries() async => const {};

  /// Current access token (for external use like cover URLs, socket auth).
  String get token => _accessToken;

  bool get hasRefreshToken => _refreshToken?.isNotEmpty == true;
  bool get isLegacyToken => _isLegacyToken;

  static String get userAgent => 'Absorb/$appVersionFull';

  Map<String, String> get _headers => {
        ...customHeaders,
        'Authorization': 'Bearer $_accessToken',
        'Content-Type': 'application/json',
      };

  /// Public headers for image/audio requests (no Content-Type needed).
  Map<String, String> get mediaHeaders => {
        ...customHeaders,
        'Authorization': 'Bearer $_accessToken',
      };

  /// Playback-session tracks use ABS's unguessable public session URLs, so
  /// only reverse-proxy headers belong on the media request. Keeping the
  /// account token off the AVPlayer/ExoPlayer source prevents token rotation
  /// from invalidating a stream that is already playing.
  Map<String, String> get playbackSessionHeaders => {...customHeaders};

  String get _cleanBaseUrl => normalizeServerUrl(baseUrl);

  Future<http.Response> _get(Uri url, {Map<String, String>? headers}) {
    return _httpClient?.get(url, headers: headers) ?? http.get(url, headers: headers);
  }

  Future<http.Response> _post(Uri url, {Map<String, String>? headers, Object? body}) {
    return _httpClient?.post(url, headers: headers, body: body) ??
        http.post(url, headers: headers, body: body);
  }

  Future<http.Response> _patch(Uri url, {Map<String, String>? headers, Object? body}) {
    return _httpClient?.patch(url, headers: headers, body: body) ??
        http.patch(url, headers: headers, body: body);
  }

  Future<http.Response> _delete(Uri url, {Map<String, String>? headers}) {
    return _httpClient?.delete(url, headers: headers) ?? http.delete(url, headers: headers);
  }

  /// Loggable token identity: length plus the signature tail, enough to tell
  /// token A from token B across a log without exposing the credential.
  static String tokenFp(String? token) {
    if (token == null || token.isEmpty) return 'none';
    final tail = token.length <= 8 ? token : token.substring(token.length - 8);
    return '${token.length}:$tail';
  }

  Future<bool> _adoptPersistedTokens() async {
    final loader = loadPersistedTokens;
    if (loader == null) return false;

    final previousAccess = _accessToken;
    try {
      final persisted = await loader();
      final persistedAccess = persisted?.accessToken;
      if (persistedAccess == null) return false;
      _accessToken = persistedAccess;
      if (persisted?.refreshToken != null) {
        _refreshToken = persisted!.refreshToken;
      }
      final adopted = _accessToken != previousAccess;
      if (adopted) {
        debugPrint(
          '[API] Adopted persisted tokens: access=${tokenFp(_accessToken)} '
          'refresh=${tokenFp(_refreshToken)}',
        );
        await _notifyTokensRefreshed();
      }
      return adopted;
    } catch (e) {
      debugPrint('[API] Failed to reload persisted tokens: $e');
      return false;
    }
  }

  Future<void> _notifyTokensRefreshed() async {
    try {
      final persisted = await onTokensRefreshed?.call(_accessToken, _refreshToken);
      debugPrint(
        persisted == false
            ? '[API] Tokens NOT persisted (rotation held in memory only): '
                  'access=${tokenFp(_accessToken)} '
                  'refresh=${tokenFp(_refreshToken)}'
            : '[API] Tokens handed to persistence: access=${tokenFp(_accessToken)} '
                  'refresh=${tokenFp(_refreshToken)}',
      );
    } catch (e) {
      debugPrint('[API] Failed to persist refreshed tokens: $e');
    }
  }

  Future<Completer<void>> _acquireTokenMutationLock() async {
    while (_tokenMutationCompleter != null) {
      await _tokenMutationCompleter!.future;
    }
    final lock = Completer<void>();
    _tokenMutationCompleter = lock;
    return lock;
  }

  void _releaseTokenMutationLock(Completer<void> lock) {
    if (identical(_tokenMutationCompleter, lock)) {
      _tokenMutationCompleter = null;
    }
    if (!lock.isCompleted) lock.complete();
  }

  Future<http.Response> _sendRefresh(String refreshToken) => _post(
        Uri.parse('$_cleanBaseUrl/auth/refresh'),
        headers: {
          ...customHeaders,
          'x-refresh-token': refreshToken,
          if (!kIsWeb) 'User-Agent': userAgent,
        },
      );

  Future<bool> _refreshTokenPairOnce() async {
    final refreshToken = _refreshToken;
    if (_isLegacyToken || refreshToken == null) return false;
    try {
      final response = await _sendRefresh(refreshToken)
          .timeout(const Duration(seconds: 15));
      if (response.statusCode != 200) {
        debugPrint(
          '[API] Proactive token refresh failed: ${response.statusCode} '
          '(refresh=${tokenFp(refreshToken)})',
        );
        return false;
      }
      final data = jsonDecode(response.body) as Map<String, dynamic>;
      final tokens = AuthTokens.fromResponse(data);
      if (tokens.accessToken == null || tokens.refreshToken == null) return false;
      _accessToken = tokens.accessToken!;
      _refreshToken = tokens.refreshToken!;
      await _notifyTokensRefreshed();
      debugPrint(
        '[API] Proactive token refresh ok -> '
        'refresh=${tokenFp(_refreshToken)}',
      );
      return true;
    } catch (_) {
      return false;
    }
  }

  /// An API key can't be refreshed, so a 401 on one may mean it was revoked.
  /// Ask the server once whether it still knows the key before signing out,
  /// so a stray 401 from something in between doesn't end the session.
  static DateTime? _apiKeyCheckedAt;
  static bool _apiKeyCheckRunning = false;

  void _checkRevokedApiKey() {
    if (isBookOrbit || _apiKeyCheckRunning) return;
    final last = _apiKeyCheckedAt;
    if (last != null && DateTime.now().difference(last) < const Duration(minutes: 1)) return;
    _apiKeyCheckedAt = DateTime.now();
    _apiKeyCheckRunning = true;
    () async {
      try {
        final r = await _get(Uri.parse('$_cleanBaseUrl/api/me'), headers: _headers)
            .timeout(const Duration(seconds: 15));
        if (r.statusCode == 401) {
          debugPrint('[API] The server no longer accepts this API key');
          onAuthExpired?.call();
        }
      } catch (_) {
      } finally {
        _apiKeyCheckRunning = false;
      }
    }();
  }

  /// Gets a new access token now, whatever this phone makes of the old one's
  /// age: the server said it has run out. True once a new one is in hand.
  Future<bool> refreshAccessTokenNow() async {
    final outcome = await _refreshAccessToken();
    if (outcome == _RefreshOutcome.rejected) onAuthExpired?.call();
    return outcome == _RefreshOutcome.refreshed;
  }

  /// Attempt to refresh the access token using the refresh token. A rejected
  /// refresh is kept distinct from a temporary network/server failure so only
  /// an explicit 401/403 can expire the local session.
  Future<_RefreshOutcome> _refreshAccessToken() async {
    if (_isLegacyToken || _refreshToken == null) {
      debugPrint('[API] Cannot refresh: isLegacy=$_isLegacyToken, hasRefreshToken=${_refreshToken != null}');
      return _RefreshOutcome.transientFailure;
    }

    // If a refresh is already in progress, wait for it
    if (_refreshCompleter != null) {
      debugPrint('[API] Token refresh joining in-flight attempt');
      return _refreshCompleter!.future;
    }

    debugPrint(
      '[API] Token refresh start: access=${tokenFp(_accessToken)} '
      'refresh=${tokenFp(_refreshToken)}',
    );
    _refreshCompleter = Completer<_RefreshOutcome>();
    final mutationLock = await _acquireTokenMutationLock();
    try {
      if (await _adoptPersistedTokens()) {
        _refreshCompleter!.complete(_RefreshOutcome.refreshed);
        return _RefreshOutcome.refreshed;
      }

      for (var attempt = 0; attempt < 2; attempt++) {
        final refreshTokenSent = _refreshToken;
        if (refreshTokenSent == null) break;

        try {
          // Timeout is load-bearing: this is awaited from tryRestoreSession via
          // the 401-retry path, and a stalled response here would otherwise hold
          // the splash screen forever.
          final response = await _sendRefresh(refreshTokenSent)
              .timeout(const Duration(seconds: 15));

          if (response.statusCode == 200) {
            final data = jsonDecode(response.body) as Map<String, dynamic>;
            final tokens = AuthTokens.fromResponse(data);
            final newAccess = tokens.accessToken;
            final newRefresh = tokens.refreshToken;
            if (newAccess != null) {
              _accessToken = newAccess;
              if (newRefresh != null) _refreshToken = newRefresh;
              await _notifyTokensRefreshed();
              debugPrint(
                '[API] Token refreshed successfully -> '
                'access=${tokenFp(newAccess)} refresh=${tokenFp(newRefresh)} '
                'rotated=${newRefresh != null && newRefresh != refreshTokenSent}',
              );
              _refreshCompleter!.complete(_RefreshOutcome.refreshed);
              return _RefreshOutcome.refreshed;
            }
          }

          if (response.statusCode == 401 || response.statusCode == 403) {
            if (await _adoptPersistedTokens()) {
              _refreshCompleter!.complete(_RefreshOutcome.refreshed);
              return _RefreshOutcome.refreshed;
            }
            if (_refreshToken != refreshTokenSent && attempt == 0) continue;
            debugPrint(
              '[API] Token refresh rejected: ${response.statusCode} '
              '(sent refresh=${tokenFp(refreshTokenSent)})'
              '${_refreshToken == refreshTokenSent ? " - storage holds the same spent token, session is dead until re-login" : ""}',
            );
            _refreshCompleter!.complete(_RefreshOutcome.rejected);
            return _RefreshOutcome.rejected;
          }

          debugPrint('[API] Token refresh failed: ${response.statusCode}');
        } catch (e) {
          debugPrint('[API] Token refresh error: $e');
        }

        if (attempt == 0) {
          await Future<void>.delayed(_refreshRetryDelay);
          if (await _adoptPersistedTokens()) {
            _refreshCompleter!.complete(_RefreshOutcome.refreshed);
            return _RefreshOutcome.refreshed;
          }
        }
      }

      _refreshCompleter!.complete(_RefreshOutcome.transientFailure);
      return _RefreshOutcome.transientFailure;
    } finally {
      _refreshCompleter = null;
      _releaseTokenMutationLock(mutationLock);
    }
  }

  /// Seconds of headroom before the access token's own expiry at which we stop
  /// trusting it. Generous because a slow request that starts valid can still
  /// arrive expired.
  static const _accessTokenSkew = Duration(seconds: 60);

  /// Expiry stamped in the access token, or null when it can't be read
  /// (legacy static tokens, opaque tokens, malformed payloads).
  DateTime? get _accessTokenExpiry {
    final parts = _accessToken.split('.');
    if (parts.length != 3) return null;
    try {
      final payload = jsonDecode(
        utf8.decode(base64Url.decode(base64Url.normalize(parts[1]))),
      );
      if (payload is! Map) return null;
      final exp = payload['exp'];
      if (exp is! int) return null;
      return DateTime.fromMillisecondsSinceEpoch(exp * 1000);
    } catch (_) {
      return null;
    }
  }

  /// Suppresses the pre-flight after a refresh that couldn't reach the server.
  /// Static because callers construct a fresh ApiService per use.
  static DateTime? _preflightCooldownUntil;
  static const _preflightCooldown = Duration(minutes: 2);

  /// Static state outlives a single test, so a test that trips the cooldown
  /// would otherwise silently disable the pre-flight for whatever runs next.
  @visibleForTesting
  static void resetPreflightCooldown() {
    _preflightCooldownUntil = null;
    _apiKeyCheckedAt = null;
    _apiKeyCheckRunning = false;
  }

  /// Refresh BEFORE spending a known-expired access token, rather than firing
  /// the request, taking a 401, and recovering afterwards.
  ///
  /// Reactive-only refresh means every parallel call that happens to fall after
  /// expiry races into its own recovery - four concurrent refreshes inside one
  /// second showed up in the 2026-08-13 logout log - and it widens the window
  /// in which a rotation can be lost. The server's grace period for a spent
  /// refresh token is only ten minutes, so noticing early matters.
  ///
  /// The cooldown is what keeps this from being worse than the old behaviour
  /// when the server is routable but not answering (LAN-only server, away from
  /// home): without it every call would spend two 15s refresh timeouts, holding
  /// the token mutation lock, before its own request even started - so a
  /// handful of queued calls turn into minutes. After one unreachable attempt
  /// we go back to letting the request itself fail.
  Future<void> _ensureFreshAccessToken() async {
    if (_isLegacyToken || _refreshToken == null) return;
    final cooldownUntil = _preflightCooldownUntil;
    if (cooldownUntil != null && DateTime.now().isBefore(cooldownUntil)) return;
    final expiry = _accessTokenExpiry;
    if (expiry == null) return;
    if (DateTime.now().add(_accessTokenSkew).isBefore(expiry)) return;
    final outcome = await _refreshAccessToken();
    switch (outcome) {
      case _RefreshOutcome.refreshed:
        _preflightCooldownUntil = null;
      case _RefreshOutcome.rejected:
        _preflightCooldownUntil = null;
        onAuthExpired?.call();
      case _RefreshOutcome.transientFailure:
        _preflightCooldownUntil = DateTime.now().add(_preflightCooldown);
        debugPrint(
          '[API] Pre-flight refresh could not reach the server - '
          'falling back to on-401 refresh for '
          '${_preflightCooldown.inMinutes}m',
        );
    }
  }

  /// Make an authenticated GET request, retrying once on 401 with a refreshed token.
  ///
  /// [sendRefreshTokenHeader] adds `x-refresh-token` from whatever the current
  /// pair is once the pre-flight has run, rather than from a value the caller
  /// captured earlier.
  Future<http.Response> _authGet(Uri url, {Map<String, String>? headers, bool sendRefreshTokenHeader = false, Duration timeout = const Duration(seconds: 15)}) async {
    await _ensureFreshAccessToken();
    var h = headers ?? _headers;
    if (sendRefreshTokenHeader && _refreshToken != null) {
      h = {...h, 'x-refresh-token': _refreshToken!};
    }
    var response = await _get(url, headers: h).timeout(timeout);
    if (response.statusCode == 401) {
      debugPrint('[API] 401 on GET ${url.path} - isLegacy=$_isLegacyToken, hasRefresh=${_refreshToken != null}, tokenLen=${_accessToken.length}');
    }
    if (response.statusCode == 401 && !_isLegacyToken) {
      final outcome = await _refreshAccessToken();
      if (outcome == _RefreshOutcome.refreshed) {
        final refreshedHeaders = Map<String, String>.from(h)
          ..['Authorization'] = 'Bearer $_accessToken';
        if (refreshedHeaders.containsKey('x-refresh-token') &&
            _refreshToken != null) {
          refreshedHeaders['x-refresh-token'] = _refreshToken!;
        }
        response = await _get(url, headers: refreshedHeaders).timeout(timeout);
      }
      if (outcome == _RefreshOutcome.rejected) onAuthExpired?.call();
    } else if (response.statusCode == 401) {
      _checkRevokedApiKey();
    }
    return response;
  }

  /// Make an authenticated POST request, retrying once on 401 with a refreshed token.
  Future<http.Response> _authPost(Uri url, {Map<String, String>? headers, Object? body, Duration timeout = const Duration(seconds: 15)}) async {
    await _ensureFreshAccessToken();
    final h = headers ?? _headers;
    var response = await _post(url, headers: h, body: body).timeout(timeout);
    if (response.statusCode == 401 && !_isLegacyToken) {
      final outcome = await _refreshAccessToken();
      if (outcome == _RefreshOutcome.refreshed) {
        final refreshedHeaders = Map<String, String>.from(h)
          ..['Authorization'] = 'Bearer $_accessToken';
        response = await _post(url, headers: refreshedHeaders, body: body).timeout(timeout);
      }
      if (outcome == _RefreshOutcome.rejected) onAuthExpired?.call();
    } else if (response.statusCode == 401) {
      _checkRevokedApiKey();
    }
    return response;
  }

  /// Make an authenticated PATCH request, retrying once on 401 with a refreshed token.
  Future<http.Response> _authPatch(Uri url, {Map<String, String>? headers, Object? body, Duration timeout = const Duration(seconds: 15)}) async {
    await _ensureFreshAccessToken();
    final h = headers ?? _headers;
    var response = await _patch(url, headers: h, body: body).timeout(timeout);
    if (response.statusCode == 401 && !_isLegacyToken) {
      final outcome = await _refreshAccessToken();
      if (outcome == _RefreshOutcome.refreshed) {
        final refreshedHeaders = Map<String, String>.from(h)
          ..['Authorization'] = 'Bearer $_accessToken';
        response = await _patch(url, headers: refreshedHeaders, body: body).timeout(timeout);
      }
      if (outcome == _RefreshOutcome.rejected) onAuthExpired?.call();
    } else if (response.statusCode == 401) {
      _checkRevokedApiKey();
    }
    return response;
  }

  /// Make an authenticated DELETE request, retrying once on 401 with a refreshed token.
  Future<http.Response> _authDelete(Uri url, {Map<String, String>? headers, Duration timeout = const Duration(seconds: 15)}) async {
    await _ensureFreshAccessToken();
    final h = headers ?? _headers;
    var response = await _delete(url, headers: h).timeout(timeout);
    if (response.statusCode == 401 && !_isLegacyToken) {
      final outcome = await _refreshAccessToken();
      if (outcome == _RefreshOutcome.refreshed) {
        final refreshedHeaders = Map<String, String>.from(h)
          ..['Authorization'] = 'Bearer $_accessToken';
        response = await _delete(url, headers: refreshedHeaders).timeout(timeout);
      }
      if (outcome == _RefreshOutcome.rejected) onAuthExpired?.call();
    } else if (response.statusCode == 401) {
      _checkRevokedApiKey();
    }
    return response;
  }

  /// Login and return the full response JSON (contains user, token, etc.) and HTTP status code.
  static Future<(Map<String, dynamic>?, int)> login({
    required String serverUrl,
    required String username,
    required String password,
    Map<String, String> customHeaders = const {},
    ServerBackend backend = ServerBackend.audiobookshelf,
  }) async {
    if (backend.isBookOrbit) {
      return BookOrbitApiService.signIn(
        serverUrl: serverUrl,
        username: username,
        password: password,
        customHeaders: customHeaders,
      );
    }
    final url = serverUrl.endsWith('/')
        ? '${serverUrl}login'
        : '$serverUrl/login';

    try {
      final response = await http.post(
        Uri.parse(url),
        headers: {
          ...customHeaders,
          'Content-Type': 'application/json',
          'x-return-tokens': 'true',
          if (!kIsWeb) 'User-Agent': userAgent,
        },
        body: jsonEncode({'username': username, 'password': password}),
      // A server that takes the connection and then never answers (a proxy
      // up with the server behind it down) left the sign-in spinning forever.
      ).timeout(const Duration(seconds: 20));

      if (response.statusCode == 200) {
        return (jsonDecode(response.body) as Map<String, dynamic>, 200);
      }
      return (null, response.statusCode);
    } on TimeoutException {
      debugPrint('[API] login to $url got no answer in 20s');
      return (null, 0);
    } catch (e) {
      return (null, 0);
    }
  }

  /// Validate an API key by hitting `/api/me`. Returns the user JSON and the
  /// HTTP status code. API keys are sent as a Bearer token, same as JWT/legacy
  /// tokens, so successful validation lets us reuse the legacy-token path
  /// (no refresh, persists like any other session).
  static Future<(Map<String, dynamic>?, int)> loginWithApiKey({
    required String serverUrl,
    required String apiKey,
    Map<String, String> customHeaders = const {},
    ServerBackend backend = ServerBackend.audiobookshelf,
  }) async {
    if (backend.isBookOrbit) return (null, 0);
    final base = serverUrl.endsWith('/') ? serverUrl : '$serverUrl/';
    final url = '${base}api/me';

    try {
      final response = await http.get(
        Uri.parse(url),
        headers: {...customHeaders, 'Authorization': 'Bearer $apiKey'},
      ).timeout(const Duration(seconds: 15));

      if (response.statusCode == 200) {
        return (jsonDecode(response.body) as Map<String, dynamic>, 200);
      }
      return (null, response.statusCode);
    } catch (_) {
      return (null, 0);
    }
  }

  /// Ping the server to check connectivity.
  static Future<bool> pingServer(String serverUrl, {Map<String, String> customHeaders = const {}, ServerBackend? backend}) async {
    if ((backend ?? ServerBackend.active).isBookOrbit) {
      return (await BookOrbitApiService.probe(serverUrl, customHeaders: customHeaders)).ok;
    }
    final url = serverUrl.endsWith('/')
        ? '${serverUrl}ping'
        : '$serverUrl/ping';
    try {
      final response = await http.get(Uri.parse(url), headers: customHeaders.isNotEmpty ? customHeaders : null)
          .timeout(const Duration(seconds: 10));
      return response.statusCode == 200;
    } catch (_) {
      return false;
    }
  }

  /// Ping the server and report why it failed, for the login screen. The
  /// plain [pingServer] collapses every failure into a single false, which
  /// leaves users (and us) blind when a server reachable in a browser won't
  /// connect in the app - usually a proxy/CDN treating the app's request
  /// differently than a browser. Kept separate so the connectivity hot paths
  /// keep their lean bool + short timeouts. [detail] is null on success.
  static Future<({bool ok, String? detail})> pingServerDetailed(
    String serverUrl, {
    Map<String, String> customHeaders = const {},
    ServerBackend? backend,
  }) async {
    if ((backend ?? ServerBackend.active).isBookOrbit) {
      return BookOrbitApiService.probe(
        serverUrl,
        customHeaders: customHeaders,
        timeout: const Duration(seconds: 15),
      );
    }
    final url = serverUrl.endsWith('/') ? '${serverUrl}ping' : '$serverUrl/ping';
    try {
      final response = await http
          .get(Uri.parse(url), headers: customHeaders.isNotEmpty ? customHeaders : null)
          .timeout(const Duration(seconds: 15));
      if (response.statusCode == 200) return (ok: true, detail: null);
      return (ok: false, detail: 'Server returned HTTP ${response.statusCode} instead of 200.');
    } catch (e) {
      return (ok: false, detail: _describePingError(e));
    }
  }

  /// Turn a raw ping exception into a plain-language reason. Classifies by
  /// message text rather than type because the http package flattens socket
  /// and TLS errors into ClientException, hiding the original class.
  static String _describePingError(Object e) {
    if (e is TimeoutException) {
      return 'Timed out after 15s. The server is slow to respond, or something on the way is dropping the connection.';
    }
    final msg = e.toString();
    final lower = msg.toLowerCase();
    if (lower.contains('failed host lookup') || lower.contains('nodename nor servname')) {
      return 'Could not resolve the domain (DNS). Check the address is spelled right. ($msg)';
    }
    if (lower.contains('handshake') || lower.contains('certificate') || lower.contains('tls')) {
      return 'Secure connection (TLS) failed. If your server uses a self-signed certificate, turn on Trust all certificates above. Otherwise the server may be blocking non-browser apps. ($msg)';
    }
    if (lower.contains('connection refused')) {
      return 'Connection refused - nothing is listening on that address or port. ($msg)';
    }
    if (lower.contains('connection closed before full header') ||
        lower.contains('http/2') ||
        lower.contains('protocol error')) {
      return 'The server closed the connection early. This can happen when a proxy only speaks HTTP/2. ($msg)';
    }
    if (lower.contains('connection reset') || lower.contains('connection terminated')) {
      return 'The connection was reset, which usually means a proxy or firewall is blocking the app even though browsers get through. ($msg)';
    }
    return msg;
  }

  /// Get the server version via the /status endpoint (no auth needed).
  static Future<String?> getServerVersion(String serverUrl, {Map<String, String> customHeaders = const {}, ServerBackend? backend}) async {
    // BookOrbit only tells a signed-in client its version.
    if ((backend ?? ServerBackend.active).isBookOrbit) return null;
    final url = serverUrl.endsWith('/')
        ? '${serverUrl}status'
        : '$serverUrl/status';
    try {
      final response = await http.get(Uri.parse(url), headers: customHeaders.isNotEmpty ? customHeaders : null)
          .timeout(const Duration(seconds: 10));
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final version = data['serverVersion'] as String?;
        cacheServerVersion(serverUrl, version);
        return version;
      }
    } catch (_) {}
    return null;
  }

  // Last-known version per server origin. Stream URL shape depends on the
  // server's capabilities, and buildTrackUrl is synchronous, so the version
  // has to already be in memory by the time playback starts. Persisted per
  // origin and re-hydrated on construction to cover cold starts where the
  // /status fetch hasn't answered yet.
  static final Map<String, String> _serverVersions = {};
  static final Set<String> _serverVersionLoads = {};

  static String? _originOf(String url) {
    try {
      return Uri.parse(normalizeServerUrl(url)).origin;
    } catch (_) {
      return null;
    }
  }

  /// Remember [version] for the server at [serverUrl], in memory and in prefs.
  /// Called from every place a version is learned: login responses, /status,
  /// and admin settings saves.
  static void cacheServerVersion(String serverUrl, String? version) {
    if (version == null || version.isEmpty) return;
    final origin = _originOf(serverUrl);
    if (origin == null) return;
    _serverVersionLoads.add(origin);
    if (_serverVersions[origin] == version) return;
    _serverVersions[origin] = version;
    unawaited(
      SharedPreferences.getInstance()
          .then((p) => p.setString('server_version_$origin', version))
          .catchError((Object _) => false),
    );
  }

  static void _loadCachedServerVersion(String serverUrl) {
    final origin = _originOf(serverUrl);
    if (origin == null || !_serverVersionLoads.add(origin)) return;
    unawaited(
      SharedPreferences.getInstance().then((p) {
        final v = p.getString('server_version_$origin');
        if (v != null && v.isNotEmpty) {
          _serverVersions.putIfAbsent(origin, () => v);
        }
      }).catchError((Object _) {}),
    );
  }

  /// True when [version] parses as `major.minor[.patch]` (optionally with a
  /// leading `v`) and is at least [major].[minor]. Unparseable = false.
  static bool serverVersionAtLeast(String? version, int major, int minor) {
    final m = RegExp(r'^\s*v?(\d+)\.(\d+)').firstMatch(version ?? '');
    if (m == null) return false;
    final vMajor = int.parse(m.group(1)!);
    if (vMajor != major) return vMajor > major;
    return int.parse(m.group(2)!) >= minor;
  }

  /// Whether this server has the tokenless public session track endpoint
  /// (added in Audiobookshelf v2.22.0). False while the version is unknown,
  /// which safely degrades to the tokened URL form.
  bool get _hasPublicSessionTracks {
    final origin = _originOf(_cleanBaseUrl);
    if (origin == null) return false;
    return serverVersionAtLeast(_serverVersions[origin], 2, 22);
  }

  /// Get all libraries.
  Future<List<dynamic>> getLibraries() async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries'),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body);
        final libs = (data['libraries'] as List?) ?? [];
        debugPrint('[API] getLibraries: ${libs.length} libraries');
        return libs;
      } else {
        debugPrint('[API] getLibraries failed: ${response.statusCode}');
      }
    } catch (e) {
      debugPrint('[API] getLibraries error: $e');
    }
    return [];
  }

  /// Get the personalized home view for a library.
  /// Returns sections like "continue-listening", "recently-added", "discover", etc.
  /// Null means the request failed (network / non-200), as opposed to an
  /// empty list of shelves.
  Future<List<dynamic>?> getPersonalizedView(
    String libraryId, {
    bool minified = true,
    List<String> include = const ['numEpisodesIncomplete'],
    List<String>? shelves,
    int? limit,
  }) async {
    try {
      final query = <String, String>{};
      if (minified) query['minified'] = '1';
      if (include.isNotEmpty) query['include'] = include.join(',');
      if (shelves != null && shelves.isNotEmpty) {
        query['shelves'] = shelves.join(',');
      }
      if (limit != null) query['limit'] = '$limit';

      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/personalized')
            .replace(queryParameters: query.isEmpty ? null : query),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body);
        if (data is List<dynamic>) return data;
        if (data is Map<String, dynamic>) {
          final shelvesData = data['shelves'];
          if (shelvesData is List<dynamic>) return shelvesData;
          final results = data['results'];
          if (results is List<dynamic>) return results;
        }
      }
    } catch (e) {
      // ignore
    }
    return null;
  }

  /// Get library items (paginated).
  Future<Map<String, dynamic>?> getLibraryItems(
    String libraryId, {
    int page = 0,
    int limit = 20,
    String sort = 'addedAt',
    int desc = 1,
    String? filter,
    bool expanded = false,
    bool collapseSeries = false,
  }) async {
    try {
      var url = '$_cleanBaseUrl/api/libraries/$libraryId/items'
          '?page=$page&limit=$limit&sort=$sort&desc=$desc'
          // Ask the server to populate numEpisodesIncomplete on podcast items
          // so podcast tiles can show an unplayed-count badge without loading
          // every show's full episode list.
          '&include=numEpisodesIncomplete';
      if (filter != null) url += '&filter=$filter';
      if (expanded) url += '&minified=0';
      if (collapseSeries) url += '&collapseseries=1';
      final response = await _authGet(
        Uri.parse(url),
      );

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
      debugPrint('[API] getLibraryItems page=$page limit=$limit: '
          'HTTP ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getLibraryItems page=$page limit=$limit failed: $e');
    }
    return null;
  }

  /// Fetch every library item the server has flagged with an issue - missing
  /// (files gone from disk) or invalid (present but unparseable). ABS exposes
  /// both under the plain `filter=issues` param. Each result carries the
  /// `isMissing` / `isInvalid` booleans so the caller can tell them apart.
  Future<List<dynamic>> getIssueItems(String libraryId) async {
    final all = <dynamic>[];
    var page = 0;
    while (page < 100) {
      final data = await getLibraryItems(
        libraryId,
        filter: 'issues',
        page: page,
        limit: 100,
        sort: 'media.metadata.title',
        desc: 0,
      );
      final results = data?['results'] as List? ?? const [];
      all.addAll(results);
      final total = data?['total'] as int?;
      page++;
      if (results.isEmpty || (total != null && all.length >= total)) break;
    }
    return all;
  }

  /// Count of issue items in a library (missing + invalid), fetched cheaply by
  /// reading `total` from a single-item issues query. Returns 0 on any failure.
  Future<int> getIssueItemCount(String libraryId) async {
    final data = await getLibraryItems(libraryId, filter: 'issues', limit: 1);
    return data?['total'] as int? ?? 0;
  }

  /// Build a cover image URL for a library item.
  /// [coverSlot] picks BookOrbit's 'audio' (square) or 'ebook' (portrait)
  /// cover and is ignored on Audiobookshelf, which has one.
  String getCoverUrl(String itemId, {int? width = 400, int? updatedAt, String? coverSlot}) {
    var url = '$_cleanBaseUrl/api/items/$itemId/cover?token=$token';
    if (width != null) url += '&width=$width';
    if (updatedAt != null) url += '&ts=$updatedAt';
    return url;
  }

  /// POST /api/authorize - validates the current token and returns the same
  /// payload shape as /login: { user, userDefaultLibraryId, serverSettings,
  /// ereaderDevices, Source }. Use on cold-start restore when you need the
  /// top-level extras (especially ereaderDevices, since /api/me drops them).
  Future<Map<String, dynamic>?> authorize() async {
    try {
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/authorize'),
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
      debugPrint('[API] authorize failed: ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] authorize error: $e');
    }
    return null;
  }

  /// Get current user info including all mediaProgress.
  Future<Map<String, dynamic>?> getMe() async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me'),
        timeout: const Duration(seconds: 10));

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
      debugPrint('[API] getMe failed: ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getMe error: $e');
    }
    return null;
  }

  /// Use the compact v2.36 endpoint, with one `/api/me` fallback for older servers.
  Future<List<Map<String, dynamic>>?> getAllProgress() async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/progress'),
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return (data['mediaProgress'] as List<dynamic>? ?? const [])
            .whereType<Map<String, dynamic>>()
            .toList();
      }
      if (response.statusCode != 404) return null;
      final user = await getMe();
      return (user?['mediaProgress'] as List<dynamic>? ?? const [])
          .whereType<Map<String, dynamic>>()
          .toList();
    } catch (e) {
      debugPrint('[API] getAllProgress error: $e');
      return null;
    }
  }

  /// Use the compact v2.36 endpoint, with one `/api/me` fallback for older servers.
  Future<List<Map<String, dynamic>>?> getAllBookmarks() async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/bookmarks'),
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return (data['bookmarks'] as List<dynamic>? ?? const [])
            .whereType<Map<String, dynamic>>()
            .toList();
      }
      if (response.statusCode != 404) return null;
      final user = await getMe();
      return (user?['bookmarks'] as List<dynamic>? ?? const [])
          .whereType<Map<String, dynamic>>()
          .toList();
    } catch (e) {
      debugPrint('[API] getAllBookmarks error: $e');
      return null;
    }
  }

  Future<AuthSessionsResult> getAuthSessions({int page = 0, int itemsPerPage = 20}) async {
    try {
      // Headers are built by _authGet AFTER its pre-flight refresh, so this
      // can't be snapshotted here - a rotation would leave both the Bearer and
      // the x-refresh-token stale, guaranteeing a 401 and a second rotation.
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/sessions?page=$page&itemsPerPage=$itemsPerPage'),
        sendRefreshTokenHeader: true,
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 404) {
        return const AuthSessionsResult(AuthSessionsStatus.unsupported);
      }
      if (response.statusCode != 200) {
        return const AuthSessionsResult(AuthSessionsStatus.failed);
      }
      final data = jsonDecode(response.body) as Map<String, dynamic>;
      return AuthSessionsResult(
        AuthSessionsStatus.supported,
        AuthSessionsPage.fromJson(data));
    } catch (e) {
      debugPrint('[API] getAuthSessions error: $e');
      return const AuthSessionsResult(AuthSessionsStatus.failed);
    }
  }

  Future<bool> deleteAuthSession(AuthSession session) async {
    if (session.current) return false;
    try {
      final response = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/me/sessions/${session.id}'),
        timeout: const Duration(seconds: 10));
      return response.statusCode >= 200 && response.statusCode < 300;
    } catch (e) {
      debugPrint('[API] deleteAuthSession error: $e');
      return false;
    }
  }

  Future<bool> revokeServerSession({bool allDevices = false}) async {
    final refreshToken = _refreshToken;
    if (refreshToken == null || refreshToken.isEmpty) return false;
    try {
      final suffix = allDevices ? '?allDevices=1' : '';
      final response = await _post(
        Uri.parse('$_cleanBaseUrl/logout$suffix'),
        headers: {
          ...customHeaders,
          'x-refresh-token': refreshToken,
          if (!kIsWeb) 'User-Agent': userAgent,
        }).timeout(const Duration(seconds: 10));
      return response.statusCode >= 200 && response.statusCode < 300;
    } catch (e) {
      debugPrint('[API] logout error: $e');
      return false;
    }
  }

  Future<PasswordChangeResult> changeMyPassword({
    required String currentPassword,
    required String newPassword,
  }) async {
    final mutationLock = await _acquireTokenMutationLock();
    try {
      await _adoptPersistedTokens();
      Future<http.Response> sendPasswordChange() => _patch(
          Uri.parse('$_cleanBaseUrl/api/me/password'),
          headers: {
            ..._headers,
            if (_refreshToken != null) 'x-refresh-token': _refreshToken!,
            if (!kIsWeb) 'User-Agent': userAgent,
          },
          body: jsonEncode({'password': currentPassword, 'newPassword': newPassword})
        ).timeout(const Duration(seconds: 15));

      var response = await sendPasswordChange();
      if (response.statusCode == 401 && !_isLegacyToken) {
        final adopted = await _adoptPersistedTokens();
        if (adopted || await _refreshTokenPairOnce()) {
          response = await sendPasswordChange();
        }
      }

      if (response.statusCode == 404) {
        return const PasswordChangeResult(PasswordChangeStatus.unsupported);
      }
      if (response.statusCode == 400) {
        return PasswordChangeResult(
          PasswordChangeStatus.invalidPassword,
          message: response.body.trim().isEmpty ? null : response.body.trim());
      }
      if (response.statusCode != 200) {
        return const PasswordChangeResult(PasswordChangeStatus.failed);
      }

      if (response.body.trim().isNotEmpty) {
        final decoded = jsonDecode(response.body);
        if (decoded is! Map<String, dynamic>) {
          return const PasswordChangeResult(PasswordChangeStatus.failed);
        }
        final data = decoded;
        final error = data['error'];
        if (error is String && error.trim().isNotEmpty) {
          return PasswordChangeResult(
            PasswordChangeStatus.invalidPassword,
            message: error.trim(),
          );
        }
        final tokens = AuthTokens.fromResponse(data);
        // The server rotates these together. Never adopt half a pair.
        if (tokens.accessToken != null && tokens.refreshToken != null) {
          _accessToken = tokens.accessToken!;
          _refreshToken = tokens.refreshToken!;
          await _notifyTokensRefreshed();
        }
      }
      // Older servers return an empty 200 and keep the current pair valid.
      return const PasswordChangeResult(PasswordChangeStatus.success);
    } catch (e) {
      debugPrint('[API] changeMyPassword error: $e');
      return const PasswordChangeResult(PasswordChangeStatus.failed);
    } finally {
      _releaseTokenMutationLock(mutationLock);
    }
  }

  /// Get user's listening stats.
  Future<Map<String, dynamic>?> getListeningStats() async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/listening-stats'),
        timeout: const Duration(seconds: 10));

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// Every listening session this user has for one item - the whole history,
  /// not a page of it, so the totals below are the real totals.
  Future<List<dynamic>> getMyItemListeningSessions(
    String itemId, {
    String? episodeId,
  }) async {
    try {
      final path = episodeId != null && episodeId.isNotEmpty
          ? '/api/me/item/listening-sessions/$itemId/$episodeId'
          : '/api/me/item/listening-sessions/$itemId';
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl$path?itemsPerPage=1000'),
        timeout: const Duration(seconds: 15),
      );
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return (data['sessions'] as List<dynamic>?) ?? [];
      }
    } catch (e) {
      debugPrint('getMyItemListeningSessions error: $e');
    }
    return [];
  }

  /// Get user's listening sessions (paginated).
  Future<Map<String, dynamic>?> getListeningSessions({int page = 0, int itemsPerPage = 20}) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/listening-sessions?itemsPerPage=$itemsPerPage&page=$page'),
        timeout: const Duration(seconds: 10));

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// One day's sessions, for a server that lists them by day. Null means
  /// page through [getListeningSessions] instead.
  Future<List<Map<String, dynamic>>?> getListeningSessionsForDay(DateTime day) async => null;

  /// Sets the time zone the server splits this account's days in, for a
  /// server that keeps one. False when it couldn't.
  Future<bool> setAccountTimeZone(String zone) async => false;

  Future<List<Map<String, dynamic>>?> getItemListeningSessions(
    String libraryItemId, {
    String? episodeId,
  }) async {
    const itemsPerPage = 100;
    final itemPath = Uri.encodeComponent(libraryItemId);
    final episodePath = episodeId == null
        ? ''
        : '/${Uri.encodeComponent(episodeId)}';
    final endpoint =
        '$_cleanBaseUrl/api/me/item/listening-sessions/$itemPath$episodePath';
    final sessions = <Map<String, dynamic>>[];
    var page = 0;

    try {
      while (true) {
        final uri = Uri.parse(endpoint).replace(queryParameters: {
          'itemsPerPage': '$itemsPerPage',
          'page': '$page',
        });
        final response = await _authGet(
          uri,
          timeout: const Duration(seconds: 10),
        );
        if (response.statusCode != 200) return null;

        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final pageSessions = (data['sessions'] as List<dynamic>? ?? const [])
            .whereType<Map<String, dynamic>>()
            .toList();
        sessions.addAll(pageSessions);

        final numPages = (data['numPages'] as num?)?.toInt() ?? 1;
        if (pageSessions.isEmpty || page + 1 >= numPages) break;
        page++;
      }
      return sessions;
    } catch (_) {
      return null;
    }
  }

  /// Get a specific user's listening sessions (admin, paginated).
  Future<Map<String, dynamic>?> getUserListeningSessions(String userId, {int page = 0, int itemsPerPage = 10}) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/users/$userId/listening-sessions?itemsPerPage=$itemsPerPage&page=$page'),
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// Get a library's series (paginated).
  Future<Map<String, dynamic>?> getLibrarySeries(
    String libraryId, {
    int page = 0,
    int limit = 50,
    String sort = 'addedAt',
    int desc = 1,
  }) async {
    try {
      final response = await _authGet(
        Uri.parse(
          '$_cleanBaseUrl/api/libraries/$libraryId/series'
          '?page=$page&limit=$limit&sort=$sort&desc=$desc',
        ),
        timeout: const Duration(seconds: 60),
      );

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
      debugPrint('[API] getLibrarySeries page=$page: HTTP ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getLibrarySeries page=$page failed: $e');
    }
    return null;
  }

  /// Build an author image URL.
  String getAuthorImageUrl(String authorId, {int width = 200, int? updatedAt}) {
    var url = '$_cleanBaseUrl/api/authors/$authorId/image?width=$width&token=$token';
    if (updatedAt != null) url += '&ts=$updatedAt';
    return url;
  }

  /// Get a library's filter data (authors, series, genres, etc.)
  /// Used by Android Auto to build browse tree without fetching full items.
  Future<Map<String, dynamic>?> getLibraryFilterData(String libraryId) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId?include=filterdata'),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return data['filterdata'] as Map<String, dynamic>?;
      }
    } catch (e) {
      // ignore
    }
    return null;
  }

  /// Get books by a specific author using the filter API.
  /// Filter format: authors.<base64(authorId)>
  Future<List<dynamic>> getBooksByAuthor(
    String libraryId,
    String authorId, {
    int limit = 50,
  }) async {
    try {
      final filterValue = base64Encode(utf8.encode(authorId));
      final url = '$_cleanBaseUrl/api/libraries/$libraryId/items'
          '?filter=authors.$filterValue&sort=media.metadata.title&limit=$limit';
      final response = await _authGet(
        Uri.parse(url),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return data['results'] as List<dynamic>? ?? [];
      }
    } catch (e) {
      debugPrint('[API] getBooksByAuthor error: $e');
    }
    return [];
  }

  /// Get all authors for a library.
  Future<List<Map<String, dynamic>>> getLibraryAuthors(String libraryId) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/authors'),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final authors = data['authors'] as List<dynamic>? ?? [];
        return authors.cast<Map<String, dynamic>>();
      }
    } catch (e) {
      debugPrint('[API] getLibraryAuthors error: $e');
    }
    return [];
  }

  /// One page of a library's authors, sorted server-side. [sort] is `name`,
  /// `lastFirst`, `addedAt`, `updatedAt` or `numBooks`. Stock ABS answers
  /// `{results, total, ...}`; a server that ignores paging answers `{authors}`
  /// with everything, which callers treat as the only page.
  Future<Map<String, dynamic>?> getLibraryAuthorsPage(
    String libraryId, {
    int page = 0,
    int limit = 100,
    String sort = 'name',
    int desc = 0,
  }) async {
    try {
      final sw = Stopwatch()..start();
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/authors'
            '?limit=$limit&page=$page&sort=$sort&desc=$desc'),
        timeout: const Duration(seconds: 30),
      );
      debugPrint('[API] getLibraryAuthorsPage page=$page: HTTP '
          '${response.statusCode} in ${sw.elapsedMilliseconds}ms');
      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (e) {
      debugPrint('[API] getLibraryAuthorsPage page=$page failed: $e');
    }
    return null;
  }

  /// Fetch several items by id in one request. One indexed query server-side,
  /// unlike the filtered items listing, which sorts the whole library first.
  Future<List<Map<String, dynamic>>> getLibraryItemsBatch(
      List<String> ids) async {
    if (ids.isEmpty) return const [];
    try {
      final sw = Stopwatch()..start();
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/batch/get'),
        body: jsonEncode({'libraryItemIds': ids}),
        timeout: const Duration(seconds: 30),
      );
      debugPrint('[API] getLibraryItemsBatch ${ids.length} ids: HTTP '
          '${response.statusCode} in ${sw.elapsedMilliseconds}ms');
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return (data['libraryItems'] as List<dynamic>? ?? const [])
            .whereType<Map<String, dynamic>>()
            .toList();
      }
    } catch (e) {
      debugPrint('[API] getLibraryItemsBatch failed: $e');
    }
    return const [];
  }

  /// Get all narrators for a library. ABS exposes narrators only via the
  /// filterdata endpoint as a list of name strings (no IDs/images/bios).
  Future<List<String>> getLibraryNarrators(String libraryId) async {
    try {
      final data = await getLibraryFilterData(libraryId);
      if (data == null) return [];
      final raw = data['narrators'] as List<dynamic>? ?? [];
      return raw
          .map((e) => e?.toString() ?? '')
          .where((s) => s.isNotEmpty)
          .toList();
    } catch (e) {
      debugPrint('[API] getLibraryNarrators error: $e');
    }
    return [];
  }

  /// Book count per narrator name. The narrators endpoint walks every book
  /// with a narrator server-side, so it is slower than filterdata; callers
  /// fetch it after the names and treat an empty map as "not available".
  Future<Map<String, int>> getLibraryNarratorCounts(String libraryId) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/narrators'),
        timeout: const Duration(seconds: 30),
      );
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final counts = <String, int>{};
        for (final n in data['narrators'] as List<dynamic>? ?? const []) {
          if (n is! Map<String, dynamic>) continue;
          final name = n['name'] as String?;
          final count = (n['numBooks'] as num?)?.toInt();
          if (name != null && name.isNotEmpty && count != null) {
            counts[name] = count;
          }
        }
        return counts;
      }
      debugPrint('[API] getLibraryNarratorCounts: HTTP ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getLibraryNarratorCounts failed: $e');
    }
    return const {};
  }

  /// Get books narrated by a specific person.
  /// Filter format: narrators.<base64(name)>
  Future<List<dynamic>> getBooksByNarrator(
    String libraryId,
    String narratorName, {
    int limit = 50,
  }) async {
    try {
      final filterValue = base64Encode(utf8.encode(narratorName));
      final url = '$_cleanBaseUrl/api/libraries/$libraryId/items'
          '?filter=narrators.$filterValue&sort=media.metadata.title&limit=$limit';
      final response = await _authGet(
        Uri.parse(url),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return data['results'] as List<dynamic>? ?? [];
      }
    } catch (e) {
      debugPrint('[API] getBooksByNarrator error: $e');
    }
    return [];
  }

  /// Get full author details including description/bio.
  Future<Map<String, dynamic>?> getAuthorById(String authorId, {String? libraryId}) async {
    try {
      var url = '$_cleanBaseUrl/api/authors/$authorId?include=items,series';
      if (libraryId != null) url += '&library=$libraryId';
      final response = await _authGet(
        Uri.parse(url),
      );

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (e) {
      debugPrint('[API] getAuthorById error: $e');
    }
    return null;
  }

  /// Update an author's editable fields (admin/root only).
  /// Returns one of:
  ///   { ok: true, author: {...} }         - normal update succeeded
  ///   { ok: true, merged: { id, name } }  - name matched another author, this one was merged
  ///   { ok: false }                       - request failed
  /// PATCH /api/authors/:id
  Future<Map<String, dynamic>> updateAuthor(
    String authorId, {
    String? name,
    String? description,
    String? asin,
    String? imagePath,
  }) async {
    try {
      final body = <String, dynamic>{};
      if (name != null) body['name'] = name;
      if (description != null) body['description'] = description;
      if (asin != null) body['asin'] = asin;
      if (imagePath != null) body['imagePath'] = imagePath;
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/authors/$authorId'),
        body: jsonEncode(body),
      );
      debugPrint('[API] updateAuthor $authorId -> ${r.statusCode}: ${r.body}');
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body) as Map<String, dynamic>;
        if (data['merged'] != null) {
          return {'ok': true, 'merged': data['merged']};
        }
        return {'ok': true, 'author': data['author'] ?? data};
      }
    } catch (e) { debugPrint('updateAuthor error: $e'); }
    return {'ok': false};
  }

  /// Quick-match an author against the configured provider (Audible).
  /// Server fetches name/asin/description/image, updates the author server-side,
  /// and returns the author. Returns null if no match or on error. A successful
  /// match can return the unchanged author when its stored details are already
  /// current.
  /// POST /api/authors/:id/match  body: { q, region }
  /// Response: { updated, author } on match; a missing provider match is 404.
  Future<Map<String, dynamic>?> matchAuthor(
    String authorId, {
    required String q,
    String region = 'us',
  }) async {
    final result = await quickMatchAuthor(authorId, q: q, region: region);
    if (!result.found) return null;
    return result.author;
  }

  /// Quick-match one author using the same ASIN-first request shape as the
  /// Audiobookshelf web client. The full response is retained so batch callers
  /// can distinguish a match with no changes from a missing author or a failed
  /// request.
  Future<AuthorQuickMatchResult> quickMatchAuthor(
    String authorId, {
    String? q,
    String? asin,
    String region = 'us',
  }) async {
    final trimmedAsin = asin?.trim() ?? '';
    final trimmedQuery = q?.trim() ?? '';
    if (trimmedAsin.isEmpty && trimmedQuery.isEmpty) {
      return const AuthorQuickMatchResult(statusCode: 0);
    }

    try {
      final body = <String, dynamic>{'region': region};
      if (trimmedAsin.isNotEmpty) {
        body['asin'] = trimmedAsin;
      } else {
        body['q'] = trimmedQuery;
      }
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/authors/$authorId/match'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 30),
      );
      debugPrint(
        '[API] quickMatchAuthor $authorId -> ${r.statusCode}: ${r.body}',
      );
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body) as Map<String, dynamic>;
        final author = data['author'] is Map
            ? Map<String, dynamic>.from(data['author'] as Map)
            : null;
        // Current ABS returns 404 when the provider has no match. Older
        // servers returned 200 with {updated: false} and no author payload.
        if (author == null && data['updated'] == false) {
          return const AuthorQuickMatchResult(statusCode: 404);
        }
        return AuthorQuickMatchResult(
          statusCode: r.statusCode,
          updated: data['updated'] == true,
          author: author,
        );
      }
      return AuthorQuickMatchResult(statusCode: r.statusCode);
    } catch (e) {
      debugPrint('quickMatchAuthor error: $e');
    }
    return const AuthorQuickMatchResult(statusCode: 0);
  }

  /// Set the author image from a remote URL.
  /// POST /api/authors/:id/image  body: { url }
  Future<bool> updateAuthorImageFromUrl(String authorId, String url) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/authors/$authorId/image'),
        body: jsonEncode({'url': url}),
        timeout: const Duration(seconds: 30),
      );
      debugPrint('[API] updateAuthorImageFromUrl $authorId -> ${r.statusCode}');
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateAuthorImageFromUrl error: $e'); }
    return false;
  }

  /// Remove the author's image.
  /// DELETE /api/authors/:id/image
  Future<bool> deleteAuthorImage(String authorId) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/authors/$authorId/image'),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('deleteAuthorImage error: $e'); }
    return false;
  }

  /// Get books in a specific series using the filter API.
  /// Filter format: series.<base64(seriesId)>
  Future<List<dynamic>> getBooksBySeries(
    String libraryId,
    String seriesId, {
    int limit = 50,
  }) async {
    try {
      final filterValue = base64Encode(utf8.encode(seriesId));
      final url = '$_cleanBaseUrl/api/libraries/$libraryId/items'
          '?filter=series.$filterValue'
          '&sort=media.metadata.series.sequence&limit=$limit&collapseseries=0';
      final response = await _authGet(
        Uri.parse(url),
      );

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return data['results'] as List<dynamic>? ?? [];
      }
    } catch (e) {
      debugPrint('[API] getBooksBySeries error: $e');
    }
    return [];
  }

  /// Every book in a series, in sequence order. The queue and rolling
  /// download need the whole series: a capped page only ever holds the first
  /// N sequences, so a long series (GH #377, 200+ entries) never queued
  /// anything past that cap. limit=0 is unlimited on the server.
  Future<List<dynamic>> getAllBooksBySeries(
    String libraryId,
    String seriesId,
  ) async {
    try {
      final filterValue = base64Encode(utf8.encode(seriesId));
      final url = '$_cleanBaseUrl/api/libraries/$libraryId/items'
          '?filter=series.$filterValue'
          '&sort=media.metadata.series.sequence&limit=0&collapseseries=0';
      final sw = Stopwatch()..start();
      final response = await _authGet(
        Uri.parse(url),
        timeout: const Duration(seconds: 30),
      );
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final results = data['results'] as List<dynamic>? ?? [];
        debugPrint('[API] getAllBooksBySeries $seriesId: ${results.length} books '
            '(total=${data['total']}) in ${sw.elapsedMilliseconds}ms');
        return results;
      }
      debugPrint('[API] getAllBooksBySeries $seriesId: HTTP ${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getAllBooksBySeries error: $e');
    }
    return [];
  }

  /// Expose clean base URL for audio player to build URLs
  String get cleanBaseUrl => _cleanBaseUrl;

  /// The device descriptor ABS attaches to playback sessions. Shared by the
  /// /play session calls and the client-owned local-session calls.
  Map<String, dynamic> get _deviceInfo => {
        'clientName': 'Absorb',
        'clientVersion': appVersion,
        'deviceId': deviceId,
        'deviceName': '${deviceManufacturer.isNotEmpty ? "$deviceManufacturer " : ""}$deviceModel'.trim(),
        'manufacturer': deviceManufacturer,
        'model': deviceModel,
      };

  /// Time spent reading shows up on the server as its own client: "Absorb
  /// (ebook)" with its own device id, since the server keeps one name per
  /// device id and would otherwise rename this phone's listening too.
  Map<String, dynamic> get _readingDeviceInfo => {
        ..._deviceInfo,
        'clientName': 'Absorb (ebook)',
        'deviceId': '$deviceId-ebook',
      };

  /// The media player a reading session is marked with.
  static const readingMediaPlayer = 'ebook-reader';

  /// Start a playback session for a library item.
  /// POST /api/items/:id/play
  /// Returns the full session object including audioTracks with contentUrl.
  Future<Map<String, dynamic>?> startPlaybackSession(String itemId, {String? episodeId, bool forceDirectPlay = false, bool forceTranscode = false, double? startOffset}) async {
    try {
      final epPath = episodeId != null ? '/$episodeId' : '';
      final url = '$_cleanBaseUrl/api/items/$itemId/play$epPath';
      debugPrint('[ABS] Starting playback session: POST $url (forceDirectPlay: $forceDirectPlay, forceTranscode: $forceTranscode)');
      final body = <String, dynamic>{
        'deviceInfo': _deviceInfo,
        'forceDirectPlay': !forceTranscode,
        'forceTranscode': forceTranscode,
        // Match what the native ABS Android app sends so the server treats us
        // as a known ExoPlayer client and picks direct-play correctly.
        'mediaPlayer': 'exo-player',
        'supportedMimeTypes': [
          'audio/flac',
          'audio/mpeg',
          'audio/mp4',
          'audio/ogg',
          'audio/aac',
          'audio/x-m4a',
          'audio/x-m4b',
          'audio/opus',
          'audio/webm',
          'audio/wav',
          'audio/x-wav',
          'audio/x-matroska',
          'audio/x-ms-wma',
        ],
      };
      if (startOffset != null && startOffset > 0) body['startOffset'] = startOffset;
      final response = await _authPost(
        Uri.parse(url),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 20));

      debugPrint('[ABS] Play session response: ${response.statusCode}');
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final tracks = data['audioTracks'] as List<dynamic>?;
        debugPrint('[ABS] Session ID: ${data['id']}');
        debugPrint('[ABS] Audio tracks: ${tracks?.length ?? 0}');
        if (tracks != null && tracks.isNotEmpty) {
          final firstTrack = tracks.first as Map<String, dynamic>;
          debugPrint('[ABS] First track contentUrl: ${firstTrack['contentUrl']}');
        }
        return data;
      } else {
        debugPrint('[ABS] Play session failed: ${response.body}');
      }
    } catch (e) {
      debugPrint('[ABS] Play session error: $e');
    }
    return null;
  }

  /// Build a full audio track URL from a contentUrl returned by the play
  /// session. When the caller passes the session context ([sessionId], the
  /// track's own [trackIndex], [playMethod]) and the session is direct play
  /// on a server with the public session endpoint, the URL is synthesized
  /// with no token in it at all - the unguessable session id is the
  /// credential, so token rotation can't 401 a stream mid-book. Everything
  /// else keeps the contentUrl-based forms.
  String buildTrackUrl(
    String contentUrl, {
    String? sessionId,
    int? trackIndex,
    int? playMethod,
  }) {
    // ABS servers with ROUTER_BASE_PATH set return contentUrls that already
    // include the base path (e.g. "/abs/public/session/.../track/0"). If the
    // user's server URL also includes that base path, blindly concatenating
    // would double it ("/abs/abs/..."). Detect and use origin only.
    final baseUri = Uri.parse(_cleanBaseUrl);
    final basePath = baseUri.path;
    final isAbsolute = contentUrl.startsWith('http');
    final Uri trackUri;
    if (isAbsolute) {
      trackUri = Uri.parse(contentUrl);
    } else if (basePath.isNotEmpty && contentUrl.startsWith('$basePath/')) {
      trackUri = Uri.parse('${baseUri.origin}$contentUrl');
    } else {
      trackUri = Uri.parse('$_cleanBaseUrl$contentUrl');
    }

    if (trackUri.path.contains('/public/session/')) {
      final query = Map<String, dynamic>.from(trackUri.queryParametersAll)
        ..remove('token');
      if (query.isEmpty) {
        final value = trackUri.toString();
        final queryStart = value.indexOf('?');
        if (queryStart < 0) return value;
        final fragmentStart = value.indexOf('#', queryStart);
        return value.substring(0, queryStart) +
            (fragmentStart < 0 ? '' : value.substring(fragmentStart));
      }
      return trackUri.replace(queryParameters: query).toString();
    }

    if (isAbsolute) return contentUrl;

    // playMethod 0 = direct play. Transcode sessions must keep their HLS
    // contentUrl, and pre-2.22 servers lack the endpoint but hand out legacy
    // tokens that never expire, so both fall through safely.
    if (sessionId != null &&
        sessionId.isNotEmpty &&
        trackIndex != null &&
        playMethod == 0 &&
        _hasPublicSessionTracks) {
      return '$_cleanBaseUrl/public/session/$sessionId/track/$trackIndex';
    }

    // No per-track logging here: this runs in a hot loop over every track, and
    // books with thousands of files would flood (and roll over) the log buffer.
    // The session's "First track contentUrl" line already gives a sample.
    final query = Map<String, dynamic>.from(trackUri.queryParametersAll)
      ..['token'] = token;
    return trackUri.replace(queryParameters: query).toString();
  }

  /// Build a durable, session-independent file download URL for [ino] within
  /// [itemId]. Unlike a playback-session track URL, this survives session close
  /// and app suspension, so it is safe for background downloads that outlive the
  /// session/app. Auth travels as `?token=` (the Authorization header can be
  /// dropped across reverse-proxy redirects); custom proxy headers still ride
  /// along via [mediaHeaders] when the downloader sets them.
  String buildFileUrl(String itemId, String ino) {
    return '$_cleanBaseUrl/api/items/$itemId/file/$ino?token=$token';
  }

  /// Sync playback progress. Returns true if sync succeeded.
  /// POST /api/session/:id/sync
  Future<bool> syncPlaybackSession(
    String sessionId, {
    required double currentTime,
    required double duration,
    int timeListened = 60,
  }) async =>
      await syncPlaybackSessionStatus(
        sessionId,
        currentTime: currentTime,
        duration: duration,
        timeListened: timeListened,
      ) ==
      200;

  /// The sync's status code, or null when the request itself failed. A 404
  /// means the server no longer has the session; anything else is transient.
  Future<int?> syncPlaybackSessionStatus(
    String sessionId, {
    required double currentTime,
    required double duration,
    int timeListened = 60,
  }) async {
    try {
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/session/$sessionId/sync'),
        body: jsonEncode({
          'currentTime': currentTime,
          'timeListened': timeListened,
          // Older servers use this duration unconditionally for the progress
          // row, so it must be sent; progress is ignored by every version
          // (the server derives it from the session).
          'duration': duration,
        }),
        timeout: const Duration(seconds: 10));
      return response.statusCode;
    } catch (_) {
      return null;
    }
  }

  /// Close a playback session.
  /// POST /api/session/:id/close
  Future<void> closePlaybackSession(String sessionId) async {
    try {
      await _authPost(
        Uri.parse('$_cleanBaseUrl/api/session/$sessionId/close'),
        timeout: const Duration(seconds: 10));
    } catch (_) {}
  }

  /// Upsert a client-owned local playback session (downloaded/offline plays).
  /// POST /api/session/local — preserves our playMethod (LOCAL) and the
  /// client-supplied date/timestamps, unlike /play which forces Direct Play.
  /// [session] is a fully-built session map; deviceInfo/mediaPlayer/playMethod
  /// are stamped here so they can't be omitted.
  Future<LocalSessionResult> syncLocalSession(Map<String, dynamic> session) async {
    final reading = session['keepProgress'] == true;
    final kept = await _besideProgress(session);
    if (kept == null) return const LocalSessionResult(ok: false, serverTooOld: false);
    session = kept;
    try {
      final body = {
        ...session,
        'deviceInfo': reading ? _readingDeviceInfo : _deviceInfo,
        'mediaPlayer': reading ? readingMediaPlayer : 'exo-player',
        'playMethod': session['playMethod'] ?? 3, // LOCAL unless streamed
      };
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/session/local'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 10));
      return LocalSessionResult(
        ok: resp.statusCode == 200,
        serverTooOld: resp.statusCode == 404 || resp.statusCode == 501,
      );
    } catch (_) {
      return const LocalSessionResult(ok: false, serverTooOld: false);
    }
  }

  /// Batch-upsert local sessions, used to replay the offline queue on reconnect.
  /// POST /api/session/local-all
  Future<LocalSessionResult> syncLocalSessionsAll(
      List<Map<String, dynamic>> sessions) async {
    // Reading time goes one at a time: the batch carries a single device.
    var readingOk = true;
    for (final s in sessions.where((s) => s['keepProgress'] == true)) {
      if (!(await syncLocalSession(s)).ok) readingOk = false;
    }
    final kept = <Map<String, dynamic>>[];
    for (final s in sessions.where((s) => s['keepProgress'] != true)) {
      final k = await _besideProgress(s);
      if (k != null) kept.add(k);
    }
    sessions = kept;
    if (sessions.isEmpty) return LocalSessionResult(ok: readingOk, serverTooOld: false);
    try {
      final body = {
        'sessions': sessions
            .map((s) => {...s, 'mediaPlayer': 'exo-player', 'playMethod': s['playMethod'] ?? 3})
            .toList(),
        'deviceInfo': _deviceInfo,
      };
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/session/local-all'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 20));
      return LocalSessionResult(
        ok: resp.statusCode == 200 && readingOk,
        serverTooOld: resp.statusCode == 404 || resp.statusCode == 501,
      );
    } catch (_) {
      return const LocalSessionResult(ok: false, serverTooOld: false);
    }
  }

  /// A phone-made session whose numbers aren't the book's listening position:
  /// an EPUB's narration (the server sizes a new session by the item's own
  /// length, zero for an ebook) or time spent reading (`keepProgress`). The
  /// server copies a session's position onto the progress row unless the
  /// row is newer, so the session is dated just before the row's last save:
  /// the time is logged and the progress is left as it is. Null when there
  /// is no row to keep yet for a reading session.
  Future<Map<String, dynamic>?> _besideProgress(Map<String, dynamic> session) async {
    final reading = session['keepProgress'] == true;
    final out = Map<String, dynamic>.from(session)..remove('keepProgress');
    final id = session['libraryItemId'];
    final narration = id is String ? NarratedBooks.duration(id) : null;
    if (isBookOrbit || id is! String || (!reading && narration == null)) return out;
    var row = await getItemProgress(id);
    if (row == null && reading) debugPrint('[Session] $id: no progress row yet - reading time waits');
    if (row == null && narration != null) {
      try {
        await updateProgress(id,
            currentTime: (session['currentTime'] as num?)?.toDouble() ?? 0, duration: narration);
      } catch (_) {}
      row = await getItemProgress(id);
    }
    final rowAt = (row?['lastUpdate'] as num?)?.toInt();
    if (rowAt == null) return reading ? null : out;
    if (narration != null) out['duration'] = narration;
    final at = (session['updatedAt'] as num?)?.toInt() ?? DateTime.now().millisecondsSinceEpoch;
    if (at >= rowAt) out['updatedAt'] = rowAt - 1000;
    if (_besideLogged.add('${session['id']}')) {
      debugPrint('[Session] $id: ${reading ? 'reading time' : 'narration'} session ${session['id']} '
          'logged beside the progress row (${at >= rowAt ? 'dated before it' : 'already older'})');
    }
    return out;
  }

  static final Set<String> _besideLogged = {};

  static const _weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];

  /// Time spent reading, as the local listening session Audiobookshelf takes
  /// it in: at the audiobook's current spot ([audioAt], 0 for an ebook with
  /// no audio) and marked to leave the progress as it is.
  static Map<String, dynamic> readingSession(
    String itemId, {
    required String sessionId,
    required DateTime startedAt,
    required int seconds,
    required double audioAt,
    required double audioDuration,
    String? title,
  }) {
    String day(DateTime d) =>
        '${d.year}-${d.month.toString().padLeft(2, '0')}-${d.day.toString().padLeft(2, '0')}';
    return {
      'id': sessionId,
      'libraryItemId': itemId,
      'episodeId': null,
      'mediaType': 'book',
      'displayTitle': title,
      'duration': audioDuration,
      'startTime': audioAt,
      'currentTime': audioAt,
      'timeListening': seconds,
      'startedAt': startedAt.millisecondsSinceEpoch,
      'updatedAt': DateTime.now().millisecondsSinceEpoch,
      'date': day(startedAt),
      'dayOfWeek': _weekdays[startedAt.weekday - 1],
      'keepProgress': true,
    };
  }

  /// Time spent reading [itemId]'s ebook, kept as a session [sessionId] so it
  /// counts in stats (sent again as it grows, the same id each time).
  /// Audiobookshelf has no reading sessions, so it goes in as a listening
  /// session that leaves the listening progress as it is.
  Future<bool> logReadingTime(
    String itemId, {
    required String sessionId,
    required DateTime startedAt,
    required int seconds,
    required double audioAt,
    required double audioDuration,
    String? title,
    double? ebookStart,
    double? ebookEnd,
  }) async {
    final r = await syncLocalSession(readingSession(
      itemId,
      sessionId: sessionId,
      startedAt: startedAt,
      seconds: seconds,
      audioAt: audioAt,
      audioDuration: audioDuration,
      title: title,
    ));
    return r.ok;
  }

  /// Edit an existing listening session by re-POSTing it through the local
  /// upsert. The server honors timeListening, currentTime, and updatedAt (it
  /// re-derives the session's day from updatedAt); other fields on an existing
  /// session are left untouched, so the original playMethod/device stay intact.
  /// Returns true on success.
  Future<bool> updateListeningSession(Map<String, dynamic> session) async {
    try {
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/session/local'),
        body: jsonEncode(session),
        timeout: const Duration(seconds: 10));
      return resp.statusCode == 200;
    } catch (_) {
      return false;
    }
  }

  /// Logs a listen that happened away from the app, to catch up a book's
  /// listening time. It ends at the book's saved spot so the book keeps its
  /// place.
  Future<bool> addListeningSession({
    required String itemId,
    required DateTime startedAt,
    required int seconds,
  }) async {
    final item = await getLibraryItem(itemId);
    final media = item?['media'] as Map<String, dynamic>?;
    final meta = media?['metadata'] as Map<String, dynamic>?;
    final progress = item?['userMediaProgress'] as Map<String, dynamic>?;
    final at = (progress?['currentTime'] as num?)?.toDouble() ?? 0;
    final ended = startedAt.add(Duration(seconds: seconds));
    String two(int v) => v.toString().padLeft(2, '0');
    const weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
    final result = await syncLocalSession({
      'id': BookOrbitApiService._uuid(),
      'libraryItemId': itemId,
      'episodeId': null,
      'mediaType': 'book',
      'displayTitle': meta?['title'],
      'displayAuthor': meta?['authorName'],
      'duration': (media?['duration'] as num?)?.toDouble() ?? 0,
      'startTime': math.max(0.0, at - seconds),
      'currentTime': at,
      'timeListening': seconds,
      'startedAt': startedAt.millisecondsSinceEpoch,
      'updatedAt': ended.millisecondsSinceEpoch,
      'date': '${startedAt.year}-${two(startedAt.month)}-${two(startedAt.day)}',
      'dayOfWeek': weekdays[startedAt.weekday - 1],
    });
    return result.ok;
  }

  /// Delete a listening session. Needs the user's delete permission on the
  /// server (403 otherwise). Returns true on success. [itemId] is the book
  /// the session belongs to, which BookOrbit needs.
  Future<bool> deleteListeningSession(String sessionId, {String? itemId}) async {
    try {
      final resp = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/sessions/$sessionId'),
        timeout: const Duration(seconds: 10));
      return resp.statusCode == 200;
    } catch (_) {
      return false;
    }
  }

  /// Get server progress for a single item.
  /// GET /api/me/progress/:id
  Future<Map<String, dynamic>?> getItemProgress(String itemId) async {
    try {
      // Podcast episodes use compound key "showId-episodeId" →
      // ABS endpoint: /api/me/progress/{showId}/{episodeId}
      final progressPath = itemId.length > 36
          ? '${itemId.substring(0, 36)}/${itemId.substring(37)}'
          : itemId;
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$progressPath'),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return await _withPageReadElsewhere(itemId, jsonDecode(resp.body) as Map<String, dynamic>);
      }
    } catch (_) {}
    return null;
  }

  /// The narration time of the page a narrated book was read to on another
  /// device, when that page is the newer place. Set by the app at start.
  static Future<double?> Function(String itemId, Map<String, dynamic> progress)? pageReadElsewhere;

  /// Audiobookshelf sees only the ebook in a narrated EPUB, so reading it in
  /// its web reader moves the page and leaves the audio behind. A newer page
  /// ahead of the audio is where listening picks up.
  Future<Map<String, dynamic>> _withPageReadElsewhere(String itemId, Map<String, dynamic> progress) async {
    final place = pageReadElsewhere;
    if (place == null || isBookOrbit || !NarratedBooks.contains(itemId)) return progress;
    try {
      final at = await place(itemId, progress);
      return at == null ? progress : {...progress, 'currentTime': at};
    } catch (_) {
      return progress;
    }
  }

  /// The server's place in an item's ebook, for opening the reader there:
  /// ebookLocation, ebookProgress and, when the server keeps one apart from
  /// listening, ebookUpdatedAt (ms).
  Future<Map<String, dynamic>?> getEbookPosition(String itemId) =>
      getItemProgress(itemId);

  Map<String, dynamic>? _progressRecreationBody(
    Map<String, dynamic> progress, {
    required int startedAt,
  }) {
    final originalStartedAt = progress['startedAt'];
    if (progress['id'] is! String || originalStartedAt is! num) return null;

    final body = <String, dynamic>{
      'createdAt': startedAt,
      'isFinished': progress['isFinished'] == true,
    };
    for (final key in [
      'currentTime',
      'duration',
      'progress',
      'hideFromContinueListening',
      'ebookLocation',
      'ebookProgress',
      'finishedAt',
    ]) {
      if (progress[key] != null) body[key] = progress[key];
    }
    return body;
  }

  /// Change a book's start date while preserving its listening progress.
  /// Audiobookshelf stores the displayed start date as the progress record's
  /// creation time, so changing it requires recreating that record.
  Future<bool> updateProgressStartDate(String itemId, int startedAt) async {
    try {
      final progress = await getItemProgress(itemId);
      if (progress == null) return false;
      final progressId = progress['id'];
      final originalStartedAt = progress['startedAt'];
      if (progressId is! String || originalStartedAt is! num) return false;

      final updatedBody = _progressRecreationBody(
        progress,
        startedAt: startedAt,
      );
      final originalBody = _progressRecreationBody(
        progress,
        startedAt: originalStartedAt.toInt(),
      );
      if (updatedBody == null || originalBody == null) return false;

      final deleteResponse = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$progressId'),
        timeout: const Duration(seconds: 10),
      );
      if (deleteResponse.statusCode < 200 || deleteResponse.statusCode >= 300) {
        return false;
      }

      await Future<void>.delayed(const Duration(milliseconds: 500));
      int? updateStatus;
      try {
        final updateResponse = await _authPatch(
          Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId'),
          body: jsonEncode(updatedBody),
          timeout: const Duration(seconds: 10),
        );
        updateStatus = updateResponse.statusCode;
        if (updateStatus >= 200 && updateStatus < 300) return true;
      } catch (e) {
        debugPrint('[API] updateProgressStartDate recreate error: $e');
      }

      try {
        final restoreResponse = await _authPatch(
          Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId'),
          body: jsonEncode(originalBody),
          timeout: const Duration(seconds: 10),
        );
        debugPrint(
          '[API] updateProgressStartDate failed ($updateStatus); '
          'restore=${restoreResponse.statusCode}',
        );
      } catch (e) {
        debugPrint('[API] updateProgressStartDate restore error: $e');
      }
    } catch (e) {
      debugPrint('[API] updateProgressStartDate error: $e');
    }
    return false;
  }

  /// Change the finish date on an existing progress record.
  Future<bool> updateProgressFinishedDate(String itemId, int finishedAt) async {
    try {
      final response = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId'),
        body: jsonEncode({'finishedAt': finishedAt, 'isFinished': true}),
        timeout: const Duration(seconds: 10),
      );
      return response.statusCode >= 200 && response.statusCode < 300;
    } catch (e) {
      debugPrint('[API] updateProgressFinishedDate error: $e');
      return false;
    }
  }

  /// Update media progress directly (for offline sync).
  /// PATCH /api/me/progress/:id
  /// [isFinished] null = leave the finished flag out of the body. The server
  /// only writes the percent it shows (`progress`) when `isFinished` is
  /// absent; a body carrying `isFinished: false` on an unfinished record moves
  /// currentTime and nothing else, so the web UI percent never budges. Pass
  /// false only to deliberately un-finish: the server answers that by
  /// clearing the position to 0, same as the web UI's "mark as not finished",
  /// so [currentTime] is not sent in that case.
  /// Returns false on a 5xx, where a retry could still land; network errors
  /// still throw.
  Future<bool> updateProgress(
    String itemId, {
    required double currentTime,
    required double duration,
    bool? isFinished,
  }) async {
    try {
      final progressPath = itemId.length > 36
          ? '${itemId.substring(0, 36)}/${itemId.substring(37)}'
          : itemId;
      final url = Uri.parse('$_cleanBaseUrl/api/me/progress/$progressPath');
      if (isFinished == false) {
        final unfinish = await _authPatch(url,
            body: jsonEncode({'isFinished': false}),
            timeout: const Duration(seconds: 10));
        debugPrint('[API] updateProgress unfinish $progressPath: ${unfinish.statusCode}');
        return unfinish.statusCode < 500;
      }
      final body = jsonEncode({
        'currentTime': currentTime,
        'duration': duration,
        'progress': duration > 0 ? (currentTime / duration).clamp(0.0, 1.0) : 0,
        if (isFinished == true) 'isFinished': true,
      });
      debugPrint('[API] updateProgress PATCH /api/me/progress/$progressPath');
      debugPrint('[API] updateProgress body: currentTime=$currentTime');
      final resp = await _authPatch(url,
        body: body,
        timeout: const Duration(seconds: 10));
      debugPrint('[API] updateProgress response: ${resp.statusCode} ${resp.body}');
      return resp.statusCode < 500;
    } catch (e) {
      debugPrint('[API] updateProgress error: $e');
      rethrow;
    }
  }

  /// Update ebook reading progress on the server. Returns whether the PATCH
  /// landed, so the caller can queue the position for a later retry.
  /// PATCH /api/me/progress/:id
  /// HTTP status of the last [updateEbookProgress], null when it never got an
  /// answer. A 404 means the server has no such book, so retrying is pointless.
  int? lastEbookProgressStatus;

  Future<bool> updateEbookProgress(
    String itemId, {
    required String ebookLocation,
    required double ebookProgress,
  }) async {
    lastEbookProgressStatus = null;
    try {
      final body = jsonEncode({
        'ebookLocation': ebookLocation,
        'ebookProgress': ebookProgress,
        // Only ever MARK finished from the ebook; never send isFinished:false.
        // The server shares one isFinished flag for audio+ebook, and on a
        // true->false transition it also resets currentTime to 0 - so sending
        // false here would un-finish the book and wipe the audiobook's position.
        if (ebookProgress >= 1.0) 'isFinished': true,
      });
      final progressPath = itemId.length > 36
          ? '${itemId.substring(0, 36)}/${itemId.substring(37)}'
          : itemId;
      debugPrint('[API] updateEbookProgress PATCH /api/me/progress/$progressPath');
      final resp = await http.patch(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$progressPath'),
        headers: _headers,
        body: body,
      ).timeout(const Duration(seconds: 10));
      debugPrint('[API] updateEbookProgress response: ${resp.statusCode} ${resp.body}');
      lastEbookProgressStatus = resp.statusCode;
      return resp.statusCode >= 200 && resp.statusCode < 300;
    } catch (e) {
      debugPrint('[API] updateEbookProgress error: $e');
      return false;
    }
  }

  /// Mark a book as finished on the server.
  Future<void> markFinished(String itemId, double duration) async {
    await updateProgress(
      itemId,
      currentTime: duration,
      duration: duration,
      isFinished: true,
    );
  }

  /// Mark a book as not finished (reset progress to a position).
  Future<void> markNotFinished(String itemId, {
    required double currentTime,
    required double duration,
  }) async {
    await updateProgress(
      itemId,
      currentTime: currentTime,
      duration: duration,
      isFinished: false,
    );
  }

  /// Reset progress to zero. [progressId] is the server's progress record id
  /// when one is known; the delete route only accepts that.
  Future<bool> resetProgress(String itemId, double duration,
      {String? progressId}) async {
    try {
      final progressPath = itemId.length > 36
          ? '${itemId.substring(0, 36)}/${itemId.substring(37)}'
          : itemId;
      final isCompound = itemId.length > 36;
      final apiItemId = isCompound ? itemId.substring(0, 36) : itemId;
      final episodeId = isCompound ? itemId.substring(37) : null;

      if (progressId != null) await deleteMediaProgress(progressId);

      // Start session at 0 and close — forces server to update position. An
      // EPUB's narration has no server audio to open a session on.
      final sessionData = NarratedBooks.contains(apiItemId) && episodeId == null
          ? null
          : await startPlaybackSession(apiItemId, episodeId: episodeId);
      if (sessionData != null) {
        final sessionId = sessionData['id'] as String?;
        if (sessionId != null) {
          await syncPlaybackSession(sessionId, currentTime: 0, duration: duration);
          await closePlaybackSession(sessionId);
        }
      }

      // PATCH last to hide from continue listening (after session sync)
      await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$progressPath'),
        body: jsonEncode({
          'currentTime': 0,
          'progress': 0,
          'ebookLocation': null,
          'ebookProgress': 0,
          'isFinished': false,
          'hideFromContinueListening': true,
          'lastUpdate': DateTime.now().millisecondsSinceEpoch,
        }),
        timeout: const Duration(seconds: 10));

      return true;
    } catch (e) {
      debugPrint('[API] resetProgress error: $e');
      return false;
    }
  }

  /// Hide an entire series from the "Continue Series" home shelf.
  /// GET /api/me/series/:seriesId/remove-from-continue-listening
  Future<bool> removeSeriesFromContinueListening(String seriesId) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/series/$seriesId/remove-from-continue-listening'),
        timeout: const Duration(seconds: 10));
      return resp.statusCode == 200;
    } catch (e) {
      debugPrint('[API] removeSeriesFromContinueListening error: $e');
      return false;
    }
  }

  /// Hide a single item from the "Continue Listening" home shelf.
  /// GET /api/me/progress/:mediaProgressId/remove-from-continue-listening
  /// The path id is the media-progress record id (not the libraryItemId).
  Future<bool> removeItemFromContinueListening(String mediaProgressId) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$mediaProgressId/remove-from-continue-listening'),
        timeout: const Duration(seconds: 10));
      return resp.statusCode == 200;
    } catch (e) {
      debugPrint('[API] removeItemFromContinueListening error: $e');
      return false;
    }
  }

  // ─── Podcast Episode Endpoints ─────────────────────────────

  /// Start a playback session for a podcast episode.
  /// POST /api/items/:itemId/play/:episodeId
  Future<Map<String, dynamic>?> startEpisodePlaybackSession(
      String itemId, String episodeId, {bool forceTranscode = false}) async {
    try {
      final url = '$_cleanBaseUrl/api/items/$itemId/play/$episodeId';
      debugPrint('[ABS] Starting episode session: POST $url (forceTranscode: $forceTranscode)');
      final response = await _authPost(
        Uri.parse(url),
        body: jsonEncode({
          'deviceInfo': _deviceInfo,
          'forceDirectPlay': !forceTranscode,
          'forceTranscode': forceTranscode,
          'mediaPlayer': 'exo-player',
          'supportedMimeTypes': [
            'audio/flac',
            'audio/mpeg',
            'audio/mp4',
            'audio/ogg',
            'audio/aac',
            'audio/x-m4a',
            'audio/x-m4b',
            'audio/opus',
            'audio/webm',
            'audio/wav',
            'audio/x-wav',
            'audio/x-matroska',
            'audio/x-ms-wma',
          ],
        }),
        timeout: const Duration(seconds: 20));

      debugPrint('[ABS] Episode session response: ${response.statusCode}');
      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      } else {
        debugPrint('[ABS] Episode session failed: ${response.body}');
      }
    } catch (e) {
      debugPrint('[ABS] Episode session error: $e');
    }
    return null;
  }

  /// Get server progress for a podcast episode.
  /// GET /api/me/progress/:itemId/:episodeId
  Future<Map<String, dynamic>?> getEpisodeProgress(
      String itemId, String episodeId) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId/$episodeId'),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// Update progress for a podcast episode.
  /// PATCH /api/me/progress/:itemId/:episodeId
  /// Same [isFinished] contract as [updateProgress]: null leaves the flag out
  /// so the server writes the percent, true marks finished, false un-finishes
  /// and lets the server clear the position to 0.
  /// Returns false when it never reached the server (network error or 5xx),
  /// so a queued save can stay queued.
  Future<bool> updateEpisodeProgress(
    String itemId,
    String episodeId, {
    required double currentTime,
    required double duration,
    bool? isFinished,
  }) async {
    try {
      final url = Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId/$episodeId');
      if (isFinished == false) {
        final unfinish = await _authPatch(url,
            body: jsonEncode({'isFinished': false}),
            timeout: const Duration(seconds: 10));
        debugPrint('[API] updateEpisodeProgress unfinish $episodeId: ${unfinish.statusCode}');
        return unfinish.statusCode < 500;
      }
      final resp = await _authPatch(url,
        body: jsonEncode({
          'currentTime': currentTime,
          'duration': duration,
          'progress': duration > 0 ? (currentTime / duration).clamp(0.0, 1.0) : 0,
          if (isFinished == true) 'isFinished': true,
        }),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode != 200) {
        debugPrint('[API] updateEpisodeProgress $episodeId: HTTP ${resp.statusCode}');
      }
      return resp.statusCode < 500;
    } catch (e) {
      debugPrint('[API] updateEpisodeProgress error: $e');
      return false;
    }
  }

  /// DELETE /api/me/progress/:progressId
  /// The server's delete route takes the progress record's own id (from the
  /// user's mediaProgress list), not the item or episode id.
  Future<bool> deleteMediaProgress(String progressId) async {
    try {
      final resp = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/me/progress/$progressId'),
        timeout: const Duration(seconds: 10));
      debugPrint('[API] deleteMediaProgress $progressId: ${resp.statusCode}');
      return resp.statusCode >= 200 && resp.statusCode < 300;
    } catch (e) {
      debugPrint('[API] deleteMediaProgress error: $e');
      return false;
    }
  }

  /// Zero an episode's progress in place when there is no record id to delete.
  /// ABS ignores `progress` in a PATCH that also carries `isFinished`, and only
  /// zeroes an in-progress record when `isFinished` is absent, so this goes in
  /// two steps: clear the finished flag, then write the zero position.
  Future<bool> zeroEpisodeProgress(
    String itemId,
    String episodeId, {
    required double duration,
  }) async {
    try {
      final url = Uri.parse('$_cleanBaseUrl/api/me/progress/$itemId/$episodeId');
      final unfinish = await _authPatch(url,
          body: jsonEncode({'isFinished': false}),
          timeout: const Duration(seconds: 10));
      final zero = await _authPatch(url,
          body: jsonEncode({
            'currentTime': 0,
            'duration': duration,
            'progress': 0,
          }),
          timeout: const Duration(seconds: 10));
      debugPrint('[API] zeroEpisodeProgress: unfinish=${unfinish.statusCode} zero=${zero.statusCode}');
      return unfinish.statusCode == 200 && zero.statusCode == 200;
    } catch (e) {
      debugPrint('[API] zeroEpisodeProgress error: $e');
      return false;
    }
  }

  /// Get recent podcast episodes for a library.
  /// GET /api/libraries/:id/recent-episodes
  Future<List<dynamic>> getRecentEpisodes(String libraryId, {int limit = 25, int page = 0}) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/recent-episodes?limit=$limit&page=$page'),
      );
      if (resp.statusCode == 200) {
        final data = jsonDecode(resp.body);
        if (data is Map && data['episodes'] is List) return data['episodes'] as List<dynamic>;
        if (data is List) return data;
      }
    } catch (e) {
      debugPrint('[API] getRecentEpisodes error: $e');
    }
    return [];
  }

  /// Get a single library item with full detail (expanded=1 gives chapters, tracks, etc.)
  Future<Map<String, dynamic>?> getLibraryItem(String itemId) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId?expanded=1&include=progress'),
      );

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (e) {
      // ignore
    }
    return null;
  }

  // ─── Bookmark Endpoints ───────────────────────────────────

  /// Get bookmarks for an item from the server.
  Future<List<Map<String, dynamic>>?> getServerBookmarks(String itemId) async {
    try {
      final response = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/me/bookmarks/$itemId'),
        timeout: const Duration(seconds: 10));
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return (data['bookmarks'] as List<dynamic>? ?? const [])
            .whereType<Map<String, dynamic>>()
            .toList();
      }
      if (response.statusCode != 404) return null;

      final user = await getMe();
      if (user != null) {
        final bookmarks = user['bookmarks'] as List<dynamic>?;
        if (bookmarks != null) {
          // Filter to bookmarks for this item
          return bookmarks
              .whereType<Map<String, dynamic>>()
              .where((b) => b['libraryItemId'] == itemId)
              .toList();
        }
      }
      return [];
    } catch (e) { debugPrint('getServerBookmarks error: $e'); }
    return null;
  }

  /// Create a bookmark on the server.
  /// POST /api/me/item/:id/bookmark  body: { time, title }
  Future<bool> createBookmark(String itemId, {required double time, required String title}) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/me/item/$itemId/bookmark'),
        body: jsonEncode({'time': time, 'title': title}),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('createBookmark error: $e'); }
    return false;
  }

  /// Update a bookmark on the server.
  /// PATCH /api/me/item/:id/bookmark  body: { time, title }
  Future<bool> updateBookmark(String itemId, {required double time, required String title}) async {
    try {
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/me/item/$itemId/bookmark'),
        body: jsonEncode({'time': time, 'title': title}),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateBookmark error: $e'); }
    return false;
  }

  /// Delete a bookmark on the server.
  /// DELETE /api/me/item/:id/bookmark/:time
  Future<bool> deleteBookmark(String itemId, {required double time}) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/me/item/$itemId/bookmark/$time'),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('deleteBookmark error: $e'); }
    return false;
  }

  // ─── Email / E-Reader ──────────────────────────────────────────────

  /// Send the ebook file for [libraryItemId] to a configured ereader.
  /// POST /api/emails/send-ebook-to-device  body: { libraryItemId, deviceName }
  Future<bool> sendEBookToDevice({
    required String libraryItemId,
    required String deviceName,
  }) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/emails/send-ebook-to-device'),
        body: jsonEncode({'libraryItemId': libraryItemId, 'deviceName': deviceName}),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] sendEBookToDevice error: $e'); }
    return false;
  }

  /// GET /api/emails/settings (admin only)
  Future<Map<String, dynamic>?> getEmailSettings() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/emails/settings'));
      if (r.statusCode != 200) return null;
      final body = jsonDecode(r.body);
      if (body is Map<String, dynamic>) {
        // ABS wraps the settings in `settings` on this endpoint.
        final settings = body['settings'];
        if (settings is Map<String, dynamic>) return settings;
        return body;
      }
      return null;
    } catch (e) { debugPrint('[API] getEmailSettings error: $e'); }
    return null;
  }

  /// PATCH /api/emails/settings (admin only)
  Future<bool> updateEmailSettings(Map<String, dynamic> patch) async {
    try {
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/emails/settings'),
        body: jsonEncode(patch),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] updateEmailSettings error: $e'); }
    return false;
  }

  /// POST /api/emails/test (admin only)
  Future<bool> sendTestEmail() async {
    try {
      final r = await _authPost(Uri.parse('$_cleanBaseUrl/api/emails/test'));
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] sendTestEmail error: $e'); }
    return false;
  }

  /// Replace the full ereader devices list (admin only).
  /// POST /api/emails/ereader-devices  body: { ereaderDevices: [{name, email, availabilityOption, users}, ...] }
  Future<bool> updateEReaderDevices(List<Map<String, dynamic>> devices) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/emails/ereader-devices'),
        body: jsonEncode({'ereaderDevices': devices}),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] updateEReaderDevices error: $e'); }
    return false;
  }

  /// Get a single series with its books (paginated).
  /// If [onPageLoaded] is provided, it's called after each page with the
  /// cumulative results and total so the UI can show books as they arrive.
  /// Series metadata only, for ids stored without a name. Tries the direct
  /// series endpoint first and falls back to the per-library one for servers
  /// that don't expose it.
  Future<Map<String, dynamic>?> getSeriesInfo(
    String seriesId, {
    List<String> libraryIds = const [],
  }) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/series/$seriesId'),
      );
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    for (final libraryId in libraryIds) {
      try {
        final resp = await _authGet(
          Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/series/$seriesId'),
        );
        if (resp.statusCode == 200) {
          return jsonDecode(resp.body) as Map<String, dynamic>;
        }
      } catch (_) {}
    }
    return null;
  }

  Future<Map<String, dynamic>?> getSeries(String seriesId, {String? libraryId, void Function(List<dynamic> books, int total, {double? totalDuration})? onPageLoaded}) async {
    if (libraryId == null) return null;
    try {
      // ABS filter format: series.<base64(seriesId)>
      final filterValue = base64Encode(utf8.encode(seriesId));
      const pageSize = 100;
      final allResults = <dynamic>[];
      int total = 0;
      int page = 0;

      Future<Map<String, dynamic>?> fetchMeta() async {
        final sw = Stopwatch()..start();
        try {
          final resp = await _authGet(
            Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/series/$seriesId'),
            timeout: const Duration(seconds: 30));
          debugPrint('[API] getSeries $seriesId meta: HTTP ${resp.statusCode} '
              'in ${sw.elapsedMilliseconds}ms');
          if (resp.statusCode == 200) {
            return jsonDecode(resp.body) as Map<String, dynamic>;
          }
        } catch (e) {
          debugPrint('[API] getSeries $seriesId meta failed after '
              '${sw.elapsedMilliseconds}ms: $e');
        }
        return null;
      }

      Future<http.Response> fetchItems(int p) => _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/items?filter=series.$filterValue&sort=media.metadata.series.sequence&limit=$pageSize&page=$p&collapseseries=0'),
        timeout: const Duration(seconds: 30));

      // The books are what the sheet shows; the series record only adds the
      // name and total duration. Ask for the first page of books before the
      // record so a slow server answers the important one first, and let the
      // record land whenever it does.
      var itemsFuture = fetchItems(0);
      final metaFuture = fetchMeta();
      while (true) {
        final pageSw = Stopwatch()..start();
        final itemsResp = await itemsFuture;
        if (itemsResp.statusCode != 200) {
          debugPrint('[API] getSeries $seriesId items page $page failed: ${itemsResp.statusCode}');
          break;
        }
        final data = jsonDecode(itemsResp.body) as Map<String, dynamic>;
        final results = data['results'] as List<dynamic>? ?? [];
        total = (data['total'] as num?)?.toInt() ?? results.length;
        debugPrint('[API] getSeries $seriesId items page=$page results=${results.length} '
            'total=$total in ${pageSw.elapsedMilliseconds}ms');
        allResults.addAll(results);
        onPageLoaded?.call(allResults, total);
        if (allResults.length >= total || results.isEmpty) break;
        page++;
        itemsFuture = fetchItems(page);
      }

      final seriesMeta = await metaFuture;
      final totalDuration = (seriesMeta?['totalDuration'] as num?)?.toDouble();
      if (allResults.isNotEmpty) {
        if (totalDuration != null) {
          onPageLoaded?.call(allResults, total, totalDuration: totalDuration);
        }
        return {
          'id': seriesId,
          'name': seriesMeta?['name'] ?? '',
          'books': allResults,
          'total': total,
          if (seriesMeta != null) 'totalDuration': seriesMeta['totalDuration'],
        };
      }
    } catch (e) {
      debugPrint('[API] getSeries $seriesId failed: $e');
    }
    return null;
  }

  /// Get books in a series with collapseseries=1 to detect sub-series.
  /// Returns items where books sharing another series are collapsed into
  /// a single entry with a 'collapsedSeries' object.
  Future<List<dynamic>> getSeriesCollapsed(String seriesId, {required String libraryId}) async {
    try {
      final filterValue = base64Encode(utf8.encode(seriesId));
      final allResults = <dynamic>[];
      int page = 0;
      final sw = Stopwatch()..start();
      while (true) {
        final url = '$_cleanBaseUrl/api/libraries/$libraryId/items?filter=series.$filterValue&sort=addedAt&limit=100&page=$page&collapseseries=1';
        final resp = await _authGet(Uri.parse(url), timeout: const Duration(seconds: 60));
        if (resp.statusCode != 200) {
          debugPrint('[API] getSeriesCollapsed page $page failed: ${resp.statusCode}');
          break;
        }
        final data = jsonDecode(resp.body) as Map<String, dynamic>;
        final results = data['results'] as List<dynamic>? ?? [];
        final total = (data['total'] as num?)?.toInt() ?? results.length;
        debugPrint('[API] getSeriesCollapsed page=$page results=${results.length} '
            'total=$total in ${sw.elapsedMilliseconds}ms');
        sw.reset();
        allResults.addAll(results);
        if (allResults.length >= total || results.isEmpty) break;
        page++;
      }
      return allResults;
    } catch (e) { debugPrint('[API] getSeriesCollapsed error: $e'); }
    return [];
  }

  /// Search a library. Returns { book: [...], series: [...], authors: [...] }
  Future<Map<String, dynamic>?> searchLibrary(
    String libraryId,
    String query, {
    int limit = 25,
  }) async {
    try {
      final encoded = Uri.encodeQueryComponent(query);
      final response = await _authGet(
        Uri.parse(
          '$_cleanBaseUrl/api/libraries/$libraryId/search?q=$encoded&limit=$limit',
        ),
        timeout: const Duration(seconds: 60),
      );

      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
    } catch (e) {
      // ignore
    }
    return null;
  }

  /// Search for book metadata via the ABS server's search endpoint.
  /// Uses the server's configured providers (Audible, Google, etc.).
  /// Returns a list of result maps with title, author, description, cover, etc.
  Future<List<Map<String, dynamic>>> searchBooks({
    required String title,
    String? author,
    String provider = 'audible',
  }) async {
    try {
      final params = <String, String>{
        'title': title,
        'provider': provider,
        'region': _region,
      };
      if (author != null && author.isNotEmpty) {
        params['author'] = author;
      }
      final uri = Uri.parse('$_cleanBaseUrl/api/search/books')
          .replace(queryParameters: params);
      debugPrint('[API] searchBooks: $uri');
      final response = await _authGet(
        uri,
      );

      debugPrint('[API] searchBooks status=${response.statusCode} bodyLen=${response.body.length}');

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body);

        // ABS returns a plain List for most providers
        if (data is List) {
          debugPrint('[API] searchBooks: got List with ${data.length} items');
          return data.whereType<Map<String, dynamic>>().toList();
        }

        // Some providers may return a Map with results nested under a key
        if (data is Map<String, dynamic>) {
          debugPrint('[API] searchBooks: got Map with keys: ${data.keys.join(', ')}');
          // Try common nesting patterns
          for (final key in ['results', 'items', 'books', 'matches']) {
            final nested = data[key];
            if (nested is List && nested.isNotEmpty) {
              return nested.whereType<Map<String, dynamic>>().toList();
            }
          }
          // Single result as a map — wrap it
          if (data.containsKey('title') || data.containsKey('book')) {
            return [data];
          }
        }

        debugPrint('[API] searchBooks: unexpected response type: ${data.runtimeType}');
      }
    } catch (e) {
      debugPrint('[API] searchBooks error: $e');
    }
    return [];
  }

  /// Audible rating for an ASIN: the score and how many ratings it rests on.
  /// Audible's own catalog answers both, on the store matching the device
  /// locale like every other Audible lookup here. Audnexus stays as the
  /// fallback; it knows the score but not the count.
  /// Returns { rating, count, asin } or null.
  static Future<Map<String, dynamic>?> getAudibleRating(String asin) async {
    final catalog = await _audibleCatalogRating(asin);
    if (catalog != null) return catalog;
    try {
      final response = await http.get(
        Uri.parse('https://api.audnex.us/books/$asin?region=$_region&update=1'),
      ).timeout(const Duration(seconds: 10));

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final rating = data['rating'] as String?;
        if (rating != null) {
          return {
            'rating': double.tryParse(rating) ?? 0.0,
            'count': null,
            'asin': asin,
          };
        }
      }
    } catch (e) {
      // ignore — Audnexus is optional
    }
    return null;
  }

  static Future<Map<String, dynamic>?> _audibleCatalogRating(String asin) async {
    // Audible's API sends no CORS headers, so a browser always blocks it.
    if (kIsWeb) return null;
    try {
      final response = await http.get(
        Uri.parse(
          'https://api.audible$_audibleTld/1.0/catalog/products/'
          '${Uri.encodeComponent(asin)}?response_groups=rating',
        ),
      ).timeout(const Duration(seconds: 10));
      if (response.statusCode != 200) return null;
      final data = jsonDecode(response.body) as Map<String, dynamic>;
      final product = data['product'] as Map<String, dynamic>?;
      final overall = (product?['rating'] as Map<String, dynamic>?)
          ?['overall_distribution'] as Map<String, dynamic>?;
      final score = (overall?['average_rating'] as num?)?.toDouble();
      final count = (overall?['num_ratings'] as num?)?.toInt();
      if (score == null || !score.isFinite || score <= 0 || score > 5) {
        return null;
      }
      return {
        'rating': score,
        'count': count != null && count >= 0 ? count : null,
        'asin': asin,
      };
    } catch (e) {
      debugPrint('[API] Audible catalog rating $asin error: $e');
      return null;
    }
  }

  /// Read a previously-fetched Audible rating from local cache, keyed by
  /// library item id. Used so the rating shows immediately on book detail
  /// open even when Audnexus is slow or unreachable, and so a transient
  /// network failure doesn't make a known rating disappear.
  static Future<Map<String, dynamic>?> getCachedAudibleRating(String itemId) async {
    try {
      final prefs = await SharedPreferences.getInstance();
      final raw = prefs.getString('audible_rating_$itemId');
      if (raw == null) return null;
      final data = jsonDecode(raw) as Map<String, dynamic>;
      final rating = (data['rating'] as num?)?.toDouble();
      if (rating == null || rating <= 0) return null;
      return {
        'rating': rating,
        'count': (data['count'] as num?)?.toInt(),
        'asin': data['asin'] as String?,
      };
    } catch (_) {
      return null;
    }
  }

  /// Persist a fresh Audible rating so subsequent book detail opens render
  /// the stars instantly without waiting on Audnexus.
  static Future<void> setCachedAudibleRating(
      String itemId, double rating, String? asin, {int? count}) async {
    if (rating <= 0) return;
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString('audible_rating_$itemId', jsonEncode({
        'rating': rating,
        'count': count,
        'asin': asin,
        'fetchedAt': DateTime.now().millisecondsSinceEpoch,
      }));
    } catch (_) {}
  }

  /// Search Audible via the audiobookshelf server for an ASIN by title+author,
  /// then fetch the rating from Audnexus. Used as a fallback when the book's
  /// stored ASIN returns no rating.
  Future<Map<String, dynamic>?> searchAudibleRating(
      String title, String? author) async {
    try {
      // Use the ABS server's search endpoint to query Audible for the book.
      final response = await _authGet(
        Uri.parse(
          '$_cleanBaseUrl/api/search/covers?title=${Uri.encodeQueryComponent(title)}'
          '&author=${Uri.encodeQueryComponent(author ?? '')}'
          '&provider=audible&region=$_region',
        ),
      );

      if (response.statusCode == 200) {
        final results = jsonDecode(response.body) as List<dynamic>? ?? [];
        // Look for an ASIN in the results
        for (final r in results) {
          if (r is Map<String, dynamic>) {
            final asin = r['asin'] as String? ?? r['key'] as String? ?? '';
            if (asin.isNotEmpty && asin.startsWith('B')) {
              return await getAudibleRating(asin);
            }
          }
        }
      }
    } catch (e) {
      // ignore
    }
    return null;
  }

  // ─── Audible Series Discovery ─────────────────────────────

  /// Supported Audible regions for series discovery.
  static const audibleRegions = {
    'us': 'Audible.com (US)',
    'uk': 'Audible.co.uk (UK)',
    'au': 'Audible.com.au (AU)',
    'ca': 'Audible.ca (CA)',
    'de': 'Audible.de (DE)',
    'fr': 'Audible.fr (FR)',
    'it': 'Audible.it (IT)',
    'es': 'Audible.es (ES)',
    'jp': 'Audible.co.jp (JP)',
    'in': 'Audible.in (IN)',
    'br': 'Audible.com.br (BR)',
  };

  /// Map region code to Audible API TLD.
  static String _audibleTldFor(String region) {
    const tlds = {
      'us': '.com', 'uk': '.co.uk', 'gb': '.co.uk', 'au': '.com.au',
      'ca': '.ca', 'de': '.de', 'fr': '.fr', 'it': '.it', 'es': '.es',
      'jp': '.co.jp', 'in': '.in', 'br': '.com.br',
    };
    return tlds[region] ?? '.com';
  }

  static String get _audibleTld => _audibleTldFor(_region);

  /// Fetch full book metadata from Audnexus by ASIN.
  /// Returns the raw Audnexus response including seriesPrimary, releaseDate, etc.
  /// If [region] is provided, it overrides the device locale region.
  static Future<Map<String, dynamic>?> getAudnexusBook(String asin, {String? region}) async {
    final r = region ?? _region;
    final book = await _getAudnexusBookRaw(asin, r);
    if (book != null || r == 'us') return book;
    // Audnexus often has no data for the smaller regional stores
    // (REGION_UNAVAILABLE) even when that store sells the book. Series
    // structure is the same everywhere, so fall back to the US record
    // instead of failing the whole lookup.
    return _getAudnexusBookRaw(asin, 'us');
  }

  static Future<Map<String, dynamic>?> _getAudnexusBookRaw(String asin, String region) async {
    try {
      final response = await http.get(
        Uri.parse('https://api.audnex.us/books/$asin?region=$region'),
      ).timeout(const Duration(seconds: 10));
      if (response.statusCode == 200) {
        return jsonDecode(response.body) as Map<String, dynamic>;
      }
      debugPrint('[API] getAudnexusBook $asin region=$region status=${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getAudnexusBook error: $e');
    }
    return null;
  }

  /// Get all book ASINs in an Audible series using the catalog relationships endpoint.
  /// Returns a list of { asin, sequence, sort } maps.
  static Future<List<Map<String, dynamic>>> getAudibleSeriesBooks(String seriesAsin, {String? region}) async {
    if (kIsWeb) return [];
    try {
      final tld = region != null ? _audibleTldFor(region) : _audibleTld;
      final url = 'https://api.audible$tld/1.0/catalog/products/$seriesAsin'
          '?response_groups=relationships';
      debugPrint('[API] getAudibleSeriesBooks: $url');
      final response = await http.get(Uri.parse(url))
          .timeout(const Duration(seconds: 15));

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        final product = data['product'] as Map<String, dynamic>? ?? {};
        final relationships = product['relationships'] as List<dynamic>? ?? [];

        final books = <Map<String, dynamic>>[];
        for (final r in relationships) {
          if (r is! Map<String, dynamic>) continue;
          final asin = r['asin'] as String?;
          if (asin == null || asin.isEmpty) continue;
          books.add({
            'asin': asin,
            'sequence': r['sequence']?.toString() ?? '',
            'sort': r['sort']?.toString() ?? '0',
          });
        }
        return books;
      }
      debugPrint('[API] getAudibleSeriesBooks status=${response.statusCode}');
    } catch (e) {
      debugPrint('[API] getAudibleSeriesBooks error: $e');
    }
    return [];
  }

  /// Fetch details for a single book from the Audible catalog API.
  /// Returns title, authors, narrators, release_date, runtime, rating, cover, etc.
  static Future<Map<String, dynamic>?> getAudibleBookDetails(String asin, {String? region}) async {
    if (kIsWeb) return null;
    try {
      final tld = region != null ? _audibleTldFor(region) : _audibleTld;
      final url = 'https://api.audible$tld/1.0/catalog/products/$asin'
          '?response_groups=product_attrs,product_desc,product_details,series,rating,media';
      final response = await http.get(Uri.parse(url))
          .timeout(const Duration(seconds: 10));

      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return data['product'] as Map<String, dynamic>?;
      }
    } catch (e) {
      debugPrint('[API] getAudibleBookDetails error: $e');
    }
    return null;
  }

  /// High-level: discover all books in an Audible series, returning enriched data.
  /// [seriesAsin] is the Audible series ASIN.
  /// Returns a list of book maps with: asin, title, subtitle, authors, narrators,
  /// releaseDate, runtimeMinutes, rating, coverUrl, sequence.
  /// Books are deduplicated by sequence (prefers user's region) and sorted.
  /// When [newestOnly] is true (default false), only fetches details for the
  /// newest ~50 books by sequence - used by upcoming releases scan to avoid
  /// hammering the Audible API for series with hundreds of entries.
  static Future<List<Map<String, dynamic>>> discoverAudibleSeries(
    String seriesAsin, {
    String? region,
    bool newestOnly = false,
  }) async {
    var effectiveRegion = region;
    var relationships = await getAudibleSeriesBooks(seriesAsin, region: region);
    if (relationships.isEmpty && region != null && region != 'us') {
      // Regional stores often lack the series ASIN even when they sell the
      // books - US data beats no data. Details must then come from the US
      // store too, since these relationship ASINs may not exist regionally.
      relationships = await getAudibleSeriesBooks(seriesAsin, region: 'us');
      if (relationships.isNotEmpty) {
        debugPrint('[API] discoverAudibleSeries: region $region empty, using us');
        effectiveRegion = 'us';
      }
    }
    if (relationships.isEmpty) return [];

    final bySequence = <String, List<Map<String, dynamic>>>{};
    for (final r in relationships) {
      final seq = r['sequence'] as String? ?? '';
      final sort = r['sort'] as String? ?? '0';
      final key = seq.isNotEmpty ? seq : 'sort_$sort';
      bySequence.putIfAbsent(key, () => []).add(r);
    }

    var uniqueBooks = <Map<String, dynamic>>[];
    for (final entry in bySequence.entries) {
      uniqueBooks.add({
        ...entry.value.first,
        '_allAsins': entry.value.map((e) => e['asin'] as String).toList(),
      });
    }

    // For upcoming releases scan, only fetch details for the newest books.
    // Sort by sequence descending and take the tail - upcoming/recent releases
    // will always be among the highest-numbered entries.
    if (newestOnly && uniqueBooks.length > 50) {
      uniqueBooks.sort((a, b) {
        final seqA = double.tryParse(a['sequence']?.toString() ?? '') ?? 999999;
        final seqB = double.tryParse(b['sequence']?.toString() ?? '') ?? 999999;
        return seqB.compareTo(seqA); // descending
      });
      debugPrint('[API] discoverAudibleSeries: capping ${uniqueBooks.length} books to newest 50');
      uniqueBooks = uniqueBooks.take(50).toList();
    }

    final results = <Map<String, dynamic>>[];
    for (var i = 0; i < uniqueBooks.length; i += 10) {
      final batch = uniqueBooks.skip(i).take(10);
      final futures = batch.map((book) async {
        final asin = book['asin'] as String;
        final details = await getAudibleBookDetails(asin, region: effectiveRegion);
        if (details == null) return null;

        final authors = (details['authors'] as List<dynamic>? ?? [])
            .map((a) => (a as Map<String, dynamic>)['name'] ?? '').join(', ');
        final narrators = (details['narrators'] as List<dynamic>? ?? [])
            .map((n) => (n as Map<String, dynamic>)['name'] ?? '').join(', ');
        final rating = details['rating'] as Map<String, dynamic>?;

        return <String, dynamic>{
          'asin': asin,
          'title': details['title'] ?? '',
          'subtitle': details['subtitle'] ?? '',
          'authors': authors,
          'narrators': narrators,
          'releaseDate': details['release_date'] ?? '',
          'runtimeMinutes': details['runtime_length_min'] ?? 0,
          'rating': rating?['overall_distribution']?['display_average_rating'] ?? 0.0,
          'numRatings': rating?['overall_distribution']?['num_ratings'] ?? 0,
          'coverUrl': details['product_images']?['500'] ?? details['product_images']?['1024'] ?? '',
          'sequence': book['sequence'] ?? '',
          'sort': book['sort'] ?? '0',
          'publisherSummary': details['publisher_summary'] ?? '',
          'allAsins': book['_allAsins'] ?? <String>[asin],
        };
      });
      final batchResults = await Future.wait(futures);
      results.addAll(batchResults.whereType<Map<String, dynamic>>());
    }

    results.sort((a, b) {
      final seqA = double.tryParse(a['sequence']?.toString() ?? '') ?? 999;
      final seqB = double.tryParse(b['sequence']?.toString() ?? '') ?? 999;
      return seqA.compareTo(seqB);
    });

    return results;
  }

  // ─── Admin Endpoints ──────────────────────────────────────

  /// Get all users (admin only)
  Future<List<dynamic>> getUsers() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/users'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is List) return data;
        if (data is Map) {
          // ABS wraps in {"users": [...]}
          if (data['users'] is List) return data['users'] as List<dynamic>;
          // Fallback: return first list found
          for (final v in data.values) {
            if (v is List) return v;
          }
        }
      }
    } catch (e) { debugPrint('getUsers error: $e'); }
    return [];
  }

  /// Get online users (admin only)
  Future<List<dynamic>> getOnlineUsers() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/users/online'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is Map && data['usersOnline'] is List) return data['usersOnline'] as List<dynamic>;
        if (data is Map && data['openSessions'] is List) return data['openSessions'] as List<dynamic>;
        if (data is List) return data;
      }
    } catch (e) { debugPrint('getOnlineUsers error: $e'); }
    return [];
  }

  /// Get all listening sessions (admin only)
  Future<List<dynamic>> getAllSessions({int limit = 25}) async {
    try {
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/sessions?itemsPerPage=$limit'),
      );
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        return (data['sessions'] as List<dynamic>?) ?? [];
      }
    } catch (e) { debugPrint('getAllSessions error: $e'); }
    return [];
  }

  /// Admin: paginated listing of every user's sessions. Returns the full
  /// envelope (total, numPages, page, sessions) with each session carrying its
  /// user. Optionally filter to a single [userId]. Admin-only server-side.
  Future<Map<String, dynamic>?> getAllSessionsPaged({
    int page = 0,
    int itemsPerPage = 25,
    String? userId,
    String sort = 'updatedAt',
    bool desc = true,
  }) async {
    try {
      final params = <String, String>{
        'itemsPerPage': '$itemsPerPage',
        'page': '$page',
        'sort': sort,
        'desc': desc ? '1' : '0',
        if (userId != null && userId.isNotEmpty) 'user': userId,
      };
      final uri = Uri.parse('$_cleanBaseUrl/api/sessions')
          .replace(queryParameters: params);
      final r = await _authGet(uri, timeout: const Duration(seconds: 15));
      if (r.statusCode == 200) {
        return jsonDecode(r.body) as Map<String, dynamic>;
      }
    } catch (e) {
      debugPrint('getAllSessionsPaged error: $e');
    }
    return null;
  }

  /// Get all backups (admin only)
  Future<List<dynamic>> getBackups() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/backups'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        return (data['backups'] as List<dynamic>?) ?? [];
      }
    } catch (e) { debugPrint('getBackups error: $e'); }
    return [];
  }

  /// Get the server's currently running background tasks.
  Future<List<Map<String, dynamic>>?> getServerTasks() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/tasks'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        final rawTasks = data is Map ? data['tasks'] : data;
        if (rawTasks is List) {
          return rawTasks
              .whereType<Map>()
              .map((task) => Map<String, dynamic>.from(task))
              .toList();
        }
      }
      debugPrint('[API] getServerTasks failed: ${r.statusCode}');
    } catch (e) {
      debugPrint('[API] getServerTasks error: $e');
    }
    return null;
  }

  /// Check whether Audiobookshelf's destination directory for an upload is
  /// already in use. The web client performs this check before POST /api/upload
  /// so files are not merged into an existing library item directory.
  Future<UploadPathCheckResult> checkUploadPathExists({
    required String directory,
    required String folderPath,
  }) async {
    try {
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/filesystem/pathexists'),
        body: jsonEncode({
          'directory': directory,
          'folderPath': folderPath,
        }),
        timeout: const Duration(seconds: 20),
      );
      if (response.statusCode == 200) {
        final data = jsonDecode(response.body) as Map<String, dynamic>;
        return UploadPathCheckResult(
          success: true,
          exists: data['exists'] == true,
          libraryItemTitle: data['libraryItemTitle'] as String?,
        );
      }
      final error = response.body.trim();
      return UploadPathCheckResult(
        success: false,
        error: error.isEmpty ? 'HTTP ${response.statusCode}' : error,
      );
    } catch (e) {
      debugPrint('[API] checkUploadPathExists error: $e');
      return UploadPathCheckResult(success: false, error: '$e');
    }
  }

  /// Upload one book or podcast and its related files to Audiobookshelf.
  /// File fields are numbered to match the server's web uploader.
  Future<MediaUploadResult> uploadMedia(
    MediaUploadRequest upload, {
    void Function(int sentBytes, int totalBytes)? onProgress,
  }) async {
    try {
      final request = http.MultipartRequest(
        'POST',
        Uri.parse('$_cleanBaseUrl/api/upload'),
      );
      request.headers.addAll(mediaHeaders);
      request.fields.addAll({
        'title': upload.title.trim(),
        'library': upload.libraryId,
        'folder': upload.folderId,
        if (upload.mediaType != 'podcast') ...{
          'author': upload.author?.trim() ?? '',
          'series': upload.series?.trim() ?? '',
        },
      });

      final totalBytes = upload.files.fold<int>(
        0,
        (total, file) => total + file.size,
      );
      var sentBytes = 0;

      for (var i = 0; i < upload.files.length; i++) {
        final file = upload.files[i];
        if (file.bytes != null) {
          final source = Stream<List<int>>.value(file.bytes!);
          final tracked = source.map((chunk) {
            sentBytes += chunk.length;
            onProgress?.call(sentBytes, totalBytes);
            return chunk;
          });
          request.files.add(http.MultipartFile(
            '$i',
            tracked,
            file.size > 0 ? file.size : file.bytes!.length,
            filename: file.name,
          ));
        } else if (file.path != null && file.path!.isNotEmpty) {
          request.files.add(await http.MultipartFile.fromPath(
            '$i',
            file.path!,
            filename: file.name,
          ));
        } else if (file.readStream != null) {
          final tracked = file.readStream!.map((chunk) {
            sentBytes += chunk.length;
            onProgress?.call(sentBytes, totalBytes);
            return chunk;
          });
          request.files.add(http.MultipartFile(
            '$i',
            tracked,
            file.size,
            filename: file.name,
          ));
        } else {
          return MediaUploadResult(
            success: false,
            error: 'Unable to read ${file.name}',
          );
        }
      }

      final streamedResponse = await request.send();
      final response = await http.Response.fromStream(streamedResponse);
      if (response.statusCode == 200) {
        onProgress?.call(totalBytes, totalBytes);
        return const MediaUploadResult(success: true);
      }

      final error = response.body.trim();
      return MediaUploadResult(
        success: false,
        error: error.isEmpty ? 'HTTP ${response.statusCode}' : error,
      );
    } catch (e) {
      debugPrint('[API] uploadMedia error: $e');
      return MediaUploadResult(success: false, error: '$e');
    }
  }

  /// Create a backup (admin only)
  Future<bool> createBackup() async {
    try {
      final r = await _authPost(Uri.parse('$_cleanBaseUrl/api/backups'), timeout: const Duration(seconds: 60));
      return r.statusCode == 200;
    } catch (e) { debugPrint('createBackup error: $e'); }
    return false;
  }

  /// Scan a library's folders (admin only)
  Future<bool> scanLibrary(String libraryId) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/scan'),
        timeout: const Duration(seconds: 30));
      return r.statusCode == 200;
    } catch (e) { debugPrint('scanLibrary error: $e'); }
    return false;
  }

  /// Match all items in a library (admin only)
  Future<bool> matchLibrary(String libraryId) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/match'),
        timeout: const Duration(seconds: 30));
      return r.statusCode == 200;
    } catch (e) { debugPrint('matchLibrary error: $e'); }
    return false;
  }

  /// Get library stats (admin only)
  Future<Map<String, dynamic>?> getLibraryStats(String libraryId) async {
    try {
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/stats'),
      );
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('getLibraryStats error: $e'); }
    return null;
  }

  /// Purge server cache (admin only)
  Future<bool> purgeCache() async {
    try {
      final r = await _authPost(Uri.parse('$_cleanBaseUrl/api/cache/purge'), timeout: const Duration(seconds: 30));
      return r.statusCode == 200;
    } catch (e) { debugPrint('purgeCache error: $e'); }
    return false;
  }

  /// GET /api/filesystem?path= — browse server directories (admin only).
  /// Omit [path] for the root listing (drive letters on Windows servers).
  /// Returns { posix: bool, directories: [{path, dirname, level}] }.
  Future<Map<String, dynamic>?> getFilesystemPaths({String? path}) async {
    try {
      final uri = Uri.parse('$_cleanBaseUrl/api/filesystem')
          .replace(queryParameters: path != null ? {'path': path} : null);
      final r = await _authGet(uri, timeout: const Duration(seconds: 20));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('[API] getFilesystemPaths error: $e'); }
    return null;
  }

  /// POST /api/libraries — create a library (admin only).
  /// [body] needs name + folders (each {fullPath}); optional mediaType, icon,
  /// provider, settings. Returns the new library object on success.
  Future<Map<String, dynamic>?> createLibrary(Map<String, dynamic> body) async {
    try {
      final r = await _authPost(Uri.parse('$_cleanBaseUrl/api/libraries'),
          body: jsonEncode(body), timeout: const Duration(seconds: 30));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
      debugPrint('[API] createLibrary failed: ${r.statusCode}');
    } catch (e) { debugPrint('[API] createLibrary error: $e'); }
    return null;
  }

  /// PATCH /api/libraries/:id — partial update (admin only).
  /// In [body]'s folders array, keep existing folders as {id, fullPath}, add
  /// new ones as {fullPath}; omitting a folder DELETES it (cascades on server).
  Future<bool> updateLibrary(String id, Map<String, dynamic> body) async {
    try {
      final r = await _authPatch(Uri.parse('$_cleanBaseUrl/api/libraries/$id'),
          body: jsonEncode(body), timeout: const Duration(seconds: 30));
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] updateLibrary error: $e'); }
    return false;
  }

  /// DELETE /api/libraries/:id — removes the library and all its items (admin only).
  Future<bool> deleteLibrary(String id) async {
    try {
      final r = await _authDelete(Uri.parse('$_cleanBaseUrl/api/libraries/$id'),
          timeout: const Duration(seconds: 30));
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] deleteLibrary error: $e'); }
    return false;
  }

  /// POST /api/libraries/order — body is a raw array [{id, newOrder}] (admin only).
  Future<bool> reorderLibraries(List<Map<String, dynamic>> order) async {
    try {
      final r = await _authPost(Uri.parse('$_cleanBaseUrl/api/libraries/order'),
          body: jsonEncode(order));
      return r.statusCode == 200;
    } catch (e) { debugPrint('[API] reorderLibraries error: $e'); }
    return false;
  }

  /// Metadata provider ids for the library editor. The server has no endpoint
  /// for these - the ABS web UI hardcodes them client-side - so this is the
  /// same fixed set, plus any custom metadata providers configured on the
  /// server (GET /api/custom-metadata-providers, dropdown value custom-<id>).
  Future<List<String>> getMetadataProviders() async {
    final out = <String>[
      'google', 'openlibrary', 'itunes',
      'audible', 'audible.ca', 'audible.uk', 'audible.au', 'audible.fr',
      'audible.de', 'audible.jp', 'audible.it', 'audible.in', 'audible.es',
      'audnexus', 'fantlab',
    ];
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/custom-metadata-providers'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        for (final p in (data['providers'] as List?) ?? []) {
          if (p is Map && p['id'] != null) {
            final v = 'custom-${p['id']}';
            if (!out.contains(v)) out.add(v);
          }
        }
      }
    } catch (e) { debugPrint('[API] getMetadataProviders error: $e'); }
    return out;
  }

  /// PATCH /api/settings — update server settings (admin only).
  /// There is no GET; read current values from AuthProvider.serverSettings.
  /// Returns the fresh serverSettings map so the caller can re-cache it.
  Future<Map<String, dynamic>?> updateServerSettings(Map<String, dynamic> patch) async {
    try {
      final r = await _authPatch(Uri.parse('$_cleanBaseUrl/api/settings'),
          body: jsonEncode(patch));
      if (r.statusCode == 200) {
        return jsonDecode(r.body)['serverSettings'] as Map<String, dynamic>?;
      }
      debugPrint('[API] updateServerSettings failed: ${r.statusCode}');
    } catch (e) { debugPrint('[API] updateServerSettings error: $e'); }
    return null;
  }

  /// PATCH /api/sorting-prefixes — body { sortingPrefixes: [..] } (admin only).
  /// Returns the fresh serverSettings map (the response also has rowsUpdated).
  Future<Map<String, dynamic>?> updateSortingPrefixes(List<String> prefixes) async {
    try {
      final r = await _authPatch(Uri.parse('$_cleanBaseUrl/api/sorting-prefixes'),
          body: jsonEncode({'sortingPrefixes': prefixes}),
          timeout: const Duration(seconds: 30));
      if (r.statusCode == 200) {
        return jsonDecode(r.body)['serverSettings'] as Map<String, dynamic>?;
      }
    } catch (e) { debugPrint('[API] updateSortingPrefixes error: $e'); }
    return null;
  }

  /// GET /api/auth-settings - password and OpenID Connect settings (admin only).
  Future<Map<String, dynamic>?> getAuthSettings() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/auth-settings'));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
      debugPrint('[API] getAuthSettings failed: ${r.statusCode}');
    } catch (e) { debugPrint('[API] getAuthSettings error: $e'); }
    return null;
  }

  /// PATCH /api/auth-settings (admin only). Returns { updated, serverSettings }.
  Future<Map<String, dynamic>?> updateAuthSettings(Map<String, dynamic> patch) async {
    try {
      final r = await _authPatch(Uri.parse('$_cleanBaseUrl/api/auth-settings'),
          body: jsonEncode(patch));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
      debugPrint('[API] updateAuthSettings failed: ${r.statusCode}');
    } catch (e) { debugPrint('[API] updateAuthSettings error: $e'); }
    return null;
  }

  /// GET /auth/openid/config?issuer= - the server fetches the issuer's
  /// openid-configuration (admin only). On failure [error] holds the
  /// server's message.
  Future<({Map<String, dynamic>? config, String? error})> getOpenIdIssuerConfig(String issuer) async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/auth/openid/config')
          .replace(queryParameters: {'issuer': issuer}));
      if (r.statusCode == 200) {
        return (config: jsonDecode(r.body) as Map<String, dynamic>, error: null);
      }
      final body = r.body.trim();
      return (config: null, error: body.isNotEmpty ? body : 'HTTP ${r.statusCode}');
    } catch (e) {
      debugPrint('[API] getOpenIdIssuerConfig error: $e');
      return (config: null, error: e.toString());
    }
  }

  /// GET /api/stats/server — { books, podcasts, total } (admin only).
  Future<Map<String, dynamic>?> getServerStats() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/stats/server'));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('[API] getServerStats error: $e'); }
    return null;
  }

  /// GET /api/stats/year/:year — admin year-in-review stats (admin only).
  Future<Map<String, dynamic>?> getServerYearStats(int year) async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/stats/year/$year'),
          timeout: const Duration(seconds: 30));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('[API] getServerYearStats error: $e'); }
    return null;
  }

  /// GET /api/me/stats/year/:year — the signed-in user's year-in-review stats.
  Future<Map<String, dynamic>?> getMyYearStats(int year) async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/me/stats/year/$year'),
          timeout: const Duration(seconds: 30));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('[API] getMyYearStats error: $e'); }
    return null;
  }

  /// Create a new user (admin only)
  Future<Map<String, dynamic>?> createUser({
    required String username,
    required String password,
    required String type,
    Map<String, dynamic>? permissions,
    List<String>? librariesAccessible,
    bool isActive = true,
  }) async {
    try {
      final body = <String, dynamic>{
        'username': username,
        'password': password,
        'type': type,
        'isActive': isActive,
      };
      if (permissions != null) body['permissions'] = permissions;
      if (librariesAccessible != null) body['librariesAccessible'] = librariesAccessible;
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/users'),
        body: jsonEncode(body),
      );
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('createUser error: $e'); }
    return null;
  }

  /// Get a single user with full details including mediaProgress (admin only)
  Future<Map<String, dynamic>?> getUser(String userId) async {
    try {
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/users/$userId'),
      );
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('getUser error: $e'); }
    return null;
  }

  /// Update a user (admin only)
  Future<bool> updateUser(String userId, Map<String, dynamic> updates) async {
    try {
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/users/$userId'),
        body: jsonEncode(updates),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateUser error: $e'); }
    return false;
  }

  /// Delete a user (admin only)
  Future<bool> deleteUser(String userId) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/users/$userId'),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('deleteUser error: $e'); }
    return false;
  }

  /// Unlink a user from their OpenID/SSO connection (admin only). Clears the
  /// server's stored authOpenIDSub so the user can re-enroll. The server
  /// returns 200 even if there was no link to begin with.
  Future<bool> unlinkOpenID(String userId) async {
    try {
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/users/$userId/openid-unlink'),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('unlinkOpenID error: $e'); }
    return false;
  }

  /// List all API keys (admin only). Each entry includes the expanded `user`
  /// ({id, username, type}) plus name, isActive, expiresAt, lastUsedAt, createdAt.
  /// The actual key string is never returned here, only on creation.
  Future<List<dynamic>> getApiKeys() async {
    try {
      final r = await _authGet(Uri.parse('$_cleanBaseUrl/api/api-keys'));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is Map && data['apiKeys'] is List) return data['apiKeys'] as List<dynamic>;
        if (data is List) return data;
      }
    } catch (e) { debugPrint('getApiKeys error: $e'); }
    return [];
  }

  /// Create an API key (admin only). [expiresIn] is in seconds; pass null for
  /// no expiration. Returns the created key map which — only on creation —
  /// includes the actual token under `apiKey`.
  Future<Map<String, dynamic>?> createApiKey({
    required String name,
    required String userId,
    int? expiresIn,
    bool isActive = true,
  }) async {
    try {
      final body = <String, dynamic>{'name': name, 'userId': userId, 'isActive': isActive};
      if (expiresIn != null) body['expiresIn'] = expiresIn;
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/api-keys'),
        body: jsonEncode(body),
      );
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is Map && data['apiKey'] is Map) return Map<String, dynamic>.from(data['apiKey'] as Map);
      }
    } catch (e) { debugPrint('createApiKey error: $e'); }
    return null;
  }

  /// Update an API key (admin only). Only `isActive` and `userId` are mutable
  /// server-side (name and expiry are baked into the JWT).
  Future<bool> updateApiKey(String keyId, {bool? isActive, String? userId}) async {
    try {
      final body = <String, dynamic>{};
      if (isActive != null) body['isActive'] = isActive;
      if (userId != null) body['userId'] = userId;
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/api-keys/$keyId'),
        body: jsonEncode(body),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateApiKey error: $e'); }
    return false;
  }

  /// Delete (revoke) an API key (admin only).
  Future<bool> deleteApiKey(String keyId) async {
    try {
      final r = await _authDelete(Uri.parse('$_cleanBaseUrl/api/api-keys/$keyId'));
      return r.statusCode == 200;
    } catch (e) { debugPrint('deleteApiKey error: $e'); }
    return false;
  }

  /// Update a library item's media metadata (admin/root only).
  /// PATCH /api/items/:id/media. Tags live on `media`, not `metadata`, so
  /// pass them via the [tags] arg to be included at the top level of the
  /// payload alongside the metadata block.
  Future<bool> updateItemMedia(
    String itemId,
    Map<String, dynamic> media, {
    List<String>? tags,
  }) async {
    try {
      final body = <String, dynamic>{'metadata': media};
      if (tags != null) body['tags'] = tags;
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/media'),
        body: jsonEncode(body),
      );
      debugPrint('[API] updateItemMedia $itemId -> ${r.statusCode}: ${r.body}');
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateItemMedia error: $e'); }
    return false;
  }

  /// Upload a cover image URL for a library item (admin only)
  Future<bool> updateItemCoverUrl(String itemId, String url, {String? coverSlot}) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/cover'),
        body: jsonEncode({'url': url}),
        timeout: const Duration(seconds: 30));
      debugPrint('[API] updateItemCoverUrl $itemId -> ${r.statusCode}: ${r.body}');
      return r.statusCode == 200;
    } catch (e) { debugPrint('updateItemCoverUrl error: $e'); }
    return false;
  }

  /// Remove a library item's cover, leaving it with none (admin only).
  /// DELETE /api/items/:id/cover
  Future<bool> removeItemCover(String itemId, {String? coverSlot}) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/cover'),
        timeout: const Duration(seconds: 30));
      debugPrint('[API] removeItemCover $itemId -> ${r.statusCode}');
      return r.statusCode == 200;
    } catch (e) { debugPrint('removeItemCover error: $e'); }
    return false;
  }

  /// Upload a cover image file for a library item (admin only)
  Future<bool> uploadItemCover(String itemId, String filePath, {String? coverSlot}) async {
    try {
      final req = http.MultipartRequest(
        'POST',
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/cover'),
      );
      req.headers.addAll(_headers);
      req.files.add(await http.MultipartFile.fromPath('cover', filePath));
      final res = await req.send().timeout(const Duration(seconds: 60));
      return res.statusCode == 200;
    } catch (e) { debugPrint('uploadItemCover error: $e'); }
    return false;
  }

  /// Search provider cover images for a book.
  /// GET /api/search/covers?title=&author=&provider=  ->  { results: [url, ...] }
  Future<List<String>> searchCovers(String title,
      {String? author, String provider = 'google', String? coverSlot}) async {
    try {
      final uri = Uri.parse('$_cleanBaseUrl/api/search/covers').replace(queryParameters: {
        'title': title,
        if (author != null && author.trim().isNotEmpty) 'author': author.trim(),
        'provider': provider,
      });
      final r = await _authGet(uri, timeout: const Duration(seconds: 25));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        final results = data is Map<String, dynamic> ? data['results'] : data;
        if (results is List) {
          final urls = <String>[];
          for (final e in results) {
            if (e is String && e.isNotEmpty) {
              urls.add(e);
            } else if (e is Map<String, dynamic>) {
              final u = (e['cover'] ?? e['url'] ?? e['image']) as String?;
              if (u != null && u.isNotEmpty) urls.add(u);
            }
          }
          return urls;
        }
      }
    } catch (e) {
      debugPrint('[API] searchCovers error: $e');
    }
    return [];
  }

  // ─── Podcast Endpoints ────────────────────────────────────

  /// Search for podcasts (uses iTunes)
  Future<List<dynamic>> searchPodcasts(String query) async {
    try {
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/search/podcast?term=${Uri.encodeComponent(query)}'),
      );
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is List) return data;
        if (data is Map) {
          if (data['podcasts'] is List) return data['podcasts'] as List<dynamic>;
          for (final key in data.keys) {
            if (data[key] is List) return data[key] as List<dynamic>;
          }
        }
      }
    } catch (e) { debugPrint('searchPodcasts error: $e'); }
    return [];
  }

  /// Create a podcast (add to library from feed URL)
  Future<Map<String, dynamic>?> createPodcast({
    required String libraryId,
    required String folderId,
    required String feedUrl,
    required Map<String, dynamic> podcastData,
    bool autoDownloadEpisodes = false,
    String? autoDownloadSchedule,
  }) async {
    try {
      // ABS search returns: id, artistId, title, artistName, description,
      // descriptionPlain, releaseDate, genres, cover, trackCount, feedUrl,
      // pageUrl, explicit
      final title = podcastData['title'] as String? ?? 'Podcast';

      // Build the podcast path from the library folder + title
      String podcastPath = '';
      try {
        final libs = await getLibraries();
        final lib = libs.firstWhere((l) => l['id'] == libraryId, orElse: () => <String, dynamic>{});
        final folders = lib['folders'] as List?;
        if (folders != null && folders.isNotEmpty) {
          final folder = folders.firstWhere((f) => f['id'] == folderId, orElse: () => folders.first);
          final folderPath = folder['fullPath'] as String? ?? '';
          if (folderPath.isNotEmpty) {
            final cleanTitle = title.replaceAll(RegExp(r'[\\/:*?"<>|]'), '');
            podcastPath = '$folderPath/$cleanTitle';
          }
        }
      } catch (_) {}

      final body = <String, dynamic>{
        'libraryId': libraryId,
        'folderId': folderId,
        'path': podcastPath,
        'media': {
          'metadata': {
            'title': title,
            'author': podcastData['artistName'] ?? '',
            'description': podcastData['description'] ?? podcastData['descriptionPlain'] ?? '',
            'releaseDate': podcastData['releaseDate'] ?? '',
            'genres': podcastData['genres'] ?? [],
            'feedUrl': feedUrl,
            'imageUrl': podcastData['cover'] ?? podcastData['imageUrl'] ?? '',
            'itunesPageUrl': podcastData['pageUrl'] ?? '',
            'itunesId': podcastData['id'],
            'itunesArtistId': podcastData['artistId'],
            'explicit': podcastData['explicit'] ?? false,
            'language': podcastData['language'],
          },
          'autoDownloadEpisodes': autoDownloadEpisodes,
          'autoDownloadSchedule': autoDownloadSchedule ?? '0 0 * * 1',
        },
      };
      final bodyJson = jsonEncode(body);
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/podcasts'),
        body: bodyJson,
        timeout: const Duration(seconds: 30));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('createPodcast error: $e'); }
    return null;
  }

  /// Get a podcast's RSS feed episodes by feed URL
  /// POST /api/podcasts/feed  body: { "rssFeed": "https://..." }
  Future<Map<String, dynamic>?> getPodcastFeed(String rssFeedUrl) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/podcasts/feed'),
        body: jsonEncode({'rssFeed': rssFeedUrl}),
        timeout: const Duration(seconds: 20));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is Map<String, dynamic>) return data;
      }
    } catch (e) { debugPrint('getPodcastFeed error: $e'); }
    return null;
  }

  /// Get podcast episode download queue for a library
  Future<Map<String, dynamic>?> getEpisodeDownloads(String libraryId) async {
    try {
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/libraries/$libraryId/episode-downloads'),
        timeout: const Duration(seconds: 10));
      if (r.statusCode == 200) return jsonDecode(r.body) as Map<String, dynamic>;
    } catch (e) { debugPrint('getEpisodeDownloads error: $e'); }
    return null;
  }

  /// Download specific podcast episodes
  Future<bool> downloadPodcastEpisodes(String libraryItemId, List<Map<String, dynamic>> episodes) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/podcasts/$libraryItemId/download-episodes'),
        body: jsonEncode(episodes),
        timeout: const Duration(seconds: 30),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('downloadPodcastEpisodes error: $e'); }
    return false;
  }

  /// Check for new podcast episodes across all podcasts in a library
  /// Uses per-podcast check since there's no single library-level endpoint
  Future<bool> checkNewEpisodes(String libraryId) async {
    try {
      // First get all podcast items in the library
      final items = await getLibraryItems(libraryId, limit: 100);
      final results = items?['results'] as List? ?? [];
      if (results.isEmpty) return false;

      // Trigger check on each podcast
      int success = 0;
      for (final item in results) {
        final libItem = item is Map ? (item['libraryItem'] ?? item) : item;
        final id = libItem is Map ? libItem['id'] as String? : null;
        if (id == null) continue;
        try {
          final r = await _authGet(
            Uri.parse('$_cleanBaseUrl/api/podcasts/$id/checknew'),
            timeout: const Duration(seconds: 10));
          if (r.statusCode == 200) success++;
        } catch (_) {}
      }
      return success > 0;
    } catch (e) { debugPrint('checkNewEpisodes error: $e'); }
    return false;
  }

  /// Check a single podcast for new episodes from its RSS feed
  /// GET /api/podcasts/:id/checknew?limit=N
  /// Returns the list of new episodes found, or null on failure.
  Future<List<dynamic>?> checkNewPodcastEpisodes(String podcastId, {int? limit}) async {
    try {
      final limitParam = limit != null ? '?limit=$limit' : '';
      final r = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/podcasts/$podcastId/checknew$limitParam'),
      );
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        return (data['episodes'] as List<dynamic>?) ?? [];
      }
    } catch (e) { debugPrint('checkNewPodcastEpisodes error: $e'); }
    return null;
  }

  /// Match a library item with external metadata.
  /// POST /api/items/:id/match
  ///
  /// When the override flags are omitted, the server applies its configured
  /// "Prefer matched metadata" setting.
  Future<Map<String, dynamic>?> matchLibraryItem(
    String itemId, {
    String? title,
    String? author,
    String? provider,
    bool? overrideCover,
    bool? overrideDetails,
  }) async {
    try {
      final body = <String, dynamic>{};
      if (title != null) body['title'] = title;
      if (author != null) body['author'] = author;
      if (provider != null) body['provider'] = provider;
      if (overrideCover != null) body['overrideCover'] = overrideCover;
      if (overrideDetails != null) body['overrideDetails'] = overrideDetails;
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/match'),
        body: jsonEncode(body),
      );
      if (r.statusCode == 200) {
        return jsonDecode(r.body) as Map<String, dynamic>;
      }
    } catch (e) { debugPrint('matchLibraryItem error: $e'); }
    return null;
  }

  /// Update a book's chapters. POST /api/items/:id/chapters
  /// [chapters] is the full ordered list of {id, start, end, title}. Pass an
  /// empty list to clear all chapters. Returns true on a 200 response.
  Future<bool> updateChapters(
      String itemId, List<Map<String, dynamic>> chapters) async {
    try {
      final r = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/chapters'),
        body: jsonEncode({'chapters': chapters}),
        timeout: const Duration(seconds: 20),
      );
      if (r.statusCode != 200) {
        debugPrint('[API] updateChapters failed: ${r.statusCode}');
      } else {
        debugPrint('[API] updateChapters $itemId: ${chapters.length} chapters saved');
      }
      return r.statusCode == 200;
    } catch (e) {
      debugPrint('[API] updateChapters error: $e');
      return false;
    }
  }

  /// Look up chapters for an ASIN. The server proxies this to Audnexus.
  /// GET /api/search/chapters?asin=&region=
  /// Returns the raw result map on 200 (chapters + runtime + brand-intro/outro
  /// durations, or {error, stringKey} when the lookup fails), else null.
  /// [itemId] lets BookOrbit look the chapters up itself; Audiobookshelf
  /// ignores it.
  Future<Map<String, dynamic>?> searchChapters(String asin, String region, {String? itemId}) async {
    try {
      final uri = Uri.parse('$_cleanBaseUrl/api/search/chapters')
          .replace(queryParameters: {'asin': asin, 'region': region, 'id': ?itemId});
      final r = await _authGet(uri, timeout: const Duration(seconds: 20));
      if (r.statusCode == 200) {
        final data = jsonDecode(r.body);
        if (data is Map<String, dynamic>) return data;
      }
      debugPrint('[API] searchChapters failed: ${r.statusCode}');
      return null;
    } catch (e) {
      debugPrint('[API] searchChapters error: $e');
      return null;
    }
  }

  /// Start an embed-metadata task: writes tags/chapters/cover into the audio
  /// files. POST /api/tools/item/:id/embed-metadata?backup=0|1  (admin)
  Future<bool> embedMetadata(String itemId, {bool backup = true}) async {
    try {
      final uri = Uri.parse('$_cleanBaseUrl/api/tools/item/$itemId/embed-metadata')
          .replace(queryParameters: {'backup': backup ? '1' : '0'});
      final r = await _authPost(uri);
      return r.statusCode == 200;
    } catch (e) {
      debugPrint('embedMetadata error: $e');
    }
    return false;
  }

  /// Start an M4B encode task on the server.
  /// POST /api/tools/item/:id/encode-m4b?codec=&bitrate=&channels=
  Future<bool> startM4bEncode(
    String itemId, {
    required String codec,
    required String bitrate,
    required int channels,
  }) async {
    try {
      final uri = Uri.parse('$_cleanBaseUrl/api/tools/item/$itemId/encode-m4b')
          .replace(queryParameters: {
        'codec': codec,
        'bitrate': bitrate,
        'channels': '$channels',
      });
      final r = await _authPost(uri);
      return r.statusCode == 200;
    } catch (e) {
      debugPrint('startM4bEncode error: $e');
    }
    return false;
  }

  /// Update podcast media settings (auto-download, etc.)
  /// PATCH /api/items/:id/media  body: mediaUpdates at the media level
  Future<bool> updatePodcastMedia(String itemId, Map<String, dynamic> mediaUpdates) async {
    try {
      final r = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/media'),
        body: jsonEncode(mediaUpdates),
      );
      return r.statusCode == 200;
    } catch (e) { debugPrint('updatePodcastMedia error: $e'); }
    return false;
  }

  /// Delete a podcast episode
  /// Returns the HTTP status code (0 on exception). 200 = success;
  /// 403 = caller lacks the `delete` permission flag on the server. Callers
  /// should surface 403 with a "needs delete permission" message.
  /// [hard] true also deletes the episode's audio file from the server's disk;
  /// false leaves the file and only drops the episode from the database.
  Future<int> deletePodcastEpisode(String podcastId, String episodeId, {bool hard = false}) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/podcasts/$podcastId/episode/$episodeId?hard=${hard ? 1 : 0}'),
      );
      return r.statusCode;
    } catch (e) { debugPrint('deletePodcastEpisode error: $e'); }
    return 0;
  }

  /// Delete a library item (e.g. remove a podcast show). See [deletePodcastEpisode] for status semantics.
  ///
  /// [hard] true deletes the item's folder from the server's disk as well;
  /// false keeps the files, so a later library scan can pick the item back up.
  Future<int> deleteLibraryItem(String itemId, {bool hard = false}) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId?hard=${hard ? 1 : 0}'),
      );
      return r.statusCode;
    } catch (e) { debugPrint('deleteLibraryItem error: $e'); }
    return 0;
  }

  /// Delete one of an item's files from the server's disk: an audio track,
  /// the ebook or any other file in its folder. See [deletePodcastEpisode]
  /// for status semantics.
  Future<int> deleteLibraryFile(String itemId, String fileId) async {
    try {
      final r = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/items/$itemId/file/${Uri.encodeComponent(fileId)}'),
      );
      return r.statusCode;
    } catch (e) { debugPrint('deleteLibraryFile error: $e'); }
    return 0;
  }

  /// Delete several library items in one server operation.
  /// Returns the HTTP status code so callers can distinguish a missing
  /// `delete` permission (403) from other failures. Zero means no request was
  /// made or the request threw.
  Future<int> deleteLibraryItems(
    List<String> itemIds, {
    bool hard = false,
  }) async {
    if (itemIds.isEmpty) return 0;
    try {
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/batch/delete?hard=${hard ? 1 : 0}'),
        body: jsonEncode({'libraryItemIds': itemIds}),
        timeout: const Duration(seconds: 60),
      );
      return response.statusCode;
    } catch (e) {
      debugPrint('deleteLibraryItems error: $e');
      return 0;
    }
  }

  /// Quick-match several items using Audiobookshelf's native batch endpoint.
  Future<bool> quickMatchLibraryItems(
    List<String> itemIds, {
    required String provider,
    bool overrideCover = false,
    bool overrideDetails = false,
  }) async {
    if (itemIds.isEmpty) return false;
    try {
      final response = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/items/batch/quickmatch'),
        body: jsonEncode({
          'options': {
            'provider': provider,
            'overrideCover': overrideCover,
            'overrideDetails': overrideDetails,
          },
          'libraryItemIds': itemIds,
        }),
        timeout: const Duration(seconds: 60),
      );
      return response.statusCode == 200;
    } catch (e) {
      debugPrint('quickMatchLibraryItems error: $e');
      return false;
    }
  }

  /// Mark several library items finished or unfinished in one request.
  Future<bool> updateLibraryItemsFinished(
    List<String> itemIds, {
    required bool isFinished,
  }) async {
    if (itemIds.isEmpty) return false;
    try {
      final response = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/me/progress/batch/update'),
        body: jsonEncode([
          for (final itemId in itemIds)
            {'libraryItemId': itemId, 'isFinished': isFinished},
        ]),
      );
      return response.statusCode == 200;
    } catch (e) {
      debugPrint('updateLibraryItemsFinished error: $e');
      return false;
    }
  }

  // ── Playlists ──────────────────────────────────────────────────────────

  /// GET /api/libraries/:libraryId/playlists
  /// Null means the request failed - see [getLibraryCollections].
  Future<List<dynamic>?> getLibraryPlaylists(String libraryId) =>
      _getAllPaged('/api/libraries/$libraryId/playlists');

  /// Fetch a paged results endpoint to completion. Collections and playlists
  /// come back with every book expanded, so a server with a hundred-plus of
  /// them produces a single response big enough to time out or choke the
  /// decoder (#362) - pages keep each response bounded. Null on any failure
  /// rather than a partial list: partial would read as collections silently
  /// missing instead of a load that failed.
  Future<List<dynamic>?> _getAllPaged(String path, {int pageSize = 25}) async {
    try {
      final out = <dynamic>[];
      for (var page = 0; page < 80; page++) {
        final resp = await _authGet(
          Uri.parse('$_cleanBaseUrl$path?limit=$pageSize&page=$page'),
          timeout: const Duration(seconds: 30),
        );
        if (resp.statusCode != 200) {
          debugPrint('[API] $path failed: HTTP ${resp.statusCode} (page $page)');
          return null;
        }
        final data = jsonDecode(resp.body);
        final results = (data['results'] as List<dynamic>?) ?? [];
        out.addAll(results);
        // Servers that ignore limit/page return everything with total equal
        // to the result count, so this exits after one round trip there.
        final total = (data['total'] as num?)?.toInt() ?? out.length;
        if (results.isEmpty || out.length >= total) return out;
      }
      return out;
    } catch (e) {
      debugPrint('[API] $path error: $e');
      return null;
    }
  }

  /// GET /api/playlists/:id
  Future<Map<String, dynamic>?> getPlaylist(String playlistId) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/playlists/$playlistId'),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// POST /api/playlists
  Future<Map<String, dynamic>?> createPlaylist(
    String libraryId,
    String name, {
    List<Map<String, dynamic>> items = const [],
  }) async {
    try {
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/playlists'),
        body: jsonEncode({
          'libraryId': libraryId,
          'name': name,
          'items': items,
        }),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// PATCH /api/playlists/:id
  Future<Map<String, dynamic>?> updatePlaylist(
    String playlistId, {
    String? name,
    List<Map<String, dynamic>>? items,
  }) async {
    try {
      final body = <String, dynamic>{};
      if (name != null) body['name'] = name;
      if (items != null) body['items'] = items;
      final resp = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/playlists/$playlistId'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// DELETE /api/playlists/:id
  Future<bool> deletePlaylist(String playlistId) async {
    try {
      final resp = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/playlists/$playlistId'),
        timeout: const Duration(seconds: 10));
      return resp.statusCode == 200;
    } catch (_) {}
    return false;
  }

  /// POST /api/playlists/:id/item
  Future<Map<String, dynamic>?> addItemToPlaylist(
    String playlistId,
    String libraryItemId, {
    String? episodeId,
  }) async {
    try {
      final body = <String, dynamic>{'libraryItemId': libraryItemId};
      if (episodeId != null) body['episodeId'] = episodeId;
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/playlists/$playlistId/item'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// DELETE /api/playlists/:id/item/:libraryItemId/:episodeId
  Future<Map<String, dynamic>?> removeItemFromPlaylist(
    String playlistId,
    String libraryItemId, {
    String? episodeId,
  }) async {
    try {
      var path = '$_cleanBaseUrl/api/playlists/$playlistId/item/$libraryItemId';
      if (episodeId != null) path += '/$episodeId';
      final resp = await _authDelete(
        Uri.parse(path),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  // ── Collections ────────────────────────────────────────────────────────

  /// GET /api/libraries/:libraryId/collections
  /// Null means the request failed, which is not the same as a library with no
  /// collections - the Lists tab tells the user which of the two happened.
  Future<List<dynamic>?> getLibraryCollections(String libraryId) =>
      _getAllPaged('/api/libraries/$libraryId/collections');

  /// GET /api/collections/:id
  Future<Map<String, dynamic>?> getCollection(String collectionId) async {
    try {
      final resp = await _authGet(
        Uri.parse('$_cleanBaseUrl/api/collections/$collectionId'),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// POST /api/collections
  Future<Map<String, dynamic>?> createCollection(
    String libraryId,
    String name, {
    String? description,
    List<String> books = const [],
  }) async {
    try {
      final body = <String, dynamic>{
        'libraryId': libraryId,
        'name': name,
        'books': books,
      };
      if (description != null) body['description'] = description;
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/collections'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// PATCH /api/collections/:id
  Future<Map<String, dynamic>?> updateCollection(
    String collectionId, {
    String? name,
    String? description,
    List<String>? books,
  }) async {
    try {
      final body = <String, dynamic>{};
      if (name != null) body['name'] = name;
      if (description != null) body['description'] = description;
      if (books != null) body['books'] = books;
      final resp = await _authPatch(
        Uri.parse('$_cleanBaseUrl/api/collections/$collectionId'),
        body: jsonEncode(body),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// DELETE /api/collections/:id. Returns the HTTP status code
  /// (0 on exception). 200 = success; 403 = caller lacks the `delete`
  /// permission flag on the server.
  Future<int> deleteCollection(String collectionId) async {
    try {
      final resp = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/collections/$collectionId'),
        timeout: const Duration(seconds: 10));
      return resp.statusCode;
    } catch (_) {}
    return 0;
  }

  /// POST /api/collections/:id/books
  Future<Map<String, dynamic>?> addBookToCollection(
    String collectionId,
    String libraryItemId,
  ) async {
    try {
      final resp = await _authPost(
        Uri.parse('$_cleanBaseUrl/api/collections/$collectionId/book'),
        body: jsonEncode({'id': libraryItemId}),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }

  /// DELETE /api/collections/:id/books/:libraryItemId
  Future<Map<String, dynamic>?> removeBookFromCollection(
    String collectionId,
    String libraryItemId,
  ) async {
    try {
      final resp = await _authDelete(
        Uri.parse('$_cleanBaseUrl/api/collections/$collectionId/book/$libraryItemId'),
        timeout: const Duration(seconds: 10));
      if (resp.statusCode == 200) {
        return jsonDecode(resp.body) as Map<String, dynamic>;
      }
    } catch (_) {}
    return null;
  }
}