Search docs.molo17.com
    A newer version of this documentation is available.
    View Latest (v2.3)

    Node.js SDK Node.js Repository

    The Gluesync Node.js SDK provides a powerful JavaScript interface for building integrations, modules, and extensions that communicate with the Core Hub.

    Open Source This project is Open Source

    Overview

    The Node.js SDK offers a modern, promise-based API for interacting with Gluesync’s Core Hub. Built with JavaScript/TypeScript developers in mind, it provides an intuitive interface for real-time data synchronization, event processing, and Core Hub integration.

    Installation

    npm install gitlab:molo17-public/gluesync/gluesync-nodejs-corehub-handshake-sdk

    Key Features

    • Promise-based API

      • Async/await support

      • Modern JavaScript patterns

      • TypeScript type definitions

    • Core Hub Handshake

      • WebSocket connection management

      • Protocol version negotiation

      • Connection resiliency

      • Automatic reconnection

    • Authentication

      • API key authentication

      • JWT token management

      • Session handling

      • Secure credential storage

    • Security

      • SSL/TLS support with JKS certificates

      • Secure token management

      • Verified connections

    • (Coming soon) Event Handling

      • Real-time event subscription

      • Event stream processing

      • Custom event handlers

      • Event filtering and routing

    • (Coming soon) Data Processing

      • JSON serialization/deserialization

      • Schema validation

      • Transformation utilities

      • Error handling middleware

    Basic Usage

    import { GluesyncClient } from 'gluesync-sdk';
    
    async function main() {
      // Initialize the client with Core Hub address and license file path
      // For fixed address:
      const client = new GluesyncClient({
        host: 'localhost',
        port: 1717,
        licenseFilePath: '/path/to/gs-license.dat',
        moduleTag: 'my-module'
      });
    
      // Or use UDP autodiscovery (set host to null)
      // const client = new GluesyncClient({
      //   host: null,  // Will use UDP autodiscovery to find Core Hub
      //   port: 1717,
      //   licenseFilePath: '/path/to/gs-license.dat',
      //   moduleTag: 'my-module'
      // });
    
      // Connect to Core Hub
      await client.connect();
    
      // The JWT token for API requests is available after connection
      const jwtToken = client.token;
      console.log(`Connected with token: ${jwtToken}`);
    
      // Do your work here
    
      // Disconnect when done
      await client.disconnect();
    }
    
    main().catch(console.error);

    Advanced Features

    Using UDP Autodiscovery

    import { GluesyncClient } from 'gluesync-sdk';
    
    async function main() {
      // Initialize the client without specifying a host to use autodiscovery
      const client = new GluesyncClient({
        // host parameter is omitted to enable autodiscovery
        licenseFilePath: '/path/to/gs-license.dat',
        moduleTag: 'my-module'
      });
    
      // Connect will automatically discover the Core Hub on the network
      await client.connect();
    
      // Do your work here
    
      // Disconnect when done
      await client.disconnect();
    }
    
    main().catch(console.error);

    You can also use the environment variable CORE_HUB_ADDRESS to bypass autodiscovery:

    // Set this to bypass autodiscovery
    process.env.CORE_HUB_ADDRESS = '192.168.1.100';

    Using SSL/TLS with JKS Certificates

    import { GluesyncClient } from 'gluesync-sdk';
    
    async function main() {
      const client = new GluesyncClient({
        host: 'corehub.example.com',
        port: 1717,
        licenseFilePath: '/path/to/gs-license.dat',
        moduleTag: 'my-module',
        ssl: true,
        keystorePath: '/path/to/Gluesync.com.jks',
        keystorePassword: 'your-password'
      });
    
      await client.connect();
      // ...
    }
    
    main().catch(console.error);

    Event Handling

    import { GluesyncClient } from 'gluesync-sdk';
    
    // Option 1: Using callback functions
    async function main() {
      const client = new GluesyncClient({
        host: 'localhost',
        port: 1717,
        licenseFilePath: '/path/to/gs-license.dat',
        moduleTag: 'my-module'
      });
    
      // Set up event handlers
      client.onConnected = (token) => {
        console.log(`Connected! Received token: ${token}`);
      };
    
      client.onDisconnected = (reason) => {
        console.log(`Disconnected: ${reason}`);
      };
    
      client.onError = (error) => {
        console.log(`Error: ${error}`);
      };
    
      await client.connect();
    
      // Keep the connection alive for some time
      await new Promise(resolve => setTimeout(resolve, 3600000));
    
      await client.disconnect();
    }
    
    // Option 2: Using event emitter API
    async function mainWithEvents() {
      const client = new GluesyncClient({
        host: 'localhost',
        port: 1717,
        licenseFilePath: '/path/to/gs-license.dat',
        moduleTag: 'my-module'
      });
    
      // Set up event listeners
      client.on('connected', (token) => {
        console.log(`Connected! Received token: ${token}`);
      });
    
      client.on('disconnected', (reason) => {
        console.log(`Disconnected: ${reason}`);
      });
    
      client.on('error', (error) => {
        console.log(`Error: ${error}`);
      });
    
      await client.connect();
    
      // Keep the connection alive for some time
      await new Promise(resolve => setTimeout(resolve, 3600000));
    
      await client.disconnect();
    }
    
    main().catch(console.error);

    Configuration Options

    The GluesyncClient constructor accepts the following configuration options:

    Parameter Type Required Default Description

    host

    string | null

    No

    null

    The hostname or IP of the Core Hub. If null, autodiscovery will be used

    port

    number

    No

    1717

    The port number for the Core Hub WebSocket

    licenseFilePath

    string

    No

    "gs-license.dat"

    Path to the gs-license.dat file

    moduleTag

    string

    No

    "nodejs-module"

    The module identifier tag

    ssl

    boolean

    No

    false

    Whether to use SSL/TLS

    keystorePath

    string

    No

    null

    Path to JKS keystore file (required if ssl=true)

    keystorePassword

    string

    No

    null

    Password for the JKS keystore

    pingInterval

    number

    No

    1000

    Interval in milliseconds between ping messages

    timeout

    number

    No

    10000

    Connection timeout in milliseconds

    discoveryStartPort

    number

    No

    1717

    The base port number for UDP discovery

    discoveryPortRange

    number

    No

    10

    Number of ports to scan for UDP discovery

    API Reference

    GluesyncClient Methods

    • connect(): Establishes a WebSocket connection to the Core Hub

    • disconnect(): Closes the WebSocket connection

    Properties

    • token: The JWT token received from Core Hub

    • connectionStatus: Current status of the connection

    • isConnected: Returns true if connected, false otherwise

    Event Handlers

    • onConnected(token): Called when connection is successfully established

    • onDisconnected(reason): Called when connection is closed

    • onError(error): Called when an error occurs

    Events (EventEmitter API)

    • connected: Emitted when connection is successfully established

    • disconnected: Emitted when connection is closed

    • error: Emitted when an error occurs

    For complete API documentation, please visit the GitLab repository: Node.js SDK on GitLab.

    Source Code & Contributing

    The Node.js SDK is open source and available on GitLab:

    • Repository: Node.js SDK on GitLab

    • Issues: Please report bugs and feature requests through the GitLab issue tracker

    • Contributing: See the CONTRIBUTING section in the repository for guidelines

    License

    The Gluesync Node.js SDK is dual-licensed under the following licenses:

    1. GNU General Public License (GPL) Version 3 You may use, modify, and distribute this software under the terms of the GPL v3. See the LICENSE-GPL file or GPL v3 for details. This option is available at no cost, but any derivative works must also be licensed under GPL v3.

    2. MOLO17 Commercial License Alternatively, you may use this software under the MOLO17 Commercial License, which includes a warranty and permits proprietary use. Contact MOLO17 at info@molo17.com for licensing terms and conditions.

    You must choose one of these licenses to use this software. Using this software implies acceptance of one of these licenses.

    Copyright © 2025 MOLO17. All rights reserved.