package Torello.Browser.BrowserAPI;

import java.util.*;
import javax.json.*;
import javax.json.stream.*;
import java.io.*;

import java.lang.reflect.Method;
import java.lang.reflect.Parameter;
import java.util.function.Function;

import Torello.Browser.BrowserEvent;
import Torello.Browser.JavaScriptAPI.*;
import Torello.Browser.helper.*;

import Torello.Java.Additional.*;
import Torello.Java.JSON.*;

import static Torello.Java.JSON.JFlag.*;

import Torello.Java.StrCmpr;
import Torello.JavaDoc.StaticFunctional;
import Torello.JavaDoc.JDHeaderBackgroundImg;
import Torello.JavaDoc.Excuse;

/**
 * <SPAN CLASS=COPIEDJDK><B>This domain allows interacting with the browser to control PWAs.</B></SPAN>
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=CODE_GEN_NOTE>
 */
@StaticFunctional(Excused={"counter"}, Excuses={Excuse.CONFIGURATION})
@JDHeaderBackgroundImg(EmbedTagFileID="WOOD_PLANK_NOTE")
public class PWA
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Class Header Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    // No Pubic Constructors
    private PWA () { }

    // These two Vector's are used by all the "Methods" exported by this class.  java.lang.reflect
    // is used to generate the JSON String's.  It saves thousands of lines of Auto-Generated Code.
    private static final Map<String, Vector<String>>    parameterNames = new HashMap<>();
    private static final Map<String, Vector<Class<?>>>  parameterTypes = new HashMap<>();

    // Some Methods do not take any parameters - for instance all the "enable()" and "disable()"
    // I simply could not get ride of RAW-TYPES and UNCHECKED warnings... so there are now,
    // offically, two empty-vectors.  One for String's, and the other for Classes.

    private static final Vector<String>     EMPTY_VEC_STR = new Vector<>();
    private static final Vector<Class<?>>   EMPTY_VEC_CLASS = new Vector<>();

    static
    {
        for (Method m : PWA.class.getMethods())
        {
            // This doesn't work!  The parameter names are all "arg0" ... "argN"
            // It works for java.lang.reflect.Field, BUT NOT java.lang.reflect.Parameter!
            //
            // Vector<String> parameterNamesList = new Vector<>(); -- NOPE!

            Vector<Class<?>> parameterTypesList = new Vector<>();
        
            for (Parameter p : m.getParameters()) parameterTypesList.add(p.getType());

            parameterTypes.put(
                m.getName(),
                (parameterTypesList.size() > 0) ? parameterTypesList : EMPTY_VEC_CLASS
            );
        }
    }

    static
    {
        Vector<String> v = null;

        v = new Vector<String>(1);
        parameterNames.put("getOsAppState", v);
        Collections.addAll(v, new String[]
        { "manifestId", });

        v = new Vector<String>(2);
        parameterNames.put("install", v);
        Collections.addAll(v, new String[]
        { "manifestId", "installUrlOrBundleUrl", });

        v = new Vector<String>(1);
        parameterNames.put("uninstall", v);
        Collections.addAll(v, new String[]
        { "manifestId", });

        v = new Vector<String>(2);
        parameterNames.put("launch", v);
        Collections.addAll(v, new String[]
        { "manifestId", "url", });

        v = new Vector<String>(2);
        parameterNames.put("launchFilesInApp", v);
        Collections.addAll(v, new String[]
        { "manifestId", "files", });

        v = new Vector<String>(1);
        parameterNames.put("openCurrentPageInApp", v);
        Collections.addAll(v, new String[]
        { "manifestId", });

        v = new Vector<String>(3);
        parameterNames.put("changeAppUserSettings", v);
        Collections.addAll(v, new String[]
        { "manifestId", "linkCapturing", "displayMode", });
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Types - Static Inner Classes
    // ********************************************************************************************
    // ********************************************************************************************

    /** If user prefers opening the app in browser or an app window. */
    public static final String[] DisplayMode =
    { "standalone", "browser", };
    
    /**
     * The following types are the replica of
     * https://crsrc.org/c/chrome/browser/web_applications/proto/web_app_os_integration_state.proto;drc=9910d3be894c8f142c977ba1023f30a656bc13fc;l=67
     */
    public static class FileHandlerAccept
        extends BaseType
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { false, false, }; }
        
        /**
         * New name of the mimetype according to
         * https://www.iana.org/assignments/media-types/media-types.xhtml
         */
        public final String mediaType;
        
        /** <CODE>[No Description Provided by Google]</CODE> */
        public final String[] fileExtensions;
        
        /**
         * Constructor
         *
         * @param mediaType 
         * New name of the mimetype according to
         * https://www.iana.org/assignments/media-types/media-types.xhtml
         * 
         * @param fileExtensions -
         */
        public FileHandlerAccept(String mediaType, String[] fileExtensions)
        {
            // Exception-Check(s) to ensure that if any parameters which are not declared as
            // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
            
            if (mediaType == null)      THROWS.throwNPE("mediaType");
            if (fileExtensions == null) THROWS.throwNPE("fileExtensions");
            
            this.mediaType       = mediaType;
            this.fileExtensions  = fileExtensions;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'FileHandlerAccept'}.
         */
        public FileHandlerAccept (JsonObject jo)
        {
            this.mediaType       = ReadJSON.getString(jo, "mediaType", false, true);
            this.fileExtensions = (jo.getJsonArray("fileExtensions") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("fileExtensions"), null, 0).toArray(String[]::new);
        
        }
        
        
        /** Checks whether {@code 'this'} equals an input Java-{@code Object} */
        public boolean equals(Object other)
        {
            if (this == other)                       return true;
            if (other == null)                       return false;
            if (other.getClass() != this.getClass()) return false;
        
            FileHandlerAccept o = (FileHandlerAccept) other;
        
            return
                    Objects.equals(this.mediaType, o.mediaType)
                &&  Arrays.deepEquals(this.fileExtensions, o.fileExtensions);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.mediaType)
                +   Arrays.deepHashCode(this.fileExtensions);
        }
    }
    
    /** <CODE>[No Description Provided by Google]</CODE> */
    public static class FileHandler
        extends BaseType
        implements java.io.Serializable
    {
        /** For Object Serialization.  java.io.Serializable */
        protected static final long serialVersionUID = 1;
        
        public boolean[] optionals()
        { return new boolean[] { false, false, false, }; }
        
        /** <CODE>[No Description Provided by Google]</CODE> */
        public final String action;
        
        /** <CODE>[No Description Provided by Google]</CODE> */
        public final PWA.FileHandlerAccept[] accepts;
        
        /** <CODE>[No Description Provided by Google]</CODE> */
        public final String displayName;
        
        /**
         * Constructor
         *
         * @param action -
         * 
         * @param accepts -
         * 
         * @param displayName -
         */
        public FileHandler(String action, PWA.FileHandlerAccept[] accepts, String displayName)
        {
            // Exception-Check(s) to ensure that if any parameters which are not declared as
            // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
            
            if (action == null)      THROWS.throwNPE("action");
            if (accepts == null)     THROWS.throwNPE("accepts");
            if (displayName == null) THROWS.throwNPE("displayName");
            
            this.action       = action;
            this.accepts      = accepts;
            this.displayName  = displayName;
        }
        
        /**
         * JSON Object Constructor
         * @param jo A Json-Object having data about an instance of {@code 'FileHandler'}.
         */
        public FileHandler (JsonObject jo)
        {
            this.action       = ReadJSON.getString(jo, "action", false, true);
            this.accepts = (jo.getJsonArray("accepts") == null)
                ? null
                : RJArrIntoStream.objArr(jo.getJsonArray("accepts"), null, 0, PWA.FileHandlerAccept.class).toArray(PWA.FileHandlerAccept[]::new);
        
            this.displayName  = ReadJSON.getString(jo, "displayName", false, true);
        }
        
        
        /** Checks whether {@code 'this'} equals an input Java-{@code Object} */
        public boolean equals(Object other)
        {
            if (this == other)                       return true;
            if (other == null)                       return false;
            if (other.getClass() != this.getClass()) return false;
        
            FileHandler o = (FileHandler) other;
        
            return
                    Objects.equals(this.action, o.action)
                &&  Arrays.deepEquals(this.accepts, o.accepts)
                &&  Objects.equals(this.displayName, o.displayName);
        }
        
        /** Generates a Hash-Code for {@code 'this'} instance */
        public int hashCode()
        {
            return
                    Objects.hashCode(this.action)
                +   Arrays.deepHashCode(this.accepts)
                +   Objects.hashCode(this.displayName);
        }
    }
    
    
    // Counter for keeping the WebSocket Request ID's distinct.
    private static int counter = 1;
    
    /**
     * Returns the following OS state for the given manifest id.
     * 
     * @param manifestId 
     * The id from the webapp's manifest file, commonly it's the url of the
     * site installing the webapp. See
     * https://web.dev/learn/pwa/web-app-manifest.
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret2}&gt;</CODE>
     *
     * <BR /><BR />This {@link Script} may be <B STYLE='color:red'>executed</B> (using 
     * {@link Script#exec()}), and a {@link Promise} returned.
     *
     * <BR /><BR />When the {@code Promise} is <B STYLE='color: red'>awaited</B>
     * (using {@link Promise#await()}), the {@code Ret2} will subsequently
     * be returned from that call.
     * 
     * <BR /><BR />The <B STYLE='color: red'>returned</B> values are encapsulated
     * in an instance of <B>{@link Ret2}</B>
     *
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><CODE><B>Ret2.a:</B> Integer (<B>badgeCount</B>)</CODE>
     *     <BR />-
     *     <BR /><BR /></LI>
     * <LI><CODE><B>Ret2.b:</B> {@link PWA.FileHandler}[] (<B>fileHandlers</B>)</CODE>
     *     <BR />-
     *     </LI>
     * </UL>
     */
    public static Script<String, JsonObject, Ret2<Integer, PWA.FileHandler[]>> getOsAppState
        (String manifestId)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        final int       webSocketID = 52000000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("getOsAppState"),
            parameterNames.get("getOsAppState"),
            optionals, webSocketID,
            "PWA.getOsAppState",
            manifestId
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON into Java-Type 'Ret2'
        Function<JsonObject, Ret2<Integer, PWA.FileHandler[]>>
            responseProcessor = (JsonObject jo) -> new Ret2<>(
                ReadBoxedJSON.getInteger(jo, "badgeCount", true),
                (jo.getJsonArray("fileHandlers") == null)
                    ? null
                    : RJArrIntoStream.objArr(jo.getJsonArray("fileHandlers"), null, 0, PWA.FileHandler.class).toArray(PWA.FileHandler[]::new)
            );
        
        return new Script<>(webSocketID, requestJSON, responseProcessor);
    }
    
    /**
     * Installs the given manifest identity, optionally using the given installUrlOrBundleUrl
     * 
     * IWA-specific install description:
     * manifestId corresponds to isolated-app:// + web_package::SignedWebBundleId
     * 
     * File installation mode:
     * The installUrlOrBundleUrl can be either file:// or http(s):// pointing
     * to a signed web bundle (.swbn). In this case SignedWebBundleId must correspond to
     * The .swbn file's signing key.
     * 
     * Dev proxy installation mode:
     * installUrlOrBundleUrl must be http(s):// that serves dev mode IWA.
     * web_package::SignedWebBundleId must be of type dev proxy.
     * 
     * The advantage of dev proxy mode is that all changes to IWA
     * automatically will be reflected in the running app without
     * reinstallation.
     * 
     * To generate bundle id for proxy mode:
     * 1. Generate 32 random bytes.
     * 2. Add a specific suffix 0x00 at the end.
     * 3. Encode the entire sequence using Base32 without padding.
     * 
     * If Chrome is not in IWA dev
     * mode, the installation will fail, regardless of the state of the allowlist.
     * 
     * @param manifestId -
     * 
     * @param installUrlOrBundleUrl 
     * The location of the app or bundle overriding the one derived from the
     * manifestId.
     * <BR /><B CLASS=Opt>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> install
        (String manifestId, String installUrlOrBundleUrl)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        final int       webSocketID = 52001000 + counter++;
        final boolean[] optionals   = { false, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("install"),
            parameterNames.get("install"),
            optionals, webSocketID,
            "PWA.install",
            manifestId, installUrlOrBundleUrl
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
    }
    
    /**
     * Uninstalls the given manifest_id and closes any opened app windows.
     * 
     * @param manifestId -
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> uninstall(String manifestId)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        final int       webSocketID = 52002000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("uninstall"),
            parameterNames.get("uninstall"),
            optionals, webSocketID,
            "PWA.uninstall",
            manifestId
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
    }
    
    /**
     * Launches the installed web app, or an url in the same web app instead of the
     * default start url if it is provided. Returns a page Target.TargetID which
     * can be used to attach to via Target.attachToTarget or similar APIs.
     * 
     * @param manifestId -
     * 
     * @param url -
     * <BR /><B CLASS=Opt>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * String&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE>&lt;JsonObject,
     * String&gt;</CODE> will be returned.
     *
     * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>,
     * using {@link Promise#await()}, <I>and the returned result of this Browser Function may
      * may be retrieved.</I>
     *
     * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B>
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><CODE>String (<B>targetId</B></CODE>)
     *     <BR />ID of the tab target created as a result.
     * </LI>
     * </UL> */
    public static Script<String, JsonObject, String> launch(String manifestId, String url)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        final int       webSocketID = 52003000 + counter++;
        final boolean[] optionals   = { false, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("launch"),
            parameterNames.get("launch"),
            optionals, webSocketID,
            "PWA.launch",
            manifestId, url
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON to 'String'
        Function<JsonObject, String> responseProcessor = (JsonObject jo) ->
            ReadJSON.getString(jo, "targetId", false, true);
        
        return new Script<>(webSocketID, requestJSON, responseProcessor);
    }
    
    /**
     * Opens one or more local files from an installed web app identified by its
     * manifestId. The web app needs to have file handlers registered to process
     * the files. The API returns one or more page Target.TargetIDs which can be
     * used to attach to via Target.attachToTarget or similar APIs.
     * If some files in the parameters cannot be handled by the web app, they will
     * be ignored. If none of the files can be handled, this API returns an error.
     * If no files are provided as the parameter, this API also returns an error.
     * 
     * According to the definition of the file handlers in the manifest file, one
     * Target.TargetID may represent a page handling one or more files. The order
     * of the returned Target.TargetIDs is not guaranteed.
     * 
     * TODO(crbug.com/339454034): Check the existences of the input files.
     * 
     * @param manifestId -
     * 
     * @param files -
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * String[]&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec()}, and afterwards, a {@link Promise}<CODE>&lt;JsonObject,
     * String[]&gt;</CODE> will be returned.
     *
     * <BR /><BR />Finally, the <B>{@code Promise}</B> may be <B STYLE='color: red'>awaited</B>,
     * using {@link Promise#await()}, <I>and the returned result of this Browser Function may
      * may be retrieved.</I>
     *
     * <BR /><BR />This Browser Function <B STYLE='color: red'>returns</B>
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><CODE>String[] (<B>targetIds</B></CODE>)
     *     <BR />IDs of the tab targets created as the result.
     * </LI>
     * </UL> */
    public static Script<String, JsonObject, String[]> launchFilesInApp
        (String manifestId, String[] files)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        if (files == null)      THROWS.throwNPE("files");
        
        final int       webSocketID = 52004000 + counter++;
        final boolean[] optionals   = { false, false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("launchFilesInApp"),
            parameterNames.get("launchFilesInApp"),
            optionals, webSocketID,
            "PWA.launchFilesInApp",
            manifestId, files
        );
        
        // 'JSON Binding' ... Converts Browser Response-JSON to 'String[]'
        Function<JsonObject, String[]> responseProcessor = (JsonObject jo) ->
            (jo.getJsonArray("targetIds") == null)
                ? null
                : RJArrIntoStream.strArr(jo.getJsonArray("targetIds"), null, 0).toArray(String[]::new);
        
        return new Script<>(webSocketID, requestJSON, responseProcessor);
    }
    
    /**
     * Opens the current page in its web app identified by the manifest id, needs
     * to be called on a page target. This function returns immediately without
     * waiting for the app to finish loading.
     * 
     * @param manifestId -
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> openCurrentPageInApp(String manifestId)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        final int       webSocketID = 52005000 + counter++;
        final boolean[] optionals   = { false, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("openCurrentPageInApp"),
            parameterNames.get("openCurrentPageInApp"),
            optionals, webSocketID,
            "PWA.openCurrentPageInApp",
            manifestId
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
    }
    
    /**
     * Changes user settings of the web app identified by its manifestId. If the
     * app was not installed, this command returns an error. Unset parameters will
     * be ignored; unrecognized values will cause an error.
     * 
     * Unlike the ones defined in the manifest files of the web apps, these
     * settings are provided by the browser and controlled by the users, they
     * impact the way the browser handling the web apps.
     * 
     * See the comment of each parameter.
     * 
     * @param manifestId -
     * 
     * @param linkCapturing 
     * If user allows the links clicked on by the user in the app's scope, or
     * extended scope if the manifest has scope extensions and the flags
     * {@code DesktopPWAsLinkCapturingWithScopeExtensions} and
     * {@code WebAppEnableScopeExtensions} are enabled.
     * 
     * Note, the API does not support resetting the linkCapturing to the
     * initial value, uninstalling and installing the web app again will reset
     * it.
     * 
     * TODO(crbug.com/339453269): Setting this value on ChromeOS is not
     * supported yet.
     * <BR /><B CLASS=Opt>OPTIONAL</B>
     * 
     * @param displayMode -
     * <BR /><B CLASS=Opt>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String, {@link JsonObject},
     * {@link Ret0}&gt;</CODE>
     *
     * <BR /><BR />This {@code Script} instance must be <B STYLE='color:red'>executed</B> before the
     * browser receives the invocation-request.
     *
     * <BR /><BR />This Browser-Function <I>does not have</I> a return-value.  You may choose to
     * <B STYLE='color: red'>await</B> the {@link Promise}{@code <JsonObject,} {@link Ret0}
     * {@code >} to ensure the Browser Function has run to completion.
     */
    public static Script<String, JsonObject, Ret0> changeAppUserSettings
        (String manifestId, Boolean linkCapturing, String displayMode)
    {
        // Exception-Check(s) to ensure that if any parameters which are not declared as
        // 'Optional', but have a 'null' value anyway, that a NullPointerException shall throw.
        
        if (manifestId == null) THROWS.throwNPE("manifestId");
        
        // Exception-Check(s) to ensure that if any parameters which must adhere to a
        // provided List of Enumerated Values, fails, then IllegalArgumentException shall throw.
        
        THROWS.checkIAE("displayMode", displayMode, "PWA.DisplayMode", PWA.DisplayMode);
        
        final int       webSocketID = 52006000 + counter++;
        final boolean[] optionals   = { false, true, true, };
        
        // Convert Method Parameters into JSON.  Build the JSON Request-Object (as a String)
        String requestJSON = WriteJSON.get(
            parameterTypes.get("changeAppUserSettings"),
            parameterNames.get("changeAppUserSettings"),
            optionals, webSocketID,
            "PWA.changeAppUserSettings",
            manifestId, linkCapturing, displayMode
        );
        
        // This Remote Command does not have a Return-Value.
        return new Script<>
            (webSocketID, requestJSON, VOID_RETURN.NoReturnValues);
    }
    
}