### Install @bloomreach/discovery-web-sdk

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Install the SDK using npm, pnpm, or yarn.

```shell
# npm
npm add @bloomreach/discovery-web-sdk

# pnpm
pnpm add @bloomreach/discovery-web-sdk

# yarn
yarn add @bloomreach/discovery-web-sdk
```

--------------------------------

### Install Discovery Web SDK using PNPM

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Use this command to add the SDK to your project with PNPM.

```shell
pnpm add @bloomreach/discovery-web-sdk
```

--------------------------------

### Install Discovery Web SDK using NPM

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Use this command to add the SDK to your project with NPM.

```shell
npm add @bloomreach/discovery-web-sdk
```

--------------------------------

### Recommendations and Pathways API Example

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

This example shows how to retrieve widget data for recommendations or pathways using the getCategoryWidget function. Configure the account, catalog, and widget-specific options.

```typescript
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);
```

--------------------------------

### Install Dependencies

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Installs project dependencies using PNPM. Ensure Node.js 20+ and PNPM 9+ are installed.

```bash
pnpm install
```

--------------------------------

### Install Discovery Web SDK using Yarn

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Use this command to add the SDK to your project with Yarn.

```shell
yarn add @bloomreach/discovery-web-sdk
```

--------------------------------

### Autosuggest API Usage

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/readme/bloomreach-discovery-sdk.md

Example demonstrating how to use the Autosuggest API with the Discovery Web SDK. It shows setting up configuration and search parameters, then retrieving suggestions.

```APIDOC
## Autosuggest API

### Description
Retrieves search suggestions based on the provided query and configuration.

### Method
`autosuggest(config: Configuration, searchOptions: AutosuggestOptions)`

### Parameters
#### Configuration
- **account_id** (number) - Required - Your Bloomreach account ID.
- **domain_key** (string) - Required - Your Bloomreach domain key.

#### AutosuggestOptions
- **catalog_views** (string) - Optional - Specifies which catalog views to use for suggestions.
- **q** (string) - Required - The search query string.
- **url** (string) - Required - The URL of the current page.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Request Example
```typescript
import type { Configuration, AutosuggestOptions } from '@bloomreach/discovery-web-sdk';
import { autosuggest } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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

const data = await autosuggest(config, searchOptions);
```

### Response
#### Success Response (200)
- **data** (object) - Contains the autosuggest results.
```

--------------------------------

### Run Build in Watch Mode

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Starts the build process in watch mode, automatically recompiling assets when changes are detected. Useful for active development.

```bash
pnpm dev
```

--------------------------------

### Product Search API Usage

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/readme/bloomreach-discovery-sdk.md

Example demonstrating how to use the Product Search API with the Discovery Web SDK. It shows setting up configuration and search parameters, then retrieving product data.

```APIDOC
## Product and Category Search API - Product Search

### Description
Performs a search for products based on a query and returns relevant product data.

### Method
`productSearch(config: Configuration, searchOptions: ProductSearchOptions)`

### Parameters
#### Configuration
- **account_id** (number) - Required - Your Bloomreach account ID.
- **domain_key** (string) - Required - Your Bloomreach domain key.

#### ProductSearchOptions
- **q** (string) - Required - The search query string for products.
- **fl** (string) - Optional - Comma-separated list of fields to return for each product.
- **start** (number) - Optional - The starting index for search results (pagination).
- **rows** (number) - Optional - The number of results to return per page.
- **url** (string) - Required - The URL of the current page.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Request Example
```typescript
import type { Configuration, ProductSearchOptions } from '@bloomreach/discovery-web-sdk';
import { productSearch } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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',
};

const data = await productSearch(config, searchOptions);
```

### Response
#### Success Response (200)
- **data** (object) - Contains the product search results.
```

--------------------------------

### Bestseller API Example

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Use this snippet to retrieve bestseller product data. Configure the account and provide search parameters including fields to retrieve, pagination, and user tracking.

```typescript
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);
```

--------------------------------

### Content Search API Example

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Use this snippet to retrieve content data using the Content Search API. Ensure the Configuration and ContentSearchOptions are correctly set.

```typescript
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);
```

--------------------------------

### Category Search API Usage

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/readme/bloomreach-discovery-sdk.md

