@phoenix-iq/notifications 0.0.0-stage → 1.1.0

package/dist/index.js

@@ -0,0 +1,501 @@
+import { mountBanner } from './banner.js';
+import { mountBell } from './bell.js';
+import { keys, store } from './store.js';
+/**
+ * Phoenix Notifications web SDK: subscribes the browser to web push for an app on notifications.phnx-iq.com, binds it to
+ * the signed-in user with an identity token from the app's own backend, and hands notification clicks to the app. When the
+ * app has its subscription bell or banner switched on in HQ, it also draws them, so a site needs no button of its own.
+ *
+ * Nothing here throws for an unsupported browser or a denied permission: check `isSupported()` / `permission()`.
+ * The service worker file (phoenix-notifications-sw.js) must be served from the site, at `serviceWorkerPath`.
+ */
+export const DEFAULT_SERVER_URL = 'https://notifications.phnx-iq.com';
+export const DEFAULT_SERVICE_WORKER_PATH = '/phoenix-notifications-sw.js';
+export class NotificationsError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'NotificationsError';
+        this.status = status;
+    }
+}
+const CLICK_MESSAGE = 'phoenix-notifications:click';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RESYNC_AFTER_MS = DAY_MS;
+let options = {
+    appId: '',
+    serverUrl: DEFAULT_SERVER_URL,
+    serviceWorkerPath: DEFAULT_SERVICE_WORKER_PATH,
+    serviceWorkerScope: '/',
+    language: '',
+};
+let registration = null;
+let ready = null;
+let syncing = null;
+/** The last successful sync of this page, so init and login on the same load ask the server once. */
+let synced = null;
+const SYNC_REUSE_MS = 5 * 60 * 1000;
+/** The app's web config, read once per page: the subscription and the bell both need it. */
+let config = null;
+const clickHandlers = new Set();
+const changeHandlers = new Set();
+let lastState = null;
+let listening = false;
+let watchingPermission = false;
+let bell = null;
+let banner = null;
+function supported() {
+    return (typeof window !== 'undefined' &&
+        window.isSecureContext &&
+        'serviceWorker' in navigator &&
+        'PushManager' in window &&
+        'Notification' in window &&
+        'indexedDB' in window);
+}
+function url(path) {
+    return `${options.serverUrl.replace(/\/+$/, '')}${path}`;
+}
+async function call(method, path, body, deviceSecret) {
+    const headers = {};
+    if (body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    if (deviceSecret)
+        headers.Authorization = `Device ${deviceSecret}`;
+    const response = await fetch(url(path), { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+    if (response.status === 204)
+        return undefined;
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        payload = undefined;
+    }
+    if (!response.ok)
+        throw new NotificationsError(response.status, payload?.errors?.join(' ') || `Request failed with ${response.status}`);
+    return payload?.result;
+}
+function webConfig(force = false) {
+    if (force || !config || config.appId !== options.appId) {
+        const appId = options.appId;
+        const value = call('GET', `/v1/apps/${appId}/web`);
+        // a failed read is not kept: the next call asks again
+        value.catch(() => {
+            if (config?.value === value)
+                config = null;
+        });
+        config = { appId, value };
+    }
+    return config.value;
+}
+function toBytes(base64Url) {
+    const padded = base64Url.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (base64Url.length % 4)) % 4);
+    const raw = atob(padded);
+    const bytes = new Uint8Array(new ArrayBuffer(raw.length));
+    for (let i = 0; i < raw.length; i++)
+        bytes[i] = raw.charCodeAt(i);
+    return bytes;
+}
+function toBase64Url(buffer) {
+    if (!buffer)
+        return '';
+    let raw = '';
+    for (const byte of new Uint8Array(buffer))
+        raw += String.fromCharCode(byte);
+    return btoa(raw).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function sameKey(subscription, vapidKey) {
+    return toBase64Url(subscription.options.applicationServerKey) === vapidKey.replace(/=+$/, '');
+}
+function subscriptionBody(subscription, vapidKey) {
+    return {
+        endpoint: subscription.endpoint,
+        p256dh: toBase64Url(subscription.getKey('p256dh')),
+        auth: toBase64Url(subscription.getKey('auth')),
+        applicationServerKey: vapidKey,
+    };
+}
+function language() {
+    return options.language || document.documentElement.lang || navigator.language;
+}
+function deviceInfo() {
+    return {
+        language: language(),
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        appVersion: options.appVersion,
+        os: navigator.platform || undefined,
+        deviceModel: navigator.userAgent.slice(0, 200),
+    };
+}
+function listenForClicks() {
+    if (listening)
+        return;
+    listening = true;
+    navigator.serviceWorker.addEventListener('message', (event) => {
+        const message = event.data;
+        if (message?.type !== CLICK_MESSAGE)
+            return;
+        const click = { url: message.url, data: message.data ?? {}, messageId: message.messageId };
+        if (clickHandlers.size === 0) {
+            if (click.url)
+                window.location.assign(click.url);
+            return;
+        }
+        for (const handler of clickHandlers)
+            handler(click);
+    });
+    // messages from the worker wait in a queue until the page says it is listening
+    navigator.serviceWorker.startMessages();
+}
+async function optedOut() {
+    return !!options.appId && !!(await store.get(keys.optOut(options.appId)));
+}
+async function currentState() {
+    if (!supported())
+        return { permission: 'unsupported', subscribed: false };
+    const permission = Notification.permission;
+    if (permission !== 'granted' || !options.appId)
+        return { permission, subscribed: false };
+    const [device, out] = await Promise.all([store.get(keys.device(options.appId)), optedOut()]);
+    return { permission, subscribed: !!device && !out };
+}
+/** Tells the listeners when the state changed; never throws. */
+async function announce() {
+    try {
+        const state = await currentState();
+        const key = `${options.appId}:${state.permission}:${state.subscribed}`;
+        if (key === lastState)
+            return;
+        lastState = key;
+        for (const handler of changeHandlers)
+            handler(state);
+    }
+    catch {
+        // a listener's failure or a blocked IndexedDB must not break the caller
+    }
+}
+/** Subscribes (or renews the subscription) and registers or updates the device. Needs the permission granted, and no opt-out. */
+async function sync() {
+    if (!registration || Notification.permission !== 'granted' || (await optedOut()))
+        return null;
+    const web = await webConfig();
+    if (!web)
+        return null;
+    const vapidKey = web.vapidPublicKey;
+    await store.set(keys.config, { appId: options.appId, serverUrl: options.serverUrl, vapidKey });
+    let subscription = await registration.pushManager.getSubscription();
+    // a subscription made with another key (an earlier key of this app, or another push provider) cannot receive our pushes
+    if (subscription && !sameKey(subscription, vapidKey)) {
+        await subscription.unsubscribe();
+        subscription = null;
+    }
+    subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: toBytes(vapidKey) });
+    const stored = await store.get(keys.device(options.appId));
+    const body = { subscription: subscriptionBody(subscription, vapidKey), ...deviceInfo() };
+    if (stored) {
+        const changed = stored.endpoint !== subscription.endpoint || stored.vapidKey !== vapidKey;
+        if (!changed && Date.now() - stored.syncedAt < RESYNC_AFTER_MS)
+            return stored;
+        try {
+            await call('PUT', `/v1/devices/${stored.id}`, changed ? body : deviceInfo(), stored.secret);
+            const updated = { ...stored, endpoint: subscription.endpoint, vapidKey, syncedAt: Date.now() };
+            await store.set(keys.device(options.appId), updated);
+            return updated;
+        }
+        catch (error) {
+            // the server no longer knows this device (or another record owns the subscription): register it again
+            if (!(error instanceof NotificationsError) || ![401, 404, 409].includes(error.status))
+                throw error;
+        }
+    }
+    const registered = await call('POST', `/v1/apps/${options.appId}/devices`, body);
+    if (!registered)
+        return null;
+    const device = {
+        appId: options.appId,
+        id: registered.deviceId,
+        secret: registered.deviceSecret,
+        endpoint: subscription.endpoint,
+        vapidKey,
+        syncedAt: Date.now(),
+    };
+    await store.set(keys.device(options.appId), device);
+    await store.remove(keys.login(options.appId));
+    return device;
+}
+function syncOnce(force = false) {
+    if (!force && synced && synced.device.appId === options.appId && Date.now() - synced.at < SYNC_REUSE_MS)
+        return Promise.resolve(synced.device);
+    syncing ??= sync()
+        .then((device) => {
+        synced = device ? { device, at: Date.now() } : null;
+        return device;
+    })
+        .finally(() => {
+        syncing = null;
+        void announce();
+    });
+    return syncing;
+}
+/**
+ * A login made before the person allowed notifications (or kept through an unsubscribe) is applied once there is a device.
+ * Its failure does not undo the subscription: an expired token is dropped, and the site logs in again on its next load.
+ */
+async function applyPendingLogin(device) {
+    if (!device)
+        return;
+    const pending = await store.get(keys.login(options.appId));
+    if (!pending || pending.at !== 0)
+        return;
+    try {
+        await Notifications.login(pending.token);
+    }
+    catch (error) {
+        if (error instanceof NotificationsError && error.status === 401)
+            await store.remove(keys.login(options.appId));
+        console.warn('[notifications] the pending login failed', error);
+    }
+}
+/** Follows permission changes made outside the page (the site settings next to the address bar). */
+function watchPermission() {
+    if (watchingPermission)
+        return;
+    watchingPermission = true;
+    let known = Notification.permission;
+    const changed = () => {
+        if (Notification.permission === known)
+            return;
+        known = Notification.permission;
+        if (known === 'granted')
+            void syncOnce(true).catch(() => undefined);
+        void announce();
+    };
+    window.addEventListener('focus', changed);
+    void navigator.permissions
+        ?.query({ name: 'notifications' })
+        .then((status) => status.addEventListener('change', changed))
+        .catch(() => undefined);
+}
+/** Draws the bell once the app's config says so. A failure only means no bell. */
+async function showBell(appId) {
+    try {
+        const web = await webConfig();
+        if (bell?.appId !== appId || !web?.bell?.enabled)
+            return;
+        if (document.readyState === 'loading')
+            await new Promise((resolve) => document.addEventListener('DOMContentLoaded', resolve, { once: true }));
+        if (bell?.appId !== appId || bell.handle)
+            return;
+        bell.handle = mountBell({
+            state: currentState,
+            subscribe: async () => {
+                await Notifications.requestPermission();
+                return currentState();
+            },
+            unsubscribe: () => Notifications.unsubscribe(),
+            onChange: (handler) => Notifications.onSubscriptionChange(handler),
+        }, web.bell, language());
+    }
+    catch (error) {
+        console.warn('[notifications] the subscription bell is not available', error);
+    }
+}
+function whenDocumentReady() {
+    if (document.readyState !== 'loading')
+        return Promise.resolve();
+    return new Promise((resolve) => document.addEventListener('DOMContentLoaded', () => resolve(), { once: true }));
+}
+/**
+ * Slides the banner in when its time has come: only for a browser never asked (the permission still to be given, and no
+ * unsubscribe here), from the page view HQ set, not within the days after a "Later", and after the delay. Each call is one page
+ * view. A failure only means no banner.
+ */
+async function showBanner(appId) {
+    try {
+        const web = await webConfig();
+        const settings = web?.banner;
+        if (banner?.appId !== appId || !settings?.enabled)
+            return;
+        if (Notification.permission !== 'default' || (await optedOut()))
+            return;
+        const key = keys.banner(appId);
+        const stored = (await store.get(key)) ?? { appId, views: 0 };
+        const views = Math.min(stored.views + 1, 1000);
+        await store.set(key, { ...stored, views });
+        if (views < settings.pageViews)
+            return;
+        if (stored.dismissedAt && Date.now() - stored.dismissedAt < settings.repromptDays * DAY_MS)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, Math.max(0, settings.delaySeconds) * 1000));
+        await whenDocumentReady();
+        // the page may have moved on meanwhile: another app, the person subscribed with the bell, or answered the browser
+        if (banner?.appId !== appId || banner.handle || Notification.permission !== 'default' || (await optedOut()))
+            return;
+        banner.handle = mountBanner({
+            subscribe: async () => {
+                await Notifications.requestPermission();
+                return currentState();
+            },
+            dismiss: async () => {
+                const latest = (await store.get(key)) ?? { appId, views };
+                await store.set(key, { ...latest, dismissedAt: Date.now() });
+            },
+            onChange: (handler) => Notifications.onSubscriptionChange(handler),
+        }, settings, language(), { iconUrl: web?.iconUrl, aboveBell: !!bell?.handle });
+    }
+    catch (error) {
+        console.warn('[notifications] the subscription banner is not available', error);
+    }
+}
+export const Notifications = {
+    /** True when this browser can receive web push here (a secure context with service workers and the Push API). */
+    isSupported() {
+        return supported();
+    },
+    /**
+     * Registers the service worker, and draws the subscription bell and the banner when the app has them on. When the person
+     * already allowed notifications (and did not unsubscribe here), subscribes quietly.
+     */
+    async init(init) {
+        if (!supported())
+            return;
+        if (!init.appId)
+            throw new Error('Notifications.init needs the appId.');
+        options = {
+            appId: init.appId,
+            serverUrl: init.serverUrl ?? DEFAULT_SERVER_URL,
+            serviceWorkerPath: init.serviceWorkerPath ?? DEFAULT_SERVICE_WORKER_PATH,
+            serviceWorkerScope: init.serviceWorkerScope ?? '/',
+            language: init.language ?? '',
+            appVersion: init.appVersion,
+        };
+        // one bell per page, for the app last initialised
+        const wantsBell = init.bell !== false;
+        if (bell && (bell.appId !== init.appId || !wantsBell)) {
+            bell.handle?.destroy();
+            bell = null;
+        }
+        if (wantsBell && !bell) {
+            bell = { appId: init.appId, handle: null };
+            void showBell(init.appId);
+        }
+        // the banner likewise; a second init of the same app on one page (React's strict mode) is no second page view
+        const wantsBanner = init.banner !== false;
+        if (banner && (banner.appId !== init.appId || !wantsBanner)) {
+            banner.handle?.destroy();
+            banner = null;
+        }
+        if (wantsBanner && !banner) {
+            banner = { appId: init.appId, handle: null };
+            void showBanner(init.appId);
+        }
+        ready = (async () => {
+            registration = await navigator.serviceWorker.register(options.serviceWorkerPath, { scope: options.serviceWorkerScope });
+            listenForClicks();
+        })();
+        await ready;
+        watchPermission();
+        if (Notification.permission === 'granted')
+            await applyPendingLogin(await syncOnce(true));
+        else
+            void announce();
+    },
+    permission() {
+        return supported() ? Notification.permission : 'unsupported';
+    },
+    /** Whether this browser gets the app's notifications now. */
+    getState() {
+        return currentState();
+    },
+    /**
+     * Asks the person (call it from a click: browsers only ask on a user gesture) and subscribes when they allow. It also
+     * subscribes again after `unsubscribe()`, without asking, since the browser keeps the permission.
+     */
+    async requestPermission() {
+        if (!supported())
+            return 'unsupported';
+        const result = await Notification.requestPermission();
+        if (result !== 'granted') {
+            void announce();
+            return result;
+        }
+        if (options.appId)
+            await store.remove(keys.optOut(options.appId));
+        await ready;
+        await applyPendingLogin(await syncOnce(true));
+        return result;
+    },
+    /**
+     * Binds this browser to the user an identity token from the app's backend vouches for. Before the person allows
+     * notifications there is no device yet: the token is kept and used once they do.
+     */
+    async login(identityToken) {
+        if (!supported())
+            return;
+        await ready;
+        const loginKey = keys.login(options.appId);
+        const previous = await store.get(loginKey);
+        const device = await syncOnce();
+        if (!device) {
+            await store.set(loginKey, { appId: options.appId, token: identityToken, at: 0 });
+            return;
+        }
+        if (previous && previous.token === identityToken && previous.at > 0 && Date.now() - previous.at < RESYNC_AFTER_MS)
+            return;
+        await call('POST', `/v1/devices/${device.id}/login`, { identityToken }, device.secret);
+        await store.set(loginKey, { appId: options.appId, token: identityToken, at: Date.now() });
+    },
+    /** The browser keeps receiving the app's broadcasts as a guest, but no longer this user's notifications. */
+    async logout() {
+        if (!supported() || !options.appId)
+            return;
+        await store.remove(keys.login(options.appId));
+        const device = await store.get(keys.device(options.appId));
+        if (device)
+            await call('POST', `/v1/devices/${device.id}/logout`, undefined, device.secret);
+    },
+    /**
+     * Stops notifications in this browser altogether, and remembers it: later page loads do not subscribe again although the
+     * permission stays granted, until `requestPermission()` (the bell's "Subscribe").
+     */
+    async unsubscribe() {
+        if (!supported() || !options.appId)
+            return;
+        await store.set(keys.optOut(options.appId), { appId: options.appId, at: Date.now() });
+        synced = null;
+        try {
+            const device = await store.get(keys.device(options.appId));
+            if (device) {
+                await call('DELETE', `/v1/devices/${device.id}`, undefined, device.secret);
+                await store.remove(keys.device(options.appId));
+            }
+            // the user is kept for a later subscription, like a login made before the permission
+            const login = await store.get(keys.login(options.appId));
+            if (login)
+                await store.set(keys.login(options.appId), { ...login, at: 0 });
+            const subscription = await registration?.pushManager.getSubscription();
+            await subscription?.unsubscribe();
+        }
+        finally {
+            void announce();
+        }
+    },
+    /** A notification was clicked while the site was open. Without a handler the SDK opens its link. Returns an unsubscribe function. */
+    onClick(handler) {
+        clickHandlers.add(handler);
+        return () => clickHandlers.delete(handler);
+    },
+    /** Called when this browser subscribes, unsubscribes or the permission changes. Returns an unsubscribe function. */
+    onSubscriptionChange(handler) {
+        changeHandlers.add(handler);
+        return () => changeHandlers.delete(handler);
+    },
+    /** Re-runs the subscription check now (e.g. after the person changed the site's permission). */
+    async refresh() {
+        if (!supported())
+            return;
+        await ready;
+        void webConfig(true).catch(() => undefined);
+        await applyPendingLogin(await syncOnce(true));
+    },
+};

