@phoenix-iq/notifications 1.2.0 → 1.2.1

package/README.md

@@ -1,8 +1,9 @@
 # @phoenix-iq/notifications (web SDK)
 
 Browser push for apps on `notifications.phnx-iq.com`. It subscribes the browser (standard Web Push with the app's VAPID key),
-binds it to your signed-in user with an identity token your backend signs, hands notification clicks to your app, and draws
-the subscribe prompt HQ chose for the app: a bell, the app's logo or a pop-up. TypeScript, no dependencies.
+binds it to your signed-in user with an identity token your backend signs, hands notification clicks (and the pushes that
+arrive while your site is open) to your app, and draws the subscribe prompt HQ chose for the app: a bell, the app's logo or a
+pop-up. TypeScript, no dependencies.
 
 How the whole service works, the server API and the identity tokens: [docs/notifications.md](../../docs/notifications.md).
 
@@ -35,8 +36,9 @@ await Notifications.logout();
 ```
 
 `init` subscribes quietly when the person already allowed notifications (and did not unsubscribe here). `login` before the
-permission is granted is kept and applied once it is. Nothing throws on an unsupported browser; check
-`Notifications.isSupported()` and `Notifications.permission()` to decide what to show.
+permission is granted is kept and applied once it is (up to 1.2.0 it was lost when the browser subscribed, and the browser
+stayed a guest until a later `login`). Nothing throws on an unsupported browser; check `Notifications.isSupported()` and
+`Notifications.permission()` to decide what to show.
 
 ## The subscribe prompt
 
@@ -59,6 +61,20 @@ the page's font, pick a light or dark look from the page's background, live in a
 and are hidden when printing. `bell: false` and `banner: false` in `init` keep the button or the pop-up off a page even when
 HQ chose it.
 
+**Room for your layout.** The button sits 20 px from its corner (16 px on phones) and the pop-up 16 px from its edge, above
+everything. Keep them clear of a fixed bottom bar or header with `offset` (CSS pixels), or with CSS variables, which win
+over it and can sit in a media query for a bar only phones have:
+
+```ts
+await Notifications.init({ appId, offset: { bottom: 64 } }); // also `top` (a pop-up at the top) and `side` (the button)
+```
+
+```css
+@media (max-width: 1023px) {
+  :root { --phoenix-notifications-offset-bottom: 64px; } /* and -offset-top, -offset-side */
+}
+```
+
 ## Subscription state
 
 ```ts
@@ -80,7 +96,18 @@ Notifications.onClick(({ url, data }) => router.navigate(new URL(url ?? '/', loc
 ```
 
 A click on a notification focuses an open tab of your site and calls your handler; without a handler the SDK opens the link.
-With no tab open, the browser opens the link directly.
+With no tab open, the browser opens the link directly; with no link (none in the push, no default link in HQ), your site's
+home page.
+
+## 4. Pushes while your site is open
+
+```ts
+Notifications.onPush(({ title, body, url, data, messageId }) => refreshInbox());
+```
+
+The browser shows every push as a notification, open tab or not. `onPush` also tells your open tabs (each of them) that one
+arrived, so they can refresh a list or a count. It returns an unsubscribe function. Up to 1.2.0 this needed a script of
+your own appended to the service worker.
 
 ## Options
 
@@ -94,6 +121,7 @@ With no tab open, the browser opens the link directly.
 | `appVersion` | none | Stored with the device; in-app messages can target versions below one |
 | `bell` | as HQ chose | `false` never draws the floating button (bell or logo) |
 | `banner` | as HQ chose | `false` never shows the pop-up |
+| `offset` | none | `{ top, bottom, side }` in CSS pixels: room the prompt leaves for your fixed header or bottom bar |
 
 ## Notes
 
@@ -104,6 +132,8 @@ With no tab open, the browser opens the link directly.
   `/example/bell.html`).
 - Up to 1.1.0 the SDK read a switch on the bell and one on the banner; from 1.2.0 it follows the one prompt HQ chose and can
   draw the logo. An older SDK still works with a newer server: it draws a bell where HQ chose the logo.
+- 1.2.1 needs no server change: it applies a login made before the permission, adds `onPush` and `offset`, and opens the
+  home page for a click with no link (1.2.0 opened the service worker's scope, a folder of its own on some sites).
 
 ## Publishing
 

package/dist/banner.d.ts

@@ -1,4 +1,5 @@
 import type { SubscriptionState } from './index.js';
+import { type PromptOffset } from './theme.js';
 /**
  * The pop-up of the banner prompt: a card that slides in at the top or the bottom of the page with a short message,
  * "Subscribe" and "Later". "Subscribe" opens the browser's own question; "Later" keeps it away for some days. The SDK
@@ -31,5 +32,8 @@ export interface BannerApi {
 export interface BannerHandle {
     destroy(): void;
 }
-/** Slides the banner in, with the app's icon beside the message (else a bell in its colour); `destroy()` takes it away at once. */
-export declare function mountBanner(api: BannerApi, settings: BannerSettings, language: string, iconUrl?: string | null): BannerHandle;
+/**
+ * Slides the banner in, with the app's icon beside the message (else a bell in its colour), clear of the site's fixed parts by
+ * `offset`; `destroy()` takes it away at once.
+ */
+export declare function mountBanner(api: BannerApi, settings: BannerSettings, language: string, iconUrl?: string | null, offset?: PromptOffset): BannerHandle;

package/dist/banner.js

@@ -1,4 +1,4 @@
-import { applyColors, applyTheme, colorOr, ICONS, svg, uiLanguage } from './theme.js';
+import { applyColors, applyOffset, applyTheme, colorOr, ICONS, OFFSET, svg, uiLanguage } from './theme.js';
 const THANKS_MS = 2500;
 const LEAVE_MS = 400;
 const TEXTS = {
@@ -26,8 +26,8 @@ const STYLE = `
   all: initial; position: fixed; z-index: 2147483001; left: 0; right: 0; pointer-events: none; font-family: inherit;
 }
 .wrap { max-width: 484px; margin: 0 auto; padding: 0 12px; }
-:host([data-position="top"]) { top: calc(16px + env(safe-area-inset-top, 0px)); }
-:host([data-position="bottom"]) { bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+:host([data-position="top"]) { top: calc(16px + env(safe-area-inset-top, 0px) + ${OFFSET.top}); }
+:host([data-position="bottom"]) { bottom: calc(16px + env(safe-area-inset-bottom, 0px) + ${OFFSET.bottom}); }
 @media print { :host { display: none !important; } }
 * { box-sizing: border-box; }
 [hidden] { display: none !important; }
@@ -42,7 +42,7 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
 :host([data-position="bottom"]) .card { transform: translateY(24px); }
 @media (max-width: 600px) {
   /* on a phone the top of the page is the site's header and menu: the banner comes from the bottom */
-  :host([data-position="top"]) { top: auto; bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+  :host([data-position="top"]) { top: auto; bottom: calc(16px + env(safe-area-inset-bottom, 0px) + ${OFFSET.bottom}); }
   :host([data-position="top"]) .card { transform: translateY(24px); }
 }
 :host([data-shown]) .card { opacity: 1; transform: none; }
@@ -65,13 +65,17 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
   .card { transition: opacity 0.2s ease; transform: none !important; }
 }
 `;
-/** Slides the banner in, with the app's icon beside the message (else a bell in its colour); `destroy()` takes it away at once. */
-export function mountBanner(api, settings, language, iconUrl) {
+/**
+ * Slides the banner in, with the app's icon beside the message (else a bell in its colour), clear of the site's fixed parts by
+ * `offset`; `destroy()` takes it away at once.
+ */
+export function mountBanner(api, settings, language, iconUrl, offset) {
     const lang = uiLanguage(language);
     const t = TEXTS[lang];
     const host = document.createElement('phoenix-notifications-banner');
     host.dataset.position = settings.position === 'bottom' ? 'bottom' : 'top';
     applyColors(host, colorOr(settings.color));
+    applyOffset(host, offset);
     const shadow = host.attachShadow({ mode: 'open' });
     // only constants go into this markup; HQ's texts and the icon's address are set as text and a property below
     shadow.innerHTML = `<style>${STYLE}</style>

package/dist/bell.d.ts

@@ -1,4 +1,5 @@
 import type { SubscriptionState } from './index.js';
+import { type PromptOffset } from './theme.js';
 /**
  * The floating subscribe button of the bell and logo prompts: a round button in a bottom corner of the site that subscribes
  * this browser on a click, shows that it is subscribed and lets the person unsubscribe, or explains how to allow notifications
@@ -34,5 +35,5 @@ export interface BellApi {
 export interface BellHandle {
     destroy(): void;
 }
-/** Draws the button into the page; `destroy()` takes it away again. */
-export declare function mountBell(api: BellApi, settings: BellSettings, language: string): BellHandle;
+/** Draws the button into the page, clear of the site's fixed parts by `offset`; `destroy()` takes it away again. */
+export declare function mountBell(api: BellApi, settings: BellSettings, language: string, offset?: PromptOffset): BellHandle;

package/dist/bell.js

@@ -1,4 +1,4 @@
-import { applyColors, applyTheme, colorOr, ICONS, svg, uiLanguage } from './theme.js';
+import { applyColors, applyOffset, applyTheme, colorOr, ICONS, OFFSET, svg, uiLanguage } from './theme.js';
 const MESSAGE_MS = 3500;
 const ATTENTION_MS = 4000;
 const TEXTS = {
@@ -35,14 +35,15 @@ const TEXTS = {
         close: 'إغلاق',
     },
 };
+// the room the site asked for (OFFSET) comes on top of the usual distance from the corner
 const STYLE = `
-:host { all: initial; position: fixed; z-index: 2147483000; bottom: calc(20px + env(safe-area-inset-bottom, 0px)); font-family: inherit; }
-:host([data-side="right"]) { right: calc(20px + env(safe-area-inset-right, 0px)); }
-:host([data-side="left"]) { left: calc(20px + env(safe-area-inset-left, 0px)); }
+:host { all: initial; position: fixed; z-index: 2147483000; bottom: calc(20px + env(safe-area-inset-bottom, 0px) + ${OFFSET.bottom}); font-family: inherit; }
+:host([data-side="right"]) { right: calc(20px + env(safe-area-inset-right, 0px) + ${OFFSET.side}); }
+:host([data-side="left"]) { left: calc(20px + env(safe-area-inset-left, 0px) + ${OFFSET.side}); }
 @media (max-width: 480px) {
-  :host { bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
-  :host([data-side="right"]) { right: calc(16px + env(safe-area-inset-right, 0px)); }
-  :host([data-side="left"]) { left: calc(16px + env(safe-area-inset-left, 0px)); }
+  :host { bottom: calc(16px + env(safe-area-inset-bottom, 0px) + ${OFFSET.bottom}); }
+  :host([data-side="right"]) { right: calc(16px + env(safe-area-inset-right, 0px) + ${OFFSET.side}); }
+  :host([data-side="left"]) { left: calc(16px + env(safe-area-inset-left, 0px) + ${OFFSET.side}); }
 }
 @media print { :host { display: none !important; } }
 * { box-sizing: border-box; }
@@ -74,7 +75,7 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
 .badge[data-kind="bell"] { background: var(--bell); color: var(--bell-text); }
 .badge[data-kind="blocked"] { background: #6b7280; }
 .bubble {
-  position: absolute; bottom: 7px; width: max-content; max-width: min(260px, calc(100vw - 104px)); padding: 7px 11px; border-radius: 8px;
+  position: absolute; bottom: 7px; width: max-content; max-width: min(260px, calc(100vw - 104px - ${OFFSET.side})); padding: 7px 11px; border-radius: 8px;
   background: var(--tip); color: var(--tip-text); font-size: 13px; line-height: 1.45; text-align: start;
   box-shadow: 0 4px 14px rgba(0, 0, 0, 0.25); opacity: 0; transform: translateY(4px); pointer-events: none;
   transition: opacity 0.15s ease, transform 0.15s ease;
@@ -83,7 +84,7 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
 :host([data-side="left"]) .bubble { left: 60px; }
 .bubble[data-shown] { opacity: 1; transform: none; }
 .panel {
-  position: absolute; bottom: 60px; width: min(300px, calc(100vw - 32px)); padding: 14px 16px 16px; border-radius: 14px;
+  position: absolute; bottom: 60px; width: min(300px, calc(100vw - 32px - ${OFFSET.side})); padding: 14px 16px 16px; border-radius: 14px;
   background: var(--panel); color: var(--text); border: 1px solid var(--border); text-align: start;
   box-shadow: 0 14px 40px rgba(0, 0, 0, 0.32); font-size: 14px; line-height: 1.55;
 }
@@ -112,8 +113,8 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
   :host([data-attention][data-view="unsubscribed"]) .bell::after { animation: none; }
 }
 `;
-/** Draws the button into the page; `destroy()` takes it away again. */
-export function mountBell(api, settings, language) {
+/** Draws the button into the page, clear of the site's fixed parts by `offset`; `destroy()` takes it away again. */
+export function mountBell(api, settings, language, offset) {
     const lang = uiLanguage(language);
     const t = TEXTS[lang];
     const logoUrl = settings.face === 'logo' && /^https?:\/\//i.test(settings.logoUrl ?? '') ? settings.logoUrl : null;
@@ -121,6 +122,7 @@ export function mountBell(api, settings, language) {
     host.dataset.side = settings.position === 'bottom_left' ? 'left' : 'right';
     host.dataset.view = 'unsubscribed';
     applyColors(host, colorOr(settings.color));
+    applyOffset(host, offset);
     const shadow = host.attachShadow({ mode: 'open' });
     // only constants go into this markup (the texts and icons above, lang 'ar' or 'en'); the colour is set as a property
     shadow.innerHTML = `<style>${STYLE}</style>

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import { type StoredDevice } from './store.js';
+import type { PromptOffset } from './theme.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. It also
- * draws the prompt HQ chose for the app (a bell, the app's logo or a pop-up), so a site needs no button of its own.
+ * the signed-in user with an identity token from the app's own backend, and hands notification clicks (and the pushes that
+ * arrive while the site is open) to the app. It also draws the prompt HQ chose for the app (a bell, the app's logo or a
+ * pop-up), 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`.
@@ -26,6 +28,12 @@ export interface InitOptions {
     bell?: boolean;
     /** The pop-up, shown when HQ chose it as the app's prompt. `false` never shows it. */
     banner?: boolean;
+    /**
+     * Room (CSS pixels) the button and the pop-up leave for the site's fixed parts: `bottom` above a bottom bar, `top` below a
+     * header (a pop-up at the top), `side` beside the button. CSS variables on the page win over it, e.g. in a media query for
+     * a bar only phones have: `--phoenix-notifications-offset-bottom`, `-top`, `-side`.
+     */
+    offset?: PromptOffset;
 }
 /** How the app's sites offer notifications, as HQ chose: one prompt, or none. */
 export type Prompt = 'none' | 'bell' | 'logo' | 'banner';
@@ -41,6 +49,14 @@ export interface NotificationClick {
     data: Record<string, string>;
     messageId?: string;
 }
+/** A push that arrived while the site was open. The browser shows it as a notification all the same. */
+export interface ReceivedNotification {
+    title: string;
+    body: string;
+    url?: string;
+    data: Record<string, string>;
+    messageId?: string;
+}
 export declare class NotificationsError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -75,6 +91,11 @@ export declare const Notifications: {
     unsubscribe(): Promise<void>;
     /** A notification was clicked while the site was open. Without a handler the SDK opens its link. Returns an unsubscribe function. */
     onClick(handler: (click: NotificationClick) => void): () => void;
+    /**
+     * A push arrived while the site was open (every open tab hears it), e.g. to refresh a list or a count; the browser shows
+     * the notification as well. Returns an unsubscribe function.
+     */
+    onPush(handler: (push: ReceivedNotification) => void): () => void;
     /** Called when this browser subscribes, unsubscribes or the permission changes. Returns an unsubscribe function. */
     onSubscriptionChange(handler: (state: SubscriptionState) => void): () => void;
     /** Re-runs the subscription check now (e.g. after the person changed the site's permission). */
@@ -82,4 +103,5 @@ export declare const Notifications: {
 };
 export type { BannerPosition } from './banner.js';
 export type { BellPosition } from './bell.js';
+export type { PromptOffset } from './theme.js';
 export type { StoredDevice };

package/dist/index.js

@@ -3,8 +3,9 @@ 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. It also
- * draws the prompt HQ chose for the app (a bell, the app's logo or a pop-up), so a site needs no button of its own.
+ * the signed-in user with an identity token from the app's own backend, and hands notification clicks (and the pushes that
+ * arrive while the site is open) to the app. It also draws the prompt HQ chose for the app (a bell, the app's logo or a
+ * pop-up), 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`.
@@ -26,7 +27,9 @@ export class NotificationsError extends Error {
         this.status = status;
     }
 }
+// what the service worker posts to the site's open tabs
 const CLICK_MESSAGE = 'phoenix-notifications:click';
+const PUSH_MESSAGE = 'phoenix-notifications:push';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const RESYNC_AFTER_MS = DAY_MS;
 let options = {
@@ -45,6 +48,7 @@ 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 pushHandlers = new Set();
 const changeHandlers = new Set();
 let lastState = null;
 let listening = false;
@@ -134,12 +138,30 @@ function deviceInfo() {
         deviceModel: navigator.userAgent.slice(0, 200),
     };
 }
-function listenForClicks() {
+/** Calls every handler; one that throws does not keep the others from hearing it, and still reaches the site's error reporting. */
+function tell(handlers, value) {
+    for (const handler of handlers) {
+        try {
+            handler(value);
+        }
+        catch (error) {
+            queueMicrotask(() => {
+                throw error;
+            });
+        }
+    }
+}
+/** What the service worker tells the site's open tabs: a click on a notification, or a push that arrived. */
+function listenToWorker() {
     if (listening)
         return;
     listening = true;
     navigator.serviceWorker.addEventListener('message', (event) => {
         const message = event.data;
+        if (message?.type === PUSH_MESSAGE) {
+            tell(pushHandlers, { title: message.title ?? '', body: message.body ?? '', url: message.url, data: message.data ?? {}, messageId: message.messageId });
+            return;
+        }
         if (message?.type !== CLICK_MESSAGE)
             return;
         const click = { url: message.url, data: message.data ?? {}, messageId: message.messageId };
@@ -148,8 +170,7 @@ function listenForClicks() {
                 window.location.assign(click.url);
             return;
         }
-        for (const handler of clickHandlers)
-            handler(click);
+        tell(clickHandlers, click);
     });
     // messages from the worker wait in a queue until the page says it is listening
     navigator.serviceWorker.startMessages();
@@ -227,7 +248,11 @@ async function sync() {
         syncedAt: Date.now(),
     };
     await store.set(keys.device(options.appId), device);
-    await store.remove(keys.login(options.appId));
+    // a new device belongs to nobody yet: the user logged in here (before the permission, or on the device it replaces) is
+    // bound to it by applyPendingLogin. Up to 1.2.0 that login was dropped, so the browser stayed a guest.
+    const login = await store.get(keys.login(options.appId));
+    if (login && login.at !== 0)
+        await store.set(keys.login(options.appId), { ...login, at: 0 });
     return device;
 }
 function syncOnce(force = false) {
@@ -244,24 +269,31 @@ function syncOnce(force = false) {
     });
     return syncing;
 }
+let applying = null;
 /**
  * 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.
+ * One at a time: when the person allows, the permission's watcher and `requestPermission` both get here.
  */
-async function applyPendingLogin(device) {
+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);
-    }
+        return Promise.resolve();
+    applying ??= (async () => {
+        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);
+        }
+    })().finally(() => {
+        applying = null;
+    });
+    return applying;
 }
 /** Follows permission changes made outside the page (the site settings next to the address bar). */
 function watchPermission() {
@@ -274,7 +306,7 @@ function watchPermission() {
             return;
         known = Notification.permission;
         if (known === 'granted')
-            void syncOnce(true).catch(() => undefined);
+            void syncOnce(true).then(applyPendingLogin).catch(() => undefined);
         void announce();
     };
     window.addEventListener('focus', changed);
@@ -302,7 +334,7 @@ async function showBell(appId) {
             },
             unsubscribe: () => Notifications.unsubscribe(),
             onChange: (handler) => Notifications.onSubscriptionChange(handler),
-        }, { ...web.bell, face: prompt === 'logo' ? 'logo' : 'bell', logoUrl: web.iconUrl }, language());
+        }, { ...web.bell, face: prompt === 'logo' ? 'logo' : 'bell', logoUrl: web.iconUrl }, language(), options.offset);
     }
     catch (error) {
         console.warn('[notifications] the subscribe button is not available', error);
@@ -349,7 +381,7 @@ async function showBanner(appId) {
                 await store.set(key, { ...latest, dismissedAt: Date.now() });
             },
             onChange: (handler) => Notifications.onSubscriptionChange(handler),
-        }, settings, language(), web?.iconUrl);
+        }, settings, language(), web?.iconUrl, options.offset);
     }
     catch (error) {
         console.warn('[notifications] the subscribe pop-up is not available', error);
@@ -376,6 +408,7 @@ export const Notifications = {
             serviceWorkerScope: init.serviceWorkerScope ?? '/',
             language: init.language ?? '',
             appVersion: init.appVersion,
+            offset: init.offset,
         };
         // one bell per page, for the app last initialised
         const wantsBell = init.bell !== false;
@@ -399,7 +432,7 @@ export const Notifications = {
         }
         ready = (async () => {
             registration = await navigator.serviceWorker.register(options.serviceWorkerPath, { scope: options.serviceWorkerScope });
-            listenForClicks();
+            listenToWorker();
         })();
         await ready;
         watchPermission();
@@ -442,8 +475,9 @@ export const Notifications = {
             return;
         await ready;
         const loginKey = keys.login(options.appId);
-        const previous = await store.get(loginKey);
         const device = await syncOnce();
+        // read after the sync: a device it had to register anew belongs to nobody yet, however recent the last login
+        const previous = await store.get(loginKey);
         if (!device) {
             await store.set(loginKey, { appId: options.appId, token: identityToken, at: 0 });
             return;
@@ -493,6 +527,14 @@ export const Notifications = {
         clickHandlers.add(handler);
         return () => clickHandlers.delete(handler);
     },
+    /**
+     * A push arrived while the site was open (every open tab hears it), e.g. to refresh a list or a count; the browser shows
+     * the notification as well. Returns an unsubscribe function.
+     */
+    onPush(handler) {
+        pushHandlers.add(handler);
+        return () => pushHandlers.delete(handler);
+    },
     /** Called when this browser subscribes, unsubscribes or the permission changes. Returns an unsubscribe function. */
     onSubscriptionChange(handler) {
         changeHandlers.add(handler);

package/dist/theme.d.ts

@@ -13,6 +13,27 @@ export declare function textOn(color: string): string;
 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;
+/**
+ * Room the bell and the banner leave for the site's own fixed parts, in CSS pixels, besides their usual distance from the edge:
+ * `bottom` for a bottom bar (the button, and a pop-up at the bottom), `top` for a header (a pop-up at the top), `side` for the
+ * button's side of the page.
+ */
+export interface PromptOffset {
+    top?: number;
+    bottom?: number;
+    side?: number;
+}
+/**
+ * The room on each edge, for the hosts' CSS: the page's own CSS variable when it sets one (it can, in a media query, for a bar
+ * only phones have), else the `offset` option (`applyOffset`), else none.
+ */
+export declare const OFFSET: {
+    top: string;
+    bottom: string;
+    side: string;
+};
+/** Puts the `offset` option on the host, under the page's CSS variables. */
+export declare function applyOffset(host: HTMLElement, offset: PromptOffset | undefined): 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: {

package/dist/theme.js

@@ -77,6 +77,22 @@ export function applyTheme(host) {
     }))
         host.style.setProperty(name, value);
 }
+/**
+ * The room on each edge, for the hosts' CSS: the page's own CSS variable when it sets one (it can, in a media query, for a bar
+ * only phones have), else the `offset` option (`applyOffset`), else none.
+ */
+export const OFFSET = {
+    top: 'var(--phoenix-notifications-offset-top, var(--phx-offset-top, 0px))',
+    bottom: 'var(--phoenix-notifications-offset-bottom, var(--phx-offset-bottom, 0px))',
+    side: 'var(--phoenix-notifications-offset-side, var(--phx-offset-side, 0px))',
+};
+/** Puts the `offset` option on the host, under the page's CSS variables. */
+export function applyOffset(host, offset) {
+    for (const edge of ['top', 'bottom', 'side']) {
+        const value = offset?.[edge];
+        host.style.setProperty(`--phx-offset-${edge}`, `${typeof value === 'number' && Number.isFinite(value) ? value : 0}px`);
+    }
+}
 /** The language the bell and the banner speak: Arabic for `ar…`, else English. */
 export function uiLanguage(language) {
     return language.toLowerCase().startsWith('ar') ? 'ar' : 'en';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phoenix-iq/notifications",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Phoenix Notifications web SDK: browser push subscriptions, the subscribe prompt (a bell, the app's logo or a pop-up), verified sign-in and click handling for apps on notifications.phnx-iq.com.",
   "type": "module",
   "license": "UNLICENSED",

package/phoenix-notifications-sw.js

@@ -2,14 +2,16 @@
  * Phoenix Notifications service worker. Serve it from the site's root (default path /phoenix-notifications-sw.js) so it
  * controls the whole site. Plain JavaScript on purpose: copy it as it is, no build step.
  *
- * It shows the pushes the site receives, reports clicks to the notifications API, focuses an open tab of the site (and tells
- * the page, which routes the click) or opens the link, and renews the subscription when the browser replaces it.
+ * It shows the pushes the site receives (and tells the site's open tabs, for Notifications.onPush), reports clicks to the
+ * notifications API, focuses an open tab of the site (and tells the page, which routes the click) or opens the link, and
+ * renews the subscription when the browser replaces it.
  * Its state is shared with the SDK through IndexedDB ("phoenix-notifications" / "state"); keep the two in step.
  */
 
 const DB_NAME = 'phoenix-notifications';
 const STORE = 'state';
 const CLICK_MESSAGE = 'phoenix-notifications:click';
+const PUSH_MESSAGE = 'phoenix-notifications:push';
 
 function openDb() {
   return new Promise((resolve, reject) => {
@@ -89,9 +91,24 @@ self.addEventListener('push', (event) => {
     tag: payload.m || undefined,
     data: { id: payload.id, m: payload.m, url: payload.url, data: payload.data || {} },
   };
-  event.waitUntil(self.registration.showNotification(payload.title || '', options));
+  event.waitUntil(
+    Promise.all([
+      self.registration.showNotification(payload.title || '', options),
+      tellOpenTabs({ type: PUSH_MESSAGE, title: payload.title || '', body: payload.body || '', url: payload.url, data: payload.data || {}, messageId: payload.m }),
+    ]),
+  );
 });
 
+/** Every open tab of the site hears of the push (the SDK's onPush), e.g. to refresh a list; the notification shows regardless. */
+async function tellOpenTabs(message) {
+  try {
+    const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+    for (const client of windows) client.postMessage(message);
+  } catch {
+    // the tabs only miss a refresh
+  }
+}
+
 self.addEventListener('notificationclick', (event) => {
   event.notification.close();
   const details = event.notification.data || {};
@@ -114,7 +131,8 @@ self.addEventListener('notificationclick', (event) => {
         open.postMessage({ type: CLICK_MESSAGE, url: details.url, data: details.data || {}, messageId: details.m });
         return;
       }
-      await self.clients.openWindow(details.url || self.registration.scope);
+      // no link in the push nor a default one in HQ: the site's home page (the worker's scope may be a folder of its own)
+      await self.clients.openWindow(details.url || new URL('/', self.location.origin).href);
     })(),
   );
 });