homebridge-unifi-access 1.3.0 → 1.5.0

package/homebridge-ui/public/lib/webUi.mjs

@@ -0,0 +1,184 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi.mjs: Plugin webUI.
+ */
+"use strict";
+
+import { webUiFeatureOptions } from "./webUi-featureoptions.mjs";
+
+export class webUi {
+
+  // Feature options class instance.
+  featureOptions;
+
+  // First run webUI callback endpoints for customization.
+  #firstRun;
+
+  // Plugin name.
+  #name;
+
+  /**
+   * featureOptions - parameters to webUiFeatureOptions.
+   * firstRun - first run handlers:
+   *   isRequired - do we need to run the first run UI workflow?
+   *   onStart - initialization for the first run webUI to populate forms and other startup tasks.
+   *   onSubmit - execute the first run workflow, typically a login or configuration validation of some sort.
+   * name - plugin name.
+   */
+  constructor({ featureOptions, firstRun = {}, name } = {}) {
+
+    // Defaults for our first run handlers.
+    this.#firstRun = { isRequired: () => false, onStart: () => true, onSubmit: () => true };
+
+    // Figure out the options passed in to us.
+    this.featureOptions = new webUiFeatureOptions(featureOptions);
+    this.#firstRun = Object.assign({}, this.#firstRun, firstRun);
+    this.#name = name;
+  }
+
+  /**
+   * Render the webUI.
+   */
+  // Render the UI.
+  show() {
+
+    // Fire off our UI, catching errors along the way.
+    try {
+
+      this.#launchWebUI();
+    } catch(err) {
+
+      // If we had an error instantiating or updating the UI, notify the user.
+      homebridge.toast.error(err.message, "Error");
+    } finally {
+
+      // Always leave the UI in a usable place for the end user.
+      homebridge.hideSpinner();
+    }
+  }
+
+  // Show the first run user experience if we don't have valid login credentials.
+  async #showFirstRun() {
+
+    const buttonFirstRun = document.getElementById("firstRun");
+
+    // Run a custom initialization handler the user may have provided.
+    if(!(await this.#processHandler(this.#firstRun.onStart))) {
+
+      return;
+    }
+
+    // First run user experience.
+    buttonFirstRun.addEventListener("click", async () => {
+
+      // Show the beachball while we setup.
+      homebridge.showSpinner();
+
+      // Run a custom submit handler the user may have provided.
+      if(!(await this.#processHandler(this.#firstRun.onSubmit))) {
+
+        return;
+      }
+
+      // Create our UI.
+      document.getElementById("pageFirstRun").style.display = "none";
+      document.getElementById("menuWrapper").style.display = "inline-flex";
+      this.featureOptions.show();
+
+      // All done. Let the user interact with us, although in practice, we shouldn't get here.
+      // homebridge.hideSpinner();
+    });
+
+    document.getElementById("pageFirstRun").style.display = "block";
+  }
+
+  // Show the main plugin configuration tab.
+  #showSettings() {
+
+    // Show the beachball while we setup.
+    homebridge.showSpinner();
+
+    // Highlight the tab in our UI.
+    this.#toggleClasses("menuHome", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuFeatureOptions", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuSettings", "btn-primary", "btn-elegant");
+
+    document.getElementById("pageSupport").style.display = "none";
+    document.getElementById("pageFeatureOptions").style.display = "none";
+
+    homebridge.showSchemaForm();
+
+    // All done. Let the user interact with us.
+    homebridge.hideSpinner();
+  }
+
+  // Show the support tab.
+  #showSupport() {
+
+    // Show the beachball while we setup.
+    homebridge.showSpinner();
+    homebridge.hideSchemaForm();
+
+    // Highlight the tab in our UI.
+    this.#toggleClasses("menuHome", "btn-primary", "btn-elegant");
+    this.#toggleClasses("menuFeatureOptions", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuSettings", "btn-elegant", "btn-primary");
+
+    document.getElementById("pageSupport").style.display = "block";
+    document.getElementById("pageFeatureOptions").style.display = "none";
+
+    // All done. Let the user interact with us.
+    homebridge.hideSpinner();
+  }
+
+  // Launch our webUI.
+  async #launchWebUI() {
+
+    // Retrieve the current plugin configuration.
+    this.featureOptions.currentConfig = await homebridge.getPluginConfig();
+
+    // Add our event listeners to animate the UI.
+    document.getElementById("menuHome").addEventListener("click", () => this.#showSupport());
+    document.getElementById("menuFeatureOptions").addEventListener("click", () => this.featureOptions.show());
+    document.getElementById("menuSettings").addEventListener("click", () => this.#showSettings());
+
+    // Get the list of devices the plugin knows about.
+    const devices = await homebridge.getCachedAccessories();
+
+    // If we've got devices detected, we launch our feature option UI. Otherwise, we launch our first run UI.
+    if(this.featureOptions.currentConfig.length && devices?.length && !(await this.#processHandler(this.#firstRun.isRequired))) {
+
+      document.getElementById("menuWrapper").style.display = "inline-flex";
+      this.featureOptions.show();
+
+      return;
+    }
+
+    // If we have the name property set for the plugin configuration yet, let's do so now. If we don't have a configuration, let's initialize it as well.
+    (this.featureOptions.currentConfig[0] ??= { name: this.#name }).name ??= this.#name;
+
+    // Update the plugin configuration and launch the first run UI.
+    await homebridge.updatePluginConfig(this.featureOptions.currentConfig);
+    this.#showFirstRun();
+  }
+
+  // Utility to process user-provided custom handlers that can handle both synchronous and asynchronous handlers.
+  async #processHandler(handler) {
+
+    if(((typeof handler === "function") && !(await handler())) || ((typeof handler !== "function") && !handler)) {
+
+      return false;
+    }
+
+    return true;
+  }
+
+  // Utility to toggle our classes.
+  #toggleClasses(id, removeClass, addClass) {
+
+    const element = document.getElementById(id);
+
+    element.classList.remove(removeClass);
+    element.classList.add(addClass);
+  }
+}

package/homebridge-ui/public/ui.mjs

@@ -1,182 +1,291 @@
 /* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * ui.mjs: HBUA webUI.
+ * ui.mjs: Homebridge UniFi Access webUI.
  */
 "use strict";
 
-// Keep a list of all the feature options and option groups. We dynamically import our modules to avoid browser caches.
-const featureOptions = new (await import("./access-featureoptions.mjs")).AccessFeatureOptions();
+import { webUi } from "./lib/webUi.mjs";
 
-// Show the first run user experience if we don't have valid login credentials.
-function showFirstRun () {
+// Execute our first run screen if we don't have valid Access login credentials and a controller.
+const firstRunIsRequired = () => {
 
-  const buttonFirstRun = document.getElementById("firstRun");
-  const inputAddress = document.getElementById("address");
-  const inputUsername = document.getElementById("username");
-  const inputPassword = document.getElementById("password");
+  if(ui.featureOptions.currentConfig.length && ui.featureOptions.currentConfig[0].controllers?.length &&
+    ui.featureOptions.currentConfig[0].controllers[0]?.address?.length && ui.featureOptions.currentConfig[0].controllers[0]?.username?.length &&
+    ui.featureOptions.currentConfig[0].controllers[0]?.password?.length) {
+
+    return false;
+  }
+
+  return true;
+};
+
+// Initialize our first run screen with any information from our existing configuration.
+const firstRunOnStart = () => {
+
+  // Pre-populate with anything we might already have in our configuration.
+  document.getElementById("address").value = ui.featureOptions.currentConfig[0].controllers?.[0]?.address ?? "";
+  document.getElementById("username").value = ui.featureOptions.currentConfig[0].controllers?.[0]?.username ?? "";
+  document.getElementById("password").value = ui.featureOptions.currentConfig[0].controllers?.[0]?.password ?? "";
+
+  return true;
+};
+
+// Validate our Access credentials.
+const firstRunOnSubmit = async () => {
+
+  const address = document.getElementById("address").value;
+  const username = document.getElementById("username").value;
+  const password = document.getElementById("password").value;
   const tdLoginError = document.getElementById("loginError");
 
-  // If we don't have any controllers configured, initialize the list.
-  if(!featureOptions.currentConfig[0].controllers) {
+  tdLoginError.innerHTML = " ";
+
+  if(!address?.length || !username?.length || !password?.length) {
+
+    tdLoginError.innerHTML = "<code class=\"text-danger\">Please enter a valid UniFi Access controller address, username and password.</code>";
+    homebridge.hideSpinner();
 
-    featureOptions.currentConfig[0].controllers = [ {} ];
+    return false;
   }
 
-  // Pre-populate with anything we might already have in our configuration.
-  inputAddress.value = featureOptions.currentConfig[0].controllers[0].address ?? "";
-  inputUsername.value = featureOptions.currentConfig[0].controllers[0].username ?? "";
-  inputPassword.value = featureOptions.currentConfig[0].controllers[0].password ?? "";
+  const udaDevices = await homebridge.request("/getDevices", { address: address, password: password, username: username });
+
+  // Couldn't connect to the Access controller for some reason.
+  if(!udaDevices?.length) {
+
+    tdLoginError.innerHTML = "Unable to login to the UniFi Access controller.<br>" +
+      "Please check your controller address, username, and password.<br><code class=\"text-danger\">" + (await homebridge.request("/getErrorMessage")) + "</code>";
+    homebridge.hideSpinner();
+
+    return false;
+  }
+
+  // Save the login credentials to our configuration.
+  if(!ui.featureOptions.currentConfig[0].controllers?.length) {
+
+    ui.featureOptions.currentConfig[0].controllers = [{}];
+  }
+
+  ui.featureOptions.currentConfig[0].controllers[0].address = address;
+  ui.featureOptions.currentConfig[0].controllers[0].username = username;
+  ui.featureOptions.currentConfig[0].controllers[0].password = password;
+
+  await homebridge.updatePluginConfig(ui.featureOptions.currentConfig);
+
+  return true;
+};
 
-  // Clear login error messages when the login credentials change.
-  inputAddress.addEventListener("input", () => {
+// Return the list of devices associated with a given Access controller.
+const getDevices = async (controller) => {
 
-    tdLoginError.innerHTML = "&nbsp;";
-  });
+  // If we're in the global context, we have no devices.
+  if(!controller) {
 
-  inputUsername.addEventListener("input", () => {
+    return [];
+  }
+
+  // Retrieve the current list of devices from the Access controller.
+  let devices = await homebridge.request("/getDevices", { address: controller.address, password: controller.password, username: controller.username });
+
+  // Since the controller JSON doesn't have the same properties as the device JSON, let's make the controller JSON emulate the properties we care about.
+  if(devices?.length) {
+
+    /* eslint-disable camelcase */
+    devices[0].display_model = "controller";
+    devices[0].ip = devices[0].host.ip;
+    devices[0].is_online = true;
+    devices[0].mac = devices[0].host.mac;
+    devices[0].model = devices[0].host.device_type;
+    devices[0].unique_id = devices[0].host.mac;
+    /* eslint-enable camelcase */
+  }
+
+  // Add the fields that the webUI framework is looking for to render.
+  devices = devices.map(device => ({
 
-    tdLoginError.innerHTML = "&nbsp;";
-  });
+    ...device,
+    serial: device.mac.replace(/:/g, "").toUpperCase()
+  }));
 
-  inputPassword.addEventListener("input", () => {
+  return devices;
+};
 
-    tdLoginError.innerHTML = "&nbsp;";
-  });
+// Return whether a given device is a controller.
+const isController = (device) => device.modelKey === "controller";
 
-  // First run user experience.
-  buttonFirstRun.addEventListener("click", async () => {
+// Show the list of Access devices associated with a controller, grouped by model.
+const showSidebarDevices = (controller, devices) => {
 
-    // Show the beachball while we setup.
-    homebridge.showSpinner();
+  // Workaround for the time being to reduce the number of models we see to just the currently supported ones.
+  const modelKeys =
+    [...new Set(devices.filter(device => ["controller"].includes(device.display_model) || device.capabilities.includes("is_hub")).map(device => device.display_model))];
 
-    const address = inputAddress.value;
-    const username = inputUsername.value;
-    const password = inputPassword.value;
+  // Start with a clean slate.
+  ui.featureOptions.devicesTable.innerHTML = "";
 
-    tdLoginError.innerHTML = "&nbsp;";
+  for(const key of modelKeys) {
 
-    if(!address?.length || !username?.length || !password?.length) {
+    // Get all the devices associated with this device category.
+    const modelDevices = devices.filter(x => x.display_model === key);
 
-      tdLoginError.appendChild(document.createTextNode("Please enter a valid UniFi Access controller address, username and password."));
-      homebridge.hideSpinner();
-      return;
+    // Nothing in this category, let's keep going.
+    if(!modelDevices.length) {
+
+      continue;
     }
 
-    const udaDevices = await homebridge.request("/getDevices", { address: address, username: username, password: password });
+    // If it's a controller, we handle that case differently.
+    if(key === "controller") {
 
-    // Couldn't connect to the Access controller for some reason.
-    if(!udaDevices?.length) {
+      // Change the name of the controller that we show users once we've connected with the controller.
+      ui.featureOptions.webUiControllerList.map(x => (x.name === controller.address) ? x.childNodes[0].nodeValue = modelDevices[0].host.hostname : true);
 
-      tdLoginError.innerHTML = "Unable to login to the UniFi Access controller.<br>Please check your controller address, username, and password.<br><code class=\"text-danger\">" + (await homebridge.request("/getErrorMessage")) + "</code>";
-      homebridge.hideSpinner();
-      return;
+      continue;
     }
 
-    // Save the login credentials to our configuration.
-    featureOptions.currentConfig[0].controllers[0].address = address;
-    featureOptions.currentConfig[0].controllers[0].username = username;
-    featureOptions.currentConfig[0].controllers[0].password = password;
+    // Create a row for this device category.
+    const trCategory = document.createElement("tr");
 
-    await homebridge.updatePluginConfig(featureOptions.currentConfig);
+    // Disable any pointer events and hover activity.
+    trCategory.style.pointerEvents = "none";
 
-    // Create our UI.
-    document.getElementById("pageFirstRun").style.display = "none";
-    document.getElementById("menuWrapper").style.display = "inline-flex";
-    featureOptions.showUI();
-  });
+    // Create the cell for our device category row.
+    const tdCategory = document.createElement("td");
 
-  document.getElementById("pageFirstRun").style.display = "block";
-}
+    tdCategory.classList.add("m-0", "p-0", "pl-1", "w-100");
 
-// Show the main plugin configuration tab.
-function showSettings () {
+    // Add the category name, with appropriate casing.
+    tdCategory.appendChild(document.createTextNode((key.charAt(0).toUpperCase() + key.slice(1) + "s")));
+    tdCategory.style.fontWeight = "bold";
 
-  // Show the beachball while we setup.
-  homebridge.showSpinner();
+    // Add the cell to the table row.
+    trCategory.appendChild(tdCategory);
 
-  // Create our UI.
-  document.getElementById("menuHome").classList.remove("btn-elegant");
-  document.getElementById("menuHome").classList.add("btn-primary");
-  document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
-  document.getElementById("menuFeatureOptions").classList.add("btn-primary");
-  document.getElementById("menuSettings").classList.add("btn-elegant");
-  document.getElementById("menuSettings").classList.remove("btn-primary");
+    // Add the table row to the table.
+    ui.featureOptions.devicesTable.appendChild(trCategory);
 
-  document.getElementById("pageSupport").style.display = "none";
-  document.getElementById("pageFeatureOptions").style.display = "none";
+    for(const device of modelDevices) {
 
-  homebridge.showSchemaForm();
+      // Create a row for this device.
+      const trDevice = document.createElement("tr");
 
-  // All done. Let the user interact with us.
-  homebridge.hideSpinner();
-}
+      trDevice.classList.add("m-0", "p-0");
 
-// Show the support tab.
-function showSupport() {
+      // Create a cell for our device.
+      const tdDevice = document.createElement("td");
 
-  // Show the beachball while we setup.
-  homebridge.showSpinner();
-  homebridge.hideSchemaForm();
+      tdDevice.classList.add("m-0", "p-0" , "w-100");
 
-  // Create our UI.
-  document.getElementById("menuHome").classList.add("btn-elegant");
-  document.getElementById("menuHome").classList.remove("btn-primary");
-  document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
-  document.getElementById("menuFeatureOptions").classList.add("btn-primary");
-  document.getElementById("menuSettings").classList.remove("btn-elegant");
-  document.getElementById("menuSettings").classList.add("btn-primary");
+      const label = document.createElement("label");
 
-  document.getElementById("pageSupport").style.display = "block";
-  document.getElementById("pageFeatureOptions").style.display = "none";
+      label.name = device.serial;
+      label.appendChild(document.createTextNode(device.alias ?? device.display_model));
+      label.style.cursor = "pointer";
+      label.classList.add("mx-2", "my-0", "p-0", "w-100");
 
-  // All done. Let the user interact with us.
-  homebridge.hideSpinner();
-}
+      label.addEventListener("click", () => ui.featureOptions.showDeviceOptions(device.serial));
 
-// Launch our webUI.
-async function launchWebUI() {
+      // Add the device label to our cell.
+      tdDevice.appendChild(label);
 
-  // Retrieve the current plugin configuration.
-  featureOptions.currentConfig = await homebridge.getPluginConfig();
+      // Add the cell to the table row.
+      trDevice.appendChild(tdDevice);
 
-  // Add our event listeners to animate the UI.
-  menuHome.addEventListener("click", () => showSupport());
-  menuFeatureOptions.addEventListener("click", () => featureOptions.showUI());
-  menuSettings.addEventListener("click", () => showSettings());
+      // Add the table row to the table.
+      ui.featureOptions.devicesTable.appendChild(trDevice);
 
-  // If we've got a valid Access controller, username, and password configured, we launch our feature option UI. Otherwise, we launch our first run UI.
-  if(featureOptions.currentConfig.length && featureOptions.currentConfig[0].controllers?.length && featureOptions.currentConfig[0].controllers[0]?.address?.length && featureOptions.currentConfig[0].controllers[0]?.username?.length && featureOptions.currentConfig[0].controllers[0]?.password?.length) {
+      ui.featureOptions.webUiDeviceList.push(label);
+    }
+  }
+};
 
-    document.getElementById("menuWrapper").style.display = "inline-flex";
-    featureOptions.showUI();
-    return;
+// Only show feature options that are valid for the capabilities of this device.
+const validOption = (device, option) => {
+
+  if(device && (device.display_model !== "controller") && (
+    (option.hasFeature && (!device.capabilities || !option.hasFeature.some(x => device.capabilities[x]))) ||
+    (option.hasProperty && !option.hasProperty.some(x => x in device)) ||
+    (option.modelKey && (option.modelKey !== "all") && !option.modelKey.includes(device.display_model)))) {
+
+    return false;
+  }
+
+  return true;
+};
+
+// Only show feature option categories that are valid for a particular device type.
+const validOptionCategory = (device, category) => {
+
+  if(device && (device.display_model !== "controller") && !category.modelKey.some(model => ["all", device.display_model].includes(model))) {
+
+    return false;
   }
 
-  // If we have no configuration, let's create one.
-  if(!featureOptions.currentConfig.length) {
+  return true;
+};
 
-    featureOptions.currentConfig.push({ controllers: [ {} ], name: "UniFi Access" });
-  } else if(!("name" in featureOptions.currentConfig[0])) {
+// Show the details for this device.
+const showAccessDetails = (device) => {
+
+  // No device specified, we must be in a global context.
+  if(!device) {
+
+    document.getElementById("device_model").classList.remove("text-center");
+    document.getElementById("device_model").colSpan = 1;
+    document.getElementById("device_model").style.fontWeight = "normal";
+    document.getElementById("device_model").innerHTML = "N/A";
+    document.getElementById("device_mac").innerHTML = "N/A";
+    document.getElementById("device_address").innerHTML = "N/A";
+    document.getElementById("device_online").innerHTML = "N/A";
+
+    return;
+  }
 
-    // If we haven't set the name, let's do so now.
-    featureOptions.currentConfig[0].name = "UniFi Access";
+  // Populate the device details.
+  document.getElementById("device_model").classList.remove("text-center");
+  document.getElementById("device_model").colSpan = 1;
+  document.getElementById("device_model").style.fontWeight = "normal";
+  document.getElementById("device_model").innerHTML = device.model ?? device.display_model;
+  document.getElementById("device_mac").innerHTML = device.mac.replace(/:/g, "").toUpperCase();
+  document.getElementById("device_address").innerHTML = device.ip;
+  document.getElementById("device_online").innerHTML = device.is_online ? "Connected" : "Disconnected";
+};
+
+// Parameters for our feature options webUI.
+const featureOptionsParams = {
+
+  getDevices: getDevices,
+  hasControllers: true,
+  infoPanel: showAccessDetails,
+  sidebar: {
+
+    controllerLabel: "Access Controllers",
+    deviceLabel: "Access Devices",
+    showDevices: showSidebarDevices
+  },
+  ui: {
+
+    isController: isController,
+    validOption: validOption,
+    validOptionCategory: validOptionCategory
   }
+};
 
-  // Update the plugin configuration and launch the first run UI.
-  await homebridge.updatePluginConfig(featureOptions.currentConfig);
-  showFirstRun();
-}
+// Parameters for our plugin webUI.
+const webUiParams = {
 
-// Fire off our UI, catching errors along the way.
-try {
+  featureOptions: featureOptionsParams,
+  firstRun: {
 
-  launchWebUI();
-} catch(err) {
+    isRequired: firstRunIsRequired,
+    onStart: firstRunOnStart,
+    onSubmit: firstRunOnSubmit
+  },
+  name: "UniFi Access"
+};
 
-  // If we had an error instantiating or updating the UI, notify the user.
-  homebridge.toast.error(err.message, "Error");
-} finally {
+// Instantiate the webUI.
+const ui = new webUi(webUiParams);
 
-  // Always leave the UI in a usable place for the end user.
-  homebridge.hideSpinner();
-}
+// Display the webUI.
+ui.show();