package/dist/store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The SDK's state in IndexedDB, shared with the service worker (which reads `config` to report clicks and to renew a
+ * subscription). Keep the database name, store and keys in step with phoenix-notifications-sw.js.
+ */
+/** What the service worker needs: where to report clicks and the key to subscribe with. */
+export interface StoredConfig {
+    appId: string;
+    serverUrl: string;
+    vapidKey: string;
+}
+/** This browser's device record on the server. The secret authenticates every later call for the device. */
+export interface StoredDevice {
+    appId: string;
+    id: string;
+    secret: string;
+    endpoint: string;
+    vapidKey: string;
+    /** When the server last heard from this device (ms), to refresh it about once a day. */
+    syncedAt: number;
+}
+/** The user the device was last bound to, so a page load does not log in again with the same token. */
+export interface StoredLogin {
+    appId: string;
+    token: string;
+    at: number;
+}
+export declare const store: {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T): Promise<void>;
+    remove(key: string): Promise<void>;
+};
+/** The person turned notifications off here (the bell's "Unsubscribe", or `unsubscribe()`): a granted permission no longer subscribes. */
+export interface StoredOptOut {
+    appId: string;
+    at: number;
+}
+/** The banner in this browser: page views counted since it was switched on, and the last "Later". */
+export interface StoredBanner {
+    appId: string;
+    views: number;
+    dismissedAt?: number;
+}
+export declare const keys: {
+    config: string;
+    device: (appId: string) => string;
+    login: (appId: string) => string;
+    optOut: (appId: string) => string;
+    banner: (appId: string) => string;
+};

