🤖 Merge PR DefinitelyTyped#72573 [chrome]: add userScripts.execute() by @nicolas377

Author: nicolas377

types/chrome/index.d.ts

@@ -14860,6 +14860,18 @@ declare namespace chrome {
          */
         export type ExecutionWorld = "MAIN" | "USER_SCRIPT";
 
+        /** @since Chrome 135 */
+        export interface InjectionResult {
+            /** The document associated with the injection. */
+            documentId: string;
+            /** The error, if any. `error` and `result` are mutually exclusive. */
+            error?: string;
+            /** The frame associated with the injection. */
+            frameId: number;
+            /** The result of the script execution. */
+            result: any;
+        }
+
         export interface WorldProperties {
             /** Specifies the world csp. The default is the `ISOLATED` world csp. */
             csp?: string;
@@ -14876,6 +14888,18 @@ declare namespace chrome {
             ids?: string[];
         }
 
+        /** @since Chrome 135 */
+        export interface InjectionTarget {
+            /** Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if `frameIds` is specified. */
+            allFrames?: boolean;
+            /** The IDs of specific documentIds to inject into. This must not be set if `frameIds` is set. */
+            documentIds?: string[];
+            /** The IDs of specific frames to inject into. */
+            frameIds?: number[];
+            /** The ID of the tab into which to inject. */
+            tabId: number;
+        }
+
         export interface 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. */
             allFrames?: boolean;
@@ -14902,6 +14926,20 @@ declare namespace chrome {
             worldId?: string;
         }
 
+        /** @since Chrome 135 */
+        export interface 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. */
+            injectImmediately?: boolean;
+            /** The list of ScriptSource objects defining sources of scripts to be injected into the target. */
+            js: ScriptSource[];
+            /** Details specifying the target into which to inject the script. */
+            target: InjectionTarget;
+            /** The JavaScript "world" to run the script in. The default is `USER_SCRIPT`. */
+            world?: ExecutionWorld;
+            /** 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. */
+            worldId?: string;
+        }
+
         /**
          * Properties for a script source.
          */
@@ -14954,6 +14992,13 @@ declare namespace chrome {
         export function getWorldConfigurations(): Promise<WorldProperties[]>;
         export function getWorldConfigurations(callback: (worlds: WorldProperties[]) => void): void;
 
+        /**
+         * Injects a script into a target context. By default, the script will be run at `document_idle`, or immediately if the page has already loaded. If the `injectImmediately` 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.
+         * @since Chrome 135
+         */
+        export function execute(injection: UserScriptInjection): Promise<InjectionResult[]>;
+        export function execute(injection: UserScriptInjection, callback: (result: InjectionResult[]) => void): void;
+
         /**
          * Registers one or more user scripts for this extension.
          *

types/chrome/test/index.ts

@@ -4404,6 +4404,12 @@ function testUserScripts() {
     chrome.userScripts.getScripts(userScriptFilter); // $ExpectType Promise<RegisteredUserScript[]>
     chrome.userScripts.getScripts(userScriptFilter, (scripts: chrome.userScripts.RegisteredUserScript[]) => void 0); // $ExpectType void
 
+    const badScripts = [
+        {
+            id: "badScriptId",
+            matches: ["*://example.com/*"],
+        },
+    ];
     const scripts = [
         {
             id: "scriptId1",
@@ -4416,13 +4422,26 @@ function testUserScripts() {
             matches: ["*://example.org/*"],
         },
     ];
-
-    const badScripts = [
+    const jsInjections: chrome.userScripts.ScriptSource[] = [
         {
-            id: "badScriptId",
-            matches: ["*://example.com/*"],
+            file: "./the/script.js",
+        },
+        {
+            code: "console.log(\"Wow the script works!\");",
         },
     ];
+    const injectionTarget: chrome.userScripts.InjectionTarget = {
+        tabId: 46,
+        allFrames: true,
+    };
+
+    const badExeOptions = {};
+    const exeOptions: chrome.userScripts.UserScriptInjection = {
+        injectImmediately: true,
+        js: jsInjections,
+        target: injectionTarget,
+        worldId: "USER_SCRIPT",
+    };
 
     chrome.userScripts.getWorldConfigurations(); // $ExpectType Promise<WorldProperties[]>
     chrome.userScripts.getWorldConfigurations(([world]) => { // $ExpectType void
@@ -4433,6 +4452,13 @@ function testUserScripts() {
     // @ts-expect-error
     chrome.userScripts.getWorldConfigurations(() => {}).then(() => {});
 
+    // @ts-expect-error
+    chrome.userScripts.execute(badExeOptions);
+    chrome.userScripts.execute(exeOptions); // $ExpectType Promise<InjectionResult[]>
+    chrome.userScripts.execute(exeOptions, (result) => { // $ExpectType void
+        result; // $ExpectType InjectionResult[]
+    });
+
     chrome.userScripts.register(scripts); // $ExpectType Promise<void>
     chrome.userScripts.register(scripts, () => void 0); // $ExpectType void
     // @ts-expect-error Missing required property 'js'.