relayx-webjs 1.0.4 → 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__ide__getDiagnostics",
+      "Bash(grep:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/CHANGELOG.md

@@ -1,3 +1,6 @@
+V1.0.5
+- Removed DNS testing code
+
 V1.0.4
 - Removed DNS Spoofing for testing
 

package/LICENSE

@@ -175,18 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2025 TerraOrbital
+   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.

package/README.md

@@ -1,186 +1,136 @@
-# Relay JS Library for the Web
-![License](https://img.shields.io/badge/Apache_2.0-green?label=License)<br>
-A powerful library for integrating real-time communication into your web app, 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)
+
+A fast, simple SDK for messaging, queues, and key-value storage in JavaScript.
+
+---
+
+## What is RelayX?
+
+RelayX is a real-time messaging platform that makes it easy to build distributed systems. It provides pub/sub messaging, durable queues, and a key-value store with a simple API.
+
+---
 
 ## Installation
-Install the relay library by running the command below in your terminal<br>
-`npm install relayx-webjs`
-
-## Usage
-### Prerequisites
-1. Obtain API key and Secret key
-2. Initialize the library
-    ```javascript
-    import { Realtime, CONNECTED, RECONNECT, DISCONNECTED } from "relayx-webjs"
-
-    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 the SDK using npm:
+
+```bash
+npm install relayx-webjs
+```
+
+---
+
+## Quick Start
+
+Here's a complete example that publishes and subscribes to a message:
+
+```javascript
+import { Realtime } from 'relayx-webjs';
+
+const client = new Realtime({
+  api_key: 'your-api-key',
+  secret: 'your-secret'
+});
+
+await client.init();
+await client.connect();
+
+await client.on('chat', (message) => {
+  console.log('Received:', message);
+});
+
+await client.publish('chat', { text: 'Hello, RelayX!' });
+```
+
+---
+
+## Messaging (Pub/Sub)
+
+### Publishing a Message
+
+```javascript
+await client.publish('notifications', {
+  type: 'alert',
+  message: 'System update complete'
+});
+```
+
+### Subscribing to Messages
+
+```javascript
+await client.on('notifications', (message) => {
+  console.log('Notification:', message);
+});
+```
+
+---
+
+## Queues
+
+### Publishing a Job
+
+```javascript
+const queue = await client.initQueue('queue-id');
+
+await queue.publish('image-processing', {
+  imageUrl: 'https://example.com/photo.jpg',
+  operation: 'resize'
+});
+```
+
+### Processing Jobs
+
+```javascript
+await queue.consume(
+  {
+    name: 'image-worker',
+    topic: 'image-processing',
+    group: 'workers'
+  },
+  async (job) => {
+    console.log('Processing:', job.message);
+
+    await job.ack();
+  }
+);
+```
+
+---
+
+## Key-Value Store
+
+### Storing Data
+
+```javascript
+const kvStore = await client.initKVStore();
+
+await kvStore.put('user:123', {
+  name: 'Alice',
+  status: 'active'
+});
+```
+
+### Retrieving Data
+
+```javascript
+const user = await kvStore.get('user:123');
+console.log(user);
+```
+
+---
+
+## Documentation
+
+For complete documentation including delivery guarantees, error handling, limits, and advanced features, visit:
+
+**https://docs.relay-x.io**
+
+All system behavior and configuration options are documented there.
+
+---
+
+## License
+
+This SDK is licensed under the Apache 2.0 License.

package/example/stand-alone/example_chat.js

@@ -11,9 +11,12 @@ async function run(){
         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: true
+        }
     });
 
     realtime.on(CONNECTED, async () => {

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "relayx-webjs",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "A powerful library for integrating real-time communication into your webapps, powered by the Relay Network.",
   "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"
   },
   "repository": {
     "type": "git",
@@ -25,8 +27,9 @@
   },
   "homepage": "https://github.com/Realtime-Relay/relayx-webjs#readme",
   "dependencies": {
-    "@msgpack/msgpack": "^3.1.2",
+    "@msgpack/msgpack": "3.1.2",
     "@nats-io/jetstream": "3.0.0-35",
+    "@nats-io/kv": "3.2.0",
     "jest": "30.0.4",
     "nats.ws": "1.30.3",
     "uuid": "11.1.0"

package/realtime/kv_storage.js

@@ -0,0 +1,195 @@
+import { Kvm } from "@nats-io/kv";
+import { ErrorLogging, Logging } from "./utils.js";
+
+export class KVStore{
+
+    #kvManager = null
+    #kvStore = null
+
+    #namespace = null;
+
+    #logger = null;
+    #errorLogger = null;
+
+    constructor(data){
+        this.#namespace = data.namespace;
+
+        this.#kvManager = new Kvm(data.jetstream)
+
+        this.#logger = new Logging(data.debug)
+
+        this.#errorLogger = new ErrorLogging()
+    }
+
+    async init(){
+        this.#validateInput()
+
+        this.#kvStore = await this.#kvManager.open(this.#namespace)
+
+        return this.#kvStore != null
+    }
+
+    async get(key){
+        this.#validateKey(key)
+
+        try{
+            const val = await this.#kvStore.get(key);
+
+            this.#logger.log("Value for", key)
+            
+            var json = null;
+
+            json = JSON.parse(val.string())
+            return json
+        }catch(err){
+            this.#errorLogger.logError({
+                err: err, 
+                op: "kv_read"
+            })
+
+            return null
+        }
+    }
+
+    async put(key, value){
+        this.#validateKey(key)
+        this.#validateValue(value)
+
+        this.#logger.log(`Creating KV pair for ${key}`)
+
+        try{
+            await this.#kvStore.create(key, JSON.stringify(value))
+        }catch(err){
+            // The assumption here is that the key might already exist
+            try{
+                await this.#kvStore.put(key, JSON.stringify(value))
+            }catch(err2){
+                // The key creation failed because we don't have permission
+                this.#errorLogger.logError({
+                    err: err2,
+                    op: "kv_write"
+                })
+            }
+        }
+    }
+
+    async delete(key){
+        this.#validateKey(key)
+
+        try{
+            await this.#kvStore.purge(key);
+        }catch(err){
+            // The key delete failed because we don't have permission
+            this.#errorLogger.logError({
+                err: err,
+                op: "kv_delete"
+            })
+        }
+
+    }
+
+    async keys(){
+        var keys = [];
+
+        try{
+            var qKeys = await this.#kvStore.keys();
+
+            for await (const key of qKeys) {
+                this.#logger.log("Key: ", key);
+                keys.push(key);
+            }
+        }catch(err){
+            this.#errorLogger.logError({
+                err: err, 
+                op: "kv_read"
+            })
+        }
+
+        return keys;
+
+    }
+
+    // Utility functions
+    #validateInput(){
+        if(this.#namespace === null || this.#namespace === undefined || this.#namespace == ""){
+            throw new Error("$namespace cannot be null / undefined / empty")
+        }
+    }
+
+    #validateKey(key){
+        if(key == null || key == undefined){
+            throw new Error("$key cannot be null / undefined")
+        }
+
+        if(typeof key != "string"){
+            throw new Error("$key cannot be a string")
+        }
+
+        if(key == ""){
+            throw new Error("$key cannot be empty")
+        }
+
+        // Validate key characters: only a-z, A-Z, 0-9, _, -, ., = and / are allowed
+        const validKeyPattern = /^[a-zA-Z0-9_\-\.=\/]+$/;
+        if(!validKeyPattern.test(key)){
+            throw new Error("$key can only contain alphanumeric characters and the following: _ - . = /")
+        }
+    }
+
+    #validateValue(value){
+        var valueValid = (
+            value === null ||
+            typeof value == "string" ||
+            typeof value == "number" ||
+            typeof value == "boolean" ||
+            Array.isArray(value) ||
+            this.#isJSON(value)
+        );
+
+        if(!valueValid){
+            throw new Error(`$value MUST be null, string, number, boolean, array or json! $value is "${typeof value}"`)
+        }
+    }
+
+    #isJSON(data){
+        try{
+            JSON.stringify(data?.toString())
+            return true;
+        }catch(err){
+            return false
+        }
+    }
+
+    // Test helper methods - expose private methods/state for testing
+    // Only available when process.env.NODE_ENV == "test"
+    testGetNamespace(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return this.#namespace;
+    }
+
+    testIsKvStoreInitialized(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return this.#kvStore != null;
+    }
+
+    testValidateKey(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return (key) => this.#validateKey(key);
+    }
+
+    testValidateValue(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return (value) => this.#validateValue(value);
+    }
+
+    testValidateInput(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return () => this.#validateInput();
+    }
+
+    testIsJSON(){
+        if(process.env.NODE_ENV !== "test") return undefined;
+        return (data) => this.#isJSON(data);
+    }
+
+}

package/realtime/models/message.js

@@ -0,0 +1,26 @@
+
+export default class Message {
+    id = null
+    message = null
+    topic = null
+
+    msg = null
+    
+    constructor(message){
+        this.id = message.id;
+
+        this.message = message.message;
+
+        this.topic = message.topic;
+
+        this.msg = message.msg;
+    }
+
+    ack(){
+        this.msg?.ack()
+    }
+
+    nack(millis){
+        this.msg?.nak(millis)
+    }
+}