n8n-nodes-jmap 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+# n8n-nodes-jmap
+
+Community node for [n8n](https://n8n.io/) to interact with JMAP email servers ([RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620)/[RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621)).
+
+Compatible with:
+- [Apache James](https://james.apache.org/)
+- [Twake Mail](https://twake.app/)
+- [Stalwart Mail Server](https://stalw.art/)
+- [Fastmail](https://www.fastmail.com/)
+- Any JMAP-compliant email server
+
+## Installation
+
+### Community Nodes (Recommended)
+
+1. Go to **Settings > Community Nodes**
+2. Select **Install**
+3. Enter `n8n-nodes-jmap`
+4. Agree to the risks and click **Install**
+
+### Manual Installation
+
+```bash
+cd ~/.n8n/nodes
+npm install n8n-nodes-jmap
+```
+
+Then restart n8n.
+
+---
+
+## Authentication
+
+This node supports **three authentication methods** to connect to JMAP servers.
+
+### Method 1: Basic Authentication
+
+The simplest method using email and password directly.
+
+**Configuration:**
+1. Create a new **JMAP API** credential
+2. Set **Authentication Method** to `Basic Auth`
+3. Fill in:
+   - **JMAP Server URL**: `https://jmap.example.com/jmap`
+   - **Email**: `user@example.com`
+   - **Password**: Your password
+
+**Use case:** Development, testing, or servers without OAuth2 support.
+
+---
+
+### Method 2: Bearer Token
+
+Use a pre-obtained access token (e.g., from an external OAuth2 flow).
+
+**Configuration:**
+1. Create a new **JMAP API** credential
+2. Set **Authentication Method** to `Bearer Token`
+3. Fill in:
+   - **JMAP Server URL**: `https://jmap.example.com/jmap`
+   - **Access Token**: Your JWT or access token
+
+**Use case:** Integration with existing authentication systems, tokens obtained via scripts or other workflows.
+
+---
+
+### Method 3: OAuth2 / OIDC with PKCE
+
+Full OAuth2 Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the **recommended method for production** as it provides:
+- Automatic token refresh
+- No password storage in n8n
+- Secure SSO integration
+
+**Configuration:**
+1. Create a new **JMAP OAuth2 API** credential
+2. Fill in:
+   - **Client ID**: Your OIDC client ID
+   - **Client Secret**: Leave empty for public clients (PKCE)
+   - **Authorization URL**: `https://sso.example.com/oauth2/authorize`
+   - **Access Token URL**: `https://sso.example.com/oauth2/token`
+   - **JMAP Server URL**: `https://jmap.example.com/jmap`
+3. Click **Connect** to initiate the OAuth2 flow
+4. Log in with your SSO credentials
+
+**Compatible Identity Providers:**
+- [LemonLDAP::NG](https://lemonldap-ng.org/)
+- [Keycloak](https://www.keycloak.org/)
+- [Auth0](https://auth0.com/)
+- Any OAuth2/OIDC compliant provider
+
+#### Example: LemonLDAP::NG Configuration
+
+```
+Authorization URL: https://sso.example.com/oauth2/authorize
+Access Token URL:  https://sso.example.com/oauth2/token
+Client ID:         my-n8n-client
+Scope:             openid email profile offline_access
+```
+
+#### Example: Keycloak Configuration
+
+```
+Authorization URL: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth
+Access Token URL:  https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token
+Client ID:         n8n-jmap-client
+Scope:             openid email profile offline_access
+```
+
+---
+
+## Nodes
+
+### JMAP Node
+
+Main node for email operations.
+
+| Resource | Operation | Description |
+|----------|-----------|-------------|
+| Email | Send | Send a new email |
+| Email | Reply | Reply to an existing email |
+| Email | Get | Retrieve an email by ID |
+| Email | Get Many | List emails (with optional mailbox filter) |
+| Email | Create Draft | Create a draft without sending |
+| Email | Delete | Delete an email |
+| Email | Mark as Read | Mark email as read |
+| Email | Mark as Unread | Mark email as unread |
+| Email | Move | Move email to another mailbox |
+| Email | Add Label | Add a mailbox label to an email |
+| Email | Remove Label | Remove a mailbox label from an email |
+| Email | Get Labels | Get all labels for an email |
+| Mailbox | Get | Get mailbox details by ID |
+| Mailbox | Get Many | List all mailboxes |
+| Thread | Get | Get thread details by ID |
+| Thread | Get Many | Get all emails in a thread |
+
+### JMAP Trigger Node
+
+Polling-based trigger for new emails.
+
+| Event | Description |
+|-------|-------------|
+| New Email | Triggers on any new email |
+| New Email in Mailbox | Triggers on new email in a specific mailbox |
+
+**Options:**
+- **Simple Output**: Return simplified email data
+- **Include Attachments Info**: Include attachment metadata
+- **Mark as Read**: Automatically mark fetched emails as read
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Development mode (watch)
+npm run dev
+
+# Lint
+npm run lint
+
+# Format code
+npm run format
+```
+
+### Local Testing
+
+```bash
+# Link for local n8n development
+npm link
+
+# In your n8n installation
+npm link n8n-nodes-jmap
+```
+
+---
+
+## JMAP Protocol
+
+JMAP (JSON Meta Application Protocol) is a modern, efficient alternative to IMAP for email access:
+
+- **Stateless**: No persistent connections required
+- **JSON-based**: Easy to parse and debug
+- **Efficient**: Batched requests, delta sync
+- **Standardized**: RFC 8620 (Core) and RFC 8621 (Mail)
+
+Learn more: [jmap.io](https://jmap.io/)
+
+---
+
+## License
+
+AGPL-3.0
+
+---
+
+## Author
+
+[Michel-Marie Maudet](https://github.com/mmaudet)

package/dist/credentials/JmapApi.credentials.d.ts

@@ -0,0 +1,13 @@
+import { ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+/**
+ * JMAP API Credentials for Basic Auth or Bearer Token authentication
+ *
+ * For OAuth2/OIDC with LemonLDAP, use the JmapOAuth2Api credentials instead.
+ */
+export declare class JmapApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+}

package/dist/credentials/JmapApi.credentials.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JmapApi = void 0;
+/**
+ * JMAP API Credentials for Basic Auth or Bearer Token authentication
+ *
+ * For OAuth2/OIDC with LemonLDAP, use the JmapOAuth2Api credentials instead.
+ */
+class JmapApi {
+    constructor() {
+        this.name = 'jmapApi';
+        this.displayName = 'JMAP API';
+        this.documentationUrl = 'https://jmap.io/spec-core.html';
+        this.properties = [
+            {
+                displayName: 'JMAP Server URL',
+                name: 'serverUrl',
+                type: 'string',
+                default: 'https://jmap.example.com/jmap',
+                placeholder: 'https://jmap.example.com/jmap',
+                description: 'The base URL of the JMAP server',
+                required: true,
+            },
+            {
+                displayName: 'Authentication Method',
+                name: 'authMethod',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Basic Auth',
+                        value: 'basicAuth',
+                        description: 'Authenticate with email and password',
+                    },
+                    {
+                        name: 'Bearer Token',
+                        value: 'bearerToken',
+                        description: 'Authenticate with an existing access token',
+                    },
+                ],
+                default: 'basicAuth',
+            },
+            // Basic Auth fields
+            {
+                displayName: 'Email',
+                name: 'email',
+                type: 'string',
+                placeholder: 'user@example.com',
+                default: '',
+                required: true,
+                displayOptions: {
+                    show: {
+                        authMethod: ['basicAuth'],
+                    },
+                },
+            },
+            {
+                displayName: 'Password',
+                name: 'password',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                displayOptions: {
+                    show: {
+                        authMethod: ['basicAuth'],
+                    },
+                },
+            },
+            // Bearer Token field
+            {
+                displayName: 'Access Token',
+                name: 'accessToken',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                description: 'The access token (e.g., from OAuth2/OIDC)',
+                displayOptions: {
+                    show: {
+                        authMethod: ['bearerToken'],
+                    },
+                },
+            },
+        ];
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.serverUrl}}',
+                url: '/session',
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                },
+                auth: {
+                    username: '={{$credentials.email}}',
+                    password: '={{$credentials.password}}',
+                },
+            },
+        };
+    }
+}
+exports.JmapApi = JmapApi;

package/dist/credentials/JmapOAuth2Api.credentials.d.ts

@@ -0,0 +1,27 @@
+import type { ICredentialType, INodeProperties, Icon } from 'n8n-workflow';
+/**
+ * JMAP OAuth2 API Credentials for LemonLDAP::NG SSO
+ *
+ * Uses Authorization Code Flow with PKCE (public client, no secret required)
+ */
+export declare class JmapOAuth2Api implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    extends: string[];
+    icon: Icon;
+    properties: INodeProperties[];
+    oauth2: {
+        tokenExpiredStatusCode: number;
+        grantType: string;
+        scope: string;
+        tokenRequestMethod: "POST";
+        authorizeUrl: {
+            url: string;
+        };
+        accessTokenUrl: {
+            url: string;
+        };
+        clientAuthentication: "body";
+    };
+}

package/dist/credentials/JmapOAuth2Api.credentials.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JmapOAuth2Api = void 0;
+/**
+ * JMAP OAuth2 API Credentials for LemonLDAP::NG SSO
+ *
+ * Uses Authorization Code Flow with PKCE (public client, no secret required)
+ */
+class JmapOAuth2Api {
+    constructor() {
+        this.name = 'jmapOAuth2Api';
+        this.displayName = 'JMAP OAuth2 API';
+        this.documentationUrl = 'https://jmap.io/spec-core.html';
+        this.extends = ['oAuth2Api'];
+        this.icon = {
+            light: 'file:../nodes/Jmap/jmap.svg',
+            dark: 'file:../nodes/Jmap/jmap.svg',
+        };
+        this.properties = [
+            {
+                displayName: 'Client ID',
+                name: 'clientId',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'my-client-id',
+                hint: 'OIDC Client ID registered with your identity provider',
+            },
+            {
+                displayName: 'Client Secret',
+                name: 'clientSecret',
+                type: 'string',
+                typeOptions: { password: true },
+                default: '',
+                required: false,
+                hint: 'Leave empty for public clients using PKCE',
+            },
+            {
+                displayName: 'Authorization URL',
+                name: 'authUrl',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'https://sso.example.com/oauth2/authorize',
+                hint: 'OAuth2/OIDC authorization endpoint',
+            },
+            {
+                displayName: 'Access Token URL',
+                name: 'accessTokenUrl',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'https://sso.example.com/oauth2/token',
+                hint: 'OAuth2/OIDC token endpoint',
+            },
+            {
+                displayName: 'JMAP Server URL',
+                name: 'jmapServerUrl',
+                type: 'string',
+                default: '',
+                required: true,
+                placeholder: 'https://jmap.example.com/jmap',
+                hint: 'The JMAP API endpoint URL',
+            },
+            // OAuth2 configuration - hidden fields
+            {
+                displayName: 'Scope',
+                name: 'scope',
+                type: 'hidden',
+                default: 'openid email profile offline_access',
+            },
+            {
+                displayName: 'Auth URI Query Parameters',
+                name: 'authQueryParameters',
+                type: 'hidden',
+                default: '',
+            },
+            {
+                displayName: 'Grant Type',
+                name: 'grantType',
+                type: 'hidden',
+                default: 'pkce',
+            },
+            {
+                displayName: 'Authentication',
+                name: 'authentication',
+                type: 'hidden',
+                default: 'body',
+            },
+        ];
+        // OAuth2 flow configuration
+        this.oauth2 = {
+            tokenExpiredStatusCode: 401,
+            grantType: 'pkce',
+            scope: 'openid email profile offline_access',
+            tokenRequestMethod: 'POST',
+            authorizeUrl: { url: '={{ $credentials.authUrl }}' },
+            accessTokenUrl: { url: '={{ $credentials.accessTokenUrl }}' },
+            clientAuthentication: 'body',
+        };
+    }
+}
+exports.JmapOAuth2Api = JmapOAuth2Api;

package/dist/nodes/Jmap/GenericFunctions.d.ts

@@ -0,0 +1,121 @@
+import type { IExecuteFunctions, ILoadOptionsFunctions, IPollFunctions, IDataObject } from 'n8n-workflow';
+export interface IJmapSession {
+    accounts: {
+        [key: string]: IJmapAccount;
+    };
+    primaryAccounts: {
+        [key: string]: string;
+    };
+    username: string;
+    apiUrl: string;
+    downloadUrl: string;
+    uploadUrl: string;
+    eventSourceUrl: string;
+    state: string;
+    capabilities: {
+        [key: string]: IDataObject;
+    };
+}
+export interface IJmapAccount {
+    name: string;
+    isPersonal: boolean;
+    isReadOnly: boolean;
+    accountCapabilities: {
+        [key: string]: IDataObject;
+    };
+}
+export interface IJmapRequest {
+    using: string[];
+    methodCalls: [string, IDataObject, string][];
+}
+export interface IJmapResponse {
+    methodResponses: [string, IDataObject, string][];
+    sessionState: string;
+}
+export declare const JMAP_CAPABILITIES: {
+    CORE: string;
+    MAIL: string;
+    SUBMISSION: string;
+    VACATION_RESPONSE: string;
+    JAMES_SHARES: string;
+    JAMES_QUOTA: string;
+};
+/**
+ * Get JMAP session from the server
+ */
+export declare function getJmapSession(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions): Promise<IJmapSession>;
+/**
+ * Make a JMAP API request
+ */
+export declare function jmapApiRequest(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, methodCalls: [string, IDataObject, string][], using?: string[]): Promise<IJmapResponse>;
+/**
+ * Get the primary account ID for mail
+ */
+export declare function getPrimaryAccountId(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions): Promise<string>;
+/**
+ * Get all mailboxes for an account
+ */
+export declare function getMailboxes(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string): Promise<IDataObject[]>;
+/**
+ * Find a mailbox by name
+ */
+export declare function findMailboxByName(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string, name: string): Promise<IDataObject | undefined>;
+/**
+ * Find a mailbox by role
+ */
+export declare function findMailboxByRole(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string, role: string): Promise<IDataObject | undefined>;
+/**
+ * Query emails with filters
+ */
+export declare function queryEmails(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string, filter?: IDataObject, sort?: IDataObject[], limit?: number, position?: number): Promise<{
+    ids: string[];
+    total: number;
+}>;
+/**
+ * Get emails by IDs
+ */
+export declare function getEmails(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string, ids: string[], properties?: string[], fetchTextBodyValues?: boolean, fetchHTMLBodyValues?: boolean): Promise<IDataObject[]>;
+/**
+ * Create and send an email
+ */
+export declare function sendEmail(this: IExecuteFunctions, accountId: string, email: IDataObject, identityId: string): Promise<IDataObject>;
+/**
+ * Create a draft email
+ */
+export declare function createDraft(this: IExecuteFunctions, accountId: string, email: IDataObject): Promise<IDataObject>;
+/**
+ * Get identities
+ */
+export declare function getIdentities(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string): Promise<IDataObject[]>;
+/**
+ * Update email keywords
+ */
+export declare function updateEmailKeywords(this: IExecuteFunctions, accountId: string, emailId: string, keywords: IDataObject): Promise<IDataObject>;
+/**
+ * Move email to a different mailbox
+ */
+export declare function moveEmail(this: IExecuteFunctions, accountId: string, emailId: string, targetMailboxId: string): Promise<IDataObject>;
+/**
+ * Add a label (mailbox) to an email
+ */
+export declare function addLabel(this: IExecuteFunctions, accountId: string, emailId: string, mailboxId: string): Promise<IDataObject>;
+/**
+ * Remove a label (mailbox) from an email
+ */
+export declare function removeLabel(this: IExecuteFunctions, accountId: string, emailId: string, mailboxId: string): Promise<IDataObject>;
+/**
+ * Get labels (mailboxes) for an email with their names
+ */
+export declare function getLabels(this: IExecuteFunctions, accountId: string, emailId: string): Promise<IDataObject[]>;
+/**
+ * Delete emails
+ */
+export declare function deleteEmails(this: IExecuteFunctions, accountId: string, emailIds: string[]): Promise<IDataObject>;
+/**
+ * Get threads
+ */
+export declare function getThreads(this: IExecuteFunctions | ILoadOptionsFunctions | IPollFunctions, accountId: string, ids: string[]): Promise<IDataObject[]>;
+/**
+ * Download an attachment blob
+ */
+export declare function downloadBlob(this: IExecuteFunctions, accountId: string, blobId: string, name: string, type: string): Promise<Buffer>;