docs: remove duplications

Author: johannschopplich

README.md

@@ -23,9 +23,6 @@ npm i -D apiful
 
 ## Usage
 
-> [!TIP]
-> [📖 Read the documentation](https://apiful.land)
-
 ### Your First API Client
 
 Create your first API client by initialising it with a base URL and a sample bearer token for authorization:
@@ -42,7 +39,7 @@ const client = createClient({
 ```
 
 > [!NOTE]
-> The `createClient` function returns an [`ApiClient`](https://apiful.land/reference/api-client) instance that does not yet have a call signature. You will need to add a base extension to the client in order to make API requests. Read on to learn how to do this.
+> The `createClient` function returns an [`ApiClient`](https://apiful.land/reference/api-client) instance that can't yet make requests. You'll need to add a handler extension to enable HTTP functionality. Read on to learn how to do this.
 
 ### Built-in Extensions
 
@@ -88,7 +85,7 @@ await api.users.post({ name: 'foo' })
 
 **What it does:**
 
-The `apiRouterBuilder` provides a jQuery-like and Axios-esque API for building and making API requests. It allows you to construct your API calls in a declarative way.
+The `apiRouterBuilder` provides a jQuery-like and Axios-style API for building and making API requests. It allows you to construct your API calls in a declarative way.
 
 </td></tr><tr><td width="500px" valign="top">
 
@@ -150,7 +147,7 @@ const extendedClient = client
 extendedClient.logDefaults() // { baseURL: 'https://api.example.com', headers: { Authorization: 'Bearer <your-bearer-token>' } }
 ```
 
-If you have specific requirements that are not covered by the included extensions, you can create your own extensions. Follow the [Custom Extensions](https://apiful.land/guide/custom-extensions) guide to learn more.
+If you have specific requirements that aren't covered by the included extensions, you can create your own extensions. Follow the [Custom Extensions](https://apiful.land/guide/custom-extensions) guide to learn more.
 
 ## Development
 

docs/extensions/api-router.md

@@ -3,7 +3,7 @@
 > [!NOTE]
 > This is a [handler extension](/guide/custom-extensions#handler-extension) and wraps [ofetch](https://github.com/unjs/ofetch) under the hood.
 
-The route builder extension gives you a jQuery-like and Axios-esque API to construct your API calls. This extension is particularly powerful for REST APIs with predictable URL patterns, as it generates zero runtime overhead for property access until you call an HTTP method, at which point it constructs the full URL path and delegates to the underlying HTTP client. This design makes it ideal for APIs with deep nesting (like `/api/v1/organizations/123/projects/456/tasks`) while maintaining excellent TypeScript intellisense throughout the chain:
+The route builder extension gives you a jQuery-like and Axios-style API to construct your API calls. This extension is particularly powerful for REST APIs with predictable URL patterns, as it generates zero runtime overhead for property access until you call an HTTP method, at which point it constructs the full URL path and delegates to the underlying HTTP client. This design makes it ideal for APIs with deep nesting (like `/api/v1/organizations/123/projects/456/tasks`) while maintaining excellent TypeScript intellisense throughout the chain:
 
 ```ts
 // GET request to <baseURL>/users

docs/extensions/ofetch.md

@@ -3,7 +3,7 @@
 > [!NOTE]
 > This is a [handler extension](/guide/custom-extensions#handler-extension) that wraps [ofetch](https://github.com/unjs/ofetch) under the hood.
 
-This built-in extension provides the most straightforward way to make HTTP requests with APIful. It wraps the battle-tested ofetch library with automatic JSON parsing, intelligent error handling, and request/response interception. Since it inherits all default options from the client, it is perfect for developers familiar with fetch or Axios who want enhanced capabilities without complexity.
+This built-in extension provides the most straightforward way to make HTTP requests with APIful. It wraps the battle-tested ofetch library with automatic JSON parsing, intelligent error handling, and request/response interception. Since it inherits all default options from the client, it's perfect for developers familiar with fetch or Axios who want enhanced capabilities without complexity.
 
 Import the `ofetchBuilder` extension and add it to your client:
 

docs/extensions/openapi.md

@@ -9,7 +9,7 @@ To use this extension, APIful must first generate TypeScript definitions from yo
 
 ## Prerequisites
 
-To keep the package size small, APIful does not include `openapi-typescript` as a dependency. Install the package using your preferred package manager:
+To keep the package size small, APIful doesn't include `openapi-typescript` as a dependency. Install the package using your preferred package manager:
 
 ::: code-group
   ```bash [pnpm]
@@ -24,7 +24,7 @@ To keep the package size small, APIful does not include `openapi-typescript` as
 :::
 
 > [!NOTE]
-> `openapi-typescript` is only needed during development for type generation. It will not be included in your production bundle.
+> `openapi-typescript` is only needed during development for type generation. It won't be included in your production bundle.
 
 ## TypeScript Definitions Generation
 
@@ -55,7 +55,7 @@ The type generation process uses `openapi-typescript` to parse your OpenAPI sche
 Done! You can now use the `OpenAPIBuilder` extension to create a type-safe API client. Make sure you pass the **service name** to it as a generic parameter, such as `OpenAPIBuilder<'petStore'>()`. Follow the next chapter for more details.
 
 > [!IMPORTANT]
-> Make sure the generated `apiful.d.ts` file is not excluded by your `tsconfig.json` configuration. TypeScript needs to find this file to provide typed definitions for your OpenAPI schema.
+> Make sure the generated `apiful.d.ts` file isn't excluded by your `tsconfig.json` configuration. TypeScript needs to find this file to provide typed definitions for your OpenAPI schema.
 
 > [!TIP]
 > Run the generate command whenever your OpenAPI schema changes to keep your types up-to-date. Consider adding it to your build process or a pre-commit hook.
@@ -98,7 +98,7 @@ declare const userResponse: {
 
 ## OpenAPI Path Parameters
 
-OpenAPI can define path parameters on given endpoints. They are typically declared as `/foo/{id}`. Unfortunately, the endpoint type is not defined as `/foo/10`. Thus, using the latter as the path will break type inference.
+OpenAPI can define path parameters on given endpoints. They are typically declared as `/foo/{id}`. Unfortunately, the endpoint type isn't defined as `/foo/10`. Thus, using the latter as the path will break type inference.
 
 Instead, use the property `path` to pass an object of the parameters. You can then use the declared path for type inference, and the type checker will ensure you provide all required path parameters. The parameters will be interpolated into the path before the request is made.
 
@@ -111,11 +111,11 @@ const response = await petStore('/foo/{id}', {
 ```
 
 > [!WARNING]
-> Incorrect parameters will not be reported at runtime. An incomplete path will be sent to the backend _as-is_.
+> Incorrect parameters won't be reported at runtime. An incomplete path will be sent to the backend _as-is_.
 
 ## Request Headers
 
-Add headers to the request using the `headers` field. All headers defined in the OpenAPI schema will be type checked. You can still add additional headers that are not defined in the schema, which will not be type checked.
+Add headers to the request using the `headers` field. All headers defined in the OpenAPI schema will be type checked. You can still add additional headers that aren't defined in the schema, which won't be type checked.
 
 ```ts
 const response = await petStore('/some/endpoint', {

docs/guide/cli.md

@@ -22,19 +22,7 @@ The CLI currently provides one primary command:
 
 Generates TypeScript definitions from OpenAPI schemas. This is the core command for enabling type-safe API clients.
 
-This command requires the `openapi-typescript` package, which APIful does not include by default to keep its package size small. Install the package using your preferred package manager:
-
-::: code-group
-  ```bash [pnpm]
-  pnpm add -D openapi-typescript
-  ```
-  ```bash [yarn]
-  yarn add -D openapi-typescript
-  ```
-  ```bash [npm]
-  npm install -D openapi-typescript
-  ```
-:::
+This command requires the `openapi-typescript` package. See the [OpenAPI extension prerequisites](/extensions/openapi#prerequisites) for installation instructions.
 
 > [!IMPORTANT]
 > You must have a valid `apiful.config.ts` file with service definitions before running this command.
@@ -62,7 +50,7 @@ This displays the following output:
 <<< @/snippets/generate-help.ansi
 
 > [!NOTE]
-> Although it is recommended to create an `apiful.config.ts` file with a [`defineApifulConfig`](/reference/define-apiful-config) default export, you can also write plain JavaScript (`.js`, `.mjs`, `.cjs`) or JSON (`.json`, `.json5`) configuration files.
+> Although it's recommended to create an `apiful.config.ts` file with a [`defineApifulConfig`](/reference/define-apiful-config) default export, you can also write plain JavaScript (`.js`, `.mjs`, `.cjs`) or JSON (`.json`, `.json5`) configuration files.
 
 #### Fragmented Output
 

docs/guide/custom-extensions.md

@@ -4,14 +4,7 @@ APIful's true power lies in its extensibility. You can chain multiple extensions
 
 ## Extension Types
 
-Before creating your first extension, it is essential to understand the two types of extensions available.
-
-APIful provides two types of extensions:
-
-- **Handler Extension**: Adds the callable signature to a client instance (e.g., `client('/path')`). This provides the core HTTP functionality.
-- **Methods Extension**: Adds methods to the client instance (e.g., `client.login()`, `client.cache.get()`). You can chain multiple method extensions.
-
-Both extension types are created using a builder function that receives the client instance and returns the extension function (handler) or object (methods). This builder pattern serves two essential purposes: it provides access to the client instance for reading default options and existing extensions, and it enables TypeScript's type inference to work correctly across the extension chain.
+Before creating your first extension, make sure you understand the [two types of extensions](/guide/extension-types) available: handler extensions (callable signature) and methods extensions (additional methods).
 
 > [!IMPORTANT]
 > Use `satisfies HandlerExtensionBuilder` or `satisfies MethodsExtensionBuilder` instead of declaring extension variables directly with these types. The `satisfies` operator is crucial here – it validates that your extension conforms to the expected interface while preserving the exact return type for downstream type inference, ensuring seamless integration with other extensions.

docs/guide/getting-started.md

@@ -2,7 +2,7 @@
 
 ## What Is This?
 
-APIful provides a unified interface to manage all your API interactions by setting up a client with default fetch options, such as the base API URL and headers. Extensions add a variety of features to the client through a sophisticated proxy-based architecture that maintains full TypeScript type safety while allowing runtime composition. This approach ensures that each extension can enhance or override behavior without breaking the client contract, while keeping bundle sizes minimal through intelligent tree-shaking.
+APIful provides a unified interface to manage all your API interactions by setting up a client with default fetch options, such as the base API URL and headers. Extensions add a variety of features to the client while maintaining full TypeScript type safety. Learn more about [how extensions work](/guide/using-extensions#how-extensions-work).
 
 You can use one of the [built-in extensions](/guide/using-extensions#built-in-extensions) to get started right away, or create your own [custom extension](/guide/custom-extensions) to meet your specific needs.
 
@@ -23,7 +23,7 @@ Get started by installing `apiful` in your project:
 :::
 
 > [!TIP]
-> APIful is designed as a development dependency since it is primarily used for generating types and building API clients during your build process.
+> APIful is designed as a development dependency since it's primarily used for generating types and building API clients during your build process.
 
 ## Your First API Client
 
@@ -41,7 +41,7 @@ const client = createClient({
 ```
 
 > [!NOTE]
-> The `createClient` function returns an [`ApiClient`](/reference/api-client) instance that cannot yet make requests. You will need to add a handler extension to enable HTTP functionality.
+> The `createClient` function returns an [`ApiClient`](/reference/api-client) instance that can't yet make requests. You'll need to add a handler extension to enable HTTP functionality.
 
 ## Choose a Built-in Extension
 
@@ -105,12 +105,8 @@ const extendedClient = client
 extendedClient.logDefaults() // { baseURL: 'https://api.example.com', headers: { Authorization: 'Bearer <your-bearer-token>' } }
 ```
 
-## Error Handling Across Extensions
-
-Each extension can implement its own error handling strategy, and errors propagate through the extension chain in a predictable manner. The ofetch extension automatically throws detailed errors with status codes and response bodies, while custom extensions can implement retry logic, circuit breakers, or custom error transformation. This layered approach allows higher-level extensions to catch and transform errors from lower-level ones, giving you complete control over how your application handles API failures.
-
 > [!IMPORTANT]
 > When chaining multiple extensions, later extensions override methods from earlier ones. This gives you fine-grained control over the final client behavior.
 
 > [!TIP]
-> If you have specific requirements that are not covered by the included extensions, you can create your own extensions. Follow the [Custom Extensions](/guide/custom-extensions) guide to learn more.
+> If you have specific requirements that aren't covered by the included extensions, you can create your own extensions. Follow the [Custom Extensions](/guide/custom-extensions) guide to learn more.

docs/guide/using-extensions.md

@@ -17,7 +17,7 @@ const client = createClient({
 ```
 
 > [!IMPORTANT]
-> The client by itself cannot make requests - you need at least one handler extension to provide the actual HTTP functionality.
+> The client by itself can't make requests – you need at least one handler extension to provide the actual HTTP functionality.
 
 > [!TIP]
 > Default options are automatically passed to all extensions, ensuring consistent configuration across your entire client.
@@ -42,7 +42,7 @@ Choose the extension that best fits your use case and personal preference:
 - **[API Router](/extensions/api-router)** - jQuery/Axios-style chaining with `client.users.get()`
 
 > [!TIP]
-> Start with the ofetch extension if you are new to APIful - it provides the most familiar API for developers coming from fetch or Axios.
+> Start with the ofetch extension if you're new to APIful – it provides the most familiar API for developers coming from fetch or Axios.
 
 ## Custom Extensions
 

docs/reference/create-openapi-client.md

@@ -7,27 +7,13 @@ Creates a type-safe OpenAPI client directly without using the APIful extension s
 Use `createOpenAPIClient` when you:
 
 - Want a direct, lightweight OpenAPI client
-- Don not need the extensibility features of the main APIful client system
+- Don't need the extensibility features of the main APIful client system
 - Prefer a simpler API without the `.with()` extension pattern
 - Want to avoid the additional abstraction layer
 
 ## Prerequisites
 
-Same as the [`OpenAPIBuilder`](/extensions/openapi) extension:
-
-::: code-group
-  ```bash [pnpm]
-  pnpm add -D openapi-typescript
-  ```
-  ```bash [yarn]
-  yarn add -D openapi-typescript
-  ```
-  ```bash [npm]
-  npm install -D openapi-typescript
-  ```
-:::
-
-You also need to generate TypeScript definitions using the [`generate`](/guide/cli) command.
+Same as the [`OpenAPIBuilder`](/extensions/openapi#prerequisites) extension – you need `openapi-typescript` installed and TypeScript definitions generated using the [`generate`](/guide/cli) command.
 
 ## Example
 
@@ -59,21 +45,6 @@ const userResponse = await petStore('/user/{username}', {
 | API complexity | ✅ Simple, direct API | ❌ More complex setup |
 | Customization | ❌ Limited to fetch options | ✅ Unlimited via extensions |
 
-## Example
-
-```ts
-import { createOpenAPIClient } from 'apiful'
-
-const petStore = createOpenAPIClient<'petStore'>({
-  baseURL: 'https://petstore3.swagger.io/api/v3',
-})
-
-const userResponse = await petStore('/user/{username}', {
-  method: 'GET',
-  path: { username: 'user1' },
-})
-```
-
 ## Type Definition
 
 ```ts

docs/utilities/http-status-codes.md

@@ -5,7 +5,7 @@ APIful provides all common HTTP status codes as constants. These are individuall
 All status codes defined in RFC1945 (HTTP/1.0), RFC2616 (HTTP/1.1), RFC2518 (WebDAV), RFC6585 (Additional HTTP Status Codes), and RFC7538 (Permanent Redirect) are supported.
 
 > [!TIP]
-> You may be wondering, why not use the [http-status-codes](https://www.npmjs.com/package/http-status-codes) package directly? Because the enums exported by the package do not work well with frameworks like Hono that use the `@hono/zod-openapi` type system.
+> You may be wondering, why not use the [http-status-codes](https://www.npmjs.com/package/http-status-codes) package directly? Because the enums exported by the package don't work well with frameworks like Hono that use the `@hono/zod-openapi` type system.
 
 ## Usage