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.Extensions$$Commands;


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

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

/**
 * <SPAN CLASS=COPIEDJDK><B>Defines commands and events for browser extensions.</B></SPAN>
 * <EMBED CLASS='external-html' DATA-FILE-ID=CDP.CODE_GEN_NOTE>
 */
@StaticFunctional@JDHeaderBackgroundImg(EmbedTagFileID="CDP.WOOD_PLANK_NOTE")
public class Extensions
{
    // No Pubic Constructors
    private Extensions() { }


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


    /**
     * Storage areas.
     * <BR /><BR /><B CLASS=StrEnumType>String-Enumeration Type</B>
     */
    public static final ReadOnlyList<String> StorageArea = new ReadOnlyArrayList<>
        (String.class, "local", "managed", "session", "sync");





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


    /**
     * Clears extension storage in the given <CODE>storageArea</CODE>.
     * 
     * @param id ID of extension.
     * 
     * @param storageArea StorageArea to remove data from.
     * 
     * @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> clearStorageItems(String id, String storageArea)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            Extensions$$Commands.clearStorageItems$$, "Extensions.clearStorageItems",
            id, storageArea
        );

        return Script.NO_RET(Domains.Extensions, "clearStorageItems", requestJSON);
    }

    /**
     * Gets data from extension storage in the given <CODE>storageArea</CODE>. If <CODE>keys</CODE> is
     * specified, these are used to filter the result.
     * 
     * @param id ID of extension.
     * 
     * @param storageArea StorageArea to retrieve data from.
     * 
     * @param keys Keys to retrieve.
     * <BR /><B CLASS=Opt-Top>OPTIONAL</B>
     * 
     * @return An instance of <CODE>{@link Script}&lt;JsonValue&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;JsonValue&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>JsonValue (<B>data</B>)</CODE>
     * </DIV>
     */
    public static Script<JsonValue> getStorageItems(String id, String storageArea, String[] keys)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            Extensions$$Commands.getStorageItems$$, "Extensions.getStorageItems",
            id, storageArea, keys
        );

        return new Script<>(
            Domains.Extensions, "getStorageItems", requestJSON,
            jo -> jo.get("data"),
            JsonValue.class
        );
    }

    /**
     * Installs an unpacked extension from the filesystem similar to
     * --load-extension CLI flags. Returns extension ID once the extension
     * has been installed. Available if the client is connected using the
     * --remote-debugging-pipe flag and the --enable-unsafe-extension-debugging
     * flag is set.
     * 
     * @param path Absolute file path.
     * 
     * @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>id</B>)</CODE>
     * <BR />
     * Extension id.
     * </DIV>
     */
    public static Script<String> loadUnpacked(String path)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "path", false, "Extensions.loadUnpacked", path);

        return new Script<>(
            Domains.Extensions, "loadUnpacked", requestJSON,
            jo -> ReadJSON.getString(jo, "id", true, false),
            String.class
        );
    }

    /**
     * Removes <CODE>keys</CODE> from extension storage in the given <CODE>storageArea</CODE>.
     * 
     * @param id ID of extension.
     * 
     * @param storageArea StorageArea to remove data from.
     * 
     * @param keys Keys to remove.
     * 
     * @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> removeStorageItems(String id, String storageArea, String[] keys)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            Extensions$$Commands.removeStorageItems$$, "Extensions.removeStorageItems",
            id, storageArea, keys
        );

        return Script.NO_RET(Domains.Extensions, "removeStorageItems", requestJSON);
    }

    /**
     * Sets <CODE>values</CODE> in extension storage in the given <CODE>storageArea</CODE>. The provided <CODE>values</CODE>
     * will be merged with existing values in the storage area.
     * 
     * @param id ID of extension.
     * 
     * @param storageArea StorageArea to set data in.
     * 
     * @param values Values to set.
     * 
     * @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> setStorageItems(String id, String storageArea, JsonValue values)
    {
        // Convert all Method Parameters into a JSON Request-Object (as a String)
        final String requestJSON = WriteJSON.get(
            Extensions$$Commands.setStorageItems$$, "Extensions.setStorageItems",
            id, storageArea, values
        );

        return Script.NO_RET(Domains.Extensions, "setStorageItems", requestJSON);
    }

    /**
     * Uninstalls an unpacked extension (others not supported) from the profile.
     * Available if the client is connected using the --remote-debugging-pipe flag
     * and the --enable-unsafe-extension-debugging.
     * 
     * @param id Extension id.
     * 
     * @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 id)
    {
        // Build the JSON Request-Object (as a String); only 1 Parameter is passed
        final String requestJSON = WriteJSON.get
            (CDPTypes.STRING, "id", false, "Extensions.uninstall", id);

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


}