fix(atproto): Detect dupe rkey in batch before persist

#689

.gitignore

@@ -159,4 +159,4 @@ storybook-static
 
 bun.lock
 .DS_Store
-**/.DS_Store
+**/.DS_Store

docsite/.gitignore

@@ -18,4 +18,7 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-lib
+lib
+
+docs/api/
+static/openapi.json

docsite/docs/configuration/clients/_env_configs/_discord.md

@@ -6,7 +6,7 @@
 | `DISCORD_TOKEN`                    | string                     |                       |                                         |
 | `DISCORD_ARTWORK`                  | boolean OR string OR array |                       |                                         |
 | `DISCORD_APPLICATION_ID`           | string                     |                       |                                         |
-| `DISCORD_IPC_LOCATIONS`            | string OR array            |                       |                                         |
+| `DISCORD_IPC_LOCATIONS`            | string                     |                       |                                         |
 | `DISCORD_ARTWORK_DEFAULT_URL`      | string                     |                       |                                         |
-| `DISCORD_STATUS_OVERRIDE_ALLOW`    | string OR array            |                       |                                         |
-| `DISCORD_LISTENING_ACTIVITY_ALLOW` | string OR array            |                       |                                         |
+| `DISCORD_STATUS_OVERRIDE_ALLOW`    | string                     |                       |                                         |
+| `DISCORD_LISTENING_ACTIVITY_ALLOW` | string                     |                       |                                         |

docsite/docs/configuration/clients/_env_configs/_rocksky.md

@@ -5,4 +5,4 @@
 | `ROCKSKY_ENABLE`       | boolean | true                  | Should this component be used?                                                                                                                   |
 | `ROCKSKY_KEY`          | string  |                       | API Key generated from [API Applications](https://docs.rocksky.app/migrating-from-listenbrainz-to-rocksky-1040189m0) in Rocksky for your account |
 | `ROCKSKY_TOKEN`        | string  |                       | Access Token generated from https://rocksky.app/access-tokens in Rocksky for your account                                                        |
-| _**`ROCKSKY_HANDLE`**_ | string  |                       | The **fully-qualified** handle for your ATPRoto/Bluesky account, like:                                                                           |
+| _**`ROCKSKY_HANDLE`**_ | string  |                       | The **fully-qualified** handle for your ATPRoto/Bluesky account                                                                                  |

docsite/docs/configuration/clients/discord/discord-app.mdx

@@ -557,10 +557,12 @@ Remember, this URL need to be accessible on the public internet.
 ## Configuration
 
 <Config config="DiscordClientConfig" fileContent={JsonConfig} client name="discord">
-        | Environmental Variable        | Required? | Default | Description                                                                                                      |
-        | :---------------------------- | --------- | ------- | :--------------------------------------------------------------------------------------------------------------- |
-        | `DISCORD_APPLICATION_ID`      | Yes       |         | Application ID                                                                                                   |
-        | `DISCORD_IPC_LOCATIONS`       | No        |         | A commera-separated list of `host:port` network locations or file paths to unix socket for Discord               |
-        | `DISCORD_ARTWORK`             | No        |         | A boolean indicating if external artwork URLs should be used. Or a comma-separated list of allowed domains       |
-        | `DISCORD_ARTWORK_DEFAULT_URL` | No        |         | A URL of an image to use as a fallback if the album art URL cannot be used. Or `false` to use discord's default. |
+        | Environmental Variable         | Type              | Default               | Description                                                                                                      |
+        | :----------------------------- | ----------------- | --------------------- | :--------------------------------------------------------------------------------------------------------------- |
+        | _**`DISCORD_ID`**_             | string            |                       | A globally unique ID EX `myComponentId`                                                                          |
+        | `DISCORD_NAME`                 | string            | Value of `DISCORD_ID` | A vanity name EX `My Cool Component`                                                                             |
+        | _**`DISCORD_APPLICATION_ID`**_ | string            |                       | Application ID                                                                                                   |
+        | `DISCORD_IPC_LOCATIONS`        | string            |                       | A commera-separated list of `host:port` network locations or file paths to unix socket for Discord               |
+        | `DISCORD_ARTWORK`              | boolean           |                       | A boolean indicating if external artwork URLs should be used. Or a comma-separated list of allowed domains       |
+        | `DISCORD_ARTWORK_DEFAULT_URL`  | string or boolean |                       | A URL of an image to use as a fallback if the album art URL cannot be used. Or `false` to use discord's default. |
 </Config>

docsite/docs/configuration/clients/discord/discord-headless.mdx

@@ -323,12 +323,14 @@ The order in which multi-scrobbler determines what image to use is the same as t
 ## Configuration
 
 <Config config="DiscordClientConfig" fileContent={JsonConfig} client name="discord">
-        | Environmental Variable             | Required? | Default           | Description                                                                                                       |
-        | :--------------------------------- | --------- | ----------------- | :---------------------------------------------------------------------------------------------------------------- |
-        | `DISCORD_TOKEN`                    | Yes       |                   | User Token acquired from an active Discord sessions                                                               |
-        | `DISCORD_APPLICATION_ID`           | No        |                   | Application ID used to display album art                                                                          |
-        | `DISCORD_ARTWORK`                  | No        |                   | A boolean indicating if external artwork URLs should be used. Or a comma-separated list of allowed domains        |
-        | `DISCORD_ARTWORK_DEFAULT_URL`      | No        |                   | A URL of an image to use as a fallback if the album art URL cannot be used. Or `false` to use discord's default.  |
-        | `DISCORD_STATUS_OVERRIDE_ALLOW`    | No        | `online,idle,dnd` | A comma-separated list of statuses are allowed to have presence.                                                  |
-        | `DISCORD_LISTENING_ACTIVITY_ALLOW` | No        |                   | A commera-seperated list of listening activity names MS **is allowed** to broadcast presence at the same time as. |
+        | Environmental Variable             | Type              | Default               | Description                                                                                                       |
+        | :--------------------------------- | ----------------- | --------------------- | :---------------------------------------------------------------------------------------------------------------- |
+        | _**`DISCORD_ID`**_                 | string            |                       | A globally unique ID EX `myComponentId`                                                                           |
+        | `DISCORD_NAME`                     | string            | Value of `DISCORD_ID` | A vanity name EX `My Cool Component`                                                                              |
+        | _**`DISCORD_TOKEN`**_              | string            |                       | User Token acquired from an active Discord sessions                                                               |
+        | `DISCORD_APPLICATION_ID`           | string            |                       | Application ID used to display album art                                                                          |
+        | `DISCORD_ARTWORK`                  | boolean           |                       | A boolean indicating if external artwork URLs should be used. Or a comma-separated list of allowed domains        |
+        | `DISCORD_ARTWORK_DEFAULT_URL`      | string or boolean |                       | A URL of an image to use as a fallback if the album art URL cannot be used. Or `false` to use discord's default.  |
+        | `DISCORD_STATUS_OVERRIDE_ALLOW`    | string            | `online,idle,dnd`     | A comma-separated list of statuses are allowed to have presence.                                                  |
+        | `DISCORD_LISTENING_ACTIVITY_ALLOW` | string            |                       | A commera-seperated list of listening activity names MS **is allowed** to broadcast presence at the same time as. |
 </Config>

docsite/docs/configuration/sources/_env_configs/_rocksky.md

@@ -4,4 +4,4 @@
 | `SOURCE_ROCKSKY_NAME`         | string  | Value of `SOURCE_ROCKSKY_ID` | A vanity name EX `My Cool Component`                                                                                                             |
 | `SOURCE_ROCKSKY_ENABLE`       | boolean | true                         | Should this component be used?                                                                                                                   |
 | `SOURCE_ROCKSKY_KEY`          | string  |                              | API Key generated from [API Applications](https://docs.rocksky.app/migrating-from-listenbrainz-to-rocksky-1040189m0) in Rocksky for your account |
-| _**`SOURCE_ROCKSKY_HANDLE`**_ | string  |                              | The **fully-qualified** handle for your ATPRoto/Bluesky account, like:                                                                           |
+| _**`SOURCE_ROCKSKY_HANDLE`**_ | string  |                              | The **fully-qualified** handle for your ATPRoto/Bluesky account                                                                                  |

docsite/docusaurus.config.ts

@@ -3,6 +3,7 @@ import type { Config } from '@docusaurus/types';
 import * as themes from 'prism-react-renderer';
 import * as Renderers from './lib/socialCard/ImageRenderers.js';
 import path from 'node:path';
+import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
 //import sidebars from './sidebars';
 
 let baseSite: string = 'https://foxxmd.github.io';
@@ -32,7 +33,7 @@ const config: Config = {
     v4: {
       removeLegacyPostBuildHeadAttribute: true, // required
     },
-    experimental_faster: {
+    faster: {
       ssgWorkerThreads: true,
       rspackBundler: true, // required flag
       rspackPersistentCache: true, // new flag
@@ -75,20 +76,29 @@ const config: Config = {
     [
       'classic',
       {
+        
         docs: {
           sidebarPath: './sidebars.ts',
+          docItemComponent: "@theme/ApiItem",
           routeBasePath: '/',
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl: (params: {
-              version: string;
-              versionDocsDirPath: string;
-              docPath: string;
-              permalink: string;
-              locale: string;
-            }) => {
-              return `${path.join('https://github.com/FoxxMD/multi-scrobbler/blob/master/docsite', params.versionDocsDirPath, params.docPath)}?plain=1`;
-            }
+            version: string;
+            versionDocsDirPath: string;
+            docPath: string;
+            permalink: string;
+            locale: string;
+          }) => {
+            return `https://github.com/FoxxMD/multi-scrobbler/blob/master${path.join('/docsite', params.versionDocsDirPath, params.docPath)}?plain=1`;
+          },
+          // based on this https://github.com/facebook/docusaurus/issues/6127#issuecomment-3937124499
+          // to filter out the autogenerated api folder sidebar item
+          sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, ...args }) {
+            const items = await defaultSidebarItemsGenerator(args);
+            const filteredItems = items.filter(item => !(item.type === 'category' && item.label === 'api'));
+            return filteredItems
+          },
         },
         // blog: {
         //   showReadingTime: true,
@@ -100,7 +110,7 @@ const config: Config = {
         blog: false,
 
         theme: {
-          customCss: './src/css/custom.css',
+          customCss: ['./src/css/custom.css','./src/css/openapiBase.css','./src/css/evergreen.css'],
         },
       } satisfies Preset.Options,
     ],
@@ -122,10 +132,11 @@ const config: Config = {
         // ```
       },
     ],
-    'docusaurus-theme-github-codeblock'
+    'docusaurus-theme-github-codeblock',
+    "docusaurus-theme-openapi-docs"
   ],
   plugins: [
-          'docusaurus-plugin-sass',
+    'docusaurus-plugin-sass',
     [
       '@docusaurus/plugin-client-redirects',
       {
@@ -167,7 +178,38 @@ const config: Config = {
             'docusaurus-plugin-content-pages': Renderers.docs,
         },
       },
-    ]
+    ],
+    [
+    'docusaurus-plugin-openapi-docs',
+      {
+        id: "api", // plugin id
+        docsPluginId: "classic", // configured for preset-classic
+        config: {
+          ms: {
+            specPath: "static/openapi.json",
+            outputDir: "docs/api",
+            showInfoPage: true,
+            maskCredentials: false, // Disable credential masking in code snippets
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          } satisfies OpenApiPlugin.Options,
+        }
+      },
+    ],
+    // [
+    //   '@docusaurus/plugin-content-docs',
+    //   {
+    //     sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, ...args }) {
+    //       const items = await defaultSidebarItemsGenerator(args);
+    //       for(const i of items) {
+    //         console.log(i);
+    //       }
+    //       //const filteredItems = items.filter(item => item.type !== 'doc' || !item.id.endsWith('/index'));
+    //       //return filteredItems
+    //     },
+    //   }
+    // ]
   ],
   themeConfig:
     {
@@ -193,6 +235,11 @@ const config: Config = {
             position: 'left',
             label: 'Config Playground',
           },
+          {
+            to: 'api/multi-scrobbler-api',
+            position: 'left',
+            label: 'API',
+          },
           {
             href: 'https://github.com/foxxmd/multi-scrobbler',
             label: 'GitHub',

docsite/package.json

@@ -14,14 +14,15 @@
     "typecheck": "tsc",
     "postinstall": "patch-package",
     "previews:build-renderer": "tsc --project tsconfig.client.json || exit 0",
-    "prebuild": "npm run -s previews:build-renderer"
+    "prebuild": "npm run -s previews:build-renderer && npm run -s openapi:generate",
+    "openapi:generate": "docusaurus clean-api-docs ms && docusaurus gen-api-docs ms"
   },
   "dependencies": {
     "@bony_chops/docusaurus-og": "^1.0.3-beta.3",
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/faster": "3.9.2",
-    "@docusaurus/plugin-client-redirects": "^3.9.2",
-    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/core": "3.10.2",
+    "@docusaurus/faster": "3.10.2",
+    "@docusaurus/plugin-client-redirects": "^3.10.2",
+    "@docusaurus/preset-classic": "3.10.2",
     "@easyops-cn/docusaurus-search-local": "0.51.1",
     "@mdx-js/react": "^3.0.0",
     "ajv": "^8.18.0",
@@ -30,6 +31,7 @@
     "clsx": "^2.0.0",
     "docusaurus-plugin-sass": "^0.2.6",
     "docusaurus-theme-github-codeblock": "^2.0.2",
+    "docusaurus-theme-openapi-docs": "^5.2.0",
     "embla-carousel": "^9.0.0-rc02",
     "embla-carousel-react": "^9.0.0-rc02",
     "json5": "^2.2.3",
@@ -44,9 +46,9 @@
     "sass": "^1.97.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.9.2",
-    "@docusaurus/tsconfig": "^3.9.2",
-    "@docusaurus/types": "^3.9.2",
+    "@docusaurus/module-type-aliases": "^3.10.2",
+    "@docusaurus/tsconfig": "^3.10.2",
+    "@docusaurus/types": "^3.10.2",
     "@types/react": "^19.2.4",
     "typescript": "~5.6.2"
   },
@@ -69,6 +71,7 @@
   "overrides": {
     "lodash": "4.18.1",
     "satori": "0.25.0",
-    "hast-util-to-jsx-runtime": "2.3.6"
+    "hast-util-to-jsx-runtime": "2.3.6",
+    "sharp": "0.35.3"
   }
 }

docsite/sidebars.ts

@@ -1,5 +1,5 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
-
+import msSidebar from "./docs/api/sidebar.js";
 /**
  * Creating a sidebar enables you to:
  - create an ordered group of docs
@@ -19,21 +19,13 @@ const sidebars: SidebarsConfig = {
       type: "link",
       label: "Config Playground",
       href: "/playground"
-    }
-  ],
-
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+    },
+        {
+      type: "category",
+      label: "Api",
+      items: msSidebar,
     },
   ],
-   */
 };
 
 export default sidebars;

docsite/src/components/PlaygroundInner.tsx

@@ -11,6 +11,7 @@ import "./json-schema-viewer-styles.css";
 import "./modern-json-react-styles.css";
 import { Mode, ReactJsonEditor, createAjvValidator, type Content  } from 'modern-react-json-editor';
 import f from "ajv-formats"
+import Ajv2020 from 'ajv/dist/2020';
 import DetailsAdmo from "./AdmonitionDetails";
 
 const validator = createAjvValidator({
@@ -21,9 +22,11 @@ const validator = createAjvValidator({
         allowUnionTypes: true,
      },
     onCreateAjv: (ajv) => {
-            ajv.addKeyword('deprecationMessage');
-            f.default(ajv);
-            return ajv;
+            const a = new Ajv2020();
+            a.addKeyword('deprecationMessage');
+            a.addKeyword('zockerId');
+            f.default(a);
+            return a;
     }
 });
 

docsite/src/components/Schema/SchemaEditor.tsx

@@ -5,6 +5,7 @@ import { useColorMode } from '@docusaurus/theme-common';
 const STRINGIFY_JSON = (json: unknown) => JSON.stringify(json, null, "\t");
 import "../modern-json-react-styles.css";
 import { JSONSchema, Mode, ReactJsonEditor, createAjvValidator, type Content, type Validator } from 'modern-react-json-editor';
+import Ajv2020 from 'ajv/dist/2020';
 import f from "ajv-formats"
 import json5 from 'json5';
 
@@ -29,9 +30,11 @@ function SchemaEditorInner(props: SchemaEditorProps): JSX.Element {
                 allowUnionTypes: true,
             },
             onCreateAjv: (ajv) => {
-                ajv.addKeyword('deprecationMessage');
-                f.default(ajv);
-                return ajv;
+                const a = new Ajv2020();
+                a.addKeyword('deprecationMessage');
+                a.addKeyword('zockerId');
+                f.default(a);
+                return a;
             }
         });
     }, [props.schema]);

docsite/src/css/evergreen.css

@@ -0,0 +1,323 @@
+/**
+ * Evergreen theme for docusaurus-openapi-docs demo.
+ *
+ * A modern riff on the classic Docusaurus green. Keeps the signature
+ * #2e8555 primary family, adds Plus Jakarta Sans, a richer dark mode,
+ * and cleaner shadows — what the default template could look like with
+ * a bit more design polish.
+ *
+ * Load alongside custom.css in docusaurus.config.ts:
+ *
+ *   customCss: ["./src/css/custom.css", "./src/css/themes/evergreen.css"]
+ */
+
+/* ============================================================
+ * Fonts — Plus Jakarta Sans (body) + Fira Code (code)
+ * ============================================================ */
+
+@import url("https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap");
+@import url("https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&display=swap");
+
+/* ============================================================
+ * Light mode
+ * ============================================================ */
+
+:root {
+  /* Primary — the classic Docusaurus green, slightly enriched */
+  /* --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e; */
+
+  /* Content */
+  /* --ifm-color-content: #1c1e21;
+  --ifm-heading-color: #1c1e21;
+  --ifm-color-content-secondary: #525860; */
+
+  /* Semantic */
+  /* --ifm-color-success: #2e8555;
+  --ifm-color-warning: #d97706;
+  --ifm-color-danger: #dc2626;
+  --ifm-color-info: #0284c7; */
+
+  /* Typography */
+  /* --ifm-font-size-base: 95%;
+  --ifm-code-font-size: 85%;
+  --ifm-font-family-base:
+    "Plus Jakarta Sans", ui-sans-serif, system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --ifm-heading-font-family:
+    "Plus Jakarta Sans", ui-sans-serif, system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --ifm-font-family-monospace:
+    "Fira Code", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Courier New", monospace;
+  --font-mono:
+    "Fira Code", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Courier New", monospace;
+  --ifm-font-weight-base: 400;
+  --ifm-font-weight-semibold: 600;
+  --ifm-heading-font-weight: 700; */
+
+  /* Heading scale */
+  /* --ifm-h1-font-size: 2rem;
+  --ifm-h2-font-size: 1.6rem;
+  --ifm-h3-font-size: 1.3rem;
+  --ifm-h4-font-size: 1.1rem;
+  --ifm-h5-font-size: 1rem;
+  --ifm-h6-font-size: 0.9rem; */
+
+  /* Theme hooks for custom.css */
+  --theme-primary-rgb: 46, 133, 85;
+  --site-primary-hue-saturation: 148 49%;
+  --theme-border-radius-sm: 4px;
+  --theme-border-radius-md: 8px;
+  --theme-border-radius-lg: 12px;
+  --theme-border-radius-xl: 16px;
+  --theme-border-radius-2xl: 24px;
+
+  /* Shadow scale — neutral, not green-tinted */
+  --theme-shadow-sm:
+    0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.06);
+  --theme-shadow-md:
+    0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.06);
+  --theme-shadow-lg:
+    0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.06);
+
+  /* --ifm-hr-background-color: var(--ifm-color-emphasis-200);
+  --docusaurus-highlighted-code-line-bg: rgba(46, 133, 85, 0.1); */
+
+  /* Explorer — unified font size for code tabs and request body */
+  --openapi-explorer-font-size-code: 13px;
+}
+
+/* ============================================================
+ * Dark mode — richer than the Docusaurus default
+ * ============================================================ */
+
+[data-theme="dark"] {
+  /* Lighter green — readable on dark surfaces */
+  /* --ifm-color-primary: #3cad6e;
+  --ifm-color-primary-dark: #359962;
+  --ifm-color-primary-darker: #33925d;
+  --ifm-color-primary-darkest: #2e8555;
+  --ifm-color-primary-light: #4db87c;
+  --ifm-color-primary-lighter: #5ec389;
+  --ifm-color-primary-lightest: #85d4a8; */
+
+  /* --ifm-color-content: #dadde1;
+  --ifm-color-content-secondary: #9ba1aa;
+  --ifm-heading-color: #f5f6f7; */
+
+  /* Richer dark background vs. the flat Docusaurus default */
+  /* --ifm-background-color: #18191a !important;
+  --ifm-navbar-background-color: #18191a; */
+
+  /* Warm-neutral dark gray scale */
+  /* --ifm-color-emphasis-100: #242526;
+  --ifm-color-emphasis-200: #3a3b3c;
+  --ifm-color-emphasis-300: #4e4f50;
+  --ifm-color-emphasis-400: #6b6c6d;
+  --ifm-color-emphasis-500: #8d8f91;
+  --ifm-color-emphasis-600: #b0b3b8;
+  --ifm-color-emphasis-700: #dadde1;
+  --ifm-color-emphasis-800: #e4e6eb;
+  --ifm-color-emphasis-900: #f0f2f5; */
+
+  /* --ifm-link-color: #3cad6e;
+  --ifm-link-hover-color: #5ec389; */
+
+  --docusaurus-highlighted-code-line-bg: rgba(60, 173, 110, 0.12);
+  /* --theme-primary-rgb: 60, 173, 110; */
+}
+
+/* ============================================================
+ * Method badge colors — sidebar pills
+ * ============================================================ */
+
+.get > .menu__link::before {
+  background-color: rgba(46, 133, 85, 0.12);
+  color: #29784c;
+}
+.get > .menu__link--active::before {
+  background-color: #2e8555;
+  color: #ffffff;
+}
+
+.post > .menu__link::before {
+  background-color: rgba(2, 132, 199, 0.12);
+  color: #0369a1;
+}
+.post > .menu__link--active::before {
+  background-color: #0284c7;
+  color: #ffffff;
+}
+
+.delete > .menu__link::before {
+  background-color: rgba(220, 38, 38, 0.12);
+  color: #dc2626;
+}
+.delete > .menu__link--active::before {
+  background-color: #dc2626;
+  color: #ffffff;
+}
+
+.put > .menu__link::before {
+  background-color: rgba(217, 119, 6, 0.15);
+  color: #b45309;
+}
+.put > .menu__link--active::before {
+  background-color: #d97706;
+  color: #ffffff;
+}
+
+.patch > .menu__link::before {
+  background-color: rgba(217, 119, 6, 0.15);
+  color: #b45309;
+}
+.patch > .menu__link--active::before {
+  background-color: #d97706;
+  color: #ffffff;
+}
+
+/* Dark mode */
+[data-theme="dark"] .get > .menu__link::before {
+  background-color: rgba(60, 173, 110, 0.15);
+  color: #3cad6e;
+}
+[data-theme="dark"] .get > .menu__link--active::before {
+  background-color: #3cad6e;
+  color: #18191a;
+}
+
+[data-theme="dark"] .post > .menu__link::before {
+  background-color: rgba(56, 189, 248, 0.12);
+  color: #38bdf8;
+}
+[data-theme="dark"] .post > .menu__link--active::before {
+  background-color: #0ea5e9;
+  color: #18191a;
+}
+
+[data-theme="dark"] .delete > .menu__link::before {
+  background-color: rgba(239, 68, 68, 0.12);
+  color: #f87171;
+}
+[data-theme="dark"] .delete > .menu__link--active::before {
+  background-color: #ef4444;
+  color: #ffffff;
+}
+
+[data-theme="dark"] .put > .menu__link::before {
+  background-color: rgba(251, 191, 36, 0.12);
+  color: #fbbf24;
+}
+[data-theme="dark"] .put > .menu__link--active::before {
+  background-color: #f59e0b;
+  color: #18191a;
+}
+
+[data-theme="dark"] .patch > .menu__link::before {
+  background-color: rgba(251, 191, 36, 0.12);
+  color: #fbbf24;
+}
+[data-theme="dark"] .patch > .menu__link--active::before {
+  background-color: #f59e0b;
+  color: #18191a;
+}
+
+/* ============================================================
+ * API page method badges (.badge--*)
+ * ============================================================ */
+
+.badge--primary {
+  /* GET */
+  background-color: #2e8555;
+  color: #ffffff;
+  --ifm-badge-border-color: transparent;
+}
+
+.badge--success {
+  /* POST */
+  background-color: #0284c7;
+  color: #ffffff;
+  --ifm-badge-border-color: transparent;
+}
+
+.badge--danger {
+  /* DELETE */
+  background-color: #dc2626;
+  color: #ffffff;
+  --ifm-badge-border-color: transparent;
+}
+
+.badge--info {
+  /* PUT */
+  background-color: #d97706;
+  color: #ffffff;
+  --ifm-badge-border-color: transparent;
+}
+
+.badge--warning {
+  /* PATCH */
+  background-color: #d97706;
+  color: #ffffff;
+  --ifm-badge-border-color: transparent;
+}
+
+[data-theme="dark"] .badge--primary {
+  /* GET */
+  background-color: #3cad6e;
+  color: #18191a;
+}
+[data-theme="dark"] .badge--success {
+  /* POST */
+  background-color: #0ea5e9;
+  color: #18191a;
+}
+[data-theme="dark"] .badge--danger {
+  /* DELETE */
+  background-color: #ef4444;
+  color: #ffffff;
+}
+[data-theme="dark"] .badge--info {
+  /* PUT */
+  background-color: #f59e0b;
+  color: #18191a;
+}
+[data-theme="dark"] .badge--warning {
+  /* PATCH */
+  background-color: #f59e0b;
+  color: #18191a;
+}
+
+/* ============================================================
+ * API Explorer — request body editor font size
+ *
+ * react-simple-code-editor renders an inner textarea + pre that
+ * can slip past the outer !important font shorthand. Target them
+ * directly so the body editor matches the code snippet tabs.
+ * ============================================================ */
+
+.openapi-explorer__playground-editor,
+.openapi-explorer__playground-editor textarea,
+.openapi-explorer__playground-editor pre {
+  font-size: var(--openapi-explorer-font-size-code) !important;
+}
+
+/* ============================================================
+ * API Explorer — Send button dark mode
+ * ============================================================ */
+
+[data-theme="dark"] .openapi-explorer__request-btn {
+  background-color: #2e8555;
+  color: #ffffff;
+}
+
+[data-theme="dark"] .openapi-explorer__request-btn:hover {
+  background-color: #3cad6e;
+}
+

docsite/src/css/openapiBase.css

