ubudu-rtls-sdk

Official TypeScript SDK for the Ubudu RTLS API.

Features

• Works with JavaScript and TypeScript
• ESM, CommonJS, and browser builds included
• Full TypeScript support with auto-generated types from OpenAPI spec
• Simple, ergonomic API with default context
• WebSocket support for real-time position streaming and publishing
• Built-in async iterators for memory-efficient processing
• Filter DSL for building queries
• Comprehensive error handling with typed error classes
• Request timeout and cancellation support

Installation

npm install ubudu-rtls-sdk

Quick Start

JavaScript (ESM)

import { createRtlsClient } from 'ubudu-rtls-sdk';

// Configure once with default context
const client = createRtlsClient({
  apiKey: process.env.RTLS_API_KEY,
  namespace: 'my-namespace',
});

// List assets (uses default namespace)
const assets = await client.assets.list();

// Get real-time positions
const positions = await client.positions.listCached();

// Set venue for venue-scoped calls
client.setVenue(123);
const zones = await client.zones.list();

TypeScript

import { createRtlsClient, Asset, Position } from 'ubudu-rtls-sdk';

const client = createRtlsClient({
  apiKey: process.env.RTLS_API_KEY,
  namespace: 'my-namespace',
  venueId: 123,
});

// Full type safety
const assets: Asset[] = await client.assets.list();
const positions: Position[] = await client.positions.listCached();

// Spatial queries
const nearbyZones = await client.spatial.nearestZones({
  lat: 48.8566,
  lon: 2.3522,
  limit: 5,
});

CommonJS

const { createRtlsClient } = require('ubudu-rtls-sdk');

const client = createRtlsClient({
  apiKey: process.env.RTLS_API_KEY,
  namespace: 'my-namespace',
});

Documentation

• Getting Started - Installation and first API calls
• Asset Tracking - Asset CRUD, positions, history
• Zone & Geofencing - Spatial queries and presence
• Navigation - POIs, paths, indoor routing
• WebSocket Streaming - Real-time data streaming
• Error Handling - Error types and retry strategies
• Advanced Patterns - Pagination, filtering, patterns
• Migration Guide v2 - Migrating to default context
• API Reference - Complete API documentation

Examples

Both JavaScript and TypeScript examples are available in examples/:

cd examples
npm install
cp .env.example .env  # Add your credentials

JavaScript Examples

npm run js:getting-started     # Basic SDK setup
npm run js:asset-tracking      # Assets and positions
npm run js:zone-geofencing     # Zones and spatial queries
npm run js:navigation          # POIs and navigation paths
npm run js:error-handling      # Error types and retry
npm run js:pagination          # Iterators and filters
npm run js:default-context     # Default context patterns
npm run js:websocket-subscriber  # Real-time event subscription
npm run js:websocket-publisher   # Position publishing
npm run js:websocket-unified     # Combined pub/sub client
npm run js:all                 # Run all JS examples (except WebSocket)

TypeScript Examples

npm run ts:getting-started
npm run ts:asset-tracking
npm run ts:zone-geofencing
npm run ts:navigation
npm run ts:error-handling
npm run ts:pagination
npm run ts:default-context
npm run ts:websocket-subscriber  # Real-time event subscription
npm run ts:websocket-publisher   # Position publishing
npm run ts:websocket-unified     # Combined pub/sub client
npm run ts:all                 # Run all TS examples (except WebSocket)

Note: WebSocket examples require MAP_UUID environment variable for publishing. They are not included in js:all/ts:all since they require additional setup.

Resources

The SDK provides access to these API resources:

Resource	Description
client.assets	Asset CRUD, history, statistics
client.positions	Real-time and historical positions
client.venues	Venues, maps, POIs, paths
client.zones	Zone management and presence
client.spatial	Spatial queries (containing point, nearest, within radius)
client.alerts	Alert rules
client.dashboards	Dashboard configuration
client.navigation	Indoor routing

WebSocket Streaming

Real-time position updates, zone events, and alerts via WebSocket:

import { RtlsWebSocketSubscriber, SubscriptionType } from 'ubudu-rtls-sdk';

const subscriber = new RtlsWebSocketSubscriber({
  apiKey: 'your-api-key',
  namespace: 'your-namespace',
});

// Register event handlers
subscriber.on('POSITIONS', (pos) => {
  console.log(`Tag ${pos.user_uuid} at ${pos.lat}, ${pos.lon}`);
});

subscriber.on('ALERTS', (alert) => {
  console.log(`Alert: ${alert.params.title}`);
});

// Connect and subscribe
await subscriber.connect();
await subscriber.subscribe([
  SubscriptionType.POSITIONS,
  SubscriptionType.ALERTS,
]);

