@phoenix-iq/notifications 1.1.0 → 1.2.1

package/README.md

@@ -1,9 +1,9 @@
 # @phoenix-iq/notifications (web SDK)
 
-Browser push for apps on `notifications.phnx-iq.com`, our replacement for OneSignal's web SDK. 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 shows the subscription bell and banner when the app has them on. TypeScript, no
-dependencies.
+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 (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).
 
@@ -25,7 +25,7 @@ import { Notifications } from '@phoenix-iq/notifications';
 
 await Notifications.init({ appId: '<app id from HQ: Notification management>' });
 
-// from a click ("Get notifications"): browsers only show the prompt on a user gesture
+// from a click on your own button ("Get notifications"): browsers only ask on a user gesture
 const permission = await Notifications.requestPermission(); // 'granted' | 'denied' | 'default' | 'unsupported'
 
 // after your own sign-in, with the identity token your backend returned
@@ -36,30 +36,44 @@ 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
+
+HQ chooses one per app (the app → Web push → How visitors subscribe) and `init` draws it; a change shows on the next page load.
+
+- **Bell** or **logo**: a round button in the bottom right or left corner, in the colour HQ set, showing a bell, or the app's
+  icon with a small bell on it (a logo that fails to load gives way to the bell). The first click asks the browser; then the
+  button shows that this browser is subscribed and offers "Unsubscribe", or, when notifications were blocked, says how to
+  allow them again. With *Hide after subscribing*, only browsers that are not subscribed see it.
+- **Pop-up**: shown, when its time comes, to a browser never asked: a card at the top or bottom with a message, "Subscribe"
+  (the browser's own question) and "Later". HQ sets the delay after the page opens, the page view it starts from and how many
+  days "Later" keeps it away; the SDK counts these in the browser (IndexedDB). Texts left empty are the SDK's own in the
+  page's language. On a phone a top pop-up comes from the bottom, clear of your header; the strip around the card lets
+  clicks through.
+- **None**: nothing is drawn. Ask from your own button with `requestPermission()`, and use `unsubscribe()` and the state
+  below.
+
+They speak the page's language (`<html lang="ar">` → Arabic, right to left; else English, or the `language` option), take
+the page's font, pick a light or dark look from the page's background, live in a shadow root (your CSS and theirs stay apart)
+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:
 
-## The subscription bell
-
-Switch it on in HQ (the app → Web push → Subscription bell) and `init` draws it: a round bell in the bottom right or left
-corner, in the colour you chose. The first click asks the browser; then the bell shows that this browser is subscribed and
-offers "Unsubscribe", or, when notifications were blocked, says how to allow them again. It speaks the page's language
-(`<html lang="ar">` → Arabic, right to left; else English, or the `language` option), takes the page's font, and picks a
-light or dark panel from the page's background. It sits in a shadow root, so your CSS and its CSS stay apart, and it is
-hidden when printing. A change in HQ shows on the next page load. With *Hide the bell once subscribed*, only browsers that
-are not subscribed see it.
-
-## The subscription banner
-
-OneSignal's slide prompt. Switch it on in HQ (the app → Web push → Subscription banner) and `init` shows it, when its time
-comes, to a browser never asked: a card at the top or bottom with a message, "Subscribe" (the browser's own question) and
-"Later". HQ sets the delay after the page opens, the page view it starts from and how many days "Later" keeps it away; the
-SDK counts these in the browser (IndexedDB). Texts left empty are the SDK's own in the page's language. On a phone a top
-banner comes from the bottom, clear of your header, and a bottom one sits above the bell. Like the bell it lives in a shadow
-root; the strip around the card lets clicks through.
+```ts
+await Notifications.init({ appId, offset: { bottom: 64 } }); // also `top` (a pop-up at the top) and `side` (the button)
+```
 
-A site with its own "Get notifications" button passes `bell: false` and `banner: false`, and uses `requestPermission()`,
-`unsubscribe()` and the state below.
+```css
+@media (max-width: 1023px) {
+  :root { --phoenix-notifications-offset-bottom: 64px; } /* and -offset-top, -offset-side */
+}
+```
 
 ## Subscription state
 
@@ -82,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
 
@@ -92,17 +117,23 @@ With no tab open, the browser opens the link directly.
 | `serverUrl` | `https://notifications.phnx-iq.com` | `''` uses your own origin (development behind a proxy) |
 | `serviceWorkerPath` | `/phoenix-notifications-sw.js` | |
 | `serviceWorkerScope` | `/` | |
-| `language` | the page's (`<html lang>`), then the browser's | Picks the Arabic or English text of a notification, and the bell's language |
+| `language` | the page's (`<html lang>`), then the browser's | Picks the Arabic or English text of a notification, and the prompt's language |
 | `appVersion` | none | Stored with the device; in-app messages can target versions below one |
-| `bell` | as HQ set it | `false` never draws the subscription bell (a site with its own button) |
-| `banner` | as HQ set it | `false` never shows the subscription banner |
+| `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
 
 - iPhone and iPad: web push works only for a site added to the home screen (iOS 16.4+), as with any web push provider.
 - The device secret the server gives the browser is kept in IndexedDB; it only lets this browser manage its own subscription.
 - Your site must be in the app's sites (the app → Web push), or registration is refused.
-- `example/bell.html` draws the bell and the banner in every state without a server (serve `sdk/web`, open `/example/bell.html`).
+- `example/bell.html` draws the button (bell or logo) and the pop-up in every state without a server (serve `sdk/web`, open
+  `/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,10 +1,11 @@
 import type { SubscriptionState } from './index.js';
+import { type PromptOffset } from './theme.js';
 /**
- * The subscription banner (OneSignal's slide 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
+ * 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
  * decides when it shows (a browser never asked, from a page view, after a delay); this only draws it and answers its buttons.
  *
- * Like the bell it lives in a shadow root, takes the page's font and language and a light or dark look to suit the page.
+ * Like the floating button it lives in a shadow root, takes the page's font and language and a light or dark look to suit the page.
  * Texts HQ wrote are shown as they are; the empty ones are the SDK's own, in the page's language.
  */
 export type BannerPosition = 'top' | 'bottom';
@@ -31,11 +32,8 @@ export interface BannerApi {
 export interface BannerHandle {
     destroy(): void;
 }
-export interface BannerPlacement {
-    /** The app's icon, shown beside the message (else a bell in the banner's colour). */
-    iconUrl?: string | null;
-    /** The bell is on the page: a bottom banner keeps clear of it on narrow screens. */
-    aboveBell?: boolean;
-}
-/** Slides the banner in; `destroy()` takes it away at once. */
-export declare function mountBanner(api: BannerApi, settings: BannerSettings, language: string, placement?: BannerPlacement): 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; }
@@ -41,11 +41,9 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
 :host([data-position="top"]) .card { transform: translateY(-24px); }
 :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, as OneSignal's does */
-  :host([data-position="top"]) { top: auto; bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+  /* 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) + ${OFFSET.bottom}); }
   :host([data-position="top"]) .card { transform: translateY(24px); }
-  /* and where it would cover the bell in its corner, it sits above it */
-  :host([data-above-bell]) { bottom: calc(84px + env(safe-area-inset-bottom, 0px)); }
 }
 :host([data-shown]) .card { opacity: 1; transform: none; }
 .icon {
@@ -67,16 +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; `destroy()` takes it away at once. */
-export function mountBanner(api, settings, language, placement = {}) {
+/**
+ * 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 { iconUrl, aboveBell } = placement;
     const host = document.createElement('phoenix-notifications-banner');
     host.dataset.position = settings.position === 'bottom' ? 'bottom' : 'top';
-    if (aboveBell)
-        host.dataset.aboveBell = '';
     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,20 +1,28 @@
 import type { SubscriptionState } from './index.js';
+import { type PromptOffset } from './theme.js';
 /**
- * The subscription bell (OneSignal's "subscription bell"): 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
- * again once they blocked them. HQ switches it on per app; the SDK draws it from the web config.
+ * 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
+ * again once they blocked them. It shows a bell, or the app's logo with a small bell on it. HQ chooses the prompt per app;
+ * the SDK draws it from the web config.
  *
  * It lives in a shadow root, so the site's CSS cannot reach it and its CSS cannot leak out. It takes the page's font and
  * language (Arabic right to left, else English), the colour HQ gave it, and a light or dark panel to suit the page.
  */
 export type BellPosition = 'bottom_right' | 'bottom_left';
-/** The bell as HQ set it up (the web config's `bell`). */
+/** What the button shows: a bell, or the app's logo (its icon). */
+export type BellFace = 'bell' | 'logo';
+/** The button as HQ set it up (the web config's `bell`). */
 export interface BellSettings {
     position: BellPosition;
     /** `#rrggbb`; null: the SDK's blue. */
     color?: string | null;
     /** Only browsers that are not subscribed see it (after its thanks, a browser that subscribes no longer does). */
     hideWhenSubscribed?: boolean;
+    /** `bell` unless the logo prompt is chosen. */
+    face?: BellFace;
+    /** The logo's address (the app's icon); without one, or when it fails to load, the button shows the bell. */
+    logoUrl?: string | null;
 }
 /** What the bell needs from the SDK. */
 export interface BellApi {
@@ -27,5 +35,5 @@ export interface BellApi {
 export interface BellHandle {
     destroy(): void;
 }
-/** Draws the bell 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; }
@@ -66,8 +67,15 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
   position: absolute; top: -3px; right: -3px; display: grid; place-items: center; width: 18px; height: 18px; border-radius: 50%;
   background: #16a34a; color: #ffffff; border: 2px solid #ffffff;
 }
+/* the logo face: the app's icon on a white disc ringed in the colour; its badge says what the button is for */
+:host([data-face="logo"]) .bell { background: #ffffff; box-shadow: 0 0 0 2px var(--bell), 0 6px 20px rgba(0, 0, 0, 0.28), 0 1px 3px rgba(0, 0, 0, 0.22); }
+:host([data-face="logo"]) .icon { width: 100%; height: 100%; border-radius: 50%; overflow: hidden; }
+.logo { display: block; width: 100%; height: 100%; object-fit: cover; }
+:host([data-face="logo"][data-view="blocked"]) .logo { filter: grayscale(1); }
+.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;
@@ -76,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;
 }
@@ -105,14 +113,16 @@ button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
   :host([data-attention][data-view="unsubscribed"]) .bell::after { animation: none; }
 }
 `;
-/** Draws the bell 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;
     const host = document.createElement('phoenix-notifications-bell');
     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>
@@ -146,18 +156,48 @@ export function mountBell(api, settings, language) {
     let iconFor = null;
     /** Hidden until the first read of the state, so it never shows a wrong state (or shows at all, when it hides) first. */
     let settled = false;
+    /** The logo while it loads and after; a logo that fails to load gives way to the bell. */
+    let face = logoUrl ? 'logo' : 'bell';
+    let logo = null;
     const viewOf = (state) => (state.permission === 'denied' ? 'blocked' : state.subscribed ? 'subscribed' : 'unsubscribed');
+    function drawFace() {
+        if (face === 'bell') {
+            icon.innerHTML = svg(view === 'blocked' ? ICONS.bellOff : ICONS.bell, 24);
+            badge.innerHTML = svg(ICONS.check, 11, 3);
+            delete badge.dataset.kind;
+            return;
+        }
+        if (!logo) {
+            logo = document.createElement('img');
+            logo.className = 'logo';
+            logo.alt = '';
+            logo.src = logoUrl;
+            logo.addEventListener('error', () => {
+                face = 'bell';
+                iconFor = null;
+                render();
+            }, { once: true });
+        }
+        icon.replaceChildren(logo);
+        // the logo alone does not say "notifications": a bell on it does, a check once subscribed, a struck bell once blocked
+        badge.innerHTML = view === 'subscribed' ? svg(ICONS.check, 11, 3) : svg(view === 'blocked' ? ICONS.bellOff : ICONS.bell, 11, 2.4);
+        if (view === 'subscribed')
+            delete badge.dataset.kind;
+        else
+            badge.dataset.kind = view === 'blocked' ? 'blocked' : 'bell';
+    }
     function render() {
         host.dataset.view = view;
+        host.dataset.face = face;
         const hidden = !settled || (!!settings.hideWhenSubscribed && view === 'subscribed' && !open && !busy && !message);
         host.style.display = hidden ? 'none' : '';
         bell.setAttribute('aria-label', t[view]);
         bell.setAttribute('aria-expanded', String(open));
-        if (iconFor !== view) {
-            icon.innerHTML = svg(view === 'blocked' ? ICONS.bellOff : ICONS.bell, 24);
-            iconFor = view;
+        if (iconFor !== `${face}:${view}`) {
+            drawFace();
+            iconFor = `${face}:${view}`;
         }
-        badge.hidden = view !== 'subscribed';
+        badge.hidden = face === 'bell' && view !== 'subscribed';
         panel.hidden = !open;
         if (!open)
             return;

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. 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.
+ * 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`.
@@ -16,17 +18,25 @@ export interface InitOptions {
     serverUrl?: string;
     serviceWorkerPath?: string;
     serviceWorkerScope?: string;
-    /** Language the device reports (picks Arabic or English text, and the bell's language); defaults to the page's, then the browser's. */
+    /** Language the device reports (picks Arabic or English text, and the prompt's language); defaults to the page's, then the browser's. */
     language?: string;
     appVersion?: string;
     /**
-     * The subscription bell, drawn when the app has it switched on in HQ (the app → Web push → Subscription bell). `false`
-     * never draws it, for a site with its own "Get notifications" button.
+     * The floating button (a bell or the app's logo), drawn when HQ chose one of those as the app's prompt (the app → Web push
+     * → How visitors subscribe). `false` never draws it. A site with its own button usually has "None" chosen in HQ instead.
      */
     bell?: boolean;
-    /** The subscription banner, shown when the app has it switched on in HQ (the app → Web push → Subscription banner). `false` never shows it. */
+    /** 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';
 export type PushPermission = 'granted' | 'denied' | 'default' | 'unsupported';
 /** Whether this browser gets the app's notifications, for a site's own button. */
 export interface SubscriptionState {
@@ -39,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);
@@ -47,7 +65,7 @@ export declare const Notifications: {
     /** True when this browser can receive web push here (a secure context with service workers and the Push API). */
     isSupported(): boolean;
     /**
-     * Registers the service worker, and draws the subscription bell and the banner when the app has them on. When the person
+     * Registers the service worker, and draws the prompt HQ chose for the app (a bell, the logo or a pop-up). When the person
      * already allowed notifications (and did not unsubscribe here), subscribes quietly.
      */
     init(init: InitOptions): Promise<void>;
@@ -73,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). */
@@ -80,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,14 +3,22 @@ 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.
+ * 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`.
  */
 export const DEFAULT_SERVER_URL = 'https://notifications.phnx-iq.com';
 export const DEFAULT_SERVICE_WORKER_PATH = '/phoenix-notifications-sw.js';
+function promptOf(web) {
+    if (!web)
+        return 'none';
+    if (web.prompt)
+        return web.prompt;
+    return web.bell?.enabled ? 'bell' : web.banner?.enabled ? 'banner' : 'none';
+}
 export class NotificationsError extends Error {
     status;
     constructor(status, message) {
@@ -19,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 = {
@@ -38,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;
@@ -127,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 };
@@ -141,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();
@@ -220,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) {
@@ -237,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() {
@@ -267,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);
@@ -276,11 +315,12 @@ function watchPermission() {
         .then((status) => status.addEventListener('change', changed))
         .catch(() => undefined);
 }
-/** Draws the bell once the app's config says so. A failure only means no bell. */
+/** Draws the floating button (a bell, or the app's logo) when it is the app's prompt. A failure only means no button. */
 async function showBell(appId) {
     try {
         const web = await webConfig();
-        if (bell?.appId !== appId || !web?.bell?.enabled)
+        const prompt = promptOf(web);
+        if (bell?.appId !== appId || !web?.bell || (prompt !== 'bell' && prompt !== 'logo'))
             return;
         if (document.readyState === 'loading')
             await new Promise((resolve) => document.addEventListener('DOMContentLoaded', resolve, { once: true }));
@@ -294,10 +334,10 @@ async function showBell(appId) {
             },
             unsubscribe: () => Notifications.unsubscribe(),
             onChange: (handler) => Notifications.onSubscriptionChange(handler),
-        }, web.bell, language());
+        }, { ...web.bell, face: prompt === 'logo' ? 'logo' : 'bell', logoUrl: web.iconUrl }, language(), options.offset);
     }
     catch (error) {
-        console.warn('[notifications] the subscription bell is not available', error);
+        console.warn('[notifications] the subscribe button is not available', error);
     }
 }
 function whenDocumentReady() {
@@ -306,15 +346,15 @@ function whenDocumentReady() {
     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.
+ * Slides the pop-up in when it is the app's prompt and 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 pop-up.
  */
 async function showBanner(appId) {
     try {
         const web = await webConfig();
         const settings = web?.banner;
-        if (banner?.appId !== appId || !settings?.enabled)
+        if (banner?.appId !== appId || !settings || promptOf(web) !== 'banner')
             return;
         if (Notification.permission !== 'default' || (await optedOut()))
             return;
@@ -328,7 +368,7 @@ async function showBanner(appId) {
             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
+        // the page may have moved on meanwhile: another app, the person subscribed with the site's own button, or answered the browser
         if (banner?.appId !== appId || banner.handle || Notification.permission !== 'default' || (await optedOut()))
             return;
         banner.handle = mountBanner({
@@ -341,10 +381,10 @@ async function showBanner(appId) {
                 await store.set(key, { ...latest, dismissedAt: Date.now() });
             },
             onChange: (handler) => Notifications.onSubscriptionChange(handler),
-        }, settings, language(), { iconUrl: web?.iconUrl, aboveBell: !!bell?.handle });
+        }, settings, language(), web?.iconUrl, options.offset);
     }
     catch (error) {
-        console.warn('[notifications] the subscription banner is not available', error);
+        console.warn('[notifications] the subscribe pop-up is not available', error);
     }
 }
 export const Notifications = {
@@ -353,7 +393,7 @@ export const Notifications = {
         return supported();
     },
     /**
-     * Registers the service worker, and draws the subscription bell and the banner when the app has them on. When the person
+     * Registers the service worker, and draws the prompt HQ chose for the app (a bell, the logo or a pop-up). When the person
      * already allowed notifications (and did not unsubscribe here), subscribes quietly.
      */
     async init(init) {
@@ -368,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;
@@ -391,7 +432,7 @@ export const Notifications = {
         }
         ready = (async () => {
             registration = await navigator.serviceWorker.register(options.serviceWorkerPath, { scope: options.serviceWorkerScope });
-            listenForClicks();
+            listenToWorker();
         })();
         await ready;
         watchPermission();
@@ -434,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;
@@ -485,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,7 +1,7 @@
 {
   "name": "@phoenix-iq/notifications",
-  "version": "1.1.0",
-  "description": "Phoenix Notifications web SDK: browser push subscriptions, the subscription bell, verified sign-in and click handling for apps on notifications.phnx-iq.com.",
+  "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",
   "main": "./dist/index.js",

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);
     })(),
   );
 });