☰

Jira issue page updated notification

Give Jira issue page an update button, in the top navigation bar, when the issue is updated while the page is shown. Also update the title.

// ==UserScript==
// @name        Jira issue page updated notification
// @namespace   https://greasyfork.org/users/1047370
// @description Give Jira issue page an update button, in the top navigation bar, when the issue is updated while the page is shown.  Also update the title.
// @author      Marnix Klooster <[email protected]>
// @copyright   public domain
// @license     public domain
// @version     0.10
// @homepage    https://greasyfork.org/scripts/462479
// @include     /^https?://(jira\.[^/]*|[^/]*\.atlassian\.net)/(browse|projects/[^/]+/issues)//
// @require     https://cdn.jsdelivr.net/npm/[email protected]/build/global/luxon.min.js
// @grant       none
// ==/UserScript==

/// TODO list
///
///  * Bug report in Edge: After the button shows, and it has been clicked, then using browser 'back',
///    which goes from a URL ending in a '#' to a URL without it,
///    results in the 'refresh icon' shown again in the tab title bar.  (Edge bug?)
///
///  * Also support URLs like https://jira.example.com/secure/RapidBoard.jspa?...&selectedIssue=MYPROJ-98765&...
///
///  * Usability issue.  On 'Jira issue in search result' .../browse/SOMEPROJ-12345?jql=... pages,
///    the top navigation bar scrolls out of view when scrolling down,
///    making the 'update' button inaccessible, which is not helpful.
///
///    Consider moving the button into the issue header (<header id="stalker" class="issue-header"/>),
///    either in the primary toolbar on the left (`<div class="aui-toolbar2-primary">`)
///    or in the secondary toolbar on the right (`<div class="aui-toolbar2-secondary">`).
///
///    EXCEPT that on .../projects/SOMEPROJ/issues/... pages, it is the other way around:
///    There the top navigation bar remains visible, and the issue header scrolls out of view...
///
///    Options:
///     - Do nothing, the 'search result' user will see the 'refresh' circular arrow in the title,
///       and that triggers them to scroll up.
///     - Show two buttons always, both in top bar and in issue header.  Ugly.
///     - If the top bar button scrolls out of view, then show that button e.g. floating.
///       (Or add a second button in the issue header?)
///
///  * Try to get rid of `href="#"`, since the URL-changing when clicking the button is not nice.
///
///  * Perhaps: Also show the _type_ of changes, in the 'updated' button's tooltip.
///    (It seems this needs both its ...?field=&expand=changelog
///    and the issue's full .../comment list, and perhaps more.)
///      If this is built, it also would make sense to keep watching for issue updates,
///    and keep updating the tooltip (and perhaps the time, see other TODO item).
///
///    Additionally, if (at least) the Description changed, make the button red/bold/highlighted
///    since that other Description change will be lost.
///    (And/or make that a separate userscript, that only looks at Description collisions.)
///
///  * Idea: Switch to relative times, e.g. as follows:
///
///       changed 10 min. — 52 sec. ago
///
///    (using `DateTime.toRelative()` twice) or
///
///       changed yesterday 4:30 PM — 7:42 PM GMT+2
///
///    (using `DateTime.toRelativeCalendar()` and `DateTime.toLocaleString(DateTime.TIME_...)` twice),
///    together with the following algorithm to combine two strings into an 'interval string':
///     - Split start and end time string using `s.split(/\s+(?!(?:AM|PM))\b/)`, resulting in two arrays.
///     - Show the start, but leave out the suffix common to start and end.
///     - Show `"—"` (that is, an `&mdash`).
///     - Show the end, but leave out the prefix common to start and end.
///
///    If this is done, try hard to update the button also in case of a connection error.
///    (The button could even be made a different color in that case...)
///
///  * Bug/limitation: From a query result page (https://jira.infor.com/issues/?jql=...)
///    clicking on a specific issue, the page is updated 'in place',
///    so even though the address bar URL changes, this userscript is not activated.
///    See if there is a way to fix that.
///
///  * Robustness in case `aui-nav` element does not exist.
///
///  * Perhaps: Wait longer after an error response, to reduce server load?

/// END of TODO list


"use strict";

/// Configuration settings
/// (also look at @include and @match in the manifest above,
/// which you can usually override in your userscript browser extension configuration)

/// Setting the following too high will overload the Jira server;
/// setting it too low will make this userscript less useful.
var timeBetweenChecksInSeconds = 10;

/// END of Configuration settings


/// Helper functions

/// From https://stackoverflow.com/a/35385518/223837:
/// Construct an DOM element from the given HTML string.
/// The caller must ensure no injection occurs, e.g. using `stringToHTML()` below.
function htmlToElement(html) {
    var template = document.createElement('template');
    html = html.trim(); // Never return a text node of whitespace as the result
    template.innerHTML = html;
    return template.content.firstChild;
}

/// From https://stackoverflow.com/a/22706073/223837:
/// Convert a string to the equivalent HTML source code.
function stringToHTML(str){
    return new Option(str).innerHTML;
}

/// END of Helper functions


// Documentation about the Jira REST API that is used here can be found at
// https://docs.atlassian.com/software/jira/docs/api/REST/latest/
// (currently https://docs.atlassian.com/software/jira/docs/api/REST/9.7.0/),
// specifically
//
// - https://docs.atlassian.com/software/jira/docs/api/REST/latest/#api/2/issue-getIssue
// - https://docs.atlassian.com/software/jira/docs/api/REST/latest/#api/2/issue-getComments
//
// Documentation about the Javascript JIRA object's API doesn't seem to exist.
// There are mostly fragments floating around in forum questions and answers.

