zod-codegen 1.0.3 → 1.1.1

package/examples/petstore/README.md

@@ -0,0 +1,121 @@
+# Petstore API Example
+
+This example demonstrates how to use `zod-codegen` with the Swagger Petstore OpenAPI specification.
+
+## Generated Files
+
+After running `zod-codegen`, you'll get:
+
+- `type.ts` - Contains all Zod schemas and the generated API client
+
+## Basic Usage
+
+```typescript
+import {SwaggerPetstoreOpenAPI30} from './type.js';
+
+// Create a client instance using default server from OpenAPI spec
+const client = new SwaggerPetstoreOpenAPI30({});
+
+// Use the generated methods
+const pets = await client.findPetsByStatus('available');
+console.log('Available pets:', pets);
+```
+
+### Server Configuration Options
+
+The generated client supports flexible server configuration:
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+// Option 1: Use default server (first server from OpenAPI spec)
+const defaultClient = new SwaggerPetstoreOpenAPI30({});
+
+// Option 2: Override with custom base URL
+const customClient = new SwaggerPetstoreOpenAPI30({
+  baseUrl: 'https://custom-api.example.com/v3',
+});
+
+// Option 3: Select server by index (if multiple servers exist)
+const indexedClient = new SwaggerPetstoreOpenAPI30({
+  serverIndex: 0,
+});
+
+// Option 4: Use server variables (if your OpenAPI spec has templated URLs)
+// Example spec: https://{environment}.example.com:{port}/v{version}
+const variableClient = new SwaggerPetstoreOpenAPI30({
+  serverIndex: 0,
+  serverVariables: {
+    environment: 'api.staging',
+    port: '8443',
+    version: '2',
+  },
+});
+```
+
+## Example: Finding Pets
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, defaultBaseUrl} from './type.js';
+
+async function findAvailablePets() {
+  const client = new SwaggerPetstoreOpenAPI30(defaultBaseUrl);
+
+  try {
+    // Find pets by status
+    const availablePets = await client.findPetsByStatus('available');
+    console.log(`Found ${availablePets.length} available pets`);
+
+    // Find pets by tags
+    const taggedPets = await client.findPetsByTags(['friendly', 'cute']);
+    console.log(`Found ${taggedPets.length} tagged pets`);
+
+    // Get a specific pet by ID
+    const pet = await client.getPetById(1);
+    console.log('Pet details:', pet);
+  } catch (error) {
+    console.error('Error fetching pets:', error);
+  }
+}
+
+findAvailablePets();
+```
+
+## Example: Adding a Pet
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, Pet, PetStatus, defaultBaseUrl} from './type.js';
+import {z} from 'zod';
+
+async function addNewPet() {
+  const client = new SwaggerPetstoreOpenAPI30(defaultBaseUrl);
+
+  const newPet: z.infer<typeof Pet> = {
+    id: 12345,
+    name: 'Fluffy',
+    status: PetStatus.enum.available,
+    category: {
+      id: 1,
+      name: 'Dogs',
+    },
+    photoUrls: ['https://example.com/fluffy.jpg'],
+    tags: [
+      {id: 1, name: 'friendly'},
+      {id: 2, name: 'cute'},
+    ],
+  };
+
+  try {
+    const addedPet = await client.addPet(newPet);
+    console.log('Pet added:', addedPet);
+  } catch (error) {
+    console.error('Error adding pet:', error);
+  }
+}
+
+addNewPet();
+```
+
+## Example: Extending the Client
+
+See the main [EXAMPLES.md](../../EXAMPLES.md) for comprehensive examples on extending the client for authentication, CORS, and custom headers.

package/examples/petstore/authenticated-usage.ts

@@ -0,0 +1,60 @@
+/**
+ * Example showing how to extend the generated client for authentication
+ *
+ * Run with: npx ts-node examples/petstore/authenticated-usage.ts
+ */
+
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+class AuthenticatedPetstoreAPI extends SwaggerPetstoreOpenAPI30 {
+  private apiKey: string | null = null;
+
+  constructor(options: ClientOptions = {}) {
+    super(options);
+  }
+
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    const options = super.getBaseRequestOptions();
+    return {
+      ...options,
+      headers: {
+        ...((options.headers as Record<string, string>) || {}),
+        ...(this.apiKey ? {api_key: this.apiKey} : {}),
+        'User-Agent': 'PetstoreClient/1.0.0',
+      },
+    };
+  }
+
+  setApiKey(key: string): void {
+    this.apiKey = key;
+  }
+
+  clearApiKey(): void {
+    this.apiKey = null;
+  }
+}
+
+async function main() {
+  const client = new AuthenticatedPetstoreAPI({});
+
+  // Set API key for authenticated requests
+  client.setApiKey('your-api-key-here');
+
+  try {
+    console.log('🔐 Making authenticated request...\n');
+
+    // This endpoint typically requires authentication
+    const inventory = await client.getInventory();
+    console.log('✅ Inventory retrieved:');
+    console.log(JSON.stringify(inventory, null, 2));
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ Error:', error.message);
+    } else {
+      console.error('❌ Unknown error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+void main();

package/examples/petstore/basic-usage.ts

@@ -0,0 +1,51 @@
+/**
+ * Basic usage example for the generated Petstore API client
+ *
+ * Run with: npx ts-node examples/petstore/basic-usage.ts
+ */
+
+import {SwaggerPetstoreOpenAPI30} from './type.js';
+
+async function main() {
+  // Use default server (first server from OpenAPI spec)
+  const client = new SwaggerPetstoreOpenAPI30({});
+
+  try {
+    console.log('🔍 Finding available pets...\n');
+
+    // Find pets by status
+    const availablePets = await client.findPetsByStatus('available');
+    console.log(`✅ Found ${availablePets.length} available pets`);
+
+    if (availablePets.length > 0) {
+      console.log('\n📋 First pet details:');
+      console.log(JSON.stringify(availablePets[0], null, 2));
+    }
+
+    // Find pets by tags (if available)
+    try {
+      const taggedPets = await client.findPetsByTags(['friendly']);
+      console.log(`\n🏷️  Found ${taggedPets.length} pets with tags`);
+    } catch (error) {
+      console.log('\n⚠️  Tags endpoint may not be available');
+    }
+
+    // Get store inventory
+    try {
+      const inventory = await client.getInventory();
+      console.log('\n📦 Store inventory:');
+      console.log(JSON.stringify(inventory, null, 2));
+    } catch (error) {
+      console.log('\n⚠️  Inventory endpoint may require authentication');
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ Error:', error.message);
+    } else {
+      console.error('❌ Unknown error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+void main();

package/examples/petstore/server-variables-usage.ts

@@ -0,0 +1,63 @@
+/**
+ * Example showing how to use server variables for different environments
+ *
+ * Run with: npx ts-node examples/petstore/server-variables-usage.ts
+ *
+ * Note: This example uses a hypothetical API with server variables.
+ * For a real example, generate a client from an OpenAPI spec with server variables.
+ */
+
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+async function main() {
+  // Example 1: Use default server (first server from OpenAPI spec)
+  console.log('📡 Example 1: Using default server\n');
+  const defaultClient = new SwaggerPetstoreOpenAPI30({});
+  console.log('Default client created');
+
+  // Example 2: Override with custom baseUrl
+  console.log('\n📡 Example 2: Overriding with custom baseUrl\n');
+  const customClient = new SwaggerPetstoreOpenAPI30({
+    baseUrl: 'https://custom-api.example.com/v3',
+  });
+  console.log('Custom client created');
+
+  // Example 3: Select different server by index (if multiple servers exist)
+  console.log('\n📡 Example 3: Selecting server by index\n');
+  const indexedClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0, // Use first server
+  });
+  console.log('Indexed client created');
+
+  // Example 4: Using server variables (if your OpenAPI spec has templated URLs)
+  // For example: https://{environment}.example.com:{port}/v{version}
+  console.log('\n📡 Example 4: Using server variables\n');
+  const variableClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0,
+    serverVariables: {
+      // environment: 'api.staging',  // Uncomment if your spec has these variables
+      // port: '8443',
+      // version: '2',
+    },
+  });
+  console.log('Variable client created');
+
+  // Example 5: Combining server selection with custom baseUrl override
+  console.log('\n📡 Example 5: Combining options\n');
+  const combinedClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0,
+    serverVariables: {
+      // Add variables here if your spec supports them
+    },
+    // baseUrl takes precedence if provided
+    // baseUrl: 'https://override.example.com',
+  });
+  console.log('Combined client created');
+
+  console.log('\n✅ All examples completed!');
+  console.log("\n💡 Tip: Check your OpenAPI spec's servers array to see available options.");
+  console.log('   Server variables allow you to switch between environments (dev, staging, prod)');
+  console.log('   without changing code!');
+}
+
+void main();

package/examples/petstore/type.ts

@@ -0,0 +1,217 @@
+// THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+// Built with zod-codegen@1.0.1
+// Latest edit: Thu, 13 Nov 2025 13:36:35 GMT
+// Source file: ./samples/swagger-petstore.yaml
+/* eslint-disable */
+// @ts-nocheck
+
+// Imports
+import {z} from 'zod';
+
+// Components schemas
+export const Order = z.object({
+  id: z.number().int().optional(),
+  petId: z.number().int().optional(),
+  quantity: z.number().int().optional(),
+  shipDate: z.string().datetime().optional(),
+  status: z.enum(['placed', 'approved', 'delivered']).optional(),
+  complete: z.boolean().optional(),
+});
+export const Address = z.object({
+  street: z.string().optional(),
+  city: z.string().optional(),
+  state: z.string().optional(),
+  zip: z.string().optional(),
+});
+export const Customer = z.object({
+  id: z.number().int().optional(),
+  username: z.string().optional(),
+  address: z.array(Address).optional(),
+});
+export const Category = z.object({
+  id: z.number().int().optional(),
+  name: z.string().optional(),
+});
+export const User = z.object({
+  id: z.number().int().optional(),
+  username: z.string().optional(),
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  email: z.string().optional(),
+  password: z.string().optional(),
+  phone: z.string().optional(),
+  userStatus: z.number().int().optional(),
+});
+export const Tag = z.object({
+  id: z.number().int().optional(),
+  name: z.string().optional(),
+});
+export const Pet = z.object({
+  id: z.number().int().optional(),
+  name: z.string(),
+  category: Category.optional(),
+  photoUrls: z.array(z.string()),
+  tags: z.array(Tag).optional(),
+  status: z.enum(['available', 'pending', 'sold']).optional(),
+});
+export const ApiResponse = z.object({
+  code: z.number().int().optional(),
+  type: z.string().optional(),
+  message: z.string().optional(),
+});
+export const serverConfigurations = [
+  {
+    url: 'https://petstore3.swagger.io/api/v3',
+  },
+];
+export const defaultBaseUrl = 'https://petstore3.swagger.io/api/v3';
+export type ClientOptions = {
+  baseUrl?: string;
+  serverIndex?: number;
+  serverVariables?: Record<string, string>;
+};
+function resolveServerUrl(serverIndex?: number | undefined, serverVariables?: Record<string, string> = {}): string {
+  const configs = [
+    {
+      url: 'https://petstore3.swagger.io/api/v3',
+    },
+  ];
+  const idx = serverIndex ?? 0;
+  if (idx < configs.length) {
+    const config = configs[idx];
+    let url = config.url;
+    if (config.variables && serverVariables) {
+      for (const [key, value] of Object.entries(serverVariables)) {
+        url = url.replace(new RegExp('\\{' + key + '\\}', 'g'), value);
+      }
+    }
+    return url;
+  }
+  return 'https://petstore3.swagger.io/api/v3';
+}
+
+// Client class
+export class SwaggerPetstoreOpenAPI30 {
+  readonly #baseUrl: string;
+  constructor(options: ClientOptions) {
+    const resolvedUrl =
+      options.baseUrl !== null ? options.baseUrl : resolveServerUrl(options.serverIndex, options.serverVariables);
+    this.#baseUrl = resolvedUrl;
+  }
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    return {};
+  }
+  async #makeRequest<T>(
+    method: string,
+    path: string,
+    options: _params___Record_string__string___number___boolean___data___unknown__contentType___string__headers___Record_string__string__ = {},
+  ): Promise<T> {
+    const baseUrl = `${this.#baseUrl}${path}`;
+    const url =
+      options.params && Object.keys(options.params).length > 0
+        ? (() => {
+            Object.entries(options.params).forEach(([key, value]) => {
+              new URL(baseUrl).searchParams.set(key, String(value));
+            });
+            return new URL(baseUrl).toString();
+          })()
+        : new URL(baseUrl).toString();
+    const baseOptions = this.getBaseRequestOptions();
+    const contentType =
+      options.contentType === 'application/x-www-form-urlencoded'
+        ? 'application/x-www-form-urlencoded'
+        : 'application/json';
+    const baseHeaders = baseOptions.headers !== undefined ? baseOptions.headers : {};
+    const headers = Object.assign(
+      {},
+      baseHeaders,
+      {'Content-Type': contentType},
+      options.headers !== undefined ? options.headers : {},
+    );
+    const body =
+      options.data !== undefined
+        ? options.contentType === 'application/x-www-form-urlencoded'
+          ? (() => {
+              const params = new URLSearchParams();
+              Object.entries(options.data).forEach(([key, value]) => {
+                params.set(key, String(value));
+              });
+              return params.toString();
+            })()
+          : JSON.stringify(options.data)
+        : null;
+    const response = await fetch(url, Object.assign({}, baseOptions, {method, headers: headers, body: body}));
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    return await response.json();
+  }
+  async addPet(body: Pet): Promise<Pet> {
+    return Pet.parse(
+      await this.#makeRequest('POST', '/pet', {data: body, contentType: 'application/x-www-form-urlencoded'}),
+    );
+  }
+  async updatePet(body: Pet): Promise<Pet> {
+    return Pet.parse(
+      await this.#makeRequest('PUT', '/pet', {data: body, contentType: 'application/x-www-form-urlencoded'}),
+    );
+  }
+  async findPetsByStatus(status?: string): Promise<Pet[]> {
+    return await this.#makeRequest('GET', '/pet/findByStatus', {params: {status: status}});
+  }
+  async findPetsByTags(tags?: string[]): Promise<Pet[]> {
+    return await this.#makeRequest('GET', '/pet/findByTags', {params: {tags: tags}});
+  }
+  async getPetById(petId: number): Promise<Pet> {
+    return Pet.parse(await this.#makeRequest('GET', `/pet/${petId}`, {}));
+  }
+  async updatePetWithForm(petId: number, name?: string, status?: string): Promise<void> {
+    return await this.#makeRequest('POST', `/pet/${petId}`, {params: {name: name, status: status}});
+  }
+  async deletePet(petId: number): Promise<void> {
+    return await this.#makeRequest('DELETE', `/pet/${petId}`, {});
+  }
+  async uploadFile(petId: number, additionalMetadata?: string): Promise<ApiResponse> {
+    return ApiResponse.parse(
+      await this.#makeRequest('POST', `/pet/${petId}/uploadImage`, {params: {additionalMetadata: additionalMetadata}}),
+    );
+  }
+  async getInventory(): Promise<Record<string, unknown>> {
+    return await this.#makeRequest('GET', '/store/inventory', {});
+  }
+  async placeOrder(body?: Order): Promise<Order> {
+    return Order.parse(
+      await this.#makeRequest('POST', '/store/order', {data: body, contentType: 'application/x-www-form-urlencoded'}),
+    );
+  }
+  async getOrderById(orderId: number): Promise<Order> {
+    return Order.parse(await this.#makeRequest('GET', `/store/order/${orderId}`, {}));
+  }
+  async deleteOrder(orderId: number): Promise<void> {
+    return await this.#makeRequest('DELETE', `/store/order/${orderId}`, {});
+  }
+  async createUser(body?: User): Promise<User> {
+    return User.parse(
+      await this.#makeRequest('POST', '/user', {data: body, contentType: 'application/x-www-form-urlencoded'}),
+    );
+  }
+  async createUsersWithListInput(body?: User[]): Promise<User> {
+    return User.parse(await this.#makeRequest('POST', '/user/createWithList', {data: body}));
+  }
+  async loginUser(username?: string, password?: string): Promise<string> {
+    return await this.#makeRequest('GET', '/user/login', {params: {username: username, password: password}});
+  }
+  async logoutUser(): Promise<void> {
+    return await this.#makeRequest('GET', '/user/logout', {});
+  }
+  async getUserByName(username: string): Promise<User> {
+    return User.parse(await this.#makeRequest('GET', `/user/${username}`, {}));
+  }
+  async updateUser(username: string, body?: User): Promise<void> {
+    return await this.#makeRequest('PUT', `/user/${username}`, {
+      data: body,
+      contentType: 'application/x-www-form-urlencoded',
+    });
+  }
+  async deleteUser(username: string): Promise<void> {
+    return await this.#makeRequest('DELETE', `/user/${username}`, {});
+  }
+}

package/examples/pokeapi/README.md

@@ -0,0 +1,105 @@
+# PokéAPI Example
+
+This example demonstrates how to use `zod-codegen` with the PokéAPI OpenAPI specification.
+
+## Setup
+
+First, generate the client from the PokéAPI OpenAPI spec:
+
+```bash
+zod-codegen --input ./samples/pokeapi-openapi.json --output ./examples/pokeapi
+```
+
+**Note**: PokéAPI doesn't provide an official OpenAPI specification, so we've created a simplified OpenAPI spec based on their API structure. For production use, you may want to create a more complete specification based on the [PokéAPI documentation](https://pokeapi.co/docs/v2).
+
+## Basic Usage
+
+```typescript
+import {PokAPI, defaultBaseUrl} from './type.js';
+
+// Create a client instance
+const client = new PokAPI(defaultBaseUrl);
+
+// Use the generated methods
+const pokemon = await client.getPokemonById('pikachu');
+console.log('Pokemon:', pokemon);
+```
+
+## Example: Fetching Pokémon Data
+
+See [basic-usage.ts](./basic-usage.ts) for a complete example:
+
+```typescript
+import {PokAPI, defaultBaseUrl} from './type.js';
+
+async function getPokemonInfo() {
+  const client = new PokAPI(defaultBaseUrl);
+
+  try {
+    // Get a specific Pokémon by ID or name
+    const pikachu = await client.getPokemonById('pikachu');
+    console.log(`Name: ${pikachu.name}`);
+    console.log(`Height: ${pikachu.height} dm`);
+    console.log(`Weight: ${pikachu.weight} hg`);
+
+    if (pikachu.types && pikachu.types.length > 0) {
+      const types = pikachu.types
+        .map((t) => t.type?.name)
+        .filter(Boolean)
+        .join(', ');
+      console.log(`Types: ${types}`);
+    }
+
+    // Get Pokémon list with pagination
+    const pokemonList = await client.getPokemonList(20, 0);
+    console.log(`\nTotal Pokémon: ${pokemonList.count}`);
+    console.log(`Showing: ${pokemonList.results.length} results`);
+  } catch (error) {
+    console.error('Error fetching Pokémon:', error);
+  }
+}
+
+getPokemonInfo();
+```
+
+**Run the example:**
+
+```bash
+npx ts-node examples/pokeapi/basic-usage.ts
+```
+
+## Example: Extending for Custom Headers
+
+See [custom-client.ts](./custom-client.ts) for a complete example:
+
+```typescript
+import {PokAPI, defaultBaseUrl} from './type.js';
+
+class CustomPokeAPI extends PokAPI {
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    const options = super.getBaseRequestOptions();
+    return {
+      ...options,
+      headers: {
+        ...((options.headers as Record<string, string>) || {}),
+        'User-Agent': 'MyPokemonApp/1.0.0',
+        Accept: 'application/json',
+      },
+      mode: 'cors',
+      cache: 'default',
+    };
+  }
+}
+
+const client = new CustomPokeAPI(defaultBaseUrl);
+```
+
+**Run the example:**
+
+```bash
+npx ts-node examples/pokeapi/custom-client.ts
+```
+
+## Note
+
+PokéAPI is a public API that doesn't require authentication, making it perfect for testing and learning. The generated client will work out of the box without any additional configuration.

package/examples/pokeapi/basic-usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Basic usage example for the generated PokéAPI client
+ *
+ * Run with: npx ts-node examples/pokeapi/basic-usage.ts
+ */
+
+import {PokAPI, defaultBaseUrl} from './type.js';
+
+async function main() {
+  const client = new PokAPI(defaultBaseUrl);
+
+  try {
+    console.log('🔍 Fetching Pokémon data...\n');
+
+    // Get a specific Pokémon by ID or name
+    console.log('📖 Getting Pikachu...');
+    const pikachu = await client.getPokemonById('pikachu');
+    console.log(`✅ Found: ${pikachu.name}`);
+    console.log(`   ID: ${pikachu.id}`);
+    console.log(`   Height: ${pikachu.height} dm`);
+    console.log(`   Weight: ${pikachu.weight} hg`);
+
+    if (pikachu.types && pikachu.types.length > 0) {
+      const types = pikachu.types
+        .map((t) => t.type?.name)
+        .filter(Boolean)
+        .join(', ');
+      console.log(`   Types: ${types}`);
+    }
+
+    if (pikachu.sprites?.front_default) {
+      console.log(`   Sprite: ${pikachu.sprites.front_default}`);
+    }
+
+    // Get Pokémon list
+    console.log('\n📋 Getting Pokémon list...');
+    const pokemonList = await client.getPokemonList(10, 0);
+    console.log(`✅ Found ${pokemonList.count} total Pokémon`);
+    console.log(`   Showing first ${pokemonList.results.length} results:`);
+
+    pokemonList.results.slice(0, 5).forEach((pokemon, index) => {
+      console.log(`   ${index + 1}. ${pokemon.name}`);
+    });
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ Error:', error.message);
+      if (error.message.includes('HTTP')) {
+        console.error('   This might be a network issue or the API endpoint may have changed.');
+      }
+    } else {
+      console.error('❌ Unknown error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+void main();