top-level metrics class

shakyShane · mgurgel · commit e0fc9c2565d2 · 2025-08-01T15:02:05.000+01:00
diff --git a/injected/src/features/duck-player-native.js b/injected/src/features/duck-player-native.js
@@ -4,7 +4,7 @@ import { DuckPlayerNativeMessages } from './duckplayer-native/messages.js';
 import { setupDuckPlayerForNoCookie, setupDuckPlayerForSerp, setupDuckPlayerForYouTube } from './duckplayer-native/sub-feature.js';
 import { Environment } from './duckplayer/environment.js';
 import { Logger } from './duckplayer/util.js';
-import { MetricsReporter, EXCEPTION_KIND_INITIAL_SETUP_ERROR } from '../../../special-pages/shared/metrics/metrics-reporter.js';
+import { MetricsReporter, EXCEPTION_KIND_INITIAL_SETUP_ERROR } from '../../../metrics/metrics-reporter.js';
 
 /**
  * @import {DuckPlayerNativeSubFeature} from './duckplayer-native/sub-feature.js'
diff --git a/injected/src/features/duck-player.js b/injected/src/features/duck-player.js
@@ -37,7 +37,7 @@ import { DuckPlayerOverlayMessages, OpenInDuckPlayerMsg, Pixel } from './duckpla
 import { isBeingFramed } from '../utils.js';
 import { initOverlays } from './duckplayer/overlays.js';
 import { Environment } from './duckplayer/environment.js';
-import { MetricsReporter } from '../../../special-pages/shared/metrics/metrics-reporter.js';
+import { MetricsReporter } from '../../../metrics/metrics-reporter.js';
 
 /**
  * @typedef UserValues - A way to communicate user settings
diff --git a/injected/src/features/duckplayer-native/messages.js b/injected/src/features/duckplayer-native/messages.js
@@ -1,5 +1,5 @@
 import * as constants from './constants.js';
-import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from 'special-pages/shared/metrics/metrics-reporter.js';
+import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from '../../../..//metrics/metrics-reporter.js';
 
 /** @import {YouTubeError} from './error-detection.js' */
 /** @import {Environment} from '../duckplayer/environment.js' */
diff --git a/injected/src/features/duckplayer/overlay-messages.js b/injected/src/features/duckplayer/overlay-messages.js
@@ -1,6 +1,6 @@
 /* eslint-disable promise/prefer-await-to-then */
 import * as constants from './constants.js';