Example demonstrating how to use the Category Search API with the Discovery Web SDK. It shows setting up configuration and search parameters, then retrieving category data.

```APIDOC
## Product and Category Search API - Category Search

### Description
Performs a search for categories based on a query and returns relevant category data.

### Method
`categorySearch(config: Configuration, searchOptions: CategorySearchOptions)`

### Parameters
#### Configuration
- **account_id** (number) - Required - Your Bloomreach account ID.
- **domain_key** (string) - Required - Your Bloomreach domain key.

#### CategorySearchOptions
- **q** (string) - Required - The search query string for categories (e.g., category ID).
- **fl** (string) - Optional - Comma-separated list of fields to return for each category.
- **start** (number) - Optional - The starting index for search results (pagination).
- **rows** (number) - Optional - The number of results to return per page.
- **url** (string) - Required - The URL of the current page.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Request Example
```typescript
import type { Configuration, CategorySearchOptions } from '@bloomreach/discovery-web-sdk';
import { categorySearch } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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',
};

const data = await categorySearch(config, searchOptions);
```

### Response
#### Success Response (200)
- **data** (object) - Contains the category search results.
```

--------------------------------

### Fetch Keyword Recommendations Widget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Get product recommendations based on a search keyword. This is suitable for displaying on search results pages. Ensure the `query` and other options are correctly configured.

```typescript
import type { Configuration, KeywordWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getKeywordWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: KeywordWidgetOptions = {
  query: 'running shoes',
  rows: 6,
  start: 0,
  url: 'https://www.example.com/search?q=running+shoes',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
};

try {
  const data = await getKeywordWidget('keyword_recs_widget', config, options);

  console.log(`${data.response.numFound} keyword-based recommendations`);
  data.response.docs.forEach(doc => console.log(doc.pid, doc.title, doc.price));
} catch (err) {
  console.error('getKeywordWidget failed:', err);
}
```

--------------------------------

### Lint Code with ESLint

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Runs ESLint to check for code style and potential errors according to the Airbnb style guide. Ensures code quality and consistency.

```bash
pnpm lint
```

--------------------------------

### Fetch Global Recommendations Widget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Use this to get globally trending or editorially curated product recommendations. It's not tied to specific user actions. Ensure the configuration and options are properly defined.

```typescript
import type { Configuration, GlobalWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getGlobalWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: GlobalWidgetOptions = {
  rows: 8,
  start: 0,
  url: 'https://www.example.com/homepage',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
  fields: 'pid,title,price,thumb_image,url',
};

try {
  const data = await getGlobalWidget('trending_homepage_widget', config, options);

  console.log(`Widget: ${data.metadata.widget.name} (${data.metadata.widget.type})`);
  console.log(`Personalized: ${data.metadata.response.personalized_results}`);
  console.log(`Total products: ${data.response.numFound}`);

  data.response.docs.forEach(doc => {
    console.log(`[${doc.pid}] ${doc.title} — $${doc.price} (sale: $${doc.sale_price})`);
    console.log('  Image:', doc.thumb_image);
    console.log('  URL:', doc.url);
  });
} catch (err) {
  console.error('getGlobalWidget failed:', err);
}
```

--------------------------------

### Run Tests in Watch Mode

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Starts the test runner in watch mode, automatically re-running tests when code changes are detected. Ideal for TDD or continuous testing during development.

```bash
pnpm test:watch
```

--------------------------------

### Perform a product search with options

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Use `productSearch` to query the product catalog. Configure search parameters like fields, filters, sorting, and facets. Handle potential errors and process the response, including product details, facets, and spell corrections.

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

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: ProductSearchOptions = {
  fl: 'pid,title,description,brand,price,sale_price,thumb_image,url',
  rows: 12,
  start: 0,
  url: 'https://www.example.com/search?q=boots',
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  // Facet filtering: only "Boots" brand, price ≤ $200
  fq: ['brand:("Boots")', 'price:("*" TO "200")'],
  sort: 'price asc',
  'stats.field': 'price',
  'query.precision': 'text_match_precision',
  'query.spellcorrect': 'closest_match',
};

