Add HyperCheckout integration and documentation (#12)

- Introduced a new `HyperCheckout` library for seamless integration with Juspay's HyperCheckout payment solution.
- Added `HyperCheckoutClient` for managing payment sessions, orders, and refunds.
- Created protocols for handling order, session, and refund routes.
- Included comprehensive documentation in `.docc` format for getting started and API usage.
- Updated `Package.swift` to include `HyperCheckout` as a library target.
- Added tests for HyperCheckout functionalities to ensure reliability and correctness.

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [JuspayKit, HyperCheckout]

Package.swift

@@ -14,6 +14,10 @@ let package = Package(
             name: "JuspayKit",
             targets: ["JuspayKit"]
         ),
+        .library(
+            name: "HyperCheckout",
+            targets: ["HyperCheckout"]
+        ),
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.3.0"),
@@ -29,9 +33,18 @@ let package = Package(
             ],
             swiftSettings: swiftSettings
         ),
+        .target(
+            name: "HyperCheckout",
+            dependencies: ["JuspayKit"],
+            swiftSettings: swiftSettings
+        ),
         .testTarget(
             name: "JuspayKitTests",
-            dependencies: ["JuspayKit"]
+            dependencies: ["JuspayKit", "HyperCheckout"]
+        ),
+        .testTarget(
+            name: "HyperCheckoutTests",
+            dependencies: ["HyperCheckout", "JuspayKit"]
         )
     ]
 )

Sources/HyperCheckout/HyperCheckout.docc/GettingStarted.md

@@ -0,0 +1,53 @@
+# Getting Started with HyperCheckout
+
+Learn how to integrate Juspay's HyperCheckout payment solution into your application.
+
+## Overview
+
+The HyperCheckout framework provides a simplified interface for integrating Juspay's payment processing capabilities into your application. It wraps the core JuspayKit functionality with HyperCheckout-specific implementations for managing orders, payment sessions, and refunds.
+
+### Initialize the Client
+
+First, create a JuspayClient with your API credentials and then use it to initialize the HyperCheckout client:
+
+```swift
+let juspayClient = JuspayClient(apiKey: "YOUR_API_KEY", apiSecret: "YOUR_API_SECRET", environment: .sandbox)
+let hyperCheckoutClient = HyperCheckoutClient(juspayClient: juspayClient)
+```
+
+### Create a Payment Session
+
+To create a payment session, use the `create` method of the HyperCheckout client:
+
+```swift
+let session = Session(
+    amount: "100.00",
+    customerId: "CUST123",
+    customerEmail: "customer@example.com",
+    customerPhone: "1234567890",
+    paymentPageClientId: merchantId,
+    action: .paymentPage,
+    returnUrl: "https://merchant.com/return"
+)
+```
+
+### Get Order Status
+
+To get the status of an order, use the `status` method of the HyperCheckout client:
+
+```swift
+let order = try await hyperCheckoutClient.orders.status(orderId: "ORDER123", routingId: "CUST123")
+```
+
+### Process a Refund
+
+To process a refund, use the `refund` method of the HyperCheckout client:
+
+```swift
+let refundRequest = RefundRequest(
+    uniqueRequestId: "REFUND123",
+    amount: 50.00,
+    reason: "Customer request"
+)
+let refund = try await hyperCheckoutClient.refunds.create(orderId: "ORDER123", routingId: "CUST123", refund: refundRequest)
+``` 

Sources/HyperCheckout/HyperCheckout.docc/HyperCheckout.md

@@ -0,0 +1,26 @@
+# ``HyperCheckout``
+
+Integrate Juspay's HyperCheckout payment solution into your application.
+
+## Overview
+
+The HyperCheckout framework provides a simplified interface for integrating Juspay's payment processing capabilities into your application. It wraps the core JuspayKit functionality with HyperCheckout-specific implementations for managing orders, payment sessions, and refunds.
+
+## Topics
+
+### Essentials
+
+- <doc:GettingStarted>
+- ``HyperCheckoutClient``
+
+### Payment Operations
+
+- ``HyperOrderRoutes``
+- ``HyperSessionRoutes`` 
+- ``HyperRefundRoutes``
+
+### Default Implementations
+
+- ``DefaultHyperOrderRoutes``
+- ``DefaultHyperSessionRoutes``
+- ``DefaultHyperRefundRoutes``

Sources/HyperCheckout/HyperCheckout.swift

