@bloomreach/discovery-web-sdk

Discovery Web SDK

⚙️ SDK Reference

The detailed TSDoc and reference for the SDK are available here.

The Bloomreach Discovery Web SDK is a TypeScript SDK designed to interact with the Bloomreach Discovery APIs. This SDK provides a convenient way to integrate and use the Discovery data in your website or applications.

The SDK provides an interface to implement the following Bloomreach Discovery APIs:

• Autosuggest API
• Product and Category Search API
• Content Search API
• Recommendations and Pathways APIs
• Bestseller API

The Discovery Web SDK is fully Open-Sourced and open to contributions.

View Repo

Getting Started

Requirements

The SDK currently requires:

• Node.js 20+

Installation

npm add @bloomreach/discovery-web-sdk

pnpm add @bloomreach/discovery-web-sdk

yarn add @bloomreach/discovery-web-sdk

Debug logging

Adding debug: true to the Configuration you pass into the API calls will enable some minor debug logging with [BR] as a prefix for your convenience.

Usage

Below are some usage examples that demonstrate how to call and use various Discovery APIs in your website or application using the SDK.

Autosuggest API

import type { Configuration, AutosuggestOptions } from '@bloomreach/discovery-web-sdk';
import { autosuggest } from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: AutosuggestOptions = {
  catalog_views: 'product:store1,store2|recipe:premium|articles',
  q: 'Roses',
  url: 'http://example.com',
  _br_uid_2: 'someCookieId',
};

// Retrieve the suggestions with a search using the provided search parameters
const data = await autosuggest(config, searchOptions);

Product and Category Search API

Product Search

import type { Configuration, ProductSearchOptions } from '@bloomreach/discovery-web-sdk';
import { productSearch } from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: ProductSearchOptions = {
  q: 'Generic Metal Pants',
  fl: 'pid,title,description,brand,price,thumb_image',
  start: 0,
  rows: 10,
  url: 'http://example.com',
  _br_uid_2: 'someCookieId',
};

// Retrieve the product data with a search using the provided search parameters
const data = await productSearch(config, searchOptions);

Category Search

import type { Configuration, CategorySearchOptions } from '@bloomreach/discovery-web-sdk';
import { categorySearch } from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: CategorySearchOptions = {
  q: 'cat92082',
  fl: 'pid,title,description,brand,price,thumb_image',
  start: 0,
  rows: 10,
  url: 'http://example.com',
  _br_uid_2: 'someCookieId',
};

// Retrieve the product data with a search using the provided search parameters
const data = await categorySearch(config, searchOptions);

Content Search API

import type { Configuration, ContentSearchOptions } from '@bloomreach/discovery-web-sdk';
import { contentSearch } from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: ContentSearchOptions = {
  catalog_name: 'Flowers',
  q: 'Roses',
  fl: 'pid,title,description,brand,price,thumb_image',
  start: 0,
  rows: 10,
  url: 'http://example.com',
  _br_uid_2: 'someCookieId',
};

// Retrieve the Content data with a search using the provided search parameters
const data = await contentSearch(config, searchOptions);

Recommendations and Pathways APIs

import {
  CategoryWidgetOptions,
  Configuration,
  WidgetResponse,
  getCategoryWidget,
} from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: CategoryWidgetOptions = {
  cat_id: 'cat123959',
  start: 0,
  rows: 10,
  url: 'http://example.com',
  ref_url: 'http://google.com',
  request_id: 1234,
  _br_uid_2: 'test',
};

const widgetId = 'my_widget_id';

// Retrieve the widget using the widgetId and parameters
const widget = getCategoryWidget(widgetId, config, searchOptions);

Similar functions and types are exposed for all widget types:

• getGlobalWidget
• getKeywordWidget
• getCategoryWidget
• getItemWidget
• getPersonalizedWidget
• getRecentlyViewedWidget

Bestseller API

import type { Configuration, BestsellerOptions } from '@bloomreach/discovery-web-sdk';
import { bestseller } from '@bloomreach/discovery-web-sdk';

// Set the account and catalog configuration
const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

// Set up the search parameters
const searchOptions: BestsellerOptions = {
  q: 'Bolts',
  fl: 'pid,title,description,brand,price,thumb_image',
  start: 0,
  rows: 10,
  url: 'http://example.com',
  _br_uid_2: 'someCookieId',
};

// Retrieve the product data with a search using the provided search parameters
const data = await bestseller(config, searchOptions);

Related resources

• Limitless Commerce UI Kit
• Web Code Samples
• Sample Catalogs

Contribution & Development

The Bloomreach Discovery SDK is Open-Source, and we welcome outside contributions. See our Contribution Guide.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Changelog

2.0.1 (2024-11-26)

Bug Fixes

• types: Export all search response types (2817d35)

• fix!: Search API functions how take query as a parameter (07e122e)

• fix!: Remove invalid SearchOption type guard functions (2e40d50)

BREAKING CHANGES

• productSearch, bestseller, contentSearch, categorySearch and autoSuggest parameters have changed.
• Removed isBestsellerOptions, isAutosuggestOptions, isContentSearchOptions, isProductSearchOptions, isCategorySearchOptions functions from the API.