@nosto/nosto-react 0.4.0 → 0.4.3

package/src/components/NostoProvider.tsx

@@ -0,0 +1,220 @@
+import React, { useEffect, isValidElement, useState, useRef } from "react"
+import { NostoContext } from "./context"
+import { createRoot, Root } from "react-dom/client"
+import { NostoClient, Recommendation } from "../types"
+
+/**
+ * @group Components
+ */
+export interface NostoProviderProps {
+  /**
+   * Indicates merchant id
+   */
+  account: string
+  /**
+   * Indicates currency
+   */
+  currentVariation?: string
+  /**
+   * Indicates an url of a server
+   */
+  host?: string
+  children: React.ReactElement
+  /**
+   * Indicates if merchant uses multiple currencies
+   */
+  multiCurrency?: boolean
+  /**
+   * Recommendation component which holds nostoRecommendation object
+   */
+  recommendationComponent?: React.ReactElement<{
+    nostoRecommendation: Recommendation
+  }>
+  /**
+   * Enables Shopify markets with language and market id
+   */
+  shopifyMarkets?: {
+    language?: string
+    marketId?: string | number
+  }
+}
+
+/**
+ * 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 Components
+ */
+export default function NostoProvider(props: NostoProviderProps) {
+  const {
+    account,
+    multiCurrency = false,
+    host,
+    children,
+    recommendationComponent,
+    shopifyMarkets,
+  } = props
+  const [clientScriptLoadedState, setClientScriptLoadedState] = React.useState(false)
+  const clientScriptLoaded = React.useMemo(() => clientScriptLoadedState, [clientScriptLoadedState])
+
+  // Pass currentVariation as empty string if multiCurrency is disabled
+  const currentVariation = multiCurrency ? props.currentVariation : ""
+
+  // Set responseMode for loading campaigns:
+  const responseMode = isValidElement(recommendationComponent) ? "JSON_ORIGINAL" : "HTML"
+
+  // RecommendationComponent for client-side rendering:
+  function RecommendationComponentWrapper(props: { nostoRecommendation: Recommendation }) {
+    return React.cloneElement(recommendationComponent!, {
+      // eslint-disable-next-line react/prop-types
+      nostoRecommendation: props.nostoRecommendation,
+    })
+  }
+
+  // custom hook for rendering campaigns (CSR/SSR):
+  const [pageType, setPageType] = useState("")
+  function useRenderCampaigns(type: string = "") {
+    const placementRefs = useRef<Record<string, Root>>({})
+    useEffect(() => {
+      if (pageType !== type) {
+        setPageType(type)
+      }
+    }, [])
+
+    const pageTypeUpdated = type === pageType
+
+    function renderCampaigns(
+      data: {
+        recommendations: Record<string, Recommendation>
+        campaigns: {
+          recommendations: Record<string, Recommendation>
+        }
+      },
+      api: NostoClient
+    ) {
+      if (responseMode == "HTML") {
+        // inject content campaigns as usual:
+        api.placements.injectCampaigns(data.recommendations)
+      } else {
+        // render recommendation component into placements:
+        const recommendations = data.campaigns.recommendations
+        for (const key in recommendations) {
+          const recommendation = recommendations[key]
+          const placementSelector = "#" + key
+          const placement = () => document.querySelector(placementSelector)
+
+          if (placement()) {
+            if (!placementRefs.current[key]) placementRefs.current[key] = createRoot(placement()!)
+            const root = placementRefs.current[key]!
+            root.render(
+              <RecommendationComponentWrapper
+                nostoRecommendation={recommendation}
+              ></RecommendationComponentWrapper>
+            )
+          }
+        }
+      }
+    }
+    return { renderCampaigns, pageTypeUpdated }
+  }
+
+  useEffect(() => {
+    if (!window.nostojs) {
+      window.nostojs = (cb: (api: NostoClient) => void) => {
+        (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 = () => {
+        if (typeof jest !== "undefined") {
+          window.nosto?.reload({
+            site: "localhost",
+          })
+        }
+        setClientScriptLoadedState(true)
+      }
+      document.body.appendChild(script)
+    }
+
+    // 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
+      value={{
+        account,
+        clientScriptLoaded,
+        currentVariation,
+        responseMode,
+        recommendationComponent,
+        useRenderCampaigns,
+        pageType,
+      }}
+    >
+      {children}
+    </NostoContext.Provider>
+  )
+}

package/src/components/{Search/index.client.tsx → NostoSearch.tsx}

@@ -1,5 +1,5 @@
-import { useEffect } from "react";
-import { useNostoContext } from "../Provider/context.client";
+import { useNostoContext } from "./context"
+import { useNostoApi } from "../utils/hooks"
 
 /**
  * You can personalise your search pages by using the NostoSearch component.
@@ -22,42 +22,24 @@ import { useNostoContext } from "../Provider/context.client";
  * 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
+ * @group Components
  */
-export default function NostoSearch(props: { query: string }): JSX.Element {
-  const { query } = props;
-  const {
-    clientScriptLoaded,
-    currentVariation,
-    responseMode,
-    recommendationComponent,
-    useRenderCampaigns,
-  } = useNostoContext();
+export default function NostoSearch(props: { query: string; placements?: string[] }) {
+  const { query, placements } = props
+  const { recommendationComponent, useRenderCampaigns } = useNostoContext()
 
-  const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("search");
+  const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("search")
 
-  useEffect(() => {
-    if (clientScriptLoaded && pageTypeUpdated) {
-      window.nostojs((api) => {
-        api
-          .defaultSession()
-          .setVariation(currentVariation)
-          .setResponseMode(responseMode)
-          .viewSearch(query)
-          .setPlacements(api.placements.getPlacements())
-          .load()
-          .then((data) => {
-            renderCampaigns(data, api);
-          });
-      });
-    }
-  }, [
-    clientScriptLoaded,
-    currentVariation,
-    query,
-    recommendationComponent,
-    pageTypeUpdated,
-  ]);
+  useNostoApi(
+    async (api) => {
+      const data = await api.defaultSession()
+        .viewSearch(query)
+        .setPlacements(placements || api.placements.getPlacements())
+        .load()
+      renderCampaigns(data, api)
+    },
+    [query, recommendationComponent, pageTypeUpdated]
+  )
 
   return (
     <>
@@ -68,5 +50,5 @@ export default function NostoSearch(props: { query: string }): JSX.Element {
         {query}
       </div>
     </>
-  );
+  )
 }

package/src/components/{Session/index.client.tsx → NostoSession.tsx}

@@ -1,7 +1,7 @@
-import { useNostoContext } from "../Provider/context.client";
-import { Cart, Customer } from "../../types";
-import { snakeize } from "../../utils/snakeize";
-import { useDeepCompareEffect } from "../../utils/hooks";
+import { useNostoContext } from "./context"
+import { Cart, Customer } from "../types"
+import { snakeize } from "../utils/snakeize"
+import { useDeepCompareEffect } from "../utils/hooks"
 
 /**
  * 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.
@@ -13,29 +13,26 @@ import { useDeepCompareEffect } from "../../utils/hooks";
  *
  * @group Essential Functions
  */
-export default function NostoSession(props: {
-  cart: Cart;
-  customer: Customer;
-}): JSX.Element {
-  const { cart, customer } = props;
-  const { clientScriptLoaded } = useNostoContext();
+export default function NostoSession(props: { cart: Cart; customer: Customer }) {
+  const { cart, customer } = props
+  const { clientScriptLoaded } = useNostoContext()
 
   useDeepCompareEffect(() => {
-    const currentCart = cart ? snakeize(cart) : undefined;
-    const currentCustomer = customer ? snakeize(customer) : undefined;
+    const currentCart = cart ? snakeize(cart) : undefined
+    const currentCustomer = customer ? snakeize(customer) : undefined
 
     if (clientScriptLoaded) {
-      window.nostojs((api) => {
+      window.nostojs(api => {
         api
           .defaultSession()
           .setResponseMode("HTML")
           .setCart(currentCart)
           .setCustomer(currentCustomer)
           .viewOther()
-          .load();
-      });
+          .load()
+      })
     }
-  }, [clientScriptLoaded, cart, customer]);
+  }, [clientScriptLoaded, cart, customer])
 
-  return <></>;
+  return <></>
 }

package/src/components/context.ts

@@ -0,0 +1,55 @@
+import { createContext, useContext } from "react"
+import { NostoClient, Recommendation } from "../types"
+
+type AnyFunction = (...args: unknown[]) => unknown
+
+/**
+ * @group Types
+ */
+export interface NostoContextType {
+  account: string
+  clientScriptLoaded: boolean
+  currentVariation?: string
+  renderFunction?: AnyFunction
+  responseMode: string
+  recommendationComponent?: React.ReactElement<{
+    nostoRecommendation: Recommendation
+  }>
+  useRenderCampaigns(type: string): {
+    renderCampaigns(data: unknown, api: NostoClient): void
+    pageTypeUpdated: boolean
+  }
+  pageType: string
+}
+
+/**
+ * @group Essential Functions
+ */
+export const NostoContext = createContext<NostoContextType>({
+  account: "",
+  currentVariation: "",
+  pageType: "",
+  responseMode: "HTML",
+  clientScriptLoaded: false,
+  useRenderCampaigns: () => {
+    return {
+      renderCampaigns: () => {},
+      pageTypeUpdated: false,
+    }
+  },
+})
+
+/**
+ * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
+ *
+ * @group Essential Functions
+ */
+export function useNostoContext(): NostoContextType {
+  const context = useContext(NostoContext)
+
+  if (!context) {
+    throw new Error("No nosto context found")
+  }
+
+  return context
+}

package/src/components/index.ts

@@ -0,0 +1,14 @@
+export { default as Nosto404 } from "./Nosto404"
+export { default as NostoOther } from "./NostoOther"
+export { default as NostoCheckout } from "./NostoCheckout"
+export { default as NostoProduct } from "./NostoProduct"
+export { default as NostoCategory } from "./NostoCategory"
+export { default as NostoSearch } from "./NostoSearch"
+export { default as NostoOrder } from "./NostoOrder"
+export { default as NostoHome } from "./NostoHome"
+export { default as NostoPlacement } from "./NostoPlacement"
+export { default as NostoProvider } from "./NostoProvider"
+
+export { NostoContext, useNostoContext } from "./context"
+export type { NostoContextType } from "./context"
+export { default as NostoSession } from "./NostoSession"

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { Buyer, Cart, Customer, Item, Product, Purchase, Recommendation, SKU } from "./types"
+
+export * from "./components"

package/src/types.ts

@@ -1,158 +1,173 @@
 declare global {
   interface Window {
     nosto?: {
-      reload(settings: unknown): void;
-    };
+      reload(settings: unknown): void
+    }
     nostojs: {
-      (callback: (api: NostoClient) => void): void;
-      q?: unknown[];
-    };
+      (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;
+export interface Affinity {
+  name: string
+  score: number
+}
+
+/**
+ * @group Types
+ */
+export interface SessionAction {
+  setPlacements(placements: string[]): SessionAction
   load(): Promise<{
-    affinities: Record<
-      string,
-      {
-        name: string;
-        score: number;
-      }[]
-    >;
-    geo_location?: string[];
-    page_views: number;
-    recommendations: Recommendation[];
-  }>;
+    affinities: Record<string, Affinity[]>
+    geo_location?: string[]
+    page_views: number
+    recommendations: Recommendation[]
+  }>
+}
+
+/**
+ * @group Types
+ */
+export interface NostoSession {
+  setCart(cart?: Cart): NostoSession
+  setCustomer(customer?: Customer): NostoSession
+  setResponseMode(mode: string): NostoSession
+  setVariation(variation?: string): NostoSession
+  addOrder(order: { purchase: Purchase }): SessionAction
+  viewCategory(category: string): SessionAction
+  viewProduct(product: string): SessionAction
+  viewFrontPage(): SessionAction
+  viewNotFound(): SessionAction
+  viewOther(): SessionAction
+  viewSearch(query: string): SessionAction
+  viewCart(): SessionAction
+}
+
+/**
+ * @group Types
+ */
+export interface NostoClient {
+  setAutoLoad(autoload: boolean): NostoClient
+  defaultSession(): NostoSession
   placements: {
-    getPlacements(): string[];
-  };
+    getPlacements(): string[]
+    injectCampaigns(recommendations: Record<string, Recommendation>): void
+  }
 }
 
 /**
  * @group Types
  */
 export interface Recommendation {
-  result_id: string;
-  products: Product[];
-  result_type: string;
-  title: string;
-  div_id: string;
-  source_product_ids: string[];
-  params: unknown;
+  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;
-  product_id: string;
-  quantity: number;
-  sku_id: string;
-  unit_price: number;
+  name: string
+  price_currency_code: string
+  product_id: string
+  quantity: number
+  sku_id: string
+  unit_price: number
 }
 
 /**
  * @group Types
  */
 export interface Cart {
-  items: Item[];
+  items: Item[]
 }
 
 /**
  * @group Types
  */
 export interface Customer {
-  customer_reference: string;
-  email: string;
-  first_name: string;
-  last_name: string;
-  newsletter: boolean;
+  customer_reference: string
+  email: string
+  first_name: string
+  last_name: string
+  newsletter: boolean
 }
 
 /**
  * @group Types
  */
 export interface Buyer {
-  first_name: string;
-  last_name: string;
-  email: string;
-  type: string;
-  newsletter: boolean;
+  first_name: string
+  last_name: string
+  email: string
+  type: string
+  newsletter: boolean
 }
 
 /**
  * @group Types
  */
 export interface Purchase {
-  number: string;
-  info: Buyer;
-  items: Item[];
+  number: string
+  info: Buyer
+  items: Item[]
 }
 
 /**
  * @group Types
  */
 export interface SKU {
-  id: string;
-  name: string;
-  price: number;
-  listPrice?: number;
-  url: URL;
-  imageUrl: URL;
-  gtin?: string;
-  availability: "InStock" | "OutOfStock";
-  customFields?: { [key: string]: string };
+  id: string
+  name: string
+  price: number
+  listPrice?: number
+  url: URL
+  imageUrl: URL
+  gtin?: string
+  availability: "InStock" | "OutOfStock"
+  customFields?: { [key: string]: string }
 }
 
 /**
  * @group Types
  */
 export interface Product {
-  alternateImageUrls?: URL[];
-  availability: "InStock" | "OutOfStock";
-  brand?: string;
-  category: string[];
-  categoryIds?: string[];
-  description: string;
-  googleCategory?: string;
-  condition?: string;
-  gender?: string;
-  ageGroup?: string;
-  gtin?: string;
-  imageUrl: URL;
-  listPrice?: number;
-  name: string;
-  price: number;
-  ratingValue?: number;
-  reviewCount?: number;
-  priceCurrencyCode: string;
-  productId: string;
-  tags1?: string[];
-  tags2?: string[];
-  tags3?: string[];
-  thumbUrl?: URL;
-  url: URL;
-  customFields?: { [key: string]: string };
-  variationId?: string;
-  skus?: SKU[];
+  alternateImageUrls?: URL[]
+  availability: "InStock" | "OutOfStock"
+  brand?: string
+  category: string[]
+  categoryIds?: string[]
+  description: string
+  googleCategory?: string
+  condition?: string
+  gender?: string
+  ageGroup?: string
+  gtin?: string
+  imageUrl: URL
+  listPrice?: number
+  name: string
+  price: number
+  ratingValue?: number
+  reviewCount?: number
+  priceCurrencyCode: string
+  productId: string
+  tags1?: string[]
+  tags2?: string[]
+  tags3?: string[]
+  thumbUrl?: URL
+  url: URL
+  customFields?: { [key: string]: string }
+  variationId?: string
+  skus?: SKU[]
 }