package Torello.Browser.BrowserAPI;

// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Java-HTML Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

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

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;

import Torello.JavaDoc.Annotations.StaticFunctional;
import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;

import Torello.Browser.BrowserAPI.NestedHelpers.Commands.PWA$$Commands;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// JDK Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import javax.json.JsonObject;
import javax.json.JsonValue;

/**
 * <SPAN CLASS=COPIEDJDK><B>This domain allows interacting with the browser to control PWAs.</B></SPAN>
 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE>
 */
@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE")
public class PWA
{
    // No Pubic Constructors
    private PWA() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Enumerated String Constants Lists
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * If user prefers opening the app in browser or an app window.
     * <BR /><BR /><B CLASS=StrEnumType>String-Enumeration Type</B>
     */
    public static final ReadOnlyList<String> DisplayMode = new ReadOnlyArrayList<>
        (String.class, "browser", "standalone");



    // ********************************************************************************************
    // ********************************************************************************************
    // Basic Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <CODE>[No Description Provided by Google]</CODE>
     * 
     * <EMBED CLASS=globalDefs DATA-DOMAIN=PWA DATA-API=BrowserAPI>
     */
    @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_TYPE_JDHBI")
    public static class FileHandler
        extends BaseType<FileHandler>
        implements java.io.Serializable
    {
        /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
        protected static final long serialVersionUID = 1;

        private static final NestedHelper<PWA.FileHandler> singleton =
            Torello.Browser.BrowserAPI.NestedHelpers.Types.
                PWA$$FileHandler$$.singleton;

        /** <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.  Please review this class' fields for documentation. */
        public FileHandler(
                ReadOnlyList<Boolean> isPresent, String action, FileHandlerAccept[] accepts,
                String displayName
            )
        {
            super(singleton, Domains.PWA, "FileHandler", 3);

            this.action         = action;
            this.accepts        = accepts;
            this.displayName    = displayName;

            this.isPresent = (isPresent == null)
                ? singleton.generateIsPresentList(this)
                : THROWS.check(isPresent, 3, "PWA.FileHandler");
        }

        /** Creates an instance of this class from a {@link JsonObject}.*/
        public static FileHandler fromJSON(JsonObject jo)
        { return singleton.fromJSON(jo); }

        /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/
        public static NestedDescriptor<FileHandler> descriptor()
        { return singleton.descriptor(); }
    }

