mass-queue-types 0.1.0

package/.editorconfig

@@ -0,0 +1,8 @@
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.js]
+indent_style = space
+indent_size = 2
+max_line_length = 120

package/.gitattributes

@@ -0,0 +1,4 @@
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gábor Tolnai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+[![GitHub Release][release-shield]][release]
+
+[![Maintainer][maintainer-shield]][maintainer]
+[![GitHub Activity][activity-shield]][activity]
+[![License][license-shield]][license]
+
+</div>
+
+[release-shield]: https://img.shields.io/github/release/droans/mass-queue-types.svg?style=for-the-badge
+[release]: https://github.com/droans/mass-queue-types/releases
+[license-shield]: https://img.shields.io/github/license/droans/mass-queue-types?style=for-the-badge
+[license]: LICENSE
+[maintainer-shield]: https://img.shields.io/badge/maintainer-droans-blue.svg?style=for-the-badge
+[maintainer]: https://github.com/droans
+[activity-shield]: https://img.shields.io/github/last-commit/droans/mass-queue-types?style=for-the-badge
+[activity]: https://github.com/droans/mass-queue-types/commits/main
+
+# Music Assistant Queue Actions Types
+
+Typescript types and interfaces for the [Music Assistant Queue Actions](https://github.com/droans/mass_queue)
+
+# Table of Contents
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+  - [Installation](#installation)
+- [Configuration](#configuration)
+  - [Base Config](#base-config)
+  - [Entity Config](#entity-config)
+  - [Entity Hidden Elements Config](#entity-hidden-elements-config)
+  - [Music Player Config](#music-player-config)
+  - [Music Player Hidden Elements Config](#music-player-hidden-elements-config)
+  - [Music Player Layout Config](#music-player-layout-config)
+  - [Queue Config](#queue-config)
+  - [Queue Hidden Elements Config](#queue-hidden-elements-config)
+  - [Media Browser Config](#media-browser-config)
+  - [Media Browser Hidden Elements Config](#media-browser-hidden-elements-config)
+  - [Favorites Config](#favorites-config)
+  - [Recommendations Config](#recommendations-config)
+  - [Sections Config](#sections-config)
+  - [Section Item Config](#section-item-config)
+  - [Players Config](#players-config)
+  - [Players Hidden Elements Config](#players-hidden-elements-config)
+- [FAQs](#faqs)
+  - [The card won't display at all or won't display properly!](#the-card-wont-display-at-all-or-wont-display-properly)
+  - [The media browser won't display any items for:](#the-media-browser-wont-display-any-items-for)
+  - [I'm not seeing any artwork in the queue or media browser!](#im-not-seeing-any-artwork-in-the-queue-or-media-browser)
+  - [How do I theme the card?](#how-do-i-theme-the-card)
+  - [Can this card work in my local language?](#can-this-card-work-in-my-local-language)
+  - [I am having issues with this card on my iOS/OSX device but it works fine elsewhere.](#i-am-having-issues-with-this-card-on-my-iososx-device-but-it-works-fine-elsewhere)
+  - [I have other questions or issues not addressed](#i-have-other-questions-or-issues-not-addressed)
+- [Contributing](#contributing)
+- [Developing](#developing)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Installation
+
+1. Add `@droans/mass-queue-actions` to your package.json file or run `npm i @droans/mass-queue-actions`
+
+# Usage
+
+## Service Schemas
+All service schemas are available as PARTIAL (service data only) or FULL (entire service call) schemas. Full will only work when calling `hass.callWS` due to the function schemas.
+
+**Use FULL when...**
+* You are calling `hass.callWS`.
+* You want complete validation, including the `type`, `domain`, `service`, and (if applicable), `return_response`.
+
+**Use PARTIAL when...**
+* You are calling `hass.callService`.
+* You only want to validate the service data being passed.
+
+### Available service schemas
+
+All `mass_queue` services have schemas available:
+* `get_group_volume`
+* `get_queue_items`
+* `get_recommendations`
+* `move_queue_item_down`
+* `move_queue_item_next`
+* `move_queue_item_up`
+* `play_queue_item`
+* `remove_queue_item`
+* `send_command`
+* `set_group_volume`
+* `unfavorite_current_item`
+
+## Response Schemas
+There are only a few services in Music Assistant Queue Actions which can return a service response. All of these are available.
+
+Like with Service Schemas, these are available as PARTIAL (response data only) or FULL (data inside the `response` key).
+
+### Available service response schemas:
+* `get_group_volume`
+* `get_queue_items`
+* `get_recommendations`
+
+## Websocket Commands
+Music Assistant Queue Actions supports a handful of WebSocket commands which aren't available as service calls. All of them have their service and response schemas available.
+
+### Available WebSocket schemas:
+* `mass_queue/download_and_encode_image`
+  * **NOTE**: No response schema is available since this only returns a string
+* `mass_queue/encode_images`
+* `mass_queue.get_info`
+
+# FAQs
+
+## I would like to sponsor you/the card and/or pay to add a new feature!
+
+While I appreciate it, I am not going to accept any funding.
+
+When someone funds development, there's often an implied belief that the card will keep being developed or the maintainer will provide new projects. I want to be able to drop development on this card when I feel that it is complete. I do not want people to feel misled, cheated, or that I should prioritize their wants over anything else. This card is something I created for myself
+
+## I have other questions or issues not addressed
+
+Check the [repository issues](https://github.com/droans/mass-queue-types/issues) to see if your question has already been asked. If not, feel free to [submit a new issue](https://github.com/droans/mass-queue-types/issues/new). 
+
+# Contributing
+
+I am happy to accept any new contributions to this repository. Feel free to fork and submit pull requests.
+
+# Developing
+
+This card uses `corepack` for development and relies on Node 22.
+
+### Clone the repository:
+```bash
+git clone https://github.com/droans/mass-queue-types
+```
+
+### Set up the environment
+Switch to Node 22:
+```bash
+nvm use 22
+```
+
+Install `corepack`:
+```bash
+npm install corepack
+```
+
+Install dependencies:
+```bash
+yarn install
+```

package/eslint.config.mjs

@@ -0,0 +1,55 @@
+import eslint from "@eslint/js";
+import prettierConfig from "eslint-config-prettier";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import wc from 'eslint-plugin-wc';
+const rootConfigFiles = [".prettierrc.js", "eslint.config.mjs"];
+
+export default tseslint.config(
+  { ignores: ["dist", "node_modules/*"] },
+  // apply default config
+  prettierConfig,
+  eslint.configs.recommended,
+  tseslint.configs.strictTypeChecked,
+  tseslint.configs.stylisticTypeChecked,
+  {
+    plugins: {
+      wc: wc,
+    },
+    rules: {
+      ...wc.configs.recommended.rules,
+    }
+  },
+  // default language/parser options
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: rootConfigFiles,
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+  },
+  // individual rule overrides
+  {
+    rules: {
+      "no-console": "warn",
+      "@typescript-eslint/no-unnecessary-condition": "off",
+    },
+  },
+  // disable type checking for root config files
+  {
+    files: rootConfigFiles,
+    ...tseslint.configs.disableTypeChecked,
+    languageOptions: { sourceType: "commonjs" },
+    rules: {
+      ...tseslint.configs.disableTypeChecked.rules,
+      "@typescript-eslint/no-require-imports": "off",
+    },
+  }
+);

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mass-queue-types",
+  "description": "Custom Types and Interfaces for Music Assistant Queue Actions",
+  "repository": "https://github.com/droans/mass-queue-types",
+  "author": "Michael Carroll",
+  "version": "0.1.0",
+  "module": "mass-queue-types.js",
+  "keywords": [
+    "home-assistant",
+    "homeassistant",
+    "hass",
+    "hacs",
+    "lovelace",
+    "custom-cards",
+    "music-assistant",
+    "mass_queue",
+    "mass",
+    "music",
+    "media",
+    "player",
+    "assistant"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@eslint/js": "9.39.1",
+    "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.4",
+    "@typescript-eslint/parser": "^8.46.4",
+    "eslint": "9.21.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-jest": "29.1.0",
+    "eslint-plugin-wc": "^3.0.1",
+    "prettier": "^3.6.2",
+    "rollup": "^4.53.2",
+    "rollup-plugin-commonjs": "^10.1.0",
+    "rollup-plugin-serve": "^3.0.0",
+    "typescript": "5.8.2",
+    "typescript-eslint": "8.26.0"
+  },
+  "scripts": {
+    "build": "yarn rollup",
+    "prettier": "prettier ./src --write",
+    "lint": "eslint packages/**/*.ts --max-warnings 0 --no-warn-ignored",
+    "full": "echo 'Generating TOC' && yarn docs && echo 'Running Prettier' && yarn prettier && echo 'Linting' && yarn lint",
+    "docs": "doctoc ./README.md --maxlevel 2"
+  },
+  "packageManager": "yarn@4.9.1",
+  "prettier": {
+    "printWidth": 80,
+    "tabWidth": 2,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": false,
+    "trailingComma": "all",
+    "bracketSpacing": true,
+    "bracketSameLine": false,
+    "arrowParens": "always",
+    "endOfLine": "lf"
+  }
+}

package/packages/actions/get_group_volume.ts

@@ -0,0 +1,18 @@
+import { baseMassQueueServiceWithResponseSchema } from "../utils.js";
+
+export interface getGroupVolumePartialServiceResponse {
+  volume_level: number
+}
+
+export interface getGroupVolumeServiceResponse {
+  response: getGroupVolumePartialSchema
+}
+
+export interface getGroupVolumePartialSchema {
+  entity: string;
+}
+
+export interface getGroupVolumeServiceSchema extends baseMassQueueServiceWithResponseSchema {
+  service: "get_group_volume",
+  service_data: getGroupVolumePartialSchema,
+}

package/packages/actions/get_queue_items.ts

@@ -0,0 +1,37 @@
+import { baseMassQueueServiceWithResponseSchema } from "../utils.js";
+
+export interface queueItem {
+  media_title: string;
+  media_album_name: string;
+  media_artist: string;
+  media_content_id: string;
+  playing: boolean;
+  queue_item_id: string;
+  media_image: string;
+  local_image_encoded?: string;
+  show_action_buttons: boolean;
+  show_artist_name: boolean;
+  show_move_up_next: boolean;
+  favorite: boolean;
+};
+
+export type queueItems = queueItem[];
+
+type getQueueItemsPartialResponse = Record<string, queueItems>;
+
+export interface getQueueItemsServiceResponse {
+  response: getQueueItemsPartialResponse
+}
+
+export interface getQueueItemsPartialSchema {
+  entity: string;
+  limit_before?: number;
+  limit_after?: number;
+  limt?: number;
+  offset?: number;
+}
+
+export interface getQueueItemsServiceSchema extends baseMassQueueServiceWithResponseSchema {
+  service: "get_queue_items",
+  service_data: getQueueItemsPartialSchema,
+}

package/packages/actions/get_recommendations.ts

@@ -0,0 +1,40 @@
+import { baseMassQueueServiceWithResponseSchema } from "../utils.js";
+
+export interface recommendationItem {
+  item_id: string;
+  name: string;
+  sort_name: string;
+  uri: string;
+  media_type: string;
+  image: string;
+}
+
+export type recommendationItems = recommendationItem[];
+
+export interface recommendationSection {
+  item_id: string;
+  provider: string;
+  sort_name: string;
+  name: string;
+  uri: string;
+  icon: string;
+  image: string | null;
+  items: recommendationItems;
+}
+
+export interface getRecommendationsPartialServiceResponse {
+  response: recommendationSection[];
+}
+
+export interface getRecommendationsServiceResponse {
+  response: getRecommendationsPartialServiceResponse;
+}
+
+export interface getRecommendationsPartialSchema {
+  entity: string;
+}
+
+export interface getRecommendationsServiceSchema extends baseMassQueueServiceWithResponseSchema {
+  service: "get_recommendations",
+  service_data: getRecommendationsPartialSchema,
+}

package/packages/actions/move_queue_item_down.ts

@@ -0,0 +1,9 @@
+import {
+  baseMassQueueServiceSchema,
+  queueItemPartialSchema
+} from "../utils.js";
+
+export interface moveQueueItemDownServiceSchema extends baseMassQueueServiceSchema {
+  service: "move_queue_item_down",
+  service_data: queueItemPartialSchema,
+}

package/packages/actions/move_queue_item_next.ts

@@ -0,0 +1,9 @@
+import {
+  baseMassQueueServiceSchema,
+  queueItemPartialSchema
+} from "../utils.js";
+
+export interface moveQueueItemNextServiceSchema extends baseMassQueueServiceSchema {
+  service: "move_queue_item_next",
+  service_data: queueItemPartialSchema,
+}

package/packages/actions/move_queue_item_up.ts

@@ -0,0 +1,9 @@
+import {
+  baseMassQueueServiceSchema,
+  queueItemPartialSchema
+} from "../utils.js";
+
+export interface moveQueueItemUpServiceSchema extends baseMassQueueServiceSchema {
+  service: "move_queue_item_up",
+  service_data: queueItemPartialSchema,
+}

package/packages/actions/play_queue_item.ts

@@ -0,0 +1,9 @@
+import {
+  baseMassQueueServiceSchema,
+  queueItemPartialSchema
+} from "../utils.js";
+
+export interface playQueueItemServiceSchema extends baseMassQueueServiceSchema {
+  service: "play_queue_item",
+  service_data: queueItemPartialSchema,
+}

package/packages/actions/remove_queue_item.ts

@@ -0,0 +1,9 @@
+import {
+  baseMassQueueServiceSchema,
+  queueItemPartialSchema
+} from "../utils.js";
+
+export interface removeServiceSchema extends baseMassQueueServiceSchema {
+  service: "remove_queue_item",
+  service_data: queueItemPartialSchema,
+}

package/packages/actions/send_command.ts

@@ -0,0 +1,16 @@
+import { baseMassQueueServiceSchema } from "../utils.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type dataSchema = Record<string, any>;
+
+
+export interface sendCommandPartialSchema {
+  command: string;
+  config_entry_id: string;
+  data: dataSchema | null | undefined;
+}
+
+export interface sendCommandServiceSchema extends baseMassQueueServiceSchema {
+  service: "send_command",
+  service_data: sendCommandPartialSchema,
+}

package/packages/actions/set_group_volume.ts

@@ -0,0 +1,11 @@
+import { baseMassQueueServiceSchema } from "../utils.js";
+
+export interface setGroupVolumePartialSchema {
+  entity: string;
+  volume_level: number;
+}
+
+export interface setGroupVolumeServiceSchema extends baseMassQueueServiceSchema {
+  service: "set_group_volume",
+  service_data: setGroupVolumePartialSchema,
+}

package/packages/actions/unfavorite_current_item.ts

@@ -0,0 +1,10 @@
+import { baseMassQueueServiceSchema } from "../utils.js";
+
+export interface unfavoriteCurrentItemPartialSchema {
+  entity: string;
+}
+
+export interface unfavoriteCurrentItemServiceSchema extends baseMassQueueServiceSchema {
+  service: "unfavorite_current_item",
+  service_data: unfavoriteCurrentItemPartialSchema,
+}

package/packages/utils.ts

@@ -0,0 +1,14 @@
+export interface baseMassQueueServiceSchema {
+  type: "call_service",
+  domain: "mass_queue",
+  service: string
+}
+
+export interface baseMassQueueServiceWithResponseSchema extends baseMassQueueServiceSchema {
+  return_response: true;
+}
+
+export interface queueItemPartialSchema {
+  entity: string;
+  queue_item_id: string;
+}

package/packages/ws/download_and_encode_image.ts

@@ -0,0 +1,4 @@
+export interface downloadAndEncodeImagesWSServiceSchema {
+  type: "mass_queue/download_and_encode_image";
+  url: string;
+}

package/packages/ws/encode_images.ts

@@ -0,0 +1,18 @@
+export interface encodeImagesWSServiceSchema {
+  type: "mass_queue/encode_images";
+  entity_id: string;
+  images: string[];
+}
+
+export interface imageData {
+  provider: string;
+  path: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [str: string]: any;
+}
+
+export interface encodedImageData extends imageData {
+  encoded: string;
+}
+
+export type encodeImagesWSServiceResponse = encodedImageData[];

package/packages/ws/get_info.ts

@@ -0,0 +1,32 @@
+export interface getInfoWSServiceSchema {
+  type: "mass_queue/get_info";
+  entity_id: string;
+}
+
+export interface getInfoWSResponseSchema {
+  available: boolean;
+  can_group_with: string[];
+  connection: {
+    configuration_url: string;
+    url: string;
+  };
+  entries: {
+    music_assistant: string;
+    mass_queue: string;
+  };
+  features: string[];
+  manufacturer: string;
+  model: string;
+  name: string;
+  player_id: string;
+  provider: string;
+  queue_id: string;
+  server: {
+    connection: {
+      url: string;
+      websocket: string;
+    };
+  };
+  synced_to: string|null
+  type: string;
+}

package/rollup.config.dev.js

@@ -0,0 +1,32 @@
+import typescript from '@rollup/plugin-typescript';
+import commonjs from 'rollup-plugin-commonjs';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import serve from 'rollup-plugin-serve';
+import terser from '@rollup/plugin-terser';
+import json from '@rollup/plugin-json';
+
+export default {
+  input: ['src/main.ts'],
+  output: {
+    file: '../www/mass-queue-types.js',
+    format: 'es',
+  },
+  plugins: [
+    nodeResolve(),
+    commonjs(),
+    typescript(),
+    json(),
+    terser(),
+    serve({
+      contentBase: '../www',
+      host: '0.0.0.0',
+      port: 5001,
+      headers: {
+        'Access-Control-Allow-Origin': '*',
+      },
+    }),
+  ],
+  onwarn(warning, warn) {
+    warn(warning);
+  },
+};

package/rollup.config.js

@@ -0,0 +1,25 @@
+import typescript from '@rollup/plugin-typescript';
+import commonjs from 'rollup-plugin-commonjs';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+import json from '@rollup/plugin-json';
+
+export default [
+  {
+    input: 'src/main.ts',
+    output: {
+      file: './dist/mass-queue-types.js',
+      format: 'es',
+    },
+    plugins: [
+      nodeResolve(),
+      commonjs(),
+      typescript(),
+      json(),
+      terser(),
+    ],
+    onwarn(warning, warn) {
+      warn(warning);
+    },
+  },
+];

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "lib": ["es2021", "dom", "dom.iterable"],
+    "noEmit": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "strict": true,
+    "noImplicitAny": false,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+  },
+  "include": ["packages"]
+}