omni-sync-sdk 0.21.3 → 0.21.4

package/README.md

@@ -148,23 +148,61 @@ const order = await omni.submitGuestOrder();
 - Guest user + Local cart → `startGuestCheckout()` or `submitGuestOrder()`
 - Logged-in user + Server cart → `createCheckout({ cartId })`
 
-### 2. All Types Are Exported - Don't Create Local Interfaces!
+### 2. ⛔ NEVER Create Local Interfaces - Use SDK Types!
+
+**This causes type errors and runtime bugs!**
 
 ```typescript
-// ❌ WRONG - Don't create these locally
-interface PaymentProvider { ... }
-interface ProductSuggestion { ... }
+// ❌ WRONG - Don't create your own interfaces!
+interface CartItem {
+  id: string;
+  name: string; // WRONG - it's item.product.name!
+  price: number; // WRONG - prices are strings!
+}
 
-// ✅ CORRECT - Import from SDK
-import {
-  PaymentProvider,           // or PaymentProviderConfig
+// ❌ WRONG - Don't use 'as unknown as' casting!
+const item = result as unknown as MyLocalType;
+
+// ✅ CORRECT - Import ALL types from SDK
+import type {
+  Product,
+  ProductVariant,
+  Cart,
+  CartItem,
+  Checkout,
+  CheckoutLineItem,
+  Order,
+  OrderItem,
+  CustomerProfile,
+  CustomerAddress,
+  ShippingRate,
+  PaymentProvider,
+  PaymentIntent,
+  PaymentStatus,
+  SearchSuggestions,
   ProductSuggestion,
   CategorySuggestion,
-  SearchSuggestions,
+  OAuthAuthorizeResponse,
+  CustomerOAuthProvider,
 } from 'omni-sync-sdk';
 ```
 
-### 2. formatPrice Expects Options Object
+**⚠️ SDK Type Facts - Trust These!**
+
+| What                     | Correct                       | Wrong                 |
+| ------------------------ | ----------------------------- | --------------------- |
+| Prices                   | `string` (use `parseFloat()`) | `number`              |
+| Cart item name           | `item.product.name`           | `item.name`           |
+| Order item name          | `item.name`                   | `item.product.name`   |
+| Cart item image          | `item.product.images[0]`      | `item.image`          |
+| Order item image         | `item.image`                  | `item.product.images` |
+| Address state/province   | `region`                      | `state` or `province` |
+| OAuth redirect URL       | `authorizationUrl`            | `url`                 |
+| OAuth providers response | `{ providers: [...] }`        | `[...]` directly      |
+
+**If you think a type is "wrong", YOU are wrong. Read the SDK types!**
+
+### 3. formatPrice Expects Options Object
 
 ```typescript
 // ❌ WRONG
@@ -174,7 +212,7 @@ formatPrice(amount, 'USD');
 formatPrice(amount, { currency: 'USD' });
 ```
 
-### 3. Cart/Checkout vs Order - Different Item Structures!
+### 4. Cart/Checkout vs Order - Different Item Structures!
 
 **IMPORTANT:** Cart and Checkout items have NESTED product data. Order items are FLAT.
 
@@ -200,7 +238,7 @@ order.items.forEach((item) => {
 | `CheckoutLineItem` | `item.product.name` | `item.product.images` |
 | `OrderItem`        | `item.name`         | `item.image`          |
 
-### 4. Payment Status is 'succeeded', not 'completed'
+### 5. Payment Status is 'succeeded', not 'completed'
 
 ```typescript
 // ❌ WRONG
@@ -210,7 +248,7 @@ if (status.status === 'completed')
 if (status.status === 'succeeded')
 ```
 
-### 5. ProductSuggestion vs Product - Different Types
+### 6. ProductSuggestion vs Product - Different Types
 
 `getSearchSuggestions()` returns `ProductSuggestion[]`, NOT `Product[]`.
 This is intentional - suggestions are lightweight for autocomplete.
@@ -224,7 +262,7 @@ This is intentional - suggestions are lightweight for autocomplete.
 // Product has many more fields
 ```
 
-### 6. All Prices Are Strings - Use parseFloat()
+### 7. All Prices Are Strings - Use parseFloat()
 
 ```typescript
 // ❌ WRONG - assuming number
@@ -238,7 +276,7 @@ import { formatPrice } from 'omni-sync-sdk';
 const display = formatPrice(item.price, { currency: 'USD' });
 ```
 
-### 7. Variant Attributes Are `Record<string, string>`
+### 8. Variant Attributes Are `Record<string, string>`
 
 ```typescript
 // Accessing variant attributes:
@@ -246,7 +284,7 @@ const color = variant.attributes?.['Color']; // string
 const size = variant.attributes?.['Size']; // string
 ```
 
-### 8. Address Uses `region`, NOT `state`
+### 9. Address Uses `region`, NOT `state`
 
 ```typescript
 // ❌ WRONG
@@ -266,7 +304,7 @@ const address: SetShippingAddressDto = {
 };
 ```
 
-### 9. OAuth - Use `authorizationUrl`, NOT `url`
+### 10. OAuth - Use `authorizationUrl`, NOT `url`
 
 ```typescript
 // ❌ WRONG
@@ -278,7 +316,7 @@ const response = await omni.getOAuthAuthorizeUrl('GOOGLE', { redirectUrl });
 window.location.href = response.authorizationUrl; // Correct property name
 ```
 
-### 10. OAuth Provider Type is Exported
+### 11. OAuth Provider Type is Exported
 
 ```typescript
 // ❌ WRONG - creating your own type
@@ -292,7 +330,7 @@ const provider: CustomerOAuthProvider = 'GOOGLE';
 await omni.getOAuthAuthorizeUrl(provider, { redirectUrl });
 ```
 
-### 11. getAvailableOAuthProviders Returns Object, Not Array
+### 12. getAvailableOAuthProviders Returns Object, Not Array
 
 ```typescript
 // ❌ WRONG - expecting array directly
@@ -304,7 +342,7 @@ const response = await omni.getAvailableOAuthProviders();
 response.providers.forEach(p => ...);  // response.providers is the array
 ```
 
-### 12. SDK Uses `null`, Not `undefined`
+### 13. SDK Uses `null`, Not `undefined`
 
 Optional fields in SDK types use `null`, not `undefined`:
 
@@ -320,7 +358,7 @@ if (product.slug !== null) {
 }
 ```
 
-### 13. Cart Has No `total` Field - Use `getCartTotals()` Helper
+### 14. Cart Has No `total` Field - Use `getCartTotals()` Helper
 
 ```typescript
 // ❌ WRONG - these fields don't exist on Cart
@@ -344,7 +382,7 @@ const total = subtotal - discount;
 - Cart has NO `total` field - use `getCartTotals()` or calculate
 - Checkout DOES have a `total` field, but Cart does not
 
-### 14. SearchSuggestions - Products Have `price`, Not `basePrice`
+### 15. SearchSuggestions - Products Have `price`, Not `basePrice`
 
 ```typescript
 // In SearchSuggestions, ProductSuggestion has:
@@ -358,7 +396,7 @@ suggestions.products.map(p => (
 ));
 ```
 
-### 15. Forgetting to Clear Cart After Payment
+### 16. Forgetting to Clear Cart After Payment
 
 **This causes "ghost items" in the cart after successful payment!**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Official SDK for building e-commerce storefronts with OmniSync Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",