omni-sync-sdk 0.7.0 → 0.7.1

package/README.md

@@ -449,6 +449,8 @@ console.log(order.message); // 'Order created successfully'
 // Cart is automatically cleared after successful order
 ```
 
+> **🔄 Automatic Tracking:** If "Track Guest Checkouts" is enabled in your connection settings (OmniSync Admin), `submitGuestOrder()` will automatically create a tracked checkout session before placing the order. This allows you to see abandoned carts and checkout sessions in your admin dashboard - **no code changes needed!**
+
 #### Keep Cart After Order
 
 ```typescript
@@ -498,31 +500,26 @@ interface GuestOrderResponse {
 
 ---
 
-### Tracked Guest Checkout (Optional)
+### Tracked Guest Checkout (Automatic)
+
+> **Note:** As of SDK v0.7.1, `submitGuestOrder()` automatically handles tracking. You don't need to use these methods unless you want explicit control over the checkout flow.
 
-By default, guest checkouts are stored only in localStorage until the order is placed. If you want the store admin to see checkout sessions and abandoned carts, you can enable **Guest Checkout Tracking** in the connection settings.
+When **"Track Guest Checkouts"** is enabled in your connection settings, checkout sessions are automatically created on the server, allowing:
 
-When enabled, checkout sessions are created on the server, allowing:
 - Visibility of checkout sessions in admin dashboard
 - Abandoned cart tracking
 - Future: abandoned cart recovery emails
 
-#### Check if Tracking is Available
+#### How to Enable
 
-```typescript
-// When customer goes to checkout page
-const result = await omni.startGuestCheckout();
+1. Go to OmniSync Admin → Integrations → Vibe-Coded Sites
+2. Click on your connection → Settings
+3. Enable "Track Guest Checkouts"
+4. Save - that's it! No code changes needed.
 
-if (result.tracked) {
-  // Tracking is enabled - use tracked flow
-  console.log('Checkout session created:', result.checkoutId);
-} else {
-  // Tracking not enabled - use regular flow
-  console.log('Using local-only checkout');
-}
-```
+#### Advanced: Manual Tracking Control
 
-#### Tracked Checkout Flow
+If you need explicit control over the tracking flow (e.g., to track checkout steps before the user places an order):
 
 ```typescript
 // 1. Start tracked checkout (sends cart items to server)

package/dist/index.d.mts

@@ -1983,7 +1983,10 @@ declare class OmniSyncClient {
     /**
      * Create order directly from local cart (guest checkout)
      * This is the main checkout method for vibe-coded sites!
-     * Sends cart data to server and creates order in ONE API call.
+     *
+     * **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
+     * settings, this method will automatically create a tracked checkout session
+     * (visible in admin) before creating the order. No code changes needed!
      *
      * @example
      * ```typescript
@@ -1992,12 +1995,11 @@ declare class OmniSyncClient {
      * omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
      * omni.setLocalCartShippingAddress({ ... });
      *
-     * // Then submit the order
+     * // Then submit the order - tracking is automatic if enabled in admin!
      * const result = await omni.submitGuestOrder();
      * console.log('Order created:', result.orderId);
      *
-     * // Clear cart after successful order
-     * omni.clearLocalCart();
+     * // Cart is automatically cleared on success
      * ```
      */
     submitGuestOrder(options?: {

package/dist/index.d.ts

@@ -1983,7 +1983,10 @@ declare class OmniSyncClient {
     /**
      * Create order directly from local cart (guest checkout)
      * This is the main checkout method for vibe-coded sites!
-     * Sends cart data to server and creates order in ONE API call.
+     *
+     * **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
+     * settings, this method will automatically create a tracked checkout session
+     * (visible in admin) before creating the order. No code changes needed!
      *
      * @example
      * ```typescript
@@ -1992,12 +1995,11 @@ declare class OmniSyncClient {
      * omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
      * omni.setLocalCartShippingAddress({ ... });
      *
-     * // Then submit the order
+     * // Then submit the order - tracking is automatic if enabled in admin!
      * const result = await omni.submitGuestOrder();
      * console.log('Order created:', result.orderId);
      *
-     * // Clear cart after successful order
-     * omni.clearLocalCart();
+     * // Cart is automatically cleared on success
      * ```
      */
     submitGuestOrder(options?: {

package/dist/index.js

@@ -1705,7 +1705,10 @@ var OmniSyncClient = class {
   /**
    * Create order directly from local cart (guest checkout)
    * This is the main checkout method for vibe-coded sites!
-   * Sends cart data to server and creates order in ONE API call.
+   *
+   * **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
+   * settings, this method will automatically create a tracked checkout session
+   * (visible in admin) before creating the order. No code changes needed!
    *
    * @example
    * ```typescript
@@ -1714,12 +1717,11 @@ var OmniSyncClient = class {
    * omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
    * omni.setLocalCartShippingAddress({ ... });
    *
-   * // Then submit the order
+   * // Then submit the order - tracking is automatic if enabled in admin!
    * const result = await omni.submitGuestOrder();
    * console.log('Order created:', result.orderId);
    *
-   * // Clear cart after successful order
-   * omni.clearLocalCart();
+   * // Cart is automatically cleared on success
    * ```
    */
   async submitGuestOrder(options) {
@@ -1733,6 +1735,28 @@ var OmniSyncClient = class {
     if (!cart.shippingAddress) {
       throw new OmniSyncError("Shipping address is required", 400);
     }
+    try {
+      const trackingResult = await this.startGuestCheckout();
+      if (trackingResult.tracked) {
+        await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
+          shippingAddress: cart.shippingAddress,
+          billingAddress: cart.billingAddress
+        });
+        const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
+          clearCartOnSuccess: options?.clearCartOnSuccess
+        });
+        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)"
+        };
+      }
+    } catch {
+    }
     const orderData = {
       items: cart.items.map((item) => ({
         productId: item.productId,

package/dist/index.mjs

@@ -1680,7 +1680,10 @@ var OmniSyncClient = class {
   /**
    * Create order directly from local cart (guest checkout)
    * This is the main checkout method for vibe-coded sites!
-   * Sends cart data to server and creates order in ONE API call.
+   *
+   * **Automatic Tracking:** If "Track Guest Checkouts" is enabled in the connection
+   * settings, this method will automatically create a tracked checkout session
+   * (visible in admin) before creating the order. No code changes needed!
    *
    * @example
    * ```typescript
@@ -1689,12 +1692,11 @@ var OmniSyncClient = class {
    * omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
    * omni.setLocalCartShippingAddress({ ... });
    *
-   * // Then submit the order
+   * // Then submit the order - tracking is automatic if enabled in admin!
    * const result = await omni.submitGuestOrder();
    * console.log('Order created:', result.orderId);
    *
-   * // Clear cart after successful order
-   * omni.clearLocalCart();
+   * // Cart is automatically cleared on success
    * ```
    */
   async submitGuestOrder(options) {
@@ -1708,6 +1710,28 @@ var OmniSyncClient = class {
     if (!cart.shippingAddress) {
       throw new OmniSyncError("Shipping address is required", 400);
     }
+    try {
+      const trackingResult = await this.startGuestCheckout();
+      if (trackingResult.tracked) {
+        await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
+          shippingAddress: cart.shippingAddress,
+          billingAddress: cart.billingAddress
+        });
+        const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
+          clearCartOnSuccess: options?.clearCartOnSuccess
+        });
+        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)"
+        };
+      }
+    } catch {
+    }
     const orderData = {
       items: cart.items.map((item) => ({
         productId: item.productId,

package/package.json

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