@kawaiininja/fetch 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,172 @@
+# @kawaiininja/fetch
+
+A production-grade, hybrid-native HTTP client designed for the Onyx Framework.
+
+**Rating: S-Tier Utility 🏆**
+
+This package automates enterprise-grade security, CSRF handling, and platform detection (Web vs. Native Mobile), allowing you to focus on building features rather than handling HTTP boilerplate.
+
+## 🚀 Features
+
+- **Hybrid Intelligence**: Automatically detects if running on Web or Native Mobile (Capacitor).
+- **Pro Security**:
+  - **Native**: Uses `SecureStoragePlugin` for token management.
+  - **Web**: Uses `HttpOnly` cookies + Auto-CSRF token rotation.
+- **Smart Retries**: Automatically handles `403 CSRF` errors by fetching a new token and retrying the request.
+- **Optimistic Updates**: Update your UI instantly before the server responds.
+- **Type-Safe**: Full TypeScript support, but works efficiently in JS too.
+
+---
+
+## 🛠️ Setup
+
+Wrap your application with the `ApiProvider` to configure your base URL and global behavior.
+
+```jsx
+// src/App.jsx
+import { ApiProvider } from "@kawaiininja/fetch";
+
+const apiConfig = {
+  baseUrl: "https://api.myapp.com",
+  version: "v1",
+  // Optional: Global error handler (e.g., for Toast notifications)
+  onError: (msg, status) => console.error(`[API Error ${status}]: ${msg}`),
+};
+
+export default function App() {
+  return (
+    <ApiProvider config={apiConfig}>
+      <YourApp />
+    </ApiProvider>
+  );
+}
+```
+
+---
+
+## 📖 Usage Patterns (Efficient JS)
+
+### 1. Lazy Action (Forms & Buttons)
+
+Best for login forms, submitting data, or manual triggers. No need for `useState` or `try/catch` boilerplate.
+
+```jsx
+import { useFetch } from "@kawaiininja/fetch";
+
+export const LoginForm = () => {
+  // Extract helpers directly
+  const { post, isLoading, error } = useFetch("/auth/login");
+
+  const handleLogin = async (e) => {
+    e.preventDefault();
+    const formData = new FormData(e.target);
+    const payload = Object.fromEntries(formData);
+
+    // ✅ Efficient: helper handles JSON stringify, headers, and loading state
+    const user = await post(payload);
+
+    if (user) {
+      console.log("Welcome", user.name);
+      // Redirect or update context here
+    }
+  };
+
+  return (
+    <form onSubmit={handleLogin}>
+      {error && <div className="error-banner">{error}</div>}
+
+      <input name="email" type="email" placeholder="Email" />
+      <input name="password" type="password" placeholder="Password" />
+
+      <button disabled={isLoading}>
+        {isLoading ? "Logging in..." : "Log In"}
+      </button>
+    </form>
+  );
+};
+```
+
+### 2. Optimistic Updates (Instant UX)
+
+Make your app feel zero-latency by updating the local data _before_ the server responds.
+
+```jsx
+const UserProfile = () => {
+  // 'data' is your state, 'setData' lets you modify it instantly
+  const { data, setData, patch } = useFetch("/user/me");
+
+  const updateName = async (newName) => {
+    // 1. Instant UI update (Optimistic)
+    // We assume it will succeed to make it feel snappy
+    setData((prev) => ({ ...prev, name: newName }));
+
+    // 2. Send request in background
+    // If it fails, the error state will update automatically and revert (if you handle it)
+    await patch({ name: newName });
+  };
+
+  return (
+    <div>
+      <h1>Hello, {data?.name || "Guest"}</h1>
+      <button onClick={() => updateName("Vinay")}>Update Name</button>
+    </div>
+  );
+};
+```
+
+### 3. Fetch on Load (Page Data)
+
+For standard "load data when page opens" behavior, simply pair with `useEffect`.
+
+```jsx
+import { useEffect } from "react";
+import { useFetch } from "@kawaiininja/fetch";
+
+export const Dashboard = () => {
+  // 'get' is the trigger function
+  const { data, isLoading, get } = useFetch("/dashboard");
+
+  useEffect(() => {
+    // Trigger the fetch when component mounts
+    get();
+  }, []); // Empty array ensures it only runs once
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>Dashboard Stats</h1>
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+};
+```
+
+### 4. Reactive Fetch (Search & Filters)
+
+Trigger a fetch automatically whenever a variable changes (like a filter button or search bar).
+
+```jsx
+import { useEffect, useState } from "react";
+import { useFetch } from "@kawaiininja/fetch";
+
+export const FilterList = () => {
+  const [filter, setFilter] = useState("all");
+  const [search, setSearch] = useState("");
+  const { data, get } = useFetch("/items");
+
+  // ✅ The "Watcher" Pattern
+  useEffect(() => {
+    // Overrides the URL with new params whenever dependencies change
+    get({ url: `/items?status=${filter}&q=${search}` });
+  }, [filter, search]); // 👈 DEPENDENCY ARRAY controls the trigger
+
+  return (
+    <div>
+      <button onClick={() => setFilter("active")}>Active</button>
+      <input onChange={(e) => setSearch(e.target.value)} />
+      <List items={data} />
+    </div>
+  );
+};
+```

package/package.json

@@ -1,46 +1,46 @@
-{
-    "name": "@kawaiininja/fetch",
-    "version": "1.0.4",
-    "description": "Core fetch utility for Onyx Framework",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "module": "dist/index.js",
-    "type": "module",
-    "exports": {
-        ".": "./dist/index.js"
-    },
-    "files": [
-        "dist",
-        "README.md"
-    ],
-    "scripts": {
-        "build": "tsc"
-    },
-    "keywords": [
-        "react",
-        "fetch",
-        "onyx",
-        "kawaiininja",
-        "http"
-    ],
-    "author": "Vinay (4kawaiininja)",
-    "license": "MIT",
-    "peerDependencies": {
-        "react": "^18.0.0 || ^19.0.0",
-        "react-dom": "^18.0.0 || ^19.0.0"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "devDependencies": {
-        "@types/react": "^19.2.7",
-        "@types/react-dom": "^19.2.3",
-        "typescript": "^5.7.0"
-    },
-    "dependencies": {
-        "@capacitor-community/security-provider": "^7.0.0",
-        "@capacitor-community/text-to-speech": "^6.1.0",
-        "@capacitor/core": "^8.0.1",
-        "capacitor-secure-storage-plugin": "^0.13.0"
-    }
-}
+{
+    "name": "@kawaiininja/fetch",
+    "version": "1.0.6",
+    "description": "Core fetch utility for Onyx Framework",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "module": "dist/index.js",
+    "type": "module",
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc"
+    },
+    "keywords": [
+        "react",
+        "fetch",
+        "onyx",
+        "kawaiininja",
+        "http"
+    ],
+    "author": "Tristan (4kawaiininja)",
+    "license": "MIT",
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.7",
+        "@types/react-dom": "^19.2.3",
+        "typescript": "^5.7.0"
+    },
+    "dependencies": {
+        "@capacitor-community/security-provider": "^7.0.0",
+        "@capacitor-community/text-to-speech": "^6.1.0",
+        "@capacitor/core": "^8.0.1",
+        "capacitor-secure-storage-plugin": "^0.13.0"
+    }
+}