@@ -0,0 +1,580 @@
+/**
+ * Structural CSS for the docusaurus-openapi-docs demo site.
+ *
+ * This file contains layout, component behavior, animations, and utilities.
+ * It is intentionally free of hard-coded colors and fonts — those live in
+ * a theme file loaded alongside this one via docusaurus.config.ts:
+ *
+ *   customCss: ["./src/css/custom.css", "./src/css/themes/panw.css"]
+ *
+ * To try a different palette, swap the theme file. The following CSS
+ * variables must be defined by the active theme:
+ *
+ *   --theme-primary-rgb          RGB triplet of primary color (for animations)
+ *   --theme-border-radius-sm/md  Border radius tokens
+ *   --site-primary-hue-saturation  Hue+saturation for the announcement bar
+ *
+ * Structure inspired by @gleanwork/docusaurus-theme-glean.
+ */
+
+/* ============================================================
+ * Typography
+ * ============================================================ */
+
+.markdown h1,
+article h1,
+.main-wrapper h1 {
+  letter-spacing: 0.025em;
+  font-weight: var(--ifm-heading-font-weight);
+  line-height: 1.2;
+  margin-bottom: 1.5rem;
+  color: var(--ifm-heading-color);
+}
+
+.markdown h2,
+article h2,
+.markdown h3,
+article h3 {
+  font-weight: var(--ifm-font-weight-semibold);
+}
+
+/* .markdown strong,
+article strong,
+.markdown b,
+article b {
+  font-weight: var(--ifm-font-weight-semibold);
+} */
+
+.font-mono {
+  font-family: var(--font-mono);
+  /* font-variant-ligatures: none; */
+}
+
+.table-of-contents {
+  font-size: 0.95rem;
+}
+
+html {
+  scroll-padding-top: 50px;
+}
+
+/* ============================================================
+ * Links
+ * ============================================================ */
+
+a:any-link:hover {
+  text-decoration: none;
+}
+
+article p a,
+article ul a,
+article li a,
+.markdown p a,
+.theme-doc-markdown p a {
+  text-decoration: underline 1px var(--ifm-color-primary);
+  transition: color 0.2s ease;
+}
+
+article p a:hover,
+article ul a:hover,
+article li a:hover,
+.markdown p a:hover,
+.theme-doc-markdown p a:hover {
+  text-decoration: underline 2px var(--ifm-color-primary);
+}
+
+/* ============================================================
+ * Sidebar structure
+ * ============================================================ */
+
+/* Slightly off-white sidebar in light mode */
+.theme-doc-sidebar-container {
+  background-color: #f6f6f6;
+}
+
+[data-theme="dark"] .theme-doc-sidebar-container {
+  background-color: unset;
+}
+
+/* Tighter nested indentation */
+.menu__list .menu__list {
+  padding-left: 10px;
+}
+
+/* No underlines on menu links */
+.menu__link {
+  text-decoration: none;
+  color: var(--ifm-color-emphasis-700);
+}
+
+/* Top-level category labels: uppercase, small caps, bold */
+/* .theme-doc-sidebar-item-category-level-1
+  > .menu__list-item-collapsible
+  > .menu__link,
+.theme-doc-sidebar-item-category-level-1
+  > .menu__list-item-collapsible
+  > .menu__link.menu__link--active {
+  text-transform: uppercase;
+  font-weight: 700;
+  letter-spacing: 0.5px;
+  line-height: 16px;
+  font-size: 12px;
+  color: var(--ifm-color-emphasis-900);
+} */
+
+/* Hover: text darkens, no background fill */
+/* .menu__link:hover {
+  background-color: transparent;
+  color: var(--ifm-color-emphasis-800);
+  text-decoration: none;
+} */
+
+/* Active item: primary-colored text, no background */
+/* .menu__link--active:not(
+  .theme-doc-sidebar-item-category-level-1
+    > .menu__list-item-collapsible
+    > .menu__link
+) {
+  color: var(--ifm-color-primary);
+  background-color: transparent;
+  font-weight: 500;
+}
+
+.menu__link--active:not(
+    .theme-doc-sidebar-item-category-level-1
+      > .menu__list-item-collapsible
+      > .menu__link
+  ):hover {
+  color: var(--ifm-color-primary);
+  background-color: transparent;
+} */
+
+/* [data-theme="dark"]
+  .menu__link--active:not(
+    .theme-doc-sidebar-item-category-level-1
+      > .menu__list-item-collapsible
+      > .menu__link
+  ) {
+  color: var(--ifm-color-primary-light);
+}
+
+.menu__list-item-collapsible:hover,
+.menu__list-item-collapsible:active,
+.menu__list-item-collapsible:focus-within,
+.menu__list-item-collapsible.menu__list-item-collapsible--active {
+  background: transparent;
+} */
+
+/* Custom caret */
+.menu__link--sublist-caret:after,
+.menu__caret::before {
+  --ifm-menu-link-sublist-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="8px" height="8px" viewBox="0 0 24 24"><path fill="rgba(0,0,0,0.5)" d="M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z"></path></svg>');
+  content: " ";
+  background-size: contain;
+}
+
+/* ============================================================
+ * Sidebar Method labels — Default (pill style)
+ *
+ * Shape and content labels only. Colors are in the theme file.
+ * ============================================================ */
+
+.api-method > .menu__link,
+.schema > .menu__link {
+  align-items: center;
+  justify-content: start;
+}
+
+.api-method > .menu__link::before,
+.schema > .menu__link::before {
+  font-size: 0.55rem;
+  font-weight: 700;
+  padding: 0.125rem 0.25rem;
+  border-radius: 0.375rem;
+  line-height: 1.25;
+  width: 2.25rem;
+  height: auto;
+  border: none;
+  text-transform: uppercase;
+  margin-right: var(--ifm-spacing-horizontal);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  text-align: center;
+}
+
+/* Content labels */
+.get > .menu__link::before {
+  content: "get";
+}
+.post > .menu__link::before {
+  content: "post";
+}
+.delete > .menu__link::before {
+  content: "del";
+}
+.put > .menu__link::before {
+  content: "put";
+}
+.patch > .menu__link::before {
+  content: "patch";
+}
+
+/* HEAD / EVENT / SCHEMA — neutral colors, no theme needed */
+.head > .menu__link::before {
+  content: "head";
+  background-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-700);
+}
+.event > .menu__link::before {
+  content: "event";
+  background-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-700);
+}
+.schema > .menu__link::before {
+  content: "schema";
+  background-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-emphasis-700);
+}
+
+/* Deprecated */
+.menu__list-item--deprecated > .menu__link,
+.menu__list-item--deprecated > .menu__link:hover {
+  text-decoration: line-through;
+}
+
+/* ============================================================
+ * Sidebar Method labels — High Contrast variant (unchanged)
+ * ============================================================ */
+
+.api-method-contrast > .menu__link,
+.schema-contrast > .menu__link {
+  align-items: center;
+  justify-content: start;
+}
+
+.api-method-contrast > .menu__link::before,
+.schema-contrast > .menu__link::before {
+  width: 55px;
+  height: 20px;
+  font-size: 12px;
+  line-height: 20px;
+  text-transform: uppercase;
+  font-weight: 600;
+  border-radius: 0.25rem;
+  border: 1px solid;
+  border-inline-start-width: 5px;
+  margin-right: var(--ifm-spacing-horizontal);
+  text-align: center;
+  flex-shrink: 0;
+}
+
+.get-contrast > .menu__link::before {
+  content: "get";
+  background-color: var(--ifm-color-info-contrast-background);
+  color: var(--ifm-color-info-contrast-foreground);
+  border-color: var(--ifm-color-info-dark);
+}
+.post-contrast > .menu__link::before {
+  content: "post";
+  background-color: var(--ifm-color-success-contrast-background);
+  color: var(--ifm-color-success-contrast-foreground);
+  border-color: var(--ifm-color-success-dark);
+}
+.delete-contrast > .menu__link::before {
+  content: "del";
+  background-color: var(--ifm-color-danger-contrast-background);
+  color: var(--ifm-color-danger-contrast-foreground);
+  border-color: var(--ifm-color-danger-dark);
+}
+.put-contrast > .menu__link::before {
+  content: "put";
+  background-color: var(--ifm-color-warning-contrast-background);
+  color: var(--ifm-color-warning-contrast-foreground);
+  border-color: var(--ifm-color-warning-dark);
+}
+.patch-contrast > .menu__link::before {
+  content: "patch";
+  background-color: var(--ifm-color-success-contrast-background);
+  color: var(--ifm-color-success-contrast-foreground);
+  border-color: var(--ifm-color-success-dark);
+}
+.head-contrast > .menu__link::before {
+  content: "head";
+  background-color: var(--ifm-color-secondary-contrast-background);
+  color: var(--ifm-color-secondary-contrast-foreground);
+  border-color: var(--ifm-color-secondary-dark);
+}
+.event-contrast > .menu__link::before {
+  content: "event";
+  background-color: var(--ifm-color-secondary-contrast-background);
+  color: var(--ifm-color-secondary-contrast-foreground);
+  border-color: var(--ifm-color-secondary-dark);
+}
+.schema-contrast > .menu__link::before {
+  content: "schema";
+  background-color: var(--ifm-color-secondary-contrast-background);
+  color: var(--ifm-color-secondary-contrast-foreground);
+  border-color: var(--ifm-color-secondary-dark);
+}
+
+/* ============================================================
+ * Sidebar Method labels — Simple variant (unchanged)
+ * ============================================================ */
+
+.api-method-simple > .menu__link {
+  align-items: center;
+  justify-content: start;
+}
+.api-method-simple > .menu__link::before {
+  width: 55px;
+  height: 20px;
+  font-size: 12px;
+  line-height: 20px;
+  text-transform: uppercase;
+  font-weight: 600;
+  border-radius: 0.25rem;
+  align-content: start;
+  margin-right: var(--ifm-spacing-horizontal);
+  text-align: right;
+  flex-shrink: 0;
+  border-color: transparent;
+}
+
+.get-simple > .menu__link::before {
+  content: "get";
+  color: var(--ifm-color-info);
+}
+.post-simple > .menu__link::before {
+  content: "post";
+  color: var(--ifm-color-success);
+}
+.delete-simple > .menu__link::before {
+  content: "del";
+  color: var(--ifm-color-danger);
+}
+.put-simple > .menu__link::before {
+  content: "put";
+  color: var(--ifm-color-warning);
+}
+.patch-simple > .menu__link::before {
+  content: "patch";
+  color: var(--ifm-color-warning);
+}
+.head-simple > .menu__link::before {
+  content: "head";
+  color: var(--ifm-color-secondary-contrast-foreground);
+}
+.event-simple > .menu__link::before {
+  content: "event";
+  color: var(--ifm-color-secondary-contrast-foreground);
+}
+.schema-simple > .menu__link::before {
+  content: "schema";
+  color: var(--ifm-color-secondary-contrast-foreground);
+}
+
+/* ============================================================
+ * Admonitions
+ * ============================================================ */
+
+.alert {
+  border: none;
+  border-radius: var(--theme-border-radius-md, 8px);
+}
+
+/* ============================================================
+ * Navbar header icons
+ * ============================================================ */
+
+.header-github-link:hover {
+  opacity: 0.6;
+}
+
+.header-github-link:before {
+  content: "";
+  width: 24px;
+  height: 24px;
+  display: flex;
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}
+
+html[data-theme="dark"] .header-github-link:before {
+  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
+    no-repeat;
+}
+
+.header-medium-link:hover {
+  opacity: 0.6;
+}
+
+.header-medium-link:before {
+  content: "\f23a";
+  font-family: "Font Awesome 5 Brands";
+  font-size: x-large;
+}
+
+/* ============================================================
+ * Announcement bar
+ * ============================================================ */
+
+div[class^="announcementBar_"] {
+  --site-announcement-bar-stripe-color1: hsl(
+    var(--site-primary-hue-saturation) 85%
+  );
+  --site-announcement-bar-stripe-color2: hsl(
+    var(--site-primary-hue-saturation) 95%
+  );
+  background: repeating-linear-gradient(
+    35deg,
+    var(--site-announcement-bar-stripe-color1),
+    var(--site-announcement-bar-stripe-color1) 20px,
+    var(--site-announcement-bar-stripe-color2) 10px,
+    var(--site-announcement-bar-stripe-color2) 40px
+  );
+  font-weight: bold;
+}
+
+/* ============================================================
+ * Schema parameter highlight animation
+ *
+ * Color driven by --theme-primary-rgb (defined in the theme file).
+ * ============================================================ */
+
+[id]:target {
+  animation: highlight-flash 2s ease-out;
+  background-color: rgba(var(--theme-primary-rgb, 0, 76, 157), 0.08);
+  border-radius: 4px;
+  padding: 2px 4px;
+  margin: -2px -4px;
+}
+
+@keyframes highlight-flash {
+  0% {
+    background-color: rgba(var(--theme-primary-rgb, 0, 76, 157), 0.25);
+    box-shadow: 0 0 0 3px rgba(var(--theme-primary-rgb, 0, 76, 157), 0.25);
+  }
+  50% {
+    background-color: rgba(var(--theme-primary-rgb, 0, 76, 157), 0.15);
+    box-shadow: 0 0 0 2px rgba(var(--theme-primary-rgb, 0, 76, 157), 0.15);
+  }
+  100% {
+    background-color: rgba(var(--theme-primary-rgb, 0, 76, 157), 0.08);
+    box-shadow: none;
+  }
+}
+
+.openapi-markdown__details [id]:target,
+.openapi-schema__list-item [id]:target {
+  animation: highlight-flash 2s ease-out;
+  background-color: rgba(var(--theme-primary-rgb, 0, 76, 157), 0.08) !important;
+}
+
+/* ============================================================
+ * Code tab scrollbar
+ * ============================================================ */
+
+.tabs-container [role="tabpanel"] {
+  min-width: 0;
+  overflow-x: auto;
+}
+
+.tabs-container [role="tabpanel"] pre {
+  overflow-x: auto;
+  white-space: pre;
+  word-wrap: normal;
+  max-width: 100%;
+}
+
+.tabs-container [role="tabpanel"] pre::-webkit-scrollbar {
+  height: 6px;
+}
+
+.tabs-container [role="tabpanel"] pre::-webkit-scrollbar-track {
+  background: var(--ifm-color-emphasis-200);
+  border-radius: var(--theme-border-radius-sm, 4px);
+}
+
+.tabs-container [role="tabpanel"] pre::-webkit-scrollbar-thumb {
+  background: var(--ifm-color-emphasis-400);
+  border-radius: var(--theme-border-radius-sm, 4px);
+}
+
+.tabs-container [role="tabpanel"] pre::-webkit-scrollbar-thumb:hover {
+  background: var(--ifm-color-emphasis-500);
+}
+
+/* ============================================================
+ * OpenAPI code tab language icons
+ * ============================================================ */
+
+.openapi-tabs__code-item--python {
+  color: var(--ifm-color-success);
+}
+.openapi-tabs__code-item--python::after {
+  content: "";
+  width: var(--code-tab-logo-width);
+  height: var(--code-tab-logo-height);
+  background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/python/python-plain.svg")
+    no-repeat;
+  margin-block: auto;
+}
+.openapi-tabs__code-item--python.active {
+  box-shadow: 0 0 0 3px var(--openapi-code-tab-shadow-color-python);
+  border-color: var(--openapi-code-tab-border-color-python);
+}
+
+/* ============================================================
+ * Grid utilities
+ * ============================================================ */
+
+.grid {
+  display: grid;
+}
+.grid-cols-1 {
+  grid-template-columns: repeat(1, minmax(0, 1fr));
+}
+.grid-cols-2 {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+.grid-cols-3 {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+.grid-cols-4 {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+.gap-3 {
+  gap: 0.75rem;
+}
+.gap-6 {
+  gap: 1.5rem;
+}
+.my-4 {
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+}
+.my-6 {
+  margin-top: 1.5rem;
+  margin-bottom: 1.5rem;
+}
+.mt-2 {
+  margin-top: 0.5rem;
+}
+
+@media (min-width: 768px) {
+  .md\:grid-cols-2 {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (min-width: 1024px) {
+  .lg\:grid-cols-3 {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+  .lg\:grid-cols-4 {
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+  }
+}
+

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "multi-scrobbler",
-  "version": "0.16.3",
+  "version": "0.17.0-RC1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "multi-scrobbler",
-      "version": "0.16.3",
+      "version": "0.17.0-RC1",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -30,6 +30,7 @@
         "@kenyip/backoff-strategies": "^1.0.4",
         "@keyv/valkey": "^1.0.8",
         "@lukehagar/plexjs": "^0.39.0",
+        "@minisylar/express-typed-router": "^1.9.8",
         "@pierre/diffs": "^1.2.4",
         "@rocksky/sdk": "^0.3.0",
         "@supercharge/promise-pool": "^3.0.0",
@@ -132,6 +133,8 @@
         "@storybook/addon-docs": "^10.4.3",
         "@storybook/react-vite": "^10.4.3",
         "@tailwindcss/vite": "^4.2.2",
+        "@tanstack/form-core": "^2.0.0-alpha.2",
+        "@tanstack/react-form": "^2.0.0-alpha.2",
         "@tanstack/react-query": "^5.101.0",
         "@tanstack/react-query-devtools": "^5.101.0",
         "@tanstack/react-virtual": "^3.14.3",
@@ -159,6 +162,7 @@
         "@types/sinon": "^21.0.0",
         "@types/spotify-web-api-node": "^5.0.7",
         "@types/superagent": "^8.1.9",
+        "@types/supertest": "^7.2.1",
         "@types/xml2js": "^0.4.11",
         "@vitejs/plugin-react": "^6.0.2",
         "@welldone-software/why-did-you-render": "^10.0.1",
@@ -173,7 +177,7 @@
         "eslint-import-resolver-typescript": "^4.4.5",
         "eslint-plugin-boundaries": "^7.0.2",
         "eslint-plugin-import-x": "^4.17.1",
-        "eslint-plugin-mocha": "^11.3.0",
+        "eslint-plugin-mocha": "^12.0.2",
         "eslint-plugin-prefer-arrow-functions": "^3.2.4",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-storybook": "^10.3.6",
@@ -202,6 +206,7 @@
         "sinon": "^21.0.2",
         "storybook": "^10.4.3",
         "storybook-addon-remix-react-router": "^6.1.0",
+        "supertest": "^7.2.2",
         "tailwindcss": "^4.2.2",
         "tinyexec": "^1.1.1",
         "ts-essentials": "^10.2.0",
@@ -209,7 +214,9 @@
         "typescript-eslint": "^8.59.3",
         "usehooks-ts": "^3.1.1",
         "vite": "^8.0.12",
+        "vite-plugin-svgr": "^5.2.0",
         "with-local-tmp-dir": "^7.0.1",
+        "zocker": "^3.0.0",
         "zod": "^4.4.3"
       },
       "engines": {
@@ -2269,9 +2276,9 @@
       }
     },
     "node_modules/@eslint-community/eslint-utils": {
-      "version": "4.9.1",
-      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.1.tgz",
-      "integrity": "sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==",
+      "version": "4.10.1",
+      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz",
+      "integrity": "sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2999,6 +3006,22 @@
         "react": ">=16"
       }
     },
+    "node_modules/@minisylar/express-typed-router": {
+      "version": "1.9.8",
+      "resolved": "https://registry.npmjs.org/@minisylar/express-typed-router/-/express-typed-router-1.9.8.tgz",
+      "integrity": "sha512-C0VW62eAPNFYP/pPqpepVQLitsJLPI1/8CFSVGIfZO4uaPkJZchN9eDpcCE/S2Rc1RXC+71tZ1A/A/yCu8kp7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "@standard-schema/utils": "^0.3.0"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "peerDependencies": {
+        "express": "^4.18.0 || ^5.0.0"
+      }
+    },
     "node_modules/@mjackson/form-data-parser": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@mjackson/form-data-parser/-/form-data-parser-0.4.0.tgz",
@@ -5328,7 +5351,6 @@
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/@standard-schema/utils/-/utils-0.3.0.tgz",
       "integrity": "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/@stdlib/error-tools-fmtprodmsg": {
@@ -5812,6 +5834,258 @@
         "node": ">=8"
       }
     },
+    "node_modules/@svgr/babel-plugin-add-jsx-attribute": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-add-jsx-attribute/-/babel-plugin-add-jsx-attribute-8.0.0.tgz",
+      "integrity": "sha512-b9MIk7yhdS1pMCZM8VeNfUlSKVRhsHZNMl5O9SfaX0l0t5wjdgu4IDzGB8bpnGBBOjGST3rRFVsaaEtI4W6f7g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-remove-jsx-attribute": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-remove-jsx-attribute/-/babel-plugin-remove-jsx-attribute-8.0.0.tgz",
+      "integrity": "sha512-BcCkm/STipKvbCl6b7QFrMh/vx00vIP63k2eM66MfHJzPr6O2U0jYEViXkHJWqXqQYjdeA9cuCl5KWmlwjDvbA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-remove-jsx-empty-expression": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-remove-jsx-empty-expression/-/babel-plugin-remove-jsx-empty-expression-8.0.0.tgz",
+      "integrity": "sha512-5BcGCBfBxB5+XSDSWnhTThfI9jcO5f0Ai2V24gZpG+wXF14BzwxxdDb4g6trdOux0rhibGs385BeFMSmxtS3uA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-replace-jsx-attribute-value": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-replace-jsx-attribute-value/-/babel-plugin-replace-jsx-attribute-value-8.0.0.tgz",
+      "integrity": "sha512-KVQ+PtIjb1BuYT3ht8M5KbzWBhdAjjUPdlMtpuw/VjT8coTrItWX6Qafl9+ji831JaJcu6PJNKCV0bp01lBNzQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-svg-dynamic-title": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-svg-dynamic-title/-/babel-plugin-svg-dynamic-title-8.0.0.tgz",
+      "integrity": "sha512-omNiKqwjNmOQJ2v6ge4SErBbkooV2aAWwaPFs2vUY7p7GhVkzRkJ00kILXQvRhA6miHnNpXv7MRnnSjdRjK8og==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-svg-em-dimensions": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-svg-em-dimensions/-/babel-plugin-svg-em-dimensions-8.0.0.tgz",
+      "integrity": "sha512-mURHYnu6Iw3UBTbhGwE/vsngtCIbHE43xCRK7kCw4t01xyGqb2Pd+WXekRRoFOBIY29ZoOhUCTEweDMdrjfi9g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-transform-react-native-svg": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-transform-react-native-svg/-/babel-plugin-transform-react-native-svg-8.1.0.tgz",
+      "integrity": "sha512-Tx8T58CHo+7nwJ+EhUwx3LfdNSG9R2OKfaIXXs5soiy5HtgoAEkDay9LIimLOcG8dJQH1wPZp/cnAv6S9CrR1Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-plugin-transform-svg-component": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-plugin-transform-svg-component/-/babel-plugin-transform-svg-component-8.0.0.tgz",
+      "integrity": "sha512-DFx8xa3cZXTdb/k3kfPeaixecQLgKh5NVBMwD0AQxOzcZawK4oo1Jh9LbrcACUivsCA7TLG8eeWgrDXjTMhRmw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/babel-preset": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/@svgr/babel-preset/-/babel-preset-8.1.0.tgz",
+      "integrity": "sha512-7EYDbHE7MxHpv4sxvnVPngw5fuR6pw79SkcrILHJ/iMpuKySNCl5W1qcwPEpU+LgyRXOaAFgH0KhwD18wwg6ug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@svgr/babel-plugin-add-jsx-attribute": "8.0.0",
+        "@svgr/babel-plugin-remove-jsx-attribute": "8.0.0",
+        "@svgr/babel-plugin-remove-jsx-empty-expression": "8.0.0",
+        "@svgr/babel-plugin-replace-jsx-attribute-value": "8.0.0",
+        "@svgr/babel-plugin-svg-dynamic-title": "8.0.0",
+        "@svgr/babel-plugin-svg-em-dimensions": "8.0.0",
+        "@svgr/babel-plugin-transform-react-native-svg": "8.1.0",
+        "@svgr/babel-plugin-transform-svg-component": "8.0.0"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@svgr/core": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/@svgr/core/-/core-8.1.0.tgz",
+      "integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.21.3",
+        "@svgr/babel-preset": "8.1.0",
+        "camelcase": "^6.2.0",
+        "cosmiconfig": "^8.1.3",
+        "snake-case": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      }
+    },
+    "node_modules/@svgr/core/node_modules/cosmiconfig": {
+      "version": "8.3.6",
+      "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-8.3.6.tgz",
+      "integrity": "sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "import-fresh": "^3.3.0",
+        "js-yaml": "^4.1.0",
+        "parse-json": "^5.2.0",
+        "path-type": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/d-fischer"
+      },
+      "peerDependencies": {
+        "typescript": ">=4.9.5"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@svgr/hast-util-to-babel-ast": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@svgr/hast-util-to-babel-ast/-/hast-util-to-babel-ast-8.0.0.tgz",
+      "integrity": "sha512-EbDKwO9GpfWP4jN9sGdYwPBU0kdomaPIL2Eu4YwmgP+sJeXT+L7bMwJUBnhzfH8Q2qMBqZ4fJwpCyYsAN3mt2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.21.3",
+        "entities": "^4.4.0"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      }
+    },
+    "node_modules/@svgr/plugin-jsx": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/@svgr/plugin-jsx/-/plugin-jsx-8.1.0.tgz",
+      "integrity": "sha512-0xiIyBsLlr8quN+WyuxooNW9RJ0Dpr8uOnH/xrCVO8GLUcwHISwj1AG0k+LFzteTkAA0GbX0kj9q6Dk70PTiPA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.21.3",
+        "@svgr/babel-preset": "8.1.0",
+        "@svgr/hast-util-to-babel-ast": "8.0.0",
+        "svg-parser": "^2.0.4"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+      },
+      "peerDependencies": {
+        "@svgr/core": "*"
+      }
+    },
     "node_modules/@svrooij/sonos": {
       "version": "2.5.0",
       "resolved": "https://registry.npmjs.org/@svrooij/sonos/-/sonos-2.5.0.tgz",
@@ -6143,6 +6417,38 @@
         "vite": "^5.2.0 || ^6 || ^7 || ^8"
       }
     },
+    "node_modules/@tanstack/form-core": {
+      "version": "2.0.0-alpha.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/form-core/-/form-core-2.0.0-alpha.2.tgz",
+      "integrity": "sha512-u/2s1rJ1pSdFgU/oKz2zt/Wdb3XQK9LY1IIL2pLMu0AVYK5f8Ue5UwaCjcUxEAI8g6XJpbmEuy2wLIwHZbZnwA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/pacer-lite": "^0.2.2",
+        "@tanstack/store": "^0.11.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/pacer-lite": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/pacer-lite/-/pacer-lite-0.2.2.tgz",
+      "integrity": "sha512-eQ1MyLKCHyXiH7NbdmB80W77OhiMgGBUb+qDx/8WMGbwg5Lf/NlfD0TfNYAqY77i8V3AxoDoYdICrQE5ADw4Yw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
     "node_modules/@tanstack/query-core": {
       "version": "5.101.0",
       "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.101.0.tgz",
@@ -6165,6 +6471,27 @@
         "url": "https://github.com/sponsors/tannerlinsley"
       }
     },
+    "node_modules/@tanstack/react-form": {
+      "version": "2.0.0-alpha.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-form/-/react-form-2.0.0-alpha.2.tgz",
+      "integrity": "sha512-rIm6kRhpK9Fbb5p3xiwKKofOKHXAK3K28NeR4sM5T0h8CU0TpCLMz27SAHY2xjvG2iSgx8n4mLVEyTxw7iHJdw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/form-core": "2.0.0-alpha.2",
+        "@tanstack/react-store": "^0.11.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/@tanstack/react-query": {
       "version": "5.101.0",
       "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.101.0.tgz",
@@ -6200,6 +6527,25 @@
         "react": "^18 || ^19"
       }
     },
+    "node_modules/@tanstack/react-store": {
+      "version": "0.11.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-store/-/react-store-0.11.1.tgz",
+      "integrity": "sha512-HaIGKI3YLmjBYIvy5DFDY23oNaYZIsTZfngey07Uh5iLVJgM3bIGCnZeOFOqzjFld9JHWcaHJnasD/bKoGKwJQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/store": "0.11.1",
+        "use-sync-external-store": "^1.6.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/@tanstack/react-virtual": {
       "version": "3.14.3",
       "resolved": "https://registry.npmjs.org/@tanstack/react-virtual/-/react-virtual-3.14.3.tgz",
@@ -6218,6 +6564,17 @@
         "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/@tanstack/store": {
+      "version": "0.11.1",
+      "resolved": "https://registry.npmjs.org/@tanstack/store/-/store-0.11.1.tgz",
+      "integrity": "sha512-mzTOBhypOuDJAy/D8n2MfUZ1HFkXnmSETviRyhqEC8LUE7/IZQExOTxMANj3KjTofYTkFNpBY67qaVrT41YccA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
     "node_modules/@tanstack/virtual-core": {
       "version": "3.17.1",
       "resolved": "https://registry.npmjs.org/@tanstack/virtual-core/-/virtual-core-3.17.1.tgz",
@@ -6859,6 +7216,17 @@
         "form-data": "^4.0.0"
       }
     },
+    "node_modules/@types/supertest": {
+      "version": "7.2.1",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-7.2.1.tgz",
+      "integrity": "sha512-4CbBvoYVLHL7+yhbYrZET0vsvuyXTC05aRe7dNQkwMzm56auceoy6Yu3K50uZmwfHna1os3CMSgM/3QVkUtPTw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
     "node_modules/@types/unist": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
@@ -10316,6 +10684,17 @@
         "csstype": "^3.0.2"
       }
     },
+    "node_modules/dot-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/dot-case/-/dot-case-3.0.4.tgz",
+      "integrity": "sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "no-case": "^3.0.4",
+        "tslib": "^2.0.3"
+      }
+    },
     "node_modules/dotenv": {
       "version": "10.0.0",
       "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-10.0.0.tgz",
@@ -10325,6 +10704,16 @@
         "node": ">=10"
       }
     },
+    "node_modules/drange": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/drange/-/drange-1.1.1.tgz",
+      "integrity": "sha512-pYxfDYpued//QpnLIm4Avk7rsNtAtQkUES2cwAYSvD/wd2pKD71gN2Ebj3e7klzXwjocvE8c5vx/1fxwpqmSxA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/drizzle-kit": {
       "version": "1.0.0-rc.4-ca0f029",
       "resolved": "https://registry.npmjs.org/drizzle-kit/-/drizzle-kit-1.0.0-rc.4-ca0f029.tgz",
@@ -11479,27 +11868,37 @@
       }
     },
     "node_modules/eslint-plugin-mocha": {
-      "version": "11.3.0",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-11.3.0.tgz",
-      "integrity": "sha512-anENwrIwmdvunmmssjMn5a4nTd+mYMkqBlwjksxOECcIThLNhefWJIiTWY7pY/arMQFjNwHQjVOZb6pQ9PrLjg==",
+      "version": "12.0.2",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-mocha/-/eslint-plugin-mocha-12.0.2.tgz",
+      "integrity": "sha512-RzjnzVBoidGFjVcvzQShLbfWug5pL/6d6LZFbBZk1b5duZ0ooq6dasmpu6qLyNowUZBqaWvQbnR5U1hsKX/+5g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@eslint-community/eslint-utils": "^4.4.1",
-        "globals": "^15.14.0"
+        "@eslint-community/eslint-utils": "4.10.1",
+        "@eslint/core": "1.2.1",
+        "@types/estree": "1.0.9",
+        "globals": "17.8.0",
+        "json-schema-to-ts": "3.1.1",
+        "type-fest": "5.8.0"
+      },
+      "engines": {
+        "node": ">=22.0.0"
       },
       "peerDependencies": {
-        "eslint": ">=9.0.0"
+        "eslint": ">=10.2.0"
       }
     },
-    "node_modules/eslint-plugin-mocha/node_modules/globals": {
-      "version": "15.15.0",
-      "resolved": "https://registry.npmjs.org/globals/-/globals-15.15.0.tgz",
-      "integrity": "sha512-7ACyT3wmyp3I61S4fG682L0VA2RGD9otkqGJIwNUMF1SWUombIIk+af1unuDYgMm082aHYwD+mzJvv9Iu8dsgg==",
+    "node_modules/eslint-plugin-mocha/node_modules/type-fest": {
+      "version": "5.8.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.8.0.tgz",
+      "integrity": "sha512-YGYEVz3Fm5iy/AybuA0oyNFq7H4CgQNfRp/qfe8nurE1kuCeNm3/vfm9X4Mtl+qLyaKJUh5xrFZwogr41SMjYA==",
       "dev": true,
-      "license": "MIT",
+      "license": "(MIT OR CC0-1.0)",
+      "dependencies": {
+        "tagged-tag": "^1.0.0"
+      },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       },
       "funding": {
         "url": "https://github.com/sponsors/sindresorhus"
@@ -13190,9 +13589,9 @@
       }
     },
     "node_modules/globals": {
-      "version": "17.7.0",
-      "resolved": "https://registry.npmjs.org/globals/-/globals-17.7.0.tgz",
-      "integrity": "sha512-Czmyns5dUsq4seFBR/Kdydhmo8y9kC79hiSkPn0YcGtNnYWnrgt0vjrSjx9tspoDGWm2CMarffRuLjM4xUz8xg==",
+      "version": "17.8.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-17.8.0.tgz",
+      "integrity": "sha512-Zz/LMDZScFmkakeL2cTHzf+PbWKdpU3uclqkZT7TjDG58j5WPt0PpA+n9uPI24fZtlw07q0OtEi84K+umsRzqQ==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -14469,6 +14868,20 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/json-schema-to-ts": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz",
+      "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.18.3",
+        "ts-algebra": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
     "node_modules/json-stable-stringify": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/json-stable-stringify/-/json-stable-stringify-1.3.0.tgz",
@@ -15089,6 +15502,16 @@
         "get-func-name": "^2.0.1"
       }
     },
+    "node_modules/lower-case": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/lower-case/-/lower-case-2.0.2.tgz",
+      "integrity": "sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.3"
+      }
+    },
     "node_modules/lowercase-keys": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/lowercase-keys/-/lowercase-keys-2.0.0.tgz",
@@ -15985,6 +16408,17 @@
         "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc"
       }
     },
+    "node_modules/no-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/no-case/-/no-case-3.0.4.tgz",
+      "integrity": "sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "lower-case": "^2.0.2",
+        "tslib": "^2.0.3"
+      }
+    },
     "node_modules/node-addon-api": {
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
@@ -17310,6 +17744,20 @@
         "url": "https://github.com/sindresorhus/quote-js-string?sponsor=1"
       }
     },
+    "node_modules/randexp": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/randexp/-/randexp-0.5.3.tgz",
+      "integrity": "sha512-U+5l2KrcMNOUPYvazA3h5ekF80FHTUG+87SEAmHZmolh1M+i/WyTCxVzmi+tidIa1tM4BSe8g2Y/D3loWDjj+w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "drange": "^1.0.2",
+        "ret": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/random-bytes": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/random-bytes/-/random-bytes-1.0.0.tgz",
@@ -17840,6 +18288,16 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/ret": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/ret/-/ret-0.2.2.tgz",
+      "integrity": "sha512-M0b3YWQs7R3Z917WRQy1HHA7Ba7D8hvZg6UE5mLykJxQVE2ju0IXbGlaHPPlkY+WN7wFP+wUMXmBFA0aV6vYGQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/retry": {
       "version": "0.13.1",
       "resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz",
@@ -18521,6 +18979,17 @@
         "node": ">=6"
       }
     },
+    "node_modules/snake-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/snake-case/-/snake-case-3.0.4.tgz",
+      "integrity": "sha512-LAOh4z89bGQvl9pFfNF8V146i7o7/CqFPbqzYgP+yYzDIDeS9HaNFtXABamRW+AQzEVODcvE79ljJ+8a9YSdMg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "dot-case": "^3.0.4",
+        "tslib": "^2.0.3"
+      }
+    },
     "node_modules/sonic-boom": {
       "version": "4.2.1",
       "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
@@ -18961,6 +19430,42 @@
         "url": "https://ko-fi.com/tunnckoCore/commissions"
       }
     },
+    "node_modules/supertest": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.2.2.tgz",
+      "integrity": "sha512-oK8WG9diS3DlhdUkcFn4tkNIiIbBx9lI2ClF8K+b2/m8Eyv47LSawxUzZQSNKUrVb2KsqeTDCcjAAVPYaSLVTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/supertest/node_modules/superagent": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.3.0.tgz",
+      "integrity": "sha512-B+4Ik7ROgVKrQsXTV0Jwp2u+PXYLSlqtDAhYnkkD+zn3yg8s/zjA2MeGayPoY/KICrbitwneDHrjSotxKL+0XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
@@ -18986,6 +19491,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/svg-parser": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/svg-parser/-/svg-parser-2.0.5.tgz",
+      "integrity": "sha512-FuT74puvVMJQ8sgFxgOKPex5MbxPeltqCXJV3wR9Xq+vPHaF+tTdE1lhJcwspUxjtjvXy1NwqcSLZx9UNwHawg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/tagged-tag": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
@@ -19223,6 +19738,13 @@
       "integrity": "sha512-0s7O4OFi0f8DpD03spao04Osrt2b4p1v2uags7JBMLsAe36pUI0mQU6XMgQuQSv5jOTqTFS0W50wTPrlzST80w==",
       "license": "MIT"
     },
+    "node_modules/ts-algebra": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz",
+      "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/ts-dedent": {
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz",
@@ -20139,6 +20661,21 @@
         "picocolors": "^1.1.1"
       }
     },
