umami

lib/services/analytics/umami-analytics-service.ts

@@ -1,16 +1,74 @@
 import type { AnalyticsEventProperties, AnalyticsService } from './analytics-service';
 
+/**
+ * Type definition for the Umami global object.
+ *
+ * This represents the `window.umami` object that the Umami script exposes.
+ * The `track` function can accept either an event name or a URL.
+ */
 type UmamiGlobal = {
   track?: (eventOrUrl: string, props?: AnalyticsEventProperties) => void;
 };
 
+/**
+ * Configuration options for UmamiAnalyticsService.
+ *
+ * @property enabled - Whether analytics are enabled
+ */
 export type UmamiAnalyticsServiceOptions = {
   enabled: boolean;
 };
 
+/**
+ * Umami Analytics Service Implementation.
+ *
+ * This service implements the AnalyticsService interface for Umami analytics.
+ * It provides type-safe event tracking and pageview tracking.
+ *
+ * @example
+ * ```typescript
+ * // Service creation (usually done by create-services.ts)
+ * const service = new UmamiAnalyticsService({ enabled: true });
+ *
+ * // Track events
+ * service.track('button_click', { button_id: 'cta' });
+ * service.trackPageview('/products/123');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using through the service layer (recommended)
+ * import { getAppServices } from '@/lib/services/create-services';
+ *
+ * const services = getAppServices();
+ * services.analytics.track('product_add_to_cart', {
+ *   product_id: '123',
+ *   price: 99.99,
+ * });
+ * ```
+ */
 export class UmamiAnalyticsService implements AnalyticsService {
   constructor(private readonly options: UmamiAnalyticsServiceOptions) {}
 
+  /**
+   * Track a custom event with optional properties.
+   *
+   * This method checks if analytics are enabled and if we're in a browser environment
+   * before attempting to track the event.
+   *
+   * @param eventName - The name of the event to track
+   * @param props - Optional event properties
+   *
+   * @example
+   * ```typescript
+   * service.track('product_add_to_cart', {
+   *   product_id: '123',
+   *   product_name: 'Cable',
+   *   price: 99.99,
+   *   quantity: 1,
+   * });
+   * ```
+   */
   track(eventName: string, props?: AnalyticsEventProperties) {
     if (!this.options.enabled) return;
     if (typeof window === 'undefined') return;
@@ -19,6 +77,26 @@ export class UmamiAnalyticsService implements AnalyticsService {
     umami?.track?.(eventName, props);
   }
 
+  /**
+   * Track a pageview.
+   *
+   * This method checks if analytics are enabled and if we're in a browser environment
+   * before attempting to track the pageview.
+   *
+   * Umami treats `track(url)` as a pageview override, so we can use the same
+   * `track` function for both events and pageviews.
+   *
+   * @param url - The URL to track (defaults to current location)
+   *
+   * @example
+   * ```typescript
+   * // Track current page
+   * service.trackPageview();
+   *
+   * // Track custom URL
+   * service.trackPageview('/products/123?category=cables');
+   * ```
+   */
   trackPageview(url?: string) {
     if (!this.options.enabled) return;
     if (typeof window === 'undefined') return;