headless-js-api/dist/api/index.d.cts

Headless JS client for Ecwid public API

import { Blob } from 'buffer';

/**
 * Paginated response
 * @template T - The type of the items in the response.
 * @property {number} total - The total number of items in the response.
 * @property {number} count - The number of items in the response.
 * @property {number} offset - The offset of the items in the response.
 * @property {number} limit - The limit of the items in the response.
 * @property {T[]} items - The items in the response.
 */
interface PaginatedResponse<T> {
    total: number;
    count: number;
    offset: number;
    limit: number;
    items: T[];
}

type SearchParams = Record<string, string | number | boolean | undefined>;

/**
 * Configuration object for initializing the API client.
 *
 * @property {string} publicToken - The public access token for your store's API.
 * This token is used to authenticate requests that do not require a private token, such as fetching product or category data.
 * @property {string} [baseURL] - The base URL for the Ecwid API.
 * Default to 'https://app.ecwid.com/api/v3/'. This can be overridden for testing or specific regional API endpoints.
 * @property {string} [storeId] - The unique identifier for your Ecwid store. This ID is used to specify which store's data to access.
 */
interface ApiConfig {
    publicToken: string;
    storeId?: number;
    baseURL?: string;
    useMocks?: boolean;
}

declare enum SortBy {
    RELEVANCE = "RELEVANCE",
    DEFINED_BY_STORE_OWNER = "DEFINED_BY_STORE_OWNER",
    ADDED_TIME_DESC = "ADDED_TIME_DESC",
    ADDED_TIME_ASC = "ADDED_TIME_ASC",
    NAME_ASC = "NAME_ASC",
    NAME_DESC = "NAME_DESC",
    PRICE_ASC = "PRICE_ASC",
    PRICE_DESC = "PRICE_DESC",
    UPDATED_TIME_ASC = "UPDATED_TIME_ASC",
    UPDATED_TIME_DESC = "UPDATED_TIME_DESC"
}

declare const getApiConfig: () => ApiConfig;
declare const initStorefrontApi: (config: ApiConfig) => Promise<void>;

/** Detailed information about product's taxes. */
interface ProductTax {
    /** Defines if taxes can be applied to the product. */
    taxable: boolean;
    /** Default tax rate (%) for including into product price. It's a sum of all enabled taxes included in product price for the store location. Read only. */
    defaultLocationIncludedTaxRate: number;
    /** List of internal IDs for manual taxes. Empty if no manual taxes are enabled or automatic taxes are enabled. */
    enabledManualTaxes: number[];
    /** Tax class code for the product that determines the taxability of the products for a certain region. */
    taxClassCode: string;
}

/** Represents a wholesale price tier for a product or variation. */
interface WholesalePrice {
    /** Number of product items on this wholesale tier. */
    quantity: number;
    /** Product price on the tier. */
    price: number;
}

/** Product lowest price settings, typically for EU stores. */
interface LowestPriceSettings {
    /** Defines if the lowest price is enabled for the product and shown on the storefront. */
    lowestPriceEnabled: boolean;
    /** Manually entered lowest price for the last 30 days before any discounts or taxes applied. */
    manualLowestPrice?: number;
    /** manualLowestPrice with taxes applied. */
    defaultDisplayedManualLowestPrice?: number;
    /** Formatted display of defaultDisplayedManualLowestPrice using store format settings. */
    defaultDisplayedManualLowestPriceFormatted?: string;
    /** Automatically calculated lowest price for the last 30 days before any discounts or taxes applied. Read-only. */
    automaticLowestPrice?: number;
    /** automaticLowestPrice with taxes applied. Read-only. */
    defaultDisplayedAutomaticLowestPrice?: number;
    /** Formatted display of defaultDisplayedAutomaticLowestPrice using store format settings. Read-only. */
    defaultDisplayedAutomaticLowestPriceFormatted?: string;
}

/** Represents a choice for a product option, detailing its text and price modification. */
interface ProductOptionChoice {
    /** Text displayed for the option choice. */
    text: string;
    /** Available translations for the choice's text field. */
    textTranslated: Record<string, string>;
    /** Value of the option's price markup. */
    priceModifier: number;
    /** Option markup calculation type (PERCENT or ABSOLUTE). */
    priceModifierType: string;
}

/** Defines a product option, such as size or color, including its type, name, and available choices. */
interface ProductOption {
    /** Option type that defines its functionality.
     * One of: SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES, SIZE, SWATCHES. */
    type: string;
    /** Product option name (e.g., Color or Size). */
    name: string;
    /** Available translations for product option name. */
    nameTranslated: Record<string, string>;
    /** List of available option choices for users.
     * Only works for SELECT, CHECKBOX, RADIO, SIZE, or SWATCHES option types. */
    choices?: ProductOptionChoice[];
    /** Index of the option's default selection. Can be null (no default option), otherwise starts with 0.
     * Only works for SELECT, CHECKBOX, RADIO, SIZE, or SWATCHES option types. */
    defaultChoice?: number;
    /** Defines if this option is required to add product to the cart. */
    required?: boolean;
}

/** Shipping settings specific to the product. */
interface ProductShipping {
    /** Type of shipping calculation.
     * One of: "GLOBAL_METHODS", "SELECTED_METHODS", "FLAT_RATE", "FREE_SHIPPING". */
    type: string;
    /** Additional product shipping cost added to any shipping methods. */
    methodMarkup: number;
    /** Flat rate cost for shipping the product. If set, shipping costs for it will not be calculated. */
    flatRate: number;
    /** IDs of shipping methods that need to be excluded from calculation when this product is in cart. */
    disabledMethods: string[];
    /** IDs of shipping methods which will only be shown when this product is in cart. */
    enabledMethods: string[];
}

