homebridge-generac 0.1.0-beta.1

package/homebridge-ui/public/js/copy.js

@@ -0,0 +1,167 @@
+/**
+ * Every string the settings page shows, verbatim from SPEC section 11.3 (the harness checks each constant
+ * against SPEC.md). Functions build the strings with a value inserted; their templates are in the SPEC too.
+ */
+export const TOAST_TITLE = 'Generac for Homebridge';
+/** SPEC 11.3 A. The banner artwork carries the title and tagline; here they are its alt text. */
+export const BANNER = {
+    file: 'generac-banner.png',
+    title: 'Generac for Homebridge',
+    tagline: 'Standby generator status in the Home app',
+};
+export const INTRO = {
+    one: 'Generac for Homebridge shows the standby generators on your Mobile Link account in the Home app. '
+        + 'Each generator appears as a Running sensor, a Fault sensor, a Maintenance Due sensor and a starting battery reading. '
+        + 'Propane models will also get a tank level later.',
+    two: 'It is read only. It cannot start, stop or exercise the generator. Connect your account below and your generators are found for you.',
+    accountHeading: 'Mobile Link account',
+    accountHelp: 'One account per Homebridge instance. Use the email and password you use in the Mobile Link app.',
+    generatorsHeading: 'Generators',
+    generatorsHelp: 'Every generator on the account gets a card here. You can rename each one.',
+    generatorsEmpty: 'No generators yet. Connect your Mobile Link account above and they appear here within a minute.',
+    settingsHeading: 'Settings',
+    closing: 'Your generators appear in the Home app as sensors. Add them to automations; for example, turn on a light when Running opens.',
+    affiliation: 'Not affiliated with or endorsed by Generac Power Systems, Inc. Generac and Mobile Link are its trademarks. '
+        + 'Uses Generac\'s undocumented Mobile Link API, which can change without notice.',
+};
+/** SPEC 11.3 B. */
+export const ACCOUNT = {
+    title: 'Mobile Link account',
+    notConnectedBody: 'Sign in once with your Mobile Link email and password. Your password is used to sign in and is not stored.',
+    connect: 'Connect',
+    checking: 'Checking',
+    checkingBody: 'Signed in. Homebridge picks up the new sign-in within a minute.',
+    checkingSlow: 'Homebridge hasn\'t picked it up yet. Restart Homebridge from Power Options.',
+    connected: 'Connected',
+    lastChecked: (relative) => `Last checked ${relative}`,
+    disconnect: 'Disconnect',
+    disconnectQuestion: 'Disconnect this account? The plugin will stop updating your generators until you connect again.',
+    keep: 'Keep',
+    reconnectBadge: 'Reconnect needed',
+    reconnectBody: 'Mobile Link signed this plugin out. This happens after a password change or if Generac revokes access. Sign in again to resume updates.',
+    reconnectAttention: 'The Attention needed sensor is on in HomeKit until you reconnect.',
+    reconnect: 'Reconnect',
+};
+/** SPEC 11.3 C. */
+export const CONNECT = {
+    email: 'Email',
+    emailPlaceholder: 'e.g. you@example.com',
+    password: 'Password',
+    passwordHelp: 'Used once to sign in. Not stored.',
+    signIn: 'Sign in',
+    cancel: 'Cancel',
+    signingIn: 'Signing in…',
+    wrongPassword: 'Mobile Link rejected that password. If you haven\'t reset it since Generac\'s security update on April 21, 2026, '
+        + 'reset it in the Mobile Link app, then try again.',
+    unknownEmail: 'Mobile Link doesn\'t recognize that email.',
+    network: 'Couldn\'t reach Mobile Link. Try again in a minute.',
+    codeTitle: 'Enter your code',
+    codeBodySms: 'Mobile Link texted a code to the phone on your account.',
+    codeBodyOtp: 'Enter the code from your authenticator app.',
+    codeBodyEmail: (email) => `Mobile Link emailed a code to ${email}.`,
+    codeSecondLine: 'Didn\'t get it? Cancel and sign in again.',
+    code: 'Code',
+    codePlaceholder: 'e.g. 123456',
+    continue: 'Continue',
+    wrongCode: 'That code didn\'t work. Check for a newer message and try again.',
+    tooMany: 'Too many attempts. Cancel and sign in again.',
+    expired: 'That sign-in timed out. Cancel and sign in again.',
+    unsupported: 'Your account uses a sign-in method this plugin can\'t complete. In the Mobile Link app, switch to text message '
+        + 'or an authenticator app, then try again.',
+};
+/** SPEC 11.3 D. */
+export const GENERATOR = {
+    maintenanceDue: 'Maintenance due',
+    serial: (serial) => `S/N ${serial}`,
+    ready: 'Ready to run',
+    running: 'Running',
+    exercising: 'Exercising',
+    fault: 'Fault',
+    notResponding: 'Not responding',
+    notRespondingNote: (time) => `Mobile Link hasn't heard from this generator since ${time}.`,
+    battery: 'Battery',
+    volts: (volts) => `${volts} V`,
+    low: 'Low',
+    fuel: 'Fuel',
+    percent: (percent) => `${percent}%`,
+    fuelHelp: 'Propane models only',
+    engineHours: 'Engine hours',
+    hours: (n) => `${n} h`,
+    exerciseTime: 'Exercise time',
+    weekly: (time) => `${time} weekly`,
+    lastExercise: 'Last exercise',
+    dateAt: (date, time) => `${date} at ${time}`,
+    lastSeen: 'Last seen',
+    rename: 'Rename',
+    name: 'Name',
+    saveName: 'Save name',
+    cancel: 'Cancel',
+    alsoPropane: 'Also on your account: Propane tank monitor (tank level support is coming).',
+    alsoEcobee: (name) => `Also on your account: ecobee thermostat "${name}" (already in HomeKit, skipped).`,
+};
+/** SPEC 11.3 E. */
+export const SETTINGS = {
+    name: 'Name',
+    pollIdle: 'Poll interval while idle (minutes)',
+    pollIdleHelp: 'Mobile Link updates every few minutes and limits how often you can check. Faster than this rarely helps.',
+    pollIdleError: 'Minimum is 2 minutes.',
+    pollActive: 'Poll interval while running or in fault (seconds)',
+    pollActiveHelp: 'Used while a generator is running, exercising, or reporting a problem.',
+    pollActiveError: 'Minimum is 60 seconds.',
+    batteryLow: 'Low battery threshold (volts)',
+    batteryLowHelp: 'A healthy starting battery on charge reads 13.4 to 13.8 V.',
+    batteryLowError: 'Enter volts with one decimal place, for example 12.0.',
+    faultOnStopped: 'Treat Stopped as a fault',
+    faultOnStoppedHelp: 'Stopped means the control switch is in OFF and the generator won\'t start during an outage.',
+    faultOnDisconnected: 'Treat a lost connection as a fault',
+    faultOnDisconnectedHelp: 'Off by default. Wi-Fi drops are common and the sensors already show Not responding.',
+    attentionSensor: 'Attention needed sensor',
+    attentionSensorHelp: 'Adds an occupancy sensor to HomeKit that turns on when the plugin needs you to reconnect.',
+    exerciseSensor: 'Exercising sensor',
+    exerciseSensorHelp: 'Adds a sensor that opens while the weekly exercise runs, or when Mobile Link reports one finished. '
+        + 'Use it to confirm the generator exercised this week.',
+    exerciseTime: 'Exercise time',
+    exerciseTimeHelp: 'When your generator\'s weekly exercise starts. Prefilled from Mobile Link; correct it if your unit starts at a different time. '
+        + 'The plugin checks more often around this time every day.',
+    exerciseTimePlaceholder: 'e.g. 10:00',
+    exerciseTimeError: 'Enter a time as HH:MM, for example 10:00.',
+    exerciseHold: 'Exercise hold (minutes)',
+    exerciseHoldHelp: 'How long the Exercising sensor stays open after an exercise is detected.',
+    exerciseHoldError: 'Minimum is 1 minute.',
+    debug: 'Debug logging',
+    debugHelp: 'Verbose logging. Your password is never logged, even with this on.',
+    resetLines: [
+        'Signs out of Mobile Link and removes the saved sign-in.',
+        'Removes every generator and its sensors from the Home app.',
+        'Clears all settings on this page.',
+    ],
+};
+/** Shell strings (SPEC 11.3 F): the disclosure, the Reset dialog, the password toggle, the credit footer and relative times. */
+export const SHELL = {
+    advanced: 'Advanced',
+    reset: 'Reset plugin to fresh install',
+    resetTitle: 'Reset plugin to fresh install?',
+    resetPrompt: 'Type RESET to confirm.',
+    resetConfirm: 'Confirm',
+    resetCancel: 'Cancel',
+    resetDone: 'Signed out and reset. Click Save, then restart Homebridge.',
+    show: 'Show',
+    hide: 'Hide',
+    required: (label) => `${label} is required.`,
+    loadFailed: 'Could not load the configuration.',
+    updateFailed: 'Could not update the configuration.',
+};
+export const FOOTER = {
+    name: 'Generac for Homebridge',
+    madeBy: 'Made by Alex Rodriguez',
+    site: 'alex-rodriguez.com',
+    siteUrl: 'https://alex-rodriguez.com/?ref=generac',
+    issues: 'Report an issue',
+    issuesUrl: 'https://github.com/arodbuilds/homebridge-generac/issues',
+};
+export const RELATIVE = {
+    justNow: 'just now',
+    minutes: (n) => (n === 1 ? '1 minute ago' : `${n} minutes ago`),
+    hours: (n) => (n === 1 ? '1 hour ago' : `${n} hours ago`),
+    days: (n) => (n === 1 ? '1 day ago' : `${n} days ago`),
+};

