vantiv.io 1.0.0

package/index.js

@@ -0,0 +1,13 @@
+/// <reference types="./typings/index.d.ts" />
+'use strict';
+
+/**
+ * Highrise Bot SDK
+ * A HIghrise WebSocket SDK for Highrise bots
+ * 
+ * @copyright 2025 Yahya Ahmed
+ * @license MIT
+ */
+
+exports.Highrise = require('./src/core/Highrise')
+exports.WebApi = require('./src/classes/WebApi/webapi').WebApi

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vantiv.io",
+  "version": "1.0.0",
+  "description": "Enterprise WebSocket infrastructure for Highrise featuring spatial intelligence systems, memory-optimized architecture, and production-grade reliability for scalable application development",
+  "keywords": [
+    "highrise",
+    "websocket",
+    "sdk",
+    "bot",
+    "typescript",
+    "spatial",
+    "cache"
+  ],
+  "main": "./index.js",
+  "types": "./typings/index.d.ts",
+  "author": "Yahya Ahmed eheaahmed2000@gmail.com",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "axios": "^1.13.2",
+    "chalk": "^4.1.2",
+    "colors": "^1.4.0",
+    "express": "^5.2.1",
+    "sharp": "^0.34.5",
+    "user-agents": "^1.1.669",
+    "ws": "^8.18.3"
+  }
+}

package/src/classes/Actions/Awaiter.js

