Add convenience methods & types for sending error preset signals

Sources/TelemetryClient/Presets/ErrorCategory.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+/// An enumeration of common categories for errors. Each case has its own insight preset on TelemetryDeck.
+public enum ErrorCategory: String {
+    /// Represents an error that was thrown as an exception.
+    case thrownException = "thrown-exception"
+
+    /// Represents an error caused by user input.
+    case userInput = "user-input"
+
+    /// Represents an error caused by the application's state.
+    case appState = "app-state"
+}

Sources/TelemetryClient/Presets/IdentifiableError.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+/// A protocol that represents an error with an identifiable ID.
+public protocol IdentifiableError: Error {
+    /// A unique identifier for the error.
+    var id: String { get }
+}

Sources/TelemetryClient/Presets/TelemetryDeckExt.swift

@@ -0,0 +1,93 @@
+import Foundation
+
+extension TelemetryDeck {
+    /// Sends a telemetry signal indicating that an error has occurred.
+    ///
+    /// - Parameters:
+    ///   - id: A unique identifier for the error.
+    ///   - category: An optional category for the error. Default is `nil`.
+    ///   - message: An optional message describing the error. Default is `nil`.
+    ///   - parameters: Additional parameters to include with the signal. Default is an empty dictionary.
+    ///   - floatValue: An optional floating-point value to include with the signal. Default is `nil`.
+    ///   - customUserID: An optional custom user identifier. If provided, it overrides the default user identifier from the configuration. Default is `nil`.
+    public static func errorOccurred(
+        id: String,
+        category: ErrorCategory? = nil,
+        message: String? = nil,
+        parameters: [String: String] = [:],
+        floatValue: Double? = nil,
+        customUserID: String? = nil
+    ) {
+        var errorParameters: [String: String] = ["TelemetryDeck.Error.id": id]
+
+        if let category {
+            errorParameters["TelemetryDeck.Error.category"] = category.rawValue
+        }
+
+        if let message {
+            errorParameters["TelemetryDeck.Error.message"] = message
+        }
+
+        self.signal(
+            "TelemetryDeck.Error.occurred",
+            parameters: errorParameters.merging(parameters) { $1 },
+            floatValue: floatValue,
+            customUserID: customUserID
+        )
+    }
+
+    /// Sends a telemetry signal indicating that an identifiable error has occurred.
+    ///
+    /// - Parameters:
+    ///   - identifiableError: The error that conforms to `IdentifiableError`.
+    ///   - category: The category of the error. Default is `.thrownException`.
+    ///   - parameters: Additional parameters to include with the signal. Default is an empty dictionary.
+    ///   - floatValue: An optional floating-point value to include with the signal. Default is `nil`.
+    ///   - customUserID: An optional custom user identifier. If provided, it overrides the default user identifier from the configuration. Default is `nil`.
+    public static func errorOccurred(
+        identifiableError: IdentifiableError,
+        category: ErrorCategory = .thrownException,
+        parameters: [String: String] = [:],
+        floatValue: Double? = nil,
+        customUserID: String? = nil
+    ) {
+        self.errorOccurred(
+            id: identifiableError.id,
+            category: category,
+            message: identifiableError.localizedDescription,
+            parameters: parameters,
+            floatValue: floatValue,
+            customUserID: customUserID
+        )
+    }
+
+    /// Sends a telemetry signal indicating that an identifiable error has occurred, with an optional message.
+    ///
+    /// - Parameters:
+    ///   - identifiableError: The error that conforms to `IdentifiableError`.
+    ///   - category: The category of the error. Default is `.thrownException`.
+    ///   - message: An optional message describing the error. Default is `nil`.
+    ///   - parameters: Additional parameters to include with the signal. Default is an empty dictionary.
+    ///   - floatValue: An optional floating-point value to include with the signal. Default is `nil`.
+    ///   - customUserID: An optional custom user identifier. If provided, it overrides the default user identifier from the configuration. Default is `nil`.
+    ///
+    ///  - Note: Use this overload if you want to provide a custom `message` parameter. Prefer ``errorOccurred(identifiableError:category:parameters:floatValue:customUserID:)`` to send `error.localizedDescription` as the `message` automatically.
+    @_disfavoredOverload
+    public static func errorOccurred(
+        identifiableError: IdentifiableError,
+        category: ErrorCategory = .thrownException,
+        message: String? = nil,
+        parameters: [String: String] = [:],
+        floatValue: Double? = nil,
+        customUserID: String? = nil
+    ) {
+        self.errorOccurred(
+            id: identifiableError.id,
+            category: category,
+            message: message,
+            parameters: parameters,
+            floatValue: floatValue,
+            customUserID: customUserID
+        )
+    }
+}

Sources/TelemetryClient/TelemetryDeck.swift

@@ -24,7 +24,12 @@ public enum TelemetryDeck {
     ///   - customUserID: An optional string specifying a custom user identifier. If provided, it will override the default user identifier from the configuration. Default is `nil`.
     ///
     /// This function wraps the `TelemetryManager.send` method, providing a streamlined way to send signals from anywhere in the app.
-    public static func signal(_ signalName: String, parameters: [String: String] = [:], floatValue: Double? = nil, customUserID: String? = nil) {
+    public static func signal(
+        _ signalName: String,
+        parameters: [String: String] = [:],
+        floatValue: Double? = nil,
+        customUserID: String? = nil
+    ) {
         TelemetryManager.send(signalName, for: customUserID, floatValue: floatValue, with: parameters)
     }
 }