@phoenix-iq/notifications 1.0.0 → 1.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @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,
-and hands notification clicks to your app. 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 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).
 
@@ -22,9 +22,9 @@ small plugin (HQ's dashboard `vite.config.ts` does).
 ```ts
 import { Notifications } from '@phoenix-iq/notifications';
 
-await Notifications.init({ appId: '<app id from HQ: Push apps>' });
+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
@@ -34,9 +34,44 @@ await Notifications.login(identityToken);
 await Notifications.logout();
 ```
 
-`init` subscribes quietly when the person already allowed notifications. `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.
+`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.
+
+## 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.
+
+## Subscription state
+
+```ts
+const { permission, subscribed } = await Notifications.getState();
+Notifications.onSubscriptionChange(({ permission, subscribed }) => render(permission, subscribed));
+```
+
+`unsubscribe()` stops notifications here and is remembered: the browser keeps its permission, but later page loads do not
+subscribe again until `requestPermission()` (which then subscribes without asking). Up to 1.0.0 the next `init` subscribed
+again.
+
+When the app has a welcome notification (HQ: Web push → Welcome notification), the service pushes it right after a browser
+subscribes; nothing to do here.
 
 ## 3. Handle clicks
 
@@ -51,20 +86,28 @@ With no tab open, the browser opens the link directly.
 
 | Option | Default | |
 |---|---|---|
-| `appId` | (required) | The app's id: HQ → Push apps → the app |
+| `appId` | (required) | The app's id: HQ → Notification management → the app |
 | `serverUrl` | `https://notifications.phnx-iq.com` | `''` uses your own origin (development behind a proxy) |
 | `serviceWorkerPath` | `/phoenix-notifications-sw.js` | |
 | `serviceWorkerScope` | `/` | |
-| `language` | the browser's | Picks the Arabic or English text of a notification |
+| `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 chose | `false` never draws the floating button (bell or logo) |
+| `banner` | as HQ chose | `false` never shows the pop-up |
 
 ## 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 → Settings → Web push), or registration is refused.
+- Your site must be in the app's sites (the app → Web push), or registration is refused.
+- `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.
 
 ## Publishing
 
-`npm run build` compiles `src` to `dist` (ES modules and type declarations). To release, raise `version` in
-`package.json` and run `npm publish` here (it builds first); the package is public on npmjs.com under `@phoenix-iq`.
+`npm run build` compiles `src` to a fresh `dist` (ES modules and type declarations, no source maps); the package ships
+`dist`, the service worker and this README, never `src`. `npm run lint` checks `src` and the service worker. To release,
+raise `version` in `package.json` and run `npm publish` here (it builds first); the package is public on npmjs.com under
+`@phoenix-iq`.

package/dist/banner.d.ts

@@ -0,0 +1,35 @@
+import type { SubscriptionState } from './index.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
+ * 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 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';
+/** The banner as HQ set it up (the web config's `banner`). */
+export interface BannerSettings {
+    position: BannerPosition;
+    message?: string | null;
+    acceptText?: string | null;
+    cancelText?: string | null;
+    /** `#rrggbb` of the "Subscribe" button; null: the SDK's blue. */
+    color?: string | null;
+    delaySeconds: number;
+    pageViews: number;
+    repromptDays: number;
+}
+/** What the banner needs from the SDK. */
+export interface BannerApi {
+    /** Asks the browser (synchronously, inside the click) and subscribes; resolves with the state afterwards. */
+    subscribe(): Promise<SubscriptionState>;
+    /** "Later": remembered, so the banner stays away for the days HQ set. */
+    dismiss(): Promise<void>;
+    onChange(handler: (state: SubscriptionState) => void): () => void;
+}
+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;

package/dist/banner.js

@@ -0,0 +1,178 @@
+import { applyColors, applyTheme, colorOr, ICONS, svg, uiLanguage } from './theme.js';
+const THANKS_MS = 2500;
+const LEAVE_MS = 400;
+const TEXTS = {
+    en: {
+        message: 'Get our news and updates as notifications in this browser. You can unsubscribe at any time.',
+        accept: 'Subscribe',
+        cancel: 'Later',
+        thanks: 'Thanks for subscribing!',
+        failed: "This browser couldn't be subscribed. Try again later.",
+        label: 'Notifications',
+    },
+    ar: {
+        message: 'اشترك ليصلك جديدنا وآخر أخبارنا إشعاراتٍ على هذا المتصفح، ويمكنك إلغاء الاشتراك متى شئت.',
+        accept: 'اشتراك',
+        cancel: 'لاحقًا',
+        thanks: 'شكرًا لاشتراكك!',
+        failed: 'تعذّر الاشتراك من هذا المتصفح. حاول لاحقًا.',
+        label: 'الإشعارات',
+    },
+};
+const STYLE = `
+/* The host only spans the width and lets clicks through; the centring happens inside, where the page's CSS (a reset that
+   zeroes every element's margin, say) cannot reach. */
+:host {
+  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)); }
+@media print { :host { display: none !important; } }
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
+.card {
+  pointer-events: auto; display: flex; gap: 14px; align-items: flex-start; padding: 16px; border-radius: 16px; text-align: start;
+  background: var(--panel); color: var(--text); border: 1px solid var(--border);
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.32), 0 2px 6px rgba(0, 0, 0, 0.18); font-size: 14px; line-height: 1.55;
+  opacity: 0; transition: transform 0.45s cubic-bezier(0.22, 1, 0.36, 1), opacity 0.3s ease;
+}
+: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 */
+  :host([data-position="top"]) { top: auto; bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+  :host([data-position="top"]) .card { transform: translateY(24px); }
+}
+:host([data-shown]) .card { opacity: 1; transform: none; }
+.icon {
+  flex: none; display: grid; place-items: center; width: 44px; height: 44px; border-radius: 12px; overflow: hidden;
+  background: var(--bell); color: var(--bell-text);
+}
+.icon img { width: 100%; height: 100%; object-fit: cover; }
+.body { flex: 1; min-width: 0; }
+.message { margin: 0; overflow-wrap: anywhere; }
+.error { margin: 6px 0 0; color: var(--error); font-size: 13px; }
+.actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 8px; margin-top: 12px; }
+.actions button { min-height: 38px; padding: 7px 16px; border-radius: 9px; border: 1px solid transparent; font-weight: 600; cursor: pointer; }
+.actions .later { background: transparent; color: inherit; border-color: var(--border); }
+.actions .later:hover { background: var(--hover); }
+.actions .accept { background: var(--bell); color: var(--bell-text); }
+.actions .accept:disabled { opacity: 0.6; cursor: progress; }
+.actions button:focus-visible { outline: 2px solid var(--text); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) {
+  .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) {
+    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));
+    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>
+<div class="wrap"><div class="card" role="dialog" aria-label="${t.label}" aria-describedby="phx-banner-message" dir="${lang === 'ar' ? 'rtl' : 'ltr'}" lang="${lang}">
+  <div class="icon"></div>
+  <div class="body">
+    <p class="message" id="phx-banner-message" dir="auto"></p>
+    <p class="error" role="alert" hidden></p>
+    <div class="actions"><button type="button" class="later"></button><button type="button" class="accept"></button></div>
+  </div>
+</div></div>`;
+    const $ = (selector) => shadow.querySelector(selector);
+    const icon = $('.icon');
+    const message = $('.message');
+    const errorLine = $('.error');
+    const actions = $('.actions');
+    const later = $('.later');
+    const accept = $('.accept');
+    message.textContent = settings.message?.trim() || t.message;
+    later.textContent = settings.cancelText?.trim() || t.cancel;
+    accept.textContent = settings.acceptText?.trim() || t.accept;
+    errorLine.textContent = t.failed;
+    if (iconUrl && /^https?:\/\//i.test(iconUrl)) {
+        const image = document.createElement('img');
+        image.alt = '';
+        image.src = iconUrl;
+        // a broken icon falls back to the bell
+        image.addEventListener('error', () => (icon.innerHTML = svg(ICONS.bell, 24)), { once: true });
+        icon.append(image);
+    }
+    else {
+        icon.innerHTML = svg(ICONS.bell, 24);
+    }
+    let busy = false;
+    let gone = false;
+    let leaveTimer = 0;
+    function leave() {
+        if (gone)
+            return;
+        gone = true;
+        stop();
+        delete host.dataset.shown;
+        leaveTimer = window.setTimeout(() => host.remove(), LEAVE_MS);
+    }
+    async function subscribe() {
+        if (busy)
+            return;
+        busy = true;
+        accept.disabled = true;
+        errorLine.hidden = true;
+        try {
+            // the browser's prompt opens inside this call, while the click still counts as the person's gesture
+            const state = await api.subscribe();
+            if (state.subscribed) {
+                message.textContent = t.thanks;
+                actions.hidden = true;
+                window.setTimeout(leave, THANKS_MS);
+            }
+            else if (state.permission === 'granted') {
+                errorLine.hidden = false;
+            }
+            else {
+                // blocked, or the browser's question was closed without an answer: as good as "Later"
+                if (state.permission === 'default')
+                    await api.dismiss();
+                leave();
+            }
+        }
+        catch (error) {
+            console.warn('[notifications] subscribing failed', error);
+            errorLine.hidden = false;
+        }
+        finally {
+            busy = false;
+            accept.disabled = false;
+        }
+    }
+    accept.addEventListener('click', () => void subscribe());
+    later.addEventListener('click', () => {
+        void api.dismiss().catch(() => undefined);
+        leave();
+    });
+    shadow.addEventListener('keydown', ((event) => {
+        if (event.key === 'Escape' && !busy)
+            later.click();
+    }));
+    // subscribed elsewhere (the bell, the site's own button) or blocked: nothing left to ask
+    const stop = api.onChange((state) => {
+        if (!busy && (state.subscribed || state.permission === 'denied'))
+            leave();
+    });
+    document.body.appendChild(host);
+    applyTheme(host);
+    // two frames, so the card starts from its hidden place and slides
+    requestAnimationFrame(() => requestAnimationFrame(() => (host.dataset.shown = '')));
+    return {
+        destroy() {
+            gone = true;
+            stop();
+            window.clearTimeout(leaveTimer);
+            host.remove();
+        },
+    };
+}

package/dist/bell.d.ts

@@ -0,0 +1,38 @@
+import type { SubscriptionState } from './index.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
+ * 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';
+/** 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 {
+    state(): Promise<SubscriptionState>;
+    /** Asks the browser (synchronously, inside the click) and subscribes; resolves with the state afterwards. */
+    subscribe(): Promise<SubscriptionState>;
+    unsubscribe(): Promise<void>;
+    onChange(handler: (state: SubscriptionState) => void): () => void;
+}
+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;