Merge branch 'develop' into bugfix/cleanup

API.Benchmark/API.Benchmark.csproj

@@ -26,5 +26,10 @@
         <CopyToOutputDirectory>Always</CopyToOutputDirectory>
       </Content>
     </ItemGroup>
+    <ItemGroup>
+      <None Update="Data\AesopsFables.epub">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+    </ItemGroup>
 
 </Project>

API.Benchmark/KoreaderHashBenchmark.cs

@@ -0,0 +1,41 @@
+using API.Helpers.Builders;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Order;
+using System;
+using API.Entities.Enums;
+
+namespace API.Benchmark
+{
+    [StopOnFirstError]
+    [MemoryDiagnoser]
+    [RankColumn]
+    [Orderer(SummaryOrderPolicy.FastestToSlowest)]
+    [SimpleJob(launchCount: 1, warmupCount: 5, invocationCount: 20)]
+    public class KoreaderHashBenchmark
+    {
+        private const string sourceEpub = "./Data/AesopsFables.epub";
+
+        [Benchmark(Baseline = true)]
+        public void TestBuildManga_baseline()
+        {
+            var file = new MangaFileBuilder(sourceEpub, MangaFormat.Epub)
+                .Build();
+            if (file == null)
+            {
+                throw new Exception("Failed to build manga file");
+            }
+        }
+
+        [Benchmark]
+        public void TestBuildManga_withHash()
+        {
+            var file = new MangaFileBuilder(sourceEpub, MangaFormat.Epub)
+                .WithHash()
+                .Build();
+            if (file == null)
+            {
+                throw new Exception("Failed to build manga file");
+            }
+        }
+    }
+}

API.Tests/API.Tests.csproj

@@ -36,4 +36,10 @@
         <None Remove="Extensions\Test Data\modified on run.txt" />
     </ItemGroup>
 
+    <ItemGroup>
+      <None Update="Data\AesopsFables.epub">
+        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+      </None>
+    </ItemGroup>
+
 </Project>

API.Tests/Extensions/QueryableExtensionsTests.cs

@@ -67,7 +67,7 @@ public class QueryableExtensionsTests
 
     [Theory]
     [InlineData(true, 2)]
