omni-sync-sdk 0.16.2 → 0.17.2

package/README.md

@@ -26,15 +26,26 @@ The SDK exports these utility functions for common UI tasks:
 | `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                | Same as above                                  |
 | `getDescriptionContent(product)`               | Get product description (HTML or text) | `getDescriptionContent(product)`               |
 | `isHtmlDescription(product)`                   | Check if description is HTML           | `isHtmlDescription(product)` → `true/false`    |
-| `getStockStatus(variant)`                      | Get human-readable stock status        | `getStockStatus(variant)` → `"In Stock"`       |
+| `getStockStatus(inventory)`                    | Get human-readable stock status        | `getStockStatus(inventory)` → `"In Stock"`     |
+| `getProductPrice(product)`                     | Get effective price (handles sales)    | `getProductPrice(product)` → `29.99`           |
+| `getProductPriceInfo(product)`                 | Get price + sale info + discount %     | `{ price, isOnSale, discountPercent }`         |
+| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback        | `getVariantPrice(variant, '29.99')` → `34.99`  |
+| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total | `{ subtotal, discount, shipping, total }`      |
+| `getCartItemName(item)`                        | Get name from nested cart item         | `getCartItemName(item)` → `"Blue T-Shirt"`     |
+| `getCartItemImage(item)`                       | Get image URL from cart item           | `getCartItemImage(item)` → `"https://..."`     |
+| `getVariantOptions(variant)`                   | Get variant attributes as array        | `[{ name: "Color", value: "Red" }]`            |
 | `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                | `isCouponApplicableToProduct(coupon, product)` |
 
 ```typescript
 import {
   formatPrice,
-  getPriceDisplay, // Alias for formatPrice
   getDescriptionContent,
   getStockStatus,
+  getProductPrice,
+  getProductPriceInfo,
+  getCartTotals,
+  getCartItemName,
+  getCartItemImage,
 } from 'omni-sync-sdk';
 
 // Format price for display
@@ -44,9 +55,26 @@ const priceText = formatPrice(product.basePrice, 'USD'); // "$99.99"
 const description = getDescriptionContent(product);
 
 // Get stock status text
-const stockText = getStockStatus(product.variants[0]); // "In Stock", "Low Stock", "Out of Stock"
+const stockText = getStockStatus(product.inventory); // "In Stock", "Low Stock", "Out of Stock"
+
+// Get effective price (handles sale prices automatically)
+const price = getProductPrice(product); // Returns number: 29.99
+
+// Get full price info including sale status
+const priceInfo = getProductPriceInfo(product);
+// { price: 19.99, originalPrice: 29.99, isOnSale: true, discountPercent: 33 }
+
+// Calculate cart totals
+const totals = getCartTotals(cart, shippingRate?.price);
+// { subtotal: 59.98, discount: 10, shipping: 5.99, total: 55.97 }
+
+// Access cart item details (handles nested structure)
+const itemName = getCartItemName(cartItem); // "Blue T-Shirt - Large"
+const itemImage = getCartItemImage(cartItem); // "https://..."
 ```
 
+> **⚠️ DO NOT CREATE YOUR OWN UTILITY FILES!** All helper functions above are exported from `omni-sync-sdk`. Never create `utils/format.ts`, `lib/helpers.ts`, or similar files - use the SDK exports directly.
+
 ---
 
 ## ⚠️ CRITICAL: Payment Integration Required!
@@ -440,9 +468,9 @@ const response: PaginatedResponse<Product> = await omni.getProducts({
   sortOrder: 'desc', // Optional: 'asc' | 'desc'
 });
 
-console.log(response.items); // Product[]
-console.log(response.total); // Total number of products
-console.log(response.totalPages); // Total pages
+console.log(response.data); // Product[]
+console.log(response.meta.total); // Total number of products
+console.log(response.meta.totalPages); // Total pages
 ```
 
 #### Get Single Product
@@ -2306,8 +2334,8 @@ export default function ProductsPage() {
         <button onClick={() => setPage(p => Math.max(1, p - 1))} disabled={page === 1}>
           Previous
         </button>
-        <span>Page {data.page} of {data.totalPages}</span>
-        <button onClick={() => setPage(p => p + 1)} disabled={page >= data.totalPages}>
+        <span>Page {data.meta.page} of {data.meta.totalPages}</span>
+        <button onClick={() => setPage(p => p + 1)} disabled={page >= data.meta.totalPages}>
           Next
         </button>
       </div>
@@ -3205,7 +3233,7 @@ export default function AccountPage() {
           omni.getMyOrders({ limit: 10 }),
         ]);
         setProfile(p);
-        setOrders(o.items);
+        setOrders(o.data);
       } finally {
         setLoading(false);
       }

package/dist/index.d.mts

@@ -148,6 +148,8 @@ interface ProductImage {
     url: string;
     position?: number;
     isMain?: boolean;
+    /** Alt text for accessibility */
+    alt?: string;
 }
 interface ProductVariant {
     id: string;
@@ -160,6 +162,14 @@ interface ProductVariant {
     /** Variant attributes (e.g., { "Color": "Red", "Size": "M" }) */
     attributes?: Record<string, unknown>;
     inventory?: InventoryInfo | null;
+    /** Variant image URL or image object */
+    image?: string | {
+        url: string;
+    } | null;
+    /** Display position/order for sorting variants */
+    position?: number;
+    /** Variant status */
+    status?: 'active' | 'draft' | 'archived';
 }
 /**
  * Inventory tracking mode determines how stock is managed:
@@ -328,6 +338,155 @@ interface FormatPriceOptions {
  * ```
  */
 declare function formatPrice(priceString: string | undefined | null, options?: FormatPriceOptions): string | number;
