A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:http/http.dart' as http;
import '../l10n/app_localizations.dart';
/// HTTP client for the ReadMeABook (RMAB) native API.
///
/// Covers the user-scoped allowlisted endpoints: me, search, listRequests,
/// getRequest, createRequest. Admin-only endpoints (metrics / active downloads
/// / recent requests) will land in a follow-up.
///
/// See: documentation/backend/services/api-tokens.md in the RMAB repo.
class RmabService {
RmabService({
required String baseUrl,
required this.apiToken,
this.customHeaders = const {},
}) : baseUrl = _trimTrailingSlash(baseUrl);
/// Bare RMAB server URL with no trailing slash (e.g. https://rmab.example.com).
final String baseUrl;
/// `rmab_…` bearer token issued by the RMAB server.
final String apiToken;
/// Extra headers sent on every request, for auth proxies in front of RMAB
/// (Cloudflare Access service tokens, Authelia bypass headers, etc.).
final Map<String, String> customHeaders;
static String _trimTrailingSlash(String s) =>
s.endsWith('/') ? s.substring(0, s.length - 1) : s;
Map<String, String> get _headers => {
...customHeaders,
'Authorization': 'Bearer $apiToken',
'Content-Type': 'application/json',
'Accept': 'application/json',
};
// ─── /api/auth/me ───────────────────────────────────────────────
/// GET /api/auth/me — verifies the token and returns the connected user.
Future<RmabMe> me() async {
final uri = Uri.parse('$baseUrl/api/auth/me');
final res = await _get(uri, label: 'me');
final result = _decode(res, (json) {
final user = json['user'];
if (user is! Map<String, dynamic>) {
throw const FormatException('Response missing "user" object');
}
return RmabMe.fromJson(user);
}, label: 'me');
debugPrint(
'[RMAB] me() ok username=${result.username} role=${result.role}');
return result;
}
// ─── /api/audiobooks/search ─────────────────────────────────────
/// GET /api/audiobooks/search?q=…&page=… — search Audible via RMAB.
///
/// Results are per-user enriched (isRequested, requestStatus, isAvailable,
/// isIgnored, hasReportedIssue) when called with a valid `rmab_` token.
Future<RmabSearchResponse> search(String query, {int page = 1}) async {
debugPrint('[RMAB] search(query="$query", page=$page)');
final uri = Uri.parse('$baseUrl/api/audiobooks/search').replace(
queryParameters: {'q': query, 'page': '$page'},
);
final res = await _get(uri, label: 'search');
final out = _decode(res, (json) {
final list = (json['results'] as List<dynamic>? ?? [])
.whereType<Map<String, dynamic>>()
.map(RmabSearchResult.fromJson)
.toList();
return RmabSearchResponse(
query: (json['query'] as String?) ?? query,
results: list,
page: _asInt(json['page']) ?? page,
hasMore: (json['hasMore'] as bool?) ?? false,
);
}, label: 'search');
final requestedCount = out.results.where((r) => r.isRequested).length;
final availableCount = out.results.where((r) => r.isAvailable).length;
debugPrint('[RMAB] search() -> ${out.results.length} results '
'(${out.hasMore ? 'hasMore' : 'last page'}, '
'requested=$requestedCount available=$availableCount)');
return out;
}
// ─── /api/requests ──────────────────────────────────────────────
/// GET /api/requests — paginated list of the user's requests.
Future<RmabRequestsPage> listRequests({
RmabStatusGroup? statusGroup,
String? cursor,
int take = 20,
bool myOnly = true,
String type = 'audiobook',
}) async {
debugPrint(
'[RMAB] listRequests(statusGroup=${statusGroup?.name ?? 'all'}, '
'cursor=${cursor ?? '-'}, take=$take, myOnly=$myOnly, type=$type)');
final qp = <String, String>{
'take': '$take',
if (statusGroup != null) 'status': statusGroup.name,
if (cursor != null) 'cursor': cursor,
if (myOnly) 'myOnly': 'true',
'type': type,
};
final uri =
Uri.parse('$baseUrl/api/requests').replace(queryParameters: qp);
final res = await _get(uri, label: 'listRequests');
final out = _decode(res, (json) {
final requests = (json['requests'] as List<dynamic>? ?? [])
.whereType<Map<String, dynamic>>()
.map(RmabRequest.fromJson)
.toList();
final countsJson = (json['counts'] as Map<String, dynamic>?) ?? const {};
return RmabRequestsPage(
requests: requests,
nextCursor: json['nextCursor'] as String?,
counts: RmabRequestCounts(
all: _asInt(countsJson['all']) ?? requests.length,
active: _asInt(countsJson['active']) ?? 0,
waiting: _asInt(countsJson['waiting']) ?? 0,
completed: _asInt(countsJson['completed']) ?? 0,
failed: _asInt(countsJson['failed']) ?? 0,
cancelled: _asInt(countsJson['cancelled']) ?? 0,
),
);
}, label: 'listRequests');
debugPrint('[RMAB] listRequests() -> ${out.requests.length} '
'(counts: all=${out.counts.all} active=${out.counts.active} '
'waiting=${out.counts.waiting} completed=${out.counts.completed} '
'failed=${out.counts.failed} cancelled=${out.counts.cancelled})');
return out;
}
/// GET /api/requests/:id — full detail for a single request.
Future<RmabRequest> getRequest(String id) async {
debugPrint('[RMAB] getRequest(id=$id)');
final uri = Uri.parse('$baseUrl/api/requests/$id');
final res = await _get(uri, label: 'getRequest');
final out = _decode(res, (json) {
final req = json['request'];
if (req is! Map<String, dynamic>) {
throw const FormatException('Response missing "request"');
}
return RmabRequest.fromJson(req);
}, label: 'getRequest');
debugPrint('[RMAB] getRequest() -> status=${out.status} '
'progress=${out.progress}%');
return out;
}
/// POST /api/requests — create a request. Returns a typed success or named
/// error. Throws [RmabException] only for transport / auth / 5xx failures.
Future<RmabCreateResult> createRequest(RmabRequestInput input) async {
debugPrint('[RMAB] createRequest(asin=${input.asin} '
'title="${input.title}" author="${input.author}")');
final uri = Uri.parse('$baseUrl/api/requests');
final http.Response res;
try {
res = await http
.post(
uri,
headers: _headers,
body: jsonEncode({'audiobook': input.toJson()}),
)
.timeout(const Duration(seconds: 15));
debugPrint('[RMAB] createRequest <- ${res.statusCode} '
'(${res.body.length} bytes, '
'content-type: ${res.headers['content-type']})');
} on TimeoutException {
throw RmabException(RmabErrorKind.network, 'Request timed out');
} on SocketException catch (e) {
throw RmabException(RmabErrorKind.network, e.message);
} on http.ClientException catch (e) {
throw RmabException(RmabErrorKind.network, e.message);
} catch (e) {
throw RmabException(RmabErrorKind.network, e.toString());
}
if (res.statusCode == 401) {
throw RmabException(RmabErrorKind.unauthorized,
_safeServerMessage(res) ?? 'Unauthorized');
}
if (res.statusCode == 403) {
throw RmabException(RmabErrorKind.forbidden,
_safeServerMessage(res) ?? 'Forbidden');
}
if (res.statusCode == 201) {
try {
final body = jsonDecode(res.body) as Map<String, dynamic>;
final reqJson = body['request'];
if (reqJson is! Map<String, dynamic>) {
throw const FormatException('Response missing "request"');
}
final created = RmabRequest.fromJson(reqJson);
debugPrint('[RMAB] createRequest ok '
'requestId=${created.id} status=${created.status}');
return RmabCreateSuccess(created);
} catch (e) {
debugPrint('[RMAB] createRequest parse error: $e');
throw RmabException(
RmabErrorKind.parse, 'Unexpected response from server');
}
}
// Named errors — server returns 4xx / 5xx with { error, message }
try {
final body = jsonDecode(res.body) as Map<String, dynamic>;
final errorName = (body['error'] as String?) ?? '';
final message = (body['message'] as String?) ?? '';
final kind = _mapCreateError(errorName);
debugPrint(
'[RMAB] createRequest named error: $errorName -> ${kind.name} '
'("$message")');
return RmabCreateNamedError(kind, message);
} catch (_) {
throw RmabException(RmabErrorKind.server,
'Server returned HTTP ${res.statusCode}');
}
}
RmabCreateErrorKind _mapCreateError(String name) {
switch (name) {
case 'AlreadyAvailable':
return RmabCreateErrorKind.alreadyAvailable;
case 'BeingProcessed':
return RmabCreateErrorKind.beingProcessed;
case 'DuplicateRequest':
return RmabCreateErrorKind.duplicateRequest;
case 'Ignored':
return RmabCreateErrorKind.ignored;
case 'UserNotFound':
return RmabCreateErrorKind.userNotFound;
case 'ValidationError':
return RmabCreateErrorKind.validationError;
default:
return RmabCreateErrorKind.requestError;
}
}
// ─── Shared helpers ─────────────────────────────────────────────
Future<http.Response> _get(Uri uri, {required String label}) async {
debugPrint('[RMAB] $label GET $uri');
final http.Response res;
try {
res = await http
.get(uri, headers: _headers)
.timeout(const Duration(seconds: 15));
debugPrint('[RMAB] $label <- ${res.statusCode} '
'(${res.body.length} bytes, '
'content-type: ${res.headers['content-type']})');
} on TimeoutException {
debugPrint('[RMAB] $label network: timeout');
throw RmabException(RmabErrorKind.network, 'Request timed out');
} on SocketException catch (e) {
debugPrint('[RMAB] $label network: socket ${e.message}');
throw RmabException(RmabErrorKind.network, e.message);
} on http.ClientException catch (e) {
debugPrint('[RMAB] $label network: client ${e.message}');
throw RmabException(RmabErrorKind.network, e.message);
} catch (e) {
debugPrint('[RMAB] $label network: $e');
throw RmabException(RmabErrorKind.network, e.toString());
}
if (res.statusCode == 401) {
throw RmabException(RmabErrorKind.unauthorized,
_safeServerMessage(res) ?? 'Unauthorized');
}
if (res.statusCode == 403) {
throw RmabException(RmabErrorKind.forbidden,
_safeServerMessage(res) ?? 'Forbidden');
}
if (res.statusCode < 200 || res.statusCode >= 300) {
throw RmabException(
RmabErrorKind.server,
_safeServerMessage(res) ??
'Server returned HTTP ${res.statusCode}');
}
return res;
}
/// Wrap a JSON decode in [RmabException]-aware error handling so callers
/// don't have to repeat the try/catch.
T _decode<T>(http.Response res, T Function(Map<String, dynamic>) builder,
{required String label}) {
try {
final body = jsonDecode(res.body) as Map<String, dynamic>;
return builder(body);
} catch (e) {
debugPrint('[RMAB] $label() parse error: $e');
throw RmabException(
RmabErrorKind.parse, 'Unexpected response from server');
}
}
String? _safeServerMessage(http.Response res) {
try {
final body = jsonDecode(res.body);
if (body is Map<String, dynamic>) {
final msg = body['message'] ?? body['error'];
if (msg is String && msg.isNotEmpty) return msg;
}
} catch (_) {}
return null;
}
}
// ─── Error model ──────────────────────────────────────────────────
enum RmabErrorKind {
/// Connection refused, DNS failure, timeout, TLS error, etc.
network,
/// HTTP 401 — token rejected.
unauthorized,
/// HTTP 403 — token valid but not allowed (e.g. user-scoped token hitting
/// an admin endpoint).
forbidden,
/// HTTP 4xx / 5xx that isn't 401/403.
server,
/// Response was 2xx but the body didn't match the expected shape.
parse,
}
class RmabException implements Exception {
RmabException(this.kind, this.message);
final RmabErrorKind kind;
final String message;
/// User-facing message for this error. [genericPrefix] labels the
/// fallback case (e.g. request vs search wording).
String localizedMessage(AppLocalizations l, String genericPrefix) {
switch (kind) {
case RmabErrorKind.unauthorized:
return l.rmabRequestErrorTokenRejected;
case RmabErrorKind.network:
return l.rmabConfigErrorNetwork;
default:
return '$genericPrefix: $message';
}
}
@override
String toString() => 'RmabException($kind): $message';
}
// ─── /api/auth/me models ──────────────────────────────────────────
class RmabMe {
RmabMe({
required this.id,
required this.username,
required this.role,
required this.isLocalAdmin,
});
final String id;
final String username;
final String role; // 'user' | 'admin'
final bool isLocalAdmin;
bool get isAdmin => role == 'admin';
factory RmabMe.fromJson(Map<String, dynamic> json) => RmabMe(
id: (json['id'] ?? '') as String,
username: (json['username'] ?? '') as String,
role: (json['role'] ?? 'user') as String,
isLocalAdmin: (json['isLocalAdmin'] ?? false) as bool,
);
}
// ─── /api/audiobooks/search models ────────────────────────────────
class RmabSearchResponse {
RmabSearchResponse({
required this.query,
required this.results,
required this.page,
required this.hasMore,
});
final String query;
final List<RmabSearchResult> results;
final int page;
final bool hasMore;
}
class RmabSearchResult {
RmabSearchResult({
required this.asin,
required this.title,
required this.author,
this.narrator,
this.description,
this.coverArtUrl,
this.durationMinutes,
this.releaseDate,
this.rating,
this.series,
this.seriesPart,
this.language,
this.publisherName,
this.isAvailable = false,
this.isRequested = false,
this.requestStatus,
this.requestId,
this.isIgnored = false,
this.hasReportedIssue = false,
});
final String asin;
final String title;
final String author;
final String? narrator;
final String? description;
final String? coverArtUrl;
final int? durationMinutes;
final String? releaseDate;
final double? rating;
final String? series;
final String? seriesPart;
final String? language;
final String? publisherName;
/// Per-user enrichment (set by RMAB when called with a valid token).
final bool isAvailable;
final bool isRequested;
final String? requestStatus;
final String? requestId;
final bool isIgnored;
final bool hasReportedIssue;
/// Year extracted from [releaseDate] (best-effort parse, null on failure).
int? get releaseYear {
final raw = releaseDate;
if (raw == null || raw.isEmpty) return null;
final dt = DateTime.tryParse(raw);
return dt?.year;
}
factory RmabSearchResult.fromJson(Map<String, dynamic> json) =>
RmabSearchResult(
asin: (json['asin'] ?? '') as String,
title: (json['title'] ?? '') as String,
author: (json['author'] ?? '') as String,
narrator: json['narrator'] as String?,
description: json['description'] as String?,
coverArtUrl: json['coverArtUrl'] as String?,
durationMinutes: _asInt(json['durationMinutes']),
releaseDate: json['releaseDate'] as String?,
rating: _asDouble(json['rating']),
series: json['series'] as String?,
seriesPart: json['seriesPart'] as String?,
language: json['language'] as String?,
publisherName: json['publisherName'] as String?,
isAvailable: (json['isAvailable'] as bool?) ?? false,
isRequested: (json['isRequested'] as bool?) ?? false,
requestStatus: json['requestStatus'] as String?,
requestId: json['requestId'] as String?,
isIgnored: (json['isIgnored'] as bool?) ?? false,
hasReportedIssue: (json['hasReportedIssue'] as bool?) ?? false,
);
/// Bridge a book map from the Absorb upcoming-releases service into a
/// [RmabSearchResult] we can hand to the detail sheet. The upcoming-side
/// map uses different field names (authors/narrators as lists, coverUrl,
/// publisherSummary) so do the translation here in one place.
factory RmabSearchResult.fromUpcomingBookMap(Map<String, dynamic> m) {
String joinList(dynamic v) {
if (v is List) {
return v
.map((e) {
if (e is String) return e;
if (e is Map && e['name'] is String) return e['name'] as String;
return '';
})
.where((s) => s.isNotEmpty)
.join(', ');
}
if (v is String) return v;
return '';
}
return RmabSearchResult(
asin: (m['asin'] ?? '') as String,
title: (m['title'] ?? '') as String,
author: joinList(m['authors'] ?? m['author']),
narrator: () {
final s = joinList(m['narrators'] ?? m['narrator']);
return s.isEmpty ? null : s;
}(),
description: (m['publisherSummary'] ?? m['description']) as String?,
coverArtUrl: (m['coverUrl'] ?? m['coverArtUrl']) as String?,
durationMinutes: _asInt(m['runtimeMinutes'] ?? m['durationMinutes']),
releaseDate: m['releaseDate'] as String?,
rating: _asDouble(m['rating']),
series: m['series'] as String?,
seriesPart: (m['sequence'] ?? m['seriesPart']) as String?,
);
}
}
// ─── /api/requests models ─────────────────────────────────────────
class RmabRequest {
RmabRequest({
required this.id,
required this.status,
required this.progress,
required this.createdAt,
required this.updatedAt,
required this.audiobook,
this.completedAt,
this.errorMessage,
this.type = 'audiobook',
this.downloadAvailable = false,
});
final String id;
final String status;
final int progress;
final DateTime createdAt;
final DateTime updatedAt;
final DateTime? completedAt;
final String? errorMessage;
final String type;
final bool downloadAvailable;
final RmabAudiobookSummary audiobook;
RmabStatusGroup? get statusGroup => status.rmabGroup;
factory RmabRequest.fromJson(Map<String, dynamic> json) {
final book = json['audiobook'] as Map<String, dynamic>?;
return RmabRequest(
id: (json['id'] ?? '') as String,
status: (json['status'] ?? '') as String,
progress: _asInt(json['progress']) ?? 0,
createdAt: _asDate(json['createdAt']) ?? DateTime.now(),
updatedAt: _asDate(json['updatedAt']) ?? DateTime.now(),
completedAt: _asDate(json['completedAt']),
errorMessage: json['errorMessage'] as String?,
type: (json['type'] ?? 'audiobook') as String,
downloadAvailable: (json['downloadAvailable'] as bool?) ?? false,
audiobook: book != null
? RmabAudiobookSummary.fromJson(book)
: RmabAudiobookSummary.empty(),
);
}
}
class RmabAudiobookSummary {
RmabAudiobookSummary({
required this.id,
required this.title,
required this.author,
this.audibleAsin,
this.narrator,
this.coverArtUrl,
this.series,
this.seriesPart,
this.year,
});
final String id;
final String title;
final String author;
final String? audibleAsin;
final String? narrator;
final String? coverArtUrl;
final String? series;
final String? seriesPart;
final int? year;
factory RmabAudiobookSummary.empty() =>
RmabAudiobookSummary(id: '', title: '', author: '');
factory RmabAudiobookSummary.fromJson(Map<String, dynamic> json) =>
RmabAudiobookSummary(
id: (json['id'] ?? '') as String,
title: (json['title'] ?? '') as String,
author: (json['author'] ?? '') as String,
audibleAsin: json['audibleAsin'] as String?,
narrator: json['narrator'] as String?,
coverArtUrl: json['coverArtUrl'] as String?,
series: json['series'] as String?,
seriesPart: json['seriesPart'] as String?,
year: _asInt(json['year']),
);
}
class RmabRequestsPage {
RmabRequestsPage({
required this.requests,
required this.counts,
this.nextCursor,
});
final List<RmabRequest> requests;
final String? nextCursor;
final RmabRequestCounts counts;
}
class RmabRequestCounts {
const RmabRequestCounts({
required this.all,
required this.active,
required this.waiting,
required this.completed,
required this.failed,
required this.cancelled,
});
final int all;
final int active;
final int waiting;
final int completed;
final int failed;
final int cancelled;
}
// ─── createRequest models ─────────────────────────────────────────
class RmabRequestInput {
RmabRequestInput({
required this.asin,
required this.title,
required this.author,
this.narrator,
this.description,
this.coverArtUrl,
this.durationMinutes,
this.releaseDate,
this.rating,
});
final String asin;
final String title;
final String author;
final String? narrator;
final String? description;
final String? coverArtUrl;
final int? durationMinutes;
final String? releaseDate;
final double? rating;
Map<String, dynamic> toJson() => {
'asin': asin,
'title': title,
'author': author,
if (narrator != null) 'narrator': narrator,
if (description != null) 'description': description,
if (coverArtUrl != null) 'coverArtUrl': coverArtUrl,
if (durationMinutes != null) 'durationMinutes': durationMinutes,
if (releaseDate != null) 'releaseDate': releaseDate,
if (rating != null) 'rating': rating,
};
factory RmabRequestInput.fromSearchResult(RmabSearchResult r) =>
RmabRequestInput(
asin: r.asin,
title: r.title,
author: r.author,
narrator: r.narrator,
description: r.description,
coverArtUrl: r.coverArtUrl,
durationMinutes: r.durationMinutes,
releaseDate: r.releaseDate,
rating: r.rating,
);
}
sealed class RmabCreateResult {
const RmabCreateResult();
}
class RmabCreateSuccess extends RmabCreateResult {
const RmabCreateSuccess(this.request);
final RmabRequest request;
}
class RmabCreateNamedError extends RmabCreateResult {
const RmabCreateNamedError(this.kind, this.message);
final RmabCreateErrorKind kind;
final String message;
}
enum RmabCreateErrorKind {
alreadyAvailable,
beingProcessed,
duplicateRequest,
/// `bypassIgnore: true` is hardcoded for token requests so this shouldn't
/// fire, but model it for completeness.
ignored,
userNotFound,
validationError,
requestError,
}
// ─── Local in-memory request cache ────────────────────────────────
/// In-memory bridge between "I just submitted a request" and "the server's
/// next enrichment will reflect it."
///
/// Without this, dismissing and reopening the detail sheet for a freshly
/// requested book would reset the UI to the unrequested state (because the
/// `RmabSearchResult` we were handed by the parent still has
/// `isRequested: false` from the last search).
///
/// All RMAB widgets consult this on render. The cache only adds requested
/// state — it never claims a book ISN'T requested. So a stale "Already
/// requested" badge is the worst case (better UX than showing a Request
/// button that would just 409 with `DuplicateRequest`).
///
/// In-memory only. Cleared on app restart and on disconnect.
class RmabLocalRequestCache {
RmabLocalRequestCache._();
static final Map<String, String> _statusByAsin = {};
/// The locally-cached status for [asin], or null if we haven't recorded
/// a fresh request for it during this app session.
static String? statusFor(String asin) => _statusByAsin[asin];
/// Record a freshly-created request. [status] should be the server's
/// returned status string (e.g. `pending`, `searching`).
static void markRequested(String asin, String status) {
if (asin.isEmpty) return;
_statusByAsin[asin] = status;
}
/// Clear every cached entry. Called on disconnect.
static void clear() {
_statusByAsin.clear();
}
}
// ─── Status taxonomy ──────────────────────────────────────────────
/// The five status buckets the server groups by in `STATUS_GROUPS`
/// (src/app/api/requests/route.ts).
enum RmabStatusGroup { active, waiting, completed, failed, cancelled }
extension RmabStatusGroupOf on String {
/// Map a raw status string to its visual group. Returns null for `warn`
/// or any unknown status (callers should treat null as "unknown" rather
/// than miscategorising).
RmabStatusGroup? get rmabGroup {
switch (this) {
case 'pending':
case 'searching':
case 'downloading':
case 'processing':
return RmabStatusGroup.active;
case 'awaiting_search':
case 'awaiting_import':
case 'awaiting_approval':
case 'awaiting_release':
return RmabStatusGroup.waiting;
case 'available':
case 'downloaded':
return RmabStatusGroup.completed;
case 'failed':
return RmabStatusGroup.failed;
case 'cancelled':
case 'denied':
return RmabStatusGroup.cancelled;
default:
return null;
}
}
}
// ─── tiny coercion helpers ────────────────────────────────────────
int? _asInt(dynamic v) {
if (v == null) return null;
if (v is int) return v;
if (v is num) return v.toInt();
if (v is String) return int.tryParse(v);
return null;
}
double? _asDouble(dynamic v) {
if (v == null) return null;
if (v is double) return v;
if (v is num) return v.toDouble();
if (v is String) return double.tryParse(v);
return null;
}
DateTime? _asDate(dynamic v) {
if (v == null) return null;
if (v is DateTime) return v;
if (v is String && v.isNotEmpty) return DateTime.tryParse(v);
return null;
}