@@ -0,0 +1,202 @@
+class AwaitClass {
+    constructor(ws) {
+        if (!ws) {
+            throw new Error('ws instance is required');
+        }
+        this.ws = ws;
+        this._pendingAwaiters = new Map();
+    }
+
+    chat(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
+        if (!this._validateParameters('chat', filter, timeout, maxToCollect)) {
+            return Promise.resolve([]);
+        }
+
+        return this._createAwaiter('chat', filter, timeout, maxToCollect, uniqueUsers);
+    }
+
+    whisper(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
+        if (!this._validateParameters('whisper', filter, timeout, maxToCollect)) {
+            return Promise.resolve([]);
+        }
+        
+        return this._createAwaiter('whisper', filter, timeout, maxToCollect, uniqueUsers);
+    }
+
+    direct(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
+        if (!this._validateParameters('direct', filter, timeout, maxToCollect)) {
+            return Promise.resolve([]);
+        }
+        return this._createAwaiter('direct', filter, timeout, maxToCollect, uniqueUsers);
+    }
+
+    tip(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
+        if (!this._validateParameters('tip', filter, timeout, maxToCollect)) {
+            return Promise.resolve([]);
+        }
+        return this._createAwaiter('tip', filter, timeout, maxToCollect, uniqueUsers);
+    }
+
+    movement(filter = () => true, timeout = 30000, maxToCollect = 1, uniqueUsers = false) {
+        if (!this._validateParameters('movement', filter, timeout, maxToCollect)) {
+            return Promise.resolve([]);
+        }
+        return this._createAwaiter('movement', filter, timeout, maxToCollect, uniqueUsers);
+    }
+
+    _validateParameters(method, filter, timeout, maxToCollect) {
+        try {
+            if (typeof filter !== 'function') {
+                throw new TypeError(`Filter must be a function`);
+            }
+
+            if (typeof timeout !== 'number') {
+                throw new TypeError(`Timeout must be a number`);
+            }
+            if (timeout < 0) {
+                throw new RangeError(`Timeout cannot be negative`);
+            }
+            if (timeout > 300000) {
+                throw new RangeError(`Timeout cannot exceed 5 minutes (300000ms)`);
+            }
+
+            if (typeof maxToCollect !== 'number') {
+                throw new TypeError(`maxToCollect must be a number`);
+            }
+            if (!Number.isInteger(maxToCollect)) {
+                throw new TypeError(`maxToCollect must be an integer`);
+            }
+            if (maxToCollect < 1) {
+                throw new RangeError(`maxToCollect must be at least 1`);
+            }
+            if (maxToCollect > 1000) {
+                throw new RangeError(`maxToCollect cannot exceed 1000`);
+            }
+
+            if (!this.ws.isConnected || !this.ws.isConnected()) {
+                throw new Error(`WebSocket is not connected to Highrise`);
+            }
+
+            return true;
+
+        } catch (error) {
+            if (error instanceof TypeError) {
+                this.ws._logger.error(`await.${method}`, `TypeError: ${error.message}`, { timeout, maxToCollect }, error);
+            } else if (error instanceof RangeError) {
+                this.ws._logger.error(`await.${method}`, `RangeError: ${error.message}`, { timeout, maxToCollect }, error);
+            } else {
+                this.ws._logger.error(`await.${method}`, error.message, { timeout, maxToCollect }, error);
+            }
+            return false;
+        }
+    }
+
+    _createAwaiter(eventType, filter, timeout, maxToCollect, uniqueUsers = false) {
+        return new Promise((resolve, reject) => {
+            const awaiterId = Symbol('awaiter');
+            const collected = [];
+            const seenUsers = new Set();
+            let timeoutId;
+
+            const cleanup = () => {
+                clearTimeout(timeoutId);
+                this._pendingAwaiters.delete(awaiterId);
+            };
+
+            const awaiter = {
+                eventType,
+                filter,
+                maxToCollect,
+                collected,
+                uniqueUsers,
+                seenUsers,
+                resolve: (results) => {
+                    cleanup();
+                    resolve(results);
+                },
+                reject: (error) => {
+                    cleanup();
+                    reject(error);
+                }
+            };
+
+            this._pendingAwaiters.set(awaiterId, awaiter);
+
+            if (timeout > 0) {
+                timeoutId = setTimeout(() => {
+                    awaiter.resolve(collected);
+                }, timeout);
+            }
+        });
+    }
+
+    _processEvent(eventType, ...eventArgs) {
+        for (const [awaiterId, awaiter] of this._pendingAwaiters) {
+            if (awaiter.eventType === eventType) {
+                try {
+                    this._validateEventArguments(eventType, eventArgs);
+
+                    if (awaiter.uniqueUsers && eventArgs[0]?.id) {
+                        if (awaiter.seenUsers.has(eventArgs[0].id)) {
+                            continue;
+                        }
+                        awaiter.seenUsers.add(eventArgs[0].id);
+                    }
+
+                    if (awaiter.filter(...eventArgs)) {
+                        awaiter.collected.push(eventArgs);
+
+                        if (awaiter.collected.length >= awaiter.maxToCollect) {
+                            awaiter.resolve(awaiter.collected);
+                        }
+                    }
+                } catch (error) {
+                    this.ws._logger.error(`await.${eventType}`, `Filter error: ${error.message}`)
+                }
+            }
+        }
+    }
+
+    _validateEventArguments(eventType, eventArgs) {
+        const validators = {
+            chat: (args) => {
+                if (args.length !== 2) throw new TypeError('Chat event requires 2 arguments (user, message)');
+                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in chat event');
+                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in chat event');
+            },
+            whisper: (args) => {
+                if (args.length !== 2) throw new TypeError('Whisper event requires 2 arguments (user, message)');
+                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in whisper event');
+                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in whisper event');
+            },
+            direct: (args) => {
+                if (args.length !== 3) throw new TypeError('Direct event requires 3 arguments (user, message, conversation)');
+                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in direct event');
+                if (typeof args[1] !== 'string') throw new TypeError('Invalid message in direct event');
+                if (!args[2] || typeof args[2].id !== 'string') throw new TypeError('Invalid conversation object in direct event');
+            },
+            tip: (args) => {
+                if (args.length !== 3) throw new TypeError('Tip event requires 3 arguments (sender, receiver, currency)');
+                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid sender in tip event');
+                if (!args[1] || typeof args[1].id !== 'string') throw new TypeError('Invalid receiver in tip event');
+                if (!args[2] || typeof args[2].amount !== 'number') throw new TypeError('Invalid currency in tip event');
+            },
+            movement: (args) => {
+                if (args.length !== 3) throw new TypeError('Movement event requires 3 arguments (user, position, anchor)');
+                if (!args[0] || typeof args[0].id !== 'string') throw new TypeError('Invalid user object in movement event');
+                if (!args[1] || typeof args[1].x !== 'number') throw new TypeError('Invalid position in movement event');
+                if (args[2] !== null && (!args[2] || typeof args[2].entity_id !== 'string')) throw new TypeError('Invalid anchor in movement event');
+            }
+        };
+
+        if (validators[eventType]) {
+            try {
+                validators[eventType](eventArgs);
+            } catch (error) {
+                this.ws._logger.error(`await.${eventType}`, error.message)
+            }
+        }
+    }
+}
+
+module.exports = AwaitClass;

