# lockstep-jukebox

Gradle project containing **jukebox**, an Android library that implements the **data layer** for a music player: it syncs playlist and track **metadata** from the Lockstep Spotify wrapper API (`https://api.lockstep.at`) into a local **SQLite** database (via Room), so the app can read playlists and tracks offline after sync.

Repository layout:

- **`jukebox/`** — Android library (Java, Retrofit, Gson, Room).
- **`docs/playlists.md`** — HTTP contract for `GET /playlists` and `GET /playlists/{id}`.
- **`schema/playlist_cache.sql`** — reference schema for the on-device cache tables.

The library does **not** handle Spotify login, audio playback, or full Spotify API modeling—only what’s needed to cache the metadata described in the docs.

## Main entry points

| Entry | Role |
| --- | --- |
| **`Jukebox.playlistRepository(Context, Interceptor)`** | Convenience factory. Builds `DefaultPlaylistRepository` with default base URL `https://api.lockstep.at/`. Optional overload passes a custom **`baseUrl`**. You supply an **`Interceptor`** so session cookies, `Authorization`, or other headers stay in the host app. |
| **`DefaultPlaylistRepository.create(...)`** | Same wiring as `Jukebox`; use when you prefer a static factory on the concrete type. |
| **`PlaylistRepository`** | Primary API surface after construction: **`syncInitial()`** (full refresh), **`syncDelta(retainRemovedPlaylists)`** (incremental sync using `snapshot_id`), **`observePlaylists()`** / **`getPlaylists()`**, **`observeTracks(playlistId)`** / **`getTracks(playlistId)`**. Sync methods **block** and perform I/O—call them off the main thread. Observation returns **`LiveData`** for lifecycle-friendly UI updates. |
| **`LockstepPlaylistClient`** | Interface implemented by **`PlaylistRemoteClient`**. Lets tests or advanced setups swap the network backend without changing **`SyncCoordinator`**. |

Errors from the API’s `{ "ok": false, "error": "..." }` shape are thrown as **`LockstepApiException`**. Network failures use **`IOException`**.

## Building

From the repo root (with `ANDROID_HOME` / `local.properties` **`sdk.dir`** set):

```bash
./gradlew :jukebox:assembleDebug
./gradlew :jukebox:testDebugUnitTest
```

On Windows, use `gradlew.bat` instead of `./gradlew`.