@doswiftly/cli 0.1.18 → 0.1.20

package/templates/storefront-nextjs-shadcn/lib/graphql/hooks.ts

@@ -1,134 +1,196 @@
 'use client';
 
 import { useQuery, useMutation, useQueryClient, type UseQueryOptions, type UseMutationOptions } from '@tanstack/react-query';
-import { getGraphQLClient } from './client';
-import { useCurrencyStore } from '@/stores/currency-store';
-import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { useExecute } from './client';
+import { useCurrencyStore, useAuthStore, useLanguageStore } from '@doswiftly/storefront-sdk/react';
+import { normalizeConnection, type NormalizedConnection } from '@doswiftly/storefront-sdk';
+import { queryKeys } from './query-keys';
+import type { TypedDocumentString } from '@/generated/graphql';
+import type { NormalizedProductsResult, NormalizedCollectionsResult, NormalizedCategoriesResult } from './types';
+
+// Static imports — Documents
+import {
+  ProductDocument,
+  ProductsDocument,
+  CollectionDocument,
+  CollectionsDocument,
+  CategoriesDocument,
+  CategoryDocument,
+  AvailableFiltersDocument,
+  CartDocument,
+  CartCreateDocument,
+  CartLinesAddDocument,
+  CartLinesUpdateDocument,
+  CartLinesRemoveDocument,
+  CartDiscountCodesUpdateDocument,
+  CheckoutDocument,
+  CheckoutCreateDocument,
+  CheckoutShippingAddressUpdateDocument,
+  CheckoutBillingAddressUpdateDocument,
+  CheckoutEmailUpdateDocument,
+  CheckoutShippingLineUpdateDocument,
+  CheckoutDiscountCodeApplyDocument,
+  CheckoutDiscountCodeRemoveDocument,
+  CheckoutCompleteDocument,
+  CheckoutGiftCardApplyDocument,
+  CheckoutGiftCardRemoveDocument,
+  CheckoutGiftCardRecipientUpdateDocument,
+  CustomerDocument,
+  CustomerProfileDocument,
+  CustomerOrderDocument,
+  CustomerUpdateDocument,
+  CustomerAddressCreateDocument,
+  CustomerAddressUpdateDocument,
+  CustomerAddressDeleteDocument,
+  CustomerDefaultAddressUpdateDocument,
+  CustomerLoginDocument,
+  CustomerLogoutDocument,
+  LoyaltyMemberDocument,
+  LoyaltyRewardsDocument,
+  LoyaltyTransactionsDocument,
+  LoyaltySettingsDocument,
+  ReferralStatsDocument,
+  RedeemLoyaltyRewardDocument,
+} from '@/generated/graphql';
+
+// Static imports — Types
+import type {
+  ProductQuery,
+  ProductQueryVariables,
+  ProductsQuery,
+  ProductsQueryVariables,
+  ProductSortKeys,
+  CollectionQuery,
+  CollectionQueryVariables,
+  CollectionsQuery,
+  CollectionsQueryVariables,
+  CollectionSortKeys,
+  CategoriesQuery,
+  CategoryQuery,
+  CategoryQueryVariables,
+  Category,
+  ProductFilterInput,
+  AvailableFiltersQuery,
+  AvailableFiltersQueryVariables,
+  AvailableFiltersInput,
+  CartQuery,
+  CartQueryVariables,
+  CartCreateMutation,
+  CartCreateMutationVariables,
+  CartLinesAddMutation,
+  CartLinesAddMutationVariables,
+  CartLinesUpdateMutation,
+  CartLinesUpdateMutationVariables,
+  CartLinesRemoveMutation,
+  CartLinesRemoveMutationVariables,
+  CartDiscountCodesUpdateMutation,
+  CartDiscountCodesUpdateMutationVariables,
+  CheckoutQuery,
+  CheckoutQueryVariables,
+  CheckoutCreateMutation,
+  CheckoutCreateMutationVariables,
+  CheckoutShippingAddressUpdateMutation,
+  CheckoutShippingAddressUpdateMutationVariables,
+  CheckoutBillingAddressUpdateMutation,
+  CheckoutBillingAddressUpdateMutationVariables,
+  CheckoutEmailUpdateMutation,
+  CheckoutEmailUpdateMutationVariables,
+  CheckoutShippingLineUpdateMutation,
+  CheckoutShippingLineUpdateMutationVariables,
+  CheckoutDiscountCodeApplyMutation,
+  CheckoutDiscountCodeApplyMutationVariables,
+  CheckoutDiscountCodeRemoveMutation,
+  CheckoutDiscountCodeRemoveMutationVariables,
+  CheckoutCompleteMutation,
+  CheckoutCompleteMutationVariables,
+  CheckoutGiftCardApplyMutation,
+  CheckoutGiftCardApplyMutationVariables,
+  CheckoutGiftCardRemoveMutation,
+  CheckoutGiftCardRemoveMutationVariables,
+  CheckoutGiftCardRecipientUpdateMutation,
+  CheckoutGiftCardRecipientUpdateMutationVariables,
+  CustomerQuery,
+  CustomerQueryVariables,
+  CustomerProfileQuery,
+  CustomerProfileQueryVariables,
+  CustomerOrderQuery,
+  CustomerOrderQueryVariables,
+  CustomerUpdateMutation,
+  CustomerUpdateMutationVariables,
+  CustomerUpdateInput,
+  CustomerAddressCreateMutation,
+  CustomerAddressCreateMutationVariables,
+  CustomerAddressUpdateMutation,
+  CustomerAddressUpdateMutationVariables,
+  CustomerAddressDeleteMutation,
+  CustomerAddressDeleteMutationVariables,
+  CustomerDefaultAddressUpdateMutation,
+  CustomerDefaultAddressUpdateMutationVariables,
+  CustomerLoginMutation,
+  CustomerLoginMutationVariables,
+  CustomerLogoutMutation,
+  CustomerLogoutMutationVariables,
+  LoyaltyMemberQuery,
+  LoyaltyRewardsQuery,
+  LoyaltyTransactionsQuery,
+  LoyaltyTransactionsQueryVariables,
+  LoyaltySettingsQuery,
+  ReferralStatsQuery,
+  RedeemLoyaltyRewardMutation,
+  RedeemLoyaltyRewardMutationVariables,
+} from '@/generated/graphql';
+
+// normalizeConnection and NormalizedConnection imported from SDK (see top of file)
 
 // ============================================================================
-// TYPES
+// GENERIC QUERY HOOK
 // ============================================================================
 
