bookmark.md

# Multiple Playback Bookmarks Plan This feature allows users to save specific timestamps with optional notes for each audiobook in their library and return to them later. ## Progress Checklist - [x] **1. Database Layer (`packages/db`)** - [x] Create `Bookmark` entity. - [x] Create and run migration. - [x] **2. Contracts & Validation (`packages/contracts`)** - [x] Define Zod schemas (`Create`, `Update`, `Response`). - [x] Export types. - [x] **3. Backend API (`apps/api`)** - [x] Create `BookmarkController`. - [x] Implement CRUD logic (`create`, `list`, `update`, `delete`). - [x] Register `bookmarkRoutes`. - [x] **4. Frontend Integration** - [x] **API Client:** Add `bookmarks` methods to `ApiClient` in `packages/client`. - [x] **Player Context:** Update `PlayerContext` to manage bookmark state. - [x] **UI Components:** - [x] Add "Add Bookmark" button to Player. - [x] Create `BookmarkList` component. - [x] Integrate `BookmarkList` into the UI (e.g., via a modal or drawer). --- ## 1. Database Layer (`packages/db`) ### New Entity: `Bookmark` * **Fields:** * `id`: UUID (Primary Key) * `user`: Many-to-One relationship to `User` * `book`: Many-to-One relationship to `Book` * `timestamp`: Integer (position in seconds) * `label`: String (Optional, e.g., "Great quote") * `createdAt`: DateTime * `updatedAt`: DateTime ## 2. Contracts & Validation (`packages/contracts`) ### Schemas (Zod) * `CreateBookmarkRequestSchema`: Validates `bookId`, `timestamp`, and optional `label`. * `UpdateBookmarkRequestSchema`: Validates `label`. * `BookmarkResponseSchema`: Defines the standard bookmark object shape. ## 3. Backend API (`apps/api`) ### New Routes (`/api/bookmarks`) * `POST /`: Create a new bookmark (requires ownership of the book). * `GET /book/:bookId`: Fetch all bookmarks for a specific book. * `PATCH /:id`: Update bookmark label. * `DELETE /:id`: Remove a bookmark. ## 4. Frontend Integration ### API Client (`packages/client`) * Add `bookmarks` namespace to `ApiClient` for standard CRUD operations. ### Player Context (`apps/web/lib/PlayerContext.tsx`) * Manage a `bookmarks` state array for the currently playing book. * Provide `addBookmark`, `deleteBookmark`, and `loadBookmarks` methods. ### UI Components (`apps/web`) * **Player UI:** Add a "Bookmark" button next to controls to save current time. * **Bookmark List:** Create a component to display bookmarks with "Seek", "Edit", and "Delete" actions. * **Timeline Markers:** (Optional) Show visual indicators on the progress bar. ## 5. Implementation Workflow 1. User clicks the Bookmark button in the player. 2. Frontend captures `audio.currentTime` and calls `POST /api/bookmarks`. 3. The list of bookmarks is updated in the state. 4. User selects a bookmark from the list to trigger `audio.currentTime = timestamp`.