@liquidcommerce/cloud-sdk 1.0.1

package/dist/types/core/catalog-helper.service.d.ts

@@ -0,0 +1,113 @@
+import type { ICatalogParams } from '../interfaces/catalog.service.interface';
+import type { IAvailabilityParams } from '../services/catalog.service';
+import type { LocationHelperService } from './location-helper.service';
+/**
+ * The `CatalogHelperService` class provides utility methods for validating and normalizing
+ * input parameters for availability and catalog search.
+ */
+export declare class CatalogHelperService {
+    private locationServiceHelper;
+    private readonly taxonomyValues;
+    constructor(locationServiceHelper: LocationHelperService);
+    /**
+     * Validates and normalizes the input parameters for availability.
+     *
+     * @param {IAvailabilityParams} params - The availability parameters to be validated and normalized.
+     * @returns {IAvailabilityParams} - The validated and normalized availability parameters.
+     */
+    validateAndNormalizeParams(params: IAvailabilityParams): IAvailabilityParams;
+    /**
+     * Validates and normalizes the search parameters for catalog search.
+     *
+     * @param {ICatalogParams} params - The search parameters to be validated and normalized.
+     * @returns {ICatalogParams} - The validated and normalized search parameters.
+     */
+    validateAndNormalizeSearchParams(params: ICatalogParams): ICatalogParams & {
+        error?: string;
+    };
+    /**
+     * Validates an array of UPCs.
+     *
+     * @param {string[]} upcs - The array of UPCs to validate.
+     * @throws {Error} If upcs is not an array or is an empty array.
+     * @throws {Error} If any UPC in the array is not a non-empty string.
+     */
+    private validateUPCs;
+    /**
+     * Validates the orderBy parameter and adds any validation errors to the errors array.
+     *
+     * @param orderBy - The orderBy value to validate.
+     * @param errors - The array to store any validation errors.
+     *
+     * @return void
+     */
+    private validateOrderBy;
+    /**
+     * Validates the order direction.
+     *
+     * @param {ENUM_NAVIGATION_ORDER_DIRECTION_TYPE | undefined} orderDirection - The order direction to be validated.
+     * @param {string[]} errors - An array to store error messages.
+     *
+     * @return {void} This method does not return any value.
+     */
+    private validateOrderDirection;
+    /**
+     * Validates the filters for the catalog.
+     *
+     * @param filters - The filters to be validated.
+     * @param errors - An array to store any validation errors.
+     * @returns void
+     */
+    private validateFilters;
+    /**
+     * Validates the availability filter value.
+     *
+     * @param {ENUM_AVAILABILITY_VALUE} value - The value to be validated.
+     * @param {string[]} errors - The array to store any validation errors.
+     *
+     * @return {void}
+     */
+    private validateAvailabilityFilter;
+    /**
+     * Validates the given array filter.
+     *
+     * @param values - The array to be validated.
+     * @param maxLength - The maximum number of values allowed in the array filter.
+     * @param filterName - The name of the filter being validated.
+     * @param errors - An array to store any validation errors.
+     *
+     * @return - This method does not return anything.
+     *
+     * @remarks
+     * This method checks if the given values parameter is an array. If it is not, an error message is added
+     * to the errors array indicating that the filter must be an array.
+     *
+     * If the array has a length that exceeds the maxLength parameter, an error message is added to the errors
+     * array indicating that the filter can have a maximum of maxLength values.
+     */
+    private validateArrayFilter;
+    /**
+     * Validates the categories filter values.
+     *
+     * @param {LiquidTaxonomy[]} values - The array of category values to validate.
+     * @param {string[]} errors - An array to store any validation errors.
+     *
+     * @return {void} - This method does not return a value.
+     */
+    private validateCategoriesFilter;
+    /**
+     * Validates the pagination options.
+     *
+     * @param {number | undefined} page - The current page number.
+     * @param {number | undefined} perPage - The number of items per page.
+     * @param {string[]} errors - An array to store any validation errors.
+     *
+     * @return {void}
+     *
+     * @description
+     * This method validates the provided pagination options and adds any validation errors to the `errors` array.
+     * The `page` argument must be a non-negative number, and the `perPage` argument must be a positive number.
+     * If either argument fails validation, an error message is pushed to the `errors` array.
+     */
+    private validatePagination;
+}

