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 { AvailabilityResult } from '../models/index';
export type GetAvailabilityExpandEnum = 'variations' | 'set_products';
export type GetAvailabilitySfdcDwDntEnum = '0' | '1';
export type GetAvailabilityPersonalizedEnum = 'none';
/**
* [Shopper Availability](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-availability:Summary)
* ==================================
*
* *[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-availability/shopper-availability-oas-v1-public.yaml)

# API Overview

Use the Shopper Availability API enables to retrieve inventory availability for products without fetching full product details. This allows independent caching strategies for volatile availability data and stable product data.

Use `/availability` to retrieve availability for products. If the `inventoryIds` parameter is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists.

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

## Authentication & Authorization

The client requesting the availability information must have access to the Availability resource. The Shopper Availability API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scopes in the client ID used to generate the SLAS token. 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#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

## Use Cases

### Retrieve Product Availability

Use the Shopper Availability API so that a customer can see whether products are in stock. This API returns availability details, including stock levels and inventory status, for up to 24 products per request.

### Retrieve Availability from Specific Inventory Lists

Use the `inventoryIds` parameter to retrieve availability from specific inventory lists rather than the site-assigned default. This is useful for scenarios such as showing availability at specific store locations or warehouses. You can request availability from up to 5 inventory lists per request.

### Retrieve Availability for Product Variations

Use the `expand=variations` parameter to retrieve availability for all variants of a master product in a single request. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant.

## Use Hooks

For details working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)* <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 { ShopperAvailability, ClientConfig } from "commerce-sdk";
* // or
* const { ShopperAvailability, 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 shopperAvailabilityClient = new ShopperAvailability(clientConfig);
* ```
*
* <span style="font-size:.7em; display:block; text-align: right">
* API Version: 1.4.4<br />
* Last Updated: <br />
* </span>
*
*/
export declare class ShopperAvailability extends BaseClient {
    constructor(config: ClientConfig);
    /**
    * Returns availability for multiple products. If `inventoryIds` is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists. The maximum number of product IDs that you can request is 24. The maximum number of inventory list IDs you can request is 5. The `productIds` parameter accepts product IDs for any product type (master, variant, standard, set, or bundle). Products that are offline or not found are silently filtered from the response. To retrieve availability for all variants of a master product, use the `expand=variations` parameter. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant.
    *
    * If you would like to get a raw Response object use the other getAvailability 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.productIds - The IDs of the requested products (comma-separated, max 24 IDs). If more than 24 IDs are required, split them into multiple parallel requests. Products that are offline or not found are silently filtered from the response.
    * @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.inventoryIds - The inventory list IDs for which the availability should be shown (comma-separated, max 5 inventory list IDs). If omitted, availability is returned from the site-assigned default inventory list. If provided, availability is returned only from the specified inventory lists.
    * @param options.parameters.expand - Expand the response to include availability for related products. When `variations` is specified, availability for all variation products of a master product is included. When `set_products` is specified, availability for all products in a product set is included. The parent product's availability is always included alongside the expanded entries. Expansion is single-level only: if a variation is itself a product set, its set products are not further expanded. Other product types (bundles, bundled items, set items) are not expanded. Expanded results are returned flat at the top level of the response array, not nested below their parent product.
**Note:** When using `expand=variations`, combine this response with variant data from the Shopper Products API to determine which specific variant attribute combinations (e.g. size=L, color=red) are orderable. Use the `productId` from each entry in the Shopper Products API `variants` array as the key to look up availability for that variant in this response.
    * @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 AvailabilityResult.
    */
    getAvailability(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            productIds: Array<string>;
            siteId: string;
            inventoryIds?: Array<string>;
            expand?: Array<GetAvailabilityExpandEnum>;
            personalized?: GetAvailabilityPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>): Promise<AvailabilityResult>;
    /**
    * Returns availability for multiple products. If `inventoryIds` is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists. The maximum number of product IDs that you can request is 24. The maximum number of inventory list IDs you can request is 5. The `productIds` parameter accepts product IDs for any product type (master, variant, standard, set, or bundle). Products that are offline or not found are silently filtered from the response. To retrieve availability for all variants of a master product, use the `expand=variations` parameter. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant.
    *
    * @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.productIds - The IDs of the requested products (comma-separated, max 24 IDs). If more than 24 IDs are required, split them into multiple parallel requests. Products that are offline or not found are silently filtered from the response.
    * @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.inventoryIds - The inventory list IDs for which the availability should be shown (comma-separated, max 5 inventory list IDs). If omitted, availability is returned from the site-assigned default inventory list. If provided, availability is returned only from the specified inventory lists.
    * @param options.parameters.expand - Expand the response to include availability for related products. When `variations` is specified, availability for all variation products of a master product is included. When `set_products` is specified, availability for all products in a product set is included. The parent product's availability is always included alongside the expanded entries. Expansion is single-level only: if a variation is itself a product set, its set products are not further expanded. Other product types (bundles, bundled items, set items) are not expanded. Expanded results are returned flat at the top level of the response array, not nested below their parent product.
**Note:** When using `expand=variations`, combine this response with variant data from the Shopper Products API to determine which specific variant attribute combinations (e.g. size=L, color=red) are orderable. Use the `productId` from each entry in the Shopper Products API `variants` array as the key to look up availability for that variant in this response.
    * @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 AvailabilityResult otherwise.
    */
    getAvailability<T extends boolean>(options?: RequireParametersUnlessAllAreOptional<{
        parameters?: CompositeParameters<{
            organizationId: string;
            productIds: Array<string>;
            siteId: string;
            inventoryIds?: Array<string>;
            expand?: Array<GetAvailabilityExpandEnum>;
            personalized?: GetAvailabilityPersonalizedEnum;
        } & QueryParameters, CommonParameters>;
        retrySettings?: OperationOptions;
        fetchOptions?: RequestInit;
        headers?: {
            [key: string]: string;
        };
    }>, rawResponse?: T): Promise<T extends true ? Response : AvailabilityResult>;
}