@smartpointstech/sptflo-nats

DEPRECATED: sptflo-nats has been replaced by SPT Wire (spt-wire crate). See ADR-088.

SPTFlo NATS client - real-time messaging for swarm coordination and event streaming (deprecated).

Overview

This package provides a high-level NATS client for SPTFlo event messaging. It wraps the nats.js client with typed event publishing and subscription, offering purpose-built helpers for swarm lifecycle events (creation, task assignment, task completion). Includes both core pub/sub via SptNatsClient and JetStream support via SptJetStream.

Installation

npm install @smartpointstech/sptflo-nats

Key Features

• Typed Event Messaging -- publish and subscribe to SptEvent envelopes with full type safety
• Swarm Event Helpers -- pre-built functions for swarm creation, task assignment, and completion
• JetStream Support -- durable, persistent streaming via SptJetStream
• Subject Hierarchy -- structured NATS subject naming for swarm coordination
• Connection Management -- status reporting, drain, and reconnection handling

Dependencies

Key external dependencies:

• nats -- NATS.js client library (v2.28+)

Quick Start

import { SptNatsClient, publishSwarmCreated, subscribeToSwarm } from '@smartpointstech/sptflo-nats';

const client = await SptNatsClient.connect('nats://localhost:4222');

await publishSwarmCreated(client, { swarmId: 'swarm-1', topology: 'hierarchical' });

await subscribeToSwarm(client, 'swarm-1', {
  onTaskAssigned: (event) => console.log('Task assigned:', event),
  onTaskCompleted: (event) => console.log('Task completed:', event),
});

API Reference

Exports

Export	Type	Description
SptNatsClient	class	High-level NATS client for typed event pub/sub
SptJetStream	class	JetStream wrapper for durable streaming
publishSwarmCreated	function	Publish a swarm creation event
publishTaskAssign	function	Publish a task assignment event
publishTaskComplete	function	Publish a task completion event
subscribeToSwarm	function	Subscribe to all events for a swarm
ConnectionStatus	type	Connection status shape
Subscription	type	Subscription handle with unsubscribe/drain
SwarmEventHandlers	type	Callback map for swarm event subscription