npm - omni-sync-sdk - Versions diffs - 0.7.1 → 0.7.3 - Mend

omni-sync-sdk 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE ADDED Viewed

File without changes

package/README.md CHANGED Viewed

@@ -1921,6 +1921,148 @@ When building a store, implement these pages:
 ---
+## Error Handling & Toast Notifications
+For a polished user experience, use toast notifications to show success/error messages. We recommend [Sonner](https://sonner.emilkowal.ski/) - a lightweight toast library.
+### Setup Toast Notifications
+```bash
+npm install sonner
+```
+Add the Toaster component to your app layout:
+```tsx
+// app/layout.tsx or App.tsx
+import { Toaster } from 'sonner';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster
+          position="top-right"
+          richColors
+          closeButton
+          toastOptions={{
+            duration: 4000,
+          }}
+        />
+      </body>
+    </html>
+  );
+}
+```
+### Handling SDK Errors
+The SDK throws `OmniSyncError` with helpful messages. Wrap SDK calls in try/catch:
+```tsx
+import { toast } from 'sonner';
+import { OmniSyncError } from 'omni-sync-sdk';
+// Add to cart with toast feedback
+const handleAddToCart = async (productId: string, quantity: number) => {
+  try {
+    omni.addToLocalCart({ productId, quantity });
+    toast.success('Added to cart!');
+  } catch (error) {
+    if (error instanceof OmniSyncError) {
+      toast.error(error.message);
+    } else {
+      toast.error('Something went wrong');
+    }
+  }
+};
+// Checkout with toast feedback
+const handleCheckout = async () => {
+  try {
+    const order = await omni.submitGuestOrder();
+    toast.success(`Order placed! Order #${order.orderNumber}`);
+    // Navigate to success page
+  } catch (error) {
+    if (error instanceof OmniSyncError) {
+      // Show specific error message from SDK
+      toast.error(error.message);
+    } else {
+      toast.error('Failed to place order. Please try again.');
+    }
+  }
+};
+```
+### Common Error Messages
+| Error                          | When it occurs                     |
+| ------------------------------ | ---------------------------------- |
+| `Cart is empty`                | Trying to checkout with empty cart |
+| `Customer email is required`   | Missing email at checkout          |
+| `Shipping address is required` | Missing shipping address           |
+| `Product not found`            | Invalid product ID                 |
+| `Insufficient inventory`       | Not enough stock                   |
+| `Invalid quantity`             | Quantity < 1 or > available        |
+### Custom Hook for SDK Operations (Optional)
+Create a reusable hook for SDK operations with automatic toast handling:
+```tsx
+// hooks/useOmniAction.ts
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { OmniSyncError } from 'omni-sync-sdk';
+export function useOmniAction<T>() {
+  const [isLoading, setIsLoading] = useState(false);
+  const execute = async (
+    action: () => Promise<T>,
+    options?: {
+      successMessage?: string;
+      errorMessage?: string;
+      onSuccess?: (result: T) => void;
+    }
+  ): Promise<T | null> => {
+    setIsLoading(true);
+    try {
+      const result = await action();
+      if (options?.successMessage) {
+        toast.success(options.successMessage);
+      }
+      options?.onSuccess?.(result);
+      return result;
+    } catch (error) {
+      const message =
+        error instanceof OmniSyncError
+          ? error.message
+          : options?.errorMessage || 'Something went wrong';
+      toast.error(message);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  };
+  return { execute, isLoading };
+}
+// Usage:
+const { execute, isLoading } = useOmniAction();
+const handlePlaceOrder = () => {
+  execute(() => omni.submitGuestOrder(), {
+    successMessage: 'Order placed successfully!',
+    onSuccess: (order) => navigate(`/order/${order.orderId}`),
+  });
+};
+```
+---
 ## Important Rules
 ### DO:
@@ -1928,9 +2070,11 @@ When building a store, implement these pages:
 - Install `omni-sync-sdk` and use it for ALL data
 - Import types from the SDK
 - Handle loading states and errors
+- **Use toast notifications (Sonner) for user feedback on actions**
 - Persist cart ID in localStorage
 - Persist customer token after login
 - **Check `descriptionFormat` and render HTML with `dangerouslySetInnerHTML` when format is `'html'`**
+- **Wrap SDK calls in try/catch and show error toasts**
 ### DON'T:

package/dist/index.d.mts CHANGED Viewed

@@ -2051,9 +2051,7 @@ declare class OmniSyncClient {
      */
     completeGuestCheckout(checkoutId: string, options?: {
         clearCartOnSuccess?: boolean;
-    }): Promise<{
-        orderId: string;
-    }>;
+    }): Promise<GuestOrderResponse>;
     /**
      * Create order from custom data (not from local cart)
      * Use this if you manage cart state yourself

package/dist/index.d.ts CHANGED Viewed

@@ -2051,9 +2051,7 @@ declare class OmniSyncClient {
      */
     completeGuestCheckout(checkoutId: string, options?: {
         clearCartOnSuccess?: boolean;
-    }): Promise<{
-        orderId: string;
-    }>;
+    }): Promise<GuestOrderResponse>;
     /**
      * Create order from custom data (not from local cart)
      * Use this if you manage cart state yourself

package/dist/index.js CHANGED Viewed

@@ -1747,12 +1747,10 @@ var OmniSyncClient = class {
         });
         return {
           orderId: orderResult.orderId,
-          orderNumber: orderResult.orderId,
-          // Will be overwritten by actual order number if returned
-          status: "pending",
-          total: 0,
-          // Actual total comes from server
-          message: "Order created successfully (tracked)"
+          orderNumber: orderResult.orderNumber || orderResult.orderId,
+          status: orderResult.status || "pending",
+          total: orderResult.total ?? 0,
+          message: orderResult.message || "Order created successfully"
         };
       }
     } catch {

package/dist/index.mjs CHANGED Viewed

@@ -1722,12 +1722,10 @@ var OmniSyncClient = class {
         });
         return {
           orderId: orderResult.orderId,
-          orderNumber: orderResult.orderId,
-          // Will be overwritten by actual order number if returned
-          status: "pending",
-          total: 0,
-          // Actual total comes from server
-          message: "Order created successfully (tracked)"
+          orderNumber: orderResult.orderNumber || orderResult.orderId,
+          status: orderResult.status || "pending",
+          total: orderResult.total ?? 0,
+          message: orderResult.message || "Order created successfully"
         };
       }
     } catch {

package/package.json CHANGED Viewed

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