@@ -0,0 +1,71 @@
+import JuspayKit
+import AsyncHTTPClient
+import Foundation
+
+/// A client for interacting with Juspay's HyperCheckout payment solution.
+///
+/// The `HyperCheckoutClient` provides a simplified interface for integrating Juspay's HyperCheckout
+/// payment solution into your application. It wraps the core JuspayKit functionality with
+/// HyperCheckout-specific implementations.
+///
+/// ## Topics
+///
+/// ### Creating a Client
+/// - ``init(_:)``
+///
+/// ### Available Routes
+/// - ``orders``
+/// - ``sessions``
+/// - ``refunds``
+///
+/// ### Example
+///
+/// ```swift
+/// // Initialize the base Juspay client
+/// let juspayClient = JuspayClient(
+///     httpClient: HTTPClient.shared,
+///     apiKey: "your_api_key",
+///     merchantId: "your_merchant_id",
+///     environment: .sandbox
+/// )
+///
+/// // Create the HyperCheckout client
+/// let hyperCheckout = HyperCheckoutClient(juspayClient)
+///
+/// // Create a payment session
+/// let session = Session(
+///     orderId: "ORDER123",
+///     amount: "100.00",
+///     customerId: "CUST123",
+///     customerEmail: "customer@example.com",
+///     customerPhone: "1234567890",
+///     paymentPageClientId: merchantId,
+///     action: .paymentPage,
+///     returnUrl: "https://your-return-url.com"
+/// )
+///
+/// let response = try await hyperCheckout.sessions.create(session: session)
+/// ```
+public actor HyperCheckoutClient {
+    /// The underlying JuspayClient instance.
+    private let juspayClient: JuspayClient
+
+    /// Routes for order-related operations.
+    public let orders: any HyperOrderRoutes
+
+    /// Routes for session-related operations.
+    public let sessions: any HyperSessionRoutes
+
+    /// Routes for refund-related operations.
+    public let refunds: any HyperRefundRoutes
+
+    /// Creates a new HyperCheckout client.
+    ///
+    /// - Parameter juspayClient: A configured JuspayClient instance.
+    public init(_ juspayClient: JuspayClient) {
+        self.juspayClient = juspayClient
+        self.orders = DefaultHyperOrderRoutes(juspayClient: juspayClient)
+        self.sessions = DefaultHyperSessionRoutes(juspayClient: juspayClient)
+        self.refunds = DefaultHyperRefundRoutes(juspayClient: juspayClient)
+    }
+}

Sources/HyperCheckout/Routes/HyperOrderRoutes.swift

@@ -0,0 +1,47 @@
+import JuspayKit
+import Foundation
+import NIOHTTP1
+
+/// Protocol defining HyperCheckout order-related operations.
+///
+/// The `HyperOrderRoutes` protocol provides methods for managing orders
+/// through Juspay's HyperCheckout solution.
+///
+/// ## Topics
+///
+/// ### Checking Order Status
+/// - ``status(orderId:routingId:)``
+///
+/// ### Example
+///
+/// ```swift
+/// // Check the status of an order
+/// let order = try await hyperCheckout.orders.status(
+///     orderId: "ORDER123",
+///     routingId: "CUSTOMER456"
+/// )
+///
+/// print("Order Status: \(order.status)")
+/// ```
+public protocol HyperOrderRoutes {
+    /// Retrieves the status of an order.
+    ///
+    /// - Parameters:
+    ///   - orderId: The unique identifier of the order.
+    ///   - routingId: The routing identifier (typically the customer ID).
+    /// - Returns: An `Order` object containing the current status.
+    /// - Throws: An error if the status check fails.
+    func status(orderId: String, routingId: String) async throws -> Order
+}
+
+public struct DefaultHyperOrderRoutes: HyperOrderRoutes {
+    private let juspayClient: JuspayClient
+
+    init(juspayClient: JuspayClient) {
+        self.juspayClient = juspayClient
+    }
+
+    public func status(orderId: String, routingId: String) async throws -> Order {
+        return try await juspayClient.orders.retrieve(orderId: orderId, routingId: routingId)
+    }
+}

Sources/HyperCheckout/Routes/HyperRefundRoutes.swift

