@liquidcommerce/cloud-sdk 1.2.0 → 1.4.0

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

@@ -0,0 +1,8 @@
+export * from './address.interface';
+export * from './cart.interface';
+export * from './catalog.interface';
+export * from './checkout.interface';
+export * from './liquid-commerce-client.interface';
+export * from './payment.interface';
+export * from './retailer.interface';
+export * from './user.interface';

package/dist/types/interfaces/liquid-commerce-client.interface.d.ts

@@ -1,11 +1,10 @@
-import type { IAddressAutocompleteParams, IAddressAutocompleteResult, IAddressDetailsParams, IAddressDetailsResult } from '../services/address.service';
-import type { IAvailabilityParams, IAvailabilityResponse } from '../services/catalog.service';
 import type { IApiResponseWithData, IApiResponseWithoutData, ILiquidCommerceConfig } from '../types';
+import type { IAddressAutocompleteParams, IAddressAutocompleteResult, IAddressDetailsParams, IAddressDetailsResult } from './address.interface';
 import type { ICart, ICartUpdateParams } from './cart.interface';
-import type { ICatalog, ICatalogParams } from './catalog.service.interface';
+import type { IAvailabilityParams, IAvailabilityResponse, ICatalog, ICatalogParams } from './catalog.interface';
 import type { ICheckoutCompleteParams, ICheckoutCompleteResponse, ICheckoutPrepareParams, ICheckoutPrepareResponse } from './checkout.interface';
 import type { ILiquidPaymentConfig, ILiquidPaymentToken, IPaymentElementEventMap } from './payment.interface';
-import type { IPurgeResponse, IUser, IUserAddress, IUserAddressParams, IUserSessionParams } from './user.interface';
+import type { BaseUser, IPurgeResponse, IUser, IUserAddress, IUserAddressParams, IUserPayment, IUserPaymentAddParams, IUserPaymentUpdateParams, IUserSessionParams } from './user.interface';
 /**
  * Interface representing the LiquidCommerce client.
  * Provides access to methods related to addresses, catalogs, carts, and initialization.
@@ -37,14 +36,18 @@ export interface ILiquidCommerceClient {
      */
     cart: ICartMethod;
     /**
-     * Represents a payment method for processing a payment.
-     * @type {IPaymentMethod} - The interface representing the payment method.
+     * Provides methods for managing user data and authentication.
+     * See {@link IUserMethod} for more details on the available methods.
+     */
+    user: IUserMethod;
+    /**
+     * Provides methods for processing payments.
+     * See {@link IPaymentMethod} for more details on the available methods.
      */
     payment: IPaymentMethod;
     /**
-     * Represents a method of checking out items in a shopping system.
-     *
-     * @type {ICheckoutMethod} - The interface representing the checkout method.
+     * Provides methods for managing the checkout process.
+     * See {@link ICheckoutMethod} for more details on the available methods.
      */
     checkout: ICheckoutMethod;
 }
