diff --git a/apps/storefront/lib/auth/Readme.md b/apps/storefront/lib/auth/Readme.md index 9358ed808..8a1398883 100644 --- a/apps/storefront/lib/auth/Readme.md +++ b/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) => 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`** -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,7 +97,7 @@ 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(); @@ -105,13 +105,13 @@ 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`** -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(); @@ -119,11 +119,11 @@ 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`** -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({ diff --git a/packages/checkout-storefront/src/lib/auth/Readme.md b/packages/checkout-storefront/src/lib/auth/Readme.md index 0f504cf5f..8a1398883 100644 --- a/packages/checkout-storefront/src/lib/auth/Readme.md +++ b/packages/checkout-storefront/src/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) => 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`** -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,7 +97,7 @@ 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(); @@ -105,13 +105,13 @@ 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`** -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(); @@ -119,11 +119,11 @@ 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`** -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,16 +194,16 @@ 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 staticApolloClient = new ApolloClient({ +export const serverApolloClient = new ApolloClient({ link: createHttpLink({ uri: API_URI }), cache: new InMemoryCache({ typePolicies }), ssrMode: true, @@ -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({