JavaScript SDK

ncc-cloud-integration-js is Noccela’s JavaScript and TypeScript client for the real-time API. It hides the WebSocket protocol behind a few promise-based functions and takes care of the parts that are easy to get wrong: finding the site’s node, authentication, pings, token refresh, reconnects and re-registering subscriptions.

Install

The package is installed from GitHub; it is not published in the npm registry.

npm install https://github.com/noccela/ncc-cloud-integration-js

Then import it as an ES module, which keeps the type information and works with bundlers:

import * as Ncc from '@noccela/ncc-cloud-integration';

Other builds in the repository’s dist folder:

• Browser: ncc.min.js, loaded with a script tag.
• Node.js with require: ncc.node.min.cjs. Install the ws package as well: npm install ws.

Connect

An EventChannel is one connection to one site. Create it with the numeric account and site IDs, then connect.

// Replace YOUR_ACCOUNT_ID and YOUR_SITE_ID with your numeric IDs.
const channel = new Ncc.EventChannel(YOUR_ACCOUNT_ID, YOUR_SITE_ID);

Persistent connection (recommended). Pass an async function that returns a fresh access token. The SDK calls it whenever it needs a token: at connect, when less than half of the token’s lifetime is left, and after a reconnect. Your credentials stay in your own code.

async function fetchToken() {
  // Call your backend, or the token endpoint from server-side code:
  // see /developers/authentication/
  const response = await fetch('/api/noccela-token');
  const { token } = await response.json();
  return token;
}

await channel.connectPersistent(fetchToken);
// The authenticated connection now stays up, re-authenticating as needed.

Simple connection. channel.connect(clientId, clientSecret) fetches the token itself. It needs the client secret in the SDK’s process, so use it only in server-side code, never in a browser.

Subscribe

Callbacks follow the Node.js convention: the error first, then the payload. Each registration returns an ID that you can use to unregister.

// Positions only: the lightest stream.
const subscription = await channel.registerLocationUpdate((err, payload) => {
  if (err) return console.error(err);
  for (const [deviceId, { x, y, floor, timestamp }] of Object.entries(payload)) {
    console.log(deviceId, x, y, floor, new Date(timestamp));
  }
}, null); // device IDs, or null for every tag on the site

// The full state of every tag, once, and again after each reconnect.
await channel.registerInitialTagState((err, tags) => { /* … */ }, null);

// Changed tag properties as they happen.
await channel.registerTagDiffStream((err, diff) => { /* diff.tags, diff.removedTags */ }, null);

// Later:
await channel.unregister(subscription);
await channel.close();

The quickstart also uses registerSiteInformation, registerLayoutChanges and getBlueprint to load the floor plan.

Generic and raw access

channel.register(Ncc.EVENT_TYPES['LOCATION_UPDATE'], filters, callback) does the same as the named functions. For real-time actions the SDK does not wrap yet, such as alert streams, send raw requests and listen to raw server messages:

const response = await channel.sendMessageRaw('registerAlertDiffStream', {});
const id = channel.registerToServerMessageRaw('alertDiffStream', (err, payload) => { /* … */ });
channel.unregisterServerMessageRaw('alertDiffStream', id);

Logging

The SDK logs through console-like loggers. Pass your own in the channel options, or an empty list to silence it:

const channel = new Ncc.EventChannel(YOUR_ACCOUNT_ID, YOUR_SITE_ID, {
  loggers: [{ log: () => {}, warn: console.warn, error: console.error, exception: console.error }],
});

What it handles for you

• Looks up the site’s node with /realtime/domain before connecting.
• Sends the token, answers pings and refreshes the token when less than half of its lifetime is left (with connectPersistent).
• Reconnects after a broken connection and registers your subscriptions again.
• Matches responses to requests and filters server messages to the right callbacks.

Known limitations

• Duplicate registrations. The server tracks subscriptions by action and filters. If you register the same event twice with identical filters and then unregister one, both stop. Register each stream once and fan the events out yourself.
• Coverage. The SDK wraps positions, tag state and site information. Alert handling and the HTTP API are not wrapped; use the raw functions and a generated HTTP client.
• Maintenance. Check the repository for the latest changes before you depend on a feature.

Licence

The repository does not include a licence file yet; one is being added. Until it is, contact us before you redistribute the SDK as part of your own product.

Other languages

There is no official SDK for other languages. The real-time protocol is plain JSON over WebSocket plus MessagePack for initial states, so any language with a WebSocket client can use it: follow the real-time API reference. For HTTP, generate a client from the OpenAPI description.