-    [InlineData(false, 1)]
+    [InlineData(false, 2)]
     public void RestrictAgainstAgeRestriction_Genre_ShouldRestrictEverythingAboveTeen(bool includeUnknowns, int expectedCount)
     {
         var items = new List<Genre>()
@@ -94,7 +94,7 @@ public class QueryableExtensionsTests
 
     [Theory]
     [InlineData(true, 2)]
-    [InlineData(false, 1)]
+    [InlineData(false, 2)]
     public void RestrictAgainstAgeRestriction_Tag_ShouldRestrictEverythingAboveTeen(bool includeUnknowns, int expectedCount)
     {
         var items = new List<Tag>()

API.Tests/Helpers/KoreaderHelperTests.cs

@@ -0,0 +1,60 @@
+using API.DTOs.Koreader;
+using API.DTOs.Progress;
+using API.Helpers;
+using System.Runtime.CompilerServices;
+using Xunit;
+
+namespace API.Tests.Helpers;
+
+
+public class KoreaderHelperTests
+{
+
+    [Theory]
+    [InlineData("/body/DocFragment[11]/body/div/a", 10, null)]
+    [InlineData("/body/DocFragment[1]/body/div/p[40]", 0, 40)]
+    [InlineData("/body/DocFragment[8]/body/div/p[28]/text().264", 7, 28)]
+    public void GetEpubPositionDto(string koreaderPosition, int page, int? pNumber)
+    {
+        var expected = EmptyProgressDto();
+        expected.BookScrollId = pNumber.HasValue ? $"//html[1]/BODY/APP-ROOT[1]/DIV[1]/DIV[1]/DIV[1]/APP-BOOK-READER[1]/DIV[1]/DIV[2]/DIV[1]/DIV[1]/DIV[1]/P[{pNumber}]" : null;
+        expected.PageNum = page;
+        var actual = EmptyProgressDto();
+
+        KoreaderHelper.UpdateProgressDto(actual, koreaderPosition);
+        Assert.Equal(expected.BookScrollId, actual.BookScrollId);
+        Assert.Equal(expected.PageNum, actual.PageNum);
+    }
+
+
+    [Theory]
+    [InlineData("//html[1]/BODY/APP-ROOT[1]/DIV[1]/DIV[1]/DIV[1]/APP-BOOK-READER[1]/DIV[1]/DIV[2]/DIV[1]/DIV[1]/DIV[1]/P[20]", 5, "/body/DocFragment[6]/body/div/p[20]")]
+    [InlineData(null, 10, "/body/DocFragment[11]/body/div/a")]
+    public void GetKoreaderPosition(string scrollId, int page, string koreaderPosition)
+    {
+        var given = EmptyProgressDto();
+        given.BookScrollId = scrollId;
+        given.PageNum = page;
+
+        Assert.Equal(koreaderPosition, KoreaderHelper.GetKoreaderPosition(given));
+    }
+
+    [Theory]
+    [InlineData("./Data/AesopsFables.epub", "8795ACA4BF264B57C1EEDF06A0CEE688")]
+    public void GetKoreaderHash(string filePath, string hash)
+    {
+        Assert.Equal(KoreaderHelper.HashContents(filePath), hash);
+    }
+
+    private ProgressDto EmptyProgressDto()
+    {
+        return new ProgressDto
+        {
+            ChapterId = 0,
+            PageNum = 0,
+            VolumeId = 0,
+            SeriesId = 0,
+            LibraryId = 0
+        };
+    }
+}

API.Tests/Services/ExternalMetadataServiceTests.cs

@@ -2935,6 +2935,8 @@ public class ExternalMetadataServiceTests : AbstractDbTest
        metadataSettings.EnableTags = false;
        metadataSettings.EnablePublicationStatus = false;
        metadataSettings.EnableStartDate = false;
+       metadataSettings.FieldMappings = [];
+       metadataSettings.AgeRatingMappings = new Dictionary<string, AgeRating>();
        Context.MetadataSettings.Update(metadataSettings);
 
        await Context.SaveChangesAsync();

API.Tests/Services/ScrobblingServiceTests.cs

@@ -1,11 +1,17 @@
-using System.Linq;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
 using System.Threading.Tasks;
+using API.Data.Repositories;
 using API.DTOs.Scrobbling;
+using API.Entities;
 using API.Entities.Enums;
+using API.Entities.Scrobble;
 using API.Helpers.Builders;
 using API.Services;
 using API.Services.Plus;
 using API.SignalR;
+using Kavita.Common;
 using Microsoft.Extensions.Logging;
 using NSubstitute;
 using Xunit;
@@ -15,11 +21,33 @@ namespace API.Tests.Services;
 
 public class ScrobblingServiceTests : AbstractDbTest
 {
+    private const int ChapterPages = 100;
+
+    /// <summary>
+    /// {
+    /// "Issuer": "Issuer",
+    /// "Issued At": "2025-06-15T21:01:57.615Z",
+    /// "Expiration": "2200-06-15T21:01:57.615Z"
+    /// }
+    /// </summary>
+    /// <remarks>Our UnitTests will fail in 2200 :(</remarks>
+    private const string ValidJwtToken =
+        "eyJhbGciOiJIUzI1NiJ9.eyJJc3N1ZXIiOiJJc3N1ZXIiLCJleHAiOjcyNzI0NTAxMTcsImlhdCI6MTc1MDAyMTMxN30.zADmcGq_BfxbcV8vy4xw5Cbzn4COkmVINxgqpuL17Ng";
+
     private readonly ScrobblingService _service;
     private readonly ILicenseService _licenseService;
     private readonly ILocalizationService _localizationService;
     private readonly ILogger<ScrobblingService> _logger;
     private readonly IEmailService _emailService;
+    private readonly IKavitaPlusApiService _kavitaPlusApiService;
+    /// <summary>
+    /// IReaderService, without the ScrobblingService injected
+    /// </summary>
+    private readonly IReaderService _readerService;
+    /// <summary>
+    /// IReaderService, with the _service injected
+    /// </summary>
+    private readonly IReaderService _hookedUpReaderService;
 
     public ScrobblingServiceTests()
     {
@@ -27,8 +55,24 @@ public class ScrobblingServiceTests : AbstractDbTest
         _localizationService = Substitute.For<ILocalizationService>();
         _logger = Substitute.For<ILogger<ScrobblingService>>();
         _emailService = Substitute.For<IEmailService>();
+        _kavitaPlusApiService = Substitute.For<IKavitaPlusApiService>();
 
-        _service = new ScrobblingService(UnitOfWork, Substitute.For<IEventHub>(), _logger,  _licenseService, _localizationService, _emailService);
+        _service = new ScrobblingService(UnitOfWork, Substitute.For<IEventHub>(), _logger,  _licenseService,
+            _localizationService, _emailService, _kavitaPlusApiService);
+
+        _readerService = new ReaderService(UnitOfWork,
+            Substitute.For<ILogger<ReaderService>>(),
+            Substitute.For<IEventHub>(),
+            Substitute.For<IImageService>(),
+            Substitute.For<IDirectoryService>(),
+            Substitute.For<IScrobblingService>()); // Do not use the actual one
+
+        _hookedUpReaderService = new ReaderService(UnitOfWork,
+            Substitute.For<ILogger<ReaderService>>(),
+            Substitute.For<IEventHub>(),
+            Substitute.For<IImageService>(),
+            Substitute.For<IDirectoryService>(),
+            _service);
     }
 
     protected override async Task ResetDb()
@@ -46,6 +90,30 @@ public class ScrobblingServiceTests : AbstractDbTest
         var series = new SeriesBuilder("Test Series")
             .WithFormat(MangaFormat.Archive)
             .WithMetadata(new SeriesMetadataBuilder().Build())
+            .WithVolume(new VolumeBuilder("Volume 1")
+                .WithChapters([
+                    new ChapterBuilder("1")
+                        .WithPages(ChapterPages)
+                        .Build(),
+                    new ChapterBuilder("2")
+                        .WithPages(ChapterPages)
+                        .Build(),
+                    new ChapterBuilder("3")
+                        .WithPages(ChapterPages)
+                        .Build()])
+                .Build())
+            .WithVolume(new VolumeBuilder("Volume 2")
+                .WithChapters([
+                    new ChapterBuilder("4")
+                        .WithPages(ChapterPages)
+                        .Build(),
+                    new ChapterBuilder("5")
+                        .WithPages(ChapterPages)
+                        .Build(),
+                    new ChapterBuilder("6")
+                        .WithPages(ChapterPages)
+                        .Build()])
+                .Build())
             .Build();
 
         var library = new LibraryBuilder("Test Library", LibraryType.Manga)
@@ -67,6 +135,296 @@ public class ScrobblingServiceTests : AbstractDbTest
         await UnitOfWork.CommitAsync();
     }
 
+    private async Task<ScrobbleEvent> CreateScrobbleEvent(int? seriesId = null)
+    {
+        var evt = new ScrobbleEvent
+        {
+            ScrobbleEventType = ScrobbleEventType.ChapterRead,
+            Format = PlusMediaFormat.Manga,
+            SeriesId = seriesId ?? 0,
+            LibraryId = 0,
+            AppUserId = 0,
+        };
+
+        if (seriesId != null)
+        {
+            var series = await UnitOfWork.SeriesRepository.GetSeriesByIdAsync(seriesId.Value);
+            if (series != null) evt.Series = series;
+        }
+
+        return evt;
+    }
+
+
+    #region K+ API Request Tests
+
+    [Fact]
+    public async Task PostScrobbleUpdate_AuthErrors()
+    {
+        _kavitaPlusApiService.PostScrobbleUpdate(null!, "")
+            .ReturnsForAnyArgs(new ScrobbleResponseDto()
+            {
+                ErrorMessage = "Unauthorized"
+            });
+
+        var evt = await CreateScrobbleEvent();
+        await Assert.ThrowsAsync<KavitaException>(async () =>
+        {
+            await _service.PostScrobbleUpdate(new ScrobbleDto(), "", evt);
+        });
+        Assert.True(evt.IsErrored);
+        Assert.Equal("Kavita+ subscription no longer active", evt.ErrorDetails);
+    }
+
+    [Fact]
+    public async Task PostScrobbleUpdate_UnknownSeriesLoggedAsError()
+    {
+        _kavitaPlusApiService.PostScrobbleUpdate(null!, "")
+            .ReturnsForAnyArgs(new ScrobbleResponseDto()
+            {
+                ErrorMessage = "Unknown Series"
+            });
+
+        await SeedData();
+        var evt = await CreateScrobbleEvent(1);
+
+        await _service.PostScrobbleUpdate(new ScrobbleDto(), "", evt);
+        await UnitOfWork.CommitAsync();
+        Assert.True(evt.IsErrored);
+
+        var series = await UnitOfWork.SeriesRepository.GetSeriesByIdAsync(1);
+        Assert.NotNull(series);
+        Assert.True(series.IsBlacklisted);
+
+        var errors = await UnitOfWork.ScrobbleRepository.GetAllScrobbleErrorsForSeries(1);
+        Assert.Single(errors);
+        Assert.Equal("Series cannot be matched for Scrobbling", errors.First().Comment);
+        Assert.Equal(series.Id, errors.First().SeriesId);
+    }
+
+    [Fact]
+    public async Task PostScrobbleUpdate_InvalidAccessToken()
+    {
+        _kavitaPlusApiService.PostScrobbleUpdate(null!, "")
+            .ReturnsForAnyArgs(new ScrobbleResponseDto()
+            {
+                ErrorMessage = "Access token is invalid"
+            });
+
+        var evt = await CreateScrobbleEvent();
+
+        await Assert.ThrowsAsync<KavitaException>(async () =>
+        {
+            await _service.PostScrobbleUpdate(new ScrobbleDto(), "", evt);
+        });
+
+        Assert.True(evt.IsErrored);
+        Assert.Equal("Access Token needs to be rotated to continue scrobbling", evt.ErrorDetails);
+    }
+
+    #endregion
+
+    #region K+ API Request data tests
+
+    [Fact]
+    public async Task ProcessReadEvents_CreatesNoEventsWhenNoProgress()
+    {
+        await ResetDb();
+        await SeedData();
+
+        // Set Returns
+        _licenseService.HasActiveLicense().Returns(Task.FromResult(true));
+        _kavitaPlusApiService.GetRateLimit(Arg.Any<string>(), Arg.Any<string>())
+            .Returns(100);
+
+        var user = await UnitOfWork.UserRepository.GetUserByIdAsync(1);
+        Assert.NotNull(user);
+
+        // Ensure CanProcessScrobbleEvent returns true
+        user.AniListAccessToken = ValidJwtToken;
+        UnitOfWork.UserRepository.Update(user);
+        await UnitOfWork.CommitAsync();
+
+        var chapter = await UnitOfWork.ChapterRepository.GetChapterAsync(4);
+        Assert.NotNull(chapter);
+
+        var volume = await UnitOfWork.VolumeRepository.GetVolumeAsync(1, VolumeIncludes.Chapters);
+        Assert.NotNull(volume);
+
+        // Call Scrobble without having any progress
+        await _service.ScrobbleReadingUpdate(1, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+    }
+
+    [Fact]
+    public async Task ProcessReadEvents_UpdateVolumeAndChapterData()
+    {
+        await ResetDb();
+        await SeedData();
+
+        // Set Returns
+        _licenseService.HasActiveLicense().Returns(Task.FromResult(true));
+        _kavitaPlusApiService.GetRateLimit(Arg.Any<string>(), Arg.Any<string>())
+            .Returns(100);
+
+        var user = await UnitOfWork.UserRepository.GetUserByIdAsync(1);
+        Assert.NotNull(user);
+
+        // Ensure CanProcessScrobbleEvent returns true
+        user.AniListAccessToken = ValidJwtToken;
+        UnitOfWork.UserRepository.Update(user);
+        await UnitOfWork.CommitAsync();
+
+        var chapter = await UnitOfWork.ChapterRepository.GetChapterAsync(4);
+        Assert.NotNull(chapter);
+
+        var volume = await UnitOfWork.VolumeRepository.GetVolumeAsync(1, VolumeIncludes.Chapters);
+        Assert.NotNull(volume);
+
+        // Mark something as read to trigger event creation
+        await _readerService.MarkChaptersAsRead(user, 1, new List<Chapter>() {volume.Chapters[0]});
+        await UnitOfWork.CommitAsync();
+
+        // Call Scrobble while having some progress
+        await _service.ScrobbleReadingUpdate(user.Id, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Single(events);
+
+        // Give it some (more) read progress
+        await _readerService.MarkChaptersAsRead(user, 1, volume.Chapters);
+        await _readerService.MarkChaptersAsRead(user, 1, [chapter]);
+        await UnitOfWork.CommitAsync();
+
+        await _service.ProcessUpdatesSinceLastSync();
+
+        await _kavitaPlusApiService.Received(1).PostScrobbleUpdate(
+            Arg.Is<ScrobbleDto>(data =>
+                data.ChapterNumber == (int)chapter.MaxNumber &&
+                data.VolumeNumber == (int)volume.MaxNumber
+                ),
+            Arg.Any<string>());
+    }
+
+    #endregion
+
+    #region Scrobble Reading Update Tests
+
+    [Fact]
+    public async Task ScrobbleReadingUpdate_IgnoreNoLicense()
+    {
+        await ResetDb();
+        await SeedData();
+
+        _licenseService.HasActiveLicense().Returns(false);
+
+        await _service.ScrobbleReadingUpdate(1, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+    }
+
+    [Fact]
+    public async Task ScrobbleReadingUpdate_RemoveWhenNoProgress()
+    {
+        await ResetDb();
+        await SeedData();
+
+        _licenseService.HasActiveLicense().Returns(true);
+
+        var user = await UnitOfWork.UserRepository.GetUserByIdAsync(1);
+        Assert.NotNull(user);
+
+        var volume = await UnitOfWork.VolumeRepository.GetVolumeAsync(1, VolumeIncludes.Chapters);
+        Assert.NotNull(volume);
+
+        await _readerService.MarkChaptersAsRead(user, 1, new List<Chapter>() {volume.Chapters[0]});
+        await UnitOfWork.CommitAsync();
+
+        await _service.ScrobbleReadingUpdate(1, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Single(events);
+
+        var readEvent = events.First();
+        Assert.False(readEvent.IsProcessed);
+
+        await _hookedUpReaderService.MarkSeriesAsUnread(user, 1);
+        await UnitOfWork.CommitAsync();
+
+        // Existing event is deleted
+        await _service.ScrobbleReadingUpdate(1, 1);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+
+        await _hookedUpReaderService.MarkSeriesAsUnread(user, 1);
+        await UnitOfWork.CommitAsync();
+
+        // No new events are added
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+    }
+
+    [Fact]
+    public async Task ScrobbleReadingUpdate_UpdateExistingNotIsProcessed()
+    {
+        await ResetDb();
+        await SeedData();
+
+        var user = await UnitOfWork.UserRepository.GetUserByIdAsync(1);
+        Assert.NotNull(user);
+
+        var chapter1 = await UnitOfWork.ChapterRepository.GetChapterAsync(1);
+        var chapter2 = await UnitOfWork.ChapterRepository.GetChapterAsync(2);
+        var chapter3 = await UnitOfWork.ChapterRepository.GetChapterAsync(3);
+        Assert.NotNull(chapter1);
+        Assert.NotNull(chapter2);
+        Assert.NotNull(chapter3);
+
+        _licenseService.HasActiveLicense().Returns(true);
+
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+
+
+        await _readerService.MarkChaptersAsRead(user, 1, [chapter1]);
+        await UnitOfWork.CommitAsync();
+
+        // Scrobble update
+        await _service.ScrobbleReadingUpdate(1, 1);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Single(events);
+
+        var readEvent = events[0];
+        Assert.False(readEvent.IsProcessed);
+        Assert.Equal(1, readEvent.ChapterNumber);
+
+        // Mark as processed
+        readEvent.IsProcessed = true;
+        await UnitOfWork.CommitAsync();
+
+        await _readerService.MarkChaptersAsRead(user, 1, [chapter2]);
+        await UnitOfWork.CommitAsync();
+
+        // Scrobble update
+        await _service.ScrobbleReadingUpdate(1, 1);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Equal(2, events.Count);
+        Assert.Single(events.Where(e => e.IsProcessed).ToList());
+        Assert.Single(events.Where(e => !e.IsProcessed).ToList());
+
+        // Should update the existing non processed event
+        await _readerService.MarkChaptersAsRead(user, 1, [chapter3]);
+        await UnitOfWork.CommitAsync();
+
+        // Scrobble update
+        await _service.ScrobbleReadingUpdate(1, 1);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Equal(2, events.Count);
+        Assert.Single(events.Where(e => e.IsProcessed).ToList());
+        Assert.Single(events.Where(e => !e.IsProcessed).ToList());
+    }
+
+    #endregion
+
     #region ScrobbleWantToReadUpdate Tests
 
     [Fact]
@@ -203,6 +561,59 @@ public class ScrobblingServiceTests : AbstractDbTest
 
     #endregion
 
+    #region Scrobble Rating Update Test
+
+    [Fact]
+    public async Task ScrobbleRatingUpdate_IgnoreNoLicense()
+    {
+        await ResetDb();
+        await SeedData();
+
+        _licenseService.HasActiveLicense().Returns(false);
+
+        await _service.ScrobbleRatingUpdate(1, 1, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Empty(events);
+    }
+
+    [Fact]
+    public async Task ScrobbleRatingUpdate_UpdateExistingNotIsProcessed()
+    {
+        await ResetDb();
+        await SeedData();
+
+        _licenseService.HasActiveLicense().Returns(true);
+
+        var user = await UnitOfWork.UserRepository.GetUserByIdAsync(1);
+        Assert.NotNull(user);
+
+        var series = await UnitOfWork.SeriesRepository.GetSeriesByIdAsync(1);
+        Assert.NotNull(series);
+
+        await _service.ScrobbleRatingUpdate(user.Id, series.Id, 1);
+        var events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Single(events);
+        Assert.Equal(1, events.First().Rating);
+
+        // Mark as processed
+        events.First().IsProcessed = true;
+        await UnitOfWork.CommitAsync();
+
+        await _service.ScrobbleRatingUpdate(user.Id, series.Id, 5);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Equal(2, events.Count);
+        Assert.Single(events, evt => evt.IsProcessed);
+        Assert.Single(events, evt => !evt.IsProcessed);
+
+        await _service.ScrobbleRatingUpdate(user.Id, series.Id, 5);
+        events = await UnitOfWork.ScrobbleRepository.GetAllEventsForSeries(1);
+        Assert.Single(events, evt => !evt.IsProcessed);
+        Assert.Equal(5, events.First(evt => !evt.IsProcessed).Rating);
+
+    }
+
+    #endregion
+
     [Theory]
     [InlineData("https://anilist.co/manga/35851/Byeontaega-Doeja/", 35851)]
     [InlineData("https://anilist.co/manga/30105", 30105)]

API/Controllers/KoreaderController.cs

@@ -0,0 +1,118 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using System;
+using System.Threading.Tasks;
+using API.Data;
+using API.Data.Repositories;
+using API.DTOs.Koreader;
+using API.Entities;
+using API.Services;
+using Kavita.Common;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.Extensions.Logging;
+using static System.Net.WebRequestMethods;
+
+namespace API.Controllers;
+#nullable enable
+
+/// <summary>
+/// The endpoint to interface with Koreader's Progress Sync plugin.
+/// </summary>
+/// <remarks>
+/// Koreader uses a different form of authentication. It stores the username and password in headers.
+/// https://github.com/koreader/koreader/blob/master/plugins/kosync.koplugin/KOSyncClient.lua
+/// </remarks>
+[AllowAnonymous]
+public class KoreaderController : BaseApiController
+{
+
+    private readonly IUnitOfWork _unitOfWork;
+    private readonly ILocalizationService _localizationService;
+    private readonly IKoreaderService _koreaderService;
+    private readonly ILogger<KoreaderController> _logger;
+
+    public KoreaderController(IUnitOfWork unitOfWork, ILocalizationService localizationService,
+            IKoreaderService koreaderService, ILogger<KoreaderController> logger)
+    {
+        _unitOfWork = unitOfWork;
+        _localizationService = localizationService;
+        _koreaderService = koreaderService;
+        _logger = logger;
+    }
+
+    // We won't allow users to be created from Koreader. Rather, they
+    // must already have an account.
+    /*
+    [HttpPost("/users/create")]
+    public IActionResult CreateUser(CreateUserRequest request)
+    {
+    }
+    */
+
+    [HttpGet("{apiKey}/users/auth")]
+    public async Task<IActionResult> Authenticate(string apiKey)
+    {
+        var userId = await GetUserId(apiKey);
+        var user = await _unitOfWork.UserRepository.GetUserByIdAsync(userId);
+        if (user == null) return Unauthorized();
+
+        return Ok(new { username = user.UserName });
+    }
+
+    /// <summary>
+    /// Syncs book progress with Kavita. Will attempt to save the underlying reader position if possible.
+    /// </summary>
+    /// <param name="apiKey"></param>
+    /// <param name="request"></param>
+    /// <returns></returns>
+    [HttpPut("{apiKey}/syncs/progress")]
+    public async Task<ActionResult<KoreaderProgressUpdateDto>> UpdateProgress(string apiKey, KoreaderBookDto request)
+    {
+        try
+        {
+            var userId = await GetUserId(apiKey);
+            await _koreaderService.SaveProgress(request, userId);
+
+            return Ok(new KoreaderProgressUpdateDto{ Document = request.Document, Timestamp = DateTime.UtcNow });
+        }
+        catch (KavitaException ex)
+        {
+            return BadRequest(ex.Message);
+        }
+    }
+
+    /// <summary>
+    /// Gets book progress from Kavita, if not found will return a 400
+    /// </summary>
+    /// <param name="apiKey"></param>
+    /// <param name="ebookHash"></param>
+    /// <returns></returns>
+    [HttpGet("{apiKey}/syncs/progress/{ebookHash}")]
+    public async Task<ActionResult<KoreaderBookDto>> GetProgress(string apiKey, string ebookHash)
+    {
+        try
+        {
+            var userId = await GetUserId(apiKey);
+            var response = await _koreaderService.GetProgress(ebookHash, userId);
+            _logger.LogDebug("Koreader response progress: {Progress}", response.Progress);
+
+            return Ok(response);
+        }
+        catch (KavitaException ex)
+        {
+            return BadRequest(ex.Message);
+        }
+    }
+
+    private async Task<int> GetUserId(string apiKey)
+    {
+        try
+        {
+            return await _unitOfWork.UserRepository.GetUserIdByApiKeyAsync(apiKey);
+        }
+        catch
+        {
+            throw new KavitaException(await _localizationService.Get("en", "user-doesnt-exist"));
+        }
+    }
+}

API/Controllers/ScrobblingController.cs

@@ -254,7 +254,7 @@ public class ScrobblingController : BaseApiController
     }
 
     /// <summary>
-    /// Adds a hold against the Series for user's scrobbling
+    /// Remove a hold against the Series for user's scrobbling
     /// </summary>
     /// <param name="seriesId"></param>
     /// <returns></returns>
@@ -281,4 +281,18 @@ public class ScrobblingController : BaseApiController
         var user = await _unitOfWork.UserRepository.GetUserByIdAsync(User.GetUserId());
         return Ok(user is {HasRunScrobbleEventGeneration: true});
     }
+
+    /// <summary>
+    /// Delete the given scrobble events if they belong to that user
+    /// </summary>
+    /// <param name="eventIds"></param>
+    /// <returns></returns>
+    [HttpPost("bulk-remove-events")]
+    public async Task<ActionResult> BulkRemoveScrobbleEvents(IList<long> eventIds)
+    {
+        var events = await _unitOfWork.ScrobbleRepository.GetUserEvents(User.GetUserId(), eventIds);
+        _unitOfWork.ScrobbleRepository.Remove(events);
+        await _unitOfWork.CommitAsync();
+        return Ok();
+    }
 }

API/DTOs/Koreader/KoreaderBookDto.cs

@@ -0,0 +1,33 @@
+using API.DTOs.Progress;
+
+namespace API.DTOs.Koreader;
+
+/// <summary>
+/// This is the interface for receiving and sending updates to Koreader. The only fields
+/// that are actually used are the Document and Progress fields.
+/// </summary>
+public class KoreaderBookDto
+{
+    /// <summary>
+    /// This is the Koreader hash of the book. It is used to identify the book.
+    /// </summary>
+    public string Document { get; set; }
+    /// <summary>
+    /// A randomly generated id from the koreader device. Only used to maintain the Koreader interface.
+    /// </summary>
+    public string Device_id { get; set; }
+    /// <summary>
+    /// The Koreader device name. Only used to maintain the Koreader interface.
+    /// </summary>
+    public string Device { get; set; }
+    /// <summary>
+    /// Percent progress of the book. Only used to maintain the Koreader interface.
+    /// </summary>
+    public float Percentage { get; set; }
+    /// <summary>
+    /// An XPath string read by Koreader to determine the location within the epub.
+    /// Essentially, it is Koreader's equivalent to ProgressDto.BookScrollId.
+    /// </summary>
+    /// <seealso cref="ProgressDto.BookScrollId"/>
+    public string Progress { get; set; }
+}

API/DTOs/Koreader/KoreaderProgressUpdateDto.cs

@@ -0,0 +1,15 @@
+using System;
+
+namespace API.DTOs.Koreader;
+
+public class KoreaderProgressUpdateDto
+{
+    /// <summary>
+    /// This is the Koreader hash of the book. It is used to identify the book.
+    /// </summary>
+    public string Document { get; set; }
+    /// <summary>
+    /// UTC Timestamp to return to KOReader
+    /// </summary>
+    public DateTime Timestamp { get; set; }
+}

API/DTOs/Scrobbling/ScrobbleEventDto.cs

@@ -5,6 +5,7 @@ namespace API.DTOs.Scrobbling;
 
 public sealed record ScrobbleEventDto
 {
+    public long Id { get; init; }
     public string SeriesName { get; set; }
     public int SeriesId { get; set; }
     public int LibraryId { get; set; }

API/DTOs/Scrobbling/ScrobbleResponseDto.cs

@@ -8,5 +8,6 @@ public sealed record ScrobbleResponseDto
 {
     public bool Successful { get; set; }
     public string? ErrorMessage { get; set; }
+    public string? ExtraInformation  {get; set;}
     public int RateLeft { get; set; }
 }

API/Data/Migrations/20250519151126_KoreaderHash.cs

@@ -0,0 +1,28 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace API.Data.Migrations
+{
+    /// <inheritdoc />
+    public partial class KoreaderHash : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<string>(
+                name: "KoreaderHash",
+                table: "MangaFile",
+                type: "TEXT",
+                nullable: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "KoreaderHash",
+                table: "MangaFile");
+        }
+    }
+}

API/Data/Migrations/DataContextModelSnapshot.cs

@@ -1408,6 +1408,9 @@ namespace API.Data.Migrations
                     b.Property<int>("Format")
                         .HasColumnType("INTEGER");
 
+                    b.Property<string>("KoreaderHash")
+                        .HasColumnType("TEXT");
+
                     b.Property<DateTime>("LastFileAnalysis")
                         .HasColumnType("TEXT");
 

API/Data/Repositories/MangaFileRepository.cs

@@ -5,11 +5,13 @@ using API.Entities;
 using Microsoft.EntityFrameworkCore;
 
 namespace API.Data.Repositories;
+#nullable enable
 
 public interface IMangaFileRepository
 {
     void Update(MangaFile file);
     Task<IList<MangaFile>> GetAllWithMissingExtension();
+    Task<MangaFile?> GetByKoreaderHash(string hash);
 }
 
 public class MangaFileRepository : IMangaFileRepository
@@ -32,4 +34,13 @@ public class MangaFileRepository : IMangaFileRepository
             .Where(f => string.IsNullOrEmpty(f.Extension))
             .ToListAsync();
     }
+
+    public async Task<MangaFile?> GetByKoreaderHash(string hash)
+    {
+        if (string.IsNullOrEmpty(hash)) return null;
+
+        return await _context.MangaFile
+            .FirstOrDefaultAsync(f => f.KoreaderHash != null &&
+                                    f.KoreaderHash.Equals(hash.ToUpper()));
+    }
 }

API/Data/Repositories/ScrobbleEventRepository.cs

@@ -29,8 +29,23 @@ public interface IScrobbleRepository
     Task<IList<ScrobbleError>> GetAllScrobbleErrorsForSeries(int seriesId);
     Task ClearScrobbleErrors();
     Task<bool> HasErrorForSeries(int seriesId);
-    Task<ScrobbleEvent?> GetEvent(int userId, int seriesId, ScrobbleEventType eventType);
+    /// <summary>
+    /// Get all events for a specific user and type
+    /// </summary>
+    /// <param name="userId"></param>
+    /// <param name="seriesId"></param>
+    /// <param name="eventType"></param>
+    /// <param name="isNotProcessed">If true, only returned not processed events</param>
+    /// <returns></returns>
+    Task<ScrobbleEvent?> GetEvent(int userId, int seriesId, ScrobbleEventType eventType, bool isNotProcessed = false);
     Task<IEnumerable<ScrobbleEvent>> GetUserEventsForSeries(int userId, int seriesId);
+    /// <summary>
+    /// Return the events with given ids, when belonging to the passed user
+    /// </summary>
+    /// <param name="userId"></param>
+    /// <param name="scrobbleEventIds"></param>
+    /// <returns></returns>
+    Task<IList<ScrobbleEvent>> GetUserEvents(int userId, IList<long> scrobbleEventIds);
     Task<PagedList<ScrobbleEventDto>> GetUserEvents(int userId, ScrobbleEventFilter filter, UserParams pagination);
     Task<IList<ScrobbleEvent>> GetAllEventsForSeries(int seriesId);
     Task<IList<ScrobbleEvent>> GetAllEventsWithSeriesIds(IEnumerable<int> seriesIds);
@@ -146,22 +161,32 @@ public class ScrobbleRepository : IScrobbleRepository
         return await _context.ScrobbleError.AnyAsync(n => n.SeriesId == seriesId);
     }
 
