@appweaver/cli 1.3.1 → 1.4.0

package/skill/references/client.md

@@ -1,599 +1,609 @@
-# Client
-
-`@appweaver/client` is a type-safe HTTP client generator and runtime library for consuming Appweaver APIs. It has two
-distinct parts:
-
-- **`weaver-client` CLI** — reads an OpenAPI v3 schema and emits TypeScript types and a typed client class.
-- **Runtime library** — provides `FetchClient` and a set of module clients used directly in application code.
-
----
-
-## Module formats (ESM & CommonJS)
-
-The package ships **both** an ESM and a CommonJS build, selected automatically via the `exports` map — no configuration
-needed. Both import styles work for the main entry and the `/angular` subpath:
-
-```ts
-// ESM (tree-shakable — preferred for bundlers like Angular/Vite/webpack prod builds)
-import { FetchClient, ClientError } from '@appweaver/client';
-import { AngularClient } from '@appweaver/client/angular';
-
-// CommonJS (e.g. plain Node scripts without a build step)
-const { FetchClient, ClientError } = require('@appweaver/client');
-const { AngularClient } = require('@appweaver/client/angular');
-```
-
----
-
-## `weaver-client` CLI
-
-```
-weaver-client <command>
-```
-
-| Command     | Alias | Description                                     |
-|-------------|-------|-------------------------------------------------|
-| `generate`  | `g`   | Generate TypeScript types and/or a client class |
-| `--version` | `-v`  | Output package version                          |
-| `--help`    | `-h`  | Output usage information                        |
-
----
-
-### `weaver-client generate`
-
-```
-weaver-client generate|g <schemaPath> [options]
-```
-
-Reads an OpenAPI v3 schema and generates TypeScript types and a typed client class.
-
-**Arguments:**
-
-| Argument       | Description                                                                                                                                                                                                                |
-|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `<schemaPath>` | Path to the OpenAPI schema. Accepts a relative or absolute file path (including a Windows drive path such as `C:\api\openapi.json`) or a URL (`http://`, `https://`, `file://`). JSON and YAML formats are both supported. |
-
-**Options:**
-
-| Option                | Description                                                                                | Default                   |
-|-----------------------|--------------------------------------------------------------------------------------------|---------------------------|
-| `--outputPath [path]` | Output path for both types and client (used when `--typesPath`/`--clientPath` are not set) | `./generated/client.ts`   |
-| `--typesPath [path]`  | Output path for generated TypeScript types only                                            | same as `outputPath`      |
-| `--clientPath [path]` | Output path for generated client class only                                                | same as `outputPath`      |
-| `--clientName [name]` | Custom name for the generated client class                                                 | derived from schema title |
-| `--framework [name]`  | Framework for the generated client class (`fetch` or `angular`)                            | `fetch`                   |
-| `--typesOnly`         | Generate TypeScript types only, skip client class generation                               | `false`                   |
-| `--clientOnly`        | Generate client class only, skip TypeScript types generation                               | `false`                   |
-| `--noTypes`           | Generate client class without TypeScript type support                                      | `false`                   |
-
-**Generation process:**
-
-1. Reads and parses the schema (JSON or YAML, local or remote).
-2. Generates TypeScript interfaces via `openapi-typescript`, enriching them with JSDoc validation tags (`@minLength`,
-   `@maxLength`, `@minimum`, `@maximum`, `@pattern`, `@format`).
-3. Deduplicates union types and extracts inline schemas to named exported types, including the ones carrying a
-   description (i.e. `PostQuerySort`).
-4. Hoists the schemas the document repeats inline into a shared definition each, so the generated types declare them
-   once and reference them everywhere else. This covers the enums (every sortable field of every resource shares one
-   `SortDirection` rather than declaring an `asc | desc` enum of its own) and the value a filterable field accepts
-   (`QueryFilterValue`, built from the plain `QueryFilterScalar`), while every property keeps its own description.
-5. Emits every enum as a constant object plus a type alias of its values, so both the member (`SortDirection.asc`) and
-   the plain literal (`'asc'`) are accepted wherever the enum is used. When the types are written to a declaration file
-   (`.d.ts`), the constant is declared rather than initialized, since such a file carries no runtime values.
-6. Classifies all API paths into route groups: resources, auth, account, health, files, and custom.
-7. Emits a typed client class extending `FetchClient<Paths>` with a getter for each route group. Resources with
-   unsupported operations are excluded at compile time using `Omit`.
-8. Formats all output with Prettier.
-9. Writes files with an autogenerated header comment.
-
-**Examples:**
-
-```bash
-# Generate types + client from a local OpenAPI file (single output file)
-weaver-client generate ./openapi.json --outputPath ./src/generated/client.ts
-
-# Generate types + client from a running server
-weaver-client generate http://localhost:3000/openapi.json --outputPath ./src/generated/client.ts
-
-# Generate types only
-weaver-client generate ./openapi.json --typesOnly --outputPath ./src/types/api.ts
-
-# Generate client class only
-weaver-client generate ./openapi.json --clientOnly --outputPath ./src/client.ts
-
-# Generate client class without TypeScript types
-weaver-client generate ./openapi.json --noTypes --outputPath ./src/client.ts
-
-# Separate output files with a custom class name
-weaver-client generate ./openapi.json \
-  --typesPath ./src/types/api.ts \
-  --clientPath ./src/client.ts \
-  --clientName CmsApiClient
-```
-
----
-
-## Typical end-to-end workflow
-
-```bash
-# 1. Export the OpenAPI spec from the running Appweaver API
-weaver openapi --outputPath ./openapi.json
-
-# 2. Generate the typed client
-weaver-client generate ./openapi.json --outputPath ./generated/client.ts
-
-# 3. Use the generated client in application code
-import { createClient } from './generated/client';
-
-const client = createClient({ baseUrl: 'http://localhost:3000', auth: { jwt: 'token' } });
-const users = await client.user.query({ filter: { enabled: true } });
-```
-
----
-
-## Generated output
-
-Running `weaver-client generate` produces one or two files depending on the options used.
-
-### Types file
-
-Contains all TypeScript interfaces and type aliases derived from the OpenAPI schema. The key export is the `paths`
-namespace used to parameterise `FetchClient`. Module-level types (`AuthModuleType`, `AccountModuleType`,
-`HealthModuleType`, per-resource `*ResourceModuleType`) are also exported and consumed by the client class.
-
-Every schema definition becomes an exported type named after it, so the request and response shapes can be referenced
-directly. The per-resource module type holds the same types under the keys the `ResourceClient` methods use:
-
-```ts
-import { PostQuerySort, SortDirection } from './generated/schema';
-
-const sort: PostQuerySort = { createdAt: SortDirection.desc, title: SortDirection.asc };
-const posts = await client.post.query({ sort, page: 1, size: 20 });
-```
-
-Enums are generated as a constant object together with a type alias of its values, so the members and the raw literals
-are interchangeable and no import is needed for the literal form:
-
-```ts
-export const SortDirection = { asc: 'asc', desc: 'desc' } as const;
-export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
-
-// Both are valid and equally type safe
-const byMember: PostQuerySort = { createdAt: SortDirection.desc };
-const byLiteral: PostQuerySort = { createdAt: 'desc' };
-```
-
-The value a filterable field accepts is declared once as well, rather than being spelled out again for every field of
-every resource. A scalar field references `QueryFilterValue`, and a relation field adds the filter of the related
-resource to the plain values it accepts:
-
-```ts
-export type QueryFilterScalar = string | number | boolean | null;
-export type QueryFilterValue = QueryFilterScalar | QueryFilterScalar[] | QueryCondition;
-
-export type PostQueryFilter = {
-  /** @description Filter by the title field */
-  title?: QueryFilterValue;
-  /** @description Filter by the author relation, matching an id, a list of ids, or a nested User filter */
-  author?: QueryFilterScalar | QueryFilterScalar[] | UserQueryFilter | UserQueryFilter[];
-  // ...
-};
-```
-
-### Client file
-
-```ts
-// Generated by Appweaver. Please do not edit this file manually.
-
-import { ClientConfig, FetchClient } from '@appweaver/client';
-import * as Type from './schema';
-
-export class CMSAPIClient extends FetchClient<Type.paths> {
-  public auth = this.authClient<Type.AuthModuleType>('/auth');
-
-  public account = this.accountClient<Type.AccountModuleType>('/auth/account');
-
-  public health = this.healthClient<Type.HealthModuleType>('/health');
-
-  public files = this.filesClient('/files');
-
-  // Resource with some operations excluded (compile-time Omit)
-  public apiKey = this.resourceClient<
-    Type.ApiKeyResourceModuleType,
-    ['aggregate', 'export', 'uploadFiles', 'deleteFiles']
-  >('/api/api-keys');
-
-  public post = this.resourceClient<Type.PostResourceModuleType, ['delete']>(
-    '/api/posts'
-  );
-
-  public user = this.resourceClient<Type.UserResourceModuleType>('/api/users');
-
-  // Custom routes that don't match a standard module
-  public info = this.customRequest('get', '/api/');
-  public postApiPublishPosts = this.customRequest('post', '/api/publish-posts');
-}
-
-export function createClient(config: ClientConfig): CMSAPIClient {
-  return new CMSAPIClient(config);
-}
-```
-
-The generated second type argument to `resourceClient` (e.g., `['aggregate', 'export', 'uploadFiles', 'deleteFiles']`)
-removes those methods from the returned `ResourceClient` at the TypeScript level, preventing accidental calls to
-operations not exposed by the API.
-
-### Angular client (`--framework angular`)
-
-Passing `--framework angular` generates a client class extending `AngularClient` instead of `FetchClient`. The generated
-class is constructed with Angular's `HttpClient` and all its methods return RxJS `Observable`s instead of
-`Promise`s:
-
-```ts
-import { ClientConfig, ClientError } from '@appweaver/client';
-import { AngularClient } from '@appweaver/client/angular';
-import { HttpClient } from '@angular/common/http';
-
-// In an Angular service or provider:
-const client = new CMSAPIClient(httpClient, { baseUrl: 'http://localhost:3000' });
-client.user.query({ filter: { enabled: true } }).subscribe((users) => {
-});
-```
-
-**Important:** `AngularClient` is only available from the `@appweaver/client/angular` subpath — it is not exported from
-the main `@appweaver/client` entry point. This keeps `rxjs` completely out of the module graph (runtime and types) for
-`FetchClient` users. `rxjs` is an **optional peer dependency**: Angular projects already have it installed, while
-fetch-only projects do not need it at all.
-
----
-
-## Runtime library
-
-### `ClientConfig`
-
-```ts
-type ClientConfig = {
-  baseUrl: string;           // Base URL prepended to every request path
-  timeout?: number;          // Request timeout in milliseconds
-  middlewares?: Middleware[]; // Additional openapi-fetch middlewares
-  auth?: AuthConfig;         // Authentication strategy
-};
-```
-
-### Authentication
-
-Exactly one authentication strategy may be provided via `auth`. Each strategy accepts a static value, a typed config
-object, or an async function that receives the outgoing `Request` and returns the auth value dynamically.
-
-```ts
-// JWT Bearer — plain token string
-let client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { jwt: 'my-access-token' }
-});
-
-// JWT Bearer — object with optional refresh token
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { jwt: { accessToken: 'access', refreshToken: 'refresh' } }
-});
-
-// JWT Bearer — dynamic async function
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { jwt: async (req) => await tokenStore.getToken() }
-});
-
-// API Key — plain string (uses X-Api-Key header by default)
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { apiKey: 'my-api-key' }
-});
-
-// API Key — custom header name
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { apiKey: { key: 'my-api-key', header: 'X-Custom-Key' } }
-});
-
-// HTTP Basic — plain Base64 string
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { basic: btoa('user:pass') }
-});
-
-// HTTP Basic — username/password object (auto-encodes)
-client = createClient({
-  baseUrl: 'https://api.example.com',
-  auth: { basic: { username: 'user', password: 'pass' } }
-});
-```
-
-### Request timeout
-
-```ts
-const client = createClient({
-  baseUrl: 'https://api.example.com',
-  timeout: 5000 // abort requests after 5 seconds
-});
-```
-
-### Custom middlewares
-
-Additional `openapi-fetch` middlewares are applied after the built-in timeout and auth middlewares:
-
-```ts
-const client = createClient({
-  baseUrl: 'https://api.example.com',
-  middlewares: [
-    {
-      async onRequest({ request }) {
-        request.headers.set('X-Request-Id', crypto.randomUUID());
-        return request;
-      }
-    }
-  ]
-});
-```
-
----
-
-## Module clients
-
-### `ResourceClient`
-
-Exposes CRUD and file operations for a single resource endpoint.
-
-| Method                         | HTTP                                 | Description                                              |
-|--------------------------------|--------------------------------------|----------------------------------------------------------|
-| `find(id, options?)`           | `GET /{resource}/{id}`               | Fetch a single record by ID                              |
-| `query(request, options?)`     | `POST /{resource}/query`             | Filter, sort, and paginate the collection                |
-| `aggregate(request, options?)` | `POST /{resource}/aggregate`         | Aggregation query (count, sum, avg, etc.)                |
-| `create(resource, options?)`   | `POST /{resource}`                   | Create a new record                                      |
-| `update(resource, options?)`   | `PUT /{resource}/{id}`               | Update an existing record (`resource` must include `id`) |
-| `delete(id, options?)`         | `DELETE /{resource}/{id}`            | Delete a record by ID                                    |
-| `export(request, options?)`    | `POST /{resource}/export`            | Export collection as a file; returns `FileDataResponse`  |
-| `uploadFiles(files, options?)` | `POST /{resource}/{id}/files`        | Upload files to a record                                 |
-| `deleteFiles(files, options?)` | `POST /{resource}/{id}/delete-files` | Remove files from a record                               |
-
-```ts
-// Find a single record
-const post = await client.post.find(1);
-
-// Query with filters, sorting and pagination. The sort accepts a comma-separated
-// field list ('-createdAt,id') or an object of field directions
-const result = await client.post.query({
-  filter: { published: true },
-  sort: { author: { lastName: 'asc' }, createdAt: 'desc' },
-  page: 1,
-  size: 20
-});
-
-// Aggregate. The select holds the operators to apply per numeric or date field
-const stats = await client.post.aggregate({
-  select: { counter: { count: true, sum: true }, createdAt: { min: true } },
-  dateField: 'createdAt'
-});
-
-// Create
-const newPost = await client.post.create({ title: 'Hello', body: '...' });
-
-// Update (id must be part of the payload)
-const updated = await client.post.update({ id: 1, title: 'Updated' });
-
-// Delete
-const deleted = await client.post.delete(1);
-
-// Export as CSV
-const file = await client.post.export({ filter: { published: true } });
-// file.body — ReadableStream, file.filename — string, file.contentType — string
-
-// Upload files
-const files = await client.post.uploadFiles({ cover: new File([], 'cover.jpg') });
-
-// Delete files
-await client.post.deleteFiles({ fileIds: [42, 43] });
-```
-
-### `AuthClient`
-
-| Method                              | HTTP                         | Description                                 |
-|-------------------------------------|------------------------------|---------------------------------------------|
-| `login(request, options?)`          | `POST /auth/login`           | Authenticate with credentials               |
-| `logout(options?)`                  | `POST /auth/logout`          | Invalidate the current session              |
-| `refresh(options?)`                 | `POST /auth/refresh`         | Renew access token                          |
-| `changePassword(request, options?)` | `POST /auth/change-password` | Change the authenticated user's password    |
-| `exchangeToken(request, options?)`  | `POST /auth/exchange-token`  | Exchange a third-party token for app tokens |
-| `me(options?)`                      | `GET /auth/me`               | Get the current user's identity             |
-
-```ts
-const session = await client.auth.login({ email: 'user@example.com', password: 'secret' });
-const me = await client.auth.me();
-await client.auth.logout();
-```
-
-### `AccountClient`
-
-| Method                                 | HTTP                                      | Description                        |
-|----------------------------------------|-------------------------------------------|------------------------------------|
-| `sendVerifyEmail(request, options?)`   | `POST /auth/account/send-verify-email`    | Send email verification link       |
-| `verifyEmail(request, options?)`       | `POST /auth/account/verify-email`         | Verify email with token            |
-| `verifyEmailRedirect(token, options?)` | `GET /auth/account/verify-email-redirect` | Handle redirect-based verification |
-| `sendResetPassword(request, options?)` | `POST /auth/account/send-reset-password`  | Send password reset email          |
-| `resetPassword(request, options?)`     | `POST /auth/account/reset-password`       | Reset password with token          |
-| `send2FACode(request, options?)`       | `POST /auth/account/send-2fa-code`        | Send a 2FA code to the user        |
-| `verify2FACode(request, options?)`     | `POST /auth/account/verify-2fa-code`      | Verify a submitted 2FA code        |
-
-```ts
-await client.account.sendVerifyEmail({ email: 'user@example.com' });
-await client.account.verifyEmail({ token: 'abc123' });
-await client.account.sendResetPassword({ email: 'user@example.com' });
-await client.account.resetPassword({ token: 'abc123', password: 'newpass' });
-```
-
-### `HealthClient`
-
-| Method            | HTTP                | Description         |
-|-------------------|---------------------|---------------------|
-| `check(options?)` | `GET /health`       | Health check status |
-| `ready(options?)` | `GET /health/ready` | Readiness probe     |
-
-```ts
-const status = await client.health.check();
-```
-
-### `FilesClient`
-
-| Method                      | HTTP                  | Description               |
-|-----------------------------|-----------------------|---------------------------|
-| `public(path, options?)`    | `GET /files/{path}`   | Download a public file    |
-| `protected(path, options?)` | `GET /files/p/{path}` | Download a protected file |
-
-```ts
-const file = await client.files.public('images/photo.jpg');
-const fileData = await file.base64(); // or use file.stream to pipe output to file etc.
-```
-
-### `FileDataResponse`
-
-Both `FilesClient` methods and `ResourceClient.export` return a `FileDataResponse` instance instead of a raw response
-body. It exposes file metadata as properties and provides helper methods to consume the content.
-
-**Properties:**
-
-| Property    | Type                | Description                                                     |
-|-------------|---------------------|-----------------------------------------------------------------|
-| `stream`    | `ReadableStream`    | Readable stream of the file content                             |
-| `fileName`  | `string`            | File name extracted from the `Content-Disposition` header       |
-| `type`      | `string`            | MIME type from the `Content-Type` header                        |
-| `length`    | `number`            | File size in bytes from the `Content-Length` header             |
-| `range`     | `FileContentRange?` | Byte range info present on partial-content (HTTP 206) responses |
-| `maxAge`    | `number?`           | Cache duration in seconds from `Cache-Control: max-age`         |
-| `expiresAt` | `string?`           | Expiration timestamp from the `Expires` header                  |
-
-**Methods:**
-
-| Method                   | Returns                | Description                                                           |
-|--------------------------|------------------------|-----------------------------------------------------------------------|
-| `buffer()`               | `Promise<ArrayBuffer>` | Raw binary content as an `ArrayBuffer`                                |
-| `blob()`                 | `Promise<Blob>`        | Content wrapped in a `Blob` with the correct MIME type                |
-| `text(encoding: string)` | `Promise<string>`      | Content decoded to string using specified encoding (default is UTF-8) |
-| `base64()`               | `Promise<string>`      | Content as a Base64 data URL (`data:<type>;base64,...`)               |
-
-The stream is read lazily on the first call to any consumption method, and the result is cached — later calls return the
-same `ArrayBuffer` without re-reading the stream.
-
-The `FileContentRange` type describes a partial-content range:
-
-```ts
-type FileContentRange = {
-  start: number;  // Starting byte position (inclusive)
-  end: number;    // Ending byte position (inclusive)
-  total: number;  // Total size of the complete file in bytes
-};
-```
-
-**Examples:**
-
-```ts
-// Download a public file and convert to a data URL for display
-let file = await client.files.public('images/photo.jpg');
-const dataUrl = await file.base64();
-img.src = dataUrl;
-
-// Download a protected file and save as a Blob
-file = await client.files.protected('reports/data.pdf');
-const blob = await file.blob();
-const url = URL.createObjectURL(blob);
-
-// Export a resource collection as CSV and read as text
-file = await client.post.export({ filter: { published: true } });
-const csv = await file.text();
-
-// Inspect metadata before consuming
-console.log(file.fileName); // e.g. "export.csv"
-console.log(file.type);     // e.g. "text/csv"
-console.log(file.length);   // e.g. 4096
-```
-
----
-
-## Direct requests
-
-### `sendRequest`
-
-Sends a typed request and returns the parsed response body. Throws `ClientError` on any non-2xx response.
-
-```ts
-const data = await client.sendRequest('get', '/api/custom-endpoint');
-```
-
-### `sendRequestRaw`
-
-Returns the raw `{ data, error, response }` tuple from `openapi-fetch` without throwing. Useful when the caller needs to
-inspect error details or branch on status codes.
-
-```ts
-const { data, error, response } = await client.sendRequestRaw('post', '/api/custom-endpoint', {
-  body: { key: 'value' }
-});
-
-if (error) {
-  console.error(`Failed with ${response.status}`);
-} else {
-  console.log(data);
-}
-```
-
-### `getClient`
-
-Returns the underlying `openapi-fetch` `Client` instance for advanced use cases not covered by the helper methods.
-
-```ts
-const rawClient = client.getClient();
-const { data } = await rawClient.GET('/api/custom-endpoint');
-```
-
-### Custom request (generated)
-
-Routes that do not match any standard module pattern are exposed via `customRequest` in the generated class:
-
-```ts
-// In the generated client:
-const postApiPublishPosts = this.customRequest('post', '/api/publish-posts');
-
-// Usage:
-const result = await client.postApiPublishPosts({ body: { ids: [1, 2, 3] } });
-```
-
----
-
-## Error handling
-
-All module client methods and `sendRequest` throw `ClientError` on non-2xx responses:
-
-```ts
-import { ClientError } from '@appweaver/client';
-
-try {
-  const post = await client.post.find(999);
-} catch (err) {
-  if (err instanceof ClientError) {
-    console.error(err.message);        // Error message from the API response body
-    console.error(err.errorCode);      // HTTP status code (or API errorCode field)
-    console.error(err.response);       // Native Response object
-  }
-}
-```
-
-Use `sendRequestRaw` to avoid exceptions and handle errors inline:
-
-```ts
-const { data, error, response } = await client.sendRequestRaw('get', '/api/posts/{id}', {
-  params: { path: { id: 999 } }
-});
-
-if (response.status === 404) {
-  // handle not found
-}
-```
+# Client
+
+`@appweaver/client` is a type-safe HTTP client generator and runtime library for consuming Appweaver APIs. It has two
+distinct parts:
+
+- **`weaver-client` CLI** — reads an OpenAPI v3 schema and emits TypeScript types and a typed client class.
+- **Runtime library** — provides `FetchClient` and a set of module clients used directly in application code.
+
+---
+
+## Module formats (ESM & CommonJS)
+
+The package ships **both** an ESM and a CommonJS build, selected automatically via the `exports` map — no configuration
+needed. Both import styles work for the main entry and the `/angular` subpath:
+
+```ts
+// ESM (tree-shakable — preferred for bundlers like Angular/Vite/webpack prod builds)
+import { FetchClient, ClientError } from '@appweaver/client';
+import { AngularClient } from '@appweaver/client/angular';
+
+// CommonJS (e.g. plain Node scripts without a build step)
+const { FetchClient, ClientError } = require('@appweaver/client');
+const { AngularClient } = require('@appweaver/client/angular');
+```
+
+---
+
+## `weaver-client` CLI
+
+```
+weaver-client <command>
+```
+
+| Command     | Alias | Description                                     |
+|-------------|-------|-------------------------------------------------|
+| `generate`  | `g`   | Generate TypeScript types and/or a client class |
+| `--version` | `-v`  | Output package version                          |
+| `--help`    | `-h`  | Output usage information                        |
+
+---
+
+### `weaver-client generate`
+
+```
+weaver-client generate|g <schemaPath> [options]
+```
+
+Reads an OpenAPI v3 schema and generates TypeScript types and a typed client class.
+
+**Arguments:**
+
+| Argument       | Description                                                                                                                                                                                                                |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<schemaPath>` | Path to the OpenAPI schema. Accepts a relative or absolute file path (including a Windows drive path such as `C:\api\openapi.json`) or a URL (`http://`, `https://`, `file://`). JSON and YAML formats are both supported. |
+
+**Options:**
+
+| Option                | Description                                                                                | Default                   |
+|-----------------------|--------------------------------------------------------------------------------------------|---------------------------|
+| `--outputPath [path]` | Output path for both types and client (used when `--typesPath`/`--clientPath` are not set) | `./generated/client.ts`   |
+| `--typesPath [path]`  | Output path for generated TypeScript types only                                            | same as `outputPath`      |
+| `--clientPath [path]` | Output path for generated client class only                                                | same as `outputPath`      |
+| `--clientName [name]` | Custom name for the generated client class                                                 | derived from schema title |
+| `--framework [name]`  | Framework for the generated client class (`fetch` or `angular`)                            | `fetch`                   |
+| `--typesOnly`         | Generate TypeScript types only, skip client class generation                               | `false`                   |
+| `--clientOnly`        | Generate client class only, skip TypeScript types generation                               | `false`                   |
+| `--noTypes`           | Generate client class without TypeScript type support                                      | `false`                   |
+
+**Generation process:**
+
+1. Reads and parses the schema (JSON or YAML, local or remote).
+2. Generates TypeScript interfaces via `openapi-typescript`, enriching them with JSDoc validation tags (`@minLength`,
+   `@maxLength`, `@minimum`, `@maximum`, `@pattern`, `@format`).
+3. Deduplicates union types and extracts inline schemas to named exported types, including the ones carrying a
+   description (i.e. `PostQuerySort`).
+4. Hoists the schemas the document repeats inline into a shared definition each, so the generated types declare them
+   once and reference them everywhere else. This covers the enums (every sortable field of every resource shares one
+   `SortDirection` rather than declaring an `asc | desc` enum of its own) and the value a filterable field accepts
+   (`QueryFilterValue`, built from the plain `QueryFilterScalar`), while every property keeps its own description.
+5. Emits every enum as a constant object plus a type alias of its values, so both the member (`SortDirection.asc`) and
+   the plain literal (`'asc'`) are accepted wherever the enum is used. When the types are written to a declaration file
+   (`.d.ts`), the constant is declared rather than initialized, since such a file carries no runtime values.
+6. Classifies all API paths into route groups: resources, auth, account, health, files, and custom.
+7. Emits a typed client class extending `FetchClient<Paths>` with a getter for each route group. Resources with
+   unsupported operations are excluded at compile time using `Omit`.
+8. Formats all output with Prettier.
+9. Writes files with an autogenerated header comment.
+
+**Examples:**
+
+```bash
+# Generate types + client from a local OpenAPI file (single output file)
+weaver-client generate ./openapi.json --outputPath ./src/generated/client.ts
+
+# Generate types + client from a running server
+weaver-client generate http://localhost:3000/openapi.json --outputPath ./src/generated/client.ts
+
+# Generate types only
+weaver-client generate ./openapi.json --typesOnly --outputPath ./src/types/api.ts
+
+# Generate client class only
+weaver-client generate ./openapi.json --clientOnly --outputPath ./src/client.ts
+
+# Generate client class without TypeScript types
+weaver-client generate ./openapi.json --noTypes --outputPath ./src/client.ts
+
+# Separate output files with a custom class name
+weaver-client generate ./openapi.json \
+  --typesPath ./src/types/api.ts \
+  --clientPath ./src/client.ts \
+  --clientName CmsApiClient
+```
+
+---
+
+## Typical end-to-end workflow
+
+```bash
+# 1. Export the OpenAPI spec from the running Appweaver API
+weaver openapi --outputPath ./openapi.json
+
+# 2. Generate the typed client
+weaver-client generate ./openapi.json --outputPath ./generated/client.ts
+
+# 3. Use the generated client in application code
+import { createClient } from './generated/client';
+
+const client = createClient({ baseUrl: 'http://localhost:3000', auth: { jwt: 'token' } });
+const users = await client.user.query({ filter: { enabled: true } });
+```
+
+---
+
+## Generated output
+
+Running `weaver-client generate` produces one or two files depending on the options used.
+
+### Types file
+
+Contains all TypeScript interfaces and type aliases derived from the OpenAPI schema. The key export is the `paths`
+namespace used to parameterise `FetchClient`. Module-level types (`AuthModuleType`, `AccountModuleType`,
+`HealthModuleType`, per-resource `*ResourceModuleType`) are also exported and consumed by the client class.
+
+Every schema definition becomes an exported type named after it, so the request and response shapes can be referenced
+directly. The per-resource module type holds the same types under the keys the `ResourceClient` methods use:
+
+```ts
+import { PostQuerySort, SortDirection } from './generated/schema';
+
+const sort: PostQuerySort = { createdAt: SortDirection.desc, title: SortDirection.asc };
+const posts = await client.post.query({ sort, page: 1, size: 20 });
+```
+
+Enums are generated as a constant object together with a type alias of its values, so the members and the raw literals
+are interchangeable and no import is needed for the literal form:
+
+```ts
+export const SortDirection = { asc: 'asc', desc: 'desc' } as const;
+export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
+
+// Both are valid and equally type safe
+const byMember: PostQuerySort = { createdAt: SortDirection.desc };
+const byLiteral: PostQuerySort = { createdAt: 'desc' };
+```
+
+The value a filterable field accepts is declared once as well, rather than being spelled out again for every field of
+every resource. A scalar field references `QueryFilterValue`, and a relation field adds the filter of the related
+resource to the plain values it accepts:
+
+```ts
+export type QueryFilterScalar = string | number | boolean | null;
+export type QueryFilterValue = QueryFilterScalar | QueryFilterScalar[] | QueryCondition;
+
+export type PostQueryFilter = {
+  /** @description Filter by the title field */
+  title?: QueryFilterValue;
+  /** @description Filter by the author relation, matching an id, a list of ids, or a nested User filter */
+  author?: QueryFilterScalar | QueryFilterScalar[] | UserQueryFilter | UserQueryFilter[];
+  // ...
+};
+```
+
+### Client file
+
+```ts
+// Generated by Appweaver. Please do not edit this file manually.
+
+import { ClientConfig, FetchClient } from '@appweaver/client';
+import * as Type from './schema';
+
+export class CMSAPIClient extends FetchClient<Type.paths> {
+  public auth = this.authClient<Type.AuthModuleType>('/auth');
+
+  public account = this.accountClient<Type.AccountModuleType>('/auth/account');
+
+  public health = this.healthClient<Type.HealthModuleType>('/health');
+
+  public files = this.filesClient('/files');
+
+  // Resource with some operations excluded (compile-time Omit)
+  public apiKey = this.resourceClient<
+    Type.ApiKeyResourceModuleType,
+    ['aggregate', 'export', 'uploadFiles', 'deleteFiles']
+  >('/api/api-keys');
+
+  public post = this.resourceClient<Type.PostResourceModuleType, ['delete']>(
+    '/api/posts'
+  );
+
+  public user = this.resourceClient<Type.UserResourceModuleType>('/api/users');
+
+  // Custom routes that don't match a standard module
+  public info = this.customRequest('get', '/api/');
+  public postApiPublishPosts = this.customRequest('post', '/api/publish-posts');
+}
+
+export function createClient(config: ClientConfig): CMSAPIClient {
+  return new CMSAPIClient(config);
+}
+```
+
+The generated second type argument to `resourceClient` (e.g., `['aggregate', 'export', 'uploadFiles', 'deleteFiles']`)
+removes those methods from the returned `ResourceClient` at the TypeScript level, preventing accidental calls to
+operations not exposed by the API.
+
+### Angular client (`--framework angular`)
+
+Passing `--framework angular` generates a client class extending `AngularClient` instead of `FetchClient`. The generated
+class is constructed with Angular's `HttpClient` and all its methods return RxJS `Observable`s instead of
+`Promise`s:
+
+```ts
+import { ClientConfig, ClientError } from '@appweaver/client';
+import { AngularClient } from '@appweaver/client/angular';
+import { HttpClient } from '@angular/common/http';
+
+// In an Angular service or provider:
+const client = new CMSAPIClient(httpClient, { baseUrl: 'http://localhost:3000' });
+client.user.query({ filter: { enabled: true } }).subscribe((users) => {
+});
+```
+
+**Important:** `AngularClient` is only available from the `@appweaver/client/angular` subpath — it is not exported from
+the main `@appweaver/client` entry point. This keeps `rxjs` completely out of the module graph (runtime and types) for
+`FetchClient` users. `rxjs` is an **optional peer dependency**: Angular projects already have it installed, while
+fetch-only projects do not need it at all.
+
+---
+
+## Runtime library
+
+### `ClientConfig`
+
+```ts
+type ClientConfig = {
+  baseUrl: string;           // Base URL prepended to every request path
+  timeout?: number;          // Request timeout in milliseconds
+  middlewares?: Middleware[]; // Additional openapi-fetch middlewares
+  auth?: AuthConfig;         // Authentication strategy
+};
+```
+
+### Authentication
+
+Exactly one authentication strategy may be provided via `auth`. Each strategy accepts a static value, a typed config
+object, or an async function that receives the outgoing `Request` and returns the auth value dynamically.
+
+```ts
+// JWT Bearer — plain token string
+let client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { jwt: 'my-access-token' }
+});
+
+// JWT Bearer — object with optional refresh token
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { jwt: { accessToken: 'access', refreshToken: 'refresh' } }
+});
+
+// JWT Bearer — dynamic async function
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { jwt: async (req) => await tokenStore.getToken() }
+});
+
+// API Key — plain string (uses X-Api-Key header by default)
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { apiKey: 'my-api-key' }
+});
+
+// API Key — custom header name
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { apiKey: { key: 'my-api-key', header: 'X-Custom-Key' } }
+});
+
+// HTTP Basic — plain Base64 string
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { basic: btoa('user:pass') }
+});
+
+// HTTP Basic — username/password object (auto-encodes)
+client = createClient({
+  baseUrl: 'https://api.example.com',
+  auth: { basic: { username: 'user', password: 'pass' } }
+});
+```
+
+### Request timeout
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  timeout: 5000 // abort requests after 5 seconds
+});
+```
+
+### Custom middlewares
+
+Additional `openapi-fetch` middlewares are applied after the built-in timeout and auth middlewares:
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  middlewares: [
+    {
+      async onRequest({ request }) {
+        request.headers.set('X-Request-Id', crypto.randomUUID());
+        return request;
+      }
+    }
+  ]
+});
+```
+
+---
+
+## Module clients
+
+### `ResourceClient`
+
+Exposes CRUD and file operations for a single resource endpoint.
+
+| Method                         | HTTP                                 | Description                                              |
+|--------------------------------|--------------------------------------|----------------------------------------------------------|
+| `find(id, options?)`           | `GET /{resource}/{id}`               | Fetch a single record by ID                              |
+| `query(request, options?)`     | `POST /{resource}/query`             | Filter, sort, and paginate the collection                |
+| `aggregate(request, options?)` | `POST /{resource}/aggregate`         | Aggregation query (count, sum, avg, etc.)                |
+| `create(resource, options?)`   | `POST /{resource}`                   | Create a new record                                      |
+| `update(resource, options?)`   | `PUT /{resource}/{id}`               | Update an existing record (`resource` must include `id`) |
+| `delete(id, options?)`         | `DELETE /{resource}/{id}`            | Delete a record by ID                                    |
+| `export(request, options?)`    | `POST /{resource}/export`            | Export collection as a file; returns `FileDataResponse`  |
+| `uploadFiles(files, options?)` | `POST /{resource}/{id}/files`        | Upload files to a record                                 |
+| `deleteFiles(files, options?)` | `POST /{resource}/{id}/delete-files` | Remove files from a record                               |
+
+```ts
+// Find a single record
+const post = await client.post.find(1);
+
+// Query with filters, sorting and pagination. The sort accepts a comma-separated
+// field list ('-createdAt,title') or an object of field directions
+const result = await client.post.query({
+  filter: { published: true },
+  sort: { author: { lastName: 'asc' }, createdAt: 'desc' },
+  page: 1,
+  size: 20
+});
+
+// Page by cursor instead of by offset, sending back the cursor of the response
+// and skipping the count the first page already returned
+const next = await client.post.query({
+  filter: { published: true },
+  sort: { author: { lastName: 'asc' }, createdAt: 'desc' },
+  size: 20,
+  cursor: result.nextCursor,
+  totalCount: false
+});
+
+// Aggregate. The select holds the operators to apply per numeric or date field
+const stats = await client.post.aggregate({
+  select: { counter: { count: true, sum: true }, createdAt: { min: true } },
+  dateField: 'createdAt'
+});
+
+// Create
+const newPost = await client.post.create({ title: 'Hello', body: '...' });
+
+// Update (id must be part of the payload)
+const updated = await client.post.update({ id: 1, title: 'Updated' });
+
+// Delete
+const deleted = await client.post.delete(1);
+
+// Export as CSV
+const file = await client.post.export({ filter: { published: true } });
+// file.body — ReadableStream, file.filename — string, file.contentType — string
+
+// Upload files
+const files = await client.post.uploadFiles({ cover: new File([], 'cover.jpg') });
+
+// Delete files
+await client.post.deleteFiles({ fileIds: [42, 43] });
+```
+
+### `AuthClient`
+
+| Method                              | HTTP                         | Description                                 |
+|-------------------------------------|------------------------------|---------------------------------------------|
+| `login(request, options?)`          | `POST /auth/login`           | Authenticate with credentials               |
+| `logout(options?)`                  | `POST /auth/logout`          | Invalidate the current session              |
+| `refresh(options?)`                 | `POST /auth/refresh`         | Renew access token                          |
+| `changePassword(request, options?)` | `POST /auth/change-password` | Change the authenticated user's password    |
+| `exchangeToken(request, options?)`  | `POST /auth/exchange-token`  | Exchange a third-party token for app tokens |
+| `me(options?)`                      | `GET /auth/me`               | Get the current user's identity             |
+
+```ts
+const session = await client.auth.login({ email: 'user@example.com', password: 'secret' });
+const me = await client.auth.me();
+await client.auth.logout();
+```
+
+### `AccountClient`
+
+| Method                                 | HTTP                                      | Description                        |
+|----------------------------------------|-------------------------------------------|------------------------------------|
+| `sendVerifyEmail(request, options?)`   | `POST /auth/account/send-verify-email`    | Send email verification link       |
+| `verifyEmail(request, options?)`       | `POST /auth/account/verify-email`         | Verify email with token            |
+| `verifyEmailRedirect(token, options?)` | `GET /auth/account/verify-email-redirect` | Handle redirect-based verification |
+| `sendResetPassword(request, options?)` | `POST /auth/account/send-reset-password`  | Send password reset email          |
+| `resetPassword(request, options?)`     | `POST /auth/account/reset-password`       | Reset password with token          |
+| `send2FACode(request, options?)`       | `POST /auth/account/send-2fa-code`        | Send a 2FA code to the user        |
+| `verify2FACode(request, options?)`     | `POST /auth/account/verify-2fa-code`      | Verify a submitted 2FA code        |
+
+```ts
+await client.account.sendVerifyEmail({ email: 'user@example.com' });
+await client.account.verifyEmail({ token: 'abc123' });
+await client.account.sendResetPassword({ email: 'user@example.com' });
+await client.account.resetPassword({ token: 'abc123', password: 'newpass' });
+```
+
+### `HealthClient`
+
+| Method            | HTTP                | Description         |
+|-------------------|---------------------|---------------------|
+| `check(options?)` | `GET /health`       | Health check status |
+| `ready(options?)` | `GET /health/ready` | Readiness probe     |
+
+```ts
+const status = await client.health.check();
+```
+
+### `FilesClient`
+
+| Method                      | HTTP                  | Description               |
+|-----------------------------|-----------------------|---------------------------|
+| `public(path, options?)`    | `GET /files/{path}`   | Download a public file    |
+| `protected(path, options?)` | `GET /files/p/{path}` | Download a protected file |
+
+```ts
+const file = await client.files.public('images/photo.jpg');
+const fileData = await file.base64(); // or use file.stream to pipe output to file etc.
+```
+
+### `FileDataResponse`
+
+Both `FilesClient` methods and `ResourceClient.export` return a `FileDataResponse` instance instead of a raw response
+body. It exposes file metadata as properties and provides helper methods to consume the content.
+
+**Properties:**
+
+| Property    | Type                | Description                                                     |
+|-------------|---------------------|-----------------------------------------------------------------|
+| `stream`    | `ReadableStream`    | Readable stream of the file content                             |
+| `fileName`  | `string`            | File name extracted from the `Content-Disposition` header       |
+| `type`      | `string`            | MIME type from the `Content-Type` header                        |
+| `length`    | `number`            | File size in bytes from the `Content-Length` header             |
+| `range`     | `FileContentRange?` | Byte range info present on partial-content (HTTP 206) responses |
+| `maxAge`    | `number?`           | Cache duration in seconds from `Cache-Control: max-age`         |
+| `expiresAt` | `string?`           | Expiration timestamp from the `Expires` header                  |
+
+**Methods:**
+
+| Method                   | Returns                | Description                                                           |
+|--------------------------|------------------------|-----------------------------------------------------------------------|
+| `buffer()`               | `Promise<ArrayBuffer>` | Raw binary content as an `ArrayBuffer`                                |
+| `blob()`                 | `Promise<Blob>`        | Content wrapped in a `Blob` with the correct MIME type                |
+| `text(encoding: string)` | `Promise<string>`      | Content decoded to string using specified encoding (default is UTF-8) |
+| `base64()`               | `Promise<string>`      | Content as a Base64 data URL (`data:<type>;base64,...`)               |
+
+The stream is read lazily on the first call to any consumption method, and the result is cached — later calls return the
+same `ArrayBuffer` without re-reading the stream.
+
+The `FileContentRange` type describes a partial-content range:
+
+```ts
+type FileContentRange = {
+  start: number;  // Starting byte position (inclusive)
+  end: number;    // Ending byte position (inclusive)
+  total: number;  // Total size of the complete file in bytes
+};
+```
+
+**Examples:**
+
+```ts
+// Download a public file and convert to a data URL for display
+let file = await client.files.public('images/photo.jpg');
+const dataUrl = await file.base64();
+img.src = dataUrl;
+
+// Download a protected file and save as a Blob
+file = await client.files.protected('reports/data.pdf');
+const blob = await file.blob();
+const url = URL.createObjectURL(blob);
+
+// Export a resource collection as CSV and read as text
+file = await client.post.export({ filter: { published: true } });
+const csv = await file.text();
+
+// Inspect metadata before consuming
+console.log(file.fileName); // e.g. "export.csv"
+console.log(file.type);     // e.g. "text/csv"
+console.log(file.length);   // e.g. 4096
+```
+
+---
+
+## Direct requests
+
+### `sendRequest`
+
+Sends a typed request and returns the parsed response body. Throws `ClientError` on any non-2xx response.
+
+```ts
+const data = await client.sendRequest('get', '/api/custom-endpoint');
+```
+
+### `sendRequestRaw`
+
+Returns the raw `{ data, error, response }` tuple from `openapi-fetch` without throwing. Useful when the caller needs to
+inspect error details or branch on status codes.
+
+```ts
+const { data, error, response } = await client.sendRequestRaw('post', '/api/custom-endpoint', {
+  body: { key: 'value' }
+});
+
+if (error) {
+  console.error(`Failed with ${response.status}`);
+} else {
+  console.log(data);
+}
+```
+
+### `getClient`
+
+Returns the underlying `openapi-fetch` `Client` instance for advanced use cases not covered by the helper methods.
+
+```ts
+const rawClient = client.getClient();
+const { data } = await rawClient.GET('/api/custom-endpoint');
+```
+
+### Custom request (generated)
+
+Routes that do not match any standard module pattern are exposed via `customRequest` in the generated class:
+
+```ts
+// In the generated client:
+const postApiPublishPosts = this.customRequest('post', '/api/publish-posts');
+
+// Usage:
+const result = await client.postApiPublishPosts({ body: { ids: [1, 2, 3] } });
+```
+
+---
+
+## Error handling
+
+All module client methods and `sendRequest` throw `ClientError` on non-2xx responses:
+
+```ts
+import { ClientError } from '@appweaver/client';
+
+try {
+  const post = await client.post.find(999);
+} catch (err) {
+  if (err instanceof ClientError) {
+    console.error(err.message);        // Error message from the API response body
+    console.error(err.errorCode);      // HTTP status code (or API errorCode field)
+    console.error(err.response);       // Native Response object
+  }
+}
+```
+
+Use `sendRequestRaw` to avoid exceptions and handle errors inline:
+
+```ts
+const { data, error, response } = await client.sendRequestRaw('get', '/api/posts/{id}', {
+  params: { path: { id: 999 } }
+});
+
+if (response.status === 404) {
+  // handle not found
+}
+```