omni-sync-sdk 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -373,6 +373,14 @@ interface UpdateCustomerDto {
     tags?: string[];
     metadata?: Record<string, unknown>;
 }
+interface CustomerQueryParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    hasAccount?: boolean;
+    sortBy?: 'createdAt' | 'email' | 'firstName' | 'lastName' | 'lastOrderAt';
+    sortOrder?: 'asc' | 'desc';
+}
 interface CreateAddressDto {
     label?: string;
     firstName: string;
@@ -471,6 +479,9 @@ interface AddToCartDto {
 interface UpdateCartItemDto {
     quantity: number;
 }
+interface ApplyCouponDto {
+    code: string;
+}
 interface MergeCartsDto {
     sourceSessionToken: string;
     targetCustomerId: string;
@@ -564,6 +575,9 @@ interface SetShippingAddressDto {
 interface SetBillingAddressDto extends SetShippingAddressDto {
     sameAsShipping?: boolean;
 }
+interface SelectShippingMethodDto {
+    shippingRateId: string;
+}
 interface SetShippingAddressResponse {
     checkout: Checkout;
     rates: ShippingRate[];
@@ -580,6 +594,184 @@ interface WebhookEvent {
     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';
+type VariantStatus = 'active' | 'draft';
+interface CreateVariantDto {
+    sku?: string;
+    name?: string;
+    attributes?: Record<string, unknown>;
+    price?: number;
+    salePrice?: number;
+    inventory?: number;
+    image?: unknown;
+    position?: number;
+    status?: VariantStatus;
+}
+interface UpdateVariantDto {
+    sku?: string;
+    name?: string;
+    attributes?: Record<string, unknown>;
+    price?: number;
+    salePrice?: number;
+    image?: string | unknown;
+    position?: number;
+    status?: VariantStatus;
+}
+interface VariantPlatformOverlay {
+    price?: number;
+    salePrice?: number;
+    sku?: string;
+    stock?: number;
+    name?: string;
+}
+interface BulkVariantInput {
+    id?: string;
+    sku: string;
+    name?: string;
+    attributes: Record<string, string>;
+    price?: number | null;
+    salePrice?: number | null;
+    stock: number;
+    image?: unknown | null;
+    isEnabled: boolean;
+    isDeleted?: boolean;
+    overlays?: Record<string, VariantPlatformOverlay>;
+}
+interface ProductAttributeInput {
+    attributeId: string;
+    selectedOptionIds: string[];
+    isForVariations: boolean;
+}
+interface BulkSaveVariantsDto {
+    variants: BulkVariantInput[];
+    productAttributes?: ProductAttributeInput[];
+}
+interface BulkSaveVariantsResponse {
+    created: number;
+    updated: number;
+    deleted: number;
+    variants: ProductVariant[];
+}
+interface UpdateVariantInventoryDto {
+    newTotal: number;
+    reason?: string;
+}
+interface VariantInventoryResponse {
+    total: number;
+    reserved: number;
+    available: number;
+    lastInventorySyncAt?: string | null;
+}
+type RefundType = 'full' | 'partial';
+interface RefundLineItem {
+    lineItemId: string;
+    quantity: number;
+}
+interface CreateRefundDto {
+    type: RefundType;
+    items?: RefundLineItem[];
+    restockInventory?: boolean;
+    notifyCustomer?: boolean;
+    reason?: string;
+}
+interface RefundLineItemResponse {
+    name: string;
+    quantity: number;
+    amount: string;
+}
+interface Refund {
+    id: string;
+    createdAt: string;
+    amount: string;
+    currency: string;
+    reason?: string;
+    items?: RefundLineItemResponse[];
+    status: string;
+}
+interface UpdateOrderShippingDto {
+    firstName?: string;
+    lastName?: string;
+    name?: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    country: string;
+    postalCode: string;
+    phone?: string;
+}
+interface FulfillOrderDto {
+    trackingNumber?: string;
+    trackingCompany?: string;
+    notifyCustomer?: boolean;
+}
+interface CompleteDraftDto {
+    paymentPending?: boolean;
+}
+interface SendInvoiceDto {
+    to?: string;
+    subject?: string;
+    customMessage?: string;
+}
+interface AppliedDiscount {
+    valueType: 'fixed_amount' | 'percentage';
+    value: string;
+    description?: string;
+    title?: string;
+}
+interface DraftLineItem {
+    variantId?: number;
+    quantity?: number;
+    title?: string;
+    price?: string;
+    appliedDiscount?: AppliedDiscount;
+}
+interface ShippingLine {
+    title: string;
+    price: string;
+}
+interface UpdateDraftDto {
+    note?: string;
+    tags?: string;
+    email?: string;
+    shippingAddress?: Record<string, unknown>;
+    billingAddress?: Record<string, unknown>;
+    lineItems?: DraftLineItem[];
+    appliedDiscount?: AppliedDiscount;
+    shippingLine?: ShippingLine;
+}
+interface EditInventoryDto {
+    productId: string;
+    newTotal: number;
+    reason?: string;
+}
+interface InventorySyncStatus {
+    total: number;
+    pending: number;
+    synced: number;
+    neverSynced: number;
+    lastSyncAt: string | null;
+}
+interface BulkInventoryResponse {
+    productId: string;
+    total: number;
+    reserved: number;
+    available: number;
+}
+interface ReconcileInventoryResponse {
+    productId?: string;
+    results?: unknown;
+    total?: number;
+    reconciled?: number;
+    discrepancies?: number;
+}
+interface PublishProductResponse {
+    productId: string;
+    results: Record<string, {
+        success: boolean;
+        error?: string;
+    }>;
+}
 interface OmniSyncApiError {
     statusCode: number;
     message: string;
@@ -633,6 +825,111 @@ declare class OmniSyncClient {
      * Delete a product
      */
     deleteProduct(productId: string): Promise<void>;
+    /**
+     * Convert a SIMPLE product to VARIABLE product
+     *
+     * @example
+     * ```typescript
+     * const product = await omni.convertToVariable('prod_123');
+     * console.log('Product type:', product.type); // 'VARIABLE'
+     * ```
+     */
+    convertToVariable(productId: string): Promise<Product>;
+    /**
+     * Convert a VARIABLE product to SIMPLE product
+     * Note: This will delete all variants
+     *
+     * @example
+     * ```typescript
+     * const product = await omni.convertToSimple('prod_123');
+     * console.log('Product type:', product.type); // 'SIMPLE'
+     * ```
+     */
+    convertToSimple(productId: string): Promise<Product>;
+    /**
+     * Publish a product to specific platforms
+     *
+     * @example
+     * ```typescript
+     * const result = await omni.publishProduct('prod_123', ['SHOPIFY', 'WOOCOMMERCE']);
+     * console.log('Publish results:', result.results);
+     * ```
+     */
+    publishProduct(productId: string, platforms: string[]): Promise<PublishProductResponse>;
+    /**
+     * Create a new variant for a product
+     *
+     * @example
+     * ```typescript
+     * const variant = await omni.createVariant('prod_123', {
+     *   sku: 'PROD-SM-RED',
+     *   name: 'Small / Red',
+     *   attributes: { size: 'S', color: 'Red' },
+     *   price: 29.99,
+     *   inventory: 100,
+     * });
+     * ```
+     */
+    createVariant(productId: string, data: CreateVariantDto): Promise<ProductVariant>;
+    /**
+     * Bulk save variants (create, update, delete in one operation)
+     *
+     * @example
+     * ```typescript
+     * const result = await omni.bulkSaveVariants('prod_123', {
+     *   variants: [
+     *     { sku: 'SM-RED', attributes: { size: 'S', color: 'Red' }, stock: 10, isEnabled: true },
+     *     { id: 'var_456', sku: 'MD-BLUE', attributes: { size: 'M', color: 'Blue' }, stock: 5, isEnabled: true },
+     *     { id: 'var_789', sku: 'LG-GREEN', attributes: {}, stock: 0, isEnabled: false, isDeleted: true },
+     *   ],
+     * });
+     * console.log(`Created: ${result.created}, Updated: ${result.updated}, Deleted: ${result.deleted}`);
+     * ```
+     */
+    bulkSaveVariants(productId: string, data: BulkSaveVariantsDto): Promise<BulkSaveVariantsResponse>;
+    /**
+     * Update a variant
+     *
+     * @example
+     * ```typescript
+     * const variant = await omni.updateVariant('prod_123', 'var_456', {
+     *   price: 34.99,
+     *   salePrice: 29.99,
+     * });
+     * ```
+     */
+    updateVariant(productId: string, variantId: string, data: UpdateVariantDto): Promise<ProductVariant>;
+    /**
+     * Delete a variant
+     *
+     * @example
+     * ```typescript
+     * await omni.deleteVariant('prod_123', 'var_456');
+     * ```
+     */
+    deleteVariant(productId: string, variantId: string): Promise<void>;
+    /**
+     * Get inventory for a specific variant
+     *
+     * @example
+     * ```typescript
+     * const inventory = await omni.getVariantInventory('prod_123', 'var_456');
+     * console.log('Available:', inventory.available);
+     * ```
+     */
+    getVariantInventory(productId: string, variantId: string): Promise<VariantInventoryResponse>;
+    /**
+     * Update inventory for a specific variant
+     *
+     * @example
+     * ```typescript
+     * const inventory = await omni.updateVariantInventory('prod_123', 'var_456', {
+     *   newTotal: 50,
+     *   reason: 'Restocked from supplier',
+     * });
+     * ```
+     */
+    updateVariantInventory(productId: string, variantId: string, data: UpdateVariantInventoryDto): Promise<VariantInventoryResponse>;
     /**
      * Get a list of orders with pagination
      */
@@ -650,6 +947,181 @@ declare class OmniSyncClient {
      * Update an order (e.g., change status)
      */
     updateOrder(orderId: string, data: UpdateOrderDto): Promise<Order>;
+    /**
+     * Update order status
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.updateOrderStatus('order_123', 'shipped');
+     * ```
+     */
+    updateOrderStatus(orderId: string, status: string): Promise<Order>;
+    /**
+     * Update order payment method
+     * Note: Only WooCommerce supports syncing payment method changes back to platform
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.updatePaymentMethod('order_123', 'credit_card');
+     * ```
+     */
+    updatePaymentMethod(orderId: string, paymentMethod: string): Promise<Order>;
+    /**
+     * Update order notes
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.updateOrderNotes('order_123', 'Customer requested gift wrapping');
+     * ```
+     */
+    updateOrderNotes(orderId: string, notes: string): Promise<Order>;
+    /**
+     * Get refunds for an order
+     * Returns refunds from the source platform (Shopify/WooCommerce only)
+     *
+     * @example
+     * ```typescript
+     * const refunds = await omni.getOrderRefunds('order_123');
+     * console.log('Total refunds:', refunds.length);
+     * ```
+     */
+    getOrderRefunds(orderId: string): Promise<Refund[]>;
+    /**
+     * Create a refund for an order
+     * Creates refund on the source platform (Shopify/WooCommerce only)
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * const refund = await omni.createRefund('order_123', {
+     *   type: 'full',
+     *   restockInventory: true,
+     *   notifyCustomer: true,
+     *   reason: 'Customer request',
+     * });
+     *
+     * // Partial refund
+     * const partialRefund = await omni.createRefund('order_123', {
+     *   type: 'partial',
+     *   items: [
+     *     { lineItemId: 'item_456', quantity: 1 },
+     *   ],
+     *   restockInventory: true,
+     * });
+     * ```
+     */
+    createRefund(orderId: string, data: CreateRefundDto): Promise<Refund>;
+    /**
+     * Update order shipping address
+     * Syncs to source platform (Shopify/WooCommerce only)
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.updateOrderShipping('order_123', {
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   line1: '456 New Address',
+     *   city: 'Los Angeles',
+     *   state: 'CA',
+     *   country: 'US',
+     *   postalCode: '90001',
+     * });
+     * ```
+     */
+    updateOrderShipping(orderId: string, data: UpdateOrderShippingDto): Promise<Order>;
+    /**
+     * Cancel an order
+     * Works for Shopify and WooCommerce orders that haven't been fulfilled
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.cancelOrder('order_123');
+     * console.log('Order status:', order.status); // 'cancelled'
+     * ```
+     */
+    cancelOrder(orderId: string): Promise<Order>;
+    /**
+     * Fulfill an order (mark as shipped)
+     * Works for Shopify and WooCommerce orders
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.fulfillOrder('order_123', {
+     *   trackingNumber: '1Z999AA10123456784',
+     *   trackingCompany: 'UPS',
+     *   notifyCustomer: true,
+     * });
+     * ```
+     */
+    fulfillOrder(orderId: string, data?: FulfillOrderDto): Promise<Order>;
+    /**
+     * Sync draft orders from connected platforms
+     *
+     * @example
+     * ```typescript
+     * const result = await omni.syncDraftOrders();
+     * console.log('Draft orders synced');
+     * ```
+     */
+    syncDraftOrders(): Promise<{
+        message: string;
+    }>;
+    /**
+     * Complete a draft order (convert to regular order)
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.completeDraftOrder('draft_123', {
+     *   paymentPending: false,
+     * });
+     * ```
+     */
+    completeDraftOrder(orderId: string, data?: CompleteDraftDto): Promise<Order>;
+    /**
+     * Send invoice for a draft order
+     *
+     * @example
+     * ```typescript
+     * await omni.sendDraftInvoice('draft_123', {
+     *   to: 'customer@example.com',
+     *   subject: 'Your Invoice',
+     *   customMessage: 'Thank you for your order!',
+     * });
+     * ```
+     */
+    sendDraftInvoice(orderId: string, data?: SendInvoiceDto): Promise<{
+        message: string;
+    }>;
+    /**
+     * Delete a draft order
+     *
+     * @example
+     * ```typescript
+     * await omni.deleteDraftOrder('draft_123');
+     * ```
+     */
+    deleteDraftOrder(orderId: string): Promise<void>;
+    /**
+     * Update a draft order
+     *
+     * @example
+     * ```typescript
+     * const order = await omni.updateDraftOrder('draft_123', {
+     *   note: 'Updated customer note',
+     *   email: 'newemail@example.com',
+     *   shippingAddress: {
+     *     firstName: 'John',
+     *     lastName: 'Doe',
+     *     address1: '123 Main St',
+     *     city: 'New York',
+     *     province: 'NY',
+     *     country: 'US',
+     *     zip: '10001',
+     *   },
+     * });
+     * ```
+     */
+    updateDraftOrder(orderId: string, data: UpdateDraftDto): Promise<Order>;
     /**
      * Update inventory for a product
      * This will sync inventory to all connected platforms
@@ -663,6 +1135,64 @@ declare class OmniSyncClient {
         reserved: number;
         total: number;
     }>;
+    /**
+     * Edit inventory manually with reason for audit trail
+     *
+     * @example
+     * ```typescript
+     * const inventory = await omni.editInventory({
+     *   productId: 'prod_123',
+     *   newTotal: 100,
+     *   reason: 'Restocked from warehouse',
+     * });
+     * ```
+     */
+    editInventory(data: EditInventoryDto): Promise<{
+        total: number;
+        reserved: number;
+        available: number;
+    }>;
+    /**
+     * Get inventory sync status for all products in the store
+     *
+     * @example
+     * ```typescript
+     * const status = await omni.getInventorySyncStatus();
+     * console.log(`${status.pending} products pending sync`);
+     * console.log(`Last sync: ${status.lastSyncAt}`);
+     * ```
+     */
+    getInventorySyncStatus(): Promise<InventorySyncStatus>;
+    /**
+     * Get inventory for multiple products at once
+     *
+     * @example
+     * ```typescript
+     * const inventories = await omni.getBulkInventory(['prod_123', 'prod_456', 'prod_789']);
+     * inventories.forEach(inv => {
+     *   console.log(`${inv.productId}: ${inv.available} available`);
+     * });
+     * ```
+     */
+    getBulkInventory(productIds: string[]): Promise<BulkInventoryResponse[]>;
+    /**
+     * Reconcile inventory between OmniSync and connected platforms
+     * Detects and optionally fixes discrepancies
+     *
+     * @example
+     * ```typescript
+     * // Reconcile single product (dry run)
+     * const result = await omni.reconcileInventory({ productId: 'prod_123' });
+     *
+     * // Reconcile all products with auto-fix
+     * const summary = await omni.reconcileInventory({ autoFix: true });
+     * console.log(`Reconciled ${summary.reconciled} products`);
+     * ```
+     */
+    reconcileInventory(options?: {
+        productId?: string;
+        autoFix?: boolean;
+    }): Promise<ReconcileInventoryResponse>;
     /**
      * Trigger a sync to a specific platform or all platforms
      */
@@ -1134,4 +1664,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 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 };
+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 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 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 };