Update Readme.md (saleor#771)

apps/storefront/lib/auth/Readme.md

@@ -2,7 +2,7 @@
 
 ## SaleorAuthClient
 
-Most of the authentication flow is managed to by a vanilla JS class SaleorAuthClient. You can create an instance providing a couple of props:
+Most of the authentication flow is managed by a vanilla JS class `SaleorAuthClient`. You can create an instance providing a couple of props:
 
 ```javascript
 interface SaleorAuthClientProps {
@@ -12,11 +12,11 @@ interface SaleorAuthClientProps {
 }
 ```
 
-`saleorApiUrl` is required so the auth module can refresh access token on its own.
+`saleorApiUrl` is required so the auth module can refresh the access token.
 
-## How do I tell my graphql client to use authentication?
+## How do I tell my GraphQL client to use authentication?
 
-SaleorAuthClient class provdies an `fetchWithAuth` method, that you should pass to your graphql client. That'll ensure that once user signs in, every request will be authenticated.
+The `SaleorAuthClient` class provides a `fetchWithAuth` method that you should pass to your GraphQL client. That will ensure that every request will be authenticated once the user signs in.
 
 ```javascript
 const { authFetch } = new SaleorAuthClient(clientProps);
@@ -31,7 +31,7 @@ createClient({
 
 #### **`useSaleorAuthClient({ saleorApiUrl, storage, onAuthRefresh }: UseSaleorAuthClientProps) => SaleorAuthClientProps`**
 
-On top of taking part in react component lifecycle, because the client sets event listeners on the window, we need to remove those once we're done. Hence we're proving an `useSaleorAuthClient` hook that does exactly that. It takes up the same props as `SaleorAuthClient` and returns the instance of SaleorAuthClient along with isAuthenticating prop.
+The authentication occurs in the React component lifecycle by setting the event listeners on the window. After the listeners are resolved, we need to make sure we removed them. For that purpose, we are providing an `useSaleorAuthClient` hook. It takes up the same props as `SaleorAuthClient` and returns the instance of `SaleorAuthClient` along with the `isAuthenticating` prop.
 
 ```javascript
 const { saleorAuthClient, isAuthenticating } = useSaleorAuthClient({
@@ -44,7 +44,7 @@ const { saleorAuthClient, isAuthenticating } = useSaleorAuthClient({
 
 #### **`SaleorAuthProvider({ saleorAuthClient, isAuthenticating, children }: PropsWithChildren<UseSaleorAuthClient>) => JSX.Element`**
 
-The hook is supposed to be used only in the root of your project. If you'd like to access the client methods or isAuthenticating prop down the tree without extensive prop drilling, you can use `SaleorAuthProvider` passing it down the return value of useSaleorAuthClient hook.
+The hook should be used only at the root of your project. If you would like to access the client methods or the `isAuthenticating` prop down the tree without extensive prop drilling, you can use the `SaleorAuthProvider`. As the value for it, you should use the result of the `useSaleorAuthClient` hook.
 
 ```jsx
 const saleorAuthClientData = useSaleorAuthClient(authClientProps)
@@ -58,7 +58,7 @@ const saleorAuthClientData = useSaleorAuthClient(authClientProps)
 
 #### **`useSaleorAuthContext() => SaleorAuthContextConsumerProps`**
 
-The provider also equips you with `useSaleorAuthContext` hook
+The provider also equips you with the `useSaleorAuthContext` hook:
 
 ```javascript
 const { isAuthenticating, signIn, signOut, checkoutSignOut } = useSaleorAuthContext();
@@ -68,7 +68,7 @@ const { isAuthenticating, signIn, signOut, checkoutSignOut } = useSaleorAuthCont
 
 #### **`useAuthChange({ onSignedIn, onSignedOut }: UseAuthChangeProps) => void`**
 
-Once the successful sign in or sign out happens, as well as failed authentication (for e.g when refresh token is expired and there's no way to obtain a new access token from the api) you'll probably want to trigger some actions. Hence we're provided a `useAuthChange` hook that'll listen to storage changes and trigger callbacks.
+We provided a `useAuthChange` hook that listens to storage changes and triggers callbacks.
 
 ```javascript
   useAuthChange({
@@ -82,7 +82,7 @@ Once the successful sign in or sign out happens, as well as failed authenticatio
 
 #### **`SaleorAuthClient.signIn: ({ email, password }: TokenCreateVariables) => Promise<TokenCreateResponse>`**
 
-SaleorAuthClient returns a `signIn` method. You can also access it via the **useSaleorAuthContext** hook.
+`SaleorAuthClient` returns a `signIn` method. You can also access it via the **useSaleorAuthContext** hook.
 
 ```javascript
 const { signIn } = useSaleorAuthContext();
@@ -97,33 +97,33 @@ const response = await signIn({
 
 #### **`SaleorAuthClient.signOut: () => void`**
 
-This method will remove access and refresh tokens from SaleorAuthClient state and storage. It'll also trigger sign out event, which in turn will trigger [onSignOut method of useAuthChange hook](#how-do-i-tell-my-graphql-client-to-refresh-queries-on-signin--signout)
+This method will remove access and refresh tokens from the `SaleorAuthClient` state and storage. It will also call the sign-out event, which will trigger [`onSignOut` method of the `useAuthChange` hook](#how-do-i-tell-my-graphql-client-to-refresh-queries-on-signin--signout).
 
 ```javascript
 const { signOut } = useSaleorAuthContext();
 
 signOut();
 ```
 
-⚠️ For checkout sign out see [signing out in checkout](#how-do-i-sign-out-in-checkout)
+⚠️ For checkout sign-out, see [signing-out in checkout](#how-do-i-sign-out-in-checkout).
 
 ## How do I sign out in checkout?
 
 #### **`SaleorAuthClient.checkoutSignOut: ({ checkoutId }: CustomerDetachVariables) => Promise<CustomerDetachResponse>`**
 
-On top of the regular sign out login, in checkout we need to start signing out process with detaching customer from checkout. Since detach requires a signed in user, it'll happen first and removing tokens from state / storage will only happen if the mutation returned success:
+When dealing with authentication in the checkout, we need to start the signing-out process by detaching the customer from checkout. Since it requires the user to be signed in, it must be executed first. If the mutation succeeds, the tokens from the state/storage will be removed.
 
 ```javascript
 const { checkoutSignOut } = useSaleorAuthContext();
 
 const response = await checkoutSignOut({ checkoutId: checkout.id });
 ```
 
-## How does auth handle resetting password?
+## How do I reset password?
 
 #### **`SaleorAuthClient.resetPassword: ({ email, password, token }: PasswordResetVariables) => Promise<PasswordResetResponse>`**
 
-SaleorAuthClient class provides you with a reset password method. If the reset password mutation is successful, it'll log you in automatically just like after a regular sign in. The [onSignIn method of useAuthChange hook](#how-do-i-tell-my-graphql-client-to-refresh-queries-on-signin--signout) will also be triggered.
+The `SaleorAuthClient` class provides you with a reset password method. If the reset password mutation is successful, it will log you in automatically, just like after a regular sign-in. The [`onSignIn` method of `useAuthChange` hook](#how-do-i-tell-my-graphql-client-to-refresh-queries-on-signin--signout) will also be triggered.
 
 ```javascript
 const { resetPassword } = useSaleorAuthContext();
@@ -135,9 +135,9 @@ const response = await resetPassword({
 });
 ```
 
-## How do I use this with Urql?
+## How do I use this with urql?
 
-Once an authentication change happens, you might want to refetch some of your queries. Because Urql doesn't provide a direct way to invalidate cache manually, we're following urql's [proposed approach](https://github.com/urql-graphql/urql/issues/297#issuecomment-501646761) of installing a new instance of the client in place of the old one. We have a hook for that called `useUrqlClient` that takes Urql `ClientOptions` as an only argument and returns the current `urqlClient` and `resetClient` function:
+Once an authentication change happens, you might want to refetch some of your queries. Because urql doesn't provide a direct way to invalidate cache manually, we're following urql's [proposed approach](https://github.com/urql-graphql/urql/issues/297#issuecomment-501646761) of installing a new instance of the client in place of the old one. We have a hook for that called `useUrqlClient` that takes urql `ClientOptions` as the only argument and returns the current `urqlClient` and the `resetClient` function:
 
 ```javascript
 const { urqlClient, resetClient } = useUrqlClient({
@@ -147,7 +147,7 @@ const { urqlClient, resetClient } = useUrqlClient({
 });
 ```
 
-Then, you'll want to pass the `resetClient` function to the useAuthChange hook
+Then, you may want to pass the `resetClient` function to the `useAuthChange` hook:
 
 ```javascript
 useAuthChange({
@@ -194,13 +194,13 @@ export const App = () => {
 
 ### How do I use it with Apollo?
 
-We have a hook for that called useApolloClient that authenticated fetch as its only argument and returns the current client and resetClient function
+We provide support for Apollo with a hook called `useApolloClient` that authenticates fetch as its only argument and returns the current client, as well as the `resetClient` function:
 
 ```javascript
 const { apolloClient, resetClient } = useApolloClient(saleorAuthClient.fetchWithAuth);
 ```
 
-Becasue we're using the client to also retrieve unauthenticated data in SSR, we separated them into two - one for SSR, that can be used outside of React flow, and the other returned by our hook.
+Because we're using the client to also retrieve unauthenticated data in SSR, we separated them into two - one for SSR, which can be used outside of React flow, and the other returned by our hook.
 
 ```javascript
 export const serverApolloClient = new ApolloClient({
@@ -228,7 +228,7 @@ export const useApolloClient = (fetchWithAuth: Fetch) => {
 };
 ```
 
-Once you get the client with authenticated fetch, you'll want to pass the `resetClient` function to the useAuthChange hook
+Once you get the client with authenticated fetch, you'll want to pass the `resetClient` function to the `useAuthChange` hook:
 
 ```javascript
 useAuthChange({