umami

lib/services/analytics/analytics-service.ts

@@ -1,10 +1,77 @@
+/**
+ * Type definition for analytics event properties.
+ *
+ * @example
+ * ```typescript
+ * const properties: AnalyticsEventProperties = {
+ *   product_id: '123',
+ *   product_name: 'Cable',
+ *   price: 99.99,
+ *   quantity: 1,
+ *   in_stock: true,
+ * };
+ * ```
+ */
 export type AnalyticsEventProperties = Record<
   string,
   string | number | boolean | null | undefined
 >;
 
+/**
+ * Interface for analytics service implementations.
+ *
+ * This interface defines the contract for all analytics services,
+ * allowing for different implementations (Umami, Google Analytics, etc.)
+ * while maintaining a consistent API.
+ *
+ * @example
+ * ```typescript
+ * // Using the service directly
+ * const service = new UmamiAnalyticsService({ enabled: true });
+ * service.track('button_click', { button_id: 'cta' });
+ * service.trackPageview('/products/123');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the useAnalytics hook (recommended)
+ * const { trackEvent, trackPageview } = useAnalytics();
+ * trackEvent('button_click', { button_id: 'cta' });
+ * trackPageview('/products/123');
+ * ```
+ */
 export interface AnalyticsService {
+  /**
+   * Track a custom event with optional properties.
+   *
+   * @param eventName - The name of the event to track
+   * @param props - Optional event properties (metadata)
+   *
+   * @example
+   * ```typescript
+   * track('product_add_to_cart', {
+   *   product_id: '123',
+   *   product_name: 'Cable',
+   *   price: 99.99,
+   * });
+   * ```
+   */
   track(eventName: string, props?: AnalyticsEventProperties): void;
+
+  /**
+   * Track a pageview.
+   *
+   * @param url - The URL to track (defaults to current location)
+   *
+   * @example
+   * ```typescript
+   * // Track current page
+   * trackPageview();
+   *
+   * // Track custom URL
+   * trackPageview('/products/123?category=cables');
+   * ```
+   */
   trackPageview(url?: string): void;
 }