omni-sync-sdk 0.8.2 → 0.9.0

package/README.md

@@ -38,10 +38,10 @@ const { data: products } = await omni.getProducts();
 
 > **IMPORTANT:** There are TWO different checkout flows. You MUST use the correct one based on whether the customer is logged in or not.
 
-| Customer Type | Cart Type | Checkout Method | Orders Linked to Account? |
-|---------------|-----------|-----------------|---------------------------|
-| **Guest** | Local Cart (localStorage) | `submitGuestOrder()` | No |
-| **Logged In** | Server Cart | `completeCheckout()` | Yes |
+| Customer Type | Cart Type                 | Checkout Method      | Orders Linked to Account? |
+| ------------- | ------------------------- | -------------------- | ------------------------- |
+| **Guest**     | Local Cart (localStorage) | `submitGuestOrder()` | No                        |
+| **Logged In** | Server Cart               | `completeCheckout()` | Yes                       |
 
 ### Decision Flow
 
@@ -2110,6 +2110,7 @@ export default function CheckoutPage() {
 ```
 
 > **Key Points:**
+>
 > - `isLoggedIn()` determines which flow to use
 > - Logged-in customers use `createCart()` → `createCheckout()` → `completeCheckout()`
 > - Guests use local cart + `submitGuestOrder()`

package/dist/index.d.mts

@@ -65,6 +65,12 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+interface ProductMetafield {
+    key: string;
+    value: string;
+    name?: string;
+    type?: string;
+}
 interface Product {
     id: string;
     name: string;
@@ -82,6 +88,7 @@ interface Product {
     variants?: ProductVariant[];
     categories?: string[];
     tags?: string[];
+    metafields?: ProductMetafield[];
     channels?: Record<string, Record<string, unknown>>;
     createdAt: string;
     updatedAt: string;
@@ -993,6 +1000,37 @@ interface ReconcileInventoryResponse {
     reconciled?: number;
     discrepancies?: number;
 }
+interface StockAvailabilityRequest {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+}
+interface StockAvailabilityResult {
+    productId: string;
+    variantId?: string | null;
+    isAvailable: boolean;
+    available: number;
+    requested: number;
+    shortfall: number;
+}
+interface StockAvailabilityResponse {
+    allAvailable: boolean;
+    results: StockAvailabilityResult[];
+}
+interface InsufficientStockError {
+    code: 'INSUFFICIENT_STOCK';
+    message: string;
+    available: number;
+    requested: number;
+    productId?: string;
+    variantId?: string;
+    items?: Array<{
+        productId: string;
+        variantId?: string;
+        available: number;
+        requested: number;
+    }>;
+}
 interface PublishProductResponse {
     productId: string;
     results: Record<string, {
@@ -1561,6 +1599,27 @@ declare class OmniSyncClient {
         productId?: string;
         autoFix?: boolean;
     }): Promise<ReconcileInventoryResponse>;
+    /**
+     * Check stock availability for one or more items before adding to cart or checkout
+     * Use this to validate stock before operations that might fail due to insufficient inventory
+     *
+     * @example
+     * ```typescript
+     * // Check if items are available before adding to cart
+     * const result = await omni.checkStockAvailability([
+     *   { productId: 'prod_123', quantity: 2 },
+     *   { productId: 'prod_456', variantId: 'var_789', quantity: 1 }
+     * ]);
+     *
+     * if (!result.allAvailable) {
+     *   const unavailable = result.results.filter(r => !r.isAvailable);
+     *   unavailable.forEach(item => {
+     *     console.log(`Only ${item.available} available for product ${item.productId}`);
+     *   });
+     * }
+     * ```
+     */
+    checkStockAvailability(items: StockAvailabilityRequest[]): Promise<StockAvailabilityResponse>;
     /**
      * Trigger a sync to a specific platform or all platforms
      */
@@ -2549,4 +2608,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 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 FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, 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 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 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 WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, 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 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 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 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 WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.d.ts

@@ -65,6 +65,12 @@ interface CustomerProfile {
     createdAt: string;
     updatedAt: string;
 }
+interface ProductMetafield {
+    key: string;
+    value: string;
+    name?: string;
+    type?: string;
+}
 interface Product {
     id: string;
     name: string;
@@ -82,6 +88,7 @@ interface Product {
     variants?: ProductVariant[];
     categories?: string[];
     tags?: string[];
+    metafields?: ProductMetafield[];
     channels?: Record<string, Record<string, unknown>>;
     createdAt: string;
     updatedAt: string;
@@ -993,6 +1000,37 @@ interface ReconcileInventoryResponse {
     reconciled?: number;
     discrepancies?: number;
 }
+interface StockAvailabilityRequest {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+}
+interface StockAvailabilityResult {
+    productId: string;
+    variantId?: string | null;
+    isAvailable: boolean;
+    available: number;
+    requested: number;
+    shortfall: number;
+}
+interface StockAvailabilityResponse {
+    allAvailable: boolean;
+    results: StockAvailabilityResult[];
+}
+interface InsufficientStockError {
+    code: 'INSUFFICIENT_STOCK';
+    message: string;
+    available: number;
+    requested: number;
+    productId?: string;
+    variantId?: string;
+    items?: Array<{
+        productId: string;
+        variantId?: string;
+        available: number;
+        requested: number;
+    }>;
+}
 interface PublishProductResponse {
     productId: string;
     results: Record<string, {
@@ -1561,6 +1599,27 @@ declare class OmniSyncClient {
         productId?: string;
         autoFix?: boolean;
     }): Promise<ReconcileInventoryResponse>;
+    /**
+     * Check stock availability for one or more items before adding to cart or checkout
+     * Use this to validate stock before operations that might fail due to insufficient inventory
+     *
+     * @example
+     * ```typescript
+     * // Check if items are available before adding to cart
+     * const result = await omni.checkStockAvailability([
+     *   { productId: 'prod_123', quantity: 2 },
+     *   { productId: 'prod_456', variantId: 'var_789', quantity: 1 }
+     * ]);
+     *
+     * if (!result.allAvailable) {
+     *   const unavailable = result.results.filter(r => !r.isAvailable);
+     *   unavailable.forEach(item => {
+     *     console.log(`Only ${item.available} available for product ${item.productId}`);
+     *   });
+     * }
+     * ```
+     */
+    checkStockAvailability(items: StockAvailabilityRequest[]): Promise<StockAvailabilityResponse>;
     /**
      * Trigger a sync to a specific platform or all platforms
      */
@@ -2549,4 +2608,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 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 FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, 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 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 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 WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, 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 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 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 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 WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };

package/dist/index.js

@@ -880,6 +880,47 @@ var OmniSyncClient = class {
       queryParams
     );
   }
+  /**
+   * Check stock availability for one or more items before adding to cart or checkout
+   * Use this to validate stock before operations that might fail due to insufficient inventory
+   *
+   * @example
+   * ```typescript
+   * // Check if items are available before adding to cart
+   * const result = await omni.checkStockAvailability([
+   *   { productId: 'prod_123', quantity: 2 },
+   *   { productId: 'prod_456', variantId: 'var_789', quantity: 1 }
+   * ]);
+   *
+   * if (!result.allAvailable) {
+   *   const unavailable = result.results.filter(r => !r.isAvailable);
+   *   unavailable.forEach(item => {
+   *     console.log(`Only ${item.available} available for product ${item.productId}`);
+   *   });
+   * }
+   * ```
+   */
+  async checkStockAvailability(items) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        "/inventory/check-availability",
+        { items }
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/inventory/check-availability",
+        { items }
+      );
+    }
+    return this.request(
+      "POST",
+      "/api/v1/inventory/check-availability",
+      { items }
+    );
+  }
   // -------------------- Sync --------------------
   /**
    * Trigger a sync to a specific platform or all platforms

package/dist/index.mjs

@@ -855,6 +855,47 @@ var OmniSyncClient = class {
       queryParams
     );
   }
+  /**
+   * Check stock availability for one or more items before adding to cart or checkout
+   * Use this to validate stock before operations that might fail due to insufficient inventory
+   *
+   * @example
+   * ```typescript
+   * // Check if items are available before adding to cart
+   * const result = await omni.checkStockAvailability([
+   *   { productId: 'prod_123', quantity: 2 },
+   *   { productId: 'prod_456', variantId: 'var_789', quantity: 1 }
+   * ]);
+   *
+   * if (!result.allAvailable) {
+   *   const unavailable = result.results.filter(r => !r.isAvailable);
+   *   unavailable.forEach(item => {
+   *     console.log(`Only ${item.available} available for product ${item.productId}`);
+   *   });
+   * }
+   * ```
+   */
+  async checkStockAvailability(items) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "POST",
+        "/inventory/check-availability",
+        { items }
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "POST",
+        "/inventory/check-availability",
+        { items }
+      );
+    }
+    return this.request(
+      "POST",
+      "/api/v1/inventory/check-availability",
+      { items }
+    );
+  }
   // -------------------- Sync --------------------
   /**
    * Trigger a sync to a specific platform or all platforms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-sync-sdk",
-  "version": "0.8.2",
+  "version": "0.9.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",
@@ -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"
   }
-}
+}