-/**
- * Normalized response for paginated queries
- * Converts GraphQL edges/nodes structure to flat arrays
- */
-export interface NormalizedConnection<T> {
-  items: T[];
-  pageInfo: {
-    hasNextPage: boolean;
-    hasPreviousPage: boolean;
-    startCursor?: string | null;
-    endCursor?: string | null;
-  };
-  totalCount?: number;
-}
-
-/**
- * GraphQL connection edge structure
- */
-interface Edge<T> {
-  node: T;
-  cursor: string;
-}
+/** Cache operation names to avoid regex on every render */
+const operationNameCache = new Map<TypedDocumentString<unknown, unknown>, string>();
 
-/**
- * GraphQL connection structure
- */
-interface Connection<T> {
-  edges: Edge<T>[];
-  pageInfo: {
-    hasNextPage: boolean;
-    hasPreviousPage: boolean;
-    startCursor?: string | null;
-    endCursor?: string | null;
-  };
-  totalCount?: number;
+function getOperationName(document: TypedDocumentString<unknown, unknown>): string {
+  let name = operationNameCache.get(document);
+  if (!name) {
+    name = document.toString().match(/^(?:query|mutation|subscription)\s+(\w+)/)?.[1] || 'GraphQLQuery';
+    operationNameCache.set(document, name);
+  }
+  return name;
 }
 
-// ============================================================================
-// UTILITY FUNCTIONS
-// ============================================================================
-
-/**
- * Normalize GraphQL connection to flat array
- * 
- * Converts edges/nodes structure to a simple array of items
- * for easier consumption in components.
- * 
- * @param connection - GraphQL connection object
- * @returns Normalized response with flat items array
- * 
- * @example
- * ```typescript
- * const data = { products: { edges: [...], pageInfo: {...} } };
- * const normalized = normalizeConnection(data.products);
- * // normalized.items is now a flat array
- * ```
- */
-export function normalizeConnection<T>(
-  connection: Connection<T>
-): NormalizedConnection<T> {
-  return {
-    items: connection.edges.map((edge) => edge.node),
-    pageInfo: connection.pageInfo,
-    totalCount: connection.totalCount,
-  };
-}
-
-// ============================================================================
-// GENERIC QUERY HOOK
-// ============================================================================
-
 /**
  * Generic query hook with currency-aware caching
- * 
+ *
  * Wraps React Query's useQuery with automatic currency injection
  * into query keys for proper cache invalidation when currency changes.
- * 
- * @param document - TypedDocumentNode from codegen
- * @param variables - Query variables
- * @param options - React Query options
- * @returns React Query result
- * 
+ *
  * @example
  * ```typescript
  * const { data } = useGraphQLQuery(ProductDocument, { handle: 'my-product' });
  * ```
  */
 export function useGraphQLQuery<TResult, TVariables>(
-  document: TypedDocumentNode<TResult, TVariables>,
+  document: TypedDocumentString<TResult, TVariables>,
   variables?: TVariables,
   options?: Omit<UseQueryOptions<TResult>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
-  // Generate query key from document name and variables
-  // Include currency to invalidate cache when currency changes
-  const queryKey = [
-    // Extract operation name from document
-    (document as any).definitions?.[0]?.name?.value || 'GraphQLQuery',
-    variables,
-    currency,
-  ];
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+  const operationName = getOperationName(document as TypedDocumentString<unknown, unknown>);
+  const queryKey = [operationName, variables, currency, language];
+
   return useQuery({
     queryKey,
-    queryFn: () => client.request(document, variables as any),
+    queryFn: () => execute<TResult>(document.toString(), variables as Record<string, unknown>),
+    enabled: !!language && (options?.enabled ?? true),
     ...options,
   });
 }
 
 /**
  * Generic mutation hook
- * 
- * Wraps React Query's useMutation for GraphQL mutations.
- * 
- * @param document - TypedDocumentNode from codegen
- * @param options - React Query mutation options
- * @returns React Query mutation result
- * 
+ *
  * @example
  * ```typescript
  * const mutation = useGraphQLMutation(CartCreateDocument);
@@ -136,13 +198,13 @@ export function useGraphQLQuery<TResult, TVariables>(
  * ```
  */
 export function useGraphQLMutation<TResult, TVariables>(
-  document: TypedDocumentNode<TResult, TVariables>,
+  document: TypedDocumentString<TResult, TVariables>,
   options?: UseMutationOptions<TResult, Error, TVariables>
 ) {
-  const client = getGraphQLClient();
-  
+  const execute = useExecute();
+
   return useMutation({
-    mutationFn: (variables: TVariables) => client.request(document, variables as any),
+    mutationFn: (variables: TVariables) => execute<TResult>(document.toString(), variables as Record<string, unknown>),
     ...options,
   });
 }
@@ -153,106 +215,64 @@ export function useGraphQLMutation<TResult, TVariables>(
 
 /**
  * Fetch single product by handle or ID
- * 
- * Automatically includes current currency in request headers
- * and query key for proper cache invalidation.
- * 
- * @param handleOrId - Product handle (string) or ID (gid://)
- * @param options - React Query options
- * @returns Product query result
- * 
+ *
  * @example
  * ```typescript
- * // In a Client Component
- * 'use client';
- * 
- * export function ProductPrice({ handle }) {
- *   const { data, isLoading } = useProduct(handle);
- *   
- *   if (isLoading) return <div>Loading...</div>;
- *   
- *   return (
- *     <div suppressHydrationWarning>
- *       {data.product.priceRange.minVariantPrice.amount}{' '}
- *       {data.product.priceRange.minVariantPrice.currencyCode}
- *     </div>
- *   );
- * }
+ * const { data, isLoading } = useProduct('my-product-handle');
+ * const product = data?.product;
  * ```
  */
 export function useProduct(
   handleOrId: string,
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<ProductQuery>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
-  // Determine if it's an ID or handle
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
   const isId = handleOrId.startsWith('gid://');
-  
+
   return useQuery({
-    queryKey: ['Product', handleOrId, currency],
-    queryFn: async () => {
-      // Dynamic import to avoid circular dependencies
-      const { ProductDocument } = await import('@/generated/graphql');
-      
-      const variables = isId ? { id: handleOrId } : { handle: handleOrId };
-      return client.request(ProductDocument, variables as any);
+    queryKey: queryKeys.products.detail(handleOrId, currency, language),
+    queryFn: () => {
+      const variables: ProductQueryVariables = isId
+        ? { id: handleOrId }
+        : { handle: handleOrId };
+      return execute<ProductQuery>(ProductDocument.toString(), variables);
     },
     ...options,
   });
 }
 
-/**
- * Fetch products with pagination and normalization
- * 
- * Automatically normalizes GraphQL edges/nodes structure to flat arrays.
- * Includes currency in query key for cache invalidation.
- * 
- * @param variables - Query variables (first, after, query, sortKey, reverse)
- * @param options - React Query options
- * @returns Normalized products response
- * 
- * @example
- * ```typescript
- * // In a Client Component
- * 'use client';
- * 
- * export function ProductList() {
- *   const { data, isLoading } = useProducts({ first: 20 });
- *   
- *   if (isLoading) return <div>Loading...</div>;
- *   
- *   return (
- *     <div>
- *       {data.products.map(product => (
- *         <ProductCard key={product.id} product={product} />
- *       ))}
- *     </div>
- *   );
- * }
- * ```
- */
 /**
  * Map frontend sort values to GraphQL enum values
  */
-function normalizeSortKey(sortKey?: string): { sortKey?: string; reverse?: boolean } {
+function normalizeSortKey(sortKey?: string): { sortKey: ProductSortKeys; reverse: boolean } {
   if (!sortKey) return { sortKey: 'BEST_SELLING', reverse: false };
-  
-  const sortMap: Record<string, { sortKey: string; reverse: boolean }> = {
+
+  const sortMap: Record<string, { sortKey: ProductSortKeys; reverse: boolean }> = {
     'relevance': { sortKey: 'RELEVANCE', reverse: false },
     'best-selling': { sortKey: 'BEST_SELLING', reverse: false },
     'price-low-to-high': { sortKey: 'PRICE', reverse: false },
     'price-high-to-low': { sortKey: 'PRICE', reverse: true },
     'title-asc': { sortKey: 'TITLE', reverse: false },
     'title-desc': { sortKey: 'TITLE', reverse: true },
-    'created-desc': { sortKey: 'CREATED', reverse: true },
-    'created-asc': { sortKey: 'CREATED', reverse: false },
+    'created-desc': { sortKey: 'CREATED_AT', reverse: true },
+    'created-asc': { sortKey: 'CREATED_AT', reverse: false },
   };
-  
+
   return sortMap[sortKey] || { sortKey: 'BEST_SELLING', reverse: false };
 }
 
+/**
+ * Fetch products with pagination and normalization
+ *
+ * @example
+ * ```typescript
+ * const { data, isLoading } = useProducts({ first: 20 });
+ * data?.products.map(product => ...)
+ * ```
+ */
 export function useProducts(
   variables?: {
     first?: number;
@@ -260,32 +280,32 @@ export function useProducts(
     query?: string;
     sortKey?: string;
     reverse?: boolean;
+    filters?: ProductFilterInput;
   },
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<NormalizedProductsResult>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
   return useQuery({
-    queryKey: ['Products', variables, currency],
+    queryKey: queryKeys.products.list(variables as Record<string, unknown>, currency, language),
     queryFn: async () => {
-      // Dynamic import to avoid circular dependencies
-      const { ProductsDocument } = await import('@/generated/graphql');
-      
-      // Normalize sort key to GraphQL enum format
       const { sortKey: normalizedSortKey, reverse: normalizedReverse } = normalizeSortKey(variables?.sortKey);
-      
-      const data = await client.request(ProductsDocument, {
+
+      const graphqlVariables: ProductsQueryVariables = {
         first: variables?.first ?? 20,
         after: variables?.after,
         query: variables?.query,
-        sortKey: normalizedSortKey as any,
+        sortKey: normalizedSortKey,
         reverse: variables?.reverse !== undefined ? variables.reverse : normalizedReverse,
-      });
-      
-      // Normalize: edges/nodes → flat array
+        filters: variables?.filters,
+      };
+
+      const data = await execute<ProductsQuery>(ProductsDocument.toString(), graphqlVariables);
+
       return {
-        products: data.products.edges.map((edge: any) => edge.node),
+        products: data.products.edges.map((edge) => edge.node),
         pageInfo: data.products.pageInfo,
         totalCount: data.products.totalCount,
       };
@@ -300,11 +320,7 @@ export function useProducts(
 
 /**
  * Fetch single collection by handle or ID
- * 
- * @param handleOrId - Collection handle or ID
- * @param options - React Query options
- * @returns Collection query result
- * 
+ *
  * @example
  * ```typescript
  * const { data } = useCollection('featured-products');
@@ -312,24 +328,21 @@ export function useProducts(
  */
 export function useCollection(
   handleOrId: string,
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<CollectionQuery>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
   const isId = handleOrId.startsWith('gid://');
-  
+
   return useQuery({
-    queryKey: ['Collection', handleOrId, currency],
-    queryFn: async () => {
-      const { CollectionDocument } = await import('@/generated/graphql');
-      
-      // Type-safe conditional variables
-      const variables = isId 
-        ? { id: handleOrId } as { id: string }
-        : { handle: handleOrId } as { handle: string };
-      
-      return client.request(CollectionDocument, variables as any);
+    queryKey: queryKeys.collections.detail(handleOrId, currency, language),
+    queryFn: () => {
+      const variables: CollectionQueryVariables = isId
+        ? { id: handleOrId }
+        : { handle: handleOrId };
+      return execute<CollectionQuery>(CollectionDocument.toString(), variables);
     },
     ...options,
   });
@@ -337,11 +350,7 @@ export function useCollection(
 
 /**
  * Fetch collections with pagination and normalization
- * 
- * @param variables - Query variables
- * @param options - React Query options
- * @returns Normalized collections response
- * 
+ *
  * @example
  * ```typescript
  * const { data } = useCollections({ first: 10 });
@@ -352,30 +361,30 @@ export function useCollections(
     first?: number;
     after?: string;
     query?: string;
-    sortKey?: string;
+    sortKey?: CollectionSortKeys;
     reverse?: boolean;
   },
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<NormalizedCollectionsResult>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
   return useQuery({
-    queryKey: ['Collections', variables, currency],
+    queryKey: queryKeys.collections.list(variables as Record<string, unknown>, currency, language),
     queryFn: async () => {
-      const { CollectionsDocument } = await import('@/generated/graphql');
-      
-      const data = await client.request(CollectionsDocument, {
+      const graphqlVariables: CollectionsQueryVariables = {
         first: variables?.first ?? 20,
         after: variables?.after,
         query: variables?.query,
-        sortKey: variables?.sortKey as any,
+        sortKey: variables?.sortKey,
         reverse: variables?.reverse,
-      });
-      
-      // Normalize: edges/nodes → flat array
+      };
+
+      const data = await execute<CollectionsQuery>(CollectionsDocument.toString(), graphqlVariables);
+
       return {
-        collections: data.collections.edges.map((edge: any) => edge.node),
+        collections: data.collections.edges.map((edge) => edge.node),
         pageInfo: data.collections.pageInfo,
         totalCount: data.collections.totalCount,
       };
@@ -388,17 +397,38 @@ export function useCollections(
 // CATEGORY HOOKS
 // ============================================================================
 
+/**
+ * Fetch single category by slug or ID
+ *
+ * @example
+ * ```typescript
+ * const { data } = useCategory('gift-cards');
+ * const category = data?.category;
+ * ```
+ */
+export function useCategory(
+  slugOrId: string,
+  options?: Omit<UseQueryOptions<CategoryQuery>, 'queryKey' | 'queryFn'>
+) {
+  const execute = useExecute();
+
+  const isId = slugOrId.startsWith('gid://');
+
+  return useQuery({
+    queryKey: queryKeys.categories.detail(slugOrId),
+    queryFn: () => {
+      const variables: CategoryQueryVariables = isId
+        ? { id: slugOrId }
+        : { slug: slugOrId };
+      return execute<CategoryQuery>(CategoryDocument.toString(), variables);
+    },
+    ...options,
+  });
+}
+
 /**
  * Fetch categories with hierarchical structure
- * 
- * Categories are hierarchical (tree structure) and used for catalog organization.
- * Use for filters, navigation, and SEO.
- * 
- * Returns flat array of all categories (roots + children) for easy filtering.
- * 
- * @param options - React Query options
- * @returns Categories response with flat array
- * 
+ *
  * @example
  * ```typescript
  * const { data } = useCategories();
@@ -406,28 +436,26 @@ export function useCollections(
  * ```
  */
 export function useCategories(
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<NormalizedCategoriesResult>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
   return useQuery({
-    queryKey: ['Categories', currency],
+    queryKey: queryKeys.categories.list(currency, language),
     queryFn: async () => {
-      const { CategoriesDocument } = await import('@/generated/graphql');
-      
-      const data = await client.request(CategoriesDocument);
-      
-      // Flatten hierarchical structure to array for filters
-      const flattenCategories = (cats: any[]): any[] => {
-        return cats.flatMap((cat: any) => [
+      const data = await execute<CategoriesQuery>(CategoriesDocument.toString());
+
+      const flattenCategories = (cats: Category[]): Category[] => {
+        return cats.flatMap((cat) => [
           cat,
-          ...(cat.children ? flattenCategories(cat.children) : [])
+          ...(cat.children ? flattenCategories(cat.children as Category[]) : [])
         ]);
       };
-      
-      const allCategories = flattenCategories(data.categories.roots || []);
-      
+
+      const allCategories = flattenCategories(data.categories.roots as Category[]);
+
       return {
         categories: allCategories,
         roots: data.categories.roots,
@@ -438,21 +466,48 @@ export function useCategories(
   });
 }
 
+// ============================================================================
+// AVAILABLE FILTERS HOOK
+// ============================================================================
+
+/**
+ * Fetch available filters for product listing (dynamic attributes, price range, categories).
+ * Context-aware: pass categoryId, collectionId, or searchQuery to scope filters.
+ *
+ * @example
+ * ```typescript
+ * const { data } = useAvailableFilters({ categoryId: 'some-id' });
+ * data?.availableFilters.attributes // dynamic attribute filters with counts
+ * data?.availableFilters.priceRange // { min, max } in context
+ * data?.availableFilters.categories // category filters with counts
+ * ```
+ */
+export function useAvailableFilters(
+  input?: AvailableFiltersInput,
+  options?: Omit<UseQueryOptions<AvailableFiltersQuery>, 'queryKey' | 'queryFn'>
+) {
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+  const language = useLanguageStore((s) => s.language);
+
+  return useQuery({
+    queryKey: queryKeys.filters.forContext(input as Record<string, unknown>, currency, language),
+    queryFn: () => {
+      const variables: AvailableFiltersQueryVariables = { input: input || null };
+      return execute<AvailableFiltersQuery>(AvailableFiltersDocument.toString(), variables);
+    },
+    staleTime: 60_000, // Filters change infrequently, cache for 1 min
+    ...options,
+  });
+}
+
 // ============================================================================
 // CART HOOKS
 // ============================================================================
 
 /**
  * Fetch cart by ID
- * 
- * Includes currency in query key to refetch when currency changes.
- * Cart prices are locked for 24 hours, but currency header is still
- * included for consistency.
- * 
- * @param cartId - Cart ID
- * @param options - React Query options
- * @returns Cart query result
- * 
+ *
  * @example
  * ```typescript
  * const { data } = useCart(cartId);
@@ -460,19 +515,17 @@ export function useCategories(
  */
 export function useCart(
   cartId: string | null,
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<CartQuery | null>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
-  
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
+
   return useQuery({
-    queryKey: ['Cart', cartId, currency],
-    queryFn: async () => {
+    queryKey: queryKeys.cart.detail(cartId, currency),
+    queryFn: () => {
       if (!cartId) return null;
-      
-      const { CartDocument } = await import('@/generated/graphql');
-      
-      return client.request(CartDocument, { id: cartId });
+      const variables: CartQueryVariables = { id: cartId };
+      return execute<CartQuery>(CartDocument.toString(), variables);
     },
     enabled: Boolean(cartId),
     ...options,
@@ -481,40 +534,22 @@ export function useCart(
 
 /**
  * Create a new cart
- * 
- * @param options - React Query mutation options
- * @returns Cart create mutation
- * 
- * @example
- * ```typescript
- * const createCart = useCartCreate();
- * 
- * const handleCreate = async () => {
- *   const { cartCreate } = await createCart.mutateAsync({
- *     input: { lines: [...] }
- *   });
- *   
- *   if (cartCreate.cart) {
- *     // Store cart ID
- *     localStorage.setItem('cartId', cartCreate.cart.id);
- *   }
- * };
- * ```
  */
 export function useCartCreate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CartCreateMutation, Error, CartCreateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
-  
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CartCreateDocument } = await import('@/generated/graphql');
-      return client.request(CartCreateDocument, variables);
+    mutationFn: (variables: CartCreateMutationVariables) =>
+      execute<CartCreateMutation>(CartCreateDocument.toString(), variables),
+    onMutate: async () => {
+      // Cancel in-flight cart queries to prevent stale data overwriting mutation result
+      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
     },
-    onSuccess: () => {
-      // Invalidate cart queries
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -522,36 +557,21 @@ export function useCartCreate(
 
 /**
  * Add lines to cart
- * 
- * @param options - React Query mutation options
- * @returns Cart lines add mutation
- * 
- * @example
- * ```typescript
- * const addLines = useCartLinesAdd();
- * 
- * const handleAddToCart = async () => {
- *   await addLines.mutateAsync({
- *     cartId: 'cart-123',
- *     lines: [{ merchandiseId: 'variant-456', quantity: 1 }]
- *   });
- * };
- * ```
  */
 export function useCartLinesAdd(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CartLinesAddMutation, Error, CartLinesAddMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
-  
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CartLinesAddDocument } = await import('@/generated/graphql');
-      return client.request(CartLinesAddDocument, variables);
+    mutationFn: (variables: CartLinesAddMutationVariables) =>
+      execute<CartLinesAddMutation>(CartLinesAddDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
     },
-    onSuccess: () => {
-      // Invalidate cart queries
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -559,36 +579,21 @@ export function useCartLinesAdd(
 
 /**
  * Update cart lines
- * 
- * @param options - React Query mutation options
- * @returns Cart lines update mutation
- * 
- * @example
- * ```typescript
- * const updateLines = useCartLinesUpdate();
- * 
- * const handleUpdateQuantity = async (lineId: string, quantity: number) => {
- *   await updateLines.mutateAsync({
- *     cartId: 'cart-123',
- *     lines: [{ id: lineId, quantity }]
- *   });
- * };
- * ```
  */
 export function useCartLinesUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CartLinesUpdateMutation, Error, CartLinesUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
-  
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CartLinesUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CartLinesUpdateDocument, variables);
+    mutationFn: (variables: CartLinesUpdateMutationVariables) =>
+      execute<CartLinesUpdateMutation>(CartLinesUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
     },
-    onSuccess: () => {
-      // Invalidate cart queries
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -596,36 +601,21 @@ export function useCartLinesUpdate(
 
 /**
  * Remove lines from cart
- * 
- * @param options - React Query mutation options
- * @returns Cart lines remove mutation
- * 
- * @example
- * ```typescript
- * const removeLines = useCartLinesRemove();
- * 
- * const handleRemove = async (lineId: string) => {
- *   await removeLines.mutateAsync({
- *     cartId: 'cart-123',
- *     lineIds: [lineId]
- *   });
- * };
- * ```
  */
 export function useCartLinesRemove(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CartLinesRemoveMutation, Error, CartLinesRemoveMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
-  
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CartLinesRemoveDocument } = await import('@/generated/graphql');
-      return client.request(CartLinesRemoveDocument, variables);
+    mutationFn: (variables: CartLinesRemoveMutationVariables) =>
+      execute<CartLinesRemoveMutation>(CartLinesRemoveDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
     },
-    onSuccess: () => {
-      // Invalidate cart queries
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -633,26 +623,21 @@ export function useCartLinesRemove(
 
 /**
  * Update discount codes on cart
- *
- * Invalidates cart query on success so all consumers (useCartSync)
- * automatically receive updated discount data.
- *
- * @param options - React Query mutation options
- * @returns Cart discount codes update mutation
  */
 export function useCartDiscountCodesUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CartDiscountCodesUpdateMutation, Error, CartDiscountCodesUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CartDiscountCodesUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CartDiscountCodesUpdateDocument, variables);
+    mutationFn: (variables: CartDiscountCodesUpdateMutationVariables) =>
+      execute<CartDiscountCodesUpdateMutation>(CartDiscountCodesUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.cart.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -664,25 +649,20 @@ export function useCartDiscountCodesUpdate(
 
 /**
  * Fetch checkout by ID
- *
- * @param checkoutId - Checkout ID
- * @param options - React Query options
- * @returns Checkout query result
  */
 export function useCheckout(
   checkoutId: string | null,
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<CheckoutQuery | null>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
+  const execute = useExecute();
+  const currency = useCurrencyStore((s) => s.currency);
 
   return useQuery({
-    queryKey: ['Checkout', checkoutId, currency],
-    queryFn: async () => {
+    queryKey: queryKeys.checkout.detail(checkoutId, currency),
+    queryFn: () => {
       if (!checkoutId) return null;
-
-      const { CheckoutDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutDocument, { id: checkoutId });
+      const variables: CheckoutQueryVariables = { id: checkoutId };
+      return execute<CheckoutQuery>(CheckoutDocument.toString(), variables);
     },
     enabled: Boolean(checkoutId),
     ...options,
@@ -691,23 +671,21 @@ export function useCheckout(
 
 /**
  * Create checkout from cart
- *
- * @param options - React Query mutation options
- * @returns Checkout create mutation
  */
 export function useCheckoutCreate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutCreateMutation, Error, CheckoutCreateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutCreateDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutCreateDocument, variables);
+    mutationFn: (variables: CheckoutCreateMutationVariables) =>
+      execute<CheckoutCreateMutation>(CheckoutCreateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -715,23 +693,21 @@ export function useCheckoutCreate(
 
 /**
  * Update checkout shipping address
- *
- * @param options - React Query mutation options
- * @returns Checkout shipping address update mutation
  */
 export function useCheckoutShippingAddressUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutShippingAddressUpdateMutation, Error, CheckoutShippingAddressUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutShippingAddressUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutShippingAddressUpdateDocument, variables);
+    mutationFn: (variables: CheckoutShippingAddressUpdateMutationVariables) =>
+      execute<CheckoutShippingAddressUpdateMutation>(CheckoutShippingAddressUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -739,23 +715,21 @@ export function useCheckoutShippingAddressUpdate(
 
 /**
  * Update checkout billing address
- *
- * @param options - React Query mutation options
- * @returns Checkout billing address update mutation
  */
 export function useCheckoutBillingAddressUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutBillingAddressUpdateMutation, Error, CheckoutBillingAddressUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutBillingAddressUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutBillingAddressUpdateDocument, variables);
+    mutationFn: (variables: CheckoutBillingAddressUpdateMutationVariables) =>
+      execute<CheckoutBillingAddressUpdateMutation>(CheckoutBillingAddressUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -763,23 +737,21 @@ export function useCheckoutBillingAddressUpdate(
 
 /**
  * Update checkout email
- *
- * @param options - React Query mutation options
- * @returns Checkout email update mutation
  */
 export function useCheckoutEmailUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutEmailUpdateMutation, Error, CheckoutEmailUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutEmailUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutEmailUpdateDocument, variables);
+    mutationFn: (variables: CheckoutEmailUpdateMutationVariables) =>
+      execute<CheckoutEmailUpdateMutation>(CheckoutEmailUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -787,23 +759,21 @@ export function useCheckoutEmailUpdate(
 
 /**
  * Update checkout shipping line (select shipping method)
- *
- * @param options - React Query mutation options
- * @returns Checkout shipping line update mutation
  */
 export function useCheckoutShippingLineUpdate(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutShippingLineUpdateMutation, Error, CheckoutShippingLineUpdateMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutShippingLineUpdateDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutShippingLineUpdateDocument, variables);
+    mutationFn: (variables: CheckoutShippingLineUpdateMutationVariables) =>
+      execute<CheckoutShippingLineUpdateMutation>(CheckoutShippingLineUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -811,23 +781,21 @@ export function useCheckoutShippingLineUpdate(
 
 /**
  * Apply discount code to checkout
- *
- * @param options - React Query mutation options
- * @returns Checkout discount code apply mutation
  */
 export function useCheckoutDiscountCodeApply(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutDiscountCodeApplyMutation, Error, CheckoutDiscountCodeApplyMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutDiscountCodeApplyDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutDiscountCodeApplyDocument, variables);
+    mutationFn: (variables: CheckoutDiscountCodeApplyMutationVariables) =>
+      execute<CheckoutDiscountCodeApplyMutation>(CheckoutDiscountCodeApplyDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -835,23 +803,21 @@ export function useCheckoutDiscountCodeApply(
 
 /**
  * Remove discount code from checkout
- *
- * @param options - React Query mutation options
- * @returns Checkout discount code remove mutation
  */
 export function useCheckoutDiscountCodeRemove(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutDiscountCodeRemoveMutation, Error, CheckoutDiscountCodeRemoveMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutDiscountCodeRemoveDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutDiscountCodeRemoveDocument, variables);
+    mutationFn: (variables: CheckoutDiscountCodeRemoveMutationVariables) =>
+      execute<CheckoutDiscountCodeRemoveMutation>(CheckoutDiscountCodeRemoveDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -859,24 +825,22 @@ export function useCheckoutDiscountCodeRemove(
 
 /**
  * Complete checkout (finalize order)
- *
- * @param options - React Query mutation options
- * @returns Checkout complete mutation
  */
 export function useCheckoutComplete(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutCompleteMutation, Error, CheckoutCompleteMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutCompleteDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutCompleteDocument, variables);
+    mutationFn: (variables: CheckoutCompleteMutationVariables) =>
+      execute<CheckoutCompleteMutation>(CheckoutCompleteDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
-      queryClient.invalidateQueries({ queryKey: ['Cart'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
+      queryClient.invalidateQueries({ queryKey: queryKeys.cart.all() });
     },
     ...options,
   });
@@ -884,23 +848,21 @@ export function useCheckoutComplete(
 
 /**
  * Apply gift card code to checkout
- *
- * @param options - React Query mutation options
- * @returns Checkout gift card apply mutation
  */
 export function useCheckoutGiftCardApply(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutGiftCardApplyMutation, Error, CheckoutGiftCardApplyMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutGiftCardApplyDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutGiftCardApplyDocument, variables);
+    mutationFn: (variables: CheckoutGiftCardApplyMutationVariables) =>
+      execute<CheckoutGiftCardApplyMutation>(CheckoutGiftCardApplyDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -908,23 +870,43 @@ export function useCheckoutGiftCardApply(
 
 /**
  * Remove gift card from checkout
- *
- * @param options - React Query mutation options
- * @returns Checkout gift card remove mutation
  */
 export function useCheckoutGiftCardRemove(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CheckoutGiftCardRemoveMutation, Error, CheckoutGiftCardRemoveMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CheckoutGiftCardRemoveDocument } = await import('@/generated/graphql');
-      return client.request(CheckoutGiftCardRemoveDocument, variables);
+    mutationFn: (variables: CheckoutGiftCardRemoveMutationVariables) =>
+      execute<CheckoutGiftCardRemoveMutation>(CheckoutGiftCardRemoveDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['Checkout'] });
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update gift card recipient data on checkout line item
+ */
+export function useCheckoutGiftCardRecipientUpdate(
+  options?: UseMutationOptions<CheckoutGiftCardRecipientUpdateMutation, Error, CheckoutGiftCardRecipientUpdateMutationVariables>
+) {
+  const execute = useExecute();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (variables: CheckoutGiftCardRecipientUpdateMutationVariables) =>
+      execute<CheckoutGiftCardRecipientUpdateMutation>(CheckoutGiftCardRecipientUpdateDocument.toString(), variables),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.checkout.all() });
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.checkout.all() });
     },
     ...options,
   });
@@ -934,78 +916,217 @@ export function useCheckoutGiftCardRemove(
 // CUSTOMER HOOKS
 // ============================================================================
 
+/**
+ * Fetch current customer data (profile, addresses, orders).
+ * Automatically reads accessToken from auth store.
+ * Query is disabled until accessToken is available (after Zustand persist rehydration).
+ */
+export function useCustomer(
+  options?: Omit<UseQueryOptions<CustomerQuery>, 'queryKey' | 'queryFn' | 'enabled'>
+) {
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+
+  return useQuery({
+    queryKey: queryKeys.customer.detail(accessToken || ''),
+    queryFn: () =>
+      execute<CustomerQuery>(CustomerDocument.toString(), {
+        customerAccessToken: accessToken!,
+      } as CustomerQueryVariables),
+    enabled: !!accessToken,
+    ...options,
+  });
+}
+
+/**
+ * Lightweight customer profile query (no orders, no addresses list).
+ * Use for settings/profile pages that only need basic customer info.
+ */
+export function useCustomerProfile(
+  options?: Omit<UseQueryOptions<CustomerProfileQuery>, 'queryKey' | 'queryFn' | 'enabled'>
+) {
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+
+  return useQuery({
+    queryKey: queryKeys.customer.detail(accessToken || ''),
+    queryFn: () =>
+      execute<CustomerProfileQuery>(CustomerProfileDocument.toString(), {
+        customerAccessToken: accessToken!,
+      } as CustomerProfileQueryVariables),
+    enabled: !!accessToken,
+    ...options,
+  });
+}
+
+/**
+ * Fetch single order by ID for authenticated customer.
+ * More efficient than useCustomer() — fetches only the requested order.
+ */
+export function useCustomerOrder(
+  orderId: string,
+  options?: Omit<UseQueryOptions<CustomerOrderQuery>, 'queryKey' | 'queryFn' | 'enabled'>
+) {
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+  const currency = useCurrencyStore((s) => s.currency);
+
+  return useQuery({
+    queryKey: queryKeys.customer.order(orderId, currency),
+    queryFn: () =>
+      execute<CustomerOrderQuery>(CustomerOrderDocument.toString(), {
+        orderId,
+        customerAccessToken: accessToken!,
+      } as CustomerOrderQueryVariables),
+    enabled: !!accessToken && !!orderId,
+    ...options,
+  });
+}
+
+/**
+ * Update customer profile (firstName, lastName, phone).
+ * Automatically invalidates all customer queries on settle.
+ */
+export function useCustomerUpdate(
+  options?: UseMutationOptions<CustomerUpdateMutation, Error, CustomerUpdateInput>
+) {
+  const execute = useExecute();
+  const { accessToken } = useAuthStore();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (customer: CustomerUpdateInput) =>
+      execute<CustomerUpdateMutation>(CustomerUpdateDocument.toString(), {
+        customer,
+        customerAccessToken: accessToken!,
+      } as CustomerUpdateMutationVariables),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.customer.all() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Create a new customer address.
+ */
+export function useCustomerAddressCreate(
+  options?: UseMutationOptions<CustomerAddressCreateMutation, Error, { address: Record<string, unknown> }>
+) {
+  const execute = useExecute();
+  const { accessToken } = useAuthStore();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ address }: { address: Record<string, unknown> }) =>
+      execute<CustomerAddressCreateMutation>(
+        CustomerAddressCreateDocument.toString(),
+        { address, customerAccessToken: accessToken! } as CustomerAddressCreateMutationVariables,
+      ),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.customer.all() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Update an existing customer address.
+ */
+export function useCustomerAddressUpdate(
+  options?: UseMutationOptions<CustomerAddressUpdateMutation, Error, { id: string; address: Record<string, unknown> }>
+) {
+  const execute = useExecute();
+  const { accessToken } = useAuthStore();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, address }: { id: string; address: Record<string, unknown> }) =>
+      execute<CustomerAddressUpdateMutation>(
+        CustomerAddressUpdateDocument.toString(),
+        { id, address, customerAccessToken: accessToken! } as CustomerAddressUpdateMutationVariables,
+      ),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.customer.all() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Delete a customer address.
+ */
+export function useCustomerAddressDelete(
+  options?: UseMutationOptions<CustomerAddressDeleteMutation, Error, string>
+) {
+  const execute = useExecute();
+  const { accessToken } = useAuthStore();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) =>
+      execute<CustomerAddressDeleteMutation>(
+        CustomerAddressDeleteDocument.toString(),
+        { id, customerAccessToken: accessToken! } as CustomerAddressDeleteMutationVariables,
+      ),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.customer.all() });
+    },
+    ...options,
+  });
+}
+
+/**
+ * Set default customer address.
+ */
+export function useCustomerDefaultAddressUpdate(
+  options?: UseMutationOptions<CustomerDefaultAddressUpdateMutation, Error, string>
+) {
+  const execute = useExecute();
+  const { accessToken } = useAuthStore();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (addressId: string) =>
+      execute<CustomerDefaultAddressUpdateMutation>(
+        CustomerDefaultAddressUpdateDocument.toString(),
+        { addressId, customerAccessToken: accessToken! } as CustomerDefaultAddressUpdateMutationVariables,
+      ),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.customer.all() });
+    },
+    ...options,
+  });
+}
+
 /**
  * Customer login mutation
- * 
- * @param options - React Query mutation options
- * @returns Customer login mutation
- * 
- * @example
- * ```typescript
- * const login = useCustomerLogin();
- * 
- * const handleLogin = async (email: string, password: string) => {
- *   const { customerAccessTokenCreate } = await login.mutateAsync({
- *     input: { email, password }
- *   });
- *   
- *   if (customerAccessTokenCreate.customerAccessToken) {
- *     // Store token in httpOnly cookie via API route
- *     await fetch('/api/auth/set-token', {
- *       method: 'POST',
- *       body: JSON.stringify({
- *         token: customerAccessTokenCreate.customerAccessToken.accessToken
- *       })
- *     });
- *   }
- * };
- * ```
  */
 export function useCustomerLogin(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CustomerLoginMutation, Error, CustomerLoginMutationVariables>
 ) {
-  const client = getGraphQLClient();
-  
+  const execute = useExecute();
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CustomerLoginDocument } = await import('@/generated/graphql');
-      return client.request(CustomerLoginDocument, variables);
-    },
+    mutationFn: (variables: CustomerLoginMutationVariables) =>
+      execute<CustomerLoginMutation>(CustomerLoginDocument.toString(), variables),
     ...options,
   });
 }
 
 /**
  * Customer logout mutation
- * 
- * @param options - React Query mutation options
- * @returns Customer logout mutation
- * 
- * @example
- * ```typescript
- * const logout = useCustomerLogout();
- * 
- * const handleLogout = async () => {
- *   await logout.mutateAsync({ customerAccessToken: token });
- *   
- *   // Clear cookie via API route
- *   await fetch('/api/auth/clear-token', { method: 'POST' });
- * };
- * ```
  */
 export function useCustomerLogout(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<CustomerLogoutMutation, Error, CustomerLogoutMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
-  
+
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { CustomerLogoutDocument } = await import('@/generated/graphql');
-      return client.request(CustomerLogoutDocument, variables);
-    },
+    mutationFn: (variables: CustomerLogoutMutationVariables) =>
+      execute<CustomerLogoutMutation>(CustomerLogoutDocument.toString(), variables),
     onSuccess: () => {
-      // Clear all queries on logout
       queryClient.clear();
     },
     ...options,
@@ -1018,139 +1139,114 @@ export function useCustomerLogout(
 
 /**
  * Fetch loyalty member data
- *
- * @param options - React Query options
- * @returns Loyalty member query result
  */
 export function useLoyaltyMember(
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<LoyaltyMemberQuery>, 'queryKey' | 'queryFn' | 'enabled'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+  const currency = useCurrencyStore((s) => s.currency);
 
   return useQuery({
-    queryKey: ['LoyaltyMember', currency],
-    queryFn: async () => {
-      const { LoyaltyMemberDocument } = await import('@/generated/graphql');
-      return client.request(LoyaltyMemberDocument);
-    },
+    queryKey: queryKeys.loyalty.member(currency),
+    queryFn: () => execute<LoyaltyMemberQuery>(LoyaltyMemberDocument.toString()),
+    enabled: !!accessToken,
     ...options,
   });
 }
 
 /**
  * Fetch loyalty rewards
- *
- * @param options - React Query options
- * @returns Loyalty rewards query result
  */
 export function useLoyaltyRewards(
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<LoyaltyRewardsQuery>, 'queryKey' | 'queryFn' | 'enabled'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+  const currency = useCurrencyStore((s) => s.currency);
 
   return useQuery({
-    queryKey: ['LoyaltyRewards', currency],
-    queryFn: async () => {
-      const { LoyaltyRewardsDocument } = await import('@/generated/graphql');
-      return client.request(LoyaltyRewardsDocument);
-    },
+    queryKey: queryKeys.loyalty.rewards(currency),
+    queryFn: () => execute<LoyaltyRewardsQuery>(LoyaltyRewardsDocument.toString()),
+    enabled: !!accessToken,
     ...options,
   });
 }
 
 /**
  * Fetch loyalty transactions with pagination
- *
- * @param variables - Query variables (first, after)
- * @param options - React Query options
- * @returns Loyalty transactions query result
  */
 export function useLoyaltyTransactions(
   variables?: { first?: number; after?: string },
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<LoyaltyTransactionsQuery>, 'queryKey' | 'queryFn' | 'enabled'>
 ) {
-  const client = getGraphQLClient();
-  const currency = useCurrencyStore((s: any) => s.currency);
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
+  const currency = useCurrencyStore((s) => s.currency);
 
   return useQuery({
-    queryKey: ['LoyaltyTransactions', variables, currency],
-    queryFn: async () => {
-      const { LoyaltyTransactionsDocument } = await import('@/generated/graphql');
-      return client.request(LoyaltyTransactionsDocument, {
+    queryKey: queryKeys.loyalty.transactions(variables as Record<string, unknown>, currency),
+    queryFn: () => {
+      const graphqlVariables: LoyaltyTransactionsQueryVariables = {
         first: variables?.first ?? 20,
         after: variables?.after,
-      });
+      };
+      return execute<LoyaltyTransactionsQuery>(LoyaltyTransactionsDocument.toString(), graphqlVariables);
     },
+    enabled: !!accessToken,
     ...options,
   });
 }
 
 /**
  * Fetch loyalty settings
- *
- * @param options - React Query options
- * @returns Loyalty settings query result
  */
 export function useLoyaltySettings(
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<LoyaltySettingsQuery>, 'queryKey' | 'queryFn'>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
 
   return useQuery({
-    queryKey: ['LoyaltySettings'],
-    queryFn: async () => {
-      const { LoyaltySettingsDocument } = await import('@/generated/graphql');
-      return client.request(LoyaltySettingsDocument);
-    },
+    queryKey: queryKeys.loyalty.settings(),
+    queryFn: () => execute<LoyaltySettingsQuery>(LoyaltySettingsDocument.toString()),
     ...options,
   });
 }
 
 /**
  * Fetch referral stats
- *
- * @param options - React Query options
- * @returns Referral stats query result
  */
 export function useReferralStats(
-  options?: Omit<UseQueryOptions<any>, 'queryKey' | 'queryFn'>
+  options?: Omit<UseQueryOptions<ReferralStatsQuery>, 'queryKey' | 'queryFn' | 'enabled'>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
+  const accessToken = useAuthStore((s) => s.accessToken);
 
   return useQuery({
-    queryKey: ['ReferralStats'],
-    queryFn: async () => {
-      const { ReferralStatsDocument } = await import('@/generated/graphql');
-      return client.request(ReferralStatsDocument);
-    },
+    queryKey: queryKeys.loyalty.referralStats(),
+    queryFn: () => execute<ReferralStatsQuery>(ReferralStatsDocument.toString()),
+    enabled: !!accessToken,
     ...options,
   });
 }
 
 /**
  * Redeem loyalty reward mutation
- *
- * @param options - React Query mutation options
- * @returns Redeem reward mutation
  */
 export function useRedeemLoyaltyReward(
-  options?: UseMutationOptions<any, Error, any>
+  options?: UseMutationOptions<RedeemLoyaltyRewardMutation, Error, RedeemLoyaltyRewardMutationVariables>
 ) {
-  const client = getGraphQLClient();
+  const execute = useExecute();
   const queryClient = useQueryClient();
+  const currency = useCurrencyStore((s) => s.currency);
 
   return useMutation({
-    mutationFn: async (variables: any) => {
-      const { RedeemLoyaltyRewardDocument } = await import('@/generated/graphql');
-      return client.request(RedeemLoyaltyRewardDocument, variables);
-    },
+    mutationFn: (variables: RedeemLoyaltyRewardMutationVariables) =>
+      execute<RedeemLoyaltyRewardMutation>(RedeemLoyaltyRewardDocument.toString(), variables),
     onSuccess: () => {
-      // Invalidate loyalty queries to refresh points and rewards
-      queryClient.invalidateQueries({ queryKey: ['LoyaltyMember'] });
-      queryClient.invalidateQueries({ queryKey: ['LoyaltyRewards'] });
-      queryClient.invalidateQueries({ queryKey: ['LoyaltyTransactions'] });
+      queryClient.invalidateQueries({ queryKey: queryKeys.loyalty.member(currency) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.loyalty.rewards(currency) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.loyalty.transactions() });
     },
     ...options,
   });
@@ -1162,21 +1258,13 @@ export function useRedeemLoyaltyReward(
 
 /**
  * Hook to invalidate all queries when currency changes
- * 
+ *
  * This is automatically handled by including currency in query keys,
  * but this utility can be used for manual invalidation if needed.
- * 
- * @example
- * ```typescript
- * const invalidateOnCurrencyChange = useInvalidateOnCurrencyChange();
- * 
- * // Manually trigger invalidation
- * invalidateOnCurrencyChange();
- * ```
  */
 export function useInvalidateOnCurrencyChange() {
   const queryClient = useQueryClient();
-  
+
   return () => {
     queryClient.invalidateQueries();
   };