-    public async Task<ScrobbleEvent?> GetEvent(int userId, int seriesId, ScrobbleEventType eventType)
+    public async Task<ScrobbleEvent?> GetEvent(int userId, int seriesId, ScrobbleEventType eventType, bool isNotProcessed = false)
     {
-        return await _context.ScrobbleEvent.FirstOrDefaultAsync(e =>
+        return await _context.ScrobbleEvent
-            e.AppUserId == userId && e.SeriesId == seriesId && e.ScrobbleEventType == eventType);
+            .Where(e => e.AppUserId == userId && e.SeriesId == seriesId && e.ScrobbleEventType == eventType)
+            .WhereIf(isNotProcessed, e => !e.IsProcessed)
+            .OrderBy(e => e.LastModifiedUtc)
+            .FirstOrDefaultAsync();
     }
 
     public async Task<IEnumerable<ScrobbleEvent>> GetUserEventsForSeries(int userId, int seriesId)
     {
         return await _context.ScrobbleEvent
-            .Where(e => e.AppUserId == userId && !e.IsProcessed)
+            .Where(e => e.AppUserId == userId && !e.IsProcessed && e.SeriesId == seriesId)
             .Include(e => e.Series)
             .OrderBy(e => e.LastModifiedUtc)
             .AsSplitQuery()
             .ToListAsync();
     }
 
