Add semantic safe API for alert notifications (#144)

# Motivation
We want to provide new APIs that are semantically safe when sending alerts to APNs. These APIs should feel native in Swift and not leak too many APIs of the APNs interface.

# Modification
This PR creates a few new semantic types to represent currency types from the APNs API. Furthermore, the PR adds new types for the alert notification and a convenience method to send alert notifications with the APNSClient.

# Result
We can now send alert notifications.

Author: FranzBusch

Sources/APNSwift/APNSAlert.swift

@@ -140,6 +140,78 @@ public final class APNSClient<Decoder: APNSJSONDecoder, Encoder: APNSJSONEncoder
 // MARK: - Raw sending
 
 extension APNSClient {
+    /// Sends a notification to APNs.
+    ///
+    /// - Important: This method exposes the raw API for APNs. In general, this should be avoided
+    /// and the semantic-safe APIs should be used instead.
+    ///
+    /// - Parameters:
+    ///   - payload: The notification payload.
+    ///
+    ///   - deviceToken: The hexadecimal bytes that identify the user’s device. Your app receives the bytes for this device token
+    ///    when registering for remote notifications.
+    ///
+    ///   - pushType: The value of this header must accurately reflect the contents of your notification’s payload. If there’s a mismatch,
+    ///    or if the header is missing on required systems, APNs may return an error, delay the delivery of the notification, or drop it altogether.
+    ///
+    ///   - apnsID: A canonical UUID that identifies the notification. If there is an error sending the notification,
+    ///    APNs uses this value to identify the notification to your server. The canonical form is 32 lowercase hexadecimal digits,
+    ///    displayed in five groups separated by hyphens in the form 8-4-4-4-12. An example UUID is as follows: 123e4567-e89b-12d3-a456-42665544000.
+    ///    If you omit this, a new UUID is created by APNs and returned in the response.
+    ///
+    ///   - expiration: The date when the notification is no longer valid and can be discarded. If this value is not `none`,
+    ///    APNs stores the notification and tries to deliver it at least once, repeating the attempt as needed if it is unable to deliver the notification the first time.
+    ///    If the value is `immediately`, APNs treats the notification as if it expires immediately and does not store the notification or attempt to redeliver it.
+    ///
+    ///   - priority: The priority of the notification. If you omit this header, APNs sets the notification priority to `immediately`.
+    ///
+    ///   - topic: The topic for the notification. In general, the topic is your app’s bundle ID/app ID.
+    ///    It can have a suffix based on the type of push notification. If you’re using a certificate that supports PushKit VoIP or watchOS complication notifications,
+    ///    you must include this header with bundle ID of you app and if applicable, the proper suffix.
+    ///    If you’re using token-based authentication with APNs, you must include this header with the correct bundle ID and suffix combination.
+    ///
+    ///   - collapseID: An identifier you use to coalesce multiple notifications into a single notification for the user.
+    ///    Typically, each notification request causes a new notification to be displayed on the user’s device.
+    ///    When sending the same notification more than once, use the same value in this header to coalesce the requests.
+    ///    The value of this key must not exceed 64 bytes.
+    ///
+    ///   - deadline: Point in time by which sending the notification to APNs must complete.
+    ///
+    ///   - logger: The logger to use for sending this notification.
+    @discardableResult
+    @inlinable
+    public func send<Payload: Encodable>(
+        payload: Payload?,
+        deviceToken: String,
+        pushType: APNSPushType,
+        apnsID: UUID? = nil,
+        expiration: APNSNotificationExpiration,
+        priority: APNSPriority,
+        topic: String? = nil,
+        collapseID: String? = nil,
+        deadline: NIODeadline,
+        logger: Logger = _noOpLogger
+    ) async throws -> APNSResponse {
+        var byteBuffer = self.byteBufferAllocator.buffer(capacity: 0)
+
+        if let payload = payload {
+            try self.requestEncoder.encode(payload, into: &byteBuffer)
+        }
+
+        return try await self.send(
+            payload: byteBuffer,
+            deviceToken: deviceToken,
+            pushType: pushType.configuration.rawValue,
+            apnsID: apnsID,
+            expiration: expiration.expiration,
+            priority: priority.rawValue,
+            topic: topic,
+            collapseID: collapseID,
+            deadline: deadline,
+            logger: logger
+        )
+    }
+
     /// Sends a notification to APNs.
     ///
     /// - Important: This method exposes the raw API for APNs. In general, this should be avoided

Sources/APNSwift/APNSClient.swift

@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2022 the APNSwift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of APNSwift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// A struct representing the different expiration options for a notification.
+public struct APNSNotificationExpiration: Hashable {
+    /// The date at which the notification is no longer valid.
+    /// This value is a UNIX epoch expressed in seconds (UTC)
+    @usableFromInline
+    let expiration: Int?
+
+    /// Omits sending an expiration for APNs. APNs will default to a default value.
+    public static let none = Self(expiration: nil)
+
+    /// This tells APNs to not try to redeliver the notification.
+    ///
+    /// - Important: This does not mean that the notification is delivered immediately. Due to various network conditions
+    /// the message might be delivered with some delay.
+    public static let immediately = Self(expiration: 0)
+
+    /// This tells APNs that the notification expires at the given date.
+    ///
+    /// - Important: This does not mean that the notification is delivered until this date. Due to various network conditions
+    /// the message might be delivered after the passed date.
+    public static func timeIntervalSince1970InSeconds(_ timeInterval: Int) -> Self {
+        Self(expiration: timeInterval)
+    }
+}

Sources/APNSwift/APNSNotification.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the APNSwift open source project
+//
+// Copyright (c) 2022 the APNSwift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of APNSwift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// A struct which represents the supported priorities by APNs.
+public struct APNSPriority: Hashable {
+    /// The underlying raw value that is send to APNs.
+    @usableFromInline
+    internal let rawValue: Int
+
+    /// Specifies that the notification should be send immediately.
+    public static let immediately = Self(rawValue: 10)
+
+    /// Specifies that the notification should be send based on power considerations on the user’s device.
+    public static let consideringDevicePower = Self(rawValue: 5)
+}