omni-sync-sdk 0.13.0 → 0.14.0

package/README.md

@@ -260,6 +260,111 @@ export function isLoggedIn(): boolean {
 
 ---
 
+## Important: Cart & Checkout Data Structures
+
+### Nested Product/Variant Structure
+
+Cart and Checkout items use a **nested structure** for product and variant data. This is a common pattern that prevents data duplication and ensures consistency.
+
+**Common Mistake:**
+
+```typescript
+// WRONG - product name is NOT at top level
+const name = item.name; // undefined!
+const sku = item.sku; // undefined!
+```
+
+**Correct Access Pattern:**
+
+```typescript
+// CORRECT - access via nested objects
+const name = item.product.name;
+const sku = item.product.sku;
+const variantName = item.variant?.name;
+const variantSku = item.variant?.sku;
+```
+
+### Field Mapping Reference
+
+| What You Want  | CartItem                  | CheckoutLineItem          |
+| -------------- | ------------------------- | ------------------------- |
+| Product Name   | `item.product.name`       | `item.product.name`       |
+| Product SKU    | `item.product.sku`        | `item.product.sku`        |
+| Product ID     | `item.productId`          | `item.productId`          |
+| Product Images | `item.product.images`     | `item.product.images`     |
+| Variant Name   | `item.variant?.name`      | `item.variant?.name`      |
+| Variant SKU    | `item.variant?.sku`       | `item.variant?.sku`       |
+| Variant ID     | `item.variantId`          | `item.variantId`          |
+| Unit Price     | `item.unitPrice` (string) | `item.unitPrice` (string) |
+| Quantity       | `item.quantity`           | `item.quantity`           |
+
+### Price Fields Are Strings
+
+All monetary values in Cart and Checkout are returned as **strings** (e.g., `"29.99"`) to preserve decimal precision across different systems. Use `parseFloat()` or the `formatPrice()` helper:
+
+```typescript
+// Monetary fields that are strings:
+// - CartItem: unitPrice, discountAmount
+// - Cart: subtotal, discountAmount
+// - CheckoutLineItem: unitPrice, discountAmount
+// - Checkout: subtotal, discountAmount, shippingAmount, taxAmount, total
+// - ShippingRate: price
+
+import { formatPrice } from 'omni-sync-sdk';
+
+// Option 1: Using formatPrice helper (recommended)
+const cart = await omni.getCart(cartId);
+const total = formatPrice(cart.subtotal); // "$59.98"
+const totalNum = formatPrice(cart.subtotal, { asNumber: true }); // 59.98
+
+// Option 2: Manual parseFloat
+const subtotal = parseFloat(cart.subtotal);
+const discount = parseFloat(cart.discountAmount);
+const total = subtotal - discount;
+
+// Line item total
+cart.items.forEach((item) => {
+  const lineTotal = parseFloat(item.unitPrice) * item.quantity;
+  console.log(`${item.product.name}: $${lineTotal.toFixed(2)}`);
+});
+```
+
+### Complete Cart Item Display Example
+
+```typescript
+import type { CartItem } from 'omni-sync-sdk';
+import { formatPrice } from 'omni-sync-sdk';
+
+function CartItemRow({ item }: { item: CartItem }) {
+  // Access nested product data
+  const productName = item.product.name;
+  const productSku = item.product.sku;
+  const productImage = item.product.images?.[0]?.url;
+
+  // Access nested variant data (if exists)
+  const variantName = item.variant?.name;
+  const displayName = variantName ? `${productName} - ${variantName}` : productName;
+
+  // Format price using helper
+  const unitPrice = formatPrice(item.unitPrice);
+  const lineTotal = formatPrice(item.unitPrice, { asNumber: true }) * item.quantity;
+
+  return (
+    <div className="flex items-center gap-4">
+      <img src={productImage} alt={displayName} className="w-16 h-16 object-cover" />
+      <div className="flex-1">
+        <h3 className="font-medium">{displayName}</h3>
+        <p className="text-sm text-gray-500">SKU: {item.variant?.sku || productSku}</p>
+      </div>
+      <span className="text-gray-600">Qty: {item.quantity}</span>
+      <span className="font-medium">${lineTotal.toFixed(2)}</span>
+    </div>
+  );
+}
+```
+
+---
+
 ## API Reference
 
 ### Products
@@ -473,19 +578,36 @@ function ProductPrice({ product }: { product: Product }) {
 
 #### Rendering Product Descriptions
 
-**IMPORTANT**: Product descriptions may contain HTML (from Shopify/WooCommerce) or plain text. Always check `descriptionFormat` before rendering:
+> **CRITICAL**: Product descriptions from Shopify/WooCommerce contain HTML tags. If you render them as plain text, users will see raw `<p>`, `<ul>`, `<li>` tags instead of formatted content!
+
+Use the SDK helper functions to handle this automatically:
 
 ```tsx
-// Correct way to render product descriptions
-{
-  product.description &&
-    (product.descriptionFormat === 'html' ? (
-      // HTML content from Shopify/WooCommerce - render as HTML
-      <div dangerouslySetInnerHTML={{ __html: product.description }} />
-    ) : (
-      // Plain text - render normally
-      <p>{product.description}</p>
-    ));
+import { isHtmlDescription, getDescriptionContent } from 'omni-sync-sdk';
+
+// Option 1: Using isHtmlDescription helper (recommended)
+function ProductDescription({ product }: { product: Product }) {
+  if (!product.description) return null;
+
+  if (isHtmlDescription(product)) {
+    // HTML from Shopify/WooCommerce - MUST use dangerouslySetInnerHTML
+    return <div dangerouslySetInnerHTML={{ __html: product.description }} />;
+  }
+
+  // Plain text - render normally
+  return <p>{product.description}</p>;
+}
+
+// Option 2: Using getDescriptionContent helper
+function ProductDescription({ product }: { product: Product }) {
+  const content = getDescriptionContent(product);
+  if (!content) return null;
+
+  if ('html' in content) {
+    return <div dangerouslySetInnerHTML={{ __html: content.html }} />;
+  }
+
+  return <p>{content.text}</p>;
 }
 ```
 
@@ -496,6 +618,13 @@ function ProductPrice({ product }: { product: Product }) {
 | TikTok          | `'text'`          | Render as plain text          |
 | Manual entry    | `'text'`          | Render as plain text          |
 
+**Common Mistake** - DO NOT do this:
+
+```tsx
+// WRONG - HTML will show as raw tags like <p>Hello</p>
+<p>{product.description}</p>
+```
+
 ---
 
 ### Local Cart (Guest Users) - RECOMMENDED
@@ -988,6 +1117,98 @@ interface ShippingRate {
 }
 ```
 
+#### Shipping Rates: Complete Flow
+
+The shipping flow involves setting an address and then selecting from available rates:
+
+```typescript
+// Step 1: Set shipping address - this returns available rates
+const { checkout, rates } = await omni.setShippingAddress(checkoutId, {
+  firstName: 'John',
+  lastName: 'Doe',
+  line1: '123 Main St',
+  city: 'New York',
+  region: 'NY',
+  postalCode: '10001',
+  country: 'US',
+});
+
+// Step 2: Handle empty rates (edge case)
+if (rates.length === 0) {
+  // No shipping options available for this address
+  // This can happen when:
+  // - Store doesn't ship to this address/country
+  // - All shipping methods have restrictions that exclude this address
+  // - Shipping rates haven't been configured in the store
+
+  return (
+    <div className="bg-yellow-50 p-4 rounded">
+      <p className="font-medium">No shipping options available</p>
+      <p className="text-sm text-gray-600">
+        We currently cannot ship to this address. Please try a different address or contact us for
+        assistance.
+      </p>
+    </div>
+  );
+}
+
+// Step 3: Display available rates to customer
+<div className="space-y-2">
+  <h3 className="font-medium">Select Shipping Method</h3>
+  {rates.map((rate) => (
+    <label key={rate.id} className="flex items-center gap-3 p-3 border rounded cursor-pointer">
+      <input
+        type="radio"
+        name="shipping"
+        value={rate.id}
+        checked={selectedRateId === rate.id}
+        onChange={() => setSelectedRateId(rate.id)}
+      />
+      <div className="flex-1">
+        <span className="font-medium">{rate.name}</span>
+        {rate.description && <p className="text-sm text-gray-500">{rate.description}</p>}
+        {rate.estimatedDays && (
+          <p className="text-sm text-gray-500">Estimated delivery: {rate.estimatedDays} business days</p>
+        )}
+      </div>
+      <span className="font-medium">${parseFloat(rate.price).toFixed(2)}</span>
+    </label>
+  ))}
+</div>;
+
+// Step 4: Select the shipping method
+await omni.selectShippingMethod(checkoutId, selectedRateId);
+```
+
+**Handling Empty Shipping Rates:**
+
+When no shipping rates are available, you have several options:
+
+```typescript
+// Option 1: Show helpful message
+if (rates.length === 0) {
+  return <NoShippingAvailable address={shippingAddress} />;
+}
+
+// Option 2: Allow customer to contact store
+if (rates.length === 0) {
+  return (
+    <div>
+      <p>Shipping not available to your location.</p>
+      <a href="/contact">Request a shipping quote</a>
+    </div>
+  );
+}
+
+// Option 3: Validate before proceeding
+function canProceedToPayment(checkout: Checkout, rates: ShippingRate[]): boolean {
+  if (rates.length === 0) return false;
+  if (!checkout.shippingRateId) return false;
+  if (!checkout.email) return false;
+  return true;
+}
+```
+
 ---
 
 ### Customer Authentication
@@ -1726,6 +1947,7 @@ export default function ProductsPage() {
 'use client';
 import { useEffect, useState } from 'react';
 import { omni } from '@/lib/omni-sync';
+import { isHtmlDescription } from 'omni-sync-sdk';
 import type { Product } from 'omni-sync-sdk';
 
 export default function ProductPage({ params }: { params: { id: string } }) {
@@ -1791,9 +2013,9 @@ export default function ProductPage({ params }: { params: { id: string } }) {
           ${product.salePrice || product.basePrice}
         </p>
 
-        {/* Render description based on format (HTML from Shopify/WooCommerce, text otherwise) */}
+        {/* IMPORTANT: Use isHtmlDescription() to render HTML descriptions correctly */}
         {product.description && (
-          product.descriptionFormat === 'html' ? (
+          isHtmlDescription(product) ? (
             <div className="mt-4 text-gray-600" dangerouslySetInnerHTML={{ __html: product.description }} />
           ) : (
             <p className="mt-4 text-gray-600">{product.description}</p>
@@ -3010,7 +3232,7 @@ const handlePlaceOrder = () => {
 - **Use toast notifications (Sonner) for user feedback on actions**
 - Persist cart ID in localStorage
 - Persist customer token after login
-- **Check `descriptionFormat` and render HTML with `dangerouslySetInnerHTML` when format is `'html'`**
+- **Use `isHtmlDescription(product)` helper and render HTML with `dangerouslySetInnerHTML` when it returns true**
 - **Wrap SDK calls in try/catch and show error toasts**
 
 ### DON'T:
@@ -3020,7 +3242,7 @@ const handlePlaceOrder = () => {
 - Skip implementing required pages
 - Write `const products = [...]` - use the API!
 - Use `@apply group` in CSS - Tailwind doesn't allow 'group' in @apply. Use `className="group"` on the element instead
-- **Render `product.description` as plain text without checking `descriptionFormat` - HTML will show as raw tags!**
+- **Render `product.description` as plain text without using `isHtmlDescription()` - HTML will show as raw tags like `<p>`, `<ul>`, `<li>`!**
 
 ---