Module @hiyve/semantic-relay-client

@hiyve/semantic-relay-client — framework-agnostic browser client for the Hiyve Semantic Relay (Go WebTransport datagram service).

Designed for high-frequency, fire-and-forget, room-scoped messaging where the WebRTC data channel's per-message overhead (negotiation, peer-to-peer routing, JSON snapshot envelopes) is too heavy. Typical use cases: instrument note events, semantic-avatar blendshape streams, spatial audio cues.

For React applications, use @hiyve/react-semantic-relay which wraps this client with a context provider and topic-scoped pub/sub hooks.

Example

import { SemanticRelayClient } from '@hiyve/semantic-relay-client';

const client = new SemanticRelayClient({
  url: 'https://semantic.hiyve.tv:4443/relay',
  roomId: 'lesson-abc',
  userId: 'alice@example.com',
  token: jwtFromBackend,
  serverCertificateHashes,
});

await client.connect();

const unsubscribe = client.subscribe('instrument-notes', ({ payload, userId }) => {
  console.log(`${userId} played`, payload);
});

client.publish('instrument-notes', { midi: 60, on: true, velocity: 100 });
// ...
unsubscribe();
client.dispose();

@hiyve/semantic-relay-client

Framework-agnostic browser client for the Hiyve Semantic Relay — a WebTransport (HTTP/3 / QUIC) datagram service co-deployed with the signaling server, built for high-frequency, fire-and-forget, room-scoped messaging.

For React applications, use @hiyve/react-semantic-relay which wraps this client with a context provider and topic-scoped pub/sub hooks.

Installation

npm install @hiyve/semantic-relay-client

Quick start

import { SemanticRelayClient } from '@hiyve/semantic-relay-client';

const client = new SemanticRelayClient({
  url: 'https://semantic.hiyve.tv:4443/relay',
  roomId: 'lesson-abc',
  userId: 'alice@example.com',
  token: jwtFromBackend,
  serverCertificateHashes, // optional; required for self-signed dev/prod certs
});

const session = await client.connect();
console.log('session id', session.sessionId, 'peers', session.peers);

const unsubscribe = client.subscribe('instrument-notes', ({ payload, userId }) => {
  console.log(`${userId} played`, payload);
});

client.publish('instrument-notes', { midi: 60, on: true, velocity: 100 });

// Later:
unsubscribe();
client.dispose();

serverCertificateHashes is a RelayCertHash[] of SHA-256 fingerprints — see the WebTransport docs for derivation. Production deployments using a public CA can omit it.

Options

Option	Required	Description
`url`	yes	Base WebTransport URL (`https://...:4443/relay`).
`roomId`	yes	Room identifier — relay-side broadcast scope.
`userId`	yes	Sender identity attached to every published message.
`token`	yes	Short-lived auth token minted by the app backend.
`serverCertificateHashes`	no	SHA-256 certificate hashes for self-signed certs.
`onError`	no	Connection / publish / decode errors.
`onConnectionChange`	no	Notification when the connection state changes (`connecting`, `connected`, `closed`, `error`).
`onDebug`	no	Debug logger; pairs with `createDebugLogger('hiyve:semantic-relay')`.
`maxSeenMessages`	no	Per-topic dedupe cache size (default 200).
`pruneCount`	no	Dedupe entries dropped when the cache is full (default 50).
`retryDelaysMs`	no	Connect-retry backoff (default `[200, 800, 2000]`). Auth failures bypass.

The client wraps relay messages in a small envelope; serialization, framing, and identity stamping are handled internally.

Limits

One sender per connection (peer routing is server-side).
Up to 100 participants per room (relay-enforced).
Max envelope size ~1200 bytes (MAX_DATAGRAM_BYTES); larger messages should fragment at the application layer.

Browser support

WebTransport is available in Chrome, Edge, and Firefox. Safari requires an experimental flag at the time of writing. Consumers should fall back to a different transport when globalThis.WebTransport is undefined.

Types & constants

Export	Description
`SemanticRelayClient`	The client class.
`RelayCertHash`	Shape of a single SHA-256 cert hash entry.
`RelayConnectionState`	`'idle' \| 'connecting' \| 'connected' \| 'error' \| 'closed'`.
`RelayEnvelope<T>`	Wire envelope shape.
`RelayMessage<T>`	Subscriber-visible message: `{ topic, payload, userId, messageId, timestamp }`.
`RelayOptions`	Constructor options shape.
`DefaultedRelayOptions`	Options after defaults are applied.
`RelaySubscribeHandler<T>`	Callback signature for `subscribe`.
`SessionInfo`	Session metadata returned by `connect()`.
`DEFAULT_OPTIONS`	The full default options object.
`mergeOptions(user)`	Merge user options on top of `DEFAULT_OPTIONS`.
`MAX_DATAGRAM_BYTES`	Max envelope size (~1200).
`SESSION_ID_HEADER_BYTES`	Bytes reserved for the session-id header in each datagram.
`DEFAULT_MAX_SEEN_MESSAGES`	Default dedupe cache size.
`DEFAULT_PRUNE_COUNT`	Default prune count when the cache is full.
`DEFAULT_RETRY_DELAYS_MS`	Default reconnect backoff schedule.
`DEFAULT_CONNECT_TIMEOUT_MS`	Default connect timeout.
`SESSION_INFO_TYPE`	Tag for `SessionInfo` messages on the control topic.