Add documentation

1 files changed, 169 insertions, 0 deletions

diff --git a/docs/frontend_api.md b/docs/frontend_api.md
new file mode 100644
index 0000000..c1d35ce
--- /dev/null
+++ b/docs/frontend_api.md
@@ -0,0 +1,169 @@
+# Frontend API
+
+Provides a set of helper functions to integrate the service into [Ferdi](https://getferdi.com).
+
+## Ferdi Class Methods
+* [setBadge](#user-content-setbadge)
+* [injectCSS](#user-content-injectcss)
+* [loop](#user-content-loop)
+* [onNotify](#user-content-onnotify)
+* [handleDarkMode](#user-content-handleDarkMode)
+
+### setBadge(directMessages, [indirectMessages])
+Sets the unread message badge
+
+#### Arguments
+1. `int` directMessages
+  * sets the count of direct messages eg. Slack direct mentions, or a message to @channel
+2. `int` indirectMessages (optional)
+  * Set a badge that defines there are new messages but they do not involve me directly to me eg. in a channel
+
+#### Usage
+
+```js
+Ferdi.setBadge(4, 2);
+
+// or
+
+Ferdi.setBadge(3);
+```
+
+### injectCSS(pathToCssFile)
+Injects the contents of one or more CSS files into the current webview
+
+#### Arguments
+1. `string` cssFile
+  * CSS files that should be injected. This must be an absolute path to the file
+
+#### Usage
+
+```js
+const path = require('path');
+
+// inject a single css file
+Ferdi.injectCSS(path.join(__dirname, 'style.css'));
+
+// inject multiple css files
+const globalStyles = path.join(__dirname, 'global.css');
+const focusModeStyles = path.join(__dirname, 'focusmode.css');
+
+Ferdi.injectCSS(globalStyles, focusModeStyles);
+```
+
+### loop(action)
+Runs an action every X milliseconds (Ferdi default is currently 1s)
+
+#### Arguments
+1. `function` action
+
+#### Usage
+
+```js
+// slack integration
+const path = require('path');
+
+module.exports = (Ferdi) => {
+  const getMessages = () => {
+    const directMessages = $('.unread_highlights, .unread_highlight').not('.hidden').length;
+    const indirectMessages = $('.unread').length - directMessages;
+
+    Ferdi.setBadge(directMessages, indirectMessages);
+  }
+
+  Ferdi.loop(getMessages);
+
+  Ferdi.injectCSS(path.join(__dirname, 'style.css'));
+}
+```
+
+### onNotify(fn)
+Runs `fn` on every notification created by the service before sending them to the host (Useful if you want to update information of the notification before showing it to the user)
+
+#### Arguments
+1. `function` fn
+
+#### Usage
+
+```js
+// messenger integration
+module.exports = (Ferdi) => {
+  const getMessages = function getMessages() {
+    let count = document.querySelectorAll('._5fx8:not(._569x),._1ht3:not(._569x)').length;
+    const messageRequestsElement = document.querySelector('._5nxf');
+    if (messageRequestsElement) {
+      count += parseInt(messageRequestsElement.innerHTML, 10);
+    }
+
+    Ferdi.setBadge(count);
+  };
+
+  Ferdi.loop(getMessages);
+
+  Ferdi.onNotify(notification => {
+
+    if (typeof notification.title !== 'string') {
+      notification.title = ((notification.title.props || {}).content || [])[0] || 'Messenger';
+    }
+
+    return notification;
+
+  });
+};
+```
+
+### handleDarkMode(callback)
+You can use a `darkmode.css` to automatically get the service into a dark theme. If your service already supports its own dark mode (e.g. Reddit and YouTube have build-in dark modes) you can use a custom dark mode handler instead.
+
+This handler should take the nesessary steps to (de-)activate dark mode on the page, e.g. by clicking a button or flipping a switch.
+
+Ferdi won't activate DarkReader or inject `darkmode.css` if the recipe has defined a custom handler. If you still need to do this, you can use the `injectDarkModeStyle` or `enableDarkMode` function provided as the second argument.
+
+#### Arguments
+1. `function` callback
+
+#### Callback function arguments
+1. `boolean` isEnabled: Is Dark Mode currently enabled?
+2. `object` helpers: Helper functions that you can use in your function:
+  `enableDarkMode` - Enable DarkReader
+  `injectDarkModeStyle` - Inject darkmode.css
+  `removeDarkModeStyle` - Remove service's darkmode.css
+  `disableDarkMode` - Disable DarkReader
+  `isDarkModeStyleInjected` - Function that returns true if darkmode.css is injected into the page
+
+#### Usage
+```JavaScript
+// Handler that works for Reddit
+Ferdi.handleDarkMode((isEnabled, helpers) => {
+  // Open dropdown menu if not already open
+  const menu = document.querySelector('#USER_DROPDOWN_ID');
+  if (menu.getAttribute('aria-expanded') === 'false') {
+    menu.click();
+  }
+
+  setTimeout(() => {
+    // Check if service is already in right mode
+    const btn = document.querySelector('[role=menu] button button');
+    const checked = btn.getAttribute('aria-checked') === 'true';
+
+    if ((checked && !isEnabled) || (!checked && isEnabled)) {
+      // Click the button to switch between modes
+      btn.click();
+    }
+  }, 50);
+});
+
+// --- or ---
+
+// Helper that activates DarkReader and injects your darkmode.css at the same time
+Ferdi.handleDarkMode((isEnabled, helpers) => {
+  if (isEnabled) {
+    helpers.enableDarkMode();
+    if (!helpers.isDarkModeStyleInjected()) {
+      helpers.injectDarkModeStyle();
+    }
+  } else {
+    helpers.disableDarkMode();
+    helpers.removeDarkModeStyle();
+  }
+})
+```
\ No newline at end of file