@modernman00/shared-js-lib 1.2.90 → 1.6.2

package/WebPushClient.js

@@ -0,0 +1,308 @@
+/**
+ * @modernman00/shared-js-lib — WebPushClient
+ *
+ * Enterprise Web Push & Service Worker Lifecycle Engine (RFC-0009):
+ * - Bounded Watchdog Promises (8s SW ready, 20s permission prompt, 10s PushManager subscribe, 8s backend sync)
+ * - Automatic VAPID Key Rotation Recovery (catches InvalidStateError, unsubscribes stale endpoint, retries once)
+ * - Smart 3-Day (72-Hour) Dismissal Cooldown (re-prompts unsubscribed users after 72h instead of permanent suppression)
+ * - Cross-Tab BroadcastChannel Deduplication ('fp_notification_sync')
+ */
+
+export const DEFAULT_DISMISS_COOLDOWN_MS = 3 * 24 * 60 * 60 * 1000; // 72 hours (3 days)
+export const DEFAULT_DISMISS_KEY = 'fp_push_banner_dismissed';
+export const DEFAULT_SUBSCRIBED_KEY = 'fp_push_subscribed';
+
+/**
+ * Wraps any Promise or thenable with a deterministic watchdog timer so UI spinners never hang indefinitely.
+ *
+ * @param {Promise<any>} promise
+ * @param {number} ms
+ * @param {string} [timeoutMessage]
+ * @returns {Promise<any>}
+ */
+export function withPushTimeout(promise, ms, timeoutMessage = 'Push operation timed out') {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(timeoutMessage));
+        }, ms);
+        Promise.resolve(promise).then(
+            (val) => {
+                clearTimeout(timer);
+                resolve(val);
+            },
+            (err) => {
+                clearTimeout(timer);
+                reject(err);
+            }
+        );
+    });
+}
+
+/**
+ * Converts a URL-safe base64 VAPID public key string into a Uint8Array for PushManager.subscribe().
+ *
+ * @param {string} base64String
+ * @returns {Uint8Array}
+ */
+export function urlBase64ToUint8Array(base64String) {
+    const clean = String(base64String || '').trim();
+    const padding = '='.repeat((4 - (clean.length % 4)) % 4);
+    const base64 = (clean + padding).replace(/-/g, '+').replace(/_/g, '/');
+    const rawData = typeof window !== 'undefined' && typeof window.atob === 'function'
+        ? window.atob(base64)
+        : Buffer.from(base64, 'base64').toString('binary');
+    const outputArray = new Uint8Array(rawData.length);
+    for (let i = 0; i < rawData.length; ++i) {
+        outputArray[i] = rawData.charCodeAt(i);
+    }
+    return outputArray;
+}
+
+/**
+ * Checks whether the user dismissed the push prompt within the 3-day (72-hour) cooldown window.
+ * Automatically migrates legacy boolean `'true'` values to a timestamp and clears expired timestamps.
+ *
+ * @param {string} [storageKey=DEFAULT_DISMISS_KEY]
+ * @param {number} [cooldownMs=DEFAULT_DISMISS_COOLDOWN_MS]
+ * @param {Storage} [storage]
+ * @returns {boolean} True if dismissed within the cooldown window; false if eligible to prompt again.
+ */
+export function isPushDismissedWithinCooldown(
+    storageKey = DEFAULT_DISMISS_KEY,
+    cooldownMs = DEFAULT_DISMISS_COOLDOWN_MS,
+    storage = typeof localStorage !== 'undefined' ? localStorage : null
+) {
+    if (!storage) return false;
+    try {
+        const raw = storage.getItem(storageKey);
+        if (!raw) return false;
+
+        // Legacy migration: if 'true' was stored before RFC-0009, convert to current timestamp
+        if (raw === 'true') {
+            storage.setItem(storageKey, String(Date.now()));
+            return true;
+        }
+
+        const dismissedAt = parseInt(raw, 10);
+        if (Number.isNaN(dismissedAt) || dismissedAt <= 0) {
+            storage.removeItem(storageKey);
+            return false;
+        }
+
+        if (Date.now() - dismissedAt < cooldownMs) {
+            return true;
+        }
+
+        // Cooldown expired (>= 3 days): clear key so user is re-prompted
+        storage.removeItem(storageKey);
+        return false;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Records the current timestamp when a user clicks "Not Now" or closes the push prompt.
+ *
+ * @param {string} [storageKey=DEFAULT_DISMISS_KEY]
+ * @param {Storage} [storage]
+ */
+export function recordPushDismissal(
+    storageKey = DEFAULT_DISMISS_KEY,
+    storage = typeof localStorage !== 'undefined' ? localStorage : null
+) {
+    if (!storage) return;
+    try {
+        storage.setItem(storageKey, String(Date.now()));
+    } catch {
+        // Ignore storage quota errors
+    }
+}
+
+/**
+ * Clears any recorded push dismissal timestamp (e.g., once the user enables notifications).
+ *
+ * @param {string} [storageKey=DEFAULT_DISMISS_KEY]
+ * @param {Storage} [storage]
+ */
+export function clearPushDismissal(
+    storageKey = DEFAULT_DISMISS_KEY,
+    storage = typeof localStorage !== 'undefined' ? localStorage : null
+) {
+    if (!storage) return;
+    try {
+        storage.removeItem(storageKey);
+    } catch {
+        // Ignore storage errors
+    }
+}
+
+/**
+ * Ensures the Service Worker is registered and active within a bounded timeout (default 8s),
+ * preventing `navigator.serviceWorker.ready` from hanging forever when registration fails.
+ *
+ * @param {object} [options]
+ * @param {string} [options.swUrl='/sw.js']
+ * @param {string} [options.scope='/']
+ * @param {number} [options.timeoutMs=8000]
+ * @returns {Promise<ServiceWorkerRegistration>}
+ */
+export async function ensureServiceWorkerReady(options = {}) {
+    const swUrl = options.swUrl || '/sw.js';
+    const scope = options.scope || '/';
+    const timeoutMs = options.timeoutMs || 8000;
+
+    if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+        throw new Error('Service Workers are not supported in this browser.');
+    }
+
+    let reg = await navigator.serviceWorker.getRegistration(scope);
+    if (!reg) {
+        reg = await navigator.serviceWorker.register(swUrl, { scope });
+    }
+    if (reg && reg.active) {
+        return reg;
+    }
+
+    return withPushTimeout(
+        navigator.serviceWorker.ready,
+        timeoutMs,
+        'Service Worker activation timed out. Please reload the page and try again.'
+    );
+}
+
+/**
+ * Subscribes the browser to Web Push via PushManager with automatic InvalidStateError
+ * VAPID key rotation recovery and bounded timeouts.
+ *
+ * @param {object} options
+ * @param {string} options.vapidPublicKey
+ * @param {(subscription: PushSubscription) => Promise<any>} [options.syncToServer]
+ * @param {string} [options.swUrl='/sw.js']
+ * @param {string} [options.scope='/']
+ * @param {number} [options.swTimeoutMs=8000]
+ * @param {number} [options.subscribeTimeoutMs=10000]
+ * @param {number} [options.syncTimeoutMs=8000]
+ * @returns {Promise<PushSubscription>}
+ */
+export async function subscribeWithKeyRotation(options = {}) {
+    const {
+        vapidPublicKey,
+        syncToServer,
+        swUrl = '/sw.js',
+        scope = '/',
+        swTimeoutMs = 8000,
+        subscribeTimeoutMs = 10000,
+        syncTimeoutMs = 8000,
+    } = options;
+
+    if (typeof navigator === 'undefined' || !('serviceWorker' in navigator) || typeof window === 'undefined' || !('PushManager' in window)) {
+        throw new Error('Push notifications are not supported in this browser.');
+    }
+
+    if (!vapidPublicKey || String(vapidPublicKey).trim() === '') {
+        throw new Error('VAPID public key is not configured.');
+    }
+
+    const registration = await ensureServiceWorkerReady({ swUrl, scope, timeoutMs: swTimeoutMs });
+    let subscription = await registration.pushManager.getSubscription();
+
+    if (!subscription) {
+        const appServerKey = urlBase64ToUint8Array(vapidPublicKey);
+        const attemptSubscribe = async () => {
+            try {
+                return await registration.pushManager.subscribe({
+                    userVisibleOnly: true,
+                    applicationServerKey: appServerKey,
+                });
+            } catch (subErr) {
+                if (subErr && subErr.name === 'InvalidStateError') {
+                    const staleSub = await registration.pushManager.getSubscription();
+                    if (staleSub) {
+                        await staleSub.unsubscribe();
+                    }
+                    return await registration.pushManager.subscribe({
+                        userVisibleOnly: true,
+                        applicationServerKey: appServerKey,
+                    });
+                }
+                throw subErr;
+            }
+        };
+
+        subscription = await withPushTimeout(
+            attemptSubscribe(),
+            subscribeTimeoutMs,
+            'Push service connection timed out. Check your internet connection or browser push settings.'
+        );
+    }
+
+    if (typeof syncToServer === 'function') {
+        await withPushTimeout(
+            syncToServer(subscription),
+            syncTimeoutMs,
+            'Server subscription sync timed out.'
+        );
+    }
+
+    return subscription;
+}
+
+/**
+ * Cross-tab BroadcastChannel coordinator so multiple open tabs share read-state and badge updates
+ * without duplicate network polling.
+ *
+ * @param {(payload: any) => void} onMessage
+ * @param {string} [channelName='fp_notification_sync']
+ * @returns {{ broadcast: (data: any) => void, close: () => void }}
+ */
+export function createNotificationSyncChannel(onMessage, channelName = 'fp_notification_sync') {
+    if (typeof window === 'undefined' || typeof window.BroadcastChannel !== 'function') {
+        return {
+            broadcast: () => {},
+            close: () => {},
+        };
+    }
+
+    const channel = new window.BroadcastChannel(channelName);
+    if (typeof onMessage === 'function') {
+        channel.onmessage = (event) => {
+            if (event && event.data) {
+                onMessage(event.data);
+            }
+        };
+    }
+
+    return {
+        broadcast: (data) => {
+            try {
+                channel.postMessage(data);
+            } catch {
+                // Ignore closed channel errors
+            }
+        },
+        close: () => {
+            try {
+                channel.close();
+            } catch {
+                // Ignore
+            }
+        },
+    };
+}
+
+export const WebPushClient = {
+    DEFAULT_DISMISS_COOLDOWN_MS,
+    DEFAULT_DISMISS_KEY,
+    DEFAULT_SUBSCRIBED_KEY,
+    withPushTimeout,
+    urlBase64ToUint8Array,
+    isPushDismissedWithinCooldown,
+    recordPushDismissal,
+    clearPushDismissal,
+    ensureServiceWorkerReady,
+    subscribeWithKeyRotation,
+    createNotificationSyncChannel,
+};
+
+export default WebPushClient;

package/axiosWrapper.js

@@ -18,4 +18,5 @@ axios.interceptors.request.use(config => {
     return config;
 });
 
+export const axiosWrapper = axios;
 export default axios;

package/index.js

@@ -32,4 +32,16 @@ export * from './ShareManager.js';
 export * from './WebAuthnClient.js';
 export * from './OtpInputManager.js';
 export * from './AddressAutocomplete.js';
-export * from './DigitalSignaturePad.js';
+export * from './DigitalSignaturePad.js';
+export * from './AiVoiceRecorder.js';
+export * from './AiMediaGuard.js';
+export * from './AiSemanticSearch.js';
+export * from './AiFlyerStudio.js';
+export * from './AiBillSplitter.js';
+export * from './AiEntertainmentPrompt.js';
+export * from './AiPrivacyGuard.js';
+export * from './WebPushClient.js';
+export * from './FileUpload.js';
+export * from './CanvasPhysicsEngine.js';
+export * from './SovereignBroadcasterClient.js';
+export * from './HyperReality3DEngine.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modernman00/shared-js-lib",
-  "version": "1.2.90",
+  "version": "1.6.2",
   "description": "Reusable JS utilities for numerous js problems",
   "homepage": "https://github.com/modernman00/shared-js-lib#readme",
   "keywords": [
@@ -66,6 +66,18 @@
     "OtpInputManager.js",
     "AddressAutocomplete.js",
     "DigitalSignaturePad.js",
+    "AiVoiceRecorder.js",
+    "AiMediaGuard.js",
+    "AiSemanticSearch.js",
+    "AiFlyerStudio.js",
+    "AiBillSplitter.js",
+    "AiEntertainmentPrompt.js",
+    "AiPrivacyGuard.js",
+    "WebPushClient.js",
+    "CanvasPhysicsEngine.js",
+    "HyperReality3DEngine.js",
+    "SovereignBroadcasterClient.js",
+    "VisualSupremacyRuntime.js",
     "templates/"
   ],
   "devDependencies": {

package/templates/sw.template.js

@@ -138,7 +138,7 @@ if (typeof workbox !== 'undefined') {
   ]);
 }
 