package/homebridge-ui/public/js/dom.js

@@ -0,0 +1,247 @@
+/**
+ * Tiny DOM helpers on the shell's field and button anatomy (homebridge-notify-switch homebridge-ui/src/dom.ts, the
+ * pieces this page needs). The UI is plain HTML built with these; Bootstrap 5 classes come from the Homebridge
+ * UI, which injects its stylesheet and theme into the settings iframe.
+ */
+import { SHELL } from './copy.js';
+export function append(parent, ...children) {
+    for (const child of children) {
+        if (child === null || child === undefined || child === false) {
+            continue;
+        }
+        parent.appendChild(typeof child === 'string' ? document.createTextNode(child) : child);
+    }
+}
+export function el(tag, attrs = {}, ...children) {
+    const node = document.createElement(tag);
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined || value === false) {
+            continue;
+        }
+        if (key === 'class') {
+            node.className = String(value);
+        }
+        else if (value === true) {
+            node.setAttribute(key, '');
+        }
+        else {
+            node.setAttribute(key, value);
+        }
+    }
+    append(node, ...children);
+    return node;
+}
+export function clear(node) {
+    while (node.firstChild) {
+        node.removeChild(node.firstChild);
+    }
+}
+let idCounter = 0;
+export function uniqueId(prefix = 'f') {
+    idCounter += 1;
+    return `${prefix}-${idCounter}`;
+}
+/** One line of field help. Carries `ns-help` like the shell so a help toggle could collapse it. */
+export function helpText(text, extra = '') {
+    return el('div', { class: `form-text ns-help${extra ? ` ${extra}` : ''}` }, text);
+}
+function wrapField(id, label, control, opts, invalidTarget) {
+    const star = opts.required ? el('span', { class: 'text-danger ms-1', 'aria-hidden': 'true' }, '*') : null;
+    return el('div', { class: 'mb-3', 'data-path': opts.path, 'data-invalid-target': invalidTarget ? 'group' : undefined }, el('label', { class: 'form-label', for: id }, label, star), control, opts.help ? helpText(opts.help) : null, el('div', { class: 'invalid-feedback' }));
+}
+/** A labelled input with optional help text, calling `onChange` with the new string on every input event. */
+export function textField(label, value, onChange, opts = {}) {
+    const id = uniqueId();
+    const input = el('input', {
+        id,
+        class: `form-control${opts.monospace ? ' font-monospace' : ''}`,
+        type: opts.type ?? 'text',
+        value,
+        placeholder: opts.placeholder,
+        autocomplete: opts.autocomplete ?? 'off',
+        inputmode: opts.inputmode,
+        spellcheck: 'false',
+    });
+    input.addEventListener('input', () => onChange(input.value));
+    return wrapField(id, label, input, opts);
+}
+/** A number input; `onChange` receives the parsed number or NaN. With `format`, the value is shown formatted on load and after blur. */
+export function numberField(label, value, onChange, opts = {}) {
+    const id = uniqueId();
+    const shown = (v) => (Number.isFinite(v) ? opts.format?.(v) ?? String(v) : '');
+    const input = el('input', {
+        id, class: 'form-control', type: 'number', value: shown(value), inputmode: opts.step ? 'decimal' : 'numeric',
+        min: opts.min !== undefined ? String(opts.min) : undefined, max: opts.max !== undefined ? String(opts.max) : undefined, step: opts.step ?? '1',
+    });
+    const parse = () => (input.value.trim() === '' ? Number.NaN : Number(input.value));
+    input.addEventListener('input', () => onChange(parse()));
+    if (opts.format) {
+        input.addEventListener('blur', () => {
+            const formatted = shown(parse());
+            if (formatted && formatted !== input.value) {
+                input.value = formatted;
+            }
+        });
+    }
+    return wrapField(id, label, input, opts);
+}
+/**
+ * A password input with a Show/Hide toggle. The value is never echoed anywhere but the input itself.
+ * `autocomplete` is `new-password` because browsers ignore `off` on password inputs and would offer the
+ * saved Homebridge login. The toggle only flips `type`; the value is untouched.
+ */
+export function passwordField(label, value, onChange, opts = {}) {
+    const id = uniqueId();
+    const input = el('input', { id, class: 'form-control font-monospace', type: 'password', value, autocomplete: 'new-password', spellcheck: 'false' });
+    input.addEventListener('input', () => onChange(input.value));
+    const toggle = el('button', { class: 'btn btn-outline-secondary', type: 'button', 'aria-label': `${SHELL.show} ${label}` }, SHELL.show);
+    toggle.addEventListener('click', () => {
+        const reveal = input.type === 'password';
+        input.type = reveal ? 'text' : 'password';
+        toggle.textContent = reveal ? SHELL.hide : SHELL.show;
+        toggle.setAttribute('aria-label', `${reveal ? SHELL.hide : SHELL.show} ${label}`);
+    });
+    const group = el('div', { class: 'input-group' }, input, toggle);
+    return wrapField(id, label, group, opts, input);
+}
+export function checkboxField(label, checked, onChange, opts = {}) {
+    const id = uniqueId();
+    const input = el('input', { id, class: 'form-check-input', type: 'checkbox' });
+    input.checked = checked;
+    input.addEventListener('change', () => onChange(input.checked));
+    return el('div', { class: 'form-check mb-3', 'data-path': opts.path }, input, el('label', { class: 'form-check-label', for: id }, label), opts.help ? helpText(opts.help) : null, el('div', { class: 'invalid-feedback' }));
+}
+export function button(label, onClick, cls = 'btn btn-outline-primary btn-sm') {
+    const node = el('button', { type: 'button', class: cls }, label);
+    node.addEventListener('click', onClick);
+    return node;
+}
+export function paragraph(text, cls = 'section-copy') {
+    return el('p', { class: cls }, text);
+}
+/** The one 38px primary button of a section (Connect, Reconnect, Sign in, Continue). */
+export function primaryButton(label, onClick) {
+    return button(label, onClick, 'btn btn-primary ns-section-add');
+}
+/** A link-style (text) button: no border or background, for Cancel, Keep and Disconnect. */
+export function linkButton(label, onClick, extra = '') {
+    return button(label, onClick, `btn btn-link btn-sm p-0 ns-link-button${extra ? ` ${extra}` : ''}`);
+}
+/** A red text button: Reset only. */
+export function dangerLinkButton(label, onClick) {
+    return linkButton(label, onClick, 'text-danger ns-danger-link');
+}
+/** An outlined secondary 31px button (the Unsupported factor Cancel). */
+export function outlineButton(label, onClick, extra = '') {
+    return button(label, onClick, `btn btn-outline-secondary btn-sm${extra ? ` ${extra}` : ''}`);
+}
+/** The card footer's primary action (Rename): an outlined, link-coloured 31px button. */
+export function footerAction(label, onClick) {
+    return button(label, onClick, 'btn btn-outline-primary btn-sm ns-footer-action');
+}
+/** A cell of the 12-column grid: `span` columns wide, full width below 600px. */
+export function gridCell(span, ...children) {
+    return el('div', { class: `ns-span-${span}` }, ...children);
+}
+/** The 12-column grid with its 8px column gap; `cells` come from `gridCell`. */
+export function grid(...cells) {
+    return el('div', { class: 'ns-grid' }, ...cells);
+}
+/** A collapsed disclosure ("Advanced"). */
+export function disclosure(summary, body, opts = {}) {
+    const details = el('details', { class: `ns-advanced${opts.cls ? ` ${opts.cls}` : ''}` }, el('summary', { class: 'ns-secondary small' }, summary), el('div', { class: 'mt-2' }, ...body));
+    if (opts.open) {
+        details.open = true;
+    }
+    return details;
+}
+/** A toned status box (a Connect error). */
+export function statusBox(kind, message) {
+    return el('div', { class: `status-box alert alert-${kind} py-2 px-3 mb-3`, role: 'status' }, message);
+}
+/**
+ * Brings a control that just opened into view. The page sits in an iframe the host sizes to the content, so a
+ * `scrollIntoView` here scrolls the host's modal (same-origin). The host learns the new height a moment after the
+ * page grows (its ResizeObserver posts it to the parent), so the call is made now and once more after that.
+ */
+export function reveal(node) {
+    const scroll = () => {
+        try {
+            node.scrollIntoView({ block: 'center' });
+        }
+        catch {
+            // An old browser without the options form: leave the page where it is.
+        }
+    };
+    scroll();
+    window.setTimeout(scroll, 250);
+}
+/**
+ * In-place confirmation: clicking `start` replaces it with the question, a confirm button and a text Cancel
+ * button. Escape or Cancel restores the original button.
+ */
+export function inlineConfirm(opts) {
+    const control = el('span', { class: `d-inline-flex flex-wrap align-items-center gap-2 ns-inline-confirm${opts.cls ? ` ${opts.cls}` : ''}` });
+    let onKey = () => undefined;
+    const reset = () => {
+        document.removeEventListener('keydown', onKey);
+        clear(control);
+        control.appendChild(opts.start);
+        opts.onOpen?.(false);
+    };
+    onKey = (event) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            reset();
+        }
+    };
+    const show = (clicked) => {
+        clear(control);
+        control.appendChild(el('span', { class: 'small ns-confirm-question' }, opts.question));
+        const confirm = button(opts.confirmLabel, () => {
+            reset();
+            opts.onConfirm();
+        }, opts.confirmClass);
+        control.appendChild(confirm);
+        control.appendChild(linkButton(opts.cancelLabel, reset));
+        document.addEventListener('keydown', onKey);
+        if (clicked) {
+            opts.onOpen?.(true);
+            confirm.focus();
+            reveal(control);
+        }
+    };
+    opts.start.addEventListener('click', () => show(true));
+    if (opts.open) {
+        show(false);
+    }
+    else {
+        control.appendChild(opts.start);
+    }
+    return control;
+}
+/**
+ * A dialog in the page flow (the Reset dialog), drawn where it is opened rather than over the page: a fixed
+ * overlay would pin to the iframe's own top, off-screen when the opener sits at the bottom of a scrolled host
+ * modal. Escape closes it; `onClose` runs on every close, including the caller's.
+ */
+export function inlineDialog(opts) {
+    const dialog = el('div', { class: 'ns-inline-dialog', role: 'dialog', 'aria-label': opts.title });
+    let onKey = () => undefined;
+    const close = () => {
+        document.removeEventListener('keydown', onKey);
+        dialog.remove();
+        opts.onClose?.();
+    };
+    onKey = (event) => {
+        if (event.key === 'Escape') {
+            event.preventDefault();
+            close();
+        }
+    };
+    document.addEventListener('keydown', onKey);
+    dialog.appendChild(el('div', { class: 'ns-inline-dialog-title fw-semibold' }, opts.title));
+    dialog.appendChild(el('div', { class: 'ns-inline-dialog-body' }, opts.body));
+    dialog.appendChild(el('div', { class: 'ns-inline-dialog-actions' }, ...opts.actions));
+    return { el: dialog, close };
+}

