Finalize account overview

Fernando Fernandes · Fernando Fernandes · commit 1b01f9552d69 · 2022-01-31T00:13:29.000+01:00
diff --git a/Sources/SwiftTrader/Extensions/Decodable+String.swift b/Sources/SwiftTrader/Extensions/Decodable+String.swift
@@ -0,0 +1,20 @@
+//
+//  Decodable+String.swift
+//  
+//
+//  Created by Fernando Fernandes on 30.01.22.
+//
+
+import Foundation
+
+public extension Decodable {
+    
+    func toString() -> String {
+        if let data = try? JSONSerialization.data(withJSONObject: self, options: .prettyPrinted),
+           let dataString = String(data: data, encoding: .utf8) {
+            return dataString
+        } else {
+            return ""
+        }
+    }
+}
diff --git a/Sources/SwiftTrader/HTTPMethod.swift b/Sources/SwiftTrader/HTTPMethod.swift
@@ -1,5 +1,5 @@
 //
-//  URLRequest+HTTPMethod.swift
+// HTTPMethod.swift
 //  
 //
 //  Created by Fernando Fernandes on 29.01.22.
diff --git a/Sources/SwiftTrader/Model/Kucoin/KucoinError.swift b/Sources/SwiftTrader/Model/Kucoin/KucoinError.swift
@@ -7,7 +7,7 @@
 
 import Foundation
 
-/// Represents errors that may occur while interacting with Kucoin REST APIs.
+/// Encapsulates Kucoin system errors that may occur while interacting with its REST APIs.
 ///
 /// https://docs.kucoin.com/futures/#requests
 public struct KucoinSystemError: Codable {
diff --git a/Sources/SwiftTrader/Network/Kucoin/AccountOverview/KucoinAccountOverviewRequest.swift b/Sources/SwiftTrader/Network/Kucoin/AccountOverview/KucoinAccountOverviewRequest.swift
@@ -23,13 +23,7 @@ public struct KucoinAccountOverviewRequest: NetworkRequest {
             let accountOverviewResource = KucoinAccountOverviewResource(currencySymbol: currencySymbol)
             var urlRequest = URLRequest(url: try accountOverviewResource.url)
             urlRequest.httpMethod = HTTPMethod.GET.rawValue
-            
-#warning("TODO: header")
-            //    request.setValue(key, forHTTPHeaderField: "KC-API-KEY")
-            //    request.setValue(signature(secret: secret), forHTTPHeaderField: "KC-API-SIGN")
-            //    request.setValue("\(timestampMilliseconds)", forHTTPHeaderField: "KC-API-TIMESTAMP")
-            //    request.setValue(passphrase, forHTTPHeaderField: "KC-API-PASSPHRASE")
-            
+            try KucoinAPI.setRequestHeaderFields(request: &urlRequest, kucoinAuth: kucoinAuth)
             return urlRequest
         }
     }
