@brickert/kerio-connect-api 0.0.6 → 0.0.7

package/index.d.ts

@@ -108,6 +108,7 @@ export class Kerio extends WebClient {
     Session: Session;
     Logs: Logs;
     Domains: Domains;
+    Users: Users;
 
     login(user: KerioUser): void;
 
@@ -348,4 +349,59 @@ export interface DKIMRecord {
      * @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.6",
+  "version": "0.0.7",
   "description": "An unofficial API wrapper for Kerio Connect Mail Server jsonrpc Admin API.",
   "keywords": [
     "kerio",

package/src/kerio.js

@@ -2,6 +2,7 @@ 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';
@@ -25,6 +26,7 @@ export class Kerio extends WebClient {
         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/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;
+        }
+    }
+}