+    public async Task<IList<ScrobbleEvent>> GetUserEvents(int userId, IList<long> scrobbleEventIds)
+    {
+        return await _context.ScrobbleEvent
+            .Where(e => e.AppUserId == userId && scrobbleEventIds.Contains(e.Id))
+            .ToListAsync();
+    }
+
     public async Task<PagedList<ScrobbleEventDto>> GetUserEvents(int userId, ScrobbleEventFilter filter, UserParams pagination)
     {
         var query =  _context.ScrobbleEvent

API/Entities/MangaFile.cs

@@ -21,6 +21,11 @@ public class MangaFile : IEntityDate
     /// </summary>
     public required string FilePath { get; set; }
     /// <summary>
+    /// A hash of the document using Koreader's unique hashing algorithm
+    /// </summary>
+    /// <remark> KoreaderHash is only available for epub types </remark>
+    public string? KoreaderHash { get; set; }
+    /// <summary>
     /// Number of pages for the given file
     /// </summary>
     public int Pages { get; set; }

API/Entities/Scrobble/ScrobbleEvent.cs

@@ -68,4 +68,14 @@ public class ScrobbleEvent : IEntityDate
     public DateTime LastModified { get; set; }
     public DateTime CreatedUtc { get; set; }
     public DateTime LastModifiedUtc { get; set; }
+
+    /// <summary>
+    /// Sets the ErrorDetail and marks the event as <see cref="IsErrored"/>
+    /// </summary>
+    /// <param name="errorMessage"></param>
+    public void SetErrorMessage(string errorMessage)
+    {
+        ErrorDetails = errorMessage;
+        IsErrored = true;
+    }
 }