+    "node_modules/vite-plugin-svgr": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/vite-plugin-svgr/-/vite-plugin-svgr-5.2.0.tgz",
+      "integrity": "sha512-qj2eAKF8C6PZWemVTvQA0xgQIcP1hHU6Buh7fl6BhvayWwnuxE+z417miKxeDvRWbDrupQ1oK99hfxElopJ3sQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rollup/pluginutils": "^5.3.0",
+        "@svgr/core": "^8.1.0",
+        "@svgr/plugin-jsx": "^8.1.0"
+      },
+      "peerDependencies": {
+        "vite": ">=3.0.0"
+      }
+    },
     "node_modules/vlc-client": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/vlc-client/-/vlc-client-1.1.1.tgz",
@@ -20506,6 +21043,37 @@
         "node": ">=18.17"
       }
     },
+    "node_modules/zocker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/zocker/-/zocker-3.0.0.tgz",
+      "integrity": "sha512-xSJz2M9AELZKzgpuuZPbTQdMv9263p/zSHDIj81B58X3334Xl6iJ/C3u6OQiOlsrWAoJSJsveBcIdz1eEPL0EA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@faker-js/faker": "^10.0.0",
+        "randexp": "^0.5.3"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      }
+    },
+    "node_modules/zocker/node_modules/@faker-js/faker": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-10.5.0.tgz",
+      "integrity": "sha512-bsxD8WLS5lIj7aaoCx1YJkktqYj5vlBUE6HWzu2Q51ksrGJ0H737ECCKlFU7Yf8Br45z9t99frBp/J7kzbMPAg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fakerjs"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || ^23.5.0 || >=24.0.0",
+        "npm": ">=10"
+      }
+    },
     "node_modules/zod": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",

package.json