/** Details about a product image, typically the main image. */
interface ProductImage {
    /** Link to the full-size product image. */
    url: string;
    /** Width of the full-size product image in px. */
    width: number;
    /** Height of the full-size product image in px. */
    height: number;
}

interface ProductColor {
    /** Red channel (from 0 to 255, RGB). */
    red: number;
    /** Green channel (from 0 to 255, RGB). */
    green: number;
    /** Blue channel (from 0 to 255, RGB). */
    blue: number;
    /** Alpha channel (from 0 to 255). */
    alpha: number;
}

/** Details about an image border added at the storefront, including its dominating color and homogeneity. */
interface ProductBorderInfo {
    /** Border color in RGBa format. */
    dominatingColor: ProductColor;
    /** Defines if an image is homogeneous. */
    homogeneity: boolean;
}

interface ProductGalleryImage {
    id: number;
    url: string;
    /** Link to the gallery image thumbnail resized to fit 160x160px container. */
    thumbnail: string;
    /** Link to the full-sized gallery image. */
    originalImageUrl: string;
    /** Link to the gallery image resized to fit 1200x1200px container. */
    imageUrl: string;
    /** Link to the gallery image thumbnail resized to fit 800x800px container. */
    hdThumbnailUrl: string;
    /** Link to the gallery image thumbnail resized to fit 400x400px container. */
    thumbnailUrl: string;
    /** Link to the gallery image thumbnail resized to fit 160x160px container. */
    smallThumbnailUrl: string;
    /** Width of the full-sized gallery image in px. */
    width: number;
    /** Height of the full-sized gallery image in px. */
    height: number;
    /** Consecutive number of an image in the gallery. Starts with 0. */
    orderBy: number;
    /** Details about image border added at the storefront. */
    borderInfo: ProductBorderInfo;
}

/** Represents the alt text for a product image, including translations. */
interface ProductImageAlt {
    /** Image description for the "alt" HTML attribute of the image. */
    main?: string;
    /** Available translations for the "alt" text. */
    translated: Record<string, string>;
}

/** Details about a product image within the media collection. */
interface ProductMediaImage {
    /** Internal image ID in a string format. Starts with "0". */
    id: string;
    /** Defines the main product image (if true). */
    isMain: boolean;
    /** Consecutive number of an image in the gallery. */
    orderBy: number;
    /** Link to the product image resized to fit 160x160px. */
    image160pxUrl: string;
    /** Link to the product image resized to fit 400x400px. */
    image400pxUrl: string;
    /** Link to the product image resized to fit 800x800px. */
    image800pxUrl: string;
    /** Link to the product image resized to fit 1500x1500px. */
    image1500pxUrl: string;
    /** Link to the full-sized product image. */
    imageOriginalUrl: string;
    /** Image description for the "alt" HTML attribute and its translations. */
    alt: ProductImageAlt;
}

/** Details about a product video within the media collection. */
interface ProductMediaVideo {
    /** Internal video ID. Starts with "0". */
    id: number;
    /** Internal ID of the video cover image. */
    videoCoverId: number;
    /** Link to the video file. */
    url: string;
    /** Video embedding code in HTML. */
    embedHtml: string;
    /** Video hosting provider name. */
    providerName: string;
    /** Video title. */
    title: string;
    /** Link to the video cover image resized to fit 160x160px container. */
    image160pxUrl: string;
    /** Link to the video cover image resized to fit 400x400px container. */
    image400pxUrl: string;
    /** Link to the video cover image resized to fit 800x800px container. */
    image800pxUrl: string;
    /** Link to the video cover image resized to fit 1500x1500px container. */
    image1500pxUrl: string;
    /** Link to the full-sized video cover image. */
    imageOriginalUrl: string;
}

/** Contains details about product images and videos. */
interface ProductMedia {
    /** Details about product images. */
    images: ProductMediaImage[];
    /** Details about product videos. */
    videos: ProductMediaVideo[];
}

/** Represents a category a product belongs to, including its ID and enabled status. */
interface ProductCategory {
    /** Internal category ID. */
    id: number;
    /** Defines if the category is enabled. */
    enabled: boolean;
}

/** Stats showing how many times the product was added to favorites on the storefront. */
interface ProductFavorites {
    /** Total count the product was added to favorites on the storefront. */
    count: number;
    /** The number of likes visible on the storefront. May differ from count if it exceeds 1000 (e.g., 1K). */
    displayedCount: string;
}

/** Represents a product attribute and its value. */
interface ProductAttribute {
    /** Internal attribute ID. */
    id: number;
    /** Attribute name visible on the storefront. */
    name: string;
    /** Available translations for the attribute name. */
    nameTranslated: Record<string, string>;
    /** Value of the attribute for this product. */
    value: string;
    /** Available translations for the attribute value. */
    valueTranslated: Record<string, string>;
    /** Attribute type (e.g., CUSTOM, UPC, BRAND).
     * One of: CUSTOM, UPC, BRAND, GENDER, AGE_GROUP, COLOR, SIZE, PRICE_PER_UNIT, UNITS_IN_PRODUCT. */
    type: string;
    /** Defines if an attribute is visible on a product page.
     * One of: NOTSHOW, DESCR, PRICE. */
    show: string;
}

/** Details about a downloadable file attached to the product. */
interface ProductFile {
    /** Internal ID of the file attached to the product. */
    id: number;
    /** File name visible to clients. */
    name: string;
    /** File description visible to clients. */
    description: string;
    /** File size in bytes (64-bit integer). */
    size: number;
    /** Direct link to the file. Important: to download, append API access token. */
    adminUrl: string;
}

/** Describes the "N random related products from a category" option for related products. */
interface ProductRelatedCategory {
    /** Defines if the "N random related products from a category" option is enabled. */
    enabled: boolean;
    /** ID of the related category. Empty value means related products can be from any category. */
    categoryId: number;
    /** Number of random products from the given category. */
    productCount: number;
}

