@liquidcommerce/elements-sdk 2.6.0-beta.7 → 2.6.0-beta.71

package/docs/v1/api/actions/checkout-actions.md

@@ -0,0 +1,427 @@
+# Checkout Actions API
+
+Checkout actions allow you to programmatically control the checkout flow.
+
+## Navigation Actions
+
+### actions.checkout.openCheckout()
+
+```typescript
+openCheckout(): void
+```
+
+Opens the checkout drawer or navigates to checkout page.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.openCheckout();
+```
+
+### actions.checkout.closeCheckout()
+
+```typescript
+closeCheckout(): void
+```
+
+Closes the checkout drawer.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.closeCheckout();
+```
+
+### actions.checkout.toggleCheckout()
+
+```typescript
+toggleCheckout(): void
+```
+
+Toggles checkout open/closed.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.toggleCheckout();
+```
+
+### actions.checkout.exitCheckout()
+
+```typescript
+exitCheckout(): void
+```
+
+Navigates away from checkout (requires `exitUrl` configuration).
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.exitCheckout();
+```
+
+## Product Actions
+
+### actions.checkout.addProduct()
+
+```typescript
+addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
+```
+
+Add products directly to checkout, bypassing the cart.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // Open checkout after adding
+```
+
+### actions.checkout.addAnonymousProduct()
+
+```typescript
+addAnonymousProduct(
+  params: IAnonymousCheckoutAddProductParams
+): Promise<IAnonymousCheckoutAddProductResponse>
+```
+
+Add a product to checkout without requiring a cart session. Used for direct-to-checkout flows.
+
+```javascript
+const result = await window.LiquidCommerce.elements.actions.checkout
+  .addAnonymousProduct({
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  });
+```
+
+## Promo & Gift Card Actions
+
+### actions.checkout.applyPromoCode()
+
+```typescript
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+Apply a promo code during checkout.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyPromoCode('WELCOME10');
+```
+
+### actions.checkout.removePromoCode()
+
+```typescript
+removePromoCode(): Promise<void>
+```
+
+Remove the active promo code.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removePromoCode();
+```
+
+### actions.checkout.applyGiftCard()
+
+```typescript
+applyGiftCard(code: string): Promise<void>
+```
+
+Apply a gift card.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyGiftCard('GIFT-1234-5678-9012');
+```
+
+### actions.checkout.removeGiftCard()
+
+```typescript
+removeGiftCard(code: string): Promise<void>
+```
+
+Remove a gift card.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removeGiftCard('GIFT-1234-5678-9012');
+```
+
+## Toggle Actions
+
+### actions.checkout.toggleIsGift()
+
+```typescript
+toggleIsGift(active?: boolean): Promise<void>
+```
+
+Enable/disable gift mode.
+
+```javascript
+// Enable
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(true);
+
+// Disable
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(false);
+
+// Toggle
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift();
+```
+
+### actions.checkout.toggleBillingSameAsShipping()
+
+```typescript
+toggleBillingSameAsShipping(active?: boolean): Promise<void>
+```
+
+Set whether billing address matches shipping.
+
+```javascript
+// Use shipping address for billing
+await window.LiquidCommerce.elements.actions.checkout.toggleBillingSameAsShipping(true);
+
+// Use different billing address
+await window.LiquidCommerce.elements.actions.checkout.toggleBillingSameAsShipping(false);
+```
+
+### actions.checkout.toggleMarketingPreferences()
+
+```typescript
+toggleMarketingPreferences(field: 'canEmail' | 'canSms', active: boolean): Promise<void>
+```
+
+Set marketing opt-in preferences.
+
+```javascript
+// Opt into email marketing
+await window.LiquidCommerce.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+
+// Opt into SMS marketing
+await window.LiquidCommerce.elements.actions.checkout.toggleMarketingPreferences('canSms', true);
+```
+
+## Form Update Actions
+
+### actions.checkout.updateCustomerInfo()
+
+```typescript
+updateCustomerInfo(params: Record<CustomerFieldName, string>): void
+```
+
+Pre-fill customer information.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `birthdate`, `addressTwo`
+- `company`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  birthdate: '1990-01-01',
+  addressTwo: 'Apt 4B',
+  company: 'Acme Corp'
+});
+```
+
+### actions.checkout.updateBillingInfo()
+
+```typescript
+updateBillingInfo(params: Record<BillingFieldName, string>): void
+```
+
+Pre-fill billing address.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`, `company`
+- `addressOne`, `addressTwo`
+- `city`, `state`, `zipCode`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  company: 'Acme Corp',
+  addressOne: '123 Main St',
+  addressTwo: 'Apt 4B',
+  city: 'New York',
+  state: 'NY',
+  zipCode: '10001'
+});
+```
+
+### actions.checkout.updateGiftInfo()
+
+```typescript
+updateGiftInfo(params: Record<GiftFieldName, string>): void
+```
+
+Pre-fill gift recipient information.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `message`, `addressTwo`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  email: 'jane@example.com',
+  phone: '+15559876543',
+  addressTwo: 'Suite 200',
+  message: 'Happy Birthday!',
+});
+```
+
+## Data Retrieval
+
+### actions.checkout.getDetails()
+
+```typescript
+getDetails(): ICheckoutDetailsEventData
+```
+
+Retrieve current checkout information.
+
+```javascript
+const checkout = window.LiquidCommerce.elements.actions.checkout.getDetails();
+
+console.log(`Cart ID: ${checkout.cartId}`);
+console.log(`Total: $${checkout.amounts.total / 100}`);
+console.log(`Items: ${checkout.items.length}`);
+console.log(`Is Gift: ${checkout.isGift}`);
+```
+
+**Returns:**
+
+```typescript
+interface ICheckoutDetailsEventData {
+  cartId: string;
+  items: ICheckoutItem[];
+  amounts: {
+    subtotal: number;
+    tax: number;
+    shipping: number;
+    tip: number;
+    total: number;
+  };
+  customer: ICustomerInfo;
+  shippingAddress: IAddress;
+  billingAddress?: IAddress;
+  isGift: boolean;
+  giftRecipient?: IGiftRecipient;
+  promoCode?: IPromoCode;
+  giftCards: IGiftCard[];
+  // ... additional fields
+}
+```
+
+### actions.checkout.getProductAvailabilityByState()
+
+```typescript
+getProductAvailabilityByState(
+  identifiers: string[],
+  state?: string
+): Promise<IProductAvailabilityResponse>
+```
+
+Check product availability across states from the checkout context.
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.checkout
+  .getProductAvailabilityByState(['00619947000020'], 'CA');
+```
+
+| Parameter     | Type     | Required | Description                          |
+|---------------|----------|----------|--------------------------------------|
+| `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs  |
+| `state`       | string   | No       | Two-letter state code (e.g., `'NY'`) |
+
+## Use Cases
+
+### Pre-fill for Logged-In Users
+
+```javascript
+window.addEventListener('lce:actions.checkout_opened', () => {
+  if (userIsLoggedIn) {
+    window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+      firstName: currentUser.firstName,
+      lastName: currentUser.lastName,
+      email: currentUser.email,
+      phone: currentUser.phone
+    });
+  }
+});
+```
+
+### Track Checkout Progress
+
+```javascript
+window.addEventListener('lce:actions.checkout_customer_information_updated', () => {
+  gtag('event', 'checkout_progress', { step: 'customer_info' });
+});
+
+window.addEventListener('lce:actions.checkout_submit_started', () => {
+  gtag('event', 'checkout_progress', { step: 'payment' });
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderId, total } = event.detail.data;
+  
+  gtag('event', 'purchase', {
+    transaction_id: orderId,
+    value: total / 100,
+    currency: 'USD'
+  });
+});
+```
+
+### Gift Flow
+
+```javascript
+document.getElementById('gift-checkbox').addEventListener('change', async (e) => {
+  await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(e.target.checked);
+  
+  if (e.target.checked) {
+    showGiftForm();
+  } else {
+    hideGiftForm();
+  }
+});
+```
+
+### Auto-Apply Campaign Codes
+
+```javascript
+const params = new URLSearchParams(window.location.search);
+const campaignCode = params.get('promo');
+
+if (campaignCode) {
+  window.addEventListener('lce:actions.checkout_opened', async () => {
+    try {
+      await window.LiquidCommerce.elements.actions.checkout.applyPromoCode(campaignCode);
+    } catch (error) {
+      console.log('Invalid campaign code');
+    }
+  });
+}
+```
+
+## Events
+
+Checkout actions trigger numerous events. See [Checkout Events](../../guides/events.md#checkout-events) for complete list.
+
+Key events:
+- `checkout_opened`, `checkout_closed`
+- `checkout_customer_information_updated`
+- `checkout_submit_started`, `checkout_submit_completed`, `checkout_submit_failed`
+- `checkout_promo_code_applied`, `checkout_promo_code_failed`
+- `checkout_gift_card_applied`, `checkout_gift_card_failed`
+
+## See Also
+
+- [Checkout Component Guide](../../guides/checkout-component.md)
+- [Checkout Events](../../guides/events.md#checkout-events)
+- [Cart Actions](./cart-actions.md)

package/docs/v1/api/actions/product-actions.md

@@ -0,0 +1,158 @@
+# Product Actions API
+
+Product actions allow you to programmatically retrieve product information.
+
+## actions.product.getDetails()
+
+Retrieve details of a loaded product.
+
+### Signature
+
+```typescript
+getDetails(identifier: string): IBaseProductEventData
+```
+
+### Parameters
+
+| Parameter    | Type   | Required | Description             |
+|--------------|--------|----------|-------------------------|
+| `identifier` | string | Yes      | Product UPC, SKU, or ID |
+
+### Returns
+
+```typescript
+interface IBaseProductEventData {
+  identifier: string;
+  name: string;
+  description: string;
+  price: number;  // in cents
+  selectedSize: IProductSize;
+  selectedFulfillmentType: FulfillmentType;
+  selectedRetailer: IRetailer;
+  quantity: number;
+  images: string[];
+  brand: string;
+  category: string;
+  // ... additional fields
+}
+```
+
+### Example
+
+```javascript
+const productData = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+
+console.log(productData.name);        // "Premium Whiskey"
+console.log(productData.price / 100); // 49.99
+console.log(productData.selectedSize.name); // "750ml"
+console.log(productData.quantity);     // 1
+```
+
+### Errors
+
+**Throws `SDKError` if:**
+- Identifier is empty or invalid
+- Product has not been loaded yet
+- Product does not exist
+
+```javascript
+try {
+  const data = window.LiquidCommerce.elements.actions.product.getDetails('invalid_id');
+} catch (error) {
+  console.error('Product not found:', error.message);
+}
+```
+
+### Use Cases
+
+#### Display Product Info Elsewhere
+
+```javascript
+const product = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+
+document.getElementById('product-name').textContent = product.name;
+document.getElementById('product-price').textContent = `$${product.price / 100}`;
+```
+
+#### Sync with Analytics
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', () => {
+  const product = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+  
+  gtag('event', 'view_item', {
+    items: [{
+      item_id: product.identifier,
+      item_name: product.name,
+      price: product.price / 100,
+      item_brand: product.brand
+    }]
+  });
+});
+```
+
+#### Custom Product Comparison
+
+```javascript
+const product1 = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
+const product2 = window.LiquidCommerce.elements.actions.product.getDetails('08504405135');
+
+if (product1.price < product2.price) {
+  console.log(`${product1.name} is cheaper`);
+}
+```
+
+---
+
+## actions.product.getProductAvailabilityByState()
+
+Check product availability across states.
+
+### Signature
+
+```typescript
+getProductAvailabilityByState(
+  identifiers: string[],
+  state?: string
+): Promise<IProductAvailabilityResponse>
+```
+
+### Parameters
+
+| Parameter     | Type     | Required | Description                              |
+|---------------|----------|----------|------------------------------------------|
+| `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs      |
+| `state`       | string   | No       | Two-letter state code (e.g., `'NY'`)     |
+
+### Example
+
+```javascript
+// Check availability in a specific state
+const availability = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020', '08504405135'], 'CA');
+
+// Check availability in the user's current state (uses address if set)
+const availability = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020']);
+```
+
+### Errors
+
+**Throws `SDKError` if:**
+- No identifiers provided or array is empty
+- API request fails
+
+---
+
+## Notes
+
+- Product must be injected and loaded before calling `getDetails()`
+- `getDetails()` is synchronous - returns immediately
+- `getProductAvailabilityByState()` is async - returns a Promise
+- Prices are always in cents (divide by 100 for dollars)
+- Selected values reflect current user selection in the component
+
+## See Also
+
+- [Product Component Guide](../../guides/product-component.md)
+- [Product Events](../../guides/events.md#product-events)