Code review improvements

Author: jmarek41

Sources/FTAPIKit/Endpoint.swift

@@ -10,6 +10,10 @@ import Foundation
 /// cases and information about one endpoint is spreaded all over the files. Also,
 /// structs offer us generated initializers, which is very helpful.
 ///
+/// - Important: Each endpoint should conform to at most one body-providing protocol
+///   (``DataEndpoint``, ``URLEncodedEndpoint``, ``MultipartEndpoint``, ``RequestEndpoint``,
+///   ``UploadEndpoint``). Conforming to multiple body protocols results in undefined body selection.
+///
 public protocol Endpoint {
 
     /// URL path component without base URI.
@@ -35,34 +39,54 @@ public extension Endpoint {
 }
 
 /// ``DataEndpoint`` transmits data provided in the ``FTAPIKit/DataEndpoint/body`` property without any further encoding.
+/// - Note: Default HTTP method is ``FTAPIKit/HTTPMethod/post``.
 public protocol DataEndpoint: Endpoint {
     var body: Data { get }
 }
 
+public extension DataEndpoint {
+    var method: HTTPMethod { .post }
+}
+
 /// ``UploadEndpoint`` will send the provided file to the API.
 ///
 /// - Note: If the standard implementation is used, `URLSession.uploadTask` methods will be used.
+/// Default HTTP method is ``FTAPIKit/HTTPMethod/post``.
 public protocol UploadEndpoint: Endpoint {
 
     /// File which will be sent.
     var file: URL { get }
 }
 
+public extension UploadEndpoint {
+    var method: HTTPMethod { .post }
+}
+
 /// Endpoint which will be sent as a multipart HTTP request.
 ///
 /// - Note: If the standard implementation is used, the body parts will be merged into a temporary file, which will
 /// then be transformed to an input stream and passed to the request as a `httpBodyStream`.
+/// Default HTTP method is ``FTAPIKit/HTTPMethod/post``.
 public protocol MultipartEndpoint: Endpoint {
 
     /// List of individual body parts.
     var parts: [MultipartBodyPart] { get }
 }
 
+public extension MultipartEndpoint {
+    var method: HTTPMethod { .post }
+}
+
 /// The body of the endpoint with the URL query format.
+/// - Note: Default HTTP method is ``FTAPIKit/HTTPMethod/post``.
 public protocol URLEncodedEndpoint: Endpoint {
     var body: URLQuery { get }
 }
 
+public extension URLEncodedEndpoint {
+    var method: HTTPMethod { .post }
+}
+
 /// An abstract representation of endpoint, body of which is represented by Swift encodable type. It serves as an
 /// abstraction between the ``URLServer`` protocol and more specific ``Endpoint`` conforming protocols.
 /// Do not use this protocol to represent an encodable endpoint, use ``RequestEndpoint`` instead.
@@ -90,7 +114,7 @@ public protocol ResponseEndpoint: Endpoint {
 public protocol RequestEndpoint: EncodableEndpoint {
     /// Associated type describing the encodable request model for serialization. The associated type is derived
     /// from the body property.
-    associatedtype Request: Encodable
+    associatedtype Request: Encodable & Sendable
     /// Generic encodable model, which will be sent in the body of the request.
     var request: Request { get }
 }

Sources/FTAPIKit/URLServer+Async.swift

@@ -7,7 +7,8 @@ public extension URLServer {
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
     /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
-    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
+    ///   `EncodingError` if request building fails, or an error from ``RequestConfiguring/configure(_:)``
+    ///   if configuration fails.
     func call(endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws {
         _ = try await execute(endpoint: endpoint, configuring: configuring)
     }
@@ -17,7 +18,8 @@ public extension URLServer {
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
     /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
-    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
+    ///   `EncodingError` if request building fails, or an error from ``RequestConfiguring/configure(_:)``
+    ///   if configuration fails.
     /// - Returns: Plain data returned with the HTTP Response
     func call(data endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws -> Data {
         try await execute(endpoint: endpoint, configuring: configuring).data
@@ -28,7 +30,8 @@ public extension URLServer {
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
     /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
-    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
+    ///   `EncodingError` if request building fails, or an error from ``RequestConfiguring/configure(_:)``
+    ///   if configuration fails.
     /// - Returns: Instance of the required type
     func call<EP: ResponseEndpoint>(response endpoint: EP, configuring: RequestConfiguring? = nil) async throws -> EP.Response {
         let result = try await execute(endpoint: endpoint, configuring: configuring)
@@ -46,10 +49,11 @@ public extension URLServer {
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
     /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
-    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
+    ///   `EncodingError` if request building fails, or an error from ``RequestConfiguring/configure(_:)``
+    ///   if configuration fails.
     /// - Returns: The location of a temporary file where the server's response is stored.
     ///   You must move this file or open it for reading before the async function returns. Otherwise, the file
-    ///   is deleted, and the data is lost.
+    ///   is deleted, and the data is lost. For automatic file management, use ``download(endpoint:destination:configuring:)`` instead.
     func download(endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws -> URL {
         let (urlRequest, observers) = try await prepareObservers(endpoint: endpoint, configuring: configuring)
 
@@ -67,6 +71,19 @@ public extension URLServer {
 
         return localURL
     }
+
+    /// Downloads a file from the specified endpoint and moves it to the given destination.
+    /// - Parameters:
+    ///   - endpoint: The endpoint
+    ///   - destination: The file URL where the downloaded file should be stored
+    ///   - configuring: Optional request configuration to apply before sending
+    /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
+    ///   `EncodingError` if request building fails, or an error from ``RequestConfiguring/configure(_:)``
+    ///   if configuration fails.
+    func download(endpoint: Endpoint, destination: URL, configuring: RequestConfiguring? = nil) async throws {
+        let tempURL = try await download(endpoint: endpoint, configuring: configuring)
+        try FileManager.default.moveItem(at: tempURL, to: destination)
+    }
 }
 
 // MARK: - Private helpers

Templates/Makefile

@@ -3,6 +3,7 @@ INSTALL_DIR = ~/Library/Developer/Xcode/Templates/File\ Templates/FTAPIKit
 install:
 	mkdir -p $(INSTALL_DIR)
 	cp -R Endpoints.xctemplate $(INSTALL_DIR)/
+	@echo "Templates installed to $(INSTALL_DIR)"
 
 uninstall:
 	rm -rf $(INSTALL_DIR)

Tests/FTAPIKitTests/EndpointTypeTests.swift

@@ -59,4 +59,14 @@ struct EndpointTypeTests {
         let url = try await server.download(endpoint: endpoint)
         #expect(FileManager.default.fileExists(atPath: url.path))
     }
+
+    @Test
+    func downloadEndpointToDestination() async throws {
+        let server = HTTPBinServer()
+        let endpoint = ImageEndpoint()
+        let destination = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        try await server.download(endpoint: endpoint, destination: destination)
+        #expect(FileManager.default.fileExists(atPath: destination.path))
+        try FileManager.default.removeItem(at: destination)
+    }
 }

Tests/FTAPIKitTests/Mockups/Endpoints.swift

@@ -97,3 +97,10 @@ struct TestUploadEndpoint: UploadEndpoint {
 struct ImageEndpoint: Endpoint {
     let path = "image/jpeg"
 }
+
+/// Endpoint that will succeed at the network level but fail during decoding,
+/// because the response from `/get` does not match `[Int]`.
+struct DecodingFailureEndpoint: ResponseEndpoint {
+    typealias Response = [Int]
+    let path = "get"
+}

Tests/FTAPIKitTests/NetworkObserverTests.swift

@@ -60,6 +60,24 @@ struct NetworkObserverTests {
         #expect(mockObserver.didFailCount == 1, "didFail should be called on failure")
     }
 
+    @Test
+    func observerReceivesResponseBeforeDecodingFailure() async {
+        let mockObserver = MockNetworkObserver()
+        let server = HTTPBinServerWithObservers(observers: [mockObserver])
+        let endpoint = DecodingFailureEndpoint()
+
+        do {
+            _ = try await server.call(response: endpoint)
+            Issue.record("Expected decoding error")
+        } catch {
+            // Expected decoding error
+        }
+
+        #expect(mockObserver.willSendCount == 1, "willSendRequest should be called once")
+        #expect(mockObserver.didReceiveCount == 1, "didReceiveResponse should be called even when decoding fails")
+        #expect(mockObserver.didFailCount == 1, "didFail should be called for decoding error")
+    }
+
     @Test
     func multipleObserversAllReceiveCallbacks() async throws {
         let observer1 = MockNetworkObserver()