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 b0f6e106..a524b83c 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 @@ -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 _getForageConfigOrThrow(element: AbstractForageElement): 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 @@ -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 { val (foragePanEditText, customerId, reusable) = params @@ -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 { val (foragePinEditText, paymentMethodRef) = params @@ -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 { val (foragePinEditText, paymentRef) = params @@ -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 { val (foragePinEditText, paymentRef) = params