@fgrzl/fetch 1.0.0-ci.11 → 1.1.0-alpha.10

package/README.md

@@ -3,77 +3,101 @@
 
 # @fgrzl/fetch
 
-A lightweight, middleware-friendly fetch client for TypeScript projects.
+A production-ready HTTP client for TypeScript that **just works** out of the box.
 
 ## ✨ Features
 
+- **Pit of Success Design**: Simple defaults that just work, customizable when needed
 - Simple API: `api.get('/api/user')`
-- Built-in CSRF token support
-- Automatic 401 redirect handling
+- Built-in CSRF token support (XSRF-TOKEN standard)
+- Smart 401 redirect handling with return URL preservation
+- Retry middleware with configurable strategies
 - Custom middleware support (request/response)
 - TypeScript-first, small and dependency-free
 
 ## 📦 Installation
 
+**Install**
+
 ```bash
 npm install @fgrzl/fetch
 ```
 
-## 🚀 Quick Start
+**Use immediately** - no configuration required:
 
 ```ts
 import api from "@fgrzl/fetch";
 
-const data = await api.get("/api/user");
+// It just works! 🎉
+const users = await api.get("/api/users");
+const newUser = await api.post("/api/users", { name: "John" });
+
+// Built-in error handling
+if (users.ok) {
+  console.log("Users:", users.data);
+} else {
+  console.error("Error:", users.error?.message);
+}
 ```
 
-Or create a custom instance:
+**Need custom config?** Add it when you need it:
 
 ```ts
-import { FetchClient } from "./client";
-import { useCSRF } from "./csrf";
-import { useUnauthorized } from "./unauthorized";
-
-const api = new FetchClient({
-  credentials: "same-origin",
-});
+import { FetchClient, useAuthentication } from "@fgrzl/fetch";
 
-useCSRF(api, {
-  cookieName: "csrf_token",
-  headerName: "X-CSRF-Token",
+const authClient = useAuthentication(new FetchClient(), {
+  tokenProvider: () => localStorage.getItem("token") || "",
 });
 
-useUnauthorized(api, {
-  loginPath: "/login",
-});
+// Smart defaults - just works
+useCSRF(client);
+useAuthorization(client); // Redirects to /login with return URL
+useRetry(client);
+
+// All requests now return FetchResponse<T>
+interface User {
+  id: number;
+  name: string;
+}
+const userResponse = await client.get<User>("/api/user");
+if (userResponse.ok) {
+  console.log(userResponse.data.name); // Typed access to data
+} else {
+  console.error(`Failed with status ${userResponse.status}`);
+}
 ```
 
-## 🧩 Middleware
+## ✨ What You Get Out of the Box
 
-Add your own middleware:
+- **Zero Configuration** - Works immediately with smart defaults
+- **CSRF Protection** - Automatic XSRF-TOKEN handling
+- **Retry Logic** - Exponential backoff for failed requests
+- **Request Logging** - Built-in observability
+- **TypeScript First** - Full type safety and IntelliSense
+- **Middleware System** - Composable and extensible
 
-```ts
-client.useRequestMiddleware(async (req, url) => {
-  return [{ ...req, headers: { ...req.headers, "X-Debug": "true" } }, url];
-});
-```
+## 📚 Documentation
 
-## 🔐 CSRF + 401 Handling
+Ready to go deeper? Check out our comprehensive guides:
 
-The default export is pre-configured with:
+- **[Getting Started](docs/getting-started.md)** - Installation and basic usage
+- **[Configuration](docs/configuration.md)** - Advanced client setup
+- **[Middleware](docs/middleware.md)** - Authentication, caching, retries
+- **[Error Handling](docs/error-handling.md)** - Robust error management
+- **[TypeScript Guide](docs/typescript.md)** - Type-safe API calls
+- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
 
-- `credentials: 'same-origin'`
-- CSRF token from `XSRF-TOKEN` cookie
-- 401 redirect to `/login?returnTo=...`
+## 🏗️ Architecture
 
-## 🧪 Testing
+Built on a **"pit of success"** philosophy where:
 
-```bash
-npm run test
-```
+- Simple things are simple (`api.get("/path")`)
+- Complex things are possible (custom middleware stacks)
+- TypeScript guides you to correct usage
+- Smart defaults handle 80% of use cases
 
-## 🛠 Build
+[Learn more about our architecture →](docs/architecture.md)
 
-```bash
-npm run build
-```
+## License
+
+MIT