Merge pull request #3 from vamsii777/chore/docs-and-swift-testing

Update Razorpay SDK Documentation and Migrate to Swift Testing Framework

Sources/RazorpayKit/Constants/APIConstants.swift

@@ -1,31 +1,93 @@
+/// Constants defining the API endpoints and URLs used by the Razorpay API
+///
+/// This struct contains static constants for all the API endpoints used to interact with
+/// Razorpay's REST API. The constants include the base URL and paths for various resources
+/// like orders, payments, customers etc.
 public struct APIConstants {
+    /// The base URL for all Razorpay API requests
     static let baseURL = "https://api.razorpay.com"
+
+    /// API version 1 path component
     static let v1 = "/v1"
+
+    /// API version 2 path component
     static let v2 = "/v2"
+
+    /// Path for orders related endpoints
     static let orderURL = "/orders"
+
+    /// Path for invoice related endpoints
     static let invoiceURL = "/invoices"
+
+    /// Path for payment related endpoints
     static let paymentURL = "/payments"
+
+    /// Path for payment links related endpoints
     static let paymentLinkURL = "/payment_links"
+
+    /// Path for refund related endpoints
     static let refundURL = "/refunds"
+
+    /// Path for card related endpoints
     static let cardURL = "/cards"
+
+    /// Path for customer related endpoints
     static let customerURL = "/customers"
+
+    /// Path for addon related endpoints
     static let addonURL = "/addons"
+
+    /// Path for transfer related endpoints
     static let transferURL = "/transfers"
+
+    /// Path for virtual account related endpoints
     static let virtualAccountURL = "/virtual_accounts"
+
+    /// Path for subscription related endpoints
     static let subscriptionURL = "/subscriptions"
+
+    /// Path for plan related endpoints
     static let planURL = "/plans"
+
+    /// Path for QR code payment related endpoints
     static let qrCodeURL = "/payments/qr_codes"
+
+    /// Path for fund account related endpoints
     static let fundAccountURL = "/fund_accounts"
+
+    /// Path for settlement related endpoints
     static let settlementURL = "/settlements"
+
+    /// Path for item related endpoints
     static let itemURL = "/items"
+
+    /// Path for payment methods related endpoints
     static let methodsURL = "/methods"
+
+    /// Path for account related endpoints
     static let accountURL = "/accounts"
+
+    /// Path for stakeholder related endpoints
     static let stakeholderURL = "/stakeholders"
+
+    /// Path for product related endpoints
     static let productURL = "/products"
+
+    /// Path for terms and conditions related endpoints
     static let tncURL = "/tnc"
+
+    /// Path for IIN (Issuer Identification Number) related endpoints
     static let iinURL = "/iins"
+
+    /// Path for webhook related endpoints
     static let webhookURL = "/webhooks"
+
+    /// Alternative path for IIN related endpoints
     static let iin: String = "/iins"
+
+    /// Alternative path for terms and conditions
     static let tnc: String = "/tnc"
+
+    /// Alternative path for webhooks
     static let webhook: String = "/webhooks"
 }

Sources/RazorpayKit/Constants/ErrorCode.swift

@@ -1,5 +1,16 @@
+/// Error codes returned by the Razorpay API
+///
+/// These error codes indicate different types of failures that can occur during API interactions:
+/// - ``badRequestError``: Indicates invalid parameters or malformed request
+/// - ``gatewayError``: Indicates an error occurred at the payment gateway level
+/// - ``serverError``: Indicates an internal server error at Razorpay
 enum ErrorCode: String {
+    /// Error code indicating invalid parameters or malformed request
     case badRequestError = "BAD_REQUEST_ERROR"
+
+    /// Error code indicating a payment gateway level error
     case gatewayError = "GATEWAY_ERROR"
+
+    /// Error code indicating an internal Razorpay server error
     case serverError = "SERVER_ERROR"
 }

Sources/RazorpayKit/Errors/RZPError.swift

@@ -1,13 +1,49 @@
 import Foundation
 
