User Request
    │
    ├─ "Place order" / "Checkout"
    │   └─ sdk.order.createOrder() → handle payment_info
    │       → See cart-checkout/ for full checkout flow
    │
    ├─ "My orders" / "Order history"
    │   └─ sdk.order.listOrders({ page, limit })
    │
    ├─ "Order detail" / "Order #123"
    │   └─ sdk.order.getOrderDetails({ order_number })
    │
    ├─ "Track shipment"
    │   └─ sdk.order.listOrderShipments({ order_number })
    │       → tracking_url, awb_no, status, eta_delivery
    │
    ├─ "Payment failed" / "Retry"
    │   ├─ Check → sdk.order.getPaymentStatus(orderNumber)
    │   └─ Retry → sdk.order.retryOrderPayment({ order_number }, { payment_method })
    │
    └─ "Cancel order"
        ├─ Check is_cancellation_allowed first
        └─ sdk.order.cancelOrder({ order_number }, { ... })

const { data: order, error } = await sdk.order.createOrder({
  cart_id: cartId,
  payment_method: {
    payment_provider_slug: "juspay",
    integration_type: "hyper-checkout",
    gateway_reference_id: gatewayRefId,
    return_url: "https://yoursite.com/order/confirm",
    action: "paymentPage",
  },
});

if (order.payment_required) {
  // Use payment_info to redirect or handle payment flow
}

const { data, error } = await sdk.order.listOrders({
  page: 1,
  limit: 10,
  sort_by: JSON.stringify({ order_date: "desc" }),
});

// data.orders → OrderList[] (summary view)
// data.pagination → { total_records, total_pages, next_page }

async function pollPaymentStatus(orderNumber: string) {
  // Note: getPaymentStatus takes a string, not an object
  const { data, error } = await sdk.order.getPaymentStatus(orderNumber);

  if (data.status === "pending") {
    setTimeout(() => pollPaymentStatus(orderNumber), 3000);
    return;
  }

  if (data.status === "success") {
    showConfirmation(orderNumber);
  } else if (data.is_retry_available) {
    showRetryOption(orderNumber);
  } else {
    showPaymentFailed();
  }
}

// First check if cancellation is allowed
const { data: order } = await sdk.order.getOrderDetails({
  order_number: orderNumber,
});

if (order.is_cancellation_allowed) {
  const { data, error } = await sdk.order.cancelOrder(
    { order_number: orderNumber },
    {
      cancellation_reason: "Changed my mind",
      refund_mode: "original_payment_mode",
      feedback: "Optional feedback",
    }
  );
}

const { data, error } = await sdk.order.listOrderShipments({
  order_number: orderNumber,
});

data.shipments.forEach((shipment) => {
  console.log(shipment.status);        // "shipped", "delivered", etc.
  console.log(shipment.tracking_url);  // Courier tracking link
  console.log(shipment.awb_no);        // Air waybill number
  console.log(shipment.eta_delivery);  // Estimated delivery date
});