package/dist/types/core/checkout-helper.service.d.ts

@@ -0,0 +1,76 @@
+import type { ICheckoutCompleteParams, ICheckoutPrepareParams } from '../interfaces/checkout.interface';
+import type { LocationHelperService } from './location-helper.service';
+/**
+ * CheckoutHelperService is a helper class that provides methods
+ * for validating and normalizing checkout parameters.
+ */
+export declare class CheckoutHelperService {
+    private locationHelperService;
+    constructor(locationHelperService: LocationHelperService);
+    /**
+     * Validates and normalizes prepare parameters.
+     *
+     * @param {ICheckoutPrepareParams} params - The prepare parameters to be validated and normalized.
+     *
+     * @return {ICheckoutPrepareParams} - The normalized prepare parameters.
+     *
+     * @throws {Error} - Invalid cartId if cartId is missing or not a string.
+     */
+    validateAndNormalizePrepareParams(params: ICheckoutPrepareParams): ICheckoutPrepareParams;
+    /**
+     * Validates and normalizes the complete checkout parameters.
+     *
+     * @param {ICheckoutCompleteParams} params - The complete checkout parameters.
+     *
+     * @throws {Error} If the token is missing or not a string.
+     * @throws {Error} If the payment token is missing or not a string.
+     *
+     * @return {ICheckoutCompleteParams} The validated and normalized complete checkout parameters.
+     */
+    validateAndNormalizeCompleteParams(params: ICheckoutCompleteParams): ICheckoutCompleteParams;
+    /**
+     * Validates the recipient object.
+     *
+     * @param {ICheckoutPrepareParams['recipient']} recipient - The recipient object to be validated.
+     * @throws {Error} If the recipient object is invalid.
+     * @returns {void}
+     */
+    private validateRecipient;
+    /**
+     * Validates the given address object.
+     * @param {IAddress} address - The address object to validate.
+     * @throws {Error} If the address is invalid or any required field is missing or not a string.
+     * @returns {void}
+     */
+    private validateAddress;
+    /**
+     * Validates the giftOptions parameter.
+     *
+     * @param {ICheckoutPrepareParams['giftOptions']} giftOptions - The giftOptions to be validated.
+     *
+     * @throws {Error} If the giftOptions parameter is not provided or is not an object.
+     * @throws {Error} If the gift message is provided but is not a string.
+     * @throws {Error} If the gift recipient's name, phone, or email is provided but is not a string.
+     *
+     * @returns {void}
+     */
+    private validateGiftOptions;
+    /**
+     * Validates the given marketing preferences.
+     *
+     * @param {ICheckoutPrepareParams['marketingPreferences']} preferences - The marketing preferences to validate.
+     *
+     * @throws {Error} The error thrown if the marketing preferences are invalid.
+     */
+    private validateMarketingPreferences;
+    /**
+     * Validates the delivery tips array.
+     *
+     * @param {ICheckoutPrepareParams['deliveryTips']} tips - An array of delivery tips to validate.
+     * @throws {Error} If the deliveryTips parameter is not an array.
+     * @throws {Error} If the fulfillmentId property of any delivery tip is invalid.
+     * @throws {Error} If the tip amount of any delivery tip is invalid.
+     * @return {void}
+     */
+    private validateDeliveryTips;
+}

package/dist/types/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from './authenticated.service';
+export * from './cart-helper.service';
+export * from './catalog-helper.service';
+export * from './checkout-helper.service';
+export * from './location-helper.service';
+export * from './payment-provider.service';
+export * from './singleton.service';

package/dist/types/core/location-helper.service.d.ts

