@nosto/nosto-react 1.0.0 → 2.1.0

package/src/components/NostoProvider.tsx

@@ -1,7 +1,8 @@
-import React, { useEffect, isValidElement, useState, useRef } from "react"
-import { NostoContext } from "./context"
-import { createRoot, Root } from "react-dom/client"
-import { NostoClient, Recommendation } from "../types"
+import { isValidElement } from "react"
+import { NostoContext, RecommendationComponent } from "../context"
+import { useLoadClientScript } from "../hooks"
+import type { ReactElement } from "react"
+import { ScriptLoadOptions } from "../hooks/scriptLoader"
 
 /**
  * @group Components
@@ -19,7 +20,10 @@ export interface NostoProviderProps {
    * Indicates an url of a server
    */
   host?: string
-  children: React.ReactElement
+  /**
+   * children
+   */
+  children: ReactElement | ReactElement[]
   /**
    * Indicates if merchant uses multiple currencies
    */
@@ -27,9 +31,7 @@ export interface NostoProviderProps {
   /**
    * Recommendation component which holds nostoRecommendation object
    */
-  recommendationComponent?: React.ReactElement<{
-    nostoRecommendation: Recommendation
-  }>
+  recommendationComponent?: RecommendationComponent
   /**
    * Enables Shopify markets with language and market id
    */
@@ -37,6 +39,14 @@ export interface NostoProviderProps {
     language?: string
     marketId?: string | number
   }
+  /**
+   * Load nosto script (should be false if loading the script outside of nosto-react)
+   */
+  loadScript?: boolean
+  /**
+   * Custom script loader
+   */
+  scriptLoader?: (scriptSrc: string, options?: ScriptLoadOptions) => Promise<void>
 }
 
 /**
@@ -64,143 +74,23 @@ 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 }
+  if (recommendationComponent && !isValidElement(recommendationComponent)) {
+    throw new Error(
+      "The recommendationComponent prop must be a valid React element. Please provide a valid React element."
+    )
   }
 
-  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))
+  // Set responseMode for loading campaigns:
+  const responseMode = recommendationComponent ? "JSON_ORIGINAL" : "HTML"
 
-        script.onload = () => {
-          if (typeof jest !== "undefined") {
-            window.nosto?.reload({
-              site: "localhost",
-            })
-          }
-          setClientScriptLoadedState(true)
-        }
-        document.body.appendChild(script)
-      }
-    }
-  }, [clientScriptLoadedState, shopifyMarkets])
+  const { clientScriptLoaded } = useLoadClientScript(props)
 
   return (
     <NostoContext.Provider
@@ -209,9 +99,7 @@ export default function NostoProvider(props: NostoProviderProps) {
         clientScriptLoaded,
         currentVariation,
         responseMode,
-        recommendationComponent,
-        useRenderCampaigns,
-        pageType,
+        recommendationComponent
       }}
     >
       {children}

package/src/components/NostoSearch.tsx

@@ -1,5 +1,4 @@
-import { useNostoContext } from "./context"
-import { useNostoApi } from "../utils/hooks"
+import { useRenderCampaigns, useNostoApi } from "../hooks"
 
 /**
  * You can personalise your search pages by using the NostoSearch component.
@@ -26,9 +25,7 @@ import { useNostoApi } from "../utils/hooks"
  */
 export default function NostoSearch(props: { query: string; placements?: string[] }) {
   const { query, placements } = props
-  const { recommendationComponent, useRenderCampaigns } = useNostoContext()
-
-  const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("search")
+  const { renderCampaigns } = useRenderCampaigns()
 
   useNostoApi(
     async (api) => {
@@ -36,9 +33,9 @@ export default function NostoSearch(props: { query: string; placements?: string[
         .viewSearch(query)
         .setPlacements(placements || api.placements.getPlacements())
         .load()
-      renderCampaigns(data, api)
+      renderCampaigns(data)
     },
-    [query, recommendationComponent, pageTypeUpdated]
+    [query]
   )
   return null
 }

package/src/components/NostoSession.tsx

@@ -1,7 +1,6 @@
-import { useNostoContext } from "./context"
+import { useNostoContext, useDeepCompareEffect } from "../hooks"
 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.

package/src/components/helpers.ts

@@ -0,0 +1,3 @@
+export function isNostoLoaded() {
+  return typeof window.nosto !== "undefined"    
+}

package/src/components/index.ts

@@ -7,8 +7,5 @@ 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 NostoProvider, type NostoProviderProps } from "./NostoProvider"
 export { default as NostoSession } from "./NostoSession"

package/src/context.ts

@@ -0,0 +1,31 @@
+import { createContext, ReactElement } from "react"
+import { Recommendation, RenderMode } from "./types"
+
+type AnyFunction = (...args: unknown[]) => unknown
+
+export type RecommendationComponent = ReactElement<{
+  nostoRecommendation: Recommendation
+}>
+
+/**
+ * @group Types
+ */
+export interface NostoContextType {
+  account: string
+  clientScriptLoaded: boolean
+  currentVariation?: string
+  renderFunction?: AnyFunction
+  responseMode: RenderMode
+  recommendationComponent?: RecommendationComponent
+}
+
+/**
+ * @group Essential Functions
+ */
+export const NostoContext = createContext<NostoContextType>({
+  account: "",
+  currentVariation: "",
+  responseMode: "HTML",
+  clientScriptLoaded: false
+})
+

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export { useDeepCompareEffect } from "./useDeepCompareEffect"
+export { useNostoApi } from "./useNostoApi"
+export { useNostoContext } from "./useNostoContext"
+export { useRenderCampaigns } from "./useRenderCampaigns"
+export { useLoadClientScript } from "./useLoadClientScript"

package/src/hooks/scriptLoader.ts

@@ -0,0 +1,30 @@
+export default function scriptLoader(scriptSrc: string, options?: ScriptLoadOptions): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const script = document.createElement("script")
+    script.type = "text/javascript"
+    script.src = scriptSrc
+    script.async = true
+    script.onload = () => resolve()
+    script.onerror = () => reject()
+    Object.entries(options?.attributes ?? {}).forEach(([k, v]) => script.setAttribute(k, v))
+    if (options?.position === "head") {
+      document.head.appendChild(script)    
+    } else {
+      document.body.appendChild(script)    
+    }
+  })
+}
+
+/**
+ * @group Types
+ */
+export type ScriptLoadOptions = {
+  /**
+   * Indicates the position of the script, default is "body"
+   */
+  position?: "head" | "body"
+  /**
+   * Indicates the attributes of the script element
+   */
+  attributes?: Record<string, string>    
+}  