try {
  const data = await productSearch('waterproof boots', config, options);

  const { numFound, start, docs } = data.response ?? {};
  console.log(`Found ${numFound} products, showing from ${start}`);

  docs?.forEach(doc => {
    console.log(`[${doc.pid}] ${doc.title} — $${doc.price} (sale: $${doc.sale_price})`);
  });

  // Facets (v3 format)
  data.facet_counts?.facets?.forEach(facet => {
    console.log('Facet:', facet.name, facet.type);
  });

  // Spell correction / "did you mean"
  if (data.autoCorrectQuery) console.log('Auto-corrected to:', data.autoCorrectQuery);
  if (data.did_you_mean?.length) console.log('Did you mean:', data.did_you_mean);

  // Price stats
  const priceStats = data.stats?.stats_fields.price;
  if (priceStats) console.log(`Price range: $${priceStats.min} – $${priceStats.max}`);
} catch (err) {
  console.error('productSearch failed:', err);
}
```

--------------------------------

### Fetch Bestselling Products with Options

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Use this to retrieve bestselling products, optionally filtered by a query term or category. Ensure the configuration object is correctly set up with account ID and domain key.

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

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: BestsellerOptions = {
  fl: 'pid,title,price,sale_price,thumb_image,brand',
  rows: 8,
  start: 0,
  url: 'https://www.example.com/bestsellers',
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  fq: 'category:("outerwear")',
  sort: 'sale_price asc',
};

try {
  // Pass an empty string or a category/keyword to scope bestsellers
  const data = await bestseller('', config, options);

  const { numFound, docs } = data.response ?? {};
  console.log(`Top ${docs?.length} bestsellers out of ${numFound}`);
  docs?.forEach((doc, i) => {
    console.log(`#${i + 1} [${doc.pid}] ${doc.title} — $${doc.price}`);
  });
} catch (err) {
  console.error('bestseller failed:', err);
}
```

--------------------------------

### Use Autosuggest API for Query and Product Suggestions

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Retrieve query, product, and attribute suggestions as a user types. Results are grouped by catalog and can be filtered by `catalog_views`. Ensure the `config` object is properly initialized.

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

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: AutosuggestOptions = {
  // catalog_views: 'catalogName:viewId1,viewId2|anotherCatalog'
  catalog_views: 'my_store_com:store_us,store_uk|articles',
  url: 'https://www.example.com/search',
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  ref_url: 'https://www.google.com',
  user_id: 'anonymous-user-42',
};

try {
  const data = await autoSuggest('ros', config, options);

  // data.suggestionGroups is an array, one entry per catalog
  for (const group of data.suggestionGroups ?? []) {
    console.log('Catalog:', group.catalogName);

    // Query suggestions (e.g. "roses", "rosemary", "rose gold")
    group.querySuggestions?.forEach(s => console.log('Query:', s.query, '|', s.displayText));

    // Product suggestions
    group.searchSuggestions?.forEach(p => console.log('Product:', p.pid, p.title, p.thumb_image));

    // Attribute suggestions (e.g. color: "rose gold")
    group.attributeSuggestions?.forEach(a =>
      console.log('Attribute:', a.attributeType, a.name, a.value)
    );
  }
} catch (err) {
  console.error('autoSuggest failed:', err);
}

// Expected shape of data:
// {
//   queryContext: { originalQuery: 'ros' },
//   suggestionGroups: [
//     {
//       catalogName: 'my_store_com',
//       querySuggestions: [{ query: 'roses', displayText: 'roses' }],
//       searchSuggestions: [{ pid: 'p001', title: 'Red Roses', thumb_image: '...', url: '...', sale_price: '9.99' }],
//       attributeSuggestions: [{ name: 'color', value: 'rose gold', attributeType: 'text' }]
//     }
//   ]
// }
```

--------------------------------

### Fetch Similar Items Widget using getItemWidget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Fetches 'similar items' or 'frequently bought together' product recommendations based on specific product IDs. Ensure the Configuration object includes account_id and domain_key.

```typescript
import type { Configuration, ItemWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getItemWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: ItemWidgetOptions = {
  item_ids: 'prod-001,prod-002',   // Comma-separated product IDs
  rows: 6,
  start: 0,
  url: 'https://www.example.com/product/prod-001',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
  fields: 'pid,title,price,sale_price,thumb_image',
};

try {
  const data = await getItemWidget('similar_items_widget', config, options);

  console.log(`${data.response.numFound} similar items`);
  data.response.docs.forEach(doc => {
    console.log(`${doc.pid}: ${doc.title} — $${doc.price}`);
  });
} catch (err) {
  console.error('getItemWidget failed:', err);
}
```

