-## Documentation
+## 🎯 Features
-The full documentation for PWA Kit and Managed Runtime is hosted on the [Salesforce Developers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/overview) portal.
+- Shopper authentication & token management via [SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login)
+- Server side data fetching (in conjuction with PWA Kit)
+- Phased Launch support ([plugin_slas](https://github.com/SalesforceCommerceCloud/plugin_slas) compatible)
+- Built-in caching for easy state management
+ - automatic cache invalidations/updates via the library's built-in mutations
+ - automatic cache key generation
+## ⚙️ Installation
-## PWA-Kit Integration
+```bash
+npm install @salesforce/commerce-sdk-react @tanstack/react-query
+```
-> To integration this library with your PWA-Kit application you can use the `CommerceApiProvider` directly given that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished.
+## ⚡️ Quickstart (PWA Kit v2.3.0+)
-```
+To integrate this library with your PWA Kit application you can use the `CommerceApiProvider` directly assuming that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished.
+
+```jsx
// app/components/_app-config/index.jsx
+import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
import {withReactQuery} from 'pwa-kit-react-sdk/ssr/universal/components/with-react-query'
const AppConfig = ({children}) => {
return (
-
+
{children}
)
@@ -42,20 +63,30 @@ const options = {
export default withReactQuery(AppConfig, options)
```
-## Generic Integration
+## ⚡️ Quickstart (Generic React App)
-> You can use this library in any React application provided you bring your own QueryClient and QueryClientProvider. Below is a sample integration:
+You can use this library in any React application by creating a new QueryClient and wrap your application with `QueryClientProvider`. For example:
-```
-import {QueryClient, QueryClientConfig, QueryClientProvider} from '@tanstack/react-query'
+```jsx
+import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query'
const App = ({children}) => {
- const queryClient = new QueryClient(queryClientConfig)
+ const queryClient = new QueryClient()
return (
-
+
{children}
@@ -64,7 +95,224 @@ const App = ({children}) => {
export default App
```
-### Useful Links:
+
+## Shopper Authentication and Token Management
+
+_💡 This section assumes you have read and completed the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._
+
+To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Currently, the library supports the [Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html).
+
+### Shopper Session Initialization
+
+On `CommerceApiProvider` mount, the provider initializes shopper session by initiating the SLAS __Public Client__ login flow. The tokens are stored/managed/refreshed by the library.
+
+### Authenticate request queue
+
+While the library is fetching/refreshing the access token, the network requests will queue up until there is a valid access token.
+
+### Login helpers
+
+To leverage the managed shopper authentication feature, use the `useAuthHelper` hook for shopper login.
+
+Example:
+
+```jsx
+import {AuthHelpers, useAuthHelper} from '@salesforce/commerce-sdk-react'
+
+const Example = () => {
+ const register = useAuthHelper(AuthHelpers.Register)
+ const login = useAuthHelper(AuthHelpers.LoginRegisteredUserB2C)
+ const logout = useAuthHelper(AuthHelpers.LogOut)
+
+ return