package/src/hooks/useDeepCompareEffect.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef, useMemo } from "react"
+import { deepCompare } from "../utils/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/hooks/useLoadClientScript.ts

@@ -0,0 +1,84 @@
+import { useState, useEffect } from "react"
+import { isNostoLoaded } from "../components/helpers"
+import type { NostoClient } from "../types"
+import type { NostoProviderProps } from "../components/NostoProvider"
+import scriptLoaderFn from "./scriptLoader"
+
+type NostoScriptProps = Pick<NostoProviderProps, "account" | "host" | "shopifyMarkets" | "loadScript" | "scriptLoader">
+
+export function useLoadClientScript(props: NostoScriptProps) {
+  const { host = "connect.nosto.com", scriptLoader = scriptLoaderFn, account, shopifyMarkets, loadScript = true } = props
+  const [clientScriptLoaded, setClientScriptLoaded] = useState(false)
+
+  useEffect(() => {
+    function scriptOnload() {
+      // Override for production scripts to work in unit tests
+      if ("nostoReactTest" in window) {
+        window.nosto?.reload({
+          site: "localhost"
+        })
+      }
+      setClientScriptLoaded(true)
+    }
+
+    // Create and append script element
+    async function injectScriptElement(urlPartial: string, extraAttributes: Record<string, string> = {}) {
+      const scriptSrc = `//${host}${urlPartial}`
+      const attributes = { "nosto-client-script": "", ...extraAttributes }
+      await scriptLoader(scriptSrc, { attributes })
+      scriptOnload()
+    }
+
+    function prepareShopifyMarketsScript() {
+      const existingScript = document.querySelector("[nosto-client-script]")
+
+      const marketId = String(shopifyMarkets?.marketId || "")
+      const language = shopifyMarkets?.language || ""
+
+      const attributeMismatch =
+        existingScript?.getAttribute("nosto-language") !== language ||
+        existingScript?.getAttribute("nosto-market-id") !== marketId
+
+      if (!existingScript || attributeMismatch) {
+        if (clientScriptLoaded) {
+          setClientScriptLoaded(false)
+        }
+
+        const nostoSandbox = document.querySelector("#nosto-sandbox")
+
+        existingScript?.parentNode?.removeChild(existingScript)
+        nostoSandbox?.parentNode?.removeChild(nostoSandbox)
+
+        const urlPartial =
+          `/script/shopify/market/nosto.js?merchant=${account}&market=${marketId}&locale=${language.toLowerCase()}`
+        injectScriptElement(urlPartial, { "nosto-language": language, "nosto-market-id": marketId })
+      }
+    }
+
+    // Load Nosto API stub
+    if (!window.nostojs) {
+      window.nostojs = (cb: (api: NostoClient) => void) => {
+        (window.nostojs.q = window.nostojs.q || []).push(cb)
+      }
+      window.nostojs(api => api.setAutoLoad(false))
+    }
+
+    if (!loadScript) {
+      window.nosto ? scriptOnload() : window.nostojs(scriptOnload)
+      return
+    }
+
+    // Load Nosto client script if not already loaded externally
+    if (!isNostoLoaded() && !shopifyMarkets) {
+      const urlPartial = `/include/${account}`
+      injectScriptElement(urlPartial)
+    }
+
+    // Load Shopify Markets scripts
+    if (shopifyMarkets) {
+      prepareShopifyMarketsScript()
+    }
+  }, [shopifyMarkets?.marketId, shopifyMarkets?.language])
+
+  return { clientScriptLoaded }
+}

