omni-sync-sdk 0.22.0 → 0.22.1

package/AI_BUILDER_PROMPT.md

@@ -519,8 +519,27 @@ providers.forEach (OAuth)            response.providers.forEach
 status === 'completed'               status === 'succeeded'
 product.metafields.name              product.metafields[0].definitionName
 product.metafields.key               product.metafields[0].definitionKey
+orderItem.unitPrice                  orderItem.price (OrderItem is FLAT, not nested!)
+cartItem.price                       cartItem.unitPrice (Cart/Checkout items use unitPrice)
+waitResult.orderNumber               waitResult.status.orderNumber (nested in PaymentStatus)
+variant.attributes.map(...)          Object.entries(variant.attributes || {}) (it's an object!)
+categorySuggestion.slug              // ❌ doesn't exist! Only: id, name, productCount
+order.status === 'COMPLETED'         order.status === 'delivered' (OrderStatus is lowercase!)
+getCartTotals(localCart)             // ❌ LocalCart has no subtotal! Calculate manually
+result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's a union type
 ```
 
+**Key distinctions:**
+
+- **OrderItem** (from orders): Flat structure — `item.price`, `item.name`, `item.image`
+- **CartItem / CheckoutLineItem**: Nested structure — `item.unitPrice`, `item.product.name`, `item.product.images`
+- **`getCartTotals()`** only works with **server Cart** (has `subtotal`/`discountAmount`). For **LocalCart**, calculate manually:
+  ```typescript
+  const subtotal = cart.items.reduce((sum, item) => sum + parseFloat(item.price || '0') * item.quantity, 0);
+  ```
+- **`GuestCheckoutStartResponse`** is a union type — always check `result.tracked` before accessing `result.checkoutId`
+- **`WaitForOrderResult`** has `result.status.orderNumber`, NOT `result.orderNumber`. But `completeGuestCheckout()` returns `GuestOrderResponse` which DOES have `result.orderNumber` directly.
+
 ---
 
 ## Full SDK Documentation