-import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from 'special-pages/shared/metrics/metrics-reporter.js';
+import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from '../../../../metrics/metrics-reporter.js';
 
 /**
  * @typedef {import("@duckduckgo/messaging").Messaging} Messaging
diff --git a/injected/src/features/duckplayer/overlays.js b/injected/src/features/duckplayer/overlays.js
@@ -2,7 +2,7 @@ import { DomState } from './util.js';
 import { ClickInterception, Thumbnails } from './thumbnails.js';
 import { VideoOverlay } from './video-overlay.js';
 import { registerCustomElements } from './components/index.js';
-import { EXCEPTION_KIND_INITIAL_SETUP_ERROR } from 'special-pages/shared/metrics/metrics-reporter.js';
+import { EXCEPTION_KIND_INITIAL_SETUP_ERROR } from '../../../../metrics/metrics-reporter.js';
 
 /**
  * @typedef {object} OverlayOptions
diff --git a/injected/unit-test/verify-artifacts.js b/injected/unit-test/verify-artifacts.js
@@ -7,7 +7,7 @@ const ROOT = join(cwd(import.meta.url), '..', '..');
 console.log(ROOT);
 const BUILD = join(ROOT, 'build');
 
-let CSS_OUTPUT_SIZE = 770_000;
+let CSS_OUTPUT_SIZE = 780_000;
 if (process.platform === 'win32') {
     CSS_OUTPUT_SIZE = CSS_OUTPUT_SIZE * 1.1; // 10% larger for Windows due to line endings
 }
diff --git a/metrics/docs/readme.md b/metrics/docs/readme.md
@@ -0,0 +1,16 @@
+---
+title: Metrics
+---
+
+# Metrics
+
+Utility class for reporting metrics and exceptions to the native layer.
+
+This class provides standardized methods for sending metric events and exception reports
+through the messaging system. It includes predefined metric names for common error types
+and helper methods to construct and send metric events.
+
+Please see [metrics-reporter.js](../metrics-reporter.js)
+for the message schema
+
+{@includeCode ../examples/metrics.js}
diff --git a/metrics/examples/metrics.js b/metrics/examples/metrics.js
@@ -0,0 +1,39 @@
+import { MetricsReporter } from '../metrics-reporter.js';
+import { Messaging, MessagingContext, TestTransportConfig } from '@duckduckgo/messaging';
+
+const messaging = createMessaging();
+const metrics = new MetricsReporter(messaging);
+
+// Report a custom metric
+metrics.reportMetric({
+    metricName: 'exception',
+    params: { kind: 'abc', message: 'something went' },
+});
+
+// Report an exception
+metrics.reportException({
+    message: 'Failed to load user data',
+    kind: 'NetworkError',
+});
+
+// Report an exception by passing an Error object
+metrics.reportExceptionWithError(new Error('Missing params'));
+
+// test messaging example
+function createMessaging() {
+    const context = new MessagingContext({
+        context: 'test',
+        env: 'development',
+        featureName: 'testFeature',
+    });
+    const config = new TestTransportConfig({
+        notify() {},
+        request() {
+            return Promise.resolve(null);
+        },
+        subscribe() {
+            return () => {};
+        },
+    });
+    return new Messaging(context, config);
+}
diff --git a/metrics/messages/reportMetric.notify.json b/metrics/messages/reportMetric.notify.json
diff --git a/metrics/metrics-reporter.js b/metrics/metrics-reporter.js
@@ -1,43 +1,7 @@
-/**
- * Utility class for reporting metrics and exceptions to the native layer.
- *
- * This class provides standardized methods for sending metric events and exception reports
- * through the messaging system. It includes predefined metric names for common error types
- * and helper methods to construct and send metric events.
- *
- * Please see https://duckduckgo.github.io/content-scope-scripts/interfaces/shared_messages.reportmetricnotification
- * for the message schema
- *
- * @example
- * ```javascript
- * import { MetricsReporter } from './metrics-reporter.js';
- *
- * const metrics = new MetricsReporter(messaging);
- *
- * // Report a custom metric
- * metrics.reportMetric({
- *     metricName: 'userAction',
- *     params: { action: 'buttonClick', page: 'home' }
- * });
- *
- * // Report an exception
- * metrics.reportException({
- *     message: 'Failed to load user data',
- *     kind: 'NetworkError'
- * });
- *
- * // Report an exception by passing an Error object
- * metrics.reportExceptionWithError(new Error('Missing params'));
- * ```
- *
- * @module Metrics Reporter
- */
-
 /**
  * @typedef {import('./types/metrics.ts').ExceptionMetric} ExceptionMetric
  * @typedef {import('./types/metrics.ts').ReportMetricEvent} ReportMetricEvent
  */
-
 import { createTypedMessages } from '@duckduckgo/messaging/lib/typed-messages.js';
 
 /** Exception kind for generic errors */