+/**
+ * Get the effective price of a product (sale price if on sale, otherwise base price).
+ * Returns the price as a NUMBER, not string.
+ *
+ * @param product - Product or object with basePrice and optional salePrice
+ * @returns The effective price as a number
+ *
+ * @example
+ * ```typescript
+ * const product = await omni.getProduct('prod_123');
+ * const price = getProductPrice(product); // Returns number, e.g., 29.99
+ *
+ * // Check if on sale
+ * const { price, isOnSale, originalPrice } = getProductPriceInfo(product);
+ * ```
+ */
+declare function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice'> | null | undefined): number;
+/**
+ * Get detailed price information for a product including sale status.
+ *
+ * @param product - Product or object with basePrice and optional salePrice
+ * @returns Object with price, originalPrice, isOnSale, and discount info
+ *
+ * @example
+ * ```typescript
+ * const info = getProductPriceInfo(product);
+ * // info = {
+ * //   price: 19.99,           // Current/effective price
+ * //   originalPrice: 29.99,   // Original price (same as price if not on sale)
+ * //   isOnSale: true,
+ * //   discountAmount: 10,     // How much is saved
+ * //   discountPercent: 33     // Percentage off (rounded)
+ * // }
+ *
+ * // In React component:
+ * if (info.isOnSale) {
+ *   return (
+ *     <div>
+ *       <span className="text-red-600">${info.price}</span>
+ *       <span className="line-through">${info.originalPrice}</span>
+ *       <span className="badge">-{info.discountPercent}%</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice'> | null | undefined): {
+    price: number;
+    originalPrice: number;
+    isOnSale: boolean;
+    discountAmount: number;
+    discountPercent: number;
+};
+/**
+ * Get the price of a variant, falling back to product base price if not set.
+ * Returns the price as a NUMBER.
+ *
+ * @param variant - The product variant
+ * @param productBasePrice - The product's base price as fallback
+ * @returns The variant price as a number
+ *
+ * @example
+ * ```typescript
+ * product.variants?.forEach(variant => {
+ *   const price = getVariantPrice(variant, product.basePrice);
+ *   console.log(`${variant.name}: $${price}`);
+ * });
+ * ```
+ */
+declare function getVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice'> | null | undefined, productBasePrice: string): number;
+/**
+ * Calculate the total for a cart.
+ * Cart does NOT have a 'total' field - use this helper!
+ *
+ * @param cart - The cart object
+ * @param shippingPrice - Optional shipping price (string or number)
+ * @returns Object with subtotal, discount, shipping, and total
+ *
+ * @example
+ * ```typescript
+ * const cart = await omni.getCart(cartId);
+ * const totals = getCartTotals(cart);
+ * // totals = { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
+ *
+ * // With shipping
+ * const totals = getCartTotals(cart, selectedRate?.price);
+ * // totals = { subtotal: 59.98, discount: 0, shipping: 5.99, total: 65.97 }
+ * ```
+ */
+declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> | null | undefined, shippingPrice?: string | number | null): {
+    subtotal: number;
+    discount: number;
+    shipping: number;
+    total: number;
+};
+/**
+ * Get the display name for a cart item.
+ * Handles the nested product/variant structure - uses variant name if available,
+ * otherwise falls back to product name.
+ *
+ * @param item - The cart item
+ * @returns The display name for the item
+ *
+ * @example
+ * ```typescript
+ * cart.items.forEach(item => {
+ *   const name = getCartItemName(item);
+ *   console.log(`${name} x ${item.quantity}`);
+ * });
+ * ```
+ */
+declare function getCartItemName(item: CartItem): string;
+/**
+ * Get the image URL for a cart item.
+ * Checks variant image first, then falls back to the first product image.
+ *
+ * @param item - The cart item
+ * @returns The image URL or undefined if no image exists
+ *
+ * @example
+ * ```typescript
+ * const imageUrl = getCartItemImage(item);
+ * if (imageUrl) {
+ *   return <img src={imageUrl} alt={getCartItemName(item)} />;
+ * }
+ * ```
+ */
+declare function getCartItemImage(item: CartItem): string | undefined;
+/**
+ * Convert variant attributes to an array of name/value pairs.
+ * Transforms { "Color": "Red", "Size": "M" } to [{ name: "Color", value: "Red" }, ...]
+ *
+ * @param variant - The product variant (or object with attributes)
+ * @returns Array of { name, value } objects
+ *
+ * @example
+ * ```typescript
+ * const options = getVariantOptions(selectedVariant);
+ * // options = [{ name: "Color", value: "Red" }, { name: "Size", value: "M" }]
+ *
+ * options.forEach(opt => {
+ *   console.log(`${opt.name}: ${opt.value}`);
+ * });
+ * ```
+ */
+declare function getVariantOptions(variant: Pick<ProductVariant, 'attributes'> | null | undefined): Array<{
+    name: string;
+    value: string;
+}>;
 interface ProductQueryParams {
     page?: number;
     limit?: number;
@@ -419,10 +578,22 @@ interface UpdateProductDto {
 interface Order {
     id: string;
     externalId?: string;
+    /** Human-readable order number (e.g., "#1001") */
+    orderNumber?: string;
     status: OrderStatus;
-    totalAmount: number;
-    customer: OrderCustomer;
+    /** Total amount as string (e.g., "99.99"). Use parseFloat() for calculations. */
+    totalAmount: string;
+    /** Currency code (e.g., "USD", "ILS") */
+    currency?: string;
+    /** Customer info (may be null for guest orders) */
+    customer?: OrderCustomer | null;
     items: OrderItem[];
+    /** Number of items in the order */
+    itemCount?: number;
+    /** Shipping address for the order */
+    shippingAddress?: OrderAddress;
+    /** Billing address for the order */
+    billingAddress?: OrderAddress;
     platform?: string;
     createdAt: string;
 }
@@ -434,20 +605,32 @@ interface OrderCustomer {
     address?: OrderAddress;
 }
 interface OrderAddress {
+    firstName?: string;
+    lastName?: string;
+    company?: string;
     line1: string;
     line2?: string;
     city: string;
+    /** State/Province (alias: use `state` or `region`) */
     state?: string;
+    /** Region/Province (alias: use `state` or `region`) */
+    region?: string;
     postalCode: string;
     country: string;
+    phone?: string;
 }
 interface OrderItem {
     productId: string;
+    variantId?: string;
     sku?: string;
     name?: string;
     quantity: number;
+    /** Price per unit as number */
     price: number;
-    variantId?: string;
+    /** Unit price as string (for consistency with Cart/Checkout) */
+    unitPrice?: string;
+    /** Product image URL */
+    image?: string;
 }
 interface OrderQueryParams {
     page?: number;
@@ -1995,6 +2178,11 @@ declare class OmniSyncClient {
     private readonly timeout;
     private customerToken;
     private customerCartId;
+    /**
+     * Virtual cart ID used for localStorage carts (guest users not logged in).
+     * When a cart has this ID, operations use localStorage instead of server API.
+     */
+    private readonly VIRTUAL_LOCAL_CART_ID;
     private readonly onAuthError?;
     constructor(options: OmniSyncClientOptions);
     /**
@@ -3454,6 +3642,16 @@ declare class OmniSyncClient {
      * Save local cart to localStorage
      */
     private saveLocalCart;
+    /**
+     * Calculate subtotal for a local cart
+     */
+    private calculateLocalCartSubtotal;
+    /**
+     * Convert LocalCart to Cart format for consistent API.
+     * This allows cart methods to return the same Cart type regardless
+     * of whether data is stored locally or on the server.
+     */
+    private localCartToCart;
     /**
      * Add item to local cart (NO API call)
      * If item already exists, updates quantity
@@ -3923,4 +4121,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
  */
 declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentConfig, type PaymentIntent, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, formatPrice, getDescriptionContent, formatPrice as getPriceDisplay, getStockStatus, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentConfig, type PaymentIntent, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductAvailability, type ProductImage, type ProductMetafield, type ProductQueryParams, type ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type SearchSuggestions, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type SyncJob, type TaxBreakdown, type TaxBreakdownItem, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductPrice, getProductPriceInfo, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.d.ts

@@ -148,6 +148,8 @@ interface ProductImage {
     url: string;
     position?: number;
     isMain?: boolean;
+    /** Alt text for accessibility */
+    alt?: string;
 }
 interface ProductVariant {
     id: string;
@@ -160,6 +162,14 @@ interface ProductVariant {
     /** Variant attributes (e.g., { "Color": "Red", "Size": "M" }) */
     attributes?: Record<string, unknown>;
     inventory?: InventoryInfo | null;
+    /** Variant image URL or image object */
+    image?: string | {
+        url: string;
+    } | null;
+    /** Display position/order for sorting variants */
+    position?: number;
+    /** Variant status */
+    status?: 'active' | 'draft' | 'archived';
 }
 /**
  * Inventory tracking mode determines how stock is managed:
@@ -328,6 +338,155 @@ interface FormatPriceOptions {
  * ```
  */
 declare function formatPrice(priceString: string | undefined | null, options?: FormatPriceOptions): string | number;
+/**
+ * Get the effective price of a product (sale price if on sale, otherwise base price).
+ * Returns the price as a NUMBER, not string.
+ *
+ * @param product - Product or object with basePrice and optional salePrice
+ * @returns The effective price as a number
+ *
+ * @example
+ * ```typescript
+ * const product = await omni.getProduct('prod_123');
+ * const price = getProductPrice(product); // Returns number, e.g., 29.99
+ *
+ * // Check if on sale
+ * const { price, isOnSale, originalPrice } = getProductPriceInfo(product);
+ * ```
+ */
+declare function getProductPrice(product: Pick<Product, 'basePrice' | 'salePrice'> | null | undefined): number;
+/**
+ * Get detailed price information for a product including sale status.
+ *
+ * @param product - Product or object with basePrice and optional salePrice
+ * @returns Object with price, originalPrice, isOnSale, and discount info
+ *
+ * @example
+ * ```typescript
+ * const info = getProductPriceInfo(product);
+ * // info = {
+ * //   price: 19.99,           // Current/effective price
+ * //   originalPrice: 29.99,   // Original price (same as price if not on sale)
+ * //   isOnSale: true,
+ * //   discountAmount: 10,     // How much is saved
+ * //   discountPercent: 33     // Percentage off (rounded)
+ * // }
+ *
+ * // In React component:
+ * if (info.isOnSale) {
+ *   return (
+ *     <div>
+ *       <span className="text-red-600">${info.price}</span>
+ *       <span className="line-through">${info.originalPrice}</span>
+ *       <span className="badge">-{info.discountPercent}%</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function getProductPriceInfo(product: Pick<Product, 'basePrice' | 'salePrice'> | null | undefined): {
+    price: number;
+    originalPrice: number;
+    isOnSale: boolean;
+    discountAmount: number;
+    discountPercent: number;
+};
+/**
+ * Get the price of a variant, falling back to product base price if not set.
+ * Returns the price as a NUMBER.
+ *
+ * @param variant - The product variant
+ * @param productBasePrice - The product's base price as fallback
+ * @returns The variant price as a number
+ *
+ * @example
+ * ```typescript
+ * product.variants?.forEach(variant => {
+ *   const price = getVariantPrice(variant, product.basePrice);
+ *   console.log(`${variant.name}: $${price}`);
+ * });
+ * ```
+ */
+declare function getVariantPrice(variant: Pick<ProductVariant, 'price' | 'salePrice'> | null | undefined, productBasePrice: string): number;
+/**
+ * Calculate the total for a cart.
+ * Cart does NOT have a 'total' field - use this helper!
+ *
+ * @param cart - The cart object
+ * @param shippingPrice - Optional shipping price (string or number)
+ * @returns Object with subtotal, discount, shipping, and total
+ *
+ * @example
+ * ```typescript
+ * const cart = await omni.getCart(cartId);
+ * const totals = getCartTotals(cart);
+ * // totals = { subtotal: 59.98, discount: 10, shipping: 0, total: 49.98 }
+ *
+ * // With shipping
+ * const totals = getCartTotals(cart, selectedRate?.price);
+ * // totals = { subtotal: 59.98, discount: 0, shipping: 5.99, total: 65.97 }
+ * ```
+ */
+declare function getCartTotals(cart: Pick<Cart, 'subtotal' | 'discountAmount'> | null | undefined, shippingPrice?: string | number | null): {
+    subtotal: number;
+    discount: number;
+    shipping: number;
+    total: number;
+};
+/**
+ * Get the display name for a cart item.
+ * Handles the nested product/variant structure - uses variant name if available,
+ * otherwise falls back to product name.
+ *
+ * @param item - The cart item
+ * @returns The display name for the item
+ *
+ * @example
+ * ```typescript
+ * cart.items.forEach(item => {
+ *   const name = getCartItemName(item);
+ *   console.log(`${name} x ${item.quantity}`);
+ * });
+ * ```
+ */
+declare function getCartItemName(item: CartItem): string;
+/**
+ * Get the image URL for a cart item.
+ * Checks variant image first, then falls back to the first product image.
+ *
+ * @param item - The cart item
+ * @returns The image URL or undefined if no image exists
+ *
+ * @example
+ * ```typescript
+ * const imageUrl = getCartItemImage(item);
+ * if (imageUrl) {
+ *   return <img src={imageUrl} alt={getCartItemName(item)} />;
+ * }
+ * ```
+ */
+declare function getCartItemImage(item: CartItem): string | undefined;
+/**
+ * Convert variant attributes to an array of name/value pairs.
+ * Transforms { "Color": "Red", "Size": "M" } to [{ name: "Color", value: "Red" }, ...]
+ *
+ * @param variant - The product variant (or object with attributes)
+ * @returns Array of { name, value } objects
+ *
+ * @example
+ * ```typescript
+ * const options = getVariantOptions(selectedVariant);
+ * // options = [{ name: "Color", value: "Red" }, { name: "Size", value: "M" }]
+ *
+ * options.forEach(opt => {
+ *   console.log(`${opt.name}: ${opt.value}`);
+ * });
+ * ```
+ */
+declare function getVariantOptions(variant: Pick<ProductVariant, 'attributes'> | null | undefined): Array<{
+    name: string;
+    value: string;
+}>;
 interface ProductQueryParams {
     page?: number;
     limit?: number;
@@ -419,10 +578,22 @@ interface UpdateProductDto {
 interface Order {
     id: string;
     externalId?: string;
+    /** Human-readable order number (e.g., "#1001") */
+    orderNumber?: string;
     status: OrderStatus;
-    totalAmount: number;
-    customer: OrderCustomer;
+    /** Total amount as string (e.g., "99.99"). Use parseFloat() for calculations. */
+    totalAmount: string;
+    /** Currency code (e.g., "USD", "ILS") */
+    currency?: string;
+    /** Customer info (may be null for guest orders) */
+    customer?: OrderCustomer | null;
     items: OrderItem[];
+    /** Number of items in the order */
+    itemCount?: number;
+    /** Shipping address for the order */
+    shippingAddress?: OrderAddress;
+    /** Billing address for the order */
+    billingAddress?: OrderAddress;
     platform?: string;
     createdAt: string;
 }
@@ -434,20 +605,32 @@ interface OrderCustomer {
     address?: OrderAddress;
 }
 interface OrderAddress {
+    firstName?: string;
+    lastName?: string;
+    company?: string;
     line1: string;
     line2?: string;
     city: string;
+    /** State/Province (alias: use `state` or `region`) */
     state?: string;
+    /** Region/Province (alias: use `state` or `region`) */
+    region?: string;
     postalCode: string;
     country: string;
+    phone?: string;
 }
 interface OrderItem {
     productId: string;
+    variantId?: string;
     sku?: string;
     name?: string;
     quantity: number;
+    /** Price per unit as number */
     price: number;
-    variantId?: string;
+    /** Unit price as string (for consistency with Cart/Checkout) */
+    unitPrice?: string;
+    /** Product image URL */
+    image?: string;
 }
 interface OrderQueryParams {
     page?: number;
@@ -1995,6 +2178,11 @@ declare class OmniSyncClient {
     private readonly timeout;
     private customerToken;
     private customerCartId;
+    /**
+     * Virtual cart ID used for localStorage carts (guest users not logged in).
+     * When a cart has this ID, operations use localStorage instead of server API.
+     */
+    private readonly VIRTUAL_LOCAL_CART_ID;
     private readonly onAuthError?;
     constructor(options: OmniSyncClientOptions);
     /**
@@ -3454,6 +3642,16 @@ declare class OmniSyncClient {
      * Save local cart to localStorage
      */
     private saveLocalCart;
+    /**
+     * Calculate subtotal for a local cart
+     */
+    private calculateLocalCartSubtotal;
+    /**
+     * Convert LocalCart to Cart format for consistent API.
+     * This allows cart methods to return the same Cart type regardless
+     * of whether data is stored locally or on the server.
+     */
+    private localCartToCart;
     /**
      * Add item to local cart (NO API call)
      * If item already exists, updates quantity
@@ -3923,4 +4121,4 @@ declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType)
  */
 declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
 
-export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentConfig, type PaymentIntent, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductImage, type ProductQueryParams, type ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type SearchSuggestions, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type SyncJob, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, formatPrice, getDescriptionContent, formatPrice as getPriceDisplay, getStockStatus, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };
+export { type AddToCartDto, type AppliedDiscount, type ApplyCouponDto, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type Cart, type CartItem, type CartStatus, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateCheckoutDto, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateGuestOrderDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type EmailVerificationResponse, type ExtendReservationResponse, type FormatPriceOptions, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type LocalCart, type LocalCartItem, type MergeCartsDto, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProvidersResponse, type OmniSyncApiError, OmniSyncClient, type OmniSyncClientOptions, OmniSyncError, type Order, type OrderAddress, type OrderCustomer, type OrderItem, type OrderQueryParams, type OrderStatus, type PaginatedResponse, type PaymentConfig, type PaymentIntent, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PlatformCouponCapabilities, type Product, type ProductAttributeInput, type ProductAvailability, type ProductImage, type ProductMetafield, type ProductQueryParams, type ProductSuggestion, type ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type SearchSuggestions, type SelectShippingMethodDto, type SendInvoiceDto, type SetBillingAddressDto, type SetCheckoutCustomerDto, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingLine, type ShippingRate, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type SyncJob, type TaxBreakdown, type TaxBreakdownItem, type UpdateAddressDto, type UpdateCartItemDto, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateVariantDto, type UpdateVariantInventoryDto, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, createWebhookHandler, formatPrice, getCartItemImage, getCartItemName, getCartTotals, getDescriptionContent, formatPrice as getPriceDisplay, getProductPrice, getProductPriceInfo, getStockStatus, getVariantOptions, getVariantPrice, isCouponApplicableToProduct, isHtmlDescription, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.js

@@ -24,9 +24,16 @@ __export(index_exports, {
   OmniSyncError: () => OmniSyncError,
   createWebhookHandler: () => createWebhookHandler,
   formatPrice: () => formatPrice,
+  getCartItemImage: () => getCartItemImage,
+  getCartItemName: () => getCartItemName,
+  getCartTotals: () => getCartTotals,
   getDescriptionContent: () => getDescriptionContent,
   getPriceDisplay: () => formatPrice,
+  getProductPrice: () => getProductPrice,
+  getProductPriceInfo: () => getProductPriceInfo,
   getStockStatus: () => getStockStatus,
+  getVariantOptions: () => getVariantOptions,
+  getVariantPrice: () => getVariantPrice,
   isCouponApplicableToProduct: () => isCouponApplicableToProduct,
   isHtmlDescription: () => isHtmlDescription,
   isWebhookEventType: () => isWebhookEventType,
@@ -42,6 +49,11 @@ var OmniSyncClient = class {
   constructor(options) {
     this.customerToken = null;
     this.customerCartId = null;
+    /**
+     * Virtual cart ID used for localStorage carts (guest users not logged in).
+     * When a cart has this ID, operations use localStorage instead of server API.
+     */
+    this.VIRTUAL_LOCAL_CART_ID = "__local__";
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -1633,6 +1645,10 @@ var OmniSyncClient = class {
    * ```
    */
   async createCart() {
+    if (this.isVibeCodedMode() && !this.isCustomerLoggedIn()) {
+      const localCart = this.getLocalCart();
+      return this.localCartToCart(localCart);
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/cart");
     }
@@ -1675,6 +1691,9 @@ var OmniSyncClient = class {
    * Get a cart by ID
    */
   async getCart(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("GET", `/cart/${cartId}`);
     }
@@ -1696,6 +1715,14 @@ var OmniSyncClient = class {
    * ```
    */
   async addToCart(cartId, item) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      this.addToLocalCart({
+        productId: item.productId,
+        variantId: item.variantId,
+        quantity: item.quantity
+      });
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", `/cart/${cartId}/items`, item);
     }
@@ -1713,6 +1740,15 @@ var OmniSyncClient = class {
    * ```
    */
   async updateCartItem(cartId, itemId, data) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      const index = parseInt(itemId.replace("local_", ""), 10);
+      const localCart = this.getLocalCart();
+      if (index >= 0 && index < localCart.items.length) {
+        const item = localCart.items[index];
+        this.updateLocalCartItem(item.productId, data.quantity, item.variantId);
+      }
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("PATCH", `/cart/${cartId}/items/${itemId}`, data);
     }
@@ -1730,6 +1766,15 @@ var OmniSyncClient = class {
    * ```
    */
   async removeCartItem(cartId, itemId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      const index = parseInt(itemId.replace("local_", ""), 10);
+      const localCart = this.getLocalCart();
+      if (index >= 0 && index < localCart.items.length) {
+        const item = localCart.items[index];
+        this.removeFromLocalCart(item.productId, item.variantId);
+      }
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("DELETE", `/cart/${cartId}/items/${itemId}`);
     }
@@ -1747,6 +1792,10 @@ var OmniSyncClient = class {
    * ```
    */
   async clearCart(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      this.clearLocalCart();
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("DELETE", `/cart/${cartId}`);
     }
@@ -2561,6 +2610,62 @@ var OmniSyncClient = class {
     cart.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     window.localStorage.setItem(this.LOCAL_CART_KEY, JSON.stringify(cart));
   }
+  /**
+   * Calculate subtotal for a local cart
+   */
+  calculateLocalCartSubtotal(localCart) {
+    const total = localCart.items.reduce((sum, item) => {
+      return sum + parseFloat(item.price || "0") * item.quantity;
+    }, 0);
+    return total.toFixed(2);
+  }
+  /**
+   * Convert LocalCart to Cart format for consistent API.
+   * This allows cart methods to return the same Cart type regardless
+   * of whether data is stored locally or on the server.
+   */
+  localCartToCart(localCart) {
+    return {
+      id: this.VIRTUAL_LOCAL_CART_ID,
+      sessionToken: null,
+      customerId: null,
+      status: "ACTIVE",
+      currency: "USD",
+      // Default currency
+      notes: localCart.notes || null,
+      subtotal: this.calculateLocalCartSubtotal(localCart),
+      discountAmount: "0",
+      couponCode: localCart.couponCode || null,
+      items: localCart.items.map((item, index) => ({
+        id: `local_${index}`,
+        productId: item.productId,
+        variantId: item.variantId || null,
+        quantity: item.quantity,
+        unitPrice: item.price || "0",
+        discountAmount: "0",
+        notes: null,
+        metadata: null,
+        product: {
+          id: item.productId,
+          name: item.name || "Unknown Product",
+          sku: item.sku || "",
+          images: item.image ? [{ url: item.image }] : []
+        },
+        variant: item.variantId ? {
+          id: item.variantId,
+          name: null,
+          sku: null,
+          image: null
+        } : null,
+        createdAt: item.addedAt,
+        updatedAt: item.addedAt
+      })),
+      itemCount: localCart.items.reduce((sum, i) => sum + i.quantity, 0),
+      expiresAt: null,
+      createdAt: localCart.updatedAt,
+      updatedAt: localCart.updatedAt
+    };
+  }
   /**
    * Add item to local cart (NO API call)
    * If item already exists, updates quantity
@@ -3421,6 +3526,75 @@ function formatPrice(priceString, options) {
     currency
   }).format(isNaN(value) ? 0 : value);
 }
+function getProductPrice(product) {
+  if (!product) return 0;
+  const basePrice = parseFloat(product.basePrice) || 0;
+  const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
+  if (salePrice !== null && salePrice < basePrice) {
+    return salePrice;
+  }
+  return basePrice;
+}
+function getProductPriceInfo(product) {
+  if (!product) {
+    return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
+  }
+  const basePrice = parseFloat(product.basePrice) || 0;
+  const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
+  const isOnSale = salePrice !== null && salePrice < basePrice;
+  const effectivePrice = isOnSale ? salePrice : basePrice;
+  const discountAmount = isOnSale ? basePrice - salePrice : 0;
+  const discountPercent = isOnSale && basePrice > 0 ? Math.round(discountAmount / basePrice * 100) : 0;
+  return {
+    price: effectivePrice,
+    originalPrice: basePrice,
+    isOnSale,
+    discountAmount,
+    discountPercent
+  };
+}
+function getVariantPrice(variant, productBasePrice) {
+  if (!variant) return parseFloat(productBasePrice) || 0;
+  const variantPrice = variant.price ? parseFloat(variant.price) : null;
+  const variantSalePrice = variant.salePrice ? parseFloat(variant.salePrice) : null;
+  const basePrice = parseFloat(productBasePrice) || 0;
+  if (variantSalePrice !== null && variantPrice !== null && variantSalePrice < variantPrice) {
+    return variantSalePrice;
+  }
+  if (variantPrice !== null) {
+    return variantPrice;
+  }
+  return basePrice;
+}
+function getCartTotals(cart, shippingPrice) {
+  if (!cart) {
+    return { subtotal: 0, discount: 0, shipping: 0, total: 0 };
+  }
+  const subtotal = parseFloat(cart.subtotal) || 0;
+  const discount = parseFloat(cart.discountAmount) || 0;
+  const shipping = typeof shippingPrice === "string" ? parseFloat(shippingPrice) || 0 : shippingPrice || 0;
+  const total = subtotal - discount + shipping;
+  return { subtotal, discount, shipping, total };
+}
+function getCartItemName(item) {
+  return item.variant?.name || item.product.name;
+}
+function getCartItemImage(item) {
+  if (item.variant?.image) {
+    if (typeof item.variant.image === "string") {
+      return item.variant.image;
+    }
+    if (typeof item.variant.image === "object" && item.variant.image !== null) {
+      const imgObj = item.variant.image;
+      if (imgObj.url) return imgObj.url;
+    }
+  }
+  return item.product.images?.[0]?.url;
+}
+function getVariantOptions(variant) {
+  if (!variant?.attributes) return [];
+  return Object.entries(variant.attributes).filter(([, value]) => typeof value === "string").map(([name, value]) => ({ name, value }));
+}
 function isCouponApplicableToProduct(coupon, productId, productCategoryIds) {
   if (coupon.excludedProducts?.includes(productId)) {
     return false;
@@ -3446,9 +3620,16 @@ function isCouponApplicableToProduct(coupon, productId, productCategoryIds) {
   OmniSyncError,
   createWebhookHandler,
   formatPrice,
+  getCartItemImage,
+  getCartItemName,
+  getCartTotals,
   getDescriptionContent,
   getPriceDisplay,
+  getProductPrice,
+  getProductPriceInfo,
   getStockStatus,
+  getVariantOptions,
+  getVariantPrice,
   isCouponApplicableToProduct,
   isHtmlDescription,
   isWebhookEventType,

package/dist/index.mjs

@@ -12,6 +12,11 @@ var OmniSyncClient = class {
   constructor(options) {
     this.customerToken = null;
     this.customerCartId = null;
+    /**
+     * Virtual cart ID used for localStorage carts (guest users not logged in).
+     * When a cart has this ID, operations use localStorage instead of server API.
+     */
+    this.VIRTUAL_LOCAL_CART_ID = "__local__";
     // -------------------- Local Cart (Client-Side for Guests) --------------------
     // These methods store cart data in localStorage - NO API calls!
     // Use for guest users in vibe-coded sites
@@ -1603,6 +1608,10 @@ var OmniSyncClient = class {
    * ```
    */
   async createCart() {
+    if (this.isVibeCodedMode() && !this.isCustomerLoggedIn()) {
+      const localCart = this.getLocalCart();
+      return this.localCartToCart(localCart);
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", "/cart");
     }
@@ -1645,6 +1654,9 @@ var OmniSyncClient = class {
    * Get a cart by ID
    */
   async getCart(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("GET", `/cart/${cartId}`);
     }
@@ -1666,6 +1678,14 @@ var OmniSyncClient = class {
    * ```
    */
   async addToCart(cartId, item) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      this.addToLocalCart({
+        productId: item.productId,
+        variantId: item.variantId,
+        quantity: item.quantity
+      });
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("POST", `/cart/${cartId}/items`, item);
     }
@@ -1683,6 +1703,15 @@ var OmniSyncClient = class {
    * ```
    */
   async updateCartItem(cartId, itemId, data) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      const index = parseInt(itemId.replace("local_", ""), 10);
+      const localCart = this.getLocalCart();
+      if (index >= 0 && index < localCart.items.length) {
+        const item = localCart.items[index];
+        this.updateLocalCartItem(item.productId, data.quantity, item.variantId);
+      }
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("PATCH", `/cart/${cartId}/items/${itemId}`, data);
     }
@@ -1700,6 +1729,15 @@ var OmniSyncClient = class {
    * ```
    */
   async removeCartItem(cartId, itemId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      const index = parseInt(itemId.replace("local_", ""), 10);
+      const localCart = this.getLocalCart();
+      if (index >= 0 && index < localCart.items.length) {
+        const item = localCart.items[index];
+        this.removeFromLocalCart(item.productId, item.variantId);
+      }
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("DELETE", `/cart/${cartId}/items/${itemId}`);
     }
@@ -1717,6 +1755,10 @@ var OmniSyncClient = class {
    * ```
    */
   async clearCart(cartId) {
+    if (cartId === this.VIRTUAL_LOCAL_CART_ID) {
+      this.clearLocalCart();
+      return this.localCartToCart(this.getLocalCart());
+    }
     if (this.isVibeCodedMode()) {
       return this.vibeCodedRequest("DELETE", `/cart/${cartId}`);
     }
@@ -2531,6 +2573,62 @@ var OmniSyncClient = class {
     cart.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     window.localStorage.setItem(this.LOCAL_CART_KEY, JSON.stringify(cart));
   }
+  /**
+   * Calculate subtotal for a local cart
+   */
+  calculateLocalCartSubtotal(localCart) {
+    const total = localCart.items.reduce((sum, item) => {
+      return sum + parseFloat(item.price || "0") * item.quantity;
+    }, 0);
+    return total.toFixed(2);
+  }
+  /**
+   * Convert LocalCart to Cart format for consistent API.
+   * This allows cart methods to return the same Cart type regardless
+   * of whether data is stored locally or on the server.
+   */
+  localCartToCart(localCart) {
+    return {
+      id: this.VIRTUAL_LOCAL_CART_ID,
+      sessionToken: null,
+      customerId: null,
+      status: "ACTIVE",
+      currency: "USD",
+      // Default currency
+      notes: localCart.notes || null,
+      subtotal: this.calculateLocalCartSubtotal(localCart),
+      discountAmount: "0",
+      couponCode: localCart.couponCode || null,
+      items: localCart.items.map((item, index) => ({
+        id: `local_${index}`,
+        productId: item.productId,
+        variantId: item.variantId || null,
+        quantity: item.quantity,
+        unitPrice: item.price || "0",
+        discountAmount: "0",
+        notes: null,
+        metadata: null,
+        product: {
+          id: item.productId,
+          name: item.name || "Unknown Product",
+          sku: item.sku || "",
+          images: item.image ? [{ url: item.image }] : []
+        },
+        variant: item.variantId ? {
+          id: item.variantId,
+          name: null,
+          sku: null,
+          image: null
+        } : null,
+        createdAt: item.addedAt,
+        updatedAt: item.addedAt
+      })),
+      itemCount: localCart.items.reduce((sum, i) => sum + i.quantity, 0),
+      expiresAt: null,
+      createdAt: localCart.updatedAt,
+      updatedAt: localCart.updatedAt
+    };
+  }
   /**
    * Add item to local cart (NO API call)
    * If item already exists, updates quantity
@@ -3391,6 +3489,75 @@ function formatPrice(priceString, options) {
     currency
   }).format(isNaN(value) ? 0 : value);
 }
+function getProductPrice(product) {
+  if (!product) return 0;
+  const basePrice = parseFloat(product.basePrice) || 0;
+  const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
+  if (salePrice !== null && salePrice < basePrice) {
+    return salePrice;
+  }
+  return basePrice;
+}
+function getProductPriceInfo(product) {
+  if (!product) {
+    return { price: 0, originalPrice: 0, isOnSale: false, discountAmount: 0, discountPercent: 0 };
+  }
+  const basePrice = parseFloat(product.basePrice) || 0;
+  const salePrice = product.salePrice ? parseFloat(product.salePrice) : null;
+  const isOnSale = salePrice !== null && salePrice < basePrice;
+  const effectivePrice = isOnSale ? salePrice : basePrice;
+  const discountAmount = isOnSale ? basePrice - salePrice : 0;
+  const discountPercent = isOnSale && basePrice > 0 ? Math.round(discountAmount / basePrice * 100) : 0;
+  return {
+    price: effectivePrice,
+    originalPrice: basePrice,
+    isOnSale,
+    discountAmount,
+    discountPercent
+  };
+}
+function getVariantPrice(variant, productBasePrice) {
+  if (!variant) return parseFloat(productBasePrice) || 0;
+  const variantPrice = variant.price ? parseFloat(variant.price) : null;
+  const variantSalePrice = variant.salePrice ? parseFloat(variant.salePrice) : null;
+  const basePrice = parseFloat(productBasePrice) || 0;
+  if (variantSalePrice !== null && variantPrice !== null && variantSalePrice < variantPrice) {
+    return variantSalePrice;
+  }
+  if (variantPrice !== null) {
+    return variantPrice;
+  }
+  return basePrice;
+}
+function getCartTotals(cart, shippingPrice) {
+  if (!cart) {
+    return { subtotal: 0, discount: 0, shipping: 0, total: 0 };
+  }
+  const subtotal = parseFloat(cart.subtotal) || 0;
+  const discount = parseFloat(cart.discountAmount) || 0;
+  const shipping = typeof shippingPrice === "string" ? parseFloat(shippingPrice) || 0 : shippingPrice || 0;
+  const total = subtotal - discount + shipping;
+  return { subtotal, discount, shipping, total };
+}
+function getCartItemName(item) {
+  return item.variant?.name || item.product.name;
+}
+function getCartItemImage(item) {
+  if (item.variant?.image) {
+    if (typeof item.variant.image === "string") {
+      return item.variant.image;
+    }
+    if (typeof item.variant.image === "object" && item.variant.image !== null) {
+      const imgObj = item.variant.image;
+      if (imgObj.url) return imgObj.url;
+    }
+  }
+  return item.product.images?.[0]?.url;
+}
+function getVariantOptions(variant) {
+  if (!variant?.attributes) return [];
+  return Object.entries(variant.attributes).filter(([, value]) => typeof value === "string").map(([name, value]) => ({ name, value }));
+}
 function isCouponApplicableToProduct(coupon, productId, productCategoryIds) {
   if (coupon.excludedProducts?.includes(productId)) {
     return false;
@@ -3415,9 +3582,16 @@ export {
   OmniSyncError,
   createWebhookHandler,
   formatPrice,
+  getCartItemImage,
+  getCartItemName,
+  getCartTotals,
   getDescriptionContent,
   formatPrice as getPriceDisplay,
+  getProductPrice,
+  getProductPriceInfo,
   getStockStatus,
+  getVariantOptions,
+  getVariantPrice,
   isCouponApplicableToProduct,
   isHtmlDescription,
   isWebhookEventType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.16.2",
+  "version": "0.17.2",
   "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",
@@ -16,6 +16,14 @@
     "dist",
     "README.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",
@@ -64,12 +72,5 @@
     "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"
   }
-}
+}