Komga

Detalhes específicos da integração com Komga, um servidor de biblioteca de quadrinhos self-hosted. Para o modelo geral de fonte remota (dado compartilhado com o Kavita, diálogo de conexão, credenciais, decisão de ações em massa) ver Fontes Remotas; para o Kavita especificamente, ver Kavita.

Autenticação

Basic Auth (usuário + senha) ou API key, à escolha do usuário no momento de conectar. Qualquer uma das duas é cifrada e guardada como descrito em Fontes Remotas.

Organização e modo de raiz

  • Organização FOLDERS: espelha a estrutura real de pastas configurada no servidor Komga. SERIES: uma pasta por série (agrupamento lógico do Komga), arquivos soltos dentro — útil quando a organização de pastas do servidor não bate com a série real do conteúdo.
  • Modo de raiz MERGE: o conteúdo da biblioteca entra direto na raiz do acervo, junto com tudo mais. LIBRARY_FOLDER: entra dentro de uma pasta com o nome da biblioteca Komga.
  • Capas HQ (hqCovers, exclusivo do Komga, desligado por padrão): usa a página em resolução cheia como capa em vez da miniatura padrão do servidor — mais nítido, mas baixa MBs por livro e decodifica uma página inteira só pra virar miniatura; numa biblioteca grande isso pesa na rede e na CPU durante a geração de capas (ver Sistema de Capas).

Múltiplos servidores Komga podem coexistir (cada um sua própria fonte, própria credencial); dentro de um mesmo servidor, cada biblioteca selecionada tem suas próprias opções.

Cliente e endpoints

KomgaClient fala com a API REST do Komga (/api/v1/...) via HttpURLConnection simples. Os pontos usados pelo InkShelf:

  • GET /api/v1/libraries — listagem de bibliotecas, usada tanto pro fluxo de conexão quanto pelo ping leve de disponibilidade.
  • GET /api/v1/books (paginado) — catálogo de livros de uma biblioteca, consumido pelo KomgaScanner.
  • GET /api/v1/books/{id}/thumbnail e GET /api/v1/books/{id}/pages/{n} — miniatura e página em resolução cheia (esta última só quando hqCovers está ligado), usadas por ensureKomgaCover (ver Sistema de Capas).
  • PATCH /api/v1/books/{id}/read-progress — envia progresso (página + completed); DELETE /api/v1/books/{id}/read-progress — desmarca como lido. Diferente do Kavita, o Komga tem um endpoint dedicado de remoção, não precisa reenviar page=0.
  • GET/POST /api/v1/readlists, PATCH /api/v1/readlists/{id} — read lists, usadas como substituto de favoritos (ver abaixo).

Progresso de leitura

KomgaProgressSync empurra o progresso (debounce de 1200ms por livro) via PATCH read-progress; marcar como não lido chama o DELETE dedicado imediatamente, sem debounce. Ler ou marcar como lido/não lido direto no Komga volta pro InkShelf no próximo resync, com a mesma janela de graça descrita em Fontes Remotas.

Favoritos

O Komga não tem favoritos nativos por livro. O InkShelf usa uma Read List chamada "Favoritos" (ou variante reconhecida do nome) como substituto — ver o mecanismo geral em Fontes Remotas. A API de read list do Komga só tem substituição completa (PATCH reescrevendo a lista de bookIds inteira) — não existe endpoint de adicionar/remover 1 item. Por isso KomgaFavoritesSync.push sempre recalcula o conjunto completo de favoritos daquele servidor e reenvia tudo de uma vez, em vez de enviar só o delta (ao contrário do Kavita).

Download

Baixar um item Komga pra leitura offline usa KomgaDownloadService (fila serial, cancelável, notificação de 1º plano). O download falha imediatamente se o servidor não estiver acessível no início do processo, em vez de tentar e ficar preso — checagem feita antes de começar a baixar, não durante.

Sincronização de biblioteca

KomgaScanner lê bibliotecas/séries/livros do servidor e o merge com o Room segue a filosofia geral descrita em Fontes Remotas. Bibliotecas grandes rodam via KomgaSyncService (serviço de 1º plano com notificação de progresso).

Listas de Leitura

As Read Lists do Komga alimentam as Listas de Leitura do app: são importadas no fim da sincronização e as edições feitas no app voltam para o servidor (Premium). Nenhuma lista do servidor é apagada por engano — apagar no servidor só acontece com confirmação explícita.