@notifizz/subscribe-vanilla

Vanilla JavaScript / TypeScript wrapper around the Notifizz subscribe widget. Mount as many widget instances as you need on the same page — one per Kanban card, one per thread, one per resource.

Install

npm install @notifizz/subscribe-vanilla

Quick start

import { createSubscribe } from '@notifizz/subscribe-vanilla';

const subscribe = createSubscribe({
  apiKey: 'ntfz_pk_xxx',          // your env public key
  mode: 'secure',                  // or 'public' for resources with no privacy
  subscriberId: 'user_42',         // matches your backend HMAC input
});

const widget = await subscribe.mount({
  container: '#card-42',           // CSS selector or HTMLElement
  resourceId: 'proj_42',
  hash: 'a1b2c3...',               // required in secure mode
});

widget.subscribe();
widget.onStateChange((state) => {
  console.log('subscribed?', state.isSubscribed);
  console.log('total subs:', state.subscriberCount);
});

Multi-instance — N widgets on the same page

const subscribe = createSubscribe({ apiKey, mode: 'secure', subscriberId });

// Mount one widget per Kanban card
const projects = await fetchProjects();
for (const project of projects) {
  await subscribe.mount({
    container: `#card-${project.id}`,
    resourceId: project.id,
    hash: project.subscribeHash,   // generated server-side per project
  });
}

Widgets that share the same resourceId automatically stay in sync — clicking Subscribe on one updates the avatar list of all the others without a refetch.

Generating the hash (secure mode)

Server-side, using a Notifizz backend SDK:

// Node.js
const hash = notifizz.generateSubscribeToken(subscriberId, resourceId);
// = HMAC-SHA256(authSecretKey, subscriberId + resourceId)

Same method exists in the PHP and Java SDKs. The hash is then passed to mount() from the client.

In public mode, no hash is needed — the backend accepts any subscriberId.

API

createSubscribe(options): SubscribeVanillaApi

| Option | Required | Default | Notes | |---|---|---|---| | apiKey | ✅ | — | Public API key from your Notifizz environment | | mode | ✅ | — | 'secure' (HMAC required) or 'public' | | subscriberId | ✅ | — | Current user's ID — must match the server-side hash input | | apiUrl | | https://eu.api.notifizz.com/v1 | Override for self-hosted / staging | | serverUrl | | https://widget.notifizz.com | Where to load the widget loader from | | widgetPath | | /v1/subscribe-loader.js | Loader path | | autoMount | | false | Whether the widget should scan [data-notifizz-subscribe] automatically. Usually off when driving via mount() | | maxAvatars | | 5 | Default — overridden by org brand if defined | | readyTimeoutMs | | 10000 | How long to wait for the loader to finish |

subscribe.mount(options): Promise<SubscribeHandle>

Mount a widget on a container. Returns a handle to interact with that instance.

| Option | Required | Notes | |---|---|---| | container | ✅ | CSS selector or HTMLElement | | resourceId | ✅ | Identifier of the resource being subscribed to | | hash | If mode === 'secure' | HMAC hash for this (subscriberId, resourceId) pair |

SubscribeHandle methods

handle.subscribe()          // Promise<void>
handle.unsubscribe()        // Promise<void>
handle.toggle()             // Promise<void>
handle.refresh()            // Promise<void> — force refetch from server
handle.getState()           // { isSubscribed, subscriberCount, subscribers[] }
handle.onStateChange(cb)    // () => void — returns unsubscribe function
handle.destroy()            // tear down DOM + listeners

subscribe.destroy()

Tear down all active widget instances created via this subscribe controller. Does NOT remove the loader script (it may be shared with future mounts).

Lifecycle in SPAs

Pair mount() with cleanup in your framework's effect hook:

// React example
useEffect(() => {
  let widget: SubscribeHandle | null = null;
  let cancelled = false;

  subscribe.mount({
    container: ref.current!,
    resourceId: project.id,
    hash: project.subscribeHash,
  }).then((w) => {
    if (cancelled) {
      w.destroy();
    } else {
      widget = w;
    }
  });

  return () => {
    cancelled = true;
    widget?.destroy();
  };
}, [project.id]);

(For React, prefer @notifizz/subscribe-react — it does all this wiring for you.)

Errors

mount() rejects when:

• The loader script fails to load (network / CSP) within readyTimeoutMs
• The container doesn't exist or is already mounted
• mode === 'secure' but no hash is provided
• init() hasn't been called (shouldn't happen via this wrapper — it's automatic)

See also

• @notifizz/subscribe-react — React-native multi-instance with useSubscription hook
• @notifizz/subscribe-angular — Angular component
• Documentation: https://docs.notifizz.com/sdks/subscribe (coming soon)