relayx-js 1.0.0

package/README.md

@@ -0,0 +1,156 @@
+# Relay NodeJS Library
+![License](https://img.shields.io/badge/MIT-green?label=License)<br>
+A powerful library for integrating real-time communication into your software stack, powered by the Relay Network.
+
+## Features
+1. Real-time communication made easy—connect, publish, and subscribe with minimal effort.
+2. Automatic reconnection built-in, with a 2-minute retry window for network disruptions.
+3. Message persistence during reconnection ensures no data loss when the client reconnects.
+
+## Installation
+Install the relay library by running the command below in your terminal<br>
+`npm install relay-x-js`
+
+## Usage
+### Prerequisites
+1. Obtain API key and Secret key
+2. Initialize the library
+    ```javascript
+    import { Realtime, CONNECTED, RECONNECT, DISCONNECTED } from "relay-x-js"
+
+    var realtime = new Realtime({
+        api_key: process.env.api_key,
+        secret: process.env.secret,
+    });
+    realtime.init();
+
+    // Initialization of topic listeners go here... (look at examples/example_chat.js for full implementation)
+
+    realtime.connect();
+
+    // Other application logic...
+    ```
+
+### Usage
+1. <b>Publish</b><br>
+Send a message to a topic:<br>
+    ```javascript
+    var sent = await realtime.publish("power_telemetry", {
+        "voltage_V": 5,
+        "current_mA": 400,
+        "power_W": 2 
+    });
+
+    if(sent){
+        console.log("Message was successfully sent to topic => power_telemetry");
+    }else{
+        console.log("Message was not sent to topic => power_telemetry");
+    }
+    ```
+2. <b>Listen</b><br>
+Subscribe to a topic to receive messages:<br>
+    ```javascript
+    await realtime.on("power_telemetry", (data) => {
+        console.log(data);
+    });
+    ```
+3. <b>Turn Off Listener</b><br>
+Unsubscribe from a topic:<br>
+    ```javascript
+    var unsubscribed = await realtime.off("power_telemetry");
+
+    if(unsubscribed){
+        console.log("Successfully unsubscribed from power_telemetry");
+    }else{
+        console.log("Unable to unsubscribe from power_telemetry");
+    }
+    ```
+4. <b>Valid Topic Check</b><br>
+Utility function to check if a particular topic is valid
+    ```javascript
+    var isValid = realtime.isTopicValid("topic");
+
+    console.log(`Topic Valid => ${isValid}`);
+    ```
+5. <b>Sleep</b><br>
+Utility async function to delay code execution
+    ```javascript
+    console.log("Starting code execution...");
+    await realtime.sleep(2000) // arg is in ms
+    console.log("This line executed after 2 seconds");
+    ```
+6. <b>Close Connection to Relay</b><br>
+Manually disconnect from the Relay Network
+    ```javascript
+    // Logic here
+
+    realtime.close();
+    ```
+
+## System Events
+1. <b>CONNECTED</b><br>
+This event is fired when the library connects to the Relay Network.
+    ```javascript
+    await realtime.on(CONNECTED, () => {
+        console.log("Connected to the Relay Network!");
+    });
+    ```
+
+2. <b>RECONNECT</b><br>
+This event is fired when the library reconnects to the Relay Network. This is only fired when the disconnection event is not manual, i.e, disconnection due to network issues.
+    ```javascript
+    await realtime.on(RECONNECT, (status) => {
+        console.log(`Reconnected! => ${status}`);
+    });
+    ```
+    `status` can have values of `RECONNECTING` & `RECONNECTED`.
+
+    `RECONNECTING` => Reconnection attempts have begun. If `status == RECONNECTING`, the `RECONNECT` event is fired every 1 second.<br>
+    `RECONNECTED` => Reconnected to the Relay Network.
+3. <b>DISCONNECTED</b><br>
+This event is fired when the library disconnects from the Relay Network. This includes disconnection due to network issues as well.
+    ```javascript
+    await realtime.on(DISCONNECTED, () => {
+        console.log("Disconnected from the Relay Network");
+    });
+    ```
+4. <b>MESSAGE_RESEND</b><br>
+This event is fired when the library resends the messages upon reconnection to the Relay Network.
+    ```javascript
+    await realtime.on(MESSAGE_RESEND, (messages) => {
+        console.log("Offline messages may have been resent");
+        console.log("Messages");
+        console.log(messages);
+    });
+    ```
+    `messages` is an array of the following object,<br>
+    ```json
+    {
+        "topic": "<topic the message belongs to>",
+        "message": "<message you sent>",
+        "resent": "<boolean, indicating if the message was sent successully>"
+    }
+    ```
+
+## API Reference
+1. init()<br>
+Initializes library with configuration options
+2. connect()<br>
+Connects the library to the Relay Network. This is an async function.
+3. close()<br>
+Disconnects the library from the Relay Network.
+3. on()<br>
+Subscribes to a topic. This is an async function.
+     * @param {string} topic - Name of the event
+     * @param {function} func - Callback function to call on user thread
+     * @returns {boolean} - To check if topic subscription was successful
+3. off()<br>
+Deletes reference to user defined event callback for a topic. This will stop listening to a topic. This is an async function.
+     * @param {string} topic 
+     * @returns {boolean} - To check if topic unsubscribe was successful
+4. isTopicValid()<br>
+Checks if a topic can be used to send messages to.
+     * @param {string} topic - Name of event
+     * @returns {boolean} - If topic is valid or not
+5. sleep()<br>
+Pauses code execution for a user defined time. Time passed into the method is in milliseconds.  This is an async function.

package/examples/example_chat.js

@@ -0,0 +1,97 @@
+import { Realtime, CONNECTED, RECONNECT, DISCONNECTED, MESSAGE_RESEND } from "../realtime/realtime.js"
+import * as readline from 'readline';
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+});
+
+async function run(){
+    // await throttle.start(options["fois"]);
+
+    var realtime = new Realtime({
+        api_key: process.env.user_key,
+        secret: process.env.secret
+    });
+    await realtime.init({
+        max_retries: 2,
+        debug: true
+    });
+
+    realtime.on(CONNECTED, async () => {
+        console.log("[IMPL] => CONNECTED!");
+    });
+
+    realtime.on(RECONNECT, (status) => {
+        console.log(`[IMPL] RECONNECT => ${status}`)
+    });
+
+    realtime.on(DISCONNECTED, () => {
+        console.log(`[IMPL] DISONNECT`)
+    });
+
+    await realtime.on("hello", (data) => {
+        console.log("hello", data);
+    });
+
+    await realtime.on("hello1", (data) => {
+        console.log("hello1", data);
+    });
+
+    realtime.on(MESSAGE_RESEND, (data) => {
+        console.log(`[MSG RESEND] => ${data}`)
+    });
+
+    rl.on('line', async (input) => {
+        console.log(`You entered: ${input}`);
+
+        if(input == "exit"){
+            var output = await realtime.off("hello"); 
+            console.log(output);
+
+            realtime.close();
+
+            process.exit();
+        }else if(input == "history"){
+            var since = Date.now() - 1 * 60 * 60 * 1000; // 1 hour ago
+
+            var history = await realtime.history.getMessagesSince("hello", since, 1, 1000);
+            console.log(history);
+        }else if(input == "off"){
+            rl.question("topic to off(): ", async (topic) => {
+                await realtime.off(topic);
+                console.log("off() executed")
+            })
+
+            
+        }else if(input == "close"){
+            realtime.close();
+            console.log("Connection closed");
+        }else if(input == "on"){
+            rl.question("topic: ", async (topic) => {
+                await realtime.on(topic, (data) => {
+                    console.log(topic, data);
+                });
+            })
+        }else{
+            rl.question("topic: ", async (topic) => {
+                var output = await realtime.publish(topic, {
+                    "data": input
+                });
+            })
+        }
+    });
+
+    realtime.connect();
+
+    process.on('SIGINT', async () => {
+        console.log('Keyboard interrupt detected (Ctrl+C). Cleaning up...');
+        // Perform any necessary cleanup here
+    
+        // Exit the process
+        process.exit();
+    });
+    
+}
+
+await run();

