@liquidcommerce/cloud-sdk 1.6.0 → 1.8.0

package/README.md

@@ -14,14 +14,18 @@ The LiquidCommerce Cloud SDK provides an easy way to interact with our APIs thro
 
 - [Installation](#installation)
 - [Configuration](#configuration)
-- [Usage](#usage)
-- [Services](#services)
+  - [API Key Authentication](#api-key-authentication)
+  - [Order API Authentication](#order-api-authentication)
+- [Services & Usage](#services-and-usage)
   - [Address](#address)
   - [Catalog](#catalog)
   - [Cart](#cart)
   - [User](#user)
-  - [Payment](#payment)
+  - [Payment Element](#payment-element)
+  - [Legacy Payment](#legacy-payment)
   - [Checkout](#checkout)
+  - [Order](#order)
+  - [Webhook](#webhook)
 - [Response Types](#response-types)
 - [Error Handling](#error-handling)
 - [Documentation](#documentation)
@@ -40,19 +44,40 @@ pnpm add @liquidcommerce/cloud-sdk
 
 ## Configuration
 
-The SDK requires configuration during initialization:
+### API Key Authentication
 
-```typescript
-import { LiquidCommerce, LIQUID_COMMERCE_ENV } from '@liquidcommerce/cloud-sdk';
+The LiquidCommerce API Key Authentication provides a secure method to obtain an access token for all other API calls to LiquidCommerce Services.
+
+Example using LiquidCommerce client:
 
+```typescript
+// The SDK automatically handles authentication
 const client = await LiquidCommerce('YOUR_LIQUIDCOMMERCE_API_KEY', {
   googlePlacesApiKey: 'YOUR_GOOGLE_PLACES_API_KEY', // Required for address services
-  env: LIQUID_COMMERCE_ENV.STAGE // STAGE or PROD
+  env: LIQUID_COMMERCE_ENV.STAGE, // or PROD
 });
+```
+
+[Click Here For Manual Authentication](https://docs.liquidcommerce.cloud/authentication-api-integration/get-access-token)
+
+### Order API Authentication
+
+LiquidCommerce provides a separate authentication mechanism for Order API endpoints. The Order client uses Basic Authentication with a username and password.
 
-await client.init();
+Example using LiquidCommerceOrders client:
+
+```typescript
+const orderClient = await LiquidCommerceOrders({
+  userID: 'YOUR_ORDER_API_USER_ID',
+  password: 'YOUR_ORDER_API_PASSWORD',
+  env: LIQUID_COMMERCE_ENV.STAGE, // or PROD
+});
 ```
 
+[Click Here For Manual Authentication](https://docs.liquidcommerce.cloud/services/orders-api/authentication)
+
+Note: Order authentication credentials are required to access Order API. The SDK will return appropriate authentication errors if these credentials are missing or invalid.
+
 ## Response Types
 
 All API responses follow a consistent structure:
@@ -73,7 +98,7 @@ interface ApiResponse<T> {
 }
 ```
 
-## Services
+## Services and Usage
 
 ### Address
 
@@ -82,7 +107,7 @@ Services for address validation and lookup:
 ```typescript
 // Address autocompletion
 const autocompleteResponse = await client.address.autocomplete({
-  input: '100 Madison Ave, New York'
+  input: '100 Madison Ave, New York',
 });
 
 // Response type: IApiResponseWithData<IAddressAutocompleteResult[]>
@@ -93,7 +118,7 @@ const autocompleteResponse = await client.address.autocomplete({
 
 // Get detailed address information
 const detailsResponse = await client.address.details({
-  id: 'ChIJd8BlQ2BZwokRjMKtTjMezRw'
+  id: 'ChIJd8BlQ2BZwokRjMKtTjMezRw',
 });
 
 // Response type: IApiResponseWithData<IAddressDetailsResult>
@@ -103,6 +128,14 @@ const detailsResponse = await client.address.details({
 //     lat: number;
 //     long: number;
 //   }
+//   address: {
+//     one: string,
+//     two: string,
+//     city": string,
+//     state: string,
+//     zip: string,
+//     country: "US"
+//   }
 // }
 ```
 
@@ -121,41 +154,43 @@ const availabilityResponse = await client.catalog.availability({
       one: '123 Main St',
       city: 'New York',
       state: 'NY',
-      zip: '10001'
-    }
+      zip: '10001',
+    },
   },
-  shouldShowOffHours: true
+  shouldShowOffHours: true,
 });
 
 // Search catalog with filters
 const searchResponse = await client.catalog.search({
   search: 'whiskey',
+  pageToken: '',
+  entity: '',
   page: 1,
   perPage: 20,
   orderBy: ENUM_ORDER_BY.PRICE,
   orderDirection: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE.ASC,
   filters: [
-    { 
-      key: ENUM_FILTER_KEYS.CATEGORIES, 
-      values: [ENUM_SPIRITS.WHISKEY] 
+    {
+      key: ENUM_FILTER_KEYS.CATEGORIES,
+      values: [ENUM_SPIRITS.WHISKEY],
     },
-    { 
-      key: ENUM_FILTER_KEYS.PRICE, 
-      values: { min: 2000, max: 10000 } // Prices in cents
+    {
+      key: ENUM_FILTER_KEYS.PRICE,
+      values: { min: 2000, max: 10000 }, // Prices in cents
     },
     {
       key: ENUM_FILTER_KEYS.AVAILABILITY,
-      values: ENUM_AVAILABILITY_VALUE.IN_STOCK
-    }
+      values: ENUM_AVAILABILITY_VALUE.IN_STOCK,
+    },
   ],
   loc: {
     address: {
       one: '123 Main St',
       city: 'New York',
       state: 'NY',
-      zip: '10001'
-    }
-  }
+      zip: '10001',
+    },
+  },
 });
 ```
 
@@ -180,18 +215,18 @@ const updatedCart = await client.cart.update({
       fulfillmentId: 'fulfillment_id',
       engravingLines: ['Line 1', 'Line 2'], // Optional
       scheduledFor: '2024-12-25', // Optional
-    }
+    },
   ],
   loc: {
     address: {
       one: '123 Main St',
       city: 'New York',
       state: 'NY',
-      zip: '10001'
-    }
+      zip: '10001',
+    },
   },
   promoCode: 'DISCOUNT10', // Optional
-  giftCards: ['GC123456'] // Optional
+  giftCards: ['GC123456'], // Optional
 });
 ```
 
@@ -202,13 +237,14 @@ User profile and preferences management:
 ```typescript
 // Create/update user session
 const userSession = await client.user.session({
-  email: "user@example.com",
-  firstName: "John",
-  lastName: "Smith",
-  phone: "2125551234",
-  company: "Company Inc",
-  profileImage: "https://...",
-  birthDate: "1990-01-01"
+  email: 'user@example.com',
+  firstName: 'John',
+  lastName: 'Smith',
+  phone: '2125551234',
+  company: 'Company Inc',
+  profileImage: 'https://...',
+  birthDate: '1990-01-01',
+  id: 'user_id', // Existing user identifier (for updates only), email becomes optional
 });
 
 // Fetch user by ID or email
@@ -216,7 +252,7 @@ const userData = await client.user.fetch('user_id_or_email');
 
 // Address management
 const newAddress = await client.user.addAddress({
-  customerId: 'customer_id',
+  userId: 'user_id',
   placesId: 'google_places_id', // Optional if providing address details
   one: '100 Madison St',
   two: 'Apt 4B',
@@ -225,9 +261,9 @@ const newAddress = await client.user.addAddress({
   zip: '10004',
   country: 'US',
   lat: 40.7128, // Optional
-  long: -74.0060, // Optional
+  long: -74.006, // Optional
   type: ENUM_ADDRESS_TYPE.SHIPPING,
-  isDefault: true
+  isDefault: true,
 });
 
 const updatedAddress = await client.user.updateAddress({
@@ -238,13 +274,13 @@ const updatedAddress = await client.user.updateAddress({
 const newPayment = await client.user.addPayment({
   customerId: 'customer_id',
   paymentMethodId: 'payment_method_id',
-  isDefault: true
+  isDefault: true,
 });
 
 const updatedPayment = await client.user.updatePayment({
   customerId: 'customer_id',
   paymentMethodId: 'payment_method_id',
-  isDefault: true // Required for updates
+  isDefault: true, // Required for updates
 });
 
 // Data removal
@@ -253,17 +289,117 @@ await client.user.purgeAddress('address_id');
 await client.user.purgePayment('customer_id', 'payment_id');
 ```
 
-### Payment
+### Payment Element
 
-The payment system uses secure elements for handling sensitive payment data. Before using payment features, you must first create a user session.
+The Payment Element is a secure and modern UI component for collecting payment details. It simplifies PCI compliance by handling all sensitive information within an iframe.
 
 #### Prerequisites
 
-1. User Session Creation:
+Before mounting the Payment Element, you must create a payment session. This can be tied to a user, cart, or checkout.
+
+```typescript
+// Create a payment session to get a client secret
+const paymentSession = await client.user.paymentSession({
+  // Optionally link to a cart, checkout, or customer
+  // cartId: 'your_cart_id',
+  // checkoutToken: 'your_checkout_token',
+  // customerId: 'your_customer_id',
+});
+
+const { key, secret } = paymentSession.data.session;
+```
+
+#### Integration
+
+1.  **Initialize and Mount**
+
+    The `LiquidCommercePaymentElement` function creates and manages the UI component.
+
+    ```typescript
+    // Initialize the payment element
+    const paymentElement = LiquidCommercePaymentElement({
+      session: {
+        key, // Public key from payment session
+        secret, // Client secret from payment session
+      },
+    });
+
+    // Mount the element to a container in your DOM
+    await paymentElement.mount({
+      elementId: 'payment-element-container',
+      appearance: {
+        theme: 'night', // 'stripe' | 'night' | 'flat'
+      },
+      elementOptions: {
+        layout: 'tabs', // 'tabs' | 'accordion' | 'auto'
+      },
+    });
+    ```
+
+2.  **Generate a Confirmation Token**
+
+    Once the user has filled out the payment form, create a confirmation token. This token securely represents the payment details.
+
+    ```typescript
+    const result = await paymentElement.createConfirmationToken({
+      returnUrl: 'https://your-return-url.com/checkout/confirm',
+    });
+
+    if (result.token) {
+      // Token successfully created
+      const confirmationToken = result.token;
+      // Use this token to complete the checkout or save the payment method
+    } else {
+      // Handle error
+      console.error(result.message);
+    }
+    ```
+
+3.  **Confirm the Payment Session**
+
+    Use the confirmation token to finalize the payment and retrieve the payment method details.
+
+    ```typescript
+    const confirmation = await client.user.confirmPaymentSession(confirmationToken);
+
+    if (confirmation.data) {
+      const paymentMethod = confirmation.data;
+      // Now you have the payment method ID, card details, etc.
+      // e.g., paymentMethod.id, paymentMethod.card.brand
+    }
+    ```
+
+4.  **Lifecycle Management**
+
+    Properly manage the element's lifecycle to ensure a smooth user experience and resource cleanup.
+
+    ```typescript
+    // Listen to events
+    paymentElement.subscribe('ready', () => {
+      console.log('Payment element is ready.');
+    });
+
+    paymentElement.subscribe('change', (event) => {
+      // Handle form state changes (e.g., enable/disable submit button)
+    });
+
+    // Clean up when the element is no longer needed
+    paymentElement.unmount();
+    paymentElement.destroy();
+    ```
+
+### Legacy Payment
+
+The legacy payment system uses a previous version of our payment integration. For new integrations, we strongly recommend using the [Payment Element](#payment-element) for a more secure and flexible solution.
+
+#### Prerequisites
+
+1.  User Session Creation:
+
 ```typescript
 // First create or get a user session
 const userSession = await client.user.session({
-  email: "user@example.com",
+  email: 'user@example.com',
   // ... other user details
 });
 
@@ -276,15 +412,15 @@ const { setupIntent, publicKey } = userSession.data.session;
 ```typescript
 // Initialize payment form using session credentials
 await client.payment.mount({
-  clientSecret: userSession.data.session.setupIntent,  // Required: from session
-  key: userSession.data.session.publicKey,            // Required: from session
-  elementId: 'payment-element-container',             // Your DOM element ID
-  appearance: { 
-    theme: 'night'  // 'default' | 'night' | 'flat'
+  clientSecret: userSession.data.session.setupIntent, // Required: from session
+  key: userSession.data.session.publicKey, // Required: from session
+  elementId: 'payment-element-container', // Your DOM element ID
+  appearance: {
+    theme: 'night', // 'stripe' | 'night' | 'flat'
+  },
+  elementOptions: {
+    layout: 'tabs', // 'tabs' | 'accordion' | 'auto'
   },
-  elementOptions: { 
-    layout: 'tabs'  // 'tabs' | 'accordion' | 'auto'
-  }
 });
 
 // Monitor payment element state
@@ -327,11 +463,12 @@ client.payment.destroy();
 #### Best Practices
 
 1. **Error Handling**: Always implement proper error handling:
+
 ```typescript
 try {
   const token = await client.payment.generateToken();
   if ('error' in token) {
-    switch(token.error.type) {
+    switch (token.error.type) {
       case 'validation_error':
         // Handle invalid card data
         break;
@@ -352,12 +489,14 @@ try {
 ```
 
 2. **Cleanup**: Always clean up payment elements when done:
+
 - When navigation away from payment page
 - After successful payment
 - After failed payment attempt
 - Before unmounting payment component
 
 3. **Event Handling**: Monitor element state for better user experience:
+
 ```typescript
 client.payment.subscribe('change', (event) => {
   // Update UI based on validation state
@@ -374,6 +513,7 @@ client.payment.subscribe('loaderror', (event) => {
 #### Responsive Design
 
 The payment element automatically adapts to:
+
 - Mobile and desktop viewports
 - Right-to-left languages
 - Dark/light themes
@@ -383,7 +523,7 @@ The payment element automatically adapts to:
 
 When testing payments in staging environment, use these test cards:
 
-```typescript
+```
 // Test Visa Card
 Card Number: 4242 4242 4242 4242
 Expiry: Any future date
@@ -408,6 +548,7 @@ ZIP: Any 5 digits
 These cards will be accepted in test mode and will simulate successful payments. They should only be used in the staging environment, never in production.
 
 **Important Notes:**
+
 - These cards work only in test/staging environment
 - Real cards will be declined in test mode
 - Test cards will be declined in production
@@ -425,59 +566,67 @@ Checkout process management:
 ```typescript
 // Prepare checkout
 const preparedCheckout = await client.checkout.prepare({
-  cartId: "cart_id",
+  cartId: 'cart_id',
   customer: {
-    id: "customer_id", // Optional
-    email: "customer@example.com",
-    firstName: "John",
-    lastName: "Smith",
-    phone: "2125551234",
-    birthDate: "1990-01-01"
+    id: 'customer_id', // Optional
+    email: 'customer@example.com',
+    firstName: 'John',
+    lastName: 'Smith',
+    phone: '2125551234',
+    birthDate: '1990-01-01',
   },
   hasAgeVerify: true,
   billingAddress: {
-    firstName: "John",
-    lastName: "Smith",
-    email: "billing@example.com",
-    phone: "2125551234",
-    one: "123 Main St",
-    two: "Apt 4B",
-    city: "New York",
-    state: "NY",
-    zip: "10001",
-    country: "US"
+    firstName: 'John',
+    lastName: 'Smith',
+    email: 'billing@example.com',
+    phone: '2125551234',
+    one: '123 Main St',
+    two: 'Apt 4B',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US',
   },
   hasSubstitutionPolicy: true,
   isGift: true,
   billingSameAsShipping: false,
   giftOptions: {
-    message: "Happy Birthday!",
+    message: 'Happy Birthday!',
     recipient: {
-      name: "Jane Smith",
-      email: "jane@example.com",
-      phone: "2125555678"
-    }
+      name: 'Jane Smith',
+      email: 'jane@example.com',
+      phone: '2125555678',
+    },
   },
   marketingPreferences: {
     canEmail: true,
-    canSms: true
+    canSms: true,
   },
   deliveryTips: [
     {
-      fulfillmentId: "fulfillment_id",
-      tip: 500 // Amount in cents
-    }
+      fulfillmentId: 'fulfillment_id',
+      tip: 500, // Amount in cents
+    },
+  ],
+   deliveryInstructions: [
+    {
+      fulfillmentId: 'fulfillment_id',
+      instructions: "", // 250 Max characters
+    },
   ],
   acceptedAccountCreation: true,
-  scheduledDelivery: "2024-12-25T14:00:00Z"
+  scheduledDelivery: '2024-12-25T14:00:00Z',
+  promoCode: 'DISCOUNT10', // Optional
+  giftCards: ['GC123456'], // Optional
 });
 
 // Complete checkout
 const completedCheckout = await client.checkout.complete({
   token: preparedCheckout.token,
-  payment: "payment_token"
+  payment: 'payment_id',
 });
-```_
+```
 
 #### Checkout Payment
 
@@ -486,38 +635,69 @@ For direct checkout payments, the flow is similar but uses the checkout session:
 ```typescript
 // 1. First prepare the checkout
 const preparedCheckout = await client.checkout.prepare({
-  cartId: "cart_id",
+  cartId: 'cart_id',
   // ... other checkout details
 });
 
-// 2. Initialize payment form with checkout data
-await client.payment.mount({
-  clientSecret: preparedCheckout.payment.clientSecret, // From checkout prepare response
-  key: preparedCheckout.payment.publicKey,            // From checkout prepare response
+// 2. Initialize payment element with checkout session
+const paymentElement = LiquidCommercePaymentElement({
+  session: {
+    key: preparedCheckout.data.payment.publicKey, // From checkout prepare response
+    secret: preparedCheckout.data.payment.clientSecret, // From checkout prepare response
+  }
+});
+
+// 3. Mount the element
+await paymentElement.mount({
   elementId: 'payment-element-container',
   appearance: { theme: 'night' },
-  elementOptions: { layout: 'tabs' }
+  elementOptions: { layout: 'tabs' },
 });
 
-// 3. Handle payment element events
-client.payment.subscribe('change', (event) => {
-  // Monitor payment form state
-  const { complete, empty, value } = event;
-});
+// 4. Handle payment element events and create confirmation token
+const result = await paymentElement.createConfirmationToken();
 
-// 4. When ready to complete checkout, generate payment token
-const tokenResult = await client.payment.generateToken();
-if (!('error' in tokenResult)) {
-  // 5. Complete checkout with payment token
+if (result.token) {
+  // 5. Complete checkout with the confirmation token
   const completedCheckout = await client.checkout.complete({
-    token: preparedCheckout.token,
-    payment: tokenResult.id
+    token: preparedCheckout.data.token,
+    payment: result.token,
   });
 }
 
 // 6. Clean up
-client.payment.unmount();
-client.payment.destroy();
+paymentElement.unmount();
+paymentElement.destroy();
+```
+
+### Order
+
+Order retrieval services:
+
+```typescript
+const orderClient = await LiquidCommerceOrders({
+  userID: 'YOUR_ORDER_API_USER_ID',
+  password: 'YOUR_ORDER_API_PASSWORD',
+  env: LIQUID_COMMERCE_ENV.STAGE, // or PROD
+});
+
+// Fetch order details by ID or number
+const orderResponse = await orderClient.order.fetch(/* reference id or order number */);
+```
+
+[Click here to access the docs for the order response structure](https://docs.liquidcommerce.cloud/types/order)
+
+### Webhook
+
+Webhook test services:
+
+```typescript
+// Test webhook endpoint
+const webhookTestResult = await client.webhook.test(/* endpoint */);
+
+// Response is a simple boolean indicating success or failure
+// true = webhook test was successful
+// false = webhook test failed
 ```
 
 ## Error Handling
@@ -534,6 +714,7 @@ try {
 ```
 
 Common error scenarios:
+
 - Authentication failures
 - Invalid parameters
 - Network errors
@@ -544,6 +725,7 @@ Common error scenarios:
 ## Price Handling
 
 All monetary values in the SDK are handled in cents (the smallest currency unit). For example:
+
 - $10.00 is represented as 1000
 - $5.99 is represented as 599
 - $0.50 is represented as 50