/** List of related products displayed as "You may also like" for a product. */
interface ProductRelatedProducts {
    /** List of related product IDs. */
    productIds: number[];
    /** Describes the "N random related products from a category" option. */
    relatedCategory: ProductRelatedCategory;
}

/** Product's dimensions for calculating shipping costs. */
interface ProductDimensions {
    /** Length of a product for calculating shipping costs. */
    length: number;
    /** Width of a product for calculating shipping costs. */
    width: number;
    /** Height of a product for calculating shipping costs. */
    height: number;
}

/** Represents a selected product option value that identifies a product variation. */
interface ProductCombinationOption {
    /** Name of the selected option. */
    name: string;
    /** Available translations for the product option name. */
    nameTranslated: Record<string, string>;
    /** Value of the selected option. */
    value: string;
    /** Available translations for the product option value. */
    valueTranslated: Record<string, string>;
}

/** Details about a product variation (combination of product options). */
interface ProductCombination {
    /** Internal ID for the product variation. */
    id: number;
    /** Ordered variation number displayed in Ecwid admin. Starts with 1. */
    combinationNumber: number;
    /** Set of selected product option values that identify this variation. */
    options: ProductCombinationOption[];
    /** Variation SKU. If empty, inherits the base product's SKU. */
    sku?: string;
    /** Link to the variation image resized to fit 400x400px container. */
    thumbnailUrl?: string;
    /** Link to the variation image resized to fit 1200x1200px container. */
    imageUrl?: string;
    /** Link to the variation image resized to fit 160x160px container. */
    smallThumbnailUrl?: string;
    /** Link to the variation image resized to fit 800x800px container. */
    hdThumbnailUrl?: string;
    /** Link to the full-sized variation image. */
    originalImageUrl?: string;
    /** Number of variation items in stock. Not returned if unlimited is true. */
    quantity?: number;
    /** Defines if the variation has unlimited stock. */
    unlimited?: boolean;
    /** Base variation price without any modifiers. */
    price?: number;
    /** Sorted list of wholesale price tiers specific to the variation. */
    wholesalePrices?: WholesalePrice[];
    /** Variation's weight for calculating shipping costs. */
    weight?: number;
    /** Minimum amount of variation in stock to trigger "low stock" notification. */
    warningLimit?: number;
    /** List of variation attributes and their values. */
    attributes?: ProductAttribute[];
    /** Pre-sale price for the variation. */
    compareToPrice?: number;
    /** Sets minimum product purchase quantity. Default is null. */
    minPurchaseQuantity?: number;
    /** Sets maximum product purchase quantity. Default is null. */
    maxPurchaseQuantity?: number;
    /** Defines visibility/pre-order behavior when out-of-stock. One of: SHOW, HIDE, ALLOW_PREORDER. */
    outOfStockVisibilityBehaviour?: string;
    /** Variation price for logged out customers with default location. Includes taxes. */
    defaultDisplayedPrice?: number;
    /** Formatted variant of defaultDisplayedPrice. */
    defaultDisplayedPriceFormatted?: string;
    /** Variation's lowest price for EU store. */
    lowestPrice?: number;
    /** Variation's lowest price for logged out customers with default location. Includes taxes. */
    defaultDisplayedLowestPrice?: number;
    /** Formatted variant of defaultDisplayedLowestPrice. */
    defaultDisplayedLowestPriceFormatted?: string;
    /** Variation's lowest price settings. Defines if lowest price is enabled. */
    lowestPriceSettings?: LowestPriceSettings;
    /** Variation's dimensions. */
    dimensions?: ProductDimensions;
    /** Variation volume for calculations shipping costs, fractional number, 0 by default. */
    volume?: number;
    /** Variation image description for the "alt" HTML attribute and its translations. */
    alt?: ProductImageAlt;
}

/** Internal details on recurring charges for product subscriptions. */
interface ProductRecurringChargeSettings {
    /** Charge recurring interval. Supported values: DAY, WEEK, MONTH, YEAR. */
    recurringInterval: 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
    /** Charge recurring interval count.
     * Supported values: for DAY - 1 (daily), for WEEK - 1 (weekly), 2 (biweekly),
     * for MONTH - 1 (monthly), 3 (quarterly), for YEAR - 1 (annually). */
    recurringIntervalCount: number;
}

/** Internal details for subscription products. */
interface ProductSubscriptionSettings {
    /** true if the product can be sold as subscription. */
    subscriptionAllowed: boolean;
    /** true if the product can be purchased once. */
    oneTimePurchaseAllowed: boolean;
    /** The cost of the product by subscription with a one-time purchase, null by default. */
    oneTimePurchasePrice?: number | null;
    /** Formatted cost of the product for a one-time purchase. */
    oneTimePurchasePriceFormatted?: string;
    /** Difference between subscription price and one-time purchase price (absolute). */
    oneTimePurchaseMarkup?: number;
    /** Formatted difference (absolute). */
    oneTimePurchaseMarkupFormatted?: string;
    /** Difference between subscription price and one-time purchase price (percentage). */
    oneTimePurchaseMarkupPercent?: number;
    /** Formatted difference (percentage). */
    oneTimePurchaseMarkupPercentFormatted?: string;
    /** Recurring charge settings. */
    recurringChargeSettings?: ProductRecurringChargeSettings[];
    /** The cost of the product for the first subscription order. */
    subscriptionPriceWithSignUpFee?: number;
    /** Formatted cost for the first subscription order. */
    subscriptionPriceWithSignUpFeeFormatted?: string;
    /** The size of the markup that is imposed on the first order. */
    signUpFee?: number;
    /** Formatted size of the markup for the first order. */
    signUpFeeFormatted?: string;
}

