/** * Umami Analytics Utility * * Provides type-safe event tracking for all ManaCore apps. * Events are automatically sent to Umami at stats.mana.how * * @example * ```typescript * import { trackEvent, trackClick } from '@manacore/shared-utils/analytics'; * * // Track a custom event * trackEvent('signup_completed', { method: 'email' }); * * // Track a button click * trackClick('cta_hero', 'Get Started'); * ``` */ // Umami types declare global { interface Window { umami?: { track: (eventName: string, eventData?: Record) => void; }; } } /** * Check if Umami is available */ export function isUmamiAvailable(): boolean { return typeof window !== 'undefined' && typeof window.umami?.track === 'function'; } /** * Track a custom event * * @param eventName - Name of the event (snake_case recommended) * @param data - Optional event data/properties * * @example * trackEvent('image_generated', { model: 'flux', style: 'realistic' }); */ export function trackEvent( eventName: string, data?: Record ): void { if (!isUmamiAvailable()) { return; } try { window.umami!.track(eventName, data); } catch (error) { console.warn('[Analytics] Failed to track event:', eventName, error); } } /** * Track a button/link click * * @param elementId - Identifier for the element (e.g., 'cta_hero', 'nav_pricing') * @param label - Human-readable label * * @example * trackClick('cta_hero', 'Start Free Trial'); */ export function trackClick(elementId: string, label?: string): void { trackEvent('click', { element: elementId, label: label || elementId }); } /** * Track a page/section view * * @param section - Section identifier * * @example * trackView('pricing_section'); */ export function trackView(section: string): void { trackEvent('view', { section }); } /** * Track form submission * * @param formId - Form identifier * @param success - Whether submission was successful * * @example * trackFormSubmit('contact_form', true); */ export function trackFormSubmit(formId: string, success: boolean): void { trackEvent('form_submit', { form: formId, success }); } /** * Track search queries * * @param query - Search query (consider privacy - don't track full queries) * @param resultsCount - Number of results * * @example * trackSearch('react hooks', 42); */ export function trackSearch(query: string, resultsCount: number): void { // Only track query length for privacy trackEvent('search', { query_length: query.length, results: resultsCount }); } /** * Track errors * * @param errorType - Type of error * @param message - Error message (sanitized) * * @example * trackError('api_error', 'Failed to fetch data'); */ export function trackError(errorType: string, message?: string): void { trackEvent('error', { type: errorType, message: message?.substring(0, 100) || 'unknown', }); } // ============================================================================= // App-Specific Event Helpers // ============================================================================= /** * Auth Events */ export const AuthEvents = { login: (method: 'email' | 'google' | 'github' = 'email') => trackEvent('login', { method }), logout: () => trackEvent('logout'), signup: (method: 'email' | 'google' | 'github' = 'email') => trackEvent('signup', { method }), signupCompleted: () => trackEvent('signup_completed'), passwordReset: () => trackEvent('password_reset'), }; /** * Landing Page Events */ export const LandingEvents = { ctaClick: (location: 'hero' | 'pricing' | 'features' | 'footer' | string) => trackEvent('cta_click', { location }), pricingViewed: () => trackEvent('pricing_viewed'), pricingPlanSelected: (plan: string) => trackEvent('pricing_plan_selected', { plan }), demoStarted: () => trackEvent('demo_started'), featureExplored: (feature: string) => trackEvent('feature_explored', { feature }), faqOpened: (question: string) => trackEvent('faq_opened', { question: question.substring(0, 50) }), contactFormSubmitted: () => trackEvent('contact_form_submitted'), newsletterSubscribed: () => trackEvent('newsletter_subscribed'), }; /** * Chat App Events */ export const ChatEvents = { conversationCreated: () => trackEvent('conversation_created'), messageSent: (modelId?: string) => trackEvent('message_sent', modelId ? { model: modelId } : undefined), modelChanged: (modelId: string) => trackEvent('model_changed', { model: modelId }), conversationDeleted: () => trackEvent('conversation_deleted'), conversationShared: () => trackEvent('conversation_shared'), }; /** * Picture App Events */ export const PictureEvents = { imageGenerated: (model: string, style?: string) => trackEvent('image_generated', { model, ...(style && { style }) }), imageDownloaded: () => trackEvent('image_downloaded'), imageFavorited: () => trackEvent('image_favorited'), imageShared: () => trackEvent('image_shared'), modelSelected: (model: string) => trackEvent('model_selected', { model }), styleSelected: (style: string) => trackEvent('style_selected', { style }), generationFailed: (reason?: string) => trackEvent('generation_failed', { reason: reason || 'unknown' }), }; /** * Todo App Events */ export const TodoEvents = { taskCreated: (hasDeadline = false) => trackEvent('task_created', { has_deadline: hasDeadline }), taskCompleted: () => trackEvent('task_completed'), taskDeleted: () => trackEvent('task_deleted'), taskUncompleted: () => trackEvent('task_uncompleted'), subtaskCompleted: () => trackEvent('subtask_completed'), projectCreated: () => trackEvent('project_created'), projectDeleted: () => trackEvent('project_deleted'), labelCreated: () => trackEvent('label_created'), viewChanged: (view: string) => trackEvent('view_changed', { view }), quickAddUsed: () => trackEvent('quick_add_used'), filterUsed: (filterType: string) => trackEvent('filter_used', { filter: filterType }), }; /** * Calendar App Events */ export const CalendarEvents = { eventCreated: (isRecurring = false) => trackEvent('event_created', { recurring: isRecurring }), eventUpdated: () => trackEvent('event_updated'), eventDeleted: () => trackEvent('event_deleted'), calendarCreated: () => trackEvent('calendar_created'), calendarDeleted: () => trackEvent('calendar_deleted'), calendarShared: () => trackEvent('calendar_shared'), viewChanged: (view: string) => trackEvent('view_changed', { view }), reminderSet: (minutesBefore: number) => trackEvent('reminder_set', { minutes: minutesBefore }), eventDragged: () => trackEvent('event_dragged'), }; /** * Clock App Events */ export const ClockEvents = { timerStarted: (type: 'pomodoro' | 'stopwatch' | 'countdown') => trackEvent('timer_started', { type }), timerCompleted: (type: 'pomodoro' | 'stopwatch' | 'countdown', duration: number) => trackEvent('timer_completed', { type, duration_seconds: duration }), timerCanceled: () => trackEvent('timer_canceled'), focusSessionStarted: () => trackEvent('focus_session_started'), focusSessionCompleted: (duration: number) => trackEvent('focus_session_completed', { duration_minutes: duration }), }; /** * Contacts App Events */ export const ContactsEvents = { contactCreated: () => trackEvent('contact_created'), contactUpdated: () => trackEvent('contact_updated'), contactDeleted: () => trackEvent('contact_deleted'), contactFavorited: () => trackEvent('contact_favorited'), contactArchived: () => trackEvent('contact_archived'), contactImported: (source: 'google' | 'csv' | 'vcard', count?: number) => trackEvent('contact_imported', { source, ...(count !== undefined && { count }) }), contactExported: (format: 'csv' | 'vcard') => trackEvent('contact_exported', { format }), tagCreated: () => trackEvent('tag_created'), searchPerformed: () => trackEvent('search_performed'), }; /** * ManaDeck App Events */ export const ManaDeckEvents = { deckCreated: () => trackEvent('deck_created'), deckDeleted: () => trackEvent('deck_deleted'), deckStudied: (cardsCount: number) => trackEvent('deck_studied', { cards: cardsCount }), cardCreated: () => trackEvent('card_created'), cardDeleted: () => trackEvent('card_deleted'), cardReviewed: (rating: 1 | 2 | 3 | 4 | 5) => trackEvent('card_reviewed', { rating }), aiCardsGenerated: (count: number) => trackEvent('ai_cards_generated', { count }), }; /** * ManaCore Platform Events */ export const ManaCoreEvents = { appOpened: (appId: string) => trackEvent('app_opened', { app: appId }), navClicked: (destination: string) => trackEvent('nav_clicked', { destination }), onboardingStarted: () => trackEvent('onboarding_started'), onboardingStepCompleted: (step: string, stepNumber: number) => trackEvent('onboarding_step_completed', { step, step_number: stepNumber }), onboardingCompleted: () => trackEvent('onboarding_completed'), onboardingSkipped: (atStep: number) => trackEvent('onboarding_skipped', { at_step: atStep }), dashboardEditToggled: (editing: boolean) => trackEvent('dashboard_edit_toggled', { editing }), widgetAdded: (widgetType: string) => trackEvent('widget_added', { widget_type: widgetType }), widgetRemoved: (widgetType: string) => trackEvent('widget_removed', { widget_type: widgetType }), widgetResized: (widgetType: string, size: string) => trackEvent('widget_resized', { widget_type: widgetType, size }), creditsTabViewed: (tab: string) => trackEvent('credits_tab_viewed', { tab }), profileUpdated: () => trackEvent('profile_updated'), }; /** * Context App Events */ export const ContextEvents = { documentCreated: (type: string) => trackEvent('document_created', { type }), documentDeleted: () => trackEvent('document_deleted'), documentPinned: (pinned: boolean) => trackEvent('document_pinned', { pinned }), spaceCreated: () => trackEvent('space_created'), spaceDeleted: () => trackEvent('space_deleted'), aiGenerated: () => trackEvent('ai_generated'), }; /** * SkillTree App Events */ export const SkillTreeEvents = { skillCreated: (branch: string) => trackEvent('skill_created', { branch }), skillDeleted: () => trackEvent('skill_deleted'), xpAdded: (xp: number, leveledUp: boolean) => trackEvent('xp_added', { xp, leveled_up: leveledUp }), }; /** * NutriPhi App Events */ export const NutriPhiEvents = { mealAdded: (mealType: string, inputType: string) => trackEvent('meal_added', { meal_type: mealType, input_type: inputType }), mealDeleted: () => trackEvent('meal_deleted'), photoAnalyzed: () => trackEvent('photo_analyzed'), textAnalyzed: () => trackEvent('text_analyzed'), goalsUpdated: () => trackEvent('goals_updated'), favoriteSaved: () => trackEvent('favorite_saved'), favoriteUsed: () => trackEvent('favorite_used'), }; /** * Planta App Events */ export const PlantaEvents = { plantAnalyzed: () => trackEvent('plant_analyzed'), plantCreated: () => trackEvent('plant_created'), plantDeleted: () => trackEvent('plant_deleted'), plantWatered: () => trackEvent('plant_watered'), }; /** * Questions App Events */ export const QuestionsEvents = { questionCreated: (depth: string) => trackEvent('question_created', { depth }), questionDeleted: () => trackEvent('question_deleted'), researchStarted: (depth: string) => trackEvent('research_started', { depth }), collectionCreated: () => trackEvent('collection_created'), collectionDeleted: () => trackEvent('collection_deleted'), }; /** * Photos App Events */ export const PhotosEvents = { photoUploaded: () => trackEvent('photo_uploaded'), photoFavorited: (favorited: boolean) => trackEvent('photo_favorited', { favorited }), photoDeleted: () => trackEvent('photo_deleted'), albumCreated: () => trackEvent('album_created'), albumDeleted: () => trackEvent('album_deleted'), photosAddedToAlbum: (count: number) => trackEvent('photos_added_to_album', { count }), photoRemovedFromAlbum: () => trackEvent('photo_removed_from_album'), filtersApplied: () => trackEvent('filters_applied'), }; /** * Storage App Events */ export const StorageEvents = { fileDownloaded: () => trackEvent('file_downloaded'), fileDeleted: () => trackEvent('file_deleted'), fileFavorited: (favorited: boolean) => trackEvent('file_favorited', { favorited }), folderDeleted: () => trackEvent('folder_deleted'), folderFavorited: (favorited: boolean) => trackEvent('folder_favorited', { favorited }), shareLinkCopied: () => trackEvent('share_link_copied'), shareLinkDeleted: () => trackEvent('share_link_deleted'), trashRestored: (type: string) => trackEvent('trash_restored', { type }), trashEmptied: () => trackEvent('trash_emptied'), searchPerformed: (resultsCount: number) => trackEvent('search_performed', { results: resultsCount }), viewModeChanged: (mode: string) => trackEvent('view_mode_changed', { mode }), }; /** * Mukke App Events */ export const MukkeEvents = { songUploaded: () => trackEvent('song_uploaded'), songUploadFailed: () => trackEvent('song_upload_failed'), songPlayed: () => trackEvent('song_played'), songFavorited: (favorited: boolean) => trackEvent('song_favorited', { favorited }), songDeleted: () => trackEvent('song_deleted'), playlistCreated: () => trackEvent('playlist_created'), playlistDeleted: () => trackEvent('playlist_deleted'), playlistPlayAll: () => trackEvent('playlist_play_all'), playlistShufflePlay: () => trackEvent('playlist_shuffle_play'), projectCreated: () => trackEvent('project_created'), projectDeleted: () => trackEvent('project_deleted'), projectExported: (format: string) => trackEvent('project_exported', { format }), }; /** * Zitare App Events */ export const ZitareEvents = { randomQuoteLoaded: () => trackEvent('random_quote_loaded'), quoteShared: (category: string) => trackEvent('quote_shared', { category }), quoteFavorited: (category: string) => trackEvent('quote_favorited', { category }), quoteUnfavorited: () => trackEvent('quote_unfavorited'), categoryViewed: (category: string) => trackEvent('category_viewed', { category }), searchPerformed: (resultsCount: number) => trackEvent('search_performed', { results: resultsCount }), listCreated: () => trackEvent('list_created'), listDeleted: () => trackEvent('list_deleted'), quoteLanguageChanged: (language: string) => trackEvent('quote_language_changed', { language }), }; /** * Presi App Events */ export const PresiEvents = { deckCreated: () => trackEvent('deck_created'), deckDeleted: () => trackEvent('deck_deleted'), slideCreated: () => trackEvent('slide_created'), slideEdited: () => trackEvent('slide_edited'), slideDeleted: () => trackEvent('slide_deleted'), slideReordered: (direction: 'up' | 'down') => trackEvent('slide_reordered', { direction }), presentationStarted: (slideCount: number) => trackEvent('presentation_started', { slide_count: slideCount }), presentationExited: (duration: number, slidesViewed: number) => trackEvent('presentation_exited', { duration_seconds: duration, slides_viewed: slidesViewed }), shareLinkCreated: () => trackEvent('share_link_created'), shareLinkCopied: () => trackEvent('share_link_copied'), shareLinkDeleted: () => trackEvent('share_link_deleted'), sharedDeckViewed: () => trackEvent('shared_deck_viewed'), }; /** * Subscription/Payment Events */ export const SubscriptionEvents = { pricingViewed: () => trackEvent('pricing_viewed'), planSelected: (plan: string) => trackEvent('plan_selected', { plan }), checkoutStarted: (plan: string) => trackEvent('checkout_started', { plan }), checkoutCompleted: (plan: string) => trackEvent('checkout_completed', { plan }), checkoutAbandoned: (plan: string) => trackEvent('checkout_abandoned', { plan }), subscriptionCanceled: (plan: string) => trackEvent('subscription_canceled', { plan }), trialStarted: () => trackEvent('trial_started'), trialEnded: (converted: boolean) => trackEvent('trial_ended', { converted }), }; /** * General App Events */ export const AppEvents = { appOpened: (app: string) => trackEvent('app_opened', { app }), themeChanged: (theme: 'light' | 'dark' | 'system') => trackEvent('theme_changed', { theme }), languageChanged: (language: string) => trackEvent('language_changed', { language }), feedbackSubmitted: (type: 'bug' | 'feature' | 'other') => trackEvent('feedback_submitted', { type }), helpOpened: () => trackEvent('help_opened'), settingsOpened: () => trackEvent('settings_opened'), shareClicked: (platform: string) => trackEvent('share_clicked', { platform }), };