@model-match/realtime

Browser-safe client for Model Match realtime notifications. Subscribe a user to their realtime feed with only a token — the endpoint, IoT authorizer, app/stage, and the user's id are discovered from the Model Match API at connect time.

npm install @model-match/realtime

Usage

import { createNotificationClient } from "@model-match/realtime";

const client = createNotificationClient({
	token: "<the user's Model Match token>", // api key, JWT, or OAuth bearer
});

// Fires for every event on the user's feed.
client.subscribe((envelope) => {
	console.log(envelope.channel, envelope.data);
});

// Fires only for events on the "loans" channel.
client.subscribe((envelope) => render(envelope), { channel: "loans" });

await client.connect();

On connect(), the client calls GET /v1/realtime/config on the Model Match API with the token, receives { endpoint, authorizerName, app, stage, userId }, then opens an MQTT-over-WSS connection to AWS IoT using the IoT custom authorizer. The authorizer validates the token server-side and grants only the caller's own topics — the client cannot subscribe to topics it has not been granted.

Token kinds

The token kind is sniffed from the token shape (mm_* → api key, a.b.c → JWT, otherwise an opaque OAuth bearer). Override it with tokenKind and point at a non-prod API with apiBaseUrl:

createNotificationClient({
	token,
	tokenKind: "bearer",
	apiBaseUrl: "https://api.live.modelmatch.co",
});

Custom fetch

Pass fetch to inject an implementation in environments without a global fetch:

createNotificationClient({ token, fetch: myFetch });

Notes

• EventBridge delivery is at-least-once; the client dedupes recent envelopes by eventId (in-memory LRU, configurable via dedupeCacheSize).
• Listener errors are isolated — a throwing listener does not affect others.