/** Represents a product in an Ecwid store. */
interface Product {
    /** Internal unique product ID. */
    id: number;
    /** Product SKU. Items with options can have several SKUs specified in the product variations. */
    sku: string;
    /** Amount of product items in stock. If product has unlimited stock, this field is not returned. */
    quantity?: number;
    /** Defines if the product has unlimited stock. */
    unlimited: boolean;
    /** Defines if the product or any of its variations are in stock (quantity > 0). */
    inStock: boolean;
    /** Product name visible on the storefront. */
    name: string;
    /** Available translations for the product name. */
    nameTranslated: Record<string, string>;
    /** Base product price without any modifiers. */
    price: number;
    /** Product price as shown on storefront (may differ from price due to pre-selected options/variations). Does not include taxes. */
    priceInProductList: number;
    /** Product price as shown on storefront for logged out customers with default location. Includes taxes. */
    defaultDisplayedPrice: number;
    /** Formatted variant of defaultDisplayedPrice. */
    defaultDisplayedPriceFormatted: string;
    /** Purchase price of the product, used for reports and profit calculations. */
    costPrice?: number;
    /** Detailed information about product's taxes. */
    tax: ProductTax;
    /** Sorted list of wholesale price tiers. */
    wholesalePrices?: WholesalePrice[];
    /** Product pre-sale price (without taxes). */
    compareToPrice?: number;
    /** Formatted display of compareToPrice (with currency symbol, includes taxes if store uses net prices). */
    compareToPriceFormatted?: string;
    /** Discount from the sale price. */
    compareToPriceDiscount?: number;
    /** Formatted discount from the sale price. */
    compareToPriceDiscountFormatted?: string;
    /** Discount percent from the sale price. */
    compareToPriceDiscountPercent?: number;
    /** Formatted sale price discount percent. */
    compareToPriceDiscountPercentFormatted?: string;
    /** Product pre-sale price including taxes. */
    defaultDisplayedCompareToPrice?: number;
    /** Formatted display of defaultDisplayedCompareToPrice (with currency symbol, includes taxes if store uses net prices). */
    defaultDisplayedCompareToPriceFormatted?: string;
    /** Discount from the sale price, including taxes. */
    defaultDisplayedCompareToPriceDiscount?: number;
    /** Formatted discount from the sale price, including taxes. */
    defaultDisplayedCompareToPriceDiscountFormatted?: string;
    /** Discount percent from the sale price, including taxes. */
    defaultDisplayedCompareToPriceDiscountPercent?: number;
    /** Formatted sale price discount percent, including taxes. */
    defaultDisplayedCompareToPriceDiscountPercentFormatted?: string;
    /** Product's lowest price (before taxes and discounts) in the last 30 days. */
    lowestPrice?: number;
    /** Product's lowest price as displayed on storefront for default location (includes taxes). */
    defaultDisplayedLowestPrice?: number;
    /** Formatted display of defaultDisplayedLowestPrice. */
    defaultDisplayedLowestPriceFormatted?: string;
    /** Product lowest price settings for EU stores. */
    lowestPriceSettings?: LowestPriceSettings;
    /** Defines if the product requires shipping. */
    isShippingRequired: boolean;
    /** Product weight in units defined in store settings. Not returned if product has no weight. */
    weight?: number;
    /** Link to the product details page on the storefront. */
    url: string;
    /** Page slug generated for the product page URL automatically. */
    autogeneratedSlug: string;
    /** Custom slug defined by the store owner. Affects product page URL. */
    customSlug: string;
    /** Datetime of the product creation (e.g., 2024-07-30 10:32:37 +0000). */
    created: string;
    /** Datetime of the latest product change (e.g., 2024-07-30 10:32:37 +0000). */
    updated: string;
    /** UNIX timestamp of the product creation. */
    createTimestamp: number;
    /** UNIX timestamp of the latest product change. */
    updateTimestamp: number;
    /** ID of the product class. 0 for default "General" class. */
    productClassId: number;
    /** Defines if the product is enabled and visible on the storefront. */
    enabled: boolean;
    /** Detailed list of product options. Empty array if no options are specified. */
    options: ProductOption[];
    /** Minimum amount of products in stock to trigger a "low stock" email notification. */
    warningLimit?: number;
    /** Legacy. True if shipping cost is 'Fixed rate per item'. See 'shipping' field instead. */
    fixedShippingRateOnly: boolean;
    /** Legacy. Product fixed shipping cost per item or extra shipping cost. See 'shipping' field instead. */
    fixedShippingRate: number;
    /** Shipping settings specific to the product. */
    shipping: ProductShipping;
    /** Identifier of the default product variation. */
    defaultCombinationId: number;
    /** Details about product main image. */
    originalImage: ProductImage;
    /** Product description in HTML format. Scripts are not supported. */
    description: string;
    /** Available translations for the product description. */
    descriptionTranslated: Record<string, string>;
    /** Details about product gallery images. */
    galleryImages: ProductGalleryImage[];
    /** Details about product images and videos. */
    media: ProductMedia;
    /** List of the category IDs the product belongs to. */
    categoryIds: number[];
    /** Detailed list of the categories the product belongs to. */
    categories: ProductCategory[];
    /** Default category ID of the product. 0 if no default category. */
    defaultCategoryId: number;
    /** Page title for search engines. Recommended length < 55 chars. */
    seoTitle: string;
    /** Translations for the SEO page title. */
    seoTitleTranslated: Record<string, string>;
    /** Page description for search engines. Recommended length < 160 chars. */
    seoDescription: string;
    /** Translations for the SEO page description. */
    seoDescriptionTranslated: Record<string, string>;
    /** Stats showing how many times the product was added to favorites. */
    favorites: ProductFavorites;
    /** List of product attributes and their values. */
    attributes: ProductAttribute[];
    /** Details about downloadable files attached to the product. */
    files: ProductFile[];
    /** List of related products displayed as "You may also like". */
    relatedProducts: ProductRelatedProducts;
    /** Details about product variations. */
    combinations: ProductCombination[];
    /** Product's dimensions. */
    dimensions: ProductDimensions;
    /** Shipping preparation time settings. Structure might vary. */
    shippingPreparationTime?: Record<string, unknown>;
    /** Whether to show delivery time in the storefront. */
    showDeliveryTimeInStorefront?: boolean;
    /** Product volume for calculations shipping costs, fractional number, 0 by default. */
    volume: number;
    /** Product index on the main storefront page starting with 1. */
    showOnFrontpage?: number;
    /** Defines sample product created by Ecwid. Sample products are unavailable for purchase. */
    isSampleProduct: boolean;
    /** Condition of the item for Google Shopping (e.g., new, used, refurbished). */
    googleItemCondition?: string;
    /** Defines if a product is a gift card. */
    isGiftCard: boolean;
    /** Defines if Ecwid can apply discounts to the product. */
    discountsAllowed: boolean;
    /** Defines if customers can set their own price for the product. */
    nameYourPriceEnabled: boolean;
    /** Internal details for subscription products. */
    subscriptionSettings: ProductSubscriptionSettings;
    /** Google Product Category ID. */
    googleProductCategory?: number;
    /** Google Product Category name. */
    googleProductCategoryName?: string;
    /** Condition of the product (e.g., NEW, USED, REFURBISHED). */
    productCondition?: string;
    /** Defines behavior for out-of-stock products (SHOW, HIDE, ALLOW_PREORDER). */
    outOfStockVisibilityBehaviour?: string;
    /** Small product description visible under the product title. */
    subtitle?: string;
    /** Available translations for product subtitles. */
    subtitleTranslated?: Record<string, string>;
    /** When true, allows to collect, check, and publish reviews for this product. */
    reviewsCollectingAllowed?: boolean;
    /** Average rating from product reviews. */
    rating?: number;
    /** Number of reviews published by the store owner. */
    reviewsPublished?: number;
    /** Number of reviews waiting for store owner's approval. */
    reviewsModerated?: number;
}

