omni-sync-sdk 0.22.2 → 0.22.3

package/AI_BUILDER_PROMPT.md

@@ -543,13 +543,16 @@ result.checkoutId (guest checkout)   // ⚠️ Check result.tracked first! It's
 - **`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.
 - **⚠️ HYDRATION: Never use `useState(omni.getLocalCart())`** in Next.js — causes hydration mismatch! Server has no localStorage (empty cart) but client does (real cart). Always start with empty state and load in `useEffect`:
+
   ```typescript
   // ❌ WRONG — hydration mismatch!
   const [cart, setCart] = useState(omni.getLocalCart());
 
   // ✅ CORRECT — load after hydration
   const [cart, setCart] = useState<LocalCart>({ items: [], updatedAt: '' });
-  useEffect(() => { setCart(omni.getLocalCart()); }, []);
+  useEffect(() => {
+    setCart(omni.getLocalCart());
+  }, []);
   ```
 
 ---

package/dist/index.d.mts

@@ -158,7 +158,11 @@ interface Product {
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
     variants?: ProductVariant[];
-    /** Categories as objects with id and name */
+    /**
+     * Categories as objects with `id` and `name`.
+     * NOT string[] - each category is `{ id: string; name: string }`.
+     * Access: `product.categories?.map(cat => cat.name)`
+     */
     categories?: Array<{
         id: string;
         name: string;
@@ -643,10 +647,17 @@ interface ProductQueryParams {
 /**
  * Product suggestion for autocomplete
  */
+/**
+ * Product suggestion for search autocomplete.
+ *
+ * **Note:** `slug` can be `null` - don't use it as a React key, use `id` instead.
+ */
 interface ProductSuggestion {
     id: string;
     name: string;
+    /** Can be null! Do NOT use as React key. Use `id` instead. */
     slug: string | null;
+    /** Can be null if product has no images */
     image: string | null;
     /** Effective price as string (salePrice if on sale, otherwise basePrice). */
     price: string;
@@ -657,7 +668,9 @@ interface ProductSuggestion {
     type: 'SIMPLE' | 'VARIABLE';
 }
 /**
- * Category suggestion for autocomplete
+ * Category suggestion for autocomplete.
+ *
+ * **Note:** This type has NO `slug` field - only `id`, `name`, `productCount`.
  */
 interface CategorySuggestion {
     id: string;
@@ -747,6 +760,10 @@ interface Order {
     platform?: string;
     createdAt: string;
 }
+/**
+ * Order status values are **lowercase**.
+ * Do NOT use uppercase values like 'COMPLETED' or 'CANCELLED'.
+ */
 type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
 interface OrderCustomer {
     email: string;
@@ -769,6 +786,24 @@ interface OrderAddress {
     country: string;
     phone?: string;
 }
+/**
+ * Order line item. **This is a flat structure** - unlike CartItem/CheckoutLineItem.
+ *
+ * **Common mistakes:**
+ * - This type has NO `id` field. Use `productId` + index as React key.
+ * - Access `item.name` directly (NOT `item.product.name` like CartItem).
+ * - Access `item.price` directly (NOT `item.unitPrice` like CartItem).
+ *
+ * @example
+ * ```typescript
+ * order.items.map((item, index) => (
+ *   <div key={`${item.productId}-${index}`}>
+ *     <span>{item.name}</span>
+ *     <span>{item.price}</span>
+ *   </div>
+ * ))
+ * ```
+ */
 interface OrderItem {
     productId: string;
     variantId?: string;
@@ -779,6 +814,8 @@ interface OrderItem {
     /**
      * Price per unit as string (e.g., "29.99").
      * Use parseFloat() for calculations.
+     *
+     * **Note:** This is `price`, not `unitPrice` (unlike CartItem/CheckoutLineItem).
      */
     price: string;
     /** Product image URL (flat, not nested under product object) */
@@ -1393,8 +1430,24 @@ interface LocalCartItem {
     addedAt: string;
 }
 /**
- * Local cart stored in localStorage/cookies
- * Complete client-side cart for guest users
+ * Local cart stored in localStorage/cookies.
+ * Complete client-side cart for guest users.
+ *
+ * **Initialization:** You can initialize with just `{ items: [] }`.
+ * All other fields are optional.
+ *
+ * **Note:** This is NOT the same as the server `Cart` type.
+ * - `getCartTotals()` does NOT work with LocalCart (use manual calculation)
+ * - Calculate total: `cart.items.reduce((sum, item) => sum + parseFloat(item.price || '0') * item.quantity, 0)`
+ *
+ * @example
+ * ```typescript
+ * // Simple initialization
+ * const [cart, setCart] = useState<LocalCart>({ items: [] });
+ *
+ * // Or with null initial state
+ * const [cart, setCart] = useState<LocalCart | null>(null);
+ * ```
  */
 interface LocalCart {
     items: LocalCartItem[];
@@ -1428,7 +1481,8 @@ interface LocalCart {
         phone?: string;
     };
     notes?: string;
-    updatedAt: string;
+    /** Last update timestamp. Optional - auto-set when you don't provide it. */
+    updatedAt?: string;
 }
 /**
  * DTO for creating order directly (guest checkout)
@@ -1485,6 +1539,25 @@ interface GuestOrderResponse {
  * If tracking is enabled, returns checkoutId and cartId
  * If tracking is not enabled, returns tracked: false
  */
+/**
+ * Response from starting guest checkout. **This is a discriminated union.**
+ *
+ * You MUST check `result.tracked` before accessing `checkoutId`:
+ * - `tracked: true` → has `checkoutId` and `cartId`
+ * - `tracked: false` → only has `message` (no checkoutId!)
+ *
+ * @example
+ * ```typescript
+ * const result = await omni.startGuestCheckout(cart);
+ * if (result.tracked) {
+ *   // Safe to access checkoutId and cartId
+ *   console.log(result.checkoutId, result.cartId);
+ * } else {
+ *   // Untracked checkout - no checkoutId available
+ *   console.log(result.message);
+ * }
+ * ```
+ */
 type GuestCheckoutStartResponse = {
     tracked: true;
     checkoutId: string;
@@ -2167,13 +2240,18 @@ interface CustomApiTestResult {
     error?: string;
 }
 /**
- * Payment provider configuration.
+ * Payment provider configuration (returned by `getPaymentProviders()`).
  * Contains only public information safe to expose in frontend.
+ *
+ * **Note:** `provider` is a flexible `string` (not an enum).
+ * Common values: `'stripe'`, `'paypal'`.
+ *
+ * **Alias:** `PaymentProvider` is the same type (use either name).
  */
 interface PaymentProviderConfig {
     /** Provider ID (use this when creating payment intents) */
     id: string;
-    /** Payment provider type: 'stripe', 'paypal' */
+    /** Payment provider type: 'stripe', 'paypal' (flexible string, not enum) */
     provider: string;
     /** Display name for the provider */
     name: string;
@@ -2188,7 +2266,10 @@ interface PaymentProviderConfig {
     /** Whether this is the default provider */
     isDefault: boolean;
 }
-/** Alias for PaymentProviderConfig for convenience */
+/**
+ * Alias for `PaymentProviderConfig`.
+ * Both types are identical - use whichever name you prefer.
+ */
 type PaymentProvider = PaymentProviderConfig;
 /**
  * All available payment providers for a store.
@@ -2303,12 +2384,31 @@ interface WaitForOrderOptions {
     onPollAttempt?: (attempt: number, status: PaymentStatus) => void;
 }
 /**
- * Result from waitForOrder method.
+ * Result from `waitForOrder()` method.
+ *
+ * **Important:** `status` is a `PaymentStatus` object, NOT a string.
+ * Access order number via `result.status.orderNumber`.
+ *
+ * For `completeGuestCheckout()`, use `GuestOrderResponse` instead
+ * which has `result.orderNumber` directly.
+ *
+ * @example
+ * ```typescript
+ * const result = await omni.waitForOrder(checkoutId);
+ * if (result.success) {
+ *   const orderNumber = result.status.orderNumber; // e.g., "ORD-20260201-0001"
+ *   const orderId = result.status.orderId;
+ * }
+ * ```
  */
 interface WaitForOrderResult {
     /** Whether the order was created within the timeout */
     success: boolean;
-    /** Final payment status */
+    /**
+     * Final payment status object.
+     * Access order number: `result.status.orderNumber`
+     * Access order ID: `result.status.orderId`
+     */
     status: PaymentStatus;
     /** Number of poll attempts made */
     attempts: number;
@@ -4272,15 +4372,19 @@ declare class OmniSyncClient {
      */
     removeCoupon(cartId: string): Promise<Cart>;
     /**
-     * Link a cart to the currently logged-in customer
-     * Use this after customer logs in to associate their guest cart with their account
-     * Requires customer token to be set via setCustomerToken()
+     * Link a cart to the currently logged-in customer.
+     * Use this after customer logs in to associate their guest cart with their account.
+     * Requires customer token to be set via setCustomerToken().
+     *
+     * **Important:** `cartId` is required - this is NOT a no-arg method.
+     *
+     * @param cartId - The cart ID to link (e.g., from a guest cart)
      *
      * @example
      * ```typescript
      * // After customer logs in
      * omni.setCustomerToken(authResponse.token);
