@rexeus/typeweaver-clients 0.0.3 → 0.1.0

package/README.md

@@ -1,411 +1,136 @@
-# @rexeus/typeweaver-clients
+# 🧵✨ @rexeus/typeweaver-clients
 
-HTTP client generators for TypeWeaver API specifications.
+[![npm version](https://img.shields.io/npm/v/@rexeus/typeweaver-clients.svg)](https://www.npmjs.com/package/@rexeus/typeweaver-clients)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-## Overview
+Typeweaver is a type-safe HTTP API framework built for API-first development with a focus on
+developer experience. Use typeweaver to specify your HTTP APIs in TypeScript and Zod, and generate
+clients, validators, routers, and more ✨
 
-This plugin generates type-safe HTTP API clients from your TypeWeaver API definitions, providing
-end-to-end type safety from API definition to client usage.
+## 📝 Clients Plugin
 
-## Installation
+This plugin generates type-safe HTTP clients from your typeweaver API definitions, providing
+end-to-end type safety. The generated clients use the Command Pattern, where each API request is
+encapsulated as a typed command object that contains all request data and handles response
+processing.
 
-```bash
-npm install @rexeus/typeweaver-clients
-```
-
-**Peer Dependencies:**
+## 📥 Installation
 
 ```bash
-npm install @rexeus/typeweaver-core @rexeus/typeweaver-gen
-```
+# Install the CLI and the plugin as a dev dependency
+npm install -D @rexeus/typeweaver @rexeus/typeweaver-clients
 
-## Usage
+# Install the runtime as a dependency
+npm install @rexeus/typeweaver-core
+```
 
-### CLI
+## 💡 How to use
 
 ```bash
 npx typeweaver generate --input ./api/definitions --output ./api/generated --plugins clients
 ```
 
-### Configuration File
+More on the CLI in [@rexeus/typeweaver](https://github.com/rexeus/typeweaver/tree/main/packages/cli/README.md#️-cli).
 
-```javascript
-// typeweaver.config.js
-export default {
-  input: "./api/definitions",
-  output: "./api/generated",
-  plugins: ["clients"],
-};
-```
-
-## Generated Output
+## 📂 Generated Output
 
-This plugin generates HTTP API clients for each entity in your API definitions.
+For each resource (e.g., `Todo`), the plugin generates a HTTP client. This client can execute
+request commands for all operations of this resource. This plugin generates the following files:
 
-### Example Generated Client
+- `<ResourceName>Client.ts` - e.g. `TodoClient.ts`
+- `<OperationId>RequestCommand.ts` - e.g. `CreateTodoRequestCommand.ts`
 
-For an API definition with a `users` entity, the plugin generates:
+### 📡 Clients
 
-```typescript
-// UsersClient.ts
-import { ApiClient } from "@rexeus/typeweaver-core";
-import { GetUserRequestCommand } from "./GetUserRequest";
-import { GetUserResponseValidator } from "./GetUserResponseValidator";
-// ... other imports
+Resource-specific HTTP clients are generated as `<ResourceName>Client.ts` files, e.g.
+`TodoClient.ts`. Each client extends the `ApiClient` base class and provides:
 
-export class UsersClient extends ApiClient {
-  public send(command: GetUserRequestCommand): Promise<GetUserResponse>;
-  public send(command: CreateUserRequestCommand): Promise<CreateUserResponse>;
-  // ... other overloads
+- **Type-safe HTTP methods** - Method overloads for each operation ensuring compile-time type
+  checking
+- **axios based** - Supports all axios features and interceptors by using custom axios instances
+- **Response type mapping** - Each response is automatically mapped to the associated response class
+  and an instance of the class is returned. This ensures that all responses are in the defined
+  format and it is type-safe.
+- **Unknown response handling**
+  - Unknown properties are automatically removed from the response. If a response exceeds the
+    definition, it is not rejected directly.
+  - If a response does not match any known format, it will be rejected by default as an
+    `UnknownResponse` instance.
+  - This unknown response handling can be configured. It is also possible for an `UnknownResponse`
+    instance to be created without being thrown.
 
-  public async send(command: unknown): Promise<unknown> {
-    if (command instanceof GetUserRequestCommand) {
-      return this.handleGetUser(command);
-    }
-    if (command instanceof CreateUserRequestCommand) {
-      return this.handleCreateUser(command);
-    }
-    // ... other handlers
-
-    throw new Error(`Unknown command type`);
-  }
-
-  private async handleGetUser(command: GetUserRequestCommand): Promise<GetUserResponse> {
-    const response = await this.makeRequest(command);
-    const validator = new GetUserResponseValidator();
-    return validator.validate(response);
-  }
-
-  // ... other private handlers
-}
-```
-
-## Usage Examples
-
-### Basic Usage
+**Using generated clients**
 
 ```typescript
-import { UsersClient } from "./api/generated/users/UsersClient";
-import { GetUserRequestCommand } from "./api/generated/users/GetUserRequest";
-
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-});
+import { TodoClient } from "path/to/generated/output";
 
