Hooks

function useShop(): {
  id: string;
  name: string;
  subdomain: string;
  domain: string;
  currency: string;
  default_language: "en" | "ar";
  logo_url: string | null;
  formatUrl: (path: string) => string;   // /products/x → https://<sub>.numueg.app/products/x
};

function Header() {
  const shop = useShop();
  return (
    <header className="flex justify-between p-4">
      {shop.logo_url ? (
        <img src={shop.logo_url} alt={shop.name} className="h-10" />
      ) : (
        <span className="font-bold text-xl">{shop.name}</span>
      )}
      <a href={shop.formatUrl("/cart")}>Cart</a>
    </header>
  );
}

// Subdomain-aware canonical URL for SEO
function CanonicalLink({ path }: { path: string }) {
  const shop = useShop();
  return <link rel="canonical" href={shop.formatUrl(path)} />;
}

function useThemeSettings(): ThemeSettingsV3;

function useLocalization(): { locale: "en" | "ar"; supportedLocales: string[] };
function useDirection(): "ltr" | "rtl";
function useTranslation(): (key: string, params?: Record<string, string>) => string;

const t = useTranslation();
return <button>{t("product.addToCart")}</button>;

function useCurrency(): {
  currency: string;
  rate: number;             // multiplier vs store currency
  symbol: string;
  format: (cents: number) => string;
};

function usePage(): {
  type: string;             // "home" | "product" | "cart" | ...
  title?: string;
  handle?: string;
  data?: Record<string, unknown>;
};

function useProduct(): Product;                  // throws if not in <ProductProvider>
function useProductOptional(): Product | null;

function useProducts(opts?: {
  limit?: number;
  page?: number;
  category_id?: string;
  search?: string;
}): {
  items: Product[];
  total: number;
  loading: boolean;
  error: Error | null;
};

function useVariantSelection(
  product: Pick<Product, "options" | "variants">,
  opts?: { autoSelect?: boolean }
): {
  selection: Record<string, string>;
  variant: ProductVariant | null;
  select: (axis: string, value: string) => void;
  reset: () => void;
  availability: Record<string, Set<string>>;
  isComplete: boolean;
};

const { selection, variant, select, availability, isComplete } = useVariantSelection(product);

return (
  <>
    {product.options.map(axis => (
      <div key={axis.name}>
        <label>{axis.name}: {selection[axis.name]}</label>
        {(axis.values || []).map(v => (
          <button
            key={v}
            disabled={!availability[axis.name].has(v)}
            onClick={() => select(axis.name, v)}
          >{v}</button>
        ))}
      </div>
    ))}
    <button disabled={!isComplete || !variant?.is_in_stock}>
      {variant ? `Add — ${variant.price}` : "Choose options"}
    </button>
  </>
);

function useRelatedProducts(
  productId: string | null | undefined,
  opts?: { limit?: number }
): { items: Product[]; loading: boolean; error: Error | null };

function useCart(): {
  cart: Cart;
  loading: boolean;
  addItem: (productId: string, variantId?: string | null, quantity?: number) => Promise<void>;
  removeItem: (itemId: string) => Promise<void>;
  updateQuantity: (itemId: string, quantity: number) => Promise<void>;
  applyDiscount: (code: string) => Promise<void>;
  removeDiscount: () => Promise<void>;
  updateNote: (note: string) => Promise<void>;
  clearCart: () => Promise<void>;
};

function useCustomer(): Customer | null;

function useCustomerActions(): {
  login: (email: string, password: string) => Promise<...>;
  register: (data: RegisterData) => Promise<...>;
  logout: () => Promise<void>;
  requestRecover: (email: string) => Promise<...>;
  confirmReset: (token: string, password: string) => Promise<...>;
  updateProfile: (patch: Partial<Customer>) => Promise<...>;
  changePassword: (currentPassword: string, newPassword: string) => Promise<...>;
};

function useCustomerAddresses(): {
  addresses: Address[];
  loading: boolean;
  addAddress: (a: Omit<Address, "id">) => Promise<Address>;
  updateAddress: (id: string, patch: Partial<Address>) => Promise<Address>;
  deleteAddress: (id: string) => Promise<void>;
  setDefaultAddress: (id: string) => Promise<void>;
};

function useOrders(opts?: { page?: number; limit?: number }): { items: Order[]; total: number; loading: boolean; };
function useOrder(id: string): { order: Order | null; loading: boolean; };
function useReorder(): {
  result: ReorderResult | null;
  loading: boolean;
  error: Error | null;
  reorder: (orderId: string) => Promise<ReorderResult | null>;
  reset: () => void;
};

const checkout = useCheckout();

await checkout.contact.set({ email, phone, shipping_address });
const rates = await checkout.shipping.refresh();
await checkout.shipping.select(rates[0].id);
await checkout.payment.select("paymob_card", { saved_payment_method_id: null });
const { order_id, payment_url } = await checkout.placeOrder();
if (payment_url) window.location.assign(payment_url);

function useShippingRates(opts: {
  address?: Partial<Address>;
  location_id?: string;
}): {
  rates: ShippingRateOption[];
  loading: boolean;
  error: Error | null;
  refresh: () => Promise<void>;
};

function useGiftCardBalance(): {
  balance: GiftCardBalance | null;
  loading: boolean;
  error: Error | null;
  check: (code: string) => Promise<GiftCardBalance | null>;
  reset: () => void;
};

function useSearch(
  query: string,
  opts?: { types?: ("product" | "collection" | "page" | "article")[]; predictive?: boolean }
): {
  results: SearchResults;
  loading: boolean;
};

function useNavigation(handle: string): { items: NavItem[]; loading: boolean };

function useAnalytics(): {
  track: (event: string, payload?: Record<string, unknown>) => void;
};

function useApp(slug: string): {
  available: boolean;
  data: Record<string, unknown> | null;
  setData: (key: string, value: unknown) => Promise<void>;
  getData: (key: string) => Promise<unknown>;
};

function useWishlist(): {
  items: WishlistItem[];
  has: (productId: string, variantId?: string | null) => boolean;
  addToWishlist: (productId: string, variantId?: string | null) => void;
  removeFromWishlist: (productId: string, variantId?: string | null) => void;
};

function useSection(): {
  id: string;
  type: string;
  settings: Record<string, unknown>;
  blocks: Record<string, BlockInstance>;
  block_order: string[];
};

function useImage(): {
  src: (url: string, opts?: { w?: number; h?: number; q?: number }) => string;
  srcset: (url: string, widths: number[]) => string;
};

function useMoney(): {
  format: (cents: number, currency?: string) => string;
  formatCurrency: (currency: string) => string;
};