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, CustomRequestBody, QueryParameters, RequireParametersUnlessAllAreOptional } from "../../types";
import type { ConsentSubscriptionBulkRequest, ConsentSubscriptionBulkResponse, ConsentSubscriptionRequest, ConsentSubscriptionResponse, ConsentSubscriptionUpdateResponse, LocaleCode } from '../models/index';
export type GetSubscriptionsExpandEnum = 'consentStatus';
export type GetSubscriptionsSfdcDwDntEnum = '0' | '1';
export type GetSubscriptionsPersonalizedEnum = 'none';
export type UpdateSubscriptionSfdcDwDntEnum = '0' | '1';
export type UpdateSubscriptionsSfdcDwDntEnum = '0' | '1';
/**
* [Shopper Consents](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-consents:Summary)
* ==================================
*
* *[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-consents/shopper-consents-oas-v1-public.yaml)

# API Overview

The Shopper Consent API offers a centralized method for managing shopper consent. With this API, shoppers can view and update subscription preferences for marketing communications across various channels. This API controls how and where shoppers receive marketing messages while ensuring compliance with privacy regulations.

The Shopper Consent API provides sensible defaults for optional fields to simplify integration:
- Consent Type: Defaults to "marketing" for marketing communications.
- Consent Required: Defaults to false, making subscriptions optional by default.
- Default Status: Defaults to "opt_out" to respect privacy-first principles.
- Tags: Defaults to an empty array when not specified.

## Authentication & Authorization

The Shopper Consent API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scope(s) in the client ID used to generate the SLAS token.

- `sfcc.shopper-consents`: Required for reading communication subscription data (GET operations).
- `sfcc.shopper-consents.rw`: Required for creating and modifying communication subscription consent data (POST operations).

For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

## Response Details

### Personalization

Responses from this API are not personalized via the Shopper Context API.

### Caching

Responses from this API are not cached. Consent data is unique to each shopper.

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

Retrieve the communication subscriptions for a shopper.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1/organizations/{organizationId}/subscriptions?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```


### Retrieve communication subscriptions

Retrieve relevant communication subscription options with rich display information.
    - Communication subscription options can be filtered by one or more qualifying tags.
    - Use the `expand` parameter to conditionally include subscription status.

### Update individual subscription consent

Update consent status for a single subscription with simple request/response pattern.

### Bulk subscription updates

Efficiently manage multiple subscription preferences with a single request.
    - Update 1-50 subscriptions per bulk request.
    - Partial success handling with detailed error reporting for failed updates.

## Data Model

### Subscriptions
Subscriptions represent a shopper's consent to receive specific types of marketing communications. Each subscription includes:

- Subscription Id: Descriptive identifier
- Channels: Array of communication methods - Email, SMS, or WhatsApp
- Consent Type: Marketing or legal subscription classification
- Consent Required: Whether the subscription is mandatory for the shopper
- Default Status: Default opt-in or opt-out behavior
- Consent Status: Array of status entries for each channel showing current opt-in or opt-out status (conditionally returned based on expand parameter)
- Rich Display Information:
  - Title: Simple localized string for subscription name
  - Subtitle: Simple localized string with HTML markup support for descriptions
  - Localized content determined by the locale parameter
- Tags: Categorical tags indicating where the subscription option can appear (defaults to empty array, max 10 tags)

### Channels
Channels define the communication methods available for a subscription:
- `email`: Email communications
- `sms`: SMS/text messages
- `whatsapp`: WhatsApp messaging

### Tags
Tags indicate where subscription options are displayed in your shopper experience. Tags are also accepted as optional filtering parameters in the retrieval of shopper consent subscriptions. For example:
- `homepage_banner`: Main website homepage
- `registration`: Shopper registration form
- `checkout`: Checkout flow
- `user_profile`: User profile management section

## Advanced Features

### Expand Parameter

The `expand` parameter provides conditional field inclusion:
- `expand=[]` (default): Returns basic subscription information
- `expand=["consentStatus"]`: Include consent status information in the response
- Future expansion may include additional fields

## Best Practices

- Use single subscription updates for real-time, interactive preference changes.
- Use bulk operations when updating multiple subscriptions to reduce API calls and improve performance.
- Only request status information when needed using the expand parameter to reduce latency.* <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 { ShopperConsents, ClientConfig } from "commerce-sdk";
* // or
* const { ShopperConsents, 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 shopperConsentsClient = new ShopperConsents(clientConfig);
* ```
*
* <span style="font-size:.7em; display:block; text-align: right">
* API Version: 1.4.4<br />
* Last Updated: <br />
* </span>
*
*/
export declare class ShopperConsents extends BaseClient {
    constructor(config: ClientConfig);
    /**
    * Retrieve all subscription preferences for the shopper (authenticated or guest).

Use the 'expand' parameter to include additional fields in the response:
- expand=["consentStatus"]: Include subscription status information
- expand=[]: Default behavior, excludes status for privacy and performance

The expand parameter provides privacy benefits by not exposing sensitive status
information unless explicitly requested.

    *
    * If you would like to get a raw Response object use the other getSubscriptions 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.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.tags - Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.
    * @param options.parameters.expand - Optional parameter to expand response with additional fields.
Accepts an array of field names to include in the response.
Currently supports:
- "consentStatus": Include consent status information in the response

Future expansions may include additional fields.

    * @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 ConsentSubscriptionResponse.
    */
    getSubscriptions(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
            tags?: Array<string>;
            expand?: Array<GetSubscriptionsExpandEnum>;
            personalized?: GetSubscriptionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<ConsentSubscriptionResponse>;
    /**
    * Retrieve all subscription preferences for the shopper (authenticated or guest).

Use the 'expand' parameter to include additional fields in the response:
- expand=["consentStatus"]: Include subscription status information
- expand=[]: Default behavior, excludes status for privacy and performance

The expand parameter provides privacy benefits by not exposing sensitive status
information unless explicitly requested.

    *
    * @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.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.tags - Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.
    * @param options.parameters.expand - Optional parameter to expand response with additional fields.
Accepts an array of field names to include in the response.
Currently supports:
- "consentStatus": Include consent status information in the response

Future expansions may include additional fields.

    * @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 ConsentSubscriptionResponse otherwise.
    */
    getSubscriptions<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
            tags?: Array<string>;
            expand?: Array<GetSubscriptionsExpandEnum>;
            personalized?: GetSubscriptionsPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : ConsentSubscriptionResponse>;
    /**
    * Update the consent status for a single subscription.
    *
    * If you would like to get a raw Response object use the other updateSubscription 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.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.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 options.body - The data to send as the request body.
    *
    * @returns A promise of type ConsentSubscriptionUpdateResponse.
    */
    updateSubscription(options: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
        body: ConsentSubscriptionRequest & CustomRequestBody;
    }>): Promise<ConsentSubscriptionUpdateResponse>;
    /**
    * Update the consent status for a single subscription.
    *
    * @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.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.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 options.body - The data to send as the request body.
    * @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 ConsentSubscriptionUpdateResponse otherwise.
    */
    updateSubscription<T extends boolean>(options: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
        body: ConsentSubscriptionRequest & CustomRequestBody;
    }>, rawResponse?: T): Promise<T extends true ? Response : ConsentSubscriptionUpdateResponse>;
    /**
    * Update the consent status for multiple subscriptions in a single bulk request. Supports 1-50 subscription updates per request with partial success handling.
    *
    * If you would like to get a raw Response object use the other updateSubscriptions 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.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.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 options.body - The data to send as the request body.
    *
    * @returns A promise of type ConsentSubscriptionBulkResponse.
    */
    updateSubscriptions(options: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
        body: ConsentSubscriptionBulkRequest & CustomRequestBody;
    }>): Promise<ConsentSubscriptionBulkResponse>;
    /**
    * Update the consent status for multiple subscriptions in a single bulk request. Supports 1-50 subscription updates per request with partial success handling.
    *
    * @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.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.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 options.body - The data to send as the request body.
    * @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 ConsentSubscriptionBulkResponse otherwise.
    */
    updateSubscriptions<T extends boolean>(options: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            siteId: string;
            locale?: LocaleCode;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
        body: ConsentSubscriptionBulkRequest & CustomRequestBody;
    }>, rawResponse?: T): Promise<T extends true ? Response : ConsentSubscriptionBulkResponse>;
}