Status Notification Subscriber

@ambita/status-notification-subscriber is Ambita's lightweight frontend library for receiving real-time infrastructure status messages ("driftsmeldinger"). It subscribes to an AWS IoT (MQTT over WebSocket) topic and emits each published message to your application, so you can show users a banner when a service is degraded.

It is the subscriber half of the status-notification system. The infrastructure (API, IoT topic, IAM, publisher endpoint) lives in the core-account CDK stack. Messages are published by Ambita Support via the Driftsmeldinger page in ambita-support.

New to this? Start with the step-by-step tutorial: Receiving infrastructure messages (Golden Path docs).

Features

• Automatically fetches temporary IoT credentials and subscribes to the notification topic.
• Works per environment (beta or prod).
• Returns an EventEmitter that emits a notification event for every published message.
• Messages are retained on the topic — a newly-connected subscriber immediately receives the current status, without waiting for the next publish.

Installation

npm install @ambita/status-notification-subscriber

Usage

import { subscribeToNotifications } from '@ambita/status-notification-subscriber';

// env must be 'beta' or 'prod' — anything else throws.
const notificationReceiver = await subscribeToNotifications('beta');

notificationReceiver.on('notification', (notification) => {
  // `notification` is the full payload for ALL apps (see Message format below).
  const status = notification['meglerpakke'];
  if (status) {
    showBanner(status.message, status.type); // type is 'info' | 'error'
  } else {
    hideBanner(); // null means no active status for this app
  }
});

subscribeToNotifications is async and resolves once the subscription is established; notifications then arrive over time via the notification event (it is event-driven, not a one-shot synchronous read).

API

subscribeToNotifications(env): Promise<EventEmitter>

| Parameter | Type | Description | | --------- | -------- | -------------------------------------------------------- | | env | string | Environment to connect to. Must be 'beta' or 'prod'. |

Returns a Promise<EventEmitter>. The emitter emits:

• notification — payload: the parsed message object (see below).

Message format

Every published message is a single object containing the status for all applications, keyed by application id. The same payload is delivered on every notification event (this is the wire contract published by Ambita Support):

{
  "meglerpakke": {
    "message": "Vi opplever for øyeblikket problemer med BankID",
    "type": "error",          // 'info' | 'error' — drives banner styling
    "time": "2026-06-23T09:12:00.000Z"  // ISO-8601, when it was published
  },
  "demo": null                // null = no active status for this app (cleared)
}

• Keys are application ids (e.g. meglerpakke, demo). The set of keys is whatever Ambita Support currently publishes — treat it as open, and read only the key(s) your app cares about.
• A value of null means there is no active status for that app; hide your banner.
• The status object fields are message (string), type ('info' | 'error'), and time (ISO-8601 string).

The field is type, not messageType. (Earlier docs showed messageType, which does not exist on the payload.)

How it works

1. Fetches short-lived IoT credentials from the open subscribe endpoint GET https://s15sbtdopj.execute-api.eu-central-1.amazonaws.com/{env}/status-notification/subscribe.
2. Opens an MQTT-over-WebSocket connection to AWS IoT using those credentials (SigV4).
3. Subscribes to the topic /status-notification/{env} and re-emits each retained/live message as a notification event.

See the core-account stack README for the endpoints, topic, IAM roles, and the publish side.

Development

npm install
npm run lint        # eslint (type-aware)
npm run typecheck   # tsc --noEmit
npm run build       # tsc -> dist/, then rollup -> index.js + index.d.ts

CI (.github/workflows/ci.yml) runs lint, typecheck and build on Node 22 and 24, and audits on every push and pull request.

index.js and index.d.ts at the repo root are build output, committed to the repo — they are the only files published (plus package.json and this README). Rebuild and commit them with any src/ change; CI fails if a fresh build does not reproduce what is committed.

Toolchain notes

• TypeScript is pinned to 6.0.3, not 7.x, deliberately. TypeScript 7 is the Go-native rewrite and ships no JavaScript compiler API, which both rollup-plugin-dts and typescript-eslint need. typescript-eslint additionally peers on typescript >=4.8.4 <6.1.0. TS 6.0.3 is a stable release that produces byte-identical output to 7.0.2 here, so staying on 6.x costs nothing and keeps type-aware linting. Revisit once typescript-eslint supports TS 7.
• The paths mapping in tsconfig.json is load-bearing. It resolves aws-iot-device-sdk-v2 to the file dist/browser.d.ts, which re-exports aws-crt/dist.browser/browser where auth.CredentialsProvider lives. The SDK's native typings only expose auth.AwsCredentialsProvider, so removing or breaking that mapping fails the build in src/client/iot-client.ts.
• uuid is pinned via overrides. aws-iot-device-sdk-v2 depends on uuid@^8.3.2, which carries GHSA-w5hq-g745-h8pq. The override raises it to 11.1.1 — the lowest fixed version that still ships a CommonJS build, which matters because the SDK calls require("uuid") and this package targets CommonJS-compatible consumers. Do not raise it to 12+: those are ESM-only and would break require(). Note that npm ignores overrides coming from a dependency, so this protects this repo and its CI, not consumers — the real fix is for the SDK to widen its range upstream.

Known limitation

subscribeToNotifications keeps its credentials and MQTT client in module-level variables, so calling it more than once in the same process makes the calls clobber each other. It is designed for a single subscription per application, which is how it is used today.

See also

• Tutorial: Receiving infrastructure messages — Golden Path step-by-step guide
• core-account StatusNotification stack — the infrastructure and publisher