--------------------------------

### Build Distribution Assets

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Builds the distribution assets for the project. This command compiles the code into a usable format.

```bash
pnpm build
```

--------------------------------

### Run Tests Once

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/CONTRIBUTING.md

Executes all tests in the project once. This is typically used in CI environments or for a quick check.

```bash
pnpm test
```

--------------------------------

### Configure Bloomreach Discovery Web SDK

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Define the minimal required configuration with account ID and domain key, or a full configuration including authentication keys, view IDs, and endpoint overrides.

```typescript
import type { Configuration } from '@bloomreach/discovery-web-sdk';

// Minimal required configuration
const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

// Full configuration with all optional fields
const fullConfig: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
  auth_key: 'my-auth-key',          // Required for server-side calls
  view_id: 'us_en',                 // Target a specific catalog view
  debug: true,                      // Enables [BR] prefixed console logs
  searchEndpoint: 'https://core.dxpapi.com/api/v1/core/',     // default
  suggestEndpoint: 'https://suggest.dxpapi.com/api/v2/suggest/', // default
  widgetEndpoint: 'https://pathways.dxpapi.com/api/v2/widgets/', // default
};
```

--------------------------------

### Bestseller API

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/readme/bloomreach-discovery-sdk.md

This section explains how to use the `bestseller` function to retrieve bestseller products. It covers the necessary configuration and options for fetching bestseller data.

```APIDOC
## Bestseller API

### Description
Retrieves a list of bestseller products based on the provided configuration and search parameters.

### Function Signature
`bestseller(config: Configuration, options: BestsellerOptions): Promise<any>`

### Parameters
#### Configuration
- **account_id** (number) - Required - Your Bloomreach account ID.
- **domain_key** (string) - Required - Your Bloomreach domain key.

#### BestsellerOptions
- **q** (string) - Optional - A query to filter bestsellers (e.g., a category or keyword).
- **fl** (string) - Optional - Comma-separated list of fields to return.
- **start** (number) - Optional - The starting offset for search results.
- **rows** (number) - Optional - The number of bestseller results to return.
- **url** (string) - Optional - The URL of the current page.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Request Example
```typescript
import type { Configuration, BestsellerOptions } from '@bloomreach/discovery-web-sdk';
import { bestseller } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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',
};

const data = await bestseller(config, searchOptions);
```

### Response
#### Success Response
The response contains the list of bestseller products matching the criteria.
```

--------------------------------

### getKeywordWidget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Provides product recommendations based on a search keyword, suitable for displaying on search results pages alongside main results.

