omni-sync-sdk 0.18.3 → 0.18.5

package/README.md

@@ -117,6 +117,97 @@ const { data: products } = await omni.getProducts();
 
 ---
 
+## Common Mistakes to Avoid
+
+> **AI Agents / Vibe-Coders:** Read this section carefully! These are common misunderstandings.
+
+### 1. All Types Are Exported - Don't Create Local Interfaces!
+
+```typescript
+// ❌ WRONG - Don't create these locally
+interface PaymentProvider { ... }
+interface ProductSuggestion { ... }
+
+// ✅ CORRECT - Import from SDK
+import {
+  PaymentProvider,           // or PaymentProviderConfig
+  ProductSuggestion,
+  CategorySuggestion,
+  SearchSuggestions,
+} from 'omni-sync-sdk';
+```
+
+### 2. formatPrice Expects Options Object
+
+```typescript
+// ❌ WRONG
+formatPrice(amount, 'USD');
+
+// ✅ CORRECT
+formatPrice(amount, { currency: 'USD' });
+```
+
+### 3. Order Fields - Use Correct Names
+
+```typescript
+// ❌ WRONG
+order.total;
+item.product.name;
+
+// ✅ CORRECT
+order.totalAmount; // or order.total (alias)
+item.name; // flat, not nested
+item.image; // flat, not nested
+```
+
+### 4. Payment Status is 'succeeded', not 'completed'
+
+```typescript
+// ❌ WRONG
+if (status.status === 'completed')
+
+// ✅ CORRECT
+if (status.status === 'succeeded')
+```
+
+### 5. ProductSuggestion vs Product - Different Types
+
+`getSearchSuggestions()` returns `ProductSuggestion[]`, NOT `Product[]`.
+This is intentional - suggestions are lightweight for autocomplete.
+
+```typescript
+// ProductSuggestion has:
+{
+  (id, name, slug, image, basePrice, salePrice, type);
+}
+
+// Product has many more fields
+```
+
+### 6. All Prices Are Strings - Use parseFloat()
+
+```typescript
+// ❌ WRONG - assuming number
+const total = item.price * quantity;
+
+// ✅ CORRECT - parse first
+const total = parseFloat(item.price) * quantity;
+
+// Or use SDK helper
+import { formatPrice } from 'omni-sync-sdk';
+const display = formatPrice(item.price, { currency: 'USD' });
+```
+
+### 7. Variant Attributes Are `Record<string, string>`
+
+```typescript
+// Accessing variant attributes:
+const color = variant.attributes?.['Color']; // string
+const size = variant.attributes?.['Size']; // string
+```
+
+---
+
 ## Checkout: Guest vs Logged-In Customer
 
 > **IMPORTANT:** There are TWO different checkout flows. You MUST use the correct one based on whether the customer is logged in or not.

package/dist/index.d.mts

