@omega.js/client 0.1.0

package/dist/modules/notifications.js

@@ -0,0 +1,433 @@
+import { createLogger } from './logger.js';
+
+const logger = createLogger('push');
+const syncLogger = createLogger('push:sync');
+
+class Notifications {
+  constructor(manager) {
+    this.manager = manager;
+    this._requestInProgress = false;
+  }
+
+  initialize(config) {
+    // Canonical home: omega.json5 `cloud.messaging.vapidKey` (public by
+    // design — VAPID public keys ship to every browser). The nested
+    // firebase.messaging shape is the web/extension bridge contract,
+    // mirroring _resolveFirebaseConfig's cloud-first order.
+    this._vapidKey = this.manager.config?.cloud?.messaging?.vapidKey
+      || this.manager.config?.firebase?.messaging?.config?.vapidKey
+      || null;
+
+    const storage = this.manager.storage();
+    const stored = storage.get('notifications');
+    const permission = typeof Notification !== 'undefined' ? Notification.permission : 'default';
+
+    logger.log('Page load check:', { storedSubscribed: stored?.subscribed, storedToken: stored?.token?.slice(-8), permission });
+
+    // If localStorage says subscribed but browser permission disagrees, clear it
+    if (stored?.subscribed && permission !== 'granted') {
+      logger.log('Clearing stale subscription — permission is', permission);
+      storage.set('notifications', { subscribed: false, token: null });
+    }
+
+    // Arm auto-request if not currently subscribed (including just-cleared)
+    const autoRequest = config?.autoRequest;
+    if ((!stored?.subscribed || permission !== 'granted') && autoRequest > 0) {
+      logger.log('Arming auto-request (delay:', `${autoRequest}ms)`);
+      this._setupAutoRequest(autoRequest);
+    }
+
+    // Listen for foreground messages (tab is focused)
+    if (permission === 'granted') {
+      logger.log('Setting up foreground listener...', { supported: this.isSupported(), hasMessaging: !!this.manager.firebaseMessaging });
+      this.onMessage((payload) => {
+        logger.log('Foreground message received:', payload);
+      }).then(unsub => {
+        logger.log('Foreground listener registered:', typeof unsub === 'function' ? 'OK' : 'FAILED (got empty fn)');
+      });
+    }
+  }
+
+  _setupAutoRequest(delay) {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const handleClick = () => {
+      document.removeEventListener('click', handleClick);
+
+      setTimeout(() => {
+        logger.log('Auto-requesting notification permissions...');
+        this.subscribe().catch(err => {
+          logger.error('Auto-subscription failed:', err.message);
+        });
+      }, delay);
+    };
+
+    document.addEventListener('click', handleClick);
+  }
+
+  // Check if notifications are supported
+  isSupported() {
+    return 'Notification' in window &&
+           'serviceWorker' in navigator &&
+           !!this.manager.firebaseMessaging;
+  }
+
+  // Check if user is subscribed to notifications
+  async isSubscribed() {
+    try {
+      if (!this.isSupported()) {
+        return false;
+      }
+
+      return Notification.permission === 'granted';
+    } catch (error) {
+      console.error('Check subscription error:', error);
+      return false;
+    }
+  }
+
+  // Subscribe to push notifications
+  async subscribe(options = {}) {
+    try {
+      if (!this.isSupported()) {
+        throw new Error('Push notifications are not supported');
+      }
+
+      if (this._requestInProgress) {
+        throw new Error('Subscription request already in progress');
+      }
+
+      this._requestInProgress = true;
+
+      // Get Firebase messaging
+      const messaging = this.manager.firebaseMessaging;
+      if (!messaging) {
+        throw new Error('Firebase Messaging not initialized');
+      }
+
+      // Get service worker registration
+      const swRegistration = this.manager.state.serviceWorker;
+      if (!swRegistration) {
+        throw new Error('Service Worker not registered');
+      }
+
+      // Request notification permission if not already granted
+      if (Notification.permission === 'default') {
+        const permission = await this._askPermission();
+        if (permission !== 'granted') {
+          throw new Error('Notification permission denied');
+        }
+      } else if (Notification.permission === 'denied') {
+        throw new Error('Notification permission denied');
+      }
+
+      // Get FCM token
+      const { getToken } = await import('firebase/messaging');
+      const tokenOptions = { serviceWorkerRegistration: swRegistration };
+      if (this._vapidKey) { tokenOptions.vapidKey = this._vapidKey; }
+      const token = await getToken(messaging, tokenOptions);
+
+      if (!token) {
+        throw new Error('Failed to get FCM token');
+      }
+
+      // Save subscription info
+      await this._saveSubscription(token);
+
+      // Track in local storage
+      const storage = this.manager.storage();
+      storage.set('notifications', {
+        subscribed: true,
+        token: token,
+        timestamp: new Date().toISOString(),
+        uid: this.manager.auth().getUser()?.uid || null
+      });
+
+      this._requestInProgress = false;
+      return { subscribed: true, token };
+
+    } catch (error) {
+      this._requestInProgress = false;
+      console.error('Subscribe error:', error);
+      throw error;
+    }
+  }
+
+  // Unsubscribe from push notifications
+  async unsubscribe() {
+    try {
+      if (!this.isSupported()) {
+        return false;
+      }
+
+      const { deleteToken } = await import('firebase/messaging');
+      const messaging = this.manager.firebaseMessaging;
+
+      if (messaging) {
+        await deleteToken(messaging);
+      }
+
+      // Clear local storage
+      const storage = this.manager.storage();
+      storage.remove('notifications');
+
+      return true;
+    } catch (error) {
+      console.error('Unsubscribe error:', error);
+      throw error;
+    }
+  }
+
+  // Request permission (without subscribing)
+  async requestPermission() {
+    try {
+      if (!this.isSupported()) {
+        throw new Error('Notifications not supported');
+      }
+
+      const permission = await this._askPermission();
+      return permission === 'granted';
+    } catch (error) {
+      console.error('Request permission error:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Ask the browser, and COUNT the asking ([#328](https://github.com/Omega-JS-Stack/omega/issues/328)
+   * inventory gap 9: nothing fired the permission trio, so the drop-off between
+   * being asked and saying yes was invisible).
+   *
+   * Only a real prompt is counted — a permission the browser has already been
+   * answered for shows the visitor no UI at all. A DISMISSED prompt leaves the
+   * permission at 'default' and fires neither outcome on purpose: the visitor
+   * denied nothing, and the gap between requested and answered is the dismissal.
+   *
+   * @returns {Promise<string>} The browser's permission after the ask.
+   */
+  async _askPermission() {
+    const prompted = Notification.permission === 'default';
+    const analytics = this.manager.analytics();
+
+    if (prompted) {
+      analytics.event('notification_permission_request');
+    }
+
+    const permission = await Notification.requestPermission();
+
+    if (prompted && permission === 'granted') {
+      analytics.event('notification_permission_grant');
+    } else if (prompted && permission === 'denied') {
+      analytics.event('notification_permission_deny');
+    }
+
+    return permission;
+  }
+
+  // Get current FCM token
+  async getToken() {
+    try {
+      if (!this.isSupported()) {
+        return null;
+      }
+
+      const messaging = this.manager.firebaseMessaging;
+      if (!messaging) {
+        return null;
+      }
+
+      const { getToken } = await import('firebase/messaging');
+      const swRegistration = this.manager.state.serviceWorker;
+
+      const tokenOptions = { serviceWorkerRegistration: swRegistration };
+      if (this._vapidKey) { tokenOptions.vapidKey = this._vapidKey; }
+      return await getToken(messaging, tokenOptions);
+    } catch (error) {
+      console.error('Get token error:', error);
+      return null;
+    }
+  }
+
+  // Listen for foreground messages
+  async onMessage(callback) {
+    try {
+      if (!this.isSupported()) {
+        return () => {};
+      }
+
+      const { onMessage } = await import('firebase/messaging');
+      const messaging = this.manager.firebaseMessaging;
+
+      if (!messaging) {
+        return () => {};
+      }
+
+      return onMessage(messaging, (payload) => {
+        console.log('Foreground message received:', payload);
+
+        // Extract notification data - handle both payload.notification and payload.data formats
+        const notificationData = payload.notification || payload.data || {};
+        const { title, body, icon, badge, image, click_action, url, tag } = notificationData;
+
+        // Determine the click URL (prioritize click_action, then url, then data.url)
+        const clickUrl = click_action || url || payload.data?.click_action || payload.data?.url;
+
+        // Show notification if we have at least a title
+        if (title) {
+          const notification = new Notification(title, {
+            body: body || '',
+            icon: icon || '/favicon.ico',
+            badge: badge,
+            image: image,
+            tag: tag || 'default',
+            data: { ...payload.data, clickUrl },
+            requireInteraction: true,
+            renotify: true
+          });
+
+          notification.onclick = (event) => {
+            event.preventDefault();
+
+            // Focus or open the target window
+            if (clickUrl) {
+              // Try to find an existing window/tab with this URL
+              window.focus();
+              window.open(clickUrl, '_blank');
+            } else {
+              // Just focus the current window if no URL
+              window.focus();
+            }
+
+            notification.close();
+          };
+        }
+
+        // Call the user's callback with the full payload
+        if (callback) {
+          callback(payload);
+        }
+      });
+    } catch (error) {
+      console.error('Message listener error:', error);
+      return () => {};
+    }
+  }
+
+  // Sync subscription when auth state changes or on page load.
+  // Re-fetches the current FCM token — if it changed (browser rotated it,
+  // service worker was re-registered, etc.), saves the new token to Firestore
+  // and updates localStorage. Clears the subscribed state if the token is gone.
+  async syncSubscription() {
+    try {
+      const storage = this.manager.storage();
+      const storedNotification = storage.get('notifications');
+
+      const permission = typeof Notification !== 'undefined' ? Notification.permission : 'default';
+
+      syncLogger.log('Starting sync:', { storedSubscribed: storedNotification?.subscribed, storedToken: storedNotification?.token?.slice(-8), permission });
+
+      if (permission !== 'granted') {
+        if (storedNotification?.subscribed) {
+          syncLogger.log('Permission not granted — clearing localStorage');
+          storage.set('notifications', { subscribed: false, token: null });
+        } else {
+          syncLogger.log('Permission not granted and not subscribed — nothing to do');
+        }
+        return false;
+      }
+
+      // Permission is granted — check if there's a live token (covers localStorage cleared, new browser, etc.)
+      const currentToken = await this.getToken();
+
+      if (!currentToken) {
+        syncLogger.log('Token fetch returned null — clearing localStorage');
+        storage.set('notifications', { subscribed: false, token: null });
+        return false;
+      }
+
+      syncLogger.log('Token valid:', currentToken.slice(-8), storedNotification?.token ? (storedNotification.token.slice(-8) === currentToken.slice(-8) ? '(unchanged)' : `(CHANGED from ${storedNotification.token.slice(-8)})`) : '(recovered — localStorage was empty)');
+
+      await this._saveSubscription(currentToken);
+
+      const user = this.manager.auth().getUser();
+      storage.set('notifications', {
+        subscribed: true,
+        token: currentToken,
+        uid: user?.uid || null,
+        timestamp: new Date().toISOString(),
+      });
+
+      syncLogger.log('Sync complete — subscribed');
+      return true;
+    } catch (error) {
+      syncLogger.error('Sync error:', error);
+      return false;
+    }
+  }
+
+  // Save subscription to Firestore
+  async _saveSubscription(token) {
+    try {
+      const firestore = this.manager.firestore();
+      const user = this.manager.auth().getUser();
+      const storage = this.manager.storage();
+
+      if (!token) {
+        return;
+      }
+
+      const now = new Date();
+      const timestamp = now.toISOString();
+      const timestampUNIX = Math.floor(now.getTime() / 1000);
+
+      // Get context for client information
+      const context = this.manager.utilities().getContext();
+      const clientData = context.client;
+
+      // Reference to the notification document (ID is the token)
+      const notificationDoc = firestore.doc(`notifications/${token}`);
+
+      // Check if document already exists
+      const existingDoc = await notificationDoc.get();
+      const existingData = existingDoc.exists() ? existingDoc.data() : null;
+
+      // Determine if we need to update
+      const currentUid = user?.uid || null;
+      const existingOwner = existingData?.owner || null;
+      const needsUpdate = existingOwner !== currentUid;
+
+      // Create or update the document as needed
+      if (!existingData) {
+        // New subscription - create the document
+        await notificationDoc.set({
+          token,
+          owner: currentUid,
+          tags: ['general'],
+          attribution: storage.get('attribution', {}),
+          context: { client: clientData },
+          metadata: {
+            created: { timestamp, timestampUNIX },
+            updated: { timestamp, timestampUNIX },
+          },
+        });
+      } else if (needsUpdate) {
+        // Existing subscription needs update (userId changed)
+        // Use dot-notation to avoid overwriting metadata.created
+        await notificationDoc.update({
+          owner: currentUid,
+          context: { client: clientData },
+          'metadata.updated': { timestamp, timestampUNIX },
+        });
+      }
+      // If no update needed, do nothing
+
+    } catch (error) {
+      console.error('Save subscription error:', error);
+      // Don't throw - this is not critical for the subscription process
+    }
+  }
+}
+
+export default Notifications;

package/dist/modules/path-prefix.js

@@ -0,0 +1,22 @@
+/**
+ * The base path this page is mounted under (#355), read off the stamp the web
+ * build's HTML pass writes on `<html data-omega-path-prefix>`.
+ *
+ * Mirrors the web package's runtime helper (core/js/libs/path-prefix.js) rather
+ * than importing across the package boundary — nothing else is shared between
+ * the two runtimes today. One difference, deliberate: the domain root reads as
+ * '' here, so a caller concatenates without a special case.
+ */
+
+// '' (domain root) or '/workkit'-shaped, no trailing slash.
+export function pathPrefix() {
+  // Every absence means the same thing — a site at the domain root: no stamp,
+  // no document (a worker scope), or a surface whose DOM has no <html> yet.
+  const stamped = typeof document === 'undefined'
+    ? ''
+    : document.documentElement?.dataset?.omegaPathPrefix;
+
+  return stamped === '/' ? '' : (stamped || '');
+}
+
+export default pathPrefix;

package/dist/modules/request.js

@@ -0,0 +1,223 @@
+/**
+ * request — the harmonized API-fetch layer (successor to legacy UJM's authorizedFetch).
+ *
+ * One implementation for every surface: the browser singleton exposes it as
+ * `omega.request(url, options)`; desktop main and the extension service worker
+ * construct their own instance via `createRequest(deps)` with their framework's
+ * url/auth plumbing. Every response's `omega-properties` header (code, tag,
+ * usage current+limits, schema, additional — emitted by @omega.js/backend's
+ * assistant on every respond/errorify) is parsed automatically; contexts with
+ * bindings get server usage merged into the top-level `usage` bindings key.
+ *
+ * deps contract:
+ *   getApiUrl()          -> base API url (required for route-relative paths)
+ *   getIdToken(force)    -> fresh Firebase ID token, or null when signed out
+ *   onProperties(props)  -> optional; called with the parsed omega-properties object
+ *   onUnauthorized()     -> optional; called (never awaited) when an authenticated
+ *                           request comes back 401 (the session probe, #798)
+ *
+ * `wakeup: true` is the one option that changes the SHAPE of the call: it warms
+ * a cold backend and returns nothing (see the branch below).
+ */
+
+import { createLogger } from './logger.js';
+
+const logger = createLogger('request');
+
+
+const PROPERTIES_HEADER = 'omega-properties';
+
+// The route every wakeup aims at, on every surface. ONE home because a wakeup
+// never runs a route: @omega.js/backend's middleware answers it before it loads
+// one, so the path is a label rather than a destination, and every caller
+// naming "the route I am about to need" would be a dozen spellings of the same
+// warm function. `/omega/health` is the public, input-free liveness probe — the
+// one route whose name means exactly what this call does, and the only one that
+// would still be harmless if the short-circuit ever stopped short-circuiting
+// ([#644](https://github.com/Omega-JS-Stack/omega/issues/644)).
+const WAKEUP_ROUTE = '/omega/health';
+
+// Delay between retry attempts (options.tries)
+const RETRY_DELAY = 500;
+
+function createRequest(deps) {
+  if (typeof deps?.getApiUrl !== 'function' || typeof deps?.getIdToken !== 'function') {
+    throw new Error('createRequest requires getApiUrl and getIdToken deps');
+  }
+
+  return async function request(url, options = {}) {
+    // Route-relative paths resolve through the host's getApiUrl(); absolute urls pass through
+    const target = url.startsWith('/')
+      ? `${deps.getApiUrl()}${url}`
+      : url;
+
+    // A wakeup is a fire-and-forget ping that warms a cold backend, nothing
+    // more: @omega.js/backend's middleware sees `wakeup` in the request data
+    // and answers it BEFORE it loads a route or authenticates, so every route
+    // costs the same and none of them runs. Nothing is read back, no token is
+    // minted, and a dead network resolves like a live one — the caller is not
+    // waiting on an answer.
+    if (options.wakeup) {
+      fetch(withWakeupParam(target), { method: 'GET' }).catch(() => {});
+      return;
+    }
+
+    const headers = { ...(options.headers || {}) };
+
+    // Attach a fresh Bearer ID token unless the caller opted out (public routes)
+    if (options.auth !== false) {
+      const idToken = await Promise.resolve(deps.getIdToken(true)).catch(() => null);
+
+      if (idToken) {
+        headers['Authorization'] = `Bearer ${idToken}`;
+      } else {
+        logger.warn('No authenticated user — sending without Authorization. Did auth settle yet?');
+      }
+    }
+
+    // JSON-encode object bodies (strings/FormData/URLSearchParams pass through)
+    let body = options.body;
+    if (body && typeof body === 'object' && !isRawBody(body)) {
+      body = JSON.stringify(body);
+      if (!hasHeader(headers, 'content-type')) {
+        headers['Content-Type'] = 'application/json';
+      }
+    }
+
+    // Fetch with bounded retries (network errors + 5xx) and an optional
+    // per-attempt timeout — the wonderful-fetch semantics the legacy
+    // authorizedFetch callers relied on (tries, timeout).
+    const tries = Math.max(1, options.tries || 1);
+    let response;
+
+    for (let attempt = 1; ; attempt++) {
+      try {
+        response = await fetch(target, {
+          ...options,
+          // A body with no explicit method infers POST — fetch throws a
+          // TypeError on GET/HEAD carrying a body, so the GET default is
+          // never right there.
+          method: options.method || (options.body ? 'POST' : 'GET'),
+          headers,
+          body,
+          ...(options.timeout ? { signal: AbortSignal.timeout(options.timeout) } : {}),
+        });
+
+        if (response.status < 500 || attempt >= tries) {
+          break;
+        }
+      } catch (e) {
+        if (attempt >= tries) {
+          throw e;
+        }
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY));
+    }
+
+    // omega-properties rides EVERY assistant response (success and error)
+    const properties = parseProperties(response.headers.get(PROPERTIES_HEADER));
+    if (properties && deps.onProperties) {
+      deps.onProperties(properties);
+    }
+
+    const data = await parseBody(response);
+
+    if (!response.ok) {
+      // A 401 on an authenticated call is a moment of doubt
+      // ([#798](https://github.com/Omega-JS-Stack/omega/issues/798)): the
+      // backend refused this token, so ask the Auth server whether the session
+      // still exists at all. Never awaited and never fatal: the caller's error
+      // must not wait on a token refresh, and a probe that fails is not this
+      // request's failure.
+      if (options.auth !== false && response.status === 401) {
+        Promise.resolve(deps.onUnauthorized?.()).catch(() => {});
+      }
+
+      const message = (data && typeof data === 'object' && data.message)
+        || (typeof data === 'string' && data)
+        || `Request failed with status ${response.status}`;
+      const error = new Error(message);
+      error.code = response.status;
+      error.properties = properties;
+      error.data = data;
+      throw error;
+    }
+
+    if (options.output === 'complete') {
+      return { status: response.status, ok: response.ok, headers: response.headers, data, properties };
+    }
+
+    return data;
+  };
+}
+
+// Merge server usage (current counters + plan limits) from an omega-properties
+// payload into the top-level `usage` bindings key — the same key auth settle
+// seeds, so `data-omega-bind` elements refresh automatically after every request.
+// Shape per feature: { monthly, daily, ..., limit }.
+function mergeUsageIntoBindings(bindings, properties) {
+  const current = properties?.usage?.current;
+  if (!current || !Object.keys(current).length) {
+    return;
+  }
+
+  const limits = properties.usage.limits || {};
+  const existing = bindings.getContext().usage || {};
+  const usage = { ...existing };
+
+  for (const key of Object.keys(current)) {
+    usage[key] = {
+      ...existing[key],
+      ...current[key],
+      // A key the server reports usage for but omits from limits must not
+      // clobber the catalog-seeded limit from auth settle
+      limit: limits[key] ?? existing[key]?.limit ?? 0,
+    };
+  }
+
+  bindings.update({ usage });
+}
+
+function parseProperties(raw) {
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    logger.warn('Failed to parse omega-properties header:', e.message);
+    return null;
+  }
+}
+
+async function parseBody(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json().catch(() => null);
+  }
+
+  return response.text();
+}
+
+// The param rides the URL because a wakeup is a GET, and the middleware reads
+// it from the request data it merges the query string into.
+function withWakeupParam(url) {
+  return `${url}${url.includes('?') ? '&' : '?'}wakeup=true`;
+}
+
+function hasHeader(headers, name) {
+  return Object.keys(headers).some((key) => key.toLowerCase() === name);
+}
+
+function isRawBody(body) {
+  return (typeof FormData !== 'undefined' && body instanceof FormData)
+    || (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams)
+    || (typeof Blob !== 'undefined' && body instanceof Blob)
+    || (typeof ArrayBuffer !== 'undefined' && body instanceof ArrayBuffer);
+}
+
+export { createRequest, mergeUsageIntoBindings, WAKEUP_ROUTE };
+export default createRequest;