omni-sync-sdk 0.4.1 → 0.6.1

package/dist/index.d.mts

@@ -69,6 +69,7 @@ interface Product {
     id: string;
     name: string;
     description?: string | null;
+    descriptionFormat?: 'text' | 'html' | 'markdown';
     sku: string;
     basePrice: number;
     salePrice?: number | null;
@@ -537,6 +538,108 @@ interface MergeCartsDto {
     sourceSessionToken: string;
     targetCustomerId: string;
 }
+/**
+ * Local cart item stored in localStorage/cookies
+ * Used for guest checkout without server-side cart
+ */
+interface LocalCartItem {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    name?: string;
+    sku?: string;
+    price?: string;
+    image?: string;
+    addedAt: string;
+}
+/**
+ * Local cart stored in localStorage/cookies
+ * Complete client-side cart for guest users
+ */
+interface LocalCart {
+    items: LocalCartItem[];
+    couponCode?: string;
+    customer?: {
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+    };
+    shippingAddress?: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        region?: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    };
+    billingAddress?: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        region?: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    };
+    notes?: string;
+    updatedAt: string;
+}
+/**
+ * DTO for creating order directly (guest checkout)
+ */
+interface CreateGuestOrderDto {
+    items: Array<{
+        productId: string;
+        variantId?: string;
+        quantity: number;
+    }>;
+    customer: {
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+    };
+    shippingAddress: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        region?: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    };
+    billingAddress?: {
+        firstName: string;
+        lastName: string;
+        line1: string;
+        line2?: string;
+        city: string;
+        region?: string;
+        postalCode: string;
+        country: string;
+        phone?: string;
+    };
+    couponCode?: string;
+    notes?: string;
+}
+/**
+ * Response from guest order creation
+ */
+interface GuestOrderResponse {
+    orderId: string;
+    orderNumber: string;
+    status: string;
+    total: number;
+    message: string;
+}
 type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'PAYMENT_PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED';
 interface CheckoutAddress {
     firstName: string;
@@ -823,6 +926,63 @@ interface PublishProductResponse {
         error?: string;
     }>;
 }