API/Extensions/ApplicationServiceExtensions.cs

@@ -55,6 +55,7 @@ public static class ApplicationServiceExtensions
         services.AddScoped<IRatingService, RatingService>();
         services.AddScoped<IPersonService, PersonService>();
         services.AddScoped<IReadingProfileService, ReadingProfileService>();
+        services.AddScoped<IKoreaderService, KoreaderService>();
 
         services.AddScoped<IScannerService, ScannerService>();
         services.AddScoped<IProcessSeries, ProcessSeries>();
@@ -75,6 +76,7 @@ public static class ApplicationServiceExtensions
         services.AddScoped<ISettingsService, SettingsService>();
 
 
+        services.AddScoped<IKavitaPlusApiService, KavitaPlusApiService>();
         services.AddScoped<IScrobblingService, ScrobblingService>();
         services.AddScoped<ILicenseService, LicenseService>();
         services.AddScoped<IExternalMetadataService, ExternalMetadataService>();

API/Extensions/QueryExtensions/RestrictByAgeExtensions.cs

@@ -82,6 +82,12 @@ public static class RestrictByAgeExtensions
             sm.Metadata.AgeRating <= restriction.AgeRating && sm.Metadata.AgeRating > AgeRating.Unknown));
     }
 
+    /// <summary>
+    /// Returns all Genres where any of the linked Series/Chapters are less than or equal to restriction age rating
+    /// </summary>
+    /// <param name="queryable"></param>
+    /// <param name="restriction"></param>
+    /// <returns></returns>
     public static IQueryable<Genre> RestrictAgainstAgeRestriction(this IQueryable<Genre> queryable, AgeRestriction restriction)
     {
         if (restriction.AgeRating == AgeRating.NotApplicable) return queryable;

API/Helpers/Builders/KoreaderBookDtoBuilder.cs

@@ -0,0 +1,46 @@
+using System;
+using System.Security.Cryptography;
+using System.Text;
+using API.DTOs.Koreader;
+
+namespace API.Helpers.Builders;
+
+public class KoreaderBookDtoBuilder : IEntityBuilder<KoreaderBookDto>
+{
+    private readonly KoreaderBookDto _dto;
+    public KoreaderBookDto Build() => _dto;
+
+    public KoreaderBookDtoBuilder(string documentHash)
+    {
+        _dto = new KoreaderBookDto()
+        {
+            Document = documentHash,
+            Device = "Kavita"
+        };
+    }
+
+    public KoreaderBookDtoBuilder WithDocument(string documentHash)
+    {
+        _dto.Document = documentHash;
+        return this;
+    }
+
+    public KoreaderBookDtoBuilder WithProgress(string progress)
+    {
+        _dto.Progress = progress;
+        return this;
+    }
+
+    public KoreaderBookDtoBuilder WithPercentage(int? pageNum, int pages)
+    {
+        _dto.Percentage = (pageNum ?? 0) / (float) pages;
+        return this;
+    }
+
+    public KoreaderBookDtoBuilder WithDeviceId(string installId, int userId)
+    {
+        var hash = SHA256.HashData(Encoding.UTF8.GetBytes(installId + userId));
+        _dto.Device_id = Convert.ToHexString(hash);
+        return this;
+    }
+}

API/Helpers/Builders/MangaFileBuilder.cs

@@ -60,4 +60,17 @@ public class MangaFileBuilder : IEntityBuilder<MangaFile>
         _mangaFile.Id = Math.Max(id, 0);
         return this;
     }
+
+    /// <summary>
+    /// Generate the Hash on the underlying file
+    /// </summary>
+    /// <remarks>Only applicable to Epubs</remarks>
+    public MangaFileBuilder WithHash()
+    {
+        if (_mangaFile.Format != MangaFormat.Epub) return this;
+
+        _mangaFile.KoreaderHash = KoreaderHelper.HashContents(_mangaFile.FilePath);
+
+        return this;
+    }
 }

API/Helpers/KoreaderHelper.cs

