@synergonai/push-web 0.1.0

package/dist/index.js

@@ -0,0 +1,421 @@
+// src/index.ts
+import {
+  ApiClient,
+  EventQueue,
+  STORAGE_KEYS
+} from "@synergonai/push-core";
+
+// src/firebase-bootstrap.ts
+import { initializeApp } from "firebase/app";
+import {
+  getMessaging,
+  getToken,
+  onMessage,
+  isSupported
+} from "firebase/messaging";
+
+// src/fcm-fetch-patch.ts
+var FCM_REGISTRATIONS_HOST = "fcmregistrations.googleapis.com";
+var PATCH_FLAG = "__synergonFcmFetchPatched";
+function installFcmFetchPatch() {
+  if (typeof globalThis === "undefined" || typeof globalThis.fetch !== "function") return;
+  const g = globalThis;
+  if (g[PATCH_FLAG]) return;
+  const originalFetch = globalThis.fetch.bind(globalThis);
+  globalThis.fetch = async function patchedFetch(input, init) {
+    try {
+      const url = resolveUrl(input);
+      if (!url || !url.includes(FCM_REGISTRATIONS_HOST)) {
+        return originalFetch(input, init);
+      }
+      const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+      if (method !== "POST" && method !== "PATCH") {
+        return originalFetch(input, init);
+      }
+      const sourceBody = init?.body ?? (input instanceof Request ? await readRequestBody(input) : void 0);
+      if (typeof sourceBody !== "string") {
+        return originalFetch(input, init);
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(sourceBody);
+      } catch {
+        return originalFetch(input, init);
+      }
+      if (!parsed?.web || !("applicationPubKey" in parsed.web)) {
+        return originalFetch(input, init);
+      }
+      delete parsed.web.applicationPubKey;
+      const patchedBody = JSON.stringify(parsed);
+      if (input instanceof Request) {
+        const clonedInit = {
+          method,
+          headers: cloneHeaders(input.headers),
+          body: patchedBody,
+          credentials: input.credentials,
+          mode: input.mode,
+          referrer: input.referrer
+        };
+        return originalFetch(input.url, clonedInit);
+      }
+      return originalFetch(input, { ...init, body: patchedBody });
+    } catch {
+      return originalFetch(input, init);
+    }
+  };
+  g[PATCH_FLAG] = true;
+}
+function resolveUrl(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.href;
+  if (input instanceof Request) return input.url;
+  return null;
+}
+async function readRequestBody(req) {
+  try {
+    return await req.clone().text();
+  } catch {
+    return void 0;
+  }
+}
+function cloneHeaders(h) {
+  const out = new Headers();
+  h.forEach((v, k) => out.append(k, v));
+  return out;
+}
+
+// src/firebase-bootstrap.ts
+var FirebaseBootstrap = class _FirebaseBootstrap {
+  constructor(app, messaging, opts) {
+    this.app = app;
+    this.messaging = messaging;
+    this.vapidKey = opts.vapidKey;
+    this.swReg = opts.serviceWorkerRegistration;
+  }
+  /**
+   * Returns null if the runtime can't support FCM (no service worker
+   * support, http://, etc). Callers should treat null as a hard "no push
+   * here" and surface that to the user.
+   */
+  static async create(opts) {
+    if (!await isSupported()) return null;
+    installFcmFetchPatch();
+    const app = initializeApp(opts.firebaseConfig);
+    const messaging = getMessaging(app);
+    return new _FirebaseBootstrap(app, messaging, opts);
+  }
+  /**
+   * Fetch the current FCM registration token. Triggers the browser's
+   * notification permission prompt if not yet granted.
+   */
+  async getToken() {
+    const token = await getToken(this.messaging, {
+      vapidKey: this.vapidKey,
+      serviceWorkerRegistration: this.swReg
+    });
+    if (!token) {
+      throw new Error("FCM returned an empty token. User may have denied notifications.");
+    }
+    return token;
+  }
+  /** Subscribe to foreground messages (page visible). Returns an unsubscribe. */
+  onMessage(handler) {
+    return onMessage(this.messaging, handler);
+  }
+};
+
+// src/storage-localstorage.ts
+var LocalStorageAdapter = class _LocalStorageAdapter {
+  constructor() {
+    this.available = _LocalStorageAdapter.isAvailable();
+  }
+  async get(key) {
+    if (!this.available) return null;
+    try {
+      const raw = window.localStorage.getItem(key);
+      if (raw === null) return null;
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async set(key, value) {
+    if (!this.available) return;
+    try {
+      window.localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+    }
+  }
+  async remove(key) {
+    if (!this.available) return;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+    }
+  }
+  /**
+   * Some browsers (Safari private mode) expose localStorage but throw on
+   * write. Probe with a no-op write and clean up.
+   */
+  static isAvailable() {
+    try {
+      if (typeof window === "undefined" || !window.localStorage) return false;
+      const probe = "__synergon_probe__";
+      window.localStorage.setItem(probe, "1");
+      window.localStorage.removeItem(probe);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/payload.ts
+import {
+  PLACEHOLDER_MESSAGE_ID,
+  SYN_CAMPAIGN_ID_KEY,
+  SYN_MESSAGE_ID_KEY
+} from "@synergonai/push-core";
+function normalizePayload(raw) {
+  const data = raw.data ?? {};
+  const notification = raw.notification ?? {};
+  const rawMessageId = data[SYN_MESSAGE_ID_KEY];
+  return {
+    notification: {
+      title: notification.title,
+      body: notification.body,
+      image: notification.image
+    },
+    data,
+    messageId: rawMessageId && rawMessageId !== PLACEHOLDER_MESSAGE_ID ? rawMessageId : void 0,
+    campaignId: data[SYN_CAMPAIGN_ID_KEY]
+  };
+}
+
+// src/index.ts
+var SynergonPushClass = class {
+  constructor() {
+    this.apiClient = null;
+    this.eventQueue = null;
+    this.firebase = null;
+    this.storage = null;
+    this.logger = {};
+    this.initOpts = null;
+    this.messageHandler = null;
+    this.unsubMessage = null;
+    this.deviceId = null;
+    this.fcmToken = null;
+  }
+  /**
+   * Bootstrap the SDK. Idempotent — safe to call from React StrictMode
+   * double-render, etc. Returns the SDK status snapshot.
+   */
+  async init(opts) {
+    if (this.initOpts) {
+      this.logger.warn?.("[push-web] SynergonPush.init called twice; ignoring second call.");
+      return this.getStatus();
+    }
+    this.initOpts = opts;
+    this.logger = opts.logger ?? {};
+    this.storage = new LocalStorageAdapter();
+    this.apiClient = new ApiClient({ config: opts });
+    this.eventQueue = new EventQueue({
+      api: this.apiClient,
+      storage: this.storage,
+      logger: this.logger
+    });
+    let bootstrap;
+    try {
+      bootstrap = await this.apiClient.bootstrap();
+    } catch (err) {
+      this.logger.error?.("[push-web] bootstrap failed", { error: err.message });
+      throw new Error(
+        "Synergon bootstrap failed. Either the publishable key is invalid or the account is missing its Firebase Web config. Configure it in Synergon admin \u2192 Campaigns \u2192 Push \u2192 Firebase Account."
+      );
+    }
+    let swReg;
+    if (opts.serviceWorkerPath) {
+      try {
+        swReg = await navigator.serviceWorker.register(opts.serviceWorkerPath);
+      } catch (err) {
+        this.logger.warn?.("[push-web] service worker registration failed", {
+          path: opts.serviceWorkerPath,
+          error: err.message
+        });
+      }
+    }
+    this.firebase = await FirebaseBootstrap.create({
+      firebaseConfig: bootstrap.firebaseConfig,
+      vapidKey: bootstrap.vapidKey,
+      serviceWorkerRegistration: swReg
+    });
+    this.deviceId = await this.storage.get(STORAGE_KEYS.deviceId);
+    this.fcmToken = await this.storage.get(STORAGE_KEYS.lastFcmToken);
+    this.eventQueue.flush().catch((err) => this.logger.warn?.("[push-web] flush at boot failed", { error: err.message }));
+    if (typeof window !== "undefined") {
+      window.addEventListener("online", () => {
+        this.eventQueue?.flush().catch(() => void 0);
+      });
+    }
+    this.subscribeForegroundMessages();
+    return this.getStatus();
+  }
+  /**
+   * Prompt the user for notification permission, fetch a token from
+   * Firebase, then register with Synergon. Throws if the user denies or
+   * if Firebase is unavailable.
+   */
+  async requestPermissionAndRegister(opts = {}) {
+    this.assertInitialized();
+    if (typeof Notification === "undefined") {
+      throw new Error("Notification API unavailable in this environment.");
+    }
+    const permission = await Notification.requestPermission();
+    if (permission !== "granted") {
+      throw new Error(`Notification permission ${permission}.`);
+    }
+    return this.register(opts);
+  }
+  /**
+   * Register only if the user has already granted permission. Returns
+   * null if not granted (no prompt). Useful when the integrator wants to
+   * call this on every app load (idempotent) without nagging the user.
+   */
+  async registerIfPermitted(opts = {}) {
+    this.assertInitialized();
+    if (typeof Notification === "undefined") return null;
+    if (Notification.permission !== "granted") return null;
+    return this.register(opts);
+  }
+  /**
+   * Fetch (or refresh) the FCM token and POST it to /v1/campaigns/push/devices.
+   * Persists `deviceId` and `fcmToken` locally so subsequent calls are no-ops
+   * if the token hasn't changed.
+   */
+  async register(opts = {}) {
+    this.assertInitialized();
+    const fb = this.firebase;
+    if (!fb) throw new Error("Firebase Messaging not supported in this browser.");
+    const token = await fb.getToken();
+    if (this.fcmToken && this.fcmToken === token && this.deviceId) {
+      this.logger.debug?.("[push-web] token unchanged; skipping re-register", {
+        deviceId: this.deviceId
+      });
+      return this.cachedDeviceResponse();
+    }
+    const response = await this.apiClient.registerDevice({
+      fcmToken: token,
+      platform: "web",
+      appVersion: opts.appVersion,
+      locale: typeof navigator !== "undefined" ? navigator.language : void 0,
+      identifierValue: opts.identifierValue,
+      leadId: opts.leadId,
+      marketingOptIn: opts.marketingOptIn
+    });
+    this.deviceId = response.id;
+    this.fcmToken = token;
+    await this.storage.set(STORAGE_KEYS.deviceId, response.id);
+    await this.storage.set(STORAGE_KEYS.lastFcmToken, token);
+    if (opts.identifierValue !== void 0) {
+      await this.storage.set(STORAGE_KEYS.identifierValue, opts.identifierValue);
+    }
+    if (opts.marketingOptIn !== void 0) {
+      await this.storage.set(STORAGE_KEYS.marketingOptIn, opts.marketingOptIn);
+    }
+    this.logger.info?.("[push-web] registered with Synergon", { deviceId: response.id });
+    return response;
+  }
+  /** Foreground message subscription. Returns an unsubscribe callable. */
+  onMessage(handler) {
+    this.messageHandler = handler;
+    return () => {
+      this.messageHandler = null;
+    };
+  }
+  /**
+   * Manually fire a delivered/opened/clicked event. The SDK's own
+   * onMessage path fires `delivered` automatically — call this only when
+   * you want to attribute custom events (e.g. a button click in a
+   * notification-triggered modal).
+   */
+  async reportEvent(idOrPayload, eventType) {
+    this.assertInitialized();
+    const ids = typeof idOrPayload === "string" ? { messageId: idOrPayload } : idOrPayload;
+    await this.eventQueue.enqueue({
+      ...ids,
+      eventType,
+      platform: "web",
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /**
+   * Clear local state. Note: this does NOT delete the device on the
+   * Synergon side — the public endpoint doesn't permit publishable-key
+   * authenticated deletes. Have your backend call DELETE
+   * /v1/campaigns/push/devices/:id if you want full removal.
+   */
+  async unregister() {
+    this.assertInitialized();
+    await this.storage.remove(STORAGE_KEYS.deviceId);
+    await this.storage.remove(STORAGE_KEYS.lastFcmToken);
+    await this.storage.remove(STORAGE_KEYS.identifierValue);
+    await this.storage.remove(STORAGE_KEYS.marketingOptIn);
+    this.deviceId = null;
+    this.fcmToken = null;
+    this.unsubMessage?.();
+    this.unsubMessage = null;
+  }
+  getStatus() {
+    const permission = typeof Notification === "undefined" ? "unsupported" : Notification.permission;
+    return {
+      initialized: this.initOpts !== null,
+      permission,
+      registered: this.deviceId !== null,
+      deviceId: this.deviceId,
+      fcmToken: this.fcmToken
+    };
+  }
+  // ─── internals ───────────────────────────────────────────────────────
+  subscribeForegroundMessages() {
+    if (!this.firebase) return;
+    this.unsubMessage = this.firebase.onMessage(async (raw) => {
+      const payload = normalizePayload(raw);
+      const canIdentify = !!payload.messageId || !!(this.fcmToken && payload.campaignId);
+      if (canIdentify) {
+        try {
+          await this.eventQueue?.enqueue({
+            messageId: payload.messageId,
+            fcmToken: payload.messageId ? void 0 : this.fcmToken,
+            campaignId: payload.messageId ? void 0 : payload.campaignId,
+            eventType: "delivered",
+            platform: "web",
+            occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } catch (err) {
+          this.logger.warn?.("[push-web] failed to report delivered", {
+            error: err.message
+          });
+        }
+      }
+      this.messageHandler?.(payload);
+    });
+  }
+  cachedDeviceResponse() {
+    return {
+      id: this.deviceId,
+      status: "active",
+      platform: "web",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      registeredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  assertInitialized() {
+    if (!this.initOpts) {
+      throw new Error("SynergonPush.init() must be called before any other SDK method.");
+    }
+  }
+};
+var SynergonPush = new SynergonPushClass();
+export {
+  SynergonPush
+};

package/dist/sw-template.cjs

@@ -0,0 +1,67 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sw-template.ts
+var sw_template_exports = {};
+__export(sw_template_exports, {
+  readServiceWorkerTemplate: () => readServiceWorkerTemplate
+});
+module.exports = __toCommonJS(sw_template_exports);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+function getModuleDir() {
+  try {
+    const dirname = (0, eval)('typeof __dirname !== "undefined" ? __dirname : undefined');
+    if (dirname) return dirname;
+  } catch {
+  }
+  const url = (0, eval)('typeof import.meta !== "undefined" ? import.meta.url : undefined');
+  if (url) return import_node_path.default.dirname((0, import_node_url.fileURLToPath)(url));
+  throw new Error("[push-web/sw-template] Unable to resolve module directory.");
+}
+var here = getModuleDir();
+function readServiceWorkerTemplate() {
+  const candidates = [
+    import_node_path.default.resolve(here, "../public/firebase-messaging-sw.js"),
+    import_node_path.default.resolve(here, "../../public/firebase-messaging-sw.js")
+  ];
+  for (const candidate of candidates) {
+    if (import_node_fs.default.existsSync(candidate)) {
+      return import_node_fs.default.readFileSync(candidate, "utf8");
+    }
+  }
+  throw new Error(
+    "[push-web/sw-template] firebase-messaging-sw.js not found. Looked at:\n  " + candidates.join("\n  ")
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  readServiceWorkerTemplate
+});

package/dist/sw-template.d.cts

@@ -0,0 +1,3 @@
+declare function readServiceWorkerTemplate(): string;
+
+export { readServiceWorkerTemplate };

package/dist/sw-template.d.ts

@@ -0,0 +1,3 @@
+declare function readServiceWorkerTemplate(): string;
+
+export { readServiceWorkerTemplate };

package/dist/sw-template.js

@@ -0,0 +1,32 @@
+// src/sw-template.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function getModuleDir() {
+  try {
+    const dirname = (0, eval)('typeof __dirname !== "undefined" ? __dirname : undefined');
+    if (dirname) return dirname;
+  } catch {
+  }
+  const url = (0, eval)('typeof import.meta !== "undefined" ? import.meta.url : undefined');
+  if (url) return path.dirname(fileURLToPath(url));
+  throw new Error("[push-web/sw-template] Unable to resolve module directory.");
+}
+var here = getModuleDir();
+function readServiceWorkerTemplate() {
+  const candidates = [
+    path.resolve(here, "../public/firebase-messaging-sw.js"),
+    path.resolve(here, "../../public/firebase-messaging-sw.js")
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return fs.readFileSync(candidate, "utf8");
+    }
+  }
+  throw new Error(
+    "[push-web/sw-template] firebase-messaging-sw.js not found. Looked at:\n  " + candidates.join("\n  ")
+  );
+}
+export {
+  readServiceWorkerTemplate
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@synergonai/push-web",
+  "version": "0.1.0",
+  "description": "Synergon Push SDK for browsers. Wraps firebase/messaging and handles registration + event reporting.",
+  "license": "Apache-2.0",
+  "homepage": "https://synergon.ai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./sw-template": {
+      "types": "./dist/sw-template.d.ts",
+      "import": "./dist/sw-template.js",
+      "require": "./dist/sw-template.cjs"
+    },
+    "./service-worker.js": "./public/firebase-messaging-sw.js"
+  },
+  "files": [
+    "dist",
+    "public/firebase-messaging-sw.js"
+  ],
+  "dependencies": {
+    "firebase": "^12.13.0",
+    "@synergonai/push-core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'web: no tests yet' && exit 0"
+  }
+}

package/public/firebase-messaging-sw.js

@@ -0,0 +1,124 @@
+/**
+ * Synergon Push — service worker template.
+ *
+ * The integrator copies (or symlinks) this file to the root of their static
+ * assets so it's served from `/firebase-messaging-sw.js` (the path
+ * firebase/messaging looks for by default).
+ *
+ * Before deploying:
+ *   1. Replace the placeholders in `firebaseConfig` with your project's
+ *      Web config from Firebase Console → Project Settings → General →
+ *      Your apps → Web → SDK setup and configuration.
+ *   2. Replace the SYNERGON_API_BASE_URL / SYNERGON_TENANT_ID /
+ *      SYNERGON_PUBLISHABLE_KEY placeholders so background message clicks
+ *      can fire /events/opened.
+ *
+ * Why this lives outside the SDK bundle: browser security requires the
+ * service worker to be served from a same-origin URL, and firebase auto
+ * looks at `/firebase-messaging-sw.js`. Bundlers can't relocate it for the
+ * integrator — they have to host it themselves.
+ *
+ * Background message rendering: Firebase auto-renders any payload with a
+ * `notification` block. We only intervene to fire /events/opened when the
+ * user taps the notification, since FCM doesn't ping us back on its own.
+ */
+
+// Compat scripts MUST match the firebase version used in the page bundle —
+// version skew silently drops pushes (the SW won't recognise the FCM envelope).
+importScripts('https://www.gstatic.com/firebasejs/12.13.0/firebase-app-compat.js');
+importScripts('https://www.gstatic.com/firebasejs/12.13.0/firebase-messaging-compat.js');
+
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', event => event.waitUntil(self.clients.claim()));
+
+// REPLACE these placeholders with your Firebase Web config + Synergon credentials.
+const firebaseConfig = {
+    apiKey:            'REPLACE_ME',
+    authDomain:        'REPLACE_ME.firebaseapp.com',
+    projectId:         'REPLACE_ME',
+    messagingSenderId: 'REPLACE_ME',
+    appId:             'REPLACE_ME',
+};
+
+const SYNERGON_API_BASE_URL    = 'REPLACE_ME';   // e.g. https://api.synergon.ai
+const SYNERGON_TENANT_ID       = 'REPLACE_ME';
+const SYNERGON_PUBLISHABLE_KEY = 'REPLACE_ME';   // pk_live_...
+
+firebase.initializeApp(firebaseConfig);
+const messaging = firebase.messaging();
+
+/**
+ * Fire-and-forget POST. We never await this inside a service-worker handler
+ * because that would delay notification rendering / tab focus.
+ */
+function reportEvent(messageId, eventType) {
+    if (!messageId) return;
+    try {
+        fetch(`${SYNERGON_API_BASE_URL}/v1/campaigns/push/events/${eventType}`, {
+            method:  'POST',
+            mode:    'cors',
+            keepalive: true,
+            headers: {
+                'Content-Type':  'application/json',
+                'X-Tenant-Id':   SYNERGON_TENANT_ID,
+                'Authorization': `Bearer ${SYNERGON_PUBLISHABLE_KEY}`,
+            },
+            body: JSON.stringify({
+                messageId,
+                eventType,
+                platform:   'web',
+                occurredAt: new Date().toISOString(),
+            }),
+        }).catch(() => undefined);
+    } catch {
+        // ignore — events are best-effort from the SW
+    }
+}
+
+// Click handler — runs when the user taps a notification rendered by FCM.
+self.addEventListener('notificationclick', event => {
+    const data      = event.notification.data ?? {};
+    const messageId = data.syn_msg_id ?? data.FCM_MSG?.data?.syn_msg_id;
+    const clickUrl  = data.click_action ?? data.FCM_MSG?.notification?.click_action ?? '/';
+
+    event.notification.close();
+    reportEvent(messageId, 'opened');
+
+    // Focus an existing tab open at clickUrl, or open a new one.
+    event.waitUntil((async () => {
+        const allClients = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+        for (const client of allClients) {
+            if (client.url.includes(clickUrl) && 'focus' in client) {
+                return client.focus();
+            }
+        }
+        if (self.clients.openWindow) {
+            return self.clients.openWindow(clickUrl);
+        }
+    })());
+});
+
+/**
+ * Background message handler. Firebase auto-renders `notification` payloads,
+ * but we still get this callback for data-only messages or when the page is
+ * hidden. We use it to fire /events/delivered.
+ *
+ * For data-only messages, we additionally show our own notification so the
+ * user sees something — otherwise the message would be invisible.
+ */
+messaging.onBackgroundMessage(payload => {
+    const data      = payload.data ?? {};
+    const messageId = data.syn_msg_id;
+    reportEvent(messageId, 'delivered');
+
+    // Render a fallback notification only if FCM didn't supply one.
+    if (!payload.notification) {
+        const title = data.title ?? 'New notification';
+        const body  = data.body  ?? '';
+        self.registration.showNotification(title, {
+            body,
+            icon: data.icon ?? undefined,
+            data,
+        });
+    }
+});