diff --git a/metrics/package.json b/metrics/package.json
@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "name": "metrics",
+  "type": "module",
+  "scripts": {
+    "build": "node scripts/types.mjs",
+    "test-unit": "node --test unit-test/*"
+  },
+  "dependencies": {
+    "@duckduckgo/messaging": "*"
+  }
+}
diff --git a/metrics/scripts/types.mjs b/metrics/scripts/types.mjs
@@ -0,0 +1,32 @@
+import { cwd, isLaunchFile } from '../../scripts/script-utils.js';
+import { join } from 'node:path';
+import { buildTypes } from '../../types-generator/build-types.mjs';
+
+const root = join(cwd(import.meta.url), '..');
+
+/** @type {Record<string, import('../../types-generator/build-types.mjs').Mapping>} */
+const injectSchemaMapping = {
+    /**
+     * Add more mappings here
+     *  - `schema` should be an absolute path to a valid JSON Schema document
+     *  - `types` should be an absolute path to the output file
+     */
+    'Metrics Messages': {
+        schemaDir: join(root, 'messages'),
+        typesDir: join(root, 'types'),
+        exclude: process.platform === 'win32',
+        kind: 'single',
+        resolve: (_dirname) => '../metrics-reporter.js',
+        className: (_top) => 'MetricsReporter',
+        filename: `metrics.ts`,
+    },
+};
+
+if (isLaunchFile(import.meta.url)) {
+    buildTypes(injectSchemaMapping)
+        // eslint-disable-next-line promise/prefer-await-to-then
+        .catch((error) => {
+            console.error(error);
+            process.exit(1);
+        });
+}
diff --git a/metrics/types/metrics.ts b/metrics/types/metrics.ts
@@ -0,0 +1,36 @@
+/**
+ * These types are auto-generated from schema files.
+ * scripts/build-types.mjs is responsible for type generation.
+ * **DO NOT** edit this file directly as your changes will be lost.
+ *
+ * @module MetricsMessages Messages
+ */
+
+export type ReportMetricEvent = ExceptionMetric;
+
+/**
+ * Requests, Notifications and Subscriptions from the MetricsMessages feature
+ */
+export interface MetricsMessagesMessages {
+    notifications: ReportMetricNotification;
+}
+/**
+ * Generated from @see "../messages/reportMetric.notify.json"
+ */
+export interface ReportMetricNotification {
+    method: 'reportMetric';
+    params: ReportMetricEvent;
+}
+export interface ExceptionMetric {
+    metricName: 'exception';
+    params: {
+        message: string;
+        kind?: string;
+    };
+}
+
+declare module '../metrics-reporter.js' {
+    export interface MetricsReporter {
+        notify: import('@duckduckgo/messaging/lib/shared-types').MessagingBase<MetricsMessagesMessages>['notify'];
+    }
+}
diff --git a/metrics/unit-test/metrics-reporter.mjs b/metrics/unit-test/metrics-reporter.mjs
@@ -1,6 +1,6 @@
 import { describe, it, mock, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { MetricsReporter } from '../shared/metrics/metrics-reporter.js';
+import { MetricsReporter } from '../metrics-reporter.js';
 
 describe('reportMetric', () => {
     let messaging;
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -34,7 +34,8 @@
     "injected",
     "special-pages",
     "messaging",
-    "types-generator"
+    "types-generator",
+    "metrics"
   ],
   "devDependencies": {
     "@duckduckgo/eslint-config": "github:duckduckgo/eslint-config#v0.1.0",
diff --git a/special-pages/pages/duckplayer/app/index.js b/special-pages/pages/duckplayer/app/index.js
@@ -15,7 +15,7 @@ import { Components } from './components/Components.jsx';
 import { MobileApp } from './components/MobileApp.jsx';
 import { DesktopApp } from './components/DesktopApp.jsx';
 import { YouTubeErrorProvider } from './providers/YouTubeErrorProvider';
-import { EXCEPTION_KIND_INIT_ERROR, EXCEPTION_KIND_INITIAL_SETUP_ERROR } from '../../../shared/metrics/metrics-reporter.js';
+import { EXCEPTION_KIND_INIT_ERROR, EXCEPTION_KIND_INITIAL_SETUP_ERROR } from '../../../../metrics/metrics-reporter.js';
 
 /** @typedef {import('../types/duckplayer').YouTubeError} YouTubeError */
 
diff --git a/special-pages/pages/duckplayer/integration-tests/duck-player.js b/special-pages/pages/duckplayer/integration-tests/duck-player.js
@@ -568,7 +568,7 @@ export class DuckPlayerPage {
     }
 
     /**
-     * @param {import('../../../shared/metrics/types/metrics.js').ReportMetricEvent} evt
+     * @param {import('../../../../metrics/types/metrics.js').ReportMetricEvent} evt
      */
     async didSendReportMetric(evt) {
         const events = await this.mocks.waitForCallCount({ method: 'reportMetric', count: 1 });
diff --git a/special-pages/pages/duckplayer/src/index.js b/special-pages/pages/duckplayer/src/index.js
@@ -4,7 +4,7 @@ import { createSpecialPageMessaging } from '../../../shared/create-special-page-
 import { init } from '../app/index.js';
 import { initStorage } from './storage.js';
 import '../../../shared/live-reload.js';
-import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from '../../../shared/metrics/metrics-reporter.js';
+import { MetricsReporter, EXCEPTION_KIND_MESSAGING_ERROR } from '../../../../metrics/metrics-reporter.js';
 
 export class DuckplayerPage {
     /**
diff --git a/special-pages/shared/metrics/types/metrics.ts b/special-pages/shared/metrics/types/metrics.ts
diff --git a/special-pages/types.mjs b/special-pages/types.mjs
@@ -29,17 +29,6 @@ for (const pageListElement of pageList) {
     };
 }
 
-/* Shared types */
-specialPagesTypes.metrics = {
-    schemaDir: join(specialPagesRoot, 'shared', 'metrics', 'messages'),
-    typesDir: join(specialPagesRoot, 'shared', 'metrics', 'types'),
-    exclude: process.platform === 'win32',
-    kind: 'single',
-    resolve: (_dirname) => '../metrics-reporter.js',
-    className: (_top) => 'MetricsReporter',
-    filename: `metrics.ts`,
-};
-
 if (isLaunchFile(import.meta.url)) {
     buildTypes(specialPagesTypes).catch((error) => {
         console.error(error);
diff --git a/tsconfig.json b/tsconfig.json
@@ -27,6 +27,7 @@
     "types-generator",
     "special-pages",
     "messaging",
+    "metrics",
     "playwright.config.js",
     "injected",
     "injected/src/globals.d.ts",
diff --git a/typedoc.js b/typedoc.js
@@ -7,6 +7,7 @@ const config = {
         'special-pages/pages/new-tab/app/new-tab.md',
         'special-pages/pages/history/app/history.md',
         'injected/docs/*.md',
+        'metrics/docs/*.md',
         'messaging/docs/messaging.md',
 
     ],
@@ -35,8 +36,7 @@ const config = {
         'special-pages/pages/special-error/app/types.js',
         'special-pages/pages/new-tab/app/favorites/constants.js',
         'special-pages/pages/**/types/*.ts',
-        'special-pages/shared/types/*.ts',
-        'special-pages/shared/metrics-reporter.js',
+        'metrics/metrics-reporter.js',
     ],
     categoryOrder: ['Special Pages', 'Content Scope Scripts Integrations', 'Other'],
     out: 'docs',

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ const ROOT = join(cwd(import.meta.url), '..', '..');`
`7`	`7`	`console.log(ROOT);`
`8`	`8`	`const BUILD = join(ROOT, 'build');`
`9`	`9`
`10`		`-let CSS_OUTPUT_SIZE = 770_000;`
	`10`	`+let CSS_OUTPUT_SIZE = 780_000;`
`11`	`11`	`if (process.platform === 'win32') {`
`12`	`12`	`CSS_OUTPUT_SIZE = CSS_OUTPUT_SIZE * 1.1; // 10% larger for Windows due to line endings`
`13`	`13`	`}`