From ba1613b1d45e18484b225739612d4402b4dab7d4 Mon Sep 17 00:00:00 2001 From: Danilo Joksimovic Date: Mon, 6 May 2024 10:23:53 -0400 Subject: [PATCH] Improve comments --- .../joinforage/forage/android/ForageSDK.kt | 21 ++++++---- .../forage/android/model/PaymentMethod.kt | 9 +--- .../network/model/ForageApiResponse.kt | 41 +++++++++++++++++++ 3 files changed, 57 insertions(+), 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 index 8e55bcbd..a5622281 100644 --- 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 { 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 index 46fa690e..f8f1c93e 100644 --- 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/forage-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt b/forage-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt index 53f73204..815e0943 100644 --- a/forage-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt +++ b/forage-android/src/main/java/com/joinforage/forage/android/network/model/ForageApiResponse.kt @@ -24,12 +24,41 @@ sealed class ForageApiResponse { * 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(val data: T) : ForageApiResponse() { + /** + * 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: ... } @@ -37,6 +66,18 @@ sealed class ForageApiResponse { 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) }