// Later: disconnect
await subscriber.disconnect();

Publishing Positions

Publish positions from external tracking sources:

import { RtlsWebSocketPublisher } from 'ubudu-rtls-sdk';

const publisher = new RtlsWebSocketPublisher({
  apiKey: 'your-api-key',
  namespace: 'your-namespace',
  mapUuid: 'your-map-uuid',  // Required for publishing
});

await publisher.connect();
await publisher.sendPosition({
  macAddress: 'aabbccddeeff',
  latitude: 48.8566,
  longitude: 2.3522,
  name: 'Asset-123',
});

Creating from REST Client

const client = createRtlsClient({
  apiKey: 'your-api-key',
  namespace: 'my-namespace',
});

// Create WebSocket client that shares configuration
const ws = client.createWebSocket({ mapUuid: 'map-uuid' });
await ws.connect();

For Node.js environments, install the ws package:

npm install ws

See WebSocket Guide for complete documentation.

Filtering

Build filters using the filter helpers:

import { createRtlsClient, filters, combineFilters } from 'ubudu-rtls-sdk';

const client = createRtlsClient({
  apiKey: process.env.RTLS_API_KEY,
  namespace: 'my-namespace',
});

const query = combineFilters(
  filters.equals('user_type', 'forklift'),
  filters.contains('user_name', 'warehouse'),
);

const assets = await client.assets.list(query);

Available Filter Operators

Helper	Operator	Description
equals	eq	Exact match
notEquals	ne	Not equal
greaterThan	gt	Greater than
greaterThanOrEqual	gte	Greater than or equal
lessThan	lt	Less than
lessThanOrEqual	lte	Less than or equal
contains	contains	String contains
startsWith	starts	String starts with
endsWith	ends	String ends with
matches	regex	Regex match
in	in	Value in array
notIn	nin	Value not in array
exists	exists	Field exists
between	between	Value in range

Async Iteration

Memory-efficient processing of large datasets:

// Uses default namespace from client
for await (const asset of client.assets.iterate()) {
  console.log(asset.user_name);

  // Can break early without fetching all data
  if (someCondition) break;
}

Error Handling

The SDK provides typed errors for different failure scenarios:

import {
  createRtlsClient,
  RtlsError,
  AuthenticationError,
  NotFoundError,
  ContextError,
} from 'ubudu-rtls-sdk';

const client = createRtlsClient({
  apiKey: process.env.RTLS_API_KEY,
  namespace: 'my-namespace',
});

try {
  await client.assets.get('invalid-mac');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Asset not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Check your API key');
  } else if (error instanceof ContextError) {
    console.log(`Missing: ${error.field} - ${error.suggestion}`);
  } else if (error instanceof RtlsError) {
    console.log(`API error: ${error.status} - ${error.message}`);
  }
}

Configuration Options

const client = createRtlsClient({
  apiKey: 'your-api-key',           // Required: API key
  baseUrl: 'https://rtls.ubudu.com/api', // Optional: API base URL
  timeoutMs: 30000,                  // Optional: Request timeout (default: 30s)
  namespace: 'my-namespace',         // Optional: Default namespace
  venueId: 123,                      // Optional: Default venue ID
  mapId: 456,                        // Optional: Default map ID
  level: 0,                          // Optional: Default floor level
});

Default Context

Configure defaults once and use throughout your application:

// Create client with defaults
const client = createRtlsClient({
  apiKey: 'your-api-key',
  namespace: 'production',
});

// Discover and set venue at runtime
const venues = await client.venues.list();
client.setVenue(venues[0].id);

// All calls use defaults - no parameters needed
const assets = await client.assets.list();
const zones = await client.zones.list();

// Override for specific calls
const stagingAssets = await client.assets.list({ namespace: 'staging' });

// Chainable setters
client.setNamespace('other').setVenue(456).setLevel(0);

// Create scoped clients (immutable)
const venue2Client = client.forVenue(789);

Requirements

• Node.js >= 18 (JavaScript or TypeScript)
• TypeScript >= 5.0 (optional, for type checking)

Browser Support

Browser	Minimum Version	Released
Chrome	94+	Sep 2021
Firefox	93+	Oct 2021
Safari	15+	Sep 2021
Edge	94+	Sep 2021

Development

For contributors and maintainers, see CLAUDE.md for development guidance.

Quick Start (Development)

npm install          # Install dependencies
npm run generate     # Generate types from OpenAPI spec
npm run build        # Build the SDK
npm run test         # Run unit tests
npm run test:integration  # Run integration tests (requires .env)

License

MIT

Links

• Documentation
• API Documentation
• Ubudu Website