🤖 Merge PR DefinitelyTyped#73413 [chrome] update desktopCapture namespace by @erwanjugand

Author: erwanjugand

types/chrome/index.d.ts

@@ -2617,31 +2617,39 @@ declare namespace chrome {
      * Permissions: "desktopCapture"
      */
     export namespace desktopCapture {
-        /** Contains properties that describe the stream. */
+        /** Enum used to define set of desktop media sources used in {@link chooseDesktopMedia}. */
+        export enum DesktopCaptureSourceType {
+            SCREEN = "screen",
+            WINDOW = "window",
+            TAB = "tab",
+            AUDIO = "audio",
+        }
+
+        /**
+         * Contains properties that describe the stream.
+         * @since Chrome 57
+         */
         export interface StreamOptions {
             /** True if "audio" is included in parameter sources, and the end user does not uncheck the "Share audio" checkbox. Otherwise false, and in this case, one should not ask for audio stream through getUserMedia call. */
             canRequestAudioTrack: boolean;
         }
         /**
          * Shows desktop media picker UI with the specified set of sources.
-         * @param sources Set of sources that should be shown to the user.
-         * Parameter streamId: An opaque string that can be passed to getUserMedia() API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty streamId. The created streamId can be used only once and expires after a few seconds when it is not used.
+         * @param sources Set of sources that should be shown to the user. The sources order in the set decides the tab order in the picker.
+         * @param targetTab Optional tab for which the stream is created. If not specified then the resulting stream can be used only by the calling extension. The stream can only be used by frames in the given tab whose security origin matches `tab.url`. The tab's origin must be a secure origin, e.g. HTTPS.
+         * @param callback streamId: An opaque string that can be passed to `getUserMedia()` API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty `streamId`. The created `streamId` can be used only once and expires after a few seconds when it is not used.
+         * @return An id that can be passed to cancelChooseDesktopMedia() in case the prompt need to be canceled.
          */
         export function chooseDesktopMedia(
-            sources: string[],
+            sources: `${DesktopCaptureSourceType}`[],
             callback: (streamId: string, options: StreamOptions) => void,
         ): number;
-        /**
-         * Shows desktop media picker UI with the specified set of sources.
-         * @param sources Set of sources that should be shown to the user.
-         * @param targetTab Optional tab for which the stream is created. If not specified then the resulting stream can be used only by the calling extension. The stream can only be used by frames in the given tab whose security origin matches tab.url.
-         * Parameter streamId: An opaque string that can be passed to getUserMedia() API to generate media stream that corresponds to the source selected by the user. If user didn't select any source (i.e. canceled the prompt) then the callback is called with an empty streamId. The created streamId can be used only once and expires after a few seconds when it is not used.
-         */
         export function chooseDesktopMedia(
-            sources: string[],
-            targetTab: chrome.tabs.Tab,
+            sources: `${DesktopCaptureSourceType}`[],
+            targetTab: tabs.Tab | undefined,
             callback: (streamId: string, options: StreamOptions) => void,
         ): number;
+
         /**
          * Hides desktop media picker dialog shown by chooseDesktopMedia().
          * @param desktopMediaRequestId Id returned by chooseDesktopMedia()

types/chrome/test/index.ts

@@ -6513,3 +6513,38 @@ function testReadingList() {
 function testDom() {
     chrome.dom.openOrClosedShadowRoot(document.body); // $ExpectType ShadowRoot | null
 }
+
+// https://developer.chrome.com/docs/extensions/reference/api/desktopCapture
+function testDesktopCapture() {
+    chrome.desktopCapture.DesktopCaptureSourceType.AUDIO === "audio";
+    chrome.desktopCapture.DesktopCaptureSourceType.SCREEN === "screen";
+    chrome.desktopCapture.DesktopCaptureSourceType.TAB === "tab";
+    chrome.desktopCapture.DesktopCaptureSourceType.WINDOW === "window";
+
+    chrome.desktopCapture.cancelChooseDesktopMedia(0); // $ExpectType void
+
+    const sources: `${chrome.desktopCapture.DesktopCaptureSourceType}`[] = [
+        "screen",
+        chrome.desktopCapture.DesktopCaptureSourceType.WINDOW,
+    ];
+
+    const tab: chrome.tabs.Tab = {
+        index: 0,
+        pinned: false,
+        highlighted: false,
+        windowId: 0,
+        active: false,
+        frozen: false,
+        incognito: false,
+        selected: false,
+        discarded: false,
+        autoDiscardable: false,
+        groupId: 0,
+    };
+
+    chrome.desktopCapture.chooseDesktopMedia(sources, () => {}); // $ExpectType number
+    chrome.desktopCapture.chooseDesktopMedia(sources, tab, (streamId, options) => {
+        streamId; // $ExpectType string
+        options; // $ExpectType StreamOptions
+    });
+}