relayx-js 1.0.18 → 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node tests/test_queue.js:*)",
+      "Bash(npm test:*)",
+      "Bash(node /tmp/debug_pattern.js:*)",
+      "Bash(node /tmp/trace_pattern.js:*)",
+      "Bash(node /tmp/debug_pattern_fixed.js:*)",
+      "Bash(ENV=test node:*)",
+      "Bash(npm run test:kv:*)",
+      "Bash(set -o allexport)",
+      "Bash(source .env)",
+      "Bash(set +o allexport)",
+      "Bash(NODE_ENV=test node:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/LICENSE

@@ -174,6 +174,15 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Terraorbital Networks (OPC) Pvt Ltd
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and

package/README.md

@@ -1,186 +1,124 @@
-# Relay NodeJS Library
-![License](https://img.shields.io/badge/Apache_2.0-green?label=License)<br>
-A powerful library for integrating real-time communication into your software stack, powered by the Relay Network.
+# RelayX JavaScript SDK
 
-## 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.
+![License](https://img.shields.io/badge/Apache_2.0-green?label=License)
+
+Real-time messaging, queues, and key-value storage for JavaScript applications.
+
+---
+
+## What is RelayX?
+
+RelayX is a real-time communication platform that enables pub/sub messaging, distributed queues, and key-value storage. This SDK provides a simple JavaScript interface to build real-time applications with minimal setup.
+
+---
 
 ## Installation
-Install the relay library by running the command below in your terminal<br>
-`npm install relayx-js`
-
-## Usage
-### Prerequisites
-1. Obtain API key and Secret key
-2. Initialize the library
-    ```javascript
-    import { Realtime, CONNECTED, RECONNECT, DISCONNECTED } from "relayx-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>History</b><br>
-Get previously published messages between a start date and end date. Dates are in UTC.
-    ```javascript
-    var start = new Date();
-    var past = start.setDate(start.getDate() - 4) // Get start date from 4 days ago
-    var startDate = new Date(past)
-
-    var end = new Date();
-    var past = end.setDate(end.getDate() - 2) // Get end date from 2 days ago
-    var endDate = new Date(past)
-
-    var history = await realtime.history(topic, startDate, endDate)
-    ```
-    The end date is optional. Supplying only the start time will fetch all messages from the start time to now.
-    ```javascript
-    var start = new Date();
-    var past = start.setDate(start.getDate() - 4) // Get start date from 4 days ago
-    var startDate = new Date(past)
-
-    // This will get all messages from 4 days ago to now
-    var history = await realtime.history(topic, startDate)
-    ```
-5. <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}`);
-    ```
-6. <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");
-    ```
-7. <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.
-    * debug (boolean): enables library level logging
-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. history()<br>
-Get a list of messages published in the past. This is an async function.<br>
-A list of messages can be obtained using a start time and end time. End time is optional. If end time is not specified, all messages from the start time to now is returned.
-     * @param {string} topic 
-     * @param {Date} start
-     * @param {Date} end
-     * @returns {JSON Array} - List of messages published in the past
-5. 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
-6. sleep()<br>
-Pauses code execution for a user defined time. Time passed into the method is in milliseconds.  This is an async function.
+
+Install via npm:
+
+```bash
+npm install relayx-js
+```
+
+---
+
+## Quick Start
+
+```javascript
+import { Realtime } from 'relayx-js';
+
+const client = new Realtime({
+  api_key: 'your-api-key',
+  secret: 'your-secret'
+});
+
+await client.init();
+await client.connect();
+
+await client.on('messages', (msg) => {
+  console.log('Received:', msg.data);
+});
+
+await client.publish('messages', { text: 'Hello RelayX!' });
+```
+
+---
+
+## Messaging (Pub/Sub)
+
+**Publishing Messages:**
+
+```javascript
+await client.publish('chat.room1', {
+  user: 'alice',
+  message: 'Hello world'
+});
+```
+
+**Subscribing to Messages:**
+
+```javascript
+await client.on('chat.room1', (msg) => {
+  console.log(`${msg.data.user}: ${msg.data.message}`);
+});
+```
+
+---
+
+## Queues
+
+**Publishing a Job:**
+
+```javascript
+const queue = await client.initQueue('tasks');
+
+await queue.publish('email.send', {
+  to: 'user@example.com',
+  subject: 'Welcome'
+});
+```
+
+**Consuming Jobs:**
+
+```javascript
+await queue.consume({ topic: 'email.send' }, async (job) => {
+  console.log('Processing:', job.data);
+  job.ack();
+});
+```
+
+---
+
+## Key-Value Store
+
+**Storing Data:**
+
+```javascript
+const kv = await client.initKVStore();
+
+await kv.put('user.123', {
+  name: 'Alice',
+  status: 'active'
+});
+```
+
+**Retrieving Data:**
+
+```javascript
+const user = await kv.get('user.123');
+console.log(user.name);
+```
+
+---
+
+## Documentation
+
+For complete documentation including guarantees, limits, API reference, and advanced usage:
+
+**https://docs.relay-x.io**
+
+---
+
+## License
+
+This SDK is licensed under the Apache 2.0 License.

package/examples/example_chat.js

@@ -6,18 +6,99 @@ const rl = readline.createInterface({
     output: process.stdout
 });
 
+var queue = null;
+
 async function run(){
     var realtime = new Realtime({
         api_key: process.env.AUTH_JWT,
         secret: process.env.AUTH_SECRET
     });
-    await realtime.init(false, {
-        max_retries: 2,
-        debug: true
+    await realtime.init({
+        staging: true, 
+        opts: {
+            max_retries: 2,
+            debug: false
+        }
     });
 
-    realtime.on(CONNECTED, async () => {
-        console.log("[IMPL] => CONNECTED!");
+    queue = await realtime.initQueue("692adca3af5ed9d55e1b1ece");
+
+    realtime.on(CONNECTED, async (connected) => {
+        console.log(`[IMPL] => ${connected ? 'CONNECTED!' : "AUTH FAILURE"}`);
+
+        if(!connected){
+            return;
+        }
+
+        var kvStore = await realtime.initKVStore();
+        console.log(`KV Store => ${kvStore}`)
+
+        // console.log("Put()")
+        // await kvStore.put("key1", {
+        //     hey: "World!"
+        // })
+
+        // await kvStore.put("key2", [{
+        //     hey: "World!"
+        // }])
+
+        // await kvStore.put("key3", [123, 123, 123])
+
+        await kvStore.put("key4", "")
+
+        // await kvStore.put("key5", ["hey", "heyb"])
+
+        // await kvStore.put("key6", 123)
+
+        // await kvStore.put("key6", null)
+
+        // await kvStore.put("key7", undefined)
+
+        // await kvStore.put("key8", true)
+
+        // await kvStore.put("key9", false)
+
+        // await kvStore.put("key10", 10.123)
+
+        console.log()
+        console.log("keys()")
+        var keys = await kvStore.keys()
+        console.log(keys)
+
+        for(const k of keys){
+            console.log()
+            console.log(`get(${k})`)
+            console.log(await kvStore.get(k))
+        }
+
+        // for(const k of keys){
+        //     console.log()
+        //     console.log(`delete(${k})`)
+        //     await kvStore.delete(k)
+        // }
+        
+        // console.log()
+        // console.log("keys()")
+        // var keys = await kvStore.keys()
+        // console.log(keys)
+
+        queue = await realtime.initQueue("692adca3af5ed9d55e1b1ece");
+
+        var config = {
+            name: "Test434",
+            group: "test-group",
+            topic: "queue.>",
+            // backoff: [2, 5, 10],
+            "ack_wait": 2
+        }
+
+        var count = 0;
+
+        queue.consume(config, (msg) => {
+            console.log(`Queue: ${msg.message}`)
+            
+            msg.ack();
+        })
     });
 
     realtime.on(RECONNECT, (status) => {
@@ -25,7 +106,7 @@ async function run(){
     });
 
     realtime.on(DISCONNECTED, () => {
-        console.log(`[IMPL] DISONNECT`)
+        console.log(`[IMPL] DISCONNECT`)
     });
 
     await realtime.on("power-telemetry", (data) => {
@@ -42,7 +123,7 @@ async function run(){
 
     // await realtime.on("hello.hey.*", (data) => {
     //     console.log("hell.hey.*", data);
-    // });
+    // });`
 
     // await realtime.on("hello.hey.>", (data) => {
     //     console.log("hello.hey.>", data);
@@ -65,7 +146,7 @@ async function run(){
         }else if(input == "history"){
             rl.question("topic: ", async (topic) => {
                 var start = new Date();
-                var past = start.setDate(start.getDate() - 4)
+                var past = start.setDate(start.getDate() - 1)
                 var pastDate = new Date(past)
 
                 var end = new Date();
@@ -93,9 +174,14 @@ async function run(){
                     console.log(topic, data);
                 });
             })
+        }else if(input == "delete_consumer"){
+            rl.question("Consumer name: ", async (name) => {
+                var del = await queue.deleteConsumer(name);
+                console.log(del)
+            })
         }else{
             rl.question("topic: ", async (topic) => {
-                var output = await realtime.publish(topic, input);
+                var output = await queue.publish(topic, input);
             })
         }
     });

package/examples/example_send_data_on_connect.js

@@ -5,9 +5,12 @@ async function run(){
         api_key: process.env.AUTH_JWT,
         secret: process.env.AUTH_SECRET
     });
-    await realtime.init(true, {
-        max_retries: 2,
-        debug: true
+    await realtime.init({
+        staging: true, 
+        opts: {
+            max_retries: 2,
+            debug: true
+        }
     });
 
     realtime.on(CONNECTED, async () => {

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "relayx-js",
-  "version": "1.0.18",
+  "version": "1.1.0",
   "main": "realtime/realtime.js",
   "type": "module",
   "scripts": {
-    "test": "NODE_ENV=test node tests/test.js"
+    "test": "set -o allexport && source .env && set +o allexport && NODE_ENV=test node tests/test.js",
+    "test:queue": "set -o allexport && source .env && set +o allexport && NODE_ENV=test node tests/test_queue.js",
+    "test:kv": "set -o allexport && source .env && set +o allexport && NODE_ENV=test node tests/test_kv.js"
   },
   "keywords": [
     "realtime",
@@ -19,8 +21,9 @@
   "dependencies": {
     "@msgpack/msgpack": "3.1.1",
     "@nats-io/jetstream": "3.0.0-35",
+    "@nats-io/kv": "3.2.0",
     "jest": "29.7.0",
-    "nats": "2.28.2",
+    "nats": "2.29.3",
     "uuid": "11.1.0"
   },
   "devDependencies": {