Util function for cleaner usage of TanStack useQuery

src/App.tsx

@@ -1,4 +1,8 @@
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  QueryCache,
+  QueryClient,
+  QueryClientProvider,
+} from "@tanstack/react-query";
 import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 import { Suspense } from "react";
 
@@ -12,6 +16,7 @@ import AuthUserProvider from "@/Providers/AuthUserProvider";
 import HistoryAPIProvider from "@/Providers/HistoryAPIProvider";
 import Routers from "@/Routers";
 import { FeatureFlagsProvider } from "@/Utils/featureFlags";
+import { handleQueryError } from "@/Utils/request/errorHandler";
 
 import { PubSubProvider } from "./Utils/pubsubContext";
 
@@ -23,6 +28,9 @@ const queryClient = new QueryClient({
       staleTime: 5 * 60 * 1000, // 5 minutes
     },
   },
+  queryCache: new QueryCache({
+    onError: handleQueryError,
+  }),
 });
 
 const App = () => {

src/Utils/request/README.md

@@ -4,36 +4,101 @@ CARE now uses TanStack Query (formerly React Query) as its data fetching solutio
 
 ## Using TanStack Query (Recommended for new code)
 
-For new API integrations, we recommend using TanStack Query directly:
+For new API integrations, we recommend using TanStack Query with `api.query`:
 
 ```tsx
 import { useQuery } from "@tanstack/react-query";
-import request from "@/Utils/request/request";
-import FooRoutes from "@foo/routes";
+import api from "@/Utils/request/api-request";
 
-export default function FooDetails({ id }) {
-  const { data, isLoading, error } = useQuery({
-    queryKey: [FooRoutes.getFoo.path, id],
-    queryFn: async () => {
-      const response = await request(FooRoutes.getFoo, {
-        pathParams: { id }
-      });
-      return response.data;
-    }
+export default function UserProfile() {
+  const { data, isLoading } = useQuery({
+    queryKey: [routes.users.current.path],
+    queryFn: api.query(routes.users.current)
   });
 
   if (isLoading) return <Loading />;
-  if (error) return <Error error={error} />;
+  return <div>{data?.name}</div>;
+}
 
-  return (
-    <div>
-      <span>{data.id}</span>
-      <span>{data.name}</span>
-    </div>
-  );
+// With path parameters
+function PatientDetails({ id }: { id: string }) {
+  const { data } = useQuery({
+    queryKey: ['patient', id],
+    queryFn: api.query(routes.patient.get, {
+      pathParams: { id }
+    })
+  });
+
+  return <div>{data?.name}</div>;
+}
+
+// With query parameters
+function SearchMedicines() {
+  const { data } = useQuery({
+    queryKey: ['medicines', 'paracetamol'],
+    queryFn: api.query(routes.medicine.search, {
+      queryParams: { search: 'paracetamol' }
+    })
+  });
+
+  return <MedicinesList medicines={data?.results} />;
+}
+
+// When you need response status/error handling
+function FacilityDetails({ id }: { id: string }) {
+  const { data, isLoading } = useQuery({
+    queryKey: ["facility", id],
+    queryFn: api.query(routes.getFacility, {
+      pathParams: { id },
+      silent: true
+    })
+  });
+
+  if (isLoading) return <Loading />;
+  return <div>{data?.name}</div>;
+}
+
+### api.query
+
+`api.query` is our wrapper around fetch that works seamlessly with TanStack Query. It:
+- Handles response parsing (JSON, text, blobs)
+- Constructs proper error objects
+- Integrates with our global error handling
+
+```typescript
+interface QueryOptions {
+  pathParams?: Record<string, string>;  // URL parameters
+  queryParams?: Record<string, string>; // Query string parameters
+  silent?: boolean;                     // Suppress error notifications
 }
+
+// Basic usage
+useQuery({
+  queryKey: ["users"],
+  queryFn: api.query(routes.users.list)
+});
+
+// With parameters
+useQuery({
+  queryKey: ["user", id],
+  queryFn: api.query(routes.users.get, {
+    pathParams: { id },
+    queryParams: { include: "details" },
+    silent: true  // Optional: suppress error notifications
+  })
+});
 ```
 
+### Error Handling
+
+All API errors are now handled globally. Common scenarios like:
+- 404 responses -> Redirects to /not-found
+- Session expiry -> Redirects to /session-expired
+- Bad requests (400/406) -> Shows error notification
+are automatically handled.
+
+Use the `silent: true` option to suppress error notifications for specific queries.
+
 ## Migration Guide & Reference
 
 ### Understanding the Transition
@@ -60,12 +125,9 @@ function LegacyComponent({ id }) {
 function ModernComponent({ id }) {
   const { data, isLoading, error, refetch } = useQuery({
     queryKey: [UserRoutes.getUser.path, id],
-    queryFn: async () => {
-      const response = await request(UserRoutes.getUser, {
-        pathParams: { id }
-      });
-      return response.data;
-    },
+    queryFn: api.query(UserRoutes.getUser, {
+      pathParams: { id }
+    }),
     enabled: true,
     refetchOnWindowFocus: false
   });
@@ -100,7 +162,7 @@ useTanStackQueryInstead(route, { prefetch: shouldFetch })
 // Modern
 useQuery({
   queryKey: [route.path],
-  queryFn: async () => (await request(route)).data,
+  queryFn: api.query(route),
   enabled: shouldFetch
 })
 ```
@@ -116,13 +178,10 @@ useTanStackQueryInstead(route, {
 // Modern
 useQuery({
   queryKey: [route.path, id, filter],
-  queryFn: async () => {
-    const response = await request(route, {
-      pathParams: { id },
-      query: { filter }
-    });
-    return response.data;
-  }
+  queryFn: api.query(route, {
+    pathParams: { id },
+    queryParams: { filter }
+  })
 })
 ```
 
@@ -135,12 +194,10 @@ if (res?.status === 403) handleForbidden();
 // Modern
 useQuery({
   queryKey: [route.path],
-  queryFn: async () => {
-    const response = await request(route);
-    if (response.res.status === 403) handleForbidden();
-    return response.data;
-  },
-  onError: (error) => handleError(error)
+  queryFn: api.query(route, {
+    silent: true // Optional: suppress error notifications
+  })
+  // Error handling is now done globally
 })
 ```
 

src/Utils/request/api-request.ts

@@ -0,0 +1,63 @@
+import careConfig from "@careConfig";
+
+import { QueryOptions, Route } from "@/Utils/request/types";
+import { makeHeaders, makeUrl } from "@/Utils/request/utils";
+
+import { ResponseError } from "../response/responseError";
+import { getResponseBody } from "./request";
+
+async function queryRequest<TData, TBody>(
+  { path, method, noAuth }: Route<TData, TBody>,
+  options?: QueryOptions<TBody> & { signal?: AbortSignal },
+): Promise<TData> {
+  const url = `${careConfig.apiUrl}${makeUrl(path, options?.queryParams, options?.pathParams)}`;
+
+  const requestOptions: RequestInit = {
+    method,
+    headers: makeHeaders(noAuth ?? false),
+    signal: options?.signal,
+  };
+
+  if (options?.body) {
+    requestOptions.body = JSON.stringify(options.body);
+  }
+
+  const res = await fetch(url, requestOptions);
+
+  if (!res.ok) {
+    const error = await res
+      .json()
+      .catch(() => ({ detail: "Something went wrong!" }));
+    throw new ResponseError({
+      name: error.name,
+      message: "Request Failed",
+      cause: {
+        ...error,
+        code: error.code || (res.status === 404 ? "not_found" : undefined),
+        status: res.status,
+        silent: options?.silent,
+        detail: error.detail || "Something went wrong!",
+      },
+    });
+  }
+
+  return getResponseBody<TData>(res);
+}
+
+/**
+ * Creates a TanStack Query compatible request function
+ */
+function createQuery<TData, TBody>(
+  route: Route<TData, TBody>,
+  options?: QueryOptions,
+) {
+  return async ({ signal }: { signal?: AbortSignal } = {}) => {
+    return queryRequest(route, { ...options, signal });
+  };
+}
+
+const api = {
+  query: createQuery,
+} as const;
+
+export default api;

src/Utils/request/errorHandler.ts

@@ -0,0 +1,70 @@
+import { navigate } from "raviger";
+
+import * as Notifications from "@/Utils/Notifications";
+import { ResponseError } from "@/Utils/response/responseError";
+
+const notify = Notifications;
+
+export function handleQueryError(error: Error) {
+  // Cast to ResponseError if it matches our expected structure
+  if (error instanceof ResponseError) {
+    const errorCause = error.cause;
+
+    // Ignore aborted requests
+    if (error?.name === "AbortError") return;
+
+    // Handle session expiry
+    if (isSessionExpired(errorCause)) {
+      handleSessionExpiry();
+      return;
+    }
+
+    // Handle bad requests
+    if (isBadRequest(errorCause)) {
+      if (!errorCause?.silent) notify.BadRequest({ errs: errorCause });
+      return;
+    }
+
+    // Handle not found
+    if (isNotFound(errorCause)) {
+      handleNotFound();
+      return;
+    }
+
+    // Handle other errors
+    if (!errorCause?.silent) {
+      notify.Error({ msg: errorCause?.detail || "Something went wrong!" });
+    }
+  } else {
+    // Handle non-ResponseError errors
+    notify.Error({ msg: error.message || "Something went wrong!" });
+  }
+}
+
+// Helper functions
+function isSessionExpired(error: any) {
+  return (
+    error?.code === "token_not_valid" ||
+    error?.detail === "Authentication credentials were not provided."
+  );
+}
+
+function handleSessionExpiry() {
+  if (!location.pathname.startsWith("/session-expired")) {
+    navigate(`/session-expired?redirect=${window.location.href}`);
+  }
+}
+
+function isBadRequest(error: any) {
+  return error?.status === 400 || error?.status === 406;
+}
+
+function isNotFound(error: any) {
+  return error?.status === 404 || error?.code === "not_found";
+}
+
+function handleNotFound() {
+  if (!location.pathname.startsWith("/not-found")) {
+    navigate("/not-found");
+  }
+}

src/Utils/request/request.ts

@@ -61,7 +61,7 @@ export default async function request<TData, TBody>(
   return result;
 }
 
-async function getResponseBody<TData>(res: Response): Promise<TData> {
+export async function getResponseBody<TData>(res: Response): Promise<TData> {
   if (!(res.headers.get("content-length") !== "0")) {
     return null as TData;
   }

src/Utils/request/types.ts

@@ -35,6 +35,13 @@ export interface RequestOptions<TData = unknown, TBody = unknown> {
   silent?: boolean;
 }
 
+export interface QueryOptions<TBody = unknown> {
+  pathParams?: Record<string, string>;
+  queryParams?: Record<string, string>;
+  body?: TBody;
+  silent?: boolean;
+}
+
 export interface PaginatedResponse<TItem> {
   count: number;
   next: string | null;

src/Utils/response/responseError.ts

@@ -0,0 +1,27 @@
+export class ResponseError extends Error {
+  name: string;
+  message: string;
+  cause: ErrorCause;
+
+  constructor({
+    name,
+    message,
+    cause,
+  }: {
+    name: string;
+    message: string;
+    cause: ErrorCause;
+  }) {
+    super(message);
+    this.name = name;
+    this.message = message;
+    this.cause = cause;
+  }
+}
+
+export interface ErrorCause {
+  code: string;
+  status: number;
+  silent: boolean | false;
+  detail: string;
+}