@liquidcommerce/cloud-sdk 1.6.0 → 1.7.0

package/README.md

@@ -14,14 +14,17 @@ 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)
   - [Checkout](#checkout)
+  - [Order](#order)
+  - [Webhook](#webhook)
 - [Response Types](#response-types)
 - [Error Handling](#error-handling)
 - [Documentation](#documentation)
@@ -40,19 +43,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.
+
+Example using OrderLiquidCommerce client:
 
-await client.init();
+```typescript
+const orderClient = await OrderLiquidCommerce({
+  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 +97,7 @@ interface ApiResponse<T> {
 }
 ```
 
-## Services
+## Services and Usage
 
 ### Address
 
@@ -82,7 +106,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 +117,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 +127,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 +153,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 +214,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 +236,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 +251,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 +260,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 +273,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
@@ -260,10 +295,11 @@ The payment system uses secure elements for handling sensitive payment data. Bef
 #### 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 +312,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 +363,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 +389,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 +413,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 +423,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 +448,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 +466,61 @@ 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
+    },
   ],
   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,17 +529,17 @@ 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
+  key: preparedCheckout.payment.publicKey, // From checkout prepare response
   elementId: 'payment-element-container',
   appearance: { theme: 'night' },
-  elementOptions: { layout: 'tabs' }
+  elementOptions: { layout: 'tabs' },
 });
 
 // 3. Handle payment element events
@@ -511,7 +554,7 @@ if (!('error' in tokenResult)) {
   // 5. Complete checkout with payment token
   const completedCheckout = await client.checkout.complete({
     token: preparedCheckout.token,
-    payment: tokenResult.id
+    payment: tokenResult.id,
   });
 }
 
@@ -520,6 +563,30 @@ client.payment.unmount();
 client.payment.destroy();
 ```
 
+### Order
+
+Order retrieval services:
+
+```typescript
+// Fetch order details by ID or number
+const orderResponse = await client.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
 
 The SDK throws errors for various scenarios. Always wrap SDK calls in try-catch blocks:
@@ -534,6 +601,7 @@ try {
 ```
 
 Common error scenarios:
+
 - Authentication failures
 - Invalid parameters
 - Network errors
@@ -544,10 +612,11 @@ 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
 
 ## Documentation
 
-For more detailed information about each method and its parameters, please refer to our [official documentation](https://docs.liquidcommerce.cloud).
+For more detailed information about each method and its parameters, please refer to our [official documentation](https://docs.liquidcommerce.cloud).