The client needs to handle OAuth-related errors in a user-friendly way

When the client is using OAuth tokens to authenticate to the API (currently this only happens when the client is embedded in a partner site) there are at least four things that can go wrong:

1. The client fails to get the grant token from the partner's web page (for example: the partner site has not inserted the grant token into the page properly)

2. The client's request to the hypothes.is API for an access token fails (for example: the grant token from the client site is invalid)

3. The client has to refresh the access token every hour, because they expire. One of the client's refresh requests to the hypothes.is API could fail (for example: if the user suspends their laptop, or loses their internet connection, so that the access token expires before the client has a chance to send a refresh request).

4. One of the client's requests that try to use the access token fails (e.g. to retrieve annotations from the server, or to make a new annotation, or just to get the user's profile information, etc). This could happen if any of the above three problems happened and then the client still tried to use the access token, or it could happen for some other reason.

Currently the only remedy, when any of the above happen, is for the user to reload the page. This will re-start the whole process: the partner site inserts the grant token into the page, the Hypothesis client extracts the grant token from the page, the client exchanges the grant token with hypothes.is for an access token... And hopefully whatever went wrong won't go wrong again.

When any of the above happen I think we need to show the user some sort of error message to the effect of "Logging into Hypothesis failed, try reloading the page".

I think there are two basic kinds of error message that we could show here:

1. Each time when the user tries to use the access token (for example when they try to make an annotation) and it fails, we can show an error to the user. So for example if you suspended your laptop and your access token expired, and then you opened up the laptop again and started trying to use h on a partner page without reloading the page, then every time you try to do something (like create an annotation) you'll see an error telling you to try reloading the page.

This is how this sort of error message currently looks in the client - the error message from the server is shown in a red bubble that disappears after a while, and if the user tries to create an annotation (or whatever) again and the request fails again then they get the bubble again:


We would need a better-worded error message, of course.

2. Rather than waiting for the user to try to do something such as create an annotation, as soon as something goes wrong (the client fails to retrieve the grant token from the page; or the client's access token request fails; or a refresh fails; or the access token expires) the "you need to reload" error message appears as some sort of "banner" (a permanent error message that does not disappear after a few seconds like the bubbles shown above do).

This is nicer because the user sees immediately that it's not working and they need to reload the page, rather than everything looking fine until they've typed out an annotation and try to save it.

I don't think we have any error message of this sort in the Hypothesis client currently, but here is an example from Slack: with Slack open turn off your internet connection, wait a few seconds, and this appears:


Turn on your internet connection again and it disappears by itself.

I think 1 is needed, 2 is a bonus.

When 2 happens we _could_ also disable the client so that you can't try to create an annotation etc, preventing further occurrences of 1. This would be another bonus.

No files, tests, or entry points are named. Start by locating the client's OAuth grant-token retrieval, access-token exchange, refresh, and authenticated-request flows; done means OAuth failures present a user-friendly reload message, with the banner or disabling behavior resolved as part of the design.

Written by the indexing model from the issue text.