// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>userScripts</code> API to execute user scripts in the User
// Scripts context.
namespace userScripts {
  // The JavaScript world for a user script to execute within.
  enum ExecutionWorld {
    // Specifies the execution environment of the DOM, which is the execution
    // environment shared with the host page's JavaScript.
    MAIN,
    // Specifies the execution environment that is specific to user scripts and
    // is exempt from the page's CSP.
    USER_SCRIPT
  };

  // The source of the script to inject.
  dictionary ScriptSource {
    // A string containing the JavaScript code to inject. Exactly one of
    // <code>file</code> or <code>code</code> must be specified.
    DOMString? code;
    // The path of the JavaScript file to inject relative to the extension's
    // root directory. Exactly one of <code>file</code> or <code>code</code>
    // must be specified.
    DOMString? file;
  };

  // Describes a user script to be injected into a web page registered through
  // this API. The script is injected into a page if its URL matches any of
  // "matches" or "include_globs" patterns, and the URL doesn't match
  // "exclude_matches" and "exclude_globs" patterns.
  dictionary RegisteredUserScript {
    // If true, it will inject into all frames, even if the frame is not the
    // top-most frame in the tab. Each frame is checked independently for URL
    // requirements; it will not inject into child frames if the URL
    // requirements are not met. Defaults to false, meaning that only the top
    // frame is matched.
    boolean? allFrames;
    // Excludes pages that this user script would otherwise be injected into.
    // See <a href="develop/concepts/match-patterns">Match Patterns</a> for more details on
    // the syntax of these strings.
    DOMString[]? excludeMatches;
    // The ID of the user script specified in the API call. This property must
    // not start with a '_' as it's reserved as a prefix for generated script
    // IDs.
    DOMString id;
    // Specifies wildcard patterns for pages this user script will be injected
    // into.
    DOMString[]? includeGlobs;
    // Specifies wildcard patterns for pages this user script will NOT be
    // injected into.
    DOMString[]? excludeGlobs;
    // The list of ScriptSource objects defining sources of scripts to be
    // injected into matching pages.
    // This property must be specified for  ${ref:register}, and when specified
    // it must be a non-empty array.
    ScriptSource[]? js;
    // Specifies which pages this user script will be injected into. See
    // <a href="develop/concepts/match-patterns">Match Patterns</a> for more details on the
    // syntax of these strings. This property must be specified for
    // ${ref:register}.
    DOMString[]? matches;
    // Specifies when JavaScript files are injected into the web page. The
    // preferred and default value is <code>document_idle</code>.
    extensionTypes.RunAt? runAt;
    // The JavaScript execution environment to run the script in. The default is
    // <code>`USER_SCRIPT`</code>.
    ExecutionWorld? world;
    // Specifies the user script world ID to execute in. If omitted, the script
    // will execute in the default user script world. Only valid if `world` is
    // omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are
    // reserved.
    DOMString? worldId;
  };

  // An object used to filter user scripts for ${ref:getScripts}.
  dictionary UserScriptFilter {
    // $(ref:getScripts) only returns scripts with the IDs specified in this
    // list.
    DOMString[]? ids;
  };

  dictionary InjectionTarget {
    // Whether the script should inject into all frames within the tab. Defaults
    // to false. This must not be true if <code>frameIds</code> is specified.
    boolean? allFrames;
    // The IDs of specific documentIds to inject into. This must not be set if
    // <code>frameIds</code> is set.
    DOMString[]? documentIds;
    // The IDs of specific frames to inject into.
    long[]? frameIds;
    // The ID of the tab into which to inject.
    long tabId;
  };

  dictionary InjectionResult {
    // The document associated with the injection.
    DOMString documentId;
    // The frame associated with the injection.
    long frameId;
    // The result of the script execution.
    any? result;
    // The error, if any. <code>error</code> and <code>result</code> are
    // mutually exclusive.
    DOMString? error;
  };