/**
 * Response type for the searchProducts request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/search-products#response-json
 */
type SearchProductsResponse = PaginatedResponse<Product>;
/**
 * Parameters for the searchProducts request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/search-products#query-params
 */
interface SearchProductsParams extends SearchParams {
    /** Ecwid store ID. */
    storeId?: number;
    /** Internal IDs of Ecwid products separated by a comma.
     * If this field is specified, other search parameters are ignored. */
    productId?: string;
    /** Product or variation SKU. Ecwid will return details of a product containing that SKU, if SKU value is an exact match.
     * If SKU is specified, other search parameters are ignored, except for product ID. */
    sku?: string;
    /** Search term. Add * at the end of the keyword to disable the exact match search.
     * Search supports any language enabled in the store and specified in the lang param.
     * Supported fields:
     * - name
     * - description
     * - SKU (including variations SKU)
     * - options
     * - category name
     * - gallery image descriptions
     * - attributes values (except for hidden attributes). Any special characters must be URI-encoded. */
    keyword?: string;
    /** Extension to keyword.
     * One of:
     * - STOREFRONT – emulates search on the storefront
     * - CP – emulates search in Ecwid admin */
    searchMethod?: 'STOREFRONT' | 'CP';
    /** Product ID in linked POS. Includes both product IDs and product variation IDs.
     * Search term for product ID from the connected POS system (Lightspeed X/R series). */
    externalReferenceId?: string;
    /** Search term for finding products assigned to a specific category by its ID. */
    category?: number;
    /** Search term for finding products assigned to specified category IDs. For example: 0,123456,138470508. */
    categories?: string;
    /** Set true to get products from the subcategories of specified categories. */
    includeProductsFromSubcategories?: boolean;
    /** Minimum product price. */
    priceFrom?: number;
    /** Maximum product price. */
    priceTo?: number;
    /** Product creation date/time (lower bound). Supported formats: UNIX timestamp, datetime.
     * Examples: 1447804800, 2023-01-15 19:27:50 */
    createdFrom?: string | number;
    /** Product creation date/time (upper bound). Supported formats: UNIX timestamp, datetime.
     * Examples: 1447804800, 2023-01-15 19:27:50 */
    createdTo?: string | number;
    /** Product update date/time (lower bound). Supported formats: UNIX timestamp, date/time.
     * Examples: 1447804800, 2023-01-15 19:27:50 */
    updatedFrom?: string | number;
    /** Product update date/time (upper bound). Supported formats: UNIX timestamp, date/time.
     * Examples: 1447804800, 2023-01-15 19:27:50 */
    updatedTo?: string | number;
    /** Sort order for found products.
     * One of:
     * - RELEVANCE (default)
     * - DEFINED_BY_STORE_OWNER
     * - ADDED_TIME_DESC
     * - ADDED_TIME_ASC
     * - NAME_ASC
     * - NAME_DESC
     * - PRICE_ASC
     * - PRICE_DESC
     * - UPDATED_TIME_ASC
     * - UPDATED_TIME_DESC
     * When category search term is set, DEFINED_BY_STORE_OWNER is used automatically. */
    sortBy?: SortBy;
    /** Set true to get only enabled products.
     * Set false to get only disabled products. */
    enabled?: boolean;
    /** Set true to get gift cards only.
     * Set false to receive gift cards only. */
    isGiftCard?: boolean;
    /** Set true to get only in-stock products.
     * Set false to get only out-of-stock products. */
    inStock?: boolean;
    /** Set true to get only products with allowed discounts.
     * Set false to get only products where discounts are not allowed. */
    discountsAllowed?: boolean;
    /** Set true to get only products visible on the storefront.
     * Set false to get only hidden products. */
    visibleInStorefront?: boolean;
    /** Set true to get only products with customer-defined prices.
     * Set false to get only products without customer-defined prices. */
    isCustomerSetPrice?: boolean;
    /** Set onsale to get only items currently on sale.
     * Set onsale to get only items currently on sale.
     * Set notonsale to get only items currently not on sale. */
    onsale?: 'onsale' | 'notonsale';
    /** Set instock to get only in-stock products.
     * Set outofstock to get only out-of-stock products. */
    inventory?: 'instock' | 'outofstock';
    /** Set base URL for URLs in response.
     * If not specified, Ecwid will use the main URL from store settings. */
    baseUrl?: string;
    /** Set true to force receiving clean URLs – catalog links without hashbang (/#!/).
     * By default Ecwid checks if this setting is enabled for the store and responds with matching URLs. */
    cleanUrls?: boolean;
    /** Set true to receive product page slugs without IDs.
     * By default Ecwid checks if this setting is enabled for the store and responds with matching URLs. */
    slugsWithoutIds?: boolean;
    /** Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request.
     * Usually used to receive all items in several requests with multiple of a hundred, for example:
     * ?offset=0 for the first request,
     * ?offset=100, for the second request,
     * ?offset=200, for the third request, etc */
    offset?: number;
    /** Limit to the number of returned items. Maximum and default value (if not specified) is 100. */
    limit?: number;
    /** Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body.
     * Example: ?responseFields=total,items(id,name,price,quantity) */
    responseFields?: string;
    /** Filter by product option name and one or several comma-separated values for that option.
     * A product will appear in the response if it has an option with a specified name that has any of the specified values.
     * For example, a product has an option named Size with three values 24, 26, and 30.
     * Then the following search term will find the product: option_Size=24,22.
     * Even when the product doesn't have an option value 22. */
    [key: `option_${string}`]: string | undefined;
    /** Filter by product attribute name and one or several comma-separated values for that attribute.
     * A product will appear in the response if it has an attribute with a specified name that has any of the specified values.
     * For example, a product has an attribute named Brand with an Ecwid value.
     * Then the following search term will find the product: attribute_Brand=Ecwid,Lightspeed.
     * Even when the product doesn't have a Lightspeed attribute value.
     */
    [key: `attribute_${string}`]: string | undefined;
}

