Complete refactor to clean up project

lib/core/models/change.dart

@@ -0,0 +1,96 @@
+import 'dart:collection';
+
+import 'sheet.dart';
+
+/// Types of changes that can be queued for server synchronization.
+enum ChangeType {
+  sheetNameChange,
+  composerNameChange,
+  addTagChange,
+  removeTagChange,
+}
+
+/// Represents a single pending change to be synced with the server.
+///
+/// Changes are stored locally when offline and applied once
+/// the device regains connectivity.
+class Change {
+  final ChangeType type;
+  final String sheetUuid;
+  final String value;
+
+  Change({
+    required this.type,
+    required this.sheetUuid,
+    required this.value,
+  });
+
+  /// Serializes this change to a map for storage.
+  Map<String, dynamic> toMap() => {
+        'type': type.index,
+        'sheetUuid': sheetUuid,
+        'value': value,
+      };
+
+  /// Deserializes a change from a stored map.
+  ///
+  /// Note: Adding new [ChangeType] values may cause issues with
+  /// previously stored changes that use index-based serialization.
+  factory Change.fromMap(Map<dynamic, dynamic> map) {
+    return Change(
+      type: ChangeType.values[map['type']],
+      sheetUuid: map['sheetUuid'],
+      value: map['value'],
+    );
+  }
+}
+
+/// A queue of pending changes to be synchronized with the server.
+///
+/// Changes are stored in FIFO order (oldest first) and applied
+/// to sheets in sequence when syncing.
+class ChangeQueue {
+  final Queue<Change> _queue = Queue();
+
+  ChangeQueue();
+
+  /// Adds a change to the end of the queue.
+  void addChange(Change change) {
+    _queue.addLast(change);
+  }
+
+  /// Returns the number of pending changes.
+  int get length => _queue.length;
+
+  /// Whether the queue has any pending changes.
+  bool get isEmpty => _queue.isEmpty;
+
+  /// Whether the queue has pending changes.
+  bool get isNotEmpty => _queue.isNotEmpty;
+
+  /// Applies all queued changes to the provided list of sheets.
+  ///
+  /// Each change modifies the corresponding sheet's properties
+  /// based on the change type.
+  void applyToSheets(List<Sheet> sheets) {
+    for (final change in _queue) {
+      final sheet = sheets.firstWhere(
+        (s) => s.uuid == change.sheetUuid,
+        orElse: () => throw StateError(
+          'Sheet with UUID ${change.sheetUuid} not found',
+        ),
+      );
+
+      switch (change.type) {
+        case ChangeType.sheetNameChange:
+          sheet.name = change.value;
+        case ChangeType.composerNameChange:
+          sheet.composerName = change.value;
+        case ChangeType.addTagChange:
+          throw UnimplementedError('Tag support not yet implemented');
+        case ChangeType.removeTagChange:
+          throw UnimplementedError('Tag support not yet implemented');
+      }
+    }
+  }
+}

lib/core/models/config.dart

@@ -0,0 +1,37 @@
+/// Application configuration model.
+///
+/// Stores user preferences that are persisted across sessions,
+/// such as display mode and fullscreen settings.
+class Config {
+  /// Storage keys for persistence
+  static const String keyTwoPageMode = 'twoPageMode';
+  static const String keyFullscreen = 'fullscreen';
+
+  /// Whether to display two pages side-by-side (for tablets/landscape).
+  bool twoPageMode;
+
+  /// Whether the app is in fullscreen mode.
+  bool fullscreen;
+
+  Config({
+    required this.twoPageMode,
+    required this.fullscreen,
+  });
+
+  /// Creates a default configuration with all options disabled.
+  factory Config.defaultConfig() => Config(
+        twoPageMode: false,
+        fullscreen: false,
+      );
+
+  /// Creates a copy of this config with optional overrides.
+  Config copyWith({
+    bool? twoPageMode,
+    bool? fullscreen,
+  }) {
+    return Config(
+      twoPageMode: twoPageMode ?? this.twoPageMode,
+      fullscreen: fullscreen ?? this.fullscreen,
+    );
+  }
+}

