CR updates

Author: jmarek41

.gitignore

@@ -34,11 +34,4 @@ FTAPIKit.xcodeproj
 # Claude Code
 .claude
 
-# fastlane
-fastlane/report.xml
-fastlane/Preview.html
-fastlane/screenshots/
-fastlane/test_output/
-fastlane/README.md
-
 *.xcuserstate

CLAUDE.md

@@ -86,7 +86,7 @@ The framework is built around two core protocols:
 ### Module Organization
 
 **Source Structure** (`Sources/FTAPIKit/`):
-- Core protocols: `Server.swift`, `Endpoint.swift`
+- Core protocols: `URLServer.swift`, `Endpoint.swift`
 - Request building: `URLRequestBuilder.swift`, `RequestConfiguring.swift`
 - Async execution: `URLServer+Async.swift`, `URLServer+Download.swift`
 - Observers: `NetworkObserver.swift`

README.md

@@ -1,4 +1,4 @@
-<img align="right" alt="FTAPIKit logo" src="Sources/FTAPIKit/Documentation.docc/Resources/FTAPIKit.svg">
+<img align="right" alt="FTAPIKit logo" src="Sources/FTAPIKit/Documentation.docc/Resources/FTAPIKit.svg" height="65">
 
 # FTAPIKit
 
@@ -45,10 +45,11 @@ are separated in various protocols for convenience.
 
 - `Endpoint` protocol has empty body. Typically used in `GET` endpoints.
 - `DataEndpoint` sends provided data in body.
-- `UploadEndpoint` uploads file using `InputStream`.
+- `UploadEndpoint` uploads file from a URL using `URLSession` upload task.
 - `MultipartEndpoint` combines body parts into `InputStream` and sends them to server.
   Body parts are represented by `MultipartBodyPart` struct and provided to the endpoint
   in an array.
+- `URLEncodedEndpoint` sends body in URL query format.
 - `RequestEndpoint` has encodable request which is encoded using encoding
   of the `URLServer` instance.
 
@@ -127,14 +128,7 @@ When we have server and endpoint defined we can call the web service using async
 let server = HTTPBinServer()
 let endpoint = UpdateUserEndpoint(request: user)
 
-Task {
-    do {
-        let updatedUser = try await server.call(response: endpoint)
-        // Handle success
-    } catch {
-        // Handle error
-    }
-}
+let updatedUser = try await server.call(response: endpoint)
 ```
 
 ### Async buildRequest
@@ -220,6 +214,38 @@ struct MyServer: URLServer {
 }
 ```
 
