@liquidcommerce/cloud-sdk 1.3.0 → 1.5.0

package/dist/types/interfaces/catalog.interface.d.ts

@@ -1,8 +1,250 @@
-import type { ENUM_MODALITIES } from '../enums';
+import type { ENUM_AVAILABILITY_VALUE, ENUM_ENGRAVING, ENUM_FILTER_KEYS, ENUM_MODALITIES, ENUM_NAVIGATION_ORDER_DIRECTION_TYPE, ENUM_ORDER_BY } from '../enums';
+import type { LiquidTaxonomy } from '../types';
+import type { ILocBase } from './address.interface';
+import type { IRetailer } from './retailer.interface';
+/**
+ * ICategoryFilter represents a filter specifically for categories.
+ */
+export interface ICategoryFilter {
+    key: ENUM_FILTER_KEYS.CATEGORIES | 'categories';
+    values: LiquidTaxonomy[];
+}
+/**
+ * The IPriceFilter interface is used to define a structure for filtering
+ * items based on their price range.
+ */
+export interface IPriceFilter {
+    key: ENUM_FILTER_KEYS.PRICE | 'price';
+    values: {
+        min?: number | string;
+        max?: number | string;
+    };
+}
+/**
+ * Interface representing a filter based on availability.
+ *
+ * @interface IAvailabilityFilter
+ */
+export interface IAvailabilityFilter {
+    key: ENUM_FILTER_KEYS.AVAILABILITY | 'availability';
+    values: ENUM_AVAILABILITY_VALUE | keyof typeof ENUM_AVAILABILITY_VALUE;
+}
+/**
+ * Interface representing a Fulfillment Filter used in search or sorting operations.
+ */
+export interface IFulfillmentFilter {
+    key: ENUM_FILTER_KEYS.FULFILLMENT | 'fulfillment';
+    values: [ENUM_MODALITIES];
+}
+/**
+ * Interface representing an engraving filter.
+ *
+ * This interface is used to define the properties for filtering items
+ * based on engraving criteria.
+ *
+ * Properties:
+ *
+ * - key: Indicates that the filter criteria is related to engraving.
+ *        It can either be the ENUM_FILTER_KEYS.ENGRAVING enum value or the string 'engraving'.
+ *
+ * - values: Specifies the possible engraving values to filter by.
+ *           It can either be from the ENUM_ENGRAVING enum or a key from the ENUM_ENGRAVING enum.
+ */
+export interface IEngravingFilter {
+    key: ENUM_FILTER_KEYS.ENGRAVING | 'engraving';
+    values: ENUM_ENGRAVING | keyof typeof ENUM_ENGRAVING;
+}
+/**
+ * Represents a filter interface for defining key-value pairs used in filtering operations.
+ *
+ * @type {IFilter} IFilter
+ */
+export interface IFilter {
+    key: Omit<ENUM_FILTER_KEYS, ENUM_FILTER_KEYS.CATEGORIES | ENUM_FILTER_KEYS.PRICE | ENUM_FILTER_KEYS.AVAILABILITY | ENUM_FILTER_KEYS.ENGRAVING | ENUM_FILTER_KEYS.FULFILLMENT>;
+    values: string | string[] | number | number[];
+}
+/**
+ * Interface representing the parameters used for catalog search and navigation.
+ */
+export interface ICatalogParams extends ILocBase {
+    search?: string;
+    pageToken?: string;
+    entity?: string;
+    page?: number;
+    perPage?: number;
+    visitorId?: string;
+    orderBy?: ENUM_ORDER_BY;
+    orderDirection?: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE;
+    filters?: Array<ICategoryFilter | IPriceFilter | IAvailabilityFilter | IFulfillmentFilter | IEngravingFilter | IFilter>;
+}
+/**
+ * ICatalog interface represents a structured collection of retailers, products, and navigation schema.
+ */
+export interface ICatalog {
+    retailers?: IRetailer[] | Array<Record<string, any>>;
+    products?: IProduct[] | Array<Record<string, any>>;
+    navigation?: INavigationSchema;
+}
+/**
+ * IFilterValue interface represents a filterable value typically used in context
+ * with searching or sorting functionalities within an application.
+ * It is designed to hold a specific value and its associated count.
+ */
+export interface IFilterValue {
+    value: LiquidTaxonomy | ENUM_AVAILABILITY_VALUE | string;
+    count: number;
+}
+/**
+ * FacetFilterKeys represents the possible keys that can be used to filter items in a faceted search.
+ * It encompasses a variety of attributes that can be used to refine search results, such as brands,
+ * flavor, region, price, availability, and more.
+ * Each key corresponds to an enumerated value in ENUM_FILTER_KEYS.
+ */
+export type FacetFilterKeys = ENUM_FILTER_KEYS.BRANDS | ENUM_FILTER_KEYS.FLAVOR | ENUM_FILTER_KEYS.REGION | ENUM_FILTER_KEYS.VARIETY | ENUM_FILTER_KEYS.ENGRAVING | ENUM_FILTER_KEYS.PRICE | ENUM_FILTER_KEYS.AVAILABILITY | ENUM_FILTER_KEYS.CATEGORIES | ENUM_FILTER_KEYS.SIZES | ENUM_FILTER_KEYS.COLORS | ENUM_FILTER_KEYS.APPELLATION | ENUM_FILTER_KEYS.COUNTRY | ENUM_FILTER_KEYS.VINTAGE | ENUM_FILTER_KEYS.MATERIALS | ENUM_FILTER_KEYS.TAGS;
+/**
+ * IFilterSchema represents the structure for filtering datasets based on specific criteria.
+ */
+export interface IFilterSchema {
+    bucket: FacetFilterKeys;
+    values: IFilterValue[];
+}
+/**
+ * ICursorSchema represents a schema interface that includes pagination tokens.
+ * This interface defines the structure for handling cursor-based pagination.
+ */
+export interface ICursorSchema {
+    nextPageToken: string;
+    previousPageToken: string;
+}
+/**
+ * Interface representing the schema for navigation data.
+ */
+export interface INavigationSchema {
+    id: string;
+    correctedQuery: string;
+    attributionToken: string;
+    currentPage: number;
+    totalPages: number;
+    totalCount: number;
+    availableOrderBy: ENUM_ORDER_BY[];
+    availableOrderDirection: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE[];
+    cursor: ICursorSchema;
+    filters: IFilterSchema[];
+}
+/**
+ * Represents parameters for availability inquiries.
+ */
+export interface IAvailabilityParams extends ILocBase {
+    upcs?: string[];
+    grouping?: string[];
+    ids?: string[];
+    shouldShowOffHours?: boolean;
+}
+/**
+ * Interface representing the availability response.
+ */
+export interface IAvailabilityResponse {
+    products: IProduct[];
+    retailers: IRetailer[];
+}
+/**
+ * Interface representing attributes related to images of a product.
+ */
+export interface IAttributesImage {
+    backOfBottle: string;
+    frontOfBottle: string;
+    lifestyle: string[];
+}
+/**
+ * The IAttributesAward interface represents the structure of an award's attributes.
+ */
+export interface IAttributesAward {
+    image: string;
+    statement: string;
+    title: string;
+}
+/**
+ * Interface representing attributes of a recipe ingredient.
+ */
+export interface IAttributesRecipeIngredient {
+    name: string;
+    amount: string;
+}
+/**
+ * Interface for defining the attributes of a recipe.
+ */
+export interface IAttributesRecipe {
+    image: string;
+    ingredients: IAttributesRecipeIngredient[];
+    steps: string[];
+    title: string;
+}
+/**
+ * Interface representing the attributes of a video.
+ *
+ * This interface includes properties for storing the video's link, image, and title.
+ */
+export interface IAttributesVideo {
+    link: string;
+    image: string;
+    title: string;
+}
+/**
+ * Interface representing the attributes of a tasting note.
+ */
+export interface IAttributesTastingNote {
+    statement: string;
+    image: string;
+    title: string;
+}
+/**
+ * Interface representing personalization attributes for an item.
+ */
+export interface IAttributesPersonalization {
+    type: string;
+    engravingMaxLines: number;
+    engravingMaxCharsPerLine: number;
+    location: string[];
+    width: number;
+    height: number;
+    image: string;
+    fee: number;
+    availableFrom: Date;
+    availableTo: Date;
+}
+/**
+ * IAttributes interface represents the attributes of a product, including its origin,
+ * ownership type, tags, images, awards, recipes, videos, tasting notes, and personalizations.
+ */
+export interface IAttributes {
+    brandOrigin: string;
+    originStatement: string;
+    ownershipType: string[];
+    tags: string[];
+    images: IAttributesImage;
+    awards: IAttributesAward[];
+    recipes: IAttributesRecipe[];
+    video: IAttributesVideo[];
+    tastingNotes: IAttributesTastingNote[];
+    personalizations: IAttributesPersonalization[];
+}
+/**
+ * Interface representing the types of product fulfillment options.
+ *
+ * Properties:
+ * - shipping: A string representing the shipping fulfillment type.
+ * - onDemand: A string representing the on-demand fulfillment type.
+ */
 export interface IProductFulfillmentTypes {
     shipping: string;
     onDemand: string;
 }