-     * const cart = await omni.linkCart('cart_123');
+     * const cart = await omni.linkCart('cart_123'); // cartId is REQUIRED
      * // Cart is now linked to the customer
      * ```
      */

package/dist/index.d.ts

@@ -158,7 +158,11 @@ interface Product {
     images?: ProductImage[];
     inventory?: InventoryInfo | null;
     variants?: ProductVariant[];
-    /** Categories as objects with id and name */
+    /**
+     * Categories as objects with `id` and `name`.
+     * NOT string[] - each category is `{ id: string; name: string }`.
+     * Access: `product.categories?.map(cat => cat.name)`
+     */
     categories?: Array<{
         id: string;
         name: string;
@@ -643,10 +647,17 @@ interface ProductQueryParams {
 /**
  * Product suggestion for autocomplete
  */
+/**
+ * Product suggestion for search autocomplete.
+ *
+ * **Note:** `slug` can be `null` - don't use it as a React key, use `id` instead.
+ */
 interface ProductSuggestion {
     id: string;
     name: string;
+    /** Can be null! Do NOT use as React key. Use `id` instead. */
     slug: string | null;
+    /** Can be null if product has no images */
     image: string | null;
     /** Effective price as string (salePrice if on sale, otherwise basePrice). */
     price: string;
@@ -657,7 +668,9 @@ interface ProductSuggestion {
     type: 'SIMPLE' | 'VARIABLE';
 }
 /**
- * Category suggestion for autocomplete
+ * Category suggestion for autocomplete.
+ *
+ * **Note:** This type has NO `slug` field - only `id`, `name`, `productCount`.
  */
 interface CategorySuggestion {
     id: string;
@@ -747,6 +760,10 @@ interface Order {
     platform?: string;
     createdAt: string;
 }
+/**
+ * Order status values are **lowercase**.
+ * Do NOT use uppercase values like 'COMPLETED' or 'CANCELLED'.
+ */
 type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
 interface OrderCustomer {
     email: string;
@@ -769,6 +786,24 @@ interface OrderAddress {
     country: string;
     phone?: string;
 }
+/**
+ * Order line item. **This is a flat structure** - unlike CartItem/CheckoutLineItem.
+ *
+ * **Common mistakes:**
+ * - This type has NO `id` field. Use `productId` + index as React key.
+ * - Access `item.name` directly (NOT `item.product.name` like CartItem).
+ * - Access `item.price` directly (NOT `item.unitPrice` like CartItem).
+ *
+ * @example
+ * ```typescript
+ * order.items.map((item, index) => (
+ *   <div key={`${item.productId}-${index}`}>
+ *     <span>{item.name}</span>
+ *     <span>{item.price}</span>
+ *   </div>
+ * ))
+ * ```
+ */
 interface OrderItem {
     productId: string;
     variantId?: string;
@@ -779,6 +814,8 @@ interface OrderItem {
     /**
      * Price per unit as string (e.g., "29.99").
      * Use parseFloat() for calculations.
+     *
+     * **Note:** This is `price`, not `unitPrice` (unlike CartItem/CheckoutLineItem).
      */
     price: string;
     /** Product image URL (flat, not nested under product object) */
@@ -1393,8 +1430,24 @@ interface LocalCartItem {
     addedAt: string;
 }
 /**
- * Local cart stored in localStorage/cookies
- * Complete client-side cart for guest users
+ * Local cart stored in localStorage/cookies.
+ * Complete client-side cart for guest users.
+ *
+ * **Initialization:** You can initialize with just `{ items: [] }`.
+ * All other fields are optional.
+ *
+ * **Note:** This is NOT the same as the server `Cart` type.
+ * - `getCartTotals()` does NOT work with LocalCart (use manual calculation)
+ * - Calculate total: `cart.items.reduce((sum, item) => sum + parseFloat(item.price || '0') * item.quantity, 0)`
+ *
+ * @example
+ * ```typescript
+ * // Simple initialization
+ * const [cart, setCart] = useState<LocalCart>({ items: [] });
+ *
+ * // Or with null initial state
+ * const [cart, setCart] = useState<LocalCart | null>(null);
+ * ```
  */
 interface LocalCart {
     items: LocalCartItem[];
@@ -1428,7 +1481,8 @@ interface LocalCart {
         phone?: string;
     };
     notes?: string;
-    updatedAt: string;
+    /** Last update timestamp. Optional - auto-set when you don't provide it. */
+    updatedAt?: string;
 }
 /**
  * DTO for creating order directly (guest checkout)
@@ -1485,6 +1539,25 @@ interface GuestOrderResponse {
  * If tracking is enabled, returns checkoutId and cartId
  * If tracking is not enabled, returns tracked: false
  */
+/**
+ * Response from starting guest checkout. **This is a discriminated union.**
+ *
+ * You MUST check `result.tracked` before accessing `checkoutId`:
+ * - `tracked: true` → has `checkoutId` and `cartId`
+ * - `tracked: false` → only has `message` (no checkoutId!)
+ *
+ * @example
+ * ```typescript
+ * const result = await omni.startGuestCheckout(cart);
+ * if (result.tracked) {
+ *   // Safe to access checkoutId and cartId
+ *   console.log(result.checkoutId, result.cartId);
+ * } else {
+ *   // Untracked checkout - no checkoutId available
+ *   console.log(result.message);
+ * }
+ * ```
+ */
 type GuestCheckoutStartResponse = {
     tracked: true;
     checkoutId: string;
@@ -2167,13 +2240,18 @@ interface CustomApiTestResult {
     error?: string;
 }
 /**
- * Payment provider configuration.
+ * Payment provider configuration (returned by `getPaymentProviders()`).
  * Contains only public information safe to expose in frontend.
+ *
+ * **Note:** `provider` is a flexible `string` (not an enum).
+ * Common values: `'stripe'`, `'paypal'`.
+ *
+ * **Alias:** `PaymentProvider` is the same type (use either name).
  */
 interface PaymentProviderConfig {
     /** Provider ID (use this when creating payment intents) */
     id: string;
-    /** Payment provider type: 'stripe', 'paypal' */
+    /** Payment provider type: 'stripe', 'paypal' (flexible string, not enum) */
     provider: string;
     /** Display name for the provider */
     name: string;
@@ -2188,7 +2266,10 @@ interface PaymentProviderConfig {
     /** Whether this is the default provider */
     isDefault: boolean;
 }
-/** Alias for PaymentProviderConfig for convenience */
+/**
+ * Alias for `PaymentProviderConfig`.
+ * Both types are identical - use whichever name you prefer.
+ */
 type PaymentProvider = PaymentProviderConfig;
 /**
  * All available payment providers for a store.
@@ -2303,12 +2384,31 @@ interface WaitForOrderOptions {
     onPollAttempt?: (attempt: number, status: PaymentStatus) => void;
 }
 /**
- * Result from waitForOrder method.
+ * Result from `waitForOrder()` method.
+ *
+ * **Important:** `status` is a `PaymentStatus` object, NOT a string.
+ * Access order number via `result.status.orderNumber`.
+ *
+ * For `completeGuestCheckout()`, use `GuestOrderResponse` instead
+ * which has `result.orderNumber` directly.
+ *
+ * @example
+ * ```typescript
+ * const result = await omni.waitForOrder(checkoutId);
+ * if (result.success) {
+ *   const orderNumber = result.status.orderNumber; // e.g., "ORD-20260201-0001"
+ *   const orderId = result.status.orderId;
+ * }
+ * ```
  */
 interface WaitForOrderResult {
     /** Whether the order was created within the timeout */
     success: boolean;
-    /** Final payment status */
+    /**
+     * Final payment status object.
+     * Access order number: `result.status.orderNumber`
+     * Access order ID: `result.status.orderId`
+     */
     status: PaymentStatus;
     /** Number of poll attempts made */
     attempts: number;
@@ -4272,15 +4372,19 @@ declare class OmniSyncClient {
      */
     removeCoupon(cartId: string): Promise<Cart>;
     /**
-     * Link a cart to the currently logged-in customer
-     * Use this after customer logs in to associate their guest cart with their account
-     * Requires customer token to be set via setCustomerToken()
+     * Link a cart to the currently logged-in customer.
+     * Use this after customer logs in to associate their guest cart with their account.
+     * Requires customer token to be set via setCustomerToken().
+     *
+     * **Important:** `cartId` is required - this is NOT a no-arg method.
+     *
+     * @param cartId - The cart ID to link (e.g., from a guest cart)
      *
      * @example
      * ```typescript
      * // After customer logs in
      * omni.setCustomerToken(authResponse.token);
