@brickert/kerio-connect-api 0.0.7 → 0.0.8

package/index.d.ts

@@ -83,6 +83,7 @@ export interface GenericResponse {
             result?: Array;
             token?: string;
             detail?: string;
+            deleteItems?: number;
         }
     };
 }
@@ -109,6 +110,7 @@ export class Kerio extends WebClient {
     Logs: Logs;
     Domains: Domains;
     Users: Users;
+    MessageQueues: MessageQueues;
 
     login(user: KerioUser): void;
 
@@ -404,4 +406,100 @@ export interface KerioUserStatistic {
         xmpp: number;
         xmpps: number;
     }
-}
+}
+
+export class MessageQueues extends KerioModules {
+    /**
+     * Get a Mapped Array of KerioMessageItems indexed by their ID for messages that are pending to be processed
+     * @returns {Promise<Map<import('../index.d.ts').KerioMessageID, import('../index.d.ts').KerioMessageItem>>}
+     */
+    pending(): Promise<Map<KerioMessageID, KerioMessageItem>>;
+
+    /**
+     * Remove select message(s) that are held in queue/processing queue.
+     * @param messageId Single or Array of KerioMessageID(s)
+     * @returns {Promise<number>} Number of successfully removed messages
+     */
+    removeFromQueue(messageId: KerioMessageID | Array<KerioMessageID>): Promise<number>;
+
+    /**
+     * Remove all message(s) in the queue pending to be processed
+     * @returns {Promise<number>} Number of successfully removed messages
+     */
+    flushQueue(): Promise<number>;
+
+    /**
+     * Manually trigger sending these message(s) before their scheduled re-attempt
+     * @param messageId Single or Array of KerioMessageID(s)
+     * @returns {Promise<void>} Returns void. Access Kerio.MessageQueues.pending() to see any changes, messages not listed there are successfully being placed into the processed queue.
+     */
+    trySendingNow(messageId: KerioMessageID | Array<KerioMessageID>): Promise<void>;
+
+    /**
+     * Get a Mapped Array of KerioMessageItems indexed by their ID for a snapshot of the server's activity on processing messages
+     * @returns {Promise<Map<import('../index.d.ts').KerioMessageID, import('../index.d.ts').KerioMessageProcessedItem>>}
+     */
+    processing(): Promise<Map<KerioMessageID, KerioMessageProcessedItem>>;
+
+    /**
+     * Manually process message(s) now from their current stage.
+     * @returns {Promise<void>} Returns void. Access Kerio.MessageQueues.procesing() to see any changes, messages not listed there are successfully delivered to the destination server.
+     */
+    tryProcessingNow(): Promise<void>;
+}
+
+/**
+ * @example "1a2b3c4d-00000"
+ */
+export type KerioMessageID = string;
+
+export interface KerioMessageItem {
+    id: KerioMessageID;
+    status: string;
+    time: {
+        creationTime: string; //YYYY-MM-DD HH:MM of server's timezone
+        nextTry: string; //YYYY-MM-DD HH:MM of server's timezone
+    };
+    messageSize: {
+        value: number;
+        units: "Bytes"
+    };
+    headers: {
+        from: string;
+        to: string;
+    };
+    authSender: { 
+        address: string; //Authorized SMTP user email address
+        ip: string; //Authorized SMTP user ip address
+    }
+}
+
+export interface KerioMessageProcessedItem {
+    id: KerioMessageID;
+    status: {
+        progress: number; //Current progress in the current status stage
+        stage: KerioMessageProcessStatusEnum;
+        timeInCurrentStatus: string; //in HH:MM:SS format
+    };
+    messageSize: {
+        value: number;
+        units: "Bytes"
+    };
+    headers: {
+        from: string;
+        to: string;
+        destination: string; //Target SMTP server FQDN
+    };
+
+}
+
+/**
+ * msExecuting: General execution/starting state.
+ * msBackup: Message is being backed up.
+ * msContentFiltering: Passing through content/spam filters.
+ * msAntivirusControl: Being scanned for viruses.
+ * msLocalDelivering: Delivering to a mailbox on the local server.
+ * msSmtpDelivering: Attempting delivery to the next hop SMTP server.
+ * msFinishing: Finalizing the delivery/cleanup process.
+ */
+export type KerioMessageProcessStatusEnum = "msExecuting" | "msBackup" | "msContentFiltering" | "msAntivirusControl" | "msLocalDelivering" | "msSmtpDelivering" | "msFinishing";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brickert/kerio-connect-api",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "An unofficial API wrapper for Kerio Connect Mail Server jsonrpc Admin API.",
   "keywords": [
     "kerio",

package/src/kerio.js

@@ -3,6 +3,7 @@ import { Logs } from "./logs.js";
 import { Session } from "./session.js";
 import { Domains } from "./domains.js";
 import { Users } from "./users.js";
+import { MessageQueues } from "./msgqueues.js";
 import { WebClient } from "./client.js";
 import { CronJob } from 'cron';
 import pino from 'pino';
@@ -27,6 +28,7 @@ export class Kerio extends WebClient {
         this.Session = new Session(this);
         this.Domains = new Domains(this);
         this.Users = new Users(this);
+        this.MessageQueues = new MessageQueues(this);
 
         this.logger = pino({
             level: "debug",

package/src/msgqueues.js

@@ -0,0 +1,469 @@
+import { KerioModules } from './modules.js';
+
+export class MessageQueues extends KerioModules {
+
+    /**
+     * Get a Mapped Array of KerioMessageItems indexed by their ID for messages that are pending to be processed
+     * @returns {Promise<Map<import('../index.d.ts').KerioMessageID, import('../index.d.ts').KerioMessageItem>>}
+     */
+    async pending() {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.queued"
+                }
+            }
+
+            let queue_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.get',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    }
+                }
+            });
+
+            let response_body = queue_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                var queueMsgsResult = new Map();
+
+                if (response_body.result.list.length > 0) {
+                    response_body.result.list.forEach(msg => {
+                        
+                        queueMsgsResult.set(msg.id, {
+                            id: msg.id,
+                            status: msg.status,
+                            time: {
+                                created: msg.creationTime,
+                                nextTry: msg.nextTry
+                            },
+                            messageSize: {
+                                value: msg.messageSize.value,
+                                units: msg.messageSize.units
+                            },
+                            headers: {
+                                from: msg.from,
+                                to: msg.to
+                            },
+                            authSender: {
+                                address: msg.authSender,
+                                ip: msg.senderIp
+                            }
+                        });
+                    });
+                }
+
+                this.instance.logger.debug({
+                    name: "KerioQueuedMessagesPending",
+                    message: `listed ${queueMsgsResult.size} queued messages pending to be processed`,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.queued"
+                });
+
+                return queueMsgsResult;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.get'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.list"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Remove select message(s) that are held in the list of queue/processing queue.
+     * @param messageId Single or Array of KerioMessageID(s)
+     * @returns {Promise<number>} Number of successfully removed messages
+     */
+    async removeFromQueue(messageId = null) {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.removeFromQueue"
+                }
+            }
+
+            if (!messageId || (Array.isArray(messageId) && messageId.length == 0)) {
+                throw {
+                    name: "KerioMessageIdError",
+                    message: `Invalid message ID or array of message IDs while processing API method 'Queue.remove'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.removeFromQueue"
+                }
+            }
+
+            //If single message ID string, convert to array of one element
+            if (!Array.isArray(messageId)) {
+                messageId = [messageId];
+            }
+
+            let queue_remove_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.remove',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    },
+                    messageIds: messageId
+                }
+            });
+
+            let response_body = queue_remove_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                this.instance.logger.debug({
+                    name: "KerioQueuedMessagesRemoved",
+                    message: `Removed ${response_body.result.deleteItems} queued messages that were pending to be processed`,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.removeFromQueue"
+                });
+
+                return response_body.result.deleteItems;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.remove'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.removeFromQueue"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Remove all message(s) in the queue pending to be processed
+     * @returns {Promise<number>} Number of successfully removed messages
+     */
+    async flushQueue() {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.flushQueue"
+                }
+            }
+
+            let queue_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.removeAll',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    }
+                }
+            });
+
+            let response_body = queue_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                this.instance.logger.debug({
+                    name: "KerioQueuedMessagesFlush",
+                    message: `Flushed ${response_body.result.deleteItems} queued messages pending to be processed`,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.flushQueue"
+                });
+
+                return response_body.result.deleteItems;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.removeAll'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.flushQueue"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Manually trigger sending these message(s) before their scheduled re-attempt
+     * @param messageId Single or Array of KerioMessageID(s)
+     * @returns {Promise<void>} Returns void. Access Kerio.MessageQueues.queued() to see any changes, messages not listed there are successfully being placed into the processed queue.
+     */
+    async trySendingNow(messageId = null) {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.trySendingNow"
+                }
+            }
+
+            if (!messageId || (Array.isArray(messageId) && messageId.length == 0)) {
+                throw {
+                    name: "KerioMessageIdError",
+                    message: `Invalid message ID or array of message IDs while processing API method 'Queue.tryToSend'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.trySendingNow"
+                }
+            }
+
+            //If single message ID string, convert to array of one element
+            if (!Array.isArray(messageId)) {
+                messageId = [messageId];
+            }
+
+            let try_sending_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.tryToSend',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    },
+                    messageIds: messageId
+                }
+            });
+
+            let response_body = try_sending_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                let debug_msg = "";
+
+                if (Array.isArray(messageId)) {
+                    debug_msg = `Processing ${messageId.length} specified queued messages right now. Message IDs of '${messageId.join(', ')}'`;
+                } else {
+                    debug_msg = `Processing queued message right now. Message ID of '${messageId}'`;
+                }
+
+                this.instance.logger.debug({
+                    name: "KerioQueueTrySendingNowAttempt",
+                    message: debug_msg,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.trySendingNow"
+                });
+
+                return;
+
+            } else {
+
+                if (response_body?.error?.code) {
+                    switch (response_body?.error?.code) {
+                        case 1000:
+                            // One or more Message Ids don't exist or already processed
+                            // Safe to silently error and return as you are intended to do Kerio.MessageQueues.pending() to check the status after.
+                            return;
+                        default:
+                            throw {
+                                name: "KerioRequestError",
+                                message: `Error occured while fetching results from API method 'Queue.tryToSend'`,
+                                type: 'Kerio',
+                                from: "Kerio.MessageQueues.trySendingNow"
+                            }
+                    }
+                }
+
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.tryToSend'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.trySendingNow"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Get a Mapped Array of KerioMessageItems indexed by their ID for a snapshot of the server's activity on processing messages
+     * @returns {Promise<Map<import('../index.d.ts').KerioMessageID, import('../index.d.ts').KerioMessageProcessedItem>>}
+     */
+    async processing() {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.processing"
+                }
+            }
+
+            let process_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.getProcessed',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    }
+                }
+            });
+
+            let response_body = process_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                var processMsgsResult = new Map();
+
+                if (response_body.result.list.length > 0) {
+                    response_body.result.list.forEach(msg => {
+
+                        processMsgsResult.set(msg.id, {
+                            id: msg.id,
+                            status: {
+                                progress: msg.percentage,
+                                stage: msg.status,
+                                timeInCurrentStatus: msg.time
+                            },
+                            messageSize: {
+                                value: msg.messageSize.value,
+                                units: msg.messageSize.units
+                            },
+                            headers: {
+                                from: msg.from,
+                                to: msg.to,
+                                destination: msg.server
+                            }
+                        });
+                    });
+                }
+
+                this.instance.logger.debug({
+                    name: "KerioQueuedMessages",
+                    message: `listed ${processMsgsResult.size} processing messages`,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.processing"
+                });
+
+                return processMsgsResult;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.get'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.list"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Manually process message(s) now from their current stage.
+     * @returns {Promise<void>} Returns void. Access Kerio.MessageQueues.procesing() to see any changes, messages not listed there are successfully delivered to the destination server.
+     */
+    async tryProcessingNow() {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.tryProcessingNow"
+                }
+            }
+
+            let try_process_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Queue.run',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                    }
+                }
+            });
+
+            let response_body = try_process_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                this.instance.logger.debug({
+                    name: "KerioQueueProcessingNow",
+                    message: `Force processing messages`,
+                    type: "Kerio",
+                    from: "Kerio.MessageQueues.tryProcessingNow"
+                });
+
+                return;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Queue.run'`,
+                    type: 'Kerio',
+                    from: "Kerio.MessageQueues.tryProcessingNow"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+}