@@ -1,11 +1,12 @@
 {
   "name": "multi-scrobbler",
-  "version": "0.16.3",
+  "version": "0.17.0-RC1",
   "type": "module",
   "description": "scrobble plays from multiple sources to multiple clients",
   "scripts": {
     "schema": "npm run -s schema:docs",
     "schema:docs": "node src/backend/utils/SchemaDocsStaticUtils.ts",
+    "openapi:docs": "node src/backend/utils/OpenApiUtils.ts",
     "circular": "madge --circular --extensions ts src/index.ts",
     "test": "npm run -s test:backend",
     "test:backend": "mocha --reporter spec",
@@ -18,7 +19,7 @@
     "build:parallel": "concurrently --kill-others-on-fail --names backend,frontend,docs \"npm run -s build:backend\" \"npm run -s build:frontend\" \"npm run docs:build\"",
     "docs:install": "cd docsite && npm install --no-audit",
     "docs:start": "cd docsite && npm start",
-    "docs:build": "npm run -s schema:docs && cd docsite && npm run build",
+    "docs:build": "npm run -s schema:docs && npm run -s openapi:docs && cd docsite && npm run build",
     "docs:netlify": "npm run -s docs:install && npm run -s docs:build",
     "postinstall": "patch-package",
     "install:parallel": "concurrently --kill-others-on-fail --names app,docs \"npm ci --no-audit\" \"npm run docs:install\"",
@@ -70,6 +71,7 @@
     "@kenyip/backoff-strategies": "^1.0.4",
     "@keyv/valkey": "^1.0.8",
     "@lukehagar/plexjs": "^0.39.0",
+    "@minisylar/express-typed-router": "^1.9.8",
     "@pierre/diffs": "^1.2.4",
     "@rocksky/sdk": "^0.3.0",
     "@supercharge/promise-pool": "^3.0.0",
@@ -172,6 +174,8 @@
     "@storybook/addon-docs": "^10.4.3",
     "@storybook/react-vite": "^10.4.3",
     "@tailwindcss/vite": "^4.2.2",
+    "@tanstack/form-core": "^2.0.0-alpha.2",
+    "@tanstack/react-form": "^2.0.0-alpha.2",
     "@tanstack/react-query": "^5.101.0",
     "@tanstack/react-query-devtools": "^5.101.0",
     "@tanstack/react-virtual": "^3.14.3",
@@ -199,6 +203,7 @@
     "@types/sinon": "^21.0.0",
     "@types/spotify-web-api-node": "^5.0.7",
     "@types/superagent": "^8.1.9",
+    "@types/supertest": "^7.2.1",
     "@types/xml2js": "^0.4.11",
     "@vitejs/plugin-react": "^6.0.2",
     "@welldone-software/why-did-you-render": "^10.0.1",
@@ -213,7 +218,7 @@
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-boundaries": "^7.0.2",
     "eslint-plugin-import-x": "^4.17.1",
-    "eslint-plugin-mocha": "^11.3.0",
+    "eslint-plugin-mocha": "^12.0.2",
     "eslint-plugin-prefer-arrow-functions": "^3.2.4",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-storybook": "^10.3.6",
@@ -242,6 +247,7 @@
     "sinon": "^21.0.2",
     "storybook": "^10.4.3",
     "storybook-addon-remix-react-router": "^6.1.0",
+    "supertest": "^7.2.2",
     "tailwindcss": "^4.2.2",
     "tinyexec": "^1.1.1",
     "ts-essentials": "^10.2.0",
@@ -249,7 +255,9 @@
     "typescript-eslint": "^8.59.3",
     "usehooks-ts": "^3.1.1",
     "vite": "^8.0.12",
+    "vite-plugin-svgr": "^5.2.0",
     "with-local-tmp-dir": "^7.0.1",
+    "zocker": "^3.0.0",
     "zod": "^4.4.3"
   },
   "browserslist": {

patches/spotify-web-api-node+5.0.2.patch

@@ -0,0 +1,16 @@
+diff --git a/node_modules/spotify-web-api-node/src/http-manager.js b/node_modules/spotify-web-api-node/src/http-manager.js
+index 6c3991f..89e7a99 100644
+--- a/node_modules/spotify-web-api-node/src/http-manager.js
++++ b/node_modules/spotify-web-api-node/src/http-manager.js
+@@ -63,6 +63,11 @@ HttpManager._makeRequest = function(method, options, uri, callback) {
+     req.send(options.data);
+   }
+ 
++  req.timeout({
++    response: 5000,  // Wait 5 seconds for the server to start sending,
++    deadline: 9000, // but allow 9 seconds for entire response to complete
++  });
++
+   req.end(function(err, response) {
+     if (err) {
+       if (err.timeout) {

patches/zocker+3.0.0.patch

@@ -0,0 +1,15 @@
+diff --git a/node_modules/zocker/dist/index.cjs b/node_modules/zocker/dist/index.cjs
+index 0745620..ab9cba8 100644
+--- a/node_modules/zocker/dist/index.cjs
++++ b/node_modules/zocker/dist/index.cjs
+@@ -51,7 +51,9 @@ function generate$1(schema, ctx) {
+ 	}
+ }
+ const generate_value$1 = (schema, generation_context) => {
+-	const reference_generator = generation_context.reference_generators.find((g) => g.schema === schema);
++	const reg = zod_v4.globalRegistry.get(schema);
++	const reference_generator = generation_context.reference_generators.find((g) => g.schema === schema
++	|| (reg?.zockerId !== undefined && zod_v4.globalRegistry.get(g.schema)?.zockerId === reg.zockerId));
+ 	if (reference_generator) return reference_generator.generator(schema, generation_context);
+ 	const instanceof_generator = generation_context.instanceof_generators.find((g) => schema instanceof g.schema);
+ 	if (instanceof_generator) return instanceof_generator.generator(schema, generation_context);

src/backend/common/AbstractComponent.ts

@@ -7,7 +7,7 @@ import {MONITORING_ORIGIN_SYSTEM, MONITORING_ORIGIN_USER, type ComponentType, ty
 import { buildTrackString } from "../../core/StringUtils.ts";
 import type {CommonClientConfig} from "./infrastructure/config/client/index.ts";
 import type {CommonSourceConfig} from "./infrastructure/config/source/index.ts";
-import { mergeSimpleError, SimpleError, SkipTransformStageError, StagePrerequisiteError, StageTransformError, TransformRulesError } from "./errors/MSErrors.ts";
+import { mergeSimpleError, SimpleError, SkipTransformStageError, StageChangeError, StagePrerequisiteError, StageTransformError, TransformRulesError } from "./errors/MSErrors.ts";
 import {
     FLOW_CONTROL_TERM,
     type PlayTransformRules,
@@ -33,13 +33,13 @@ import { getRetentionCompactAfterFromEnv, getRetentionDeleteAfterFromEnv, isComp
 import type {DbConcrete} from "./database/drizzle/drizzleUtils.ts";
 import type {ComponentSelect} from "./database/drizzle/drizzleTypes.ts";
 import { DrizzlePlayRepository } from "./database/drizzle/repositories/PlayRepository.ts";
-import type {ClientType, MonitoringStatus} from "../../core/Atomic.ts";
+import type {ClientType, MonitoringStatus, OptionalCacheUsage} from "../../core/Atomic.ts";
 import type {SourceType} from "../../core/Atomic.ts";
 import { DrizzleComponentRepository } from "./database/drizzle/repositories/ComponentRepository.ts";
 import dayjs, { type Dayjs } from "dayjs";
 import { COMPONENT_STATE, type ComponentCommonApi, type ComponentCommonApiJson, type ComponentState, type PlayApiCommonDetailed } from "../../core/Api.ts";
 import type {WebhookPayload} from "./infrastructure/config/health/webhooks.ts";
-import type { MarkRequired } from "ts-essentials";
+import type { ElementOf, MarkRequired } from "ts-essentials";
 import { serializeError } from "serialize-error";
 
 export type AbstractComponentConfig = (CommonClientConfig | CommonSourceConfig) & { transformManager?: TransformerManager };
@@ -67,7 +67,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
     type: ClientType | SourceType;
     name: string;
 
-    lastActiveAt?: Dayjs
+    lastActiveAt?: Dayjs;
     lastReadyAt?: Dayjs;
     protected lastUpdatedComponentDatesAt?: Dayjs
 
@@ -116,8 +116,8 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             name: this.config?.name ?? this.name
         });
         this.componentId = this.dbComponent.id;
-        this.lastActiveAt = this.dbComponent.lastActiveAt;
-        this.lastReadyAt = this.dbComponent.lastReadyAt;
+        this.lastActiveAt = this.dbComponent.lastActiveAt ?? undefined;
+        this.lastReadyAt = this.dbComponent.lastReadyAt ?? undefined;
         return true;
     }
 
@@ -221,6 +221,20 @@ export default abstract class AbstractComponent extends AbstractInitializable {
         }
     }
 
+    public abstract stop(opts?: {reason?: string | Error}):  Promise<void>
+    public abstract start(opts?: {forceInit?: boolean}):  Promise<boolean>
+
+    public async restart(opts: { reason?: string | Error, forceInit?: boolean } = {}): Promise<void> {
+        try {
+            await this.stop(opts);
+            await this.start(opts);
+        } catch (e) {
+            const err = new StageChangeError('Failed to restart', { cause: e });
+            this.replaceErrors(err);
+            throw err;
+        }
+    }
+
     public retentionCleanup = async () => {
         if(this.databaseOK !== true) {
             this.logger.warn(`Cannot run retention cleanup because ${this.componentType} database state is not OK`);
@@ -233,7 +247,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             this.setStatus('Retention cleanup finished');
         } catch (e) {
             const retentionErr = new Error('Failed to do retention cleanup', {cause: e});
-            this.warning = retentionErr;
+            this.warnings.push(retentionErr);
             this.logger.warn(retentionErr);
             this.setStatus('Retention cleanup failed');
         }
@@ -248,7 +262,12 @@ export default abstract class AbstractComponent extends AbstractInitializable {
         return partArr.map(x => this.transformManager.parseTransformerConfig(x));
     }
 
-    public transformPlay = async (play: PlayObject, hookType: TransformHook, log?: boolean | 'all') => {
+    public transformPlay = async (play: PlayObject, hookType: TransformHook, transformOpts: {log?: boolean | 'all'} & OptionalCacheUsage = {}) => {
+
+        const {
+            log,
+            useCachedResult = true
+        } = transformOpts;
 
         let logger: Logger;
 
@@ -280,7 +299,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             const shouldLog = log ?? this.config.options?.playTransform?.log ?? isDebugMode();
 
             const transformHash = `playTransform-${hashObject(hook)}-${hashObject(playContentInvariantTransform(play))}`;
-            const cachedSteps = await this.cache.cacheTransform.get<LifecycleStep[]>(transformHash);
+            const cachedSteps = useCachedResult ?  await this.cache.cacheTransform.get<LifecycleStep[]>(transformHash) : undefined;
             if(cachedSteps !== undefined) {
                 logger.trace(`Cache hit for Steps => ${transformHash}`);
                 //return cachedTransformPlay;
@@ -294,7 +313,8 @@ export default abstract class AbstractComponent extends AbstractInitializable {
 
             const opts = {
                 logger,
-                asyncId
+                asyncId,
+                useCachedResult
             }
 
             if(cachedSteps !== undefined) {
@@ -343,7 +363,8 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             const historyToDiff: {name: string, data?: PlayData}[] = [
                 {name: 'Pre Transform', data: play.data}
             ];
-            let isNew = false;
+            let isNew = false,
+            diffFailure = false;
             if(steps.length > 0 && transformedPlay.lifecycle === undefined) {
                 transformedPlay.lifecycle = steps;
                 isNew = true;
@@ -352,6 +373,11 @@ export default abstract class AbstractComponent extends AbstractInitializable {
                 lifecycle = []
             } = transformedPlay;
             steps.forEach((s, index) => {
+                if(diffFailure) {
+                    return;
+                }
+                const stepIdHint = `${s.source}-${s.hook}-${s.stageType}-${s.stageName}`;
+                try {
                 if(!isNew) {
                     const existingStepIndex = lifecycle.findIndex(x => x.stageName === s.stageName && x.stageType === s.stageType && x.hook === s.hook && x.source === this.getIdentifier());
                     if(existingStepIndex !== -1) {
@@ -363,12 +389,24 @@ export default abstract class AbstractComponent extends AbstractInitializable {
 
                 if(shouldLog === 'all') {
                     if(s.patch === undefined) {
-                        historyToDiff.push({name: `${s.source}-${s.hook}-${s.stageType}-${s.stageName}`});
+                        historyToDiff.push({name: `${stepIdHint}`});
                     } else {
-                        const patched = patchObject(historyToDiff[historyToDiff.length - 1].data, s.patch);
-                        historyToDiff.push({name: `${s.source}-${s.hook}-${s.stageType}-${s.stageName} ${s.cached ? ' (Cached)' : ''}`, data: patched});
+                        const lastTransformedData = historyToDiff[historyToDiff.findLastIndex(x => x.data !== undefined)].data;
+                        const patched = patchObject(lastTransformedData, s.patch);
+                        historyToDiff.push({name: `${stepIdHint} ${s.cached ? ' (Cached)' : ''}`, data: patched});
                     }
                 }
+                } catch (e) {
+                    if(`patch` in s) {
+                        this.logger.debug({
+                            patch: s.patch,
+                            playData: historyToDiff[historyToDiff.findLastIndex(x => x.data !== undefined)].data,
+                            cached: s.cached
+                        }, 'Patch and Play data context');
+                    }
+                    this.logger.warn(new SimpleError(`Error occurred while trying to generate diffed Plays for console logging on step ${stepIdHint} but will continue`, {cause: e}));
+                    diffFailure = true;
+                }
             });
             if(shouldLog !== false) {
                 if(steps.filter(x => x.patch !== undefined).length === 0) {
@@ -376,25 +414,45 @@ export default abstract class AbstractComponent extends AbstractInitializable {
                 } else {
                     const diffs: string[] = [];
 
+                    try {
+                    let lastTransformed: ElementOf<typeof historyToDiff>;
                     historyToDiff.forEach((curr, index) => {
                         if(index === 0) {
+                            lastTransformed = curr;
                             return;
                         }
                         const last = historyToDiff[index - 1];
                         if(curr.data === undefined) {
                             diffs.push(`${last.name} => ${curr.name} -- No Change`);
                         } else {
-                            const formattedDiff = diffObjectsConsoleOutput(last.data, curr.data);
-                            diffs.push(`${last.name} => ${curr.name}\n${formattedDiff}`);
+                            try {
+                                const formattedDiff = diffObjectsConsoleOutput(lastTransformed.data, curr.data);
+                                diffs.push(`${last.name} => ${curr.name}\n${formattedDiff}`);
+                                lastTransformed = curr;
+                            } catch(e) {
+                                this.logger.debug({pre: lastTransformed.data, post: curr.data}, 'Compared Pre and Post play data');
+                                throw e;
+                            }
                         }
                     });
+                    } catch (e) {
+                         this.logger.warn(new SimpleError('Error occurred while trying to generate Play diffs for console but will continue', {cause: e}));
+                         diffFailure = true;
+                    }
 
                     if(shouldLog === true || steps.filter(x => x.patch !== undefined).length > 2) {
                         const finalData = transformedPlay.data;
-                        const formattedDiff = diffObjectsConsoleOutput(play.data, finalData, true);
-                        diffs.push(`Original => Final\n${formattedDiff}`);
+                        try {
+                            const formattedDiff = diffObjectsConsoleOutput(play.data, finalData, true);
+                            diffs.push(`Original => Final\n${formattedDiff}`);
+                        } catch (e) {
+                            this.logger.warn(new SimpleError('Error occurred while trying to generate Play diffs for console but will continue', {cause: e}));
+                            diffFailure = true;
+                        }
+                    }
+                    if(diffFailure) {
+                        diffs.push('A failure during diff generation occurred but the transform was successful.');
                     }
-
                     logger.debug(`Transform Diff\n${diffs.join('\n')}`);
                 }
             }
@@ -415,17 +473,18 @@ export default abstract class AbstractComponent extends AbstractInitializable {
         }
     }
 
-    protected generateStepFromStage = async (playTruth: PlayObject, hookItem: StageConfig, hookType: TransformHook, opts: { logger?: Logger, asyncId?: string } = {}): Promise<[LifecycleStep, PlayObject]> => {
+    protected generateStepFromStage = async (playTruth: PlayObject, hookItem: StageConfig, hookType: TransformHook, opts: { logger?: Logger, asyncId?: string } & OptionalCacheUsage = {}): Promise<[LifecycleStep, PlayObject]> => {
         const {
             onSuccess = 'continue',
             onFailure = 'stop',
             onSkip = 'continue',
-            failureReturnPartial = false
+            failureReturnPartial = false,
         } = hookItem;
 
         const {
             logger = loggerNoop,
-            asyncId = nanoid(6)
+            asyncId = nanoid(6),
+            useCachedResult
         } = opts;
 
         const {
@@ -446,7 +505,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             stageName: string = 'Unnamed',
             err: Error;
         try {
-            [newTransformedPlay, stageName] = await this.transformManager.handleStage(hookItem, playTruth, asyncId);
+            [newTransformedPlay, stageName] = await this.transformManager.handleStage(hookItem, playTruth, {asyncId, useCachedResult});
             newTransformedPlay = clone(newTransformedPlay);
         } catch (e) {
             err = e;
@@ -533,7 +592,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
 
     public abstract getRunningState(): ComponentState
 
-    public getApiData(): Omit<ComponentCommonApiJson, 'type' | 'countLive' | 'players'> & Pick<ComponentCommonApi, 'state' | 'error' | 'warning'>  {
+    public getApiData(): Omit<ComponentCommonApiJson, 'type' | 'countLive' | 'players' | 'deadLetterPlays' | 'deadLetterPlaysTotal' | 'queued'> & Pick<ComponentCommonApi, 'state' | 'errors' | 'warnings'>  {
         let state: ComponentState;
         if(!this.initializedOnce || this.initializing) {
             state = COMPONENT_STATE.INITIALIZING;
@@ -551,10 +610,10 @@ export default abstract class AbstractComponent extends AbstractInitializable {
             monitoringStatus: this.getMonitoringStatus(),
             countNonLive: this.dbComponent.countNonLive,
             createdAt: this.dbComponent.createdAt?.toISOString(),
-            lastReadyAt: this.lastReadyAt?.toISOString(),
-            lastActiveAt: this.lastActiveAt?.toISOString(),
-            error: this.error !== undefined && this.error instanceof Error ? serializeError(this.error) : this.error,
-            warning: this.warning !== undefined && this.warning instanceof Error ? serializeError(this.warning) : this.warning,
+            lastReadyAt: this.lastActiveAt !== undefined ? this.lastReadyAt.toISOString() : undefined,
+            lastActiveAt: this.lastActiveAt !== undefined ? this.lastActiveAt?.toISOString() : undefined,
+            errors: this.errors.map(x => x instanceof Error ? serializeError(x) : x),
+            warnings: this.warnings.map(x => x instanceof Error ? serializeError(x) : x),
             ...this.additionalApiData()
         }
     }
@@ -569,12 +628,20 @@ export default abstract class AbstractComponent extends AbstractInitializable {
         });
     }
 
-    protected emitComponentUpdate = <T extends Partial<ReturnType<typeof this.getApiData>>>(payload: T) => {
-        if('error' in payload && payload.error instanceof Error) {
-            payload.error = serializeError(payload.error);
+    public emitComponentUpdate = <T extends Partial<ReturnType<typeof this.getApiData>>>(payload: T) => {
+        if('errors' in payload) {
+            if(payload.errors.length > 0) {
+                payload.errors = payload.errors.map(x => x instanceof Error ? serializeError(x) : x);
+            } else {
+                payload.errors = [];
+            }
         }
-        if('warning' in payload && payload.warning instanceof Error) {
-            payload.warning = serializeError(payload.warning);
+        if('warnings' in payload) {
+            if(payload.warnings.length > 0) {
+               payload.warnings = payload.warnings.map(x => x instanceof Error ? serializeError(x) : x); 
+            } else {
+                payload.warnings = [];
+            }
         }
         this.emitEvent('componentUpdate', payload);
     }
@@ -590,7 +657,7 @@ export default abstract class AbstractComponent extends AbstractInitializable {
         this.setStatus(payload.title);
     }
 
-    protected setStatus = (status: string) => {
+    public setStatus = (status: string) => {
         this.status = status;
         this.emitComponentUpdate({status});
     }

src/backend/common/AbstractInitializable.ts

@@ -3,13 +3,14 @@ import {truncateStringToLength } from "../../core/StringUtils.ts";
 import { hasNodeNetworkException } from "./errors/NodeErrors.ts";
 import { hasUpstreamError } from "./errors/UpstreamError.ts";
 import type {WebhookPayload} from "./infrastructure/config/health/webhooks.ts";
-import { AuthCheckError, BuildDataError, ConnectionCheckError, ParseCacheError, PostInitError, StageError } from "./errors/MSErrors.ts";
-import { messageWithCausesTruncatedDefault } from "../../core/ErrorUtils.ts";
+import { AuthCheckError, AuthError, BuildDataError, ConnectionCheckError, findAuthIssue, ParseCacheError, PostInitError, StageError, type AuthErrorMap } from "./errors/MSErrors.ts";
+import { generateErrorTruthyTest, messageWithCausesTruncatedDefault, type TruthyErrorsOpts } from "../../core/ErrorUtils.ts";
 import { spawn } from 'abort-controller-x';
-
+import { COMPONENT_AUTH_TYPE, type ComponentAuthType } from "../../core/Atomic.ts";
 export default abstract class AbstractInitializable {
     requiresAuth: boolean = false;
     requiresAuthInteraction: boolean = false;
+    authType: ComponentAuthType = COMPONENT_AUTH_TYPE.none;
     authed: boolean = false;
     authFailure?: boolean;
 
@@ -19,8 +20,8 @@ export default abstract class AbstractInitializable {
     databaseOK?: boolean | null;
     connectionOK?: boolean | null;
     cacheOK?: boolean | null;
-    error?: Error;
-    warning?: Error;
+    errors?: Error[] = [];
+    warnings?: Error[] = [];
 
     protected initializedOnce: boolean = false;
     initializing: boolean = false;
@@ -88,15 +89,15 @@ export default abstract class AbstractInitializable {
                 } catch (e) {
                     throw new PostInitError('Error occurred during post-initialization hook', {cause: e});
                 }
-                this.error = undefined;
-                this.warning = undefined;
+                this.errors = [];
+                this.warnings = [];
                 return true;
             } catch(e) {
                 if(notify) {
                     await this.notify({identifier: this.getIdentifier(), title: notifyTitle, message: truncateStringToLength(500)(messageWithCausesTruncatedDefault(e)), priority: 'error'});
                 }
                 const initError = new Error('Initialization failed', {cause: e});
-                this.error = initError;
+                this.errors = [initError];
                 throw initError;
             } finally {
                 this.initializing = false;
@@ -283,17 +284,31 @@ export default abstract class AbstractInitializable {
         return;
     }
 
-    authGated = () => this.requiresAuth && !this.authed
+    authGated = () => this.authType !== COMPONENT_AUTH_TYPE.none && !this.authed
 
-    canTryAuth = () => this.isUsable() && this.authGated() && this.authFailure !== true
+    canTryAuth = () => this.isUsable() && this.authGated() && !this.hasUnrecoverableAuthFailure()
 
-    canAuthUnattended = () => !this.authGated || !this.requiresAuthInteraction || (this.requiresAuthInteraction && !this.authFailure);
+    findAuthIssue = <T extends keyof AuthErrorMap = 'auth'>(opts: Parameters<typeof findAuthIssue<T>>[1] = {}): AuthErrorMap[T] | undefined => {
+        for(const err of this.errors) {
+            const authError = findAuthIssue(err, opts);
+            if(authError !== undefined) {
+                return authError;
+            }
+        }
+        return undefined;
+    }
+
+    hasAuthIssue = () => this.findAuthIssue() !== undefined;
+
+    hasUnrecoverableAuthFailure = () => this.findAuthIssue({unrecoverable: true}) !== undefined;
+
+    canAuthUnattended = () => !this.authGated() || this.authType === COMPONENT_AUTH_TYPE.unattended || (this.authType === COMPONENT_AUTH_TYPE.interactive && !this.hasUnrecoverableAuthFailure()) ;
 
     protected doAuthentication = async (): Promise<boolean> => this.authed
 
     // default init function, should be overridden if auth stage is required
     testAuth = async (force: boolean = false) => {
-        if(!this.requiresAuth) {
+        if(this.authType === COMPONENT_AUTH_TYPE.none) {
             return;
         }
         if(this.authed) {
@@ -303,24 +318,46 @@ export default abstract class AbstractInitializable {
             this.logger.debug('Auth OK but step was forced');
         }
 
-        if(this.authFailure) {
+        // only throw *before* testing if we have previously tested and the error was unrecoverable
+        // there is no reason to constantly retry auth when we already know it won't succeed
+        //
+        // test retries should be forced by api calls and auth callback flows *after* we have made changes to component credentials
+        const unrecoverableAuth = this.findAuthIssue({unrecoverable: true});
+        if(unrecoverableAuth !== undefined) {
+            let unrecoverable: boolean | undefined,
+            cause: Error;
             if(!force) {
-                if(this.requiresAuthInteraction) {
-                    throw new AuthCheckError('Authentication failure: Will not retry auth because user interaction is required for authentication');
+                if(unrecoverableAuth instanceof AuthCheckError) {
+                    // we threw a fallback AuthCheckError
+                    unrecoverable = true;
+                    cause = unrecoverableAuth.cause as Error;
+                } else {
+                    cause = unrecoverableAuth;
                 }
-                throw new AuthCheckError('Authentication failure: Will not retry auth because authentication previously failed and must be reauthenticated');
+                if(this.authType === COMPONENT_AUTH_TYPE.interactive) {
+                    throw new AuthCheckError('Authentication failure: Will not retry auth because user interaction is required for authentication', {cause, unrecoverable});
+                }
+                throw new AuthCheckError('Authentication failure: Will not retry auth because authentication previously failed and must be reauthenticated', {cause, unrecoverable});
             }
             this.logger.debug('Auth previously failed for non upstream/network reasons but retry is being forced');
         }
 
         try {
-            this.authed = await this.doAuthentication();
-            this.authFailure = !this.authed;
+            await this.doAuthentication();
+            this.authed = true;
         } catch (e) {
-            // only signal as auth failure if error was NOT either a node network error or a non-showstopping upstream error
-            this.authFailure = !(hasNodeNetworkException(e) || hasUpstreamError(e, false));
+            let unrecoverableMsg: boolean,
+            unrecoverable: boolean | undefined;
+            if(e instanceof AuthError) {
+                unrecoverableMsg = e.unrecoverable;
+            } else {
+                // if component auth test didn't throw AuthError (it should have!)
+                // then fallback teo determining by these conditions
+                unrecoverable = !(hasNodeNetworkException(e) || hasUpstreamError(e, false));
+                unrecoverableMsg = unrecoverable;
+            }
             this.authed = false;
-            throw new AuthCheckError(`Authentication test failed!${this.authFailure === false ? ' Due to a network issue. Will retry authentication on next heartbeat.' : ''}`, {cause: e});
+            throw new AuthCheckError(`Authentication test failed!${unrecoverableMsg === false ? ' Due to a network issue. Will retry authentication on next heartbeat.' : ''}`, {cause: e, unrecoverable});
         }
     }
 
@@ -349,4 +386,20 @@ export default abstract class AbstractInitializable {
     public additionalApiData(): Record<string, any> {
         return {};
     }
+
+    public clearErrors(opts?: TruthyErrorsOpts) {
+        if (!opts) { this.errors = []; return; }
+        
+        const test = generateErrorTruthyTest(opts);
+        this.errors = this.errors.filter(x => !test(x));
+    }
+
+    public replaceErrors(e: Error, opts?: TruthyErrorsOpts) {
+        if(opts !== undefined) {
+            this.clearErrors(opts);
+        } else {
+            this.clearErrors({instance: e});
+        }
+        this.errors.push(e);
+    }
 }

src/backend/common/database/appMigrations/002_inputHash.ts

@@ -0,0 +1,73 @@
+import type { SqliteDatabase, Migration } from 'sqlite-up';
+import type { MigrateBaseContext } from '../appMigrator.ts';
+import { playInputs, plays as drizzlePlays } from '../drizzle/schema/schema.ts';
+import { eq } from 'drizzle-orm';
+import { playContentBasicInvariantTransform } from '../../../utils/PlayComparisonUtils.ts';
+import { hashObject } from '../../../utils/StringUtils.ts';
+
+
+export const up: Migration<MigrateBaseContext>['up'] = async (db: SqliteDatabase, ctx: MigrateBaseContext): Promise<void> => {
+
+    ctx.logger.info('Generating hashes for Play input data...');
+
+    let more = true;
+    let offset = 0,
+        processed = 0,
+        updated = 0;
+    
+    // first update input hashes
+    while (more) {
+        const inputRows = await ctx.db.select().from(playInputs).limit(100).offset(offset);
+        for (const row of inputRows) {
+            if (row.playHash !== null) {
+                processed++;
+            }
+            try {
+                await ctx.db.update(playInputs).set({
+                    playHash: hashObject(playContentBasicInvariantTransform(row.play).data)
+                }).where(eq(playInputs.id, row.id));
+                updated++;
+                processed++;
+            } catch (e) {
+                ctx.logger.warn(new Error(`Failed to generate hash for Play Input ${row.id}`, { cause: e }));
+            }
+        }
+        offset += 100;
+        ctx.logger.verbose(`Play Input Hash Generation Progress: Processed ${processed} | Updated ${updated}`);
+        if (inputRows.length < 100) {
+            more = false;
+        }
+    }
+
+    ctx.logger.info('Regenerating hashes for Play data...');
+
+    offset = 0;
+    processed = 0;
+    updated = 0;
+    more = true;
+    // then update Plays so hashes reflect Plays after transforms are done 
+    while (more) {
+        const playsRows = await ctx.db.select().from(drizzlePlays).limit(100).offset(offset);
+        for (const row of playsRows) {
+            try {
+                await ctx.db.update(drizzlePlays).set({
+                    playHash: hashObject(playContentBasicInvariantTransform(row.play).data)
+                }).where(eq(drizzlePlays.id, row.id));
+                updated++;
+                processed++;
+            } catch (e) {
+                ctx.logger.warn(new Error(`Failed to generate hash for Play ${row.id} (${row.uid})`, { cause: e }));
+            }
+        }
+        offset += 100;
+        ctx.logger.verbose(`Play Hash Regeneration Progress: Processed ${processed} | Updated ${updated}`);
+        if (playsRows.length < 100) {
+            more = false;
+        }
+    }
+};
+
+export const down: Migration<MigrateBaseContext>['down'] = async (db: SqliteDatabase, ctx: MigrateBaseContext): Promise<void> => {
+    // Rollback code here
+    // context is passed as ctx
+};

src/backend/common/database/appMigrations/003_deadConsolidation.ts

@@ -0,0 +1,76 @@
+import type { SqliteDatabase, Migration } from 'sqlite-up';
+import type { MigrateBaseContext } from '../appMigrator.ts';
+import { queueStates } from '../drizzle/schema/schema.ts';
+import { eq } from 'drizzle-orm';
+
+
+export const up: Migration<MigrateBaseContext>['up'] = async (db: SqliteDatabase, ctx: MigrateBaseContext): Promise<void> => {
+
+    ctx.logger.info('Beginning queue entities consolidation.');
+
+    ctx.logger.verbose('Deleting (now) unused completed queue states...');
+
+    ctx.db.delete(queueStates).where(eq(queueStates.queueStatus,'completed'));
+
+    ctx.logger.verbose('Done with completed queue state deletions');
+
+    ctx.logger.info('Converting dead queue states to ingress states with failure + retries...');
+
+    let more = true;
+    let offset = 0,
+        updated = 0;
+    
+    while (more) {
+        const plays = await ctx.db.query.plays.findMany({
+            where: {
+                queueStates: {
+                    queueName: 'dead'
+                }
+            },
+            with: {
+                queueStates: true
+            },
+            limit: 100,
+            offset
+        });
+
+        for(const p of plays) {
+            const ingress = p.queueStates.find(x => x.queueName === 'ingress');
+            const dead = p.queueStates.find(x => x.queueName === 'dead');
+
+            if(ingress === undefined) {
+                await ctx.db.insert(queueStates).values([{
+                    componentId: p.componentId,
+                    playId: p.id,
+                    queueName: 'ingress',
+                    queueStatus: 'failed',
+                    retries: dead.retries,
+                    error: dead.error,
+                    createdAt: dead.updatedAt,
+                    updatedAt: dead.updatedAt
+                }]);
+            } else {
+                await ctx.db.update(queueStates).set({
+                    queueStatus: 'failed',
+                    retries: dead.retries,
+                    error: dead.error,
+                    updatedAt: dead.updatedAt}).where(eq(queueStates.id, ingress.id));
+            }
+            updated++;
+            await ctx.db.delete(queueStates).where(eq(queueStates.id, dead.id));
+        }
+
+        offset += 100;
+        ctx.logger.verbose(`Conversion Progress: Updated ${updated}`);
+        if (plays.length < 100) {
+            more = false;
+        }
+    }
+
+    ctx.logger.info('Done.');
+};
+
+export const down: Migration<MigrateBaseContext>['down'] = async (db: SqliteDatabase, ctx: MigrateBaseContext): Promise<void> => {
+    // Rollback code here
+    // context is passed as ctx
+};

src/backend/common/database/drizzle/drizzleTypes.ts

@@ -1,5 +1,5 @@
 import type {DBQueryConfig, DBQueryConfigWith, KnownKeysOnly, RelationFieldsFilterInternals, BuildQueryResult, RelationsFilter} from "drizzle-orm";
-import type { components, componentMigrations, playInputs, plays, queueStates, relations, playsHistorical } from "./schema/schema.ts";
+import type { components, componentMigrations, playInputs, plays, queueStates, relations, playsHistorical, playEvents } from "./schema/schema.ts";
 import type {TSchema, TableName} from "./schema/schema.ts";
 
 
@@ -24,6 +24,9 @@ export type PlayNew = typeof plays.$inferInsert;
 export type PlayHistoricalSelect = typeof playsHistorical.$inferSelect;
 export type PlayHistoricalNew = typeof playsHistorical.$inferInsert;
 
+export type PlayEventSelect = typeof playEvents.$inferSelect;
+export type PlayEventNew = typeof playEvents.$inferInsert;
+
 // useful references for building types
 // https://github.com/drizzle-team/drizzle-orm/discussions/2596
 // https://github.com/drizzle-team/drizzle-orm/discussions/1539

src/backend/common/database/drizzle/entityUtils.ts

@@ -1,14 +1,15 @@
 import assert from "node:assert";
-import type {PlayHistoricalNew, PlayHistoricalSelect, PlayNew, PlaySelect, PlaySelectWithQueueStates} from "./drizzleTypes.ts";
+import type {PlayHistoricalNew, PlayHistoricalSelect, PlayNew, PlaySelect, PlaySelectWithQueueStates, QueueStateSelect} from "./drizzleTypes.ts";
 import type {PlayInputNew} from "./drizzleTypes.ts";
 import type {QueueStateNew} from "./drizzleTypes.ts";
 import type {ComponentNew} from "./drizzleTypes.ts";
-import type { MarkOptional } from "ts-essentials";
-import { CLIENT_DEAD_QUEUE, type DeadLetterScrobble, type ErrorLike, type PlayObject } from "../../../../core/Atomic.ts";
+import type { MarkOptional, MarkRequired } from "ts-essentials";
+import { DEAD_QUEUE, type DeadLetterScrobble, type ErrorLike, type LifecycleStep, type PlayObject } from "../../../../core/Atomic.ts";
 import dayjs from "dayjs";
 import { playContentBasicInvariantTransform, playMbidIdentifier } from "../../../utils/PlayComparisonUtils.ts";
 import { hashObject } from "../../../utils/StringUtils.ts";
 import { serializeError } from "serialize-error";
+import { PLAY_EVENT_TYPE, type PlayEventDupeCheck, type PlayEventDupeCheckData, type PlayEventPlayStateChange, type PlayEventPlayStateChangeData, type PlayEventQueueStateChange, type PlayEventQueueStateChangeData, type PlayEventScrobbleResult, type PlayEventScrobbleResultData, type PlayEventTransform } from "../../../../core/PlayEvent.ts";
 
 export const generateComponentEntity = (data: MarkOptional<ComponentNew, 'uid'>): ComponentNew => {
     assert(data.name !== undefined, 'Must provide name');
@@ -72,7 +73,7 @@ export const hydratePlaySelect = <T extends PlaySelect | PlayHistoricalSelect>(s
 }
 
 export const playSelectToDeadScrobble = (select: PlaySelectWithQueueStates, serializedError: boolean = false): DeadLetterScrobble<PlayObject> => {
-    const deadQueue = select.queueStates.find(x => x.queueName === CLIENT_DEAD_QUEUE);
+    const deadQueue = select.queueStates.find(x => x.queueName === DEAD_QUEUE);
     return {
         play: select.play,
         id: select.uid,
@@ -85,9 +86,82 @@ export const playSelectToDeadScrobble = (select: PlaySelectWithQueueStates, seri
 }
 
 export const generateInputEntity = (data: PlayInputNew): PlayInputNew => {
-    return data;
+    const {
+        playHash = hashObject(playContentBasicInvariantTransform(data.play).data)
+    } = data;
+    return {...data, playHash};
 }
 
 export const generateQueueStateEntity = (data: QueueStateNew): QueueStateNew => {
     return data;
-}
+}
+
+export const queueStateToEventData = (qs: QueueStateSelect): PlayEventQueueStateChangeData => {
+    const {
+        queueName,
+        queueStatus,
+        error,
+        retries
+    } = qs;
+    return {
+        queueName,
+        queueStatus,
+        error,
+        retries
+    }
+}
+
+export const transformToPlayEvent = (lifecycle: LifecycleStep[]): Omit<PlayEventTransform, 'playId'> => ({
+    eventName: PLAY_EVENT_TYPE.transform,
+    createdAt: dayjs(lifecycle[0].createdAt),
+    data: lifecycle
+});
+
+export const stateChangeToPlayEvent = (partial: PlayEventPlayStateChangeData): Omit<PlayEventPlayStateChange, 'playId'> => ({
+    eventName: PLAY_EVENT_TYPE.playStateChange,
+    createdAt: dayjs(),
+    data: partial
+})
+
+export const queueStateToPlayEvent = (partial: MarkOptional<QueueStateSelect, 'context'>): Omit<PlayEventQueueStateChange, 'playId'> => ({
+    eventName: PLAY_EVENT_TYPE.queueStateChange,
+    createdAt: dayjs(),
+    data: partial
+});
+export const queueCompletionStateToPlayEvent = (partial: MarkOptional<QueueStateSelect, 'context' | 'retries'>): Omit<PlayEventQueueStateChange, 'playId'> => {
+    const {
+        context,
+        retries,
+        ...rest
+    } = partial;
+    return {
+        eventName: PLAY_EVENT_TYPE.queueStateChange,
+        createdAt: dayjs(),
+        data: rest
+    }
+}
+
+export const dupeCheckToPlayEvent = (partial: MarkRequired<Partial<PlayEventDupeCheckData>, 'match'>): Omit<PlayEventDupeCheck, 'playId'> => {
+    const {match, ...rest} = partial;
+    const data: PlayEventDupeCheckData = {
+        match,
+        score: match ? 1 : 0,
+        breakdowns: [],
+        createdAt: dayjs().toISOString(),
+        ...rest
+    };
+    return {
+        eventName: PLAY_EVENT_TYPE.dupeCheck,
+        createdAt: dayjs(),
+        data
+    }
+}
+
+export const scrobbleToPlayEvent = (data: PlayEventScrobbleResultData): Omit<PlayEventScrobbleResult, 'playId'> => ({
+    eventName: PLAY_EVENT_TYPE.scrobbleResult,
+    createdAt: data.createdAt ?? dayjs(),
+    data
+});
+
+export const entityIsPlayEntity = (obj: object): obj is PlaySelectWithQueueStates => `play` in obj && typeof obj.play === 'object'
+    && `componentId` in obj && typeof obj.componentId === 'number'

src/backend/common/database/drizzle/migrations/20260814181523_abnormal_black_tom/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE `play_inputs` ADD `playHash` text;

src/backend/common/database/drizzle/migrations/20260818175856_daffy_kate_bishop/migration.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `play_events` (
+	`id` integer PRIMARY KEY,
+	`playId` integer NOT NULL,
+	`eventName` text(50) NOT NULL,
+	`data` text,
+	`error` text,
+	`createdAt` number NOT NULL,
+	CONSTRAINT `fk_play_events_playId_plays_id_fk` FOREIGN KEY (`playId`) REFERENCES `plays`(`id`) ON UPDATE CASCADE ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE INDEX `play_event_id_idx` ON `play_events` (`playId`);

src/backend/common/database/drizzle/migrations/20260819172112_little_wolfsbane/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE `play_queue_states` ADD `context` text;

src/backend/common/database/drizzle/repositories/BaseRepository.ts

@@ -45,9 +45,9 @@ export abstract class DrizzleBaseRepository<T extends TableName> {
         await this.db.delete(this.table).where(inArray(this.table.id, ids));
     }
 
-    async updateById(id: number, data: Partial<typeof this.table.$inferInsert>): Promise<void> {
+    async updateById(id: number, data: Partial<typeof this.table.$inferInsert>): Promise<typeof this.table.$inferSelect> {
         assert(id !== null && id !== undefined, `${id === null ? 'null' : 'undefined'} given for entity id`);
-        await this.db.update(this.table).set(data).where(eq(this.table.id, id));
+        return (await this.db.update(this.table).set(data).where(eq(this.table.id, id)).returning())[0];
     }
 
     async create(data: typeof this.table.$inferInsert): Promise<typeof this.table.$inferSelect> {

src/backend/common/database/drizzle/repositories/PlayEventsRepository.ts

@@ -0,0 +1,8 @@
+import { DrizzleBaseRepository, type DrizzleRepositoryOpts } from "./BaseRepository.ts";
+import type {DbConcrete} from "../drizzleUtils.ts";
+export class DrizzlePlayEventsRepository extends DrizzleBaseRepository<'playEvents'> {
+
+    constructor(db: DbConcrete, opts: DrizzleRepositoryOpts = {}) {
+        super(db, 'playEvents', 'Play Events', opts);
+    }
+}

src/backend/common/database/drizzle/repositories/PlayRepository.ts

@@ -3,28 +3,29 @@ import dayjs, { type Dayjs } from "dayjs";
 import { eq, inArray, relationsFilterToSQL, sql } from "drizzle-orm";
 import assert from "node:assert";
 import type { MarkOptional } from "ts-essentials";
-import { type DateLike, type DeepReplaceValue, type PlayObject, type PlayState, type QueueName, TA_DEFAULT_ACCURACY, type TemporalAccuracy } from "../../../../../core/Atomic.ts";
+import { type DateLike, type DeepReplaceValue, type PlayObject, type PlayState, QUEUE_STATUS_QUEUED, type QueueName, SCROBBLE_TS_SOC_END, TA_DEFAULT_ACCURACY, type TemporalAccuracy } from "../../../../../core/Atomic.ts";
 import { removeUndefinedKeys } from '../../../../../core/DataUtils.ts';
 import { shortTodayAwareFormat } from "../../../../../core/TimeUtils.ts";
 import { playContentBasicInvariantTransform, playMbidIdentifier } from "../../../../utils/PlayComparisonUtils.ts";
 import { hashObject } from "../../../../utils/StringUtils.ts";
-import { comparePlayTemporally, getTemporalAccuracyCloseVal, hasAcceptableTemporalAccuracy } from "../../../../utils/TimeUtils.ts";
+import { comparePlayTemporally, getScrobbleTsSOCDateWithContext, getTemporalAccuracyCloseVal, hasAcceptableTemporalAccuracy } from "../../../../utils/TimeUtils.ts";
 import { type CompactableProperty, type RetentionOptions, retentionPlayTypes } from "../../../infrastructure/config/database.ts";
-import type {SourceType} from "../../../../../core/Atomic.ts";
+import type {ErrorLike, SourceType} from "../../../../../core/Atomic.ts";
 import type {FindMany, FindWhere, FindWith, PlayInputNew, PlayNew, PlaySelect, PlaySelectWithQueueStates, PlayWith, QueueStateSelect, WhereClause} from "../drizzleTypes.ts";
 import { type DbConcrete, runTransaction } from "../drizzleUtils.ts";
-import { generateInputEntity, generatePlayEntity, hydratePlaySelect, type PlayEntityOpts, type PlayHydateOptions } from "../entityUtils.ts";
-import { playInputs, plays, relations } from "../schema/schema.ts";
+import { generateInputEntity, generatePlayEntity, hydratePlaySelect, stateChangeToPlayEvent, transformToPlayEvent, type PlayEntityOpts, type PlayHydateOptions } from "../entityUtils.ts";
+import { playEvents, playInputs, plays, queueStates, relations, type TSchema } from "../schema/schema.ts";
 import { buildDateCompare, type CompareDateOp, type ComponentConstrainedRepoOpts, DrizzleBaseRepository, type DrizzleRepositoryOpts } from "./BaseRepository.ts";
 import type {PaginatedResponse} from "../../../../../core/Api.ts";
 import type {PaginatedQueryResponse} from "../../../../../core/Api.ts";
-;
+import { type PlayEventTransform } from "../../../../../core/PlayEvent.ts";
 
 // https://github.com/drizzle-team/drizzle-orm/issues/695 may be useful for typing models with relations?
 
 export interface QueueCriteria {
     queueName: QueueName
     queueStatus: QueueStateSelect['queueStatus'][] | QueueStateSelect['queueStatus']
+    retries?: number
 }
 
 export interface PlayWhereOpts<D extends DateLike = Dayjs> {
@@ -38,7 +39,7 @@ export interface PlayWhereOpts<D extends DateLike = Dayjs> {
     text?: string[]
 }
 
-export type WithPlayRelation = 'input' | 'parent' | 'parent-input' | 'queues';
+export type WithPlayRelation = 'input' | 'parent' | 'parent-input' | 'queues' | 'events' | 'children';
 export interface QueryPlaysOpts<D extends DateLike = Dayjs> extends PlayWhereOpts<D> {
     sort?: 'seenAt' | 'playedAt'
     order?: 'asc' | 'desc'
@@ -92,6 +93,26 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         return res as PlaySelectWithQueueStates;
     }
 
+    findByIdWith = async <K extends keyof TSchema['plays']["relations"]>(id: number, args: WithPlayRelation[]): Promise<PlayWith<K> | undefined> => {
+        const res = await this.db.query.plays.findFirst({
+            where: {
+                id
+            },
+            with: buildPlayWith(args)
+        });
+        return res as unknown as PlayWith<K> | undefined;
+    }
+
+    findByUidWith = async <K extends keyof TSchema['plays']["relations"]>(uid: string, args: WithPlayRelation[]): Promise<PlayWith<K> | undefined> => {
+        const res = await this.db.query.plays.findFirst({
+            where: {
+                uid
+            },
+            with: buildPlayWith(args)
+        });
+        return res as unknown as PlayWith<K> | undefined;
+    }
+
     createPlays = async (entitiesOpts: RepositoryCreatePlayOpts[], opts: HydrateOpts = {}): Promise<PlayWith<'input'>[]> => {
 
         const {
@@ -103,11 +124,14 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
 
             const entitiesData = entitiesOpts.map((data) => {
                 const {
-                    play,
+                    play: {
+                        lifecycle,
+                        ...playRest
+                    },
                     input,
                     ...rest
                 } = data;
-                return generatePlayEntity(play, { componentId: this.componentId, ...rest });
+                return generatePlayEntity(playRest, { componentId: this.componentId, ...rest });
             });
 
             const nakedPlays = await this.db.insert(plays).values(entitiesData).returning();
@@ -126,6 +150,23 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
             });
 
             const inputRow = await this.db.insert(playInputs).values(inputDatas);
+
+            const eventData = nakedPlays.map((x, index) => {
+                const {
+                    play: {
+                        lifecycle = [],
+                    } = {}
+                } = entitiesOpts[index];
+
+                if(lifecycle.length > 0) {
+                    return {...transformToPlayEvent(lifecycle), playId: x.id}
+                }
+                return undefined;
+            }).filter(x => x !== undefined);
+            if(eventData.length > 0) {
+                await this.db.insert(playEvents).values(eventData);
+            }
+
             playRows = nakedPlays.map((x, index) => ({...x, play: hydratePlaySelect(x, hydrate), input: inputRow[index]}));
         });
 
@@ -182,6 +223,9 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
                     case 'queues':
                         query.with.queueStates = true;
                         break;
+                    case 'events':
+                        query.with.events = true;
+                        break;
                     default:
                         throw new Error(`Unknown relation ${w}`);
                 }
@@ -408,28 +452,28 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
                     summaryDelStates.push(`No '${retentionType}' Plays older than ${shortTodayAwareFormat(date)}`);
                 } else {
                     for(const id of ids) {
-                        let compactedPlay: PlayObject;
                         if(compactTypes.includes('input')) {
                             await this.db.update(playInputs).set({
                                 data: {removedReason: 'Removed by compaction'}
                             }).where(eq(playInputs.playId, id));
                         }
                         if(compactTypes.includes('transform')) {
-                            const playRow = await this.db.query.plays.findFirst({where: {id: id}});
-                            if(playRow === undefined) {
-                                // uhh shouldn't be
-                                loggerCom.warn(`No Play found with ID ${id}, but it should have been...`);
-                                continue;
-                            }
-
-                            compactedPlay = playRow.play;
-                            if(compactedPlay.lifecycle !== undefined) {
-                                compactedPlay.lifecycle = compactedPlay.lifecycle.map(x => {
-                                    if(x.inputs == undefined) {
+                            const events = await this.db.query.playEvents.findMany({where: {playId: id}});
+                            for(const ev of events) {
+                                if(ev.eventName === 'transform') {
+                                    const transformEvent = ev as PlayEventTransform;
+                                    let compactedInput = false;
+                                    transformEvent.data = transformEvent.data.map(x => {
+                                        if(x.inputs !== undefined && x.inputs.length > 0) {
+                                            compactedInput = true;
+                                            return {...x, inputs: x.inputs.map((y) => ({type: y.type, input: 'Removed by compaction'}))};
+                                        }
                                         return x;
+                                    });
+                                    if(compactedInput) {
+                                        await this.db.update(playEvents).set({data: transformEvent.data}).where(eq(playEvents.id, transformEvent.id));
                                     }
-                                    return {...x, inputs: x.inputs.map(y => ({type: y.type, input: 'Removed by compaction'}))};
-                                });
+                                }
                             }
                         }
 
@@ -437,9 +481,6 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
                         const vals: Parameters<typeof updater.set>[0] = {
                             compacted: compactedFlags.join('-')
                         };
-                        if(compactedPlay !== undefined) {
-                            vals.play = compactedPlay;
-                        }
                         await this.db.update(plays).set(vals).where(eq(plays.id, id));
                     }
                     loggerCom.trace(`Compacted ${ids.length} '${retentionType}' plays`);
@@ -454,65 +495,75 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
     }
 
     protected prepareGetQueueNext = () => this.db.query.plays.findFirst({
+        // https://stackoverflow.com/a/78551796
+        // cannot bind arrays in sqlite
         where: {
             componentId: sql.placeholder('componentId'),
             queueStates: {
                 queueName: sql.placeholder('queueName'),
-                queueStatus: 'queued',
+                queueStatus: sql.placeholder('status'),
                 retries: {
                     lte: sql.placeholder('retries')
                 }
             },
         },
         with: {
-            queueStates: true
-        },
-        orderBy: {
-            seenAt: 'asc'
+            queueStates: {
+                orderBy: {
+                    updatedAt: 'asc'
+                }
+            }
         },
+        // orderBy: {
+        //     seenAt: 'asc'
+        // },
     }).prepare()
 
-    public getQueueNext = async (queueName: string, opts: {order?: 'asc' | 'desc', retries?: number} & ComponentConstrainedRepoOpts = {}): Promise<PlaySelectWithQueueStates | undefined> => {
+    public getQueueNext = async (queueName: string, opts: {order?: 'asc' | 'desc', retries?: number, notIds?: number[], status?: QueueStateSelect['queueStatus']} & ComponentConstrainedRepoOpts = {}): Promise<PlaySelectWithQueueStates | undefined> => {
         const {
-            retries = 0,
+            retries = 1000,
+            notIds,
             order = 'asc',
+            status = QUEUE_STATUS_QUEUED,
             componentId = this.componentId
         } = opts;
 
-        // let where: FindWhere<'plays'> = {
-        //     componentId
-        // }
+        let res: PlaySelectWithQueueStates | undefined;
 
-        // if(retries !== undefined) {
-        //     where.queueStates = {
-        //         queueName,
-        //         queueStatus: 'queued',
-        //         retries: {
-        //             lte: retries
-        //         }
-        //     }
-        // } else {
-        //     where.queueStates = {
-        //         queueName,
-        //         queueStatus: 'queued'
-        //     }
-        // }
+        if (notIds === undefined) {
+            if (this.getQueueNextPrepared === undefined) {
+                this.getQueueNextPrepared = this.prepareGetQueueNext();
+            }
 
-        // const res = await this.db.query.plays.findFirst({
-        //         where: where,
-        //         orderBy: {
-        //             seenAt: order
-        //         },
-        //         with: {
-        //             queueStates: true
-        //         }
-        // });
-
-        if(this.getQueueNextPrepared === undefined) {
-            this.getQueueNextPrepared = this.prepareGetQueueNext();
+            res = await this.getQueueNextPrepared.execute({ queueName, retries, componentId, status });
+        } else {
+            // cannot bind arrays in sqlite so this has to be non-prepared
+            res = await this.db.query.plays.findFirst({
+                where: {
+                    id: {
+                        notIn: notIds
+                    },
+                    componentId: componentId,
+                    queueStates: {
+                        queueName: queueName,
+                        queueStatus: status,
+                        retries: {
+                            lte: retries
+                        }
+                    },
+                },
+                with: {
+                    queueStates: {
+                        orderBy: {
+                            updatedAt: 'asc'
+                        }
+                    }
+                },
+                // orderBy: {
+                //     seenAt: 'asc'
+                // },
+            });
         }
-
-        const res = await this.getQueueNextPrepared.execute({queueName, retries, componentId});
  
         if(res === undefined) {
             return undefined;
@@ -613,12 +664,20 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         return {data: res.map(x => ({...x, play: hydratePlaySelect(x, hydrate)})), meta: {limit, offset}};
     }
 
-    public checkExisting = async (play: PlayObject, opts: {queueName?: string, states?: PlaySelect['state'][], taAccuracy?: TemporalAccuracy[]} & ComponentConstrainedRepoOpts = {}): Promise<PlaySelectWithQueueStates | undefined> => {
+    public checkExisting = async (play: PlayObject, opts: {
+        queueName?: string,
+        states?: PlaySelect['state'][],
+        taAccuracy?: TemporalAccuracy[],
+        inputHash?: string | PlayObject,
+        notId?: number
+    } & ComponentConstrainedRepoOpts = {}): Promise<PlaySelectWithQueueStates | undefined> => {
         const {
             queueName,
             componentId = this.componentId,
             taAccuracy = TA_DEFAULT_ACCURACY,
-            states
+            states,
+            inputHash,
+            notId,
         } = opts;
         const hash = hashObject(playContentBasicInvariantTransform(play).data);
 
@@ -626,19 +685,25 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         // which we can then use with temporal comparison to make sure we are comparing the correct dates
         //
         // this isn't as fast as just comparing playDate directly but its still much faster/cheaper than paginating plays and doing everything in-memory
-        const dateGranularity = getTemporalAccuracyCloseVal(play.meta.source as SourceType);
-        let endRange: Dayjs;
-        if(play.data.playDateCompleted !== undefined) {
-            // this will be present if source reports it
-            // or we tracked it live with MemorySource
-            endRange = play.data.playDateCompleted.add(dateGranularity, 's');
-        } else {
-            endRange = play.data.playDate.add(dateGranularity, 's');
-        }
+        // const dateGranularity = getTemporalAccuracyCloseVal(play.meta.source as SourceType);
+        // let endRange: Dayjs;
+        // if(play.data.playDateCompleted !== undefined) {
+        //     // this will be present if source reports it
+        //     // or we tracked it live with MemorySource
+        //     endRange = play.data.playDateCompleted.add(dateGranularity, 's');
+        // } else {
+        //     endRange = play.data.playDate.add(dateGranularity, 's');
+        // }
         const where: FindWhere<'plays'> = {
             componentId,
-            playedAt: buildDateCompare(getTemporallyCloseDateCompareOp(play)),
+            playedAt: buildDateCompare(getTemporallyCloseDateCompareOp(play, {useDuration: true})),
         };
+
+        if(notId !== undefined) {
+            where.NOT = {
+                id: notId
+            }
+        }
         
         if(queueName !== undefined) {
             where.queueStates = {
@@ -653,19 +718,20 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         }
 
         const mbidId = playMbidIdentifier(play);
-        if(mbidId !== undefined) {
-            where.AND = [
-                {
-                    OR: [
-                        {
-                            playHash: hash
-                        },
-                        {
-                            mbidIdentifier: mbidId
-                        }
-                    ]
-                }
-            ]
+        if (mbidId !== undefined || inputHash !== undefined) {
+            where.AND = [{
+                OR: [
+                    {
+                        playHash: hash
+                    }
+                ]
+            }];
+            if (mbidId !== undefined) {
+                where.AND[0].OR.push({ mbidIdentifier: mbidId });
+            }
+            if (inputHash !== undefined) {
+                where.AND[0].OR.push({ input: { playHash: typeof inputHash === 'string' ? inputHash : hashObject(playContentBasicInvariantTransform(inputHash).data) } });
+            }
         } else {
             where.playHash = hash;
         }
@@ -673,7 +739,8 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         const res = await this.db.query.plays.findMany({
             where,
             with: {
-                queueStates: true
+                queueStates: true,
+                input: true
             }
         });
         if(res.length === 0) {
@@ -685,12 +752,13 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
         })
     }
 
-    public getTemporallyClosePlays = async (play: PlayObject, opts: {states?: PlaySelect['state'][], bufferTime?: number} & { with?: WithPlayRelation[] } & ComponentConstrainedRepoOpts = {}): Promise<PlayWith<'queueStates'>[]> => {
+    public getTemporallyClosePlays = async (play: PlayObject, opts: {states?: PlaySelect['state'][], bufferTime?: number} & { with?: WithPlayRelation[], notId?: number } & ComponentConstrainedRepoOpts = {}): Promise<PlayWith<'queueStates'>[]> => {
         const {
             componentId = this.componentId,
             bufferTime,
             states,
-            with: qWith
+            with: qWith,
+            notId
         } = opts;
 
         const query: FindMany<'plays'> = {};
@@ -704,6 +772,11 @@ export class DrizzlePlayRepository extends DrizzleBaseRepository<'plays'> {
                 in: states
             }
         }
+        if(notId !== undefined) {
+            where.id = {
+                NOT: notId
+            }
+        }
         query.where = where;
 
         return ((await this.db.query.plays.findMany({
@@ -734,26 +807,75 @@ where compacted IS NOT NULL
 group by componentId,compacted;`);
         return res;
     }
+
+    async updateById(id: number, data: Partial<PlayNew> & {event?: boolean, reason?: string, error?: ErrorLike}): Promise<typeof this.table.$inferSelect> {
+        const res = await super.updateById(id, data) as PlaySelect;
+        if(data.event === true) {
+            if(data.state !== undefined) {
+                try {
+                    await this.db.insert(playEvents).values({...stateChangeToPlayEvent(removeUndefinedKeys({state: data.state, reason: data.reason, error: data.error})), playId: id});
+                } catch (e) {
+                    this.logger.warn(new Error(`Failed to create Play Event for state change ${data.state} on Play ${id}`));
+                }
+            }
+        }
+        return res;
+    }
+
+    async deleteById(id: number): Promise<void> {
+        await runTransaction(this.db, async () => {
+            await this.db.delete(playInputs).where(eq(playInputs.playId, id));
+            await this.db.delete(playEvents).where(eq(playEvents.playId, id));
+            await this.db.delete(queueStates).where(eq(queueStates.playId, id));
+            await this.db.update(plays).set({parentId: null}).where(eq(plays.parentId, id));
+            await this.db.delete(plays).where(eq(plays.id, id));
+        });
+    }
+    async deleteByIds(ids: number[]): Promise<void> {
+        await runTransaction(this.db, async () => {
+            await this.db.delete(playInputs).where(inArray(playInputs.playId, ids));
+            await this.db.delete(playEvents).where(inArray(playEvents.playId, ids));
+            await this.db.delete(queueStates).where(inArray(queueStates.playId, ids));
+            await this.db.update(plays).set({parentId: null}).where(inArray(plays.parentId, ids));
+            await this.db.delete(plays).where(inArray(plays.id, ids));
+        });
+    }
 }
 
-export const getTemporallyCloseDateCompareOp = (play: PlayObject, opts: {bufferTime?: number, useCompleted?: boolean} = {}): CompareDateOp => {
+export const getTemporallyCloseDateCompareOp = (play: PlayObject, opts: {bufferTime?: number, useCompleted?: boolean, useDuration?: boolean} = {}): CompareDateOp => {
     const {
         // use either provided arg or default to using source granularity
         bufferTime = getTemporalAccuracyCloseVal(play.meta.source as SourceType),
-        useCompleted = true
+        useCompleted,
+        useDuration,
     } = opts;
         // we get all plays with a play date between playdate - (buffer) AND (playDateCompleted or playDate) + (buffer)
-        let endRange: Dayjs;
-        if(play.data.playDateCompleted !== undefined && useCompleted) {
+        let startRange: Dayjs,
+        endRange: Dayjs;
+
+        // make sure we use the 
+        const [sotPlayDate, SOT] = getScrobbleTsSOCDateWithContext(play);
+
+        if(useDuration && play.data.duration !== undefined) {
+            if(SOT === SCROBBLE_TS_SOC_END) {
+                endRange = play.data.playDate.add(bufferTime, 's');
+                startRange = play.data.playDate.subtract(play.data.duration + bufferTime,'s')
+            } else {
+                endRange = play.data.playDate.add(play.data.duration + bufferTime, 's');
+                startRange = play.data.playDate.subtract(bufferTime,'s')
+            }
+        } else if(play.data.playDateCompleted !== undefined && useCompleted) {
+            startRange = play.data.playDate.subtract(bufferTime, 's');
             // this will be present if source reports it
             // or we tracked it live with MemorySource
             endRange = play.data.playDateCompleted.add(bufferTime, 's');
         } else {
-            endRange = play.data.playDate.add(bufferTime, 's');
+            startRange = sotPlayDate.subtract(bufferTime, 's');
+            endRange = sotPlayDate.add(bufferTime, 's');
         }
         return {
             type: 'between',
-            range: [play.data.playDate.subtract(bufferTime, 's'), endRange]
+            range: [startRange, endRange]
         }
 }
 
@@ -780,6 +902,12 @@ export const buildPlayWith = (args: WithPlayRelation[] | undefined): FindWith<'p
             case 'queues':
                 qWith.queueStates = true;
                 break;
+            case 'events':
+                qWith.events = true;
+                break;
+            case 'children':
+                qWith.children = true;
+                break;
             default:
                 throw new Error(`Unknown relation ${w}`);
         }
@@ -829,14 +957,26 @@ export const buildPlayWhere = (args: PlayWhereOpts): WhereClause<'plays'> => {
         // or else assigning an array to OR using only `typeof where.queueStates` causes a type error
         const queueWhere: typeof where.queueStates.OR[0][] = [];
         for(const q of queues) {
-            queueWhere.push(
-                {
-                    queueName: q.queueName,
-                    queueStatus: typeof q.queueStatus === 'string' ? q.queueStatus : {
-                        in: q.queueStatus
-                    }
+            const qWhereCriteria: typeof where.queueStates.OR[0] =  {
+                queueName: q.queueName,
+                queueStatus: typeof q.queueStatus === 'string' ? q.queueStatus : {
+                    in: q.queueStatus
                 }
-            )
+            };
+            if(q.retries !== undefined) {
+                qWhereCriteria.retries = {
+                    lte: q.retries
+                }
+            }
+            queueWhere.push(qWhereCriteria);
+            // queueWhere.push(
+            //     {
+            //         queueName: q.queueName,
+            //         queueStatus: typeof q.queueStatus === 'string' ? q.queueStatus : {
+            //             in: q.queueStatus
+            //         }
+            //     }
+            // )
         }
         if(queueWhere.length === 1) {
             where.queueStates = queueWhere[0];

src/backend/common/database/drizzle/repositories/QueueRepository.ts

@@ -1,9 +1,10 @@
-import { eq, and, lte, inArray } from "drizzle-orm";
+import { eq, and, gte, lte, inArray } from "drizzle-orm";
 import { DrizzleBaseRepository, type DrizzleRepositoryOpts } from "./BaseRepository.ts";
 import type {DbConcrete} from "../drizzleUtils.ts";
-import type {QueueStateSelect} from "../drizzleTypes.ts";
-import { queueStates } from "../schema/schema.ts";
-import { CLIENT_DEAD_QUEUE } from "../../../../../core/Atomic.ts";
+import type {PlaySelect, QueueStateSelect} from "../drizzleTypes.ts";
+import { playEvents, queueStates } from "../schema/schema.ts";
+import { DEAD_QUEUE, INGRESS_QUEUE } from "../../../../../core/Atomic.ts";
+import { queueStateToPlayEvent } from "../entityUtils.ts";
 export class DrizzleQueueRepository extends DrizzleBaseRepository<'queueStates'> {
 
     constructor(db: DbConcrete, opts: DrizzleRepositoryOpts = {}) {
@@ -17,7 +18,7 @@ export class DrizzleQueueRepository extends DrizzleBaseRepository<'queueStates'>
             eq(queueStates.componentId, componentId),
             lte(queueStates.retries, retries),
             eq(queueStates.queueStatus, 'failed'),
-            eq(queueStates.queueName, CLIENT_DEAD_QUEUE)
+            eq(queueStates.queueName, INGRESS_QUEUE)
         ));
     }
 
@@ -27,15 +28,56 @@ export class DrizzleQueueRepository extends DrizzleBaseRepository<'queueStates'>
         }).where(and(
             eq(queueStates.componentId, componentId),
             eq(queueStates.queueStatus, 'queued'),
-            eq(queueStates.queueName, CLIENT_DEAD_QUEUE)
+            eq(queueStates.queueName, DEAD_QUEUE)
         ));
     }
 
-    public getQueueCount = async (componentId: number, queueNames: string[], queueStatus: QueueStateSelect['queueStatus'][] = ['queued']): Promise<number> => {
+    public getQueueCount = async (componentId: number, queueNames: string[], opts: {
+        queueStatus?: QueueStateSelect['queueStatus'][],
+        retries?: number
+        retryEq?: 'lte' | 'gte'
+    } = {}): Promise<number> => {
+        const {
+            queueStatus = ['queued'],
+            retries,
+            retryEq = 'lte'
+        } = opts
+        if(retries === undefined) {
+            return await this.db.$count(queueStates, and(
+                eq(queueStates.componentId, componentId),
+                inArray(queueStates.queueName, queueNames),
+                inArray(queueStates.queueStatus, queueStatus)
+            ));
+        }
         return await this.db.$count(queueStates, and(
             eq(queueStates.componentId, componentId),
             inArray(queueStates.queueName, queueNames),
-            inArray(queueStates.queueStatus, queueStatus)
-        ));
+            inArray(queueStates.queueStatus, queueStatus),
+            retryEq === 'lte' ? lte(queueStates.retries, retries) : gte(queueStates.retries, retries)
+        )); 
+    }
+
+    async create(data: typeof this.table.$inferInsert & {playId?: PlaySelect['id'], event?: boolean}): Promise<typeof this.table.$inferSelect> {
+        const res = await super.create(data) as QueueStateSelect;
+        if(data.event === true && data.playId !== undefined) {
+            try {
+                await this.db.insert(playEvents).values({...queueStateToPlayEvent(res), playId: data.playId});
+            } catch (e) {
+                this.logger.warn(new Error(`Failed to create Play Event for new queue creation on Play ${data.playId}`));
+            }
+        }
+        return res;
+    }
+
+    async updateById(id: number, data: Partial<typeof this.table.$inferInsert> & {playId?: PlaySelect['id'], event?: boolean}): Promise<typeof this.table.$inferSelect> {
+        const res = await super.updateById(id, data) as QueueStateSelect;
+        if(data.event === true && data.playId !== undefined) {
+            try {
+                await this.db.insert(playEvents).values({...queueStateToPlayEvent(res), playId: data.playId});
+            } catch (e) {
+                this.logger.warn(new Error(`Failed to create Play Event for queue ${res.queueName} on Play ${data.playId}`));
+            }
+        }
+        return res;
     }
 }

src/backend/common/database/drizzle/schema/schema.ts

@@ -1,7 +1,7 @@
 import { integer, sqliteTable, text, index, uniqueIndex, customType, type AnySQLiteColumn } from "drizzle-orm/sqlite-core";
 import { defineRelations } from 'drizzle-orm';
 import dayjs, { type Dayjs } from "dayjs";
-import { COMPONENT_TYPE_CLIENT, COMPONENT_TYPE_SOURCE, type ErrorLike, type PlayObject } from "../../../../../core/Atomic.ts";
+import { COMPONENT_TYPE_CLIENT, COMPONENT_TYPE_SOURCE, type ErrorLike, type PlayObject, type QueueContext } from "../../../../../core/Atomic.ts";
 import { asPlayCheap } from "../../../../../core/PlayMarshalUtils.ts";
 import type {ExternalMetadataTerm, PlayTransformPartsConfig, SearchAndReplaceTerm} from "../../../../../core/Transform.ts";
 import type {JobRangeCount, JobRangeTime} from "../../../infrastructure/Job.ts";
@@ -94,6 +94,7 @@ export const playInputs = sqliteTable("play_inputs", {
   playId: integer().notNull().references(() => plays.id, {onDelete: 'cascade', onUpdate: 'cascade'}),
   data: text({ mode: 'json' }).$type<object>(),
   play: PlayJson('play').notNull(),//text({ mode: 'json' }).notNull().$type<PlayObject>(),
+  playHash: text(),
   createdAt: DayjsTimestamp('createdAt').$defaultFn(() => dayjs())
 }, (table) => [
   uniqueIndex('play_input_id_idx').on(table.playId)
@@ -143,6 +144,7 @@ export const queueStates = sqliteTable("play_queue_states", {
   queueStatus: text({enum: ['queued','completed','failed']}).notNull().default('queued'),
   retries: integer().notNull().default(0),
   error: ErrorLikeJson('error'),
+  context: text({mode: 'json'}).$type<QueueContext & {isRetry?: boolean}>(),
   createdAt: DayjsTimestamp('createdAt').notNull().$defaultFn(() => dayjs()),
   updatedAt: DayjsTimestamp('updatedAt').notNull().$defaultFn(() => dayjs()).$onUpdate(() => dayjs())
 }, (table) => [
@@ -211,7 +213,18 @@ export const jobs = sqliteTable("jobs", {
   completedAt: DayjsTimestamp('completedAt')
 });
 
-const playRelations = defineRelations({ plays, queueStates, playInputs, components, jobs, componentMigrations,playsHistorical }, (r) => ({
+export const playEvents = sqliteTable("play_events", {
+  id: integer({ mode: 'number' }).primaryKey(),
+  playId: integer().notNull().references(() => plays.id, {onDelete: 'cascade', onUpdate: 'cascade'}),
+  eventName: text({length: 50}).notNull(),
+  data: text({ mode: 'json' }),
+  error: ErrorLikeJson('error'),
+  createdAt: DayjsTimestamp('createdAt').notNull().$defaultFn(() => dayjs()),
+}, (table) => [
+  index('play_event_id_idx').on(table.playId)
+]);
+
+const playRelations = defineRelations({ plays, queueStates, playEvents, playInputs, components, jobs, componentMigrations,playsHistorical }, (r) => ({
   plays: {
     queueStates: r.many.queueStates(),
     input: r.one.playInputs({
@@ -233,7 +246,8 @@ const playRelations = defineRelations({ plays, queueStates, playInputs, componen
       from: r.plays.jobId,
       to: r.jobs.id,
       optional: true
-    })
+    }),
+    events: r.many.playEvents(),
   },
   playsHistorical: {
     component: r.one.components({
@@ -265,7 +279,13 @@ const playRelations = defineRelations({ plays, queueStates, playInputs, componen
   },
   jobs: {
     plays: r.many.plays()
-  }
+  },
+  playEvents: {
+    play: r.one.plays({
+      from: r.playEvents.playId,
+      to: r.plays.id
+    }),
+  },
 }));
 
 export const relations = playRelations;
@@ -280,6 +300,8 @@ export const getConfigByTableName = <T extends TableName>(name: T) => {
       return components;
     case 'playInputs':
       return playInputs;
+    case 'playEvents':
+      return playEvents;
     case 'queueStates':
       return queueStates;
     case 'componentMigrations':
@@ -289,7 +311,7 @@ export const getConfigByTableName = <T extends TableName>(name: T) => {
   }
 }
 
-export const schema = {playInputs, plays, components, componentMigrations, queueStates, jobs};
+export const schema = {playInputs, plays, playEvents, components, componentMigrations, queueStates, jobs};
 
 export type TSchema = typeof relations;
 export type Schema = typeof schema;

src/backend/common/errors/MSErrors.ts

@@ -33,16 +33,38 @@ export class ConnectionCheckError extends StageError {
 }
 addKnownErrorConstructor(ConnectionCheckError);
 
+export class AuthError extends NamedError {
+    override name = 'Authentication Error';
+    unrecoverable: boolean = false;
+
+    public constructor(msg?: string, opts: ErrorOptions & {unrecoverable?: boolean} = {}) {
+        super(msg, opts);
+        this.unrecoverable = opts.unrecoverable ?? false;
+    }
+}
+addKnownErrorConstructor(AuthError);
+export const isAuthError = (e: Error): e is AuthError => e.name === 'Authentication Error' || e instanceof AuthError;
 export class AuthCheckError extends StageError {
-    name = 'Authentication Check';
+    override name = 'Authentication Check';
+    unrecoverable?: boolean;
+
+    public constructor(msg?: string, opts: ErrorOptions & {unrecoverable?: boolean} = {}) {
+        super(msg, opts);
+        this.unrecoverable = opts.unrecoverable;
+    }
 }
 addKnownErrorConstructor(AuthCheckError);
+export const isAuthCheckError = (e: Error): e is AuthCheckError => e.name === 'Authentication Check' || e instanceof AuthCheckError;
 
 export class PostInitError extends StageError {
     name = 'Post Initialization';
 }
 addKnownErrorConstructor(PostInitError);
 
+export class StageChangeError extends NamedError {
+    override name = 'Stage Change';
+}
+
 const STACK_AT_REGEX = new RegExp(/[\n\r]\s*at/);
 
 export class SimpleError extends Error implements HasSimpleError {
@@ -200,3 +222,33 @@ export class InvalidRegexError extends SimpleError {
     }
 }
 addKnownErrorConstructor(InvalidRegexError, () => new InvalidRegexError(new RegExp(/1/)));
+
+export type AuthErrorMap = {
+    root: AuthError
+    check: AuthCheckError
+    auth: AuthError | AuthCheckError
+    parent: Error
+}
+
+export const findAuthIssue = <T extends keyof AuthErrorMap = 'auth'>(err: Error, opts: { type?: T, unrecoverable?: boolean } = {}): AuthErrorMap[T] | undefined => {
+    const {
+        type = 'auth',
+        unrecoverable
+    } = opts;
+    const authError = findCauseByFunc(err, (e) => {
+        if (['check','auth'].includes(type) && isAuthCheckError(e)) {
+            return unrecoverable === undefined || e.unrecoverable === unrecoverable;
+        }
+        if (['root','auth'].includes(type) && isAuthError(e)) {
+            return unrecoverable === undefined || e.unrecoverable === unrecoverable;
+        }
+        return false;
+    });
+    if (authError !== undefined) {
+        if (type === 'parent') {
+            return err as AuthErrorMap[T];
+        }
+        return authError as AuthErrorMap[T];
+    }
+    return undefined;
+}

src/backend/common/errors/PlayProcessingError.ts

@@ -0,0 +1,18 @@
+import { NamedError } from "./MSErrors.ts";
+import type { PlayProcessingResult } from "../infrastructure/PlayProcessing.ts";
+
+export interface PlayProcessingErrorData extends PlayProcessingResult {
+    showStopping: boolean
+}
+
+export class PlayProcessingError extends NamedError {
+    override name = 'Play Processing Error';
+    result: PlayProcessingResult
+    showStopping: boolean
+
+    constructor(error: Error, data: PlayProcessingErrorData, opts: ErrorOptions = {}) {
+        super('Error occured while processing Play', {...opts, cause: error});
+        this.result = data;
+        this.showStopping = data.showStopping;
+    }
+}

src/backend/common/infrastructure/MSBackendEventMap.ts

@@ -16,5 +16,7 @@ export interface MSBackendEventMap extends Omit<MSCoreEvents, 'playerUpdate'> {
         scrobbleTo: string[]
         }
     }>]
-    playerUpdate: [EmittedMSEvent<SourcePlayerObj<Dayjs> & { options: { scrobbleTo: string[] } },{},SourceType>]
+    playerUpdate: [EmittedMSEvent<SourcePlayerObj<Dayjs> & { options: { scrobbleTo: string[], wasMonitored?: boolean } },{},SourceType>]
+    configError: [Error | string]
+    instantiateError: [Error]
 }

src/backend/common/infrastructure/PlayProcessing.ts

@@ -0,0 +1,8 @@
+import type { PlayEvent } from "../../../core/PlayEvent.ts"
+import type { PlaySelectWithQueueStates, QueueStateSelect } from "../database/drizzle/drizzleTypes.ts"
+
+export interface PlayProcessingResult {
+    playEntity: PlaySelectWithQueueStates,
+    events: Omit<PlayEvent, 'playId'>[],
+    queue: QueueStateSelect
+}

src/backend/common/infrastructure/config/client/discord.ts

@@ -1,21 +1,39 @@
 import * as z from "zod";
 import {commonClientConfigSchema, commonClientDataSchema, type EnvClientSchema} from "./index.ts";
 import {componentTypeSchema} from "../../../../../core/Atomic.ts";
+import { transformSplitMaybeString } from "../../../../utils/ZodUtils.ts";
 
 export const statusTypeSchema = z.union([z.literal("online"), z.literal("idle"), z.literal("dnd"), z.literal("invisible")]);
 
 export type StatusType = z.infer<typeof statusTypeSchema>;
 
-const ipcLocationTupleSchema = z.custom<[number, string]>((val) => Array.isArray(val) && val.length === 2 && typeof val[0] === 'number' && typeof val[1] === 'string');
+const HOST_PORT_LOOSE_REGEX = new RegExp(/.+:\d+/i)
+
+const ipcTransform = z.transform((val: string, ctx) => {
+    const sp = val.split(':');
+    if(sp.length === 1) {
+        // assume its a path
+        return val;
+    }
+    if(!HOST_PORT_LOOSE_REGEX.test(val)) {
+        ctx.issues.push({
+            code: 'custom',
+            message: "Not shaped like host:port",
+            input: val
+        });
+        return z.NEVER;
+    }
+    return [parseInt(sp[1]), sp[0]]
+})
 
 export const discordDataSchema = z.object({
     token: z.string().optional(),
     applicationId: z.string().optional(),
     artwork: z.union([z.boolean(), z.string(), z.array(z.string())]).optional(),
     artworkDefaultUrl: z.string().optional(),
-    statusOverrideAllow: z.union([z.string(), z.array(statusTypeSchema)]).optional(),
+    statusOverrideAllow: z.array(statusTypeSchema).optional(),
     listeningActivityAllow: z.union([z.string(), z.array(z.string())]).optional(),
-    ipcLocations: z.union([z.string(), z.array(z.union([z.string(), ipcLocationTupleSchema]))]).optional()
+    ipcLocations: z.array(z.string().pipe(ipcTransform)).optional()
 });
 
 export type DiscordData = z.infer<typeof discordDataSchema>;
@@ -24,10 +42,10 @@ const envDataSchema = z.object({
     DISCORD_TOKEN: discordDataSchema.shape.token,
     DISCORD_ARTWORK: discordDataSchema.shape.artwork,
     DISCORD_APPLICATION_ID: discordDataSchema.shape.applicationId,
-    DISCORD_IPC_LOCATIONS: discordDataSchema.shape.ipcLocations,
+    DISCORD_IPC_LOCATIONS: z.string().optional().pipe(transformSplitMaybeString),
     DISCORD_ARTWORK_DEFAULT_URL: discordDataSchema.shape.artworkDefaultUrl,
-    DISCORD_STATUS_OVERRIDE_ALLOW: discordDataSchema.shape.statusOverrideAllow,
-    DISCORD_LISTENING_ACTIVITY_ALLOW: discordDataSchema.shape.listeningActivityAllow,
+    DISCORD_STATUS_OVERRIDE_ALLOW: z.string().optional().pipe(transformSplitMaybeString).meta(discordDataSchema.shape.statusOverrideAllow.meta()),
+    DISCORD_LISTENING_ACTIVITY_ALLOW: z.string().optional().pipe(transformSplitMaybeString).meta(discordDataSchema.shape.listeningActivityAllow.meta()),
 });
 
 export const envSchemas: EnvClientSchema<typeof envDataSchema, DiscordClientConfig> = {
@@ -40,7 +58,7 @@ export const envSchemas: EnvClientSchema<typeof envDataSchema, DiscordClientConf
                 applicationId: partial.DISCORD_APPLICATION_ID,
                 ipcLocations: partial.DISCORD_IPC_LOCATIONS,
                 artworkDefaultUrl: partial.DISCORD_ARTWORK_DEFAULT_URL,
-                statusOverrideAllow: partial.DISCORD_STATUS_OVERRIDE_ALLOW,
+                statusOverrideAllow: partial.DISCORD_STATUS_OVERRIDE_ALLOW as StatusType[],
                 listeningActivityAllow: partial.DISCORD_LISTENING_ACTIVITY_ALLOW
             }
     })
@@ -85,7 +103,7 @@ export const discordStrongDataSchema = discordDataSchema.extend({
     artwork: z.union([z.boolean(), z.array(z.string())]).optional(),
     statusOverrideAllow: z.array(statusTypeSchema).optional(),
     listeningActivityAllow: z.array(z.string()).optional(),
-    ipcLocations: z.array(z.union([z.string(), ipcLocationTupleSchema])).optional()
+    //ipcLocations: z.array(z.union([z.string(), z.tuple([z.number(),z.string()])])).optional()
 });
 
 export type DiscordStrongData = z.infer<typeof discordStrongDataSchema>;
@@ -101,7 +119,7 @@ export const discordIPCDataSchema = discordStrongDataSchema.extend({
     //ipcLocations: (string | [number, string])[]
 });
 
-export type DiscordIPCData = z.infer<typeof discordIPCDataSchema>;
+export type DiscordIPCData = Omit<z.infer<typeof discordIPCDataSchema>, 'ipcLocations'> & {ipcLocations: (string | [number, string])[]};
 
 export interface ActivityAssets {
     largeImage?: string

src/backend/common/infrastructure/config/client/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import {playTransformOptionsSchema} from "../../../../../core/Transform.ts";
-import {commonConfigSchema, requestRetryOptionsSchema, monitorOptionsSchema, type CommonComponentEnvShape} from "../common.ts";
+import {commonConfigSchema, requestRetryOptionsSchema, monitorOptionsSchema, type CommonComponentEnvShape, deadLetterOptionsSchema} from "../common.ts";
 import {retentionConfigDurationValueSchema} from "../database.ts";
 import type { PipeUnwrapDirection } from "../../../../utils/ZodUtils.ts";
 
@@ -124,6 +124,7 @@ export const commonClientOptionsSchema = z.object({
     ...monitorOptionsSchema.shape,
     ...requestRetryOptionsSchema.shape,
     ...upstreamRefreshOptionsSchema.shape,
+    ...deadLetterOptionsSchema.shape,
 
     /**
      * Check client for an existing scrobble at the same recorded time as the "new" track to be scrobbled. If an existing scrobble is found this track is not track scrobbled.
@@ -143,17 +144,6 @@ export const commonClientOptionsSchema = z.object({
     }).optional().meta({
         description: "Options used for increasing verbosity of logging in MS (used for debugging)"
     }),
-    /**
-     * Number of times MS should automatically retry scrobbles in dead letter queue
-     *
-     * @default 3
-     * @examples [3]
-     * */
-    deadLetterRetries: z.number().optional().meta({
-        description: "Number of times MS should automatically retry scrobbles in dead letter queue",
-        default: 3,
-        examples: [3]
-    }),
 
     /** Enhance/correct Play data by applying a transform pipeline */
     playTransform: playTransformOptionsSchema.optional().meta({description: 'Enhance/correct Play data by applying a transform pipeline'}),

src/backend/common/infrastructure/config/client/koito.ts

@@ -3,6 +3,7 @@ import type {UnixTimestamp} from "../../../../../core/Atomic.ts";
 import {componentTypeSchema} from "../../../../../core/Atomic.ts";
 import {requestRetryOptionsSchema} from "../common.ts";
 import {commonClientConfigSchema, commonClientDataSchema, type EnvClientSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export interface ListensResponse {
     items: ListenObjectResponse[]
@@ -54,7 +55,7 @@ export const koitoDataSchema = z.object({
      *
      * @examples ["http://192.168.0.100:4110"]
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "URL for the Koito server",
         examples: ["http://192.168.0.100:4110"]
     }),

src/backend/common/infrastructure/config/client/librefm.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import {requestRetryOptionsSchema} from "../common.ts";
 import {commonClientConfigSchema, commonClientDataSchema, type EnvClientSchema} from "./index.ts";
 import {lastfmClientOptionsSchema} from "./lastfm.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const librefmDataSchema = z.object({
     ...commonClientDataSchema.shape,
@@ -43,7 +44,7 @@ export const librefmDataSchema = z.object({
      *
      * @default 'https://libre.fm/2.0/'
     */
-    urlBase: z.string().optional().meta({
+    urlBase: httpUrl.optional().meta({
         description: "(Optional) The host and path prefix for your Libre.fm instance",
         default: "https://libre.fm/2.0/"
     }),

src/backend/common/infrastructure/config/client/listenbrainz.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import {componentTypeSchema} from "../../../../../core/Atomic.ts";
 import {requestRetryOptionsSchema} from "../common.ts";
 import {commonClientConfigSchema, commonClientDataSchema, type EnvClientSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const listenBrainzDataSchema = z.object({
     ...requestRetryOptionsSchema.shape,
@@ -11,7 +12,7 @@ export const listenBrainzDataSchema = z.object({
      * @examples ["https://api.listenbrainz.org/"]
      * @default "https://api.listenbrainz.org/"
      * */
-    url: z.string().optional().meta({
+    url: httpUrl.optional().meta({
         description: "URL for the ListenBrainz server, if not using the default",
         default: "https://api.listenbrainz.org/",
         examples: ["https://api.listenbrainz.org/"]

src/backend/common/infrastructure/config/client/maloja.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import {componentTypeSchema} from "../../../../../core/Atomic.ts";
 import {requestRetryOptionsSchema} from "../common.ts";
 import {commonClientConfigSchema, commonClientDataSchema, type EnvClientSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const malojaDataSchema = z.object({
     ...requestRetryOptionsSchema.shape,
@@ -10,7 +11,7 @@ export const malojaDataSchema = z.object({
      *
      * @examples ["http://localhost:42010"]
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "URL for maloja server",
         examples: ["http://localhost:42010"]
     }),

src/backend/common/infrastructure/config/client/rocksky.ts

@@ -34,7 +34,7 @@ export const rockSkyDataSchema = z.object({
      *
      * */
     handle: z.string().meta({
-        description: "The **fully-qualified** handle for your ATPRoto/Bluesky account, like:"
+        description: "The **fully-qualified** handle for your ATPRoto/Bluesky account"
     }),
 });
 

src/backend/common/infrastructure/config/common.ts

@@ -155,6 +155,21 @@ export const monitorOptionsSchema = z.object({
 })
 export type MonitorOptions = z.infer<typeof monitorOptionsSchema>;
 
+export const deadLetterOptionsSchema = z.object({
+    /**
+     * Number of times MS should automatically retry Plays in dead letter queue
+     *
+     * @default 3
+     * @examples [3]
+     * */
+    deadLetterRetries: z.number().optional().meta({
+        description: "Number of times MS should automatically retry Plays in dead letter queue",
+        default: 3,
+        examples: [3]
+    })
+})
+export type DeadLetterOptions = z.infer<typeof deadLetterOptionsSchema>;
+
 export type UnparsedConfig<T extends (SourceType | ClientType)> = {config: object, type: T, source?: 'file' | 'aio' | 'env', pos: string};
 
 export const generateConfigLocation = (configType: string, config: UnparsedConfig<any>): string => {

src/backend/common/infrastructure/config/health/webhooks.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export interface WebhookPayload {
     title?: string
@@ -96,7 +97,7 @@ export const ntfyConfigSchema = z.object({
      *
      * @examples ["http://192.168.0.100:8078"]
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "The URL of the Ntfy server",
         examples: ["http://192.168.0.100:8078"]
     }),
@@ -149,7 +150,7 @@ export const appriseConfigSchema = z.object({
      *
      * @examples ["http://192.168.0.100:8078"]
      * */
-    host: z.string().meta({
+    host: httpUrl.meta({
         description: "The URL of the apprise-api server",
         examples: ["http://192.168.0.100:8078"]
     }),

src/backend/common/infrastructure/config/source/applemusic.ts

@@ -24,7 +24,9 @@ export const appleMusicDataSchema = z.object({
      *
      * @examples ["https://music.apple.com"]
      */
-    origin: z.string().optional().meta({
+    origin: z.url({
+        protocol: /^https$/,
+    }).optional().meta({
         description: "Origin header to include in every Apple Music API request.",
         examples: ["https://music.apple.com"]
     }),
@@ -88,7 +90,7 @@ const envDataSchema = z.object({
     APPLEMUSIC_TEAM_ID: appleMusicKeySchema.shape.teamId.optional(),
     APPLEMUSIC_KEY_P8: appleMusicKeySchema.shape.p8.optional(),
     APPLEMUSIC_MEDIA_USER_TOKEN: appleMusicDataSchema.shape.mediaUserToken,
-    APPLEMUSIC_TOKEN: appleMusicDataSchema.shape.token,
+    APPLEMUSIC_TOKEN: appleMusicDataSchema.shape.token.optional(),
     APPLEMUSIC_ORIGIN_HEADER: appleMusicDataSchema.shape.origin,
     APPLEMUSIC_RECOVER_UNCHANGED_TOP_HISTORY: z.stringbool().optional().meta(appleMusicOptions.shape.recoverUnchangedTopHistory.meta()),
     APPLEMUSIC_NORMALIZE_ALBUM: z.stringbool().optional().meta(appleMusicOptions.shape.normalizeAlbum.meta())
@@ -104,7 +106,7 @@ export const envSchemas: EnvSourceSchema<typeof envDataSchema, AppleMusicSourceC
         if(envKeyKeys.some(x => partial[x] !== undefined)) {
             for(const k of envKeyKeys) {
                 if(partial[k] === undefined) {
-                    throw new SimpleError(`ENV ${partial[k]} is not defined but when providing auth via MusicKit Key you must provide all of these: ${envKeyKeys.join(', ')}`);
+                    throw new SimpleError(`ENV ${k} is not defined but when providing auth via MusicKit Key you must provide all of these: ${envKeyKeys.join(', ')}`);
                 }
                 appleMusicKey = {
                     id: partial.APPLEMUSIC_KEY_ID,

src/backend/common/infrastructure/config/source/azuracast.ts

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import {commonSourceConfigSchema, commonSourceDataSchema, commonSourceOptionsSchema, manualListeningOptionsSchema, type EnvSourceSchema} from "./index.ts";
 import { parseBoolStrict } from "../../../../utils.ts";
+import { wsUrl } from "../../../../utils/ZodUtils.ts";
 
 export const azuraStationInfoResponseSchema = z.object({
     id: z.string(),
@@ -71,7 +72,7 @@ export const azuracastDataSchema = z.object({
      *
      * @examples ["https://radio.mydomain.tld", "http://localhost:80"]
      * */
-    url: z.string().meta({
+    url: wsUrl.meta({
         description: "Base URL of the Azuracast instance",
         examples: ["https://radio.mydomain.tld", "http://localhost:80"]
     }),

src/backend/common/infrastructure/config/source/chromecast.ts

@@ -17,7 +17,7 @@ export const chromecastDeviceInfoSchema = z.object({
      *
      * @examples ["192.168.0.115"]
      * */
-    address: z.string().meta({
+    address: z.ipv4().meta({
         description: "The IP address of the device",
         examples: ["192.168.0.115"]
     }),

src/backend/common/infrastructure/config/source/deezer.ts

@@ -81,6 +81,14 @@ export type DeezerInternalData = z.infer<typeof deezerInternalDataSchema>;
 
 export const deezerInternalSourceOptionsSchema = z.object({
     ...commonSourceOptionsSchema.shape,
+    /**
+     * Set the heuristic level of duplicate/repeated track pruning from listening history.
+     * 
+     * Some third party integrations (Sonos) cause Deezer to report the same track many times in listening history
+     * 
+     * * `true` => detect plays with play times at exact, close to, or fuzzy (beginning/end of predicated play time + duration)
+     * * `aggressive` => above AND check for plays during previous play times that occurred during the track (50% +/- duration plus playedAt date)
+     */
     fuzzyDiscoveryIgnore: z.union([z.boolean(), z.literal('aggressive')]).optional(),
 });
 

src/backend/common/infrastructure/config/source/icecast.ts

@@ -1,5 +1,6 @@
 import * as z from "zod";
 import {commonSourceConfigSchema, commonSourceDataSchema, commonSourceOptionsSchema, manualListeningOptionsSchema, type EnvSourceSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export interface IcecastMetadata {
     icy?: {
@@ -37,7 +38,7 @@ export const icecastDataSchema = z.object({
     /**
      * The Icecast stream URL
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "The Icecast stream URL"
     }),
 });

src/backend/common/infrastructure/config/source/index.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import {requestRetryOptionsSchema, commonConfigSchema, monitorOptionsSchema} from "../common.ts";
+import {requestRetryOptionsSchema, commonConfigSchema, monitorOptionsSchema, deadLetterOptionsSchema} from "../common.ts";
 import {retentionConfigDurationValueSchema} from "../database.ts";
 import {playTransformOptionsSchema} from "../../../../../core/Transform.ts";
 import type { PipeUnwrapDirection } from "../../../../utils/ZodUtils.ts";
@@ -73,6 +73,7 @@ export const fileLogOptionsSchema = z.object({
 export const commonSourceOptionsSchema = z.object({
     ...monitorOptionsSchema.shape,
     ...sourceRetryOptionsSchema.shape,
+    ...deadLetterOptionsSchema.shape,
     /**
      * * If this source has INGRESS to MS (sends a payload, rather than MS GETTING requesting a payload) then setting this option to true will make MS log the payload JSON to DEBUG output
      * * If this source is POLLING then it will log the raw data for each unique track/response the first time it is seen

src/backend/common/infrastructure/config/source/jriver.ts

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import {pollingOptionsSchema, requestRetryOptionsSchema} from "../common.ts";
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const jRiverDataSchema = z.object({
     ...commonSourceDataSchema.shape,
@@ -24,7 +25,10 @@ export const jRiverDataSchema = z.object({
      * @examples ["http://localhost:52199/MCWS/v1/"]
      * @default "http://localhost:52199/MCWS/v1/"
      * */
-    url: z.string().meta({
+    url: z.union([
+        httpUrl,
+        z.ipv4()
+        ]).meta({
         description: "URL of the JRiver HTTP server to connect to",
         default: "http://localhost:52199/MCWS/v1/",
         examples: ["http://localhost:52199/MCWS/v1/"]

src/backend/common/infrastructure/config/source/kodi.ts

@@ -1,6 +1,7 @@
 import * as z from "zod";
 import {pollingOptionsSchema} from "../common.ts";
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const kodiDataSchema = z.object({
     ...commonSourceDataSchema.shape,
@@ -23,7 +24,7 @@ export const kodiDataSchema = z.object({
      * @examples ["http://localhost:8080/jsonrpc"]
      * @default "http://localhost:8080/jsonrpc"
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "URL of the Kodi HTTP server to connect to",
         default: "http://localhost:8080/jsonrpc",
         examples: ["http://localhost:8080/jsonrpc"]

src/backend/common/infrastructure/config/source/mopidy.ts

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import {pollingOptionsSchema} from "../common.ts";
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
-import { transformSplitMaybeString } from "../../../../utils/ZodUtils.ts";
+import { transformSplitMaybeString, wsUrl } from "../../../../utils/ZodUtils.ts";
 
 export const mopidyDataSchema = z.object({
     ...commonSourceDataSchema.shape,
@@ -26,7 +26,7 @@ export const mopidyDataSchema = z.object({
      * @examples ["ws://localhost:6680/mopidy/ws/"]
      * @default "ws://localhost:6680/mopidy/ws/"
      * */
-    url: z.string().optional().meta({
+    url: wsUrl.optional().meta({
         description: "URL of the Mopidy HTTP server to connect to",
         default: "ws://localhost:6680/mopidy/ws/",
         examples: ["ws://localhost:6680/mopidy/ws/"]

src/backend/common/infrastructure/config/source/musiccast.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import { REPORTED_PLAYER_STATUSES } from '../../../../../core/Atomic.ts';
 import type {ReportedPlayerStatus} from '../../../../../core/Atomic.ts';
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export type PlaybackStatus = 'play' | 'stop' | 'pause' | 'fast_reverse' | 'fast_forward'
 
@@ -78,7 +79,10 @@ export const musicCastDataSchema = z.object({
      *
      * @examples [["192.168.0.101","http://192.168.0.101/YamahaExtendedControl"]]
      * */
-    url: z.string().meta({
+    url: z.union([
+        httpUrl,
+        z.ipv4()
+    ]).meta({
         description: "The host or URL of the YamahaExtendedControl endpoint to use",
         examples: [["192.168.0.101", "http://192.168.0.101/YamahaExtendedControl"]]
     }),

src/backend/common/infrastructure/config/source/musikcube.ts

@@ -1,5 +1,6 @@
 import * as z from "zod";
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
+import { wsUrl } from "../../../../utils/ZodUtils.ts";
 
 export const PLAYBACK_STATUS_PLAYING_MC = 'playing';
 export const PLAYBACK_STATUS_PAUSED_MC = 'paused';
@@ -96,7 +97,7 @@ export const musikcubeDataSchema = z.object({
      * @examples ["ws://localhost:7905"]
      * @default "ws://localhost:7905"
      * */
-    url: z.string().optional().meta({
+    url: wsUrl.optional().meta({
         description: "URL of the Musikcube Websocket (Metadata) server to connect to",
         default: "ws://localhost:7905",
         examples: ["ws://localhost:7905"]

src/backend/common/infrastructure/config/source/plex.ts

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import {pollingOptionsSchema} from "../common.ts";
 import {commonSourceConfigSchema, commonSourceDataSchema, commonSourceOptionsSchema, type EnvSourceSchema} from "./index.ts";
-import { envMetaNormalize, transformSplitMaybeString } from "../../../../utils/ZodUtils.ts";
+import { envMetaNormalize, httpUrl, transformSplitMaybeString } from "../../../../utils/ZodUtils.ts";
 
 export const plexApiDataSchema = z.object({
     ...commonSourceDataSchema.shape,
@@ -10,7 +10,7 @@ export const plexApiDataSchema = z.object({
     /**
      * http(s)://HOST:PORT of the Plex server to connect to
      * */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "http(s)://HOST:PORT of the Plex server to connect to"
     }),
 

src/backend/common/infrastructure/config/source/sonos.ts

@@ -11,7 +11,7 @@ export const sonosDataSchema = z.object({
      *
      * @examples ["192.168.0.170"]
      * */
-    host: z.string().meta({
+    host: z.ipv4().meta({
         description: "IP address of any connected Sonos speaker or device",
         examples: ["192.168.0.170"]
     }),

src/backend/common/infrastructure/config/source/spotify.ts

@@ -29,7 +29,9 @@ export const spotifySourceDataSchema = z.object({
      * @default "http://localhost:9078/callback"
      * @examples ["http://localhost:9078/callback"]
      * */
-    redirectUri: z.string().optional().meta({
+    redirectUri: z.url({
+        protocol: /^https?$/,
+    }).optional().meta({
         description: "spotify redirect URI -- required only if not the default shown here.",
         default: "http://localhost:9078/callback",
         examples: ["http://localhost:9078/callback"]

src/backend/common/infrastructure/config/source/ymbridge.ts

@@ -1,12 +1,13 @@
 import * as z from "zod";
 import {pollingOptionsSchema} from "../common.ts";
 import {commonSourceConfigSchema, commonSourceDataSchema, type EnvSourceSchema} from "./index.ts";
+import { httpUrl } from "../../../../utils/ZodUtils.ts";
 
 export const yandexMusicBridgeDataSchema = z.object({
     ...commonSourceDataSchema.shape,
     ...pollingOptionsSchema.shape,
     /** URL of the local Python bridge, for example http://yandex-music-bridge:9980 */
-    url: z.string().meta({
+    url: httpUrl.meta({
         description: "URL of the local Python bridge, for example http://yandex-music-bridge:9980"
     }),
     /** Optional API key sent as X-API-Key to the bridge */

src/backend/common/transforms/AbstractTransformer.ts

@@ -1,5 +1,5 @@
 import { childLogger, type Logger } from "@foxxmd/logging";
-import type { PlayObject, TransformerCommon, TransformerCommonConfig } from "../../../core/Atomic.ts";
+import type { OptionalCacheUsage, PlayObject, TransformerCommon, TransformerCommonConfig } from "../../../core/Atomic.ts";
 import { isStageTyped, testWhenConditions } from "../../utils/PlayTransformUtils.ts";
 import AbstractInitializable from "../AbstractInitializable.ts";
 import type { StageConfig } from "../../../core/Transform.ts";
@@ -61,13 +61,16 @@ export default abstract class AbstractTransformer<T = any, Y extends StageConfig
 
     protected abstract doParseConfig(data: StageConfig): Y;
 
-    public async handle(data: Y, play: PlayObject): Promise<PlayObject> {
+    public async handle(data: Y, play: PlayObject, opts?: OptionalCacheUsage): Promise<PlayObject> {
+        const {
+            useCachedResult = true,
+        } = (opts ?? {});
         const cacheKey = `transformResult-${this.configHash}-${hashObject(data)}-${hashObject(playContentInvariantTransform(play))}`
         try {
-            const cachedTransformData = await this.cache.get<T>(cacheKey);
+            const cachedTransformData = useCachedResult ? await this.cache.get<T>(cacheKey) : undefined;
             if(cachedTransformData !== undefined) {
                 this.logger.debug('Transform cache hit');
-                const transformed = await this.doHandle(data, play, cachedTransformData);
+                const transformed = await this.doHandle(data, play, cachedTransformData, opts);
                 return transformed;
             }
         } catch (e) {
@@ -82,7 +85,7 @@ export default abstract class AbstractTransformer<T = any, Y extends StageConfig
         }
 
         try {
-            await this.handlePreFetch(play, data);
+            await this.handlePreFetch(play, data, opts);
         } catch (e) {
             if(e instanceof SkipTransformStageError) {
                 await this.cache.set(cacheKey, play, this.config.options?.ttl ?? '15s');
@@ -93,13 +96,13 @@ export default abstract class AbstractTransformer<T = any, Y extends StageConfig
         let transformData: T;
         let fetchedTransformData: any;
         try {
-            fetchedTransformData = await this.getTransformerData(play, data);
+            fetchedTransformData = await this.getTransformerData(play, data, opts);
         } catch (e) {
             throw new Error(`Could not fetch transformer data`, { cause: e });
         }
 
         try {
-            transformData = await this.handlePostFetch(play, fetchedTransformData, data);
+            transformData = await this.handlePostFetch(play, fetchedTransformData, data, opts);
         } catch (e) {
             if(e instanceof StagePrerequisiteError) {
                 await this.cache.set(cacheKey, play, this.config.options?.ttl ?? '15s');
@@ -107,22 +110,22 @@ export default abstract class AbstractTransformer<T = any, Y extends StageConfig
             throw new Error('postFetch did not pass', { cause: e });
         }
 
-        const transformed = await this.doHandle(data, play, transformData);
+        const transformed = await this.doHandle(data, play, transformData, opts);
         await this.cache.set(cacheKey, transformData, this.config.options?.ttl ?? '15s');
         return transformed;
     }
 
-    protected abstract doHandle(data: StageConfig, play: PlayObject, transformData: T): Promise<PlayObject>;
+    protected abstract doHandle(data: StageConfig, play: PlayObject, transformData: T, opts?: OptionalCacheUsage): Promise<PlayObject>;
 
-    public async getTransformerData(play: PlayObject, stageConfig: Y): Promise<any> {
+    public async getTransformerData(play: PlayObject, stageConfig: Y, opts?: OptionalCacheUsage): Promise<any> {
         return undefined;
     }
 
-    public async handlePostFetch(play: PlayObject, transformData: any, stageConfig: Y): Promise<T> {
+    public async handlePostFetch(play: PlayObject, transformData: any, stageConfig: Y, opts?: OptionalCacheUsage): Promise<T> {
         return transformData;
     }
 
-    public async handlePreFetch(play: PlayObject, stageConfig: Y): Promise<void> {
+    public async handlePreFetch(play: PlayObject, stageConfig: Y, opts?: OptionalCacheUsage): Promise<void> {
         return
     }
 }

src/backend/common/transforms/MusicbrainzTransformer.ts

@@ -1,4 +1,4 @@
-import { type ArtistCredit, asMBReleasePrimaryGroupType, asMBReleaseSecondaryGroupType, asMBReleaseStatus, DEFAULT_MISSING_TYPES, type LifecycleInput, type MBReleaseGroupPrimaryType, type MBReleaseGroupSecondaryType, type MBReleaseStatus, type MissingMbidType, type PlayObject, type TrackMeta, type TransformerCommon, type TransformOptions } from "../../../core/Atomic.ts";
+import { type ArtistCredit, asMBReleasePrimaryGroupType, asMBReleaseSecondaryGroupType, asMBReleaseStatus, DEFAULT_MISSING_TYPES, type LifecycleInput, type MBReleaseGroupPrimaryType, type MBReleaseGroupSecondaryType, type MBReleaseStatus, type MissingMbidType, type OptionalCacheUsage, type PlayObject, type TrackMeta, type TransformerCommon, type TransformOptions } from "../../../core/Atomic.ts";
 import { isWhenCondition, testWhenConditions } from "../../utils/PlayTransformUtils.ts";
 import type {WebhookPayload} from "../infrastructure/config/health/webhooks.ts";
 import type {ExternalMetadataTerm, PlayTransformMetadataStage} from "../../../core/Transform.ts";
@@ -429,7 +429,7 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
         }
     }
 
-    public async getTransformerData(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async getTransformerData(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts?: OptionalCacheUsage): Promise<IRecordingMSList> {
         
         const {
             // preserve order of search from before searchOrder
@@ -443,25 +443,25 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
             try {
                 switch(searchType) {
                     case 'isrc':
-                        results = await this.searchByIsrc(play, stageConfig);
+                        results = await this.searchByIsrc(play, stageConfig, opts);
                         break;
                     case 'album':
-                        results = await this.searchByAlbum(play, stageConfig);
+                        results = await this.searchByAlbum(play, stageConfig, opts);
                         break;
                     case 'artist':
-                        results = await this.searchByArtist(play, stageConfig);
+                        results = await this.searchByArtist(play, stageConfig, opts);
                         break;
                     case 'basic':
-                        results = await this.searchByBasicFields(play, stageConfig);
+                        results = await this.searchByBasicFields(play, stageConfig, opts);
                         break;
                     case 'freetext':
-                        results = await this.searchByFreeText(play, stageConfig);
+                        results = await this.searchByFreeText(play, stageConfig, opts);
                         break;
                     case 'basicorids':
-                        results = await this.searchByBasicFieldsOrMBIDs(play, stageConfig);
+                        results = await this.searchByBasicFieldsOrMBIDs(play, stageConfig, opts);
                         break;
                     case 'mbidrecording':
-                        results = await this.searchByRecordingMbid(play, stageConfig);
+                        results = await this.searchByRecordingMbid(play, stageConfig, opts);
                         break;
                 }
                 queries.push({type: `mbQuery-${searchType}${results.recordings.length === 0 ? '-empty' : ''}`, input: results.requestQuery});
@@ -486,12 +486,12 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
         return {...results, requestQueries: queries};
     }
 
-    public async searchByBasicFields(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByBasicFields(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         this.logger.debug({labels: ['Basic Search']}, 'Searching by artist/album/track');
-        return await this.api.searchByRecording(play);
+        return await this.api.searchByRecording(play, opts);
     }
 
-    public async searchByBasicFieldsOrMBIDs(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByBasicFieldsOrMBIDs(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         const using: UsingTypes[] = [];
         const {
             data: {
@@ -512,31 +512,31 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
         using.push((brainz.artist ?? []).length > 0 ? 'mbidartist' : 'artist');
 
         this.logger.debug({labels: ['Basic Or MBID Search']}, `Searching using ${using.join(', ')}}`);
-        return await this.api.searchByRecording(play, {using});
+        return await this.api.searchByRecording(play, {using, ...opts});
     }
 
-    public async searchByIsrc(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByIsrc(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         if(play.data.isrc !== undefined) {
             this.logger.debug({labels: ['ISRC Search']},'Searching with ISRC');
-            return await this.api.searchByRecording(play, {using: ['isrc']});
+            return await this.api.searchByRecording(play, {using: ['isrc'], ...opts});
         }
         throw new SearchPrerequisiteError('Play does not have ISRC');
     }
 
-    public async searchByRecordingMbid(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByRecordingMbid(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         if(play.data.meta?.brainz?.recording !== undefined) {
             this.logger.debug({labels: ['MBID Search']},'Searching with Recording MBID');
-            return await this.api.searchByRecording(play, {using: ['mbidrecording']});
+            return await this.api.searchByRecording(play, {using: ['mbidrecording'], ...opts});
         }
         throw new SearchPrerequisiteError('Play does not have recording MBID');
     }
 
-    public async searchByAlbum(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByAlbum(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         // possibly the artist is incorrect (may be combined as one string)
         // if we have an album we can likely still get a decent hit w/o using artist
         if(play.data.album !== undefined && play.data.artists !== undefined && play.data.artists.length > 0) {
             this.logger.debug({labels: ['Album Search']},'Searching with only track+album');
-            return await this.api.searchByRecording(play, {using: ['title','album']});
+            return await this.api.searchByRecording(play, {using: ['title','album'], ...opts});
         }
         if(play.data.album === undefined) {
             throw new SearchPrerequisiteError('Play does not have an album');
@@ -549,7 +549,7 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
         }
     }
 
-    public async searchByArtist(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByArtist(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         const {
             searchArtistMethod = this.defaults.searchArtistMethod,
         } = stageConfig;
@@ -582,7 +582,7 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
                     // so we split out all artists by all found delimiters
                     const nativePlay = nativeParse(play, {titleClean: true, delimiters: DELIMITERS});
                     this.logger.debug({labels: ['Parsed Artist Search']},'Searching with aggressive native parsing');
-                    return await this.api.searchByRecording(nativePlay, {using: ['title','artist']});
+                    return await this.api.searchByRecording(nativePlay, {using: ['title','artist'], ...opts});
                 }
             }
 
@@ -594,9 +594,9 @@ export default class MusicbrainzTransformer extends AtomicPartsTransformer<Exter
             }
     }
 
-    public async searchByFreeText(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage): Promise<IRecordingMSList> {
+    public async searchByFreeText(play: PlayObject, stageConfig: MusicbrainzTransformerDataStage, opts: OptionalCacheUsage = {}): Promise<IRecordingMSList> {
         this.logger.debug({labels: ['Freetext Search']},'Trying freetext search');
-        const results = await this.api.searchByRecording(play, {freetext: true}) as IRecordingMSList;
+        const results = await this.api.searchByRecording(play, {freetext: true, ...opts}) as IRecordingMSList;
         results.freeText = true;
         return results;
     }

src/backend/common/transforms/TransformerManager.ts

@@ -1,6 +1,6 @@
 import { childLogger, type Logger } from "@foxxmd/logging";
 import type AbstractTransformer from "./AbstractTransformer.ts";
-import type {TransformerCommonConfig} from "../../../core/Atomic.ts";
+import type {OptionalCacheUsage, TransformerCommonConfig} from "../../../core/Atomic.ts";
 import UserTransformer from "./UserTransformer.ts";
 import type {StageConfig} from "../../../core/Transform.ts";
 import type {PlayObject} from "../../../core/Atomic.ts";
@@ -146,10 +146,10 @@ export default class TransformerManager {
         return config;
     }
 
-    public async handleStage(data: StageConfig, play: PlayObject, asyncId: string = nanoid(6)): Promise<[PlayObject, string]> {
+    public async handleStage(data: StageConfig, play: PlayObject, opts: {asyncId?: string} & OptionalCacheUsage): Promise<[PlayObject, string]> {
         const t: AbstractTransformer = this.getTransformerByStage(data);
         try {
-            const transformedPlay = await this.asyncStore.run(asyncId, async () => {
+            const transformedPlay = await this.asyncStore.run(opts.asyncId ?? nanoid(6), async () => {
                 return await t.handle(data, play);
             });
             return [transformedPlay, t.name];

src/backend/common/vendor/JRiverApiClient.ts

@@ -4,6 +4,7 @@ import xml2js from 'xml2js';
 import { type AbstractApiOptions, DEFAULT_RETRY_MULTIPLIER } from "../infrastructure/Atomic.ts";
 import type {JRiverData} from "../infrastructure/config/source/jriver.ts";
 import AbstractApiClient from "./AbstractApiClient.ts";
+import { AuthError } from '../errors/MSErrors.ts';
 
 const parser = new xml2js.Parser({'async': true});
 
@@ -155,7 +156,7 @@ export class JRiverApiClient extends AbstractApiClient {
             if(this.config.username === undefined || this.config.password === undefined) {
                 msg = 'Authentication failed. No username/password was provided in config! Did you mean to do this?';
             }
-            throw new Error(msg, {cause: e});
+            throw new AuthError(msg, {cause: e});
         }
     }
 

src/backend/common/vendor/KodiApiClient.ts

@@ -9,6 +9,7 @@ import type {KodiData} from "../infrastructure/config/source/kodi.ts";
 import AbstractApiClient from "./AbstractApiClient.ts";
 import { baseFormatPlayObj } from "../../utils/PlayTransformUtils.ts";
 import { artistNamesToCredits } from "../../../core/StringUtils.ts";
+import { AuthError } from "../errors/MSErrors.ts";
 
 interface KodiDuration {
     hours: number
@@ -150,7 +151,7 @@ export class KodiApiClient extends AbstractApiClient {
             if(this.config.username === undefined || this.config.password === undefined) {
                 msg = 'Authentication failed. No username/password was provided in config! Did you mean to do this?';
             }
-            throw new Error(msg, {cause: e});
+            throw new AuthError(msg, {cause: e});
         }
     }
 

src/backend/common/vendor/LastfmApiClient.ts

@@ -13,14 +13,16 @@ import { type AbstractApiOptions, DEFAULT_RETRY_MULTIPLIER, type FormatPlayObjec
 import type {LastfmData} from "../infrastructure/config/client/lastfm.ts";
 import AbstractApiClient from "./AbstractApiClient.ts";
 import { normalizeStr, parseArtistCredits } from "../../utils/StringUtils.ts";
-import { LastFMUser, LastFMAuth, LastFMTrack, type LastFMUserGetRecentTracksResponse, type LastFMBooleanNumber, type LastFMUpdateNowPlayingResponse, type LastFMUserGetInfoResponse, type LastFMUserGetRecentTracksParams } from 'lastfm-ts-api';
+import { LastFMUser, LastFMAuth, LastFMTrack, type LastFMUserGetRecentTracksResponse, type LastFMBooleanNumber, type LastFMUpdateNowPlayingResponse, type LastFMUserGetInfoResponse, type LastFMUserGetRecentTracksParams, LastFMResponseError } from 'lastfm-ts-api';
 import clone from 'clone';
 import type { IncomingMessage } from "http";
 import { baseFormatPlayObj } from "../../utils/PlayTransformUtils.ts";
-import { ScrobbleSubmitError, SimpleError } from "../errors/MSErrors.ts";
+import { AuthError, ScrobbleSubmitError, SimpleError } from "../errors/MSErrors.ts";
 import { redactString } from "@foxxmd/redact-string";
 import dns from 'node:dns/promises';
 import xml2js from 'xml2js';
+import { findCauseByFunc } from "../../utils/ErrorUtils.ts";
+import * as z from 'zod';
 
 const badErrors = [
     'api key suspended',
@@ -30,6 +32,12 @@ const badErrors = [
     'invalid parameters'
 ];
 
+const unrecoverableAuthErrorCodes = [
+    10, // invalid api key
+    13, // invalid method signature
+    26, // api key suspended
+]
+
 const retryErrors = [
     'operation failed',
     'service offline',
@@ -247,7 +255,7 @@ export default class LastfmApiClient extends AbstractApiClient implements Pagina
         if (this.sessionKey === undefined) {
             this.logger.warn('No session key found. User interaction for authentication required.');
             this.logger.info(`Redirect URL that will be used on auth callback: '${this.redirectUri}'`);
-            throw new SimpleError('No session key found. User interaction for authentication required.');
+            throw new AuthError('No session key found. User interaction for authentication required.', {unrecoverable: false});
         }
         try {
             // existing lastfm clients are ok with getting user from getInfo
@@ -269,11 +277,32 @@ export default class LastfmApiClient extends AbstractApiClient implements Pagina
             this.logger.info(`Client authorized for user ${this.user}`)
             return true;
         } catch (e) {
+            if(e instanceof AuthError) {
+                throw e;
+            }
             this.logger.error('Testing auth failed');
             if(isNodeNetworkException(e)) {
                 this.logger.error(`Could not communicate with ${this.upstreamName} API`);
+                throw new AuthError('Testing auth failed', {cause: e, unrecoverable: false});
             }
-            throw e;
+            let unrecoverable: boolean;
+            if(e instanceof LastFMResponseError) {
+                try {
+                    const errorContent = JSON.parse(e.content);
+                    if(`error` in errorContent) {
+                        unrecoverable = unrecoverableAuthErrorCodes.includes(errorContent.error);
+                    }
+                } catch (e) {
+                    // swallow
+                }
+            }
+            if(unrecoverable === undefined) {
+                const errorWithMessage = findCauseByFunc(e, (ee) => `response` in ee) as Error & {response: IncomingMessage} | undefined;
+                if(errorWithMessage !== undefined) {
+                    unrecoverable = [401,403].includes(errorWithMessage.response.statusCode);
+                }
+            }
+            throw new AuthError('Testing auth failed', {cause: e, unrecoverable});
         }
     }
 
@@ -541,7 +570,7 @@ export class LastFMIgnoredScrobble extends UpstreamError {
 
 }
 
-export const scrobblePayloadToPlay = (obj: LastFMScrobbleRequestPayload): PlayObject => {
+export const scrobblePayloadToPlay = (obj: LastFmSingleSubmitPayload): PlayObject => {
     const {
         artist,
         track,
@@ -812,6 +841,72 @@ export interface LastFMScrobblePayload  {
         mbid?: string
 }
 
+// bodies arrive as urlencoded form data, so numeric fields are always strings (or string[] for batch keys) on the wire
+const lastfmNumericStringSchema = z.coerce.number().int().positive();
+
+export const lastfmSubmitPayloadSchema = z.object({
+    artist: z.string(),
+    track: z.string(),
+    album: z.string().optional(),
+    albumArtist: z.string().optional(),
+    mbid: z.string().optional(),
+    duration: lastfmNumericStringSchema.optional(),
+    sk: z.string().optional(),
+    api_key: z.string().optional()
+});
+
+export const lastfmSubmitMultiPayloadSchema = z.object({
+    artist: z.array(z.string()),
+    track: z.array(z.string()),
+    album: z.array(z.string()).optional(),
+    albumArtist: z.array(z.string()).optional(),
+    mbid: z.array(z.string()).optional(),
+    duration: z.array(lastfmNumericStringSchema).optional(),
+    sk: z.string().optional(),
+    api_key: z.string().optional()
+});
+
+export const lastfmScrobblePayloadSchema = z.object({
+    method: z.literal('track.scrobble'),
+    ...lastfmSubmitPayloadSchema.shape,
+    timestamp: lastfmNumericStringSchema,
+}).meta({title: 'Single Scrobble'});
+export type LastfmScrobblePayload = z.infer<typeof lastfmScrobblePayloadSchema>;
+export const lastfmScrobbleMultiPayloadSchema = z.object({
+    method: z.literal('track.scrobble'),
+    ...lastfmSubmitMultiPayloadSchema.shape,
+    timestamp: z.array(lastfmNumericStringSchema),
+}).meta({title: 'Bulk Scrobbles'});
+export const lastfmScrobbleMaybeMultiPayloadSchema = z.union([lastfmScrobblePayloadSchema,lastfmScrobbleMultiPayloadSchema]).meta({title: 'Single or Bulk Scrobble'});
+export type LastfmScrobbleMaybeMultiPayload = z.infer<typeof lastfmScrobbleMaybeMultiPayloadSchema>;
+
+export type LastFmScrobblePayload = z.infer<typeof lastfmScrobblePayloadSchema>;
+
+export const lastfmNowPlayingPayloadSchema = z.object({
+    method: z.literal('track.updateNowPlaying'),
+    ...lastfmSubmitPayloadSchema.shape,
+}).meta({title: 'Update Now Playing'});
+export type LastFmNowPlayingPayload = z.infer<typeof lastfmNowPlayingPayloadSchema>;
+
+export type LastFmSubmitPayload = LastfmScrobbleMaybeMultiPayload | LastFmNowPlayingPayload;
+export type LastFmSingleSubmitPayload = LastfmScrobblePayload | LastFmNowPlayingPayload;
+
+export const lastfmAuthRequestPayloadSchema = z.object({
+    method: z.literal('auth.getMobileSession'),
+    username: z.string().optional(),
+    password: z.string().optional(),
+    api_key: z.string().optional(),
+}).meta({title: 'Get Mobile Auth Session'});
+
+export const lastfmRequestSchema = z.union([
+    lastfmScrobbleMaybeMultiPayloadSchema,
+    z.discriminatedUnion("method", [
+        lastfmNowPlayingPayloadSchema,
+        lastfmAuthRequestPayloadSchema
+    ]).meta({title: 'Update Now Playing or Mobile Auth Session'})
+]);
+export type LastFmRequest = z.infer<typeof lastfmRequestSchema>;
+
 export interface LastFMScrobbleRequestPayload extends LastFMScrobblePayload {
     method: string
 }
@@ -821,7 +916,7 @@ const lfmPayloadKeysRequired: LastFMPayloadkey[] = ['track','artist'];
 //const lfmPayloadKeysOptional: LastFMPayloadkey[] = ['duration','album','albumArtist','mbid'];
 //const lfmPayloadKeys: LastFMPayloadkey[] = [...lfmPayloadKeysRequired, ...lfmPayloadKeysOptional];
 
-export const ingressPayloads = (obj: Record<LastFMPayloadkey, unknown>): LastFMScrobbleRequestPayload[] => {
+export const ingressPayloads = (obj: LastfmScrobbleMaybeMultiPayload): LastfmScrobblePayload[] => {
     const keys = Object.keys(obj);
     let allObject = true;
     for(const k of lfmPayloadKeysRequired) {
@@ -834,10 +929,10 @@ export const ingressPayloads = (obj: Record<LastFMPayloadkey, unknown>): LastFMS
             throw new Error('Payload is an unexpected mix of arrays and objects');
         }
     }
-    const payloads: LastFMScrobbleRequestPayload[] = [];
+    const payloads: LastfmScrobblePayload[] = [];
 
     if(allObject) {
-        payloads.push(obj as LastFMScrobbleRequestPayload);
+        payloads.push(obj as LastfmScrobblePayload);
     } else {
         let index = 0;
         for(const t of (obj.track as string[])) {
@@ -849,14 +944,14 @@ export const ingressPayloads = (obj: Record<LastFMPayloadkey, unknown>): LastFMS
                 mbid: obj.mbid !== undefined ? obj.mbid[index] : undefined,
                 duration: obj.duration !== undefined ? obj.duration[index] : undefined,
                 albumArtist: obj.albumArtist !== undefined ? obj.albumArtist[index] : undefined,
-                method: obj.method as string
+                method: obj.method
             })
             index++;
         }
     }
 
     return payloads.map(x => {
-        const cleaned: LastFMScrobbleRequestPayload = x;
+        const cleaned: LastfmScrobblePayload = x;
         if(typeof cleaned.duration === 'string') {
             cleaned.duration = Number.parseInt(cleaned.duration);
         }
@@ -946,19 +1041,19 @@ export const playToScrobbleApiResponseXml = (play: PlayObject) => {
                 scrobble: {
                     track: {
                         $: {corrected: 0},
-                        _: play.data.track
+                        _: play.data.track ?? ''
                     },
                     artist: {
                         $: {corrected: 0},
-                        _: play.data.artists?.join(',')
+                        _: play.data.artists?.join(',') ?? ''
                     },
                     album: {
                         $: {corrected: 0},
-                        _: play.data.album
+                        _: play.data.album ?? ''
                     },
                     albumArtist: {
                         $: {corrected: 0},
-                        _: play.data.albumArtists?.join(',')
+                        _: play.data.albumArtists?.join(',') ?? ''
                     },
                     timestamp: {
                         _: dayjs().unix(),
@@ -981,19 +1076,19 @@ export const playToNowPlayingApiResponseXml = (play: PlayObject) => {
             nowplaying: {
                 track: {
                     $: { corrected: 0 },
-                    _: play.data.track
+                    _: play.data.track ?? ''
                 },
                 artist: {
                     $: { corrected: 0 },
-                    _: play.data.artists?.join(',')
+                    _: play.data.artists?.join(',') ?? ''
                 },
                 album: {
                     $: { corrected: 0 },
-                    _: play.data.album
+                    _: play.data.album ?? ''
                 },
                 albumArtist: {
                     $: { corrected: 0 },
-                    _: play.data.albumArtists?.join(',')
+                    _: play.data.albumArtists?.join(',') ?? ''
                 },
                 ignoredMessage: {
                     $: { code: 0 }

src/backend/common/vendor/ListenbrainzApiClient.ts

@@ -23,12 +23,13 @@ import { unique } from '../../utils.ts';
 import { removeUndefinedKeys } from '../../../core/DataUtils.ts';
 import type {ListenPayload, ListenResponse, ListenType, SubmitPayload} from '../../../core/vendor/listenbrainz/interfaces.ts';
 import { baseFormatPlayObj } from '../../utils/PlayTransformUtils.ts';
-import { ScrobbleSubmitError, SimpleError } from '../errors/MSErrors.ts';
+import { AuthError, ScrobbleSubmitError, SimpleError } from '../errors/MSErrors.ts';
 import pRetry from 'p-retry';
 import { findCauseByFunc } from '../../utils/ErrorUtils.ts';
 import { isSuperAgentResponseError } from '../errors/ErrorUtils.ts';
 import { playToSubmitPayload } from './listenbrainz/lzUtils.ts';
 import { isrcNoHyphens } from '../../../core/PlayUtils.ts';
+import { getRoot } from '../../ioc.ts';
 
 
 export interface SubmitOptions {
@@ -59,6 +60,7 @@ export class ListenbrainzApiClient extends AbstractApiClient implements Pageless
 
     declare config: ListenBrainzClientData;
     url: URLData;
+    userAgent: string
 
     constructor(name: any, config: ListenBrainzClientData, options: AbstractApiOptions) {
         super('ListenBrainz', name, config, options);
@@ -66,6 +68,7 @@ export class ListenbrainzApiClient extends AbstractApiClient implements Pageless
             url = 'https://api.listenbrainz.org/'
         } = config;
         let cleanUrl = url;
+        this.userAgent = `multi-scrobbler/${getRoot().items.version}`
         const pathedUrl = normalizeListenbrainzUrl(cleanUrl);
         if(pathedUrl !== undefined) {
             this.logger.verbose(`LZ Server URL contained /1/, removing this because MS adds it automatically`);
@@ -84,6 +87,7 @@ export class ListenbrainzApiClient extends AbstractApiClient implements Pageless
 
         try {
             req.set('Authorization', `Token ${this.config.token}`);
+            req.set('User-Agent', this.userAgent);
             return await req as T;
         } catch (e) {
             const {
@@ -183,8 +187,12 @@ export class ListenbrainzApiClient extends AbstractApiClient implements Pageless
         try {
             const resp = await this.callApi(() => request.get(`${joinedUrl(this.url.url,'1/validate-token')}`));
             return true;
-        } catch (e) {
-            throw e;
+        } catch (err) {
+            const cause = findCauseByFunc<request.ResponseError>(err, (e) => isSuperAgentResponseError(e));
+            if(cause !== undefined && [401,403,400].includes(cause.status)) {
+                throw new AuthError('Failed to validate token', {cause: err, unrecoverable: true});
+            }
+            throw new AuthError('Failed to validate token due to non-auth error', {cause: err, unrecoverable: false});
         }
     }
 

src/backend/common/vendor/RockSkyApiClient.ts

@@ -14,7 +14,7 @@ import type {RockskyScrobble} from './rocksky/interfaces.ts';
 import type {Handle} from "@atcute/lexicons";
 import { getATProtoIdentifier, identifierToAtProtoHandle } from './atproto/atUtils.ts';
 import { baseFormatPlayObj } from "../../utils/PlayTransformUtils.ts";
-import { ScrobbleSubmitError } from "../errors/MSErrors.ts";
+import { AuthError, ScrobbleSubmitError } from "../errors/MSErrors.ts";
 import { tryApiCall } from "../../utils/RequestUtils.ts";
 import { type CreateScrobbleInput, RockskyClient } from "@rocksky/sdk";
 import { getRoot } from "../../ioc.ts";
@@ -23,6 +23,8 @@ import type {HandleData} from "../infrastructure/config/client/atproto.ts";
 import { parseRegexSingle } from "@foxxmd/regex-buddy-core";
 import { removeUndefinedKeys } from "../../../core/DataUtils.ts";
 import { isrcNoHyphens } from '../../../core/PlayUtils.ts';
+import { findCauseByFunc } from "../../utils/ErrorUtils.ts";
+import { isSuperAgentResponseError } from "../errors/ErrorUtils.ts";
 
 interface SubmitOptions {
     log?: boolean
@@ -166,7 +168,8 @@ export class RockSkyApiClient extends AbstractApiClient {
                 const resp = await this.callLZApi(() => request.get(`${joinedUrl(this.lzUrl.url,'1/validate-token')}`));
                 return true;
             } catch (e) {
-                throw e;
+                const cause = findCauseByFunc<request.ResponseError>(e, (ee) => isSuperAgentResponseError(ee));
+                throw new AuthError('Failed to validate token', {cause: e, unrecoverable: cause !== undefined && [401,403].includes(cause.status)});
             }
         } else {
             try {
@@ -174,7 +177,9 @@ export class RockSkyApiClient extends AbstractApiClient {
                 await req;
                 return true;
             } catch (e) {
-                throw new UpstreamError('Failed to get /profile with given token', {cause: e});
+                const upstreamErr = new UpstreamError('Failed to get /profile with given token', {cause: e});
+                const cause = findCauseByFunc<request.ResponseError>(e, (ee) => isSuperAgentResponseError(ee));
+                throw new AuthError('Failed to get /profile with given token', {cause: upstreamErr, unrecoverable: cause !== undefined && [401,403].includes(cause.status)});
             }
         }
     }

src/backend/common/vendor/atproto/AbstractATProtoApiClient.ts

@@ -30,6 +30,8 @@ export abstract class AbstractATProtoApiClient extends AbstractApiClient {
 
     cache: MSCache;
 
+    resetMissing: boolean = false;
+
     constructor(name: any, config: ATProtoUserIdentifierData & {handleData?: HandleData}, options: AbstractApiOptions) {
         super('atproto', name, config, options);
         this.cache = getRoot().items.cache();
@@ -76,7 +78,6 @@ export abstract class AbstractATProtoApiClient extends AbstractApiClient {
             throw new UpstreamError(`Failed to fetch repo CAR file. Response was ${resp.status} with response ${text}`, {responseBody: text});
         }
 
-        resp.headers
         return await streamBodyProgress(resp.data, {
             logger: this.logger,
             chunkDefaultSize: 1024 * 1024 * 5, // report progress every 5 MB
@@ -128,8 +129,12 @@ export abstract class AbstractATProtoApiClient extends AbstractApiClient {
         }
         try {
             const info = parseRateLimitHeaders(headers);
-            const secUntilReset = dayjs(info.reset).diff(dayjs(), 's');
+            if(info === null && this.resetMissing === false) {
+                this.logger.warn({headers}, 'PDS does not implement rate limiting or is using some non-standard rate limit headers. Rate limiting will be ignored. Expected headers: ratelimit-limit, ratelimit-remaining, ratelimit-reset');
+                this.resetMissing = true;
+            }
             if (info !== null) {
+                const secUntilReset = dayjs(info.reset).diff(dayjs(), 's');
                 await this.cache.cacheAuth.set<RateLimitInfo>(`${this.getAuthCacheKey()}-rateLimitInfo`, { limit: info.limit, remaining: info.remaining, reset: info.reset.valueOf() }, Math.min(secUntilReset, 3600));
             }
         } catch (e) {

src/backend/common/vendor/atproto/atUtils.ts

@@ -21,10 +21,14 @@ import {
 import assert from "node:assert";
 import { isPortReachableConnect, normalizeWebAddress } from "../../../utils/NetworkUtils.ts";
 import { isNodeNetworkException } from "../../errors/NodeErrors.ts";
+import * as z from 'zod';
 
 export const HANDLE_REGEX = new RegExp(/.+\..+/);
+export const HandleZodType = z.stringFormat('atproto-handle', HANDLE_REGEX)
 export const ATSIGN_REGEX = new RegExp(/^@(.+)/);
+export const AtSignZodType = z.stringFormat('atproto-atsign-handle', ATSIGN_REGEX);
 export const DID_REGEX = new RegExp(/did:(?:plc|web):.+/);
+export const DidZodType = z.stringFormat('did', DID_REGEX);
 
 export interface HandleOptions {
     logger?: Logger

src/backend/common/vendor/discord/DiscordIPCClient.ts

@@ -185,7 +185,8 @@ export const configToIPCConfig = (data: DiscordStrongData): DiscordIPCData => {
     const parsedPaths: (string | [number, string])[] = [];
     for(const p of ipcLocations) {
         if(Array.isArray(p)) {
-            parsedPaths.push(p)
+            if(typeof p[0] === 'number' && typeof p[1] === 'string')
+            parsedPaths.push([p[0],p[1]]);
         } else {
             const sp = p.split(':');
             if(sp.length > 1) {

src/backend/common/vendor/koito/KoitoApiClient.ts

@@ -11,10 +11,12 @@ import { playToListenPayload } from '../listenbrainz/lzUtils.ts';
 import type {SubmitPayload} from '../../../../core/vendor/listenbrainz/interfaces.ts';
 import type {ListenType} from '../../../../core/vendor/listenbrainz/interfaces.ts';
 import { baseFormatPlayObj } from "../../../utils/PlayTransformUtils.ts";
-import { ScrobbleSubmitError } from "../../errors/MSErrors.ts";
+import { AuthError, ScrobbleSubmitError } from "../../errors/MSErrors.ts";
 import { tryApiCall } from "../../../utils/RequestUtils.ts";
 import { parseRegexSingle } from "@foxxmd/regex-buddy-core";
 import { artistNamesToCredits } from "../../../../core/StringUtils.ts";
+import { findCauseByFunc } from "../../../utils/ErrorUtils.ts";
+import { isSuperAgentResponseError } from "../../errors/ErrorUtils.ts";
 
 interface SubmitOptions {
     log?: boolean
@@ -133,7 +135,8 @@ export class KoitoApiClient extends AbstractApiClient implements PaginatedTimeRa
             const resp = await this.callApi(() => request.get(`${joinedUrl(this.url.url, '/apis/listenbrainz/1/validate-token')}`));
             return true;
         } catch (e) {
-            throw new Error('Could not validate Koito API Key', { cause: e });
+            const superagentError = findCauseByFunc<request.ResponseError>(e, (ee) => isSuperAgentResponseError(ee));
+            throw new AuthError('Could not validate Koito API Key', { cause: e, unrecoverable: superagentError !== undefined && [401,403].includes(superagentError.status)});
         }
     }
 

src/backend/common/vendor/maloja/MalojaApiClient.ts

@@ -16,8 +16,9 @@ import { getMalojaResponseError, isMalojaAPIErrorBody, type MalojaResponseV3Comm
 import { getScrobbleTsSOCDate, getScrobbleTsSOCDateWithContext } from '../../../utils/TimeUtils.ts';
 import { artistCreditsToNames, artistNamesToCredits, buildTrackString } from '../../../../core/StringUtils.ts';
 import { baseFormatPlayObj } from '../../../utils/PlayTransformUtils.ts';
-import { ScrobbleSubmitError } from '../../errors/MSErrors.ts';
+import { AuthError, ScrobbleSubmitError } from '../../errors/MSErrors.ts';
 import { NO_RETRY_HTTP_STATUS, tryApiCall } from '../../../utils/RequestUtils.ts';
+import { findCauseByFunc } from '../../../utils/ErrorUtils.ts';
 
 
 
@@ -175,10 +176,11 @@ export class MalojaApiClient extends AbstractApiClient implements PaginatedTimeR
                     body,
                     text: text.slice(0, 50)
                 },'Maloja API Response');
-                throw new Error('Server Response body was malformed -- should have returned "status: ok"...is the URL correct?', { cause: new Error(`Maloja API Response was ${status}: ${text.slice(0, 50)}`) })
+                throw new UpstreamError('Server Response body was malformed -- should have returned "status: ok"...is the URL correct?', { cause: new UpstreamError(`Maloja API Response was ${status}: ${text.slice(0, 50)}`) })
             }
         } catch (e) {
-            throw e;
+            const superagentError = findCauseByFunc<request.ResponseError>(e, (ee) => isSuperAgentResponseError(ee));
+            throw new AuthError('Failed to test Maloja API with apikey', {cause: e, unrecoverable: superagentError !== undefined && [401,403].includes(superagentError.status)});
         }
     }
 

src/backend/common/vendor/musicbrainz/MusicbrainzApiClient.ts

@@ -1,5 +1,5 @@
 import type { Response } from 'superagent';
-import type {ArtistCredit, PlayObject, PlayObjectMinimal, URLData} from "../../../../core/Atomic.ts";
+import type {ArtistCredit, OptionalCacheUsage, PlayObject, PlayObjectMinimal, URLData} from "../../../../core/Atomic.ts";
 import { UpstreamError } from "../../errors/UpstreamError.ts";
 import { type AbstractApiOptions, type FormatPlayObjectOptions, MUSICBRAINZ_URL, type MusicbrainzApiConfigData } from "../../infrastructure/Atomic.ts";
 import AbstractApiClient from "../AbstractApiClient.ts";
@@ -9,10 +9,8 @@ import { difference, sleep } from "../../../utils.ts";
 import {SequentialRoundRobin} from 'round-robin-js';
 import type { Cacheable } from "cacheable";
 import { getRoot } from "../../../ioc.ts";
-import { version } from "../../../version.ts";
 import { hashObject } from "../../../utils/StringUtils.ts";
 import { playContentInvariantTransform } from "../../../utils/PlayComparisonUtils.ts";
-;
 import { AsyncLocalStorage } from "async_hooks";
 import { nanoid } from "nanoid";
 import { stripIndents } from "common-tags";
@@ -79,7 +77,7 @@ export class MusicbrainzApiClient extends AbstractApiClient {
             if(mb === undefined) {
                 const api = new MusicBrainzApi({
                     appName: 'multi-scrobbler',
-                    appVersion: version,
+                    appVersion: getRoot().items.version,
                     appContactInfo: mbConfig.contact,
                     baseUrl: u.url.toString(),
                     preRequest: (method, url, headers) => {
@@ -114,17 +112,18 @@ export class MusicbrainzApiClient extends AbstractApiClient {
         return 'API';
     }
 
-    callApi = async <T = Response>(func: (mb: MusicBrainzApi) => Promise<any>, options?: { timeout?: number, cacheKey?: string }): Promise<T> => {
+    callApi = async <T = Response>(func: (mb: MusicBrainzApi) => Promise<any>, options?: { timeout?: number, cacheKey?: string } & OptionalCacheUsage): Promise<T> => {
 
         let apiConfig = this.rrApis.next().value;
 
         const {
             timeout = 30000,
-            cacheKey
+            cacheKey,
+            useCachedResult = true
         } = options || {};
 
         try {
-            const cachedTransform = await this.cache.get<T>(cacheKey);
+            const cachedTransform = useCachedResult ? await this.cache.get<T>(cacheKey) : undefined;
             if(cachedTransform !== undefined) {
                 const cacheUrl = await this.cache.get<string>(`${cacheKey}-url`);
                 const cacheQs = await this.cache.get<string>(`${cacheKey}-qs`);
@@ -218,13 +217,14 @@ export class MusicbrainzApiClient extends AbstractApiClient {
         }
     }
 
-    searchByRecording = async(play: PlayObject, options?: SearchOptions): Promise<IRecordingMSList | undefined> => {
+    searchByRecording = async(play: PlayObject, options?: SearchOptions & OptionalCacheUsage): Promise<IRecordingMSList | undefined> => {
 
         const {
             escapeCharacters = true,
             removeCharacters = false,
             using = ['album','artist','title'],
-            freetext
+            freetext,
+            useCachedResult
         } = options || {};
 
         const cacheKey = `mb-recSearch-${hashObject({...playContentInvariantTransform(play), using})}`;
@@ -347,7 +347,8 @@ export class MusicbrainzApiClient extends AbstractApiClient {
                 query: q
             });
         }, {
-            cacheKey
+            cacheKey,
+            useCachedResult
         });
 
         if(res === undefined) {

src/backend/common/vendor/teal/TealApiClient.ts

@@ -1,5 +1,5 @@
 import dayjs, { type Dayjs, type ManipulateType } from "dayjs";
-import type {PlayObject, PlayObjectMinimal, BrainzMeta, MBID, ScrobbleActionResult, UnixTimestamp} from "../../../../core/Atomic.ts";
+import {type PlayObject, type PlayObjectMinimal, type BrainzMeta, type MBID, type ScrobbleActionResult, PARSED_FROM} from "../../../../core/Atomic.ts";
 import { getRoot } from "../../../ioc.ts";
 import { removeUndefinedKeys } from '../../../../core/DataUtils.ts';
 import { baseFormatPlayObj } from "../../../utils/PlayTransformUtils.ts";
@@ -8,7 +8,7 @@ import type {AbstractApiOptions, PagelessListensTimeRangeOptions, PagelessTimeRa
 import type {ListRecord, RecordOptions, TealClientData} from "../../infrastructure/config/client/tealfm.ts";
 import AbstractApiClient from "../AbstractApiClient.ts";
 import { ATProtoAppApiClient } from "../atproto/ATProtoAppApiClient.ts";
-import type { FmTealAlphaActorStatus, FmTealAlphaFeedPlay } from "./lexicons/index.ts";
+import type { FmTealActorStatus, FmTealAlphaActorStatus, FmTealAlphaFeedPlay, FmTealFeedPlay } from "./lexicons/index.ts";
 import { ScrobbleSubmitError } from "../../errors/MSErrors.ts";
 import { getScrobbleTsSOCDateWithContext, usecToUnix } from "../../../utils/TimeUtils.ts";
 import { musicServiceToCononical } from "../listenbrainz/lzUtils.ts";
@@ -18,7 +18,19 @@ import type { ATProtoAuthenticatedApiClient } from "../atproto/ATProtoAuthentica
 import { UpstreamError } from "../../errors/UpstreamError.ts";
 import type { ComAtprotoRepoCreateRecord, ComAtprotoRepoPutRecord } from '@atcute/atproto';
 import { nowPlayingExpirationDuration } from "../../../scrobblers/AbstractScrobbleClient.ts";
-import { isrcNoHyphens } from "../../../../core/PlayUtils.ts";
+import { isrcNoHyphens, sortByNewestPlayDate } from "../../../../core/PlayUtils.ts";
+import { isGenericUri } from "@atcute/lexicons/syntax";
+
+type TealPlayRecord = FmTealAlphaFeedPlay.Main | FmTealFeedPlay.Main;
+
+const TEAL_PLAY_COLLECTIONS = ['fm.teal.feed.play', 'fm.teal.alpha.feed.play'] as const;
+
+const asMusicServiceUri = (musicService?: string): `${string}:${string}` | undefined => {
+    if (musicService === undefined) {
+        return undefined;
+    }
+    return isGenericUri(musicService) ? musicService : `https://${musicService}`;
+};
 
 export class TealApiClient extends AbstractApiClient implements PagelessTimeRangeListens {
 
@@ -43,10 +55,10 @@ export class TealApiClient extends AbstractApiClient implements PagelessTimeRang
     }
 
 
-    async createScrobbleRecord(record: FmTealAlphaFeedPlay.Main): Promise<ScrobbleActionResult> {
+    async createScrobbleRecord(record: FmTealFeedPlay.Main): Promise<ScrobbleActionResult> {
         const input: ComAtprotoRepoCreateRecord.$input = {
             repo: this.client.userData.did,
-            collection: 'fm.teal.alpha.feed.play',
+            collection: 'fm.teal.feed.play',
             record
         };
         try {
@@ -62,10 +74,10 @@ export class TealApiClient extends AbstractApiClient implements PagelessTimeRang
         }
     }
 
-    async updateStatusRecord(record: FmTealAlphaActorStatus.Main): Promise<ScrobbleActionResult> {
+    async updateStatusRecord(record: FmTealActorStatus.Main): Promise<ScrobbleActionResult> {
         const input: ComAtprotoRepoPutRecord.$input = {
             repo: this.client.userData.did,
-            collection: "fm.teal.alpha.actor.status",
+            collection: "fm.teal.actor.status",
             rkey: "self",
             record
         };
@@ -92,37 +104,54 @@ export class TealApiClient extends AbstractApiClient implements PagelessTimeRang
             cursor = generateTID(dayjs.unix(to).toISOString());
         }
 
-        const resp = await this.client.get((client) => client.get('com.atproto.repo.listRecords', {
+        const responses = await Promise.all(TEAL_PLAY_COLLECTIONS.map(collection => this.client.get((client) => client.get('com.atproto.repo.listRecords', {
             params: {
                 repo: this.client.userData.did,
-                collection: "fm.teal.alpha.feed.play",
+                collection,
                 limit,
                 cursor
             }
-        }));
+        }))));
 
-        if(!resp.ok) {
-            throw new UpstreamError('Fetching records from PDS failed', {cause: resp.data});
+        const fromTimestamps: number[] = [],
+              playSets: PlayObject[][] = [];
+
+        for (const resp of responses) {
+            if (!resp.ok) {
+                throw new UpstreamError('Fetching records from PDS failed', {cause: resp.data});
+            }
+            if(resp.data.cursor !== undefined) {
+                fromTimestamps.push(usecToUnix(decodeTid(resp.data.cursor).timestampUs));
+            }
+            playSets.push((resp.data.records as ListRecord<TealPlayRecord>[]).map(x => listRecordToPlay(x)));
         }
 
-        let fromTS: UnixTimestamp;
-        if(resp.data.cursor !== undefined) {
-            const { timestampUs } = decodeTid(resp.data.cursor);
-            fromTS = usecToUnix(timestampUs);
-        }
+        const from = fromTimestamps.length > 0 ? fromTimestamps.reduce((earliest, current) => current < earliest ? current : earliest) : undefined;
+        const plays = playSets.flat().sort(sortByNewestPlayDate)
 
-        const plays = (resp.data.records as unknown as ListRecord<FmTealAlphaFeedPlay.Main>[]).map(x => listRecordToPlay(x));
-
-        return {data: plays, meta: {to, from: fromTS, limit}};
+        return {data: plays, meta: {to, from, limit, more: false, order: 'desc'}};
     }
 }
 
-export const recordToPlay = (record: FmTealAlphaFeedPlay.Main, options: RecordOptions = {}): PlayObject => {
+export const recordToPlay = (record: TealPlayRecord, options: RecordOptions = {}): PlayObject => {
+    const artists = record.artists ?? [];
+    let musicService: string;
+    if('musicServiceUri' in record) {
+        musicService = record.musicServiceUri
+    } else if(`musicServiceBaseDomain` in record) {
+        musicService = record.musicServiceBaseDomain;
+    }
+    let origin: string;
+    if('originUri' in record) {
+        origin = record.originUri;
+    } else if(`originUrl` in record) {
+        origin = record.originUrl;
+    }
 
     const play: PlayObjectMinimal = {
         data: {
             track: record.trackName,
-            artists: record.artists.filter(x => x.artistName !== undefined).map(x => ({ name: x.artistName, mbid: x.artistMbId })),
+            artists: artists.filter(x => x.artistName !== undefined).map(x => ({ name: x.artistName, mbid: x.artistMbId })),
             duration: record.duration,
             playDate: dayjs(record.playedTime),
             album: record.releaseName,
@@ -130,11 +159,12 @@ export const recordToPlay = (record: FmTealAlphaFeedPlay.Main, options: RecordOp
         },
         meta: {
             source: 'tealfm',
-            parsedFrom: 'history',
-            musicService: record.musicServiceBaseDomain,
+            parsedFrom: PARSED_FROM.history,
+            musicService,
             playId: options.playId,
             url: {
-                web: options.web
+                web: options.web,
+                origin
             },
             user: options.user
         }
@@ -143,7 +173,7 @@ export const recordToPlay = (record: FmTealAlphaFeedPlay.Main, options: RecordOp
     const brainz = removeUndefinedKeys<BrainzMeta>({
         recording: record.recordingMbId,
         album: record.releaseMbId,
-        artist: record.artists.filter(x => x.artistMbId !== undefined).length > 0 ? record.artists.filter(x => x.artistMbId !== undefined).map(x => x.artistMbId) : undefined
+        artist: artists.filter(x => x.artistMbId !== undefined).length > 0 ? artists.filter(x => x.artistMbId !== undefined).map(x => x.artistMbId) : undefined
     });
 
     if (brainz !== undefined) {
@@ -153,10 +183,24 @@ export const recordToPlay = (record: FmTealAlphaFeedPlay.Main, options: RecordOp
     return baseFormatPlayObj(record, play);
 }
 
-export const playToStatusRecord = (play: PlayObject, notPlaying: boolean, position?: number): FmTealAlphaActorStatus.Main => {
-    const { $type, ...item } = notPlaying
+export const playToStatusRecord = (play: PlayObject, notPlaying: boolean, position?: number): FmTealActorStatus.Main => {
+    const item = notPlaying
         ? { trackName: "", artists: [] }
-        : playToRecord(play);
+        : (() => {
+            const {
+                $type,
+                musicServiceUri,
+                originUri,
+                trackDiscriminant,
+                releaseDiscriminant,
+                ...record
+            } = playToRecord(play);
+            return {
+                ...record,
+                musicServiceBaseDomain: musicServiceUri,
+                originUrl: originUri
+            };
+        })();
 
     let expiry: Dayjs;
     if (notPlaying) {
@@ -167,7 +211,7 @@ export const playToStatusRecord = (play: PlayObject, notPlaying: boolean, positi
     }
 
     return {
-        $type: "fm.teal.alpha.actor.status",
+        $type: "fm.teal.actor.status",
         time: dayjs().toISOString(),
         expiry: expiry.toISOString(),
         item: {
@@ -186,17 +230,19 @@ export const mbidUriOrUndefined = (mbid?: MBID): undefined | MBIDURI => {
     return mbidToUri(mbid);
 };
 export type MBIDURI = `mbid:${MBID}`;
-export const playToRecord = (play: PlayObject): FmTealAlphaFeedPlay.Main => {
+export const playToRecord = (play: PlayObject): FmTealFeedPlay.Main => {
+    const musicService = musicServiceToCononical(play.meta.musicService) ?? play.meta.musicService;
 
-    const record: FmTealAlphaFeedPlay.Main = {
-        $type: "fm.teal.alpha.feed.play",
+    const record: FmTealFeedPlay.Main = {
+        $type: "fm.teal.feed.play",
         trackName: play.data.track,
-        artists: play.data.artists.map(x => removeUndefinedKeys({ artistName: x.name, artistMbId: mbidUriOrUndefined(x.mbid as MBID) })),
+        artists: (play.data.artists ?? []).map(x => removeUndefinedKeys({ artistName: x.name, artistMbId: mbidUriOrUndefined(x.mbid as MBID) })),
         duration: Math.round(play.data.duration),
         playedTime: getScrobbleTsSOCDateWithContext(play)[0].toISOString(),
         releaseName: play.data.album,
         submissionClientAgent: `multi-scrobbler/${getRoot().items.version}`,
-        musicServiceBaseDomain: musicServiceToCononical(play.meta.musicService) ?? play.meta.musicService,
+        musicServiceUri: asMusicServiceUri(musicService),
+        originUri: isGenericUri(play.meta.url?.origin) ? play.meta.url?.origin : undefined,
         isrc: play.data.isrc !== undefined ? isrcNoHyphens(play.data.isrc) : undefined,
         trackMbId: mbidUriOrUndefined(play.data.meta?.brainz?.track as MBID),
         recordingMbId: mbidUriOrUndefined(play.data.meta?.brainz?.recording as MBID),
@@ -205,7 +251,7 @@ export const playToRecord = (play: PlayObject): FmTealAlphaFeedPlay.Main => {
 
     return record;
 };
-export const listRecordToPlay = (listRecord: ListRecord<FmTealAlphaFeedPlay.Main>): PlayObject => {
+export const listRecordToPlay = (listRecord: ListRecord<TealPlayRecord>): PlayObject => {
     const opts: RecordOptions = {};
     const uriRes = parseRegexSingle(ATPROTO_URI_REGEX, listRecord.uri);
     if (uriRes !== undefined) {
@@ -215,5 +261,4 @@ export const listRecordToPlay = (listRecord: ListRecord<FmTealAlphaFeedPlay.Main
     }
     return recordToPlay(listRecord.value, opts);
 };
-export const ATPROTO_URI_REGEX = new RegExp(/at:\/\/(?<resource>(?<did>did.*?)\/fm.teal.alpha.feed.play\/(?<tid>.*))/);
-
+export const ATPROTO_URI_REGEX = new RegExp(/at:\/\/(?<resource>(?<did>did.*?)\/fm.teal(?:\.alpha)?\.feed.play\/(?<tid>.*))/);

src/backend/common/vendor/teal/lex.config.ts

@@ -11,6 +11,7 @@ export default defineLexiconConfig({
 		files: ['lexicons/**/*.json'],
 		outdir: 'lexicons/',
 		imports: ['@atcute/bluesky'],
+		modules: { importSuffix: '.ts' },
 	},
 	pull: {
 		outdir: path.resolve(__dirname, 'lexicons/'),
@@ -19,8 +20,8 @@ export default defineLexiconConfig({
 				type: 'git',
 				remote: 'https://github.com/teal-fm/teal.git',
 				ref: 'main',
-				pattern: ['lexicons/fm.teal.alpha/feed/*.json','lexicons/fm.teal.alpha/actor/*.json'],
+				pattern: ['lexicons/fm.teal/feed/*.json','lexicons/fm.teal/actor/*.json'],
 			},
 		],
 	},
-});
+});

src/backend/common/vendor/teal/lexicons/README.md

@@ -3,4 +3,4 @@
 this directory contains lexicon documents pulled from the following sources:
 
 - https://github.com/teal-fm/teal.git (ref: main)
-  - commit: f661868af2a56199f1b3cae1ad20cd5831ec4212
+  - commit: 82ea66cadbde3f1aee9c72b05f372c6543a4b3f6

src/backend/common/vendor/teal/lexicons/index.ts

@@ -1,3 +1,14 @@
+export * as FmTealActorDefs from "./types/fm/teal/actor/defs.ts";
+export * as FmTealActorGetProfile from "./types/fm/teal/actor/getProfile.ts";
+export * as FmTealActorGetProfiles from "./types/fm/teal/actor/getProfiles.ts";
+export * as FmTealActorProfile from "./types/fm/teal/actor/profile.ts";
+export * as FmTealActorProfileStatus from "./types/fm/teal/actor/profileStatus.ts";
+export * as FmTealActorSearchActors from "./types/fm/teal/actor/searchActors.ts";
+export * as FmTealActorStatus from "./types/fm/teal/actor/status.ts";
+export * as FmTealFeedDefs from "./types/fm/teal/feed/defs.ts";
+export * as FmTealFeedGetActorFeed from "./types/fm/teal/feed/getActorFeed.ts";
+export * as FmTealFeedGetPlay from "./types/fm/teal/feed/getPlay.ts";
+export * as FmTealFeedPlay from "./types/fm/teal/feed/play.ts";
 export * as FmTealAlphaActorDefs from "./types/fm/teal/alpha/actor/defs.ts";
 export * as FmTealAlphaActorGetProfile from "./types/fm/teal/alpha/actor/getProfile.ts";
 export * as FmTealAlphaActorGetProfiles from "./types/fm/teal/alpha/actor/getProfiles.ts";
@@ -8,4 +19,4 @@ export * as FmTealAlphaActorStatus from "./types/fm/teal/alpha/actor/status.ts";
 export * as FmTealAlphaFeedDefs from "./types/fm/teal/alpha/feed/defs.ts";
 export * as FmTealAlphaFeedGetActorFeed from "./types/fm/teal/alpha/feed/getActorFeed.ts";
 export * as FmTealAlphaFeedGetPlay from "./types/fm/teal/alpha/feed/getPlay.ts";
-export * as FmTealAlphaFeedPlay from "./types/fm/teal/alpha/feed/play.ts";
+export * as FmTealAlphaFeedPlay from "./types/fm/teal/alpha/feed/play.ts";

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/defs.ts

@@ -0,0 +1,96 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import * as AppBskyRichtextFacet from "@atcute/bluesky/types/app/richtext/facet";
+import * as FmTealActorProfile from "./profile.ts";
+import * as FmTealFeedDefs from "../feed/defs.ts";
+
+const _miniProfileViewSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.actor.defs#miniProfileView"),
+  ),
+  /**
+   * IPLD of the avatar
+   */
+  avatar: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.cidString()),
+  /**
+   * The decentralized identifier of the actor
+   */
+  did: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.didString()),
+  displayName: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+  handle: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.handleString()),
+});
+const _profileViewSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.actor.defs#profileView"),
+  ),
+  /**
+   * IPLD of the avatar
+   */
+  avatar: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.cidString()),
+  /**
+   * IPLD of the banner image
+   */
+  banner: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.cidString()),
+  createdAt: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+  /**
+   * Free-form profile description text.
+   */
+  description: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+  /**
+   * Annotations of text in the profile description (mentions, URLs, hashtags, etc). May be changed to another (backwards compatible) lexicon.
+   */
+  get descriptionFacets() {
+    return /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.array(AppBskyRichtextFacet.mainSchema),
+    );
+  },
+  /**
+   * The decentralized identifier of the actor
+   */
+  did: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.didString()),
+  displayName: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+  /**
+   * The user's most recent item featured on their profile.
+   */
+  get featuredItem() {
+    return /*#__PURE__*/ v.optional(FmTealActorProfile.featuredItemSchema);
+  },
+  get status() {
+    return /*#__PURE__*/ v.optional(statusViewSchema);
+  },
+});
+const _statusViewSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.actor.defs#statusView"),
+  ),
+  /**
+   * The datetime after which the status is no longer current.
+   */
+  expiry: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+  get item() {
+    return /*#__PURE__*/ v.optional(FmTealFeedDefs.playViewSchema);
+  },
+  /**
+   * The datetime at which the status was recorded.
+   */
+  time: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+});
+
+type miniProfileView$schematype = typeof _miniProfileViewSchema;
+type profileView$schematype = typeof _profileViewSchema;
+type statusView$schematype = typeof _statusViewSchema;
+
+export interface miniProfileViewSchema extends miniProfileView$schematype {}
+export interface profileViewSchema extends profileView$schematype {}
+export interface statusViewSchema extends statusView$schematype {}
+
+export const miniProfileViewSchema =
+  _miniProfileViewSchema as miniProfileViewSchema;
+export const profileViewSchema = _profileViewSchema as profileViewSchema;
+export const statusViewSchema = _statusViewSchema as statusViewSchema;
+
+export interface MiniProfileView extends v.InferInput<
+  typeof miniProfileViewSchema
+> {}
+export interface ProfileView extends v.InferInput<typeof profileViewSchema> {}
+export interface StatusView extends v.InferInput<typeof statusViewSchema> {}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/getProfile.ts

@@ -0,0 +1,36 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealActorDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.query("fm.teal.actor.getProfile", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * The actor's DID or handle
+     */
+    actor: /*#__PURE__*/ v.actorIdentifierString(),
+  }),
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get actor() {
+        return FmTealActorDefs.profileViewSchema;
+      },
+    }),
+  },
+});
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "fm.teal.actor.getProfile": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/getProfiles.ts

@@ -0,0 +1,40 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealActorDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.query("fm.teal.actor.getProfiles", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * Array of actor DIDs or handles
+     * @minLength 1
+     */
+    actors: /*#__PURE__*/ v.constrain(
+      /*#__PURE__*/ v.array(/*#__PURE__*/ v.actorIdentifierString()),
+      [/*#__PURE__*/ v.arrayLength(1)],
+    ),
+  }),
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get actors() {
+        return /*#__PURE__*/ v.array(FmTealActorDefs.miniProfileViewSchema);
+      },
+    }),
+  },
+});
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "fm.teal.actor.getProfiles": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/profile.ts

@@ -0,0 +1,102 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as AppBskyRichtextFacet from "@atcute/bluesky/types/app/richtext/facet";
+
+const _featuredItemSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.actor.profile#featuredItem"),
+  ),
+  /**
+   * The MusicBrainz ID URI of the item, formatted as mbid:<uuid>
+   */
+  mbid: /*#__PURE__*/ v.genericUriString(),
+  /**
+   * The MusicBrainz entity type of the item.
+   */
+  type: /*#__PURE__*/ v.string<
+    "artist" | "recording" | "release" | (string & {})
+  >(),
+});
+const _mainSchema = /*#__PURE__*/ v.record(
+  /*#__PURE__*/ v.literal("self"),
+  /*#__PURE__*/ v.object({
+    $type: /*#__PURE__*/ v.literal("fm.teal.actor.profile"),
+    /**
+     * Small image to be displayed next to posts from account. AKA, 'profile picture'
+     * @accept image/jpeg, image/png
+     * @maxSize 1000000
+     */
+    avatar: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.blob(), [
+        /*#__PURE__*/ v.blobSize(1000000),
+        /*#__PURE__*/ v.blobAccept(["image/jpeg", "image/png"]),
+      ]),
+    ),
+    /**
+     * Larger horizontal image to display behind profile view.
+     * @accept image/jpeg, image/png
+     * @maxSize 1000000
+     */
+    banner: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.blob(), [
+        /*#__PURE__*/ v.blobSize(1000000),
+        /*#__PURE__*/ v.blobAccept(["image/jpeg", "image/png"]),
+      ]),
+    ),
+    createdAt: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+    /**
+     * Free-form profile description text.
+     * @maxLength 2560
+     * @maxGraphemes 256
+     */
+    description: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 2560),
+        /*#__PURE__*/ v.stringGraphemes(0, 256),
+      ]),
+    ),
+    /**
+     * Annotations of text in the profile description (mentions, URLs, hashtags, etc).
+     */
+    get descriptionFacets() {
+      return /*#__PURE__*/ v.optional(
+        /*#__PURE__*/ v.array(AppBskyRichtextFacet.mainSchema),
+      );
+    },
+    /**
+     * @maxLength 640
+     * @maxGraphemes 64
+     */
+    displayName: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 640),
+        /*#__PURE__*/ v.stringGraphemes(0, 64),
+      ]),
+    ),
+    /**
+     * The user's most recent item featured on their profile.
+     */
+    get featuredItem() {
+      return /*#__PURE__*/ v.optional(featuredItemSchema);
+    },
+  }),
+);
+
+type featuredItem$schematype = typeof _featuredItemSchema;
+type main$schematype = typeof _mainSchema;
+
+export interface featuredItemSchema extends featuredItem$schematype {}
+export interface mainSchema extends main$schematype {}
+
+export const featuredItemSchema = _featuredItemSchema as featuredItemSchema;
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface FeaturedItem extends v.InferInput<typeof featuredItemSchema> {}
+export interface Main extends v.InferInput<typeof mainSchema> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface Records {
+    "fm.teal.actor.profile": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/profileStatus.ts

@@ -0,0 +1,42 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+
+const _mainSchema = /*#__PURE__*/ v.record(
+  /*#__PURE__*/ v.literal("self"),
+  /*#__PURE__*/ v.object({
+    $type: /*#__PURE__*/ v.literal("fm.teal.actor.profileStatus"),
+    /**
+     * The onboarding completion status
+     */
+    completedOnboarding: /*#__PURE__*/ v.string<
+      | "complete"
+      | "none"
+      | "playOnboarding"
+      | "profileOnboarding"
+      | (string & {})
+    >(),
+    /**
+     * The timestamp when this status was created
+     */
+    createdAt: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+    /**
+     * The timestamp when this status was last updated
+     */
+    updatedAt: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+  }),
+);
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface Main extends v.InferInput<typeof mainSchema> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface Records {
+    "fm.teal.actor.profileStatus": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/searchActors.ts

@@ -0,0 +1,59 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealActorDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.query("fm.teal.actor.searchActors", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * Cursor for pagination
+     */
+    cursor: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+    /**
+     * The maximum number of actors to return
+     * @minimum 1
+     * @maximum 25
+     */
+    limit: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.integer(), [
+        /*#__PURE__*/ v.integerRange(1, 25),
+      ]),
+    ),
+    /**
+     * The search query
+     * @maxLength 640
+     * @maxGraphemes 128
+     */
+    q: /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+      /*#__PURE__*/ v.stringLength(0, 640),
+      /*#__PURE__*/ v.stringGraphemes(0, 128),
+    ]),
+  }),
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get actors() {
+        return /*#__PURE__*/ v.array(FmTealActorDefs.miniProfileViewSchema);
+      },
+      /**
+       * Cursor for pagination
+       */
+      cursor: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+    }),
+  },
+});
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "fm.teal.actor.searchActors": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/actor/status.ts

@@ -0,0 +1,36 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealFeedDefs from "../feed/defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.record(
+  /*#__PURE__*/ v.literal("self"),
+  /*#__PURE__*/ v.object({
+    $type: /*#__PURE__*/ v.literal("fm.teal.actor.status"),
+    /**
+     * The datetime after which the status is no longer current. If unavailable, default to 10 minutes after the start time.
+     */
+    expiry: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+    get item() {
+      return FmTealFeedDefs.playViewSchema;
+    },
+    /**
+     * The datetime at which the status was recorded.
+     */
+    time: /*#__PURE__*/ v.datetimeString(),
+  }),
+);
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface Main extends v.InferInput<typeof mainSchema> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface Records {
+    "fm.teal.actor.status": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/feed/defs.ts

@@ -0,0 +1,109 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+
+const _artistSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.feed.defs#artist"),
+  ),
+  /**
+   * The MusicBrainz artist ID URI, formatted as mbid:<uuid>
+   */
+  artistMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The name of the artist
+   * @minLength 1
+   * @maxLength 256
+   * @maxGraphemes 2560
+   */
+  artistName: /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+    /*#__PURE__*/ v.stringLength(1, 256),
+    /*#__PURE__*/ v.stringGraphemes(0, 2560),
+  ]),
+});
+const _playViewSchema = /*#__PURE__*/ v.object({
+  $type: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.literal("fm.teal.feed.defs#playView"),
+  ),
+  /**
+   * Array of artists in order of original appearance.
+   */
+  get artists() {
+    return /*#__PURE__*/ v.array(artistSchema);
+  },
+  /**
+   * The length of the track in seconds
+   */
+  duration: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.integer()),
+  /**
+   * The ISRC code associated with the recording
+   */
+  isrc: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+  /**
+   * The canonical URI identifying the listening surface or music service.
+   */
+  musicServiceUri: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The exact URI where the listening event originated.
+   */
+  originUri: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The datetime at which playback began.
+   */
+  playedTime: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+  /**
+   * The MusicBrainz recording ID URI of the track, formatted as mbid:<uuid>
+   */
+  recordingMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The MusicBrainz release ID URI, formatted as mbid:<uuid>
+   */
+  releaseMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The name of the release/album
+   * @maxLength 256
+   * @maxGraphemes 2560
+   */
+  releaseName: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+      /*#__PURE__*/ v.stringLength(0, 256),
+      /*#__PURE__*/ v.stringGraphemes(0, 2560),
+    ]),
+  ),
+  /**
+   * A user-agent style string specifying the user agent. e.g. tealtracker/0.0.1b (Linux; Android 13; SM-A715F). Defaults to 'manual/unknown' if not provided.
+   * @maxLength 256
+   * @maxGraphemes 2560
+   */
+  submissionClientAgent: /*#__PURE__*/ v.optional(
+    /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+      /*#__PURE__*/ v.stringLength(0, 256),
+      /*#__PURE__*/ v.stringGraphemes(0, 2560),
+    ]),
+  ),
+  /**
+   * The MusicBrainz ID URI of the track, formatted as mbid:<uuid>
+   */
+  trackMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+  /**
+   * The name of the track
+   * @minLength 1
+   * @maxLength 256
+   * @maxGraphemes 2560
+   */
+  trackName: /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+    /*#__PURE__*/ v.stringLength(1, 256),
+    /*#__PURE__*/ v.stringGraphemes(0, 2560),
+  ]),
+});
+
+type artist$schematype = typeof _artistSchema;
+type playView$schematype = typeof _playViewSchema;
+
+export interface artistSchema extends artist$schematype {}
+export interface playViewSchema extends playView$schematype {}
+
+export const artistSchema = _artistSchema as artistSchema;
+export const playViewSchema = _playViewSchema as playViewSchema;
+
+export interface Artist extends v.InferInput<typeof artistSchema> {}
+export interface PlayView extends v.InferInput<typeof playViewSchema> {}