package/homebridge-ui/public/js/footer.js

@@ -0,0 +1,26 @@
+import { FOOTER } from './copy.js';
+import { el } from './dom.js';
+import { renderMark } from './mark.js';
+/**
+ * Version and credit footer (SPEC section 11.1, item 6): the last element on the page, one line of secondary
+ * text. The version arrives with /status. Both links open in a new tab; the site link
+ * carries `?ref=generac` and nothing else is tracked.
+ */
+const MARK_SIZE = 20;
+function outLink(text, href) {
+    return el('a', { href, target: '_blank', rel: 'noopener noreferrer' }, text);
+}
+function item(...children) {
+    return el('span', { class: 'ns-footer-item' }, ...children);
+}
+export function renderFooter() {
+    const label = document.createTextNode(FOOTER.name);
+    const separator = () => ' · ';
+    const footer = el('footer', { class: 'ns-footer form-text' }, item(el('span', { class: 'ns-mark-label' }, renderMark(MARK_SIZE), label)), separator(), item(FOOTER.madeBy), separator(), item(outLink(FOOTER.site, FOOTER.siteUrl)), separator(), item(outLink(FOOTER.issues, FOOTER.issuesUrl)));
+    return {
+        el: footer,
+        setVersion(version) {
+            label.textContent = version ? `${FOOTER.name} v${version}` : FOOTER.name;
+        },
+    };
+}