package/examples/example_send_data_on_connect.js

@@ -0,0 +1,46 @@
+import { Realtime, CONNECTED, RECONNECT, DISCONNECTED, MESSAGE_RESEND } from "../realtime/realtime.js"
+
+async function run(){
+    var realtime = new Realtime({
+        api_key: process.env.user_key,
+        secret: process.env.secret
+    });
+    await realtime.init(true, {
+        max_retries: 2,
+        debug: true
+    });
+
+    realtime.on(CONNECTED, async () => {
+        console.log("[IMPL] => CONNECTED!");
+
+        for (let angle = 0; angle <= 18000; angle++){
+
+            var value = Math.floor(Math.random() * (100 + 1))
+            console.log(value)
+
+            await realtime.publish("test-topic", {
+                "value": value,
+                "time": Date.now() + 2000
+            })
+
+            await realtime.sleep(100)
+        }
+    });
+
+    realtime.on(RECONNECT, (status) => {
+        console.log(`[IMPL] RECONNECT => ${status}`)
+    });
+
+    realtime.on(DISCONNECTED, () => {
+        console.log(`[IMPL] DISONNECT`)
+    });
+
+    realtime.on(MESSAGE_RESEND, (data) => {
+        console.log(`[MSG RESEND] => ${data}`)
+    });
+
+    realtime.connect();
+    
+}
+
+await run();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "relayx-js",
+  "version": "1.0.0",
+  "main": "realtime/realtime.js",
+  "type": "module",
+  "scripts": {
+    "test": "NODE_ENV=test node tests/test.js"
+  },
+  "keywords": ["realtime", "realtime-communication", "relay", "relay-x", "relay-x-js"],
+  "author": "Relay",
+  "license": "MIT License",
+  "description": "A powerful library for integrating real-time communication into your software stack, powered by the Relay Network.",
+  "dependencies": {
+    "@nats-io/jetstream": "^3.0.0-35",
+    "axios": "1.7.7",
+    "jest": "^29.7.0",
+    "nats": "^2.28.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-react": "^7.25.9",
+    "babel-jest": "^29.7.0"
+  }
+}

