@brickert/kerio-connect-api 0.0.4 → 0.0.6

package/index.d.ts

@@ -72,8 +72,9 @@ export interface GenericResponse {
             }
         }
         result?: {
+            viewport?: Array;
             userDetails?: object;
-            list?: Array<object> | Array<IPAddressGroupItem>;
+            list?: Array;
             totalItems?: number;
             errors?: Array<{
                 code: number,
@@ -81,6 +82,7 @@ export interface GenericResponse {
             }>;
             result?: Array;
             token?: string;
+            detail?: string;
         }
     };
 }
@@ -104,6 +106,8 @@ export class Kerio extends WebClient {
 
     IPAddressGroups: IPAddressGroup;
     Session: Session;
+    Logs: Logs;
+    Domains: Domains;
 
     login(user: KerioUser): void;
 
@@ -243,4 +247,105 @@ export interface KerioInstanceUserResponse {
     roles: {
         userRole: string;
     }
+}
+
+export class Logs extends KerioModules {
+    /**
+     * Get logs from the specified log and number of most recent lines. Defaults to the last 5 security logs.
+     * @param logName 
+     * @param line_count
+     * @returns An array of log lines structured with timestamp (DD/MMM/YYYY HH:MM:SS) in Kerio Connect's server timezone and the message
+     */
+    list(logName: logName, line_count: number): Promise<Array<LogLineObject>>;
+}
+
+export type logName = "config" | "debug" | "error" | "mail" | "security" | "spam" | "warning";
+
+export interface LogLineObject {
+    timestamp: string;
+    message: string;
+}
+
+export class Domains extends KerioModules {
+    /**
+     * Get a Mapped Array of KerioDomainItems indexed by their ID
+     * @returns {Promise<Map<import('../index.d.ts').KerioDomainID, import('../index.d.ts').KerioDomainItem>>}
+     */
+    list(): Promise<Map<KerioDomainID, KerioDomainItem>>;
+    /**
+     * Get the DKIM DNS TXT record object for the domain name. TXT record name & value pair, selector name, and raw public key string.
+     * @param {string} domainName Name of the domain
+     * @returns {Promise<import('../index.d.ts').DKIMRecord>}
+     */
+    getDKIMDNSRecord(domainName: string): Promise<DKIMRecord>;
+}
+
+/**
+ * @example "keriodb://domain/1234-5678-901-2345"
+ */
+export type KerioDomainID = string;
+
+export interface KerioDomainItem {
+    id: KerioDomainID;
+    name: string;
+    description: string;
+    primary: boolean;
+    userMaxCount: number;
+    passwords: {
+        expiration: {
+            enabled: boolean;
+            days: number;
+        };
+        historyCount: number;
+        enforceComplexity: boolean;
+        minLength: number;
+    };
+    messages: {
+        outgoingLimit: {
+            enabled: boolean,
+            size: number;
+            units: string;
+        };
+        autoClean: {
+            deleted: {
+                enabled: boolean;
+                days: number;
+            };
+            junk: {
+                enabled: boolean;
+                days: number;
+            };
+            sent: {
+                enabled: boolean;
+                days: number;
+            };
+            other: {
+                enabled: boolean;
+                days: number;
+            };
+        };
+        deleteRecovery: {
+            enabled: boolean;
+            days: number;
+        }
+    };
+    DKIMenabled: boolean;
+}
+
+export interface DKIMRecord {
+    /**
+     * @example 'mail._domainkey.example.org'
+     */
+    name: string;
+    selector: string;
+    type: "TXT";
+    /**
+     * @example 'v=DKIM1; p=1234'
+     */
+    value: string;
+    /**
+     * The 'p=' section of the TXT record value
+     * @example 'abcdefg1234567'
+     */
+    raw_public_key: string;
 }

package/package.json

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

package/src/domains.js

@@ -0,0 +1,207 @@
+import { KerioModules } from './modules.js';
+
+export class Domains extends KerioModules {
+
+    /**
+     * Get a Mapped Array of KerioDomainItems indexed by their ID
+     * @returns {Promise<Map<import('../index.d.ts').KerioDomainID, import('../index.d.ts').KerioDomainItem>>}
+     */
+    async list() {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.list"
+                }
+            }
+
+            let domain_list_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Domains.get',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+                        orderBy: [
+                            {
+                                columnName: "name",
+                                direction: "Asc"
+                            }
+                        ]
+                    }
+                }
+            });
+
+            let response_body = domain_list_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                var domainsListResult = new Map();
+
+                if (response_body.result.list.length > 0) {
+
+                    response_body.result.list.forEach(domain => {
+                        /**
+                         * @type {import('../index.d.ts').KerioDomainItem}
+                         */
+                        var obj = {
+                            id: domain.id,
+                            name: domain.name,
+                            description: domain.description,
+                            primary: domain.isPrimary,
+                            userMaxCount: domain.userMaxCount,
+                            passwords: {
+                                expiration: {
+                                    enabled: domain.passwordExpirationEnabled,
+                                    days: domain.passwordExpirationEnabled
+                                },
+                                historyCount: domain.passwordHistoryCount,
+                                enforceComplexity: domain.passwordComplexityEnabled,
+                                minLength: domain.passwordMinimumLength
+                            },
+                            messages: {
+                                outgoingLimit: {
+                                    enabled: domain.outgoingMessageLimit.isActive,
+                                    size: domain.outgoingMessageLimit.limit.value,
+                                    units: domain.outgoingMessageLimit.limit.units
+                                },
+                                autoClean: {
+                                    deleted: {
+                                        enabled: domain.deletedItems.isEnabled,
+                                        days: domain.deletedItems.days
+                                    },
+                                    junk: {
+                                        enabled: domain.junkEmail.isEnabled,
+                                        days: domain.junkEmail.days
+                                    },
+                                    sent: {
+                                        enabled: domain.sentItems.isEnabled,
+                                        days: domain.sentItems.days
+                                    },
+                                    other: {
+                                        enabled: domain.autoDelete.isEnabled,
+                                        days: domain.autoDelete.days
+                                    }
+                                },
+                                deleteRecovery: {
+                                    enabled: domain.keepForRecovery.isEnabled,
+                                    days: domain.keepForRecovery.days
+                                }
+                            },
+                            DKIMenabled: domain.isDkimEnabled
+                        }
+
+                        domainsListResult.set(domain.id, obj);
+                    });
+                }
+
+                this.instance.logger.debug({
+                    name: "KerioDomainsList",
+                    message: `listed ${domainsListResult.size} domains entities`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.list"
+                });
+
+                return domainsListResult;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Domains.get' for all domains`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.list"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    /**
+     * Get the DKIM DNS TXT record object for the domain name. TXT record name & value pair, selector name, and raw public key string.
+     * @param {string} domainName Name of the domain
+     * @returns {Promise<import('../index.d.ts').DKIMRecord>}
+     */
+    async getDKIMDNSRecord(domainName = null) {
+        try {
+
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.getDKIMDNSRecord"
+                }
+            }
+
+            if (!domainName) {
+                throw {
+                    name: "KerioDKIMDomainNameError",
+                    message: `Invalid Domain Name while processing API method 'Domains.getDkimDnsRecord' for domain '${domainName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.getDKIMDNSRecord"
+                }
+            }
+
+            let dkim_record_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Domains.getDkimDnsRecord',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    domain: domainName
+                }
+            });
+
+            let response_body = dkim_record_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                let _record = response_body.result.detail;
+                let name = _record.split("\n")[0].split(":")[1].trim();
+                let value = _record.split("\n")[1].split("value:")[1].trim().split(";").join("; ");
+                let raw_key = value.split("; p=")[1];
+
+                this.instance.logger.debug({
+                    name: "KerioDKIMDomainRecord",
+                    message: `A DKIM record was obtained. Excerpt of: ${raw_key.substring(0, 10)}`,
+                    type: "Kerio",
+                    from: "Kerio.Domains.getDKIMDNSRecord"
+                });
+
+                return {
+                    name,
+                    selector: name.split(".")[0],
+                    type: "TXT",
+                    value,
+                    raw_public_key: raw_key
+                }
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Domains.getDkimDnsRecord' for domain '${domainName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Domains.getDKIMDNSRecord"
+                }
+            }
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+}

package/src/ipaddressgroups.js

@@ -358,6 +358,13 @@ export class IPAddressGroup extends KerioModules {
         }
     }
 
+    /**
+     * Remove IPAddressGroupItem(s) of type 'host' by the description name from this group name. TAKE CARE as this will remove all items upto the specified max limit that share the same name. You may limit number of items to remove. They are sorted by their unique ID.
+     * @param {string} description Name of the group item(s)
+     * @param {string} group_name Name of the IPAddressGroup string to remove from
+     * @param {number} remove_limit Max number of group items to remove upto. Specifying -1 will remove ALL by the description name
+     * @returns Returns an array of host IP addresses that were removed
+     */
     async removeHostFromIPAddressGroupByDesc(description = null, group_name = null, remove_limit = 1) {
         try {
 

package/src/kerio.js

@@ -1,5 +1,7 @@
 import { IPAddressGroup } from "./ipaddressgroups.js";
+import { Logs } from "./logs.js";
 import { Session } from "./session.js";
+import { Domains } from "./domains.js";
 import { WebClient } from "./client.js";
 import { CronJob } from 'cron';
 import pino from 'pino';
@@ -20,8 +22,9 @@ export class Kerio extends WebClient {
         this.userAgent = userAgent;
 
         this.IPAddressGroups = new IPAddressGroup(this);
-
+        this.Logs = new Logs(this);
         this.Session = new Session(this);
+        this.Domains = new Domains(this);
 
         this.logger = pino({
             level: "debug",

package/src/logs.js

@@ -0,0 +1,107 @@
+import { KerioModules } from './modules.js';
+
+/**
+ * @type {import('../index.d.ts').Logs}
+ */
+export class Logs extends KerioModules {
+
+    /**
+     * Get logs from the specified log and number of most recent lines. Defaults to the last 5 security logs.
+     * @param {import('../index.d.ts').logName} logName
+     * @param {number} line_count 
+     * @returns {Promise<Array<import('../index.d.ts').LogLineObject>>} An array of log lines structured with timestamp (DD/MMM/YYYY HH:MM:SS) in Kerio Connect's server timezone and the message
+     */
+    async list(logName = "security", line_count = 5) {
+        try {
+
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.Logs.list"
+                }
+            }
+
+            if (!Number.isInteger(line_count) && line_count < 0) {
+                throw {
+                    name: "KerioLogListCountError",
+                    message: `Invalid log line count while processing API method 'Logs.get' for log '${logName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Logs.list"
+                }
+            }
+
+            if (!["config", "debug", "error", "mail", "security", "spam", "warning"].includes(logName)) {
+                throw {
+                    name: "KerioLogNameError",
+                    message: `Invalid log name while processing API method 'Logs.get' for log '${logName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Logs.list"
+                }
+            }
+
+            let log_list_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Logs.get',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    logName: logName,
+                    fromLine : -1,
+                    countLines: line_count
+                }
+            });
+
+            let response_body = log_list_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                var logLinesResult = new Array();
+
+                if (response_body.result.viewport.length > 0) {
+
+                    response_body.result.viewport.forEach(line => {
+
+                        let timestamp_string = line.content.split("]")[0];
+                        timestamp_string = timestamp_string.substring(1, timestamp_string.length).trim();
+
+                        let message = line.content.split("]")[1].trim();
+
+                        logLinesResult.push({
+                            timestamp: timestamp_string,
+                            message
+                        });
+
+                    });
+                }
+
+                this.instance.logger.debug({
+                    name: "KerioLogsList",
+                    message: `listed ${logLinesResult.length} log lines from Log '${logName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Logs.list"
+                });
+
+                return logLinesResult;
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'Logs.get' for log '${logName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Logs.list"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+}