feat(analytics): PostHog server-side SDK + analytics service (#3299)

* feat(analytics): add PostHog server-side SDK + analytics service

Add a new analytics module wrapping posthog-node with a no-op fallback
when PostHog is not configured, so downstream projects are unaffected.

Closes #3294

* fix(analytics): lazy-load posthog-node SDK via dynamic import

Addresses Copilot review: posthog-node declares engine >=22.22.0 but
this repo allows >=22.0.0.  By lazy-importing posthog-node inside
init() only when an API key is configured, unconfigured deployments
never load the SDK — eliminating engine mismatch warnings and startup
risk on older Node 22 patch versions.

- analytics.service.js: init() is now async, uses dynamic import()
- analytics.init.js: awaits AnalyticsService.init()
- express.js: awaits module init functions (initModulesConfiguration)
- All test files updated to await init()

Author: PierreBrisorgueil

.env.example

@@ -8,3 +8,9 @@ DEVKIT_NODE_stripe_prices_starter_monthly=price_xxx
 DEVKIT_NODE_stripe_prices_starter_annual=price_xxx
 DEVKIT_NODE_stripe_prices_pro_monthly=price_xxx
 DEVKIT_NODE_stripe_prices_pro_annual=price_xxx
+
+# PostHog Analytics
+# Get your keys from https://us.posthog.com/settings/project-api-key
+DEVKIT_NODE_posthog_apiKey=phc_xxx
+DEVKIT_NODE_posthog_host=https://us.i.posthog.com
+DEVKIT_NODE_posthog_personalApiKey=phx_xxx

jest.config.js

@@ -41,6 +41,8 @@ export default {
     '!<rootDir>/modules/auth/strategies/clerk/**',
     // Exclude passport init glue — just serializeUser/deserializeUser + strategy loader
     '!<rootDir>/modules/auth/auth.init.js',
+    // Exclude analytics init glue — just calls AnalyticsService.init()
+    '!<rootDir>/modules/analytics/analytics.init.js',
     // Exclude dead code — never imported anywhere in the codebase
     '!<rootDir>/modules/users/services/users.data.service.js',
     // Exclude server bootstrap — startup orchestration, tested indirectly via integration tests

lib/app.js

@@ -9,6 +9,7 @@ import config from '../config/index.js';
 import express from './services/express.js';
 import mongooseService from './services/mongoose.js';
 import migrations from './services/migrations.js';
+import AnalyticsService from '../modules/analytics/services/analytics.service.js';
 
 // Establish an SQL server connection, instantiating all models and schemas
 // const startSequelize = () =>
@@ -147,6 +148,7 @@ const shutdown = async (server) => {
 
   try {
     const value = await server;
+    await AnalyticsService.shutdown();
     await mongooseService.disconnect();
     value.http.close((err) => {
       console.info(chalk.yellow('Server closed'));

lib/services/express.js

@@ -130,7 +130,7 @@ const initMiddleware = (app) => {
 const initModulesConfiguration = async (app) => {
   for (const configPath of config.files.configs) {
     const route = await import(path.resolve(configPath));
-    route.default(app);
+    await route.default(app);
   }
 };
 

modules/analytics/analytics.init.js

@@ -0,0 +1,16 @@
+/**
+ * Module dependencies
+ */
+import AnalyticsService from './services/analytics.service.js';
+
+/**
+ * Initialise the analytics module.
+ * Called automatically by the Express init loop (matched via the
+ * `modules/{name}/{name}.init.js` glob in config/assets.js).
+ * @param {object} _app - Express application instance (unused)
+ * @returns {Promise<void>}
+ */
+// eslint-disable-next-line no-unused-vars
+export default async (_app) => {
+  await AnalyticsService.init();
+};

modules/analytics/config/analytics.development.config.js

@@ -0,0 +1,9 @@
+const config = {
+  posthog: {
+    // apiKey: process.env.DEVKIT_NODE_posthog_apiKey ?? '',
+    // host: process.env.DEVKIT_NODE_posthog_host ?? 'https://us.i.posthog.com',
+    // personalApiKey: process.env.DEVKIT_NODE_posthog_personalApiKey ?? '',
+  },
+};
+
+export default config;

modules/analytics/services/analytics.service.js

@@ -0,0 +1,109 @@
+/**
+ * Module dependencies
+ */
+import config from '../../../config/index.js';
+
+/**
+ * PostHog client instance (null when not configured)
+ * @type {import('posthog-node').PostHog|null}
+ */
+let client = null;
+
+/**
+ * Initialise the PostHog client using application config.
+ * When `posthog.apiKey` is absent the service stays in no-op mode —
+ * every public method silently returns without side-effects so that
+ * downstream projects that don't use PostHog are never affected.
+ *
+ * The `posthog-node` SDK is lazy-loaded (dynamic import) so that
+ * applications running on Node versions outside the SDK's engine
+ * range never pay the import cost when analytics is unconfigured.
+ * @returns {Promise<void>}
+ */
+const init = async () => {
+  const { apiKey, host } = config.posthog ?? {};
+  if (!apiKey) return;
+  const { PostHog } = await import('posthog-node');
+  client = new PostHog(apiKey, { host: host || 'https://us.i.posthog.com' });
+};
+
+/**
+ * Capture an analytics event.
+ * @param {string} distinctId - User or anonymous identifier
+ * @param {string} event - Event name
+ * @param {Object} [properties] - Additional event properties
+ * @param {Object} [groups] - Group identifiers (e.g. { company: orgId })
+ * @returns {void}
+ */
+const track = (distinctId, event, properties, groups) => {
+  if (!client) return;
+  client.capture({ distinctId, event, properties, groups });
+};
+
+/**
+ * Identify a user with optional properties.
+ * @param {string} distinctId - User identifier
+ * @param {Object} [properties] - User properties to set
+ * @returns {void}
+ */
+const identify = (distinctId, properties) => {
+  if (!client) return;
+  client.identify({ distinctId, properties });
+};
+
+/**
+ * Identify a group (e.g. organisation).
+ * @param {string} groupType - Group type (e.g. "company")
+ * @param {string} groupKey - Group identifier
+ * @param {Object} [properties] - Group properties to set
+ * @returns {void}
+ */
+const groupIdentify = (groupType, groupKey, properties) => {
+  if (!client) return;
+  client.groupIdentify({ groupType, groupKey, properties });
+};
+
+/**
+ * Evaluate a feature flag for the given user.
+ * @param {string} flag - Feature flag key
+ * @param {string} distinctId - User identifier
+ * @param {Object} [options] - Additional options forwarded to PostHog
+ * @returns {Promise<string|boolean|undefined>} Flag value, or undefined when not configured
+ */
+const getFeatureFlag = async (flag, distinctId, options) => {
+  if (!client) return undefined;
+  return client.getFeatureFlag(flag, distinctId, options);
+};
+
+/**
+ * Check whether a feature flag is enabled for the given user.
+ * @param {string} flag - Feature flag key
+ * @param {string} distinctId - User identifier
+ * @param {Object} [options] - Additional options forwarded to PostHog
+ * @returns {Promise<boolean|undefined>} true/false, or undefined when not configured
+ */
+const isFeatureEnabled = async (flag, distinctId, options) => {
+  if (!client) return undefined;
+  return client.isFeatureEnabled(flag, distinctId, options);
+};
+
+/**
+ * Flush pending events and shut down the PostHog client.
+ * Safe to call even when the client was never initialised.
+ * @returns {Promise<void>}
+ */
+const shutdown = async () => {
+  if (!client) return;
+  await client.shutdown();
+  client = null;
+};
+
+export default {
+  init,
+  track,
+  identify,
+  groupIdentify,
+  getFeatureFlag,
+  isFeatureEnabled,
+  shutdown,
+};