-// Define a custom error type that encompasses various Razorpay errors.
+/// A custom error type that encompasses various Razorpay API errors.
+///
+/// `RZPError` provides structured error information returned by the Razorpay API,
+/// including error messages, codes, and additional context.
 enum RZPError: Error {
+    /// Indicates an error due to invalid request parameters or format.
+    /// - Parameters:
+    ///   - message: The main error message
+    ///   - internalErrorCode: Internal error code from Razorpay
+    ///   - field: The specific field that caused the error, if applicable
+    ///   - description: Detailed description of the error
+    ///   - code: Error code string
     case badRequestError(message: String, internalErrorCode: String?, field: String?, description: String?, code: String?)
+
+    /// Indicates an internal server error from Razorpay.
+    /// - Parameters:
+    ///   - message: The main error message
+    ///   - internalErrorCode: Internal error code from Razorpay
+    ///   - field: The specific field that caused the error, if applicable
+    ///   - description: Detailed description of the error
+    ///   - code: Error code string
     case serverError(message: String, internalErrorCode: String?, field: String?, description: String?, code: String?)
+
+    /// Indicates an error from the payment gateway.
+    /// - Parameters:
+    ///   - message: The main error message
+    ///   - internalErrorCode: Internal error code from Razorpay
+    ///   - field: The specific field that caused the error, if applicable
+    ///   - description: Detailed description of the error
+    ///   - code: Error code string
     case gatewayError(message: String, internalErrorCode: String?, field: String?, description: String?, code: String?)
+
+    /// Indicates a failure in webhook signature verification.
+    /// - Parameters:
+    ///   - message: The main error message
+    ///   - internalErrorCode: Internal error code from Razorpay
+    ///   - field: The specific field that caused the error, if applicable
+    ///   - description: Detailed description of the error
+    ///   - code: Error code string
     case signatureVerificationError(message: String, internalErrorCode: String?, field: String?, description: String?, code: String?)
 
-    // Custom string representation of the error
+    /// A brief description of the error.
+    ///
+    /// Returns only the main error message without additional context.
     var errorDescription: String {
         switch self {
         case .badRequestError(let message, _, _, _, _),
@@ -18,6 +54,10 @@ enum RZPError: Error {
         }
     }
 
+    /// A detailed description of the error including all available context.
+    ///
+    /// Returns a formatted string containing the error message, code, field, description,
+    /// and error code when available. Uses "N/A" for missing values.
     var detailedError: String {
         switch self {
         case .badRequestError(message: let message, internalErrorCode: let code, field: let field, description: let description, code: let errorCode):
@@ -28,4 +68,3 @@ enum RZPError: Error {
         }
     }
 }
-

Sources/RazorpayKit/RazorpayClient.swift

@@ -1,32 +1,124 @@
 import NIO
 import AsyncHTTPClient
 
+/// A client for interacting with the Razorpay API.
+///
+/// The `RazorpayClient` provides access to all Razorpay API endpoints through dedicated route handlers.
+/// Initialize it with your API credentials to start making API requests.
+///
+/// ```swift
+/// let httpClient = HTTPClient(eventLoopGroupProvider: .shared)
+/// let razorpay = RazorpayClient(httpClient: httpClient,
+///                              key: "your_key",
+///                              secret: "your_secret")
+/// ```
+///
+/// ## Topics
+///
+/// ### Account Management
+/// - ``account``
+/// - ``stakeholder``
+///
+/// ### Payment Processing
+/// - ``payment``
+/// - ``paymentLink``
+/// - ``order``
+/// - ``refund``
+///
+/// ### Customer Management
+/// - ``customer``
+/// - ``card``
+/// - ``token``
+///
+/// ### Banking & Transfers
+/// - ``fundAccount``
+/// - ``transfer``
+/// - ``virtualAccount``
+/// - ``settlement``
+///
+/// ### Products & Subscriptions
+/// - ``product``
+/// - ``subscription``
+/// - ``invoice``
+/// - ``item``
+///
+/// ### Additional Features
+/// - ``addon``
+/// - ``iin``
+/// - ``qrCode``
+/// - ``webhook``
 public final class RazorpayClient {
 
+    /// Routes for managing Razorpay accounts
     public var account: RazorpayAccountRoutes
+
+    /// Routes for managing addons
     public var addon: RazorpayAddonRoutes
+
+    /// Routes for managing cards
     public var card: RazorpayCardRoutes
+
+    /// Routes for managing customers
     public var customer: RazorpayCustomerRoutes
+
+    /// Routes for managing fund accounts
     public var fundAccount: RazorpayFundAccountRoutes
+
+    /// Routes for managing IIN (Issuer Identification Numbers)
     public var iin: RazorpayIINRoutes
+
+    /// Routes for managing invoices
     public var invoice: RazorpayInvoiceRoutes
+
+    /// Routes for managing items
     public var item: RazorpayItemRoutes
+
+    /// Routes for managing orders
     public var order: RazorpayOrderRoutes
+
+    /// Routes for managing payments
     public var payment: RazorpayPaymentRoutes
+
+    /// Routes for managing payment links
     public var paymentLink: RazorpayPaymentLinkRoutes
+
+    /// Routes for managing products
     public var product: RazorpayProductRoutes
+
+    /// Routes for managing QR codes
     public var qrCode: RazorpayQRCodeRoutes
+
+    /// Routes for managing refunds
     public var refund: RazorpayRefundRoutes
+
+    /// Routes for managing settlements
     public var settlement: RazorpaySettlementRoutes
+
+    /// Routes for managing stakeholders
     public var stakeholder: RazorpayStakeholderRoutes
+
+    /// Routes for managing subscriptions
     public var subscription: RazorpaySubscriptionRoutes
+
+    /// Routes for managing tokens
     public var token: RazorpayTokenRoutes
+
+    /// Routes for managing transfers
     public var transfer: RazorpayTransferRoutes
+
+    /// Routes for managing virtual accounts
     public var virtualAccount: RazorpayVirtualAccountRoutes
+
+    /// Routes for managing webhooks
     public var webhook: RazorpayWebhookRoutes
 
     var handler: RazorpayAPIHandler
 
+    /// Creates a new Razorpay API client.
+    /// - Parameters:
+    ///   - httpClient: The HTTP client to use for making requests
+    ///   - key: Your Razorpay API key
+    ///   - secret: Your Razorpay API secret
     public init(httpClient: HTTPClient, key: String, secret: String) {
         self.handler = RazorpayAPIHandler(httpClient: httpClient, key: key, secret: secret)
         account = RazorpayAccountRoutes(client: handler)

Sources/RazorpayKit/RazorpayRequest.swift

@@ -4,6 +4,7 @@ import NIOFoundationCompat
 import NIOHTTP1
 import AsyncHTTPClient
 
+
 extension HTTPClientRequest.Body {
     public static func string(_ string: String) -> Self {
         .bytes(.init(string: string))
@@ -43,8 +44,11 @@ struct RazorpayAPIHandler {
         let queryString = RZPRUTL.convertToQueryString(queryParams)
         let url = APIConstants.baseURL + path + queryString
 
-        var requestHeaders: HTTPHeaders = ["Authorization": authorizationHeader(), "Content-Type": "application/json",
-                                           "Accept": "application/json"]
+        var requestHeaders: HTTPHeaders = [
+            "Authorization": authorizationHeader(),
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        ]
         headers.forEach { requestHeaders.add(name: $0.name, value: $0.value) }
 
         var request = HTTPClientRequest(url: url)