@momentumcms/plugins-analytics 0.4.0 → 0.4.1

package/src/lib/collectors/page-view-collector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Page View Collector
+ *
+ * Express middleware that tracks SSR page view timing and context.
+ * Mounted at the application root to intercept page renders.
+ */
+import type { Request, Response, NextFunction } from 'express';
+import type { AnalyticsEvent } from '../analytics-event.types';
+import type { PageViewTrackingOptions } from '../analytics-config.types';
+/**
+ * Callback type for page view event emission.
+ */
+export type PageViewEmitter = (event: AnalyticsEvent) => void;
+/**
+ * Check whether a user-agent string belongs to a known bot.
+ */
+export declare function isBot(ua: string | undefined): boolean;
+/**
+ * Check whether a request path should be excluded from page view tracking.
+ */
+export declare function shouldExcludePath(path: string, excludeExtensions: ReadonlySet<string>, excludePaths: readonly string[]): boolean;
+/**
+ * Creates Express middleware that tracks SSR page view metrics.
+ *
+ * @param emitter - Callback to emit analytics events
+ * @param options - Page view tracking options
+ * @returns Express middleware function
+ */
+export declare function createPageViewCollectorMiddleware(emitter: PageViewEmitter, options?: PageViewTrackingOptions): (req: Request, res: Response, next: NextFunction) => void;

package/src/lib/page-view-tracker.d.ts

@@ -0,0 +1,21 @@
+import type { EnvironmentProviders } from '@angular/core';
+
+/** Configuration for the client-side page view tracker. */
+export interface PageViewTrackingConfig {
+	/** Map of collection slug -> URL pattern (e.g. `{ articles: '/articles/:slug' }`) */
+	contentRoutes?: Record<string, string>;
+	/** Ingest endpoint URL. @default '/api/analytics/collect' */
+	endpoint?: string;
+	/** Additional path prefixes to exclude from tracking. */
+	excludePrefixes?: readonly string[];
+}
+
+/**
+ * Provide client-side page view tracking for an Angular application.
+ *
+ * Listens to Angular Router NavigationEnd events and sends page_view analytics
+ * events to the ingest endpoint for SPA navigations.
+ */
+export declare function providePageViewTracking(
+	config: PageViewTrackingConfig,
+): EnvironmentProviders;

package/src/lib/page-view-tracker.utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Page View Tracker — Pure Logic
+ *
+ * Testable functions used by the Angular PageViewTrackerService.
+ * No Angular dependencies — safe for Node.js and Vitest environments.
+ */
+import { type CompiledContentRoute } from './utils/content-route-matcher';
+/** Default path prefixes excluded from client-side page view tracking. */
+export declare const DEFAULT_EXCLUDE_PREFIXES: readonly string[];
+/**
+ * Determine whether a navigation should be tracked.
+ *
+ * @param url - The navigated URL (may include query string / fragment)
+ * @param isFirstNavigation - True for the initial route (already tracked by SSR)
+ * @param excludePrefixes - Path prefixes to skip
+ */
+export declare function shouldTrackNavigation(url: string, isFirstNavigation: boolean, excludePrefixes: readonly string[]): boolean;
+/**
+ * Build a page_view client event payload from a URL.
+ *
+ * @param url - The navigated URL (may include query / fragment)
+ * @param compiledRoutes - Pre-compiled content routes for collection matching
+ */
+export declare function buildPageViewEvent(url: string, compiledRoutes: readonly CompiledContentRoute[] | undefined): {
+    name: string;
+    category: string;
+    properties: Record<string, unknown>;
+};

package/src/lib/utils/content-route-matcher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Content Route Matcher
+ *
+ * Compiles Express-style :param patterns into matchers for
+ * attributing page views to CMS collections.
+ */
+/** A compiled content route matcher. */
+export interface CompiledContentRoute {
+    /** Collection slug this route maps to */
+    collection: string;
+    /** Original pattern string */
+    pattern: string;
+    /** Compiled regex */
+    regex: RegExp;
+    /** Ordered parameter names extracted from the pattern */
+    paramNames: readonly string[];
+    /** Number of static (non-param) segments — used for priority sorting */
+    staticSegments: number;
+}
+/** Result of matching a URL against content routes. */
+export interface ContentRouteMatch {
+    /** Collection slug */
+    collection: string;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+}
+/**
+ * Compile a single route pattern into a regex matcher.
+ *
+ * Supports Express-style `:paramName` segments.
+ * e.g. `/articles/:slug` compiles to `/^\/articles\/([^/]+)\/?$/`
+ */
+export declare function compileContentRoute(collection: string, pattern: string): CompiledContentRoute;
+/**
+ * Compile all content routes, sorted by specificity (most static segments first).
+ */
+export declare function compileContentRoutes(routes: Record<string, string>): CompiledContentRoute[];
+/**
+ * Match a URL path against compiled content routes.
+ * Returns the first (highest-priority) match, or undefined.
+ */
+export declare function matchContentRoute(path: string, routes: readonly CompiledContentRoute[]): ContentRouteMatch | undefined;