package/realtime/history.js

@@ -0,0 +1,160 @@
+import axios from 'axios';
+
+/**
+ * Class responsible for getting messages stored in the DB
+ */
+export class History{
+    
+    #api_key = null;
+    #staging = null;
+    #baseUrl = null;
+    #debug = null;
+
+    constructor(api_key){
+        this.#api_key = api_key;
+    }
+
+    init(staging, debug){
+        this.#staging = staging;
+        this.#debug = debug;
+
+        this.#setBaseUrl();
+    }
+
+    /**
+     * Get message from DB since a $timestamp
+     * @param {number} timestamp - unix timestamp
+     * @param {number} page - page number of pagination
+     * @param {number} limit - limit per page
+     * @returns - Message array
+     */
+    async getMessagesSince(topic, timestamp, page, limit){
+        if(topic == null || topic == undefined){
+            return new Error("$topic variable missing in getMessagesSince()");
+        }else{
+            if(typeof topic !== "string"){
+                return new Error("$topic is not a string");
+            }
+        }
+
+        if(timestamp == null || timestamp == undefined){
+            return new Error("$timestamp variable missing in getMessagesSince()");
+        }else{
+            if(!Number.isInteger(timestamp) && !Number.isNaN(timestamp)){
+                return new Error("$timestamp is either NaN or not an invalid integer");
+            }
+        }
+
+        if(page == null || page == undefined){
+            return new Error("$page variable missing in getMessagesSince()");
+        }else{
+            if(!Number.isInteger(page) && !Number.isNaN(page)){
+                return new Error("$page is either NaN or not an invalid integer");
+            }
+        }
+
+        if(limit == null || limit == undefined){
+            return new Error("$limit variable missing in getMessagesSince()");
+        }else{
+            if(!Number.isInteger(limit) && !Number.isNaN(limit)){
+                console.log("$limit is either NaN or not an invalid integer")
+                return new Error("$limit is either NaN or not an invalid integer");
+            }
+        }
+
+        try{
+            var startTime = Date.now();
+            var urlPart = `/history/since?topic=${topic}&timestamp=${timestamp}&page=${page}&limit=${limit}`
+
+            var response = await axios.get(this.#baseUrl + urlPart,{
+                headers: {
+                    "Authorization": `Bearer ${this.#api_key}`
+                }
+            });
+
+            var data = response.data
+            this.#log(data);
+
+            this.#logResponseTime(startTime, urlPart);
+
+            if (data?.status === "SUCCESS"){
+                return data.data;
+            }else{
+                return null;
+            }
+       }catch(err){
+            throw Error(err.message);
+       }
+    }
+
+    /**
+     * Get message from DB by ID
+     * @param {string} id - ID of the message
+     * @returns - Message object
+     */
+    async getMessageById(id){
+        var startTime = Date.now();
+        var urlPart = `/history/message-by-id?id=${id}`;
+
+        if(id !== null && id !== undefined){
+            try{
+                var response = await axios.get(this.#baseUrl + urlPart,{
+                    headers: {
+                        "Authorization": `Bearer ${this.#api_key}`
+                    }
+                });
+    
+                var data = response.data
+                this.#log(data);
+
+                this.#logResponseTime(startTime, urlPart);
+    
+                if (data?.status === "SUCCESS"){
+                    return data.data;
+                }else{
+                    return null;
+                }
+           }catch(err){
+                throw new Error(err.message);
+           }
+        }else{
+            return null;
+        }
+    }
+
+    // Utility Functions
+    /**
+     * Constructs base url based on staging flag
+     */
+    #setBaseUrl(){
+        if (this.#staging !== undefined || this.#staging !== null){
+            this.#baseUrl = this.#staging ? "http://127.0.0.1:3000" : "http://128.199.176.185:3000";
+        }else{
+            this.#baseUrl = "http://128.199.176.185:3000";
+        }
+    }
+
+    #log(msg){
+        if(this.#debug !== null && this.#debug !== undefined && (typeof this.#debug == "boolean")){
+            if(this.#debug){
+                console.log(msg);
+            }
+        }
+    }
+
+    async #logResponseTime(startTime, url){
+        var responseTime = Date.now() - startTime;
+
+        var data = {
+            "url": url,
+            "response_time": responseTime
+        }
+
+        await axios.post(this.#baseUrl + "/metrics/log", data, {
+            headers: {
+                "Authorization": `Bearer ${this.#api_key}`
+            }
+        });
+    }
+
+}