Improve comments

teamforage · May 6, 2024 · ba1613b · ba1613b
1 parent c349921
commit ba1613b
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 14 deletions.
diff --git a/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt b/forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt
@@ -98,10 +98,14 @@ class ForageSDK : ForageSDKInterface {
      *
      *         when (response) {
      *             is ForageApiResponse.Success -> {
-     *                 // parse response.data for the PaymentMethod object
+     *                 val paymentMethod = response.toPaymentMethod()
+     *                 // Unpack paymentMethod.ref, paymentMethod.card, etc.
+     *                 val card = paymentMethod.card as Card.EbtCard
+     *                 // Unpack card.last4, card.usState, etc.
      *             }
      *             is ForageApiResponse.Failure -> {
-     *                 // do something with error text (i.e. response.message)
+     *                 val error = response.errors[0]
+     *                 // handle error.code here
      *             }
      *         }
      *     }
@@ -167,10 +171,12 @@ class ForageSDK : ForageSDKInterface {
      *
      *         when (response) {
      *             is ForageApiResponse.Success -> {
-     *                 // response.data will have a .snap and a .cash value
+     *                 val balance = response.toBalance() as Balance.EbtBalance
+     *                 // Unpack balance.snap, balance.cash
      *             }
      *             is ForageApiResponse.Failure -> {
-     *                 // do something with error text (i.e. response.message)
+     *                 val error = response.errors[0]
+     *                 // handle error.code here
      *             }
      *         }
      *     }
@@ -253,7 +259,8 @@ class ForageSDK : ForageSDKInterface {
      *
      *             when (response) {
      *                 is ForageApiResponse.Success -> {
-     *                     // handle successful capture
+     *                     val payment = response.toPayment()
+     *                     // Unpack payment.ref, payment.receipt, etc.
      *                 }
      *                 is ForageApiResponse.Failure -> {
      *                     val error = response.errors[0]
@@ -263,7 +270,7 @@ class ForageSDK : ForageSDKInterface {
      *                         val details = error.details as ForageErrorDetails.EbtError51Details
      *                         val (snapBalance, cashBalance) = details
      *
-     *                         // do something with balances ...
+     *                         // display balance to the customer...
      *                     }
      *                 }
      *             }
@@ -283,7 +290,7 @@ class ForageSDK : ForageSDKInterface {
      * on error handling.
      * * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#payment-capture-exceptions)
      * to trigger payment capture exceptions during testing.
-     * @return A [ForageApiResponse] object.
+     * @return A [ForageApiResponse] object. Use [ForageApiResponse.Success.toPayment] to convert the `data` string to a [Payment][com.joinforage.forage.android.model.Payment].
      */
     override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse<String> {
         val (foragePinEditText, paymentRef) = params

diff --git a/forage-android/src/main/java/com/joinforage/forage/android/model/PaymentMethod.kt b/forage-android/src/main/java/com/joinforage/forage/android/model/PaymentMethod.kt
@@ -7,7 +7,7 @@ import org.json.JSONObject
  * @param ref A string identifier that refers to an instance in Forage's database of a PaymentMethod, a tokenized representation of a customer's card.
  * @param type The type of the customer’s payment instrument. ex: "ebt".
  * @param customerId A unique identifier for the end customer making the payment.
- * @param balance Refer to the [Balance] model. [null] until a balance inquiry has been performed.
+ * @param balance Refer to the [Balance] model. `null` until a balance inquiry has been performed.
  * @param card Refer to the [Card] model.
  * @param reusable Whether the PaymentMethod can be reused. If false, then the PaymentMethod can only be used for a single transaction.
  */
@@ -34,12 +34,7 @@ data class PaymentMethod(
             var balance: Balance? = null
             if (!jsonObject.isNull("balance")) {
                 val parsedBalance = jsonObject.getJSONObject("balance")
-                val snap = parsedBalance.getString("snap")
-                val cash = parsedBalance.getString("non_snap")
-                balance = Balance.EbtBalance(
-                    snap = snap,
-                    cash = cash
-                )
+                balance = Balance.EbtBalance.ModelMapper.fromApiResponse(parsedBalance)
             }
 
             val rawCard = jsonObject.getJSONObject("card")

diff --git a/...ge-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt b/...ge-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt
@@ -24,19 +24,60 @@ sealed class ForageApiResponse<out T> {
      *   response.data // { "ref": "abcde123", ... }
      * }
      * ```
+     *
+     * Use the [toPaymentMethod], [toBalance], or [toPayment] methods to convert the [data] string
+     * to a [PaymentMethod], [Balance], or [Payment] instance, respectively.
      */
     data class Success<out T>(val data: T) : ForageApiResponse<T>() {
+        /**
+         * Converts the [data] string to a [PaymentMethod] instance.
+         * ```kotlin
+         * when (forageApiResponse) {
+         *     is ForageApiResponse.Success -> {
+         *         val paymentMethod = forageApiResponse.toPaymentMethod()
+         *         // Unpack paymentMethod.ref, paymentMethod.card, etc.
+         *         val card = paymentMethod.card as Card.EbtCard
+         *         // Unpack card.last4, card.usState, etc.
+         *     }
+         * }
+         * ```
+         * @return A [PaymentMethod] instance.
+         */
         fun toPaymentMethod(): PaymentMethod {
             return PaymentMethod.ModelMapper.from(data as String)
         }
 
+        /**
+         * Converts the [data] string to a [Balance] instance.
+         * ```kotlin
+         * when (forageApiResponse) {
+         *     is ForageApiResponse.Success -> {
+         *         val balance = forageApiResponse.toBalance() as Balance.EbtBalance
+         *         // Unpack balance.snap, balance.cash
+         *     }
+         * }
+         * ```
+         * @return A [Balance] instance.
+         */
         fun toBalance(): Balance {
             // The ForageApiResponse.data string is already formatted to
             // { snap: ..., cash: ... }
             // so we use fromSdkResponse() instead of fromApiResponse()
             return Balance.EbtBalance.ModelMapper.fromSdkResponse(data as String)
         }
 
+        /**
+         * Converts the [data] string to a [Payment] instance.
+         * ```kotlin
+         * when (forageApiResponse) {
+         *     is ForageApiResponse.Success -> {
+         *         val payment = forageApiResponse.toPayment()
+         *         // Unpack payment.ref, payment.amount, payment.receipt, etc.
+         *     }
+         * }
+         * ```
+         * @return A [Payment] instance.
+         */
         fun toPayment(): Payment {
             return Payment.ModelMapper.from(data as String)
         }