lib/core/models/sheet.dart

@@ -0,0 +1,40 @@
+/// Data model representing a sheet music document.
+///
+/// A [Sheet] contains metadata about a piece of sheet music,
+/// including its title, composer information, and timestamps.
+class Sheet {
+  final String uuid;
+  String name;
+  String composerUuid;
+  String composerName;
+  DateTime updatedAt;
+
+  Sheet({
+    required this.uuid,
+    required this.name,
+    required this.composerUuid,
+    required this.composerName,
+    required this.updatedAt,
+  });
+
+  /// Creates a [Sheet] from a JSON map returned by the API.
+  factory Sheet.fromJson(Map<String, dynamic> json) {
+    final composer = json['composer'] as Map<String, dynamic>?;
+    return Sheet(
+      uuid: json['uuid'].toString(),
+      name: json['title'],
+      composerUuid: json['composer_uuid']?.toString() ?? '',
+      composerName: composer?['name'] ?? 'Unknown',
+      updatedAt: DateTime.parse(json['updated_at']),
+    );
+  }
+
+  /// Converts this sheet to a JSON map for API requests.
+  Map<String, dynamic> toJson() => {
+        'uuid': uuid,
+        'title': name,
+        'composer_uuid': composerUuid,
+        'composer_name': composerName,
+        'updated_at': updatedAt.toIso8601String(),
+      };
+}

lib/core/services/api_client.dart