src/backend/common/vendor/teal/lexicons/types/fm/teal/feed/getActorFeed.ts

@@ -0,0 +1,44 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealFeedDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.query("fm.teal.feed.getActorFeed", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * The author's DID for the play
+     */
+    authorDID: /*#__PURE__*/ v.didString(),
+    /**
+     * The cursor to start the query from
+     */
+    cursor: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+    /**
+     * The upper limit of tracks to get per request. Default is 20, max is 50.
+     */
+    limit: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.integer()),
+  }),
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get plays() {
+        return /*#__PURE__*/ v.array(FmTealFeedDefs.playViewSchema);
+      },
+    }),
+  },
+});
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "fm.teal.feed.getActorFeed": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/feed/getPlay.ts

@@ -0,0 +1,40 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealFeedDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.query("fm.teal.feed.getPlay", {
+  params: /*#__PURE__*/ v.object({
+    /**
+     * The author's DID for the play
+     */
+    authorDID: /*#__PURE__*/ v.didString(),
+    /**
+     * The record key of the play
+     */
+    rkey: /*#__PURE__*/ v.recordKeyString(),
+  }),
+  output: {
+    type: "lex",
+    schema: /*#__PURE__*/ v.object({
+      get play() {
+        return FmTealFeedDefs.playViewSchema;
+      },
+    }),
+  },
+});
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface $params extends v.InferInput<mainSchema["params"]> {}
+export interface $output extends v.InferXRPCBodyInput<mainSchema["output"]> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface XRPCQueries {
+    "fm.teal.feed.getPlay": mainSchema;
+  }
+}