-     * const cart = await omni.linkCart('cart_123');
+     * const cart = await omni.linkCart('cart_123'); // cartId is REQUIRED
      * // Cart is now linked to the customer
      * ```
      */

package/dist/index.js

@@ -1960,15 +1960,19 @@ var OmniSyncClient = class {
     return this.adminRequest("DELETE", `/api/v1/cart/${cartId}/coupon`);
   }
   /**
-   * Link a cart to the currently logged-in customer
-   * Use this after customer logs in to associate their guest cart with their account
-   * Requires customer token to be set via setCustomerToken()
+   * Link a cart to the currently logged-in customer.
+   * Use this after customer logs in to associate their guest cart with their account.
+   * Requires customer token to be set via setCustomerToken().
+   *
+   * **Important:** `cartId` is required - this is NOT a no-arg method.
+   *
+   * @param cartId - The cart ID to link (e.g., from a guest cart)
    *
    * @example
    * ```typescript
    * // After customer logs in
    * omni.setCustomerToken(authResponse.token);
-   * const cart = await omni.linkCart('cart_123');
+   * const cart = await omni.linkCart('cart_123'); // cartId is REQUIRED
    * // Cart is now linked to the customer
    * ```
    */
@@ -2848,8 +2852,8 @@ var OmniSyncClient = class {
       })),
       itemCount: localCart.items.reduce((sum, i) => sum + i.quantity, 0),
       expiresAt: null,
-      createdAt: localCart.updatedAt,
-      updatedAt: localCart.updatedAt
+      createdAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
     };
   }
   /**

package/dist/index.mjs

@@ -1920,15 +1920,19 @@ var OmniSyncClient = class {
     return this.adminRequest("DELETE", `/api/v1/cart/${cartId}/coupon`);
   }
   /**
-   * Link a cart to the currently logged-in customer
-   * Use this after customer logs in to associate their guest cart with their account
-   * Requires customer token to be set via setCustomerToken()
+   * Link a cart to the currently logged-in customer.
+   * Use this after customer logs in to associate their guest cart with their account.
+   * Requires customer token to be set via setCustomerToken().
+   *
+   * **Important:** `cartId` is required - this is NOT a no-arg method.
+   *
+   * @param cartId - The cart ID to link (e.g., from a guest cart)
    *
    * @example
    * ```typescript
    * // After customer logs in
    * omni.setCustomerToken(authResponse.token);
-   * const cart = await omni.linkCart('cart_123');
+   * const cart = await omni.linkCart('cart_123'); // cartId is REQUIRED
    * // Cart is now linked to the customer
    * ```
    */
@@ -2808,8 +2812,8 @@ var OmniSyncClient = class {
       })),
       itemCount: localCart.items.reduce((sum, i) => sum + i.quantity, 0),
       expiresAt: null,
-      createdAt: localCart.updatedAt,
-      updatedAt: localCart.updatedAt
+      createdAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString(),
+      updatedAt: localCart.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
     };
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.22.2",
+  "version": "0.22.3",
   "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",
@@ -17,14 +17,6 @@
     "README.md",
     "AI_BUILDER_PROMPT.md"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "eslint \"src/**/*.ts\"",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "omni-sync",
     "e-commerce",
@@ -73,5 +65,12 @@
     "typescript": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}