omni-sync-sdk 0.21.8 → 0.22.0

package/AI_BUILDER_PROMPT.md

@@ -30,7 +30,7 @@ if (omni.isCustomerLoggedIn()) {
 | **Guest**     | localStorage  | `startGuestCheckout()`       | `result.checkoutId` |
 | **Logged-in** | Server        | `createCheckout({ cartId })` | `checkout.id`       |
 
-### Rule 2: Clear Cart After Successful Payment!
+### Rule 2: Complete Checkout & Clear Cart After Payment!
 
 ```typescript
 // On /checkout/success page - MUST DO THIS!
@@ -38,14 +38,21 @@ export default function CheckoutSuccessPage() {
   const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
 
   useEffect(() => {
-    // This clears the cart (full or partial based on what was purchased)
-    omni.handlePaymentSuccess(checkoutId);
+    if (checkoutId) {
+      // ⚠️ CRITICAL: This sends the order to the server AND clears the cart!
+      // handlePaymentSuccess() only clears the local cart - it does NOT create the order!
+      omni.completeGuestCheckout(checkoutId);
+    }
   }, []);
 
   return <div>Thank you for your order!</div>;
 }
 ```
 
+> **WARNING:** Do NOT use `handlePaymentSuccess()` to complete an order. It only clears
+> the local cart (localStorage) and does NOT communicate with the server.
+> Always use `completeGuestCheckout()` after payment succeeds.
+
 ### Rule 3: Never Hardcode Products!
 
 ```typescript
@@ -193,7 +200,7 @@ const handleCheckout = async () => {
 **Why this matters:**
 
 - Users can buy some items now, leave others for later
-- After payment, `handlePaymentSuccess()` only removes purchased items
+- After payment, `completeGuestCheckout()` sends the order and only removes purchased items
 - Remaining items stay in cart for future purchase
 
 **⚠️ Order Summary on Checkout Page - Use checkout.lineItems!**
@@ -323,7 +330,7 @@ if (error) {
 // If no error, Stripe redirects to success page
 ```
 
-### Step 5: Success Page (Clear Cart!)
+### Step 5: Success Page (Complete Order & Clear Cart!)
 
 ```typescript
 // /checkout/success/page.tsx
@@ -333,19 +340,25 @@ import { omni } from '@/lib/omni-sync';
 
 export default function CheckoutSuccessPage() {
   const [orderNumber, setOrderNumber] = useState<string>();
+  const [loading, setLoading] = useState(true);
 
   useEffect(() => {
     const checkoutId = new URLSearchParams(window.location.search).get('checkout_id');
 
-    // ⚠️ CRITICAL: Clear the cart!
-    omni.handlePaymentSuccess(checkoutId);
-
-    // Optional: Get order details
     if (checkoutId) {
-      omni.getPaymentStatus(checkoutId).then(status => {
-        if (status.orderNumber) {
-          setOrderNumber(status.orderNumber);
-        }
+      // ⚠️ CRITICAL: Complete the order on the server AND clear the cart!
+      // Do NOT use handlePaymentSuccess() - it only clears localStorage!
+      omni.completeGuestCheckout(checkoutId).then(result => {
+        setOrderNumber(result.orderNumber);
+        setLoading(false);
+      }).catch(() => {
+        // Order may already be completed (e.g., page refresh) - check status
+        omni.getPaymentStatus(checkoutId).then(status => {
+          if (status.orderNumber) {
+            setOrderNumber(status.orderNumber);
+          }
+          setLoading(false);
+        });
       });
     }
   }, []);
@@ -353,6 +366,7 @@ export default function CheckoutSuccessPage() {
   return (
     <div className="text-center py-12">
       <h1 className="text-2xl font-bold text-green-600">Thank you for your order!</h1>
+      {loading && <p className="mt-2">Processing your order...</p>}
       {orderNumber && <p className="mt-2">Order #{orderNumber}</p>}
       <p className="mt-4">A confirmation email will be sent shortly.</p>
     </div>
@@ -372,7 +386,7 @@ const result = await omni.startGuestCheckout({
   selectedIndices: [0, 2], // Buy items at index 0 and 2 only
 });
 
-// After payment, handlePaymentSuccess() will only remove those items!
+// After payment, completeGuestCheckout() sends the order AND removes only those items!
 // Other items stay in cart.
 ```
 
@@ -399,6 +413,34 @@ const suggestions = await omni.getSearchSuggestions('blue', 5);
 
 ---
 
+## Product Custom Fields (Metafields)
+
+Products may have custom fields defined by the store owner (e.g., "Material", "Care Instructions", "Warranty").
+
+```typescript
+import { getProductMetafield, getProductMetafieldValue } from 'omni-sync-sdk';
+
+// Access metafields on a product
+const product = await omni.getProductBySlug('blue-shirt');
+
+// Get all custom fields
+product.metafields?.forEach((field) => {
+  console.log(`${field.definitionName}: ${field.value}`);
+});
+
+// Get specific field by key
+const material = getProductMetafieldValue(product, 'material');
+const careInstructions = getProductMetafield(product, 'care_instructions');
+
+// Get available metafield definitions (schema)
+const { definitions } = await omni.getPublicMetafieldDefinitions();
+// Use definitions to build dynamic UI (filters, forms, etc.)
+```
+
+> **Tip:** `metafields` may be empty if the store hasn't defined custom fields. Always use optional chaining.
+
+---
+
 ## Customer Authentication
 
 ```typescript
@@ -456,7 +498,7 @@ setCustomerToken(token);
 - [ ] **Product Detail** (`/products/[slug]`) - Use `getProductBySlug(slug)`
 - [ ] **Cart** (`/cart`) - Show items, quantities, totals
 - [ ] **Checkout** (`/checkout`) - Address → Shipping → Payment
-- [ ] **Success** (`/checkout/success`) - **Must call `handlePaymentSuccess()`!**
+- [ ] **Success** (`/checkout/success`) - **Must call `completeGuestCheckout()`!**
 - [ ] **Login** (`/login`) - Email/password + social buttons
 - [ ] **Register** (`/register`) - Registration form
 - [ ] **Account** (`/account`) - Profile + order history
@@ -475,6 +517,8 @@ item.name (in cart)                  item.product.name
 response.url (OAuth)                 response.authorizationUrl
 providers.forEach (OAuth)            response.providers.forEach
 status === 'completed'               status === 'succeeded'
+product.metafields.name              product.metafields[0].definitionName
+product.metafields.key               product.metafields[0].definitionKey
 ```
 
 ---