    /**
     * 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
     * 
     * <EMBED CLASS=globalDefs DATA-DOMAIN=PWA DATA-API=BrowserAPI>
     */
    @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_TYPE_JDHBI")
    public static class FileHandlerAccept
        extends BaseType<FileHandlerAccept>
        implements java.io.Serializable
    {
        /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
        protected static final long serialVersionUID = 1;

        private static final NestedHelper<PWA.FileHandlerAccept> singleton =
            Torello.Browser.BrowserAPI.NestedHelpers.Types.
                PWA$$FileHandlerAccept$$.singleton;

        /**
         * 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.  Please review this class' fields for documentation. */
        public FileHandlerAccept
            (ReadOnlyList<Boolean> isPresent, String mediaType, String[] fileExtensions)
        {
            super(singleton, Domains.PWA, "FileHandlerAccept", 2);

            this.mediaType      = mediaType;
            this.fileExtensions = fileExtensions;

            this.isPresent = (isPresent == null)
                ? singleton.generateIsPresentList(this)
                : THROWS.check(isPresent, 2, "PWA.FileHandlerAccept");
        }

        /** Creates an instance of this class from a {@link JsonObject}.*/
        public static FileHandlerAccept fromJSON(JsonObject jo)
        { return singleton.fromJSON(jo); }

        /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/
        public static NestedDescriptor<FileHandlerAccept> descriptor()
        { return singleton.descriptor(); }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Command-Return Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the following OS state for the given manifest id.
     * 
     * <EMBED CLASS=globalDefs DATA-DOMAIN=PWA DATA-API=BrowserAPI DATA-CMD=getOsAppState>
     * @see PWA#getOsAppState
     */
    @JDHeaderBackgroundImg(EmbedTagFileID="CDP.NESTED_CMD_JDHBI")
    public static class getOsAppState$$RET
        extends BaseType<getOsAppState$$RET>
        implements java.io.Serializable
    {
        /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
        protected static final long serialVersionUID = 1;

        private static final NestedHelper<PWA.getOsAppState$$RET> singleton =
            Torello.Browser.BrowserAPI.NestedHelpers.CmdReturns.
                PWA$$getOsAppState$$RET.singleton;

        /** <CODE>[No Description Provided by Google]</CODE> */
        public final int badgeCount;

        /** <CODE>[No Description Provided by Google]</CODE> */
        public final PWA.FileHandler[] fileHandlers;

        /** Constructor.  Please review this class' fields for documentation. */
        public getOsAppState$$RET
            (ReadOnlyList<Boolean> isPresent, int badgeCount, FileHandler[] fileHandlers)
        {
            super(singleton, Domains.PWA, "getOsAppState", 2);

            this.badgeCount     = badgeCount;
            this.fileHandlers   = fileHandlers;

            this.isPresent = (isPresent == null)
                ? singleton.generateIsPresentList(this)
                : THROWS.check(isPresent, 2, "PWA.getOsAppState$$RET");
        }

        /** Creates an instance of this class from a {@link JsonObject}.*/
        public static getOsAppState$$RET fromJSON(JsonObject jo)
        { return singleton.fromJSON(jo); }

        /** Returns this class's {@link NestedDescriptor} singleton-instance. class / type.*/
        public static NestedDescriptor<getOsAppState$$RET> descriptor()
        { return singleton.descriptor(); }
    }




    // ********************************************************************************************
    // ********************************************************************************************
    // Commands
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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</CODE> and
     * <CODE>WebAppEnableScopeExtensions</CODE> 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-Top>OPTIONAL</B>
     * 
     * @param displayMode -
     * <BR /><B CLASS=Opt-Top>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;Void&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 /><DIV CLASS=JDHint>
     * 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 <Void>} to ensure that
     * the Browser Function has run to completion.
     * </DIV>
     */
    public static Script<Void> changeAppUserSettings
        (String manifestId, Boolean linkCapturing, String displayMode)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            PWA$$Commands.changeAppUserSettings$$, "PWA.changeAppUserSettings",
            manifestId, linkCapturing, displayMode
        );

        return Script.NO_RET(Domains.PWA, "changeAppUserSettings", requestJSON);
    }

    /**
     * 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;{@link getOsAppState$$RET}&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise}
     * <CODE>&lt;{@link getOsAppState$$RET}&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
     * be retrieved.</I>
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser Function's {@code Promise} returns:{@link getOsAppState$$RET}
     * A dedicated return type implies that the browser may return more than 1 datum
     * </DIV>
     */
    public static Script<getOsAppState$$RET> getOsAppState(String manifestId)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "manifestId", false, "PWA.getOsAppState", manifestId);

        return new Script<>(
            Domains.PWA, "getOsAppState", requestJSON,
            getOsAppState$$RET::fromJSON,
            getOsAppState$$RET.class
        );
    }

    /**
     * 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-Top>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;Void&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 /><DIV CLASS=JDHint>
     * 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 <Void>} to ensure that
     * the Browser Function has run to completion.
     * </DIV>
     */
    public static Script<Void> install(String manifestId, String installUrlOrBundleUrl)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            PWA$$Commands.install$$, "PWA.install",
            manifestId, installUrlOrBundleUrl
        );

        return Script.NO_RET(Domains.PWA, "install", requestJSON);
    }

    /**
     * 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-Top>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;String&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise}
     * <CODE>&lt;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
     * be retrieved.</I>
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser Function's {@code Promise} returns:
     * <CODE>String (<B>targetId</B>)</CODE>
     * <BR />
     * ID of the tab target created as a result.
     * </DIV>
     */
    public static Script<String> launch(String manifestId, String url)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            PWA$$Commands.launch$$, "PWA.launch",
            manifestId, url
        );

        return new Script<>(
            Domains.PWA, "launch", requestJSON,
            jo -> ReadJSON.getString(jo, "targetId", true, false),
            String.class
        );
    }

    /**
     * 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[]&gt;</CODE>
     * 
     * <BR /><BR />This <B>script</B> may be <B STYLE='color: red'>executed</B>, using
     * {@link Script#exec(WebSocketSender) Script.exec}, and afterwards, a {@link Promise}
     * <CODE>&lt;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
     * be retrieved.</I>
     *
     * <BR /><BR /><DIV CLASS=JDHint>
     * This Browser Function's {@code Promise} returns:
     * <CODE>String[] (<B>targetIds</B>)</CODE>
     * <BR />
     * IDs of the tab targets created as the result.
     * </DIV>
     */
    public static Script<String[]> launchFilesInApp(String manifestId, String[] files)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            PWA$$Commands.launchFilesInApp$$, "PWA.launchFilesInApp",
            manifestId, files
        );

        return new Script<>(
            Domains.PWA, "launchFilesInApp", requestJSON,
            PWA$$Commands::launchFilesInApp,
            String[].class
        );
    }

    /**
     * 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;Void&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 /><DIV CLASS=JDHint>
     * 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 <Void>} to ensure that
     * the Browser Function has run to completion.
     * </DIV>
     */
    public static Script<Void> openCurrentPageInApp(String manifestId)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "manifestId", false, "PWA.openCurrentPageInApp", manifestId);

        return Script.NO_RET(Domains.PWA, "openCurrentPageInApp", requestJSON);
    }

    /**
     * Uninstalls the given manifest_id and closes any opened app windows.
     * 
     * @param manifestId -
     * 
     * @return An instance of <CODE>{@link Script}&lt;Void&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 /><DIV CLASS=JDHint>
     * 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 <Void>} to ensure that
     * the Browser Function has run to completion.
     * </DIV>
     */
    public static Script<Void> uninstall(String manifestId)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "manifestId", false, "PWA.uninstall", manifestId);

        return Script.NO_RET(Domains.PWA, "uninstall", requestJSON);
    }


}