/**
 * 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;
}