Node SDK
Full Documentation
This is the client SDK for EnSync engine (event-delivery based integration engine) that enables you to integrate with third-party apps as though they were native to your system and in realtime.
See Documentation on EnSync Engine.
See Documentation on Our SDKs.
Installation
npm install ensync-client-sdk
Usage
import { EnSyncEngine, EnSyncError } from "ensync-client-sdk"
API Reference
EnSyncEngine
The main class that manages connections and client creation for the EnSync system.
const engine = new EnSyncEngine(url, options)
Parameters for EnSyncEngine
url
(string): The URL of the EnSync server
options
(EnSyncEngineOptions):
{
version?: string; // API version to use (default: 'v1')
disableTls?: boolean; // Whether to disable TLS verification (default: false)
ignoreException?: boolean; // Whether to ignore exceptions (default: false)
renewAt?: number; // Time in milliseconds before client renewal (default: 420000)
}
Events
error
: Emitted when an error occurs
connect
: Emitted when connection is established
disconnect
: Emitted when connection is closed
Client Creation
const client = await engine.createClient(accessKey)
Parameters [Client Creation]
Returns [Client Creation]
Returns a new EnSyncClient instance
Publishing Events
await client.publish(eventName, payload, metadata)
Parameters [Publishing Events]
eventName
(string): The name of the event to publish
payload
(any): User-defined data structure to be published
metadata
(EnSyncPublishOptions):
{
persist?: boolean; // Whether to persist the event (default: true)
headers?: Object; // Additional headers
}
Example
await client.publish('power-usage', {
current: 100,
unit: 'kWh',
source: 'power-meter-1',
timestamp: Date.now()
});
Subscribing to Events
const subscription = await client.subscribe(eventName)
Parameters [Subscribing to Events]
Returns
Returns a subscription object with the following methods:
{
pull: (options: EnSyncSubscribeOptions, callback: (record: EnSyncEventPayload) => Promise<void>) => void;
ack: (eventId: string, block: string) => Promise<string>;
rollback: (eventId: string, block: string) => Promise<string>;
stream: (options: EnSyncSubscribeOptions, callback: (record: EnSyncEventPayload) => Promise<void>) => void;
unsubscribe: () => Promise<string>;
}
Received Event Structure (EnSyncEventPayload)
When receiving events through subscription callbacks, the events will have this structure:
{
id: string; // Event identifier
block: string; // Block identifier
name: string; // Event name
data: any; // User-defined event data
timestamp: number; // Event timestamp
header: Object; // Additional header information
}
Closing Connections
await client.destroy(stopEngine)
Complete Examples
Event Producer
const { EnSyncEngine } = require("ensync-client-sdk");
const response = async () => {
try {
const eventName = "yourcompany/payment/POS/PAYMENT_SUCCESSFUL";
const engine = new EnSyncEngine("https://localhost:8443", {
disableTls: true
});
const client = await engine.createClient("your-access-key");
// Payload is user-defined
await client.publish(eventName, {
transactionId: "123",
amount: 100,
terminal: "pos-1",
timestamp: Date.now()
});
await client.destroy();
} catch(e) {
console.error("Error:", e?.message);
}
}
Event Subscriber
const { EnSyncEngine } = require("ensync-client-sdk");
const response = async () => {
try {
const eventName = "yourcompany/payment/POS/PAYMENT_SUCCESSFUL";
const engine = new EnSyncEngine("https://localhost:8443", {
disableTls: true
});
const client = await engine.createClient("your-access-key");
const subscription = await client.subscribe(eventName);
subscription.pull({ autoAck: false }, async (event) => {
try {
// event is an EnSyncEventPayload
console.log("Event ID:", event.id);
console.log("Event Block:", event.block);
console.log("Event Data:", event.data); // Contains the user-defined payload
console.log("Event Timestamp:", event.timestamp);
await subscription.ack(event.id, event.block);
await subscription.unsubscribe();
} catch (e) {
console.error("Processing error:", e);
}
});
} catch(e) {
console.error("Error:", e?.message);
}
}
Error Handling
The SDK throws EnSyncError
for various error conditions. Always wrap your code in try-catch blocks to handle potential errors gracefully.
try {
// Your EnSync code
} catch (e) {
if (e instanceof EnSyncError) {
console.error("EnSync Error:", e.message);
} else {
console.error("Unexpected error:", e);
}
}
Last modified: 13 February 2025