@nosto/nosto-react 0.3.0 → 0.4.0

package/src/components/Provider/index.client.tsx

@@ -1,24 +1,68 @@
 import React, { useEffect, isValidElement, useState, useRef } from "react";
 import { NostoContext } from "./context.client";
 import { createRoot } from "react-dom/client";
+import { Recommendation } from "../../types";
 
-interface NostoProviderProps {
+/**
+ * This widget is what we call the Nosto root widget, which is responsible for adding the actual Nosto script and the JS API stub.
+ * This widget wraps all other React Nosto widgets.
+ *
+ * ```
+ * <NostoProvider account="your-nosto-account-id" recommendationComponent={<NostoSlot />}>
+ *   <App />
+ * </NostoProvider>
+ * ```
+ *
+ * **Note:** the component also accepts a prop to configure the host `host="connect.nosto.com"`.
+ * In advanced use-cases, the need to configure the host may surface.
+ *
+ * In order to implement client-side rendering, the requires a designated component to render the recommendations provided by Nosto.
+ * This component should be capable of processing the JSON response received from our backend.
+ * Notice the `recommendationComponent` prop passed to `<NostoProvider>` above.
+ *
+ * Learn more [here](https://github.com/Nosto/shopify-hydrogen/blob/main/README.md#client-side-rendering-for-recommendations) and see a [live example](https://github.com/Nosto/shopify-hydrogen-demo) on our demo store.
+ *
+ * @group Essential Functions
+ */
+export default function NostoProvider(props: {
+  /**
+   * Indicates merchant id
+   */
   account: string;
-  currentVariation: string;
-  host: string;
+  /**
+   * Indicates currency
+   */
+  currentVariation?: string;
+  /**
+   * Indicates an url of a server
+   */
+  host?: string;
   children: React.ReactElement;
-  multiCurrency: boolean;
+  /**
+   * Indicates if merchant uses multiple currencies
+   */
+  multiCurrency?: boolean;
+  /**
+   * Recommendation component which holds nostoRecommendation object
+   */
   recommendationComponent?: any;
-}
-
-const NostoProvider: React.FC<NostoProviderProps> = ({
-  account,
-  currentVariation = "",
-  multiCurrency = false,
-  host,
-  children,
-  recommendationComponent,
-}) => {
+  /**
+  * Enables Shopify markets with language and market id
+  */
+  shopifyMarkets?: {
+    language?: string;
+    marketId?: string | number;
+  }
+}): JSX.Element {
+  let {
+    account,
+    currentVariation = "",
+    multiCurrency = false,
+    host,
+    children,
+    recommendationComponent,
+    shopifyMarkets
+  } = props;
   const [clientScriptLoadedState, setClientScriptLoadedState] =
     React.useState(false);
   const clientScriptLoaded = React.useMemo(
@@ -35,8 +79,10 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
     : "HTML";
 
   // RecommendationComponent for client-side rendering:
-  function RecommendationComponentWrapper(props: any) {
-    return React.cloneElement(recommendationComponent, {
+  function RecommendationComponentWrapper(props: {
+    nostoRecommendation: Recommendation;
+  }) {
+    return React.cloneElement(recommendationComponent!, {
       nostoRecommendation: props.nostoRecommendation,
     });
   }
@@ -53,7 +99,21 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
 
     const pageTypeUpdated = type == pageType;
 
-    function renderCampaigns(data: any, api: any) {
+    function renderCampaigns(
+      data: {
+        recommendations: any;
+        campaigns: {
+          recommendations: {
+            [key: string]: any;
+          };
+        };
+      },
+      api: {
+        placements: {
+          injectCampaigns: (recommendations: any) => void;
+        };
+      }
+    ) {
       if (responseMode == "HTML") {
         // inject content campaigns as usual:
         api.placements.injectCampaigns(data.recommendations);
@@ -65,6 +125,7 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
           let placementSelector = "#" + key;
           let placement: Function = () =>
             document.querySelector(placementSelector);
+
           if (!!placement()) {
             if (!placementRefs.current[key])
               placementRefs.current[key] = createRoot(placement());
@@ -81,25 +142,67 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
     return { renderCampaigns, pageTypeUpdated };
   };
 
+
   useEffect(() => {
-    if (!document.querySelectorAll("[nosto-client-script]").length) {
+    if (!window.nostojs) {
+      window.nostojs = (cb: Function) => {
+        (window.nostojs.q = window.nostojs.q || []).push(cb);
+      };
+      window.nostojs((api) => api.setAutoLoad(false));
+    }
+
+    if (!document.querySelectorAll("[nosto-client-script]").length && !shopifyMarkets) {
       const script = document.createElement("script");
       script.type = "text/javascript";
       script.src = "//" + (host || "connect.nosto.com") + "/include/" + account;
       script.async = true;
       script.setAttribute("nosto-client-script", "");
+
       script.onload = () => {
-        console.log("Nosto client script loaded");
+        if (typeof jest !== "undefined") {
+          window.nosto?.reload({
+            site: "localhost",
+          });
+        }
         setClientScriptLoadedState(true);
       };
-      document.head.appendChild(script);
+      document.body.appendChild(script);
     }
 
-    window.nostojs = (cb: Function) =>
-      (window.nostojs.q = window.nostojs.q || []).push(cb);
-    // @ts-ignore
-    window.nostojs((api) => api.setAutoLoad(false));
-  }, []);
+    //Enable Shopify markets functionality:
+    if (!!shopifyMarkets) {
+
+      const existingScript = document.querySelector("[nosto-client-script]");
+      const nostoSandbox = document.querySelector('#nosto-sandbox');
+
+      if (!existingScript || existingScript?.getAttribute('nosto-language') != shopifyMarkets?.language || existingScript?.getAttribute('nosto-market-id') != shopifyMarkets?.marketId) {
+        if (clientScriptLoadedState) { setClientScriptLoadedState(false) };
+
+        existingScript?.parentNode?.removeChild(existingScript)
+        nostoSandbox?.parentNode?.removeChild(nostoSandbox)
+
+        const script = document.createElement("script");
+        script.type = "text/javascript";
+        script.src = "//" + (host || "connect.nosto.com") + `/script/shopify/market/nosto.js?merchant=${account}&market=${shopifyMarkets.marketId || ''}&locale=${shopifyMarkets?.language?.toLowerCase() || ''}`
+        script.async = true;
+        script.setAttribute("nosto-client-script", "");
+        script.setAttribute("nosto-language", shopifyMarkets?.language || '');
+        script.setAttribute("nosto-market-id", String(shopifyMarkets?.marketId));
+
+        script.onload = () => {
+          if (typeof jest !== "undefined") {
+            window.nosto?.reload({
+              site: "localhost",
+            });
+          }
+          setClientScriptLoadedState(true);
+        };
+        document.body.appendChild(script);
+      }
+
+    }
+
+  }, [clientScriptLoadedState, shopifyMarkets]);
 
   return (
     <NostoContext.Provider
@@ -116,6 +219,4 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
       {children}
     </NostoContext.Provider>
   );
-};
-
-export default NostoProvider;
+}

package/src/components/Search/index.client.tsx

@@ -1,7 +1,31 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
+/**
+ * You can personalise your search pages by using the NostoSearch component.
+ * The component requires that you provide it the current search term.
+ *
+ * By default, your account, when created, has two search-page placements named `searchpage-nosto-1` and `searchpage-nosto-2`.
+ * You may omit these and use any identifier you need. The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="search-page">
+ *   <NostoPlacement id="searchpage-nosto-1" />
+ *   <NostoPlacement id="searchpage-nosto-2" />
+ *   <NostoSearch query={"black shoes"} />
+ * </div>
+ * ```
+ *
+ * **Note:** Do not encode the search term in any way.
+ * It should be provided an unencoded string.
+ * A query for `black shoes` must be provided as-is and not as `black+shoes`.
+ * Doing so will lead to invalid results.
+ *
+ * @group Personalisation Components
+ */
+export default function NostoSearch(props: { query: string }): JSX.Element {
+  const { query } = props;
   const {
     clientScriptLoaded,
     currentVariation,
@@ -13,9 +37,8 @@ const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
   const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("search");
 
   useEffect(() => {
-    // @ts-ignore
     if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -23,7 +46,7 @@ const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
           .viewSearch(query)
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
+          .then((data) => {
             renderCampaigns(data, api);
           });
       });
@@ -46,6 +69,4 @@ const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
       </div>
     </>
   );
-};
-
-export default NostoSearch;
+}

package/src/components/Session/index.client.tsx

@@ -1,24 +1,31 @@
-import React from "react";
-import snakeize from "snakeize";
 import { useNostoContext } from "../Provider/context.client";
-
-import useDeepCompareEffect from "use-deep-compare-effect";
 import { Cart, Customer } from "../../types";
+import { snakeize } from "../../utils/snakeize";
+import { useDeepCompareEffect } from "../../utils/hooks";
 
-interface NostoSessionProps {
+/**
+ * Nosto React requires that you pass it the details of current cart contents and the details of the currently logged-in customer, if any, on every route change.
+ * This makes it easier to add attribution.
+ *
+ * The `NostoSession` component makes it very easy to keep the session up to date so long as the cart and the customer are provided.
+ *
+ * The cart prop requires a value that adheres to the type `Cart`, while the customer prop requires a value that adheres to the type `Customer`.
+ *
+ * @group Essential Functions
+ */
+export default function NostoSession(props: {
   cart: Cart;
   customer: Customer;
-}
-
-const NostoSession: React.FC<NostoSessionProps> = ({ cart, customer }) => {
+}): JSX.Element {
+  const { cart, customer } = props;
   const { clientScriptLoaded } = useNostoContext();
+
   useDeepCompareEffect(() => {
     const currentCart = cart ? snakeize(cart) : undefined;
     const currentCustomer = customer ? snakeize(customer) : undefined;
 
-    // @ts-ignore
     if (clientScriptLoaded) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setResponseMode("HTML")
@@ -28,9 +35,7 @@ const NostoSession: React.FC<NostoSessionProps> = ({ cart, customer }) => {
           .load();
       });
     }
-  }, [clientScriptLoaded, cart || [], customer || {}]);
+  }, [clientScriptLoaded, cart, customer]);
 
   return <></>;
-};
-
-export default NostoSession;
+}

package/src/index.client.ts

@@ -1,12 +1,6 @@
-declare global {
-  // noinspection JSUnusedGlobalSymbols
-  interface Window {
-    nostojs: any;
-    nosto: any;
-  }
-}
-
-export * from "./types";
+export type {
+  Buyer, Cart, Customer, Item, Product, Purchase, Recommendation, SKU
+} from "./types";
 // noinspection JSUnusedGlobalSymbols
 export { default as Nosto404 } from "./components/Fohofo/index.client";
 // noinspection JSUnusedGlobalSymbols
@@ -32,5 +26,8 @@ export {
   NostoContext,
   useNostoContext,
 } from "./components/Provider/context.client";
+export type {
+  NostoContextType,
+} from "./components/Provider/context.client";
 // noinspection JSUnusedGlobalSymbols
-export { default as NostoSession } from "./components/Session/index.client";
+export { default as NostoSession } from "./components/Session/index.client";

package/src/types.ts

@@ -1,3 +1,67 @@
+declare global {
+  interface Window {
+    nosto?: {
+      reload(settings: unknown): void;
+    };
+    nostojs: {
+      (callback: (api: NostoClient) => void): void;
+      q?: unknown[];
+    };
+  }
+}
+
+/**
+ * @group Types
+ */
+export interface NostoClient {
+  addOrder(order: { purchase: Purchase }): NostoClient;
+  defaultSession(): NostoClient;
+  setAutoLoad(autoload: boolean): NostoClient;
+  setCart(cart?: Cart): NostoClient;
+  setCustomer(customer?: Customer): NostoClient;
+  setPlacements(placements: string[]): NostoClient;
+  setResponseMode(mode: string): NostoClient;
+  setVariation(variation: string): NostoClient;
+  viewCategory(category: string): NostoClient;
+  viewProduct(product: string): NostoClient;
+  viewFrontPage(): NostoClient;
+  viewNotFound(): NostoClient;
+  viewOther(): NostoClient;
+  viewSearch(query: string): NostoClient;
+  viewCart(): NostoClient;
+  load(): Promise<{
+    affinities: Record<
+      string,
+      {
+        name: string;
+        score: number;
+      }[]
+    >;
+    geo_location?: string[];
+    page_views: number;
+    recommendations: Recommendation[];
+  }>;
+  placements: {
+    getPlacements(): string[];
+  };
+}
+
+/**
+ * @group Types
+ */
+export interface Recommendation {
+  result_id: string;
+  products: Product[];
+  result_type: string;
+  title: string;
+  div_id: string;
+  source_product_ids: string[];
+  params: unknown;
+}
+
+/**
+ * @group Types
+ */
 export interface Item {
   name: string;
   price_currency_code: string;
@@ -7,10 +71,16 @@ export interface Item {
   unit_price: number;
 }
 
+/**
+ * @group Types
+ */
 export interface Cart {
   items: Item[];
 }
 
+/**
+ * @group Types
+ */
 export interface Customer {
   customer_reference: string;
   email: string;
@@ -19,6 +89,9 @@ export interface Customer {
   newsletter: boolean;
 }
 
+/**
+ * @group Types
+ */
 export interface Buyer {
   first_name: string;
   last_name: string;
@@ -27,12 +100,18 @@ export interface Buyer {
   newsletter: boolean;
 }
 
+/**
+ * @group Types
+ */
 export interface Purchase {
   number: string;
   info: Buyer;
   items: Item[];
 }
 
+/**
+ * @group Types
+ */
 export interface SKU {
   id: string;
   name: string;
@@ -41,13 +120,16 @@ export interface SKU {
   url: URL;
   imageUrl: URL;
   gtin?: string;
-  availability: 'InStock' | 'OutOfStock';
+  availability: "InStock" | "OutOfStock";
   customFields?: { [key: string]: string };
 }
 
+/**
+ * @group Types
+ */
 export interface Product {
   alternateImageUrls?: URL[];
-  availability: 'InStock' | 'OutOfStock';
+  availability: "InStock" | "OutOfStock";
   brand?: string;
   category: string[];
   categoryIds?: string[];

package/src/utils/compare.ts

@@ -0,0 +1,30 @@
+import { isPlainObject } from "./object";
+
+export function deepCompare(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+
+  if (a instanceof Array && b instanceof Array) {
+    if (a.length !== b.length) {
+      return false;
+    }
+
+    return a.every((v, i) => deepCompare(v, b[i]));
+  }
+
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const entriesA = Object.entries(a);
+
+    if (entriesA.length !== Object.keys(b).length) {
+      return false;
+    }
+    return entriesA.every(([k, v]) => deepCompare(v, b[k]));
+  }
+
+  return false;
+}

package/src/utils/hooks.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef, useMemo } from "react";
+import { deepCompare } from "./compare";
+
+export function useDeepCompareEffect(
+  callback: Parameters<typeof useEffect>[0],
+  dependencies: Parameters<typeof useEffect>[1]
+): ReturnType<typeof useEffect> {
+  return useEffect(callback, useDeepCompareMemoize(dependencies));
+}
+
+function useDeepCompareMemoize<T>(value: T) {
+  const ref = useRef<T>(value);
+  const signalRef = useRef<number>(0);
+
+  if (!deepCompare(value, ref.current)) {
+    ref.current = value;
+    signalRef.current += 1;
+  }
+
+  return useMemo(() => ref.current, [signalRef.current]);
+}

package/src/utils/object.ts

@@ -0,0 +1,20 @@
+export function isPlainObject<T = Record<keyof any, unknown>>(
+  value: unknown
+): value is T {
+  const isObject = (v: unknown): v is object => String(v) === "[object Object]";
+
+  if (!isObject(value)) return false;
+
+  const constructor = value.constructor;
+  if (constructor === undefined) return true;
+
+  const prototype = constructor.prototype;
+  if (!isObject(prototype)) return false;
+
+  // Checks if it is not a class
+  if (!prototype.hasOwnProperty("isPrototypeOf")) {
+    return false;
+  }
+
+  return true;
+}

package/src/utils/snakeize.ts

@@ -0,0 +1,28 @@
+export function snakeize<T>(obj: T): T {
+  if (!obj || typeof obj !== "object") {
+    return obj;
+  }
+  if (isDate(obj) || isRegex(obj)) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(snakeize) as T;
+  }
+  return Object.keys(obj).reduce((acc, key) => {
+    var camel =
+      key[0].toLowerCase() +
+      key.slice(1).replace(/([A-Z]+)/g, (_, x) => {
+        return "_" + x.toLowerCase();
+      });
+    acc[camel as keyof typeof acc] = snakeize(obj[key as keyof typeof acc]);
+    return acc;
+  }, {} as T);
+}
+
+function isDate(obj: unknown) {
+  return Object.prototype.toString.call(obj) === "[object Date]";
+}
+
+function isRegex(obj: unknown) {
+  return Object.prototype.toString.call(obj) === "[object RegExp]";
+}

package/src/snakeize.d.ts

@@ -1 +0,0 @@
-declare module "snakeize";

package/src/utils/stringinate.ts

@@ -1,16 +0,0 @@
-export default function stringinate(obj: {
-  [key: string]: any;
-}): { [key: string]: any } {
-  Object.keys(obj).forEach((property) => {
-    if (obj[property] instanceof URL) {
-      obj[property] = obj[property].toString();
-    }
-    if (typeof obj[property] === "object") {
-      stringinate(obj[property]);
-    }
-
-    obj[property] = obj[property];
-  });
-
-  return obj;
-}