Scadable Stream

[crypto-a]

User Story

As a React developer
I need a useLiveTelemetry hook connected to Device objects from a Facility
So that I can consume real-time telemetry data directly inside my React components

Details and Assumptions

• The WebSocket connection uses URL parameters:

  • wss://URL?token=<api_key>&deviceid=<device_id>

• No authorization headers are allowed.

• Facility manages the API key.

• Device manages the device ID and WebSocket connection.

• Developers should register a handler via a React hook (useLiveTelemetry), not decorators (since React is function-component-driven).

• Hook should handle subscription, cleanup, and updating React state.

• TypeScript types must be provided for telemetry data.

• Documentation and 100% test coverage required (unit tests with mocks for WebSocket).

Acceptance Criteria

Given a Facility initialized with a valid API key
And a Device initialized with the Facility and a device ID
When I call useLiveTelemetry(device)
Then a WebSocket connection should open at wss://URL?token=<api_key>&deviceid=<device_id>
And incoming telemetry messages should update React state

Given an incoming message is valid JSON
When received through the WebSocket
Then it should be parsed into an object
And provided as the latest state from useLiveTelemetry

Given an incoming message is not valid JSON
When received through the WebSocket
Then the raw string should be returned as telemetry state

Given the React component unmounts
When useLiveTelemetry is active
Then the WebSocket connection should be closed

Example Use

// App.tsx
import React, { useEffect } from "react";
import { Facility, Device, useLiveTelemetry } from "scadable";

const facility = new Facility("secure-key");
const device = new Device(facility, "device-id");

export default function App() {
  const telemetry = useLiveTelemetry(device);

  // Log all incoming data
  useEffect(() => {
    if (telemetry) {
      console.log("Telemetry received:", telemetry);
    }
  }, [telemetry]);

  return (
    <div>
      <h1>Scadable Stream</h1>
      {/* Safely render temperature if present */}
      <p>
        Temperature:{" "}
        {telemetry && "temperature" in telemetry ? telemetry.temperature : "--"}
      </p>
    </div>
  );
}