@@ -56,9 +50,6 @@ public struct KucoinAccountOverviewRequest: NetworkRequest {
 
 public extension KucoinAccountOverviewRequest {
     
-#warning("TODO: kucoin error")
-    // case couldNotDecodeKucoinError(error: Error)
-    // case statusCodeNotOK(statusCode: Int, error: String, kucoinError: String)
     func decode(_ data: Data) throws -> KucoinFuturesAccountOverviewResponse {
         try JSONDecoder().decode(KucoinFuturesAccountOverviewResponse.self, from: data)
     }
diff --git a/Sources/SwiftTrader/Network/Kucoin/AccountOverview/KucoinAccountOverviewResource.swift b/Sources/SwiftTrader/Network/Kucoin/AccountOverview/KucoinAccountOverviewResource.swift
@@ -10,17 +10,17 @@ import Foundation
 /// The **resource** for requesting an overview of a Kucoin Futures account.
 ///
 /// https://docs.kucoin.com/futures/#account
-public struct KucoinAccountOverviewResource: APIResource {
+public struct KucoinAccountOverviewResource: NetworkResource {
     
     // MARK: - Properties
     
     public var url: URL {
         get throws {
-            let baseURLString = KucoinAPI.URL.base
+            let baseURLString = KucoinAPI.Futures.URL.base
             guard var urlComponents = URLComponents(string: baseURLString) else {
                 throw NetworkRequestError.invalidURLString(urlString: baseURLString)
             }
-            urlComponents.path = KucoinAPI.Path.accountOverview
+            urlComponents.path = KucoinAPI.Futures.Path.accountOverview
             let queryItems = [
                 URLQueryItem(name: KucoinAPI.QueryParam.currency, value: currencySymbol.rawValue)
             ]
diff --git a/Sources/SwiftTrader/Network/Kucoin/KucoinAPI+Header.swift b/Sources/SwiftTrader/Network/Kucoin/KucoinAPI+Header.swift
@@ -0,0 +1,70 @@
+//
+//  KucoinAPI+Header.swift
+//  
+//
+//  Created by Fernando Fernandes on 30.01.22.
+//
+
+import Foundation
+
+/// Holds logic to set values for default HTTP header fields common to all Kucoin APIs requests.
+extension KucoinAPI {
+    
+    /// Sets values for default header fields in the given `URLRequest`
+    ///
+    /// Default header fields include `KC-API-KEY`, `KC-API-SIGN`, `KC-API-TIMESTAMP`, `KC-API-PASSPHRASE`, etc
+    ///
+    /// - Parameters:
+    ///   - request: `URLRequest` where the header field values are to be set.
+    ///   - kucoinAuth: `KucoinAuth` that holds Kucoin authentication data.
+    static func setRequestHeaderFields(request: inout URLRequest, kucoinAuth: KucoinAuth) throws {
+        setAPIKey(request: &request, kucoinAuth: kucoinAuth)
+        setAPIPassphrase(request: &request, kucoinAuth: kucoinAuth)
+        try setAPISignature(request: &request, kucoinAuth: kucoinAuth)
+        setAPITimestamp(request: &request, kucoinAuth: kucoinAuth)
+    }
+}
+
+// MARK: - Private
+
+private extension KucoinAPI {
+    
+    /// "KC-API-KEY"
+    static func setAPIKey(request: inout URLRequest, kucoinAuth: KucoinAuth) {
+        request.setValue(kucoinAuth.apiKey, forHTTPHeaderField: KucoinAPI.HeaderField.apiKey)
+    }
+    
+    /// "KC-API-PASSPHRASE"
+    static func setAPIPassphrase(request: inout URLRequest, kucoinAuth: KucoinAuth) {
+        request.setValue(kucoinAuth.apiPassphrase, forHTTPHeaderField: KucoinAPI.HeaderField.apiPassphrase)
+    }
+    
+    /// "KC-API-SIGN"
+    static func setAPISignature(request: inout URLRequest, kucoinAuth: KucoinAuth) throws {
+        guard let httpMethodString = request.httpMethod else {
+            throw KucoinAPIError.missingHTTPMethod
+        }
+        guard let httpMethod = HTTPMethod(rawValue: httpMethodString) else {
+            throw KucoinAPIError.unsupportedHTTPMethod
+        }
+        guard let url = request.url else {
+            throw KucoinAPIError.missingURL(url: request.url)
+        }
+        guard !url.path.isEmpty else {
+            throw KucoinAPIError.missingPath(url: url)
+        }
+        let finalPath: String
+        if let query = url.query, !query.isEmpty {
+            finalPath = "\(url.path)?\(query)"
+        } else {
+            finalPath = url.path
+        }
+        let signature = try createSignature(for: httpMethod, path: finalPath, secret: kucoinAuth.apiSecret)
+        request.setValue(signature, forHTTPHeaderField: KucoinAPI.HeaderField.apiSign)
+    }
+    
+    /// "KC-API-TIMESTAMP"
+    static func setAPITimestamp(request: inout URLRequest, kucoinAuth: KucoinAuth) {
+        request.setValue("\(Date().timestampMilliseconds)", forHTTPHeaderField: KucoinAPI.HeaderField.apiTimestamp)
+    }
+}
diff --git a/Sources/SwiftTrader/Network/Kucoin/KucoinAPI+Signature.swift b/Sources/SwiftTrader/Network/Kucoin/KucoinAPI+Signature.swift
@@ -1,5 +1,5 @@
 //
-//  File.swift
+//  KucoinAPI+Signature.swift
 //  
 //
 //  Created by Fernando Fernandes on 29.01.22.
@@ -15,32 +15,26 @@ import CryptoKit
 import Vapor
 #endif
 
-/// Encapsulates errors that can happen while generating the signature that Kucoin APIs require.
-public enum KucoinSignatureError: Error {
-    case unableToExtractDataFromString(string: String)
-}
-
+/// Holds logic to sign requests against Kucoin APIs.
 public extension KucoinAPI {
     
-#warning("TODO: I need this from urlrequest - /api/v1/account-overview?currency=USDT")
-    
     /// Creates and returns the signature for the `KC-API-SIGN` header field.
     ///
     /// https://docs.kucoin.com/futures/#authentication
     /// - Parameters:
     ///   - method: `HTTPMethod`. E.g.: `GET`, `POST.`
-    ///   - path: Endpoint path including query parameters. E.g.: *"/api/v1/account-overview?currency=USDT"*
+    ///   - path: Endpoint path including query parameters, if any. E.g.: *"/api/v1/account-overview?currency=USDT"*
     ///   - secret: The API secret.
     /// - Returns: `Base64` encoded signature.
     static func createSignature(for method: HTTPMethod, path: String, secret: String) throws -> String {
         guard let secretData = secret.data(using: .utf8) else {
-            throw KucoinSignatureError.unableToExtractDataFromString(string: secret)
+            throw KucoinAPIError.stringToDataFailed(string: secret)
         }
         let key = SymmetricKey(data: secretData)
         let timestamp = Date().timestampMilliseconds
         let stringToSign = "\(timestamp)" + HTTPMethod.GET.rawValue + path
         guard let stringToSignData = stringToSign.data(using: .utf8) else {
-            throw KucoinSignatureError.unableToExtractDataFromString(string: stringToSign)
+            throw KucoinAPIError.stringToDataFailed(string: stringToSign)
         }
         let signature = HMAC<SHA256>.authenticationCode(for: stringToSignData, using: key)
         let base64signature = Data(signature).base64EncodedString()
diff --git a/Sources/SwiftTrader/Network/Kucoin/KucoinAPI.swift b/Sources/SwiftTrader/Network/Kucoin/KucoinAPI.swift
@@ -10,22 +10,25 @@ import Foundation
 /// Holds constants related to  Kucoin REST APIs.
 public struct KucoinAPI {
     
+    public struct Futures {
+
+        public struct Path {
+            static let accountOverview = "/api/v1/account-overview"
+        }
+        
+        public struct URL {
+            static let base = "https://api-futures.kucoin.com"
+        }
+    }
+    
     public struct HeaderField {
         static let apiKey           = "KC-API-KEY"
         static let apiSign          = "KC-API-SIGN"
         static let apiTimestamp     = "KC-API-TIMESTAMP"
         static let apiPassphrase    = "KC-API-PASSPHRASE"
     }
     
-    public struct Path {
-        static let accountOverview = "/api/v1/account-overview"
-    }
-    
     public struct QueryParam {
         static let currency = "currency"
     }
-    
-    public struct URL {
-        static let base = "https://api-futures.kucoin.com"
-    }
 }
diff --git a/Sources/SwiftTrader/Network/Kucoin/KucoinAPIError.swift b/Sources/SwiftTrader/Network/Kucoin/KucoinAPIError.swift
@@ -0,0 +1,27 @@
+//
+//  KucoinAPIError.swift
+//  
+//
+//  Created by Fernando Fernandes on 30.01.22.
+//
+
+import Foundation
+
+/// Encapsulates Kucoin API related errors.
+public enum KucoinAPIError: Error {
+    
+    /// The HTTP method (e.g.: `GET` / `POST`) is absent.
+    case missingHTTPMethod
+    
+    /// The `URLRequest`'s `path` (e.g.: `/api/v1/account-overview`) is absent.
+    case missingPath(url: URL)
+    
+    /// The `URLRequest`'s `URL` (e.g.: `https://api-futures.kucoin.com`) is absent.
+    case missingURL(url: URL?)
+    
+    /// "someString".data(using: .utf8) failed.
+    case stringToDataFailed(string: String)
+    
+    /// The HTTP method (e.g.: `GET` / `POST`) is unsupported.
+    case unsupportedHTTPMethod
+}
diff --git a/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestError.swift b/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestError.swift
@@ -10,7 +10,7 @@ import Foundation
 /// Encapsulates errors that may happen during network requests.
 public enum NetworkRequestError: Error {
     
-    /// `Data` could not be parsed into a `Decodable` object.
+    /// `Data` could not be parsed to an expected`Decodable` object.
     case couldNotDecodeModelFromData(error: Error)
     
     /// Data from response is `nil`.
@@ -26,5 +26,7 @@ public enum NetworkRequestError: Error {
     case requestFailed(error: Error)
     
     /// The response status code is something other than `200`.
-    case statusCodeNotOK(statusCode: Int, localizedErrorMessage: String)
+    ///
+    /// The underlying error may be verified by reading the `Data` argument.
+    case statusCodeNotOK(statusCode: Int, localizedErrorMessage: String, data: Data)
 }
diff --git a/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestProtocol+Result.swift b/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestProtocol+Result.swift
@@ -31,7 +31,12 @@ public extension NetworkRequest {
             }
         default:
             let localizedErrorMessage = HTTPURLResponse.localizedString(forStatusCode: statusCode)
-            return .failure(.statusCodeNotOK(statusCode: statusCode, localizedErrorMessage: localizedErrorMessage))
+            let requestError: NetworkRequestError = .statusCodeNotOK(
+                statusCode: statusCode,
+                localizedErrorMessage: localizedErrorMessage,
+                data: data
+            )
+            return .failure(requestError)
         }
     }
 }
diff --git a/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestProtocol.swift b/Sources/SwiftTrader/Network/NetworkRequest/NetworkRequestProtocol.swift
@@ -7,7 +7,7 @@
 
 import Foundation
 
-public typealias NetworkRequestResult = Result<Decodable?, NetworkRequestError>
+public typealias NetworkRequestResult = Result<Decodable, NetworkRequestError>
 
 /// Represents a generic network request composed by basic functions that make a network request possible.
 public protocol NetworkRequest {
diff --git a/Sources/SwiftTrader/Network/NetworkRequest/NetworkResourceProtocol.swift b/Sources/SwiftTrader/Network/NetworkRequest/NetworkResourceProtocol.swift
@@ -1,5 +1,5 @@
 //
-//  APIResourceProtocol.swift
+//  NetworkResourceProtocol.swift
 //  
 //
 //  Created by Fernando Fernandes on 28.01.22.
@@ -10,6 +10,6 @@ import Foundation
 /// Represents a typical API resource that can be requested by its `URL`.
 ///
 /// `URL` example: https://api-futures.kucoin.com/api/v1/account-overview?currency=USDT
-public protocol APIResource {
+public protocol NetworkResource {
     var url: URL { get throws }
 }
diff --git a/Sources/SwiftTrader/SwiftTrader.swift b/Sources/SwiftTrader/SwiftTrader.swift
@@ -5,6 +5,8 @@
 //  Created by Fernando Fernandes on 24.01.22.
 //
 
+import Foundation
+
 /// Entry point for connecting and trading on crypto exchanges such as Binance and Kucoin.
 public struct SwiftTrader {
     
@@ -23,8 +25,23 @@ public struct SwiftTrader {
 
 public extension SwiftTrader {
     
-    #warning("TODO: create a SwiftTraderResult")
-    func kucoinFuturesAccountOverview() async throws -> NetworkRequestResult {
-        await KucoinAccountOverviewRequest(kucoinAuth: kucoinAuth).execute()
+    func kucoinFuturesAccountOverview() async throws -> Result<KucoinFuturesAccountOverviewResponse, SwiftTraderError> {
+        let request = KucoinAccountOverviewRequest(kucoinAuth: kucoinAuth)
+        switch await request.execute() {
+        case .success(let model):
+            guard let accountOverview = model as? KucoinFuturesAccountOverviewResponse else {
+                let modelString = model.toString()
+                return .failure(.unexpectedResponse(modelString: modelString))
+            }
+            return .success(accountOverview)
+        case .failure(let error):
+            switch error {
+            case .statusCodeNotOK(let statusCode, let errorMessage, let data):
+                let error = SwiftTraderError.error(for: statusCode, localizedErrorMessage: errorMessage, data: data)
+                return .failure(error)
+            default:
+                return .failure(.kucoinFuturesAccountOverviewError(error: error))
+            }
+        }
     }
 }
diff --git a/Sources/SwiftTrader/SwiftTraderError+Kucoin.swift b/Sources/SwiftTrader/SwiftTraderError+Kucoin.swift
@@ -0,0 +1,24 @@
+//
+//  SwiftTraderError+Kucoin.swift
+//  
+//
+//  Created by Fernando Fernandes on 30.01.22.
+//
+
+import Foundation
+
+/// Holds logic to return meaningful error messages containing detailed Kucoin system errors whenever possible.
+public extension SwiftTraderError {
+    
+    static func error(for statusCode: Int, localizedErrorMessage: String, data: Data) -> SwiftTraderError {
+        guard let kucoinError = try? JSONDecoder().decode(KucoinSystemError.self, from: data) else {
+            return .statusCodeNotOK(statusCode: statusCode, localizedErrorMessage: localizedErrorMessage)
+        }
+        return .statusCodeNotOK(
+            statusCode: statusCode,
+            localizedErrorMessage: localizedErrorMessage,
+            kucoinErrorCode: kucoinError.code,
+            kucoinErrorMessage: kucoinError.message
+        )
+    }
+}
diff --git a/Sources/SwiftTrader/SwiftTraderError.swift b/Sources/SwiftTrader/SwiftTraderError.swift
