@omega.js/desktop 0.1.0

package/dist/lib/analytics.js

@@ -0,0 +1,360 @@
+// Analytics — GA4 via Measurement Protocol. Mirrors @omega.js/backend's
+// `Manager.config.analytics.providers.google.id` shape so the same person can be
+// tracked across desktop (@omega.js/desktop) + web (UJM/@omega.js/client) + backend (@omega.js/backend) by
+// referencing a single namespaced UUIDv5 identity.
+//
+// Cross-platform identity (the key feature):
+//   client_id = uuidv5(deviceId, namespace)    // anonymous-but-stable per install
+//   user_id   = uuidv5(firebaseUid, namespace) // same human across all surfaces
+//
+// The HUMAN is what crosses surfaces, never the machine: this app's deviceId comes
+// from desktop's own storage and a browser's comes from its localStorage, so one
+// machine is two client_ids and always was (#396). The derivation is shared
+// (@omega.js/analytics' `deriveDeviceId`), the storage it reads is not. user_id
+// rides ALONGSIDE the client_id in every payload — it never replaces it, because
+// GA stitches sessions by client_id.
+//
+// `namespace` is the consumer's `cloud.config.projectId` re-encoded as a UUIDv5
+// namespace via uuidv5.URL of the projectId string. Same projectId in @omega.js/backend/@omega.js/client/@omega.js/desktop
+// → the same uid hashes to the same user_id everywhere → unified analytics.
+//
+// Anonymous (client-bridge hasn't reported auth yet) → user_id stays null.
+// Authed (auth event fires) → user_id is set + a `login` event is dispatched. On
+// logout → user_id clears + `logout` event fires.
+//
+// API surface:
+//   manager.analytics.event(name, params?)         // generic event
+//   manager.analytics.pageview(path?)              // convenience wrapper
+//   manager.analytics.screenview(name?)            // convenience wrapper
+//   manager.analytics.setUserId(uid)               // manual override; auto-wired to omega
+//   manager.analytics.setUserProperties(props)     // merge into user_properties block
+//
+// Events fired during normal operation are queued until init completes (we need
+// context.session + measurement_id + secret). Once initialized, the queue
+// flushes and subsequent calls send immediately.
+//
+// Config:
+//   analytics: {
+//     enabled: true,                                   // default true
+//     providers: {
+//       google: {
+//         id: 'G-XXXXXXXXXX',                          // Measurement ID (REQUIRED)
+//       },
+//     },
+//   }
+//
+// Secret comes from `process.env.GOOGLE_ANALYTICS_SECRET` (matches @omega.js/backend). The bundle
+// task's esbuild `define` injects it at build time so packaged apps don't need .env at runtime.
+// Without the secret, the module logs a warning + becomes a no-op.
+
+const LoggerLite = require('./logger-lite.js');
+const fetch      = require('wonderful-fetch');
+// The MP semantics live in ONE place — @omega.js/analytics' core
+// (C4 cp106b): identity math, payload + URL shape are shared with the browser
+// engine and can never drift again.
+const core = require('../vendor/analytics/core.js');
+// And so does WHAT an event is called: the shared catalog and its adapters
+// decide the native name and payload for every surface
+// ([#328](https://github.com/Omega-JS-Stack/omega/issues/328)). This module
+// keeps only what is genuinely desktop's — the Measurement Protocol transport,
+// the pre-init queue, and the IPC bridge.
+const analytics_ = require('../vendor/analytics/index.js');
+
+const logger = new LoggerLite('analytics');
+
+const FETCH_TIMEOUT_MS = 30 * 1000;
+const MAX_QUEUE = 200;
+
+const analytics = {
+  _initialized:  false,
+  _manager:      null,
+  _enabled:      false,
+  _measurementId: null,
+  _apiSecret:    null,
+  _namespace:    null,
+  _clientId:     null,    // uuidv5(deviceId, namespace) — set on init
+  _userId:       null,    // uuidv5(firebaseUid, namespace) — set on auth
+  _userProperties: {},
+  _queue:        [],
+  _authUnsub:    null,
+
+  initialize(manager) {
+    if (analytics._initialized) return;
+    analytics._initialized = true;
+    analytics._manager = manager;
+
+    const cfg = manager.config.analytics || {};
+
+    // Presence-driven: providers.google.id presence enables analytics. No separate
+    // `enabled` flag (matches @omega.js/backend convention — credentials are the enable signal).
+    analytics._measurementId = cfg.providers?.google?.id || null;
+    // Secret comes from env. In packaged builds, the bundle task's esbuild `define`
+    // replaces `process.env.GOOGLE_ANALYTICS_SECRET` with the build-time literal so the
+    // packaged app has it baked in without shipping .env.
+    analytics._apiSecret = process.env.GOOGLE_ANALYTICS_SECRET || null;
+
+    if (!analytics._measurementId) {
+      logger.log('analytics: no measurement ID set (config.analytics.providers.google.id) — disabled.');
+      analytics._enabled = false;
+      return;
+    }
+    if (!analytics._apiSecret) {
+      logger.warn('analytics: GOOGLE_ANALYTICS_SECRET env var not set — disabled. (Set in .env for dev; the bundle task bakes it in at build time for packaged apps.)');
+      analytics._enabled = false;
+      return;
+    }
+    analytics._enabled = true;
+
+    // Namespace = uuidv5 of the firebase project ID (or app id as fallback). Same
+    // projectId in @omega.js/backend/@omega.js/client/@omega.js/desktop → same namespace → same per-uid UUIDv5
+    // everywhere. UUIDv5 needs a UUID-shaped namespace — we derive one from the
+    // string projectId by hashing it into uuidv5.URL space (RFC 4122).
+    const projectId = manager.config.cloud?.config?.projectId
+      || manager.config.brand.id;
+    analytics._namespace = core.deriveNamespace(projectId);
+
+    // Apply a uid stored by a pre-init setUserId() call — the auth
+    // subscription below still overrides it when auth resolves.
+    if (analytics._pendingUid) {
+      analytics.setUserId(analytics._pendingUid);
+      analytics._pendingUid = null;
+    }
+
+    // client_id = the PERSISTED per-install device id. context.session.deviceId is
+    // async-resolved and context.initialize() runs before this in the boot sequence,
+    // so an empty one is a broken boot order, never a runtime condition — and a
+    // fresh id minted here would persist nowhere, making every launch a new GA
+    // client (#396). It raises instead.
+    const deviceId = manager.context.session.deviceId;
+
+    if (!deviceId) {
+      throw new Error('analytics.initialize() ran before context.initialize() resolved session.deviceId — the boot sequence must init context first');
+    }
+
+    analytics._clientId = core.deriveClientId(deviceId, analytics._namespace);
+
+    // The facade's seams for THIS process. The transport is the Measurement
+    // Protocol below — Meta's and TikTok's pixels do not exist in a main
+    // process, so their descriptors report blocked and the fire log says so.
+    // Environment mirrors the app's own dev flag: an unknown event name throws
+    // in development, where a typo is a bug, and is logged-and-skipped in a
+    // packaged app, where throwing would take the user's action with it.
+    analytics_.configure({
+      transport: { send: (descriptor) => analytics._send(descriptor) },
+      context: { runtime: 'electron' },
+      environment: manager.isDevelopment?.() ? 'development' : 'production',
+    });
+
+    // Wire auth subscription so user_id flips automatically on login/logout.
+    analytics._authUnsub = manager.omega.onAuthChange((snap) => {
+      analytics._handleAuthChange(snap);
+    });
+    // Pull current state immediately in case auth already resolved.
+    const current = manager.omega.getCurrentUser();
+    if (current?.uid) analytics._handleAuthChange(current);
+
+    // Compute initial user_properties from context + usage.
+    analytics._userProperties = analytics._buildUserProperties();
+
+    logger.log(`analytics initialized — measurement=${analytics._measurementId} client_id=${analytics._clientId.slice(0, 8)}…`);
+
+    // Flush any queued events.
+    if (analytics._queue.length > 0) {
+      logger.log(`analytics: flushing ${analytics._queue.length} queued event(s).`);
+      const queued = analytics._queue.slice();
+      analytics._queue = [];
+      for (const item of queued) analytics.event(item.name, item.params);
+    }
+
+    // Auto-emit app_launch from the main process — the one launch event for the
+    // whole app. A renderer emits nothing of its own on init: it forwards the
+    // events its own code fires through the IPC bridge below, and this sender
+    // is what delivers them ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)).
+    if (analytics._isMain()) {
+      analytics.event('app_launch');
+    }
+
+    // IPC: renderer → main analytics calls. Forward fires-and-forgets via send;
+    // status query via invoke.
+    manager.ipc.unhandle('desktop:analytics:status');
+    manager.ipc.handle('desktop:analytics:status', () => analytics.toJSON());
+    // Use Set-deduped listener; named handler so re-init collapses duplicates.
+    manager.ipc.on('desktop:analytics:event',               analytics._onIpcEvent);
+    manager.ipc.on('desktop:analytics:set-user-properties', analytics._onIpcSetProps);
+  },
+
+  _onIpcEvent({ name, params } = {}) {
+    if (!name) return;
+    analytics.event(name, params);
+  },
+
+  _onIpcSetProps(props) {
+    analytics.setUserProperties(props);
+  },
+
+  // ─── Public API ─────────────────────────────────────────────────────────────
+
+  // Fire a CANONICAL event (a catalog name). Queues if not initialized yet.
+  event(name, params) {
+    if (!analytics._enabled || !analytics._measurementId) {
+      // Queue while we're still booting (init may flip _enabled later).
+      if (!analytics._initialized) {
+        if (analytics._queue.length < MAX_QUEUE) {
+          analytics._queue.push({ name, params });
+        }
+      }
+      return;
+    }
+
+    // The catalog resolves the name and the payload; the transport below is
+    // handed the result. Nothing about a provider's dialect lives here.
+    analytics_.event(name, analytics._enrichParams(params || {}));
+  },
+
+  // The Measurement Protocol transport: one resolved descriptor → one POST.
+  _send(descriptor) {
+    if (descriptor.provider !== 'ga4') {
+      return false;
+    }
+
+    const payload = core.buildPayload({
+      clientId:       analytics._clientId,
+      userId:         analytics._userId,
+      userProperties: analytics._userProperties,
+      eventName:      descriptor.name,
+      params:         descriptor.payload,
+    });
+
+    const url = core.buildCollectUrl(analytics._measurementId, analytics._apiSecret);
+
+    fetch(url, {
+      method:   'post',
+      response: 'text',
+      tries:    2,
+      timeout:  FETCH_TIMEOUT_MS,
+      body:     payload,
+    }).catch((e) => {
+      logger.warn(`event "${descriptor.name}" failed: ${e.message}`);
+    });
+
+    return true;
+  },
+
+  pageview(path) {
+    analytics.event('page_view', path ? { page_path: path } : {});
+  },
+
+  screenview(name) {
+    analytics.event('screen_view', name ? { screen_name: name } : {});
+  },
+
+  // Manual user-id override. Normally client-bridge wires this automatically.
+  setUserId(uid) {
+    if (!analytics._namespace) {
+      // Init hasn't run yet — store and apply at init.
+      analytics._pendingUid = uid || null;
+      return;
+    }
+    analytics._userId = core.deriveUserId(uid, analytics._namespace);
+  },
+
+  // Merge into the user_properties block sent on every subsequent event.
+  setUserProperties(props) {
+    if (!props || typeof props !== 'object') return;
+    analytics._userProperties = { ...analytics._userProperties, ...core.wrapUserProperties(props) };
+  },
+
+  // ─── Internals ──────────────────────────────────────────────────────────────
+
+  _isMain() {
+    return process.type === 'browser' || process.type === undefined;   // undefined in tests
+  },
+
+  // GA4 param contract: each event needs engagement_time_msec (else session bounces),
+  // and we add session_id + page_location so reports group properly.
+  _enrichParams(params) {
+    const m = analytics._manager;
+    const ctx = m.context;
+    const sessionStart = ctx.session.startTime ? new Date(ctx.session.startTime).getTime() : Date.now();
+    const engagement   = Math.max(1, Date.now() - sessionStart);
+    return {
+      session_id:           ctx.session.id || 'unknown',
+      engagement_time_msec: engagement,
+      page_location:        params.page_location || `app://${m.config.brand.id}`,
+      page_title:           params.page_title || m.config.app?.productName || m.config.brand.name,
+      ...params,
+    };
+  },
+
+  // Compute user-properties from current context + usage. Re-run on auth change.
+  _buildUserProperties() {
+    const m = analytics._manager;
+    const ctx = m.context;
+    const usage = m.usage;
+    const wrap = (v) => ({ value: v });
+    const out = {
+      app_version:      wrap(ctx.app.version || 'unknown'),
+      operating_system: wrap(ctx.client.platform || 'unknown'),
+      device_category:  wrap(ctx.client.mobile ? 'mobile' : 'desktop'),
+      country:          wrap(ctx.geolocation.country || 'None'),
+      language:         wrap(ctx.client.locale || 'None'),
+      authenticated:    wrap(!!analytics._userId),
+    };
+    out.app_opens       = wrap(usage.opens());
+    out.app_hours_total = wrap(Math.round((usage.hoursTotal() || 0) * 100) / 100);
+    return out;
+  },
+
+  // Auth bridge wiring — fires login/logout events on transition.
+  _handleAuthChange(snap) {
+    const newUid = snap?.uid || null;
+    const prevUid = analytics._userId
+      ? 'set'   // we don't reverse the uuidv5; just need to know whether one was set
+      : null;
+
+    if (newUid) {
+      const previousAuthed = analytics._userId !== null;
+      analytics.setUserId(newUid);
+      analytics._userProperties = analytics._buildUserProperties();
+      if (!previousAuthed) {
+        analytics.event('login', { method: snap?.providerId || 'unknown' });
+      }
+    } else if (prevUid) {
+      analytics.event('logout');
+      analytics._userId = null;
+      analytics._userProperties = analytics._buildUserProperties();
+    }
+  },
+
+  // Plain-JSON snapshot for IPC inspection.
+  toJSON() {
+    return {
+      enabled:        analytics._enabled,
+      measurementId:  analytics._measurementId,
+      clientId:       analytics._clientId,
+      userId:         analytics._userId,
+      queueLength:    analytics._queue.length,
+    };
+  },
+
+  // Test teardown.
+  shutdown() {
+    if (typeof analytics._authUnsub === 'function') {
+      analytics._authUnsub();
+    }
+    analytics._initialized   = false;
+    analytics._manager       = null;
+    analytics._enabled       = false;
+    analytics._measurementId = null;
+    analytics._apiSecret     = null;
+    analytics._namespace     = null;
+    analytics._clientId      = null;
+    analytics._userId        = null;
+    analytics._userProperties = {};
+    analytics._queue         = [];
+    analytics._authUnsub     = null;
+    analytics._pendingUid    = null;
+  },
+};
+
+module.exports = analytics;

