A sync service to get your listening progress from Audiobookshelf into bookhive
README.md

abs-to-bookhive #

A sync service that moves your listening progress from Audiobookshelf (ABS) to your account on BookHive.

It's a companion service, deployed on its own. By getting access to your account on both systems, it can provide the sync.

The current idea is to use the KOSync feature in BookHive to sync the information with — this allows the user to match the correct books inside of BookHive, instead of this sync service needing to match the exact identifiers for each audiobook.

Work in progress.

Development #

The environment is defined in devenv.nix and pinned by devenv.lock; it provides Node 24, pnpm 12, and SQLite.

devenv shell
pnpm install
cp .env.example .env
pnpm dev

With direnv, direnv allow activates it automatically. devenv up starts the dev server. The app is served on http://localhost:3000.

Lexicons #

The ATProto endpoints used here are described by Lexicon schemas. Two things are kept apart:

  • lexicons.json and lexicons/ are committed. The manifest pins the CID of every installed Lexicon (like a lockfile) and the directory vendors the JSON documents, so pnpm install and pnpm build never need the ATProto network to resolve them. lexicons/ is generated output from lex install, but small and pinned, so it belongs in the repository.
  • server/lexicons/ (the generated TypeScript schemas and validators) is not committed and is gitignored. postinstall, predev and prebuild regenerate it with pnpm lex:build, so it always matches the JSON it was built from.
Script Purpose
pnpm lex:build Regenerate server/lexicons/ from lexicons/. Runs automatically on install and before dev/build.
pnpm lex:check Fail when lexicons/ does not match the CIDs in lexicons.json. Runs in CI on every push and pull request.
pnpm lex:update Re-resolve the pinned Lexicons from the network and rewrite lexicons.json + lexicons/. Commit the result.
pnpm lex:drift lex:update followed by a diff: fails when upstream published a newer Lexicon version. Runs in CI on every push and pull request, so a failure there means the lockfile is stale.

To add a Lexicon, run pnpm exec lex install <nsid> and commit both lexicons.json and lexicons/.

Container #

docker compose up --build

The image runs the Nitro node server and stores SQLite data in /app/.data (mounted as a volume by docker-compose.yml).

Releases publish multi-architecture images to ATCR (linux/amd64 and linux/arm64). Pulls need authentication, so docker login atcr.io (or the credential helper) first:

docker run --rm -p 3000:3000 atcr.io/maybeanerd.com/abs-to-bookhive:latest

/api/health answers 200 with {"status":"ok","database":"ok",…} after a real read of the SQLite file, and 503 with "status":"degraded" when the database cannot be read, so the image's HEALTHCHECK (and docker compose ps) turns red on an unwritable or unmigrated volume instead of letting every sync fail quietly.

Configuration #

.env.example lists the settings. Copy it to .env and fill it in:

cp .env.example .env

Every value is read through Nuxt's runtime config, so the same names work as plain environment variables in a container; docker-compose.yml passes .env through env_file. .env is gitignored. The server validates the settings it needs at startup and refuses to boot when they are unusable, so a container with a bad configuration stays unhealthy instead of failing on the first request.

Network targets #

The service fetches the Audiobookshelf and BookHive URLs a user enters, so it only talks to public destinations: loopback, private (RFC 1918 and IPv6 ULA), link-local (including cloud metadata at 169.254.169.254), multicast and reserved addresses are refused, and a hostname is rejected when any of its DNS answers is. Redirects are re-checked hop by hop.

An Audiobookshelf on the LAN or on the same host is a normal setup, so set NUXT_ALLOW_PRIVATE_TARGETS=true to allow private and loopback targets. Link-local and metadata addresses stay blocked either way.

The connection tests and the save endpoint share a per-account budget of 5 outbound attempts per minute, so a deployment cannot be turned into a network probe.