@@ -0,0 +1,47 @@
+import type { ILoc } from '../interfaces/address.interface';
+/**
+ * The LocationHelperService class provides methods to validate and normalize location objects.
+ */
+export declare class LocationHelperService {
+    /**
+     * Validates and normalizes a location object.
+     * @param {ILoc} loc - The location object to validate and normalize.
+     * @throws {Error} - If the loc argument is not a valid object or if
+     * it doesn't contain either coords or address.
+     */
+    validateAndNormalizeLocation(loc: ILoc): void;
+    /**
+     * Validates coordinates to ensure they are within valid range.
+     *
+     * @param coords - The object containing the latitude and longitude values to be validated.
+     * @param coords.lat - The latitude value to be validated.
+     * @param coords.long - The longitude value to be validated.
+     *
+     * @throws {Error} - Throws an error if the coordinates are not valid numbers or are out of range.
+     *
+     * @return {void}
+     */
+    private validateCoordinates;
+    /**
+     * Validates and normalizes an address object.
+     *
+     * @param {any} address - The address object to validate and normalize.
+     *
+     * @throws {Error} If the state is missing or not a string.
+     * @throws {Error} If the city is missing or not a string.
+     * @throws {Error} If the ZIP code is missing or not a string.
+     *
+     * @return {void}
+     */
+    private validateAndNormalizeAddress;
+    /**
+     * Normalize the state value to its corresponding code or name.
+     * The state can be either a state code or state name.
+     *
+     * @param {STATES_CODE | STATES_NAME} state - The state value to normalize.
+     * @return {string} - The normalized state value, which is the corresponding code or name.
+     *
+     * @throws {Error} - If the state value is invalid.
+     */
+    private normalizeState;
+}

package/dist/types/core/payment-provider.service.d.ts

@@ -0,0 +1,91 @@
+import type { ILiquidPaymentConfig, ILiquidPaymentError, ILiquidPaymentToken, IPaymentElementEventMap, IPaymentProvider } from '../interfaces/payment.interface';
+/**
+ * Represents a service for handling payment processing using the Stripe API.
+ * Implements the IPaymentProvider interface.
+ */
+export declare class PaymentProviderService implements IPaymentProvider {
+    private stripe;
+    private elements;
+    private paymentElement;
+    private readonly events;
+    private readonly eventsErrorMsg;
+    /**
+     * Mounts the Stripe payment element to the specified container element on the page.
+     *
+     * @param {ILiquidPaymentConfig} config - The configuration object for the payment element.
+     *
+     * @throws {Error} If the container element with the specified ID is not found.
+     * @throws {Error} If there is an error loading or initializing the Stripe API.
+     *
+     * @return {Promise<void>} A promise that resolves when the payment element is successfully mounted.
+     */
+    mount(config: ILiquidPaymentConfig): Promise<void>;
+    /**
+     * Generate a payment token for a liquid payment.
+     *
+     * This method generates a payment token using the Stripe API. The payment token represents the payment information provided by the user.
+     * The method first checks if the Stripe instance and the Stripe Elements instance have been initialized. If not, it returns an error indicating that the payment form has not been initialized.
+     *
+     * Next, the method submits the payment form using the `submit()` method of the Stripe Elements instance. If there is an error during the submission, it returns a validation error indicating the error message and code.
+     *
+     * After successful submission, the method creates a payment method using the `createPaymentMethod()` method of the Stripe instance, passing the Stripe Elements instance as a parameter. If there is an error during the creation of the payment method, it returns the appropriate error containing the error message, code, and parameter (if applicable).
+     *
+     * If the payment method is successfully created, the method returns the payment information in the form of an object containing the payment method's ID, type, and card details (if available), as well as the creation timestamp. The card details include the card brand, country, expiration month, expiration year, last 4 digits, and funding source.
+     *
+     * If none of the above conditions are met, it returns an error indicating that the payment token generation has failed.
+     *
+     * @returns A Promise that resolves to either a LiquidPaymentToken object or a LiquidPaymentError object.
+     *
+     * The LiquidPaymentToken object has the following properties:
+     * - id (string): The ID of the payment method.
+     * - type (string): The type of the payment method.
+     * - card (object): An optional object containing the card details.
+     *    - brand (string): The brand of the card.
+     *    - country (string): The country of the card.
+     *    - expMonth (number): The expiration month of the card.
+     *    - expYear (number): The expiration year of the card.
+     *    - last4 (string): The last 4 digits of the card.
+     *    - funding (string): The funding source of the card.
+     * - created (number): The timestamp indicating when the payment method was created.
+     *
+     * The LiquidPaymentError object has the following properties:
+     * - type (string): The type of the error (either 'client_error', 'validation_error', or 'api_error').
+     * - message (string): The error message.
+     * - code (string): The error code (if applicable).
+     * - param (string): The error parameter (if applicable).
+     */
+    generateToken(): Promise<ILiquidPaymentToken | ILiquidPaymentError>;
+    /**
+     * Subscribes to a specific event on the payment element.
+     *
+     * @param eventType - The type of event to subscribe to.
+     * @param handler - The function to be called when the event is triggered.
+     * @throws {Error} - If the payment element has not been initialized.
+     * @return {void}
+     */
+    subscribe<K extends keyof IPaymentElementEventMap>(eventType: K, handler: (event: IPaymentElementEventMap[K]) => void): void;
+    /**
+     * Unsubscribes an event handler from a specific event type in the payment element.
+     *
+     * @param eventType - The type of event to unsubscribe from.
+     * @param handler - (Optional) The event handler function to unsubscribe.
+     * @throws {Error} - Thrown if the payment element has not been initialized.
+     * @return {void}
+     */
+    unsubscribe<K extends keyof IPaymentElementEventMap>(eventType: K, handler?: (event: IPaymentElementEventMap[K]) => void): void;
+    /**
+     * Maps the appearance options from the provided LiquidPaymentConfig object
+     * to the corresponding StripeElementsOptions object.
+     *
+     * @param appearance - The appearance options from the LiquidPaymentConfig object.
+     * @returns The appearance options for the StripeElementsOptions object.
+     */
+    private mapAppearance;
+    /**
+     * Maps the given options to Stripe payment element options.
+     *
+     * @param {ILiquidPaymentElementOptions} options - The options to be mapped.
+     * @return {StripePaymentElementOptions} - The mapped Stripe payment element options.
+     */
+    private mapElementOptions;
+}

