@phoenix-iq/notifications 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @phoenix-iq/notifications (web SDK)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+How the whole service works, the server API and the identity tokens: [docs/notifications.md](../../docs/notifications.md).
+
+```bash
+npm install @phoenix-iq/notifications
+```
+
+## 1. Serve the service worker
+
+Serve `phoenix-notifications-sw.js` (in this package) at your site's root, so it is reachable at
+`https://your-site/phoenix-notifications-sw.js`. It must be on your own site: a service worker only controls its own origin.
+Copy it from `node_modules/@phoenix-iq/notifications/phoenix-notifications-sw.js` in your build, or with Vite emit it from a
+small plugin (HQ's dashboard `vite.config.ts` does).
+
+## 2. Initialise and log in
+
+```ts
+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
+const permission = await Notifications.requestPermission(); // 'granted' | 'denied' | 'default' | 'unsupported'
+
+// after your own sign-in, with the identity token your backend returned
+await Notifications.login(identityToken);
+
+// on sign-out: the browser keeps your broadcasts as a guest, but not that user's notifications
+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.
+
+## 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.
+
+A site with its own "Get notifications" button passes `bell: false` and `banner: false`, and uses `requestPermission()`,
+`unsubscribe()` and the state below.
+
+## 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
+
+```ts
+Notifications.onClick(({ url, data }) => router.navigate(new URL(url ?? '/', location.origin).pathname));
+```
+
+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.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `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 page's (`<html lang>`), then the browser's | Picks the Arabic or English text of a notification, and the bell'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 |
+
+## 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`).
+
+## Publishing
+
+`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,41 @@
+import type { SubscriptionState } from './index.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
+ * 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.
+ * 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;
+}
+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;

package/dist/banner.js

@@ -0,0 +1,183 @@
+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, as OneSignal's does */
+  :host([data-position="top"]) { top: auto; bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+  :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 {
+  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; `destroy()` takes it away at once. */
+export function mountBanner(api, settings, language, placement = {}) {
+    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));
+    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,31 @@
+import type { SubscriptionState } from './index.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.
+ *
+ * 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`). */
+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;
+}
+/** 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 bell into the page; `destroy()` takes it away again. */
+export declare function mountBell(api: BellApi, settings: BellSettings, language: string): BellHandle;