@@ -0,0 +1,202 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter/foundation.dart';
+import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart';
+import 'package:path_provider/path_provider.dart';
+
+import '../models/sheet.dart';
+
+/// HTTP client for communicating with the Sheetless API server.
+///
+/// Handles authentication, sheet listing, and PDF downloads.
+/// Provides caching for PDF files on native platforms.
+class ApiClient {
+  final _log = Logger('ApiClient');
+  final String baseUrl;
+  String? token;
+
+  ApiClient({required this.baseUrl, this.token});
+
+  /// Whether the client has an authentication token set.
+  bool get isAuthenticated => token != null;
+
+  // ---------------------------------------------------------------------------
+  // Authentication
+  // ---------------------------------------------------------------------------
+
+  /// Authenticates with the server and stores the JWT token.
+  ///
+  /// Throws an [Exception] if login fails.
+  Future<void> login(String username, String password) async {
+    _log.info('Logging in...');
+    final url = Uri.parse('$baseUrl/auth/login');
+
+    final response = await http.post(
+      url,
+      headers: {'Content-Type': 'application/json'},
+      body: jsonEncode({'username': username, 'password': password}),
+    );
+
+    if (response.statusCode == 200) {
+      final responseData = jsonDecode(response.body);
+      token = responseData['token'];
+      _log.info('Login successful');
+    } else {
+      throw ApiException(
+        'Login failed',
+        statusCode: response.statusCode,
+        body: response.body,
+      );
+    }
+  }
+
+  /// Clears the authentication token.
+  void logout() {
+    token = null;
+    _log.info('Logged out successfully');
+  }
+
+  // ---------------------------------------------------------------------------
+  // HTTP Helpers
+  // ---------------------------------------------------------------------------
+
+  Map<String, String> _buildHeaders({bool isBinary = false}) {
+    return {
+      'Authorization': 'Bearer $token',
+      if (!isBinary) 'Content-Type': 'application/json',
+    };
+  }
+
+  /// Performs a GET request to the given endpoint.
+  Future<http.Response> get(
+    String endpoint, {
+    bool isBinary = false,
+  }) async {
+    final url = Uri.parse('$baseUrl$endpoint');
+    final response =
+        await http.get(url, headers: _buildHeaders(isBinary: isBinary));
+
+    if (response.statusCode != 200) {
+      _log.warning(
+        "GET '$endpoint' failed: ${response.statusCode}\n${response.body}",
+      );
+      throw ApiException(
+        'GET request failed',
+        statusCode: response.statusCode,
+        body: response.body,
+      );
+    }
+
+    return response;
+  }
+
+  /// Performs a POST request with JSON body.
+  Future<http.Response> post(
+    String endpoint,
+    Map<String, dynamic> body,
+  ) async {
+    final url = Uri.parse('$baseUrl$endpoint');
+
+    final response = await http.post(
+      url,
+      headers: _buildHeaders(),
+      body: jsonEncode(body),
+    );
+
+    if (response.statusCode != 200 && response.statusCode != 201) {
+      _log.warning(
+        "POST '$endpoint' failed: ${response.statusCode}\n${response.body}",
+      );
+      throw ApiException(
+        'POST request failed',
+        statusCode: response.statusCode,
+        body: response.body,
+      );
+    }
+
+    return response;
+  }
+
+  /// Performs a POST request with form-encoded body.
+  Future<http.Response> postFormData(String endpoint, String body) async {
+    final url = Uri.parse('$baseUrl$endpoint');
+
+    final response = await http.post(
+      url,
+      headers: {
+        'Authorization': 'Bearer $token',
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body,
+    );
+
+    if (response.statusCode != 200 && response.statusCode != 201) {
+      _log.warning(
+        "POST Form '$endpoint' failed: ${response.statusCode}\n${response.body}",
+      );
+      throw ApiException(
+        'POST Form request failed',
+        statusCode: response.statusCode,
+        body: response.body,
+      );
+    }
+
+    return response;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sheet Operations
+  // ---------------------------------------------------------------------------
+
+  /// Fetches the list of all sheets from the server.
+  Future<List<Sheet>> fetchSheets() async {
+    final response = await get('/api/sheets/list');
+    final data = jsonDecode(response.body);
+
+    return (data['sheets'] as List<dynamic>)
+        .map((sheet) => Sheet.fromJson(sheet as Map<String, dynamic>))
+        .toList();
+  }
+
+  /// Downloads PDF data for a sheet.
+  ///
+  /// Returns the raw PDF bytes. For caching, use [getPdfFileCached] instead.
+  Future<Uint8List> fetchPdfData(String sheetUuid) async {
+    final response = await get('/api/sheets/get/$sheetUuid', isBinary: true);
+    _log.info('PDF downloaded for sheet $sheetUuid');
+    return response.bodyBytes;
+  }
+
+  /// Gets a cached PDF file for a sheet, downloading if necessary.
+  ///
+  /// On web platforms, use [fetchPdfData] instead as file caching
+  /// is not supported.
+  Future<File> getPdfFileCached(String sheetUuid) async {
+    final cacheDir = await getTemporaryDirectory();
+    final cachedFile = File('${cacheDir.path}/$sheetUuid.pdf');
+
+    if (await cachedFile.exists()) {
+      _log.info('PDF found in cache: ${cachedFile.path}');
+      return cachedFile;
+    }
+
+    final pdfData = await fetchPdfData(sheetUuid);
+    await cachedFile.writeAsBytes(pdfData);
+    _log.info('PDF cached at: ${cachedFile.path}');
+    return cachedFile;
+  }
+}
+
+/// Exception thrown when an API request fails.
+class ApiException implements Exception {
+  final String message;
+  final int statusCode;
+  final String body;
+
+  ApiException(this.message, {required this.statusCode, required this.body});
+
+  @override
+  String toString() => 'ApiException: $message (status: $statusCode)\n$body';
+}

lib/core/services/storage_service.dart

@@ -0,0 +1,119 @@
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:hive/hive.dart';
+import 'package:sheetless/core/models/change.dart';
+import 'package:sheetless/core/models/config.dart';
+
+/// Keys for secure storage (credentials and tokens).
+enum SecureStorageKey { url, jwt, email }
+
+/// Service for managing local storage operations.
+///
+/// Uses [FlutterSecureStorage] for sensitive data (credentials, tokens)
+/// and [Hive] for general app data (config, sheet access times, change queue).
+class StorageService {
+  // Hive box names
+  static const String _sheetAccessTimesBox = 'sheetAccessTimes';
+  static const String _configBox = 'config';
+  static const String _changeQueueBox = 'changeQueue';
+
+  late final FlutterSecureStorage _secureStorage;
+
+  StorageService() {
+    _secureStorage = FlutterSecureStorage(
+      aOptions: const AndroidOptions(encryptedSharedPreferences: true),
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Secure Storage (Credentials & Tokens)
+  // ---------------------------------------------------------------------------
+
+  /// Reads a value from secure storage.
+  Future<String?> readSecure(SecureStorageKey key) {
+    return _secureStorage.read(key: key.name);
+  }
+
+  /// Writes a value to secure storage.
+  ///
+  /// Pass `null` to delete the key.
+  Future<void> writeSecure(SecureStorageKey key, String? value) {
+    return _secureStorage.write(key: key.name, value: value);
+  }
+
+  /// Clears the JWT token from secure storage.
+  Future<void> clearToken() {
+    return writeSecure(SecureStorageKey.jwt, null);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Config
+  // ---------------------------------------------------------------------------
+
+  /// Reads the app configuration from storage.
+  Future<Config> readConfig() async {
+    final box = await Hive.openBox(_configBox);
+    return Config(
+      twoPageMode: box.get(Config.keyTwoPageMode) ?? false,
+      fullscreen: box.get(Config.keyFullscreen) ?? false,
+    );
+  }
+
+  /// Writes the app configuration to storage.
+  Future<void> writeConfig(Config config) async {
+    final box = await Hive.openBox(_configBox);
+    await box.put(Config.keyTwoPageMode, config.twoPageMode);
+    await box.put(Config.keyFullscreen, config.fullscreen);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sheet Access Times (for sorting by recency)
+  // ---------------------------------------------------------------------------
+
+  /// Reads all sheet access times.
+  ///
+  /// Returns a map of sheet UUID to last access time.
+  Future<Map<String, DateTime>> readSheetAccessTimes() async {
+    final box = await Hive.openBox(_sheetAccessTimesBox);
+    return box.toMap().map(
+      (key, value) => MapEntry(key as String, DateTime.parse(value as String)),
+    );
+  }
+
+  /// Records when a sheet was last accessed.
+  Future<void> writeSheetAccessTime(String uuid, DateTime datetime) async {
+    final box = await Hive.openBox(_sheetAccessTimesBox);
+    await box.put(uuid, datetime.toIso8601String());
+  }
+
+  // ---------------------------------------------------------------------------
+  // Change Queue (Offline Sync)
+  // ---------------------------------------------------------------------------
+
+  /// Adds a change to the offline queue.
+  Future<void> writeChange(Change change) async {
+    final box = await Hive.openBox(_changeQueueBox);
+    await box.add(change.toMap());
+  }
+
+  /// Reads all pending changes from the queue.
+  Future<ChangeQueue> readChangeQueue() async {
+    final box = await Hive.openBox(_changeQueueBox);
+    final queue = ChangeQueue();
+
+    for (final map in box.values) {
+      queue.addChange(Change.fromMap(map as Map<dynamic, dynamic>));
+    }
+
+    return queue;
+  }
+
+  /// Removes the oldest change from the queue.
+  ///
+  /// Call this after successfully syncing a change to the server.
+  Future<void> deleteOldestChange() async {
+    final box = await Hive.openBox(_changeQueueBox);
+    if (box.isNotEmpty) {
+      await box.deleteAt(0);
+    }
+  }
+}