refactor: refactor mutation hooks

Author: bartstc

.agents/skills/building-blocks/rules/mutation-hook.md

@@ -12,7 +12,7 @@ Server write hook composed from `mutation-options-factory`. Spreads the factory
 ### Constraints
 
 - ALWAYS use `use` prefix — `useXxxMutation`, never `xxxMutation`. File: `use-xxx-mutation.ts`
-- Compose from a `mutation-options-factory` via spread — do not inline `mutationFn` or error translation here
+- Compose from a `mutation-options-factory` via spread
 - Invalidation belongs here — the hook knows what queries to invalidate via `query-keys-factory`
 - When the consumer needs to extend `onSuccess` (e.g., close a modal after mutation), spread and chain the factory's callbacks
 

.agents/skills/building-blocks/rules/mutation-options-factory.md

@@ -13,7 +13,7 @@ Reusable `mutationOptions()` factory for a single API write operation. Contains
 
 - NEVER use `use` prefix — these are factories, not hooks. Name: `xxxMutationOptions`. File: `xxx-mutation.ts`
 - One factory per API endpoint. Co-locate with related query options in the same resource directory
-- Co-locate error classes with the factory. Map API errors exhaustively in `mutationFn` — translate, log, fall back to `UnknownError`
+- Co-locate mutation types (payload & dto) and error classes with the factory. Map API errors exhaustively in `mutationFn` — translate, log, fall back to `UnknownError`
 
 ### Example
 

src/features/carts/providers/use-add-to-cart-mutation.ts

@@ -1,5 +1,28 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { cartQueryKeys } from "@/lib/api/carts/cart-query-keys";
+import {
+  addToCartMutationOptions,
+  type AddToCartPayload,
+} from "@/lib/api/carts/{cart-id}/add-to-cart-mutation";
+
 export {
-  useAddToCartMutation,
   UnknownProductError,
   ProductNotAvailableError,
 } from "@/lib/api/carts/{cart-id}/add-to-cart-mutation";
+
+export const useAddToCartMutation = () => {
+  const queryClient = useQueryClient();
+
+  const { mutateAsync, isPending } = useMutation({
+    ...addToCartMutationOptions,
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: cartQueryKeys.all });
+    },
+  });
+
+  const handler = (cartId: string, payload: AddToCartPayload) =>
+    mutateAsync({ cartId, payload });
+
+  return [handler, isPending] as const;
+};

src/features/carts/providers/use-clear-cart-mutation.ts

@@ -1 +1,17 @@
-export { useClearCartMutation } from "@/lib/api/carts/{cart-id}/clear-cart-mutation";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { cartQueryKeys } from "@/lib/api/carts/cart-query-keys";
+import { clearCartMutationOptions } from "@/lib/api/carts/{cart-id}/clear-cart-mutation";
+
+export const useClearCartMutation = () => {
+  const queryClient = useQueryClient();
+
+  const { mutateAsync, isPending } = useMutation({
+    ...clearCartMutationOptions,
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: cartQueryKeys.all });
+    },
+  });
+
+  return [mutateAsync, isPending] as const;
+};

src/features/carts/providers/use-purchase-mutation.ts

@@ -1 +1,11 @@
-export { usePurchaseMutation } from "@/lib/api/carts/{cart-id}/purchase-mutation";
+import { useMutation } from "@tanstack/react-query";
+
+import { purchaseMutationOptions } from "@/lib/api/carts/{cart-id}/purchase-mutation";
+
+export const usePurchaseMutation = () => {
+  const { mutateAsync, isPending } = useMutation({
+    ...purchaseMutationOptions,
+  });
+
+  return [mutateAsync, isPending] as const;
+};

src/features/marketing/providers/use-rate-product-mutation.ts

@@ -1 +1,59 @@
-export { useRateProductMutation } from "@/lib/api/marketing/{product-id}/use-rate-product-mutation";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+
+import { marketingQueryKeys } from "@/lib/api/marketing/marketing-query-keys";
+import type { MarketingProductDto } from "@/lib/api/marketing/{product-id}/marketing-product-dto";
+import {
+  rateProductMutationOptions,
+  type RateProductDto,
+} from "@/lib/api/marketing/{product-id}/rate-product-mutation";
+
+interface MutationContext {
+  previous: MarketingProductDto | undefined;
+  productId: string;
+}
+
+export const useRateProductMutation = () => {
+  const queryClient = useQueryClient();
+
+  const { mutateAsync, isPending } = useMutation<
+    MarketingProductDto,
+    Error,
+    RateProductDto,
+    MutationContext
+  >({
+    ...rateProductMutationOptions,
+    onMutate: async ({ productId, rating }) => {
+      const queryKey = marketingQueryKeys.product(productId);
+      await queryClient.cancelQueries({ queryKey });
+
+      const previous = queryClient.getQueryData<MarketingProductDto>(queryKey);
+
+      if (previous) {
+        const { rate: oldRate, count: oldCount } = previous.rating;
+        const newCount = oldCount + 1;
+        const newRate =
+          Math.round(((oldRate * oldCount + rating) / newCount) * 100) / 100;
+
+        queryClient.setQueryData<MarketingProductDto>(queryKey, {
+          ...previous,
+          rating: { rate: newRate, count: newCount },
+        });
+      }
+
+      return { previous, productId };
+    },
+    onError: (_err, _vars, context) => {
+      if (context?.previous) {
+        queryClient.setQueryData(
+          marketingQueryKeys.product(context.productId),
+          context.previous
+        );
+      }
+    },
+  });
+
+  const handler = (productId: string, rating: number) =>
+    mutateAsync({ productId, rating });
+
+  return [handler, isPending] as const;
+};

