better docs and examples

Author: Shane Osbourne

package-lock.json

@@ -1,6 +1,6 @@
 /**
  * @module Messaging
- *
+ * @category Libraries
  * @description
  *
  * An abstraction for communications between JavaScript and host platforms.
@@ -9,48 +9,20 @@
  * 2) Then use that to get an instance of the Messaging utility which allows
  * you to send and receive data in a unified way
  * 3) Each platform implements {@link MessagingTransport} along with its own Configuration
- *     - For example, to learn what configuration is required for Webkit, see: {@link "Webkit Messaging".WebkitMessagingConfig}
- *     - Or, to learn about how messages are sent and received in Webkit, see {@link "Webkit Messaging".WebkitMessagingTransport}
+ *     - For example, to learn what configuration is required for Webkit, see: {@link WebkitMessagingConfig}
+ *     - Or, to learn about how messages are sent and received in Webkit, see {@link WebkitMessagingTransport}
  *
  * @example Webkit Messaging
  *
- * ```js
- * import { Messaging, WebkitMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // This config would be injected into the UserScript
- * const injectedConfig = {
- *   hasModernWebkitAPI: true,
- *   webkitMessageHandlerNames: ["foo", "bar", "baz"],
- *   secret: "dax",
- * };
- *
- * // Then use that config to construct platform-specific configuration
- * const config = new WebkitMessagingConfig(injectedConfig);
- *
- * // finally, get an instance of Messaging and start sending messages in a unified way 🚀
- * const messaging = new Messaging(config);
- * messaging.notify("hello world!", {foo: "bar"})
- *
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/webkit.example.js]]```
  *
  * @example Windows Messaging
  *
- * ```js
- * import { Messaging, WindowsMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // Messaging on Windows is namespaced, so you can create multiple messaging instances
- * const autofillConfig  = new WindowsMessagingConfig({ featureName: "Autofill" });
- * const debugConfig     = new WindowsMessagingConfig({ featureName: "Debugging" });
- *
- * const autofillMessaging = new Messaging(autofillConfig);
- * const debugMessaging    = new Messaging(debugConfig);
- *
- * // Now send messages to both features as needed 🚀
- * autofillMessaging.notify("storeFormData", { "username": "dax" })
- * debugMessaging.notify("pageLoad", { time: window.performance.now() })
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/windows.example.js]]```
  */
-import { WindowsMessagingConfig, WindowsMessagingTransport } from './lib/windows.js'
+import { WindowsMessagingConfig, WindowsMessagingTransport, WindowsInteropMethods } from './lib/windows.js'
 import { WebkitMessagingConfig, WebkitMessagingTransport } from './lib/webkit.js'
 
 /**
@@ -176,4 +148,10 @@ export class MissingHandler extends Error {
 /**
  * Some re-exports for convenience
  */
-export { WebkitMessagingConfig, WindowsMessagingConfig }
+export {
+    WebkitMessagingConfig,
+    WebkitMessagingTransport,
+    WindowsMessagingConfig,
+    WindowsMessagingTransport,
+    WindowsInteropMethods
+}

packages/messaging/index.js

@@ -0,0 +1,23 @@
+import { Messaging, WebkitMessagingConfig } from '../../index.js'
+
+/**
+ * Webkit messaging involves calling methods on `window.webkit.messageHandlers`.
+ *
+ * For catalina support we support encryption which is the bulk of this configuration
+ */
+const config = new WebkitMessagingConfig({
+  hasModernWebkitAPI: true,
+  secret: 'SECRET',
+  webkitMessageHandlerNames: ['helloWorld', 'sendPixel'],
+})
+
+/**
+ * Send notifications!
+ */
+const messaging = new Messaging(config)
+messaging.notify('sendPixel')
+
+/**
+ * Or request some data
+ */
+messaging.request('helloWorld', { foo: 'bar' }).then(console.log).catch(console.error)

packages/messaging/lib/examples/webkit.example.js

@@ -1,5 +1,4 @@
 /**
- * @module Webkit Messaging
  *
  * @description
  *
@@ -9,27 +8,11 @@
  * Note: If you wish to support Catalina then you'll need to implement the native
  * part of the message handling, see {@link WebkitMessagingTransport} for details.
  *
- * ```js
- * import { Messaging, WebkitMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
- *
- * // This config would be injected into the UserScript
- * const injectedConfig = {
- *   hasModernWebkitAPI: true,
- *   webkitMessageHandlerNames: ["foo", "bar", "baz"],
- *   secret: "dax",
- * };
- *
- * // Then use that config to construct platform-specific configuration
- * const config = new WebkitMessagingConfig(injectedConfig);
- *
- * // finally, get an instance of Messaging and start sending messages in a unified way 🚀
- * const messaging = new Messaging(config);
- * messaging.notify("hello world!", {foo: "bar"})
- *
- * ```
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/webkit.example.js]]```
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { MessagingTransport, MissingHandler } from '../'
+import { MessagingTransport, MissingHandler } from '../index.js'
 
 /**
  * @example
@@ -354,7 +337,7 @@ export class SecureMessagingParams {
  * scripts from tampering with this
  */
 function captureGlobals() {
-  // Creat base with null prototype
+  // Create base with null prototype
   return {
     window,
     // Methods must be bound to their interface, otherwise they throw Illegal invocation

packages/messaging/lib/webkit.js

@@ -1,6 +1,4 @@
 /**
- * @module Windows Messaging
- *
  * @description
  *
  * A wrapper for messaging on Windows.
@@ -15,7 +13,7 @@
  */
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { MessagingTransport } from '../'
+import { MessagingTransport } from '../index.js'
 
 /**
  * @implements {MessagingTransport}

packages/messaging/lib/windows.js

@@ -4,10 +4,9 @@
   "version": "1.0.0",
   "description": "",
   "main": "index.js",
-  "devDependencies": {
-  },
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo '✅ No tests yet'"
   },
   "author": "",
   "license": "ISC"

packages/messaging/package.json

@@ -1,10 +1,13 @@
 {
     "name": "@duckduckgo/workspaces-demo",
     "entryPoints": [
-        "inject/*",
-        "packages/*",
-        "packages/messaging/lib/webkit.js",
-        "packages/messaging/lib/windows.js"
+        "inject/android.js",
+        "inject/apple.js",
+        "inject/chrome.js",
+        "inject/chrome-mv3.js",
+        "inject/mozilla.js",
+        "inject/windows.js",
+        "packages/*"
     ],
     "out": "docs",
     "excludeExternals": true,