import { SetMetadata } from '@nestjs/common';

import { TRACK_ANALYTICS_METADATA } from './constants';

import type { TrackAnalyticsOptions } from './types';

/**
 * Decorator to enable analytics tracking on a controller method or service method.
 *
 * This decorator marks a method for automatic analytics tracking. When used with
 * AnalyticsInterceptor, it will automatically track view or engagement events
 * based on the configuration.
 *
 * @param options - Configuration for analytics tracking
 *
 * @example
 * ```typescript
 * // Track product views
 * @TrackAnalytics({
 *   eventType: 'view',
 *   contentType: 'product',
 *   idExtractor: (id: string) => id,
 * })
 * @Get(':id')
 * async getProduct(@Param('id') id: string) {
 *   return this.productsService.findOne(id);
 * }
 *
 * // Track user engagement (likes)
 * @TrackAnalytics({
 *   eventType: 'engagement',
 *   metricType: 'like',
 *   targetType: 'content',
 *   idExtractor: (contentId: string) => contentId,
 * })
 * @Post(':id/like')
 * async likeContent(@Param('id') contentId: string, @Req() req) {
 *   return this.contentService.like(contentId, req.user.id);
 * }
 *
 * // Custom user ID extraction
 * @TrackAnalytics({
 *   eventType: 'view',
 *   contentType: 'stream',
 *   idExtractor: (streamId: string) => streamId,
 *   userIdExtractor: (context) => context.user?.sub,
 * })
 * @Get('streams/:id')
 * async getStream(@Param('id') streamId: string) {
 *   return this.streamService.findOne(streamId);
 * }
 * ```
 */
export const TrackAnalytics = (options: TrackAnalyticsOptions): MethodDecorator => {
  return SetMetadata(TRACK_ANALYTICS_METADATA, options);
};