```APIDOC
## getKeywordWidget — Keyword Recommendations Widget

### Description
Provides product recommendations based on a search keyword, suitable for displaying on search results pages alongside main results.

### Usage
```typescript
import type { Configuration, KeywordWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getKeywordWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: KeywordWidgetOptions = {
  query: 'running shoes',
  rows: 6,
  start: 0,
  url: 'https://www.example.com/search?q=running+shoes',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
};

try {
  const data = await getKeywordWidget('keyword_recs_widget', config, options);

  console.log(`${data.response.numFound} keyword-based recommendations`);
  data.response.docs.forEach(doc => console.log(doc.pid, doc.title, doc.price));
} catch (err) {
  console.error('getKeywordWidget failed:', err);
}
```
```

--------------------------------

### Recommendations and Pathways APIs (Category Widget)

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/readme/bloomreach-discovery-sdk.md

This section covers retrieving recommendation widgets, specifically focusing on the `getCategoryWidget` function. It outlines the necessary configuration and options for fetching category-specific widgets.

```APIDOC
## Recommendations and Pathways APIs (Category Widget)

### Description
Retrieves a category widget with recommendations or pathways based on the provided widget ID, configuration, and search options.

### Function Signature
`getCategoryWidget(widgetId: string, config: Configuration, options: CategoryWidgetOptions): Promise<WidgetResponse>`

### Parameters
#### Widget ID
- **widgetId** (string) - Required - The unique identifier for the widget.

#### Configuration
- **account_id** (number) - Required - Your Bloomreach account ID.
- **domain_key** (string) - Required - Your Bloomreach domain key.

#### CategoryWidgetOptions
- **cat_id** (string) - Required - The ID of the category for which to fetch recommendations.
- **start** (number) - Optional - The starting offset for results.
- **rows** (number) - Optional - The number of results to return.
- **url** (string) - Optional - The URL of the current page.
- **ref_url** (string) - Optional - The referring URL.
- **request_id** (number) - Optional - An identifier for the request.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Request Example
```typescript
import {
  CategoryWidgetOptions,
  Configuration,
  WidgetResponse,
  getCategoryWidget,
} from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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';

const widget = getCategoryWidget(widgetId, config, searchOptions);
```

### Other Widget Functions
Similar functions are available for other widget types:
- `getGlobalWidget`
- `getKeywordWidget`
- `getItemWidget`
- `getPersonalizedWidget`
- `getRecentlyViewedWidget`
```

--------------------------------

### Product Search API Integration in TypeScript

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Integrates the Product Search API by configuring account details, specifying search fields, pagination, and retrieving product data. Ensure the 'fl' parameter includes desired fields.

```typescript
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);
```

--------------------------------

### getCategoryWidget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Returns product recommendations relevant to a specific category page, helping to surface related or complementary items.

```APIDOC
## getCategoryWidget — Category Recommendations Widget

### Description
Returns product recommendations relevant to a specific category page, helping surface related or complementary items.

### Usage
```typescript
import type { Configuration, CategoryWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getCategoryWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: CategoryWidgetOptions = {
  cat_id: 'cat-mens-jackets',
  rows: 6,
  start: 0,
  url: 'https://www.example.com/category/mens-jackets',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
  facet: true,
  filter: ['price:("50" TO "300")'],
};

try {
  const data = await getCategoryWidget('category_recs_widget', config, options);

  console.log(`Found ${data.response.numFound} recommendations for category`);
  data.response.docs.forEach(doc => {
    console.log(`${doc.pid}: ${doc.title} ($${doc.price})`);
  });
} catch (err) {
  console.error('getCategoryWidget failed:', err);
}
```
```

--------------------------------

### Fetch Category Recommendations Widget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Retrieve product recommendations relevant to a specific category page. This is useful for surfacing related or complementary items. Ensure `cat_id` and other options are correctly set.

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

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: CategoryWidgetOptions = {
  cat_id: 'cat-mens-jackets',
  rows: 6,
  start: 0,
  url: 'https://www.example.com/category/mens-jackets',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
  facet: true,
  filter: ['price:("50" TO "300")'],
};

try {
  const data = await getCategoryWidget('category_recs_widget', config, options);

  console.log(`Found ${data.response.numFound} recommendations for category`);
  data.response.docs.forEach(doc => {
    console.log(`${doc.pid}: ${doc.title} ($${doc.price})`);
  });
} catch (err) {
  console.error('getCategoryWidget failed:', err);
}
```

--------------------------------

### Recommendations and Pathways APIs (Widgets)

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Provides functions to retrieve various types of recommendation widgets, including category, global, keyword, item, personalized, and recently viewed widgets.

```APIDOC
## Recommendations and Pathways APIs (Widgets)

### Description
Retrieves widget data for recommendations and pathways. This includes functions for various widget types.

### Available Widget Functions
- `getCategoryWidget(widgetId: string, config: Configuration, searchOptions: CategoryWidgetOptions)`
- `getGlobalWidget(widgetId: string, config: Configuration, searchOptions: GlobalWidgetOptions)`
- `getKeywordWidget(widgetId: string, config: Configuration, searchOptions: KeywordWidgetOptions)`
- `getItemWidget(widgetId: string, config: Configuration, searchOptions: ItemWidgetOptions)`
- `getPersonalizedWidget(widgetId: string, config: Configuration, searchOptions: PersonalizedWidgetOptions)`
- `getRecentlyViewedWidget(widgetId: string, config: Configuration, searchOptions: RecentlyViewedWidgetOptions)`

### Parameters for `getCategoryWidget` (Example)
#### Configuration
- **account_id** (number) - Required - The account ID for Bloomreach Discovery.
- **domain_key** (string) - Required - The domain key for Bloomreach Discovery.

#### CategoryWidgetOptions
- **cat_id** (string) - Required - The category ID for the widget.
- **start** (number) - Optional - The starting index for results (default: 0).
- **rows** (number) - Optional - The number of results to return per page (default: 10).
- **url** (string) - Optional - The URL associated with the widget context.
- **ref_url** (string) - Optional - The referring URL.
- **request_id** (number) - Optional - A unique request identifier.
- **_br_uid_2** (string) - Optional - A unique identifier for the user, often a cookie ID.

### Response
#### Success Response (200)
Returns a `WidgetResponse` object containing the widget data.

### Request Example for `getCategoryWidget`
```typescript
import {
  CategoryWidgetOptions,
  Configuration,
  WidgetResponse,
  getCategoryWidget,
} from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 1234,
  domain_key: 'example_com',
};

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';

const widget: WidgetResponse = await getCategoryWidget(widgetId, config, searchOptions);
```
```

--------------------------------

### Autosuggest API Integration in TypeScript

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Integrates the Autosuggest API by setting account and catalog configuration, defining search parameters, and retrieving suggestions. Ensure correct configuration and search options are provided.

```typescript
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);
```

--------------------------------

### autoSuggest - Autosuggest API

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Retrieves query suggestions, product suggestions, and attribute suggestions as the user types. Results are grouped by catalog. The `catalog_views` parameter controls which catalogs (and views) contribute suggestions.

```APIDOC
## autoSuggest

### Description
Retrieves query suggestions, product suggestions, and attribute suggestions as the user types. Results are grouped by catalog. The `catalog_views` parameter controls which catalogs (and views) contribute suggestions.

### Method
`autoSuggest(query: string, config: Configuration, options?: AutosuggestOptions): Promise<AutosuggestResponse>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `autoSuggest` function:
- `query` (string): The text to get suggestions for.
- `config` (Configuration): The SDK configuration object.
- `options` (AutosuggestOptions, optional): Additional options for the autosuggest request.
  - `catalog_views` (string): Comma-separated list of catalog views to get suggestions from (e.g., 'catalogName:viewId1,viewId2|anotherCatalog').
  - `url` (string): The URL to use for the request.
  - `_br_uid_2` (string): A Bloomreach-specific user identifier.
  - `ref_url` (string): The referring URL.
  - `user_id` (string): The user ID.

### Request Example
```typescript
import type { Configuration, AutosuggestOptions } from '@bloomreach/discovery-web-sdk';
import { autoSuggest } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: AutosuggestOptions = {
  catalog_views: 'my_store_com:store_us,store_uk|articles',
  url: 'https://www.example.com/search',
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  ref_url: 'https://www.google.com',
  user_id: 'anonymous-user-42',
};

try {
  const data = await autoSuggest('ros', config, options);
  // Process data.suggestionGroups
} catch (err) {
  console.error('autoSuggest failed:', err);
}
```

### Response
#### Success Response
The response contains suggestion groups, each associated with a catalog. These groups can include query suggestions, product suggestions, and attribute suggestions.

#### Response Example
```json
{
  "queryContext": { "originalQuery": "ros" },
  "suggestionGroups": [
    {
      "catalogName": "my_store_com",
      "querySuggestions": [{ "query": "roses", "displayText": "roses" }],
      "searchSuggestions": [{ "pid": "p001", "title": "Red Roses", "thumb_image": "...", "url": "...", "sale_price": "9.99" }],
      "attributeSuggestions": [{ "name": "color", "value": "rose gold", "attributeType": "text" }]
    }
  ]
}
```
```

--------------------------------

### Category Search API Integration in TypeScript

Source: https://github.com/bloomreach/discovery-web-sdk/blob/main/README.md

Integrates the Category Search API by setting up account configuration, defining search parameters including category ID, and retrieving category data. Verify the 'q' parameter correctly specifies the category.

```typescript
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);
```

--------------------------------

### Fetch Recently Viewed Products Widget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Surfaces products a user has recently viewed, suitable for a 'Continue Shopping' or 'Recently Viewed' section. The user_id is required for personalization.

```typescript
import type { Configuration, RecentlyViewedWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getRecentlyViewedWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: RecentlyViewedWidgetOptions = {
  query: '',
  user_id: 'user-anonymous-abc123',
  rows: 6,
  start: 0,
  url: 'https://www.example.com/cart',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
};

try {
  const data = await getRecentlyViewedWidget('recently_viewed_widget', config, options);

  console.log(`Showing ${data.response.docs.length} recently viewed products`);
  data.response.docs.forEach(doc => {
    console.log(`${doc.pid}: ${doc.title} — $${doc.price}`);
    console.log('  Image:', doc.thumb_image, '| URL:', doc.url);
  });
} catch (err) {
  console.error('getRecentlyViewedWidget failed:', err);
}
```

--------------------------------

### `productSearch` — Product Search API

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Performs a keyword search across the product catalog. Returns matching product documents along with facets, statistics, groupings, and spell-correction hints.

```APIDOC
## `productSearch` — Product Search API

### Description
Performs a keyword search across the product catalog. Returns matching product documents along with facets, statistics, groupings, and spell-correction hints. Defaults: `fl='pid'`, `start=0`, `facet.version='3.0'`.

### Usage Example
```typescript
import type { Configuration, ProductSearchOptions } from '@bloomreach/discovery-web-sdk';
import { productSearch } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: ProductSearchOptions = {
  fl: 'pid,title,description,brand,price,sale_price,thumb_image,url',
  rows: 12,
  start: 0,
  url: 'https://www.example.com/search?q=boots',
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  // Facet filtering: only "Boots" brand, price ≤ $200
  fq: ['brand:("Boots")', 'price:("\"*\" TO \"200\")'] ,
  sort: 'price asc',
  'stats.field': 'price',
  'query.precision': 'text_match_precision',
  'query.spellcorrect': 'closest_match',
};

try {
  const data = await productSearch('waterproof boots', config, options);

  const { numFound, start, docs } = data.response ?? {};
  console.log(`Found ${numFound} products, showing from ${start}`);

  docs?.forEach(doc => {
    console.log(`[${doc.pid}] ${doc.title} — $${doc.price} (sale: $${doc.sale_price})`);
  });

  // Facets (v3 format)
  data.facet_counts?.facets?.forEach(facet => {
    console.log('Facet:', facet.name, facet.type);
  });

  // Spell correction / "did you mean"
  if (data.autoCorrectQuery) console.log('Auto-corrected to:', data.autoCorrectQuery);
  if (data.did_you_mean?.length) console.log('Did you mean:', data.did_you_mean);

  // Price stats
  const priceStats = data.stats?.stats_fields.price;
  if (priceStats) console.log(`Price range: $${priceStats.min} – $${priceStats.max}`);
} catch (err) {
  console.error('productSearch failed:', err);
}
```
```

--------------------------------

### Fetch Personalized Recommendations Widget

Source: https://context7.com/bloomreach/discovery-web-sdk/llms.txt

Returns product recommendations personalized to a specific user using the user_id field. Avoid using Personally Identifiable Information (PII) for user_id.

```typescript
import type { Configuration, PersonalizedWidgetOptions } from '@bloomreach/discovery-web-sdk';
import { getPersonalizedWidget } from '@bloomreach/discovery-web-sdk';

const config: Configuration = {
  account_id: 7654,
  domain_key: 'my_store_com',
};

const options: PersonalizedWidgetOptions = {
  query: 'jackets',
  user_id: 'user-anonymous-abc123',  // Anonymous user ID — never use PII
  rows: 8,
  start: 0,
  url: 'https://www.example.com/for-you',
  ref_url: 'https://www.example.com',
  request_id: Date.now(),
  _br_uid_2: 'uid%3D7797686432023%3Av%3D11.5%3Ats%3D1234567890',
  view_id: 'us_en',
};

try {
  const data = await getPersonalizedWidget('personalized_recs_widget', config, options);

  const { personalized_results, fallback } = data.metadata.response;
  console.log(`Personalized: ${personalized_results}, Fallback: ${fallback}`);
  data.response.docs.forEach(doc => console.log(doc.pid, doc.title));
} catch (err) {
  console.error('getPersonalizedWidget failed:', err);
}
```