src/backend/common/vendor/teal/lexicons/types/fm/teal/feed/play.ts

@@ -0,0 +1,140 @@
+import type {} from "@atcute/lexicons";
+import * as v from "@atcute/lexicons/validations";
+import type {} from "@atcute/lexicons/ambient";
+import * as FmTealFeedDefs from "./defs.ts";
+
+const _mainSchema = /*#__PURE__*/ v.record(
+  /*#__PURE__*/ v.tidString(),
+  /*#__PURE__*/ v.object({
+    $type: /*#__PURE__*/ v.literal("fm.teal.feed.play"),
+    /**
+     * DEPRECATED: USE 'artists' INSTEAD. Array of Musicbrainz artist IDs.
+     * @deprecated
+     */
+    artistMbIds: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.array(/*#__PURE__*/ v.string()),
+    ),
+    /**
+     * DEPRECATED: USE 'artists' INSTEAD. Array of artist names in order of original appearance.
+     * @deprecated
+     */
+    artistNames: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.array(
+        /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+          /*#__PURE__*/ v.stringLength(1, 256),
+          /*#__PURE__*/ v.stringGraphemes(0, 2560),
+        ]),
+      ),
+    ),
+    /**
+     * Array of artists in order of original appearance.
+     */
+    get artists() {
+      return /*#__PURE__*/ v.optional(
+        /*#__PURE__*/ v.array(FmTealFeedDefs.artistSchema),
+      );
+    },
+    /**
+     * The length of the track in seconds
+     */
+    duration: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.integer()),
+    /**
+     * The ISRC code associated with the recording
+     */
+    isrc: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.string()),
+    /**
+     * The canonical URI identifying the listening surface or music service.
+     */
+    musicServiceUri: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.genericUriString(),
+    ),
+    /**
+     * The exact URI where the listening event originated.
+     */
+    originUri: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+    /**
+     * The datetime at which playback began.
+     */
+    playedTime: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.datetimeString()),
+    /**
+     * The MusicBrainz recording ID URI of the track, formatted as mbid:<uuid>
+     */
+    recordingMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+    /**
+     * Distinguishing information for release variants (e.g. 'Deluxe Edition', 'Remastered', '2023 Remaster', 'Special Edition'). Used to differentiate between different versions of the same base release while maintaining grouping capabilities.
+     * @maxLength 128
+     * @maxGraphemes 1280
+     */
+    releaseDiscriminant: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 128),
+        /*#__PURE__*/ v.stringGraphemes(0, 1280),
+      ]),
+    ),
+    /**
+     * The MusicBrainz release ID URI, formatted as mbid:<uuid>
+     */
+    releaseMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+    /**
+     * The name of the release/album
+     * @maxLength 256
+     * @maxGraphemes 2560
+     */
+    releaseName: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 256),
+        /*#__PURE__*/ v.stringGraphemes(0, 2560),
+      ]),
+    ),
+    /**
+     * A metadata string specifying the user agent where the format is `<app-identifier>/<version> (<kernel/OS-base>; <platform/OS-version>; <device-model>)`. If string is provided, only `app-identifier` and `version` are required. `app-identifier` is recommended to be in reverse dns format. Defaults to 'manual/unknown' if unavailable or not provided.
+     * @maxLength 256
+     * @maxGraphemes 2560
+     */
+    submissionClientAgent: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 256),
+        /*#__PURE__*/ v.stringGraphemes(0, 2560),
+      ]),
+    ),
+    /**
+     * Distinguishing information for track variants (e.g. 'Acoustic Version', 'Live at Wembley', 'Radio Edit', 'Demo'). Used to differentiate between different versions of the same base track while maintaining grouping capabilities.
+     * @maxLength 128
+     * @maxGraphemes 1280
+     */
+    trackDiscriminant: /*#__PURE__*/ v.optional(
+      /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+        /*#__PURE__*/ v.stringLength(0, 128),
+        /*#__PURE__*/ v.stringGraphemes(0, 1280),
+      ]),
+    ),
+    /**
+     * The MusicBrainz ID URI of the track, formatted as mbid:<uuid>
+     */
+    trackMbId: /*#__PURE__*/ v.optional(/*#__PURE__*/ v.genericUriString()),
+    /**
+     * The name of the track
+     * @minLength 1
+     * @maxLength 256
+     * @maxGraphemes 2560
+     */
+    trackName: /*#__PURE__*/ v.constrain(/*#__PURE__*/ v.string(), [
+      /*#__PURE__*/ v.stringLength(1, 256),
+      /*#__PURE__*/ v.stringGraphemes(0, 2560),
+    ]),
+  }),
+);
+
+type main$schematype = typeof _mainSchema;
+
+export interface mainSchema extends main$schematype {}
+
+export const mainSchema = _mainSchema as mainSchema;
+
+export interface Main extends v.InferInput<typeof mainSchema> {}
+
+declare module "@atcute/lexicons/ambient" {
+  interface Records {
+    "fm.teal.feed.play": mainSchema;
+  }
+}

