Release 0.5.0 (#46)

* Add incremental scheduler (#43)

* feat(update-cache): incremental updates — add last_updated, TTL, and isStale; update only stale/missing entries; add tests and utils
* docs(env): unify cache TTL env var to CACHE_TTL (seconds), remove duplicate vars

* feat: replace JSON file cache with SQLite persistent storage (#44)

* Add filmaffinity rating badges to posters image overlay (#45)

* feat(ui): add poster badge in films and series when you starts service schedule in docker

* fix: now download badge of series correctly and add schedule script for compose

Author: Cruzadera

.env.example

@@ -46,3 +46,27 @@ SYNC_JELLYFIN_FORCE=false
 SYNC_JELLYFIN_PAGE_SIZE=100
 # Comma-separated include types for iteration: Movie,Series,Episode
 SYNC_JELLYFIN_INCLUDE_ITEM_TYPES=Movie
+
+# Poster badge rendering (works for web, TV and mobile clients because poster is replaced server-side)
+# Enable poster processing and upload back to Jellyfin.
+ENABLE_POSTER_BADGES=false
+# Badge position: top-right, top-left, bottom-right, bottom-left
+POSTER_BADGE_POSITION=top-right
+# Badge width ratio relative to poster width (recommended 0.12 - 0.35)
+POSTER_BADGE_SIZE=0.2
+
+# Incremental cache updater tuning
+# Default TTL for cache entries that are not recent. The canonical variable is
+# `CACHE_TTL` (seconds, existing above). If you prefer days, set `CACHE_TTL` to
+# the equivalent number of seconds (e.g. 30 days = 2592000).
+# RECENT_TTL_DAYS controls the TTL (days) for recent releases (more frequent refresh)
+RECENT_TTL_DAYS=7
+# Number of years considered "recent" (used to apply RECENT_TTL_DAYS)
+RECENT_YEARS=2
+# Milliseconds to wait between individual FilmAffinity requests (scraping).
+# Increase to lower scraping load and reduce rate-limit risk.
+REQUEST_DELAY_MS=5000
+ 
+# Path to SQLite DB file used for persistent ratings storage
+# Relative to project root, e.g. `data/ratings.db`
+DB_PATH=data/ratings.db

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 .env
-.cache
+.cache
+data/ratings.json
+data/ratings.db

DOCKER.md

@@ -27,6 +27,9 @@ Environment variables reference
 - `JELLYFIN_BASE_URL`: your Jellyfin base URL (e.g. `http://192.168.1.31:8096`).
 - `JELLYFIN_API_KEY`: your Jellyfin API key.
 - `JELLYFIN_AUTH_MODE`: auth mode for Jellyfin client (`auto`|`header`|`query`).
+- `ENABLE_POSTER_BADGES`: enable FilmAffinity badge overlay and poster upload (`true`/`false`, default `false`).
+- `POSTER_BADGE_POSITION`: badge position (`top-right` default, also `top-left`, `bottom-right`, `bottom-left`).
+- `POSTER_BADGE_SIZE`: badge width ratio relative to poster width (default `0.2`).
 - `PUPPETEER_EXECUTABLE_PATH` : optional — set only if you want to use a system-installed Chromium.
 - `DEBUG_SCREENSHOTS` : set to `true` to persist debug screenshots under the `data/` folder inside the container (disabled by default).
 

README.md

@@ -12,7 +12,7 @@
 ## 🚀 Features
 
 * 🎯 Reliable scraping using **Puppeteer + Stealth Plugin**
-* 💾 Daily-generated local cache (`data/ratings.json`)
+* 💾 Persistent SQLite storage (`data/ratings.db`) with in-memory NodeCache layer
 * ⚡ Fast in-memory caching with NodeCache
 * 🔌 Simple REST API endpoint: `/movie?title=...&year=...`
 * 🔗 Direct integration support with Jellyfin API
@@ -85,33 +85,31 @@ curl "http://localhost:3000/movie?title=Inception&year=2010"
 
 ## 🐳 Docker
 
-See [DOCKER.md](DOCKER.md) for build and run instructions using Docker and Docker Compose.
+See [DOCKER.md](DOCKER.md) for build and runtime details.
 
 **Published image**
 
-Official images are published to GitHub Container Registry at `ghcr.io/cruzadera/filmaffinity-scores` by CI. To pull:
+Official images are published to GitHub Container Registry at `ghcr.io/cruzadera/filmaffinity-scores` by CI.
 
 ```bash
 docker pull ghcr.io/cruzadera/filmaffinity-scores:latest
 ```
 
-## ⏰ Scheduler service
-
-The `docker-compose.yml` includes a `scheduler` service that performs an initial full library cache population by running `node src/scripts/updateCache.js` on startup, then runs the same update once per day. The scheduler shares the `./data` volume so the generated `data/ratings.json` is persisted and available to the API container.
-
-You can control the interval with the `SLEEP_SECONDS` environment variable (default `86400` seconds = 24h). To run the scheduler with Docker Compose:
+Run scheduler only:
 
 ```bash
 docker compose up -d scheduler
 ```
 
-Or start the full stack (API + scheduler):
+The scheduler runs `updateCache` and then `sync-jellyfin` on startup and each cycle, so poster badges are updated automatically when enabled.
+It is implemented in `scripts/scheduler.js` and can force the first sync pass on startup to fill missing poster badges.
+
+Run full stack:
 
 ```bash
 docker compose up -d
 ```
 
-
 ---
 
 ## 🔗 Integrations
@@ -121,168 +119,71 @@ This service is designed to work with:
 * Jellyfin
 * Jellyseerr
 
-Future integrations may include:
-
-* Kodi
-* Plex
-
 ---
 
-## 🔌 Jellyfin integration (client)
-
-This project includes a reusable Jellyfin API client at [src/services/jellyfinClient.js](src/services/jellyfinClient.js). The client is configurable via constructor options or environment variables and supports both API key header auth and query-based `ApiKey` authentication.
+## 🔌 Jellyfin Sync + Poster Badges
 
-- File: [src/services/jellyfinClient.js](src/services/jellyfinClient.js)
+Main scripts:
 
-Environment variables (or pass as options):
+* `scripts/scheduler.js` (scheduler loop: cache + sync)
+* `scripts/sync-jellyfin.js` (recommended)
+* `src/scripts/updateJellyfin.js` (legacy updater)
 
-- `JELLYFIN_BASE_URL`: base URL of your Jellyfin server (e.g. `http://192.168.1.31:8096`)
-- `JELLYFIN_API_KEY`: Jellyfin API key
-- `JELLYFIN_TIMEOUT`: request timeout in milliseconds (optional)
-- `JELLYFIN_AUTH_MODE`: authentication mode (`auto`|`header`|`query`) — default is `auto`
+Required env vars:
 
-### Jellyfin configuration via environment variables
-
-You can configure the Jellyfin integration purely via environment variables. The application validates required values and will fail with a clear message if they are missing when strict validation is used (for example by scripts).
-
-- `JELLYFIN_BASE_URL` (required): base URL of your Jellyfin server (e.g. `http://192.168.1.31:8096`).
-- `JELLYFIN_API_KEY` (required): Jellyfin API key.
-- `JELLYFIN_USER_ID` (optional): a Jellyfin user id to scope queries.
-- `JELLYFIN_AUTH_MODE` (optional): `auto`|`header`|`query` (default `auto`).
-- `JELLYFIN_TIMEOUT` (optional): request timeout in milliseconds.
-
-Examples:
-
-Set values in a `.env` file or export them before running scripts:
-
-```bash
-JELLYFIN_BASE_URL=http://192.168.1.31:8096
-JELLYFIN_API_KEY=your_api_key_here
-```
+* `JELLYFIN_BASE_URL`
+* `JELLYFIN_API_KEY`
 
-The sync and updater scripts use a centralized config helper which will throw a helpful error if `JELLYFIN_BASE_URL` or `JELLYFIN_API_KEY` are not set when strict validation is requested.
+Optional env vars:
 
-### Setup Jellyfin API key
+* `JELLYFIN_AUTH_MODE`: `auto` | `header` | `query`
+* `SYNC_JELLYFIN_DRY_RUN`: `true`/`false`
+* `SYNC_JELLYFIN_FORCE_ON_STARTUP`: `true`/`false` (default `true`, used by `scripts/scheduler.js`)
+* `SYNC_JELLYFIN_BATCH_SIZE`, `SYNC_JELLYFIN_DELAY_MS`, `SYNC_JELLYFIN_RETRIES`, `SYNC_JELLYFIN_RETRY_DELAY`
+* `SYNC_JELLYFIN_PAGE_SIZE`, `SYNC_JELLYFIN_LIMIT`, `SYNC_JELLYFIN_INCLUDE_ITEM_TYPES`
 
-To allow this service to update your Jellyfin metadata you need an API key (token) from your Jellyfin server:
+Notes:
 
-1. Log in to Jellyfin web UI with an account that can create API keys (your personal user is fine).
-2. Open the user menu (top-right) and click your username, or go to **Dashboard → Users** and select your user.
-3. Find the **API Keys** or **API Keys / Manage API Keys** section and create a new key (give it a name like `filmaffinity-sync`).
-4. Copy the generated token and store it securely. Use it as the value for `JELLYFIN_API_KEY`.
+* Leave `SYNC_JELLYFIN_LIMIT` empty to process without limit.
 
-If you prefer to use query-based auth, set `JELLYFIN_AUTH_MODE=query` and the library will send the token as `ApiKey` query parameter.
+Poster badge env vars:
 
-### Example workflows
+* `ENABLE_POSTER_BADGES`: `true`/`false` (default `false`)
+* `POSTER_BADGE_POSITION`: `top-right` (default), `top-left`, `bottom-right`, `bottom-left`
+* `POSTER_BADGE_SIZE`: badge width ratio relative to poster width (default `0.2`)
 
-1) Dry-run to preview changes (recommended first):
+Example dry-run:
 
 ```bash
-JELLYFIN_BASE_URL=http://192.168.1.31:8096 \
-JELLYFIN_API_KEY=xxxxxx \
 LOG_LEVEL=debug \
 SYNC_JELLYFIN_DRY_RUN=true \
-  node scripts/sync-jellyfin.js --limit=5 --batch-size=2
+ENABLE_POSTER_BADGES=true \
+node scripts/sync-jellyfin.js --limit=5 --batch-size=2
 ```
 
-2) Apply a small real run (careful):
+Apply updates:
 
 ```bash
-JELLYFIN_BASE_URL=http://192.168.1.31:8096 \
-JELLYFIN_API_KEY=xxxxxx \
+LOG_LEVEL=debug \
 SYNC_JELLYFIN_DRY_RUN=false \
-  node scripts/sync-jellyfin.js --limit=10 --batch-size=3
+ENABLE_POSTER_BADGES=true \
+POSTER_BADGE_POSITION=top-right \
+POSTER_BADGE_SIZE=0.2 \
+node scripts/sync-jellyfin.js --limit=20 --batch-size=2
 ```
 
-3) Sync only Series and use a page-size tuning example:
-
-```bash
-JELLYFIN_BASE_URL=http://192.168.1.31:8096 \
-JELLYFIN_API_KEY=xxxxxx \
-node scripts/sync-jellyfin.js --include-item-types=Series --page-size=50 --limit=50
-```
-
-Notes:
-
-- Start with a dry-run and small `--limit` to confirm payloads look correct.
-- Use `SYNC_JELLYFIN_BATCH_SIZE` and `SYNC_JELLYFIN_DELAY_MS` to tune concurrency and avoid overloading your Jellyfin server.
-- If you get `401` errors, try `JELLYFIN_AUTH_MODE=query`.
-
-
-Auth behaviour:
-
-- `auto` (default): the client sends the recommended `Authorization: MediaBrowser Token="..."` header and will retry once using the `ApiKey` query parameter if the server responds `401`.
-- `header`: always use the `Authorization: MediaBrowser ...` header.
-- `query`: always use the `ApiKey` query parameter and do not send the header.
-
-Basic usage example (prefer query mode for API key-only setups):
-
-```javascript
-const JellyfinClient = require('./src/services/jellyfinClient');
+Poster processing module:
 
-const client = new JellyfinClient({
-  baseUrl: process.env.JELLYFIN_BASE_URL,
-  apiKey: process.env.JELLYFIN_API_KEY,
-  authMode: 'query', // 'auto' | 'header' | 'query'
-});
-
-async function demo() {
-  const users = await client.getUsers();
-  console.log('Users:', users);
-
-  const items = await client.getItems({ Limit: 10 });
-  console.log('Items:', items);
-}
-
-demo().catch(console.error);
-```
-
-## 🔁 Update Jellyfin metadata from FilmAffinity
-
-This project includes a helper script to update Jellyfin movie metadata with ratings retrieved from FilmAffinity. The script iterates your Jellyfin movie library, queries FilmAffinity for ratings and updates the Jellyfin item fields when necessary.
-
-Run the updater (by default it runs in dry-run mode):
-
-```bash
-npm run update-jellyfin
-```
-
-Environment variables used by the updater and the newer `sync-jellyfin` script:
-
-- `UPDATE_JELLYFIN_DRY_RUN` / `SYNC_JELLYFIN_DRY_RUN`: `true`/`false` — when `true` the script will only show the payload it would send to Jellyfin and will not perform updates. Default: `true`.
-- `UPDATE_JELLYFIN_SET_CRITIC` / `SYNC_JELLYFIN_SET_CRITIC`: `true`/`false` — when `true` the updater will also set the `CriticRating` field (optional) if available from FilmAffinity. Default: `false`.
-- `UPDATE_JELLYFIN_FORCE` / `SYNC_JELLYFIN_FORCE`: `true`/`false` — when `true` the updater will skip fetching existing metadata and forcibly apply updates. Default: `false`.
-- `UPDATE_JELLYFIN_PAGE_SIZE` / `SYNC_JELLYFIN_PAGE_SIZE`: integer — page size used when iterating items (default `50` for updater, `100` for sync script).
-- `SYNC_JELLYFIN_LIMIT`: integer — maximum number of items to process (useful for testing). Default: no limit.
-- `SYNC_JELLYFIN_BATCH_SIZE`: integer — number of concurrent tasks per batch (default `5`).
-- `SYNC_JELLYFIN_DELAY_MS`: integer — milliseconds to wait between batches (default `500`).
-- `SYNC_JELLYFIN_RETRIES`: integer — number of retries for transient operations (default `3`).
-- `SYNC_JELLYFIN_RETRY_DELAY`: integer — base retry delay in milliseconds for exponential backoff (default `1000`).
-- `SYNC_JELLYFIN_INCLUDE_ITEM_TYPES`: comma-separated list — include item types to iterate, e.g. `Movie,Series,Episode` (default `Movie`).
-
-Examples
-
-Dry-run (show payloads, do not apply updates):
-
-```bash
-LOG_LEVEL=debug SYNC_JELLYFIN_DRY_RUN=true node scripts/sync-jellyfin.js --limit=1 --batch-size=1 --page-size=1
-```
-
-Apply real updates (be careful):
-
-```bash
-LOG_LEVEL=debug SYNC_JELLYFIN_DRY_RUN=false node scripts/sync-jellyfin.js --limit=1 --batch-size=1 --page-size=1
-```
-
-Sync only Series example:
-
-```bash
-node scripts/sync-jellyfin.js --include-item-types=Series --limit=10
-```
+* `src/services/posterProcessor.js`
+* `downloadPoster(client, itemId)`
+* `generateBadge(rating, options)`
+* `applyOverlay(posterBuffer, badgeBuffer, options)`
+* `uploadPoster(client, itemId, posterBuffer)`
+* `processMoviePoster(client, movie, faData, cacheEntry, options)`
 
-Testing
+The processor stores `last_rating` and `poster_processed` in SQLite and skips regeneration when unchanged.
 
-Set `JELLYFIN_BASE_URL` and `JELLYFIN_API_KEY` in your `.env` and run:
+Testing:
 
 ```bash
 npm test

docker-compose.yml

@@ -1,5 +1,3 @@
-version: "3.8"
-
 services:
   app:
     build:
@@ -20,5 +18,4 @@ services:
     volumes:
       - ./data:/app/data
     restart: unless-stopped
-    # Run an initial full cache update, then run update once per day
-    command: sh -c "node src/scripts/updateCache.js || true; while true; do sleep ${SLEEP_SECONDS:-86400}; node src/scripts/updateCache.js || true; done"
+    command: node scripts/scheduler.js