transit-kit 0.8.0 → 0.8.2

package/README.md

@@ -1,19 +1,29 @@
-# transit-kit
+# Transit-Kit
 
 [![CI](https://github.com/D4rkr34lm/transit-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/D4rkr34lm/transit-kit/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/D4rkr34lm/transit-kit/badge.svg?branch=main)](https://coveralls.io/github/D4rkr34lm/transit-kit?branch=main)
+[![npm version](https://badge.fury.io/js/transit-kit.svg)](https://www.npmjs.com/package/transit-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
 
-A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation.
+A **declarative TypeScript framework** for building end-to-end type-safe REST APIs with Express.js and automatic OpenAPI documentation generation.
 
-## Features
+## Why Transit-Kit?
 
-- 🔒 **Type-Safe**: End-to-end type safety with TypeScript and Zod validation
-- 📝 **Declarative API Definition**: Define your endpoints with clear, declarative syntax
-- 🔄 **Automatic Validation**: Request body and query parameter validation using Zod schemas
-- 📚 **OpenAPI Generation**: Automatically generate OpenAPI documentation from your endpoint definitions
-- ⚡ **Express.js Powered**: Built on top of the battle-tested Express.js framework
-- 🪵 **Built-in Logging**: Request and response logging out of the box
-- 🎯 **Path Parameters**: Full support for path parameters with type safety
+Transit-Kit brings modern type-safety and developer experience to Express.js without abandoning the familiar, battle-tested foundation you already know. It's built on minimalism:
+
+- 🎯 **Express at its core** — Use the familiar Express API you already know
+- 🔒 **End-to-end type safety** — Full TypeScript inference from request to response
+- 📝 **Auto-generated OpenAPI** — Documentation that stays in sync with your code
+- ✅ **Zod validation** — Runtime type checking with zero boilerplate
+- 🪶 **Minimal overhead** — Thin layer over Express, not a complete rewrite
+-  **Declarative definitions** — Define endpoints declaratively with full type info
+
+## Requirements
+
+- **Node.js 22+**
+- **TypeScript 5.9+**
 
 ## Installation
 
@@ -21,450 +31,681 @@ A declarative TypeScript framework for building type-safe Express.js APIs with a
 npm install transit-kit
 ```
 
-## Quick Start
+```bash
+yarn add transit-kit
+```
 
-### 1. Create a Server
+```bash
+pnpm add transit-kit
+```
+
+## Quick Start
 
 ```typescript
 import { createServer } from "transit-kit/server";
+import { createApiEndpointHandler } from "transit-kit/server";
+import { z } from "zod";
 
+// Create a server
 const server = createServer({
   port: 3000,
   inDevMode: true,
-  logger: true, // or pass a custom logger (console-like interface)
+  logger: true,
 });
+
+// Define a simple endpoint
+const helloEndpoint = createApiEndpointHandler(
+  {
+    meta: {
+      name: "sayHello",
+      group: "Greetings",
+      description: "Returns a greeting message",
+    },
+    path: "/hello/:name",
+    method: "get",
+    responseSchemas: {
+      200: {
+        type: "json",
+        schema: z.object({
+          message: z.string(),
+        }),
+      },
+    },
+    securitySchemes: [],
+  },
+  async ({ parameters }) => {
+    return {
+      code: 200,
+      data: {
+        message: `Hello, ${parameters.name}!`,
+      },
+    };
+  }
+);
+
+// Register and start
+server.registerApiEndpoint(helloEndpoint);
+server.start();
 ```
 
-### 2. Define an API Endpoint
+## Core Concepts
+
+### 1. Endpoint Definitions
+
+Every API endpoint in Transit-Kit is defined declaratively with full type information:
 
 ```typescript
-import { createApiEndpointHandler } from "transit-kit/server";
-import z from "zod";
+const definition = {
+  meta: {
+    name: "createUser",           // Unique operation ID
+    group: "Users",                // OpenAPI tag
+    description: "Create a user"  // Endpoint description
+  },
+  path: "/users",                  // Express-style path
+  method: "post",                  // HTTP method
+  requestBodySchema: z.object({    // Request validation (optional)
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  querySchema: z.object({          // Query params validation (optional)
+    sendEmail: z.boolean().optional(),
+  }),
+  responseSchemas: {               // All possible responses
+    201: {
+      type: "json",
+      schema: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    },
+    400: {
+      type: "json",
+      schema: z.object({
+        error: z.string(),
+      }),
+    },
+  },
+  securitySchemes: [],             // Auth schemes (if any)
+};
+```
+
+### 2. Type-Safe Handlers
+
+Handlers automatically infer types from your endpoint definition:
+
+```typescript
+const handler = async ({ body, query, parameters }) => {
+  // body is typed as { name: string, email: string }
+  // query is typed as { sendEmail?: boolean }
+  // parameters are inferred from the path pattern
+  
+  const user = await createUserInDatabase(body);
+  
+  return {
+    code: 201,
+    data: user,  // Must match the response schema for code 201
+  };
+};
+```
+
+### 3. Server Registration
+
+Combine definitions and handlers, then register with your server:
+
+```typescript
+const endpoint = createApiEndpointHandler(definition, handler);
+server.registerApiEndpoint(endpoint);
+```
+
+## Example: CRUD API
+
+Here's a complete example showing a REST API for managing todos:
+
+```typescript
+import { createServer, createApiEndpointHandler } from "transit-kit/server";
+import { z } from "zod";
+
+const server = createServer({
+  port: 3000,
+  inDevMode: true,
+  logger: true,
+});
 
-// Define a simple GET endpoint
-const getUserEndpoint = createApiEndpointHandler(
+// In-memory storage (use a real database in production)
+const todos: Map<string, { id: string; title: string; completed: boolean }> = new Map();
+
+// Schemas
+const TodoSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+
+const CreateTodoSchema = z.object({
+  title: z.string().min(1),
+});
+
+// CREATE
+const createTodo = createApiEndpointHandler(
   {
     meta: {
-      name: "Get User",
-      description: "Retrieves a user by ID",
-      group: "Users",
+      name: "createTodo",
+      group: "Todos",
+      description: "Create a new todo item",
+    },
+    path: "/todos",
+    method: "post",
+    requestBodySchema: CreateTodoSchema,
+    responseSchemas: {
+      201: {
+        type: "json",
+        schema: TodoSchema,
+      },
+    },
+    securitySchemes: [],
+  },
+  async ({ body }) => {
+    const id = crypto.randomUUID();
+    const todo = {
+      id,
+      title: body.title,
+      completed: false,
+    };
+    todos.set(id, todo);
+
+    return {
+      code: 201,
+      data: todo,
+    };
+  }
+);
+
+// READ (List)
+const listTodos = createApiEndpointHandler(
+  {
+    meta: {
+      name: "listTodos",
+      group: "Todos",
+      description: "Get all todo items",
     },
+    path: "/todos",
     method: "get",
-    path: "/users/:userId",
     responseSchemas: {
       200: {
-        dataType: "application/json",
-        dataSchema: z.object({
-          id: z.string(),
-          name: z.string(),
-          email: z.string().email(),
+        type: "json",
+        schema: z.object({
+          todos: z.array(TodoSchema),
         }),
       },
-      404: {}, // Empty response
     },
+    securitySchemes: [],
   },
-  async (request) => {
-    const { userId } = request.params;
-
-    // Simulate fetching user
-    const user = await fetchUser(userId);
+  async () => {
+    return {
+      code: 200,
+      data: {
+        todos: Array.from(todos.values()),
+      },
+    };
+  }
+);
 
-    if (!user) {
+// READ (Single)
+const getTodo = createApiEndpointHandler(
+  {
+    meta: {
+      name: "getTodo",
+      group: "Todos",
+      description: "Get a specific todo item",
+    },
+    path: "/todos/:id",
+    method: "get",
+    responseSchemas: {
+      200: {
+        type: "json",
+        schema: TodoSchema,
+      },
+      404: {
+        type: "json",
+        schema: z.object({ error: z.string() }),
+      },
+    },
+    securitySchemes: [],
+  },
+  async ({ parameters }) => {
+    const todo = todos.get(parameters.id);
+    
+    if (!todo) {
       return {
         code: 404,
+        data: { error: "Todo not found" },
       };
     }
 
     return {
       code: 200,
-      dataType: "application/json",
-      json: user,
+      data: todo,
     };
-  },
+  }
 );
-```
 
-### 3. Define an Endpoint with Request Body and Query Parameters
-
-```typescript
-const createUserEndpoint = createApiEndpointHandler(
+// UPDATE
+const updateTodo = createApiEndpointHandler(
   {
     meta: {
-      name: "Create User",
-      description: "Creates a new user",
-      group: "Users",
+      name: "updateTodo",
+      group: "Todos",
+      description: "Update a todo item",
     },
-    method: "post",
-    path: "/users",
+    path: "/todos/:id",
+    method: "put",
     requestBodySchema: z.object({
-      name: z.string().min(1),
-      email: z.string().email(),
-      age: z.number().min(18),
-    }),
-    querySchema: z.object({
-      notify: z.boolean().optional(),
+      title: z.string().optional(),
+      completed: z.boolean().optional(),
     }),
     responseSchemas: {
-      201: {
-        dataType: "application/json",
-        dataSchema: z.object({
-          id: z.string(),
-          name: z.string(),
-          email: z.string().email(),
-        }),
+      200: {
+        type: "json",
+        schema: TodoSchema,
       },
-      400: {
-        dataType: "application/json",
-        dataSchema: z.object({
-          error: z.string(),
-        }),
+      404: {
+        type: "json",
+        schema: z.object({ error: z.string() }),
       },
     },
+    securitySchemes: [],
   },
-  async (request) => {
-    // Request body is automatically validated and typed
-    const { name, email, age } = request.body;
-    const { notify } = request.query;
+  async ({ parameters, body }) => {
+    const todo = todos.get(parameters.id);
+    
+    if (!todo) {
+      return {
+        code: 404,
+        data: { error: "Todo not found" },
+      };
+    }
 
-    try {
-      const newUser = await createUser({ name, email, age });
+    const updated = {
+      ...todo,
+      ...body,
+    };
+    todos.set(parameters.id, updated);
 
-      if (notify) {
-        await sendNotification(email);
-      }
+    return {
+      code: 200,
+      data: updated,
+    };
+  }
+);
 
+// DELETE
+const deleteTodo = createApiEndpointHandler(
+  {
+    meta: {
+      name: "deleteTodo",
+      group: "Todos",
+      description: "Delete a todo item",
+    },
+    path: "/todos/:id",
+    method: "delete",
+    responseSchemas: {
+      204: {
+        type: "json",
+        schema: z.object({}),
+      },
+      404: {
+        type: "json",
+        schema: z.object({ error: z.string() }),
+      },
+    },
+    securitySchemes: [],
+  },
+  async ({ parameters }) => {
+    const exists = todos.has(parameters.id);
+    
+    if (!exists) {
       return {
-        code: 201,
-        dataType: "application/json",
-        json: newUser,
-      };
-    } catch (error) {
-      return {
-        code: 400,
-        dataType: "application/json",
-        json: { error: error.message },
+        code: 404,
+        data: { error: "Todo not found" },
       };
     }
-  },
-);
-```
 
-### 4. Register Endpoints and Start Server
+    todos.delete(parameters.id);
 
-```typescript
-server.registerApiEndpoint(getUserEndpoint);
-server.registerApiEndpoint(createUserEndpoint);
+    return {
+      code: 204,
+      data: {},
+    };
+  }
+);
+
+// Register all endpoints
+server.registerApiEndpoint(createTodo);
+server.registerApiEndpoint(listTodos);
+server.registerApiEndpoint(getTodo);
+server.registerApiEndpoint(updateTodo);
+server.registerApiEndpoint(deleteTodo);
 
 server.start();
+console.log("Server running on http://localhost:3000");
 ```
 
 ## Authentication
 
-Transit-kit includes a simple, composable authentication mechanism based on `Authorization` headers. You declare one or more `SecurityScheme`s on an endpoint, and the framework will:
+Transit-Kit supports **Basic** and **Bearer** authentication schemes out of the box.
 
-- Apply an authentication middleware for that endpoint
-- Try all declared schemes in order and pick the first successful one
-- Return `401 Unauthorized` automatically when authentication fails
-- Inject the authenticated `caller` into your endpoint handler
+### Basic Authentication
 
-### Basic Auth
+```typescript
+import { createBasicAuthSchema } from "transit-kit/server";
 
-Supports `Authorization: Basic <base64(username:password)>`.
+// Define your user type
+interface User {
+  id: string;
+  username: string;
+  role: string;
+}
 
-```typescript
-import {
-  createApiEndpointHandler,
-  createServer,
-} from "transit-kit/server";
-import { createBasicAuthSchema } from "transit-kit/server/security/basicAuth";
-import z from "zod";
-
-// Define the shape of the authenticated caller
-type Caller = { id: string; role: "admin" | "user" };
-
-// Your validation logic (DB lookup, etc.)
-const basicAuth = createBasicAuthSchema<Caller>(
-  "basic",
+// Create an auth scheme
+const basicAuth = createBasicAuthSchema<User>(
+  "basicAuth",
   async (username, password) => {
-    const user = await findUserByUsername(username);
-    if (!user) return null;
-    const ok = await verifyPassword(password, user.passwordHash);
-    return ok ? { id: user.id, role: user.role } : null;
-  },
-);
-
-const getProfile = createApiEndpointHandler(
-  {
-    meta: { name: "Get Profile", description: "Returns caller profile", group: "Auth" },
-    method: "get",
-    path: "/me",
-    responseSchemas: {
-      200: {
-        dataType: "application/json",
-        dataSchema: z.object({ id: z.string(), role: z.enum(["admin", "user"]) }),
-      },
-      401: {},
-    },
-    // Enable authentication for this endpoint
-    securitySchemes: [basicAuth],
-  },
-  async (_req, { caller }) => {
-    // `caller` is typed from your security scheme
-    return { code: 200, dataType: "application/json", json: caller };
-  },
+    // Validate credentials (use your database)
+    if (username === "admin" && password === "secret") {
+      return {
+        id: "1",
+        username: "admin",
+        role: "admin",
+      };
+    }
+    return null; // Invalid credentials
+  }
 );
-
-const server = createServer({ port: 3000, inDevMode: true, logger: true });
-server.registerApiEndpoint(getProfile);
-server.start();
 ```
 
-### Bearer Token Auth
-
-Supports `Authorization: Bearer <token>`.
+### Bearer Authentication
 
 ```typescript
-import { createBearerAuthSchema } from "transit-kit/server/security/bearerAuth";
-
-type Caller = { id: string; scopes: string[] };
+import { createBearerAuthSchema } from "transit-kit/server";
 
-const bearerAuth = createBearerAuthSchema<Caller>(
-  "bearer",
+const bearerAuth = createBearerAuthSchema<User>(
+  "bearerAuth",
   async (token) => {
-    const payload = await verifyJwt(token); // or call your token introspection service
-    return payload ? { id: payload.sub, scopes: payload.scopes } : null;
-  },
+    // Validate token (e.g., JWT verification)
+    const user = await verifyJWT(token);
+    return user; // or null if invalid
+  }
 );
+```
 
-const getSecret = createApiEndpointHandler(
+### Protected Endpoints
+
+```typescript
+const protectedEndpoint = createApiEndpointHandler(
   {
-    meta: { name: "Get Secret", description: "Protected resource", group: "Auth" },
+    meta: {
+      name: "getProfile",
+      group: "Users",
+      description: "Get current user profile",
+    },
+    path: "/profile",
     method: "get",
-    path: "/secret",
     responseSchemas: {
-      200: { dataType: "application/json", dataSchema: z.object({ secret: z.string() }) },
-      401: {},
+      200: {
+        type: "json",
+        schema: z.object({
+          id: z.string(),
+          username: z.string(),
+          role: z.string(),
+        }),
+      },
+      401: {
+        type: "json",
+        schema: z.object({ error: z.string() }),
+      },
     },
-    securitySchemes: [bearerAuth],
-  },
-  async (_req, { caller }) => {
-    // Use `caller.scopes` for authorization decisions
-    return { code: 200, dataType: "application/json", json: { secret: "shh" } };
+    securitySchemes: [basicAuth], // Require authentication
   },
+  async ({ caller }) => {
+    // caller is typed as User | null
+    if (!caller) {
+      return {
+        code: 401,
+        data: { error: "Unauthorized" },
+      };
+    }
+
+    return {
+      code: 200,
+      data: caller, // Fully typed user object
+    };
+  }
 );
+
+server.registerApiEndpoint(protectedEndpoint);
 ```
 
-### Multiple Schemes per Endpoint
+### Multiple Auth Schemes
 
-You can allow multiple authentication methods on the same endpoint. The framework tries them in the order you specify and picks the first successful scheme.
+You can support multiple authentication methods:
 
 ```typescript
 const endpoint = createApiEndpointHandler(
   {
-    meta: { name: "Hybrid Auth", description: "Basic or Bearer", group: "Auth" },
-    method: "get",
-    path: "/hybrid",
-    responseSchemas: { 200: { dataType: "application/json", dataSchema: z.object({ ok: z.boolean() }) }, 401: {} },
-    securitySchemes: [basicAuth, bearerAuth],
-  },
-  async (_req, { caller }) => {
-    // `caller` resolves from whichever scheme authenticated successfully
-    return { code: 200, dataType: "application/json", json: { ok: true } };
+    // ... other config
+    securitySchemes: [basicAuth, bearerAuth], // Accept either
   },
+  async ({ caller }) => {
+    // caller will be set if any scheme succeeds
+    // ...
+  }
 );
 ```
 
-### How It Works
-
-- Authentication middleware is built automatically per-endpoint when `securitySchemes` are present.
-- Internals use `authenticate()` from [src/server/security/SecuritySchema.ts](src/server/security/SecuritySchema.ts) to try each scheme.
-- Basic auth reads and decodes the header in [src/server/security/basicAuth.ts](src/server/security/basicAuth.ts).
-- Bearer auth reads the header in [src/server/security/bearerAuth.ts](src/server/security/bearerAuth.ts).
-- On success, the authenticated `caller` is stored and passed to your handler as `extractedRequestData.caller`.
-- On failure, the framework responds with `401` and a JSON `{ message: "Unauthorized" }` from [src/server/middleware/auth.ts](src/server/middleware/auth.ts).
+## OpenAPI Documentation
 
-## Response Types
+Transit-Kit automatically generates OpenAPI 3.0 documentation from your endpoint definitions.
 
-### JSON Response
+```typescript
+import { generateOpenApiDoc } from "transit-kit/generator";
+
+const openApiDoc = await generateOpenApiDoc(server, {
+  title: "My API",
+  version: "1.0.0",
+  description: "A type-safe REST API built with Transit-Kit",
+  servers: [
+    {
+      url: "http://localhost:3000",
+      description: "Development server",
+    },
+    {
+      url: "https://api.example.com",
+      description: "Production server",
+    },
+  ],
+  contact: {
+    name: "API Support",
+    email: "support@example.com",
+  },
+  license: {
+    name: "MIT",
+    url: "https://opensource.org/licenses/MIT",
+  },
+});
 
-For endpoints that return JSON data:
+// Serve the OpenAPI spec
+server.expressApp.get("/openapi.json", (req, res) => {
+  res.json(openApiDoc);
+});
 
-```typescript
-return {
-  code: 200,
-  dataType: "application/json",
-  json: { message: "Success", data: myData },
-};
+// Or write to file
+import { writeFileSync } from "fs";
+writeFileSync("./openapi.json", JSON.stringify(openApiDoc, null, 2));
 ```
 
-### Empty Response
+The generated OpenAPI document includes:
+- All endpoints with request/response schemas
+- Path and query parameters
+- Request body validation schemas
+- Security requirements
+- Response schemas for all status codes
 
-For endpoints that return no content (e.g., 204 No Content):
+You can use this with tools like:
+- **Swagger UI** for interactive documentation
+- **Postman** for API testing
+- **OpenAPI Generator** for client SDK generation
 
-```typescript
-return {
-  code: 204,
-};
-```
+## API Reference
 
-## OpenAPI Generation
+### Server
 
-Transit-kit can automatically generate OpenAPI documentation from your endpoint definitions.
+#### `createServer(config: ServerConfig): Server`
 
-### Using the CLI
+Creates a new Transit-Kit server instance.
 
-```bash
-npx transit-kit generate-openapi --output openapi.json --target ./src
-```
+**Config Options:**
+- `port: number` — Port to listen on
+- `inDevMode: boolean` — Enable development mode (detailed logging)
+- `logger: Logger | boolean` — Custom logger or true/false for console/no logging
 
-Options:
+**Returns:** Server instance with:
+- `expressApp: Application` — Underlying Express app
+- `registerApiEndpoint(endpoint)` — Register an API endpoint
+- `start()` — Start the server
+- `endpointDefinitions` — Array of registered endpoint definitions
 
-- `-o, --output <path>`: Output path for the generated OpenAPI document (default: `openapi.json`)
-- `-t, --target <path>`: Target path to search for endpoint definitions (default: `.`)
+### Endpoint Creation
 
-### Programmatic Usage
+#### `createApiEndpointHandler(definition, handler)`
 
-```typescript
-import { generateOpenApiDoc } from "transit-kit/cli";
+Creates a type-safe API endpoint.
 
-const openApiDoc = await generateOpenApiDoc("./src");
-```
+**Parameters:**
+- `definition` — Endpoint definition object
+- `handler` — Async function handling the request
 
-The generated OpenAPI document will include:
+**Handler receives:**
+- `request` — Express Request object
+- `response` — Express Response object
+- `parameters` — Type-safe path parameters
+- `query` — Type-safe query parameters
+- `body` — Type-safe request body
+- `caller` — Authenticated user (if auth is enabled)
 
-- All registered endpoints
-- Request/response schemas
-- Path parameters
-- Query parameters
-- Request body schemas
-- Response schemas for all status codes
+### Authentication
 
-## Configuration
+#### `createBasicAuthSchema<Caller>(name, validateCaller)`
 
-### Server Configuration
+Creates a Basic authentication scheme.
 
-```typescript
-interface ServerConfig {
-  inDevMode: boolean; // Enable development mode features
-  port: number; // Port to listen on
-  logger: Logger | boolean; // Logger instance or boolean to enable/disable
-}
-```
+**Parameters:**
+- `name: string` — Unique name for the scheme
+- `validateCaller: (username, password) => Promise<Caller | null>` — Validation function
 
-### Custom Logger
+#### `createBearerAuthSchema<Caller>(name, validateCaller)`
 
-You can provide a custom logger with a console-like interface:
+Creates a Bearer token authentication scheme.
 
-```typescript
-const customLogger = {
-  log: (message: string) => {
-    /* custom logging */
-  },
-  error: (message: string) => {
-    /* custom error logging */
-  },
-  // ... other console methods
-};
+**Parameters:**
+- `name: string` — Unique name for the scheme
+- `validateCaller: (token) => Promise<Caller | null>` — Validation function
 
-const server = createServer({
-  port: 3000,
-  inDevMode: false,
-  logger: customLogger,
-});
-```
+### OpenAPI Generation
 
-## API Reference
+#### `generateOpenApiDoc(server, options): Promise<OpenAPIV3.Document>`
 
-### `createServer(config: ServerConfig): Server`
+Generates OpenAPI 3.0 documentation.
 
-Creates a new server instance with the specified configuration.
+**Parameters:**
+- `server: Server` — Your Transit-Kit server instance
+- `options: GeneratorOptions` — OpenAPI metadata
 
-### `createApiEndpointHandler(definition, handler)`
+**Options:**
+- `title: string` — API title
+- `version: string` — API version
+- `description?: string` — API description
+- `servers?: ServerObject[]` — Server URLs
+- `contact?: ContactObject` — Contact information
+- `license?: LicenseObject` — License information
 
-Creates an API endpoint handler with type-safe request/response handling.
+## Response Types
 
-**Definition properties:**
+Transit-Kit currently supports JSON responses:
 
-- `meta`: Metadata about the endpoint (name, description, group)
-- `method`: HTTP method (`get`, `post`, `put`, `patch`, `delete`)
-- `path`: Express-style path with optional parameters (e.g., `/users/:userId`)
-- `requestBodySchema`: (Optional) Zod schema for request body validation
-- `querySchema`: (Optional) Zod schema for query parameter validation
-- `responseSchemas`: Map of status codes to response schemas
+```typescript
+{
+  type: "json",
+  schema: z.object({ /* your schema */ }),
+  headers?: ["X-Custom-Header"], // Optional custom headers
+}
+```
 
-### `server.registerApiEndpoint(endpoint)`
+When using custom headers in your response schema, you must include them in the handler response:
 
-Registers an endpoint with the server.
+```typescript
+return {
+  code: 200,
+  data: { /* ... */ },
+  headers: {
+    "X-Custom-Header": "value",
+  },
+};
+```
 
-### `server.start()`
+## Accessing Express Features
 
-Starts the Express server on the configured port.
+Since Transit-Kit is built on Express, you can access the underlying Express app:
 
-## Examples
+```typescript
+const server = createServer({ /* ... */ });
 
-### Complete Example
+// Add custom middleware
+server.expressApp.use(cors());
+server.expressApp.use(helmet());
 
-```typescript
-import { createServer, createApiEndpointHandler } from "transit-kit/server";
-import z from "zod";
+// Static files
+server.expressApp.use(express.static("public"));
 
-// Create server
-const server = createServer({
-  port: 3000,
-  inDevMode: true,
-  logger: true,
+// Custom routes
+server.expressApp.get("/health", (req, res) => {
+  res.json({ status: "ok" });
 });
+```
 
-// Define endpoints
-const listUsersEndpoint = createApiEndpointHandler(
-  {
-    meta: {
-      name: "List Users",
-      description: "Get a list of all users",
-      group: "Users",
-    },
-    method: "get",
-    path: "/users",
-    querySchema: z.object({
-      page: z.number().optional(),
-      limit: z.number().optional(),
-    }),
-    responseSchemas: {
-      200: {
-        dataType: "application/json",
-        dataSchema: z.array(
-          z.object({
-            id: z.string(),
-            name: z.string(),
-          }),
-        ),
-      },
-    },
-  },
-  async (request) => {
-    const { page = 1, limit = 10 } = request.query;
-    const users = await fetchUsers(page, limit);
+## Project Structure
 
-    return {
-      code: 200,
-      dataType: "application/json",
-      json: users,
-    };
-  },
-);
+Transit-Kit exports two main modules:
 
-server.registerApiEndpoint(listUsersEndpoint);
-server.start();
+- **`transit-kit/server`** — Server creation, endpoint handlers, and authentication
+- **`transit-kit/generator`** — OpenAPI documentation generation
+
+## TypeScript Configuration
+
+For the best experience, ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "target": "ES2022",
+    "module": "ES2022"
+  }
+}
 ```
 
 ## License
 
-MIT
+MIT © [D4rkr34lm](https://github.com/D4rkr34lm)
 
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-## Author
+## Links
 
-D4rkr34lm
+- [GitHub Repository](https://github.com/D4rkr34lm/transit-kit)
+- [npm Package](https://www.npmjs.com/package/transit-kit)
+- [Report Issues](https://github.com/D4rkr34lm/transit-kit/issues)

package/dist/generator/generateOpenApi.js

@@ -17,7 +17,10 @@ function extractPathAndParameters(path) {
     return { openApiPath, parameters };
 }
 function extractQueryParameters(querySchema) {
-    const querySchemaObject = z.toJSONSchema(querySchema, { io: "input" });
+    const querySchemaObject = z.toJSONSchema(querySchema, {
+        io: "input",
+        target: "openapi-3.0",
+    });
     if (querySchemaObject.properties) {
         return Object.entries(querySchemaObject.properties).map(([name, schema]) => ({
             name: name,
@@ -65,6 +68,7 @@ function translateToOpenAPIPathItem(definition) {
                     "application/json": {
                         schema: z.toJSONSchema(requestBodySchema, {
                             io: "input",
+                            target: "openapi-3.0",
                         }), // Type assertion
                     },
                 },
@@ -76,7 +80,10 @@ function translateToOpenAPIPathItem(definition) {
         .map(([statusCode, responseDef]) => {
         if (isJsonResponseSchema(responseDef)) {
             const zodSchema = responseDef.schema;
-            const responseSchema = z.toJSONSchema(zodSchema, { io: "input" });
+            const responseSchema = z.toJSONSchema(zodSchema, {
+                io: "input",
+                target: "openapi-3.0",
+            });
             return {
                 [statusCode]: {
                     description: `Response for status code ${statusCode}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-kit",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation",
   "keywords": [
     "express",