package/src/hooks/useNostoApi.ts

@@ -0,0 +1,22 @@
+import { DependencyList, useEffect } from "react"
+import { useNostoContext } from "./useNostoContext"
+import { NostoClient } from "../types"
+import { useDeepCompareEffect } from "./useDeepCompareEffect"
+
+export function useNostoApi(
+  cb: (api: NostoClient) => void,
+  deps?: DependencyList,
+  flags?: { deep?: boolean }
+): void {
+  const { clientScriptLoaded, currentVariation, responseMode } = useNostoContext()
+  const useEffectFn = flags?.deep ? useDeepCompareEffect : useEffect
+
+  useEffectFn(() => {
+    if (clientScriptLoaded) {
+      window.nostojs(api => {
+        api.defaultSession().setVariation(currentVariation!).setResponseMode(responseMode)
+        cb(api)
+      })
+    }
+  }, [clientScriptLoaded, currentVariation, responseMode, ...(deps ?? [])])
+}

package/src/hooks/useNostoContext.ts

@@ -0,0 +1,12 @@
+import { useContext } from "react"
+import { NostoContext, NostoContextType } from "../context"
+
+/**
+ * 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 {
+    return useContext(NostoContext)
+  }
+  

package/src/hooks/useRenderCampaigns.tsx

@@ -0,0 +1,59 @@
+import { cloneElement, useRef } from "react"
+import { createRoot, Root } from "react-dom/client"
+import { ActionResponse, Recommendation } from "../types"
+import { useNostoContext } from "./useNostoContext"
+import { RecommendationComponent } from "../context"
+
+// RecommendationComponent for client-side rendering:
+function RecommendationComponentWrapper(props: { 
+    recommendationComponent: RecommendationComponent,
+    nostoRecommendation: Recommendation }) {
+
+  return cloneElement(props.recommendationComponent, {
+    // eslint-disable-next-line react/prop-types
+    nostoRecommendation: props.nostoRecommendation,
+  })
+}
+
+function injectCampaigns(data: ActionResponse) {
+  if (!window.nostojs) {
+    throw new Error("Nosto has not yet been initialized")
+  }
+  window.nostojs(api => {
+    api.placements.injectCampaigns(data.recommendations)
+  })
+}
+
+export function useRenderCampaigns() {
+  const { responseMode, recommendationComponent } = useNostoContext()
+  const placementRefs = useRef<Record<string, Root>>({})
+
+  if (responseMode == "HTML") {
+    return { renderCampaigns: injectCampaigns }
+  }
+
+  function renderCampaigns(data: ActionResponse) {
+    // render recommendation component into placements:
+    const recommendations = data.campaigns?.recommendations ?? {}
+    for (const key in recommendations) {
+      const recommendation = recommendations[key] as Recommendation
+      const placementSelector = "#" + key
+      const placementElement = document.querySelector(placementSelector)
+
+      if (placementElement) {
+        if (!placementRefs.current[key]) {
+          placementRefs.current[key] = createRoot(placementElement)
+        }
+        const root = placementRefs.current[key]!
+        root.render(
+          <RecommendationComponentWrapper
+            recommendationComponent={recommendationComponent!}
+            nostoRecommendation={recommendation}
+          ></RecommendationComponentWrapper>
+        )
+      }
+    }
+  }
+
+  return { renderCampaigns }
+}

package/src/index.ts

@@ -1,2 +1,5 @@
 export type { Cart, Customer, Product, Order, Recommendation } from "./types"
 export * from "./components"
+export { type ScriptLoadOptions } from "./hooks/scriptLoader"
+export { NostoContext, type NostoContextType } from "./context"
+export { useNostoContext } from "./hooks/useNostoContext"

package/src/types.ts

@@ -17,6 +17,7 @@ declare global {
 export interface NostoClient {
   setAutoLoad(autoload: boolean): void
   defaultSession(): Session
+  listen(event: string, callback: (data: unknown) => void): void
   placements: {
     getPlacements(): string[]
     injectCampaigns(recommendations: Record<string, unknown>): void
@@ -28,7 +29,7 @@ export interface NostoClient {
  */
 export interface Recommendation {
   result_id: string
-  products: Product[]
+  products: PushedProduct[]
   result_type: string
   title: string
   div_id: string
@@ -36,6 +37,77 @@ export interface Recommendation {
   params: unknown
 }
 
+export interface PushedProduct {
+  age_group?: string
+  alternate_image_urls: string[]
+  availability: string
+  brand?: string
+  category: string[]
+  category_id: string[]
+  condition?: string
+  custom_fields: { [index: string]: string }
+  date_published?: Date
+  description?: string
+  gender?: string
+  google_category?: string
+  gtin?: string
+  image_url?: string
+  inventory_level?: number
+  list_price?: number
+  name: string
+  parent_category_id: string[]
+  price: number
+  price_currency_code: string
+  product_id: string
+  rating_value?: number
+  review_count?: number
+  skus: PushedProductSKU[]
+  source_updated?: Date
+  supplier_cost?: number
+  tags1: string[]
+  tags2: string[]
+  tags3: string[]
+  thumb_url?: string
+  unit_pricing_base_measure?: number
+  unit_pricing_measure?: number
+  unit_pricing_unit?: string
+  update_received?: Date
+  url: string
+  variation_id?: string
+  variations: { [index: string]: PushedVariation }
+}
+
+export interface PushedProductSKU extends NostoSku { }
+
+export interface PushedVariation extends NostoVariant { }
+
+
+export interface NostoSku extends Sku {
+  inventory_level?: number
+}
+
+export interface NostoVariant {
+  availability: string
+  available: boolean
+  discounted: boolean
+  list_price?: number
+  price: number
+  price_currency_code: string
+  price_text?: string
+}
+
+export interface Sku {
+  availability: string
+  custom_fields: { [index: string]: string }
+  gtin?: string
+  id: string
+  image_url?: string
+  list_price?: number
+  name: string
+  price: number
+  url?: string
+}
+
 // copied from client script d.ts export
 declare const eventTypes: readonly ["vp", "lp", "dp", "rp", "bp", "vc", "or", "is", "cp", "ec", "es", "gc", "src", "cpr", "pl", "cc", "con"]
 declare type EventType = typeof eventTypes[number]