@brickert/kerio-connect-api 0.0.5 → 0.0.7

package/index.d.ts

@@ -74,7 +74,7 @@ export interface GenericResponse {
         result?: {
             viewport?: Array;
             userDetails?: object;
-            list?: Array<object> | Array<IPAddressGroupItem>;
+            list?: Array;
             totalItems?: number;
             errors?: Array<{
                 code: number,
@@ -82,6 +82,7 @@ export interface GenericResponse {
             }>;
             result?: Array;
             token?: string;
+            detail?: string;
         }
     };
 }
@@ -106,6 +107,8 @@ export class Kerio extends WebClient {
     IPAddressGroups: IPAddressGroup;
     Session: Session;
     Logs: Logs;
+    Domains: Domains;
+    Users: Users;
 
     login(user: KerioUser): void;
 
@@ -262,4 +265,143 @@ export type logName = "config" | "debug" | "error" | "mail" | "security" | "spam
 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;
+}
+
+export class Users extends KerioModules {
+    /**
+     * Get a Mapped Array of KerioUserItems indexed by their ID for the specified domain name
+     * @param {string} domainName Name of the domain
+     * @returns {Promise<Map<import('../index.d.ts').KerioUserID, import('../index.d.ts').KerioUserItem>>}
+     */
+    list(domainName: string): Promise<Map<KerioUserID, KerioUserItem>>;
+
+    /**
+     * Get statistics of the Kerio User. Such as mailbox size and last login timestamp in server's local time zone
+     * @param kerioUserID Kerio user UUID
+     */
+    getStatistics(kerioUserID: KerioUserID): Promise<KerioUserStatistic>;
+}
+
+/**
+ * @example "keriodb://user/1234-5678-901-2345/1234-5678-901"
+ */
+export type KerioUserID = string;
+
+export interface KerioUserItem {
+    id: string;
+    domainId: string;
+    loginName: string;
+    fullName: string;
+    description: string;
+    enabled: boolean;
+    primaryEmailAddress: string; //loginName + domainName;
+}
+
+export interface KerioUserStatistic {
+    storage: {
+        items: number;
+        value: number;
+        units: "Bytes" | string;
+    },
+    lastLogin: string; //YYYY-MM-DD HH:MM in local server time
+    loginCount: {
+        pop3: number;
+        pop3s: number;
+        imap: number;
+        imaps: number;
+        http: number;
+        https: number;
+        ldap: number;
+        ldaps: number;
+        nntp: number;
+        nntps: number;
+        activeSync: number;
+        secureActiveSync: number;
+        xmpp: number;
+        xmpps: number;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brickert/kerio-connect-api",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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/kerio.js

@@ -1,6 +1,8 @@
 import { IPAddressGroup } from "./ipaddressgroups.js";
 import { Logs } from "./logs.js";
 import { Session } from "./session.js";
+import { Domains } from "./domains.js";
+import { Users } from "./users.js";
 import { WebClient } from "./client.js";
 import { CronJob } from 'cron';
 import pino from 'pino';
@@ -21,10 +23,10 @@ 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.Users = new Users(this);
 
         this.logger = pino({
             level: "debug",

package/src/logs.js

@@ -1,15 +1,15 @@
 import { KerioModules } from './modules.js';
 
 /**
- * @type {import('../index.js').Logs}
+ * @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.js').logName} logName
+     * @param {import('../index.d.ts').logName} logName
      * @param {number} line_count 
-     * @returns {Promise<Array<import('../index.js').LogLineObject>>} An array of log lines structured with timestamp (DD/MMM/YYYY HH:MM:SS) in Kerio Connect's server timezone and the message
+     * @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 {

package/src/users.js

@@ -0,0 +1,208 @@
+import { KerioModules } from './modules.js';
+
+export class Users extends KerioModules {
+
+    /**
+     * Get a Mapped Array of KerioUserItems indexed by their ID for the specified domain name. Does not include aliases or user groups.
+     * @param {string} domainName Name of the domain
+     * @returns {Promise<Map<import('../index.d.ts').KerioUserID, import('../index.d.ts').KerioUserItem>>}
+     */
+    async list(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.Users.list"
+                }
+            }
+
+            if (!domainName) {
+                throw {
+                    name: "KerioDomainNameUserError",
+                    message: `Invalid Domain Name to find Domain ID while processing API method 'Users.get' for domain '${domainName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Users.list"
+                }
+            }
+
+            let domains = await this.instance.Domains.list();
+
+            if (domains.size != 0) {
+            
+                let domainId = Array.from(domains.values()).find(d => d.name.toLowerCase() == domainName.toLowerCase()).id;
+
+                let users_response = await this.sessionedRequest({
+                    http_method: 'POST',
+                    api_method: 'Users.get',
+                    auth: {
+                        cookie: this.instance.session_cookie,
+                        token: this.instance.x_token
+                    },
+                    body_params: {
+                        query: {
+                        },
+                        domainId: domainId
+                    }
+                });
+
+                let response_body = users_response._body;
+
+                if (!response_body.result?.errors && !response_body?.error) {
+                    
+                    var userListResult = new Map();
+
+                    if (response_body.result.list.length > 0) {
+
+                        response_body.result.list.forEach(user => {
+                            /**
+                            * @type {import('../index.d.ts').KerioUserItem}
+                            */
+                            var obj = {
+                                id: user.id,
+                                domainId: user.domainId,
+                                loginName: user.loginName,
+                                fullName: user.fullName,
+                                description: user.description,
+                                enabled: user.isEnabled,
+                                primaryEmailAddress: `${user.loginName}@${domainName}`
+                            }
+
+                            userListResult.set(user.id, obj);
+                        });
+                    }
+
+                    return userListResult;
+
+                } else {
+                    throw {
+                        name: "KerioRequestError",
+                        message: `Error occured while fetching results from API method 'Users.get' for domain ${domainName}`,
+                        type: 'Kerio',
+                        from: "Kerio.Users.list"
+                    }
+                }
+
+            } else {
+                throw {
+                    name: "KerioDomainError",
+                    message: `Domain Name not found to find Domain ID while processing API method 'Users.get' for domain '${domainName}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Users.list"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+
+    async getStatistics(kerioUserID = null) {
+        try {
+            if (!this.instance.logged_in) {
+
+                this.reset();
+
+                throw {
+                    name: "KerioClientSessionError",
+                    message: `Kerio session invalid. Try logging in again.`,
+                    type: 'Kerio',
+                    from: "Kerio.Users.getStatistics"
+                }
+            }
+
+            if (!kerioUserID || !kerioUserID.startsWith("keriodb://user/")) {
+                throw {
+                    name: "KerioUserIDError",
+                    message: `Invalid User ID while processing API method 'Users.getStatistics' for user ID '${kerioUserID}'`,
+                    type: 'Kerio',
+                    from: "Kerio.Users.getStatistics"
+                }
+            }
+
+            let user_stats_response = await this.sessionedRequest({
+                http_method: 'POST',
+                api_method: 'Users.getStatistics',
+                auth: {
+                    cookie: this.instance.session_cookie,
+                    token: this.instance.x_token
+                },
+                body_params: {
+                    query: {
+
+                    },
+                    userIds: [
+                        kerioUserID
+                    ]
+                }
+            });
+
+            let response_body = user_stats_response._body;
+
+            if (!response_body.result?.errors && !response_body?.error) {
+
+                if (Array.isArray(response_body.result.list) && response_body.result.list.length > 0) {
+
+                    let _stats = response_body.result.list[0];
+
+                    let res = {
+                        storage: {
+                            items: _stats.occupiedSpace.items,
+                            value: _stats.occupiedSpace.storage.value,
+                            units: _stats.occupiedSpace.storage.units
+                        },
+                        lastLogin: "",
+                        loginCount: {
+                            pop3: _stats.pop3.count,
+                            pop3s: _stats.securePop3.count,
+                            imap: _stats.imap.count,
+                            imaps: _stats.secureImap.count,
+                            http: _stats.http.count,
+                            https: _stats.secureHttp.count,
+                            ldap: _stats.ldap.count,
+                            ldaps: _stats.secureLdap.count,
+                            nntp: _stats.nntp.count,
+                            nntps: _stats.secureNntp.count,
+                            activeSync: _stats.activeSync.count,
+                            secureActiveSync: _stats.secureActiveSync.count,
+                            xmpp: _stats.xmpp.count,
+                            xmpps: _stats.secureXmpp.count
+                        },
+                    }
+
+                    let login_timestamps_arr = Object.values(_stats).filter(services => services.lastLogin).map(t => t.lastLogin);
+
+                    //most recent login timestamp YYYY-MM-DD HH:MM in server's local time zone
+                    res.lastLogin = login_timestamps_arr.sort().at(-1);
+
+                    return res;
+
+                } else {
+                    throw {
+                        name: "KerioUserStatsError",
+                        message: `User may not exist. No statistics found for user ID ${kerioUserID}`,
+                        type: 'Kerio',
+                        from: "Kerio.Users.getStatistics"
+                    }
+                }
+
+            } else {
+                throw {
+                    name: "KerioRequestError",
+                    message: `Error occured while fetching results from API method 'User.getStatistics'`,
+                    type: 'Kerio',
+                    from: "Kerio.Users.getStatistics"
+                }
+            }
+
+        } catch (e) {
+            this.instance.logger.error(e);
+            throw e;
+        }
+    }
+}