From 844a85f88c0827fd13160e8e006ca2f49592729c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 14 Aug 2026 08:33:32 +0200
Subject: [PATCH] Added the Event type to the Analytics type in the
 Infrastructure package.

---
 .../Sources/Public/Types/Analytics.swift      |  55 +++------
 .../Types/Analytics/AnalyticsAttribute.swift  |  31 ++++++
 .../Types/Analytics/AnalyticsEvent.swift      |  55 +++++++++
 .../Types/Analytics/AnalyticsEventTests.swift | 105 ++++++++++++++++++
 4 files changed, 206 insertions(+), 40 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift

diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 8839c63..9d127d9 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -1,16 +1,10 @@
 import Foundation
 
-/// The analytics tracker a page embeds: where the script loads from, which site it reports as, which domains it reports from, and how it behaves.
+/// The Umami analytics tracker a page embeds as a deferred `<script>` in its document head.
 ///
-/// A page carries it as an optional value so the ``Page`` scaffolding renders the tracker's deferred `<script>` in the document head, or omits it
-/// when the page has none. The attribute names follow the Umami tracker convention. The three behavior flags default to on, and each renders its
-/// `data-` attribute only when enabled, since the tracker treats an absent attribute as off. Recorder mode, by contrast, defaults to off; when
-/// activated, the page embeds a second deferred script that loads the session recorder from the tracker's origin.
+/// The behavior flags default to on and render their `data-` attributes only when enabled, since the tracker treats an absent attribute as off.
+/// Recorder mode defaults to off; when on, the page embeds a second deferred script loading the session recorder from the tracker's origin.
 public struct Analytics: Sendable {
-    
-    // MARK: Type aliases
-    
-    public typealias Attribute = (name: String, value: String)
 
     // MARK: Properties
 
@@ -66,47 +60,30 @@ public struct Analytics: Sendable {
 
     // MARK: Computed
 
-    /// The tracker script's attributes, in a stable order: the website id and the reporting domains, then each enabled behavior flag.
-    ///
-    /// A disabled flag is left out entirely, since the tracker treats an absent attribute as off. Each `name` is a full attribute name following the
-    /// Umami `data-` convention, which a page applies to the deferred script verbatim — so the page renders the tracker without knowing its shape.
+    /// The tracker script's attributes: the website id and reporting domains, then each enabled behavior flag; disabled flags are omitted.
     public var attributes: [Attribute] {
-        var attributes = [(
-            name: "data-website-id",
-            value: websiteID
-        ), (
-            name: "data-domains",
-            value: domains
-        )]
+        var attributes: [Attribute] = [
+            .init("data-website-id", value: websiteID),
+            .init("data-domains", value: domains)
+        ]
 
         if excludeHash {
-            attributes.append((
-                name: "data-exclude-hash",
-                value: "true"
-            ))
+            attributes.append(.init("data-exclude-hash", value: "true"))
         }
 
         if doNotTrack {
-            attributes.append((
-                name: "data-do-not-track",
-                value: "true"
-            ))
+            attributes.append(.init("data-do-not-track", value: "true"))
         }
 
         if performance {
-            attributes.append((
-                name: "data-performance",
-                value: "true"
-            ))
+            attributes.append(.init("data-performance", value: "true"))
         }
 
         return attributes
     }
 
-    /// The origin the tracker is served from (scheme and host, plus any explicit port), derived from the ``scriptURL``, or `nil` when the
-    /// URL carries no scheme or host.
-    ///
-    /// A page renders it as a `preconnect` hint before the tracker script, so the connection handshake starts as early as possible.
+    /// The origin the tracker is served from (scheme, host, and any explicit port), derived from the ``scriptURL``; `nil` when the URL
+    /// carries no scheme or host. Rendered as a `preconnect` hint before the tracker script.
     public var origin: String? {
         guard
             let url = URL(string: scriptURL),
@@ -121,10 +98,8 @@ public struct Analytics: Sendable {
         return "\(scheme)://\(host)\(port)"
     }
 
-    /// The URL the session recorder script is loaded from, derived from the tracker's ``origin``, or `nil` when ``recorder`` mode is off
-    /// or no origin can be derived from the ``scriptURL``.
-    ///
-    /// A page renders it as a second deferred script tag after the tracker script, carrying only the `data-website-id` attribute.
+    /// The URL the session recorder script is loaded from; `nil` when ``recorder`` mode is off or no ``origin`` can be derived.
+    /// Rendered as a second deferred script carrying only the `data-website-id` attribute.
     public var recorderScriptURL: String? {
         guard recorder, let origin else {
             return nil
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
new file mode 100644
index 0000000..370329d
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
@@ -0,0 +1,31 @@
+extension Analytics {
+    /// A name-value pair rendered as an HTML attribute.
+    ///
+    /// The ``name`` is a full `data-` attribute name applied verbatim — except inside ``Analytics/Event/properties``, where it is the bare
+    /// key the event prefixes on render.
+    public struct Attribute: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The attribute's name.
+        public let name: String
+
+        /// The attribute's value.
+        public let value: String
+
+        // MARK: Initializers
+
+        /// Creates a tracker attribute.
+        /// - Parameters:
+        ///   - name: the attribute's name.
+        ///   - value: the attribute's value.
+        public init(
+            _ name: String,
+            value: String
+        ) {
+            self.name = name
+            self.value = value
+        }
+
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
new file mode 100644
index 0000000..c552cfa
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
@@ -0,0 +1,55 @@
+extension Analytics {
+    /// An interaction a page reports to the tracker, rendered as `data-` attributes on the element that carries it.
+    ///
+    /// The tracker records a click on any element carrying `data-umami-event`; each `data-umami-event-<name>` beside it becomes a property
+    /// the report can be broken down by. Reports group by ``name``, so related interactions should share one name and differ by a property.
+    public struct Event: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The event's name, which is what a report groups by.
+        public let name: String
+
+        /// The event's properties, in declaration order, which is the order they render.
+        ///
+        /// Each ``Attribute/name`` is the bare key — `set`, not `data-umami-event-set`; ``attributes`` adds the prefix.
+        public let properties: [Attribute]
+
+        // MARK: Initializers
+
+        /// Creates an event.
+        /// - Parameters:
+        ///   - name: the event's name, which is what a report groups by.
+        ///   - properties: the event's properties as bare keys — `set`, not `data-umami-event-set` — rendered in the order written.
+        ///     Empty by default.
+        public init(
+            name: String,
+            properties: KeyValuePairs<String, String> = [:]
+        ) {
+            self.name = name
+            self.properties = properties.map {
+                .init($0.key, value: $0.value)
+            }
+        }
+
+        // MARK: Computed
+
+        /// The event's attributes — the event name, then each property — as full `data-` attribute names an element applies verbatim.
+        public var attributes: [Attribute] {
+            [.init(Constant.Name.prefix, value: name)]
+            + properties.map {
+                .init("\(Constant.Name.prefix)-\($0.name)", value: $0.value)
+            }
+        }
+
+    }
+}
+
+// MARK: - Constants
+
+private enum Constant {
+    enum Name {
+        /// The attribute name the tracker watches for, and the prefix each property renders under.
+        static let prefix = "data-umami-event"
+    }
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift
new file mode 100644
index 0000000..6256ac6
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift
@@ -0,0 +1,105 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "Analytics.Event type",
+    .tags(.type)
+)
+struct AnalyticsEventTests {
+
+    // MARK: Computed tests
+
+    @Test
+    func `renders the event name alone when it carries no properties`() {
+        let event = Analytics.Event(name: "instagram")
+
+        #expect(event.attributes.count == 1)
+        #expect(event.attributes[0] == Analytics.Attribute(
+            "data-umami-event",
+            value: "instagram"
+        ))
+    }
+
+    @Test
+    func `renders each property as an attribute suffixed by its key`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event.attributes.count == 2)
+        #expect(event.attributes[1] == Analytics.Attribute(
+            "data-umami-event-set",
+            value: "avc-xi"
+        ))
+    }
+
+    @Test
+    func `renders the name first, then the properties in the order given`() {
+        let event = Analytics.Event(
+            name: "interview",
+            properties: [
+                "placement": "credit",
+                "locale": "en",
+            ]
+        )
+
+        // The order is the rendered attribute order, which a dictionary would leave to churn between builds.
+        #expect(event.attributes.map(\.name) == [
+            "data-umami-event",
+            "data-umami-event-placement",
+            "data-umami-event-locale",
+        ])
+        #expect(event.attributes.map(\.value) == ["interview", "credit", "en"])
+    }
+
+    // MARK: Equatable tests
+
+    @Test
+    func `matches an event rendering the same attributes`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event == Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        ))
+    }
+
+    @Test(arguments: [
+        Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-ix"]
+        ),
+        Analytics.Event(
+            name: "playlist",
+            properties: ["show": "avc-xi"]
+        ),
+        Analytics.Event(
+            name: "apple_music",
+            properties: ["set": "avc-xi"]
+        ),
+        Analytics.Event(name: "playlist"),
+        Analytics.Event(
+            name: "playlist",
+            properties: [
+                "set": "avc-xi",
+                "placement": "strip",
+            ]
+        ),
+    ])
+    func `differs from an event rendering anything else`(
+        from other: Analytics.Event
+    ) {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event != other)
+    }
+
+}