src/backend/common/vendor/webscrobbler/interfaces.ts

@@ -1,78 +1,87 @@
-export type WebScrobblerHookEvent = 'scrobble' | 'paused' | 'resumedplaying' | 'nowplaying' | string;
-export interface WebScrobblerPayload {
-    eventName: WebScrobblerHookEvent
-    time?: number
-    data: {
-        song: WebScrobblerSong
-        songs?: WebScrobblerSong[]
-        currentlyPlaying?: boolean
-    }
-}
+import * as z from 'zod';
 
-interface ProcessedSongData {
-    artist?: string | null;
-    album?: string | null;
-    albumArtist?: string | null;
-    track?: string | null;
-    duration?: number | null;
-}
+//export type WebScrobblerHookEvent = 'scrobble' | 'paused' | 'resumedplaying' | 'nowplaying' | string;
+const webScrobblerHookEventSchema = z.union([z.enum(['scrobble','paused','resumedplaying','nowplaying']), z.string()]);
+export type WebScrobblerHookEvent = z.infer<typeof webScrobblerHookEventSchema>;
 
-interface ParsedSongData extends ProcessedSongData {
-    trackArt?: string | null;
-    uniqueID?: string | null;
-    originUrl?: string | null;
-    isPodcast?: boolean | null;
-    isPlaying?: boolean | null;
-    currentTime?: number | null;
-    isScrobblingAllowed?: boolean | null;
-}
+const processedSongDataSchema = z.object({
+    artist: z.string().nullish(),
+    album: z.string().nullish(),
+    albumArtist: z.string().nullish(),
+    track: z.string().nullish(),
+    duration: z.number().positive().nullish(),
+});
+export type ProcessedSongData = z.output<typeof processedSongDataSchema>;
 