+type CustomApiAuthType = 'api_key' | 'bearer' | 'basic' | 'oauth2';
+type CustomApiSyncDirection = 'inbound' | 'outbound' | 'bidirectional';
+type CustomApiConnectionStatus = 'CONNECTED' | 'DISCONNECTED' | 'PAUSED' | 'ERROR';
+interface CustomApiCredentials {
+    apiKey?: string;
+    bearerToken?: string;
+    username?: string;
+    password?: string;
+    headerName?: string;
+}
+interface CustomApiSyncConfig {
+    products?: boolean;
+    orders?: boolean;
+    inventory?: boolean;
+}
+interface CustomApiIntegration {
+    id: string;
+    storeId: string;
+    name: string;
+    description?: string | null;
+    baseUrl: string;
+    authType: CustomApiAuthType;
+    credentials?: CustomApiCredentials;
+    status: CustomApiConnectionStatus;
+    enabled: boolean;
+    syncDirection: CustomApiSyncDirection;
+    syncConfig?: CustomApiSyncConfig | null;
+    lastSyncAt?: string | null;
+    lastError?: string | null;
+    lastErrorAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCustomApiDto {
+    name: string;
+    description?: string;
+    baseUrl: string;
+    authType: CustomApiAuthType;
+    credentials?: CustomApiCredentials;
+    syncDirection?: CustomApiSyncDirection;
+    syncConfig?: CustomApiSyncConfig;
+}
+interface UpdateCustomApiDto {
+    name?: string;
+    description?: string;
+    baseUrl?: string;
+    authType?: CustomApiAuthType;
+    credentials?: CustomApiCredentials;
+    enabled?: boolean;
+    syncDirection?: CustomApiSyncDirection;
+    syncConfig?: CustomApiSyncConfig;
+}
+interface CustomApiTestResult {
+    success: boolean;
+    latency?: number;
+    error?: string;
+}
 interface OmniSyncApiError {
     statusCode: number;
     message: string;
@@ -1556,7 +1716,7 @@ declare class OmniSyncClient {
      * await omni.clearCart('cart_123');
      * ```
      */
-    clearCart(cartId: string): Promise<void>;
+    clearCart(cartId: string): Promise<Cart>;
     /**
      * Apply a coupon to the cart
      *
@@ -1700,6 +1860,149 @@ declare class OmniSyncClient {
      * ```
      */
     completeCheckout(checkoutId: string): Promise<CompleteCheckoutResponse>;
+    private readonly LOCAL_CART_KEY;
+    /**
+     * Check if localStorage is available (browser environment)
+     */
+    private isLocalStorageAvailable;
+    /**
+     * Get local cart from localStorage
+     * Returns empty cart if none exists
+     *
+     * @example
+     * ```typescript
+     * const cart = omni.getLocalCart();
+     * console.log('Items in cart:', cart.items.length);
+     * ```
+     */
+    getLocalCart(): LocalCart;
+    /**
+     * Save local cart to localStorage
+     */
+    private saveLocalCart;
+    /**
+     * Add item to local cart (NO API call)
+     * If item already exists, updates quantity
+     *
+     * @example
+     * ```typescript
+     * omni.addToLocalCart({
+     *   productId: 'prod_123',
+     *   quantity: 2,
+     *   name: 'Cool Shirt',
+     *   price: '29.99',
+     * });
+     * ```
+     */
+    addToLocalCart(item: Omit<LocalCartItem, 'addedAt'>): LocalCart;
+    /**
+     * Update item quantity in local cart
+     * Set quantity to 0 to remove item
+     *
+     * @example
+     * ```typescript
+     * omni.updateLocalCartItem('prod_123', 3); // Set quantity to 3
+     * omni.updateLocalCartItem('prod_123', 0); // Remove item
+     * ```
+     */
+    updateLocalCartItem(productId: string, quantity: number, variantId?: string): LocalCart;
+    /**
+     * Remove item from local cart
+     *
+     * @example
+     * ```typescript
+     * omni.removeFromLocalCart('prod_123');
+     * omni.removeFromLocalCart('prod_456', 'variant_789');
+     * ```
+     */
+    removeFromLocalCart(productId: string, variantId?: string): LocalCart;
+    /**
+     * Clear all items from local cart
+     *
+     * @example
+     * ```typescript
+     * omni.clearLocalCart();
+     * ```
+     */
+    clearLocalCart(): LocalCart;
+    /**
+     * Set customer info on local cart
+     *
+     * @example
+     * ```typescript
+     * omni.setLocalCartCustomer({
+     *   email: 'john@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     * });
+     * ```
+     */
+    setLocalCartCustomer(customer: LocalCart['customer']): LocalCart;
+    /**
+     * Set shipping address on local cart
+     *
+     * @example
+     * ```typescript
+     * omni.setLocalCartShippingAddress({
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   line1: '123 Main St',
+     *   city: 'Tel Aviv',
+     *   postalCode: '6100000',
+     *   country: 'IL',
+     * });
+     * ```
+     */
+    setLocalCartShippingAddress(address: LocalCart['shippingAddress']): LocalCart;
+    /**
+     * Set billing address on local cart
+     */
+    setLocalCartBillingAddress(address: LocalCart['billingAddress']): LocalCart;
+    /**
+     * Set coupon code on local cart
+     */
+    setLocalCartCoupon(couponCode: string | undefined): LocalCart;
+    /**
+     * Get total items count in local cart
+     */
+    getLocalCartItemCount(): number;
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * // Build up the local cart first
+     * omni.addToLocalCart({ productId: 'prod_123', quantity: 2 });
+     * omni.setLocalCartCustomer({ email: 'john@example.com', firstName: 'John' });
+     * omni.setLocalCartShippingAddress({ ... });
+     *
+     * // Then submit the order
+     * const result = await omni.submitGuestOrder();
+     * console.log('Order created:', result.orderId);
+     *
+     * // Clear cart after successful order
+     * omni.clearLocalCart();
+     * ```
+     */
+    submitGuestOrder(options?: {
+        clearCartOnSuccess?: boolean;
+    }): Promise<GuestOrderResponse>;
+    /**
+     * Create order from custom data (not from local cart)
+     * Use this if you manage cart state yourself
+     *
+     * @example
+     * ```typescript
+     * const result = await omni.createGuestOrder({
+     *   items: [{ productId: 'prod_123', quantity: 2 }],
+     *   customer: { email: 'john@example.com' },
+     *   shippingAddress: { firstName: 'John', ... },
+     * });
+     * ```
+     */
+    createGuestOrder(data: CreateGuestOrderDto): Promise<GuestOrderResponse>;
     /**
      * Get the current customer's profile (requires customerToken)
      * Only available in storefront mode
@@ -1756,6 +2059,92 @@ declare class OmniSyncClient {
      * Only available in storefront mode
      */
     getMyCart(): Promise<Cart>;
+    /**
+     * Get all Custom API integrations for a store
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * const integrations = await omni.getCustomApiIntegrations();
+     * integrations.forEach(api => {
+     *   console.log(`${api.name}: ${api.status}`);
+     * });
+     * ```
+     */
+    getCustomApiIntegrations(): Promise<CustomApiIntegration[]>;
+    /**
+     * Get a single Custom API integration by ID
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * const api = await omni.getCustomApiIntegration('api_123');
+     * console.log(`API: ${api.name}, URL: ${api.baseUrl}`);
+     * ```
+     */
+    getCustomApiIntegration(integrationId: string): Promise<CustomApiIntegration>;
+    /**
+     * Create a new Custom API integration
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * const api = await omni.createCustomApiIntegration({
+     *   name: 'My External API',
+     *   baseUrl: 'https://api.example.com',
+     *   authType: 'api_key',
+     *   credentials: {
+     *     apiKey: 'sk_123...',
+     *     headerName: 'X-API-Key',
+     *   },
+     *   syncDirection: 'bidirectional',
+     *   syncConfig: {
+     *     products: true,
+     *     orders: true,
+     *     inventory: true,
+     *   },
+     * });
+     * ```
+     */
+    createCustomApiIntegration(data: CreateCustomApiDto): Promise<CustomApiIntegration>;
+    /**
+     * Update a Custom API integration
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * const api = await omni.updateCustomApiIntegration('api_123', {
+     *   enabled: false,
+     *   syncConfig: { products: true, orders: false, inventory: true },
+     * });
+     * ```
+     */
+    updateCustomApiIntegration(integrationId: string, data: UpdateCustomApiDto): Promise<CustomApiIntegration>;
+    /**
+     * Delete a Custom API integration
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * await omni.deleteCustomApiIntegration('api_123');
+     * ```
+     */
+    deleteCustomApiIntegration(integrationId: string): Promise<void>;
+    /**
+     * Test connection to a Custom API
+     * Requires Admin mode (apiKey)
+     *
+     * @example
+     * ```typescript
+     * const result = await omni.testCustomApiConnection('api_123');
+     * if (result.success) {
+     *   console.log(`Connection OK, latency: ${result.latency}ms`);
+     * } else {
+     *   console.error(`Connection failed: ${result.error}`);
+     * }
+     * ```
+     */
+    testCustomApiConnection(integrationId: string): Promise<CustomApiTestResult>;
 }
 /**
  * Custom error class for Omni-Sync API errors
@@ -1823,4 +2212,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 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 CreateCustomerDto, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type InventoryInfo, type InventorySyncStatus, type MergeCartsDto, 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 ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, 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 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 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 CustomerProfile, type CustomerQueryParams, type DraftLineItem, type EditInventoryDto, type FulfillOrderDto, type GuestOrderResponse, type InventoryInfo, type InventorySyncStatus, type LocalCart, type LocalCartItem, type MergeCartsDto, 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 ProductVariant, type PublishProductResponse, type ReconcileInventoryResponse, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, 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 };