/**
 * Search for products.
 *
 * @param {SearchProductsParams} params - The parameters for the searchProducts request.
 * @returns {Promise<SearchProductsResponse>} A promise that resolves to the search results.
 */
declare const searchProducts: (params?: SearchProductsParams) => Promise<SearchProductsResponse>;

/**
 * Response type for the getProduct request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/get-product#response-json
 */
type GetProductResponse = Product;
/**
 * Parameters for the getProduct request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/get-product#path-params
 */
interface GetProductParams {
    productId: number;
    baseUrl?: string;
    cleanUrls?: boolean;
    slugsWithoutIds?: boolean;
    lang?: string;
    responseFields?: string;
}

/**
 * Fetches a single product by its ID.
 *
 * @param {GetProductParams} params - The parameters for the getProduct request.
 * @returns {Promise<GetProductResponse>} A promise that resolves to the product details.
 */
declare const getProduct: (params: GetProductParams) => Promise<GetProductResponse>;

/**
 * The response from the downloadProductFile request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/product-files/download-product-file#response-json
 */
type DownloadProductFileResponse = Blob;
/**
 * The parameters for the downloadProductFile request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/products/product-files/download-product-file#query-params
 */
interface DownloadProductFileParams {
    storeId?: number;
    productId: number;
    fileId: number;
}

/**
 * Download a product file
 * @param {DownloadProductFileParams} params - The parameters for the downloadProductFile request.
 * @returns {Promise<DownloadProductFileResponse>} A promise that resolves to the download product file results.
 */
declare const downloadProductFile: (params: DownloadProductFileParams) => Promise<DownloadProductFileResponse>;

interface Category {
    id: number;
    name: string;
    enabled: boolean;
    description?: string;
    subcategories?: Category[];
    url?: string;
    imageUrl?: string;
    originalImageUrl?: string;
    thumbnail?: string;
    orderBy?: number;
    parentId?: number;
    productCount?: number;
}

/**
 * Response type for the searchCategories request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/categories/search-categories#response-json
 */
type SearchCategoriesResponse = PaginatedResponse<Category>;
/**
 * Parameters for the searchCategories request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/categories/search-categories#query-params
 */
interface SearchCategoriesParams {
    keyword?: string;
    parent?: number;
    parentIds?: string;
    withSubcategories?: boolean;
    hidden_categories?: boolean;
    offset?: number;
    limit?: number;
    lang?: string;
    responseFields?: string;
}

/**
 * Search categories in the store based on provided parameters.
 *
 * @param {SearchCategoriesParams} params - The parameters for the searchCategories request.
 * @returns {Promise<SearchCategoriesResponse>} A promise that resolves to the categories search results.
 */
declare const searchCategories: (params?: SearchCategoriesParams) => Promise<SearchCategoriesResponse>;

interface AccountBilling {
    planName: string;
    subscriptionFee: number;
    activeSubscriptionPeriod: string;
}

interface CurrencyFormat {
    code: string;
    symbol: string;
    symbolPosition: string;
    thousandsSeparator: string;
    decimalSeparator: string;
    decimalPlaces: number;
}

interface Account {
    accountEmail: string;
    accountName: string;
    accountId: number;
    accountCurrency: string;
    accountCurrencyFormat: CurrencyFormat;
    accountBilling: AccountBilling;
    availableFunctionality: string[];
    accountNickName: string;
    whiteLabel: boolean;
    brandName: string;
    supportEmail: string;
    suspended: boolean;
    itunesSubscriptionsAvailable: boolean;
    googlePlaySubscriptionsAvailable: boolean;
    trackStorefrontStats: boolean;
    availableFeatures: string[];
    registrationDate: string;
    paid: boolean;
    limitsAndRestrictions: Record<string, any>;
}

