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, PromotionResult } from '../models/index';
export type GetPromotionsPersonalizedEnum = 'none';
export type GetPromotionsSfdcDwDntEnum = '0' | '1';
export type GetPromotionsForCampaignPersonalizedEnum = 'none';
export type GetPromotionsForCampaignSfdcDwDntEnum = '0' | '1';
/**
* [Shopper Promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-promotions:Summary)
* ==================================
*
* *[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-promotions/shopper-promotions-oas-v1-public.yaml)

# API Overview

Retrieve information about active promotions within the context of a shopper and a site. You can use this API to retrieve promotions that you configured in the commerce platform by searching for specific promotion IDs or by searching for promotions associated with a campaign.

## Authentication & Authorization

The Shopper Promotions API requires a JSON Web Token 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 scope(s) in the client ID used to generate the SLAS token. For details, see [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

### 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

### Get Promotions by ID

Retrieve one or more promotions by their IDs (comma-separated, max 50).

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-promotions/v1/organizations/{organizationId}/promotions?ids=Buy5for50,free_shipping&siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```


### Get Promotion by Promotion ID

Use the Shopper Promotions API to find promotion information by the promotion ID.

For example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the details about the applied promotions in the cart.

### Get Promotion by Campaign ID

Use the Shopper Promotions API to find promotion information by the campaign ID.

For example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the possible promotions that can be applied in the cart.

## Related APIs

- [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Create and manage promotions, discounts, and qualifiers.* <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 { ShopperPromotions, ClientConfig } from "commerce-sdk";
* // or
* const { ShopperPromotions, 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 shopperPromotionsClient = new ShopperPromotions(clientConfig);
* ```
*
* <span style="font-size:.7em; display:block; text-align: right">
* API Version: 1.4.4<br />
* Last Updated: <br />
* </span>
*
*/
export declare class ShopperPromotions extends BaseClient {
    constructor(config: ClientConfig);
    /**
    * In the request URL, you can specify up to 50 IDs. If you specify an ID that contains either parentheses or the separator characters, you must URL encode these characters.
Each request returns only enabled promotions as the server does not consider promotion qualifiers or schedules.
    *
    * If you would like to get a raw Response object use the other getPromotions 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.ids - A comma-separated list of promotion identifiers. Maximum: 50.
    * @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.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.
    * @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 PromotionResult.
    */
    getPromotions(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            ids: Array<string>;
            locale?: LocaleCode;
            personalized?: GetPromotionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<PromotionResult>;
    /**
    * In the request URL, you can specify up to 50 IDs. If you specify an ID that contains either parentheses or the separator characters, you must URL encode these characters.
Each request returns only enabled promotions as the server does not consider promotion qualifiers or schedules.
    *
    * @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.ids - A comma-separated list of promotion identifiers. Maximum: 50.
    * @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.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.
    * @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 PromotionResult otherwise.
    */
    getPromotions<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            ids: Array<string>;
            locale?: LocaleCode;
            personalized?: GetPromotionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : PromotionResult>;
    /**
    * Retrieves promotion information using filter criteria. In the request URL, you must provide a campaign_id parameter, and you can optionally specify a date
range by providing start_date and end_date parameters. Both parameters are required to specify a date range, and
omitting one causes the server to return a MissingParameterException fault. Each request returns only enabled
promotions, since the server does not consider promotion qualifiers or schedules.
    *
    * If you would like to get a raw Response object use the other getPromotionsForCampaign 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.campaignId - Find the promotions assigned to this campaign (mandatory).
    * @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.startDate - The start date of the promotion in ISO 8601 date time format.
    * @param options.parameters.endDate - The end date of the promotion in ISO 8601 date time format.
    * @param options.parameters.currency - The currency mnemonic specified for price. This parameter is effective only for product suggestions.
    * @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.
    * @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 PromotionResult.
    */
    getPromotionsForCampaign(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            campaignId: string;
            organizationId: string;
            siteId: string;
            startDate?: string;
            endDate?: string;
            currency?: string;
            personalized?: GetPromotionsForCampaignPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<PromotionResult>;
    /**
    * Retrieves promotion information using filter criteria. In the request URL, you must provide a campaign_id parameter, and you can optionally specify a date
range by providing start_date and end_date parameters. Both parameters are required to specify a date range, and
omitting one causes the server to return a MissingParameterException fault. Each request returns only enabled
promotions, since the server does not consider promotion qualifiers or schedules.
    *
    * @param options - An object containing the options for this method.
    * @param options.parameters - An object containing the parameters for this method.
    * @param options.parameters.campaignId - Find the promotions assigned to this campaign (mandatory).
    * @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.startDate - The start date of the promotion in ISO 8601 date time format.
    * @param options.parameters.endDate - The end date of the promotion in ISO 8601 date time format.
    * @param options.parameters.currency - The currency mnemonic specified for price. This parameter is effective only for product suggestions.
    * @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.
    * @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 PromotionResult otherwise.
    */
    getPromotionsForCampaign<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            campaignId: string;
            organizationId: string;
            siteId: string;
            startDate?: string;
            endDate?: string;
            currency?: string;
            personalized?: GetPromotionsForCampaignPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : PromotionResult>;
}