-export type Flags =
-    | {
-    isScrobbled: boolean;
-    isCorrectedByUser: boolean;
-    isRegexEditedByUser: {
-        track: boolean;
-        artist: boolean;
-        album: boolean;
-        albumArtist: boolean;
-    };
-    isAlbumFetched: boolean;
-    isValid: boolean;
-    isMarkedAsPlaying: boolean;
-    isSkipped: boolean;
-    isReplaying: boolean;
-}
-    | Record<string, never>;
+const parsedSongDataSchema = processedSongDataSchema.extend({
+    trackArt: z.string().nullish(),
+    uniqueID: z.string().nullish(),
+    originUrl: z.string().nullish(),
+    isPodcast: z.boolean().nullish(),
+    isPlaying: z.boolean().nullish(),
+    currentTime: z.number().nullish(),
+    isScrobblingAllowed: z.boolean().nullish(),
+});
+export type ParsedSongData = z.output<typeof parsedSongDataSchema>;
 
-export type Metadata =
-    | {
-    label: string;
-    startTimestamp: number;
+// Record<string, never> means "no keys allowed" -> empty object with no extra props
+export const flagsSchema = z.looseObject({
+        isScrobbled: z.boolean(),
+        isCorrectedByUser: z.boolean(),
+        isRegexEditedByUser: z.object({
+            track: z.boolean(),
+            artist: z.boolean(),
+            album: z.boolean(),
+            albumArtist: z.boolean(),
+        }),
+        isAlbumFetched: z.boolean(),
+        isValid: z.boolean(),
+        isMarkedAsPlaying: z.boolean(),
+        isSkipped: z.boolean(),
+        isReplaying: z.boolean(),
+});
+export type Flags = z.infer<typeof flagsSchema>;
 
-    albumMbId?: string;
-    albumUrl?: string;
-    artistUrl?: string;
-    notificationId?: string;
-    trackArtUrl?: string;
-    trackUrl?: string;
-    userPlayCount?: number;
-    userloved?: boolean;
-}
-    | Record<string, never>;
+export const metadataSchema = z.looseObject({
+        label: z.string(),
+        startTimestamp: z.int().positive(),
+        albumMbId: z.string().optional(),
+        albumUrl: z.string().optional(),
+        artistUrl: z.string().optional(),
+        notificationId: z.string().optional(),
+        trackArtUrl: z.string().optional(),
+        trackUrl: z.string().optional(),
+        userPlayCount: z.int().positive().optional(),
+        userloved: z.boolean().optional(),
+});
+export type Metadata = z.infer<typeof metadataSchema>;
 
-export interface Connector {
-    id: string
-    js: string
-    label: string
-}
-export interface WebScrobblerSong {
-    controllerTabId: string | number;
-    connector: Connector
-    parsed: ParsedSongData;
-    processed: ProcessedSongData;
-    noRegex: ProcessedSongData;
-    flags: Flags;
-    metadata: Metadata;
-    connectorLabel: string;
-}
+export const connectorSchema = z.object({
+    id: z.string(),
+    js: z.string(),
+    label: z.string(),
+});
+export type Connector = z.infer<typeof connectorSchema>;
+
+export const webScrobblerSongSchema = z.object({
+    controllerTabId: z.union([z.string(),z.int().positive()]),
+    connector: connectorSchema,
+    parsed: parsedSongDataSchema,
+    processed: processedSongDataSchema,
+    noRegex: processedSongDataSchema,
+    flags: flagsSchema,
+    metadata: metadataSchema,
+    connectorLabel: z.string()
+});
+export type WebScrobblerSong = z.infer<typeof webScrobblerSongSchema>;
+
+export const webScrobblePayloadSchema = z.object({
+    eventName: webScrobblerHookEventSchema,
+    time: z.int().positive().optional(),
+    data: z.object({
+        song: webScrobblerSongSchema,
+        songs: z.array(webScrobblerSongSchema).optional(),
+        currentlyPlaying: z.boolean().optional()
+    })
+});
+export type WebScrobblerPayload = z.infer<typeof webScrobblePayloadSchema>;

src/backend/index.ts

@@ -173,7 +173,7 @@ const dataDir = getDataDir();
 
         await root.items.cache().init(true);
 
-        initServer(logger, appLoggerStream, output, scrobbleSources, scrobbleClients);
+        initServer({sources: scrobbleSources, clients: scrobbleClients},{logger, appLoggerStream, initialOutput: output});
 
         if(process.env.IS_LOCAL === 'true') {
             logger.info('multi-scrobbler can be run as a background service! See: https://docs.multi-scrobbler.app/installation/service');
@@ -209,9 +209,9 @@ const dataDir = getDataDir();
         if(nameColl.length > 0) {
             logger.warn(`Last.FM source and clients have same names [${nameColl.map(x => x.name).join(',')}] -- this may cause issues`);
         }
-        const clientInitOptions = {deadDelay: nonEmptyStringOrDefault(process.env.DEBUG_DEAD_DELAY, undefined) !== undefined ? Number.parseInt(process.env.DEBUG_DEAD_DELAY) : undefined};
+        const initOptions = {deadDelay: nonEmptyStringOrDefault(process.env.DEBUG_DEAD_DELAY, undefined) !== undefined ? Number.parseInt(process.env.DEBUG_DEAD_DELAY) : undefined};
         for(const c of scrobbleClients.clients) {
-            c.initTasks(clientInitOptions);
+            c.initTasks(initOptions);
             const res = await Promise.race([
                 sleep(2200),
                 (async () => {
@@ -227,7 +227,7 @@ const dataDir = getDataDir();
         }
 
         for(const c of scrobbleSources.sources) {
-            c.initTasks();
+            c.initTasks(initOptions);
             const res = await Promise.race([
                 sleep(2200),
                 (async () => {

src/backend/ioc.ts

@@ -12,7 +12,7 @@ import TransformerManager from "./common/transforms/TransformerManager.ts";
 import type {TransformerCommonConfig} from "../core/Atomic.ts";
 import prom from 'prom-client';
 import { CoverArtApiClient } from "./common/vendor/musicbrainz/CoverArtApiClient.ts";
-import { version } from "./version.ts";
+import { version, stable } from "./version.ts";
 import type {DbConcrete} from "./common/database/drizzle/drizzleUtils.ts";
 import type { MSBackendEventMap } from "./common/infrastructure/MSBackendEventMap.ts";
 
@@ -35,11 +35,21 @@ const discovered = new prom.Counter({
             help: 'Number of discovered plays for a Source',
             labelNames: ['name', 'type']
 });
+const sourceDead = new prom.Gauge({
+            name: 'multiscrobbler_source_dead',
+            help: 'Number of dead letter plays for a Source',
+            labelNames: ['name', 'type']
+});
 const queuedGauge = new prom.Gauge({
             name: 'multiscrobbler_client_queued',
             help: 'Number of queued plays for a Client',
             labelNames: ['name', 'type']
         });
+const queuedSourceGauge = new prom.Gauge({
+    name: 'multiscrobbler_source_queued',
+    help: 'Number of queued plays for a Source',
+    labelNames: ['name', 'type']
+});
 const deadLetterGauge = new prom.Gauge({
             name: 'multiscrobbler_client_deadletter',
             help: 'Number of deadletter plays for a Client',
@@ -130,8 +140,18 @@ const createRoot = (options: RootOptions = {logger: loggerDebug}) => {
 
     const portVal: number | string = process.env.PORT ?? port;
 
+    const versionParts: string[] = [];
+    if(stable === version) {
+        versionParts.push(stable);
+    } else {
+        if(stable !== 'unknown') {
+            versionParts.push(stable);
+        }
+        versionParts.push(version);
+    }
+
     return createContainer().add({
-        version,
+        version: versionParts.join('-'),
         configDir: getConfigDir(),
         isProd: process.env.NODE_ENV !== undefined && (process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'prod'),
         // @ts-ignore
@@ -144,6 +164,8 @@ const createRoot = (options: RootOptions = {logger: loggerDebug}) => {
         loggingConfig,
         sourceMetics: {
             discovered: discovered,
+            queued: queuedSourceGauge,
+            deadLetter: sourceDead
             //issues: sourceIssues
         },
         clientMetrics: {

src/backend/scrobblers/AbstractHistoricalScrobbleClient.ts

@@ -94,7 +94,7 @@ export default abstract class AbstractHistoricalScrobbleClient extends AbstractS
             await this.playsHistoricalRepo.createPlays(batch);
             return [true, batch.length];
         } catch (e) {
-            logger.warn(`Failed to persist batch of ${batch} plays, trying individually...`);
+            logger.warn(`Failed to persist batch of ${batch.length} plays, trying individually...`);
         }
         signal?.throwIfAborted();
 

src/backend/scrobblers/DiscordScrobbler.ts

@@ -1,8 +1,8 @@
 import type {Logger, LogLevel} from "@foxxmd/logging";
 import type EventEmitter from "events";
-import type {PlayMatchResult, PlayObject, SourcePlayerObj} from "../../core/Atomic.ts";
+import type {ComponentAuthType, PlayMatchResult, PlayObject, SourcePlayerObj} from "../../core/Atomic.ts";
 import { type FormatPlayObjectOptions } from "../common/infrastructure/Atomic.ts";
-import { SINGLE_USER_PLATFORM_ID_STR } from '../../core/Atomic.ts';
+import { COMPONENT_AUTH_TYPE, SINGLE_USER_PLATFORM_ID_STR } from '../../core/Atomic.ts';
 import { CALCULATED_PLAYER_STATUSES } from '../../core/Atomic.ts';
 import { REPORTED_PLAYER_STATUSES } from '../../core/Atomic.ts';
 
@@ -18,6 +18,7 @@ import dayjs from "dayjs";
 export default class DiscordScrobbler extends AbstractScrobbleClient {
 
     api: DiscordWSClient | DiscordIPCClient;
+    override authType: ComponentAuthType = COMPONENT_AUTH_TYPE.unattended;
     requiresAuth = true;
     requiresAuthInteraction = false;
     override nowPlayingIsRealtime: boolean = true;
@@ -71,7 +72,11 @@ export default class DiscordScrobbler extends AbstractScrobbleClient {
                 this.authed = false;
                 this.connectionOK = false;
             }
-            await this.tryStopScrobbling();
+            try {
+                await this.tryStopScrobbling('API emitted stop event');
+            } catch (e) {
+                this.logger.warn(new Error('Failed to stop scrobbling loop after emitter stopped', {cause: e}));
+            }
         });
 
         if(typeof artwork === 'boolean') {
@@ -119,7 +124,7 @@ export default class DiscordScrobbler extends AbstractScrobbleClient {
         }
     }
 
-    queueScrobble = async (data: PlayObject | PlayObject[], source: string) => {
+    queueScrobble = async (data: PlayObject | PlayObject[]) => {
         // discord does not handle scrobbles, only Now Playing
         // so don't bother queueing any scrobbles as we don't want to cache them
         // or give the user the impression they are used (in UI as a number of queued scrobbles)

src/backend/scrobblers/KoitoScrobbler.ts

@@ -1,6 +1,6 @@
 import type {Logger} from "@foxxmd/logging";
 import type EventEmitter from "events";
-import type {PlayObject, SourcePlayerObj} from "../../core/Atomic.ts";
+import {COMPONENT_AUTH_TYPE, type ComponentAuthType, type PlayObject, type SourcePlayerObj} from "../../core/Atomic.ts";
 import { buildTrackString, capitalize } from "../../core/StringUtils.ts";
 import { isNodeNetworkException } from "../common/errors/NodeErrors.ts";
 import type {FormatPlayObjectOptions, TimeRangeListensFetcher} from "../common/infrastructure/Atomic.ts";
@@ -15,6 +15,7 @@ import { createGetScrobblesForTimeRangeFunc } from "../utils/ListenFetchUtils.ts
 export default class KoitoScrobbler extends AbstractScrobbleClient {
 
     api: KoitoApiClient;
+    override authType: ComponentAuthType = COMPONENT_AUTH_TYPE.unattended;
     requiresAuth = true;
     requiresAuthInteraction = false;
     getScrobblesForTimeRange: TimeRangeListensFetcher