-// Type-safe request
-const command = new GetUserRequestCommand({
-  param: { userId: "123" },
-  header: { Authorization: "Bearer token" },
+const client = new TodoClient({
+  axiosInstance: customAxios, // Custom axios instance
+  baseUrl: "https://api.example.com", // Base URL for all requests
+  unknownResponseHandling: "throw", // "throw" | "passthrough" for unknown responses
+  // -> In "passthrough" mode, the received status code determines if the response is thrown
+  isSuccessStatusCode: code => code < 400, // Custom success status code predicate, determines whether the response is successful or should be thrown
 });
-
-try {
-  // Fully typed response
-  const result = await client.send(command);
-  console.log(result.body.name); // Type-safe access
-} catch (error) {
-  // Typed error handling
-  if (error instanceof UserNotFoundErrorResponse) {
-    console.error("User not found:", error.body.message);
-  }
-}
 ```
 
-### Advanced Configuration
+### ✉️ Request Commands
 
-```typescript
-import { UsersClient } from "./api/generated/users/UsersClient";
+Request commands are generated as `<OperationId>RequestCommand.ts` files, e.g.
+`CreateTodoRequestCommand.ts`. These commands encapsulate all request data and provide:
 
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  timeout: 5000,
-  headers: {
-    "User-Agent": "MyApp/1.0",
-  },
-  // Custom axios config
-  axios: {
-    validateStatus: status => status < 500,
-  },
-});
-```
+- **Type-safe construction** - Constructor enforces correct request structure
+- **Complete request encapsulation** - Contains method, path, headers, query parameters, and body
+- **Response processing** - Transform raw HTTP responses into typed response objects of the correct
+  response class
 
-### Error Handling
+### Basic Usage
 
 ```typescript
 import {
-  UsersClient,
-  GetUserRequestCommand,
-  UserNotFoundErrorResponse,
+  TodoClient,
+  CreateTodoRequestCommand,
+  CreateTodoSuccessResponse,
+  OtherSuccessResponse,
   ValidationErrorResponse,
-} from "./api/generated";
-
-const client = new UsersClient({ baseURL: "https://api.example.com" });
+  InternalServerErrorResponse,
+} from "path/to/generated/output";
 
-try {
-  const result = await client.send(
-    new GetUserRequestCommand({
-      param: { userId: "invalid-id" },
-    })
-  );
-} catch (error) {
-  // Type-safe error handling
-  if (error instanceof UserNotFoundErrorResponse) {
-    console.error(`User not found: ${error.body.message}`);
-  } else if (error instanceof ValidationErrorResponse) {
-    console.error("Validation failed:", error.body.issues);
-  } else {
-    console.error("Unexpected error:", error);
-  }
-}
-```
-
-## Client Features
-
-### Type Safety
-
-- **Request Commands** - Fully typed request objects
-- **Response Types** - Typed response interfaces
-- **Error Types** - Typed error response classes
-- **Parameter Validation** - Runtime validation via Zod
-
-### Method Overloading
-
-Each client provides method overloads for perfect type inference:
-
-```typescript
-// Each command type gets its own overload
-client.send(getUserCommand); // Returns GetUserResponse
-client.send(createUserCommand); // Returns CreateUserResponse
-```
-
-### Automatic Validation
-
-- **Request validation** - Commands validate input data
-- **Response validation** - Responses validated against schemas
-- **Error parsing** - HTTP errors mapped to typed error classes
-
-### Framework Integration
-
-Works with any HTTP client framework (uses Axios by default):
-
-```typescript
-// Custom HTTP adapter
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  httpAdapter: new FetchAdapter(), // Custom adapter
+const client = new TodoClient({
+  baseUrl: "https://api.example.com",
 });
