gm_wrapper.js

/**
 * GM Wrapper for Backward Compatibility
 * 
 * This script provides a bridge for legacy `GM_*` API calls to use the modern `GM.*` API introduced in
 * newer userscript managers. It ensures backward compatibility for older scripts without requiring modifications.
 * 
 * The wrapper is lightweight, modular, and maintains error-handling integrity.
 * 
 * Supported Legacy Methods:
 * - GM_addStyle
 * - GM_getValue
 * - GM_setValue
 * - GM_deleteValue
 * - GM_listValues
 * - GM_openInTab
 * - GM_notification
 * - GM_setClipboard
 * - GM_xmlhttpRequest
 * 
 * Notes:
 * - Methods that do not exist in `GM.*` (e.g., GM_log) are intentionally omitted.
 */

(function() {
    'use strict';

    // Check for the presence of GM.* API; exit if unavailable
    if (typeof GM === 'undefined' || typeof GM.info === 'undefined') {
        console.error('GM.* API is not supported in this environment.');
        return;
    }

    /**
     * GM_addStyle
     * Adds custom CSS styles to the current page.
     *
     * @param {string} css - The CSS string to be added.
     */
    window.GM_addStyle = function(css) {
        if (typeof GM.addStyle === 'function') {
            GM.addStyle(css);
        } else {
            const style = document.createElement('style');
            style.textContent = css;
            document.head.appendChild(style);
        }
    };

    /**
     * GM_getValue
     * Retrieves a value from the script's persistent storage.
     *
     * @param {string} key - The key to retrieve.
     * @param {*} defaultValue - The default value if the key does not exist.
     * @returns {Promise<*>} - A Promise that resolves to the stored value.
     */
    window.GM_getValue = async function(key, defaultValue) {
        return await GM.getValue(key, defaultValue);
    };

    /**
     * GM_setValue
     * Stores a value in the script's persistent storage.
     *
     * @param {string} key - The key to set.
     * @param {*} value - The value to store.
     * @returns {Promise<void>} - A Promise that resolves when the value is stored.
     */
    window.GM_setValue = async function(key, value) {
        await GM.setValue(key, value);
    };

    /**
     * GM_deleteValue
     * Deletes a value from the script's persistent storage.
     *
     * @param {string} key - The key to delete.
     * @returns {Promise<void>} - A Promise that resolves when the key is deleted.
     */
    window.GM_deleteValue = async function(key) {
        await GM.deleteValue(key);
    };

    /**
     * GM_listValues
     * Lists all keys in the script's persistent storage.
     *
     * @returns {Promise<string[]>} - A Promise that resolves to an array of keys.
     */
    window.GM_listValues = async function() {
        return await GM.listValues();
    };

    /**
     * GM_openInTab
     * Opens a new browser tab with the specified URL.
     *
     * @param {string} url - The URL to open.
     * @param {boolean} [openInBackground=false] - Whether to open the tab in the background.
     * @returns {Promise<object>} - A Promise that resolves to the tab object.
     */
    window.GM_openInTab = async function(url, openInBackground = false) {
        return await GM.openInTab(url, openInBackground);
    };

    /**
     * GM_notification
     * Displays a desktop notification.
     *
     * @param {string|object} details - The notification text or an object with notification options.
     * @param {string} [title] - The notification title (if `details` is a string).
     */
    window.GM_notification = function(details, title) {
        if (typeof GM.notification === 'function') {
            GM.notification(details, title);
        } else {
            const notificationDetails = typeof details === 'string' ? { text: details, title: title } : details;
            GM.notification(notificationDetails);
        }
    };

    /**
     * GM_setClipboard
     * Copies text to the clipboard.
     *
     * @param {string} data - The data to copy.
     * @param {string} [type='text/plain'] - The MIME type of the data.
     */
    window.GM_setClipboard = function(data, type = 'text/plain') {
        GM.setClipboard(data, type);
    };

    /**
     * GM_xmlhttpRequest
     * Makes an HTTP request.
     *
     * @param {object} details - The details of the HTTP request.
     * @returns {Promise<object>} - A Promise that resolves to the response object.
     */
    window.GM_xmlhttpRequest = async function(details) {
        return await new Promise((resolve, reject) => {
            details.onload = resolve;
            details.onerror = reject;
            GM.xmlHttpRequest(details);
        });
    };
})();