Terra Pulse

Overview

Pulse is the consumer half of a Streaming API integration. It opens a WebSocket to Terra's broker, authenticates as a consumer, and renders every reading the moment it arrives, with no SDK in between. A small Express server stands in for your backend, so your API key never reaches the browser. For the producer half, see Terra Grip.

What's inside

1. Consumer connection: a WebSocket to Terra's broker that receives live readings for every user you stream.
2. Server-side tokens: a single-use developer token minted by your backend, so the API key stays off the client.
3. Connection lifecycle: HELLO, IDENTIFY, READY and DISPATCH, with jittered heartbeats and a clear close-code policy.
4. Resilient reconnects: a fresh token and exponential backoff on every retry, with dropped connections kept apart from protocol errors.
5. Live dashboard: per-user, per-type rolling buffers feeding a scrolling chart and sparkline cards.

Run it locally

You need the Terra CLI, Node.js 18 or later, and a dev ID and API key from the Terra dashboard. No hardware required.

1. Clone and configure

terra examples clone streaming-consumer-web-app my-appcd my-appnpm installcp .env.example .env

Add your dev ID and API key to .env. Only the token server reads them.

2. Start the app

npm run dev

This starts the token server on port 4000 and the app on 5173. Open localhost:5173 and the status pill turns from Connecting to Live once Terra sends READY.

3. Generate some data

Pulse only receives. On the streaming page of the dashboard, add a test user and choose Generate test data. Their section appears as soon as readings flow.

Next steps

The whole integration lives in src/lib/consumer.ts, so start there. Tokens come from a single mintToken function in src/lib/stream.ts: point it at your own endpoint and the consumer drops straight into your product. Pair it with Terra Grip to watch a real wearable stream end to end.