Feature: New Stats

Modules/Package.swift

@@ -11,6 +11,7 @@ let package = Package(
         .library(name: "AsyncImageKit", targets: ["AsyncImageKit"]),
         .library(name: "DesignSystem", targets: ["DesignSystem"]),
         .library(name: "FormattableContentKit", targets: ["FormattableContentKit"]),
+        .library(name: "JetpackStats", targets: ["JetpackStats"]),
         .library(name: "JetpackStatsWidgetsCore", targets: ["JetpackStatsWidgetsCore"]),
         .library(name: "NotificationServiceExtensionCore", targets: ["NotificationServiceExtensionCore"]),
         .library(name: "ShareExtensionCore", targets: ["ShareExtensionCore"]),
@@ -49,7 +50,7 @@ let package = Package(
         .package(url: "https://github.com/wordpress-mobile/NSURL-IDN", revision: "b34794c9a3f32312e1593d4a3d120572afa0d010"),
         .package(
             url: "https://github.com/wordpress-mobile/WordPressKit-iOS",
-            revision: "2b7d4f6acf2641b671c66b20873f5935f22210ed"
+            revision: "440d94e3a3d6f9f39035a371984e088a2fb42a32"
         ),
         .package(url: "https://github.com/zendesk/support_sdk_ios", from: "8.0.3"),
         // We can't use wordpress-rs branches nor commits here. Only tags work.
@@ -93,6 +94,14 @@ let package = Package(
             // Set to v5 to avoid @Sendable warnings and errors
             swiftSettings: [.swiftLanguageMode(.v5)]
         ),
+        .target(
+            name: "JetpackStats",
+            dependencies: [
+                "WordPressUI",
+                .product(name: "WordPressKit", package: "WordPressKit-iOS"),
+            ],
+            resources: [.process("Resources")]
+        ),
         .target(name: "JetpackStatsWidgetsCore", swiftSettings: [.swiftLanguageMode(.v5)]),
         .target(
             name: "ShareExtensionCore",
@@ -171,6 +180,7 @@ let package = Package(
             dependencies: ["AsyncImageKit", "WordPressUI", "WordPressShared"],
             resources: [.process("Resources")]
         ),
+        .testTarget(name: "JetpackStatsTests", dependencies: ["JetpackStats"]),
         .testTarget(name: "JetpackStatsWidgetsCoreTests", dependencies: [.target(name: "JetpackStatsWidgetsCore")], swiftSettings: [.swiftLanguageMode(.v5)]),
         .testTarget(name: "DesignSystemTests", dependencies: [.target(name: "DesignSystem")], swiftSettings: [.swiftLanguageMode(.v5)]),
         .testTarget(
@@ -276,6 +286,7 @@ enum XcodeSupport {
             "DesignSystem",
             "BuildSettingsKit",
             "FormattableContentKit",
+            "JetpackStats",
             "JetpackStatsWidgetsCore",
             "NotificationServiceExtensionCore",
             "SFHFKeychainUtils",

Modules/Sources/JetpackStats/Analytics/MockStatsTracker.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// A no-op implementation of StatsTracker for testing and development
+final class MockStatsTracker: StatsTracker, Sendable {
+    static let shared = MockStatsTracker()
+
+    private init() {}
+
+    func send(_ event: StatsEvent, properties: [String: String]) {
+#if DEBUG
+        // In debug builds, print events to console for debugging
+        debugPrint("[StatsTracker] Event: \(event) \(properties)")
+#endif
+    }
+}

Modules/Sources/JetpackStats/Analytics/StatsEvent.swift

@@ -0,0 +1,191 @@
+import Foundation
+
+/// Analytics events for tracking user interactions within the Stats module
+///
+/// IMPORTANT: Do not include personally identifiable information (PII) in analytics events.
+/// This includes but is not limited to:
+/// - User IDs, author IDs, or any unique identifiers
+/// - Email addresses
+/// - URLs that might contain sensitive information
+/// - Post IDs or content identifiers
+///
+/// Instead, track only:
+/// - Event types and categories
+/// - Navigation sources
+/// - UI states and configurations
+/// - Aggregated metrics
+public enum StatsEvent {
+    // MARK: - Screen View Events
+
+    /// Main stats screen shown
+    case statsMainScreenShown
+
+    /// Traffic tab shown
+    case trafficTabShown
+
+    /// Realtime tab shown
+    case realtimeTabShown
+
+    /// Subscribers tab shown
+    case subscribersTabShown
+
+    /// Post details screen shown
+    case postDetailsScreenShown
+
+    /// Author stats screen shown
+    case authorStatsScreenShown
+
+    /// Archive stats screen shown
+    case archiveStatsScreenShown
+
+    /// External link stats screen shown
+    case externalLinkStatsScreenShown
+
+    /// Referrer stats screen shown
+    case referrerStatsScreenShown
+
+    // MARK: - Date Range Events
+
+    /// Date range preset selected
+    /// - Parameters:
+    ///   - "selected_preset": The preset selected (e.g., "last_7_days", "last_28_days", "last_90_days", "last_365_days")
+    case dateRangePresetSelected
+
+    /// Custom date range selected
+    /// - Parameters:
+    ///   - "start_date": Start date in ISO format
+    ///   - "end_date": End date in ISO format
+    case customDateRangeSelected
+
+    // MARK: - Card Events
+
+    /// Card shown on screen
+    /// - Parameters:
+    ///   - "card_type": Type of card (e.g., "chart", "top_list")
+    ///   - "configuration": Card configuration details (e.g., metrics, item type)
+    case cardShown
+
+    /// Card added to dashboard
+    /// - Parameters:
+    ///   - "card_type": Type of card (e.g., "chart", "top_list")
+    case cardAdded
+
+    /// Card removed from dashboard
+    /// - Parameters:
+    ///   - "card_type": Type of card
+    case cardRemoved
+
+    // MARK: - Chart Events
+
+    /// Chart type changed
+    /// - Parameters:
+    ///   - "from_type": Previous chart type (e.g., "line", "bar")
+    ///   - "to_type": New chart type
+    case chartTypeChanged
+
+    /// Chart metric selected
+    /// - Parameters:
+    ///   - "metric": The metric selected (e.g., "visitors", "views", "likes")
+    case chartMetricSelected
+
+    // MARK: - List Events
+
+    /// Top list item tapped
+    /// - Parameters:
+    ///   - "item_type": Type of item (e.g., "posts_and_pages", "authors", "locations", "referrers")
+    ///   - "metric": The metric being sorted by
+    case topListItemTapped
+
+    // MARK: - Navigation Events
+
+    /// Stats tab selected
+    /// - Parameters:
+    ///   - "tab_name": Name of the tab selected
+    ///   - "previous_tab": Name of the previous tab
+    case statsTabSelected
+
+    // MARK: - Error Events
+
+    /// Error encountered
+    /// - Parameters:
+    ///   - "error_type": Type of error (e.g., "network", "parsing", "permission")
+    ///   - "error_code": Specific error code if available
+    ///   - "screen": Where the error occurred
+    case errorEncountered
+}
+
+// MARK: - StatsTracker Protocol
+
+/// Protocol for tracking analytics events in the Stats module
+public protocol StatsTracker: Sendable {
+    /// Send an analytics event
+    /// - Parameters:
+    ///   - event: The event to track
+    ///   - properties: Additional properties for the event
+    func send(_ event: StatsEvent, properties: [String: String])
+}
+
+// MARK: - StatsTracker Convenience
+
+extension StatsTracker {
+    /// Convenience method to send events without properties
+    func send(_ event: StatsEvent) {
+        send(event, properties: [:])
+    }
+}
+
+// MARK: - Private Extensions
+
+extension DateIntervalPreset {
+    /// Analytics tracking name for the preset
+    var analyticsName: String {
+        switch self {
+        case .today: "today"
+        case .thisWeek: "this_week"
+        case .thisMonth: "this_month"
+        case .thisQuarter: "this_quarter"
+        case .thisYear: "this_year"
+        case .last7Days: "last_7_days"
+        case .last28Days: "last_28_days"
+        case .last30Days: "last_30_days"
+        case .last90Days: "last_90_days"
+        case .last6Months: "last_6_months"
+        case .last12Months: "last_12_months"
+        case .last3Years: "last_3_years"
+        case .last10Years: "last_10_years"
+        }
+    }
+}
+
+extension TopListItemType {
+    /// Analytics tracking name for the item type
+    var analyticsName: String {
+        switch self {
+        case .postsAndPages: "posts_and_pages"
+        case .authors: "authors"
+        case .referrers: "referrers"
+        case .locations: "locations"
+        case .videos: "videos"
+        case .externalLinks: "external_links"
+        case .searchTerms: "search_terms"
+        case .fileDownloads: "file_downloads"
+        case .archive: "archive"
+        }
+    }
+}
+
+extension SiteMetric {
+    /// Analytics tracking name for the metric
+    var analyticsName: String {
+        switch self {
+        case .views: "views"
+        case .visitors: "visitors"
+        case .likes: "likes"
+        case .comments: "comments"
+        case .posts: "posts"
+        case .timeOnSite: "time_on_site"
+        case .bounceRate: "bounce_rate"
+        case .downloads: "downloads"
+        }
+    }
+}

Modules/Sources/JetpackStats/Analytics/StatsTracker+ErrorTracking.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+extension StatsTracker {
+    /// Convenience method to track errors with automatic type detection
+    /// - Parameters:
+    ///   - error: The error to track
+    ///   - screen: The screen where the error occurred
+    func trackError(_ error: Error, screen: String) {
+        let errorType: String
+        let errorCode = (error as NSError).code
+
+        // Determine error type based on the error instance
+        switch error {
+        case let urlError as URLError:
+            errorType = urlErrorType(urlError)
+        case is DecodingError:
+            errorType = "parsing"
+        case is CancellationError:
+            return
+        default:
+            // Check for common error domains
+            let nsError = error as NSError
+            switch nsError.domain {
+            case NSCocoaErrorDomain:
+                errorType = "cocoa_\(errorCode)"
+            case NSURLErrorDomain:
+                errorType = "url_\(errorCode)"
+            default:
+                errorType = "unknown"
+            }
+        }
+
+        send(.errorEncountered, properties: [
+            "error_type": errorType,
+            "error_code": "\(errorCode)",
+            "screen": screen
+        ])
+    }
+
+    /// Determine specific network error type
+    private func urlErrorType(_ error: URLError) -> String {
+        switch error.code {
+        case .notConnectedToInternet: "network_offline"
+        case .timedOut: "network_timeout"
+        case .cannotFindHost, .cannotConnectToHost: "network_host_unreachable"
+        case .networkConnectionLost: "network_connection_lost"
+        case .dnsLookupFailed: "network_dns_failed"
+        case .httpTooManyRedirects: "network_too_many_redirects"
+        case .resourceUnavailable: "network_resource_unavailable"
+        case .dataNotAllowed: "network_data_not_allowed"
+        case .secureConnectionFailed: "network_ssl_failed"
+        default: "other"
+        }
+    }
+}

Modules/Sources/JetpackStats/Cards/CardConfigurationDelegate.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+enum MoveDirection {
+    case up
+    case down
+    case top
+    case bottom
+}
+
+@MainActor
+protocol CardConfigurationDelegate: AnyObject {
+    func saveConfiguration(for card: any TrafficCardViewModel)
+    func deleteCard(_ card: any TrafficCardViewModel)
+    func moveCard(_ card: any TrafficCardViewModel, direction: MoveDirection)
+}

Modules/Sources/JetpackStats/Cards/CardViewModel.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+@MainActor
+protocol TrafficCardViewModel: AnyObject {
+    var id: UUID { get }
+    var dateRange: StatsDateRange { get set }
+    var isEditing: Bool { get set }
+    var configurationDelegate: CardConfigurationDelegate? { get set }
+}