@momentumcms/plugins-analytics 0.1.0

package/src/lib/content-performance/content-performance-handler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Content Performance Handler
+ *
+ * Express router that serves per-document analytics data.
+ * Aggregates page_view events by URL pattern and document properties.
+ */
+import { Router } from 'express';
+import type { AnalyticsAdapter } from '../analytics-config.types';
+/**
+ * Create an Express router for the content performance endpoint.
+ *
+ * @param adapter - Analytics storage adapter (must support query)
+ * @returns Express Router
+ */
+export declare function createContentPerformanceRouter(adapter: AnalyticsAdapter): Router;

package/src/lib/content-performance/content-performance.types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Content Performance Types
+ *
+ * Types for the per-document analytics feature.
+ */
+/**
+ * Performance data for a specific document.
+ */
+export interface ContentPerformanceData {
+    /** Total page views for this document */
+    pageViews: number;
+    /** Unique visitor count */
+    uniqueVisitors: number;
+    /** Top referrer URLs */
+    topReferrers: Array<{
+        referrer: string;
+        count: number;
+    }>;
+    /** Block-level engagement (if block tracking is enabled) */
+    blockEngagement?: Array<{
+        blockType: string;
+        impressions: number;
+        hovers: number;
+    }>;
+}
+/**
+ * Query parameters for the content performance endpoint.
+ */
+export interface ContentPerformanceQuery {
+    /** Collection slug */
+    collection: string;
+    /** Document ID */
+    documentId: string;
+    /** Start date (ISO string) */
+    from?: string;
+    /** End date (ISO string) */
+    to?: string;
+}

package/src/lib/event-store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Event Store
+ *
+ * In-memory buffer with periodic flush to the analytics adapter.
+ * Events are batched for performance and flushed on interval or batch size.
+ */
+import type { AnalyticsEvent } from './analytics-event.types';
+import type { AnalyticsAdapter } from './analytics-config.types';
+/**
+ * Options for the event store.
+ */
+export interface EventStoreOptions {
+    /** Storage adapter */
+    adapter: AnalyticsAdapter;
+    /** Flush interval in ms. @default 5000 */
+    flushInterval?: number;
+    /** Batch size before forced flush. @default 100 */
+    flushBatchSize?: number;
+}
+/**
+ * In-memory event buffer with periodic flush.
+ */
+export declare class EventStore {
+    private buffer;
+    private readonly adapter;
+    private readonly flushInterval;
+    private readonly flushBatchSize;
+    private readonly logger;
+    private timer;
+    private flushing;
+    constructor(options: EventStoreOptions);
+    /**
+     * Start the periodic flush timer.
+     */
+    start(): void;
+    /**
+     * Add an event to the buffer.
+     * Triggers an immediate flush if batch size is reached.
+     */
+    add(event: AnalyticsEvent): void;
+    /**
+     * Add multiple events to the buffer.
+     */
+    addBatch(events: AnalyticsEvent[]): void;
+    /**
+     * Flush all buffered events to the adapter.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stop the periodic flush timer and flush remaining events.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the current buffer size.
+     */
+    get size(): number;
+}

package/src/lib/ingest-handler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ingest Handler
+ *
+ * Express route handler for the client-side analytics ingest endpoint.
+ * Validates incoming events, assigns server-side timestamps, and rate limits.
+ */
+import type { Router } from 'express';
+import type { EventStore } from './event-store';
+/**
+ * Options for the ingest handler.
+ */
+export interface IngestHandlerOptions {
+    /** Event store to buffer events */
+    eventStore: EventStore;
+    /** Rate limit per IP per minute. @default 100 */
+    rateLimit?: number;
+}
+/**
+ * Creates an Express router for the analytics ingest endpoint.
+ *
+ * @param options - Ingest handler options
+ * @returns Express router
+ */
+export declare function createIngestRouter(options: IngestHandlerOptions): Router;