-// Push Notifications & Badging Engine
+// Push Notifications & Badging Engine — Meta/Facebook Tier-1 Standard
 self.addEventListener('push', (event) => {
   let data = {
     title: APP_NAME,
@@ -157,83 +157,131 @@ self.addEventListener('push', (event) => {
     }
   }
 
-  const promises = [];
-
-  // 1. Show System Notification Banner
-  promises.push(
-    self.registration.showNotification(data.title, {
-      body: data.body,
-      icon: data.icon,
-      badge: data.badge,
-      data: { url: data.url, id: data.targetNotificationId },
-      tag: data.tag
-    })
-  );
-
-  // 2. Web Badging API Sync (Phone App Icon Red Counter)
-  if ('setAppBadge' in navigator) {
-    let count = null;
-    if (typeof data.badgeCount === 'number') {
-      count = Math.max(0, Math.floor(data.badgeCount));
-    } else if (data.badgeCount !== null && data.badgeCount !== undefined && !isNaN(parseInt(data.badgeCount, 10))) {
-      count = Math.max(0, parseInt(data.badgeCount, 10));
+  event.waitUntil((async () => {
+    // 1. Web Badging API Sync (App Icon Counter on Home Screen / Dock)
+    let badgeCount = null;
+    if (typeof data.unread_count === 'number' || typeof data.unreadCount === 'number' || typeof data.badgeCount === 'number') {
+      badgeCount = Math.max(0, Math.floor(data.unread_count ?? data.unreadCount ?? data.badgeCount));
+    } else if (data.unread_count || data.unreadCount || data.badgeCount) {
+      const parsed = parseInt(data.unread_count || data.unreadCount || data.badgeCount, 10);
+      if (!isNaN(parsed)) badgeCount = Math.max(0, parsed);
     }
 
-    if (count !== null) {
-      promises.push(
-        count > 0 
-          ? navigator.setAppBadge(count).catch(() => {}) 
-          : navigator.clearAppBadge().catch(() => {})
-      );
-    } else {
-      // Fallback: When an active push notification arrives, ensure at least 1 badge is set on the app icon
-      promises.push(navigator.setAppBadge(1).catch(() => {}));
+    if ('setAppBadge' in navigator) {
+      try {
+        if (badgeCount !== null) {
+          if (badgeCount > 0) {
+            await navigator.setAppBadge(badgeCount);
+          } else {
+            await navigator.clearAppBadge();
+          }
+        } else {
+          await navigator.setAppBadge(1);
+        }
+      } catch (err) {}
     }
-  }
 
-  // 3. Notify any active client windows so in-app bell counter updates immediately
-  promises.push(
-    clients.matchAll({ type: 'window', includeUncontrolled: true }).then((clientList) => {
+    // 2. Client-Focus Awareness (Meta Standard: Suppress system banner when app is actively focused)
+    const clientList = await clients.matchAll({ type: 'window', includeUncontrolled: true });
+    const activeFocusedClient = clientList.find(c => c.focused && 'postMessage' in c);
+
+    if (activeFocusedClient) {
+      // User is actively looking at the screen: broadcast to DOM toast, update tab badge, and SUPPRESS OS banner
       clientList.forEach((client) => {
         client.postMessage({
           type: 'ON_APP_NOTIFICATION',
-          payload: data
+          payload: { ...data, badgeCount: badgeCount }
         });
       });
-    }).catch(() => {})
-  );
+      return; // Suppress OS lock-screen popup to eliminate double-alert noise
+    }
+
+    // Broadcast to any backgrounded open windows so their in-DOM tabs update
+    clientList.forEach((client) => {
+      client.postMessage({
+        type: 'ON_APP_NOTIFICATION',
+        payload: { ...data, badgeCount: badgeCount }
+      });
+    });
+
+    // 3. User is backgrounded or app is closed: Display Rich System Notification Banner
+    const options = {
+      body: data.body,
+      icon: data.icon || '/public/resources/assets/images/pwa/icons/icon-192x192.png',
+      badge: data.badge || '/public/resources/assets/images/pwa/icons/icon-72x72.png',
+      tag: data.tag || `${APP_NAME}-notification`,
+      vibrate: data.vibrate || [150, 80, 150],
+      renotify: data.renotify !== false,
+      data: {
+        url: data.url || '/',
+        id: data.targetNotificationId || null,
+        unreadCount: badgeCount
+      }
+    };
 
-  event.waitUntil(Promise.all(promises));
+    if (data.image) {
+      options.image = data.image;
+    }
+    if (Array.isArray(data.actions) && data.actions.length > 0) {
+      options.actions = data.actions.slice(0, 2);
+    }
+
+    return self.registration.showNotification(data.title, options);
+  })());
 });
 
-// Notification Click & Deep-Linking
+// Notification Click & Deep-Linking — Meta Standard
 self.addEventListener('notificationclick', (event) => {
   event.notification.close();
-  const targetUrl = event.notification.data?.url || '/';
+  const notifData = event.notification.data || {};
+  let targetUrl = notifData.url || '/';
 
-  const promises = [];
+  // Sanitize targetUrl: must be relative path or same origin (Red Team anti-open-redirect)
+  try {
+    const parsed = new URL(targetUrl, self.location.origin);
+    if (parsed.origin !== self.location.origin) {
+      targetUrl = '/';
+    } else {
+      targetUrl = parsed.pathname + parsed.search + parsed.hash;
+    }
+  } catch (e) {
+    targetUrl = '/';
+  }
 
-  if ('clearAppBadge' in navigator) {
-    promises.push(navigator.clearAppBadge().catch(() => {}));
+  // Handle action button clicks (e.g. "mark_read" or "dismiss")
+  if (event.action === 'mark_read' || event.action === 'read') {
+    if (notifData.id) {
+      event.waitUntil(
+        fetch('/api/notifications/read', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ id: notifData.id })
+        }).catch(() => {})
+      );
+      return;
+    }
   }
 
-  promises.push(
-    clients.matchAll({ type: 'window', includeUncontrolled: true }).then((list) => {
-      for (const client of list) {
-        if (client.url.includes(targetUrl) && 'focus' in client) {
-          if ('navigate' in client) client.navigate(targetUrl);
-          return client.focus();
-        }
+  event.waitUntil((async () => {
+    const list = await clients.matchAll({ type: 'window', includeUncontrolled: true });
+    for (const client of list) {
+      if (client.url.includes(targetUrl) && 'focus' in client) {
+        if ('navigate' in client) await client.navigate(targetUrl);
+        return client.focus();
       }
-      if (clients.openWindow) return clients.openWindow(targetUrl);
-    })
-  );
-
-  event.waitUntil(Promise.all(promises));
+    }
+    if (clients.openWindow) {
+      return clients.openWindow(targetUrl);
+    }
+  })());
 });
 
 // Cross-Tab Client Messages
 self.addEventListener('message', (event) => {
-  if (event.data?.action === 'skipWaiting') self.skipWaiting();
-  if (event.data?.action === 'clearUserCache') event.waitUntil(caches.delete(API_CACHE));
+  if (event.data?.action === 'skipWaiting' || event.data?.type === 'SKIP_WAITING') {
+    self.skipWaiting();
+  }
+  if (event.data?.action === 'clearUserCache') {
+    event.waitUntil(caches.delete(API_CACHE));
+  }
 });