  dictionary UserScriptInjection {
    // Whether the injection should be triggered in the target as soon as
    // possible. Note that this is not a guarantee that injection will occur
    // prior to page load, as the page may have already loaded by the time the
    // script reaches the target.
    boolean? injectImmediately;
    // The list of ScriptSource objects defining sources of scripts to be
    // injected into the target.
    ScriptSource[] js;
    // Details specifying the target into which to inject the script.
    InjectionTarget target;
    // The JavaScript "world" to run the script in. The default is
    // <code>USER_SCRIPT</code>.
    ExecutionWorld? world;
    // Specifies the user script world ID to execute in. If omitted, the script
    // will execute in the default user script world. Only valid if `world` is
    // omitted or is `USER_SCRIPT`. Values with leading underscores (`_`) are
    // reserved.
    DOMString? worldId;
  };

  // An object used to update the <code>`USER_SCRIPT`</code> world
  // configuration. If a property is not specified, it will reset it to its
  // default value.
  dictionary WorldProperties{
    // Specifies the ID of the specific user script world to update.
    // If not provided, updates the properties of the default user script world.
    // Values with leading underscores (`_`) are reserved.
    DOMString? worldId;

    // Specifies the world csp. The default is the <code>`ISOLATED`</code>
    // world csp.
    DOMString? csp;

    // Specifies whether messaging APIs are exposed. The default is
    // <code>false</code>.
    boolean? messaging;
  };

  callback RegisterCallback = void();

  callback GetScriptsCallback = void(RegisteredUserScript[] scripts);

  callback UnregisterCallback = void();

  callback UpdateCallback = void();

  callback ExecuteCallback = void(InjectionResult[] result);

  callback ConfigureWorldCallback = void();

  callback GetAllWorldConfigurationsCallback = void(WorldProperties[] worlds);

  callback ResetWorldConfigurationCallback = void();

  interface Functions {
    // Registers one or more user scripts for this extension.
    // |scripts|: Contains a list of user scripts to be registered.
    // |callback|: Called once scripts have been fully registered or if an error
    // has ocurred.
    static void register(
        RegisteredUserScript[] scripts,
        optional RegisterCallback callback);

    // Returns all dynamically-registered user scripts for this extension.
    // |filter|: If specified, this method returns only the user scripts that
    // match it.
    // |callback|: Called once scripts have been fully registered or if an error
    // occurs.
    static void getScripts(
        optional UserScriptFilter filter,
        GetScriptsCallback callback);

    // Unregisters all dynamically-registered user scripts for this extension.
    // |filter|: If specified, this method unregisters only the user scripts
    // that match it.
    // |callback|: Called once scripts have been fully unregistered or if an
    // error ocurs
    static void unregister(
        optional UserScriptFilter filter,
        UnregisterCallback callback);

    // Updates one or more user scripts for this extension.
    // |scripts|: Contains a list of user scripts to be updated. A property is
    // only updated for the existing script if it is specified in this object.
    // If there are errors during script parsing/file validation, or if the IDs
    // specified do not correspond to a fully registered script, then no scripts
    // are updated.
    // |callback|: Called once scripts have been fully updated or if an error
    // occurs.
    static void update(
        RegisteredUserScript[] scripts,
        optional UpdateCallback callback);

    // Injects a script into a target context. By default, the script will be
    // run at <code>document_idle</code>, or immediately if the page has already
    // loaded. If the <code>injectImmediately</code> property is set, the script
    // will inject without waiting, even if the page has not finished loading.
    // If the script evaluates to a promise, the browser will wait for the
    // promise to settle and return the resulting value.
    static void execute(
        UserScriptInjection injection,
        optional ExecuteCallback callback);

    // Configures the <code>`USER_SCRIPT`</code> execution environment.
    // |properties|: Contains the user script world configuration.
    // |callback|: Called once world hase been configured.
    static void configureWorld(
        WorldProperties properties,
        optional ConfigureWorldCallback callback);

    // Retrieves all registered world configurations.
    // |callback|: Called with the registered world configurations.
    static void getWorldConfigurations(
        GetAllWorldConfigurationsCallback callback);

    // Resets the configuration for a user script world. Any scripts that inject
    // into the world with the specified ID will use the default world
    // configuration.
    // |worldId|: The ID of the user script world to reset. If omitted, resets
    // the default world's configuration.
    // |callback|: Called when the configuration is reset.
    static void resetWorldConfiguration(
        optional DOMString worldId,
        ResetWorldConfigurationCallback callback);
  };
};