+### Error Handling
+
+The framework uses the `APIError` protocol for error handling. The default implementation `APIError.Standard` covers common cases:
+
+```swift
+do {
+    let response = try await server.call(response: endpoint)
+} catch let error as APIError.Standard {
+    switch error {
+    case .connection(let urlError):
+        // Network connectivity issue
+    case .client(let statusCode, _, _):
+        // 4xx client error
+    case .server(let statusCode, _, _):
+        // 5xx server error
+    case .decoding(let decodingError):
+        // Response parsing failed
+    default:
+        break
+    }
+}
+```
+
+For custom error parsing, define a type conforming to `APIError` and set it as the `ErrorType` on your server:
+
+```swift
+struct MyServer: URLServer {
+    typealias ErrorType = MyCustomError
+    let baseUri = URL(string: "https://api.example.com")!
+}
+```
+
 ## Contributors
 
 Current maintainer and main contributor is [Matěj Kašpar Jirásek](https://github.com/mkj-is), <matej.jirasek@futured.app>.

Sources/FTAPIKit/Coding.swift

@@ -8,6 +8,9 @@ public protocol Encoding: Sendable {
     func encode<T: Encodable>(_ object: T) throws -> Data
 
     /// Allows modification of `URLRequest`. Enables things like adding `Content-Type` header etc.
+    ///
+    /// Default implementation is a no-op. Custom `Encoding` types should override this to set
+    /// the appropriate `Content-Type` header. See ``JSONEncoding`` for an example.
     /// - Parameter request: Request which can be modified.
     func configure(request: inout URLRequest) throws
 }
@@ -21,7 +24,7 @@ public protocol Decoding: Sendable {
     func decode<T: Decodable>(data: Data) throws -> T
 }
 
-/// Type-erased JSON encoder for use with types conforming to ``Server`` protocol.
+/// Type-erased JSON encoder for use with types conforming to ``URLServer`` protocol.
 public struct JSONEncoding: Encoding {
     private let encoder: JSONEncoder
 
@@ -48,7 +51,7 @@ public struct JSONEncoding: Encoding {
     }
 }
 
-/// Type-erased JSON decoder for use with types conforming to ``Server`` protocol.
+/// Type-erased JSON decoder for use with types conforming to ``URLServer`` protocol.
 public struct JSONDecoding: Decoding {
     private let decoder: JSONDecoder
 

Sources/FTAPIKit/Documentation.docc/Documentation.md

@@ -1,20 +1,19 @@
 # ``FTAPIKit``
 
-Declarative, generic and protocol-oriented REST API framework using `URLSession` and `Codable`
+Declarative async/await REST API framework using Swift Concurrency and Codable.
 
 ## Overview
 
-Declarative and generic REST API framework using `Codable`.
-With standard implementation using `URLSesssion` and JSON encoder/decoder.
-Easily extensible for your asynchronous framework or networking stack.
+Declarative async/await REST API framework using `Codable`.
+With standard implementation using `URLSession` and JSON encoder/decoder.
+Built for Swift 6.1+ with full concurrency safety.
 
 ![Tree with a API Client root element. Its branches are servers. Each server branch has some endpoint branches.](Architecture)
 
 ## Topics
 
 ### Server
 
-- ``Server``
 - ``URLServer``
 
 ### Endpoint
@@ -29,6 +28,10 @@ Easily extensible for your asynchronous framework or networking stack.
 - ``RequestEndpoint``
 - ``RequestResponseEndpoint``
 
+### Request Configuration
+
+- ``RequestConfiguring``
+
 ### Endpoint configuration
 
 - ``HTTPMethod``
@@ -41,7 +44,10 @@ Easily extensible for your asynchronous framework or networking stack.
 - ``JSONEncoding``
 - ``Decoding``
 - ``JSONDecoding``
-- ``URLRequestEncoding``
+
+### Observers
+
+- ``NetworkObserver``
 
 ### Error handling
 

Sources/FTAPIKit/Endpoint.swift

@@ -4,7 +4,7 @@ import Foundation
 /// data and parameters which are sent to it.
 ///
 /// Recommended conformance of this protocol is implemented using `struct`. It is
-/// of course possible using `enum` or `class`. Endpoints are are not designed
+/// of course possible using `enum` or `class`. Endpoints are not designed
 /// to be referenced and used instantly after creation, so no memory usage is required.
 /// The case for not using enums is long-term sustainability. Enums tend to have many
 /// cases and information about one endpoint is spreaded all over the files. Also,
@@ -64,7 +64,7 @@ public protocol URLEncodedEndpoint: Endpoint {
 }
 
 /// An abstract representation of endpoint, body of which is represented by Swift encodable type. It serves as an
-/// abstraction between the ``Server`` protocol and more specific ``Endpoint`` conforming protocols.
+/// abstraction between the ``URLServer`` protocol and more specific ``Endpoint`` conforming protocols.
 /// Do not use this protocol to represent an encodable endpoint, use ``RequestEndpoint`` instead.
 public protocol EncodableEndpoint: Endpoint {
 
@@ -78,7 +78,7 @@ public protocol EncodableEndpoint: Endpoint {
 /// for automatic deserialization.
 public protocol ResponseEndpoint: Endpoint {
     /// Associated type describing the return type conforming to `Decodable`
-    /// protocol. This is only a phantom-type used by `APIAdapter`
+    /// protocol. This is only a phantom-type used by ``URLServer``
     /// for automatic decoding/deserialization of API results.
     associatedtype Response: Decodable & Sendable
 }

Sources/FTAPIKit/NetworkObserver.swift

@@ -8,10 +8,11 @@ import Foundation
 /// The `Context` associated type allows passing correlation data (request ID, start time, etc.)
 /// through the request lifecycle:
 /// 1. `willSendRequest` is called before the request starts and returns a `Context` value
-/// 2. `didReceiveResponse` is always called with the raw response data (useful for debugging)
+/// 2. `didReceiveResponse` is called when a response is received from the server
 /// 3. `didFail` is called additionally if the request processing fails (network, HTTP status, or decoding error)
-/// 4. If the observer is deallocated before the request completes, the context is discarded
-///    and no completion callback is invoked
+///
+/// - Note: Observers are strongly retained for the duration of a request to ensure lifecycle callbacks
+///   are always delivered.
 public protocol NetworkObserver: AnyObject, Sendable {
     associatedtype Context: Sendable
 
@@ -22,8 +23,8 @@ public protocol NetworkObserver: AnyObject, Sendable {
 
     /// Called when a response is received from the server.
     ///
-    /// This is always called with the raw response data, even if processing subsequently fails.
-    /// This allows observers to inspect the actual response for debugging purposes.
+    /// Only called when the server responds. Not called on network errors (e.g. no connectivity).
+    /// Called even if the response indicates an error (4xx, 5xx), before `didFail`.
     /// - Parameters:
     ///   - request: The original request
     ///   - response: The URL response (may be HTTPURLResponse)

Sources/FTAPIKit/URLServer+Async.swift

@@ -51,10 +51,7 @@ private extension URLServer {
     /// Core execution method that builds the request, notifies observers, performs the network call,
     /// and handles errors.
     func execute(endpoint: Endpoint, configuring: RequestConfiguring?) async throws -> ExecuteResult {
-        var urlRequest = try await buildRequest(endpoint: endpoint)
-        try await configuring?.configure(&urlRequest)
-
-        let observers = networkObservers.map { AnyObserverToken(observer: $0, request: urlRequest) }
+        let (urlRequest, observers) = try await prepareRequest(endpoint: endpoint, configuring: configuring)
 
         let file = (endpoint as? UploadEndpoint)?.file
 
@@ -66,19 +63,43 @@ private extension URLServer {
                 (data, response) = try await urlSession.data(for: urlRequest)
             }
         } catch {
-            observers.forEach { $0.didReceiveResponse(for: urlRequest, response: nil, data: nil) }
             observers.forEach { $0.didFail(request: urlRequest, error: error) }
             throw error
         }
 
         observers.forEach { $0.didReceiveResponse(for: urlRequest, response: response, data: data) }
+        try checkForError(data: data, response: response, request: urlRequest, observers: observers)
+
+        return ExecuteResult(data: data, request: urlRequest, observers: observers)
+    }
+}
+
+// MARK: - Shared helpers
 
+extension URLServer {
+
+    /// Builds the URLRequest for the endpoint, applies optional configuration, and creates observer tokens.
+    func prepareRequest(
+        endpoint: Endpoint,
+        configuring: RequestConfiguring?
+    ) async throws -> (URLRequest, [AnyObserverToken]) {
+        var urlRequest = try await buildRequest(endpoint: endpoint)
+        try await configuring?.configure(&urlRequest)
+        let observers = networkObservers.map { AnyObserverToken(observer: $0, request: urlRequest) }
+        return (urlRequest, observers)
+    }
+
+    /// Checks the response for API errors and notifies observers on failure.
+    func checkForError(
+        data: Data?,
+        response: URLResponse,
+        request: URLRequest,
+        observers: [AnyObserverToken]
+    ) throws {
         if let error = ErrorType(data: data, response: response, error: nil, decoding: decoding) {
-            observers.forEach { $0.didFail(request: urlRequest, error: error) }
+            observers.forEach { $0.didFail(request: request, error: error) }
             throw error
         }
-
-        return ExecuteResult(data: data, request: urlRequest, observers: observers)
     }
 }
 

Sources/FTAPIKit/URLServer+Download.swift

@@ -11,27 +11,18 @@ public extension URLServer {
     ///   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.
     func download(endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws -> URL {
-        var urlRequest = try await buildRequest(endpoint: endpoint)
-        try await configuring?.configure(&urlRequest)
-
-        let observers = networkObservers.map { AnyObserverToken(observer: $0, request: urlRequest) }
+        let (urlRequest, observers) = try await prepareRequest(endpoint: endpoint, configuring: configuring)
 
         let (localURL, response): (URL, URLResponse)
         do {
             (localURL, response) = try await urlSession.download(for: urlRequest)
         } catch {
-            observers.forEach { $0.didReceiveResponse(for: urlRequest, response: nil, data: nil) }
             observers.forEach { $0.didFail(request: urlRequest, error: error) }
             throw error
         }
 
         observers.forEach { $0.didReceiveResponse(for: urlRequest, response: response, data: nil) }
-
-        let urlData = localURL.absoluteString.data(using: .utf8)
-        if let error = ErrorType(data: urlData, response: response, error: nil, decoding: decoding) {
-            observers.forEach { $0.didFail(request: urlRequest, error: error) }
-            throw error
-        }
+        try checkForError(data: nil, response: response, request: urlRequest, observers: observers)
 
         return localURL
     }

Sources/FTAPIKit/URLServer.swift

@@ -11,7 +11,7 @@ import Foundation
 /// In case that the requests need to cooperate with other services, like OAuth, override the
 /// default implementation of `buildRequest`, use `buildStandardRequest(endpoint:)` within
 /// your new implementation, and use the `URLRequest` as a baseline.
-public protocol URLServer {
+public protocol URLServer: Sendable {
     /// Error type which is initialized during the request execution.
     associatedtype ErrorType: APIError = APIError.Standard