plexsonic 0.1.2 → 0.1.4

package/.env.example

@@ -10,6 +10,7 @@ TOKEN_ENC_KEY=
 PLEX_PRODUCT=Plexsonic Bridge
 # Stable client identifier recommended for Plex PIN flow.
 PLEX_CLIENT_IDENTIFIER=
+PLEX_WEBHOOK_TOKEN=
 LICENSE_EMAIL=
 PLEX_INSECURE_TLS=0
 LOG_LEVEL=warn

package/README.md

@@ -57,6 +57,7 @@ SESSION_SECRET=replace-with-a-long-random-secret
 TOKEN_ENC_KEY=
 PLEX_PRODUCT=Plexsonic Bridge
 PLEX_CLIENT_IDENTIFIER=
+PLEX_WEBHOOK_TOKEN=
 LICENSE_EMAIL=
 PLEX_INSECURE_TLS=0
 LOG_LEVEL=warn
@@ -68,10 +69,11 @@ LOG_REQUESTS=0
 - `PORT`: HTTP port (default `3127`).
 - `BIND_HOST`: listen interface (`127.0.0.1` local only, `0.0.0.0` for LAN).
 - `BASE_URL`: optional public URL override used for callback generation. If empty, origin is derived from request headers.
+- `PLEX_WEBHOOK_TOKEN`: optional shared secret for `/webhooks/plex`. If set, webhook calls must provide this token.
 - `SESSION_SECRET`: cookie/session signing secret. Keep stable across restarts.
 - `TOKEN_ENC_KEY`: optional but recommended 32-byte key (hex or base64) used to encrypt stored Plex tokens.
 - `LOG_LEVEL`: logger level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`).
-- `LOG_REQUESTS`: set to `1` to enable incoming request logs. Very verbose, and can expose your login credeitial. (`0` by default).
+- `LOG_REQUESTS`: set to `1` to enable incoming request logs. Very verbose, and can expose login credentials. (`0` by default).
 
 Generate secrets (examples):
 
@@ -166,6 +168,18 @@ Both endpoint styles are accepted:
 - `/rest/getArtists.view`
 - `/rest/getArtists`
 
+### Star/Like Mapping (Plex)
+
+Plexsonic maps Subsonic rating + star state into a single Plex numeric rating:
+- Odd points = rated only (not liked): `1, 3, 5, 7, 9`
+- Even points = liked: `2, 4, 6, 8, 10`
+- `0` = no rating and not liked
+
+Behavior:
+- `setRating(r)` updates stars and keeps current like state when possible.
+- `star` toggles like on and keeps star level. If unrated, it becomes `2` points (liked + 1-star).
+- `unstar` toggles like off and keeps star level.
+
 ## Expose to LAN
 
 Set:
@@ -184,6 +198,22 @@ If you run behind a reverse proxy, forward `X-Forwarded-Proto` and `X-Forwarded-
 
 Without HTTPS, credentials travel unencrypted on your network.
 