package/dist/types/core/singleton.service.d.ts

@@ -0,0 +1,138 @@
+import type { ILiquidCommerceClient, ILiquidCommerceClientConstructor } from '../interfaces/liquid-commerce-client.interface';
+import { AddressService } from '../services/address.service';
+import { CartService } from '../services/cart.service';
+import { CatalogService } from '../services/catalog.service';
+import { CheckoutService } from '../services/checkout.service';
+import { PaymentService } from '../services/payment.service';
+import { UserService } from '../services/user.service';
+import type { ILiquidCommerceConfig } from '../types';
+import { AuthenticatedService } from './authenticated.service';
+import { CartHelperService } from './cart-helper.service';
+import { CatalogHelperService } from './catalog-helper.service';
+import { CheckoutHelperService } from './checkout-helper.service';
+import { LocationHelperService } from './location-helper.service';
+import { PaymentProviderService } from './payment-provider.service';
+/**
+ * The SingletonManager class is responsible for managing singleton instances of various services.
+ * It provides methods for retrieving or creating instances of these services based on unique keys.
+ */
+export declare class SingletonManager {
+    private static instance;
+    private services;
+    private liquidCommerceClientConstructor;
+    static getInstance(): SingletonManager;
+    /**
+     * Sets the constructor for the Liquid Commerce Client.
+     *
+     * @param {ILiquidCommerceClientConstructor} constructor - The constructor function for the Liquid Commerce Client.
+     *
+     * @return {void}
+     */
+    setLiquidCommerceClientConstructor(constructor: ILiquidCommerceClientConstructor): void;
+    /**
+     * Retrieves or creates an instance of the LiquidCommerceClient.
+     *
+     * @param {string} apiKey - The API key for authentication.
+     * @param {ILiquidCommerceConfig} config - The configuration object.
+     * @returns {Promise<ILiquidCommerceClient>} - A promise that resolves to an instance of ILiquidCommerceClient.
+     * @throws {Error} - If the LiquidCommerceClient constructor is not set.
+     */
+    getLiquidCommerceClient(apiKey: string, config: ILiquidCommerceConfig): Promise<ILiquidCommerceClient>;
+    /**
+     * Returns an instance of a service based on the given key and ServiceClass.
+     * If the service does not exist, it creates a new instance using the ServiceClass and optional arguments.
+     *
+     * @param {string} key - The key to identify the service.
+     * @param {ServiceFactory<T>} ServiceClass - The class or factory function for the service.
+     * @param {...any[]} args - Optional arguments to be passed to the constructor or factory function.
+     * @return {T} - The instance of the service.
+     */
+    private getOrCreateService;
+    /**
+     * Returns an authenticated client for the given configuration.
+     *
+     * @param config - The configuration object containing the API key and base URL.
+     * @param config.apiKey - The API key for authentication.
+     * @param config.baseURL - The base URL for API requests.
+     *
+     * @return The authenticated service object.
+     */
+    getAuthenticatedClient(config: {
+        apiKey: string;
+        baseURL: string;
+    }): AuthenticatedService;
+    /**
+     * Retrieves the instance of the LocationHelperService.
+     * If the service does not yet exist, it will be created.
+     *
+     * @return {LocationHelperService} The LocationHelperService instance.
+     */
+    getLocationHelperService(): LocationHelperService;
+    /**
+     * Gets the AddressService instance associated with the provided AuthenticatedService.
+     *
+     * @param authenticatedClient - The authenticated client used to retrieve the AddressService instance.
+     * @return The AddressService instance associated with the authenticated client.
+     */
+    getAddressService(authenticatedClient: AuthenticatedService): AddressService;
+    /**
+     * Retrieves the CatalogHelperService instance.
+     *
+     * @return {CatalogHelperService} The CatalogHelperService instance.
+     */
+    getCatalogHelperService(): CatalogHelperService;
+    /**
+     * Retrieves the CatalogService for the provided authenticated client.
+     *
+     * @param authenticatedClient The authenticated client.
+     *
+     * @return The CatalogService instance created or retrieved.
+     */
+    getCatalogService(authenticatedClient: AuthenticatedService): CatalogService;
+    /**
+     * Retrieves the CartHelperService instance.
+     *
+     * @return {CartHelperService} The CartHelperService instance.
+     */
+    getCartHelperService(): CartHelperService;
+    /**
+     * Retrieves the CartService instance associated with the given authenticated client.
+     *
+     * @param authenticatedClient - The authenticated client for which to retrieve the CartService.
+     * @return The CartService instance associated with the authenticated client.
+     */
+    getCartService(authenticatedClient: AuthenticatedService): CartService;
+    /**
+     * Retrieves the UserService for the provided authenticated client.
+     *
+     * @param authenticatedClient - The authenticated client for which to retrieve the UserService.
+     * @return The UserService instance.
+     */
+    getUserService(authenticatedClient: AuthenticatedService): UserService;
+    /**
+     * Returns the instance of the `PaymentProviderService` class.
+     * This method uses the `getOrCreateService` method internally to obtain the instance.
+     *
+     * @return {PaymentProviderService} The instance of the `PaymentProviderService` class.
+     */
+    getPaymentProviderService(): PaymentProviderService;
+    /**
+     * Retrieves the payment service by calling the getOrCreateService method.
+     *
+     * @return {PaymentService} The payment service object.
+     */
+    getPaymentService(): PaymentService;
+    /**
+     * Retrieves the CheckoutHelperService instance.
+     *
+     * @return {CheckoutHelperService} The CheckoutHelperService instance.
+     */
+    getCheckoutHelperService(): CheckoutHelperService;
+    /**
+     * Retrieves the CheckoutService instance for the provided authenticated client.
+     *
+     * @param authenticatedClient - The authenticated client object.
+     * @return The CheckoutService instance.
+     */
+    getCheckoutService(authenticatedClient: AuthenticatedService): CheckoutService;
+}