@kawaiininja/fetch 1.0.3 → 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/dist/hooks/useCsrf.d.ts

@@ -1,4 +1,4 @@
 export declare function useCsrf(): {
     fetchCSRF: () => Promise<string>;
-    clearCsrf: () => void;
+    clearCsrf: () => Promise<void>;
 };

package/dist/hooks/useCsrf.js

@@ -1,27 +1,59 @@
+import { SecureStoragePlugin } from "capacitor-secure-storage-plugin";
 import { useCallback, useRef } from "react";
 import { INTERNAL_HEADER } from "../context/ApiContext";
 import { useApiConfig } from "./useApiConfig";
 export function useCsrf() {
     const { apiUrl } = useApiConfig();
     const csrfRef = useRef(null);
-    const clearCsrf = useCallback(() => {
+    const clearCsrf = useCallback(async () => {
+        console.log("[useCsrf] Clearing CSRF token...");
         csrfRef.current = null;
         if (typeof window !== "undefined") {
+            const platform = window.Capacitor?.getPlatform() || "web";
+            const isNative = platform === "ios" || platform === "android";
+            if (isNative) {
+                try {
+                    await SecureStoragePlugin.remove({ key: "csrf_token" });
+                    console.log("[useCsrf] Cleared from SecureStorage.");
+                }
+                catch (e) {
+                    console.warn("[useCsrf] Failed to clear from SecureStorage, trying localStorage:", e);
+                }
+            }
             localStorage.removeItem("csrf_token");
         }
     }, []);
     const fetchCSRF = useCallback(async () => {
         if (csrfRef.current)
             return csrfRef.current;
-        // Try to get from localStorage first (for Capacitor/mobile)
+        // Try to get from storage first (for Capacitor/mobile)
         if (typeof window !== "undefined") {
+            const platform = window.Capacitor?.getPlatform() || "web";
+            const isNative = platform === "ios" || platform === "android";
+            if (isNative) {
+                try {
+                    const { value } = await SecureStoragePlugin.get({
+                        key: "csrf_token",
+                    });
+                    if (value) {
+                        console.log("[useCsrf] Retrieved from SecureStorage.");
+                        csrfRef.current = value;
+                        return value;
+                    }
+                }
+                catch (e) {
+                    console.warn("[useCsrf] SecureStorage check failed:", e);
+                }
+            }
             const storedCsrf = localStorage.getItem("csrf_token");
             if (storedCsrf) {
+                console.log("[useCsrf] Retrieved from localStorage.");
                 csrfRef.current = storedCsrf;
                 return storedCsrf;
             }
         }
         // Construct CSRF URL using the context's baseUrl
+        console.log("[useCsrf] Fetching new CSRF token from server...");
         const csrfUrl = apiUrl("auth/csrf-token");
         const res = await fetch(csrfUrl, {
             method: "GET",
@@ -33,8 +65,19 @@ export function useCsrf() {
         if (!token)
             throw new Error("Missing CSRF token");
         csrfRef.current = token;
-        // Store in localStorage for Capacitor/mobile (cookies don't work cross-domain)
+        // Store in storage
         if (typeof window !== "undefined") {
+            const platform = window.Capacitor?.getPlatform() || "web";
+            const isNative = platform === "ios" || platform === "android";
+            if (isNative) {
+                try {
+                    await SecureStoragePlugin.set({ key: "csrf_token", value: token });
+                    console.log("[useCsrf] Stored in SecureStorage.");
+                }
+                catch (e) {
+                    console.warn("[useCsrf] SecureStorage set failed, falling back to localStorage:", e);
+                }
+            }
             localStorage.setItem("csrf_token", token);
         }
         return token;

package/dist/hooks/useFetch.js

@@ -51,30 +51,42 @@ export const useFetch = (endpoint, baseOptions = {}) => {
         // 🔒 SECURITY STRATEGY: NATIVE (MOBILE)
         if (isNative && isInternal) {
             // Mobile relies on manual headers ("Active Courier")
-            // We DO NOT use CSRF tokens on mobile (Cookies generally don't work reliably here)
             // 🛡️ S-RANK UPGRADE: Use Secure Storage (Async) instead of LocalStorage
+            console.log(`[useFetch] [Native] Strategy: Active Courier for ${url}`);
+            let authToken = null;
+            let sessionId = null;
             try {
-                const { value: authToken } = await SecureStoragePlugin.get({
+                const { value: secureAuthToken } = await SecureStoragePlugin.get({
                     key: "token",
-                }).catch(() => ({ value: null }));
-                const { value: sessionId } = await SecureStoragePlugin.get({
+                });
+                const { value: secureSessionId } = await SecureStoragePlugin.get({
                     key: "session_id",
-                }).catch(() => ({ value: null }));
+                });
+                authToken = secureAuthToken;
+                sessionId = secureSessionId;
                 if (authToken)
-                    headersConfig["Authorization"] = `Bearer ${authToken}`;
-                if (sessionId)
-                    headersConfig["X-Session-ID"] = sessionId;
+                    console.log("[useFetch] [Native] Token retrieved from SecureStorage.");
             }
             catch (err) {
-                // Determine if we should log this - might be noisy if keys just don't exist yet
+                console.warn("[useFetch] [Native] SecureStorage failed or not present, trying localStorage:", err);
+                authToken = localStorage.getItem("token");
+                sessionId = localStorage.getItem("session_id");
+                if (authToken)
+                    console.log("[useFetch] [Native] Token retrieved from localStorage fallback.");
             }
+            if (authToken)
+                headersConfig["Authorization"] = `Bearer ${authToken}`;
+            if (sessionId)
+                headersConfig["X-Session-ID"] = sessionId;
         }
         // 🔒 SECURITY STRATEGY: WEB (BROWSER)
         if (!isNative && isInternal) {
             // Web relies on Cookies ("Passive Courier") for Auth
             // BUT we MUST attach the CSRF Token to prevent attacks
-            if (token)
+            if (token) {
                 headersConfig["X-CSRF-Token"] = token;
+                // console.log("[useFetch] [Web] CSRF token attached.");
+            }
             // On Web, we DO NOT attach 'Authorization' or 'Session-ID' from localStorage
             // This minimizes XSS risk. The HttpOnly cookie handles it.
         }

package/package.json

@@ -1,46 +1,46 @@
-{
-    "name": "@kawaiininja/fetch",
-    "version": "1.0.3",
-    "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"
+    }
+}