import { BaseClient, ClientConfig, Response } from "@commerce-apps/core";
import type { CommonParameters } from "@commerce-apps/core";
import type { OperationOptions } from "retry";
import type { RequestInit } from "node-fetch";
import type { CompositeParameters, QueryParameters, RequireParametersUnlessAllAreOptional } from "../../types";
import type { LocaleCode, ProductSearchResult, SuggestionResult } from '../models/index';
export type GetSearchSuggestionsSearchModeEnum = 'semantic' | 'lexical';
export type GetSearchSuggestionsExpandEnum = 'images' | 'prices' | 'custom_product_properties';
export type GetSearchSuggestionsSfdcDwDntEnum = '0' | '1';
export type GetSearchSuggestionsPersonalizedEnum = 'none';
export type ProductSearchSearchModeEnum = 'semantic' | 'lexical';
export type ProductSearchExpandEnum = 'none' | 'availability' | 'images' | 'prices' | 'represented_products' | 'variations' | 'promotions' | 'custom_properties' | 'page_meta_tags' | 'slug';
export type ProductSearchSfdcDwDntEnum = '0' | '1';
export type ProductSearchPersonalizedEnum = 'none';
/**
* [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-search:Summary)
* ==================================
*
* *[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-search/shopper-search-oas-v1-public.yaml)

# API Overview

Use the Shopper Search API for search functionality that lets shoppers search for products using keywords and refinement. The search results can be products or suggestions based on the endpoint you choose in the API.

## Authentication & Authorization

The client requesting the API must have access to the product search and search suggestion resources.

The Shopper Search API requires a JWT acquired via the Shopper Customers endpoint:

```
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
```

You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

## Customization

### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

## Request Details

### Property Selection

This API supports the `select` query parameter for filtering response properties. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)

### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

## Response Details

### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

## Use Cases

### Search for Products

Search for products by keyword. Replace `{access_token}` with a valid SLAS token.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/{organizationId}/product-search?q=dress&siteId=RefArch&limit=5" \
  -H "Authorization: Bearer {access_token}"
```


### Provide Search Suggestions

Use the Shopper Search API to provide search suggestions as a shopper searches.

For example, a developer who is building a shopping app using the Salesforce Commerce API would like to provide product, brand, and category suggestions. When a shopper types in a search phrase that exceeds a definable minimum length and the GET Search Suggestion endpoint is requested, the platform delivers a set of suggestions with products (name, ID), brands (name), and categories (name, ID). Shoppers can reach their desired search results more quickly using the suggested completion and correction.

### Provide Search Results

Use the Shopper Search API to gather product results for a shoppers search query.

For example, a developer who is building a shopping app using the Salesforce Commerce API would like to implement a product search functionality. When a shopper enters a search phrase and the GET Product Search endpoint is requested, the platform performs a keyword search and a sorted search result is returned. The sorted search result can be refined according to given values (for example, a price range).
The product search result contains a definable number of product search hits. A product search hit describes a matching product with its ID and name. Furthermore, the search hit contains product images, prices, represented products, and variations. In addition to the search hits, the search results also deliver refinement and sorting options.

### Retrieve Promotion Information

Note: This only applies if `promotions` expand is provided in the query parameter.

Promotions provide discounts to shoppers when they meet certain purchase requirements.

Promotion information is described in detail in [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html), but the following list provides several key points:

- Pricing discounts for basket and shipping promotions are NEVER returned by the 'getProduct' or 'getProducts' endpoint.
- Promotional pricing is ONLY returned for products that are included with non-conditional promotions.
- Callout messages are ALWAYS returned by the 'getProduct' and 'getProducts' endpoints.

By default, 'getProduct' and 'getProducts' return promotion information for a queried product. Promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by:

- Promotion Type
- Product Type
- Product Purchase Requirements

Some promotions can be displayed on a Product Data Page (PDP) or Product Listing page (PLP), while other promotions are displayed in the context of a basket, such as an order level promotion: "add the product to your basket to view price information". It is important to understand what is included in the response when designing a PDP or PLP on top of SCAPI to ensure your design aligns with implementable features.

Note: When you search for a variant product, the Product Search API returns the master or main product as the primary search hit. When promotion data (productPromotion) is returned, it does not contain pricing information because the returned product is the main product. To retrieve pricing information, pass the query string `allVariationProperties=true` with the `promotions` expand parameter, which returns pricing data for variant products if the promotion is unconditional. The `allVariationProperties` flag specifies the variation properties to be included in the result.

### Filter Products by Promotion Role

You can filter products by their role in a promotion using the `pmid` (promotion ID) and `pmpt` (promotion product type) refinement parameters together. This allows you to find specific types of products within a promotion:

- `pmid`: Specifies the promotion ID to filter by
- `pmpt`: Specifies the type of products to return within that promotion:
  - `all`: Returns all products related to the promotion (default behavior)
  - `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus
  - `discounted`: Returns only products that receive a discount in the promotion
  - `bonus`: Returns only products that are given as bonuses in the promotion

Example Usage:
```
GET /organizations/{organizationId}/product-search?refine=pmid=summer-sale&refine=pmpt=discounted
```

This would return only the products that receive discounts in the "summer-sale" promotion.

**Note:** The `pmpt` parameter only has an effect when used with `pmid`. If `pmpt` is specified without `pmid`, it will be ignored and all products will be returned.

### Shopper Personalization
The SCAPI response can be personalized using the Shopper Context API or hooks. By setting specific values in the Shopper Context API, you can modify the response of the 'getProduct' or 'getProducts' endpoint based on the shopper's context. For instance, you can offer a 5% discount or free shipping to shoppers using mobile devices.

## JWA Caching

The response is cached in JWA, which means promotion data contained in the response is also cached based on the TTL (Time to Live) specified in the Business Manager [Feature Switches](https://help.salesforce.com/s/articleView?id=cc.b2c_feature_switches.htm&type=5) configuration.
When the shopper context value is updated, a check is conducted to see if the updated shopper context affects the retrieval of product-promotion data. If it does, then the response is fetched from the source and cached in the JWA.

For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

## Best Practices

These best practices refer to features that are generally available with B2C Commerce 24.3.

For better performance, when you call the GET Product Search endpoint, we recommend that you:

- Use the `select` query parameter to filter the response of a specified field or set of fields, and remove default outputs that you don't need. For example, filter the response to return only the relevant product names, ids, variants, and product IDs of the variants.
- Limit API requests to the GET Product Search endpoint instead of calling both the GET Product Search and GET Products endpoints to show information on a product listing page (PLP). Use these features to provide the additional product information needed to render product tiles:
    - **Allowable value:** `promotions` value in the `expand` query parameter
    - **Query parameters:** `perPricebook`, `allImages`, and `allVariationProperties`
    - **Responses:** `productPromotions`, `imageGroups`, `priceRanges`, `tieredPrices`, `variants`, and `variationGroups`
- Pass in only the `expand` values and query parameters that you consider necessary to meet your PLP requirements. Requesting large amounts of information can increase the latency, especially if there's a lot of data to be returned (for example, many imageGroups and variants).* <br />
*
* For instructions on how to retrieve access token for admin APIs: <a>https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html</a> <br /> <br />
* Example with admin auth
*
* ```typescript
* import { ShopperSearch, ClientConfig } from "commerce-sdk";
* // or
* const { ShopperSearch, ClientConfig } = require("commerce-sdk");
*
* const clientConfig: ClientConfig = {
*   parameters: {
*     clientId: "XXXXXX",
*     organizationId: "XXXX",
*     shortCode: "XXX",
*     siteId: "XX"
*   }
* };
*
* token = { access_token: 'INSERT_ACCESS_TOKEN_HERE' };
*
* clientConfig.headers['authorization'] = `Bearer ${token.access_token}`;
* const shopperSearchClient = new ShopperSearch(clientConfig);
* ```
*
* <span style="font-size:.7em; display:block; text-align: right">
* API Version: 1.4.4<br />
* Last Updated: <br />
* </span>
*
*/
export declare class ShopperSearch extends BaseClient {
    constructor(config: ClientConfig);
    /**
    * Provide keyword search functionality for products, categories, and brands suggestions. Returns suggested
products, suggested categories, and suggested brands for the given search phrase.
    *
    * If you would like to get a raw Response object use the other getSearchSuggestions function.
    *
    * @param options - An object containing the options for this method.
    * @param options.parameters - An object containing the parameters for this method.
    * @param options.parameters.organizationId - An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    * @param options.parameters.siteId - The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    * @param options.parameters.q - The search phrase (q) for which suggestions are evaluated. Search suggestions are determined when the search phrase input is at least three (default) characters long. The value is configurable in the Business Manager.
    * @param options.parameters.searchMode - A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.

The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    * @param options.parameters.limit - The maximum number of suggestions made per request. If no value is defined, by default five suggestions per suggestion type are evaluated. This affects all types of suggestions (category, product, brand, and custom suggestions).
    * @param options.parameters.currency - A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    * @param options.parameters.locale - A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    * @param options.parameters.expand - A comma-separated list that allows values `images`, `prices`, `custom_product_properties`.
By default, the expand parameter includes `prices`.
    * @param options.parameters.includedCustomProductProperties - A comma-separated list of custom property ids to be returned for product suggestions. The `custom_product_properties` expand parameter is required for these properties to be returned.
    * @param options.parameters.includeEinsteinSuggestedPhrases - The flag that determines whether or not to show recent and popular suggested phrases from Einstein.
    * @param options.parameters.personalized - Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.

When set to `none`, the server skips applying personalization to the response.

Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    * @param options.retrySettings - Retry options for the `node-retry` package
    * @param options.fetchOptions - Fetch options for the `make-fetch-happen` package
    * @param options.headers - An object literal of key value pairs of the headers to be sent with this request.
    *
    * @returns A promise of type SuggestionResult.
    */
    getSearchSuggestions(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            q: string;
            searchMode?: GetSearchSuggestionsSearchModeEnum;
            limit?: number;
            currency?: string;
            locale?: LocaleCode;
            expand?: Array<GetSearchSuggestionsExpandEnum>;
            includedCustomProductProperties?: Array<string>;
            includeEinsteinSuggestedPhrases?: boolean;
            personalized?: GetSearchSuggestionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<SuggestionResult>;
    /**
    * Provide keyword search functionality for products, categories, and brands suggestions. Returns suggested
products, suggested categories, and suggested brands for the given search phrase.
    *
    * @param options - An object containing the options for this method.
    * @param options.parameters - An object containing the parameters for this method.
    * @param options.parameters.organizationId - An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    * @param options.parameters.siteId - The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    * @param options.parameters.q - The search phrase (q) for which suggestions are evaluated. Search suggestions are determined when the search phrase input is at least three (default) characters long. The value is configurable in the Business Manager.
    * @param options.parameters.searchMode - A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.

The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    * @param options.parameters.limit - The maximum number of suggestions made per request. If no value is defined, by default five suggestions per suggestion type are evaluated. This affects all types of suggestions (category, product, brand, and custom suggestions).
    * @param options.parameters.currency - A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    * @param options.parameters.locale - A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    * @param options.parameters.expand - A comma-separated list that allows values `images`, `prices`, `custom_product_properties`.
By default, the expand parameter includes `prices`.
    * @param options.parameters.includedCustomProductProperties - A comma-separated list of custom property ids to be returned for product suggestions. The `custom_product_properties` expand parameter is required for these properties to be returned.
    * @param options.parameters.includeEinsteinSuggestedPhrases - The flag that determines whether or not to show recent and popular suggested phrases from Einstein.
    * @param options.parameters.personalized - Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.

When set to `none`, the server skips applying personalization to the response.

Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    * @param options.retrySettings - Retry options for the `node-retry` package
    * @param options.fetchOptions - Fetch options for the `make-fetch-happen` package
    * @param options.headers - An object literal of key value pairs of the headers to be sent with this request.
    * @param rawResponse - Set to true to return entire Response object instead of DTO.
    *
    * @returns A promise of type Response if rawResponse is true, a promise of type SuggestionResult otherwise.
    */
    getSearchSuggestions<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            q: string;
            searchMode?: GetSearchSuggestionsSearchModeEnum;
            limit?: number;
            currency?: string;
            locale?: LocaleCode;
            expand?: Array<GetSearchSuggestionsExpandEnum>;
            includedCustomProductProperties?: Array<string>;
            includeEinsteinSuggestedPhrases?: boolean;
            personalized?: GetSearchSuggestionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : SuggestionResult>;
    /**
    * Provide keyword and refinement search functionality for products. Only returns the product ID, link, and name in
the product search hit. The search result only contains products that are online and assigned to the site
catalog.
    *
    * If you would like to get a raw Response object use the other productSearch function.
    *
    * @param options - An object containing the options for this method.
    * @param options.parameters - An object containing the parameters for this method.
    * @param options.parameters.organizationId - An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    * @param options.parameters.siteId - The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    * @param options.parameters.select - The property selector declaring which fields are included in the product search response payload. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)
    * @param options.parameters.q - The query phrase to search for. For example to search for a product "shirt", type q=shirt. **Note:** - Lexical search queries are limited to a maximum of 50 characters.
    * @param options.parameters.refine - Parameter that represents a refinement attribute or values pair. Refinement attribute ID and values are separated by '='.<br>
Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = \"|\"), for example: refine=c_refinementColor=red|green|blue.<br>
Value ranges can be specified like this: refine=price=(100..500).<br>
Multiple refine parameters can be provided by using the refine as the key, for example: refine=price=(0..10)&refine=c_refinementColor=green.<br>
The refinements can be a collection of custom defined attributes IDs and the system defined attributes IDs but the search can only accept a total of 9 refinements at a time.<br>

The following system refinement attribute ids are supported:<br>
`cgid`: Allows refinement per single category ID. Multiple category IDs are not supported.<br>
`cgslug`: Allows refinement by a category URL slug (for example, `mens/clothing`). The server resolves the slug to a category ID using the site's storefront URL mapping. If the slug can't be resolved to a category, the API returns a 400 error. This parameter is mutually exclusive with `cgid`. If both are provided, `cgid` takes priority and `cgslug` is ignored.<br>
`price`: Allows refinement per single price range. Multiple price ranges are not supported.<br>
`htype`: Allow refinement by including only the provided hit types. Accepted types are 'product', 'master', 'set', 'bundle', 'slicing_group' (deprecated), 'variation_group'.<br>
`orderable_only`: Unavailable products are excluded from the search results if true is set. Multiple refinement values are not supported.<br>
`ilids`: Allows refining by inventory list IDs. Supports up to 10 inventory list IDs per request.<br>
`pmid`: Allows refinement on the supplied promotion ID(s). When used with `pmpt`, filters products by their role in the promotion.<br>
`pmpt`: Allows refinement per promotion product type. Must be used with `pmid` to filter products by their role in the promotion. Valid values are:
  - `all`: Returns all products related to the promotion (default)
  - `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus
  - `discounted`: Returns only products that receive a discount in the promotion
  - `bonus`: Returns only products that are given as bonuses in the promotion

**Note:** To refine a search using multiple promotion filters—for example, to find products in both the spring and summer campaigns—see [Refining by Multiple Promotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-promotions-for-developers.html#refining-by-multiple-promotions).
    * @param options.parameters.sort - The ID of the sorting option to sort the search hits.
    * @param options.parameters.searchMode - A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.

The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    * @param options.parameters.currency - A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    * @param options.parameters.locale - A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    * @param options.parameters.expand - A comma-separated list with allowed values - `availability`, `images`, `prices`, `represented_products`, `variations`, `promotions`, `custom_properties`, `slug`.
By default, the expand parameter includes `availability, images, prices, represented_products, variations`.
Use none to disable all expand options.
    * @param options.parameters.allImages - When the `images` expand parameter is used with this flag, the response includes the `imageGroups` property, which contains an image model.
If this flag is true, the full image model is returned and you can combine with `imgTypes` to filter image types and counts. If false, only matching images are included.
If no flag is passed, the `imageGroups` property is omitted from the response.
    * @param options.parameters.imgTypes - Filters product images by type with optional count limits per type. This parameter requires both the `images` expand parameter and `allImages=true`.
When used, the response includes the `imageGroups` property filtered by the specified image types.
The format is a comma-separated list of image types with optional counts: `<imageType>:<count>,<imageType>:<count>`.
If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type.
For example, `imgTypes=large:2,small:1` returns up to 2 large images and 1 small image per product in the imageGroups.
If `imgTypes` is used without `allImages=true`, it is ignored and imageGroups aren't included in the response.
    * @param options.parameters.perPricebook - When this flag is set to `true` and is used with the `prices` expand parameter, the response includes per PriceBook prices and tiered prices (if available).
    * @param options.parameters.allVariationProperties - The flag that determines which variation properties are included in the result. When set to `true` with the `variations` expand parameter, all variation properties (`variationAttributes`, `variationGroups`, `variants`) are returned. When set to false, only the default property `variationAttributes` is returned.
    * @param options.parameters.includedCustomVariationProperties - A comma-separated list of custom property ids to be returned for variant products. The `variants` expand parameter and `allVariationProperties` query parameter are required for these properties to be returned.
    * @param options.parameters.limit - Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.
    * @param options.parameters.offset - Used to retrieve the results based on a particular resource offset.
    * @param options.parameters.personalized - Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.

When set to `none`, the server skips applying personalization to the response.

Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    * @param options.retrySettings - Retry options for the `node-retry` package
    * @param options.fetchOptions - Fetch options for the `make-fetch-happen` package
    * @param options.headers - An object literal of key value pairs of the headers to be sent with this request.
    *
    * @returns A promise of type ProductSearchResult.
    */
    productSearch(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            select?: string;
            q?: string;
            refine?: Array<string>;
            sort?: string;
            searchMode?: ProductSearchSearchModeEnum;
            currency?: string;
            locale?: LocaleCode;
            expand?: Array<ProductSearchExpandEnum>;
            allImages?: boolean;
            imgTypes?: string;
            perPricebook?: boolean;
            allVariationProperties?: boolean;
            includedCustomVariationProperties?: Array<string>;
            limit?: number;
            offset?: number;
            personalized?: ProductSearchPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<ProductSearchResult>;
    /**
    * Provide keyword and refinement search functionality for products. Only returns the product ID, link, and name in
the product search hit. The search result only contains products that are online and assigned to the site
catalog.
    *
    * @param options - An object containing the options for this method.
    * @param options.parameters - An object containing the parameters for this method.
    * @param options.parameters.organizationId - An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    * @param options.parameters.siteId - The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    * @param options.parameters.select - The property selector declaring which fields are included in the product search response payload. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)
    * @param options.parameters.q - The query phrase to search for. For example to search for a product "shirt", type q=shirt. **Note:** - Lexical search queries are limited to a maximum of 50 characters.
    * @param options.parameters.refine - Parameter that represents a refinement attribute or values pair. Refinement attribute ID and values are separated by '='.<br>
Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = \"|\"), for example: refine=c_refinementColor=red|green|blue.<br>
Value ranges can be specified like this: refine=price=(100..500).<br>
Multiple refine parameters can be provided by using the refine as the key, for example: refine=price=(0..10)&refine=c_refinementColor=green.<br>
The refinements can be a collection of custom defined attributes IDs and the system defined attributes IDs but the search can only accept a total of 9 refinements at a time.<br>

The following system refinement attribute ids are supported:<br>
`cgid`: Allows refinement per single category ID. Multiple category IDs are not supported.<br>
`cgslug`: Allows refinement by a category URL slug (for example, `mens/clothing`). The server resolves the slug to a category ID using the site's storefront URL mapping. If the slug can't be resolved to a category, the API returns a 400 error. This parameter is mutually exclusive with `cgid`. If both are provided, `cgid` takes priority and `cgslug` is ignored.<br>
`price`: Allows refinement per single price range. Multiple price ranges are not supported.<br>
`htype`: Allow refinement by including only the provided hit types. Accepted types are 'product', 'master', 'set', 'bundle', 'slicing_group' (deprecated), 'variation_group'.<br>
`orderable_only`: Unavailable products are excluded from the search results if true is set. Multiple refinement values are not supported.<br>
`ilids`: Allows refining by inventory list IDs. Supports up to 10 inventory list IDs per request.<br>
`pmid`: Allows refinement on the supplied promotion ID(s). When used with `pmpt`, filters products by their role in the promotion.<br>
`pmpt`: Allows refinement per promotion product type. Must be used with `pmid` to filter products by their role in the promotion. Valid values are:
  - `all`: Returns all products related to the promotion (default)
  - `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus
  - `discounted`: Returns only products that receive a discount in the promotion
  - `bonus`: Returns only products that are given as bonuses in the promotion

**Note:** To refine a search using multiple promotion filters—for example, to find products in both the spring and summer campaigns—see [Refining by Multiple Promotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-promotions-for-developers.html#refining-by-multiple-promotions).
    * @param options.parameters.sort - The ID of the sorting option to sort the search hits.
    * @param options.parameters.searchMode - A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.

The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    * @param options.parameters.currency - A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    * @param options.parameters.locale - A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    * @param options.parameters.expand - A comma-separated list with allowed values - `availability`, `images`, `prices`, `represented_products`, `variations`, `promotions`, `custom_properties`, `slug`.
By default, the expand parameter includes `availability, images, prices, represented_products, variations`.
Use none to disable all expand options.
    * @param options.parameters.allImages - When the `images` expand parameter is used with this flag, the response includes the `imageGroups` property, which contains an image model.
If this flag is true, the full image model is returned and you can combine with `imgTypes` to filter image types and counts. If false, only matching images are included.
If no flag is passed, the `imageGroups` property is omitted from the response.
    * @param options.parameters.imgTypes - Filters product images by type with optional count limits per type. This parameter requires both the `images` expand parameter and `allImages=true`.
When used, the response includes the `imageGroups` property filtered by the specified image types.
The format is a comma-separated list of image types with optional counts: `<imageType>:<count>,<imageType>:<count>`.
If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type.
For example, `imgTypes=large:2,small:1` returns up to 2 large images and 1 small image per product in the imageGroups.
If `imgTypes` is used without `allImages=true`, it is ignored and imageGroups aren't included in the response.
    * @param options.parameters.perPricebook - When this flag is set to `true` and is used with the `prices` expand parameter, the response includes per PriceBook prices and tiered prices (if available).
    * @param options.parameters.allVariationProperties - The flag that determines which variation properties are included in the result. When set to `true` with the `variations` expand parameter, all variation properties (`variationAttributes`, `variationGroups`, `variants`) are returned. When set to false, only the default property `variationAttributes` is returned.
    * @param options.parameters.includedCustomVariationProperties - A comma-separated list of custom property ids to be returned for variant products. The `variants` expand parameter and `allVariationProperties` query parameter are required for these properties to be returned.
    * @param options.parameters.limit - Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.
    * @param options.parameters.offset - Used to retrieve the results based on a particular resource offset.
    * @param options.parameters.personalized - Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.

When set to `none`, the server skips applying personalization to the response.

Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    * @param options.retrySettings - Retry options for the `node-retry` package
    * @param options.fetchOptions - Fetch options for the `make-fetch-happen` package
    * @param options.headers - An object literal of key value pairs of the headers to be sent with this request.
    * @param rawResponse - Set to true to return entire Response object instead of DTO.
    *
    * @returns A promise of type Response if rawResponse is true, a promise of type ProductSearchResult otherwise.
    */
    productSearch<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            select?: string;
            q?: string;
            refine?: Array<string>;
            sort?: string;
            searchMode?: ProductSearchSearchModeEnum;
            currency?: string;
            locale?: LocaleCode;
            expand?: Array<ProductSearchExpandEnum>;
            allImages?: boolean;
            imgTypes?: string;
            perPricebook?: boolean;
            allVariationProperties?: boolean;
            includedCustomVariationProperties?: Array<string>;
            limit?: number;
            offset?: number;
            personalized?: ProductSearchPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : ProductSearchResult>;
}