-```
-
-## Request Commands
-
-### Command Structure
 
-Generated request commands encapsulate all request data:
-
-```typescript
-import { GetUserRequestCommand } from "./GetUserRequest";
-
-const command = new GetUserRequestCommand({
-  param: { userId: "123" }, // Path parameters
-  query: { include: ["posts"] }, // Query parameters
-  header: { Authorization: "Bearer token" }, // Headers
-  body: { name: "John Doe" }, // Request body
+const command = new CreateTodoRequestCommand({
+  header: { Authorization: "Bearer token" },
+  body: { title: "New Todo", status: "PENDING" },
 });
-```
-
-### Command Validation
 
-Commands validate input data at construction time:
-
-```typescript
 try {
-  const command = new GetUserRequestCommand({
-    param: { userId: "invalid-uuid" }, // Will throw validation error
-  });
-} catch (error) {
-  console.error("Invalid command:", error.issues);
-}
-```
-
-## Response Handling
+  const response = await client.send(command);
 
-### Success Responses
+  // If there is only one success response,
+  // you can directly access the response like:
+  console.log("Success:", response.body);
 
-```typescript
-const result = await client.send(command);
-
-// Typed access to response data
-console.log(result.statusCode); // HTTP status code
-console.log(result.header); // Response headers
-console.log(result.body.id); // Response body (fully typed)
-```
-
-### Error Responses
-
-```typescript
-try {
-  const result = await client.send(command);
-} catch (error) {
-  if (error instanceof UserNotFoundErrorResponse) {
-    // Specific error type
-    console.log(error.statusCode); // 404
-    console.log(error.body.message); // "User not found"
+  // If there are multiple success responses, you can check the instance like:
+  if (response instanceof CreateTodoSuccessResponse) {
+    console.log("Todo created successfully:", response.body);
   }
-}
-```
-
-## Plugin Architecture
-
-This plugin extends the TypeWeaver plugin system:
-
-```typescript
-import { BasePlugin, type GeneratorContext } from "@rexeus/typeweaver-gen";
-
-export default class ClientsPlugin extends BasePlugin {
-  public name = "clients";
-
-  public override generate(context: GeneratorContext): void {
-    // Generates API clients for each entity
+  if (response instanceof OtherSuccessResponse) {
+    // ... Handle "OtherSuccessResponse"
   }
-}
-```
-
-## Best Practices
-
-### Client Configuration
-
-```typescript
-// Environment-specific configuration
-const client = new UsersClient({
-  baseURL: process.env.API_BASE_URL,
-  timeout: parseInt(process.env.API_TIMEOUT || "5000"),
-  headers: {
-    "User-Agent": `${process.env.APP_NAME}/${process.env.APP_VERSION}`,
-  },
-});
-```
-
-### Error Handling Strategy
-
-```typescript
-// Centralized error handling
-async function handleApiCall<T>(operation: () => Promise<T>): Promise<T> {
-  try {
-    return await operation();
-  } catch (error) {
-    if (error instanceof ValidationErrorResponse) {
-      // Log validation issues
-      logger.warn("Validation error:", error.body.issues);
-    } else if (error instanceof UnauthorizedErrorResponse) {
-      // Handle auth errors
-      redirectToLogin();
-    }
-    throw error;
+  // ...
+} catch (error) {
+  if (error instanceof ValidationErrorResponse) {
+    // Handle validation errors
   }
-}
-
-// Usage
-const result = await handleApiCall(() =>
-  client.send(new GetUserRequestCommand({ param: { userId: "123" } }))
-);
-```
-
-### Testing
-
-```typescript
-// Mock clients for testing
-import { UsersClient } from "./api/generated";
-
-// Mock the client
-jest.mock("./api/generated/users/UsersClient");
-
-const mockClient = new UsersClient() as jest.Mocked<UsersClient>;
-mockClient.send.mockResolvedValue({
-  statusCode: 200,
-  body: { id: "123", name: "Test User" },
-});
-```
-
-## Integration Examples
-
-### React Hook
-
-```typescript
-import { useState, useEffect } from "react";
-import { UsersClient, GetUserRequestCommand } from "./api/generated";
-
-const client = new UsersClient({ baseURL: "https://api.example.com" });
-
-export function useUser(userId: string) {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  useEffect(() => {
-    async function fetchUser() {
-      try {
-        setLoading(true);
-        const result = await client.send(
-          new GetUserRequestCommand({
-            param: { userId },
-          })
-        );
-        setUser(result.body);
-      } catch (err) {
-        setError(err);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchUser();
-  }, [userId]);
-
-  return { user, loading, error };
-}
-```
-
-### Node.js Service
-
-```typescript
-import { UsersClient, CreateUserRequestCommand } from "./api/generated";
-
-export class UserService {
-  private client = new UsersClient({
-    baseURL: process.env.API_BASE_URL,
-  });
-
-  async createUser(userData: CreateUserRequest["body"]) {
-    const command = new CreateUserRequestCommand({
-      body: userData,
-      header: {
-        Authorization: `Bearer ${process.env.API_TOKEN}`,
-      },
-    });
-
-    return await this.client.send(command);
+  if (error instanceof InternalServerErrorResponse) {
+    // Handle internal server errors
   }
+  // ... Handle other errors
 }
 ```
 
-## Troubleshooting
-
-### Common Issues
-
-**Import errors**: Ensure all TypeWeaver plugins are installed **Type errors**: Regenerate code
-after API definition changes **Runtime errors**: Check that server API matches generated client
-expectations
-
-### Debug Mode
-
-Enable verbose logging:
-
-```typescript
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  debug: true, // Enable debug logging
-});
-```
-
-## License
+## 📄 License
 
-ISC © Dennis Wentzien 2025
+Apache 2.0 © Dennis Wentzien 2025

package/dist/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Dennis Wentzien
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/NOTICE

@@ -0,0 +1,4 @@
+Copyright 2025 Dennis Wentzien
+
+This project is licensed under the Apache License, Version 2.0
+See LICENSE file for details.

package/dist/index.js

@@ -1,8 +1,8 @@
-import { BasePlugin } from '@rexeus/typeweaver-gen';
 import path from 'path';
-import Case from 'case';
 import { fileURLToPath } from 'url';
+import { BasePlugin } from '@rexeus/typeweaver-gen';
 import { TsTypePrinter, TsTypeNode } from '@rexeus/typeweaver-zod-to-ts';
+import Case from 'case';
 
 const __dirname$1 = path.dirname(fileURLToPath(import.meta.url));
 class ClientGenerator {
@@ -13,13 +13,13 @@ class ClientGenerator {
       "templates",
       "RequestCommand.ejs"
     );
-    for (const [, operationResources] of Object.entries(
+    for (const [, entityResource] of Object.entries(
       context.resources.entityResources
     )) {
-      this.writeClient(clientTemplatePath, operationResources, context);
+      this.writeClient(clientTemplatePath, entityResource.operations, context);
       this.writeRequestCommands(
         commandTemplatePath,
-        operationResources,
+        entityResource.operations,
         context
       );
     }
@@ -80,30 +80,34 @@ class ClientGenerator {
     const pascalCaseOperationId = Case.pascal(operationId);
     const allResponses = responses;
     const ownSuccessResponses = allResponses.filter(
-      (r) => r.statusCode >= 200 && r.statusCode < 300 && !r.isShared
+      (r) => r.statusCode >= 200 && r.statusCode < 300 && !r.isReference
     );
     const ownErrorResponses = allResponses.filter(
-      (r) => (r.statusCode < 200 || r.statusCode >= 300) && !r.isShared
+      (r) => (r.statusCode < 200 || r.statusCode >= 300) && !r.isReference
     );
     const sharedSuccessResponses = allResponses.filter(
-      (r) => r.statusCode >= 200 && r.statusCode < 300 && r.isShared
+      (r) => r.statusCode >= 200 && r.statusCode < 300 && r.isReference
     );
     const sharedErrorResponses = allResponses.filter(
-      (r) => (r.statusCode < 200 || r.statusCode >= 300) && r.isShared
+      (r) => (r.statusCode < 200 || r.statusCode >= 300) && r.isReference
     );
     const headerTsType = request.header ? TsTypePrinter.print(TsTypeNode.fromZod(request.header)) : void 0;
     const paramTsType = request.param ? TsTypePrinter.print(TsTypeNode.fromZod(request.param)) : void 0;
     const queryTsType = request.query ? TsTypePrinter.print(TsTypeNode.fromZod(request.query)) : void 0;
     const bodyTsType = request.body ? TsTypePrinter.print(TsTypeNode.fromZod(request.body)) : void 0;
     const successResponseImportPath = (response) => {
-      if (response.isShared && response.path) {
+      if (response.isReference && response.path) {
         return response.path;
       }
       return `./${path.basename(outputResponseFileName, ".ts")}`;
     };
     const requestFile = `./${path.basename(outputRequestFileName, ".ts")}`;
     const responseValidatorFile = `./${path.basename(outputResponseValidationFileName, ".ts")}`;
-    const sourcePath = path.join(sourceDir, path.basename(sourceFile, ".ts"));
+    const relativeSourceFile = path.relative(sourceDir, sourceFile);
+    const sourcePath = path.join(
+      sourceDir,
+      relativeSourceFile.replace(/\.ts$/, "")
+    );
     const relativeSourcePath = path.relative(outputDir, sourcePath);
     const content = context.renderTemplate(templateFilePath, {
       sourcePath: relativeSourcePath,

package/dist/lib/ApiClient.ts

@@ -1,16 +1,25 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import axios, { AxiosError } from "axios";
 import type {
-  IHttpQuery,
-  IHttpParam,
   IHttpHeader,
+  IHttpParam,
+  IHttpQuery,
   IHttpResponse,
 } from "@rexeus/typeweaver-core";
 import { RequestCommand } from "./RequestCommand";
-import axios, {
-  AxiosError,
-  type AxiosInstance,
-  type AxiosResponse,
-} from "axios";
-import Case from "case";
+import type { ProcessResponseOptions } from "./RequestCommand";
+import type { AxiosHeaderValue, AxiosInstance, AxiosResponse } from "axios";
+
+/**
+ * Configuration options for handling unknown responses.
+ */
+export type UnknownResponseHandling = "throw" | "passthrough";
 
 /**
  * Configuration options for ApiClient initialization.
@@ -20,6 +29,10 @@ export type ApiClientProps = {
   axiosInstance?: AxiosInstance;
   /** Base URL for API requests. If not provided, must be set in axiosInstance */
   baseUrl?: string;
+  /** How to handle unknown responses. Defaults to "throw" */
+  unknownResponseHandling?: UnknownResponseHandling;
+  /** Predicate to determine if a status code represents success. Defaults to 2xx status codes */
+  isSuccessStatusCode?: (statusCode: number) => boolean;
 };
 
 /**
@@ -37,6 +50,10 @@ export abstract class ApiClient {
   public readonly axiosInstance: AxiosInstance;
   /** The base URL for all API requests */
   public readonly baseUrl: string;
+  /** How to handle unknown responses */
+  public readonly unknownResponseHandling: UnknownResponseHandling;
+  /** Predicate to determine if a status code represents success */
+  public readonly isSuccessStatusCode: (statusCode: number) => boolean;
 
   /**
    * Creates a new ApiClient instance.
@@ -53,6 +70,24 @@ export abstract class ApiClient {
         "Base URL must be provided either in axios instance or in constructor"
       );
     }
+
+    this.unknownResponseHandling = props.unknownResponseHandling ?? "throw";
+    this.isSuccessStatusCode =
+      props.isSuccessStatusCode ??
+      ((statusCode: number) => statusCode >= 200 && statusCode < 300);
+  }
+
+  /**
+   * Gets the process response options for this client instance.
+   *
+   * @returns The configuration options for processing responses
+   * @protected
+   */
+  protected get processResponseOptions(): ProcessResponseOptions {
+    return {
+      unknownResponseHandling: this.unknownResponseHandling,
+      isSuccessStatusCode: this.isSuccessStatusCode,
+    };
   }
 
   /**
@@ -109,28 +144,17 @@ export abstract class ApiClient {
         throw new Error("Network error: Unknown error");
       }
 
-      throw new Error(`Network error: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `Network error: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
 
   private createResponse(response: AxiosResponse): IHttpResponse {
-    const header: IHttpHeader = Object.entries(response.headers).reduce(
-      (acc, [key, value]) => {
-        if (!value) {
-          return acc;
-        }
-
-        const lowerCaseKey = key.toLowerCase();
-        const headerCaseKey = Case.header(lowerCaseKey);
-
-        return {
-          ...acc,
-          [headerCaseKey]: value,
-          [lowerCaseKey]: value,
-        };
-      },
-      {}
-    );
+    const header: IHttpHeader = {};
+    Object.entries(response.headers).forEach(([key, value]) => {
+      this.addMultiValue(header, key, String(value));
+    });
 
     return {
       body: response.data,
@@ -177,13 +201,32 @@ export abstract class ApiClient {
 
   private createUrl(path: string, query?: IHttpQuery): string {
     const url = new URL(path, this.baseUrl);
-
     this.addQuery(url, query);
-
     return url.toString();
   }
 
   private createHeader(header: any): any {
     return header;
   }
+
+  private addMultiValue(
+    record: Record<string, string | string[]>,
+    key: string,
+    value: AxiosHeaderValue
+  ): void {
+    const existing = record[key];
+    const preparedValue = Array.isArray(value)
+      ? value.map(String)
+      : [String(value)];
+    if (existing) {
+      if (Array.isArray(existing)) {
+        existing.push(...preparedValue);
+      } else {
+        record[key] = [existing, ...preparedValue];
+      }
+    } else {
+      record[key] =
+        preparedValue.length > 1 ? preparedValue : (preparedValue[0] as string);
+    }
+  }
 }

package/dist/lib/RequestCommand.ts

@@ -1,13 +1,29 @@
-import {
-  type HttpMethod,
-  type IHttpRequest,
-  type IHttpHeader,
-  type IHttpParam,
-  type IHttpQuery,
-  type IHttpBody,
-  type IHttpResponse,
-  HttpResponse,
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import { HttpResponse } from "@rexeus/typeweaver-core";
+import type {
+  HttpMethod,
+  IHttpBody,
+  IHttpHeader,
+  IHttpParam,
+  IHttpQuery,
+  IHttpRequest,
+  IHttpResponse,
 } from "@rexeus/typeweaver-core";
+import type { UnknownResponseHandling } from "./ApiClient";
+
+/**
+ * Configuration options for processing HTTP responses.
+ */
+export type ProcessResponseOptions = {
+  readonly unknownResponseHandling: UnknownResponseHandling;
+  readonly isSuccessStatusCode: (statusCode: number) => boolean;
+};
 
 /**
  * Abstract base class for type-safe API request commands.
@@ -55,7 +71,11 @@ export abstract class RequestCommand<
    * - Error response handling
    *
    * @param response - The raw HTTP response from the server
+   * @param options - Configuration options for response processing
    * @returns The processed, type-safe response object
    */
-  public abstract processResponse(response: IHttpResponse): HttpResponse;
+  public abstract processResponse(
+    response: IHttpResponse,
+    options: ProcessResponseOptions
+  ): HttpResponse;
 }

package/dist/lib/index.ts

@@ -1,2 +1,9 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
 export * from "./ApiClient";
 export * from "./RequestCommand";

package/dist/templates/Client.ejs

@@ -1,7 +1,17 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ * 
+ * @generated by @rexeus/typeweaver
+ */
+
 import { ApiClient, type ApiClientProps } from "../lib/clients";
 <% for (const operation of operations) { %>
 import { <%= operation.operationId %>RequestCommand } from "./<%= operation.operationId %>RequestCommand";
-import type { Successful<%= operation.operationId %>Response } from "<%= operation.requestFile %>";
+import type { 
+    Successful<%= operation.operationId %>Response
+} from "<%= operation.requestFile %>";
 <% } %>
 
 export type <%= pascalCaseEntityName %>RequestCommands =
@@ -25,16 +35,6 @@ export class <%= pascalCaseEntityName %>Client extends ApiClient {
     <% } %>
     public async send(command: <%= pascalCaseEntityName %>RequestCommands): Promise<Successful<%= pascalCaseEntityName %>Responses> {
         const response = await this.execute(command);
-
-        switch (true) {
-        <% for (const operation of operations) { %>
-            case command instanceof <%= operation.operationId %>RequestCommand: {
-                return command.processResponse(response);
-            }
-        <% } %>
-            default: {
-                throw new Error("Command is not supported");
-            }
-        }
+        return command.processResponse(response, this.processResponseOptions);
     }
 }

package/dist/templates/RequestCommand.ejs

@@ -1,6 +1,14 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ * 
+ * @generated by @rexeus/typeweaver
+ */
+
 import definition from "<%= sourcePath %>";
-import { HttpMethod, type IHttpResponse } from "@rexeus/typeweaver-core";
-import { RequestCommand } from "../lib/clients";
+import { HttpMethod, type IHttpResponse, ResponseValidationError, UnknownResponse } from "@rexeus/typeweaver-core";
+import { RequestCommand, type ProcessResponseOptions } from "../lib/clients";
 import { <%= pascalCaseOperationId %>ResponseValidator } from "<%= responseValidatorFile %>";
 import type {
     I<%= pascalCaseOperationId %>Request,
@@ -47,15 +55,36 @@ export class <%= pascalCaseOperationId %>RequestCommand extends RequestCommand i
         this.responseValidator = new <%= pascalCaseOperationId %>ResponseValidator();
     }
 
-    public processResponse(response: IHttpResponse): Successful<%= pascalCaseOperationId %>Response {
-        const result = this.responseValidator.validate(response);
+    public processResponse(
+        response: IHttpResponse, 
+        options: ProcessResponseOptions
+    ): Successful<%= pascalCaseOperationId %>Response {
+        try {
+            const result = this.responseValidator.validate(response);
 
-        <% for (const successResponse of [...ownSuccessResponses, ...sharedSuccessResponses]) { %>
-            if (result instanceof <%= successResponse.name %>Response) {
-                return result;
-            }
-        <% } %>
+            <% for (const successResponse of [...ownSuccessResponses, ...sharedSuccessResponses]) { %>
+                if (result instanceof <%= successResponse.name %>Response) {
+                    return result;
+                }
+            <% } %>
 
-        throw result;
+            throw result;
+        } catch (error) {
+            if (error instanceof ResponseValidationError) {
+                const unknownResponse = new UnknownResponse(
+                    response.statusCode,
+                    response.header,
+                    response.body,
+                    error
+                );
+
+                if (options.unknownResponseHandling === "passthrough" && options.isSuccessStatusCode(response.statusCode)) {
+                    return unknownResponse as any;
+                }
+
+                throw unknownResponse;
+            }
+            throw error;
+        }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rexeus/typeweaver-clients",
-  "version": "0.0.3",
-  "description": "HTTP client generator for TypeWeaver API framework",
+  "version": "0.1.0",
+  "description": "HTTP client generator for typeweaver API framework",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,9 @@
   "files": [
     "dist",
     "package.json",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "keywords": [
     "api",
@@ -26,7 +28,7 @@
     "typeweaver"
   ],
   "author": "Dennis Wentzien <dw@rexeus.com>",
-  "license": "ISC",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rexeus/typeweaver.git",
@@ -38,22 +40,25 @@
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
     "axios": "^1.7.0",
-    "@rexeus/typeweaver-core": "^0.0.3",
-    "@rexeus/typeweaver-gen": "^0.0.3"
+    "@rexeus/typeweaver-core": "^0.1.0",
+    "@rexeus/typeweaver-gen": "^0.1.0"
   },
   "devDependencies": {
-    "axios": "^1.9.0",
-    "@rexeus/typeweaver-core": "^0.0.3",
-    "@rexeus/typeweaver-gen": "^0.0.3"
+    "@hono/node-server": "^1.19.1",
+    "axios": "^1.11.0",
+    "test-utils": "file:../test-utils",
+    "@rexeus/typeweaver-gen": "^0.1.0",
+    "@rexeus/typeweaver-core": "^0.1.0"
   },
   "dependencies": {
     "case": "^1.6.3",
-    "@rexeus/typeweaver-zod-to-ts": "^0.0.3"
+    "@rexeus/typeweaver-zod-to-ts": "^0.1.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
-    "build": "pkgroll --clean-dist && cp -r ./src/templates ./dist/templates && cp -r ./src/lib ./dist/lib",
+    "build": "pkgroll --clean-dist && cp -r ./src/templates ./dist/templates && cp -r ./src/lib ./dist/lib && cp ../../LICENSE ../../NOTICE ./dist/",
+    "test": "vitest --run",
     "preversion": "npm run build"
   }
 }