Record Plausible analytics events for endpoints intended for Nextstrain CLI

These will help us in the future gain insight into Nextstrain CLI
version usage and update patterns as well as pathogen repository setup
and update patterns.

Author: tsibley

env/production/config.json

@@ -110,5 +110,6 @@
   "OIDC_GROUPS_CLAIM": "cognito:groups",
   "SESSION_COOKIE_DOMAIN": "nextstrain.org",
   "GROUPS_DATA_FILE": "groups.json",
-  "RESOURCE_INDEX": "s3://nextstrain-inventories/resources/v4.json.gz"
+  "RESOURCE_INDEX": "s3://nextstrain-inventories/resources/v4.json.gz",
+  "PLAUSIBLE_ANALYTICS_DOMAIN": "nextstrain.org"
 }

package-lock.json

@@ -89,6 +89,7 @@
     "sanitize-html": "^2.13.0",
     "session-file-store": "^1.3.1",
     "styled-components": "^6.1.8",
+    "user-agent-bag": "^0.3.0",
     "yaml-front-matter": "^4.0.0"
   },
   "devDependencies": {

package.json

@@ -0,0 +1,85 @@
+/**
+ * Analytics for server-side events.
+ *
+ * @module analytics
+ */
+import { default as UserAgentBag } from "user-agent-bag";
+import { PLAUSIBLE_ANALYTICS_DOMAIN, PLAUSIBLE_ANALYTICS_ENDPOINT } from "./config.js";
+import { fetch } from "./fetch.js";
+
+
+/**
+ * Generate middleware to record an analytics event via a request to
+ * Plausible's API.
+ *
+ * Intended for use in an Express routing chain.  The generated middleware
+ * function does not block on the analytics request before returning.
+ *
+ * If the User-Agent of the incoming request starts with "Nextstrain-CLI/",
+ * then it is parsed for several bits of information and those are
+ * automatically attached to the analytics event as custom properties.
+ *
+ * @function recordEvent
+ * @param {object} data
+ * @param {string} data.name - Event name.  Defaults to "pageview" (Plausible's default).
+ * @param {object} data.props - Custom properties.  Defaults to {}.
+ * @param {boolean} data.interactive - Interactive session or not?  Defaults to
+ *   false (opposite of Plausible's default), with the reasoning that most events
+ *   we're likely to record server-side aren't for interactive browser-based
+ *   sessions.
+ * @returns {expressMiddlewareAsync}
+ */
+export const recordEvent = ({name = "pageview", props = {}, interactive = false} = {}) => async (req, res, next) => {
+  if (PLAUSIBLE_ANALYTICS_DOMAIN) {
+    /* We intentionally do not "await fetch()" as we do not want to block
+     * request processing on analytics; we'd rather ignore failures.
+     *    -trs, 28 April 2025
+     */
+    fetch(
+      // <https://plausible.io/docs/events-api>
+      PLAUSIBLE_ANALYTICS_ENDPOINT, {
+        method: "POST",
+        headers: {
+          "User-Agent": req.header("User-Agent"),
+          "X-Forwarded-For": req.ip,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          name,
+          domain: PLAUSIBLE_ANALYTICS_DOMAIN,
+          url: new URL(req.originalUrl, req.context.origin),
+          referrer: req.header("Referer"),
+          interactive,
+          props: {
+            // <https://plausible.io/docs/custom-props/introduction>
+            ...propsFromUserAgent(req.header("User-Agent")),
+            ...props,
+          },
+        }),
+      }
+    );
+  }
+  return next();
+};
+
+
+const userAgentToPlausibleKeys = new Map([
+  ["Nextstrain-CLI",  "nextstrain-cli/version"],
+  ["Python",          "nextstrain-cli/python"],
+  ["installer",       "nextstrain-cli/installer"],
+  ["platform",        "nextstrain-cli/platform"],
+  ["tty",             "nextstrain-cli/tty"],
+]);
+
+function propsFromUserAgent(ua) {
+  if (ua && ua.match(/^Nextstrain-CLI\//)) {
+    const uaComponents = new UserAgentBag(ua);
+
+    return Object.fromEntries(
+      Array.from(userAgentToPlausibleKeys)
+        .map(([srcKey, dstKey]) => [dstKey, uaComponents.get(srcKey) ?? null])
+    );
+  }
+
+  return {};
+}

src/analytics.js

@@ -481,3 +481,19 @@ export const RESOURCE_INDEX = fromEnvOrConfig("RESOURCE_INDEX", null);
  * canonical PRODUCTION flag set here. 
  */
 export const STATIC_SITE_PRODUCTION = PRODUCTION || !!process.env.USE_PREBUILT_STATIC_SITE;
+
+/**
+ * Domain in Plausible analytics for which to record server-side analytics
+ * events.
+ *
+ * Analytics are not recorded if this is not set.
+ */
+export const PLAUSIBLE_ANALYTICS_DOMAIN = fromEnvOrConfig("PLAUSIBLE_ANALYTICS_DOMAIN", null);
+
+/**
+ * URL of submission endpoint for Plausible analytics events.
+ *
+ * Defaults to Plausible's standard endpoint.  Useful to change during
+ * development and testing of analytics.
+ */
+export const PLAUSIBLE_ANALYTICS_ENDPOINT = fromEnvOrConfig("PLAUSIBLE_ANALYTICS_ENDPOINT", "https://plausible.io/api/event");

src/config.js

@@ -1,7 +1,10 @@
+import * as analytics from '../analytics.js';
 import * as endpoints from '../endpoints/index.js';
 
 
 export function setup(app) {
+  app.useAsync("/cli", analytics.recordEvent());
+
   app.routeAsync("/cli/download/:version/:assetSuffix")
     .getAsync(endpoints.cli.download);
 

src/routing/cli.js

@@ -1,7 +1,10 @@
+import * as analytics from '../analytics.js';
 import * as endpoints from '../endpoints/index.js';
 
 
 export function setup(app) {
+  app.useAsync("/pathogen-repos", analytics.recordEvent());
+
   app.routeAsync("/pathogen-repos/:name/versions")
     .getAsync(endpoints.pathogenRepos.listVersions);