@tahanabavi/typefetch 1.0.0 → 1.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish Package
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+      - 'src/**'
+      - 'README.md'
+      - '.github/workflows/publish.yml'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,183 +1,183 @@
-# TypeFetch
-
-TypeFetch is a type-safe client for working with APIs, built with TypeScript and Zod. This project allows you to define API contracts and safely use types, while also supporting middlewares, error handling, and response transformation.
-
----
-
-## Features
-
-* Fully type-safe using TypeScript and Zod
-* Define contracts for modules and endpoints
-* Support for middlewares to add custom behavior before or after requests
-* Error handling with the `RichError` class
-* Ability to transform responses using a response transformer
-* Authentication support via token
-
----
-
-## Installation
-
-```bash
-npm install typefetch
-# or
-yarn add typefetch
-```
-
----
-
-## Defining Contracts
-
-Contracts are defined using the `Contracts` and `EndpointDef` types
-
-```ts
-import { z } from "zod";
-
-const contracts = {
-  user: {
-    getUser: {
-      method: "GET",
-      path: "/user/:id",
-      auth: true,
-      request: z.object({ id: z.string() }),
-      response: z.object({ id: z.string(), name: z.string() }),
-    },
-    createUser: {
-      method: "POST",
-      path: "/user",
-      request: z.object({ name: z.string() }),
-      response: z.object({ id: z.string(), name: z.string() }),
-    },
-  },
-} as const;
-```
-
----
-
-## Using `ApiClient`
-
-```ts
-import { ApiClient, RichError } from "typefetch";
-
-const client = new ApiClient(
-  {
-    baseUrl: "https://api.example.com",
-    token: "your-auth-token",
-  },
-  contracts
-);
-
-client.init();
-
-const user = await client.user.getUser({ id: "123" });
-const newUser = await client.user.createUser({ name: "Taha" });
-```
-
----
-
-## Error Handling
-
-All errors are provided via the `RichError` class. You can define a custom error handler:
-
-```ts
-client.onError((error: RichError) => {
-  console.error("API Error:", error.message, error.status);
-});
-```
-
----
-
-## Middlewares
-
-You can add custom behavior before or after requests. Middlewares work similarly to Express:
-
-```ts
-client.use(async (ctx, next, options) => {
-  console.log("Request URL:", ctx.url);
-  const response = await next();
-  console.log("Response status:", response.status);
-  return response;
-});
-```
-
-### Built-in Middlewares
-
-This project provides some built-in middlewares:
-
-```ts
-import {
-  LoggingMiddleware,
-  RetryMiddleware,
-  AuthMiddleware,
-  CacheMiddleware,
-} from "typefetch/middlewares";
-
-client.use(LoggingMiddleware);
-client.use(RetryMiddleware, { maxRetries: 3, delay: 100 });
-client.use(AuthMiddleware, { refreshToken: () => "your-auth-token" });
-client.use(CacheMiddleware, { ttl: 60 * 1000 });
-```
-
-* `LoggingMiddleware` – Logs requests and responses
-* `RetryMiddleware` – Retries failed requests
-* `AuthMiddleware` – Automatically adds Authorization headers
-* `CacheMiddleware` – Caches responses to reduce repeated requests
-
----
-
-## Response Transformation
-
-You can transform the response format before returning it:
-
-```ts
-client.useResponseTransform((data) => {
-  return { ...data, fetchedAt: new Date() };
-});
-```
-
----
-
-## Important Notes
-
-* Always call `client.init()` before using endpoints.
-* Types are automatically inferred from Zod, making inputs and outputs type-safe.
-* Middleware execution order: first added middleware runs last, last added middleware runs first.
-
----
-
-## Full Example
-
-```ts
-import { z } from "zod";
-import { ApiClient, RichError } from "typefetch";
-import { LoggingMiddleware, RetryMiddleware } from "typefetch/middlewares";
-
-const contracts = {
-  post: {
-    getPost: {
-      method: "GET",
-      path: "/posts/:id",
-      auth: true,
-      request: z.object({ id: z.string() }),
-      response: z.object({ id: z.string(), title: z.string() }),
-    },
-  },
-} as const;
-
-const client = new ApiClient(
-  { baseUrl: "https://api.example.com", token: "abc123" },
-  contracts
-);
-
-client.init();
-client.use(LoggingMiddleware);
-client.use(RetryMiddleware, { maxRetries: 2 });
-
-client.onError((err: RichError) => {
-  console.error("Error:", err.message);
-});
-
-(async () => {
-  const post = await client.post.getPost({ id: "1" });
-  console.log(post);
-})();
+# TypeFetch
+
+TypeFetch is a type-safe client for working with APIs, built with TypeScript and Zod. This project allows you to define API contracts and safely use types, while also supporting middlewares, error handling, and response transformation.
+
+---
+
+## Features
+
+* Fully type-safe using TypeScript and Zod
+* Define contracts for modules and endpoints
+* Support for middlewares to add custom behavior before or after requests
+* Error handling with the `RichError` class
+* Ability to transform responses using a response transformer
+* Authentication support via token
+
+---
+
+## Installation
+
+```bash
+npm install typefetch
+# or
+yarn add typefetch
+```
+
+---
+
+## Defining Contracts
+
+Contracts are defined using the `Contracts` and `EndpointDef` types
+
+```ts
+import { z } from "zod";
+
+const contracts = {
+  user: {
+    getUser: {
+      method: "GET",
+      path: "/user/:id",
+      auth: true,
+      request: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+    createUser: {
+      method: "POST",
+      path: "/user",
+      request: z.object({ name: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+  },
+} as const;
+```
+
+---
+
+## Using `ApiClient`
+
+```ts
+import { ApiClient, RichError } from "typefetch";
+
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "your-auth-token",
+  },
+  contracts
+);
+
+client.init();
+
+const user = await client.user.getUser({ id: "123" });
+const newUser = await client.user.createUser({ name: "Taha" });
+```
+
+---
+
+## Error Handling
+
+All errors are provided via the `RichError` class. You can define a custom error handler:
+
+```ts
+client.onError((error: RichError) => {
+  console.error("API Error:", error.message, error.status);
+});
+```
+
+---
+
+## Middlewares
+
+You can add custom behavior before or after requests. Middlewares work similarly to Express:
+
+```ts
+client.use(async (ctx, next, options) => {
+  console.log("Request URL:", ctx.url);
+  const response = await next();
+  console.log("Response status:", response.status);
+  return response;
+});
+```
+
+### Built-in Middlewares
+
+This project provides some built-in middlewares:
+
+```ts
+import {
+  LoggingMiddleware,
+  RetryMiddleware,
+  AuthMiddleware,
+  CacheMiddleware,
+} from "typefetch/middlewares";
+
+client.use(LoggingMiddleware);
+client.use(RetryMiddleware, { maxRetries: 3, delay: 100 });
+client.use(AuthMiddleware, { refreshToken: () => "your-auth-token" });
+client.use(CacheMiddleware, { ttl: 60 * 1000 });
+```
+
+* `LoggingMiddleware` – Logs requests and responses
+* `RetryMiddleware` – Retries failed requests
+* `AuthMiddleware` – Automatically adds Authorization headers
+* `CacheMiddleware` – Caches responses to reduce repeated requests
+
+---
+
+## Response Transformation
+
+You can transform the response format before returning it:
+
+```ts
+client.useResponseTransform((data) => {
+  return { ...data, fetchedAt: new Date() };
+});
+```
+
+---
+
+## Important Notes
+
+* Always call `client.init()` before using endpoints.
+* Types are automatically inferred from Zod, making inputs and outputs type-safe.
+* Middleware execution order: first added middleware runs last, last added middleware runs first.
+
+---
+
+## Full Example
+
+```ts
+import { z } from "zod";
+import { ApiClient, RichError } from "typefetch";
+import { LoggingMiddleware, RetryMiddleware } from "typefetch/middlewares";
+
+const contracts = {
+  post: {
+    getPost: {
+      method: "GET",
+      path: "/posts/:id",
+      auth: true,
+      request: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), title: z.string() }),
+    },
+  },
+} as const;
+
+const client = new ApiClient(
+  { baseUrl: "https://api.example.com", token: "abc123" },
+  contracts
+);
+
+client.init();
+client.use(LoggingMiddleware);
+client.use(RetryMiddleware, { maxRetries: 2 });
+
+client.onError((err: RichError) => {
+  console.error("Error:", err.message);
+});
+
+(async () => {
+  const post = await client.post.getPost({ id: "1" });
+  console.log(post);
+})();
 ```

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/client.test.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const client_1 = require("../client");
+// Mock fetch globally
+global.fetch = jest.fn();
+const contracts = {
+    user: {
+        getUser: {
+            method: "GET",
+            path: "/user",
+            request: zod_1.z.object({ id: zod_1.z.string() }),
+            response: zod_1.z.object({ id: zod_1.z.string(), name: zod_1.z.string() }),
+        },
+        createUser: {
+            method: "POST",
+            path: "/user",
+            auth: true,
+            request: zod_1.z.object({ name: zod_1.z.string() }),
+            response: zod_1.z.object({ id: zod_1.z.string(), name: zod_1.z.string() }),
+        },
+    },
+};
+describe("ApiClient", () => {
+    let client;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        client = new client_1.ApiClient({ baseUrl: "https://api.test.com" }, contracts);
+        client.init();
+    });
+    it("should initialize modules correctly", () => {
+        expect(client.modules.user).toBeDefined();
+        expect(typeof client.modules.user.getUser).toBe("function");
+    });
+    it("should call fetch with correct URL and headers", async () => {
+        fetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ id: "1", name: "John" }),
+        });
+        const res = await client.modules.user.getUser({ id: "1" });
+        expect(fetch).toHaveBeenCalledWith("https://api.test.com/user", {
+            method: "GET",
+            headers: { "Content-Type": "application/json" },
+            body: undefined,
+        });
+        expect(res).toEqual({ id: "1", name: "John" });
+    });
+    it("should throw validation error if input is invalid", async () => {
+        await expect(client.modules.user.getUser({}))
+            .rejects.toBeInstanceOf(zod_1.ZodError);
+    });
+    it("should handle auth header when token is provided", async () => {
+        const authedClient = new client_1.ApiClient({ baseUrl: "https://api.test.com", token: "mytoken" }, contracts);
+        authedClient.init();
+        fetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ id: "2", name: "Alice" }),
+        });
+        await authedClient.modules.user.createUser({ name: "Alice" });
+        expect(fetch).toHaveBeenCalledWith("https://api.test.com/user", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "Bearer mytoken",
+            },
+            body: JSON.stringify({ name: "Alice" }),
+        });
+    });
+    it("should throw error if auth required and no token provided", async () => {
+        await expect(client.modules.user.createUser({ name: "Alice" })).rejects.toThrow(client_1.RichError);
+    });
+    it("should call errorHandler when error occurs", async () => {
+        const handler = jest.fn();
+        client.onError(handler);
+        fetch.mockResolvedValueOnce({
+            ok: false,
+            status: 400,
+            statusText: "Bad Request",
+            json: async () => ({ message: "Invalid input" }),
+        });
+        await expect(client.modules.user.getUser({ id: "bad" })).rejects.toThrow();
+        expect(handler).toHaveBeenCalled();
+    });
+    it("should apply responseTransform", async () => {
+        client.useResponseTransform((data) => ({ ...data, transformed: true }));
+        fetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ id: "1", name: "John" }),
+        });
+        const res = await client.modules.user.getUser({ id: "1" });
+        expect(res).toEqual({ id: "1", name: "John", transformed: true });
+    });
+    it("should execute middleware in order", async () => {
+        const logs = [];
+        client.use(async (ctx, next) => {
+            logs.push("before");
+            const res = await next();
+            logs.push("after");
+            return res;
+        });
+        fetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ id: "1", name: "John" }),
+        });
+        await client.modules.user.getUser({ id: "1" });
+        expect(logs).toEqual(["before", "after"]);
+    });
+});

package/dist/__tests__/middlewares.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/middlewares.test.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const auth_1 = require("../middlewares/auth");
+const cache_1 = require("../middlewares/cache");
+const logging_1 = require("../middlewares/logging");
+const retry_1 = require("../middlewares/retry");
+describe("middlewares", () => {
+    const mockCtx = (url = "/test", method = "GET") => ({
+        url,
+        init: { method, headers: {} },
+    });
+    const mockNext = (response = { ok: true, status: 200 }) => jest.fn().mockResolvedValue(new Response(JSON.stringify(response)));
+    // ---------------- AUTH ----------------
+    it("authMiddleware should add refreshed token", async () => {
+        const ctx = mockCtx();
+        const next = mockNext();
+        await (0, auth_1.authMiddleware)(ctx, next, {
+            refreshToken: async () => "NEW_TOKEN",
+        });
+        expect(ctx.init.headers["Authorization"]).toBe("Bearer NEW_TOKEN");
+        expect(next).toHaveBeenCalled();
+    });
+    it("authMiddleware should skip if no refreshToken provided", async () => {
+        const ctx = mockCtx();
+        const next = mockNext();
+        await (0, auth_1.authMiddleware)(ctx, next, {});
+        expect(ctx.init.headers["Authorization"]).toBeUndefined();
+        expect(next).toHaveBeenCalled();
+    });
+    // ---------------- CACHE ----------------
+    it("cacheMiddleware should cache GET responses", async () => {
+        const ctx = mockCtx("/users", "GET");
+        const next = mockNext({ users: [1, 2, 3] });
+        const middleware = (0, cache_1.cacheMiddleware)({ ttl: 1000 });
+        const res1 = await middleware(ctx, next);
+        const res2 = await middleware(ctx, next);
+        expect(next).toHaveBeenCalledTimes(1); // only first time
+        const data2 = await res2.json();
+        expect(data2.users).toEqual([1, 2, 3]);
+    });
+    it("cacheMiddleware should bypass cache for non-GET requests", async () => {
+        const ctx = mockCtx("/users", "POST");
+        const next = mockNext({ ok: true });
+        const middleware = (0, cache_1.cacheMiddleware)();
+        await middleware(ctx, next);
+        expect(next).toHaveBeenCalledTimes(1);
+    });
+    // ---------------- LOGGING ----------------
+    it("loggingMiddleware should log request and response", async () => {
+        const ctx = mockCtx();
+        const next = mockNext();
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        await (0, logging_1.loggingMiddleware)(ctx, next, {
+            logRequest: true,
+            logResponse: true,
+            debug: true,
+        });
+        expect(logSpy).toHaveBeenCalledWith("➡️ Request:", ctx.url, ctx.init);
+        expect(logSpy).toHaveBeenCalledWith("⬅️ Response:", 200);
+        logSpy.mockRestore();
+    });
+    // ---------------- RETRY ----------------
+    it("retryMiddleware should retry failed requests", async () => {
+        const ctx = mockCtx();
+        let attempt = 0;
+        const next = jest.fn().mockImplementation(() => {
+            attempt++;
+            if (attempt < 2)
+                throw new Error("fail");
+            return Promise.resolve(new Response(JSON.stringify({ ok: true })));
+        });
+        const middleware = (0, retry_1.retryMiddleware)({ maxRetries: 3, delay: 10 });
+        const res = await middleware(ctx, next);
+        const json = await res.json();
+        expect(json.ok).toBe(true);
+        expect(next).toHaveBeenCalledTimes(2);
+    });
+    it("retryMiddleware should throw after exceeding maxRetries", async () => {
+        const ctx = mockCtx();
+        const next = jest.fn().mockRejectedValue(new Error("fail always"));
+        const middleware = (0, retry_1.retryMiddleware)({ maxRetries: 2, delay: 10 });
+        await expect(middleware(ctx, next)).rejects.toThrow("fail always");
+        expect(next).toHaveBeenCalledTimes(3); // initial + 2 retries
+    });
+});

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { Contracts, Middleware, ErrorLike, EndpointMethods } from "./types";
+export declare class RichError extends Error implements ErrorLike {
+    status?: number;
+    code?: string;
+    title?: string;
+    detail?: string;
+    errors?: Record<string, string[]>;
+    constructor(error: Partial<ErrorLike> & {
+        message: string;
+    });
+}
+export declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
+    private config;
+    private contracts;
+    private middlewares;
+    private errorHandler?;
+    private responseTransform;
+    private _modules;
+    constructor(config: {
+        baseUrl: string;
+        token?: string;
+    }, contracts: C);
+    init(): void;
+    get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
+    use<T>(middleware: Middleware<T>, options?: T): void;
+    onError(handler: (error: E) => void): void;
+    useResponseTransform(fn: (data: any) => any): void;
+    private request;
+    private createError;
+    private normalizeError;
+}