@@ -318,6 +321,28 @@ export interface IUserMethod {
      * @see {@link IUser} for the structure of the user data returned.
      */
     session: (params: IUserSessionParams) => Promise<IApiResponseWithData<IUser>>;
+    /**
+     * Represents a user object without creating a new session.
+     *
+     * @param {string} identifier - The parameters for fetching a user.
+     * @returns {Promise<IApiResponseWithData<BaseUser>>} A Promise that resolves to the API response with user data.
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   // Fetch by user ID
+     *   const userFetched = await liquidCommerce.user.fetch('c1fbd454-a540-4f42-86e9-f87a98bf1812');
+     *   console.log('User fetch response:', userFetched?.data);
+     * } catch (error) {
+     *   console.error('Failed to fetch user data:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the sessions request fails or if authentication is unsuccessful.
+     *
+     * @see {@link BaseUser} for the structure of the user data returned.
+     */
+    fetch: (identifier: string) => Promise<IApiResponseWithData<BaseUser>>;
     /**
      * Purges a user's data from the system.
      *
@@ -344,6 +369,37 @@ export interface IUserMethod {
      * @see {@link IPurgeResponse} for the structure of the user data returned.
      */
     purge: (identifier: string) => Promise<IApiResponseWithData<IPurgeResponse>>;
+    /**
+     * Adds a new address for a user.
+     *
+     * @param {IUserAddressParams} params - The parameters for adding a new address.
+     * @returns {Promise<IApiResponseWithData<IUserAddress>>} A promise that resolves to the API response with the added address data.
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   const newAddress = await liquidCommerce.user.addAddress({
+     *     customerId: 'c1fbd454-a540-4f42-86e9-f87a98bf1812',
+     *     one: '100 Madison St',
+     *     city: 'New York',
+     *     state: 'NY',
+     *     zip: '10004',
+     *     type: 'shipping',
+     *     isDefault: true
+     *   });
+     *
+     *   console.log('Added address:', newAddress?.data);
+     * } catch (error) {
+     *   console.error('Failed to add address:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the add address request fails or if authentication is unsuccessful.
+     *
+     * @see {@link IUserAddressParams} for the structure of the add address request parameters.
+     * @see {@link IUserAddress} for the structure of the user's address data returned.
+     */
+    addAddress: (params: IUserAddressParams) => Promise<IApiResponseWithData<IUserAddress>>;
     /**
      * Updates or creates a new address for a user.
      *
@@ -398,6 +454,86 @@ export interface IUserMethod {
      * @see {@link IPurgeResponse} for the structure of the user's purged data state.
      */
     purgeAddress: (addressId: string) => Promise<IApiResponseWithData<IPurgeResponse>>;
+    /**
+     * Adds a new payment method for a user.
+     *
+     * @param {IUserPaymentAddParams} params - The parameters for adding a new payment method.
+     * @returns {Promise<IApiResponseWithData<IUserPayment>>} A promise that resolves to the API response with the added payment method data.
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   const newPayment = await liquidCommerce.user.addPayment({
+     *     customerId: 'c1fbd454-a540-4f42-86e9-f87a98bf1812',
+     *     paymentMethodId: 'pm_1234567890abcdef',
+     *     isDefault: true
+     *   });
+     *
+     *   console.log('Added payment method:', newPayment?.data);
+     * } catch (error) {
+     *   console.error('Failed to add payment method:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the add payment request fails or if authentication is unsuccessful.
+     *
+     * @see {@link IUserPaymentParams} for the structure of the add payment request parameters.
+     * @see {@link IUserPayment} for the structure of the user's payment method data returned.
+     */
+    addPayment: (params: IUserPaymentAddParams) => Promise<IApiResponseWithData<IUserPayment>>;
+    /**
+     * Updates a payment method for a user.
+     *
+     * @param {IUserPaymentUpdateParams} params - The parameters for updating a payment method.
+     * @returns {Promise<IApiResponseWithData<IUserPayment>>} A promise that resolves to the API response with the updated payment method data.
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   const updatedPayment = await liquidCommerce.user.updatePayment({
+     *     customerId: 'c1fbd454-a540-4f42-86e9-f87a98bf1812',
+     *     paymentMethodId: 'pm_1234567890abcdef',
+     *     isDefault: true
+     *   });
+     *
+     *   console.log('Updated payment method:', updatedPayment?.data);
+     * } catch (error) {
+     *   console.error('Failed to update payment method:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the update payment request fails or if authentication is unsuccessful.
+     *
+     * @see {@link IUserPaymentUpdateParams} for the structure of the update payment request parameters.
+     * @see {@link IUserPayment} for the structure of the user's payment method data returned.
+     */
+    updatePayment: (params: IUserPaymentUpdateParams) => Promise<IApiResponseWithData<IUserPayment>>;
+    /**
+     * Purges a payment method for a user.
+     *
+     * @param {string} customerId - The ID of the customer.
+     * @param {string} paymentId - The ID of the payment method to purge.
+     * @returns {Promise<IApiResponseWithData<IPurgeResponse>>} A promise that resolves to the purge response.
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   const paymentPurgeResponse = await liquidCommerce.user.purgePayment(
+     *     'c1fbd454-a540-4f42-86e9-f87a98bf1812',
+     *     'pm_1234567890abcdef'
+     *   );
+     *
+     *   console.log('Payment method purge response:', paymentPurgeResponse?.data);
+     * } catch (error) {
+     *   console.error('Failed to purge payment method:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the purge payment request fails or if authentication is unsuccessful.
+     *
+     * @see {@link IPurgeResponse} for the structure of the purge response data.
+     */
+    purgePayment: (customerId: string, paymentId: string) => Promise<IApiResponseWithData<IPurgeResponse>>;
 }
 export interface IPaymentMethod {
     /**
@@ -501,6 +637,60 @@ export interface IPaymentMethod {
      * @throws {Error} - Throws an error if the payment element has not been initialized.
      */
     unsubscribe<K extends keyof IPaymentElementEventMap>(eventType: K, handler?: (event: IPaymentElementEventMap[K]) => void): void;
+    /**
+     * Collapses the payment element if it has been initialized.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   liquidCommerce.payment.collapse();
+     *   console.log('Payment element collapsed');
+     * } catch (error) {
+     *   console.error('Failed to collapse payment element:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the payment element has not been initialized.
+     */
+    collapse(): void;
+    /**
+     * Unmounts the payment element from the DOM.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   liquidCommerce.payment.unmount();
+     *   console.log('Payment element unmounted');
+     * } catch (error) {
+     *   console.error('Failed to unmount payment element:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the payment element has not been initialized.
+     */
+    unmount(): void;
+    /**
+     * Destroys the payment element if it has been initialized.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const liquidCommerce = await LiquidCommerce(apiKey, config);
+     *
+     * try {
+     *   liquidCommerce.payment.destroy();
+     *   console.log('Payment element destroyed');
+     * } catch (error) {
+     *   console.error('Failed to destroy payment element:', error);
+     * }
+     *
+     * @throws {Error} - Throws an error if the payment element has not been initialized.
+     */
+    destroy(): void;
 }
 export interface ICheckoutMethod {
     /**

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

@@ -1,8 +1,34 @@
 import type { StripePaymentElementChangeEvent } from '@stripe/stripe-js';
 import type { StripeError } from '@stripe/stripe-js/dist/stripe-js/stripe';
+/**
+ * Represents the options to configure the layout for a liquid payment element.
+ *
+ * @interface
+ * @property {'tabs' | 'accordion' | 'auto'} [layout] - Determines the layout style.
+ *    - 'tabs': Layout will use tabbed navigation.
+ *    - 'accordion': Layout will use accordion-style sections.
+ *    - 'auto': Layout style will be chosen automatically based on context.
+ */
 export interface ILiquidPaymentElementOptions {
     layout?: 'tabs' | 'accordion' | 'auto';
 }
+/**
+ * The configuration interface for Liquid Payment.
+ *
+ * @interface ILiquidPaymentConfig
+ *
+ * @property {string} clientSecret - The secret key for the client.
+ *
+ * @property {string} key - The API key provided for access.
+ *
+ * @property {string} elementId - The ID of the HTML element where the payment form will be rendered.
+ *
+ * @property {Object} [appearance] - Optional configuration for styling the payment element.
+ *
+ * @property {'default' | 'night' | 'flat'} [appearance.theme] - An optional theme for the payment form appearance.
+ *
+ * @property {ILiquidPaymentElementOptions} [elementOptions] - Additional options for configuring the payment element.
+ */
 export interface ILiquidPaymentConfig {
     clientSecret: string;
     key: string;
@@ -12,16 +38,49 @@ export interface ILiquidPaymentConfig {
     };
     elementOptions?: ILiquidPaymentElementOptions;
 }
+/**
+ * Interface representing the parameters required to confirm a session.
+ *
+ * Properties:
+ * - sessionSecret: A string representing the secret key for the session.
+ * - paymentMethodId: A string ID corresponding to the payment method to be used.
+ */
+export interface IConfirmSessionParams {
+    sessionSecret: string;
+    paymentMethodId: string;
+}
+/**
+ * Interface for representing a liquid payment token.
+ *
+ * An `ILiquidPaymentToken` contains relevant information about
+ * a payment token, which can be associated with various payment methods
+ * such as credit cards.
+ *
+ * Properties:
+ * @property {string} [id] - The unique identifier for the payment token.
+ * @property {string} [type] - The type/category of the payment token.
+ * @property {object} [card] - Information about the card associated with the payment token.
+ * @property {string|null} [card.brand] - The brand of the card (e.g., Visa, MasterCard).
+ * @property {string|null} [card.country] - The country where the card was issued.
+ * @property {number|null} [card.expMonth] - The expiration month of the card.
+ * @property {number|null} [card.expYear] - The expiration year of the card.
+ * @property {string|null} [card.last4] - The last four digits of the card number.
+ * @property {string|null} [card.funding] - The funding type of the card (e.g., credit, debit).
+ * @property {number} [created] - The timestamp (Unix epoch) indicating when the token was created.
+ * @property {object} [error] - Information about any error that occurred while generating the token.
+ * @property {string} [error.message] - The error message.
+ * @property {string} [error.code] - A code representing the specific error that occurred.
+ */
 export interface ILiquidPaymentToken {
     id?: string;
     type?: string;
     card?: {
-        brand: string;
-        country: string;
-        expMonth: number;
-        expYear: number;
-        last4: string;
-        funding: string;
+        brand: string | null;
+        country: string | null;
+        expMonth: number | null;
+        expYear: number | null;
+        last4: string | null;
+        funding: string | null;
     };
     created?: number;
     error?: {
@@ -29,12 +88,33 @@ export interface ILiquidPaymentToken {
         code?: string;
     };
 }
+/**
+ * This interface represents an error encountered during a liquid payment process.
+ *
+ * Properties:
+ *
+ * - type: A string indicating the type of error. Possible values are:
+ *   - 'validation_error': Indicates a validation error.
+ *   - 'api_error': Indicates an error related to the API.
+ *   - 'client_error': Indicates an error on the client side.
+ *   - 'confirm_error': Indicates an error during confirmation.
+ *
+ * - message: A string providing a descriptive message about the error.
+ *
+ * - code: An optional string that can provide a specific error code.
+ *
+ * - param: An optional string indicating the parameter that caused the error, if applicable.
+ */
 export interface ILiquidPaymentError {
-    type: 'validation_error' | 'api_error' | 'client_error';
+    type: 'validation_error' | 'api_error' | 'client_error' | 'confirm_error';
     message: string;
     code?: string;
     param?: string;
 }
+/**
+ * Represents the event map for payment elements and defines the types of events
+ * that can occur within the payment process.
+ */
 export interface IPaymentElementEventMap {
     change: StripePaymentElementChangeEvent;
     ready: StripePaymentElementChangeEvent;
@@ -47,8 +127,7 @@ export interface IPaymentElementEventMap {
     };
 }
 /**
- * Interface for the payment provider.
- * @interface
+ * Interface representing a payment provider that integrates with a Liquid payment gateway.
  */
 export interface IPaymentProvider {
     /**

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

@@ -1,40 +1,145 @@
 import type { DAYS_OF_WEEK, ENUM_MODALITIES } from '../enums';
 import type { IAddress } from './address.interface';
+/**
+ * The IRetailerTimes interface represents the working hours of a retailer.
+ *
+ * @property {string} startsAt - The time at which the retailer begins its operations.
+ * @property {string} endsAt - The time at which the retailer ends its operations.
+ */
 export interface IRetailerTimes {
     startsAt: string;
     endsAt: string;
 }
+/**
+ * Interface representing the configuration of retailer hours.
+ *
+ * @interface IRetailerHoursConfig
+ * @property {boolean} active - Indicates if the retailer is currently active.
+ * @property {IRetailerTimes[]} times - An array of time configurations for the retailer.
+ */
 export interface IRetailerHoursConfig {
     active: boolean;
     times: IRetailerTimes[];
 }
+/**
+ * Represents the operating hours configuration for a retailer, mapped by days of the week.
+ * Each day of the week has an associated configuration that details the opening and closing times.
+ *
+ * @type {Object} RetailerHours
+ * @property {IRetailerHoursConfig} MONDAY - Configuration for Monday
+ * @property {IRetailerHoursConfig} TUESDAY - Configuration for Tuesday
+ * @property {IRetailerHoursConfig} WEDNESDAY - Configuration for Wednesday
+ * @property {IRetailerHoursConfig} THURSDAY - Configuration for Thursday
+ * @property {IRetailerHoursConfig} FRIDAY - Configuration for Friday
+ * @property {IRetailerHoursConfig} SATURDAY - Configuration for Saturday
+ * @property {IRetailerHoursConfig} SUNDAY - Configuration for Sunday
+ */
 export type RetailerHours = {
     [day in DAYS_OF_WEEK]: IRetailerHoursConfig;
 };
+/**
+ * Interface representing the expectations of a retailer.
+ *
+ * @interface IRetailerExpectation
+ *
+ * @property {string} detail - A detailed description of the expectation.
+ * @property {string} short - A brief, summarized version of the expectation.
+ */
 export interface IRetailerExpectation {
     detail: string;
     short: string;
 }
+/**
+ * The IRetailerFreeDelivery interface represents a structure for the free delivery
+ * policy of a retailer. This includes the minimum purchase amount required for
+ * free delivery and the status of the free delivery offer.
+ *
+ * @property min - The minimum amount in the retailer's currency required to qualify
+ *                 for free delivery.
+ *
+ * @property active - A boolean indicating whether the free delivery offer is currently
+ *                    active or not.
+ */
 export interface IRetailerFreeDelivery {
     min: number;
     active: boolean;
 }
+/**
+ * Interface representing the configuration for fee-based shipping.
+ *
+ * @property {number} maxQuantity - The maximum quantity of items eligible for the shipping fee.
+ * @property {number} fee - The fee amount for shipping.
+ * @property {boolean} active - Indicates whether the fee-based shipping configuration is active.
+ */
 export interface IFeeShippingConfig {
     maxQuantity: number;
     fee: number;
     active: boolean;
 }
+/**
+ * Interface representing the shipping fee configurations for a retailer.
+ *
+ * @interface IRetailerFeeShipping
+ * @property {IFeeShippingConfig} individual - Configuration for individual item shipping fee.
+ * @property {IFeeShippingConfig} pack - Configuration for pack item shipping fee.
+ * @property {IRetailerFreeDelivery} free - Configuration for free delivery options.
+ */
 export interface IRetailerFeeShipping {
     individual: IFeeShippingConfig;
     pack: IFeeShippingConfig;
     free: IRetailerFreeDelivery;
 }
+/**
+ * Interface representing the delivery fee structure for a retailer.
+ *
+ * @interface IRetailerFeeDelivery
+ *
+ * @property {number} min - The minimum amount for delivery fee calculation.
+ * @property {number} fee - The standard delivery fee charged by the retailer.
+ * @property {IRetailerFreeDelivery} free - The criteria for free delivery.
+ */
 export interface IRetailerFeeDelivery {
     min: number;
     fee: number;
     free: IRetailerFreeDelivery;
 }
+/**
+ * Represents the possible types of retailer fees.
+ *
+ * @typedef {Object} IRetailerFees
+ * @property {IRetailerFeeShipping} shipping - The shipping fee details.
+ * @property {IRetailerFeeDelivery} delivery - The delivery fee details.
+ */
 export type IRetailerFees = IRetailerFeeShipping | IRetailerFeeDelivery;
+/**
+ * Interface representing the fulfillment details of a retailer.
+ *
+ * @interface IRetailerFulfillments
+ *
+ * @property {string} id - The unique identifier for the fulfillment.
+ *
+ * @property {ENUM_MODALITIES} type - The modality type of the fulfillment.
+ *
+ * @property {number} [deliveryFee] - Optional delivery fee for the fulfillment.
+ *
+ * @property {number} [shippingFee] - Optional shipping fee for the fulfillment.
+ *
+ * @property {number} [engravingFee] - Optional engraving fee for the fulfillment.
+ *
+ * @property {number} [subtotal] - Optional subtotal amount for the fulfillment.
+ *
+ * @property {string} [timezone] - Optional timezone associated with the fulfillment.
+ *
+ * @property {IRetailerFees} fees - The various fees associated with the fulfillment.
+ *
+ * @property {IRetailerExpectation} expectation - The expectations set for the fulfillment process.
+ *
+ * @property {RetailerHours} hours - The working hours applicable to the fulfillment.
+ *
+ * @property {IRetailerTimes[]} breaks - The breaks within the working hours.
+ *
+ * @property {string[]} items - List of item identifiers included in the fulfillment.
+ */
 export interface IRetailerFulfillments {
     id: string;
     type: ENUM_MODALITIES;
@@ -49,6 +154,22 @@ export interface IRetailerFulfillments {
     breaks: IRetailerTimes[];
     items: string[];
 }
+/**
+ * Interface representing a retailer with various attributes related to transactions and logistics.
+ *
+ * @interface
+ *
+ * @property {string} name - The name of the retailer.
+ * @property {string} id - The unique identifier for the retailer.
+ * @property {number} [platformFee] - Optional platform fee associated with the retailer.
+ * @property {number} [deliveryFee] - Optional delivery fee charged by the retailer.
+ * @property {number} [shippingFee] - Optional shipping fee charged by the retailer.
+ * @property {number} [engravingFee] - Optional engraving fee for customization services.
+ * @property {number} [subtotal] - Optional subtotal amount before fees and taxes.
+ * @property {number} [total] - Optional total amount including fees and taxes.
+ * @property {IAddress} [address] - Optional address information for the retailer.
+ * @property {IRetailerFulfillments[]} fulfillments - List of fulfillment details related to retailer orders.
+ */
 export interface IRetailer {
     name: string;
     id: string;