+## Plex Webhooks (Optional, Recommended)
+
+Webhook purpose: Plex notifies Plexsonic on library/media events so Plexsonic can refresh caches faster and reduce stale results.
+
+Plex does not auto-discover Plexsonic. You must add the webhook URL in Plex Media Server settings.
+
+1. Open Plex Media Server settings, then `Network` -> `Webhooks`.
+2. Add your Plexsonic endpoint URL.
+Without token: `http://<your-host>:3127/webhooks/plex`
+With token: `http://<your-host>:3127/webhooks/plex?token=<PLEX_WEBHOOK_TOKEN>`
+3. Save settings in Plex.
+
+Notes:
+- `BASE_URL` is not required for webhook processing.
+- Webhook URL must be reachable by your Plex Media Server (LAN IP/hostname or public URL, depending on your setup).
+
 ## Notes
 
 - This project currently targets practical client compatibility over strict parity with any single server implementation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plexsonic",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "PlexMusic to OpenSubsonic bridge",
   "main": "./src/index.js",
   "bin": {
@@ -21,11 +21,12 @@
   "dependencies": {
     "@fastify/cookie": "^11.0.2",
     "@fastify/formbody": "^8.0.2",
-    "@fastify/session": "^11.1.0",
-    "argon2": "^0.41.1",
-    "better-sqlite3": "^11.7.2",
-    "dotenv": "^16.6.1",
-    "fastify": "^5.1.0",
+    "@fastify/multipart": "^9.4.0",
+    "@fastify/session": "^11.1.1",
+    "argon2": "^0.44.0",
+    "better-sqlite3": "^12.6.2",
+    "dotenv": "^17.2.4",
+    "fastify": "^5.7.4",
     "pino-pretty": "^13.1.3"
   },
   "pnpm": {

package/src/config.js

@@ -89,6 +89,7 @@ export function loadConfig(env = process.env) {
     plexProduct: env.PLEX_PRODUCT || DEFAULT_PLEX_PRODUCT,
     plexClientIdentifier:
       env.PLEX_CLIENT_IDENTIFIER || deriveClientIdentifier(path.resolve(sqlitePath)),
+    plexWebhookToken: env.PLEX_WEBHOOK_TOKEN || '',
     licenseEmail: env.LICENSE_EMAIL || '',
     logLevel: env.LOG_LEVEL || DEFAULT_LOG_LEVEL,
     logRequests: parseBoolean(env.LOG_REQUESTS, DEFAULT_LOG_REQUESTS),

package/src/plex.js

@@ -199,10 +199,21 @@ function extractMetadataList(container) {
 }
 
 function normalizeLibrarySection(section) {
+  const parseTimestamp = (value) => {
+    const parsed = Number.parseInt(String(value ?? ''), 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+  };
+
   return {
     id: String(section.key ?? section.id ?? ''),
     title: section.title || section.name || 'Untitled',
     type: section.type || '',
+    scanning: toBool(section.refreshing) || toBool(section.scanning),
+    updatedAt: parseTimestamp(section.updatedAt),
+    scannedAt: parseTimestamp(section.scannedAt),
+    refreshedAt: parseTimestamp(section.refreshedAt),
+    contentChangedAt: parseTimestamp(section.contentChangedAt),
+    leafCount: parseTimestamp(section.leafCount),
   };
 }
 
@@ -619,6 +630,20 @@ export async function listMusicSections({ baseUrl, plexToken }) {
     .filter((section) => section.type === 'artist' || section.type === 'music');
 }
 
+export async function startPlexSectionScan({ baseUrl, plexToken, sectionId, force = true }) {
+  await fetchPms(
+    baseUrl,
+    plexToken,
+    `/library/sections/${encodeURIComponent(sectionId)}/refresh`,
+    {
+      method: 'GET',
+      searchParams: {
+        force: force ? 1 : 0,
+      },
+    },
+  );
+}
+
 export async function listPlexSectionFolder({ baseUrl, plexToken, sectionId, folderPath = null }) {
   const path = folderPath
     ? normalizeSectionFolderPath(folderPath, sectionId)
@@ -804,6 +829,35 @@ export async function listTracks({ baseUrl, plexToken, sectionId }) {
   return extractMetadataList(payload.MediaContainer);
 }
 
+export async function probeSectionFingerprint({ baseUrl, plexToken, sectionId, signal = undefined }) {
+  const payload = await fetchPmsJson(
+    baseUrl,
+    plexToken,
+    `/library/sections/${encodeURIComponent(sectionId)}/all`,
+    {
+      type: 10,
+      sort: 'updatedAt:desc',
+      'X-Plex-Container-Start': 0,
+      'X-Plex-Container-Size': 1,
+    },
+    { signal },
+  );
+
+  const container = payload?.MediaContainer || {};
+  const firstTrack = extractMetadataList(container)[0] || {};
+  const parseIntSafe = (value) => {
+    const parsed = Number.parseInt(String(value ?? ''), 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+  };
+
+  const totalSize = parseIntSafe(container.totalSize);
+  const ratingKey = String(firstTrack.ratingKey || '');
+  const updatedAt = parseIntSafe(firstTrack.updatedAt);
+  const addedAt = parseIntSafe(firstTrack.addedAt);
+
+  return `${sectionId}|${totalSize}|${ratingKey}|${updatedAt}|${addedAt}`;
+}
+
 export async function getArtist({ baseUrl, plexToken, artistId }) {
   const payload = await fetchPmsJson(baseUrl, plexToken, `/library/metadata/${encodeURIComponent(artistId)}`);
   const item = extractMetadataList(payload.MediaContainer)[0] || null;