chore: update dependencies, improve safety checks, and rewrite README

.github/workflows/Email-Plugin-CI.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [24.x]
 
     steps:
     - uses: actions/checkout@v3

GENERATOR_DOC.md

@@ -1,27 +1,22 @@
-# generator-joplin
+# Plugin development
 
-Scaffolds out a new Joplin plugin
+This documentation describes how to create a plugin, and how to work with the plugin builder framework and API.
 
 ## Installation
 
 First, install [Yeoman](http://yeoman.io) and generator-joplin using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).
 
 ```bash
-npm install -g yo
+npm install -g yo@4.3.1
 npm install -g generator-joplin
 ```
 
 Then generate your new project:
 
 ```bash
-yo joplin
+yo --node-package-manager npm joplin
 ```
 
-## Development
-
-To test the generator for development purposes, follow the instructions there: https://yeoman.io/authoring/#running-the-generator
-This is a template to create a new Joplin plugin.
-
 ## Structure
 
 The main two files you will want to look at are:
@@ -39,6 +34,10 @@ To build the plugin, simply run `npm run dist`.
 
 The project is setup to use TypeScript, although you can change the configuration to use plain JavaScript.
 
+## Updating the manifest version number
+
+You can run `npm run updateVersion` to bump the patch part of the version number, so for example 1.0.3 will become 1.0.4. This script will update both the package.json and manifest.json version numbers so as to keep them in sync.
+
 ## Publishing the plugin
 
 To publish the plugin, add it to npmjs.com by running `npm publish`. Later on, a script will pick up your plugin and add it automatically to the Joplin plugin repository as long as the package satisfies these conditions:
@@ -67,6 +66,13 @@ By default, the compiler (webpack) is going to compile `src/index.ts` only (as w
 
 To get such an external script file to compile, you need to add it to the `extraScripts` array in `plugin.config.json`. The path you add should be relative to /src. For example, if you have a file in "/src/webviews/index.ts", the path should be set to "webviews/index.ts". Once compiled, the file will always be named with a .js extension. So you will get "webviews/index.js" in the plugin package, and that's the path you should use to reference the file.
 
+## More information
+
+- [Joplin Plugin API](https://joplinapp.org/api/references/plugin_api/classes/joplin.html)
+- [Joplin Data API](https://joplinapp.org/help/api/references/rest_api)
+- [Joplin Plugin Manifest](https://joplinapp.org/api/references/plugin_manifest/)
+- Ask for help on the [forum](https://discourse.joplinapp.org/) or our [Discord channel](https://discord.gg/VSj7AFHvpq)
+
 ## License
 
 MIT © Laurent Cozic

README.md

@@ -1,6 +1,9 @@
 <h1 align = "center" > Email Plugin </h1>
 
-This plugin adds the ability to fetch email messages (including attachments) and converts them to Joplin notes in various formats, either by monitoring any `new` or `unread` messages from a specific email address or a specific mailbox, or by uploading downloaded email messages to the plugin without having to be logged in.
+This plugin allows you to fetch email messages (including attachments) and convert them into Joplin notes in multiple formats.
+
+Emails can be processed automatically by monitoring `new` or `unread` messages from a specific email address or mailbox, or manually by uploading downloaded email messages in `.eml` format without needing to log in to the plugin.
+
 
 ***
 
@@ -16,64 +19,96 @@ This plugin adds the ability to fetch email messages (including attachments) and
 
 ## Features
 
-- Monitoring and fetching any `new` or `unread` messages from a specific email address.
+- Monitor and fetch **new or unread emails** from a specific email address.
 
-- Monitoring and fetching any `new` or `unread` messages from a specific mailbox.
+- Monitor and fetch **new or unread emails** from a selected mailbox.
 
-- Send the converted message to specific notebooks and add tags to the note by using `@` or `#` in the email subject or first line of email content and then forward the email to yourself.
+- You can control how notes are created using simple syntax in the **email subject** or the **first line of the email body**:
+  - `@notebook` → save the note to a specific notebook
+  - `#tag` → add tags to the note
+  - `!Subject` → create a **Todo** note
 
-- Convert emails (including attachments) to notes without having to be logged into the plugin.
+- Convert email messages (including attachments) into notes **without being logged into the plugin**.
 
-- Convert email messages to notes in different formats (`HTML`, `Markdown`, `Text`).
+- Convert emails into notes using different output formats:
+  - `HTML`
+  - `Markdown`
+  - `Plain Text`
 
-- Show attachments in different styles, whether they are in the form of a `Table` or `Links`.
+- Display attachments in multiple styles, such as:
+  - `Table`
+  - `Links`
 
 ***
 
 ## How to use
 
-- ### Monitoring and fetching from a specific email address
+- ### 🔍 Monitoring and Fetching from a Specific Email Address
 
-  - Open Email Plugin.
+  1. Open the **Email Plugin**.
+  2. Sign in with your email credentials.
+  3. Enter the email account you want to **monitor for new or unread messages**, then enable **Fetching & Monitoring**.
 
-  - Login to the plugin with your email address and password.
+  #### ✉️ Forwarding Emails to Create Notes
+    If you enter **your own email address** in the **From** field, you can simply **forward emails to yourself**.  
+
+    You can control how the note is created using the following syntax:
+    - **Set note title**  
+      The email subject is used as the note title.
+
+    - **Assign to a notebook**  
+    Add `@notebook-name` to send the note to a specific notebook.
 
-  - Enter the email account you want to start fetching and monitoring `new` or `unread` messages from and click on the `Fetching & Monitoring` toggle.
+    - **Add tags**  
+    Add `#tag-name` to attach tags to the note.
 
-    - If you enter your email address in the `from` field, simply forward the email message to yourself after adding some easy syntax to the end of the email subject, or add this syntax in a new line at the beginning of the message content, and the plugin will handle the rest.
+    - **Create a Todo note**  
+      Start the subject with `!` to create a **Todo** instead of a regular note.
 
-      - **Set a note title** : Change note title by changing the subject of the email.
-      - **Add to a notebook** : Add `@notebook` to send it to a specific notebook.
-      - **Add tags** : Add `#tag` to organize the note with a tag.
 
-        > **For example**: Say you want this email located in the **joplin** and **gmail** folders and also want to add **gmail** and **email** as tags to the note. Just edit the email subject or add a new line at the beginning of the message content like this:
-        >>Email subject: My message @**joplin** @**email** #**gmail** #**email**
-
-        https://user-images.githubusercontent.com/58605547/188909511-479bff3b-bb9c-42da-9d48-a29d8b22fd4b.mp4
-
-    - Otherwise the email messages will be in the `email messages` folder.
+  #### 🧩 Example
+  Suppose you want:
+    - The note to be saved in the **joplin** and **email** notebooks
+    - The note to be tagged with **gmail** and **email**
+    - The note to be created as a **Todo**
+
+  Email subject:
+  `!My message @joplin @email #gmail #email`
 
-***
 
-- ### Monitoring and fetching from a specific mailbox
+  🎥 Demo:
+
+    https://user-images.githubusercontent.com/58605547/188909511-479bff3b-bb9c-42da-9d48-a29d8b22fd4b.mp4
 
-  - Open Email Plugin.
+  #### If no notebook is specified, the note will be placed in the default **Email Messages** folder.
 
-  - Login to the plugin with your email address and password.
+***
 
-  - Select a specific mailbox and notebook in which you want the email messages to be located and click on the `Fetching & Monitoring Mailbox` toggle.
+- ### 📂 Monitoring and Fetching from a Specific Mailbox
 
-***
+  1. Open the **Email Plugin**.
+  2. Sign in with your email credentials.
+  3. Select:
+     - The mailbox you want to monitor
+     - The notebook where notes should be created
+  4. Enable **Fetching & Monitoring Mailbox**.
 
-- ### Upload downloaded email messages
+  All new or unread emails from the selected mailbox will be converted into notes automatically.
 
-  - Open Email Plugin.
+  Notes created from monitored mailboxes will automatically apply the following syntax (`#` for tags, `!` for Todos) without any additional steps.
 
-  - Click on the `convert saved messages` button.
-
-  - Upload `.eml` format files of email messages that you want to convert to notes.
+***
+
+- ### 📥 Uploading Downloaded Email Messages
+  1. Open the **Email Plugin**.
+  2. Click **Convert Saved Messages**.
+  3. Upload email files in `.eml` format.
+  4. Choose:
+     - Target notebook
+     - Tags
+     - Export options
+  5. Click **Convert** to create notes from the uploaded emails.
 
-  - Select a notebook, enter the tags, select the export options, and click on the `convert` button.
 
 ## Important Notes
 

api/Joplin.d.ts

@@ -10,6 +10,8 @@ import JoplinSettings from './JoplinSettings';
 import JoplinContentScripts from './JoplinContentScripts';
 import JoplinClipboard from './JoplinClipboard';
 import JoplinWindow from './JoplinWindow';
+import BasePlatformImplementation from '../BasePlatformImplementation';
+import JoplinImaging from './JoplinImaging';
 /**
  * This is the main entry point to the Joplin API. You can access various services using the provided accessors.
  *
@@ -25,6 +27,7 @@ import JoplinWindow from './JoplinWindow';
 export default class Joplin {
     private data_;
     private plugins_;
+    private imaging_;
     private workspace_;
     private filters_;
     private commands_;
@@ -34,9 +37,11 @@ export default class Joplin {
     private contentScripts_;
     private clipboard_;
     private window_;
-    constructor(implementation: any, plugin: Plugin, store: any);
+    private implementation_;
+    constructor(implementation: BasePlatformImplementation, plugin: Plugin, store: any);
     get data(): JoplinData;
     get clipboard(): JoplinClipboard;
+    get imaging(): JoplinImaging;
     get window(): JoplinWindow;
     get plugins(): JoplinPlugins;
     get workspace(): JoplinWorkspace;
@@ -63,6 +68,13 @@ export default class Joplin {
      * - [fs-extra](https://www.npmjs.com/package/fs-extra)
      *
      * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/nativeModule)
+     *
+     * <span class="platform-desktop">desktop</span>
      */
     require(_path: string): any;
+    versionInfo(): Promise<import("./types").VersionInfo>;
+    /**
+     * Tells whether the current theme is a dark one or not.
+     */
+    shouldUseDarkColors(): Promise<boolean>;
 }

api/JoplinClipboard.d.ts

@@ -1,17 +1,24 @@
+import { ClipboardContent } from './types';
 export default class JoplinClipboard {
     private electronClipboard_;
     private electronNativeImage_;
     constructor(electronClipboard: any, electronNativeImage: any);
     readText(): Promise<string>;
     writeText(text: string): Promise<void>;
+    /** <span class="platform-desktop">desktop</span> */
     readHtml(): Promise<string>;
+    /** <span class="platform-desktop">desktop</span> */
     writeHtml(html: string): Promise<void>;
     /**
      * Returns the image in [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) format.
+     *
+     * <span class="platform-desktop">desktop</span>
      */
     readImage(): Promise<string>;
     /**
      * Takes an image in [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) format.
+     *
+     * <span class="platform-desktop">desktop</span>
      */
     writeImage(dataUrl: string): Promise<void>;
     /**
@@ -20,4 +27,19 @@ export default class JoplinClipboard {
      * For example [ 'text/plain', 'text/html' ]
      */
     availableFormats(): Promise<string[]>;
+    /**
+     * Writes multiple formats to the clipboard simultaneously.
+     * This allows setting both text/plain and text/html at the same time.
+     *
+     * <span class="platform-desktop">desktop</span>
+     *
+     * @example
+     * ```typescript
+     * await joplin.clipboard.write({
+     *   text: 'Plain text version',
+     *   html: '<strong>HTML version</strong>'
+     * });
+     * ```
+     */
+    write(content: ClipboardContent): Promise<void>;
 }

api/JoplinCommands.d.ts

@@ -1,4 +1,5 @@
 import { Command } from './types';
+import Plugin from '../Plugin';
 /**
  * This class allows executing or registering new Joplin commands. Commands
  * can be executed or associated with
@@ -13,13 +14,24 @@ import { Command } from './types';
  * now, are not well documented. You can find the list directly on GitHub
  * though at the following locations:
  *
- * * [Main screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/MainScreen/commands)
+ * * [Main screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/WindowCommandsAndDialogs/commands)
  * * [Global commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/commands)
- * * [Editor commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/NoteEditor/commands/editorCommandDeclarations.ts)
+ * * [Editor commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/NoteEditor/editorCommandDeclarations.ts)
  *
  * To view what arguments are supported, you can open any of these files
  * and look at the `execute()` command.
  *
+ * Note that many of these commands only work on desktop. The more limited list of mobile
+ * commands can be found in these places:
+ *
+ * * [Global commands](https://github.com/laurent22/joplin/tree/dev/packages/app-mobile/commands)
+ * * [Note screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-mobile/components/screens/Note/commands)
+ * * [Editor commands](https://github.com/laurent22/joplin/blob/dev/packages/app-mobile/components/NoteEditor/commandDeclarations.ts)
+ *
+ * Additionally, certain global commands have the same implementation on both platforms:
+ *
+ * * [Shared global commands](https://github.com/laurent22/joplin/tree/dev/packages/lib/commands)
+ *
  * ## Executing editor commands
  *
  * There might be a situation where you want to invoke editor commands
@@ -49,9 +61,10 @@ import { Command } from './types';
  *
  */
 export default class JoplinCommands {
+    private plugin_;
+    constructor(plugin_: Plugin);
     /**
-     * <span class="platform-desktop">desktop</span> Executes the given
-     * command.
+     * Executes the given command.
      *
      * The command can take any number of arguments, and the supported
      * arguments will vary based on the command. For custom commands, this
@@ -70,7 +83,7 @@ export default class JoplinCommands {
      */
     execute(commandName: string, ...args: any[]): Promise<any | void>;
     /**
-     * <span class="platform-desktop">desktop</span> Registers a new command.
+     * Registers a new command.
      *
      * ```typescript
      * // Register a new commmand called "testCommand1"

api/JoplinContentScripts.d.ts

@@ -21,7 +21,8 @@ export default class JoplinContentScripts {
      * for more information.
      *
      * * [View the renderer demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/content_script)
-     * * [View the editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
+     * * [View the editor plugin tutorial](https://joplinapp.org/help/api/tutorials/cm6_plugin)
+     * * [View the legacy editor demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/codemirror_content_script)
      *
      * See also the [postMessage demo](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/post_messages)
      *