@nuskin/react-search-sdk 1.1.0-pa-1255.2 → 1.1.0

package/README.md

@@ -1,11 +1,12 @@
 # @nuskin/react-search-sdk
 
 The search experience for the Nu Skin storefront: typeahead and recent searches over the Equinox
-catalog, and the NUi agent when a signed-in shopper searches for something with no products.
+catalog, and the NUi agent when a shopper it is enabled for searches for something with no products.
 
 A host renders one component, `CommerceSearch`, and gives it the market, who the customer is, how to
 navigate, and its logo. The package works out the rest itself: the market's catalog lookup, the
-minimum search length, which NUi app to use, the panel's text and the analytics events. The panel UI
+minimum search length and number of suggestions, which NUi app to use and for whom, the panel's text
+and the analytics events. The panel UI
 comes from `@nuskin/react-search-components` and the agent from
 `@nuskin/react-nui-chat-sdk`.
 
@@ -41,30 +42,57 @@ import { CommerceSearch } from '@nuskin/react-search-sdk';
 />;
 ```
 
-| Prop       | Required | Notes                                                                                                                                                               |
-| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isOpen`   | yes      | The host owns whether the panel is showing.                                                                                                                         |
-| `onClose`  | yes      | Called for Cancel, Escape, the backdrop, and after `navigate`.                                                                                                      |
-| `navigate` | yes      | Receives `{ type: 'internal', path }` (for the router, market prefix already removed) or `{ type: 'external', url }` (full page load). The panel closes afterwards. |
-| `customer` | yes      | `{ isAuthenticated, accountType?, userId? }`. Read on every request, so a change after sign-in is picked up. The agent is for signed-in visitors only.              |
-| `country`  | yes      | ISO 3166-1 alpha-2 market, for example `US`.                                                                                                                        |
-| `language` | yes      | ISO 639-1 language, for example `en`.                                                                                                                               |
-| `logo`     | no       | An element shown at the top of the panel.                                                                                                                           |
-
-The NUi agent also needs the `enableNuiSearch` flag, while that is the on/off switch: either
-`?enableNuiSearch=true` in the URL of the page the panel is opened on, or a cookie `enableNuiSearch=true`
-that you set by hand. The library only reads them and never copies the parameter into the cookie, so the
-parameter applies to that page alone. If both are present the parameter wins, so `?enableNuiSearch=false`
-switches the agent off for a page. It is for signed-in visitors only, unless the configuration sets
-`allowGuestAgent` (today only the test environment does, so the handoff can be tried where signing in
-is not possible).
+| Prop       | Required | Notes                                                                                                                                                                                                                                       |
+| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isOpen`   | yes      | The host owns whether the panel is showing.                                                                                                                                                                                                 |
+| `onClose`  | yes      | Called for Cancel, Escape, the backdrop, and after `navigate`.                                                                                                                                                                              |
+| `navigate` | yes      | Receives `{ type: 'internal', path }` (for the router, market prefix already removed) or `{ type: 'external', url }` (full page load). The panel closes afterwards.                                                                         |
+| `customer` | yes      | `{ isAuthenticated, accountType?, userId? }`. Read on every request, so a change after sign-in is picked up. `accountType` decides which agent switch applies (see below).                                                                  |
+| `country`  | yes      | ISO 3166-1 alpha-2 market, for example `US`.                                                                                                                                                                                                |
+| `language` | yes      | ISO 639-1 language, for example `en`.                                                                                                                                                                                                       |
+| `clientId` | no       | The client id the configuration service knows the host by. Without one the Configuration SDK uses the one in the page's run config; where there is none, the configuration and the suggestions cannot be read and the search does not work. |
+| `logo`     | no       | An element shown at the top of the panel.                                                                                                                                                                                                   |
+
+## Configuration
+
+The package reads the `Commerce_Search` configuration map for the market, through
+`@nuskin/configuration-sdk`, the first time the panel opens (and again at the next open if the read
+failed). Until it has loaded, and whenever it cannot be read, the search is plain search with the
+defaults below.
+
+| Field                                         | Default | Meaning                                                                                     |
+| --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `commerceSearchMinimumLength`                 | `2`     | Characters a term needs before the typeahead looks it up. A whole number, at least 1.       |
+| `commerceSearchMaxSuggestions`                | `6`     | Suggestions asked for and shown. A whole number, at least 1, and never more than 20.        |
+| `commerceSearchAgentAppKey`                   | none    | The NUi app key. The agent needs this and the base URL; with only one of them it stays off. |
+| `commerceSearchAgentApiBaseUrl`               | none    | The origin of the NUi API.                                                                  |
+| `commerceSearchAgentEnabledGuest`             | `false` | The agent is on for visitors who are not signed in.                                         |
+| `commerceSearchAgentEnabledBrandAffiliate`    | `false` | The agent is on for `Brand Affiliate` customers.                                            |
+| `commerceSearchAgentEnabledPreferredCustomer` | `false` | The agent is on for `Preferred Customer/Member` customers.                                  |
+| `commerceSearchAgentEnabledRetailCustomer`    | `false` | The agent is on for `Retail Customer` customers.                                            |
+
+Anything missing or malformed falls back to its default, and a switch is on only when it is exactly
+`true`. A visitor who is not signed in, or whose `accountType` is not one of the three above, is
+treated as a guest.
+
+### The `enableNuiSearch` testing override
+
+The `enableNuiSearch` flag overrides the configuration for the visitor who sets it, in either
+direction: `true` switches the agent on and `false` switches it off, whatever the configuration says
+for their kind of customer, and whether or not they are signed in. It is meant for testing, such as
+trying the agent in production before it is enabled for anyone. An agent still has to be configured
+(app key and base URL). Without the flag the configuration decides.
+
+Set it with `?enableNuiSearch=true` in the URL of the page the panel is opened on, or with a cookie
+`enableNuiSearch=true` that you set by hand. The library only reads them and never copies the
+parameter into the cookie, so the parameter applies to that page alone. If both are present the
+parameter wins, so `?enableNuiSearch=false` switches the agent off for a page. Anyone who knows the
+flag can use it, so it is a testing switch and not an access control.
 
 ### Known gaps
 
 - The panel text is English only. It will be read from Contentstack once its content model exists.
 - Analytics events send `page_type` as `NA` until the data team defines its values.
-- The NUi settings and the Equinox client id are fixed values for the test environment in this
-  package, to be replaced by a configuration store.
 - The `accountType` values are a best guess and need confirming against the suggestions API.
 
 ## Scripts

package/dist/index.d.mts

@@ -23,8 +23,8 @@ type CustomerAccountType = 'guest' | 'Brand Affiliate' | 'Retail Customer' | 'Pr
 /** Who is searching. */
 interface CommerceSearchCustomer {
     /**
-     * Whether the visitor is signed in. The NUi agent is for signed-in visitors only, unless the
-     * package's configuration allows guests.
+     * Whether the visitor is signed in. A visitor who is not signed in is a guest: the
+     * configuration's guest switch decides whether the NUi agent is on for them.
      */
     isAuthenticated: boolean;
     /** Defaults to `guest`. Ignored for a visitor who is not signed in. */

package/dist/index.d.ts

@@ -23,8 +23,8 @@ type CustomerAccountType = 'guest' | 'Brand Affiliate' | 'Retail Customer' | 'Pr
 /** Who is searching. */
 interface CommerceSearchCustomer {
     /**
-     * Whether the visitor is signed in. The NUi agent is for signed-in visitors only, unless the
-     * package's configuration allows guests.
+     * Whether the visitor is signed in. A visitor who is not signed in is a guest: the
+     * configuration's guest switch decides whether the NUi agent is on for them.
      */
     isAuthenticated: boolean;
     /** Defaults to `guest`. Ignored for a visitor who is not signed in. */

package/dist/index.js

@@ -111,6 +111,7 @@ async function fetchCommerceSearchConfig({
 }
 
 // src/hooks/useCommerceSearchConfig.ts
+var MISSING_CLIENT_ID_HINT = "[search] The configuration could not be read and no clientId was passed to CommerceSearch, so the Configuration SDK used the run config of the page. If the page has none, pass the clientId prop: without a client id the search cannot read its configuration or its suggestions.";
 function useCommerceSearchConfig({
   country,
   language,
@@ -124,6 +125,7 @@ function useCommerceSearchConfig({
     currentMarket.current = market;
   }, [market]);
   const reading = react.useRef(null);
+  const hasHintedClientId = react.useRef(false);
   react.useEffect(() => {
     if (!isOpen || loaded?.market === market || reading.current === market) {
       return;
@@ -142,6 +144,10 @@ function useCommerceSearchConfig({
         "[search] Could not load the product search configuration:",
         error
       );
+      if (!clientId && !hasHintedClientId.current) {
+        hasHintedClientId.current = true;
+        console.error(MISSING_CLIENT_ID_HINT);
+      }
     }).finally(() => {
       if (reading.current === market) reading.current = null;
     });
@@ -558,6 +564,7 @@ function createSearchService(options) {
     return catalogRequestConfigPromise;
   }
   const service = {
+    maxSuggestions,
     async fetchSuggestions(searchTerm) {
       const trimmedSearchTerm = String(searchTerm ?? "").trim();
       if (!trimmedSearchTerm || trimmedSearchTerm.length < minimumSearchLength) {
@@ -636,7 +643,8 @@ var fetchMarketConfig = async ({
 // src/utils/gtmConstants.ts
 var SEARCH_GTM_EVENTS = {
   CHAT_ENTRY_POINT: "Begin_chat",
-  PRODUCT_SEARCH: "ProductSearch"};
+  PRODUCT_SEARCH: "ProductSearch"
+};
 var SEARCH_GTM_SEARCH_TYPES = {
   SEMANTIC: "semantic search"};
 var SEARCH_GTM_USER_STATUS = {
@@ -793,17 +801,6 @@ function useRecentSearches({
 }
 
 // src/utils/catalogStatus.ts
-var CART_DISABLED_PRODUCT_STATUSES = /* @__PURE__ */ new Set([
-  "discontinued",
-  "preview",
-  "previewproduct",
-  "test",
-  "stopped",
-  "replacement",
-  "bundleonly",
-  "inactive",
-  "notavailable"
-]);
 function normalizeProductStatusValue(value) {
   return String(value ?? "").trim().toLowerCase().replace(/\s+/g, "");
 }
@@ -816,9 +813,6 @@ function resolveSkuStatusValues(suggestionOption) {
   ].map(normalizeProductStatusValue).filter(Boolean);
 }
 function isNonSellableStatusValue(statusValue) {
-  if (CART_DISABLED_PRODUCT_STATUSES.has(statusValue)) {
-    return true;
-  }
   return statusValue !== "sellable" && statusValue !== "active";
 }
 function isCartActionDisabled(suggestionOption) {
@@ -1056,38 +1050,21 @@ function getVisibleSuggestions(opts) {
 
 // src/hooks/useSearchSuggestions.ts
 function normalizeSuggestionsResponse(response) {
-  if (Array.isArray(response)) {
+  if (Array.isArray(response.product)) {
     return {
-      suggestions: response,
-      didYouMean: []
-    };
-  }
-  if (!response || typeof response !== "object") {
-    return { suggestions: [], didYouMean: [] };
-  }
-  const r = response;
-  if (Array.isArray(r.product)) {
-    return {
-      suggestions: r.product.map(
+      suggestions: response.product.map(
         (product, index) => mapCatalogProductToSuggestion(product, index)
       ).filter((item) => item !== null),
-      didYouMean: normalizeDidYouMean(r.didYouMean ?? r.did_you_mean)
+      didYouMean: normalizeDidYouMean(
+        response.didYouMean ?? response.did_you_mean
+      )
     };
   }
   return {
-    suggestions: Array.isArray(r.suggestions) ? r.suggestions : [],
-    didYouMean: normalizeDidYouMean(r.didYouMean)
+    suggestions: response.suggestions,
+    didYouMean: normalizeDidYouMean(response.didYouMean)
   };
 }
-function resolveTotalResultsCount2(response, fallback) {
-  if (typeof response.totalResultsCount === "number") {
-    return response.totalResultsCount;
-  }
-  if (typeof response.pageableInfo?.totalCount === "number") {
-    return response.pageableInfo.totalCount;
-  }
-  return fallback;
-}
 var FETCH_FAILED = {
   suggestions: [],
   didYouMean: [],
@@ -1106,10 +1083,7 @@ function toSettledResults(response, maxSuggestions) {
       failed: false
     };
   }
-  const total = Math.max(
-    resolveTotalResultsCount2(response, allSuggestions.length),
-    allSuggestions.length
-  );
+  const total = Math.max(response.totalResultsCount, allSuggestions.length);
   const suggestions = allSuggestions.slice(0, maxSuggestions);
   return {
     suggestions,
@@ -1121,9 +1095,9 @@ function toSettledResults(response, maxSuggestions) {
 }
 function useSearchSuggestions({
   service,
-  enabled = true,
-  maxSuggestions = DEFAULT_MAX_SUGGESTIONS
+  enabled = true
 }) {
+  const { maxSuggestions } = service;
   const [query, setQuery] = react.useState("");
   const [suggestions, setSuggestions] = react.useState([]);
   const [didYouMean, setDidYouMean] = react.useState([]);
@@ -1552,7 +1526,6 @@ function CommerceSearchView({
   agentProducts,
   logo,
   minimumSearchLength = MINIMUM_SEARCH_CHAR_LENGTH,
-  maxSuggestions = DEFAULT_MAX_SUGGESTIONS,
   gtmContext
 }) {
   const [handoff, setHandoff] = react.useState(null);
@@ -1560,7 +1533,6 @@ function CommerceSearchView({
   const [pendingTerm, setPendingTerm] = react.useState(null);
   const search = useSearchSuggestions({
     service,
-    maxSuggestions,
     enabled: isOpen && agentQuery === null
   });
   const {
@@ -1852,7 +1824,6 @@ function ValidMarketSearch({
       copy,
       logo,
       minimumSearchLength,
-      maxSuggestions,
       gtmContext
     }
   );