Skip to content

Commit

Permalink
[TW-400] Update comments for ForageSDK (#153)
Browse files Browse the repository at this point in the history 
* Update comments for ForageSDK.kt

* Address PR feedback

* Update example ebt error

* Add PR feedback

* Attempt to fix linting

* Typo
  • Loading branch information
@kimberleehowley
kimberleehowley authored Jan 16, 2024
1 parent 0fea121 commit 79dc8fd
Showing 1 changed file with 109 additions and 39 deletions.
148 changes: 109 additions & 39 deletions forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,32 @@ import com.joinforage.forage.android.ui.ForageConfig
import com.joinforage.forage.android.ui.ForagePINEditText

/**
* A class implementation of ForageSDKInterface
* Entry point to the Forage SDK.
*
* A [ForageSDK] instance interacts with the Forage API.
*
* You need an instance of the ForageSDK to perform operations like:
*
* * [Tokenizing card information][tokenizeEBTCard]
* * [Checking the balance of a card][checkBalance]
* * [Collecting a customer's card PIN for a payment and deferring
* the capture of the payment to the server][deferPaymentCapture]
* * [Capturing a payment immediately][capturePayment]
*/
class ForageSDK : ForageSDKInterface {

/**
* Retrieves the ForageConfig for a given ForageElement, or throws an exception if the
* ForageConfig is not set.
*
* @param element A ForageElement instance
* @return The ForageConfig associated with the ForageElement
* @throws ForageConfigNotSetException If the ForageConfig is not set for the ForageElement
*/
internal fun <T : ElementState> _getForageConfigOrThrow(element: AbstractForageElement<T>): ForageConfig {
val context = element.getForageConfig()
return context ?: throw ForageConfigNotSetException(
"""
The ForageElement you passed did have a ForageConfig. In order to submit
The ForageElement you passed did not have a ForageConfig. In order to submit
a request via Forage SDK, your ForageElement MUST have a ForageConfig.
Make sure to call myForageElement.setForageConfig(forageConfig: ForageConfig)
immediately on your ForageElement
Expand All @@ -38,18 +55,27 @@ class ForageSDK : ForageSDKInterface {
}

/**
* A method to securely tokenize an EBT card via ForagePANEditText
* Tokenizes an EBT Card via a [ForagePANEdit
* Text][com.joinforage.forage.android.ui.ForagePANEditText] Element.
*
* @param params The parameters required for tokenization, including
* reference to a ForagePANEditText view for card input.
*
* @return A ForageAPIResponse indicating the success or failure of the operation.
* On success, returns a [PaymentMethod](https://docs.joinforage.app/reference/create-payment-method)
* token which can be securely stored and used for subsequent transactions. On failure,
* returns a detailed error response for proper handling.
*
* @throws ForageConfigNotSetException If the passed ForagePANEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* * On success, the object includes a `ref` token that represents an instance of a Forage
* [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods#paymentmethod-object).
* You can store the token for future transactions, like to [`checkBalance`](checkBalance) or
* to [create a `Payment`](https://docs.joinforage.app/reference/create-a-payment) in
* Forage's database.
* * On failure, for example in the case of
* [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14),
* the response includes a list of
* [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can
* unpack to troubleshoot the issue.
* @param params A [TokenizeEBTCardParams] model that passes a [`foragePanEditText`]
* [com.joinforage.forage.android.ui.ForagePANEditText] instance, a `customerId`, and a `reusable`
* boolean that Forage uses to tokenize an EBT Card.
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided
* `foragePanEditText`.
* @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more
* information on error handling.
* @return A [ForageApiResponse] object.
*/
override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse<String> {
val (foragePanEditText, customerId, reusable) = params
Expand All @@ -76,17 +102,30 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Checks the balance of a given PaymentMethod using a ForagePINEditText
*
* @param params The parameters required for balance inquiries, including
* a reference to a ForagePINEditText and PaymentMethod ref
* Checks the balance of a previously created
* [`PaymentMethod`](https://docs.joinforage.app/reference/payment-methods)
* via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
*
* @return A ForageAPIResponse indicating the success or failure of the operation.
* On success, returns an object with `snap` (SNAP) and `cash` (EBT Cash) fields, whose values
* indicate the current balance of each respective tender
* * On success, the response object includes `snap` and `cash` fields that indicate
* the EBT Card's current SNAP and EBT Cash balances.
* * On failure, for example in the case of
* [`ebt_error_14`](https://docs.joinforage.app/reference/errors#ebt_error_14),
* the response includes a list of
* [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can
* unpack to troubleshoot the issue.
* @param params A [CheckBalanceParams] model that passes
* a [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a
* `paymentMethodRef`, found in the response from a call to [tokenizeEBTCard] or the
* [Create a `PaymentMethod`](https://docs.joinforage.app/reference/create-payment-method)
* endpoint, that Forage uses to check the payment method's balance.
*
* @throws ForageConfigNotSetException If the passed ForagePINEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided
* `foragePinEditText`.
* @see * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more
* information on error handling.
* * [Test EBT Cards](https://docs.joinforage.app/docs/test-ebt-cards#balance-inquiry-exceptions)
* to trigger balance inquiry exceptions during testing.
* @return A [ForageApiResponse] object.
*/
override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse<String> {
val (foragePinEditText, paymentMethodRef) = params
Expand Down Expand Up @@ -123,17 +162,32 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Captures a Forage Payment associated with an EBT card
* Immediately captures a payment via a
* [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
*
* @param params The parameters required for payment capture, including
* reference to a ForagePINEditText and a Payment ref
* * On success, the object confirms the transaction. The response includes a Forage
* [`Payment`](https://docs.joinforage.app/reference/payments) object.
* * On failure, for example in the case of
* [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable) or
* [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the
* response includes a list of
* [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can
* unpack to troubleshoot the issue.
*
* @return A ForageAPIResponse indicating the success or failure of the
* payment capture. On success, returns a confirmation of the transaction.
* On failure, provides a detailed error response.
* @param params A [CapturePaymentParams] model that passes a
* [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText]
* instance and a `paymentRef`, returned by the
* [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, that
* Forage uses to capture a payment.
*
* @throws ForageConfigNotSetException If the passed ForagePANEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided
* `foragePinEditText`.
* @see
* * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information
* 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.
*/
override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down Expand Up @@ -170,17 +224,33 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Capture a customer's PIN for an EBT payment and defer the capture of the payment to the server
* Submits a customer's PIN via a
* [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element and defers
* payment capture to the server.
*
* @param params The parameters required for pin capture, including
* reference to a ForagePINEditText and a Payment ref
* * On success, the object returns `Nothing`.
* * On failure, for example in the case of
* [`card_not_reusable`](https://docs.joinforage.app/reference/errors#card_not_reusable)
* or [`ebt_error_51`](https://docs.joinforage.app/reference/errors#ebt_error_51) errors, the
* response includes a list of
* [ForageError][com.joinforage.forage.android.network.model.ForageError] objects that you can
* unpack to troubleshoot the issue.
*
* @return A ForageAPIResponse indicating the success or failure of the
* PIN capture. On success, returns `Nothing`.
* On failure, provides a detailed error response.
* @param params A [DeferPaymentCaptureParams] model that passes a
* [`foragePinEditText`][com.joinforage.forage.android.ui.ForagePINEditText] instance and a
* `paymentRef`, returned by the
* [Create a Payment](https://docs.joinforage.app/reference/create-a-payment) endpoint, as the
* DeferPaymentCaptureParams.
*
* @throws ForageConfigNotSetException If the passed ForagePINEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @throws [ForageConfigNotSetException] If the [ForageConfig] is not set for the provided
* `foragePinEditText`.
* @see * [Defer EBT payment capture to the server](https://docs.joinforage.app/docs/capture-ebt-payments-server-side)
* for the related step-by-step guide.
* * [Capture an EBT Payment](https://docs.joinforage.app/reference/capture-a-payment)
* for the API endpoint to call after [deferPaymentCapture].
* * [SDK errors](https://docs.joinforage.app/reference/errors#sdk-errors) for more information
* on error handling.
* @return A [ForageApiResponse] object.
*/
override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down

0 comments on commit 79dc8fd

Please sign in to comment.