omni-sync-sdk 0.14.2 → 0.15.0

package/README.md

@@ -479,7 +479,7 @@ function SearchInput() {
       {suggestions && (
         <div className="suggestions">
           {suggestions.products.map((product) => (
-            <a key={product.id} href={`/products/${product.id}`}>
+            <a key={product.id} href={`/products/${product.slug}`}>
               <img src={product.image || '/placeholder.png'} alt={product.name} />
               <span>{product.name}</span>
               <span>${product.basePrice}</span>
@@ -2128,7 +2128,7 @@ export default function HomePage() {
   return (
     <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
       {products.map((product) => (
-        <a key={product.id} href={`/products/${product.id}`} className="group">
+        <a key={product.id} href={`/products/${product.slug}`} className="group">
           <img
             src={product.images?.[0]?.url || '/placeholder.jpg'}
             alt={product.name}
@@ -2185,7 +2185,7 @@ export default function ProductsPage() {
     <div>
       <div className="grid grid-cols-3 gap-6">
         {data.data.map((product) => (
-          <a key={product.id} href={`/products/${product.id}`}>
+          <a key={product.id} href={`/products/${product.slug}`}>
             <img src={product.images?.[0]?.url} alt={product.name} />
             <h3>{product.name}</h3>
             <p>${product.salePrice || product.basePrice}</p>
@@ -2217,7 +2217,8 @@ import { omni } from '@/lib/omni-sync';
 import { isHtmlDescription } from 'omni-sync-sdk';
 import type { Product } from 'omni-sync-sdk';
 
-export default function ProductPage({ params }: { params: { id: string } }) {
+// Route: /products/[slug]/page.tsx - uses URL-friendly slug instead of ID
+export default function ProductPage({ params }: { params: { slug: string } }) {
   const [product, setProduct] = useState<Product | null>(null);
   const [selectedVariant, setSelectedVariant] = useState<string | null>(null);
   const [quantity, setQuantity] = useState(1);
@@ -2226,7 +2227,8 @@ export default function ProductPage({ params }: { params: { id: string } }) {
   useEffect(() => {
     async function load() {
       try {
-        const p = await omni.getProduct(params.id);
+        // Use getProductBySlug for SEO-friendly URLs
+        const p = await omni.getProductBySlug(params.slug);
         setProduct(p);
         if (p.variants && p.variants.length > 0) {
           setSelectedVariant(p.variants[0].id);
@@ -2236,7 +2238,7 @@ export default function ProductPage({ params }: { params: { id: string } }) {
       }
     }
     load();
-  }, [params.id]);
+  }, [params.slug]);
 
   const handleAddToCart = () => {
     if (!product) return;
@@ -3336,7 +3338,7 @@ When building a store, implement these pages:
 
 - [ ] **Home** (`/`) - Product grid
 - [ ] **Products** (`/products`) - Product list with pagination
-- [ ] **Product Detail** (`/products/[id]`) - Single product with Add to Cart
+- [ ] **Product Detail** (`/products/[slug]`) - Single product with Add to Cart (use `getProductBySlug(slug)`)
 - [ ] **Cart** (`/cart`) - Cart items, update quantity, remove
 - [ ] **Checkout** (`/checkout`) - Multi-step checkout flow
 - [ ] **⚠️ Payment** (`/checkout/payment`) - **REQUIRED!** Use `getPaymentProviders()` to show Stripe/PayPal forms

package/dist/index.d.mts

@@ -349,6 +349,7 @@ interface ProductQueryParams {
 interface ProductSuggestion {
     id: string;
     name: string;
+    slug: string | null;
     image: string | null;
     basePrice: number;
     salePrice?: number | null;
@@ -914,6 +915,12 @@ interface Cart {
     createdAt: string;
     /** ISO timestamp when cart was last updated */
     updatedAt: string;
+    /**
+     * Reservation information (only present when reservation strategy is ON_CART).
+     * Use this to display countdown timer to customers.
+     * @see ReservationInfo
+     */
+    reservation?: ReservationInfo;
 }
 interface AddToCartDto {
     productId: string;
@@ -1256,12 +1263,13 @@ interface ShippingRate {
 /**
  * Represents a checkout session for completing a purchase.
  *
- * **Checkout Flow:**
- * 1. Create checkout from cart: `createCheckout({ cartId })`
- * 2. Set customer info: `setCheckoutCustomer(id, { email, ... })`
- * 3. Set shipping address: `setShippingAddress(id, address)` - returns available rates
- * 4. Select shipping method: `selectShippingMethod(id, rateId)`
- * 5. Complete checkout: `completeCheckout(id)` - creates the order
+ * **Simplified Checkout Flow (3 steps):**
+ * 1. Set shipping address (includes email): `setShippingAddress(id, { email, ...address })` - returns rates
+ * 2. Select shipping method: `selectShippingMethod(id, rateId)`
+ * 3. Pay with Stripe: `createPaymentIntent(id)` → `stripe.confirmPayment()` → Order created automatically!
+ *
+ * **Note:** Order is created automatically via webhook when payment succeeds.
+ * No need to call `completeCheckout()` - it happens automatically.
  *
  * **IMPORTANT: Price fields are strings**
  * All monetary fields (subtotal, discountAmount, shippingAmount, taxAmount, total)
@@ -1342,6 +1350,12 @@ interface Checkout {
     createdAt: string;
     /** Last update timestamp */
     updatedAt: string;
+    /**
+     * Reservation information (present when reservation strategy is ON_CHECKOUT or ON_CART).
+     * Use this to display countdown timer to customers.
+     * @see ReservationInfo
+     */
+    reservation?: ReservationInfo;
 }
 interface CreateCheckoutDto {
     cartId: string;
@@ -1354,7 +1368,13 @@ interface SetCheckoutCustomerDto {
     phone?: string;
     acceptsMarketing?: boolean;
 }
+/**
+ * Shipping address with customer email (required for checkout).
+ * Email is included here to simplify the checkout flow - no need for separate setCheckoutCustomer call.
+ */
 interface SetShippingAddressDto {
+    /** Customer email (required) - used for order confirmation */
+    email: string;
     firstName: string;
     lastName: string;
     company?: string;
@@ -1365,8 +1385,23 @@ interface SetShippingAddressDto {
     postalCode: string;
     country: string;
     phone?: string;
+    /** Whether customer accepts marketing emails */
+    acceptsMarketing?: boolean;
 }
-interface SetBillingAddressDto extends SetShippingAddressDto {
+/**
+ * Billing address (email not required - already set in shipping address)
+ */
+interface SetBillingAddressDto {
+    firstName: string;
+    lastName: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
     sameAsShipping?: boolean;
 }
 interface SelectShippingMethodDto {
@@ -1667,6 +1702,8 @@ interface PaymentProviderConfig {
     name: string;
     /** Public/publishable key (safe to expose) */
     publicKey: string;
+    /** Stripe Connect account ID (for OAuth-connected accounts) */
+    stripeAccountId?: string;
     /** Supported payment methods: ['card', 'ideal', 'bancontact'] */
     supportedMethods: string[];
     /** Whether this is test/sandbox mode */
@@ -1692,7 +1729,10 @@ interface PaymentProviderConfig {
  * const paypalProvider = providers.find(p => p.provider === 'paypal');
  *
  * if (stripeProvider) {
- *   // Initialize Stripe.js with stripeProvider.publicKey
+ *   // Initialize Stripe.js with options for Connect
+ *   const stripe = await loadStripe(stripeProvider.publicKey, {
+ *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+ *   });
  * }
  * if (paypalProvider) {
  *   // Initialize PayPal SDK with paypalProvider.publicKey as clientId
@@ -1756,6 +1796,83 @@ interface PaymentStatus {
     /** Payment intent ID from provider */
     paymentIntentId?: string;
 }
+/**
+ * When inventory is reserved for customers.
+ * Configured per vibe-coded connection by the store owner.
+ *
+ * - ON_PAYMENT: Stock is only reserved when payment is completed (default, safest)
+ * - ON_CHECKOUT: Stock is reserved when checkout is created
+ * - ON_CART: Stock is reserved immediately when added to cart (most aggressive)
+ */
+type InventoryReservationStrategy = 'ON_PAYMENT' | 'ON_CHECKOUT' | 'ON_CART';
+/**
+ * Information about a customer's inventory reservation.
+ * Included in cart/checkout responses when reservations are active.
+ *
+ * @example
+ * ```typescript
+ * const cart = await omni.getCart(cartId);
+ * if (cart.reservation?.hasReservation) {
+ *   const remaining = cart.reservation.remainingSeconds;
+ *   console.log(`Items reserved for ${remaining} seconds`);
+ * }
+ * ```
+ */
+interface ReservationInfo {
+    /** Whether there is an active reservation */
+    hasReservation: boolean;
+    /** ISO timestamp when reservation expires */
+    expiresAt?: string;
+    /** Remaining time in seconds before reservation expires */
+    remainingSeconds?: number;
+    /** The reservation strategy in use */
+    strategy: InventoryReservationStrategy;
+    /** Custom message from store owner (supports {time} placeholder) */
+    countdownMessage?: string;
+}
+/**
+ * Product availability including reserved quantities.
+ * Use this to show accurate stock to customers when reservations are enabled.
+ *
+ * @example
+ * ```typescript
+ * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+ * availability.forEach(item => {
+ *   if (!item.canPurchase) {
+ *     console.log(`${item.productId}: Cannot purchase`);
+ *   } else if (item.lowStock) {
+ *     console.log(`${item.productId}: Only ${item.available} left!`);
+ *   }
+ * });
+ * ```
+ */
+interface ProductAvailability {
+    /** Product ID */
+    productId: string;
+    /** Variant ID (null for simple products) */
+    variantId?: string | null;
+    /** Inventory tracking mode */
+    trackingMode: InventoryTrackingMode;
+    /** Total stock quantity */
+    total: number;
+    /** Quantity currently reserved by other customers */
+    reserved: number;
+    /** Available for purchase (total - reserved) */
+    available: number;
+    /** Whether the product can be purchased */
+    canPurchase: boolean;
+    /** Whether stock is below low stock threshold */
+    lowStock?: boolean;
+}
+/**
+ * Response from extending a reservation
+ */
+interface ExtendReservationResponse {
+    /** Whether the extension was successful */
+    success: boolean;
+    /** Updated reservation info */
+    reservation: ReservationInfo;
+}
 interface OmniSyncApiError {
     statusCode: number;
     message: string;
@@ -2870,12 +2987,16 @@ declare class OmniSyncClient {
      */
     setCheckoutCustomer(checkoutId: string, data: SetCheckoutCustomerDto): Promise<Checkout>;
     /**
-     * Set shipping address on checkout
-     * Returns the checkout and available shipping rates for the address
+     * Set shipping address on checkout (includes customer email).
+     * Returns the checkout and available shipping rates for the address.
+     *
+     * **This is the first step of the simplified checkout flow.**
+     * Email is required and will be used for order confirmation.
      *
      * @example
      * ```typescript
      * const { checkout, rates } = await omni.setShippingAddress('checkout_123', {
+     *   email: 'customer@example.com',  // Required!
      *   firstName: 'John',
      *   lastName: 'Doe',
      *   line1: '123 Main St',
@@ -2992,9 +3113,11 @@ declare class OmniSyncClient {
      * const stripeProvider = providers.find(p => p.provider === 'stripe');
      * const paypalProvider = providers.find(p => p.provider === 'paypal');
      *
-     * // Initialize Stripe if available
+     * // Initialize Stripe if available (with Connect account support)
      * if (stripeProvider) {
-     *   const stripe = await loadStripe(stripeProvider.publicKey);
+     *   const stripe = await loadStripe(stripeProvider.publicKey, {
+     *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+     *   });
      *   // Show Stripe payment form
      * }
      *
@@ -3398,6 +3521,72 @@ declare class OmniSyncClient {
      * ```
      */
     testCustomApiConnection(integrationId: string): Promise<CustomApiTestResult>;
+    /**
+     * Get product availability including reserved quantities.
+     * Use this to show accurate stock to customers when reservations are enabled.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     *
+     * @param productIds - Array of product IDs to check availability for
+     * @returns Array of availability info for each product
+     *
+     * @example
+     * ```typescript
+     * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+     * availability.forEach(item => {
+     *   if (!item.canPurchase) {
+     *     console.log(`${item.productId}: Cannot purchase`);
+     *   } else if (item.lowStock) {
+     *     console.log(`${item.productId}: Only ${item.available} left!`);
+     *   } else {
+     *     console.log(`${item.productId}: ${item.available} available`);
+     *   }
+     * });
+     * ```
+     */
+    getAvailability(productIds: string[]): Promise<ProductAvailability[]>;
+    /**
+     * Extend an active reservation to prevent it from expiring.
+     * Call this when a customer is still active in checkout to keep their items reserved.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+     *
+     * @param options - Either cartId or checkoutId to identify the reservation
+     * @returns Updated reservation info
+     *
+     * @example
+     * ```typescript
+     * // Extend reservation when customer shows activity
+     * const result = await omni.extendReservation({ checkoutId: 'chk_123' });
+     * if (result.success) {
+     *   console.log(`Reservation extended until ${result.reservation.expiresAt}`);
+     * }
+     * ```
+     */
+    extendReservation(options: {
+        cartId?: string;
+        checkoutId?: string;
+    }): Promise<ExtendReservationResponse>;
+    /**
+     * Release an active reservation, returning items to available stock.
+     * Call this when a customer abandons their cart/checkout.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+     *
+     * @param options - Either cartId or checkoutId to identify the reservation
+     *
+     * @example
+     * ```typescript
+     * // Release reservation when customer abandons checkout
+     * await omni.releaseReservation({ checkoutId: 'chk_123' });
+     * ```
+     */
+    releaseReservation(options: {
+        cartId?: string;
+        checkoutId?: string;
+    }): Promise<void>;
 }
 /**
  * Custom error class for Omni-Sync API errors

package/dist/index.d.ts

@@ -349,6 +349,7 @@ interface ProductQueryParams {
 interface ProductSuggestion {
     id: string;
     name: string;
+    slug: string | null;
     image: string | null;
     basePrice: number;
     salePrice?: number | null;
@@ -914,6 +915,12 @@ interface Cart {
     createdAt: string;
     /** ISO timestamp when cart was last updated */
     updatedAt: string;
+    /**
+     * Reservation information (only present when reservation strategy is ON_CART).
+     * Use this to display countdown timer to customers.
+     * @see ReservationInfo
+     */
+    reservation?: ReservationInfo;
 }
 interface AddToCartDto {
     productId: string;
@@ -1256,12 +1263,13 @@ interface ShippingRate {
 /**
  * Represents a checkout session for completing a purchase.
  *
- * **Checkout Flow:**
- * 1. Create checkout from cart: `createCheckout({ cartId })`
- * 2. Set customer info: `setCheckoutCustomer(id, { email, ... })`
- * 3. Set shipping address: `setShippingAddress(id, address)` - returns available rates
- * 4. Select shipping method: `selectShippingMethod(id, rateId)`
- * 5. Complete checkout: `completeCheckout(id)` - creates the order
+ * **Simplified Checkout Flow (3 steps):**
+ * 1. Set shipping address (includes email): `setShippingAddress(id, { email, ...address })` - returns rates
+ * 2. Select shipping method: `selectShippingMethod(id, rateId)`
+ * 3. Pay with Stripe: `createPaymentIntent(id)` → `stripe.confirmPayment()` → Order created automatically!
+ *
+ * **Note:** Order is created automatically via webhook when payment succeeds.
+ * No need to call `completeCheckout()` - it happens automatically.
  *
  * **IMPORTANT: Price fields are strings**
  * All monetary fields (subtotal, discountAmount, shippingAmount, taxAmount, total)
@@ -1342,6 +1350,12 @@ interface Checkout {
     createdAt: string;
     /** Last update timestamp */
     updatedAt: string;
+    /**
+     * Reservation information (present when reservation strategy is ON_CHECKOUT or ON_CART).
+     * Use this to display countdown timer to customers.
+     * @see ReservationInfo
+     */
+    reservation?: ReservationInfo;
 }
 interface CreateCheckoutDto {
     cartId: string;
@@ -1354,7 +1368,13 @@ interface SetCheckoutCustomerDto {
     phone?: string;
     acceptsMarketing?: boolean;
 }
+/**
+ * Shipping address with customer email (required for checkout).
+ * Email is included here to simplify the checkout flow - no need for separate setCheckoutCustomer call.
+ */
 interface SetShippingAddressDto {
+    /** Customer email (required) - used for order confirmation */
+    email: string;
     firstName: string;
     lastName: string;
     company?: string;
@@ -1365,8 +1385,23 @@ interface SetShippingAddressDto {
     postalCode: string;
     country: string;
     phone?: string;
+    /** Whether customer accepts marketing emails */
+    acceptsMarketing?: boolean;
 }
-interface SetBillingAddressDto extends SetShippingAddressDto {
+/**
+ * Billing address (email not required - already set in shipping address)
+ */
+interface SetBillingAddressDto {
+    firstName: string;
+    lastName: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
     sameAsShipping?: boolean;
 }
 interface SelectShippingMethodDto {
@@ -1667,6 +1702,8 @@ interface PaymentProviderConfig {
     name: string;
     /** Public/publishable key (safe to expose) */
     publicKey: string;
+    /** Stripe Connect account ID (for OAuth-connected accounts) */
+    stripeAccountId?: string;
     /** Supported payment methods: ['card', 'ideal', 'bancontact'] */
     supportedMethods: string[];
     /** Whether this is test/sandbox mode */
@@ -1692,7 +1729,10 @@ interface PaymentProviderConfig {
  * const paypalProvider = providers.find(p => p.provider === 'paypal');
  *
  * if (stripeProvider) {
- *   // Initialize Stripe.js with stripeProvider.publicKey
+ *   // Initialize Stripe.js with options for Connect
+ *   const stripe = await loadStripe(stripeProvider.publicKey, {
+ *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+ *   });
  * }
  * if (paypalProvider) {
  *   // Initialize PayPal SDK with paypalProvider.publicKey as clientId
@@ -1756,6 +1796,83 @@ interface PaymentStatus {
     /** Payment intent ID from provider */
     paymentIntentId?: string;
 }
+/**
+ * When inventory is reserved for customers.
+ * Configured per vibe-coded connection by the store owner.
+ *
+ * - ON_PAYMENT: Stock is only reserved when payment is completed (default, safest)
+ * - ON_CHECKOUT: Stock is reserved when checkout is created
+ * - ON_CART: Stock is reserved immediately when added to cart (most aggressive)
+ */
+type InventoryReservationStrategy = 'ON_PAYMENT' | 'ON_CHECKOUT' | 'ON_CART';
+/**
+ * Information about a customer's inventory reservation.
+ * Included in cart/checkout responses when reservations are active.
+ *
+ * @example
+ * ```typescript
+ * const cart = await omni.getCart(cartId);
+ * if (cart.reservation?.hasReservation) {
+ *   const remaining = cart.reservation.remainingSeconds;
+ *   console.log(`Items reserved for ${remaining} seconds`);
+ * }
+ * ```
+ */
+interface ReservationInfo {
+    /** Whether there is an active reservation */
+    hasReservation: boolean;
+    /** ISO timestamp when reservation expires */
+    expiresAt?: string;
+    /** Remaining time in seconds before reservation expires */
+    remainingSeconds?: number;
+    /** The reservation strategy in use */
+    strategy: InventoryReservationStrategy;
+    /** Custom message from store owner (supports {time} placeholder) */
+    countdownMessage?: string;
+}
+/**
+ * Product availability including reserved quantities.
+ * Use this to show accurate stock to customers when reservations are enabled.
+ *
+ * @example
+ * ```typescript
+ * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+ * availability.forEach(item => {
+ *   if (!item.canPurchase) {
+ *     console.log(`${item.productId}: Cannot purchase`);
+ *   } else if (item.lowStock) {
+ *     console.log(`${item.productId}: Only ${item.available} left!`);
+ *   }
+ * });
+ * ```
+ */
+interface ProductAvailability {
+    /** Product ID */
+    productId: string;
+    /** Variant ID (null for simple products) */
+    variantId?: string | null;
+    /** Inventory tracking mode */
+    trackingMode: InventoryTrackingMode;
+    /** Total stock quantity */
+    total: number;
+    /** Quantity currently reserved by other customers */
+    reserved: number;
+    /** Available for purchase (total - reserved) */
+    available: number;
+    /** Whether the product can be purchased */
+    canPurchase: boolean;
+    /** Whether stock is below low stock threshold */
+    lowStock?: boolean;
+}
+/**
+ * Response from extending a reservation
+ */
+interface ExtendReservationResponse {
+    /** Whether the extension was successful */
+    success: boolean;
+    /** Updated reservation info */
+    reservation: ReservationInfo;
+}
 interface OmniSyncApiError {
     statusCode: number;
     message: string;
@@ -2870,12 +2987,16 @@ declare class OmniSyncClient {
      */
     setCheckoutCustomer(checkoutId: string, data: SetCheckoutCustomerDto): Promise<Checkout>;
     /**
-     * Set shipping address on checkout
-     * Returns the checkout and available shipping rates for the address
+     * Set shipping address on checkout (includes customer email).
+     * Returns the checkout and available shipping rates for the address.
+     *
+     * **This is the first step of the simplified checkout flow.**
+     * Email is required and will be used for order confirmation.
      *
      * @example
      * ```typescript
      * const { checkout, rates } = await omni.setShippingAddress('checkout_123', {
+     *   email: 'customer@example.com',  // Required!
      *   firstName: 'John',
      *   lastName: 'Doe',
      *   line1: '123 Main St',
@@ -2992,9 +3113,11 @@ declare class OmniSyncClient {
      * const stripeProvider = providers.find(p => p.provider === 'stripe');
      * const paypalProvider = providers.find(p => p.provider === 'paypal');
      *
-     * // Initialize Stripe if available
+     * // Initialize Stripe if available (with Connect account support)
      * if (stripeProvider) {
-     *   const stripe = await loadStripe(stripeProvider.publicKey);
+     *   const stripe = await loadStripe(stripeProvider.publicKey, {
+     *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+     *   });
      *   // Show Stripe payment form
      * }
      *
@@ -3398,6 +3521,72 @@ declare class OmniSyncClient {
      * ```
      */
     testCustomApiConnection(integrationId: string): Promise<CustomApiTestResult>;
+    /**
+     * Get product availability including reserved quantities.
+     * Use this to show accurate stock to customers when reservations are enabled.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     *
+     * @param productIds - Array of product IDs to check availability for
+     * @returns Array of availability info for each product
+     *
+     * @example
+     * ```typescript
+     * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+     * availability.forEach(item => {
+     *   if (!item.canPurchase) {
+     *     console.log(`${item.productId}: Cannot purchase`);
+     *   } else if (item.lowStock) {
+     *     console.log(`${item.productId}: Only ${item.available} left!`);
+     *   } else {
+     *     console.log(`${item.productId}: ${item.available} available`);
+     *   }
+     * });
+     * ```
+     */
+    getAvailability(productIds: string[]): Promise<ProductAvailability[]>;
+    /**
+     * Extend an active reservation to prevent it from expiring.
+     * Call this when a customer is still active in checkout to keep their items reserved.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+     *
+     * @param options - Either cartId or checkoutId to identify the reservation
+     * @returns Updated reservation info
+     *
+     * @example
+     * ```typescript
+     * // Extend reservation when customer shows activity
+     * const result = await omni.extendReservation({ checkoutId: 'chk_123' });
+     * if (result.success) {
+     *   console.log(`Reservation extended until ${result.reservation.expiresAt}`);
+     * }
+     * ```
+     */
+    extendReservation(options: {
+        cartId?: string;
+        checkoutId?: string;
+    }): Promise<ExtendReservationResponse>;
+    /**
+     * Release an active reservation, returning items to available stock.
+     * Call this when a customer abandons their cart/checkout.
+     *
+     * **Vibe-coded mode only** - requires connectionId
+     * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+     *
+     * @param options - Either cartId or checkoutId to identify the reservation
+     *
+     * @example
+     * ```typescript
+     * // Release reservation when customer abandons checkout
+     * await omni.releaseReservation({ checkoutId: 'chk_123' });
+     * ```
+     */
+    releaseReservation(options: {
+        cartId?: string;
+        checkoutId?: string;
+    }): Promise<void>;
 }
 /**
  * Custom error class for Omni-Sync API errors

package/dist/index.js

@@ -1897,12 +1897,16 @@ var OmniSyncClient = class {
     return this.adminRequest("PATCH", `/api/v1/checkout/${checkoutId}/customer`, data);
   }
   /**
-   * Set shipping address on checkout
-   * Returns the checkout and available shipping rates for the address
+   * Set shipping address on checkout (includes customer email).
+   * Returns the checkout and available shipping rates for the address.
+   *
+   * **This is the first step of the simplified checkout flow.**
+   * Email is required and will be used for order confirmation.
    *
    * @example
    * ```typescript
    * const { checkout, rates } = await omni.setShippingAddress('checkout_123', {
+   *   email: 'customer@example.com',  // Required!
    *   firstName: 'John',
    *   lastName: 'Doe',
    *   line1: '123 Main St',
@@ -2117,9 +2121,11 @@ var OmniSyncClient = class {
    * const stripeProvider = providers.find(p => p.provider === 'stripe');
    * const paypalProvider = providers.find(p => p.provider === 'paypal');
    *
-   * // Initialize Stripe if available
+   * // Initialize Stripe if available (with Connect account support)
    * if (stripeProvider) {
-   *   const stripe = await loadStripe(stripeProvider.publicKey);
+   *   const stripe = await loadStripe(stripeProvider.publicKey, {
+   *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+   *   });
    *   // Show Stripe payment form
    * }
    *
@@ -2447,7 +2453,11 @@ var OmniSyncClient = class {
       const trackingResult = await this.startGuestCheckout();
       if (trackingResult.tracked) {
         await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
-          shippingAddress: cart.shippingAddress,
+          shippingAddress: {
+            ...cart.shippingAddress,
+            email: cart.customer.email
+            // Already validated above
+          },
           billingAddress: cart.billingAddress
         });
         const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
@@ -2866,6 +2876,99 @@ var OmniSyncClient = class {
       `/api/v1/custom-api/${integrationId}/test`
     );
   }
+  // -------------------- Inventory Reservations --------------------
+  // These methods are only available in vibe-coded mode when reservation strategy
+  // is set to ON_CART or ON_CHECKOUT
+  /**
+   * Get product availability including reserved quantities.
+   * Use this to show accurate stock to customers when reservations are enabled.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   *
+   * @param productIds - Array of product IDs to check availability for
+   * @returns Array of availability info for each product
+   *
+   * @example
+   * ```typescript
+   * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+   * availability.forEach(item => {
+   *   if (!item.canPurchase) {
+   *     console.log(`${item.productId}: Cannot purchase`);
+   *   } else if (item.lowStock) {
+   *     console.log(`${item.productId}: Only ${item.available} left!`);
+   *   } else {
+   *     console.log(`${item.productId}: ${item.available} available`);
+   *   }
+   * });
+   * ```
+   */
+  async getAvailability(productIds) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "getAvailability is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    return this.vibeCodedRequest("POST", "/availability", { productIds });
+  }
+  /**
+   * Extend an active reservation to prevent it from expiring.
+   * Call this when a customer is still active in checkout to keep their items reserved.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+   *
+   * @param options - Either cartId or checkoutId to identify the reservation
+   * @returns Updated reservation info
+   *
+   * @example
+   * ```typescript
+   * // Extend reservation when customer shows activity
+   * const result = await omni.extendReservation({ checkoutId: 'chk_123' });
+   * if (result.success) {
+   *   console.log(`Reservation extended until ${result.reservation.expiresAt}`);
+   * }
+   * ```
+   */
+  async extendReservation(options) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "extendReservation is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    if (!options.cartId && !options.checkoutId) {
+      throw new OmniSyncError("Either cartId or checkoutId is required", 400);
+    }
+    return this.vibeCodedRequest("POST", "/reservation/extend", options);
+  }
+  /**
+   * Release an active reservation, returning items to available stock.
+   * Call this when a customer abandons their cart/checkout.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+   *
+   * @param options - Either cartId or checkoutId to identify the reservation
+   *
+   * @example
+   * ```typescript
+   * // Release reservation when customer abandons checkout
+   * await omni.releaseReservation({ checkoutId: 'chk_123' });
+   * ```
+   */
+  async releaseReservation(options) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "releaseReservation is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    if (!options.cartId && !options.checkoutId) {
+      throw new OmniSyncError("Either cartId or checkoutId is required", 400);
+    }
+    await this.vibeCodedRequest("POST", "/reservation/release", options);
+  }
 };
 var OmniSyncError = class extends Error {
   constructor(message, statusCode, details) {

package/dist/index.mjs

@@ -1868,12 +1868,16 @@ var OmniSyncClient = class {
     return this.adminRequest("PATCH", `/api/v1/checkout/${checkoutId}/customer`, data);
   }
   /**
-   * Set shipping address on checkout
-   * Returns the checkout and available shipping rates for the address
+   * Set shipping address on checkout (includes customer email).
+   * Returns the checkout and available shipping rates for the address.
+   *
+   * **This is the first step of the simplified checkout flow.**
+   * Email is required and will be used for order confirmation.
    *
    * @example
    * ```typescript
    * const { checkout, rates } = await omni.setShippingAddress('checkout_123', {
+   *   email: 'customer@example.com',  // Required!
    *   firstName: 'John',
    *   lastName: 'Doe',
    *   line1: '123 Main St',
@@ -2088,9 +2092,11 @@ var OmniSyncClient = class {
    * const stripeProvider = providers.find(p => p.provider === 'stripe');
    * const paypalProvider = providers.find(p => p.provider === 'paypal');
    *
-   * // Initialize Stripe if available
+   * // Initialize Stripe if available (with Connect account support)
    * if (stripeProvider) {
-   *   const stripe = await loadStripe(stripeProvider.publicKey);
+   *   const stripe = await loadStripe(stripeProvider.publicKey, {
+   *     stripeAccount: stripeProvider.stripeAccountId, // For Stripe Connect
+   *   });
    *   // Show Stripe payment form
    * }
    *
@@ -2418,7 +2424,11 @@ var OmniSyncClient = class {
       const trackingResult = await this.startGuestCheckout();
       if (trackingResult.tracked) {
         await this.updateGuestCheckoutAddress(trackingResult.checkoutId, {
-          shippingAddress: cart.shippingAddress,
+          shippingAddress: {
+            ...cart.shippingAddress,
+            email: cart.customer.email
+            // Already validated above
+          },
           billingAddress: cart.billingAddress
         });
         const orderResult = await this.completeGuestCheckout(trackingResult.checkoutId, {
@@ -2837,6 +2847,99 @@ var OmniSyncClient = class {
       `/api/v1/custom-api/${integrationId}/test`
     );
   }
+  // -------------------- Inventory Reservations --------------------
+  // These methods are only available in vibe-coded mode when reservation strategy
+  // is set to ON_CART or ON_CHECKOUT
+  /**
+   * Get product availability including reserved quantities.
+   * Use this to show accurate stock to customers when reservations are enabled.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   *
+   * @param productIds - Array of product IDs to check availability for
+   * @returns Array of availability info for each product
+   *
+   * @example
+   * ```typescript
+   * const availability = await omni.getAvailability(['prod_123', 'prod_456']);
+   * availability.forEach(item => {
+   *   if (!item.canPurchase) {
+   *     console.log(`${item.productId}: Cannot purchase`);
+   *   } else if (item.lowStock) {
+   *     console.log(`${item.productId}: Only ${item.available} left!`);
+   *   } else {
+   *     console.log(`${item.productId}: ${item.available} available`);
+   *   }
+   * });
+   * ```
+   */
+  async getAvailability(productIds) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "getAvailability is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    return this.vibeCodedRequest("POST", "/availability", { productIds });
+  }
+  /**
+   * Extend an active reservation to prevent it from expiring.
+   * Call this when a customer is still active in checkout to keep their items reserved.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+   *
+   * @param options - Either cartId or checkoutId to identify the reservation
+   * @returns Updated reservation info
+   *
+   * @example
+   * ```typescript
+   * // Extend reservation when customer shows activity
+   * const result = await omni.extendReservation({ checkoutId: 'chk_123' });
+   * if (result.success) {
+   *   console.log(`Reservation extended until ${result.reservation.expiresAt}`);
+   * }
+   * ```
+   */
+  async extendReservation(options) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "extendReservation is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    if (!options.cartId && !options.checkoutId) {
+      throw new OmniSyncError("Either cartId or checkoutId is required", 400);
+    }
+    return this.vibeCodedRequest("POST", "/reservation/extend", options);
+  }
+  /**
+   * Release an active reservation, returning items to available stock.
+   * Call this when a customer abandons their cart/checkout.
+   *
+   * **Vibe-coded mode only** - requires connectionId
+   * Only works when reservation strategy is ON_CART or ON_CHECKOUT
+   *
+   * @param options - Either cartId or checkoutId to identify the reservation
+   *
+   * @example
+   * ```typescript
+   * // Release reservation when customer abandons checkout
+   * await omni.releaseReservation({ checkoutId: 'chk_123' });
+   * ```
+   */
+  async releaseReservation(options) {
+    if (!this.isVibeCodedMode()) {
+      throw new OmniSyncError(
+        "releaseReservation is only available in vibe-coded mode (use connectionId)",
+        400
+      );
+    }
+    if (!options.cartId && !options.checkoutId) {
+      throw new OmniSyncError("Either cartId or checkoutId is required", 400);
+    }
+    await this.vibeCodedRequest("POST", "/reservation/release", options);
+  }
 };
 var OmniSyncError = class extends Error {
   constructor(message, statusCode, details) {

package/package.json

@@ -1,76 +1,76 @@
-{
-  "name": "omni-sync-sdk",
-  "version": "0.14.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",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.js",
-      "import": "./dist/index.mjs"
-    }
-  },
-  "files": [
-    "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",
-    "ecommerce",
-    "sdk",
-    "vibe-coding",
-    "vibe-coded",
-    "ai-commerce",
-    "storefront",
-    "headless-commerce",
-    "multi-platform",
-    "shopify",
-    "tiktok",
-    "cursor",
-    "lovable",
-    "v0",
-    "cart",
-    "checkout",
-    "products",
-    "sync"
-  ],
-  "author": "Omni-Sync Platform",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/omni-sync/omni-sync-platform.git",
-    "directory": "packages/sdk"
-  },
-  "homepage": "https://omni-sync.com",
-  "bugs": {
-    "url": "https://github.com/omni-sync/omni-sync-platform/issues"
-  },
-  "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.50.1",
-    "@typescript-eslint/parser": "^8.50.1",
-    "eslint": "^9.39.2",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.7.0"
-  },
-  "peerDependenciesMeta": {
-    "typescript": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "omni-sync-sdk",
+  "version": "0.15.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "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",
+    "ecommerce",
+    "sdk",
+    "vibe-coding",
+    "vibe-coded",
+    "ai-commerce",
+    "storefront",
+    "headless-commerce",
+    "multi-platform",
+    "shopify",
+    "tiktok",
+    "cursor",
+    "lovable",
+    "v0",
+    "cart",
+    "checkout",
+    "products",
+    "sync"
+  ],
+  "author": "Omni-Sync Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omni-sync/omni-sync-platform.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://omni-sync.com",
+  "bugs": {
+    "url": "https://github.com/omni-sync/omni-sync-platform/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}