package/src/classes/Actions/Channel.js

@@ -0,0 +1,73 @@
+class ChannelClass {
+    constructor(bot) {
+        this.bot = bot;
+        this.logger = bot.logger;
+        this._manager = bot._channelManager;
+    }
+    
+    async send(message, tags = []) {
+        if (!this._manager) {
+            this.logger.error('Channel.send', 'Channel manager not available');
+            return false;
+        }
+        return await this._manager.send(message, tags);
+    }
+    
+    on(tags, callback) {
+        if (!this._manager) {
+            this.logger.error('Channel.on', 'Channel manager not available');
+            return null;
+        }
+        return this._manager.on(tags, callback);
+    }
+    
+    once(tags, callback) {
+        if (!this._manager) {
+            this.logger.error('Channel.once', 'Channel manager not available');
+            return null;
+        }
+        return this._manager.once(tags, callback);
+    }
+    
+    off(listenerId) {
+        if (!this._manager) {
+            this.logger.error('Channel.off', 'Channel manager not available');
+            return false;
+        }
+        return this._manager.off(listenerId);
+    }
+    
+    offAll(tags) {
+        if (!this._manager) {
+            this.logger.error('Channel.offAll', 'Channel manager not available');
+            return 0;
+        }
+        return this._manager.offAll(tags);
+    }
+    
+    query(filter = {}) {
+        if (!this._manager) {
+            this.logger.error('Channel.query', 'Channel manager not available');
+            return [];
+        }
+        return this._manager.query(filter);
+    }
+    
+    stats() {
+        if (!this._manager) {
+            this.logger.error('Channel.stats', 'Channel manager not available');
+            return { totalMessages: 0, listeners: 0 };
+        }
+        return this._manager.getStats();
+    }
+    
+    clear() {
+        if (!this._manager) {
+            this.logger.error('Channel.clear', 'Channel manager not available');
+            return;
+        }
+        this._manager.clear();
+    }
+}
+
+module.exports = { ChannelClass };

package/src/classes/Actions/Direct.js