@@ -0,0 +1,56 @@
+import JuspayKit
+import Foundation
+import NIOHTTP1
+
+/// Protocol defining HyperCheckout refund-related operations.
+///
+/// The `HyperRefundRoutes` protocol provides methods for processing refunds
+/// through Juspay's HyperCheckout solution.
+///
+/// ## Topics
+///
+/// ### Processing Refunds
+/// - ``request(orderId:routingId:refund:)``
+///
+/// ### Example
+///
+/// ```swift
+/// // Create a refund request
+/// let refundRequest = RefundRequest(
+///     uniqueRequestId: "REFUND123",
+///     amount: 50.00,
+///     reason: "Customer request"
+/// )
+///
+/// // Process the refund
+/// let response = try await hyperCheckout.refunds.request(
+///     orderId: "ORDER123",
+///     routingId: "CUSTOMER456",
+///     refund: refundRequest
+/// )
+///
+/// print("Refund Status: \(response.status)")
+/// ```
+public protocol HyperRefundRoutes {
+    /// Requests a refund for an order.
+    ///
+    /// - Parameters:
+    ///   - orderId: The unique identifier of the order to refund.
+    ///   - routingId: The routing identifier (typically the customer ID).
+    ///   - refund: The refund request details.
+    /// - Returns: A `RefundResponse` containing the refund status.
+    /// - Throws: An error if the refund request fails.
+    func request(orderId: String, routingId: String, refund: RefundRequest) async throws -> RefundResponse
+}
+
+public struct DefaultHyperRefundRoutes: HyperRefundRoutes {
+    private let juspayClient: JuspayClient
+
+    init(juspayClient: JuspayClient) {
+        self.juspayClient = juspayClient
+    }
+
+    public func request(orderId: String, routingId: String, refund: RefundRequest) async throws -> RefundResponse {
+        return try await juspayClient.refunds.create(orderId: orderId, routingId: routingId, refund: refund)
+    }
+} 

Sources/HyperCheckout/Routes/HyperSessionRoutes.swift

@@ -0,0 +1,51 @@
+import JuspayKit
+import Foundation
+import NIOHTTP1
+
+/// Protocol defining HyperCheckout session-related operations.
+///
+/// The `HyperSessionRoutes` protocol provides methods for managing payment sessions
+/// through Juspay's HyperCheckout solution.
+///
+/// ## Topics
+///
+/// ### Creating Sessions
+/// - ``create(session:)``
+///
+/// ### Example
+///
+/// ```swift
+/// // Create a new payment session
+/// let session = Session(
+///     orderId: "ORDER123",
+///     amount: "100.00",
+///     customerId: "CUST123",
+///     customerEmail: "customer@example.com",
+///     customerPhone: "1234567890",
+///     paymentPageClientId: merchantId,
+///     action: .paymentPage,
+///     returnUrl: "https://merchant.com/return"
+/// )
+///
+/// let response = try await hyperCheckout.sessions.create(session: session)
+/// ```
+public protocol HyperSessionRoutes {
+    /// Creates a new payment session.
+    ///
+    /// - Parameter session: The session configuration.
+    /// - Returns: A `SessionResponse` containing the created session details.
+    /// - Throws: An error if session creation fails.
+    func create(session: Session) async throws -> SessionResponse
+}
+
+public struct DefaultHyperSessionRoutes: HyperSessionRoutes {
+    private let juspayClient: JuspayClient
+
+    init(juspayClient: JuspayClient) {
+        self.juspayClient = juspayClient
+    }
+
+    public func create(session: Session) async throws -> SessionResponse {
+        return try await juspayClient.sessions.create(session: session)
+    }
+}

Sources/JuspayKit/Core/APIHandler.swift

@@ -49,7 +49,36 @@ public enum Environment: Sendable {
     }
 }
 
-/// Handles API requests to the Juspay service.
+/// Handles API requests to the Juspay payment gateway.
+///
+/// The `JuspayAPIHandler` is responsible for making HTTP requests to Juspay's API endpoints.
+/// It handles authentication, request construction, and response parsing.
+///
+/// ## Topics
+///
+/// ### Making Requests
+/// - ``send(_:method:path:query:body:headers:)``
+///
+/// ### Environment Configuration  
+/// - ``Environment``
+/// - ``Environment/production``
+/// - ``Environment/sandbox``
+///
+/// ### Example
+/// ```swift
+/// let handler = JuspayAPIHandler(
+///     httpClient: client,
+///     apiKey: "key",
+///     merchantId: "merchant",
+///     environment: .sandbox
+/// )
+///
+/// let response: PaymentMethodsResponse = try await handler.send(
+///     method: .GET,
+///     path: "merchants/guest/paymentmethods",
+///     headers: headers
+/// )
+/// ```
 actor JuspayAPIHandler {
     /// The HTTP client used for network requests.
     private let httpClient: HTTPClient