@liquidcommerce/elements-sdk 2.6.0-beta.9 → 2.6.0-beta.91

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

@@ -0,0 +1,286 @@
+# Address Actions API
+
+Address actions allow you to programmatically manage the delivery location.
+
+## actions.address.setAddressByPlacesId()
+
+Set address using a Google Places ID.
+
+### Signature
+
+```typescript
+setAddressByPlacesId(placesId: string): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `placesId` | string | Yes | Google Places ID |
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(
+  'ChIJOwg_06VPwokRYv534QaPC8g'
+);
+```
+
+### How to Get Places ID
+
+Visit [Google Place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id#find-id) for details on obtaining a Places ID.
+
+---
+
+## actions.address.setAddressManually()
+
+Set address manually without Google Places.
+
+### Signature
+
+```typescript
+setAddressManually(
+  address: IAddressAddress,
+  coordinates: IAddressCoordinates
+): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IAddressAddress {
+  one: string;     // Street address
+  two: string;     // Apt, suite, etc.
+  city: string;    // City name
+  state: string;   // Two-letter state code
+  zip: string;     // ZIP/postal code
+  country: string; // Country
+}
+
+interface IAddressCoordinates {
+  latitude: number;   // -90 to 90
+  longitude: number;  // -180 to 180
+}
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main Street',
+    two: 'Apt 4',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'
+  },
+  {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+);
+```
+
+### Validation
+
+The SDK validates:
+- All required fields are present (street, city, state, zip)
+- Latitude is between -90 and 90
+- Longitude is between -180 and 180
+
+> Note: the `state` field is expected to be a 2-letter code by convention, but the SDK does **not** enforce its format.
+
+### Errors
+
+**Throws `SDKError` if:**
+- `address` or `coordinates` is missing
+- A required field is missing (street, city, state, zip)
+- Latitude or longitude is non-numeric
+- Coordinates are out of range (latitude outside -90..90, longitude outside -180..180)
+
+---
+
+## actions.address.clear()
+
+Remove the current address.
+
+### Signature
+
+```typescript
+clear(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.clear();
+```
+
+### Effects
+
+- Clears stored address
+- Products will prompt for address on next add-to-cart
+- Cart/checkout require re-entering address
+
+---
+
+## actions.address.getDetails()
+
+Retrieve the current address.
+
+### Signature
+
+```typescript
+getDetails(): IAddressData | null
+```
+
+### Returns
+
+```typescript
+interface IAddressData {
+  id: string;  // Google Places ID (always populated when an object is returned)
+  address: {
+    one: string;
+    two: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+  };
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  formattedAddress: string;
+}
+```
+
+Returns `null` if no address is set. Manually-entered addresses (set via `setAddressManually`) are stored without a Google Places ID, so `getDetails()` also returns `null` for them.
+
+### Example
+
+```javascript
+const address = window.LiquidCommerce.elements.actions.address.getDetails();
+
+if (address) {
+  console.log('Current address:', address.formattedAddress);
+  console.log('Coordinates:', address.coordinates);
+} else {
+  console.log('No address set');
+}
+```
+
+### Use Cases
+
+#### Check if Address is Set
+
+```javascript
+if (!window.LiquidCommerce.elements.actions.address.getDetails()) {
+  // Prompt user to set address
+  showAddressPrompt();
+}
+```
+
+#### Display Current Address
+
+```javascript
+const address = window.LiquidCommerce.elements.actions.address.getDetails();
+
+if (address) {
+  document.getElementById('current-address').textContent = 
+    address.formattedAddress;
+}
+```
+## Events
+
+Address actions trigger events:
+
+```javascript
+// Address updated
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { googlePlacesId, address, coordinates, formattedAddress } = event.detail.data;
+  console.log('Address set:', formattedAddress);
+});
+
+// Address cleared
+window.addEventListener('lce:actions.address_cleared', () => {
+  console.log('Address cleared');
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+```
+
+## Best Practices
+
+### Use Places ID When Available
+
+Google Places provides accurate geocoding:
+
+```javascript
+// Good - accurate and validated
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId);
+
+// Less ideal - requires manual geocoding
+await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+```
+
+### Validate Manual Addresses
+
+When using manual address entry:
+
+```javascript
+async function setManualAddress(address, coords) {
+  // Validate format
+  if (!address.one || !address.city || !address.state || !address.zip) {
+    throw new Error('Missing required fields');
+  }
+  
+  // Validate state
+  if (!/^[A-Z]{2}$/.test(address.state)) {
+    throw new Error('State must be 2-letter code');
+  }
+  
+  // Validate ZIP
+  if (!/^\d{5}(-\d{4})?$/.test(address.zip)) {
+    throw new Error('Invalid ZIP code');
+  }
+  
+  await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+}
+```
+
+### Handle Errors
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId);
+  showSuccess('Address saved!');
+} catch (error) {
+  console.error('Failed to set address:', error);
+  showError('Unable to set that address. Please try again.');
+}
+```
+
+### Set Address Early
+
+Set address as soon as possible in user flow:
+
+```javascript
+window.addEventListener('lce:actions.client_ready', () => {
+  if (!window.LiquidCommerce.elements.actions.address.getDetails()) {
+    // Prompt for address on first visit
+    showAddressModal();
+  }
+});
+```
+
+## See Also
+
+- [Address Component Guide](../../guides/address-component.md)
+- [Address Events](../../guides/events.md#address-events)
+- [Product Component](../../guides/product-component.md#address-requirement)
+- [Cart Component](../../guides/cart-component.md#address-requirement)

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

@@ -0,0 +1,357 @@
+# Cart Actions API
+
+Cart actions allow you to programmatically control the shopping cart.
+
+## actions.cart.openCart()
+
+Open the cart drawer.
+
+### Signature
+
+```typescript
+openCart(): void
+```
+
+### Example
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+---
+
+## actions.cart.closeCart()
+
+Close the cart drawer.
+
+### Signature
+
+```typescript
+closeCart(): void
+```
+
+### Example
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.closeCart();
+```
+
+---
+
+## actions.cart.toggleCart()
+
+Toggle the cart drawer open/closed.
+
+### Signature
+
+```typescript
+toggleCart(): void
+```
+
+### Example
+
+```javascript
+// Add to your cart button
+document.getElementById('cart-btn').addEventListener('click', () => {
+  window.LiquidCommerce.elements.actions.cart.toggleCart();
+});
+```
+
+---
+
+## actions.cart.addProduct()
+
+Add products to the cart programmatically.
+
+### Signature
+
+```typescript
+addProduct(params: IAddProductParams[], openCart?: boolean): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `params` | IAddProductParams[] | Yes | Array of products to add |
+| `openCart` | boolean | No | Open cart after adding (default: false) |
+
+```typescript
+interface IAddProductParams {
+  identifier: string;      // Product UPC, size ID, or salsify grouping ID
+  fulfillmentType: FulfillmentType;  // 'shipping' or 'onDemand'
+  quantity: number;        // Number of items
+  engravingLines?: string[]; // Optional engraving (see below)
+}
+```
+
+#### `engravingLines` (optional)
+
+Pre-fills an engraving for the added item. The SDK enforces the product's engraving rules and degrades silently rather than failing the call:
+
+- Non-string-array input is ignored (warning logged).
+- Blank/whitespace-only entries are stripped; an empty result is treated as no engraving.
+- If the product/size doesn't support engraving, lines are dropped.
+- Lines beyond `maxLines` are sliced off; any line longer than `maxCharsPerLine` is truncated.
+- If no engravable variant is available for the chosen fulfillment, lines are dropped and the item is still added.
+
+### Example
+
+```javascript
+// Add single product
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // Open cart after adding
+
+// Add multiple products
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 2
+  },
+  {
+    identifier: '08504405135',
+    fulfillmentType: 'onDemand',
+    quantity: 1
+  }
+]);
+
+// Add a product with engraving
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1,
+    engravingLines: ['Happy Birthday', 'Love, Sam']
+  }
+], true);
+```
+
+### Address Requirement
+
+If no address is set, the SDK automatically:
+1. Opens address input drawer
+2. Waits for user to set address
+3. Retries add-to-cart operation
+
+### Errors
+
+**Throws `SDKError` if:**
+- Identifier is invalid
+- Fulfillment type is not `'shipping'` or `'onDemand'`
+- Quantity is less than 1
+
+Unavailable products and presale items are **not** thrown — they are silently skipped (a `cart.error` is set on the store). If no products could be added, a `cart_product_add_failed` event is emitted with `{ cartId, identifiers, error }` and the returned promise still resolves (it does not reject).
+
+---
+
+## actions.cart.applyPromoCode()
+
+Apply a promo code to the cart.
+
+### Signature
+
+```typescript
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `promoCode` | string | Yes | Promo code to apply |
+
+### Example
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.cart.applyPromoCode('SUMMER20');
+  console.log('Promo code applied successfully');
+} catch (error) {
+  console.error('Invalid promo code:', error);
+}
+```
+
+### Notes
+
+- Code is automatically normalized (trimmed, uppercased)
+- Promo codes must be enabled in configuration
+- Only one promo code can be active at a time
+- Applying a new code replaces the existing one
+
+---
+
+## actions.cart.removePromoCode()
+
+Remove the active promo code.
+
+### Signature
+
+```typescript
+removePromoCode(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.removePromoCode();
+```
+
+---
+
+## actions.cart.resetCart()
+
+Clear all items from the cart.
+
+### Signature
+
+```typescript
+resetCart(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.resetCart();
+console.log('Cart cleared');
+```
+
+### Warning
+
+This permanently removes all cart items. There is no undo.
+
+---
+
+## actions.cart.getDetails()
+
+Retrieve current cart information.
+
+### Signature
+
+```typescript
+getDetails(): IBaseCartEventData
+```
+
+### Returns
+
+```typescript
+interface IBaseCartEventData {
+  cartId: string;
+  promoCodeDiscount: number | null;  // in cents
+  subtotal: number;  // in cents
+  itemCount: number;
+  items: Record<string, ICartItem>;       // keyed by item ID
+  retailers: Record<string, ICartRetailer>; // keyed by retailer ID
+  location: {
+    placesId: string;
+    formattedAddress: string;
+    address: IAddressAddress;
+    coordinates: IAddressCoordinates;
+  } | null;
+}
+```
+
+### Example
+
+```javascript
+const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+
+console.log(`Cart ID: ${cart.cartId}`);
+console.log(`Items: ${cart.itemCount}`);
+console.log(`Subtotal: $${cart.subtotal / 100}`);
+
+if (cart.promoCodeDiscount) {
+  console.log(`Discount: $${cart.promoCodeDiscount / 100}`);
+}
+```
+
+### Use Cases
+
+#### Display Cart Summary
+
+```javascript
+function updateCartSummary() {
+  const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+  
+  document.getElementById('cart-count').textContent = cart.itemCount;
+  document.getElementById('cart-total').textContent = `$${cart.subtotal / 100}`;
+}
+
+// Update on cart changes
+window.addEventListener('lce:actions.cart_updated', updateCartSummary);
+```
+
+#### Check Cart Before Checkout
+
+```javascript
+document.getElementById('checkout-btn').addEventListener('click', () => {
+  const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+  
+  if (cart.itemCount === 0) {
+    alert('Your cart is empty');
+    return;
+  }
+  
+  window.LiquidCommerce.elements.actions.checkout.openCheckout();
+});
+```
+
+#### Track Cart Value
+
+```javascript
+const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+
+gtag('event', 'view_cart', {
+  value: cart.subtotal / 100,
+  currency: 'USD',
+  items: Object.values(cart.items).map(item => ({
+    item_id: item.partNumber,
+    quantity: item.quantity
+  }))
+});
+```
+
+## Events
+
+Cart actions trigger events that you can listen for:
+
+```javascript
+// Item added
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added:', event.detail.data);
+});
+
+// Cart updated
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  console.log('Cart updated:', event.detail.data);
+});
+
+// Promo code applied
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  console.log('Promo applied:', event.detail.data);
+});
+
+// Product add success
+window.addEventListener('lce:actions.cart_product_add_success', (event) => {
+  console.log('Products added:', event.detail.data);
+});
+
+// Product add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data);
+});
+```
+
+See [Events Guide](../../guides/events.md) for all cart events.
+
+## See Also
+
+- [Cart Component Guide](../../guides/cart-component.md)
+- [Cart Events](../../guides/events.md#cart-events)
+- [Product Actions](./product-actions.md)
+- [Checkout Actions](./checkout-actions.md)