@typokit/client 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import type { HttpMethod, RouteContract } from "@typokit/types";
+import { AppError } from "@typokit/errors";
+/** Extract param names from a path pattern like "/users/:id/posts/:postId" */
+type ExtractParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof ExtractParams<Rest>]: string;
+} : T extends `${string}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<string, never>;
+/** A single route definition binding a method + path to a contract */
+export interface RouteDefinition<TMethod extends HttpMethod = HttpMethod, TContract extends RouteContract = RouteContract> {
+    method: TMethod;
+    contract: TContract;
+}
+/** Map of path patterns to their route definitions per method */
+export type RouteMap = Record<string, Partial<Record<HttpMethod, RouteContract<any, any, any, any>>>>;
+/** Interceptor function that can modify the request before it is sent */
+export type RequestInterceptor = (request: RequestInit & {
+    url: string;
+}) => (RequestInit & {
+    url: string;
+}) | Promise<RequestInit & {
+    url: string;
+}>;
+/** Options for creating a client */
+export interface ClientOptions {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    interceptors?: RequestInterceptor[];
+}
+/** Options for individual requests */
+export interface RequestOptions<TQuery = void, TBody = void> {
+    params?: Record<string, string>;
+    query?: TQuery extends void ? never : TQuery;
+    body?: TBody extends void ? never : TBody;
+    headers?: Record<string, string>;
+}
+/** Error thrown when an API call returns a non-OK status */
+export declare class ClientError extends AppError {
+    readonly response: {
+        status: number;
+        body: unknown;
+    };
+    constructor(response: {
+        status: number;
+        body: unknown;
+    });
+}
+/** Extract routes of a given method from a RouteMap */
+type RoutesForMethod<TRoutes extends RouteMap, M extends HttpMethod> = {
+    [P in keyof TRoutes]: M extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] & string;
+/** Get the contract type for a path + method */
+type ContractFor<TRoutes extends RouteMap, P extends string, M extends HttpMethod> = P extends keyof TRoutes ? M extends keyof TRoutes[P] ? TRoutes[P][M] extends RouteContract<any, any, any, any> ? TRoutes[P][M] : never : never : never;
+/** Build the options type for a given contract + path */
+type MethodRequestOptions<TContract extends RouteContract<any, any, any, any>, _TPath extends string> = TContract extends RouteContract<infer TParams, infer TQuery, infer TBody, infer _TResponse> ? TParams extends void ? TQuery extends void ? TBody extends void ? {
+    headers?: Record<string, string>;
+} | undefined : {
+    body: TBody;
+    headers?: Record<string, string>;
+} : TBody extends void ? {
+    query: TQuery;
+    headers?: Record<string, string>;
+} : {
+    query: TQuery;
+    body: TBody;
+    headers?: Record<string, string>;
+} : TQuery extends void ? TBody extends void ? {
+    params: TParams & Record<string, string>;
+    headers?: Record<string, string>;
+} : {
+    params: TParams & Record<string, string>;
+    body: TBody;
+    headers?: Record<string, string>;
+} : TBody extends void ? {
+    params: TParams & Record<string, string>;
+    query: TQuery;
+    headers?: Record<string, string>;
+} : {
+    params: TParams & Record<string, string>;
+    query: TQuery;
+    body: TBody;
+    headers?: Record<string, string>;
+} : never;
+/** Extract the response type from a contract */
+type ResponseFor<TContract extends RouteContract<any, any, any, any>> = TContract extends RouteContract<infer _P, infer _Q, infer _B, infer TResponse> ? TResponse : never;
+/** Type-safe API client */
+export interface TypeSafeClient<TRoutes extends RouteMap> {
+    get<P extends RoutesForMethod<TRoutes, "GET">>(path: P, options?: MethodRequestOptions<ContractFor<TRoutes, P, "GET">, P>): Promise<ResponseFor<ContractFor<TRoutes, P, "GET">>>;
+    post<P extends RoutesForMethod<TRoutes, "POST">>(path: P, options?: MethodRequestOptions<ContractFor<TRoutes, P, "POST">, P>): Promise<ResponseFor<ContractFor<TRoutes, P, "POST">>>;
+    put<P extends RoutesForMethod<TRoutes, "PUT">>(path: P, options?: MethodRequestOptions<ContractFor<TRoutes, P, "PUT">, P>): Promise<ResponseFor<ContractFor<TRoutes, P, "PUT">>>;
+    patch<P extends RoutesForMethod<TRoutes, "PATCH">>(path: P, options?: MethodRequestOptions<ContractFor<TRoutes, P, "PATCH">, P>): Promise<ResponseFor<ContractFor<TRoutes, P, "PATCH">>>;
+    delete<P extends RoutesForMethod<TRoutes, "DELETE">>(path: P, options?: MethodRequestOptions<ContractFor<TRoutes, P, "DELETE">, P>): Promise<ResponseFor<ContractFor<TRoutes, P, "DELETE">>>;
+}
+/**
+ * Create a type-safe API client.
+ *
+ * @example
+ * ```ts
+ * type MyRoutes = {
+ *   "/users": { GET: RouteContract<void, { page?: number }, void, User[]> };
+ *   "/users/:id": { GET: RouteContract<{ id: string }, void, void, User> };
+ * };
+ * const client = createClient<MyRoutes>({ baseUrl: "http://localhost:3000" });
+ * const users = await client.get("/users", { query: { page: 1 } });
+ * ```
+ */
+export declare function createClient<TRoutes extends RouteMap>(options: ClientOptions): TypeSafeClient<TRoutes>;
+export type { ExtractParams };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,114 @@
+// @typokit/client — Type-Safe Fetch Client
+import { AppError, createAppError } from "@typokit/errors";
+// ─── Client Error ───────────────────────────────────────────
+/** Error thrown when an API call returns a non-OK status */
+export class ClientError extends AppError {
+    response;
+    constructor(response) {
+        super("CLIENT_ERROR", response.status, `Request failed with status ${response.status}`);
+        this.response = response;
+        this.name = "ClientError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ─── Implementation ─────────────────────────────────────────
+/** Substitute path parameters into a URL pattern */
+function buildUrl(baseUrl, path, params, query) {
+    let resolvedPath = path;
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+        }
+    }
+    const url = new URL(resolvedPath, baseUrl);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null) {
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        url.searchParams.append(key, String(item));
+                    }
+                }
+                else {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+    }
+    return url.toString();
+}
+/** Apply interceptors sequentially */
+async function applyInterceptors(request, interceptors) {
+    let current = request;
+    for (const interceptor of interceptors) {
+        current = await interceptor(current);
+    }
+    return current;
+}
+/** Parse response body, throwing a typed error on non-OK status */
+async function handleResponse(response) {
+    let body;
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        body = await response.json();
+    }
+    else {
+        body = await response.text();
+    }
+    if (!response.ok) {
+        // Try to parse as ErrorResponse and throw a typed error
+        if (body &&
+            typeof body === "object" &&
+            "error" in body &&
+            typeof body.error === "object") {
+            const errBody = body.error;
+            throw createAppError(response.status, errBody.code ?? "UNKNOWN_ERROR", errBody.message ?? `Request failed with status ${response.status}`, errBody.details);
+        }
+        throw new ClientError({ status: response.status, body });
+    }
+    return body;
+}
+/**
+ * Create a type-safe API client.
+ *
+ * @example
+ * ```ts
+ * type MyRoutes = {
+ *   "/users": { GET: RouteContract<void, { page?: number }, void, User[]> };
+ *   "/users/:id": { GET: RouteContract<{ id: string }, void, void, User> };
+ * };
+ * const client = createClient<MyRoutes>({ baseUrl: "http://localhost:3000" });
+ * const users = await client.get("/users", { query: { page: 1 } });
+ * ```
+ */
+export function createClient(options) {
+    const { baseUrl, headers: defaultHeaders = {}, interceptors = [] } = options;
+    async function request(method, path, opts) {
+        const url = buildUrl(baseUrl, path, opts?.params, opts?.query);
+        const requestHeaders = {
+            ...defaultHeaders,
+            ...(opts?.headers ?? {}),
+        };
+        if (opts?.body !== undefined) {
+            requestHeaders["content-type"] = "application/json";
+        }
+        let requestInit = {
+            url,
+            method,
+            headers: requestHeaders,
+            ...(opts?.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+        };
+        requestInit = await applyInterceptors(requestInit, interceptors);
+        const { url: finalUrl, ...fetchOpts } = requestInit;
+        const response = await fetch(finalUrl, fetchOpts);
+        return handleResponse(response);
+    }
+    return {
+        get: (path, opts) => request("GET", path, opts),
+        post: (path, opts) => request("POST", path, opts),
+        put: (path, opts) => request("PUT", path, opts),
+        patch: (path, opts) => request("PATCH", path, opts),
+        delete: (path, opts) => request("DELETE", path, opts),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@typokit/client",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "version": "0.1.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@typokit/errors": "0.1.4",
+    "@typokit/types": "0.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyleBastien/typokit",
+    "directory": "packages/client"
+  },
+  "scripts": {
+    "test": "rstest run --passWithNoTests"
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,40 @@
+// Ambient type declarations for fetch API (available in Node 18+, Bun, Deno, browsers)
+// We don't add DOM lib or @types/node to keep the package platform-agnostic.
+
+declare class Headers {
+  constructor(init?: Record<string, string>);
+  get(name: string): string | null;
+  set(name: string, value: string): void;
+  has(name: string): boolean;
+  delete(name: string): void;
+  forEach(callback: (value: string, key: string) => void): void;
+}
+
+declare class URL {
+  constructor(url: string, base?: string);
+  readonly searchParams: URLSearchParams;
+  toString(): string;
+}
+
+declare class URLSearchParams {
+  set(name: string, value: string): void;
+  append(name: string, value: string): void;
+  get(name: string): string | null;
+  toString(): string;
+}
+
+interface RequestInit {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+interface ResponseLike {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly headers: Headers;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+declare function fetch(url: string, init?: RequestInit): Promise<ResponseLike>;

package/src/index.test.ts

@@ -0,0 +1,313 @@
+// @typokit/client — Unit Tests
+
+import { describe, it, expect } from "@rstest/core";
+import { createClient, ClientError } from "./index.js";
+import type { ExtractParams, RequestInterceptor } from "./index.js";
+import type { RouteContract } from "@typokit/types";
+import { AppError } from "@typokit/errors";
+
+// ─── Type-level Tests ───────────────────────────────────────
+
+// Verify ExtractParams infers correctly at the type level
+type _AssertSingle =
+  ExtractParams<"/users/:id"> extends { id: string } ? true : never;
+const _testSingle: _AssertSingle = true;
+
+type _AssertMulti =
+  ExtractParams<"/users/:id/posts/:postId"> extends {
+    id: string;
+    postId: string;
+  }
+    ? true
+    : never;
+const _testMulti: _AssertMulti = true;
+
+type _AssertNone =
+  ExtractParams<"/users"> extends Record<string, never> ? true : never;
+const _testNone: _AssertNone = true;
+
+// Suppress unused variable warnings
+void _testSingle;
+void _testMulti;
+void _testNone;
+
+// ─── Test Route Map ─────────────────────────────────────────
+
+interface User {
+  id: string;
+  name: string;
+}
+
+type TestRoutes = {
+  "/users": {
+    GET: RouteContract<void, { page?: number }, void, User[]>;
+    POST: RouteContract<void, void, { name: string }, User>;
+  };
+  "/users/:id": {
+    GET: RouteContract<{ id: string }, void, void, User>;
+    PUT: RouteContract<{ id: string }, void, { name: string }, User>;
+    DELETE: RouteContract<{ id: string }, void, void, void>;
+  };
+};
+
+// ─── Fetch Spy ──────────────────────────────────────────────
+
+interface FetchCall {
+  url: string;
+  init?: { method?: string; headers?: Record<string, string>; body?: string };
+}
+
+let fetchCalls: FetchCall[] = [];
+
+function mockFetch(response: {
+  status: number;
+  body: unknown;
+  headers?: Record<string, string>;
+}): void {
+  fetchCalls = [];
+  const headerEntries = {
+    "content-type": "application/json",
+    ...(response.headers ?? {}),
+  };
+  (globalThis as Record<string, unknown>).fetch = (
+    url: string,
+    init?: RequestInit,
+  ) => {
+    fetchCalls.push({ url, init: init as FetchCall["init"] });
+    return Promise.resolve({
+      ok: response.status >= 200 && response.status < 300,
+      status: response.status,
+      headers: {
+        get: (name: string) =>
+          (headerEntries as Record<string, string>)[name.toLowerCase()] ?? null,
+      },
+      json: () => Promise.resolve(response.body),
+      text: () => Promise.resolve(JSON.stringify(response.body)),
+    });
+  };
+}
+
+// ─── Tests ──────────────────────────────────────────────────
+
+describe("createClient", () => {
+  it("should create a client with all HTTP methods", () => {
+    mockFetch({ status: 200, body: [] });
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+
+    expect(typeof client.get).toBe("function");
+    expect(typeof client.post).toBe("function");
+    expect(typeof client.put).toBe("function");
+    expect(typeof client.patch).toBe("function");
+    expect(typeof client.delete).toBe("function");
+  });
+
+  it("should make a GET request with correct URL", async () => {
+    const users: User[] = [{ id: "1", name: "Alice" }];
+    mockFetch({ status: 200, body: users });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    const result = await client.get("/users");
+
+    expect(result).toEqual(users);
+    expect(fetchCalls.length).toBe(1);
+    expect(fetchCalls[0].url).toBe("http://localhost:3000/users");
+    expect(fetchCalls[0].init?.method).toBe("GET");
+  });
+
+  it("should substitute path parameters", async () => {
+    const user: User = { id: "42", name: "Bob" };
+    mockFetch({ status: 200, body: user });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    const result = await client.get("/users/:id", { params: { id: "42" } });
+
+    expect(result).toEqual(user);
+    expect(fetchCalls[0].url).toBe("http://localhost:3000/users/42");
+    expect(fetchCalls[0].init?.method).toBe("GET");
+  });
+
+  it("should append query parameters", async () => {
+    mockFetch({ status: 200, body: [] });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    await client.get("/users", { query: { page: 2 } });
+
+    expect(fetchCalls[0].url).toBe("http://localhost:3000/users?page=2");
+  });
+
+  it("should send JSON body for POST requests", async () => {
+    const newUser: User = { id: "3", name: "Charlie" };
+    mockFetch({ status: 201, body: newUser });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    const result = await client.post("/users", { body: { name: "Charlie" } });
+
+    expect(result).toEqual(newUser);
+    expect(fetchCalls[0].init?.method).toBe("POST");
+    expect(fetchCalls[0].init?.body).toBe(JSON.stringify({ name: "Charlie" }));
+    expect(fetchCalls[0].init?.headers?.["content-type"]).toBe(
+      "application/json",
+    );
+  });
+
+  it("should send JSON body for PUT requests", async () => {
+    const updated: User = { id: "42", name: "Updated" };
+    mockFetch({ status: 200, body: updated });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    const result = await client.put("/users/:id", {
+      params: { id: "42" },
+      body: { name: "Updated" },
+    });
+
+    expect(result).toEqual(updated);
+    expect(fetchCalls[0].url).toBe("http://localhost:3000/users/42");
+    expect(fetchCalls[0].init?.method).toBe("PUT");
+  });
+
+  it("should make DELETE requests", async () => {
+    mockFetch({ status: 200, body: null });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+    await client.delete("/users/:id", { params: { id: "42" } });
+
+    expect(fetchCalls[0].url).toBe("http://localhost:3000/users/42");
+    expect(fetchCalls[0].init?.method).toBe("DELETE");
+  });
+
+  it("should include default headers", async () => {
+    mockFetch({ status: 200, body: [] });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+      headers: { "x-api-key": "secret123" },
+    });
+    await client.get("/users");
+
+    expect(fetchCalls[0].init?.headers?.["x-api-key"]).toBe("secret123");
+  });
+
+  it("should merge request-level headers with defaults", async () => {
+    mockFetch({ status: 200, body: [] });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+      headers: { "x-api-key": "secret123" },
+    });
+    await client.get("/users", {
+      query: {},
+      headers: { "x-request-id": "req-1" },
+    });
+
+    expect(fetchCalls[0].init?.headers?.["x-api-key"]).toBe("secret123");
+    expect(fetchCalls[0].init?.headers?.["x-request-id"]).toBe("req-1");
+  });
+});
+
+describe("error handling", () => {
+  it("should throw AppError subclass for error responses with ErrorResponse body", async () => {
+    mockFetch({
+      status: 404,
+      body: { error: { code: "NOT_FOUND", message: "User not found" } },
+    });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+
+    let caught: unknown;
+    try {
+      await client.get("/users/:id", { params: { id: "999" } });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(AppError);
+    expect((caught as AppError).status).toBe(404);
+    expect((caught as AppError).code).toBe("NOT_FOUND");
+  });
+
+  it("should throw ClientError for non-OK responses without ErrorResponse body", async () => {
+    mockFetch({
+      status: 500,
+      body: "Internal Server Error",
+      headers: { "content-type": "text/plain" },
+    });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+    });
+
+    let caught: unknown;
+    try {
+      await client.get("/users");
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(ClientError);
+    expect((caught as ClientError).status).toBe(500);
+  });
+});
+
+describe("interceptors", () => {
+  it("should apply request interceptors in order", async () => {
+    mockFetch({ status: 200, body: [] });
+
+    const interceptor1: RequestInterceptor = (req) => ({
+      ...req,
+      headers: { ...(req.headers as Record<string, string>), "x-first": "1" },
+    });
+
+    const interceptor2: RequestInterceptor = (req) => ({
+      ...req,
+      headers: { ...(req.headers as Record<string, string>), "x-second": "2" },
+    });
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+      interceptors: [interceptor1, interceptor2],
+    });
+    await client.get("/users");
+
+    expect(fetchCalls[0].init?.headers?.["x-first"]).toBe("1");
+    expect(fetchCalls[0].init?.headers?.["x-second"]).toBe("2");
+  });
+
+  it("should support async interceptors", async () => {
+    mockFetch({ status: 200, body: [] });
+
+    const asyncInterceptor: RequestInterceptor = async (req) => {
+      await Promise.resolve();
+      return {
+        ...req,
+        headers: {
+          ...(req.headers as Record<string, string>),
+          authorization: "Bearer token123",
+        },
+      };
+    };
+
+    const client = createClient<TestRoutes>({
+      baseUrl: "http://localhost:3000",
+      interceptors: [asyncInterceptor],
+    });
+    await client.get("/users");
+
+    expect(fetchCalls[0].init?.headers?.authorization).toBe("Bearer token123");
+  });
+});

package/src/index.ts

@@ -0,0 +1,328 @@
+// @typokit/client — Type-Safe Fetch Client
+
+import type { HttpMethod, RouteContract } from "@typokit/types";
+import { AppError, createAppError } from "@typokit/errors";
+
+// ─── Path Parameter Extraction ──────────────────────────────
+
+/** Extract param names from a path pattern like "/users/:id/posts/:postId" */
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? { [K in Param | keyof ExtractParams<Rest>]: string }
+    : T extends `${string}:${infer Param}`
+      ? { [K in Param]: string }
+      : Record<string, never>;
+
+// ─── Route Definition Types ─────────────────────────────────
+
+/** A single route definition binding a method + path to a contract */
+export interface RouteDefinition<
+  TMethod extends HttpMethod = HttpMethod,
+  TContract extends RouteContract = RouteContract,
+> {
+  method: TMethod;
+  contract: TContract;
+}
+
+/** Map of path patterns to their route definitions per method */
+export type RouteMap = Record<
+  string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- intentional: generic route map accepts any contract shape
+  Partial<Record<HttpMethod, RouteContract<any, any, any, any>>>
+>;
+
+// ─── Client Options ─────────────────────────────────────────
+
+/** Interceptor function that can modify the request before it is sent */
+export type RequestInterceptor = (
+  request: RequestInit & { url: string },
+) => (RequestInit & { url: string }) | Promise<RequestInit & { url: string }>;
+
+/** Options for creating a client */
+export interface ClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+  interceptors?: RequestInterceptor[];
+}
+
+/** Options for individual requests */
+export interface RequestOptions<TQuery = void, TBody = void> {
+  params?: Record<string, string>;
+  query?: TQuery extends void ? never : TQuery;
+  body?: TBody extends void ? never : TBody;
+  headers?: Record<string, string>;
+}
+
+// ─── Client Error ───────────────────────────────────────────
+
+/** Error thrown when an API call returns a non-OK status */
+export class ClientError extends AppError {
+  constructor(public readonly response: { status: number; body: unknown }) {
+    super(
+      "CLIENT_ERROR",
+      response.status,
+      `Request failed with status ${response.status}`,
+    );
+    this.name = "ClientError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// ─── Type-Level Helpers ─────────────────────────────────────
+
+/** Extract routes of a given method from a RouteMap */
+type RoutesForMethod<TRoutes extends RouteMap, M extends HttpMethod> = {
+  [P in keyof TRoutes]: M extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] &
+  string;
+
+/** Get the contract type for a path + method */
+type ContractFor<
+  TRoutes extends RouteMap,
+  P extends string,
+  M extends HttpMethod,
+> = P extends keyof TRoutes
+  ? M extends keyof TRoutes[P]
+    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      TRoutes[P][M] extends RouteContract<any, any, any, any>
+      ? TRoutes[P][M]
+      : never
+    : never
+  : never;
+
+/** Build the options type for a given contract + path */
+type MethodRequestOptions<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TContract extends RouteContract<any, any, any, any>,
+  _TPath extends string,
+> =
+  TContract extends RouteContract<
+    infer TParams,
+    infer TQuery,
+    infer TBody,
+    infer _TResponse
+  >
+    ? TParams extends void
+      ? TQuery extends void
+        ? TBody extends void
+          ? { headers?: Record<string, string> } | undefined
+          : { body: TBody; headers?: Record<string, string> }
+        : TBody extends void
+          ? { query: TQuery; headers?: Record<string, string> }
+          : { query: TQuery; body: TBody; headers?: Record<string, string> }
+      : TQuery extends void
+        ? TBody extends void
+          ? {
+              params: TParams & Record<string, string>;
+              headers?: Record<string, string>;
+            }
+          : {
+              params: TParams & Record<string, string>;
+              body: TBody;
+              headers?: Record<string, string>;
+            }
+        : TBody extends void
+          ? {
+              params: TParams & Record<string, string>;
+              query: TQuery;
+              headers?: Record<string, string>;
+            }
+          : {
+              params: TParams & Record<string, string>;
+              query: TQuery;
+              body: TBody;
+              headers?: Record<string, string>;
+            }
+    : never;
+
+/** Extract the response type from a contract */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ResponseFor<TContract extends RouteContract<any, any, any, any>> =
+  TContract extends RouteContract<infer _P, infer _Q, infer _B, infer TResponse>
+    ? TResponse
+    : never;
+
+// ─── Client Interface ───────────────────────────────────────
+
+/** Type-safe API client */
+export interface TypeSafeClient<TRoutes extends RouteMap> {
+  get<P extends RoutesForMethod<TRoutes, "GET">>(
+    path: P,
+    options?: MethodRequestOptions<ContractFor<TRoutes, P, "GET">, P>,
+  ): Promise<ResponseFor<ContractFor<TRoutes, P, "GET">>>;
+
+  post<P extends RoutesForMethod<TRoutes, "POST">>(
+    path: P,
+    options?: MethodRequestOptions<ContractFor<TRoutes, P, "POST">, P>,
+  ): Promise<ResponseFor<ContractFor<TRoutes, P, "POST">>>;
+
+  put<P extends RoutesForMethod<TRoutes, "PUT">>(
+    path: P,
+    options?: MethodRequestOptions<ContractFor<TRoutes, P, "PUT">, P>,
+  ): Promise<ResponseFor<ContractFor<TRoutes, P, "PUT">>>;
+
+  patch<P extends RoutesForMethod<TRoutes, "PATCH">>(
+    path: P,
+    options?: MethodRequestOptions<ContractFor<TRoutes, P, "PATCH">, P>,
+  ): Promise<ResponseFor<ContractFor<TRoutes, P, "PATCH">>>;
+
+  delete<P extends RoutesForMethod<TRoutes, "DELETE">>(
+    path: P,
+    options?: MethodRequestOptions<ContractFor<TRoutes, P, "DELETE">, P>,
+  ): Promise<ResponseFor<ContractFor<TRoutes, P, "DELETE">>>;
+}
+
+// ─── Implementation ─────────────────────────────────────────
+
+/** Substitute path parameters into a URL pattern */
+function buildUrl(
+  baseUrl: string,
+  path: string,
+  params?: Record<string, string>,
+  query?: Record<string, unknown>,
+): string {
+  let resolvedPath = path;
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+    }
+  }
+
+  const url = new URL(resolvedPath, baseUrl);
+
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) {
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            url.searchParams.append(key, String(item));
+          }
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+  }
+
+  return url.toString();
+}
+
+/** Apply interceptors sequentially */
+async function applyInterceptors(
+  request: RequestInit & { url: string },
+  interceptors: RequestInterceptor[],
+): Promise<RequestInit & { url: string }> {
+  let current = request;
+  for (const interceptor of interceptors) {
+    current = await interceptor(current);
+  }
+  return current;
+}
+
+/** Parse response body, throwing a typed error on non-OK status */
+async function handleResponse<T>(response: ResponseLike): Promise<T> {
+  let body: unknown;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    body = await response.json();
+  } else {
+    body = await response.text();
+  }
+
+  if (!response.ok) {
+    // Try to parse as ErrorResponse and throw a typed error
+    if (
+      body &&
+      typeof body === "object" &&
+      "error" in body &&
+      typeof (body as Record<string, unknown>).error === "object"
+    ) {
+      const errBody = (
+        body as {
+          error: {
+            code?: string;
+            message?: string;
+            details?: Record<string, unknown>;
+          };
+        }
+      ).error;
+      throw createAppError(
+        response.status,
+        errBody.code ?? "UNKNOWN_ERROR",
+        errBody.message ?? `Request failed with status ${response.status}`,
+        errBody.details,
+      );
+    }
+    throw new ClientError({ status: response.status, body });
+  }
+
+  return body as T;
+}
+
+/**
+ * Create a type-safe API client.
+ *
+ * @example
+ * ```ts
+ * type MyRoutes = {
+ *   "/users": { GET: RouteContract<void, { page?: number }, void, User[]> };
+ *   "/users/:id": { GET: RouteContract<{ id: string }, void, void, User> };
+ * };
+ * const client = createClient<MyRoutes>({ baseUrl: "http://localhost:3000" });
+ * const users = await client.get("/users", { query: { page: 1 } });
+ * ```
+ */
+export function createClient<TRoutes extends RouteMap>(
+  options: ClientOptions,
+): TypeSafeClient<TRoutes> {
+  const { baseUrl, headers: defaultHeaders = {}, interceptors = [] } = options;
+
+  async function request<T>(
+    method: HttpMethod,
+    path: string,
+    opts?: {
+      params?: Record<string, string>;
+      query?: Record<string, unknown>;
+      body?: unknown;
+      headers?: Record<string, string>;
+    },
+  ): Promise<T> {
+    const url = buildUrl(baseUrl, path, opts?.params, opts?.query);
+
+    const requestHeaders: Record<string, string> = {
+      ...defaultHeaders,
+      ...(opts?.headers ?? {}),
+    };
+
+    if (opts?.body !== undefined) {
+      requestHeaders["content-type"] = "application/json";
+    }
+
+    let requestInit: RequestInit & { url: string } = {
+      url,
+      method,
+      headers: requestHeaders,
+      ...(opts?.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+    };
+
+    requestInit = await applyInterceptors(requestInit, interceptors);
+
+    const { url: finalUrl, ...fetchOpts } = requestInit;
+    const response = await fetch(finalUrl, fetchOpts);
+
+    return handleResponse<T>(response);
+  }
+
+  return {
+    get: (path, opts) => request("GET", path, opts as Record<string, unknown>),
+    post: (path, opts) =>
+      request("POST", path, opts as Record<string, unknown>),
+    put: (path, opts) => request("PUT", path, opts as Record<string, unknown>),
+    patch: (path, opts) =>
+      request("PATCH", path, opts as Record<string, unknown>),
+    delete: (path, opts) =>
+      request("DELETE", path, opts as Record<string, unknown>),
+  } as TypeSafeClient<TRoutes>;
+}
+
+export type { ExtractParams };