Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TW-400] Update comments for ForageSDK #153

Merged
merged 7 commits into from
Jan 16, 2024
Merged

[TW-400] Update comments for ForageSDK #153

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cdce816
Update comments for ForageSDK.kt
kimberleehowley Jan 9, 2024
b60df6b
Address PR feedback
kimberleehowley Jan 12, 2024
e54947e
Update example ebt error
kimberleehowley Jan 12, 2024
8e9dae1
Add PR feedback
kimberleehowley Jan 13, 2024
fdce299
Merge branch 'main' into kimberlee/tw-400-update-comments-for-foragesdk
kimberleehowley Jan 13, 2024
30a920c
Attempt to fix linting
kimberleehowley Jan 13, 2024
bdc9211
Typo
kimberleehowley Jan 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 42 additions & 42 deletions forage-android/src/main/java/com/joinforage/forage/android/ForageSDK.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,31 @@ import com.joinforage.forage.android.ui.ForageConfig
import java.util.UUID

/**
* 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:
*
* * [capturePayment]
* * [checkBalance]
* * [deferPaymentCapture]
* * [tokenizeEBTCard]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we put this in the common order (tokenize -> checkBalance -> deferPaymentCapture -> capturePayment) these and hyperlink them with descriptions?

Suggested change
* * [capturePayment]
* * [checkBalance]
* * [deferPaymentCapture]
* * [tokenizeEBTCard]
* * [Tokenizing card information][tokenizeCard]
* * [Checking the balance of a card][checkBalance]
* * [Collecting a customer's PIN for a payment and deferring the capture of the payment to the server][deferPaymentCapture]
* * [Immediately capturing a payment][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
*/
private fun <T : ElementState> _getForageConfigOrThrow(element: AbstractForageElement<T>): ForageConfig {
kimberleehowley marked this conversation as resolved.
Show resolved Hide resolved
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 +54,12 @@ class ForageSDK : ForageSDKInterface {
}

/**
* A method to securely tokenize an EBT card via ForagePANEditText
*
* @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.
* Tokenizes an EBT Card via a [ForagePANEditText][com.joinforage.forage.android.ui.ForagePANEditText] Element.
djoksimo marked this conversation as resolved.
Show resolved Hide resolved
*
* @throws ForageConfigNotSetException If the passed ForagePANEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @param TokenizeEBTCardParams A model that passes a [`foragePanEditText`][com.joinforage.forage.android.ui.ForagePANEditText] instance, `customerId`, and `reusable` boolean as the [TokenizeEBTCardParams] 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. 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.
*/
override suspend fun tokenizeEBTCard(params: TokenizeEBTCardParams): ForageApiResponse<String> {
val (foragePanEditText, customerId, reusable) = params
Expand Down Expand Up @@ -83,17 +93,13 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Checks the balance of a given PaymentMethod using a ForagePINEditText
* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To address the issue involving the lack of newlines. What are your thoughts on the following list item-based workaround for the submit methods in this file?

Also:

  • can we wrap long lines to fit roughly inside the right-hand vertical line in Android studio (around 100 character line length limit)
    • the comments should be digestible for clients reading the comments inside Android Studio, and not just the docs site.
  • can we use the notation @param <parameter-name-not-type-here> Description with reference to type of parameter here (as seen in the example below). Sticking with the KDoc standard should reduce the risk of our Dokka breaking and should provide a more familiar + consistent format throughout our comments.
    /**
     * 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.
     *
     * * On success, the response 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][com.joinforage.forage.android.network.model] 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.
     * @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.
     */
image

*
* @param params The parameters required for balance inquiries, including
* a reference to a ForagePINEditText and PaymentMethod ref
*
* @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
*
* @throws ForageConfigNotSetException If the passed ForagePINEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @param CheckBalanceParams A 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, as the [CheckBalanceParams].
* @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. On success, the 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.
*/
override suspend fun checkBalance(params: CheckBalanceParams): ForageApiResponse<String> {
val (foragePinEditText, paymentMethodRef) = params
Expand Down Expand Up @@ -171,17 +177,13 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Captures a Forage Payment associated with an EBT card
*
* @param params The parameters required for payment capture, including
* reference to a ForagePINEditText and a Payment ref
* Immediately captures a payment via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element.
*
* @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.
*
* @throws ForageConfigNotSetException If the passed ForagePANEditText instance
* hasn't had its ForageConfig set via .setForageConfig().
* @param CapturePaymentParams A 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 [CapturePaymentParams] that Forage uses to capture a payment.
* @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. 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.
*/
override suspend fun capturePayment(params: CapturePaymentParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down Expand Up @@ -269,17 +271,15 @@ class ForageSDK : ForageSDKInterface {
}

/**
* Capture a customer's PIN for an EBT payment and defer the capture of the payment to the server
*
* @param params The parameters required for pin capture, including
* reference to a ForagePINEditText and a Payment ref
* Submits a customer's PIN via a [ForagePINEditText][com.joinforage.forage.android.ui.ForagePINEditText] Element and defers payment capture to the server.
*
* @return A ForageAPIResponse indicating the success or failure of the
* PIN capture. On success, returns `Nothing`.
* On failure, provides a detailed error response.
* @param DeferPaymentCaptureParams A 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].
kimberleehowley marked this conversation as resolved.
Show resolved Hide resolved
*
* @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. 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.
*/
override suspend fun deferPaymentCapture(params: DeferPaymentCaptureParams): ForageApiResponse<String> {
val (foragePinEditText, paymentRef) = params
Expand Down