omni-sync-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1137 @@
+interface OmniSyncClientOptions {
+    /**
+     * API Key for authentication (starts with "omni_")
+     */
+    apiKey: string;
+    /**
+     * Base URL of the Omni-Sync API
+     * @default "https://api.omni-sync.com"
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+interface Product {
+    id: string;
+    name: string;
+    description?: string | null;
+    sku: string;
+    basePrice: number;
+    salePrice?: number | null;
+    costPrice?: number | null;
+    status: 'active' | 'draft' | 'archived';
+    type: 'SIMPLE' | 'VARIABLE';
+    images?: ProductImage[];
+    inventory?: InventoryInfo | null;
+    variants?: ProductVariant[];
+    categories?: string[];
+    tags?: string[];
+    channels?: Record<string, Record<string, unknown>>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ProductImage {
+    url: string;
+    position?: number;
+    isMain?: boolean;
+}
+interface ProductVariant {
+    id: string;
+    sku?: string | null;
+    name?: string | null;
+    price?: number | null;
+    salePrice?: number | null;
+    attributes?: Record<string, string>;
+    inventory?: InventoryInfo | null;
+}
+interface InventoryInfo {
+    total: number;
+    reserved: number;
+    available: number;
+}
+interface ProductQueryParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    status?: 'active' | 'draft' | 'archived';
+    type?: 'SIMPLE' | 'VARIABLE';
+    sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'basePrice';
+    sortOrder?: 'asc' | 'desc';
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+interface CreateProductDto {
+    name: string;
+    sku?: string;
+    description?: string;
+    basePrice: number;
+    salePrice?: number;
+    costPrice?: number;
+    status?: 'active' | 'draft';
+    type?: 'SIMPLE' | 'VARIABLE';
+    categories?: string[];
+    tags?: string[];
+    images?: ProductImage[];
+}
+interface UpdateProductDto {
+    name?: string;
+    sku?: string;
+    description?: string;
+    basePrice?: number;
+    salePrice?: number | null;
+    costPrice?: number | null;
+    status?: 'active' | 'draft' | 'archived';
+    categories?: string[];
+    tags?: string[];
+    images?: ProductImage[];
+}
+interface Order {
+    id: string;
+    externalId?: string;
+    status: OrderStatus;
+    totalAmount: number;
+    customer: OrderCustomer;
+    items: OrderItem[];
+    platform?: string;
+    createdAt: string;
+}
+type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
+interface OrderCustomer {
+    email: string;
+    name?: string;
+    phone?: string;
+    address?: OrderAddress;
+}
+interface OrderAddress {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postalCode: string;
+    country: string;
+}
+interface OrderItem {
+    productId: string;
+    sku?: string;
+    name?: string;
+    quantity: number;
+    price: number;
+    variantId?: string;
+}
+interface OrderQueryParams {
+    page?: number;
+    limit?: number;
+    status?: OrderStatus;
+    sortBy?: 'createdAt' | 'totalAmount';
+    sortOrder?: 'asc' | 'desc';
+}
+interface CreateOrderDto {
+    items: {
+        productId: string;
+        quantity: number;
+        price: number;
+        variantId?: string;
+    }[];
+    customer: OrderCustomer;
+    totalAmount: number;
+    externalId?: string;
+}
+interface UpdateOrderDto {
+    status?: OrderStatus;
+}
+interface UpdateInventoryDto {
+    quantity: number;
+    variantId?: string;
+}
+interface SyncJob {
+    jobId: string;
+    status: 'queued' | 'processing' | 'completed' | 'failed';
+    platform?: string;
+    message?: string;
+}
+type ConnectorPlatform = 'SHOPIFY' | 'TIKTOK' | 'META' | 'WOOCOMMERCE' | 'CUSTOM';
+type CouponType = 'PERCENTAGE' | 'FIXED_AMOUNT' | 'FREE_SHIPPING' | 'BUY_X_GET_Y';
+type CouponStatus = 'ACTIVE' | 'SCHEDULED' | 'EXPIRED' | 'DISABLED';
+interface Coupon {
+    id: string;
+    code: string;
+    title?: string | null;
+    description?: string | null;
+    type: CouponType;
+    value: number;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    status: CouponStatus;
+    usageLimit?: number | null;
+    usageLimitPerCustomer?: number | null;
+    usageCount: number;
+    minimumOrderAmount?: number | null;
+    maximumDiscount?: number | null;
+    conditions?: Record<string, unknown> | null;
+    /**
+     * Product IDs this coupon applies to.
+     * If set, coupon only applies to these specific products.
+     */
+    applicableProducts?: string[] | null;
+    /**
+     * Product IDs excluded from this coupon.
+     * These products will not receive the discount even if in applicable categories.
+     */
+    excludedProducts?: string[] | null;
+    /**
+     * Category IDs this coupon applies to.
+     * If set, coupon only applies to products in these categories.
+     */
+    applicableCategories?: string[] | null;
+    /**
+     * Category IDs excluded from this coupon.
+     * Products in these categories will not receive the discount.
+     */
+    excludedCategories?: string[] | null;
+    combinesWithOther: boolean;
+    freeShipping: boolean;
+    shopifyCouponId?: string | null;
+    woocommerceCouponId?: string | null;
+    tiktokCouponId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CouponQueryParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    status?: CouponStatus;
+    type?: CouponType;
+    platform?: ConnectorPlatform;
+    sortBy?: 'code' | 'createdAt' | 'updatedAt' | 'value';
+    sortOrder?: 'asc' | 'desc';
+}
+interface CreateCouponDto {
+    code: string;
+    title?: string;
+    description?: string;
+    type: CouponType;
+    value: number;
+    startsAt?: string;
+    endsAt?: string;
+    status?: CouponStatus;
+    usageLimit?: number;
+    usageLimitPerCustomer?: number;
+    minimumOrderAmount?: number;
+    maximumDiscount?: number;
+    conditions?: Record<string, unknown>;
+    /** Product IDs this coupon applies to */
+    applicableProducts?: string[];
+    /** Product IDs excluded from this coupon */
+    excludedProducts?: string[];
+    /** Category IDs this coupon applies to */
+    applicableCategories?: string[];
+    /** Category IDs excluded from this coupon */
+    excludedCategories?: string[];
+    combinesWithOther?: boolean;
+    freeShipping?: boolean;
+    /** Platforms to publish this coupon to */
+    platforms?: ConnectorPlatform[];
+}
+interface UpdateCouponDto {
+    code?: string;
+    title?: string;
+    description?: string;
+    type?: CouponType;
+    value?: number;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    status?: CouponStatus;
+    usageLimit?: number | null;
+    usageLimitPerCustomer?: number | null;
+    minimumOrderAmount?: number | null;
+    maximumDiscount?: number | null;
+    conditions?: Record<string, unknown> | null;
+    applicableProducts?: string[] | null;
+    excludedProducts?: string[] | null;
+    applicableCategories?: string[] | null;
+    excludedCategories?: string[] | null;
+    combinesWithOther?: boolean;
+    freeShipping?: boolean;
+}
+/**
+ * Validation warning returned when syncing coupons to platforms
+ * that don't support certain features.
+ */
+interface CouponValidationWarning {
+    platform: string;
+    warnings: string[];
+}
+/**
+ * Response from createCoupon with optional validation warnings
+ */
+interface CouponCreateResponse extends Coupon {
+    validationWarnings?: CouponValidationWarning[];
+}
+/**
+ * Platform capability information for coupon features.
+ * Use this to understand what features each platform supports.
+ */
+interface PlatformCouponCapabilities {
+    supportsProducts: boolean;
+    supportsProductExclusions: boolean;
+    supportsCategories: boolean;
+    supportsCategoryExclusions: boolean;
+    maxProducts?: number | null;
+    notes: string[];
+}
+/**
+ * Helper function to check if a coupon applies to a specific product.
+ * Use this in your custom platform to implement coupon validation.
+ *
+ * Validation Order:
+ * 1. Check if product is in excludedProducts → REJECT
+ * 2. Check if product's category is in excludedCategories → REJECT
+ * 3. If applicableProducts is set → product MUST be in list
+ * 4. If applicableCategories is set → product MUST be in one of the categories
+ * 5. If no targeting rules → APPLY to all products
+ *
+ * @param coupon - The coupon to check
+ * @param productId - The product ID to validate
+ * @param productCategoryIds - Array of category IDs the product belongs to
+ * @returns true if the coupon applies to this product
+ *
+ * @example
+ * ```typescript
+ * const coupon = await omni.getCoupon('coupon_123');
+ * const product = await omni.getProduct('prod_456');
+ *
+ * if (isCouponApplicableToProduct(coupon, product.id, product.categories || [])) {
+ *   // Apply discount
+ * }
+ * ```
+ */
+declare function isCouponApplicableToProduct(coupon: Pick<Coupon, 'applicableProducts' | 'excludedProducts' | 'applicableCategories' | 'excludedCategories'>, productId: string, productCategoryIds: string[]): boolean;
+interface Customer {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    hasAccount: boolean;
+    emailVerified: boolean;
+    acceptsMarketing: boolean;
+    tags: string[];
+    totalOrders: number;
+    lastOrderAt?: string;
+    metadata?: Record<string, unknown>;
+    shopifyCustomerId?: string;
+    woocommerceCustomerId?: string;
+    tiktokCustomerId?: string;
+    addresses: CustomerAddress[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CustomerAddress {
+    id: string;
+    label?: string;
+    firstName: string;
+    lastName: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCustomerDto {
+    email: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    password?: string;
+    acceptsMarketing?: boolean;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCustomerDto {
+    email?: string;
+    phone?: string;
+    firstName?: string;
+    lastName?: string;
+    acceptsMarketing?: boolean;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface CreateAddressDto {
+    label?: string;
+    firstName: string;
+    lastName: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface UpdateAddressDto {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    line1?: string;
+    line2?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface CustomerAuthResponse {
+    customer: {
+        id: string;
+        email: string;
+        firstName?: string;
+        lastName?: string;
+        phone?: string;
+        emailVerified: boolean;
+    };
+    token: string;
+    expiresAt: string;
+}
+interface RegisterCustomerDto {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+}
+type CartStatus = 'ACTIVE' | 'MERGED' | 'CONVERTED' | 'ABANDONED';
+interface CartItem {
+    id: string;
+    productId: string;
+    variantId?: string | null;
+    quantity: number;
+    unitPrice: string;
+    discountAmount: string;
+    notes?: string | null;
+    metadata?: Record<string, unknown> | null;
+    product: {
+        id: string;
+        name: string;
+        sku: string;
+        images?: unknown[];
+    };
+    variant?: {
+        id: string;
+        name?: string | null;
+        sku?: string | null;
+        image?: unknown;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Cart {
+    id: string;
+    sessionToken?: string | null;
+    customerId?: string | null;
+    status: CartStatus;
+    currency: string;
+    notes?: string | null;
+    subtotal: string;
+    discountAmount: string;
+    couponCode?: string | null;
+    items: CartItem[];
+    itemCount: number;
+    expiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AddToCartDto {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateCartItemDto {
+    quantity: number;
+}
+interface MergeCartsDto {
+    sourceSessionToken: string;
+    targetCustomerId: string;
+}
+type CheckoutStatus = 'PENDING' | 'SHIPPING_SET' | 'PAYMENT_PENDING' | 'PAYMENT_PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED';
+interface CheckoutAddress {
+    firstName: string;
+    lastName: string;
+    company?: string | null;
+    line1: string;
+    line2?: string | null;
+    city: string;
+    region?: string | null;
+    postalCode: string;
+    country: string;
+    phone?: string | null;
+}
+interface CheckoutLineItem {
+    id: string;
+    productId: string;
+    variantId?: string | null;
+    quantity: number;
+    unitPrice: string;
+    discountAmount: string;
+    product: {
+        id: string;
+        name: string;
+        sku: string;
+        images?: unknown[];
+    };
+    variant?: {
+        id: string;
+        name?: string | null;
+        sku?: string | null;
+    } | null;
+}
+interface ShippingRate {
+    id: string;
+    name: string;
+    description?: string | null;
+    price: string;
+    currency: string;
+    estimatedDays?: number | null;
+}
+interface Checkout {
+    id: string;
+    status: CheckoutStatus;
+    email?: string | null;
+    customerId?: string | null;
+    shippingAddress?: CheckoutAddress | null;
+    billingAddress?: CheckoutAddress | null;
+    shippingRateId?: string | null;
+    shippingMethod?: ShippingRate | null;
+    currency: string;
+    subtotal: string;
+    discountAmount: string;
+    shippingAmount: string;
+    taxAmount: string;
+    total: string;
+    couponCode?: string | null;
+    items: CheckoutLineItem[];
+    itemCount: number;
+    availableShippingRates?: ShippingRate[];
+    expiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCheckoutDto {
+    cartId: string;
+    customerId?: string;
+}
+interface SetCheckoutCustomerDto {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    acceptsMarketing?: boolean;
+}
+interface SetShippingAddressDto {
+    firstName: string;
+    lastName: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    region?: string;
+    postalCode: string;
+    country: string;
+    phone?: string;
+}
+interface SetBillingAddressDto extends SetShippingAddressDto {
+    sameAsShipping?: boolean;
+}
+interface SetShippingAddressResponse {
+    checkout: Checkout;
+    rates: ShippingRate[];
+}
+interface CompleteCheckoutResponse {
+    orderId: string;
+}
+interface WebhookEvent {
+    event: WebhookEventType;
+    storeId: string;
+    entityId: string;
+    platform: string;
+    data: unknown;
+    timestamp: string;
+}
+type WebhookEventType = 'product.created' | 'product.updated' | 'product.deleted' | 'inventory.updated' | 'order.created' | 'order.updated' | 'coupon.created' | 'coupon.updated' | 'coupon.deleted' | 'cart.created' | 'cart.updated' | 'cart.abandoned' | 'checkout.started' | 'checkout.completed' | 'checkout.failed';
+interface OmniSyncApiError {
+    statusCode: number;
+    message: string;
+    error?: string;
+    details?: unknown;
+}
+
+/**
+ * OmniSyncClient - SDK for integrating vibe coding stores with Omni-Sync Platform
+ *
+ * @example
+ * ```typescript
+ * const omni = new OmniSyncClient({
+ *   apiKey: process.env.OMNI_SYNC_API_KEY!,
+ * });
+ *
+ * // Get products
+ * const products = await omni.getProducts();
+ *
+ * // Create an order
+ * const order = await omni.createOrder({
+ *   items: [{ productId: 'prod_123', quantity: 2, price: 99.99 }],
+ *   customer: { email: 'customer@example.com', name: 'John Doe' },
+ *   totalAmount: 199.98,
+ * });
+ * ```
+ */
+declare class OmniSyncClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options: OmniSyncClientOptions);
+    private request;
+    /**
+     * Get a list of products with pagination
+     */
+    getProducts(params?: ProductQueryParams): Promise<PaginatedResponse<Product>>;
+    /**
+     * Get a single product by ID
+     */
+    getProduct(productId: string): Promise<Product>;
+    /**
+     * Create a new product
+     */
+    createProduct(data: CreateProductDto): Promise<Product>;
+    /**
+     * Update an existing product
+     */
+    updateProduct(productId: string, data: UpdateProductDto): Promise<Product>;
+    /**
+     * Delete a product
+     */
+    deleteProduct(productId: string): Promise<void>;
+    /**
+     * Get a list of orders with pagination
+     */
+    getOrders(params?: OrderQueryParams): Promise<PaginatedResponse<Order>>;
+    /**
+     * Get a single order by ID
+     */
+    getOrder(orderId: string): Promise<Order>;
+    /**
+     * Create a new order
+     * This will automatically deduct inventory and sync to connected platforms
+     */
+    createOrder(data: CreateOrderDto): Promise<Order>;
+    /**
+     * Update an order (e.g., change status)
+     */
+    updateOrder(orderId: string, data: UpdateOrderDto): Promise<Order>;
+    /**
+     * Update inventory for a product
+     * This will sync inventory to all connected platforms
+     */
+    updateInventory(productId: string, data: UpdateInventoryDto): Promise<void>;
+    /**
+     * Get current inventory for a product
+     */
+    getInventory(productId: string): Promise<{
+        available: number;
+        reserved: number;
+        total: number;
+    }>;
+    /**
+     * Trigger a sync to a specific platform or all platforms
+     */
+    triggerSync(platform?: ConnectorPlatform): Promise<SyncJob>;
+    /**
+     * Get the status of a sync job
+     */
+    getSyncStatus(jobId: string): Promise<SyncJob>;
+    /**
+     * Get information about the connected store
+     */
+    getStoreInfo(): Promise<{
+        id: string;
+        name: string;
+        currency: string;
+        language: string;
+        connectedPlatforms: ConnectorPlatform[];
+    }>;
+    /**
+     * Get a list of coupons with pagination
+     */
+    getCoupons(params?: CouponQueryParams): Promise<PaginatedResponse<Coupon>>;
+    /**
+     * Get a single coupon by ID
+     */
+    getCoupon(couponId: string): Promise<Coupon>;
+    /**
+     * Create a new coupon.
+     * Returns validation warnings if syncing to platforms that don't support certain features.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await omni.createCoupon({
+     *   code: 'SUMMER20',
+     *   type: 'PERCENTAGE',
+     *   value: 20,
+     *   applicableCategories: ['cat_electronics'],
+     *   excludedProducts: ['prod_clearance_item'],
+     *   platforms: ['WOOCOMMERCE', 'SHOPIFY'],
+     * });
+     *
+     * // Check for platform limitations
+     * if (coupon.validationWarnings?.length) {
+     *   console.warn('Some features not supported:', coupon.validationWarnings);
+     * }
+     * ```
+     */
+    createCoupon(data: CreateCouponDto): Promise<CouponCreateResponse>;
+    /**
+     * Update an existing coupon
+     */
+    updateCoupon(couponId: string, data: UpdateCouponDto): Promise<Coupon>;
+    /**
+     * Delete a coupon
+     */
+    deleteCoupon(couponId: string): Promise<void>;
+    /**
+     * Sync a coupon to all connected platforms.
+     * Returns a sync job that can be tracked with getSyncStatus().
+     */
+    syncCoupon(couponId: string): Promise<SyncJob>;
+    /**
+     * Publish a coupon to specific platforms.
+     * Use this for selective syncing instead of syncing to all platforms.
+     *
+     * @example
+     * ```typescript
+     * // Only sync to WooCommerce and Shopify
+     * await omni.publishCoupon('coupon_123', ['WOOCOMMERCE', 'SHOPIFY']);
+     * ```
+     */
+    publishCoupon(couponId: string, platforms: ConnectorPlatform[]): Promise<SyncJob>;
+    /**
+     * Get platform capabilities for coupon features.
+     * Use this to understand what features each platform supports.
+     *
+     * @example
+     * ```typescript
+     * const capabilities = await omni.getCouponPlatformCapabilities();
+     * if (!capabilities.SHOPIFY.supportsProductExclusions) {
+     *   console.log('Shopify does not support product exclusions');
+     * }
+     * ```
+     */
+    getCouponPlatformCapabilities(): Promise<Record<string, PlatformCouponCapabilities>>;
+    /**
+     * Create a new customer
+     *
+     * @example
+     * ```typescript
+     * const customer = await omni.createCustomer({
+     *   email: 'customer@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   acceptsMarketing: true,
+     * });
+     * ```
+     */
+    createCustomer(data: CreateCustomerDto): Promise<Customer>;
+    /**
+     * Get a customer by ID
+     */
+    getCustomer(customerId: string): Promise<Customer>;
+    /**
+     * Update a customer
+     */
+    updateCustomer(customerId: string, data: UpdateCustomerDto): Promise<Customer>;
+    /**
+     * Get a customer by email
+     */
+    getCustomerByEmail(email: string): Promise<Customer | null>;
+    /**
+     * Login an existing customer (returns JWT token)
+     *
+     * @example
+     * ```typescript
+     * const auth = await omni.loginCustomer('customer@example.com', 'password123');
+     * console.log('Customer logged in:', auth.customer.email);
+     * // Store auth.token for subsequent authenticated requests
+     * ```
+     */
+    loginCustomer(email: string, password: string): Promise<CustomerAuthResponse>;
+    /**
+     * Register a new customer with password (creates account)
+     *
+     * @example
+     * ```typescript
+     * const auth = await omni.registerCustomer({
+     *   email: 'newcustomer@example.com',
+     *   password: 'securepassword123',
+     *   firstName: 'Jane',
+     *   lastName: 'Doe',
+     * });
+     * ```
+     */
+    registerCustomer(data: RegisterCustomerDto): Promise<CustomerAuthResponse>;
+    /**
+     * Request a password reset email for a customer
+     */
+    forgotPassword(email: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get all addresses for a customer
+     */
+    getCustomerAddresses(customerId: string): Promise<CustomerAddress[]>;
+    /**
+     * Add an address to a customer
+     *
+     * @example
+     * ```typescript
+     * const address = await omni.addCustomerAddress('cust_123', {
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   line1: '123 Main St',
+     *   city: 'New York',
+     *   region: 'NY',
+     *   postalCode: '10001',
+     *   country: 'US',
+     *   isDefault: true,
+     * });
+     * ```
+     */
+    addCustomerAddress(customerId: string, address: CreateAddressDto): Promise<CustomerAddress>;
+    /**
+     * Update a customer address
+     */
+    updateCustomerAddress(customerId: string, addressId: string, address: UpdateAddressDto): Promise<CustomerAddress>;
+    /**
+     * Delete a customer address
+     */
+    deleteCustomerAddress(customerId: string, addressId: string): Promise<void>;
+    /**
+     * Get orders for a customer
+     *
+     * @example
+     * ```typescript
+     * const orders = await omni.getCustomerOrders('cust_123', { page: 1, limit: 10 });
+     * console.log(`Customer has ${orders.meta.total} total orders`);
+     * ```
+     */
+    getCustomerOrders(customerId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Order>>;
+    /**
+     * Create a new cart for a guest user
+     * Returns a cart with a sessionToken that identifies this cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.createCart();
+     * console.log('Cart session:', cart.sessionToken);
+     * // Store sessionToken in localStorage or cookie
+     * ```
+     */
+    createCart(): Promise<Cart>;
+    /**
+     * Get a cart by session token (for guest users)
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.getCartBySession('sess_abc123');
+     * console.log('Items in cart:', cart.itemCount);
+     * ```
+     */
+    getCartBySession(sessionToken: string): Promise<Cart>;
+    /**
+     * Get a cart by customer ID (for authenticated users)
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.getCartByCustomer('cust_123');
+     * console.log('Customer cart total:', cart.subtotal);
+     * ```
+     */
+    getCartByCustomer(customerId: string): Promise<Cart>;
+    /**
+     * Get a cart by ID
+     */
+    getCart(cartId: string): Promise<Cart>;
+    /**
+     * Add an item to the cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.addToCart('cart_123', {
+     *   productId: 'prod_abc',
+     *   quantity: 2,
+     *   notes: 'Gift wrap please',
+     * });
+     * ```
+     */
+    addToCart(cartId: string, item: AddToCartDto): Promise<Cart>;
+    /**
+     * Update an item quantity in the cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.updateCartItem('cart_123', 'item_456', { quantity: 3 });
+     * ```
+     */
+    updateCartItem(cartId: string, itemId: string, data: UpdateCartItemDto): Promise<Cart>;
+    /**
+     * Remove an item from the cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.removeCartItem('cart_123', 'item_456');
+     * ```
+     */
+    removeCartItem(cartId: string, itemId: string): Promise<Cart>;
+    /**
+     * Clear all items from the cart
+     *
+     * @example
+     * ```typescript
+     * await omni.clearCart('cart_123');
+     * ```
+     */
+    clearCart(cartId: string): Promise<void>;
+    /**
+     * Apply a coupon to the cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.applyCoupon('cart_123', 'SAVE20');
+     * console.log('Discount:', cart.discountAmount);
+     * ```
+     */
+    applyCoupon(cartId: string, code: string): Promise<Cart>;
+    /**
+     * Remove a coupon from the cart
+     *
+     * @example
+     * ```typescript
+     * const cart = await omni.removeCoupon('cart_123');
+     * ```
+     */
+    removeCoupon(cartId: string): Promise<Cart>;
+    /**
+     * Merge a guest cart into a customer's cart (after login)
+     * The guest cart items are moved to the customer's cart
+     *
+     * @example
+     * ```typescript
+     * // After customer logs in, merge their guest cart
+     * const mergedCart = await omni.mergeCarts({
+     *   sourceSessionToken: 'sess_guest_abc',
+     *   targetCustomerId: 'cust_123',
+     * });
+     * ```
+     */
+    mergeCarts(data: MergeCartsDto): Promise<Cart>;
+    /**
+     * Create a checkout from a cart
+     * Starts the checkout process and returns checkout with available options
+     *
+     * @example
+     * ```typescript
+     * const checkout = await omni.createCheckout({ cartId: 'cart_123' });
+     * console.log('Checkout created:', checkout.id);
+     * ```
+     */
+    createCheckout(data: CreateCheckoutDto): Promise<Checkout>;
+    /**
+     * Get a checkout by ID
+     *
+     * @example
+     * ```typescript
+     * const checkout = await omni.getCheckout('checkout_123');
+     * console.log('Status:', checkout.status);
+     * ```
+     */
+    getCheckout(checkoutId: string): Promise<Checkout>;
+    /**
+     * Set customer information on checkout
+     *
+     * @example
+     * ```typescript
+     * const checkout = await omni.setCheckoutCustomer('checkout_123', {
+     *   email: 'customer@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     * });
+     * ```
+     */
+    setCheckoutCustomer(checkoutId: string, data: SetCheckoutCustomerDto): Promise<Checkout>;
+    /**
+     * Set shipping address on checkout
+     * Returns the checkout and available shipping rates for the address
+     *
+     * @example
+     * ```typescript
+     * const { checkout, rates } = await omni.setShippingAddress('checkout_123', {
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   line1: '123 Main St',
+     *   city: 'New York',
+     *   region: 'NY',
+     *   postalCode: '10001',
+     *   country: 'US',
+     * });
+     * console.log('Available rates:', rates);
+     * ```
+     */
+    setShippingAddress(checkoutId: string, address: SetShippingAddressDto): Promise<SetShippingAddressResponse>;
+    /**
+     * Get available shipping rates for a checkout
+     * Requires shipping address to be set first
+     *
+     * @example
+     * ```typescript
+     * const rates = await omni.getShippingRates('checkout_123');
+     * console.log('Shipping options:', rates);
+     * ```
+     */
+    getShippingRates(checkoutId: string): Promise<ShippingRate[]>;
+    /**
+     * Select a shipping method for checkout
+     *
+     * @example
+     * ```typescript
+     * const checkout = await omni.selectShippingMethod('checkout_123', 'rate_express');
+     * console.log('Shipping cost:', checkout.shippingAmount);
+     * ```
+     */
+    selectShippingMethod(checkoutId: string, shippingRateId: string): Promise<Checkout>;
+    /**
+     * Set billing address on checkout
+     * Can optionally use shipping address as billing address
+     *
+     * @example
+     * ```typescript
+     * // Use same as shipping
+     * const checkout = await omni.setBillingAddress('checkout_123', {
+     *   ...shippingAddress,
+     *   sameAsShipping: true,
+     * });
+     *
+     * // Or set different billing address
+     * const checkout = await omni.setBillingAddress('checkout_123', {
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   line1: '456 Business Ave',
+     *   city: 'New York',
+     *   region: 'NY',
+     *   postalCode: '10002',
+     *   country: 'US',
+     * });
+     * ```
+     */
+    setBillingAddress(checkoutId: string, address: SetBillingAddressDto): Promise<Checkout>;
+    /**
+     * Complete the checkout and create an order
+     * Requires customer email, shipping address, and shipping method to be set
+     *
+     * @example
+     * ```typescript
+     * const { orderId } = await omni.completeCheckout('checkout_123');
+     * console.log('Order created:', orderId);
+     * ```
+     */
+    completeCheckout(checkoutId: string): Promise<CompleteCheckoutResponse>;
+}
+/**
+ * Custom error class for Omni-Sync API errors
+ */
+declare class OmniSyncError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(message: string, statusCode: number, details?: unknown);
+}
+
+/**
+ * Verify a webhook signature from Omni-Sync
+ *
+ * @param payload - The raw webhook payload (as string or object)
+ * @param signature - The X-Omni-Signature header value
+ * @param secret - Your webhook secret
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@omni-sync/sdk';
+ *
+ * app.post('/webhooks/omni-sync', async (req, res) => {
+ *   const signature = req.headers['x-omni-signature'];
+ *   const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Process webhook...
+ * });
+ * ```
+ */
+declare function verifyWebhook(payload: string | object, signature: string | undefined | null, secret: string): boolean;
+/**
+ * Parse a webhook payload into a typed WebhookEvent
+ *
+ * @param payload - The raw webhook payload
+ * @returns Typed WebhookEvent object
+ */
+declare function parseWebhookEvent(payload: unknown): WebhookEvent;
+/**
+ * Type guard for checking webhook event type
+ */
+declare function isWebhookEventType(event: WebhookEvent, type: WebhookEventType): boolean;
+/**
+ * Create a webhook handler with typed event handlers
+ *
+ * @example
+ * ```typescript
+ * const handler = createWebhookHandler({
+ *   'product.updated': async (event) => {
+ *     console.log('Product updated:', event.entityId);
+ *     await refreshProductCache(event.entityId);
+ *   },
+ *   'inventory.updated': async (event) => {
+ *     console.log('Inventory changed for:', event.entityId);
+ *   },
+ * });
+ *
+ * // In your API route
+ * await handler(webhookPayload);
+ * ```
+ */
+declare function createWebhookHandler(handlers: Partial<Record<WebhookEventType, (event: WebhookEvent) => Promise<void>>>): (payload: unknown) => Promise<void>;
+
+export { type ConnectorPlatform, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateCouponDto, type CreateOrderDto, type CreateProductDto, type InventoryInfo, 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 ProductImage, type ProductQueryParams, type ProductVariant, type SyncJob, type UpdateCouponDto, type UpdateInventoryDto, type UpdateOrderDto, type UpdateProductDto, type WebhookEvent, type WebhookEventType, createWebhookHandler, isCouponApplicableToProduct, isWebhookEventType, parseWebhookEvent, verifyWebhook };