@@ -150,6 +150,10 @@ interface Product {
     /** Product status (active, draft, archived). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
+    /**
+     * Whether product is downloadable/digital.
+     * @deprecated For read operations, check channels.WOOCOMMERCE.downloadable instead
+     */
     isDownloadable?: boolean;
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
@@ -165,6 +169,8 @@ interface Product {
         name: string;
     }>;
     tags?: string[];
+    /** Array of attribute option IDs for global assignments (admin mode only) */
+    attributes?: string[];
     metafields?: ProductMetafield[];
     channels?: Record<string, Record<string, unknown>>;
     /** Shopify product ID (admin mode only) */
@@ -173,8 +179,8 @@ interface Product {
     woocommerceProductId?: string | null;
     /** Meta/Facebook Item Group ID (admin mode only) */
     metaItemGroupId?: string | null;
-    /** Whether product needs sync to platforms (admin mode only) */
-    needsSync?: boolean;
+    /** Whether product needs sync to platforms. Always returned by backend. */
+    needsSync: boolean;
     /** Last sync timestamp (admin mode only) */
     lastSyncedAt?: string | null;
     /** Menu/display order */
@@ -226,6 +232,8 @@ interface ProductImage {
     size?: number;
     /** MIME type (admin mode only) */
     mimeType?: string;
+    /** Creation timestamp (admin mode only) */
+    createdAt?: string;
 }
 interface ProductVariant {
     id: string;
@@ -238,7 +246,7 @@ interface ProductVariant {
     /** Variant sale price as string. Use parseFloat() for calculations. */
     salePrice?: string | null;
     /** Variant attributes (e.g., { "Color": "Red", "Size": "M" }) */
-    attributes?: Record<string, unknown> | null;
+    attributes?: Record<string, string> | null;
     inventory?: InventoryInfo | null;
     /** Variant image URL or image object */
     image?: string | {
@@ -287,6 +295,8 @@ interface InventoryInfo {
      * false if trackingMode is DISABLED or if out of stock.
      */
     canPurchase: boolean;
+    /** Last inventory sync timestamp (admin mode only) */
+    lastInventorySyncAt?: string | null;
 }
 /**
  * Check if a product description contains HTML and should be rendered with dangerouslySetInnerHTML
@@ -672,6 +682,11 @@ interface Order {
     status: OrderStatus;
     /** Total amount as string (e.g., "99.99"). Use parseFloat() for calculations. */
     totalAmount: string;
+    /**
+     * Alias for totalAmount. Use parseFloat() for calculations.
+     * @example order.total || order.totalAmount
+     */
+    total?: string;
     /** Currency code (e.g., "USD", "ILS") */
     currency?: string;
     /** Customer info (may be null for guest orders) */
@@ -712,13 +727,15 @@ interface OrderItem {
     productId: string;
     variantId?: string;
     sku?: string;
+    /** Product name (flat, not nested under product object) */
     name?: string;
     quantity: number;
-    /** Price per unit as number */
-    price: number;
-    /** Unit price as string (for consistency with Cart/Checkout) */
-    unitPrice?: string;
-    /** Product image URL */
+    /**
+     * Price per unit as string (e.g., "29.99").
+     * Use parseFloat() for calculations.
+     */
+    price: string;
+    /** Product image URL (flat, not nested under product object) */
     image?: string;
 }
 interface OrderQueryParams {
@@ -1794,7 +1811,7 @@ type VariantStatus = 'active' | 'draft';
 interface CreateVariantDto {
     sku?: string;
     name?: string;
-    attributes?: Record<string, unknown>;
+    attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
     inventory?: number;
@@ -1805,7 +1822,7 @@ interface CreateVariantDto {
 interface UpdateVariantDto {
     sku?: string;
     name?: string;
-    attributes?: Record<string, unknown>;
+    attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
     image?: string | unknown;

package/dist/index.d.ts

@@ -150,6 +150,10 @@ interface Product {
     /** Product status (active, draft, archived). Always returned by backend. */
     status: string;
     type: 'SIMPLE' | 'VARIABLE';
+    /**
+     * Whether product is downloadable/digital.
+     * @deprecated For read operations, check channels.WOOCOMMERCE.downloadable instead
+     */
     isDownloadable?: boolean;
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
@@ -165,6 +169,8 @@ interface Product {
         name: string;
     }>;
     tags?: string[];
+    /** Array of attribute option IDs for global assignments (admin mode only) */
+    attributes?: string[];
     metafields?: ProductMetafield[];
     channels?: Record<string, Record<string, unknown>>;
     /** Shopify product ID (admin mode only) */
@@ -173,8 +179,8 @@ interface Product {
     woocommerceProductId?: string | null;
     /** Meta/Facebook Item Group ID (admin mode only) */
     metaItemGroupId?: string | null;
-    /** Whether product needs sync to platforms (admin mode only) */
-    needsSync?: boolean;
+    /** Whether product needs sync to platforms. Always returned by backend. */
+    needsSync: boolean;
     /** Last sync timestamp (admin mode only) */
     lastSyncedAt?: string | null;
     /** Menu/display order */
@@ -226,6 +232,8 @@ interface ProductImage {
     size?: number;
     /** MIME type (admin mode only) */
     mimeType?: string;
+    /** Creation timestamp (admin mode only) */
+    createdAt?: string;
 }
 interface ProductVariant {
     id: string;
@@ -238,7 +246,7 @@ interface ProductVariant {
     /** Variant sale price as string. Use parseFloat() for calculations. */
     salePrice?: string | null;
     /** Variant attributes (e.g., { "Color": "Red", "Size": "M" }) */
-    attributes?: Record<string, unknown> | null;
+    attributes?: Record<string, string> | null;
     inventory?: InventoryInfo | null;
     /** Variant image URL or image object */
     image?: string | {
@@ -287,6 +295,8 @@ interface InventoryInfo {
      * false if trackingMode is DISABLED or if out of stock.
      */
     canPurchase: boolean;
+    /** Last inventory sync timestamp (admin mode only) */
+    lastInventorySyncAt?: string | null;
 }
 /**
  * Check if a product description contains HTML and should be rendered with dangerouslySetInnerHTML
@@ -672,6 +682,11 @@ interface Order {
     status: OrderStatus;
     /** Total amount as string (e.g., "99.99"). Use parseFloat() for calculations. */
     totalAmount: string;
+    /**
+     * Alias for totalAmount. Use parseFloat() for calculations.
+     * @example order.total || order.totalAmount
+     */
+    total?: string;
     /** Currency code (e.g., "USD", "ILS") */
     currency?: string;
     /** Customer info (may be null for guest orders) */
@@ -712,13 +727,15 @@ interface OrderItem {
     productId: string;
     variantId?: string;
     sku?: string;
+    /** Product name (flat, not nested under product object) */
     name?: string;
     quantity: number;
-    /** Price per unit as number */
-    price: number;
-    /** Unit price as string (for consistency with Cart/Checkout) */
-    unitPrice?: string;
-    /** Product image URL */
+    /**
+     * Price per unit as string (e.g., "29.99").
+     * Use parseFloat() for calculations.
+     */
+    price: string;
+    /** Product image URL (flat, not nested under product object) */
     image?: string;
 }
 interface OrderQueryParams {
@@ -1794,7 +1811,7 @@ type VariantStatus = 'active' | 'draft';
 interface CreateVariantDto {
     sku?: string;
     name?: string;
-    attributes?: Record<string, unknown>;
+    attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
     inventory?: number;
@@ -1805,7 +1822,7 @@ interface CreateVariantDto {
 interface UpdateVariantDto {
     sku?: string;
     name?: string;
-    attributes?: Record<string, unknown>;
+    attributes?: Record<string, string>;
     price?: number;
     salePrice?: number;
     image?: string | unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "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",