Capture.js

/**
 * GPII Capture Component
 *
 * Copyright 2020 Raising the Floor - International
 *
 * Licensed under the New BSD license. You may not use this file except in
 * compliance with this License.
 *
 * You may obtain a copy of the License at
 * https://github.com/gpii/universal/LICENSE.txt
 */
"use strict";

var fluid = require("infusion"),
    gpii = fluid.registerNamespace("gpii");

fluid.defaults("gpii.flowManager.capture", {
    gradeNames: ["fluid.component"],
    events: {
        // Pseudoevents for transforming promise chains to fetch the solutions on the current device
        // and capture the settings for the device.
        onSolutionsForCurrentDevice: null,
        onCaptureSettingsForCurrentDevice: null
    },
    listeners: {
        // Begin declaration of Promise Chain for onSolutionsForCurrentDevice
        "onSolutionsForCurrentDevice.getDeviceContextPromise": {
            funcName: "gpii.lifecycleManager.getDeviceContextPromise",
            args: ["{flowManager}.deviceReporter"],
            priority: "first"
        },
        "onSolutionsForCurrentDevice.getSolutions": {
            funcName: "gpii.flowManager.getSolutions",
            args: [ "{flowManager}.solutionsRegistryDataSource", "{arguments}.0"],
            priority: "after:getDeviceContextPromise"
        },
        "onSolutionsForCurrentDevice.solutionsRegistryEntriesToPromise": {
            funcName: "fluid.toPromise",
            args: ["{arguments}.0.solutionsRegistryEntries"],
            priority: "after:getSolutions"
        },
        // Begin declaration of Promise Chain for onCaptureSettingsForCurrentDevice
        "onCaptureSettingsForCurrentDevice.getInstalledSolutionsForCurrentDevice": {
            func: "{that}.getInstalledSolutionsForCurrentDevice",
            priority: "first"
        },
        "onCaptureSettingsForCurrentDevice.captureSystemSettings": {
            funcName: "gpii.flowManager.capture.captureSystemSettings",
            args: ["{lifecycleManager}.read", "{arguments}.0", "{arguments}.1"], // solutionsRegistryEntries, options
            priority: "after:getInstalledSolutionsForCurrentDevice"
        },
        "onCaptureSettingsForCurrentDevice.formatRawCapturedSettings": {
            func: "gpii.flowManager.capture.formatRawCapturedSettings",
            args: ["{arguments}.0"],
            priority: "after:captureSystemSettings"
        }
    },
    invokers: {
        getInstalledSolutionsForCurrentDevice: {
            funcName: "fluid.promise.fireTransformEvent",
            args: ["{that}.events.onSolutionsForCurrentDevice"]
        },
        getSystemSettingsCapture: {
            funcName: "fluid.promise.fireTransformEvent",
            args: ["{that}.events.onCaptureSettingsForCurrentDevice", null, "{arguments}.0"] // options
        }
    }
});

/**
 * Invoker `{gpii.flowManager.capture}.getInstalledSolutionsForCurrentDevice`
 *
 * @method
 * @name {gpii.flowManager.capture}.getInstalledSolutionsForCurrentDevice
 *
 * This invoker method will return the solution registry entries, in their usual json format,
 * that are available on the current device.
 *
 * @return {Promise} A promise resolved with an object of solutions registry entries available on the
 * current device. As with the solutions registry itself, these are keyed by the solution ID.
 */

/**
 * Invoker `{gpii.flowManager.capture}.getSystemSettingsCapture`
 *
 * @method
 * @name {gpii.flowManager.capture}.getSystemSettingsCapture
 *
 * This main API entry point for capturing settings from a system or computer. This captures
 * the actual settings on the device, so it assumed to be running in a local untrusted flow
 * manager.
 *
 * @param {Object} options - Options for this chain.
 * @param {Array} options.solutionsList - An array of solution IDs to filter by when
 * retreiving settings. If this option is not included, all available settings will be
 * returned. ex: `["com.microsoft.windows.mouseSettings", "com.freedomscientific.jaws"]`.
 * @return {Promise} A promise resolved with the payload of captured system settings.
 */

/**
 * Runs through all the solutions currently available on the system, pulls the current
 * setting for each supportedSetting and returns them in an object. Primary use case
 * is for backing Capture tools that would allow a user to set up their GPII profile
 * starting with the current settings for their applications on the local machine.
 *
 * @param {Function|gpii.lifecycleManager.read} readSettingsFunc - lifecycleManager.read (or suitable implementation),
 * that takes solution registry entries, reads their current values on the device, and returns a promise resolved to
 * them.
 * @param {Object} solutions - Solutions registry entries for solutions available on the current machine.
 * @param {Object} options - Extra options for processing.
 * @param {Array} options.solutionsList - If provided, only solutions in this list of `solutionsID`s will
 * be captured. Example:
 *
 * '''json
 * ["com.microsoft.windows.cursors", "com.freedomscientific.jaws"]
 * '''
 * @return {fluid.promise} Returns a promise resolving with the entire system settings capture.
 */
gpii.flowManager.capture.captureSystemSettings = function (readSettingsFunc, solutions, options) {
    var solutionsToFetch = fluid.copy(solutions);
    if (options.solutionsList) {
        fluid.remove_if(solutionsToFetch, function (solution, solutionID) {
            return !options.solutionsList.includes(solutionID);
        });
    }

    return readSettingsFunc(solutionsToFetch);
};

/**
 * The raw return payload from the capture promise sequence looks like:
 * '''json
 *       [
 *           {
 *               "fakemag1": [
 *                   {
 *                       "settings": {
 *                           "magnification": 2
 *                       }
 *                   }
 *               ]
 *           },
 *           {
 *               "fakemag1": [
 *                   {
 *                       "settings": {
 *                           "invert": true
 *                       }
 *                   }
 *               ]
 *           },
 *           {
 *               "fakemag2": [
 *                   {
 *                       "settings": {
 *                           "magnification": 2,
 *                           "invert": true
 *                       }
 *                   }
 *               ]
 *           }
 *       ]
 * '''
 *
 * and we want:
 * '''json
 *       {
 *           "fakemag1": {
 *               "magnification": 2,
 *               "invert": true
 *           },
 *           "fakemag2": {
 *               "magnification": 2,
 *               "invert": true
 *           }
 *       }
 * '''
 *
 * @param {Object} data - The raw captured data.
 * @return {Object} Returns a new payload with collapsed data, and multiple settings handler
 * results for the same solution merged together.
 */
gpii.flowManager.capture.formatRawCapturedSettings = function (data) {
    var togo = {};
    fluid.each(data, function (sequenceItem) {
        if (sequenceItem.isError) {
            fluid.log("Error capturing settings for: ", sequenceItem);
            return;
        }
        fluid.each(sequenceItem, function (item, key) {
            if (!togo[key]) {
                togo[key] = {};
            }
            fluid.each(fluid.get(item, [0, "settings"]), function (value, settingId) {
                togo[key][settingId] = value;
            });
        });
    });
    return togo;
};