package/homebridge-ui/public/js/format.js

@@ -0,0 +1,62 @@
+/**
+ * Times as the page shows them, in the browser's locale and time zone: 12-hour times, US-style dates (SPEC
+ * writing style) and the relative times of the account and generator cards.
+ */
+import { RELATIVE } from './copy.js';
+export function parseDate(value) {
+    if (!value) {
+        return null;
+    }
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/** "3:15 PM". */
+export function formatTime(d) {
+    return d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' });
+}
+/** "September 12, 2026". */
+export function formatDate(d) {
+    return d.toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+}
+/** "3:15 PM" today, else "September 12, 2026 at 3:15 PM". */
+export function formatTimeOrDate(d, now = new Date()) {
+    const sameDay = d.getFullYear() === now.getFullYear() && d.getMonth() === now.getMonth() && d.getDate() === now.getDate();
+    return sameDay ? formatTime(d) : `${formatDate(d)} at ${formatTime(d)}`;
+}
+/** "just now", "2 minutes ago", "3 hours ago", "2 days ago". */
+export function relativeTime(d, now = new Date()) {
+    const seconds = Math.max(0, Math.round((now.getTime() - d.getTime()) / 1000));
+    if (seconds < 45) {
+        return RELATIVE.justNow;
+    }
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) {
+        return RELATIVE.minutes(Math.max(1, minutes));
+    }
+    const hours = Math.round(minutes / 60);
+    if (hours < 24) {
+        return RELATIVE.hours(hours);
+    }
+    return RELATIVE.days(Math.round(hours / 24));
+}
+/** "10:00" to "10:00 AM"; null when the value is not HH:MM. */
+export function hhmmTo12h(value) {
+    if (!value) {
+        return null;
+    }
+    const m = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!m) {
+        return null;
+    }
+    const h = Number(m[1]);
+    const min = Number(m[2]);
+    if (h > 23 || min > 59) {
+        return null;
+    }
+    const h12 = h % 12 === 0 ? 12 : h % 12;
+    return `${h12}:${String(min).padStart(2, '0')} ${h < 12 ? 'AM' : 'PM'}`;
+}
+/** A number with at most one decimal, for volts. */
+export function formatVolts(v) {
+    return (Math.round(v * 10) / 10).toFixed(1);
+}