package/dist/lib/app-state.js

@@ -0,0 +1,220 @@
+// App state — first-launch / launch-count / crash-sentinel / startup-context flags.
+//
+// Storage shape (under storage key `appState`):
+//   {
+//     installedAt:    1700000000000,    // first time the app booted (ms epoch)
+//     launchCount:    42,
+//     lastLaunchAt:   1700000000000,    // previous launch timestamp (set BEFORE this launch increments)
+//     lastQuitAt:     1700000000000,    // last graceful quit; null/missing if previous launch crashed
+//     version:        '1.2.3',          // version of THIS launch
+//     previousVersion: '1.2.2',         // version before this launch, if it changed
+//     sentinel:       true,             // set on launch, cleared on graceful quit; survival = crash
+//   }
+//
+// Public API on `manager.appState`:
+//   isFirstLaunch()        — true only for the very first boot of the app on this machine
+//   getLaunchCount()       — total successful launches (including this one)
+//   getInstalledAt()       — Date of first launch
+//   getLastLaunchAt()      — Date of the previous launch, or null
+//   getLastQuitAt()        — Date of the last graceful quit, or null if it crashed
+//   recoveredFromCrash()   — true if the previous launch did not exit cleanly
+//   getVersion()           — package.json version of this launch
+//   getPreviousVersion()   — version before this launch (if it changed), else null
+//   wasUpgraded()          — true if version differs from previousVersion
+//   launchedAtLogin()      — true if OS launched the app via openAtLogin (mac/win)
+//   launchedFromDeepLink() — set later by lib/deep-link if argv had a deep-link payload
+//
+// Side effects on initialize():
+//   - increments launchCount
+//   - migrates lastLaunchAt → previous launch timestamp
+//   - records previousVersion if version changed
+//   - writes the crash sentinel
+//   - registers app-quit listeners that clear the sentinel + write lastQuitAt
+
+const LoggerLite = require('./logger-lite.js');
+
+const logger = new LoggerLite('app-state');
+
+const STORAGE_KEY = 'appState';
+
+const appState = {
+  _initialized:        false,
+  _quitWired:          false,
+  _manager:            null,
+  _electron:           null,
+
+  // Cached snapshot of the state AS LOADED at the start of this launch.
+  // (Mutators write through to storage; readers can use either source.)
+  _snapshot: null,
+
+  // Specifically: the previous-run sentinel value, captured BEFORE we overwrite it.
+  // True = previous launch never wrote `lastQuitAt` → it crashed.
+  _recoveredFromCrash: false,
+
+  // Set by lib/deep-link.initialize when argv contains a deep-link payload.
+  _launchedFromDeepLink: false,
+
+  async initialize(manager) {
+    if (appState._initialized) {
+      return;
+    }
+
+    appState._manager = manager;
+    appState._electron = require('electron');
+
+    const storage = manager.storage;
+
+    const now = Date.now();
+    const previous = storage.get(STORAGE_KEY) || {};
+    const isFirstLaunch = !previous.installedAt;
+
+    // Crash detection: previous launch wrote sentinel=true but never cleared it via lastQuitAt.
+    // First launch has no previous sentinel, so it can't be "recovered from crash."
+    const previousSentinel = !!previous.sentinel;
+    const previousQuitAt   = previous.lastQuitAt || null;
+    appState._recoveredFromCrash = !isFirstLaunch && previousSentinel && !previousQuitAt;
+
+    // Version detection. Prefer the cross-context manager.getVersion() helper —
+    // it tries `app.getVersion()` first (authoritative in main, reads asar
+    // package.json in packaged builds) and falls back to project package.json.
+    const currentVersion  = manager.config.app?.version
+                         || manager.getVersion()
+                         || tryGetVersionFromPackage()
+                         || null;
+    const previousVersion = previous.version || null;
+    const versionChanged  = currentVersion && previousVersion && currentVersion !== previousVersion;
+
+    // Build the next snapshot.
+    const next = {
+      installedAt:     previous.installedAt || now,
+      launchCount:     (previous.launchCount || 0) + 1,
+      lastLaunchAt:    now,
+      lastQuitAt:      null,                                          // cleared; will be set on quit
+      version:         currentVersion,
+      previousVersion: versionChanged ? previousVersion : (previous.previousVersion || null),
+      sentinel:        true,                                          // crash-sentinel for THIS launch
+    };
+
+    storage.set(STORAGE_KEY, next);
+    appState._snapshot = {
+      ...next,
+      _previousLaunchAt: previous.lastLaunchAt || null,                // exposed via getLastLaunchAt()
+      _isFirstLaunch:    isFirstLaunch,
+      _wasUpgraded:      Boolean(versionChanged),                      // true only if THIS launch differs from prior
+    };
+
+    // Wire graceful-quit cleanup. We listen to both `before-quit` and `will-quit`
+    // so a quick `app.quit()` from the main process is captured even if the
+    // window-close path didn't fire. Either firing clears the sentinel.
+    appState._wireGracefulQuit();
+
+    logger.log(`initialize — firstLaunch=${isFirstLaunch} count=${next.launchCount} version=${currentVersion || '(unknown)'} recoveredFromCrash=${appState._recoveredFromCrash}`);
+
+    appState._initialized = true;
+  },
+
+  _wireGracefulQuit() {
+    if (appState._quitWired) return;
+    appState._quitWired = true;
+    const { app } = appState._electron;
+
+    let cleared = false;
+    const onQuit = () => {
+      if (cleared) return;
+      cleared = true;
+      const storage = appState._manager.storage;
+      const cur = storage.get(STORAGE_KEY) || {};
+      cur.sentinel  = false;
+      cur.lastQuitAt = Date.now();
+      storage.set(STORAGE_KEY, cur);
+    };
+
+    app.on('before-quit', onQuit);
+    app.on('will-quit',   onQuit);
+  },
+
+  // Public API ─────────────────────────────────────────────────────────────────
+
+  isFirstLaunch() {
+    return Boolean(appState._snapshot?._isFirstLaunch);
+  },
+
+  getLaunchCount() {
+    return appState._snapshot?.launchCount || 0;
+  },
+
+  getInstalledAt() {
+    const ms = appState._snapshot?.installedAt;
+    return ms ? new Date(ms) : null;
+  },
+
+  getLastLaunchAt() {
+    const ms = appState._snapshot?._previousLaunchAt;
+    return ms ? new Date(ms) : null;
+  },
+
+  getLastQuitAt() {
+    // The CURRENT snapshot's lastQuitAt is null (we cleared it on init).
+    // What the consumer wants is "when did we previously quit gracefully" — read storage live,
+    // because at the moment of the call this launch hasn't quit yet.
+    const cur = appState._manager.storage.get(STORAGE_KEY) || {};
+    const ms  = cur.lastQuitAt;
+    return ms ? new Date(ms) : null;
+  },
+
+  recoveredFromCrash() {
+    return Boolean(appState._recoveredFromCrash);
+  },
+
+  getVersion() {
+    return appState._snapshot?.version || null;
+  },
+
+  getPreviousVersion() {
+    return appState._snapshot?.previousVersion || null;
+  },
+
+  wasUpgraded() {
+    return Boolean(appState._snapshot?._wasUpgraded);
+  },
+
+  launchedAtLogin() {
+    // `getLoginItemSettings` exists on macOS + Windows; on Linux it just returns
+    // a stub object with openAtLogin=false. So the field check below is safe
+    // everywhere — no platform branch needed.
+    const s = appState._electron.app.getLoginItemSettings();
+    // Electron exposes `wasOpenedAtLogin` on macOS (via NSWorkspace) and
+    // `openAtLogin` plus a `launchItems` array on Windows. The shorthand:
+    // if the OS booted us via the login-item path, the field is true.
+    return Boolean(s.wasOpenedAtLogin);
+  },
+
+  launchedFromDeepLink() {
+    return appState._launchedFromDeepLink;
+  },
+
+  // Hook for lib/deep-link to call when it parses a cold-start deep link from argv.
+  setLaunchedFromDeepLink(value) {
+    appState._launchedFromDeepLink = Boolean(value);
+  },
+
+  // Test helper — wipe persisted state and reset the in-memory snapshot.
+  // (Public, intentionally — used by integration tests + by consumers who want a "reset to factory" command.)
+  reset() {
+    appState._manager.storage.delete(STORAGE_KEY);
+    appState._snapshot = null;
+    appState._recoveredFromCrash = false;
+    appState._launchedFromDeepLink = false;
+  },
+};
+
+function tryGetVersionFromPackage() {
+  // Last-resort fallback used only when manager.getVersion() is unavailable.
+  // Reads via build.js's getPackage helper which already handles "no package.json
+  // at projectRoot" by returning null — no try/catch needed.
+  const Manager = require('../build.js');
+  const pkg = Manager.getPackage('project');
+  return pkg?.version || null;
+}
+
+module.exports = appState;