- TypeScript 79%
- Vue 15%
- Shell 3%
- Docker 2%
- Nix <1%
- 1 more language <1%
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.jsonandlexicons/are committed. The manifest pins the CID of every installed Lexicon (like a lockfile) and the directory vendors the JSON documents, sopnpm installandpnpm buildnever need the ATProto network to resolve them.lexicons/is generated output fromlex 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,predevandprebuildregenerate it withpnpm 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.