interface Address {
    country: string;
    street: string;
    city: string;
    stateOrProvince: string;
    postalCode: string;
}

interface ApplePay {
    enabled: boolean;
    available: boolean;
}

interface Company {
    companyName: string;
    email: string;
    street: string;
    city: string;
    countryCode: string;
    postalCode: string;
    stateOrProvinceCode: string;
    phone: string;
}

interface DesignSettings {
    enable_catalog_on_one_page: boolean;
    product_list_image_size: string;
    product_list_show_product_images: boolean;
    product_list_product_info_layout: string;
    product_details_show_product_sku: boolean;
    product_details_layout: string;
    cart_widget_layout: string;
    show_footer_menu: boolean;
    show_breadcrumbs: boolean;
}

interface FeatureToggle {
    name: string;
    visible: boolean;
    enabled: boolean;
}

interface FilterSection {
    type: string;
    enabled: boolean;
    name?: string;
}

interface AddressFormat {
    plain: string;
    multiline: string;
}
interface FormatsAndUnits {
    currency: string;
    currencyPrefix: string;
    currencySuffix: string;
    currencyGroupSeparator: string;
    currencyDecimalSeparator: string;
    currencyPrecision: number;
    currencyTruncateZeroFractional: boolean;
    currencyRate: number;
    weightUnit: string;
    weightGroupSeparator: string;
    weightDecimalSeparator: string;
    weightTruncateZeroFractional: boolean;
    timeFormat: string;
    dateFormat: string;
    timezone: string;
    dimensionsUnit: string;
    volumeUnit: string;
    orderNumberPrefix: string;
    orderNumberSuffix: string;
    addressFormat: AddressFormat;
}

interface StarterSite {
    ecwidSubdomainSuffix: string;
    generatedUrl: string;
    customDomain: string;
    storeLogoUrl: string;
}

interface GeneralInfo {
    storeId: number;
    email: string;
    creationDate: string;
    storeUrl: string;
    name: string;
    starterSite: StarterSite;
    storeLogoUrl: string;
    fbPixelId: string;
    websitePlatform: string;
    profileId: string;
}

interface InstructionsForCustomer {
    instructionsTitle: string;
    instructions: string;
    instructionsTranslated: Record<string, string>;
}

interface Languages {
    enabledLanguages: string[];
    facebookPreferredLocale: string;
    defaultLanguage: string;
}

interface LegalPage {
    type: string;
    enabled: boolean;
    title: string;
    titleTranslated: Record<string, string>;
    display: string;
    displayTranslated: Record<string, string>;
    text: string;
    textTranslated: Record<string, string>;
    externalUrl: string;
    externalUrlTranslated: Record<string, string>;
}

interface LegalPagesSettings {
    requireTermsAgreementAtCheckout: boolean;
    legalPages: LegalPage[];
}

interface NotificationSetting {
    enabled: boolean;
    marketingBlockEnabled?: boolean;
}

interface CustomerOrderMessages {
    orderConfirmation: NotificationSetting;
    orderStatusChanged: NotificationSetting;
    orderIsReadyForPickup: NotificationSetting;
    downloadEgoods: NotificationSetting;
    orderShipped: NotificationSetting;
    orderDelivered: NotificationSetting;
}
interface AdminMessages {
    newOrderPlaced: NotificationSetting;
    lowStockNotification: NotificationSetting;
    weeklyStatsReport: NotificationSetting;
}
interface MailNotifications {
    adminNotificationEmails: string[];
    customerNotificationFromEmail: string;
    customerOrderMessages: CustomerOrderMessages;
    adminMessages: AdminMessages;
}

interface OrderInvoiceSettings {
    invoiceLogoUrl: string;
    attachInvoiceToOrderEmailNotifications: string;
}

interface PaymentOption {
    id: string;
    enabled: boolean;
    configured: boolean;
    checkoutTitle: string;
    checkoutTitleTranslated: Record<string, string>;
    checkoutDescription: string;
    paymentProcessorId: string;
    paymentProcessorTitle: string;
    orderBy: number;
    appClientId: string;
    appNamespace: string;
    instructionsForCustomer: InstructionsForCustomer;
    methods: any[];
    paymentSurcharges?: {
        type: string;
        value: number;
    };
}

interface Payment {
    paymentOptions: PaymentOption[];
    applePay: ApplePay;
    applePayOptions: any[];
}

interface PhoneNotifications {
    adminNotificationPhones: string[];
}

interface ProductFiltersSettings {
    enabledInStorefront: boolean;
    filterSections: FilterSection[];
}

interface RegistrationAnswers {
    alreadySelling: string;
    goods: string;
    forSomeone: string;
    website: string;
}

interface SalePrice {
    displayOnProductList: boolean;
    oldPriceLabel: string;
    oldPriceLabelTranslated: Record<string, string>;
    displayDiscount: string;
    displayLowestPrice: boolean;
}

interface HandlingFee {
    value: number;
}
interface ShippingOrigin {
    street: string;
    city: string;
    countryCode: string;
    countryName: string;
    postalCode: string;
    stateOrProvinceCode: string;
}
interface FlatRate {
    rateType: string;
    rate: number;
}
interface DestinationZone {
    id: string;
    name: string;
}
interface EstimatedShippingTimeAtCheckoutSettings {
    estimatedDeliveryDateAtCheckoutEnabled: boolean;
    estimatedTransitTimeInDays: (number | null)[];
    fulfillmentTimeInDays: number[];
    cutoffTimeForSameDayPacking: string;
    shippingBusinessDays: string[];
    deliveryDays: string[];
}
interface ShippingOption {
    id: string;
    title: string;
    titleTranslated: Record<string, string>;
    enabled: boolean;
    orderby: number;
    fulfilmentType: string;
    ratesCalculationType?: string;
    destinationZone: DestinationZone;
    businessHours: string;
    minimumOrderSubtotal: number;
    businessHoursLimitationType: string;
    flatRate?: FlatRate;
    carrier?: string;
    estimatedShippingTimeAtCheckoutSettings?: EstimatedShippingTimeAtCheckoutSettings;
    scheduled?: boolean;
    fulfillmentTimeInMinutes?: number;
    pickupInstruction?: string;
    pickupInstructionTranslated?: Record<string, string>;
    scheduledPickup?: boolean;
    pickupPreparationTimeHours?: number;
    pickupBusinessHours?: string;
}
interface Shipping {
    handlingFee: HandlingFee;
    shippingOrigin: ShippingOrigin;
    shippingOptions: ShippingOption[];
}

