Improve error messages during account setup

[cketti]

Currently our error messages during account setup aren't as detailed as they could and should be.

When we're able to connect to an IMAP server, but that server returns an error message, we currently don't show it to the user. But we should.

For network errors we should provide more details (e.g. no internet connectivity, server couldn't be reached, name couldn't be resolved).

[kewisch]

When you work on this issue, please think about the categories of errors and how to present this to the user. We don't just want to pipe through any error message to the user. Thank you for considering!

[kewisch]

A good first step for this issue would be to:

• Determine what types of errors could occur during account setup and categorize them
• Determine what errors we could show a more pretty message about, and which ones would need the raw server message

@snk-git-hub not sure if you are still interested, but if so what are your thoughts on these questions?

[joohnq]

Hey, someone could give me a north where this should be implemented?

[kewisch]

I think the more product-focused questions above would be a good first step before implementation. If you could check in on Matrix afterwards I think that will give you a quicker engineering answer :)

[rafaeltonholo]

Hi @joohnq,

Thank you for your interest in this issue!

To complete this task, we need to finish some other tasks in the In-app error notification epic first. However, as @kewisch mentioned, a great first step would be to categorize the account setup errors, and we would greatly appreciate your assistance with this.

Here are the steps I would take to start identifying and categorizing the account setup errors:

1. Identify the Current Errors We Display

The first step is to identify the current errors we display and understand what may be unclear to the user. It’s crucial to ensure that the error messages are clear from the perspective of a non-power user (a user without a technical background).

A good starting point would be the module :feature:account:setup. Here are a few key files to begin reviewing:

• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/ui/autodiscovery/AutoDiscoveryStringMapper.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/ui/autodiscovery/AccountAutoDiscoveryViewModel.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/ui/autodiscovery/AccountAutoDiscoveryStateMapper.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/ui/createaccount/CreateAccountViewModel.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/domain/usecase/GetAutoDiscovery.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/domain/usecase/CreateAccount.kt
• feature/account/setup/src/main/kotlin/app/k9mail/feature/account/setup/domain/usecase/GetSpecialFolderOptions.kt

2. Understand IMAP Server Errors

During account setup, we send certain IMAP commands to the server to initiate authentication, check special folders, etc. The next step is to understand these commands and identify the potential error responses they may yield. Typically, if an IMAP command fails on the server, the response begins with "BAD".

Here are some commands we execute during setup, but this is not an exhaustive list:

• CAPABILITY
• AUTHENTICATE
• ID
• NAMESPACE
• LIST

You can find the definitions of these commands in RFC 3501 and RFC 9051 (@kewisch please correct me if I'm wrong or missed any RFC).

3. Map IMAP Command Errors

Once you have identified the possible error responses from the IMAP server for the commands used during account setup, the next step is to map these errors in the application. Check to see if they have been mapped yet and provide clear reasoning for each, ideally offering a solution that can be displayed to the user.

4. Display the Error Message

Lastly, we need to present the error to the user. This can be done using the new (under development) NotificationSender, creating an InAppNotification related to each error, which could also be reused later if the error occurs again after the account setup. Alternatively, we could handle it directly within the :feature:account:setup module by managing the state outcome of the use cases.

I prefer using the NotificationSender and InAppNotification as this would test the new API and allow the app to handle similar errors in the future. However, this approach depends on issues #9245 and #9312, so I am also fine with the second method.

[!IMPORTANT] It's important to note that steps 3 and 4 may require guidance from both UX and UI perspectives. I would love to hear @solangevalverde’s thoughts on this.

---

I also think it would be beneficial to split this task into smaller tasks, such as:

• IMAP errors categorization and identification
• A task to handle each IMAP error identified

Please let me know if you are interested in working on this, and I will create the smaller tasks and assign them to you.

[joohnq]

I'll check it out and get back to you.

[joohnq]

Well, I’ve studied the scenarios, but I feel I don’t yet have a broad enough understanding of the app to fully cover all the cases in this issue. Maybe, when the @rafaeltonholo splits the task into smaller ones, I can contribute.

[solangevalverde]

The good news is that I have an upcoming task that covers account setup adjustments 🎉. "Bad" news is that the design would be ready by the end of next week if not sooner. Once ready, I can upload designs here unless @laurelterlesky has conflicting information 👀 ps.: @Jesse-Moz this is something to keep an eye while we tackle the FTUE discovery task.