@liquidcommerce/elements-sdk 2.6.0-beta.37 → 2.6.0-beta.39

package/docs/actions.md

@@ -0,0 +1,320 @@
+# Actions
+
+Actions let you control the SDK with JavaScript instead of (or in addition to) user interactions. Open the cart when a user clicks your custom button, pre-fill checkout forms for returning customers, or add products to cart from anywhere in your app.
+
+## Accessing Actions
+
+```javascript
+// Global access
+const { actions } = window.elements;
+
+// Or from client instance
+const client = await Elements('YOUR_API_KEY', config);
+// Access via client.actions
+```
+
+## How Actions Work
+
+Actions are fire-and-forget methods that return `void` or `Promise<void>`. All feedback comes through [events](./events.md) - this is by design for security.
+
+```javascript
+// 1. Listen for feedback
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  const { discount, newSubtotal } = event.detail.data;
+  showSuccess(`Saved $${discount}!`);
+});
+
+// 2. Fire the action
+await actions.cart.applyPromoCode('SUMMER20');
+```
+
+---
+
+## Address Actions
+
+Manage the customer's delivery location.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `setAddressByPlacesId(placesId)` | `Promise<void>` | Set location via Google Places ID |
+| `setAddressManually(address, coords)` | `Promise<void>` | Set location with address and coordinates |
+| `getDetails()` | `IAddressData \| null` | Get current address |
+| `clear()` | `Promise<void>` | Clear address (also resets cart) |
+
+### setAddressByPlacesId
+
+```javascript
+await actions.address.setAddressByPlacesId('ChIJN1t_tDeuEmsRUsoyG83frY4');
+```
+
+### setAddressManually
+
+```javascript
+await actions.address.setAddressManually(
+  {
+    one: '123 Main St',
+    two: 'Apt 4B',        // optional
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'         // optional
+  },
+  {
+    lat: 40.7128,
+    long: -74.0060
+  }
+);
+```
+
+### getDetails
+
+```javascript
+const address = actions.address.getDetails();
+if (address) {
+  console.log(address.formattedAddress);
+  console.log(address.coordinates);
+}
+```
+
+### clear
+
+```javascript
+await actions.address.clear();
+// Note: This also clears the cart
+```
+
+**Feedback Events:** `address_updated`, `address_cleared`, `address_failed`
+
+---
+
+## Product Actions
+
+Query product information.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getDetails(identifier)` | `IBaseProductEventData` | Get product state |
+
+### getDetails
+
+```javascript
+const product = actions.product.getDetails('00619947000020');
+
+console.log(product.name);
+console.log(product.selectedSizeId);
+console.log(product.selectedFulfillmentType);
+console.log(product.priceInfo);
+```
+
+---
+
+## Cart Actions
+
+Control the shopping cart.
+
+| Method | Returns | Description         |
+|--------|---------|---------------------|
+| `openCart()` | `void` | Show cart drawer    |
+| `closeCart()` | `void` | Hide cart drawer    |
+| `toggleCart()` | `void` | Toggle cart drawer  |
+| `addProduct(items[], openCart?)` | `Promise<void>` | Add items to cart   |
+| `applyPromoCode(code)` | `Promise<void>` | Apply discount code |
+| `removePromoCode()` | `Promise<void>` | Remove discount     |
+| `resetCart()` | `Promise<void>` | Clear all items     |
+| `getDetails()` | `IBaseCartEventData` | Get cart state      |
+
+### openCart / closeCart / toggleCart
+
+```javascript
+actions.cart.openCart();
+actions.cart.closeCart();
+actions.cart.toggleCart();
+```
+
+### addProduct
+
+```javascript
+await actions.cart.addProduct(
+  [
+    {
+      identifier: '00619947000020',
+      fulfillmentType: 'shipping',  // 'shipping' or 'onDemand'
+      quantity: 2
+    }
+  ],
+  true  // Open cart after adding (optional)
+);
+```
+
+### applyPromoCode / removePromoCode
+
+```javascript
+await actions.cart.applyPromoCode('SUMMER20');
+await actions.cart.removePromoCode();
+```
+
+### resetCart
+
+```javascript
+await actions.cart.resetCart();
+```
+
+### getDetails
+
+```javascript
+const cart = actions.cart.getDetails();
+
+console.log(cart.itemCount);
+console.log(cart.subtotal);
+console.log(cart.items);
+```
+
+**Feedback Events:** `cart_opened`, `cart_closed`, `cart_product_add_success`, `cart_product_add_failed`, `cart_promo_code_applied`, `cart_promo_code_removed`, `cart_promo_code_failed`, `cart_reset`
+
+---
+
+## Checkout Actions
+
+Control the checkout flow.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `openCheckout()` | `void` | Show checkout drawer |
+| `closeCheckout()` | `void` | Hide checkout drawer |
+| `toggleCheckout()` | `void` | Toggle checkout drawer |
+| `exitCheckout()` | `void` | Navigate to exit URL |
+| `addProduct(items[], open?)` | `Promise<void>` | Add to checkout directly |
+| `applyPromoCode(code)` | `Promise<void>` | Apply discount |
+| `removePromoCode()` | `Promise<void>` | Remove discount |
+| `applyGiftCard(code)` | `Promise<void>` | Apply gift card |
+| `removeGiftCard(code)` | `Promise<void>` | Remove gift card |
+| `toggleIsGift(active?)` | `Promise<void>` | Enable/disable gift mode |
+| `toggleBillingSameAsShipping(active?)` | `Promise<void>` | Use same address |
+| `toggleMarketingPreferences(field, active)` | `Promise<void>` | Set opt-in |
+| `updateCustomerInfo(params)` | `void` | Pre-fill customer form |
+| `updateBillingInfo(params)` | `void` | Pre-fill billing form |
+| `updateGiftInfo(params)` | `void` | Pre-fill gift form |
+| `getDetails()` | `ICheckoutDetailsEventData` | Get checkout state |
+
+### openCheckout / closeCheckout / toggleCheckout / exitCheckout
+
+```javascript
+actions.checkout.openCheckout();
+actions.checkout.closeCheckout();
+actions.checkout.toggleCheckout();
+actions.checkout.exitCheckout();  // Navigates to configured exit URL
+```
+
+### addProduct
+
+```javascript
+// Add products directly to checkout (skip cart)
+await actions.checkout.addProduct(
+  [{ identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }],
+  true  // Open checkout (optional)
+);
+```
+
+### applyPromoCode / removePromoCode
+
+```javascript
+await actions.checkout.applyPromoCode('SAVE10');
+await actions.checkout.removePromoCode();
+```
+
+### applyGiftCard / removeGiftCard
+
+```javascript
+await actions.checkout.applyGiftCard('GIFT-XXXX-XXXX');
+await actions.checkout.removeGiftCard('GIFT-XXXX-XXXX');
+```
+
+### toggleIsGift / toggleBillingSameAsShipping / toggleMarketingPreferences
+
+```javascript
+await actions.checkout.toggleIsGift(true);
+await actions.checkout.toggleBillingSameAsShipping(true);
+await actions.checkout.toggleMarketingPreferences('canEmail', true);
+await actions.checkout.toggleMarketingPreferences('canSms', false);
+```
+
+### updateCustomerInfo
+
+```javascript
+actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '555-123-4567'
+});
+```
+
+### updateBillingInfo
+
+```javascript
+actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  street1: '123 Billing St',
+  street2: 'Suite 100',  // optional
+  city: 'New York',
+  state: 'NY',
+  zipCode: '10001'
+});
+```
+
+### updateGiftInfo
+
+```javascript
+actions.checkout.updateGiftInfo({
+  recipientName: 'Jane Smith',
+  senderName: 'John Doe',
+  giftMessage: 'Happy Birthday!'
+});
+```
+
+### getDetails
+
+```javascript
+const checkout = actions.checkout.getDetails();
+
+console.log(checkout.subtotal);
+console.log(checkout.total);
+console.log(checkout.items);
+console.log(checkout.isGift);
+```
+
+**Feedback Events:** `checkout_opened`, `checkout_closed`, `checkout_product_add_success`, `checkout_product_add_failed`, `checkout_promo_code_applied`, `checkout_promo_code_removed`, `checkout_promo_code_failed`, `checkout_gift_card_applied`, `checkout_gift_card_removed`, `checkout_gift_card_failed`
+
+---
+
+## Product List Actions
+
+Coming soon.
+
+---
+
+## Security Notes
+
+Events never expose sensitive information:
+
+**Safe in events:**
+- Success/failure status
+- Discount amounts
+- Total amounts
+- Item counts and identifiers
+
+**Never exposed:**
+- Promo codes or gift card codes
+- Gift card balances
+- Sensitive financial details
+
+---
+
+## See Also
+
+- [Events Reference](./events.md) - Event feedback for actions
+- [Product](./product.md) - Product component
+- [Cart](./cart.md) - Cart component
+- [Checkout](./checkout.md) - Checkout component
+- [Address](./address.md) - Address component

package/docs/address.md

@@ -0,0 +1,242 @@
+# Address
+
+The address component manages the customer's delivery location. This determines which products are available, their pricing, and fulfillment options. Most implementations don't need to interact with this directly - it's built into the product component.
+
+## Overview
+
+The address element powers location-aware shopping:
+- Customers enter their delivery address
+- The SDK fetches location-specific inventory and pricing
+- Fulfillment options update based on what's available in that area
+- The address persists across sessions for returning customers
+
+**Important:** You typically don't need to inject this component separately. The address input is embedded within the product component by default. Use standalone injection only for dedicated "enter your address" landing pages.
+
+---
+
+## Declarative Setup (HTML Attributes)
+
+In most cases, the address component is automatically managed within the product element. No separate configuration is required.
+
+When you inject a product element, customers can:
+1. Click to enter their delivery address
+2. See real-time availability and pricing for their location
+3. Have their address remembered for future visits
+
+The address UI appears as part of the product component's fulfillment section.
+
+---
+
+## Programmatic Setup (JavaScript API)
+
+For standalone address collection (e.g., a "Check Availability" page), inject the address element directly.
+
+### Basic Injection
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+const component = await client.injectAddressElement('address-container');
+```
+
+### Return Value
+
+Returns `IInjectedComponent | null`:
+
+```javascript
+if (component) {
+  // Get the container element
+  const element = component.getElement();
+
+  // Get the component type
+  const type = component.getType(); // 'address'
+
+  // Force a re-render
+  component.rerender();
+}
+```
+
+---
+
+## Actions
+
+Control address state programmatically. Useful for:
+- Pre-filling addresses for logged-in customers
+- Custom address form integrations
+- Single-click address selection
+
+### Set Address by Google Places ID
+
+Set the delivery location using a Google Places ID:
+
+```javascript
+await window.elements.actions.address.setAddressByPlacesId('ChIJN1t_tDeuEmsRUsoyG83frY4');
+```
+
+### Set Address Manually
+
+Set the delivery location with explicit address data and coordinates:
+
+```javascript
+await window.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main St',      // Street address line 1
+    two: 'Apt 4B',           // Street address line 2 (optional)
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'            // Optional, defaults to US
+  },
+  {
+    lat: 40.7128,            // Latitude
+    long: -74.0060           // Longitude
+  }
+);
+```
+
+### Get Address Details
+
+Retrieve the currently saved address:
+
+```javascript
+const address = window.elements.actions.address.getDetails();
+
+if (address) {
+  console.log(address.formattedAddress);
+  console.log(address.coordinates);
+}
+```
+
+Returns `IAddressData | null`.
+
+### Clear Address
+
+Remove the saved address. **Note:** This also clears the cart since pricing and availability are location-dependent.
+
+```javascript
+await window.elements.actions.address.clear();
+```
+
+---
+
+## Events
+
+Listen to address changes for analytics or custom UI updates.
+
+### Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { formattedAddress, coordinates } = event.detail.data;
+  console.log('Address set to:', formattedAddress);
+});
+```
+
+### Available Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `address_updated` | Location set or changed | googlePlacesId, formattedAddress, address, coordinates |
+| `address_cleared` | Location removed | boolean (true) |
+| `address_failed` | Location operation failed | error message, googlePlacesId (if applicable) |
+
+### Example: Update Custom UI
+
+```javascript
+// Update your own UI when address changes
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { formattedAddress } = event.detail.data;
+  document.querySelector('.delivery-location').textContent = formattedAddress;
+});
+
+// Handle address being cleared
+window.addEventListener('lce:actions.address_cleared', () => {
+  document.querySelector('.delivery-location').textContent = 'Enter your address';
+});
+```
+
+---
+
+## Clear Address Behavior
+
+When an address is cleared (either by the customer or programmatically), several things happen:
+
+1. **Cart is reset** - Items are removed because pricing and availability are location-specific
+2. **Local storage is cleared** - The saved address is removed
+3. **Product displays update** - Products show "Enter address" prompts again
+
+This ensures customers never see stale pricing or unavailable items.
+
+---
+
+## Use Cases
+
+### Pre-fill for Logged-in Customers
+
+```javascript
+// When user logs in, set their saved address
+if (user.savedAddress) {
+  await window.elements.actions.address.setAddressManually(
+    {
+      one: user.savedAddress.street,
+      city: user.savedAddress.city,
+      state: user.savedAddress.state,
+      zip: user.savedAddress.zip
+    },
+    {
+      lat: user.savedAddress.latitude,
+      long: user.savedAddress.longitude
+    }
+  );
+}
+```
+
+### Custom Address Form
+
+```javascript
+// Connect your own address form to the SDK
+document.querySelector('#address-form').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const formData = new FormData(e.target);
+
+  // Use your geocoding service to get coordinates
+  const coords = await geocode(formData.get('address'));
+
+  await window.elements.actions.address.setAddressManually(
+    {
+      one: formData.get('street'),
+      city: formData.get('city'),
+      state: formData.get('state'),
+      zip: formData.get('zip')
+    },
+    coords
+  );
+});
+```
+
+---
+
+## Customization
+
+Style the address component through theme configuration.
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    address: {
+      // Address-specific theme options
+    }
+  }
+});
+```
+
+See [theming.md](./theming.md) for available address theme options.
+
+---
+
+## See Also
+
+- [Product](./product.md) - The product element (includes embedded address)
+- [Actions Reference](./actions.md) - All available actions
+- [Events Reference](./events.md) - All available events
+- [Theming Guide](./theming.md) - Customization options