package/dist/store.js

@@ -0,0 +1,48 @@
+/**
+ * The SDK's state in IndexedDB, shared with the service worker (which reads `config` to report clicks and to renew a
+ * subscription). Keep the database name, store and keys in step with phoenix-notifications-sw.js.
+ */
+const DB_NAME = 'phoenix-notifications';
+const STORE = 'state';
+function open() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(DB_NAME, 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(STORE))
+                request.result.createObjectStore(STORE);
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+async function run(mode, action) {
+    const db = await open();
+    try {
+        return await new Promise((resolve, reject) => {
+            const request = action(db.transaction(STORE, mode).objectStore(STORE));
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export const store = {
+    get(key) {
+        return run('readonly', (s) => s.get(key));
+    },
+    set(key, value) {
+        return run('readwrite', (s) => s.put(value, key));
+    },
+    remove(key) {
+        return run('readwrite', (s) => s.delete(key));
+    },
+};
+export const keys = {
+    config: 'config',
+    device: (appId) => `device:${appId}`,
+    login: (appId) => `login:${appId}`,
+    optOut: (appId) => `opt-out:${appId}`,
+    banner: (appId) => `banner:${appId}`,
+};

package/dist/theme.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the bell and the banner share: their default colour, the readable text colour on it, and a light or dark look picked
+ * from the page itself, so they suit the site without settings of their own.
+ */
+export declare const DEFAULT_COLOR = "#2563eb";
+type Rgb = [number, number, number];
+/** `#rrggbb` as given, or the SDK's blue. */
+export declare function colorOr(color: string | null | undefined): string;
+export declare function hexToRgb(hex: string): Rgb;
+/** White or near-black, whichever reads better on the colour. */
+export declare function textOn(color: string): string;
+/** Sets the accent (`--bell`, `--bell-text`, `--ring`) and the page-matched look (`--panel`, `--text`…) on the host. */
+export declare function applyColors(host: HTMLElement, color: string): void;
+/** Again when something opens: the site may have changed its look since. */
+export declare function applyTheme(host: HTMLElement): void;
+/** The language the bell and the banner speak: Arabic for `ar…`, else English. */
+export declare function uiLanguage(language: string): 'ar' | 'en';
+export declare const ICONS: {
+    bell: string;
+    bellOff: string;
+    check: string;
+    close: string;
+};
+export declare function svg(paths: string, size: number, stroke?: number): string;
+export {};