@salesforce/commerce-sdk-react 1.0.0-preview.2 → 1.0.0-preview.4

package/CHANGELOG.md

@@ -1,6 +1,5 @@
-## v1.0.0-preview.2 (Jun 05, 2023)
-## v1.0.0-preview.1 (Jun 02, 2023)
-## v1.0.0-preview.0 (May 31, 2023)
+## v1.0.0-preview.4 (Jun 14, 2023)
+## v1.0.0-preview.3 (Jun 13, 2023)
 ## v1.0.0-dev (May 29, 2023)
 ## v3.0.0-dev (May 12, 2023)
 

package/README.md

@@ -5,12 +5,12 @@ A collection of <a href="https://tanstack.com/query/latest/docs/react/overview">
 
 ## 🎯 Features
 
-- 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
+-   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
 
@@ -43,10 +43,11 @@ const AppConfig = ({children}) => {
             {children}
         </CommerceApiProvider>
     )
-} 
+}
 
 // Set configuration options for react query.
 // NOTE: This configuration will be used both on the server-side and client-side.
+// retry is always disabled on server side regardless of the value from the options
 const options = {
     queryClientConfig: {
         defaultOptions: {
@@ -65,13 +66,12 @@ export default withReactQuery(AppConfig, options)
 
 ## ⚡️ Quickstart (Generic React App)
 
-You can use this library in any React application by creating a new QueryClient and wrap your application with `QueryClientProvider`. For example: 
+You can use this library in any React application by creating a new QueryClient and wrap your application with `QueryClientProvider`. For example:
 
 ```jsx
 import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
 import {QueryClient, QueryClientProvider} from '@tanstack/react-query'
 
-
 const App = ({children}) => {
     const queryClient = new QueryClient()
 
@@ -91,7 +91,7 @@ const App = ({children}) => {
             </CommerceApiProvider>
         </QueryClientProvider>
     )
-} 
+}
 
 export default App
 ```
@@ -104,7 +104,7 @@ To help reduce boilerplate code for managing shopper authentication, by default,
 
 ### 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.
+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
 
@@ -136,19 +136,15 @@ You have the option of handling shopper authentication externally, by providing
 
 ```jsx
 const MyComponent = ({children}) => {
-    return (
-        <CommerceApiProvider fetchedToken="xxxxxxxxxxxx">
-            {children}
-        </CommerceApiProvider>
-    )
-} 
+    return <CommerceApiProvider fetchedToken="xxxxxxxxxxxx">{children}</CommerceApiProvider>
+}
 ```
 
 ## Hooks
 
 The majority of hooks provided in this library are built on top of the [useQuery](https://tanstack.com/query/latest/docs/react/reference/useQuery) and the [useMutation](https://tanstack.com/query/latest/docs/react/reference/useMutation) hook from [react-query](https://tanstack.com/query/latest). React-query provides a declarative way for fetching and updating data. This library takes advantage of the features provided by react-query and combine with the [commerce-sdk-isomorphic](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic) API client to create a collection of hooks to simplify data fetching for SCAPI.
 
-The hooks can be categorized into __Query hooks__ and __Mutation hooks__.
+The hooks can be categorized into **Query hooks** and **Mutation hooks**.
 
 ### Query hooks
 
@@ -158,7 +154,7 @@ The query hooks correspond to the http GET endpoints from the SCAPI. The query h
 use<EntityName>(CommerceClientOptions, ReactQueryOptions)
 ```
 
-Both the __required__ and __optional__ parameters for the underlying `commerce-sdk-isomorphic` call is passed as the first parameter:
+Both the **required** and **optional** parameters for the underlying `commerce-sdk-isomorphic` call is passed as the first parameter:
 
 ```jsx
 import {useProduct} from '@salesforce/commerce-sdk-react'
@@ -171,10 +167,12 @@ const Example = () => {
         }
     })
 
-    return <>
-        <p>isLoading: {query.isLoading}</p>
-        <p>name: {query.data?.name}</p>
-    </>
+    return (
+        <>
+            <p>isLoading: {query.isLoading}</p>
+            <p>name: {query.data?.name}</p>
+        </>
+    )
 }
 ```
 
@@ -186,15 +184,18 @@ import {useBasket} from '@salesforce/commerce-sdk-react'
 const onServer = typeof window === undefined
 
 const Example = ({basketId}) => {
-    const query = useBasket({
-        parameters: {
-            basketId: basketId
+    const query = useBasket(
+        {
+            parameters: {
+                basketId: basketId
+            }
         },
-    }, {
-        // A common use case for `enabled` is
-        // to conditionally fetch based on environment
-        enabled: !onServer && basketId
-    })
+        {
+            // A common use case for `enabled` is
+            // to conditionally fetch based on environment
+            enabled: !onServer && basketId
+        }
+    )
 }
 ```
 
@@ -215,16 +216,22 @@ const Example = ({basketId}) => {
     // Typescript IDE intellisense for available options
     const addItemToBasket = useShopperBasketsMutation('addItemToBasket')
 
-    return <button onClick={() => addItemToBasket.mutate({
-        parameters: {
-            basketId
-        },
-        body: {
-            productId: '25592770M',
-            price: 55,
-            quantity: 1
-        }
-    })} />
+    return (
+        <button
+            onClick={() =>
+                addItemToBasket.mutate({
+                    parameters: {
+                        basketId
+                    },
+                    body: {
+                        productId: '25592770M',
+                        price: 55,
+                        quantity: 1
+                    }
+                })
+            }
+        />
+    )
 }
 ```
 
@@ -247,7 +254,7 @@ const Example = ({basketId}) => {
 
 Since mutations changes data on the server, the cache entries that are potentially affected by the mutation is automatically invalidated.
 
-For example, an `addItemToBasket` mutation automatically update `useBasket`  and `useCustomerBaskets` query cache, because the mutation result contains the information for the updated basket. In other cases, when the mutation response do not have the updated data, the library will invalidate the cache and trigger a re-fetch. For the DELETE endpoints, the library removes the cache entries on successful mutations.
+For example, an `addItemToBasket` mutation automatically update `useBasket` and `useCustomerBaskets` query cache, because the mutation result contains the information for the updated basket. In other cases, when the mutation response do not have the updated data, the library will invalidate the cache and trigger a re-fetch. For the DELETE endpoints, the library removes the cache entries on successful mutations.
 
 _💡 Debugging hint: install and include `@tanstack/react-query-devtools` in your React app to see the queries (inspect the query states and cache keys)._
 
@@ -269,14 +276,13 @@ const Example = () => {
     const fetchProducts = async () => {
         const token = await getTokenWhenReady()
         const products = await api.shopperProducts.getProducts({
-                parameters: {ids: ids.join(',')},
-                headers: {
-                    Authorization: `Bearer ${token}`
-                }
-            })
+            parameters: {ids: ids.join(',')},
+            headers: {
+                Authorization: `Bearer ${token}`
+            }
+        })
         return products
     }
-
 }
 ```
 
@@ -303,18 +309,19 @@ useCustomerId() => null | 'guest' | 'registered'
 ### `useEncUserId()`
 
 ```ts
-useEncUserId() => null | string
+useEncUserId() => {encUserId: String, getEncUserIdWhenReady: Promise}
 ```
 
 ### `useUsid()`
 
 ```ts
-useUsid() => null | string
+useUsid() => {usid: String, getUsidWhenReady: Promise}
 ```
 
 ## Roadmap
-- Optimistic update support
-- SLAS private client support
+
+-   Optimistic update support
+-   SLAS private client support
 
 ## Useful Links:
 

package/hooks/useEncUserId.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @group Shopper Authentication helpers
+ */
+interface EncUserId {
+    encUserId: string | null;
+    getEncUserIdWhenReady: () => Promise<string>;
+}
 /**
  * Hook that returns the ecom user ID.
  *
@@ -7,6 +14,6 @@
  * @category Shopper Authentication
  *
  */
-declare const useEncUserId: () => string | null;
+declare const useEncUserId: () => EncUserId;
 export default useEncUserId;
 //# sourceMappingURL=useEncUserId.d.ts.map

package/hooks/useEncUserId.js

@@ -17,6 +17,10 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
 
 const onClient = typeof window !== 'undefined';
 
+/**
+ * @group Shopper Authentication helpers
+ */
+
 /**
  * Hook that returns the ecom user ID.
  *
@@ -29,11 +33,18 @@ const onClient = typeof window !== 'undefined';
 const useEncUserId = () => {
   const config = (0, _useConfig.default)();
   const auth = (0, _useAuthContext.default)();
-  return onClient ?
+  const encUserId = onClient ?
   // This conditional is a constant value based on the environment, so the same path will
   // always be followed., and the "rule of hooks" is not violated.
   // eslint-disable-next-line react-hooks/rules-of-hooks
-  (0, _useLocalStorage.default)(`$enc_user_id_${config.siteId}`) : auth.get('enc_user_id');
+  (0, _useLocalStorage.default)(`enc_user_id_${config.siteId}`) : auth.get('enc_user_id');
+  const getEncUserIdWhenReady = () => auth.ready().then(({
+    enc_user_id
+  }) => enc_user_id);
+  return {
+    encUserId,
+    getEncUserIdWhenReady
+  };
 };
 var _default = useEncUserId;
 exports.default = _default;

package/hooks/useQuery.js

@@ -7,6 +7,7 @@ exports.useQuery = void 0;
 var _reactQuery = require("@tanstack/react-query");
 var _useAuthorizationHeader = require("./useAuthorizationHeader");
 var _utils = require("./utils");
+var _utils2 = require("../utils");
 function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
 function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
@@ -45,13 +46,17 @@ const useQuery = (apiOptions, queryOptions, hookConfig) => {
       return _ref.apply(this, arguments);
     };
   }();
-  return (0, _reactQuery.useQuery)(hookConfig.queryKey, wrappedMethod, _objectSpread({
+  return (0, _reactQuery.useQuery)(hookConfig.queryKey, wrappedMethod, _objectSpread(_objectSpread(_objectSpread({
     enabled:
     // Individual hooks can provide `enabled` checks that are done in ADDITION to
     // the required parameter check
     hookConfig.enabled !== false &&
     // The default `enabled` is "has all required parameters"
     (0, _utils.hasAllKeys)(apiOptions.parameters, hookConfig.requiredParameters)
-  }, queryOptions));
+  }, queryOptions), queryOptions !== null && queryOptions !== void 0 && queryOptions.retry ? {
+    retry: (0, _utils2.onClient)() ? queryOptions === null || queryOptions === void 0 ? void 0 : queryOptions.retry : false
+  } : {}), queryOptions !== null && queryOptions !== void 0 && queryOptions.retryOnMount ? {
+    retryOnMount: (0, _utils2.onClient)() ? queryOptions === null || queryOptions === void 0 ? void 0 : queryOptions.retryOnMount : false
+  } : {}));
 };
 exports.useQuery = useQuery;

package/hooks/useUsid.d.ts

@@ -1,9 +1,16 @@
+/**
+ * @group Shopper Authentication helpers
+ */
+interface Usid {
+    usid: string | null;
+    getUsidWhenReady: () => Promise<string>;
+}
 /**
  * Hook that returns the usid associated with the current access token.
  *
  * @group Helpers
  * @category Shopper Authentication
  */
-declare const useUsid: () => string | null;
+declare const useUsid: () => Usid;
 export default useUsid;
 //# sourceMappingURL=useUsid.d.ts.map

package/hooks/useUsid.js

@@ -5,8 +5,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _useAuthContext = _interopRequireDefault(require("./useAuthContext"));
-var _useLocalStorage = _interopRequireDefault(require("./useLocalStorage"));
-var _useConfig = _interopRequireDefault(require("./useConfig"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /*
  * Copyright (c) 2022, salesforce.com, inc.
@@ -15,7 +13,9 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-const onClient = typeof window !== 'undefined';
+/**
+ * @group Shopper Authentication helpers
+ */
 
 /**
  * Hook that returns the usid associated with the current access token.
@@ -24,13 +24,21 @@ const onClient = typeof window !== 'undefined';
  * @category Shopper Authentication
  */
 const useUsid = () => {
-  const config = (0, _useConfig.default)();
   const auth = (0, _useAuthContext.default)();
-  return onClient ?
-  // This conditional is a constant value based on the environment, so the same path will
-  // always be followed., and the "rule of hooks" is not violated.
-  // eslint-disable-next-line react-hooks/rules-of-hooks
-  (0, _useLocalStorage.default)(`usid_${config.siteId}`) : auth.get('usid');
+
+  // TODO: auth.get does not trigger a re-render.
+  // This is fine for now since the only time the usid changes is on logout
+  // and currently when we log out we redirect to the login page which
+  // causes components to unmount.
+  // This will need to change if we stay on the PDP after logout
+  const usid = auth.get('usid');
+  const getUsidWhenReady = () => auth.ready().then(({
+    usid
+  }) => usid);
+  return {
+    usid,
+    getUsidWhenReady
+  };
 };
 var _default = useUsid;
 exports.default = _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/commerce-sdk-react",
-  "version": "1.0.0-preview.2",
+  "version": "1.0.0-preview.4",
   "description": "A library that provides react hooks for fetching data from Commerce Cloud",
   "homepage": "https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/ecom-react-hooks#readme",
   "bugs": {
@@ -47,7 +47,7 @@
     "typedoc-plugin-missing-exports": "^2.0.0"
   },
   "devDependencies": {
-    "@salesforce/pwa-kit-dev": "3.0.0-preview.2",
+    "@salesforce/pwa-kit-dev": "3.0.0-preview.4",
     "@tanstack/react-query": "^4.28.0",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^14.0.0",
@@ -59,7 +59,7 @@
     "@types/react-dom": "^18.2.1",
     "@types/react-helmet": "^6.1.6",
     "cross-env": "^5.2.1",
-    "internal-lib-build": "3.0.0-preview.2",
+    "internal-lib-build": "3.0.0-preview.4",
     "jsonwebtoken": "^9.0.0",
     "nock": "^13.3.0",
     "nodemon": "^2.0.22",
@@ -86,5 +86,5 @@
   "publishConfig": {
     "directory": "dist"
   },
-  "gitHead": "a2476c090ce48fd09e9116437aedc6cc45ae60bd"
+  "gitHead": "06b3f17fd233777136fdb699aa93df4c52874217"
 }