@liquidcommerce/cloud-sdk 1.3.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, IUserPayment, IUserPaymentAddParams, IUserPaymentUpdateParams, 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.
      *

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,6 +38,39 @@ 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;
@@ -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' | '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;

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

@@ -1,22 +1,63 @@
 import type { ENUM_ADDRESS_TYPE } from '../enums';
 import type { ICoreParams } from '../types';
+/**
+ * Represents a user session with key and secret used for authentication.
+ */
 export interface IUserSession {
     key: string | null;
     secret: string | null;
     createdAt: Date;
 }
-export interface IUserAddress {
-    id: string;
+/**
+ * Represents the basic structure of a user's address.
+ *
+ * @interface IUserAddressBase
+ *
+ * @property {string} placesId - The unique identifier for the place.
+ * @property {string} one - The primary street address or neighborhood.
+ * @property {string} two - The secondary address information, such as apartment or suite number.
+ * @property {string} city - The name of the city.
+ * @property {string} state - The name of the state or region.
+ * @property {string} zip - The postal code.
+ * @property {string} country - The name of the country.
+ * @property {number} lat - The latitude coordinate of the address.
+ * @property {number} long - The longitude coordinate of the address.
+ */
+export interface IUserAddressBase {
+    placesId: string;
     one: string;
-    two?: string | null;
+    two: string;
     city: string;
     state: string;
     zip: string;
     country: string;
+    lat: number;
+    long: number;
+}
+/**
+ * IUserAddress interface represents a user's address details.
+ * It extends the IUserAddressBase interface, adding additional properties for
+ * unique identification, timestamps, and default status.
+ *
+ * @interface IUserAddress
+ * @extends {IUserAddressBase}
+ *
+ * @property {string} id - Unique identifier for the user's address.
+ * @property {Date} createdAt - Timestamp indicating when the address was created.
+ * @property {Date} updatedAt - Timestamp indicating the last update to the address.
+ * @property {boolean} [isDefault] - Optional flag indicating if this is the default address.
+ */
+export interface IUserAddress extends IUserAddressBase {
+    id: string;
     createdAt: Date;
     updatedAt: Date;
     isDefault?: boolean;
 }
+/**
+ * Interface representing a saved card.
+ *
+ * @interface ISavedCard
+ */
 export interface ISavedCard {
     brand: string | null;
     country: string | null;
@@ -25,12 +66,26 @@ export interface ISavedCard {
     last4: string | null;
     funding: string | null;
 }
+/**
+ * Represents a user's payment method.
+ *
+ * @interface IUserPayment
+ * @property {string} id - The unique identifier for the payment method.
+ * @property {string} type - The type of the payment method (e.g., credit card, PayPal).
+ * @property {boolean} isDefault - Indicates whether this payment method is the default one.
+ * @property {ISavedCard} [card] - The saved card details if the payment method is a card.
+ * @property {Date} createdAt - The date when the payment method was added.
+ */
 export interface IUserPayment {
     id: string;
     type: string;
     isDefault: boolean;
     card?: ISavedCard;
+    createdAt: Date;
 }
+/**
+ * The IUser interface defines the structure for user objects within the application.
+ */
 export interface IUser {
     id: string;
     email: string;
@@ -46,6 +101,22 @@ export interface IUser {
     savedPayments: IUserPayment[];
     session: IUserSession;
 }
+/**
+ * Represents a basic user excluding the session information.
+ *
+ * This type is useful when user session details are not required
+ * or need to be omitted for certain operations, such as basic
+ * user management tasks.
+ *
+ * It extends the IUser interface but removes the 'session' property.
+ *
+ * Typically used in contexts where minimal user information is
+ * sufficient, focusing on non-session related attributes.
+ */
+export type BaseUser = Omit<IUser, 'session'>;
+/**
+ * Interface representing the parameters for a user session.
+ */
 export interface IUserSessionParams extends ICoreParams {
     id?: string;
     email?: string;
@@ -56,27 +127,63 @@ export interface IUserSessionParams extends ICoreParams {
     profileImage?: string | null;
     birthDate?: string | null;
 }
+/**
+ * Interface representing the response from a purge operation.
+ */
 export interface IPurgeResponse {
     deleted: boolean;
     message: string;
 }
+/**
+ * Interface representing the parameters required for user address operations.
+ * Extends the core parameters from ICoreParams.
+ */
 export interface IUserAddressParams extends ICoreParams {
     customerId: string;
-    one: string;
-    two?: string | null;
-    city: string;
-    state: string;
-    zip: string;
+    placesId?: string;
+    one?: string;
+    two?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    country?: string;
+    lat?: number;
+    long?: number;
     type: ENUM_ADDRESS_TYPE;
     isDefault?: boolean;
 }
+/**
+ * Interface representing the parameters required for user payment operations.
+ *
+ * This interface extends the core parameters interface (`ICoreParams`) and includes
+ * specific properties necessary for processing a user payment.
+ *
+ * Properties:
+ * - `customerId`: A string representing the unique identifier of the customer making the payment.
+ * - `paymentMethodId`: A string representing the unique identifier of the payment method to be used.
+ */
 export interface IUserPaymentParams extends ICoreParams {
     customerId: string;
     paymentMethodId: string;
 }
+/**
+ * Interface representing the parameters required to add a user payment.
+ *
+ * Extends the IUserPaymentParams interface to inherit the basic payment parameters.
+ *
+ * @property isDefault - Optional boolean indicating if the payment method should be set as default.
+ */
 export interface IUserPaymentAddParams extends IUserPaymentParams {
     isDefault?: boolean;
 }
+/**
+ * IUserPaymentUpdateParams is an interface extending IUserPaymentParams,
+ * representing the parameters required to update user payment information.
+ *
+ * @extends IUserPaymentParams
+ *
+ * @property {boolean} isDefault - Indicates whether the payment method is the default one.
+ */
 export interface IUserPaymentUpdateParams extends IUserPaymentParams {
     isDefault: boolean;
 }