react-api-kit 1.0.3 → 1.0.5

package/README.md

@@ -1,133 +1,382 @@
-# 🚀 API Client (Axios + TanStack Query)
+# 🚀 react-api-kit
 
-A lightweight, opinion-free API client built on **Axios** and **TanStack Query**, designed for modern React applications.
+A lightweight, production-ready API client built on **Axios** + **TanStack Query** for React applications.
 
-✔ No UI dependencies  
-✔ Global success & error hooks  
-✔ Works with any toast library  
-✔ React Query–ready  
-✔ Production-grade architecture
+[![npm version](https://img.shields.io/npm/v/react-api-kit)](https://www.npmjs.com/package/react-api-kit)
+[![license](https://img.shields.io/npm/l/react-api-kit)](./LICENSE)
+
+✔ Auto Bearer / Token / Custom auth headers  
+✔ Custom static headers per project  
+✔ Global error handling with toast support  
+✔ Auto logout on 401  
+✔ React Query–ready hooks (GET, POST, PATCH, DELETE)  
+✔ No UI dependencies — works with any toast library  
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install axios @tanstack/react-query
+npm install react-api-kit axios @tanstack/react-query
 ```
 
-> **Peer requirements**
+> **Peer Dependencies:** React ≥ 17, Axios ≥ 1, TanStack Query ≥ 4
 
-- React 18+
-- TanStack Query v5+
+---
 
-## 🔧 Quick Start
+## ⚡ Quick Start
 
-### 1️⃣ Setup React Query Provider
+### 1. Wrap your app with React Query Provider
 
 ```tsx
+// main.tsx
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 const queryClient = new QueryClient();
 
-export function AppProviders({ children }) {
+export default function App() {
   return (
-    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
   );
 }
 ```
 
----
-
-### 2️⃣ Configure the API (Required)
-
-Call `setupApi` **once**, ideally at application startup.
+### 2. Configure the API (once at app startup)
 
 ```ts
+// api.config.ts
 import { setupApi } from "react-api-kit";
-import { toast } from "react-toastify";
 
 setupApi({
-  baseURL: "/api",
-
+  baseURL: "https://api.example.com",
+  tokenType: "Bearer",
   getToken: () => localStorage.getItem("token"),
+});
+```
 
+Then import `api.config.ts` in your `main.tsx` before anything else.
+
+---
+
+## 🔧 `setupApi` — Full Configuration
+
+```ts
+setupApi({
+  // ─── Required ───────────────────────────────
+  baseURL: "https://api.example.com",
+
+  // ─── Auth Token ─────────────────────────────
+  tokenType: "Bearer",                          // "Bearer" | "Token" | "JWT" | "ApiKey" | any string
+  getToken: () => localStorage.getItem("token"), // return null to skip Authorization header
+
+  // ─── Custom Static Headers ──────────────────
+  headers: {
+    "X-Api-Key": "your-api-key",               // sent with every request
+    "Accept-Language": "en",
+    "X-App-Version": "1.0.0",
+  },
+
+  // ─── Toast Notifications ────────────────────
   toast: {
     success: (msg) => toast.success(msg),
-    error: (msg) => toast.error(msg),
+    error:   (msg) => toast.error(msg),
+    info:    (msg) => toast.info(msg),          // optional
+    warn:    (msg) => toast.warn(msg),          // optional
+  },
+  toastOptions: {
+    autoClose: 3000,
+    position: "top-right",
+    theme: "light",                             // "light" | "dark" | "colored"
   },
 
+  // ─── Custom Error Messages ───────────────────
   errorMessages: {
-    401: "Session expired",
-    403: "Access denied",
-    500: "Server error",
+    401: "Session expired. Please login again.",
+    403: "Access denied.",
+    404: "Not found.",
+    500: "Server error. Try again later.",
   },
 
-  onSuccess: (data) => {
-    console.log("Global success:", data);
+  // ─── Global Callbacks ───────────────────────
+  onSuccess: (data) => console.log("Success:", data),
+  onError:   (error, message) => console.error("Error:", message),
+  onLogout:  () => {
+    localStorage.clear();
+    window.location.href = "/login";            // auto-called on 401
   },
+});
+```
+
+---
+
+## 🔑 Auth Header — `tokenType` Examples
+
+| `tokenType` | `getToken()` returns | Header sent |
+|-------------|----------------------|-------------|
+| `"Bearer"` *(default)* | `"abc123"` | `Authorization: Bearer abc123` |
+| `"Token"` | `"abc123"` | `Authorization: Token abc123` |
+| `"JWT"` | `"abc123"` | `Authorization: JWT abc123` |
+| `"ApiKey"` | `"abc123"` | `Authorization: ApiKey abc123` |
+| `""` *(empty)* | `"abc123"` | `Authorization: abc123` |
+| *(not set)* | `"abc123"` | `Authorization: Bearer abc123` |
+| `"Bearer"` | `null` / not set | *(no Authorization header)* |
+
+---
+
+## 📋 Custom Headers — `headers` Examples
+
+Use `headers` for static values that never change (API keys, app identifiers, language, etc.):
+
+```ts
+// Single custom header
+setupApi({
+  baseURL: "https://api.example.com",
+  headers: { "token_abc": "askfjshdfjk" },
+});
+// → Every request: token_abc: askfjshdfjk
 
-  onError: (error, message) => {
-    console.error("Global error:", message, error);
+// Multiple custom headers
+setupApi({
+  baseURL: "https://api.example.com",
+  headers: {
+    "X-Api-Key":       "your-api-key",
+    "X-App-ID":        "my-app-001",
+    "Accept-Language": "en",
   },
+});
 
-  onLogout: () => {
-    localStorage.clear();
-    window.location.href = "/login";
+// Custom header + Bearer token together
+setupApi({
+  baseURL: "https://api.example.com",
+  tokenType: "Bearer",
+  getToken: () => localStorage.getItem("token"),
+  headers: {
+    "X-Api-Key": "your-api-key",  // static
   },
 });
+// Both headers sent on every request
 ```
 
 ---
 
-## 🔔 Toast Integration (Optional)
+## 🪝 Hooks
 
-This package **does not ship a toast library**.
+### `useApiQuery` — Fetch data (GET)
 
-You pass your own implementation.
+```ts
+const { data, isLoading, isError, refetch } = useApiQuery(
+  queryKey,   // unique cache key array
+  method,     // "GET" only for queries
+  endpoint,   // API path
+  params?,    // query string params (optional)
+  options?    // TanStack Query options (optional)
+);
+```
+
+**Examples:**
+
+```tsx
+// Basic GET
+const { data, isLoading } = useApiQuery(["users"], "GET", "/users");
+
+// GET with query params → /users?page=1&limit=10
+const { data } = useApiQuery(["users", 1], "GET", "/users", { page: 1, limit: 10 });
+
+// GET with TanStack options
+const { data } = useApiQuery(["user", id], "GET", `/users/${id}`, undefined, {
+  enabled: !!id,           // only fetch when id exists
+  staleTime: 1000 * 60,   // cache for 1 minute
+  retry: 2,               // retry twice on failure
+});
+
+// Usage in component
+function UserList() {
+  const { data, isLoading, isError } = useApiQuery(["users"], "GET", "/users");
+
+  if (isLoading) return <p>Loading...</p>;
+  if (isError)   return <p>Error!</p>;
+  return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
 
 ---
 
-## 🪝 Hooks
+### `useApiMutation` — Create / Update / Delete
 
-### `api`
+```ts
+const { mutate, mutateAsync, isPending, isError } = useApiMutation(
+  mutationKey,   // unique key array
+  method,        // "POST" | "PATCH" | "DELETE" | "GET"
+  invalidateKey? // query keys to refetch after success (optional)
+);
+```
+
+Call `mutate` with `{ endpoint, data }`:
 
 ```ts
-import { api } from "react-api-kit";
+mutate({ endpoint: "/endpoint", data: { ...payload } });
+```
 
-const fetchUsers = () => api.get("/users").then((res) => res.data);
+**Examples:**
+
+#### POST — Create
+
+```tsx
+const { mutate, isPending } = useApiMutation(
+  ["createUser"],
+  "POST",
+  ["users"]  // refetches ["users"] query on success
+);
+
+const handleCreate = () => {
+  mutate({
+    endpoint: "/users",
+    data: { name: "John", email: "john@example.com" },
+  });
+};
 ```
 
-### useApiQuery get
+#### PATCH — Update
 
-const { data, isLoading } = useApiQuery(
-["users"],"GET","/ENDPOINT/,{parems:value},{ ...options} );
+```tsx
+const { mutate } = useApiMutation(["updateUser"], "PATCH", ["users"]);
 
-### `useApiMutation`
+mutate({
+  endpoint: `/users/${id}`,
+  data: { name: "Updated Name" },
+});
+```
 
-```ts
-import { useApiMutation, api } from "react-api-kit";
+#### DELETE — Remove
 
-// POST Req
-const { mutate, isPending } = useApiMutation(["POST KEY"], "POST", "/users", [
-  "Validate",
-]);
+```tsx
+const { mutate } = useApiMutation(["deleteUser"], "DELETE", ["users"]);
 
-// GET Req
-const { mutate, isPending } = useApiMutation(["GET KEY"], "GET", "/users", [
-  "Validate",
-]);
+mutate({ endpoint: `/users/${id}` });
+```
 
-// PATCH Req
-const { mutate, isPending } = useApiMutation(["PATCH KEY"], "PATCH", "/users", [
-  "Validate",
-]);
+#### With callbacks
 
-//Delete Feq
-const { mutate, isPending } = useApiMutation(
-  ["DELETE KEY"],
-  "DELETE",
-  "/users",
-  ["Validate"]
+```tsx
+const { mutate } = useApiMutation(["createUser"], "POST", ["users"]);
+
+mutate(
+  { endpoint: "/users", data: { name: "John" } },
+  {
+    onSuccess: (data) => toast.success("User created!"),
+    onError:   (err)  => toast.error("Failed to create user"),
+  }
 );
 ```
+
+#### Using `mutateAsync` (await)
+
+```tsx
+const { mutateAsync, isPending } = useApiMutation(["createUser"], "POST");
+
+const handleSubmit = async (formData) => {
+  try {
+    const result = await mutateAsync({ endpoint: "/users", data: formData });
+    console.log("Created:", result);
+  } catch (err) {
+    console.error(err);
+  }
+};
+```
+
+---
+
+### `api` — Direct Axios Instance
+
+For cases where you need full control:
+
+```ts
+import { api } from "react-api-kit";
+
+// GET
+const users = await api.get("/users").then(res => res.data);
+
+// GET with params
+const res = await api.get("/orders", { params: { status: "pending" } });
+
+// POST
+const res = await api.post("/users", { name: "John" });
+
+// PATCH
+const res = await api.patch(`/users/${id}`, { name: "Updated" });
+
+// DELETE
+const res = await api.delete(`/users/${id}`);
+
+// Custom header for a single request only
+const res = await api.get("/report", {
+  headers: { "X-Export-Format": "pdf" },
+});
+```
+
+> All requests made via `api` also get the global auth header and custom headers automatically.
+
+---
+
+## ⚠️ Error Handling
+
+Errors are handled automatically via the response interceptor with a **4-level priority**:
+
+| Priority | Source |
+|----------|--------|
+| 1️⃣ | `error.response.data.message` from backend |
+| 2️⃣ | Your custom `errorMessages[status]` in `setupApi` |
+| 3️⃣ | Built-in default messages (see table below) |
+| 4️⃣ | Fallback: `error.message` or `"Network Error"` |
+
+**Built-in default status messages:**
+
+| Status | Default Message |
+|--------|----------------|
+| `400` | Bad request. Please check your input. |
+| `401` | Session expired. Please login again. *(+ auto logout)* |
+| `403` | You do not have permission to perform this action. |
+| `404` | Requested resource not found. |
+| `409` | Conflict occurred. Please try again. |
+| `422` | Validation error. Please check the form. |
+| `500` | Server error. Please try again later. |
+
+> **401 Auto Logout:** When a `401` response is received, `onLogout()` is called automatically.
+
+---
+
+## 📁 Package Structure
+
+```
+src/
+├── config.ts              → ApiConfig interface + setupApi()
+├── index.ts               → Public exports
+├── api/
+│   ├── axios.ts           → Axios instance + request interceptor (auth + headers)
+│   ├── interceptors.ts    → Response interceptor (error handling + auto logout)
+│   └── globalApi.ts       → GET / POST / PATCH / DELETE wrappers
+└── hooks/
+    ├── useApiQuery.ts     → useQuery wrapper
+    └── useApiMutation.ts  → useMutation wrapper
+```
+
+---
+
+## 🔗 Exports
+
+```ts
+import {
+  setupApi,         // configure baseURL, token, headers, toast, etc.
+  api,              // raw Axios instance (with interceptors)
+  useApiQuery,      // TanStack Query hook for GET
+  useApiMutation,   // TanStack Query hook for POST / PATCH / DELETE
+} from "react-api-kit";
+```
+
+---
+
+## 📄 License
+
+ISC © [Ajay Kammar](https://github.com/)

package/dist/react-api-kit.mjs

@@ -1,16 +1,22 @@
 import c from "axios";
-import { useQuery as p, useQueryClient as d, useMutation as l } from "@tanstack/react-query";
-let o;
-const h = (e) => {
-  o = e;
-}, n = c.create();
-n.interceptors.request.use((e) => {
-  o?.baseURL && (e.baseURL = o.baseURL);
-  const t = o?.getToken?.();
-  return t && (e.headers.Authorization = `Token ${t}`), e;
+import { useQuery as p, useQueryClient as d, useMutation as h } from "@tanstack/react-query";
+let r;
+const m = (e) => {
+  r = e;
+}, a = c.create();
+a.interceptors.request.use((e) => {
+  r?.baseURL && (e.baseURL = r.baseURL), r?.headers && Object.entries(r.headers).forEach(([s, o]) => {
+    e.headers[s] = o;
+  });
+  const t = r?.getToken?.();
+  if (t) {
+    const s = r?.tokenType ?? "Bearer";
+    e.headers.Authorization = `${s} ${t}`;
+  }
+  return e;
 });
-n.interceptors.response.use(
-  (e) => (o?.onSuccess?.(e.data), e),
+a.interceptors.response.use(
+  (e) => (r?.onSuccess?.(e.data), e),
   (e) => {
     const t = e?.response?.status, s = {
       400: "Bad request. Please check your input.",
@@ -20,36 +26,36 @@ n.interceptors.response.use(
       409: "Conflict occurred. Please try again.",
       422: "Validation error. Please check the form.",
       500: "Server error. Please try again later."
-    }, r = e?.response?.data?.message || t && o?.errorMessages?.[t] || t && s[t] || e?.message || "Network Error";
-    return o?.toast?.error(r, o.toastOptions), o?.onError?.(e, r), t === 401 && o?.onLogout?.(), Promise.reject(e);
+    }, o = e?.response?.data?.message || t && r?.errorMessages?.[t] || t && s[t] || e?.message || "Network Error";
+    return r?.toast?.error(o, r.toastOptions), r?.onError?.(e, o), t === 401 && r?.onLogout?.(), Promise.reject(e);
   }
 );
 const u = {
-  GET: (e, t) => n.get(e, { params: t }).then((s) => s.data),
-  POST: (e, t) => n.post(e, t).then((s) => s.data),
-  PATCH: (e, t) => n.patch(e, t).then((s) => s.data),
-  DELETE: (e) => n.delete(e).then((t) => t.data)
+  GET: (e, t) => a.get(e, { params: t }).then((s) => s.data),
+  POST: (e, t) => a.post(e, t).then((s) => s.data),
+  PATCH: (e, t) => a.patch(e, t).then((s) => s.data),
+  DELETE: (e) => a.delete(e).then((t) => t.data)
 };
-function g(e, t, s, r, a) {
+function y(e, t, s, o, n) {
   return p({
     queryKey: e,
-    queryFn: () => u[t](s, r),
-    ...a
+    queryFn: () => u[t](s, o),
+    ...n
   });
 }
-function y(e, t, s, r) {
-  const a = d();
-  return l({
+function g(e, t, s) {
+  const o = d();
+  return h({
     mutationKey: e,
-    mutationFn: (i) => u[t](s, i),
+    mutationFn: ({ endpoint: n, data: i }) => u[t](n, i),
     onSuccess: () => {
-      r && a.invalidateQueries({ queryKey: r });
+      s && o.invalidateQueries({ queryKey: s });
     }
   });
 }
 export {
-  n as api,
-  h as setupApi,
-  y as useApiMutation,
-  g as useApiQuery
+  a as api,
+  m as setupApi,
+  g as useApiMutation,
+  y as useApiQuery
 };

package/dist/react-api-kit.umd.js

@@ -1 +1 @@
-(function(s,r){typeof exports=="object"&&typeof module<"u"?r(exports,require("axios"),require("@tanstack/react-query")):typeof define=="function"&&define.amd?define(["exports","axios","@tanstack/react-query"],r):(s=typeof globalThis<"u"?globalThis:s||self,r(s.ReactApiKit={},s.axios,s.reactQuery))})(this,(function(s,r,u){"use strict";let o;const d=e=>{o=e},i=r.create();i.interceptors.request.use(e=>{o?.baseURL&&(e.baseURL=o.baseURL);const t=o?.getToken?.();return t&&(e.headers.Authorization=`Token ${t}`),e}),i.interceptors.response.use(e=>(o?.onSuccess?.(e.data),e),e=>{const t=e?.response?.status,n={400:"Bad request. Please check your input.",401:"Session expired. Please login again.",403:"You do not have permission to perform this action.",404:"Requested resource not found.",409:"Conflict occurred. Please try again.",422:"Validation error. Please check the form.",500:"Server error. Please try again later."},a=e?.response?.data?.message||t&&o?.errorMessages?.[t]||t&&n[t]||e?.message||"Network Error";return o?.toast?.error(a,o.toastOptions),o?.onError?.(e,a),t===401&&o?.onLogout?.(),Promise.reject(e)});const p={GET:(e,t)=>i.get(e,{params:t}).then(n=>n.data),POST:(e,t)=>i.post(e,t).then(n=>n.data),PATCH:(e,t)=>i.patch(e,t).then(n=>n.data),DELETE:e=>i.delete(e).then(t=>t.data)};function f(e,t,n,a,c){return u.useQuery({queryKey:e,queryFn:()=>p[t](n,a),...c})}function l(e,t,n,a){const c=u.useQueryClient();return u.useMutation({mutationKey:e,mutationFn:y=>p[t](n,y),onSuccess:()=>{a&&c.invalidateQueries({queryKey:a})}})}s.api=i,s.setupApi=d,s.useApiMutation=l,s.useApiQuery=f,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));
+(function(o,i){typeof exports=="object"&&typeof module<"u"?i(exports,require("axios"),require("@tanstack/react-query")):typeof define=="function"&&define.amd?define(["exports","axios","@tanstack/react-query"],i):(o=typeof globalThis<"u"?globalThis:o||self,i(o.ReactApiKit={},o.axios,o.reactQuery))})(this,(function(o,i,u){"use strict";let n;const p=e=>{n=e},a=i.create();a.interceptors.request.use(e=>{n?.baseURL&&(e.baseURL=n.baseURL),n?.headers&&Object.entries(n.headers).forEach(([s,r])=>{e.headers[s]=r});const t=n?.getToken?.();if(t){const s=n?.tokenType??"Bearer";e.headers.Authorization=`${s} ${t}`}return e}),a.interceptors.response.use(e=>(n?.onSuccess?.(e.data),e),e=>{const t=e?.response?.status,s={400:"Bad request. Please check your input.",401:"Session expired. Please login again.",403:"You do not have permission to perform this action.",404:"Requested resource not found.",409:"Conflict occurred. Please try again.",422:"Validation error. Please check the form.",500:"Server error. Please try again later."},r=e?.response?.data?.message||t&&n?.errorMessages?.[t]||t&&s[t]||e?.message||"Network Error";return n?.toast?.error(r,n.toastOptions),n?.onError?.(e,r),t===401&&n?.onLogout?.(),Promise.reject(e)});const d={GET:(e,t)=>a.get(e,{params:t}).then(s=>s.data),POST:(e,t)=>a.post(e,t).then(s=>s.data),PATCH:(e,t)=>a.patch(e,t).then(s=>s.data),DELETE:e=>a.delete(e).then(t=>t.data)};function f(e,t,s,r,c){return u.useQuery({queryKey:e,queryFn:()=>d[t](s,r),...c})}function h(e,t,s){const r=u.useQueryClient();return u.useMutation({mutationKey:e,mutationFn:({endpoint:c,data:l})=>d[t](c,l),onSuccess:()=>{s&&r.invalidateQueries({queryKey:s})}})}o.api=a,o.setupApi=p,o.useApiMutation=h,o.useApiQuery=f,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "react-api-kit",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Reusable Axios + TanStack Query API hooks for React",
   "license": "ISC",
   "author": "Ajay kammar",
-  
   "main": "./dist/react-api-kit.umd.js",
   "module": "./dist/react-api-kit.mjs",
   "types": "./dist/index.d.ts",
@@ -29,4 +28,4 @@
     "@vitejs/plugin-react": "^5.1.2",
     "vite": "^7.3.0"
   }
-}
+}