@@ -0,0 +1,113 @@
+using API.DTOs.Progress;
+using System;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
+using API.Services.Tasks.Scanner.Parser;
+
+namespace API.Helpers;
+
+/// <summary>
+/// All things related to Koreader
+/// </summary>
+/// <remarks>Original developer: https://github.com/MFDeAngelo</remarks>
+public static class KoreaderHelper
+{
+    /// <summary>
+    /// Hashes the document according to a custom Koreader hashing algorithm.
+    /// Look at the util.partialMD5 method in the attached link.
+    /// Note: Only applies to epub files
+    /// </summary>
+    /// <remarks>The hashing algorithm is relatively quick as it only hashes ~10,000 bytes for the biggest of files.</remarks>
+    /// <see href="https://github.com/koreader/koreader/blob/master/frontend/util.lua#L1040"/>
+    /// <param name="filePath">The path to the file to hash</param>
+    public static string HashContents(string filePath)
+    {
+        if (string.IsNullOrEmpty(filePath) || !File.Exists(filePath) || !Parser.IsEpub(filePath))
+        {
+            return null;
+        }
+
+        using var file = File.OpenRead(filePath);
+
+        const int step = 1024;
+        const int size = 1024;
+        var md5 = MD5.Create();
+        var buffer = new byte[size];
+
+        for (var i = -1; i < 10; i++)
+        {
+            file.Position = step << 2 * i;
+            var bytesRead = file.Read(buffer, 0, size);
+            if (bytesRead > 0)
+            {
+                md5.TransformBlock(buffer, 0, bytesRead, buffer, 0);
+            }
+            else
+            {
+                break;
+            }
+        }
+
+        file.Close();
+        md5.TransformFinalBlock([], 0, 0);
+
+        return md5.Hash == null ? null : Convert.ToHexString(md5.Hash).ToUpper();
+    }
+
+    /// <summary>
+    /// Koreader can identify documents based on contents or title.
+    /// For now, we only support by contents.
+    /// </summary>
+    public static string HashTitle(string filePath)
+    {
+        var fileName = Path.GetFileName(filePath);
+        var fileNameBytes = Encoding.ASCII.GetBytes(fileName);
+        var bytes = MD5.HashData(fileNameBytes);
+
+        return Convert.ToHexString(bytes);
+    }
+
+    public static void UpdateProgressDto(ProgressDto progress, string koreaderPosition)
+    {
+        var path = koreaderPosition.Split('/');
+        if (path.Length < 6)
+        {
+            return;
+        }
+
+        var docNumber = path[2].Replace("DocFragment[", string.Empty).Replace("]", string.Empty);
+        progress.PageNum = int.Parse(docNumber) - 1;
+        var lastTag = path[5].ToUpper();
+
+        if (lastTag == "A")
+        {
+            progress.BookScrollId = null;
+        }
+        else
+        {
+            // The format that Kavita accepts as a progress string. It tells Kavita where Koreader last left off.
+            progress.BookScrollId = $"//html[1]/BODY/APP-ROOT[1]/DIV[1]/DIV[1]/DIV[1]/APP-BOOK-READER[1]/DIV[1]/DIV[2]/DIV[1]/DIV[1]/DIV[1]/{lastTag}";
+        }
+    }
+
+
+    public static string GetKoreaderPosition(ProgressDto progressDto)
+    {
+        string lastTag;
+        var koreaderPageNumber = progressDto.PageNum + 1;
+
+        if (string.IsNullOrEmpty(progressDto.BookScrollId))
+        {
+            lastTag = "a";
+        }
+        else
+        {
+            var tokens = progressDto.BookScrollId.Split('/');
+            lastTag = tokens[^1].ToLower();
+        }
+
+        // The format that Koreader accepts as a progress string. It tells Koreader where Kavita last left off.
+        return $"/body/DocFragment[{koreaderPageNumber}]/body/div/{lastTag}";
+    }
+}

API/Services/KoreaderService.cs

@@ -0,0 +1,90 @@
+using System.Threading.Tasks;
+using API.Data;
+using API.DTOs.Koreader;
+using API.DTOs.Progress;
+using API.Helpers;
+using API.Helpers.Builders;
+using Kavita.Common;
+using Microsoft.Extensions.Logging;
+
+namespace API.Services;
+
+#nullable enable
+
+public interface IKoreaderService
+{
+    Task SaveProgress(KoreaderBookDto koreaderBookDto, int userId);
+    Task<KoreaderBookDto> GetProgress(string bookHash, int userId);
+}
+
+public class KoreaderService : IKoreaderService
+{
+    private readonly IReaderService _readerService;
+    private readonly IUnitOfWork _unitOfWork;
+    private readonly ILocalizationService _localizationService;
+    private readonly ILogger<KoreaderService> _logger;
+
+    public KoreaderService(IReaderService readerService, IUnitOfWork unitOfWork, ILocalizationService localizationService, ILogger<KoreaderService> logger)
+    {
+        _readerService = readerService;
+        _unitOfWork = unitOfWork;
+        _localizationService = localizationService;
+        _logger = logger;
+    }
+
+    /// <summary>
+    /// Given a Koreader hash, locate the underlying file and generate/update a progress event.
+    /// </summary>
+    /// <param name="koreaderBookDto"></param>
+    /// <param name="userId"></param>
+    public async Task SaveProgress(KoreaderBookDto koreaderBookDto, int userId)
+    {
+        _logger.LogDebug("Saving Koreader progress for {UserId}: {KoreaderProgress}", userId, koreaderBookDto.Progress);
+        var file = await _unitOfWork.MangaFileRepository.GetByKoreaderHash(koreaderBookDto.Document);
+        if (file == null) throw new KavitaException(await _localizationService.Translate(userId, "file-missing"));
+
+        var userProgressDto = await _unitOfWork.AppUserProgressRepository.GetUserProgressDtoAsync(file.ChapterId, userId);
+        if (userProgressDto == null)
+        {
+            var chapterDto = await _unitOfWork.ChapterRepository.GetChapterDtoAsync(file.ChapterId);
+            if (chapterDto == null) throw new KavitaException(await _localizationService.Translate(userId, "chapter-doesnt-exist"));
+
+            var volumeDto = await _unitOfWork.VolumeRepository.GetVolumeByIdAsync(chapterDto.VolumeId);
+            if (volumeDto == null) throw new KavitaException(await _localizationService.Translate(userId, "volume-doesnt-exist"));
+
+            userProgressDto = new ProgressDto()
+            {
+                ChapterId = file.ChapterId,
+                VolumeId = chapterDto.VolumeId,
+                SeriesId = volumeDto.SeriesId,
+            };
+        }
+        // Update the bookScrollId if possible
+        KoreaderHelper.UpdateProgressDto(userProgressDto, koreaderBookDto.Progress);
+
+        await _readerService.SaveReadingProgress(userProgressDto, userId);
+    }
+
+    /// <summary>
+    /// Returns a Koreader Dto representing current book and the progress within
+    /// </summary>
+    /// <param name="bookHash"></param>
+    /// <param name="userId"></param>
+    /// <returns></returns>
+    public async Task<KoreaderBookDto> GetProgress(string bookHash, int userId)
+    {
+        var settingsDto = await _unitOfWork.SettingsRepository.GetSettingsDtoAsync();
+
+        var file = await _unitOfWork.MangaFileRepository.GetByKoreaderHash(bookHash);
+
+        if (file == null) throw new KavitaException(await _localizationService.Translate(userId, "file-missing"));
+
+        var progressDto = await _unitOfWork.AppUserProgressRepository.GetUserProgressDtoAsync(file.ChapterId, userId);
+        var koreaderProgress = KoreaderHelper.GetKoreaderPosition(progressDto);
+
+        return new KoreaderBookDtoBuilder(bookHash).WithProgress(koreaderProgress)
+            .WithPercentage(progressDto?.PageNum, file.Pages)
+            .WithDeviceId(settingsDto.InstallId, userId)
+            .Build();
+    }
+}

API/Services/Plus/KavitaPlusApiService.cs

@@ -0,0 +1,75 @@
+#nullable enable
+using System.Threading.Tasks;
+using API.DTOs.Scrobbling;
+using API.Extensions;
+using Flurl.Http;
+using Kavita.Common;
+using Microsoft.Extensions.Logging;
+
+namespace API.Services.Plus;
+
+/// <summary>
+/// All Http requests to K+ should be contained in this service, the service will not handle any errors.
+/// This is expected from the caller.
+/// </summary>
+public interface IKavitaPlusApiService
+{
+    Task<bool> HasTokenExpired(string license, string token, ScrobbleProvider provider);
+    Task<int> GetRateLimit(string license, string token);
+    Task<ScrobbleResponseDto> PostScrobbleUpdate(ScrobbleDto data, string license);
+}
+
+public class KavitaPlusApiService(ILogger<KavitaPlusApiService> logger): IKavitaPlusApiService
+{
+    private const string ScrobblingPath = "/api/scrobbling/";
+
+    public async Task<bool> HasTokenExpired(string license, string token, ScrobbleProvider provider)
+    {
+        var res = await Get(ScrobblingPath + "valid-key?provider=" + provider + "&key=" + token, license, token);
+        var str = await res.GetStringAsync();
+        return bool.Parse(str);
+    }
+
+    public async Task<int> GetRateLimit(string license, string token)
+    {
+        var res = await Get(ScrobblingPath + "rate-limit?accessToken=" + token, license, token);
+        var str = await res.GetStringAsync();
+        return int.Parse(str);
+    }
+
+    public async Task<ScrobbleResponseDto> PostScrobbleUpdate(ScrobbleDto data, string license)
+    {
+        return await PostAndReceive<ScrobbleResponseDto>(ScrobblingPath + "update", data, license);
+    }
+
+    /// <summary>
+    /// Send a GET request to K+
+    /// </summary>
+    /// <param name="url">only path of the uri, the host is added</param>
+    /// <param name="license"></param>
+    /// <param name="aniListToken"></param>
+    /// <returns></returns>
+    private static async Task<IFlurlResponse> Get(string url, string license, string? aniListToken = null)
+    {
+        return await (Configuration.KavitaPlusApiUrl + url)
+            .WithKavitaPlusHeaders(license, aniListToken)
+            .GetAsync();
+    }
+
+    /// <summary>
+    /// Send a POST request to K+
+    /// </summary>
+    /// <param name="url">only path of the uri, the host is added</param>
+    /// <param name="body"></param>
+    /// <param name="license"></param>
+    /// <param name="aniListToken"></param>
+    /// <typeparam name="T">Return type</typeparam>
+    /// <returns></returns>
+    private static async Task<T> PostAndReceive<T>(string url, object body, string license, string? aniListToken = null)
+    {
+        return await (Configuration.KavitaPlusApiUrl + url)
+            .WithKavitaPlusHeaders(license, aniListToken)
+            .PostJsonAsync(body)
+            .ReceiveJson<T>();
+    }
+}

