mb-run 1.1.3 → 1.1.4-dev-20261026-c73389e

package/CHANGELOG.md

@@ -22,6 +22,14 @@ If you like this project and find it useful, please consider giving it a star on
 
 <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
+## [1.1.4] - Dev branch
+
+### Changed
+
+- [template]: Update the plugin frontend guide to v.1.0.1: build API URLs from Vite's base URL to preserve Home Assistant Ingress paths.
+
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
+
 ## [1.1.3] - 2026-10-24
 
 ### Added

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "mb-run",
-  "version": "1.1.3",
+  "version": "1.1.4-dev-20261026-c73389e",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mb-run",
-      "version": "1.1.3",
+      "version": "1.1.4-dev-20261026-c73389e",
       "license": "Apache-2.0",
       "dependencies": {
         "@typescript/typescript6": "6.0.2",
@@ -1496,6 +1496,24 @@
         "util": "^0.12.5"
       }
     },
+    "node_modules/async-function": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/async-function/-/async-function-1.0.0.tgz",
+      "integrity": "sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/async-generator-function": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/async-generator-function/-/async-generator-function-1.0.0.tgz",
+      "integrity": "sha512-+NAXNqgCrB95ya4Sr66i1CL2hqLVckAk7xwRYWdcm39/ELQ6YNn1aw5r0bdQtqNZgQpEWzc5yc/igXc7aL5SLA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/async-retry": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/async-retry/-/async-retry-1.3.3.tgz",
@@ -1990,16 +2008,19 @@
       }
     },
     "node_modules/get-intrinsic": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
-      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.1.tgz",
+      "integrity": "sha512-fk1ZVEeOX9hVZ6QzoBNEC55+Ucqg4sTVwrVuigZhuRPESVFpMyXnd3sbXvPOwp7Y9riVyANiqhEuRF0G1aVSeQ==",
       "license": "MIT",
       "dependencies": {
+        "async-function": "^1.0.0",
+        "async-generator-function": "^1.0.0",
         "call-bind-apply-helpers": "^1.0.2",
         "es-define-property": "^1.0.1",
         "es-errors": "^1.3.0",
         "es-object-atoms": "^1.1.1",
         "function-bind": "^1.1.2",
+        "generator-function": "^2.0.0",
         "get-proto": "^1.0.1",
         "gopd": "^1.2.0",
         "has-symbols": "^1.1.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mb-run",
-  "version": "1.1.3",
+  "version": "1.1.4-dev-20261026-c73389e",
   "description": "Matterbridge command line executor",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",

package/template/.agents-plugin/rules/plugin-frontend.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: 'How a plugin serves its own frontend SPA and custom REST API via onFetch v.1.0.0'
+description: 'How a plugin serves its own frontend SPA and custom REST API via onFetch v.1.0.1'
 ---
 
 # Matterbridge Plugin Frontend Guide
@@ -18,6 +18,27 @@ When a plugin package contains a built SPA at `apps/frontend/build/index.html`,
 
 A plugin frontend must call its own `/plugins/<pluginName>/api/...` namespace rather than the core `/api/...` endpoints.
 
+## Preserve the base path through Home Assistant Ingress
+
+Build plugin API URLs from Vite's `import.meta.env.BASE_URL`, without a leading slash on the appended path:
+
+```ts
+const response = await fetch(`${import.meta.env.BASE_URL}api/events`, {
+  signal,
+  headers: { Accept: 'application/json' },
+});
+```
+
+The frontend template's `vite.config.ts` uses `/plugins/<pluginName>/` as its development base and `./` as its production base. Keep this arrangement and the development proxy for `${base}api`:
+
+- In development, the request goes to `/plugins/<pluginName>/api/events` and Vite proxies it to Matterbridge.
+- In production, `./api/events` resolves relative to the plugin frontend document, retaining any reverse proxy prefix.
+- Through Home Assistant Ingress, `/api/hassio_ingress/<token>/plugins/<pluginName>/` therefore requests `/api/hassio_ingress/<token>/plugins/<pluginName>/api/events`.
+
+Do not hardcode `fetch('/plugins/<pluginName>/api/events')`, a core `/api/...` URL or the Matterbridge host/port in frontend code. A root-relative URL discards the Ingress prefix and sends the request outside the addon route. The absolute plugin paths listed above describe server routes, not URLs to hardcode in browser requests.
+
+Open the plugin frontend at its directory URL with a trailing slash, as Matterbridge does. Relative production URLs resolve against the document URL; if adding nested history-based SPA routes, ensure requests still resolve from the plugin root. Verify API requests during Vite development, direct Matterbridge access and Home Assistant Ingress access.
+
 ## Use `onFetch` for a plugin's custom API
 
 The frontend WebSocket RPC protocol dispatches a fixed set of built-in `/api/...` methods and does not provide a plugin extension point. Override `onFetch` in the platform class when the plugin's frontend needs to communicate with plugin code.

package/template/.claude-plugin/rules/plugin-frontend/plugin-frontend.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: 'How a plugin serves its own frontend SPA and custom REST API via onFetch v.1.0.0'
+description: 'How a plugin serves its own frontend SPA and custom REST API via onFetch v.1.0.1'
 paths:
   - 'apps/frontend/**'
   - 'src/*.ts'

package/template/.github-plugin/instructions/plugin-frontend/plugin-frontend.instructions.md

@@ -1,5 +1,5 @@
 ---
-name: 'Matterbridge Plugin Frontend Guide v.1.0.0'
+name: 'Matterbridge Plugin Frontend Guide v.1.0.1'
 description: 'How a plugin serves its own frontend SPA and custom REST API via onFetch'
 applyTo: 'apps/frontend/**, src/*.ts'
 ---