Defining API Contracts

A TypeFetch contract is a grouped object of modules and endpoints.

const contracts = {
  user: {
    getUser: {
      method: "GET",
      path: "/users/:id",
      request: z.object({
        path: z.object({
          id: z.string(),
        }),
      }),
      response: z.object({
        id: z.string(),
        name: z.string(),
      }),
    },

    createUser: {
      method: "POST",
      path: "/users",
      request: z.object({
        body: z.object({
          name: z.string(),
          email: z.string().email(),
        }),
      }),
      response: z.object({
        id: z.string(),
        name: z.string(),
        email: z.string(),
      }),
    },
  },
} as const;

After calling client.init(), TypeFetch generates typed methods:

await api.user.getUser({
  path: { id: "123" },
});

await api.user.createUser({
  body: {
    name: "Taha",
    email: "taha@example.com",
  },
});

Structured Request Model

The recommended request shape is:

z.object({
  path: z.object({}).optional(),
  query: z.object({}).optional(),
  body: z.any().optional(),
  headers: z.record(z.string(), z.string()).optional(),
});

Each section has a specific purpose.

Key	Purpose
`path`	Replaces path parameters like `/users/:id`
`query`	Builds the query string
`body`	Sent as the JSON or `form-data` body
`headers`	Per-request headers

Example:

const contracts = {
  user: {
    updateUser: {
      method: "PATCH",
      path: "/users/:id",
      request: z.object({
        path: z.object({
          id: z.string(),
        }),
        query: z.object({
          notify: z.boolean().optional(),
        }).optional(),
        body: z.object({
          name: z.string(),
        }),
        headers: z.record(z.string(), z.string()).optional(),
      }),
      response: z.object({
        id: z.string(),
        name: z.string(),
      }),
    },
  },
} as const;

Usage:

await api.user.updateUser({
  path: { id: "123" },
  query: { notify: true },
  headers: {
    "X-Tenant": "main",
  },
  body: {
    name: "Taha",
  },
});

TypeFetch sends:

PATCH /users/123?notify=true

With body:

json

{
  "name": "Taha"
}

Request Schema Helper

You can use makeRequestSchema to make structured request schemas easier to write.

import { z } from "zod";
import { makeRequestSchema } from "@tahanabavi/typefetch";

const updateUserRequest = makeRequestSchema<
  { id: z.ZodString },
  { notify: z.ZodOptional<z.ZodBoolean> },
  z.ZodObject<{
    name: z.ZodString;
  }>
>()({
  path: z.object({
    id: z.string(),
  }),
  query: z.object({
    notify: z.boolean().optional(),
  }),
  body: z.object({
    name: z.string(),
  }),
  headers: z.record(z.string(), z.string()).optional(),
});

Use it inside an endpoint:

const contracts = {
  user: {
    updateUser: {
      method: "PATCH",
      path: "/users/:id",
      request: updateUserRequest,
      response: z.object({
        id: z.string(),
        name: z.string(),
      }),
    },
  },
} as const;

Backward Compatibility

Flat request schemas are still supported.

const contracts = {
  user: {
    createUser: {
      method: "POST",
      path: "/users",
      request: z.object({
        name: z.string(),
      }),
      response: z.object({
        id: z.string(),
        name: z.string(),
      }),
    },
  },
} as const;

Usage:

await api.user.createUser({
  name: "Taha",
});

For non-GET requests, the full flat input is sent as the JSON body.

For GET requests, flat input is validated but no body is sent.