API/Services/Tasks/Scanner/ProcessSeries.cs

@@ -880,6 +880,8 @@ public class ProcessSeries : IProcessSeries
             existingFile.FileName = Parser.Parser.RemoveExtensionIfSupported(existingFile.FilePath);
             existingFile.FilePath = Parser.Parser.NormalizePath(existingFile.FilePath);
             existingFile.Bytes = fileInfo.Length;
+            existingFile.KoreaderHash = KoreaderHelper.HashContents(existingFile.FilePath);
+
             // We skip updating DB here with last modified time so that metadata refresh can do it
         }
         else
@@ -888,6 +890,7 @@ public class ProcessSeries : IProcessSeries
             var file = new MangaFileBuilder(info.FullFilePath, info.Format, _readingItemService.GetNumberOfPages(info.FullFilePath, info.Format))
                 .WithExtension(fileInfo.Extension)
                 .WithBytes(fileInfo.Length)
+                .WithHash()
                 .Build();
             chapter.Files.Add(file);
         }

Kavita.Common/Kavita.Common.csproj

@@ -3,7 +3,7 @@
         <TargetFramework>net9.0</TargetFramework>
         <Company>kavitareader.com</Company>
         <Product>Kavita</Product>
-        <AssemblyVersion>0.8.6.15</AssemblyVersion>
+        <AssemblyVersion>0.8.6.17</AssemblyVersion>
         <NeutralLanguage>en</NeutralLanguage>
         <TieredPGO>true</TieredPGO>
     </PropertyGroup>

UI/Web/src/app/_models/scrobbling/scrobble-event.ts

@@ -7,6 +7,7 @@ export enum ScrobbleEventType {
 }
 
 export interface ScrobbleEvent {
+  id: number;
   seriesName: string;
   seriesId: number;
   libraryId: number;

UI/Web/src/app/_services/scrobbling.service.ts

@@ -104,6 +104,10 @@ export class ScrobblingService {
 
   triggerScrobbleEventGeneration() {
     return this.httpClient.post(this.baseUrl + 'scrobbling/generate-scrobble-events', TextResonse);
+  }
+
+  bulkRemoveEvents(eventIds: number[]) {
+    return this.httpClient.post(this.baseUrl + "scrobbling/bulk-remove-events", eventIds)
+  }
 
 }
-}

UI/Web/src/app/_single-module/user-scrobble-history/user-scrobble-history.component.html

@@ -20,7 +20,10 @@
     <form [formGroup]="formGroup">
       <div class="form-group pe-1">
         <label for="filter">{{t('filter-label')}}</label>
-        <input id="filter" type="text" class="form-control" formControlName="filter" autocomplete="off"/>
+        <div class="input-group">
+          <input id="filter" type="text" class="form-control" formControlName="filter" autocomplete="off" [placeholder]="t('filter-label')"/>
+          <button class="btn btn-primary" type="button" [disabled]="!selections.hasAnySelected()" (click)="bulkDelete()">{{t('delete-selected-label')}}</button>
+        </div>
       </div>
     </form>
   </div>
@@ -40,6 +43,20 @@
     [sorts]="[{prop: 'createdUtc', dir: 'desc'}]"
   >
 
+    <ngx-datatable-column prop="select" [sortable]="false" [draggable]="false" [resizeable]="false" [width]="50">
+      <ng-template let-column="column" ngx-datatable-header-template>
+        <div class="form-check">
+          <input id="select-all" type="checkbox" class="form-check-input"
+                 [ngModel]="selectAll" (change)="toggleAll()" [indeterminate]="selections.hasSomeSelected()">
+          <label for="select-all" class="form-check-label d-md-block d-none">{{t('select-all-label')}}</label>
+        </div>
+      </ng-template>
+      <ng-template let-event="row" let-idx="index" ngx-datatable-cell-template>
+        <input id="select-event-{{idx}}" type="checkbox" class="form-check-input"
+               [ngModel]="selections.isSelected(event)" (change)="handleSelection(event, idx)">
+      </ng-template>
+    </ngx-datatable-column>
+
     <ngx-datatable-column prop="createdUtc" [sortable]="true" [draggable]="false" [resizeable]="false">
       <ng-template let-column="column" ngx-datatable-header-template>
         {{t('created-header')}}
@@ -101,7 +118,7 @@
       </ng-template>
     </ngx-datatable-column>
 
-    <ngx-datatable-column prop="isPorcessed" [sortable]="true" [draggable]="false" [resizeable]="false">
+    <ngx-datatable-column prop="isProcessed" [sortable]="true" [draggable]="false" [resizeable]="false">
       <ng-template let-column="column" ngx-datatable-header-template>
         {{t('is-processed-header')}}
       </ng-template>

UI/Web/src/app/_single-module/user-scrobble-history/user-scrobble-history.component.ts

@@ -1,4 +1,12 @@
-import {ChangeDetectionStrategy, ChangeDetectorRef, Component, DestroyRef, inject, OnInit} from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  ChangeDetectorRef,
+  Component,
+  DestroyRef,
+  HostListener,
+  inject,
+  OnInit
+} from '@angular/core';
 
 import {ScrobbleProvider, ScrobblingService} from "../../_services/scrobbling.service";
 import {takeUntilDestroyed} from "@angular/core/rxjs-interop";
@@ -9,7 +17,7 @@ import {ScrobbleEventSortField} from "../../_models/scrobbling/scrobble-event-fi
 import {debounceTime, take} from "rxjs/operators";
 import {PaginatedResult} from "../../_models/pagination";
 import {SortEvent} from "../table/_directives/sortable-header.directive";
-import {FormControl, FormGroup, ReactiveFormsModule} from "@angular/forms";
+import {FormControl, FormGroup, FormsModule, ReactiveFormsModule} from "@angular/forms";
 import {translate, TranslocoModule} from "@jsverse/transloco";
 import {DefaultValuePipe} from "../../_pipes/default-value.pipe";
 import {TranslocoLocaleModule} from "@jsverse/transloco-locale";
@@ -19,6 +27,7 @@ import {ColumnMode, NgxDatatableModule} from "@siemens/ngx-datatable";
 import {AsyncPipe} from "@angular/common";
 import {AccountService} from "../../_services/account.service";
 import {ToastrService} from "ngx-toastr";