+/**
+ * Represents a product variant in the system.
+ *
+ * This interface holds details about a specific variation of a product, including its
+ * part number, retailer ID, pricing information, and fulfillment options.
+ */
 export interface IProductVariant {
     partNumber: string;
     retailerId: string;
@@ -14,6 +256,9 @@ export interface IProductVariant {
     fulfillments: string[];
     fulfillmentTypes: IProductFulfillmentTypes;
 }
+/**
+ * Represents the engraving details for a product size.
+ */
 export interface IProductSizeEngraving {
     status: boolean;
     validated?: boolean;
@@ -22,12 +267,26 @@ export interface IProductSizeEngraving {
     fee: number;
     location: string;
 }
+/**
+ * Interface representing attributes related to the size of a product.
+ *
+ * @property {IProductSizeEngraving} [engraving] - Optional engraving details for the product size.
+ */
 export interface IProductSizeAttributes {
     engraving?: IProductSizeEngraving;
 }
+/**
+ * Represents the size details of a product in an inventory system.
+ *
+ * @interface IProductSize
+ */
 export interface IProductSize {
+    id: string;
+    salsifyPid?: string;
     upc: string;
     size: string;
+    volume: string;
+    uom: string;
     image: string;
     pack: boolean;
     packDesc: string;
@@ -37,25 +296,25 @@ export interface IProductSize {
     modalities?: ENUM_MODALITIES;
     variants: IProductVariant[];
 }
+/**
+ * Represents a product with various attributes and details.
+ */
 export interface IProduct {
+    id?: string;
     name: string;
     brand: string;
     catPath: string;
     category: string;
     classification: string;
     type: string;
-    size?: string;
-    modalities?: ENUM_MODALITIES;
+    salsifyGrouping?: string;
     subType: string;
     region: string;
     country: string;
     material: string;
     abv: string;
+    proof: string;
     age: string;
-    pack?: boolean;
-    packDesc?: string;
-    container?: string;
-    containerType?: string;
     color: string;
     flavor: string;
     variety: string;
@@ -64,6 +323,7 @@ export interface IProduct {
     description: string;
     htmlDescription: string;
     tastingNotes: string;
-    images: string[];
+    images: string[] | Array<Record<string, any>>;
     sizes: IProductSize[];
+    attributes?: Partial<IAttributes>;
 }

package/dist/types/interfaces/checkout.interface.d.ts

@@ -1,118 +1,333 @@
 import type { ICoreParams } from '../types';
-import type { ILoc } from './address.interface';
-import type { ICartAttributesAmounts, ICartItem, ICartRetailer } from './cart.interface';
+import type { IAddress } from './address.interface';
+import type { ICartItemAttributes } from './cart.interface';
+import type { IRetailerExpectation } from './retailer.interface';
 /**
  * Represents a recipient of a checkout process.
  *
- * An instance of the ICheckoutRecipient interface contains
- * information about the recipient, including their
- * first name, last name, email address, phone number, birthdate,
- * and an optional flag indicating if age verification is required.
- *
- * The ICheckoutRecipient interface is intended to be used in checkout
- * processes where the recipient's information is required.
+ * Contains recipient's information such as name, contact details, and
+ * an optional flag for age verification.
  *
  * @interface
  * @public
+ * @deprecated Use ICheckoutCustomer interface instead.
+ * ICheckoutRecipient will be removed in a future version.
  */
 export interface ICheckoutRecipient {
-    firstName: string;
-    lastName: string;
-    email: string;
-    phone: string;
-    birthDate: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    birthDate?: string;
     hasAgeVerify?: boolean;
 }
+/**
+ * Represents a traditional billing address structure.
+ *
+ * @interface
+ * @public
+ * @deprecated Use ICheckoutBillingAddress instead for better integration with customer data.
+ */
+export interface IBillingAddress {
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    one?: string;
+    two?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+}
+/**
+ * Represents a customer in a checkout process.
+ *
+ * Contains information about the customer, including identification,
+ * contact details, personal information, and timestamps for profile management.
+ *
+ * @interface
+ * @public
+ */
+export interface ICheckoutCustomer {
+    id?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    phone?: string;
+    profileImage?: string;
+    birthDate?: string;
+    /**
+     * @deprecated - Moved to ICheckoutPrepareParams
+     * @type {ICheckoutPrepareParams}
+     */
+    hasAgeVerify?: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Represents the base address information for a checkout process.
+ *
+ * @interface
+ */
+interface ICheckoutBaseAddress {
+    id?: string;
+    one?: string;
+    two?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+}
+/**
+ * Represents the billing address in a checkout process.
+ *
+ * Combines base address information with customer details.
+ *
+ * @type
+ */
+export type ICheckoutBillingAddress = ICheckoutBaseAddress & Omit<ICheckoutCustomer, 'birthDate' | 'id' | 'createdAt' | 'hasAgeVerify' | 'updatedAt' | 'profileImage'>;
 /**
  * Represents the recipient information for gift options during checkout.
+ *
+ * @interface
  */
 export interface ICheckoutGiftOptionsRecipient {
-    name: string;
-    email: string;
-    phone: string;
+    name?: string;
+    email?: string;
+    phone?: string;
 }
 /**
- * Interface representing the gift options for a checkout process.
+ * Represents the gift options for a checkout process.
+ *
+ * @interface
  */
 export interface ICheckoutGiftOptions {
-    message: string;
-    recipient: ICheckoutGiftOptionsRecipient;
+    message?: string;
+    recipient?: ICheckoutGiftOptionsRecipient;
 }
 /**
  * Represents the marketing preferences for a checkout.
  *
- * @interface ICheckoutMarketingPreferences
- * @property {boolean} canEmail - Indicates whether the user allows email marketing.
- * @property {boolean} canSms - Indicates whether the user allows SMS marketing.
+ * @interface
  */
 export interface ICheckoutMarketingPreferences {
-    canEmail: boolean;
-    canSms: boolean;
+    canEmail?: boolean;
+    canSms?: boolean;
 }
 /**
  * Represents the delivery tip for a checkout.
  *
- * @interface ICheckoutDeliveryTip
- * @property {string} fulfillmentId - The ID of the fulfillment.
- * @property {number} tip - The amount of the tip.
+ * @interface
  */
 export interface ICheckoutDeliveryTip {
     fulfillmentId: string;
     tip: number;
 }
 /**
- * This interface defines the parameters required for preparing a checkout.
- * It extends the ICoreParams interface.
+ * Defines the parameters required for preparing a checkout.
+ *
+ * Extends the ICoreParams interface.
  *
- * @interface ICheckoutPrepareParams
- * @extends {ICoreParams}
+ * @interface
  */
 export interface ICheckoutPrepareParams extends ICoreParams {
     cartId: string;
-    recipient: ICheckoutRecipient;
-    billingAddress?: ILoc;
-    hasSubstitutionPolicy: boolean;
-    isGift: boolean;
-    billingSameAsShipping: boolean;
-    giftOptions: ICheckoutGiftOptions;
-    marketingPreferences: ICheckoutMarketingPreferences;
+    customer?: ICheckoutCustomer | string;
+    /**
+     * @deprecated Use customer property instead. Recipient will be removed in a future version.
+     */
+    recipient?: ICheckoutRecipient;
+    hasAgeVerify?: boolean;
+    shippingAddressTwo?: string;
+    /**
+     * Billing address information supporting both new and legacy formats.
+     * Recommended to use ICheckoutBillingAddress format for new implementations.
+     */
+    billingAddress?: ICheckoutBillingAddress | IBillingAddress;
+    hasSubstitutionPolicy?: boolean;
+    isGift?: boolean;
+    billingSameAsShipping?: boolean;
+    giftOptions?: ICheckoutGiftOptions;
+    marketingPreferences?: ICheckoutMarketingPreferences;
     deliveryTips?: ICheckoutDeliveryTip[];
+    acceptedAccountCreation?: boolean;
+    scheduledDelivery?: string;
+    payment?: string;
+}
+/**
+ * Represents total amounts and discounts for a checkout process.
+ *
+ * @interface
+ */
+export interface ICheckoutTotalAmountsDiscounts {
+    products: number;
+    delivery: number;
+    shipping: number;
+    engraving: number;
+    service: number;
+}
+/**
+ * Represents various tax-related amounts in a checkout total.
+ *
+ * @interface
+ */
+export interface ICheckoutTotalAmountsTaxes {
+    bag: number;
+    bottleDeposits: number;
+    retailDelivery: number;
+    products: number;
+    delivery: number;
+    shipping: number;
+}
+/**
+ * Represents the details of the total amounts in the checkout process.
+ *
+ * @interface
+ */
+export interface ICheckoutTotalAmountsDetails {
+    taxes: ICheckoutTotalAmountsTaxes;
+    discounts: ICheckoutTotalAmountsDiscounts;
+}
+/**
+ * Represents the total amounts in a checkout process, including fees, discounts, and the final total.
+ *
+ * @interface
+ */
+export interface ICheckoutTotalAmounts {
+    subtotal: number;
+    engraving: number;
+    service: number;
+    shipping: number;
+    delivery: number;
+    platform: number;
+    discounts: number;
+    giftCards: number;
+    tax: number;
+    tip: number;
+    total: number;
+    details: ICheckoutTotalAmountsDetails;
+}
+/**
+ * Represents a fulfillment in the checkout process.
+ *
+ * Extends ICheckoutTotalAmounts.
+ *
+ * @interface
+ */
+export interface ICheckoutFulfillment extends ICheckoutTotalAmounts {
+    id: string;
+    scheduledFor?: string | Date;
+    type: 'shipping' | 'onDemand';
+    expectation: IRetailerExpectation;
+    items: string[];
+}
+/**
+ * Represents a retailer in the checkout process.
+ *
+ * Extends ICheckoutTotalAmounts.
+ *
+ * @interface
+ */
+export interface ICheckoutRetailer extends ICheckoutTotalAmounts {
+    id: string;
+    name: string;
+    address?: IAddress;
+    fulfillments: ICheckoutFulfillment[];
+}
+/**
+ * Represents an item in the checkout process.
+ *
+ * Contains detailed information about a product in the cart, including identifiers,
+ * product details, pricing, quantity, and additional attributes.
+ *
+ * @interface
+ */
+export interface ICheckoutItem {
+    variantId: string;
+    cartItemId: string;
+    liquidId: string;
+    retailerId: string;
+    fulfillmentId: string;
+    salsifyPid?: string;
+    salsifyGrouping?: string;
+    name: string;
+    catPath: string;
+    volume: string;
+    uom: string;
+    proof: string;
+    abv: string;
+    containerType: string;
+    container: string;
+    size: string;
+    pack: boolean;
+    packDesc: string;
+    mainImage: string;
+    /**
+     * @deprecated - use mainImage
+     */
+    image: string;
+    brand: string;
+    partNumber: string;
+    upc: string;
+    price: number;
+    unitPrice: number;
+    quantity: number;
+    tax: number;
+    unitTax: number;
+    bottleDeposits: number;
+    attributes: ICartItemAttributes;
 }
 /**
  * Represents a response object for preparing a checkout process.
  *
- * @interface ICheckoutPrepareResponse
+ * @interface
  */
 export interface ICheckoutPrepareResponse {
     token: string;
+    cartId: string;
+    customer: ICheckoutCustomer;
     hasAgeVerify: boolean;
-    marketingPreferences: ICheckoutMarketingPreferences;
     hasSubstitutionPolicy: boolean;
     isGift: boolean;
     createdAt: string;
     updatedAt: string;
     billingSameAsShipping: boolean;
+    acceptedAccountCreation?: boolean;
     giftOptions: ICheckoutGiftOptions;
-    shippingAddress: ILoc;
-    billingAddress: ILoc;
-    items: ICartItem[];
-    amounts: ICartAttributesAmounts;
-    retailers: ICartRetailer[];
-    cartId: string;
+    marketingPreferences: ICheckoutMarketingPreferences;
+    shippingAddress: IAddress;
+    /**
+     * Billing address information supporting both new and legacy formats.
+     * Recommended to use ICheckoutBillingAddress format for new implementations.
+     */
+    billingAddress: ICheckoutBillingAddress | IBillingAddress;
+    amounts: ICheckoutTotalAmounts;
+    items: ICheckoutItem[];
+    retailers: ICheckoutRetailer[];
+    payment?: string;
 }
 /**
  * Represents the parameters required for completing a checkout process.
+ *
+ * Extends ICoreParams.
+ *
  * @interface
- * @extends ICoreParams
  */
 export interface ICheckoutCompleteParams extends ICoreParams {
     token: string;
     payment: string;
 }
 /**
- * Interface representing the response object after completing the checkout process.
+ * Represents the response object after completing the checkout process.
+ *
  * @interface
  */
 export interface ICheckoutCompleteResponse {
-    order: string;
+    order: {
+        number: string;
+        referenceId: string;
+    };
 }
+export {};