package/src/lib/tracking-rules/tracking-rule.types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tracking Rule Types
+ *
+ * Types for admin-managed element tracking rules.
+ * Admins define CSS selector + DOM event → analytics event mappings.
+ */
+/**
+ * DOM event types supported by tracking rules.
+ */
+export type TrackingEventType = 'click' | 'submit' | 'scroll-into-view' | 'hover' | 'focus';
+/**
+ * Describes how to extract a property value from a matched DOM element.
+ */
+export interface PropertyExtraction {
+    /** Property key in the analytics event */
+    key: string;
+    /** Where to read the value from */
+    source: 'text' | 'attribute' | 'dataset';
+    /** Attribute or dataset key name (required for 'attribute' and 'dataset' sources) */
+    attribute?: string;
+}
+/**
+ * A tracking rule as stored in the database.
+ */
+export interface TrackingRule {
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** CSS selector to match elements */
+    selector: string;
+    /** DOM event type to listen for */
+    eventType: TrackingEventType;
+    /** Analytics event name to fire */
+    eventName: string;
+    /** URL pattern to match pages (glob: * = any segment, ** = any path) */
+    urlPattern: string;
+    /** Static properties attached to every event */
+    properties: Record<string, string>;
+    /** Dynamic property extraction from matched DOM elements */
+    extractProperties?: PropertyExtraction[];
+    /** Whether this rule is active */
+    active: boolean;
+    /** Max events per minute per visitor for this rule */
+    rateLimit?: number;
+}
+/**
+ * Client-facing tracking rule (stripped of internal fields).
+ */
+export type ClientTrackingRule = Omit<TrackingRule, 'id'>;

package/src/lib/tracking-rules/tracking-rules-collection.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tracking Rules Collection
+ *
+ * Collection definition for admin-managed element tracking rules.
+ * Injected into the collections array by the analytics plugin during onInit.
+ */
+/**
+ * Tracking Rules collection config.
+ * Defines the schema for admin-managed CSS selector tracking rules.
+ */
+export declare const TrackingRules: import("@momentumcms/core").CollectionConfig;

package/src/lib/tracking-rules/tracking-rules-endpoint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tracking Rules Endpoint
+ *
+ * Serves active tracking rules to the client-side rule engine.
+ * Includes an in-memory cache to avoid DB hits on every page load.
+ */
+import { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/core';
+/**
+ * Options for the tracking rules endpoint.
+ */
+export interface TrackingRulesEndpointOptions {
+    /** Cache time-to-live in ms. @default 60000 */
+    cacheTtl?: number;
+}
+/**
+ * Create an Express router for serving tracking rules to the client.
+ *
+ * @param getApi - Function that returns the MomentumAPI instance (available after onReady)
+ * @param options - Endpoint options
+ * @returns Express Router
+ */
+export interface TrackingRulesRouterResult {
+    router: Router;
+    invalidateCache: () => void;
+}
+export declare function createTrackingRulesRouter(getApi: () => MomentumAPI | null, options?: TrackingRulesEndpointOptions): TrackingRulesRouterResult;

package/src/lib/utils/parse-user-agent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Lightweight User-Agent Parser
+ *
+ * Extracts device type, browser name, and OS from a user-agent string.
+ * Uses simple regex patterns — no external dependencies.
+ */
+export interface ParsedUserAgent {
+    /** Device type: 'mobile', 'tablet', or 'desktop' */
+    device: string;
+    /** Browser name (e.g., 'Chrome', 'Firefox', 'Safari') */
+    browser: string;
+    /** Operating system (e.g., 'Windows', 'macOS', 'Linux', 'iOS', 'Android') */
+    os: string;
+}
+/**
+ * Parse a user-agent string into device, browser, and OS components.
+ *
+ * @param ua - The user-agent string to parse
+ * @returns Parsed components with sensible defaults for unknown values
+ */
+export declare function parseUserAgent(ua: string | undefined): ParsedUserAgent;

package/src/lib/utils/selector-security.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CSS Selector Security Utilities
+ *
+ * Shared blocklist and validation for tracking rule CSS selectors.
+ * Used by both the server-side endpoint (tracking-rules-endpoint.ts)
+ * and the client-side rule engine (rule-engine.ts).
+ *
+ * Selectors targeting sensitive form inputs are rejected to prevent
+ * data exfiltration via the tracking rules system.
+ */
+/**
+ * Check if a CSS selector targets sensitive elements.
+ * Normalizes CSS escape sequences and strips pseudo-class wrappers
+ * before checking against the blocklist to prevent bypass.
+ */
+export declare function isSelectorBlocked(selector: string): boolean;

package/src/lib/utils/type-guards.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared Type Guards
+ *
+ * Common type guard functions used across the analytics plugin.
+ */
+/**
+ * Check if a value is a non-null, non-array object.
+ */
+export declare function isRecord(val: unknown): val is Record<string, unknown>;