@@ -0,0 +1,263 @@
+class DirectClass {
+    constructor(bot) {
+        this.bot = bot
+        this.logger = this.bot.logger
+    }
+
+    async send(conversation_id, message) {
+        const method = 'bot.direct.send'
+
+        try {
+            if (typeof conversation_id !== 'string' || !conversation_id) throw new TypeError('conversation_id must be a string and non-empty string')
+            if (typeof message !== 'string' || !message) throw new TypeError('message must be a string and non-empty string')
+
+            const payload = {
+                _type: 'SendMessageRequest',
+                conversation_id: conversation_id,
+                content: message,
+                type: 'text'
+            }
+
+            const response = await this.bot._fireAndForget.send(payload)
+            return response.success
+        } catch (error) {
+            if (error instanceof TypeError) {
+                this.logger.error(method, `TypeError: ${error.message}`, { conversation_id, message }, error);
+            } else {
+                this.logger.error(method, `Failed to send message: ${error.message}`, { conversation_id, message }, error);
+                return false
+            }
+        }
+    }
+
+    async bulkSend(user_ids, message) {
+        const method = 'bot.direct.bulkSend'
+
+        try {
+            if (!Array.isArray(user_ids) || user_ids.length <= 0 || user_ids.length > 100) {
+                throw new TypeError('user_ids must be an array with at least 1 ID and maximum 100 IDs');
+            }
+
+            const invalidUserIds = user_ids.filter(id => typeof id !== 'string' || id.trim() === '');
+            if (invalidUserIds.length > 0) {
+                throw new TypeError(`All user_ids must be non-empty strings. Invalid IDs: ${invalidUserIds.join(', ')}`);
+            }
+
+            if (typeof message !== 'string' || !message.trim()) {
+                throw new TypeError('message must be a non-empty string');
+            }
+
+            const payload = {
+                _type: 'SendBulkMessageRequest',
+                user_ids: user_ids,
+                content: message,
+                type: 'text'
+            }
+
+            const response = await this.bot._fireAndForget.send(payload)
+            return response.success
+        } catch (error) {
+            if (error instanceof TypeError) {
+                this.logger.error(method, `TypeError: ${error.message}`, { conversation_id, message }, error);
+            } else {
+                this.logger.error(method, `Failed to send bulk messages: ${error.message}`, { conversation_id, message }, error);
+                return false
+            }
+        }
+    }
+
+    async bulkInvite(user_ids, options = {}) {
+        const method = 'bot.direct.bulkSend'
+
+        try {
+            if (!Array.isArray(user_ids) || user_ids.length <= 0 || user_ids.length > 100) {
+                throw new TypeError('user_ids must be an array with at least 1 ID and maximum 100 IDs');
+            }
+
+            const invalidUserIds = user_ids.filter(id => typeof id !== 'string' || id.trim() === '');
+            if (invalidUserIds.length > 0) {
+                throw new TypeError(`All user_ids must be non-empty strings. Invalid IDs: ${invalidUserIds.join(', ')}`);
+            }
+
+            if (typeof options !== 'object' || options === null) {
+                throw new TypeError('options must be an object')
+            }
+
+            const providedOptions = [];
+            if (options.room_id) providedOptions.push('room_id');
+            if (options.world_id) providedOptions.push('world_id');
+
+            if (providedOptions.length === 0) {
+                throw new TypeError('Must provide exactly one of: room_id or world_id')
+            }
+            if (providedOptions.length > 1) {
+                throw new TypeError(`Cannot provide both ${providedOptions.join(' and ')} - must provide exactly one`)
+            }
+
+            const payload = {
+                _type: 'SendBulkMessageRequest',
+                user_ids: user_ids,
+                content: '',
+                type: 'invite'
+            }
+
+            if (options.room_id) {
+                if (typeof options.room_id !== 'string') {
+                    throw new TypeError('room_id must be a string')
+                }
+                payload.room_id = options.room_id;
+            } else if (options.world_id) {
+                if (typeof options.world_id !== 'string') {
+                    throw new TypeError('world_id must be a string')
+                }
+                payload.world_id = options.world_id;
+            }
+
+            const response = await this.bot._fireAndForget.send(payload)
+            return response.success
+        } catch (error) {
+            if (error instanceof TypeError) {
+                this.logger.error(method, `TypeError: ${error.message}`, { conversation_id, message }, error);
+            } else {
+                this.logger.error(method, `Failed to send bulk invites: ${error.message}`, { conversation_id, message }, error);
+                return false
+            }
+        }
+    }
+
+    async invite(conversation_id, options = {}) {
+        const method = 'bot.invite.send'
+
+        try {
+            if (typeof conversation_id !== 'string' || !conversation_id) {
+                throw new TypeError('conversation_id must be a non-empty string')
+            }
+
+            if (typeof options !== 'object' || options === null) {
+                throw new TypeError('options must be an object')
+            }
+
+            const providedOptions = [];
+            if (options.room_id) providedOptions.push('room_id');
+            if (options.world_id) providedOptions.push('world_id');
+
+            if (providedOptions.length === 0) {
+                throw new TypeError('Must provide exactly one of: room_id or world_id')
+            }
+            if (providedOptions.length > 1) {
+                throw new TypeError(`Cannot provide both ${providedOptions.join(' and ')} - must provide exactly one`)
+            }
+
+            const payload = {
+                _type: 'SendMessageRequest',
+                conversation_id: conversation_id,
+                content: '',
+                type: 'invite'
+            }
+
+            if (options.room_id) {
+                if (typeof options.room_id !== 'string') {
+                    throw new TypeError('room_id must be a string')
+                }
+                payload.room_id = options.room_id;
+            } else if (options.world_id) {
+                if (typeof options.world_id !== 'string') {
+                    throw new TypeError('world_id must be a string')
+                }
+                payload.world_id = options.world_id;
+            }
+
+            const response = await this.bot._fireAndForget.send(payload)
+            return response.success
+
+        } catch (error) {
+            if (error instanceof TypeError) {
+                this.logger.error(method, `TypeError: ${error.message}`,
+                    { conversation_id, options }, error);
+            } else {
+                this.logger.error(method, `Failed to send invite: ${error.message}`,
+                    { conversation_id, options }, error);
+                return false
+            }
+        }
+    }
+
+    conversations = {
+        get: async (last_id = null, not_joined = false) => {
+            const method = 'bot.direct.conversations.get'
+
+            try {
+                if (typeof last_id !== 'string' && last_id !== null) throw new TypeError('last_id must be a string or null')
+                if (typeof not_joined !== 'boolean') throw new TypeError('not_joined must be a boolean')
+
+                const payload = {
+                    _type: 'GetConversationsRequest',
+                    last_id,
+                    not_joined,
+                }
+
+                const response = await this.bot._requestResponse.send(payload)
+                return response.conversations
+            } catch (error) {
+                if (error instanceof TypeError) {
+                    this.logger.error(method, `TypeError: ${error.message}`, { last_id, not_joined }, error);
+                } else {
+                    this.logger.error(method, `Failed to get conversations: ${error.message}`, { last_id, not_joined }, error);
+                    return [];
+                }
+            }
+        },
+
+        leave: async (conversation_id) => {
+            const method = 'bot.direct.conversations.leave'
+
+            try {
+                if (typeof conversation_id !== 'string' || !conversation_id) throw new TypeError('conversation_id must be a string and non-empty string')
+
+                const payload = {
+                    _type: 'LeaveConversationRequest',
+                    conversation_id: conversation_id,
+                }
+
+                const response = await this.bot._fireAndForget.send(payload)
+                return response.success
+            } catch (error) {
+                if (error instanceof TypeError) {
+                    this.logger.error(method, `TypeError: ${error.message}`, { conversation_id }, error);
+                } else {
+                    this.logger.error(method, `Failed to leave conversation: ${error.message}`, { conversation_id }, error);
+                    return false
+                }
+            }
+        }
+    }
+
+    messages = {
+        get: async (conversation_id, last_message_id = null) => {
+            const method = 'bot.direct.messages.get'
+
+            try {
+                if (typeof conversation_id !== 'string' || !conversation_id) throw new TypeError('conversation_id must be a string and non-empty string')
+                if (typeof last_message_id !== 'string' && last_message_id !== null) throw new TypeError('last_message_id must be a string or null')
+
+                const payload = {
+                    _type: 'GetMessagesRequest',
+                    conversation_id,
+                    last_message_id,
+                }
+
+                const response = await this.bot._requestResponse.send(payload)
+                return response.messages
+            } catch (error) {
+                if (error instanceof TypeError) {
+                    this.logger.error(method, `TypeError: ${error.message}`, { conversation_id, last_message_id }, error);
+                } else {
+                    this.logger.error(method, `Failed to get messages: ${error.message}`, { conversation_id, last_message_id }, error);
+                    return [];
+                }
+            }
+        }
+    }
+}
+
+module.exports = { DirectClass }