@omega.js/client 0.1.0

package/dist/vendor/monitoring/browser.js

@@ -0,0 +1,207 @@
+/**
+ * browser — the web-bundle entry (#380). @omega.js/client's sentry module is
+ * its only host, which puts one policy on every browser surface the client
+ * ships into (@omega.js/web pages and @omega.js/extension views alike).
+ *
+ * The doctrine this file enforces (Ian, 2026-08-20): client-side, ONLY errors
+ * from our own framework code report. A web page shares its global with
+ * everything — user-land inline scripts, ad and chat widgets, browser
+ * extensions injecting into the DOM — and none of that is ours to answer for.
+ * So the send gate is a stack-frame check against our bundle URLs, on top of
+ * the environment gates (development, Lighthouse, automated browsers) the
+ * client already ran.
+ *
+ * No `process` and no `require` of an SDK: this file is BUNDLED into a page.
+ * The host imports @sentry/browser itself (dynamically, to keep it out of the
+ * initial chunk) and passes the module in.
+ */
+
+const { DEFAULTS, normalizeUser, createBundleFilter } = require('./core.js');
+const { createLogger } = require('./logger.js');
+
+const logger = createLogger('browser');
+
+/** Lighthouse audits every error it can provoke — none of it is a real user's. */
+function isLighthouse() {
+  try {
+    return typeof navigator !== 'undefined' && navigator.userAgent?.includes('Lighthouse');
+  } catch (e) {
+    return false;
+  }
+}
+
+/** Selenium/Puppeteer/Playwright — an e2e run's errors are the run's, not production's. */
+function isAutomatedBrowser() {
+  try {
+    return typeof navigator !== 'undefined' && navigator.webdriver === true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * The url params that ARE a credential (#661): `?authPrivateKey` is a durable
+ * key and `?authCustomToken` signs in whoever holds it. A module constant, not
+ * config — a page cannot be allowed to opt its own credentials back into an
+ * event. Not exhaustive by design: only params the framework's own auth lanes
+ * put in an address bar.
+ */
+const SENSITIVE_AUTH_PARAMS = ['authPrivateKey', 'authCustomToken'];
+
+// Any absolute url parses against a base too, so ONE parse serves both shapes;
+// the host below only ever names it back out of a relative input.
+const SCRUB_BASE = 'https://scrub.invalid';
+
+/**
+ * Drop the credential params from a url string. The SDK reads the address bar
+ * in two places we cannot reach from a catch block — the navigation breadcrumb
+ * it records around `history.replaceState`, and the request url `httpContext`
+ * attaches at capture time — so the scrub belongs on this seam, once, rather
+ * than in every lane that handles a key.
+ *
+ * A url carrying none of them comes back untouched (never re-serialized), and a
+ * same-origin breadcrumb url stays relative, the way the SDK recorded it.
+ *
+ * @param {string} url - an absolute or root-relative url
+ * @returns {string} the url without the credential params
+ */
+function scrubAuthParams(url) {
+  if (typeof url !== 'string' || !SENSITIVE_AUTH_PARAMS.some((param) => url.includes(param))) {
+    return url;
+  }
+
+  let parsed;
+  let relative = false;
+
+  try {
+    parsed = new URL(url);
+  } catch (e) {
+    relative = true;
+  }
+
+  if (relative) {
+    try {
+      parsed = new URL(url, SCRUB_BASE);
+    } catch (e) {
+      // Not a url at all — better a param name in a breadcrumb than a mangled one.
+      return url;
+    }
+  }
+
+  SENSITIVE_AUTH_PARAMS.forEach((param) => parsed.searchParams.delete(param));
+
+  return relative ? `${parsed.pathname}${parsed.search}${parsed.hash}` : parsed.toString();
+}
+
+/**
+ * Build the @sentry/browser init options: integrations plus the one beforeSend
+ * that decides what leaves the page.
+ *
+ * @param {object} params
+ * @param {object} params.Sentry - the imported @sentry/browser module
+ * @param {object} [params.config] - the resolved Sentry settings for this surface
+ *   (the build maps `monitoring.providers.sentry` into the client's `sentry.config`)
+ * @param {string} [params.release] - the host's release tag (core.releaseTag)
+ * @param {string} [params.environment]
+ * @param {() => boolean} [params.isDevelopment] - the host's dev signal, read per event
+ * @param {() => object} [params.getUser] - the signed-in user, read per event
+ * @param {() => object} [params.getTags] - extra tags, read per event
+ * @returns {object} the options object to hand Sentry.init()
+ */
+function buildInitOptions(params) {
+  const { Sentry, release, environment, isDevelopment, getUser, getTags } = params || {};
+
+  const options = { ...DEFAULTS, ...((params && params.config) || {}) };
+
+  const isFrameworkEvent = createBundleFilter(options.bundlePatterns);
+
+  // Session-hours baseline: the page's own clock starts when reporting boots.
+  const startTime = Date.now();
+
+  const integrations = [];
+  if (typeof Sentry.browserTracingIntegration === 'function') {
+    integrations.push(Sentry.browserTracingIntegration());
+  }
+  // Replay costs bandwidth and captures the DOM — strictly opt-in via sample rates.
+  const hasReplays = (options.replaysSessionSampleRate > 0) || (options.replaysOnErrorSampleRate > 0);
+  if (hasReplays && typeof Sentry.replayIntegration === 'function') {
+    integrations.push(Sentry.replayIntegration({ maskAllText: false, blockAllMedia: false }));
+  }
+
+  return {
+    dsn:              options.dsn,
+    release,
+    environment:      environment || options.environment || 'production',
+    sampleRate:       options.sampleRate,
+    tracesSampleRate: options.tracesSampleRate,
+    ...(options.replaysSessionSampleRate > 0 ? { replaysSessionSampleRate: options.replaysSessionSampleRate } : {}),
+    ...(options.replaysOnErrorSampleRate > 0 ? { replaysOnErrorSampleRate: options.replaysOnErrorSampleRate } : {}),
+    integrations,
+
+    beforeBreadcrumb(breadcrumb) {
+      // The SDK patches history.replaceState, so the very call that STRIPS a key
+      // from the address bar records the pre-strip url as `data.from` — and the
+      // breadcrumb then rides with every later event on that page load (#661).
+      if (breadcrumb && breadcrumb.category === 'navigation' && breadcrumb.data) {
+        ['from', 'to'].forEach((key) => {
+          if (typeof breadcrumb.data[key] === 'string') {
+            breadcrumb.data[key] = scrubAuthParams(breadcrumb.data[key]);
+          }
+        });
+      }
+
+      return breadcrumb;
+    },
+
+    beforeSend(event, hint) {
+      // The console line lands FIRST, before any gate: a dropped event is still
+      // an error the developer wants to see in devtools.
+      logger.error('Caught error:', {
+        message: event.message || (event.exception?.values?.[0]?.value) || 'Unknown error',
+        level:   event.level,
+        hint,
+      });
+
+      if (isDevelopment && isDevelopment()) {
+        logger.log('Development mode — not sending');
+        return null;
+      }
+      if (isLighthouse()) {
+        logger.log('Lighthouse detected — not sending');
+        return null;
+      }
+      if (isAutomatedBrowser()) {
+        logger.log('Automated browser detected — not sending');
+        return null;
+      }
+      if (!isFrameworkEvent(event)) {
+        logger.log('Not from an @omega.js bundle — not sending');
+        return null;
+      }
+
+      event.tags = {
+        ...event.tags,
+        'process.type':        'browser',
+        'usage.session.hours': ((Date.now() - startTime) / (1000 * 3600)).toFixed(2),
+        ...(getTags ? getTags() : {}),
+      };
+
+      // The other half of the #661 scrub: httpContext attaches the address bar
+      // as the request url when the event is CAPTURED, key and all.
+      if (typeof event.request?.url === 'string') {
+        event.request.url = scrubAuthParams(event.request.url);
+      }
+
+      // PII: the uid is the join key to the account and rides; the email is
+      // scrubbed unless `monitoring.providers.sentry.scrubEmail: false` opts in.
+      const user = normalizeUser(getUser ? getUser() : null, options);
+      if (user) {
+        event.user = { ...event.user, ...user };
+      }
+
+      return event;
+    },
+  };
+}
+
+module.exports = { buildInitOptions, isLighthouse, isAutomatedBrowser, scrubAuthParams };

package/dist/vendor/monitoring/core.js

@@ -0,0 +1,180 @@
+/**
+ * core — the ONE place error-reporting policy lives (#380).
+ *
+ * Pure functions, zero runtime assumptions: no SDK, no `process`, no DOM. The
+ * browser bundle imports this file, so an env read here would be a
+ * ReferenceError on a web page (esbuild defines only the NODE_ENV key) — every
+ * environment signal is passed IN as a gate. `env.js` is the Node/Electron side
+ * of that seam.
+ *
+ * Policy it owns, once for every target:
+ *   - config resolution from omega.json5's `monitoring` role section — the
+ *     settings live under `monitoring.providers.sentry` (#425) and DSN presence
+ *     is the enable signal (no separate `enabled` flag — matches
+ *     @omega.js/backend convention: a config block's credentials are its switch)
+ *   - the release tag, from the host's own version identity
+ *   - user normalization with the email SCRUBBED BY DEFAULT (the uid stays —
+ *     it is the join key to the account, and it is not PII on its own)
+ *   - the client-side framework-bundle filter: browser events report ONLY when
+ *     they come from OUR bundles. User-land page scripts, browser extensions
+ *     injecting into the page, and cross-origin "Script error." noise never do.
+ *
+ * The SDK is never loaded from here. Nothing in this file can turn reporting
+ * ON either: it can only say whether a host SHOULD boot one.
+ */
+
+const DEFAULTS = {
+  dsn:              '',
+  environment:      null,   // null = the host's gate decides (production / development)
+  sampleRate:       1,      // error events kept, 0..1 — the sampling knob (Sentry-native)
+  tracesSampleRate: 0.1,
+  attachScreenshot: false,
+  scrubEmail:       true,   // PII off by default — set false to opt IN to emails
+  // Browser only: the URL fragments that identify OUR bundles. Both @omega.js/web
+  // and @omega.js/extension serve every framework bundle (the client runtime
+  // included) out of `/assets/js/`, so one default covers both surfaces.
+  bundlePatterns:   ['/assets/js/'],
+};
+
+// A resolved-but-off result. `options` still comes back so a caller can log what
+// it read.
+function disabled(options, reason) {
+  return { shouldEnable: false, options, reason };
+}
+
+/**
+ * The Sentry settings inside a `monitoring` role section (#425). The role level
+ * carries only `enabled`; every SDK-facing key hangs off the provider, so this
+ * is the one place that knows the nesting. `{ sentry: false }` (deliberately
+ * disabled) and a missing block both resolve to nothing — no dsn, no boot.
+ *
+ * @param {object} [section] - the `monitoring` config block (target-resolved)
+ * @returns {object} the provider's settings, or {} when there are none
+ */
+function providerOptions(section) {
+  const settings = section && section.providers && section.providers.sentry;
+  return settings && typeof settings === 'object' ? settings : {};
+}
+
+/**
+ * Resolve the runtime config and decide whether reporting should boot.
+ *
+ * Reads omega.json5's `monitoring` role section: the SDK-facing keys come from
+ * `monitoring.providers.sentry`, so the resolved options feed init directly.
+ *
+ * @param {object} section - the `monitoring` config block (target-resolved)
+ * @param {object} [gates] - the host's environment signals
+ * @param {boolean} [gates.killed] - a kill switch tripped (env var, test runner)
+ * @param {string} [gates.killedReason] - what tripped it, for the log line
+ * @param {boolean} [gates.isProduction] - this run ships telemetry
+ * @param {boolean} [gates.allowInDev] - report anyway outside production
+ * @returns {{ shouldEnable: boolean, options: object, reason: string|null }}
+ */
+function resolveConfig(section, gates) {
+  gates = gates || {};
+
+  const options = { ...DEFAULTS, ...providerOptions(section) };
+
+  if (gates.killed) {
+    return disabled(options, gates.killedReason || 'disabled by the host');
+  }
+  if (!options.dsn) {
+    return disabled(options, 'no dsn set');
+  }
+  if (!gates.isProduction && !gates.allowInDev) {
+    return disabled(options, 'not a production run (set OMEGA_SENTRY_FORCE=true to override)');
+  }
+
+  if (!options.environment) {
+    options.environment = gates.isProduction ? 'production' : 'development';
+  }
+
+  return { shouldEnable: true, options, reason: null };
+}
+
+/**
+ * Normalize a @omega.js/client / firebase / admin user into the minimal shape
+ * the SDK wants. The email is PII: it rides ONLY when the host explicitly opts
+ * in with `monitoring.providers.sentry.scrubEmail: false`.
+ *
+ * @param {object} user - a user-ish object carrying uid/id and maybe email
+ * @param {object} [options] - the resolved monitoring options
+ * @returns {object|null} { id, email? } — null when there is nothing safe to send
+ */
+function normalizeUser(user, options) {
+  if (!user) return null;
+
+  const scrubEmail = (options || {}).scrubEmail !== false;
+  const out = {};
+
+  if (user.uid)     out.id = user.uid;
+  else if (user.id) out.id = user.id;
+  if (user.email && !scrubEmail) out.email = user.email;
+
+  return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * Build the release tag from the host's own version identity. ONE format on
+ * every target (Ian, 2026-08-20): `<brand.id>@<version>` — a Sentry release is
+ * comparable across the backend, the desktop app and the browser bundles only
+ * when they spell it the same way. The brand id is required config, so a tag
+ * missing one is a config hole, not a second format: no id, no tag.
+ *
+ * The version is the host's own — @omega.js/backend's functions package
+ * version, @omega.js/desktop's app version, the browser blob's app version.
+ *
+ * @param {object} identity - { id, version }
+ * @returns {string|undefined} the tag, or undefined when either half is missing
+ */
+function releaseTag(identity) {
+  const { id, version } = identity || {};
+  if (!id || !version) return undefined;
+  return `${id}@${version}`;
+}
+
+/**
+ * Every stack-frame filename an event carries (exception frames first, then the
+ * threads a hung-renderer report uses).
+ */
+function eventFrameFilenames(event) {
+  const values = [
+    ...((event && event.exception && event.exception.values) || []),
+    ...((event && event.threads && event.threads.values) || []),
+  ];
+
+  return values.flatMap((value) => ((value.stacktrace && value.stacktrace.frames) || [])
+    .map((frame) => frame.filename || frame.abs_path || '')
+    .filter(Boolean));
+}
+
+/**
+ * The client-side doctrine gate (#380): a browser event reports ONLY when our
+ * own framework code is on its stack.
+ *
+ * An event with no matching frame is DROPPED, and that includes an event with no
+ * frames at all — a cross-origin `Script error.` is exactly the third-party noise
+ * this exists to kill. Deliberate `omega.sentry().captureException(...)` calls
+ * are unaffected: they are thrown from page bundles, which ARE our bundles.
+ *
+ * @param {string[]} [patterns] - URL fragments identifying our bundles
+ * @returns {(event: object) => boolean} true when the event may report
+ */
+function createBundleFilter(patterns) {
+  const fragments = (patterns || DEFAULTS.bundlePatterns).filter(Boolean);
+
+  return function isFrameworkEvent(event) {
+    const filenames = eventFrameFilenames(event);
+    return filenames.some((filename) => fragments.some((fragment) => filename.includes(fragment)));
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  providerOptions,
+  resolveConfig,
+  normalizeUser,
+  releaseTag,
+  eventFrameFilenames,
+  createBundleFilter,
+};

package/dist/vendor/monitoring/logger.js

@@ -0,0 +1,39 @@
+/**
+ * The monitoring package's log tag — the ONE identity tag every OMEGA surface
+ * prints: `[@omega.js/monitoring:<module>]` ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+ *
+ * The twin of @omega.js/analytics' createLogger, emitting this package's
+ * segment: no timestamp, because devtools, Cloud Logging and electron-log all
+ * stamp their own lines.
+ *
+ * CJS like the rest of the package: the backend and the electron main process
+ * require() it, the browser bundles import it with standard interop.
+ */
+
+// The package segment — this file IS @omega.js/monitoring, so it is a literal.
+const PACKAGE = '@omega.js/monitoring';
+
+/**
+ * Create a tagged console for one module, e.g. createLogger('core').
+ * @param {string} module - The module identity segment.
+ * @returns {object} A console-shaped logger whose calls carry the tag.
+ */
+function createLogger(module) {
+  const tag = `[${PACKAGE}:${module}]`;
+
+  // GETTERS returning a BOUND console method, not wrapper arrows: devtools
+  // attributes a line to the frame that called console, so a wrapper would make
+  // every line read as coming from this file. Resolution stays at ACCESS time,
+  // so a test (or a consumer) that swaps console[method] still sees its own stub.
+  const logger = { tag };
+  for (const method of ['log', 'info', 'warn', 'error', 'debug']) {
+    Object.defineProperty(logger, method, {
+      get: () => console[method].bind(console, tag),
+      enumerable: true,
+    });
+  }
+
+  return logger;
+}
+
+module.exports = { createLogger };

package/docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+## Singleton Pattern
+
+The library exports a singleton `Manager` instance. Import it directly from any file — it's always the same initialized instance:
+
+```javascript
+import omega from '@omega.js/client';
+
+// Same instance everywhere — config, auth, firestore, all ready
+omega.auth().listen((state) => { ... });
+omega.utilities().escapeHTML(untrustedText);
+omega.config.environment; // 'development' or 'production'
+```
+
+**Do NOT create new instances** (`new Manager()`). @omega.js/web, @omega.js/extension, and @omega.js/desktop initialize the singleton — every import gets that same object. Do NOT pass `omega` through function params or store it in module-level variables — just import it.
+
+## Directory Structure
+
+```
+@omega.js/client/
+├── src/                       # Source code (ES6+)
+│   ├── index.js               # Manager class, initialization, Firebase setup
+│   └── modules/               # Feature modules
+│       ├── auth.js            # Firebase Auth wrapper
+│       ├── bindings.js        # Reactive DOM data binding
+│       ├── dom.js             # loadScript, ready utilities
+│       ├── firestore.js       # Firestore wrapper with chainable queries
+│       ├── notifications.js   # FCM push notifications
+│       ├── sentry.js          # Error tracking integration
+│       ├── service-worker.js  # SW registration and messaging
+│       ├── storage.js         # localStorage/sessionStorage wrapper
+│       └── utilities.js       # Helper functions (clipboard, escape, etc.)
+├── dist/                      # Transpiled ES5 output (generated)
+├── _legacy/                   # Old implementation (reference only, DO NOT MODIFY)
+└── test/                      # Mocha tests
+```
+
+## Module Dependencies
+
+```
+Manager (index.js)
+├── Storage (standalone, no deps)
+├── Auth → Manager, Bindings, Storage, Firestore
+├── Bindings → Manager
+├── Firestore → Manager (lazy Firebase import)
+├── Notifications → Manager, Storage, Firestore
+├── ServiceWorker → Manager
+├── Sentry → Manager (dynamic import)
+├── DOM utilities (standalone)
+└── Utilities (standalone)
+```
+
+## Firebase Initialization
+
+`initialize(config)` boots Firebase only when a usable web SDK config resolves:
+
+- `_resolveFirebaseConfig()` checks `cloud.config` first (the omega.json5 role shape — desktop passes its resolved config through), then the nested `firebase.app.config` (the web/extension bridge contract shape). A blob only counts when **at least one value is non-empty** — framework config merges (e.g. UJM's Jekyll chain) inject all-empty-string blobs into Firebase-less sites, and those resolve to `null` (no init, no URL derivation).
+- Initialization additionally requires a **non-empty `apiKey`** — the SDK cannot boot without one (it crashes the page with `auth/invalid-api-key`). Configs carrying only `projectId` still resolve so `getFunctionsUrl()` can derive its URL (`getApiUrl()` derives from `brand.url`, not the Firebase blob), but Firebase itself stays uninitialized and the console logs `[Firebase] Skipped: config has no apiKey ...` (same idiom as `[Analytics] Skipped:`).