src/lib/api/carts/{cart-id}/add-to-cart-mutation.ts

@@ -1,51 +1,41 @@
-import { useMutation } from "@tanstack/react-query";
+import { mutationOptions } from "@tanstack/react-query";
 
 import { httpService } from "@/lib/http";
 import { Logger } from "@/lib/logger";
 import { UnknownError } from "@/lib/types/unknown-error";
 
-interface AddToCartPayload {
+export interface AddToCartPayload {
   productId: string;
   quantity?: number;
 }
 
-interface AddToCartDto {
+export interface AddToCartDto {
   cartId: string;
   payload: AddToCartPayload;
 }
 
-export const useAddToCartMutation = () => {
-  const { mutateAsync, isPending } = useMutation<void, unknown, AddToCartDto>({
-    mutationFn: (body) =>
-      httpService.put<void, AddToCartPayload>(`carts/${body.cartId}`, {
-        productId: body.payload.productId,
-        quantity: body.payload.quantity,
-      }),
-  });
-
-  const handler = async (cartId: string, payload: AddToCartPayload) => {
+export const addToCartMutationOptions = mutationOptions({
+  mutationFn: async (body: AddToCartDto): Promise<void> => {
     try {
-      return await mutateAsync({ cartId, payload });
+      await httpService.put<void, AddToCartPayload>(
+        `carts/${body.cartId}`,
+        body.payload
+      );
     } catch (e) {
       Logger.error(
         "An error occurred during adding an item to the cart",
         e as Error
       );
-
       if (httpService.isError(e) && e.message === "Unknown product") {
         throw new UnknownProductError();
       }
-
       if (httpService.isError(e) && e.message === "Product not available") {
         throw new ProductNotAvailableError();
       }
-
       throw new UnknownError();
     }
-  };
-
-  return [handler, isPending] as const;
-};
+  },
+});
 
 export class UnknownProductError extends Error {
   constructor() {

src/lib/api/carts/{cart-id}/clear-cart-mutation.ts

@@ -1,34 +1,20 @@
-import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { mutationOptions } from "@tanstack/react-query";
 
-import { cartQueryKeys } from "@/lib/api/carts/cart-query-keys";
 import { httpService } from "@/lib/http";
 import { Logger } from "@/lib/logger";
+import { UnknownError } from "@/lib/types/unknown-error";
 
-interface IClearCartValues {
+interface ClearCartDto {
   cartId: string;
 }
 
-export const useClearCartMutation = () => {
-  const queryClient = useQueryClient();
-  const { mutateAsync, isPending } = useMutation<
-    void,
-    unknown,
-    IClearCartValues
-  >({
-    mutationFn: (body) => httpService.delete(`carts/${body.cartId}`),
-  });
-
-  const handler = (body: IClearCartValues) => {
-    return mutateAsync(body)
-      .then(async () => {
-        await queryClient.invalidateQueries({ queryKey: cartQueryKeys.all });
-      })
-      .catch((e) => {
-        Logger.error("An error occurred during clearing the cart", e as Error);
-
-        throw e;
-      });
-  };
-
-  return [handler, isPending] as const;
-};
+export const clearCartMutationOptions = mutationOptions({
+  mutationFn: async (body: ClearCartDto): Promise<void> => {
+    try {
+      await httpService.delete(`carts/${body.cartId}`);
+    } catch (e) {
+      Logger.error("An error occurred during clearing the cart", e as Error);
+      throw new UnknownError();
+    }
+  },
+});

src/lib/api/carts/{cart-id}/purchase-mutation.ts

@@ -1,18 +1,8 @@
-import { useState } from "react";
+import { mutationOptions } from "@tanstack/react-query";
 
-// todo: use msw to mock this feature
-export const usePurchaseMutation = () => {
-  const [isLoading, setIsLoading] = useState(false);
-
-  const purchase = async () => {
-    return new Promise<void>((resolve) => {
-      setIsLoading(true);
-      setTimeout(() => {
-        resolve();
-        setIsLoading(false);
-      }, 400);
-    });
-  };
-
-  return [purchase, isLoading] as const;
-};
+// AIDEV-NOTE: stub implementation — replace mutationFn with real HTTP call once MSW mock is ready
+export const purchaseMutationOptions = mutationOptions({
+  mutationFn: async (): Promise<void> => {
+    await new Promise<void>((resolve) => setTimeout(resolve, 400));
+  },
+});

src/lib/api/marketing/{product-id}/rate-product-mutation.ts

@@ -0,0 +1,29 @@
+import { mutationOptions } from "@tanstack/react-query";
+
+import { httpService } from "@/lib/http";
+import { Logger } from "@/lib/logger";
+import { UnknownError } from "@/lib/types/unknown-error";
+
+import type { MarketingProductDto } from "./marketing-product-dto";
+
+export interface RateProductDto {
+  productId: string;
+  rating: number;
+}
+
+export const rateProductMutationOptions = mutationOptions({
+  mutationFn: async ({
+    productId,
+    rating,
+  }: RateProductDto): Promise<MarketingProductDto> => {
+    try {
+      return await httpService.patch<MarketingProductDto, { rating: number }>(
+        `marketing/products/${productId}/rate`,
+        { rating }
+      );
+    } catch (e) {
+      Logger.error("An error occurred during rating the product", e as Error);
+      throw new UnknownError();
+    }
+  },
+});