@nosto/nosto-react 0.4.1 → 0.5.0

package/README.md

@@ -42,8 +42,8 @@ _\*\*Note: The search feature is available when implemented via our code editor.
 
 #### Required versions
 
-- npm: 8.5.5
-- node: v16.15.0
+- npm: 9.8.1
+- node: v18.18.0
 
 ### Installation
 
@@ -269,6 +269,9 @@ import {
 </div>;
 ```
 
+### Detailed technical documentation
+Find our latest technical specs and documentation hosted [here](https://nosto.github.io/nosto-react).
+
 ### Feedback
 
 If you've found a feature missing or you would like to report an issue, simply [open up an issue](https://github.com/nosto/nosto-react/issues/new) and let us know.

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+import { Context } from 'react';
+import { default as default_2 } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+
+/**
+ * @group Types
+ */
+declare interface Affinity {
+    name: string;
+    score: number;
+}
+
+declare type AnyFunction = (...args: unknown[]) => unknown;
+
+/**
+ * @group Types
+ */
+export declare interface Buyer {
+    first_name: string;
+    last_name: string;
+    email: string;
+    type: string;
+    newsletter: boolean;
+}
+
+/**
+ * @group Types
+ */
+export declare interface Cart {
+    items: Item[];
+}
+
+/**
+ * @group Types
+ */
+export declare interface Customer {
+    customer_reference: string;
+    email: string;
+    first_name: string;
+    last_name: string;
+    newsletter: boolean;
+}
+
+/**
+ * @group Types
+ */
+export declare interface Item {
+    name: string;
+    price_currency_code: string;
+    product_id: string;
+    quantity: number;
+    sku_id: string;
+    unit_price: number;
+}
+
+/**
+ * You can personalise your cart and checkout pages by using the `Nosto404` component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has three 404-page placements named `notfound-nosto-1`, `notfound-nosto-2` and `notfound-nosto-3`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="notfound-page">
+ *   <NostoPlacement id="notfound-nosto-1" />
+ *   <NostoPlacement id="notfound-nosto-2" />
+ *   <NostoPlacement id="notfound-nosto-3" />
+ *   <Nosto404 />
+ * </div>
+ * ```
+ *
+ * @group Components
+ */
+export declare function Nosto404(props: {
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * You can personalise your category and collection pages by using the NostoCategory component.
+ * The component requires that you provide it the the slash-delimited slug representation of the current category.
+ *
+ * By default, your account, when created, has two category placements named `categorypage-nosto-1` and `categorypage-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="category-page">
+ *   <NostoPlacement id="categorypage-nosto-1" />
+ *   <NostoPlacement id="categorypage-nosto-2" />
+ *   <NostoCategory category={category.name} />
+ * </div>
+ * ```
+ *
+ * **Note:** Be sure to pass in the correct category representation.
+ * If the category being viewed is `Mens >> Jackets`, you must provide the name as `/Mens/Jackets`.
+ * You must ensure that the category path provided here matches that of the categories tagged in your products.
+ *
+ * @group Components
+ */
+export declare function NostoCategory(props: {
+    category: string;
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * You can personalise your cart and checkout pages by using the NostoCheckout component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has two cart-page placements named `categorypage-nosto-1` and `categorypage-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="checkout-page">
+ *   <NostoPlacement id="checkout-nosto-1" />
+ *   <NostoPlacement id="checkout-nosto-2" />
+ *   <NostoCheckout />
+ * </div>
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoCheckout(props: {
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * @group Types
+ */
+declare interface NostoClient {
+    setAutoLoad(autoload: boolean): NostoClient;
+    defaultSession(): NostoClientSession;
+    placements: {
+        getPlacements(): string[];
+        injectCampaigns(recommendations: Record<string, Recommendation>): void;
+    };
+}
+
+/**
+ * @group Types
+ */
+declare interface NostoClientSession {
+    setCart(cart?: Cart): NostoClientSession;
+    setCustomer(customer?: Customer): NostoClientSession;
+    setResponseMode(mode: string): NostoClientSession;
+    setVariation(variation?: string): NostoClientSession;
+    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 Essential Functions
+ */
+export declare const NostoContext: Context<NostoContextType>;
+
+/**
+ * @group Types
+ */
+export declare 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;
+}
+
+/**
+ * The `NostoHome` component must be used to personalise the home page. The component does not require any props.
+ *
+ * By default, your account, when created, has four front-page placements named `frontpage-nosto-1`, `frontpage-nosto-2`, `frontpage-nosto-3` and `frontpage-nosto-4`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * The `<NostoHome \>` component needs to be added after the placements.
+ * Content and recommendations will be rendered through this component.
+ *
+ * @example
+ * ```
+ *  <div className="front-page">
+ *   <NostoPlacement id="frontpage-nosto-1" />
+ *   <NostoPlacement id="frontpage-nosto-2" />
+ *   <NostoPlacement id="frontpage-nosto-3" />
+ *   <NostoPlacement id="frontpage-nosto-4" />
+ *   <NostoHome />
+ * </div>
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoHome(props: {
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * You can personalise your order-confirmation/thank-you page by using the `NostoOrder` component.
+ * The component requires that you provide it with the details of the order.
+ *
+ * By default, your account, when created, has one other-page placement named `thankyou-nosto-1`.
+ * You may omit this and use any identifier you need. The identifier used here is simply provided to illustrate the example.
+ *
+ * The order prop requires a value that adheres to the type `Purchase`.
+ *
+ * @example
+ * ```
+ * <div className="thankyou-page">
+ *     <NostoPlacement id="thankyou-nosto-1" />
+ *     <NostoOrder order={{ purchase: toOrder(order) }} />
+ * </div>
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoOrder(props: {
+    order: {
+        purchase: Purchase;
+    };
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * You can personalise your miscellaneous pages by using the NostoOther component.
+ * The component does not require any props.
+ *
+ * By default, your account, when created, has two other-page placements named `other-nosto-1` and `other-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="other-page">
+ *     <NostoPlacement id="other-nosto-1" />
+ *     <NostoPlacement id="other-nosto-2" />
+ *     <NostoOther />
+ * </div>;
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoOther(props: {
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * Nosto React has a special component called NostoPlacement.
+ * The component is a simply a hidden `<div>` placeholder into which Nosto injects recommendations or personalises the content between the tags.
+ *
+ * We recommend adding as many placements across your views as needed as these are hidden and only populated when a corresponding campaign (targeting that placement) is configured.
+ *
+ * @example
+ * ```
+ * <NostoPlacement id="frontpage-nosto-1" />
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoPlacement(props: {
+    id: string;
+    pageType?: string;
+}): JSX_2.Element;
+
+/**
+ * The NostoProduct component must be used to personalise the product page.
+ * The component requires that you provide it the identifier of the current product being viewed.
+ *
+ * By default, your account, when created, has three product-page placements named `productpage-nosto-1`, `productpage-nosto-2` and `productpage-nosto-3`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * The `<NostoProduct \>` component needs to be added after the placements.
+ * Content and recommendations will be rendered through this component.
+ * Pass in the product ID via the product prop to pass this information back to Nosto.
+ *
+ * @example
+ * ```
+ * <div className="product-page">
+ *   <NostoPlacement id="productpage-nosto-1" />
+ *   <NostoPlacement id="productpage-nosto-2" />
+ *   <NostoPlacement id="productpage-nosto-3" />
+ *   <NostoProduct product={product.id} />
+ * </div>
+ * ```
+ *
+ * @group Components
+ */
+export declare function NostoProduct(props: {
+    product: string;
+    tagging?: Product;
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * 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 declare function NostoProvider(props: NostoProviderProps): JSX_2.Element;
+
+/**
+ * @group Components
+ */
+declare interface NostoProviderProps {
+    /**
+     * Indicates merchant id
+     */
+    account: string;
+    /**
+     * Indicates currency
+     */
+    currentVariation?: string;
+    /**
+     * Indicates an url of a server
+     */
+    host?: string;
+    children: default_2.ReactElement;
+    /**
+     * Indicates if merchant uses multiple currencies
+     */
+    multiCurrency?: boolean;
+    /**
+     * Recommendation component which holds nostoRecommendation object
+     */
+    recommendationComponent?: default_2.ReactElement<{
+        nostoRecommendation: Recommendation;
+    }>;
+    /**
+     * Enables Shopify markets with language and market id
+     */
+    shopifyMarkets?: {
+        language?: string;
+        marketId?: string | number;
+    };
+}
+
+/**
+ * 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 Components
+ */
+export declare function NostoSearch(props: {
+    query: string;
+    placements?: string[];
+}): JSX_2.Element;
+
+/**
+ * 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 declare function NostoSession(props: {
+    cart: Cart;
+    customer: Customer;
+}): JSX_2.Element;
+
+/**
+ * @group Types
+ */
+export declare 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[];
+}
+
+/**
+ * @group Types
+ */
+export declare interface Purchase {
+    number: string;
+    info: Buyer;
+    items: Item[];
+}
+
+/**
+ * @group Types
+ */
+export declare interface Recommendation {
+    result_id: string;
+    products: Product[];
+    result_type: string;
+    title: string;
+    div_id: string;
+    source_product_ids: string[];
+    params: unknown;
+}
+
+/**
+ * @group Types
+ */
+declare interface SessionAction {
+    setPlacements(placements: string[]): SessionAction;
+    load(): Promise<{
+        affinities: Record<string, Affinity[]>;
+        geo_location?: string[];
+        page_views: number;
+        recommendations: Recommendation[];
+    }>;
+}
+
+/**
+ * @group Types
+ */
+export declare interface SKU {
+    id: string;
+    name: string;
+    price: number;
+    listPrice?: number;
+    url: URL;
+    imageUrl: URL;
+    gtin?: string;
+    availability: "InStock" | "OutOfStock";
+    customFields?: {
+        [key: string]: string;
+    };
+}
+
+/**
+ * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
+ *
+ * @group Essential Functions
+ */
+export declare function useNostoContext(): NostoContextType;
+
+export { }
+
+declare global {
+    interface Window {
+        nosto?: {
+            reload(settings: unknown): void;
+        };
+        nostojs: {
+            (callback: (api: NostoClient) => void): void;
+            q?: unknown[];
+        };
+    }
+}
+