(function () {

    /// 'global' variables
    var theInterval = null;
    var issueFirstUpdatedAfterPage = null;

    function start() {
        if (theInterval) {
            console.log(`SOMETHING WENT WRONG.  Ignoring this call to start().`);
            return;
        }
        console.log(`STARTING regular check for issue updates`);
        theInterval = setInterval(checkForUpdates, timeBetweenChecksInSeconds * 1000);
    }

    /// (Note that this function is currently not used.)
    function stop() {
        if (!theInterval) {
            console.log(`SOMETHING WENT WRONG.  Ignoring this call to stop().`);
            return;
        }
        console.log(`STOPPING regular check for issue updates`);
        clearInterval(theInterval);
        theInterval = null;
    }

    function getPageLastUpdated() {
        // The 'best' implementation for this would be
        // ```
        // luxon.DateTime.fromISO(document.getElementById("updated-val").getElementsByTagName("time")[0].getAttribute("datetime"));
        // ```
        // but because of Jira 9 bug https://jira.atlassian.com/browse/JRASERVER-76257 (at least up until 9.10.1),
        // instead we take the latest <... class="livestamp" datetime="..."> we can find on the page.
        return luxon.DateTime.max(...Array.from(document.querySelectorAll('.livestamp[datetime]')).map(
            (t) => luxon.DateTime.fromISO(t.getAttribute("datetime"))
        ));
    }

    function checkForUpdates() {
        var issueNumber = JIRA.Issue.getIssueKey();
        if (issueNumber == null) {
            console.log(`No issue number found (yet?)...  trying again in a little while`);
            return;
        }

        console.log(`Checking whether issue ${issueNumber} has been recently updated`);
        fetch(new Request(`/rest/api/latest/issue/${issueNumber}?fields=updated`, {
            headers: {'Content-Type': 'application/json'}
        })).then((response) => {
            // technical handling of the response
            if (!response.ok) {
                console.log(`Something went wrong checking for updates of issue ${issueNumber}, will retry in a little while: ${response.statusText}`);
                return Promise.reject(response); // not handled in any way, no need
            }
            return response.json();
        }).then((responseJSON) => {
            // functional handling of the response

            // 'last updated' according to the Jira REST API
            var issueLastUpdated = luxon.DateTime.fromISO(responseJSON.fields.updated);
            // 'last updated' according to this page; could perhaps also be read via the JIRA object? could not find any documentation
            var pageLastUpdated = getPageLastUpdated();
            console.log(`Issue ${issueNumber} was last updated ${issueLastUpdated}`);
            console.log(`This page says its data is from ${pageLastUpdated}' (+/- 1 second)`);

            // remove any UI changes, preparing to make them again below if necessary.
            var updateButtonElement = document.getElementById('marnix_update_page_button');
            if (updateButtonElement) {
                // below always add a fresh button, so that we have the updated text
                updateButtonElement.remove();
            }
            const prefix = '\u21BB ';
            if (document.title.startsWith(prefix)) {
                document.title = document.title.substring(prefix.length);
            }

            if (pageLastUpdated.toMillis() + 1000 < issueLastUpdated.toMillis()) { // + 1000 since 'page last updated' has no millisecond information
                // issue was updated after the page information was refreshed

                if (!issueFirstUpdatedAfterPage) {
                    issueFirstUpdatedAfterPage = issueLastUpdated;
                }

                var issueLastUpdatedText = luxon.Interval.fromDateTimes(
                    issueFirstUpdatedAfterPage, issueLastUpdated).toLocaleString(luxon.DateTime.TIME_WITH_SHORT_OFFSET, {});
                console.log(`Concluding that issue was updated after last page refresh, just now at ${issueLastUpdatedText}: ensuring update button and updated title`);

                // We put the button as the last in the <ul class="aui-nav"> top navigation bar.
                // (The button is the same as the 'Create' button; `href="#"` is needed for the correct hover color.)
                updateButtonElement = htmlToElement(`
                            <li id="marnix_update_page_button">
                                <a
                                    href="#"
                                    class="aui-button aui-button-primary aui-style"
                                    title="Update page"
                                   >Update (changed ${stringToHTML(issueLastUpdatedText)})</a>
                            </li>
                        `);
                updateButtonElement.addEventListener("click", updateThisPage);
                document.getElementsByClassName("aui-nav")[0].appendChild(updateButtonElement);

                // prepend 'Clockwise Open Circle Arrow' character
                document.title = `${prefix}${document.title}`;

                return;
            }

            console.log(`Concluding that there was no recent issue ${issueNumber} update, will check again in a little while.`);
        });
    }

    function updateThisPage() {
        console.log(`Let this page update its information (which also reverts the title)`);
        JIRA.trigger(JIRA.Events.REFRESH_ISSUE_PAGE, [JIRA.Issue.getIssueId()]);
        // this event triggers an update, which raises an ISSUE_REFRESHED event,
        // which is caught by the event handler below, which will re-enable the regular check for issue updates
        // (or it triggers a full page reload, sometimes, it seems, e.g. if there is a network issue)
    }

    JIRA.bind(JIRA.Events.ISSUE_REFRESHED, function (e, context) {
        console.log(`Something triggered a refresh of this page`);

        if (!theInterval) {
            console.log(`We will start to look for issue updates again in a little while`);
            start();
        }

        var updateButtonElement = document.getElementById('marnix_update_page_button')
        if (updateButtonElement) {
            console.log(`We can remove the update button again`);
            updateButtonElement.remove();

            issueFirstUpdatedAfterPage = null;

            // no need to revert the document.title, the refresh that just happened has already done that
        }
    });

    // No need to updateThisPage() on JIRA.Events.INLINE_EDIT_SAVE_COMPLETE,
    // because every inline edit also updates the `Updated:` (id="updated-val") field,
    // and we already trigger on that.

    start();
})();