Merge pull request #137 from duckduckgo/shane/docs

working on docs
duckduckgo · Nov 30, 2023 · 3f587e7 · 3f587e7
2 parents 59dedf0 + 3d3ef9a
commit 3f587e7
Show file tree

Hide file tree

Showing 10 changed files with 194 additions and 24 deletions.
diff --git a/build/app/public/js/base.js b/build/app/public/js/base.js
@@ -10682,6 +10682,9 @@
         }
       };
       BurnMessage = class extends Msg {
+        /**
+         * @param {import('../../../schema/__generated__/schema.types').FireOption} opts
+         */
         constructor(opts) {
           super();
           Object.assign(this, opts);
@@ -10690,6 +10693,9 @@
       FetchBurnOptions = class extends Msg {
       };
       SetBurnDefaultOption = class extends Msg {
+        /**
+         * @param {import('../../../schema/__generated__/schema.types').FireOption['name']} name
+         */
         constructor(name) {
           super();
           this.defaultOption = name;
@@ -11021,10 +11027,12 @@
     doBurn: () => doBurn,
     fetch: () => fetch,
     getBackgroundTabData: () => getBackgroundTabData,
+    getBurnOptions: () => getBurnOptions,
     getPrivacyDashboardData: () => getPrivacyDashboardData,
     openOptions: () => openOptions,
     refreshAlias: () => refreshAlias,
     search: () => search,
+    setBurnDefaultOption: () => setBurnDefaultOption,
     setLists: () => setLists,
     setup: () => setup,
     submitBrokenSiteReport: () => submitBrokenSiteReport
@@ -11055,10 +11063,10 @@
       return doBurn(message);
     }
     if (message instanceof FetchBurnOptions) {
-      return toExtensionMessage("getBurnOptions");
+      return getBurnOptions();
     }
     if (message instanceof SetBurnDefaultOption) {
-      return toExtensionMessage("setBurnDefaultOption", message);
+      return setBurnDefaultOption(message);
     }
     return new Promise((resolve) => {
       window.chrome.runtime.sendMessage(message, (result) => {
@@ -11098,6 +11106,12 @@
   async function openOptions() {
     return toExtensionMessage("openOptions");
   }
+  function getBurnOptions() {
+    return toExtensionMessage("getBurnOptions");
+  }
+  function setBurnDefaultOption(message) {
+    return toExtensionMessage("setBurnDefaultOption", message);
+  }
   async function doBurn(message) {
     const browsingDataPermissions = {
       permissions: ["browsingData"]
@@ -12255,6 +12269,8 @@
     onChangeRequestData: () => onChangeRequestData,
     privacyDashboardOpenSettings: () => privacyDashboardOpenSettings,
     privacyDashboardOpenUrlInNewTab: () => privacyDashboardOpenUrlInNewTab,
+    privacyDashboardSetPermission: () => privacyDashboardSetPermission,
+    privacyDashboardSetProtection: () => privacyDashboardSetProtection,
     privacyDashboardSetSize: () => privacyDashboardSetSize,
     privacyDashboardSubmitBrokenSiteReport: () => privacyDashboardSubmitBrokenSiteReport,
     setup: () => setup2,
@@ -12302,6 +12318,17 @@
     Object.assign(cookiePromptManagementStatus, parsed.data);
     channel2?.send("updateTabData");
   }
+  function privacyDashboardSetProtection(params) {
+    invariant(
+      window.webkit?.messageHandlers?.privacyDashboardSetProtection,
+      "webkit.messageHandlers.privacyDashboardSetProtection required"
+    );
+    window.webkit.messageHandlers.privacyDashboardSetProtection.postMessage(params);
+  }
+  function privacyDashboardSetPermission(params) {
+    invariant(window.webkit?.messageHandlers, "webkit.messageHandlers required");
+    window.webkit.messageHandlers.privacyDashboardSetPermission.postMessage(params);
+  }
   async function fetch2(message) {
     if (message instanceof SubmitBrokenSiteReportMessage) {
       privacyDashboardSubmitBrokenSiteReport({
@@ -12319,12 +12346,9 @@
           continue;
         }
         const isProtected = value === false;
-        invariant(window.webkit?.messageHandlers?.privacyDashboardSetProtection, "webkit.messageHandlers required");
-        window.webkit.messageHandlers.privacyDashboardSetProtection.postMessage({
-          isProtected,
-          eventOrigin: message.eventOrigin
-        });
+        privacyDashboardSetProtection({ eventOrigin: message.eventOrigin, isProtected });
       }
+      return;
     }
     if (message instanceof OpenSettingsMessages) {
       privacyDashboardOpenSettings({
@@ -12333,8 +12357,7 @@
       return;
     }
     if (message instanceof UpdatePermissionMessage) {
-      invariant(window.webkit?.messageHandlers, "webkit.messageHandlers required");
-      window.webkit.messageHandlers.privacyDashboardSetPermission.postMessage({
+      privacyDashboardSetPermission({
         permission: message.id,
         value: message.value
       });
@@ -12778,8 +12801,11 @@
   // shared/js/browser/windows-communication.js
   var windows_communication_exports = {};
   __export(windows_communication_exports, {
+    AddToAllowListCommand: () => AddToAllowListCommand,
     OpenInNewTab: () => OpenInNewTab,
     OpenSettings: () => OpenSettings,
+    RemoveFromAllowListCommand: () => RemoveFromAllowListCommand,
+    SetPermissionCommand: () => SetPermissionCommand,
     SetSize: () => SetSize,
     SubmitBrokenSiteReport: () => SubmitBrokenSiteReport,
     backgroundMessage: () => backgroundMessage4,
@@ -12834,14 +12860,14 @@
         const isProtected = value === false;
         const eventOrigin = message.eventOrigin;
         if (isProtected) {
-          windowsPostMessage("RemoveFromAllowListCommand", { eventOrigin });
+          RemoveFromAllowListCommand(eventOrigin);
         } else {
-          windowsPostMessage("AddToAllowListCommand", { eventOrigin });
+          AddToAllowListCommand(eventOrigin);
         }
       }
     }
     if (message instanceof UpdatePermissionMessage) {
-      windowsPostMessage("SetPermissionCommand", {
+      SetPermissionCommand({
         permission: message.id,
         value: message.value
       });
@@ -12864,6 +12890,15 @@
   function OpenSettings(args) {
     windowsPostMessage("OpenSettings", args);
   }
+  function SetPermissionCommand(args) {
+    windowsPostMessage("SetPermissionCommand", args);
+  }
+  function RemoveFromAllowListCommand(eventOrigin) {
+    windowsPostMessage("RemoveFromAllowListCommand", { eventOrigin });
+  }
+  function AddToAllowListCommand(eventOrigin) {
+    windowsPostMessage("AddToAllowListCommand", { eventOrigin });
+  }
   function handleIncomingMessage(message) {
     const parsed = eventShape.safeParse(message);
     if (!parsed.success) {

diff --git a/integration-tests/ios.spec-int.js b/integration-tests/ios.spec-int.js
@@ -152,6 +152,7 @@ if (!process.env.CI) {
             { name: 'upgraded+secure', state: testDataStates['upgraded+secure'] },
             { name: 'google-off', state: testDataStates['google-off'] },
             { name: 'cnn', state: testDataStates.cnn },
+            { name: 'allowlisted', state: testDataStates.allowlisted },
         ]
         for (const { name, state } of states) {
             test(name, async ({ page }) => {

diff --git a/...ion-tests/ios.spec-int.js-snapshots/allowlisted-state-connection-ios-darwin.png b/...ion-tests/ios.spec-int.js-snapshots/allowlisted-state-connection-ios-darwin.png
diff --git a/...n-tests/ios.spec-int.js-snapshots/allowlisted-state-non-trackers-ios-darwin.png b/...n-tests/ios.spec-int.js-snapshots/allowlisted-state-non-trackers-ios-darwin.png
diff --git a/...ration-tests/ios.spec-int.js-snapshots/allowlisted-state-primary-ios-darwin.png b/...ration-tests/ios.spec-int.js-snapshots/allowlisted-state-primary-ios-darwin.png
diff --git a/...ation-tests/ios.spec-int.js-snapshots/allowlisted-state-trackers-ios-darwin.png b/...ation-tests/ios.spec-int.js-snapshots/allowlisted-state-trackers-ios-darwin.png
diff --git a/shared/js/browser/browser-communication.js b/shared/js/browser/browser-communication.js
@@ -61,10 +61,10 @@ export async function fetch(message) {
         return doBurn(message)
     }
     if (message instanceof FetchBurnOptions) {
-        return toExtensionMessage('getBurnOptions')
+        return getBurnOptions()
     }
     if (message instanceof SetBurnDefaultOption) {
-        return toExtensionMessage('setBurnDefaultOption', message)
+        return setBurnDefaultOption(message)
     }
     return new Promise((resolve) => {
         // console.log('🚀 [OUTGOING]', JSON.stringify(message, null, 2))
@@ -198,6 +198,48 @@ export async function openOptions() {
     return toExtensionMessage('openOptions')
 }
 
+/**
+ * @category Dashboard -> Extension Messages
+ * @return {Promise<import('../../../schema/__generated__/schema.types').FireButtonData>}
+ * @example
+ * ```javascript
+ * window.chrome.runtime.sendMessage({
+ *    messageType: 'getBurnOptions',
+ *    options: {}
+ * })
+ * ```
+ */
+export function getBurnOptions() {
+    return toExtensionMessage('getBurnOptions')
+}
+
+/**
+ * @category Dashboard -> Extension Messages
+ * @param {SetBurnDefaultOption} message
+ * @example
+ * ```javascript
+ * window.chrome.runtime.sendMessage({
+ *    messageType: 'setBurnDefaultOption',
+ *    options: {
+ *        defaultOption: "CurrentSite"
+ *    }
+ * })
+ * ```
+ */
+export function setBurnDefaultOption(message) {
+    return toExtensionMessage('setBurnDefaultOption', message)
+}
+
+/**
+ * @param {BurnMessage} message
+ * @category Dashboard -> Extension Messages
+ * @example
+ * ```javascript
+ * window.chrome.runtime.sendMessage({
+ *    messageType: 'doBurn'
+ * })
+ * ```
+ */
 export async function doBurn(message) {
     const browsingDataPermissions = {
         permissions: ['browsingData'],

diff --git a/shared/js/browser/common.js b/shared/js/browser/common.js
@@ -236,6 +236,13 @@ export async function refreshAlias() {
  */
 export function search(options) {}
 
+/**
+ * This message will be sent when the permissions dropdown is used
+ *
+ * @param {{permission: string; value: string}} params
+ */
+export function setPermission(params) {}
+
 class Msg {
     toJSON() {
         return {
@@ -341,6 +348,9 @@ export class OpenSettingsMessages extends Msg {
 }
 
 export class BurnMessage extends Msg {
+    /**
+     * @param {import('../../../schema/__generated__/schema.types').FireOption} opts
+     */
     constructor(opts) {
         super()
         Object.assign(this, opts)
@@ -350,6 +360,9 @@ export class BurnMessage extends Msg {
 export class FetchBurnOptions extends Msg {}
 
 export class SetBurnDefaultOption extends Msg {
+    /**
+     * @param {import('../../../schema/__generated__/schema.types').FireOption['name']} name
+     */
     constructor(name) {
         super()
         this.defaultOption = name

diff --git a/shared/js/browser/macos-communication.js b/shared/js/browser/macos-communication.js
@@ -188,6 +188,52 @@ export function onChangeConsentManaged(payload) {
 
 // -----------------------------------------------------------------------------
 
+/**
+ * This message will be sent when the toggle is pressed on, or off via:
+ *  - The primary screen
+ *  - The breakage form
+ *
+ * @param {import('../../../schema/__generated__/schema.types').SetProtectionParams} params
+ * @category Webkit Message Handlers
+ * @example
+ *
+ * This message handler is the equivalent of calling the following JavaScript.
+ *
+ * ```js
+ * window.webkit.messageHandlers.privacyDashboardSetProtection.postMessage({
+ *    isProtected: true,
+ *    eventOrigin: { screen: "primaryScreen" }
+ * })
+ * ```
+ */
+export function privacyDashboardSetProtection(params) {
+    invariant(
+        window.webkit?.messageHandlers?.privacyDashboardSetProtection,
+        'webkit.messageHandlers.privacyDashboardSetProtection required'
+    )
+    window.webkit.messageHandlers.privacyDashboardSetProtection.postMessage(params)
+}
+
+/**
+ * {@inheritDoc common.setPermission}
+ * @type {import("./common.js").setPermission}
+ * @category Webkit Message Handlers
+ * @example
+ *
+ * This message handler is the equivalent of calling the following JavaScript.
+ *
+ * ```js
+ * window.webkit.messageHandlers.privacyDashboardSetPermission.postMessage({
+ *    permission: "camera",
+ *    value: "grant"
+ * })
+ * ```
+ */
+export function privacyDashboardSetPermission(params) {
+    invariant(window.webkit?.messageHandlers, 'webkit.messageHandlers required')
+    window.webkit.messageHandlers.privacyDashboardSetPermission.postMessage(params)
+}
+
 /**
  * @category Internal API
  * @type {import("./common.js").fetcher}
@@ -211,12 +257,9 @@ async function fetch(message) {
             // `allowlisted: true` means the user disabled protections.
             // so `isProtected` is the opposite of `allowlisted`.
             const isProtected = value === false
-            invariant(window.webkit?.messageHandlers?.privacyDashboardSetProtection, 'webkit.messageHandlers required')
-            window.webkit.messageHandlers.privacyDashboardSetProtection.postMessage({
-                isProtected,
-                eventOrigin: message.eventOrigin,
-            })
+            privacyDashboardSetProtection({ eventOrigin: message.eventOrigin, isProtected })
         }
+        return
     }
     if (message instanceof OpenSettingsMessages) {
         privacyDashboardOpenSettings({
@@ -226,8 +269,7 @@ async function fetch(message) {
     }
 
     if (message instanceof UpdatePermissionMessage) {
-        invariant(window.webkit?.messageHandlers, 'webkit.messageHandlers required')
-        window.webkit.messageHandlers.privacyDashboardSetPermission.postMessage({
+        privacyDashboardSetPermission({
             permission: message.id,
             value: message.value,
         })