interface ShippingZone {
    id: string;
    name: string;
    countries?: string[];
}

interface ShippingSettings {
    shippingZones: ShippingZone[];
}

interface SocialLinksSettings {
    facebook: Record<string, any>;
    instagram: Record<string, any>;
    twitter: Record<string, any>;
    youtube: Record<string, any>;
    vk: Record<string, any>;
    pinterest: Record<string, any>;
}

interface StoreSettings {
    storeName: string;
    storeEmail: string;
    storeDescription: string;
    storeTitle: string;
    invoiceLogoUrl: string;
    favIconUrl: string;
    checkoutHeaderLogoUrl: string;
    defaultLanguage: string;
    languages: string[];
    shippingOrigin: Address;
    askCompanyName: boolean;
    hideOutOfStockProductsInStorefront: boolean;
    orderCommentsCaption: string;
    orderCommentsRequired: boolean;
    orderCommentsCaptionTranslated: Record<string, string>;
    favoritesEnabled: boolean;
    defaultProductSortOrder: string;
    productSortOrderInCart: string;
    salePrice: SalePrice;
    showPricePerUnit: boolean;
    googleProductCategory: number;
    googleProductCategoryName: string;
    productCondition: string;
    closed: boolean;
    storeDescriptionTranslated: Record<string, string>;
    emailLogoUrl: string;
    googleRemarketingEnabled: boolean;
    googleAnalyticsId: string;
}

interface Tax {
    id: number;
    name: string;
    enabled: boolean;
    includeInPrice: boolean;
    useShippingAddress: boolean;
    taxShipping: boolean;
    appliedByDefault: boolean;
    defaultTax: number;
    rules: any[];
}

interface TaxInvoiceSettings {
    taxInvoiceLogoUrl: string;
    attachTaxInvoiceToOrderEmailNotifications: string;
    enableTaxInvoices: boolean;
    generateInvoicesAutomatically: string;
    taxInvoiceIdPrefix: string;
    taxInvoiceIdSuffix: string;
    taxInvoiceIdMinDigitsAmount: number;
    taxInvoiceIdNextNumber: number;
}

interface TaxSettings {
    automaticTaxEnabled: boolean;
    euIossEnabled: boolean;
    ukVatRegistered: boolean;
    taxes: Tax[];
    pricesIncludeTax: boolean;
    taxExemptBusiness: boolean;
    b2b_b2c: string;
    electronicInvoiceFieldsAtCheckoutEnabled: boolean;
    taxOnShippingCalculationScheme: string;
}

interface TipsSettings {
    enabled: boolean;
    type: string;
    options: number[];
    defaultOption: number;
    title: string;
    subTitle: string;
    titleTranslated: Record<string, string>;
    subtitleTranslated: Record<string, string>;
}

interface Zone {
    id: string;
    name: string;
    countryCodes?: string[];
}

/**
 * Represents a store profile in the Ecwid API.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/store-profile/get-store-profile
 */
interface StoreProfile {
    generalInfo: GeneralInfo;
    account: Account;
    settings: StoreSettings;
    designSettings: DesignSettings;
    payment: Payment;
    shippingSettings: ShippingSettings;
    taxSettings: TaxSettings;
    mailNotifications: MailNotifications;
    productFiltersSettings: ProductFiltersSettings;
    orderInvoiceSettings: OrderInvoiceSettings;
    socialLinksSettings: SocialLinksSettings;
    registrationAnswers: RegistrationAnswers;
    tipsSettings: TipsSettings;
    taxInvoiceSettings: TaxInvoiceSettings;
    featureToggles: FeatureToggle[];
    legalPagesSettings: LegalPagesSettings;
    phoneNotifications: PhoneNotifications;
    company: Company;
    formatsAndUnits: FormatsAndUnits;
    languages: Languages;
    shipping: Shipping;
    zones: Zone[];
    taxes: Tax[];
}

/**
 * Response type for the getStoreProfile request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/store-profile/get-store-profile#response-json
 */
type GetStoreProfileResponse = StoreProfile;
/**
 * Parameters for the getStoreProfile request.
 * Based on: https://docs.ecwid.com/api-reference/rest-api/store-profile/get-store-profile#query-params
 */
interface GetStoreProfileParams {
    storeId?: number;
    /**
     * Set true to receive additional store profile data including account/billing data.
     * Requires read_store_profile_extended access scope.
     */
    showExtendedInfo?: boolean;
    /**
     * Language ISO code for translations in JSON response, e.g. en, fr.
     * Translates fields like: title, description, pickupInstruction, text, etc.
     */
    lang?: string;
    /**
     * Specify the exact fields to receive in response JSON.
     * If not specified, the response JSON will have all available fields for the entity.
     * Example: generalInfo(storeId,storeUrl)
     */
    responseFields?: string;
}

/**
 * Fetches the store profile.
 *
 * @param {GetStoreProfileParams} params - Optional parameters for the getStoreProfile request.
 * @returns {Promise<GetStoreProfileResponse>} A promise that resolves to the store profile.
 */
declare const getStoreProfile: (params?: GetStoreProfileParams) => Promise<GetStoreProfileResponse>;

export { type Account, type AccountBilling, type Address, typ