+import {SelectionModel} from "../../typeahead/_models/selection-model";
 
 export interface DataTablePage {
   pageNumber: number,
@@ -30,7 +39,7 @@ export interface DataTablePage {
 @Component({
     selector: 'app-user-scrobble-history',
   imports: [ScrobbleEventTypePipe, ReactiveFormsModule, TranslocoModule,
-    DefaultValuePipe, TranslocoLocaleModule, UtcToLocalTimePipe, NgbTooltip, NgxDatatableModule, AsyncPipe],
+    DefaultValuePipe, TranslocoLocaleModule, UtcToLocalTimePipe, NgbTooltip, NgxDatatableModule, AsyncPipe, FormsModule],
     templateUrl: './user-scrobble-history.component.html',
     styleUrls: ['./user-scrobble-history.component.scss'],
     changeDetection: ChangeDetectionStrategy.OnPush
@@ -48,8 +57,6 @@ export class UserScrobbleHistoryComponent implements OnInit {
   private readonly toastr = inject(ToastrService);
   protected readonly accountService = inject(AccountService);
 
-
-
   tokenExpired = false;
   formGroup: FormGroup = new FormGroup({
     'filter': new FormControl('', [])
@@ -68,6 +75,21 @@ export class UserScrobbleHistoryComponent implements OnInit {
   };
   hasRunScrobbleGen: boolean = false;
 
+  selections: SelectionModel<ScrobbleEvent> = new SelectionModel();
+  selectAll: boolean = false;
+  isShiftDown: boolean = false;
+  lastSelectedIndex: number | null = null;
+
+  @HostListener('document:keydown.shift', ['$event'])
+  handleKeypress(_: KeyboardEvent) {
+    this.isShiftDown = true;
+  }
+
+  @HostListener('document:keyup.shift', ['$event'])
+  handleKeyUp(_: KeyboardEvent) {
+    this.isShiftDown = false;
+  }
+
   ngOnInit() {
 
     this.pageInfo.pageNumber = 0;
@@ -118,6 +140,7 @@ export class UserScrobbleHistoryComponent implements OnInit {
       .pipe(take(1))
       .subscribe((result: PaginatedResult<ScrobbleEvent[]>) => {
       this.events = result.result;
+      this.selections = new SelectionModel(false, this.events);
 
       this.pageInfo.totalPages = result.pagination.totalPages - 1; // ngx-datatable is 0 based, Kavita is 1 based
       this.pageInfo.size = result.pagination.itemsPerPage;
@@ -143,4 +166,55 @@ export class UserScrobbleHistoryComponent implements OnInit {
       this.toastr.info(translate('toasts.scrobble-gen-init'))
     });
   }
+
+  bulkDelete() {
+    if (!this.selections.hasAnySelected()) {
+      return;
+    }
+
+    const eventIds = this.selections.selected().map(e => e.id);
+
+    this.scrobblingService.bulkRemoveEvents(eventIds).subscribe({
+      next: () => {
+        this.events = this.events.filter(e => !eventIds.includes(e.id));
+        this.selectAll = false;
+        this.selections.clearSelected();
+        this.pageInfo.totalElements -= eventIds.length;
+        this.cdRef.markForCheck();
+      },
+      error: err => {
+        console.error(err);
+      }
+    });
+  }
+
+  toggleAll() {
+    this.selectAll = !this.selectAll;
+    this.events.forEach(e => this.selections.toggle(e, this.selectAll));
+    this.cdRef.markForCheck();
+  }
+
+  handleSelection(item: ScrobbleEvent, index: number) {
+    if (this.isShiftDown && this.lastSelectedIndex !== null) {
+      // Bulk select items between the last selected item and the current one
+      const start = Math.min(this.lastSelectedIndex, index);
+      const end = Math.max(this.lastSelectedIndex, index);
+
+      for (let i = start; i <= end; i++) {
+        const event = this.events[i];
+        if (!this.selections.isSelected(event, (e1, e2) => e1.id == e2.id)) {
+          this.selections.toggle(event, true);
+        }
+      }
+    } else {
+      this.selections.toggle(item);
+    }
+
+    this.lastSelectedIndex = index;
+
+
+    const numberOfSelected = this.selections.selected().length;
+    this.selectAll = numberOfSelected === this.events.length;
+    this.cdRef.markForCheck();
+  }
 }

UI/Web/src/app/admin/manage-scrobble-errors/manage-scrobble-errors.component.html

@@ -8,7 +8,7 @@
         <label for="filter" class="visually-hidden">{{t('filter-label')}}</label>
         <div class="input-group">
           <input id="filter" type="text" class="form-control" [placeholder]="t('filter-label')" formControlName="filter" />
-          <button class="btn btn-primary" type="button" (click)="clear()">{{t('clear-errors')}}</button>
+          <button class="btn btn-primary" type="button" [disabled]="data.length === 0" (click)="clear()">{{t('clear-errors')}}</button>
         </div>
       </div>
     </div>

UI/Web/src/app/typeahead/_models/selection-model.ts

@@ -70,6 +70,28 @@ export class SelectionModel<T> {
     return (selectedCount !== this._data.length && selectedCount !== 0)
   }
 
+  /**
+   * @return If at least one item is selected
+   */
+  hasAnySelected(): boolean {
+    for (const d of this._data) {
+      if (d.selected) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Marks every data entry has not selected
+   */
+  clearSelected() {
+    this._data = this._data.map(d => {
+      d.selected = false;
+      return d;
+    });
+  }
+
   /**
    *
    * @returns All Selected items

UI/Web/src/assets/langs/en.json

@@ -42,6 +42,8 @@
         "series-header": "Series",
         "data-header": "Data",
         "is-processed-header": "Is Processed",
+        "select-all-label": "Select all",
+        "delete-selected-label": "Delete selected",
         "no-data": "{{common.no-data}}",
         "volume-and-chapter-num": "Volume {{v}} Chapter {{n}}",
         "volume-num": "Volume {{num}}",

openapi.json

@@ -2,12 +2,12 @@
   "openapi": "3.0.4",
   "info": {
     "title": "Kavita",
-    "description": "Kavita provides a set of APIs that are authenticated by JWT. JWT token can be copied from local storage. Assume all fields of a payload are required. Built against v0.8.6.14",
+    "description": "Kavita provides a set of APIs that are authenticated by JWT. JWT token can be copied from local storage. Assume all fields of a payload are required. Built against v0.8.6.15",
     "license": {
       "name": "GPL-3.0",
       "url": "https://github.com/Kareadita/Kavita/blob/develop/LICENSE"
     },
-    "version": "0.8.6.14"
+    "version": "0.8.6.15"
   },
   "servers": [
     {
@@ -2991,6 +2991,139 @@
         }
       }
     },
+    "/api/Koreader/{apiKey}/users/auth": {
+      "get": {
+        "tags": [
+          "Koreader"
+        ],
+        "parameters": [
+          {
+            "name": "apiKey",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/api/Koreader/{apiKey}/syncs/progress": {
+      "put": {
+        "tags": [
+          "Koreader"
+        ],
+        "summary": "Syncs book progress with Kavita. Will attempt to save the underlying reader position if possible.",
+        "parameters": [
+          {
+            "name": "apiKey",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KoreaderBookDto"
+              }
+            },
+            "text/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KoreaderBookDto"
+              }
+            },
+            "application/*+json": {
+              "schema": {
+                "$ref": "#/components/schemas/KoreaderBookDto"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderProgressUpdateDto"
+                }
+              },
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderProgressUpdateDto"
+                }
+              },
+              "text/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderProgressUpdateDto"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/Koreader/{apiKey}/syncs/progress/{ebookHash}": {
+      "get": {
+        "tags": [
+          "Koreader"
+        ],
+        "summary": "Gets book progress from Kavita, if not found will return a 400",
+        "parameters": [
+          {
+            "name": "apiKey",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "ebookHash",
+            "in": "path",
+            "description": "",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderBookDto"
+                }
+              },
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderBookDto"
+                }
+              },
+              "text/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/KoreaderBookDto"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/Library/create": {
       "post": {
         "tags": [
@@ -21027,6 +21160,54 @@
         },
         "additionalProperties": false
       },
+      "KoreaderBookDto": {
+        "type": "object",
+        "properties": {
+          "document": {
+            "type": "string",
+            "description": "This is the Koreader hash of the book. It is used to identify the book.",
+            "nullable": true
+          },
+          "device_id": {
+            "type": "string",
+            "description": "A randomly generated id from the koreader device. Only used to maintain the Koreader interface.",
+            "nullable": true
+          },
+          "device": {
+            "type": "string",
+            "description": "The Koreader device name. Only used to maintain the Koreader interface.",
+            "nullable": true
+          },
+          "percentage": {
+            "type": "number",
+            "description": "Percent progress of the book. Only used to maintain the Koreader interface.",
+            "format": "float"
+          },
+          "progress": {
+            "type": "string",
+            "description": "An XPath string read by Koreader to determine the location within the epub.\nEssentially, it is Koreader's equivalent to ProgressDto.BookScrollId.",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "This is the interface for receiving and sending updates to Koreader. The only fields\nthat are actually used are the Document and Progress fields."
+      },
+      "KoreaderProgressUpdateDto": {
+        "type": "object",
+        "properties": {
+          "document": {
+            "type": "string",
+            "description": "This is the Koreader hash of the book. It is used to identify the book.",
+            "nullable": true
+          },
+          "timestamp": {
+            "type": "string",
+            "description": "UTC Timestamp to return to KOReader",
+            "format": "date-time"
+          }
+        },
+        "additionalProperties": false
+      },
       "LanguageDto": {
         "required": [
           "isoCode",
@@ -21522,6 +21703,11 @@
             "description": "Absolute path to the archive file",
             "nullable": true
           },
+          "koreaderHash": {
+            "type": "string",
+            "description": "A hash of the document using Koreader's unique hashing algorithm",
+            "nullable": true
+          },
           "pages": {
             "type": "integer",
             "description": "Number of pages for the given file",
@@ -27661,6 +27847,10 @@
       "name": "Image",
       "description": "Responsible for servicing up images stored in Kavita for entities"
     },
+    {
+      "name": "Koreader",
+      "description": "The endpoint to interface with Koreader's Progress Sync plugin."
+    },
     {
       "name": "Manage",
       "description": "All things centered around Managing the Kavita instance, that isn't aligned with an entity"