===============
LIBRARY RULES
===============
From library maintainers:
- Use the scoped packages @zimic/http, @zimic/fetch, and @zimic/interceptor.
- @zimic/interceptor: In createHttpInterceptor, `type` is optional and defaults to 'local'. Only set `type: 'remote'` when using an interceptor server.
- @zimic/interceptor: Local interceptor methods are synchronous: interceptor.clear(), interceptor.checkTimes(), and handler.with()/respond()/times()/checkTimes() return values directly.
- @zimic/interceptor: Remote interceptor methods return promises: await interceptor.clear(), interceptor.checkTimes(), and every handler chain before making requests.
- @zimic/interceptor: Remote interceptors need a running server, usually started as `zimic-interceptor server start --port <port> --ephemeral -- <test command>`. Their unhandled requests can only be rejected, not bypassed.
- @zimic/interceptor: Local interceptors in browsers require `zimic-interceptor browser init <publicDirectory>` before interceptor.start().
- @zimic/interceptor: handler.with() matches partially by default. Use `exact: true` only when extra headers, search params, or body fields must cause a mismatch.
- @zimic/fetch: The package follows the Fetch API: JSON request bodies must be serialized with JSON.stringify and sent with an explicit `content-type: application/json` header. Schema content-type inference affects types only.
- @zimic/fetch: The package does not throw on non-2xx responses. Check response.ok, throw response.error when needed, and narrow caught errors with fetch.isResponseError(error, method, path).
- @zimic/http, @zimic/fetch, @zimic/interceptor: Declare path params in schema keys as '/users/:userId'. When calling fetch, pass the concrete path, such as `/users/${id}`.

### createInterceptorServer usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/api/4-create-interceptor-server.md

Example of creating and starting an interceptor server, running a command, and stopping the server. The highlighted lines show the createInterceptorServer call with hostname and port options.

```typescript
import { spawn, SpawnOptions } from 'child_process';
import { createInterceptorServer } from '@zimic/interceptor/server';

async function runCommand(commandEntry: string, commandArguments: string[], options: SpawnOptions) {
  await new Promise<void>((resolve, reject) => {
    const commandProcess = spawn(commandEntry, commandArguments, options);

    commandProcess.once('error', (error) => {
      reject(error);
    });

    commandProcess.once('close', (code) => {
      if (code === 0) {
        resolve();
      } else {
        reject(new Error(`Command '${commandEntry}' exited with code ${code}`));
      }
    });
  });
}

// highlight-start
const server = createInterceptorServer({
  hostname: 'localhost',
  port: 3000,
});
// highlight-end

await server.start();

// Run a command when the server is ready, assuming the following format:
// node <script> -- <command> [...commandArguments]
const [commandEntry, ...commandArguments] = process.argv.slice(3);
await runCommand(commandEntry, commandArguments, { stdio: 'inherit' });

await server.stop();
process.exit(0);
```

--------------------------------

### package.json postinstall script for zimic-interceptor browser init

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/2-browser.md

Example of adding the `postinstall` script to `package.json` to run `zimic-interceptor browser init ./public` after installing or upgrading `@zimic/interceptor`.

```json
{
  "scripts": {
    // highlight-next-line
    "postinstall": "zimic-interceptor browser init ./public"
  }
}
```

--------------------------------

### Filter file example (filters.txt)

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/cli/1-typegen.md

Example filter file with comments and expressions. Each line is a filter expression; comments start with #. Includes positive and negative filters.

```text
# Include any endpoint starting with /users and having any HTTP method
* /users**

# Include any sub-endpoints of /posts with method GET.
GET /posts/**/*

# Include the endpoints /workspaces with methods GET, POST, or PUT.
GET,POST,PUT /workspaces

# Exclude endpoints to get user notifications
!GET /users/*/notifications/**/*
```

--------------------------------

### Install @zimic/http and @zimic/fetch with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install both packages using pnpm. @zimic/http is a peer dependency and must be installed.

```bash
pnpm add @zimic/http @zimic/fetch
```

--------------------------------

### fetch.onResponse listener example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Shows how to set fetch.onResponse to inspect a response after it is received. The example checks if the response matches GET /users and logs the 'content-encoding' header, then returns the response unchanged.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers: { 'content-encoding'?: string };
          body: User[];
        };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:80',
});

//  highlight-start
fetch.onResponse = (response) => {
  if (fetch.isResponse(response, 'GET', '/users')) {
    console.log(response.headers.get('content-encoding'));
  }
  return response;
};
//  highlight-end
```

--------------------------------

### Install @zimic/http and @zimic/fetch with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install both packages using npm. @zimic/http is a peer dependency and must be installed.

```bash
npm install @zimic/http @zimic/fetch --save
```

--------------------------------

### zimic-interceptor server command overview

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/1-server.md

Shows the available subcommands for `zimic-interceptor server`: `start` and `token`. The `start` command starts an interceptor server, and `token` manages remote interceptor authentication tokens.

```bash
zimic-interceptor server

Commands:
  zimic-interceptor server start [--onReady]   Start an interceptor server.
  zimic-interceptor server token               Manage remote interceptor
                                               authentication tokens.
```

--------------------------------

### Install @zimic/http and @zimic/fetch with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install both packages using yarn. @zimic/http is a peer dependency and must be installed.

```bash
yarn add @zimic/http @zimic/fetch
```

--------------------------------

### Install @zimic/http with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the stable version of @zimic/http using npm.

```bash
npm install @zimic/http --save
```

--------------------------------

### Using createFetch with a typed schema

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Creates a fetch instance with a base URL and default headers, then sends a GET request with search parameters. The response is typed, and the example checks for a 404 status and uses response.ok and response.error.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        searchParams: { query?: string };
      };
      response: {
        200: { body: User[] };
        404: { body: { message: string } };
        500: { body: { message: string } };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
  headers: { 'accept-language': 'en' },
});

const response = await fetch('/users', {
  method: 'GET',
  searchParams: { query: 'u' },
});

if (response.status === 404) {
  return null; // User not found
}

if (!response.ok) {
  throw response.error;
}

const users = await response.json();
return users; // User[]
```

--------------------------------

### zimic-interceptor server start options

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/1-server.md

Displays the usage and options for `zimic-interceptor server start`. The `onReady` positional is a command to run when the server is ready. Options include `--hostname`, `--port`, `--ephemeral`, `--log-unhandled-requests`, and `--tokens-dir`.

```bash
zimic-interceptor server start [-- onReady]

Positionals:
  onReady  A command to run when the server is ready to accept connections.
                                                                        [string]

Options:
  -h, --hostname                The hostname to start the server on.
                                                 [string] [default: "localhost"]
  -p, --port                    The port to start the server on.        [number]
  -e, --ephemeral               Whether the server should stop automatically
                                after the on-ready command finishes. If no
                                on-ready command is provided and ephemeral is
                                true, the server will stop immediately after
                                starting.             [boolean] [default: false]
  -l, --log-unhandled-requests  Whether to log a warning when no interceptors
                                were found for the base URL of a request. If an
                                interceptor was matched, the logging behavior
                                for that base URL is configured in the
                                interceptor itself.                    [boolean]
  -t, --tokens-dir              The directory where the authorized interceptor
                                authentication tokens are saved. If provided,
                                only remote interceptors bearing a valid token
                                will be accepted. While authentication is
                                optional for private development servers, it is
                                strongly recommended when the server is not
                                bound to localhost, 127.0.0.1, or ::1, or when
                                it is shared over a network.            [string]
```

--------------------------------

### Install @zimic/http with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the stable version of @zimic/http using pnpm.

```bash
pnpm add @zimic/http
```

--------------------------------

### Install @zimic/http with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the stable version of @zimic/http using yarn.

```bash
yarn add @zimic/http
```

--------------------------------

### fetch.onRequest listener example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Shows how to set fetch.onRequest to modify a request before it is sent. The example checks if the request matches GET /users, appends a 'limit' search parameter, and returns a new Request. Otherwise, it returns the original request.

```TypeScript
import { createFetch } from '@zimic/fetch';
import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        searchParams: { page?: number; limit?: number };
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:80',
});

//  highlight-start
fetch.onRequest = (request) => {
  if (fetch.isRequest(request, 'GET', '/users')) {
    const url = new URL(request.url);
    url.searchParams.append('limit', '10');

    const updatedRequest = new Request(url, request);
    return updatedRequest;
  }

  return request;
};
//  highlight-end
```

--------------------------------

### Jest/Vitest setup for local interceptor (tests/setup.ts)

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/10-testing.mdx

Setup file using beforeAll, beforeEach, afterEach, and afterAll hooks to manage a local interceptor lifecycle. Calls interceptor.start(), interceptor.clear(), interceptor.checkTimes(), and interceptor.stop(). For local interceptors, clear() and checkTimes() are synchronous and do not need await.

```TypeScript
beforeAll(async () => {
  // Start intercepting requests
  // highlight-next-line
  await interceptor.start();
});

beforeEach(() => {
  // Clear interceptors so that no tests affect each other
  // highlight-next-line
  interceptor.clear();
});

afterEach(() => {
  // Check that all expected requests were made
  // highlight-next-line
  interceptor.checkTimes();
});

afterAll(async () => {
  // Stop intercepting requests
  // highlight-next-line
  await interceptor.stop();
});
```

--------------------------------

### HttpSchema.Headers usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Shows how to use HttpSchema.Headers to define request headers for a GET /users endpoint.

```TypeScript
import { HttpSchema } from '@zimic/http';

type UserListHeaders = HttpSchema.Headers<{
  accept: 'application/json';
}>;

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        headers: UserListHeaders;
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;
```

--------------------------------

### zimic-interceptor server start

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/1-server.md

Starts an interceptor server. Accepts an optional on-ready command and various options to configure the server's hostname, port, ephemeral behavior, logging, and token-based authentication.

```APIDOC
## zimic-interceptor server start

### Description
Starts an interceptor server. The server can be configured with a hostname, port, ephemeral mode, logging behavior, and optional token-based authentication.

### Command
`zimic-interceptor server start [--onReady]`

### Positionals
- **onReady** (string) - Optional - A command to run when the server is ready to accept connections.

### Options
- **-h, --hostname** (string) - Optional - The hostname to start the server on. Default: `"localhost"`.
- **-p, --port** (number) - Optional - The port to start the server on.
- **-e, --ephemeral** (boolean) - Optional - Whether the server should stop automatically after the on-ready command finishes. If no on-ready command is provided and ephemeral is true, the server will stop immediately after starting. Default: `false`.
- **-l, --log-unhandled-requests** (boolean) - Optional - Whether to log a warning when no interceptors were found for the base URL of a request. If an interceptor was matched, the logging behavior for that base URL is configured in the interceptor itself.
- **-t, --tokens-dir** (string) - Optional - The directory where the authorized interceptor authentication tokens are saved. If provided, only remote interceptors bearing a valid token will be accepted. While authentication is optional for private development servers, it is strongly recommended when the server is not bound to localhost, 127.0.0.1, or ::1, or when it is shared over a network.

### Notes
- Interceptor servers are development and test tools. Do not use them as production application servers.
- Although `--tokens-dir` is optional for private development servers, it is strongly recommended when the server is not bound to `localhost`, `127.0.0.1`, or `::1`, or when it is shared over a network. Authentication prevents unauthorized remote interceptors from connecting to the server. Use `server token create` to protect your interceptor server with a token, then configure each remote interceptor with `auth.token`.
- Without `--tokens-dir`, browser remote interceptors can connect only when both the server and the web application use a loopback hostname. Starting an unauthenticated server logs a warning when it uses a non-loopback hostname or runs with `NODE_ENV=production`.
- In `@zimic/interceptor` v2, an unauthenticated server will refuse to start on a non-loopback hostname.
```

--------------------------------

### Mocking a GET request with @zimic/interceptor and @zimic/fetch

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/guides/7-testing.md

Create an interceptor using the same schema as @zimic/fetch, start it, and mock a GET /users response. The mocked request returns the defined body, demonstrating type-safe mocking.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';
import { createHttpInterceptor } from '@zimic/interceptor/http';

type Schema = HttpSchema<{
  // ...
}>;

// highlight-next-line
const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

// highlight-next-line
const interceptor = createHttpInterceptor<Schema>({
  baseURL: fetch.baseURL,
});

await interceptor.start();

// highlight-start
interceptor.get('/users').respond({
  status: 200,
  body: [{ username: 'zimic' }],
});
// highlight-end

// Mocked! 🎉
// highlight-next-line
const response = await fetch('/users', { method: 'GET' });

const users = await response.json();
console.log(users); // [{ username: 'zimic' }]
```

--------------------------------

### HttpSchema.Response usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Shows how to use HttpSchema.Response to define a success response body for a GET /users endpoint.

```TypeScript
import { HttpSchema } from '@zimic/http';

type UserListSuccessResponse = HttpSchema.Response<{
  body: User[];
}>;

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: UserListSuccessResponse;
      };
    };
  };
}>;
```

--------------------------------

### HttpSchema.Body usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Shows how to use HttpSchema.Body to define a response body for a GET /users endpoint.

```TypeScript
import { HttpSchema } from '@zimic/http';

type UserListSuccessResponseBody = HttpSchema.Body<User[]>;

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: { body: UserListSuccessResponseBody };
      };
    };
  };
}>;
```

--------------------------------

### Jest/Vitest setup for remote interceptor (tests/setup.ts)

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/10-testing.mdx

Setup file using beforeAll, beforeEach, afterEach, and afterAll hooks to manage a remote interceptor lifecycle. Calls interceptor.start(), interceptor.clear(), interceptor.checkTimes(), and interceptor.stop(). For remote interceptors, clear() and checkTimes() are asynchronous and must be awaited.

```TypeScript
beforeAll(async () => {
  // Start intercepting requests
  // highlight-next-line
  await interceptor.start();
});

beforeEach(() => {
  // Clear interceptors so that no tests affect each other
  // highlight-next-line
  await interceptor.clear();
});

afterEach(() => {
  // Check that all expected requests were made
  // highlight-next-line
  await interceptor.checkTimes();
});

afterAll(async () => {
  // Stop intercepting requests
  // highlight-next-line
  await interceptor.stop();
});
```

--------------------------------

### HttpSchema.SearchParams usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Shows how to use HttpSchema.SearchParams to define search parameters for a GET /users endpoint.

```TypeScript
import { HttpSchema } from '@zimic/http';

type UserListSearchParams = HttpSchema.SearchParams<{
  limit: `${number}`;
  offset: `${number}`;
}>;

type Schema = HttpSchema<{
  '/users': {
    GET: {
      request: {
        searchParams: UserListSearchParams;
      };
      response: {
        200: { body: User[] };
      };
    };
  };
}>;
```

--------------------------------

### Start the interceptor server with tokens directory

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/2-remote-http-interceptors.md

Start the server with the --tokens-dir option pointing to the directory where tokens are saved. The server will only accept remote interceptors bearing a valid token.

```bash
zimic-interceptor server start --port 3000 \
  --tokens-dir .zimic/interceptor/server/tokens
```

--------------------------------

### Install canary releases with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install the latest canary versions of @zimic/http and @zimic/fetch using pnpm. Canary releases may include unstable or breaking changes.

```bash
pnpm add @zimic/http@canary @zimic/fetch@canary
```

--------------------------------

### interceptor.start()

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/api/2-http-interceptor.mdx

Starts the interceptor, allowing it to intercept HTTP requests. Returns a Promise that resolves when the interceptor has started.

```APIDOC
## Method: `interceptor.start()`

### Description
Starts the interceptor, allowing it to intercept HTTP requests.

### Returns
`Promise<void>`

### Example
```ts
await interceptor.start();
```

```

--------------------------------

### Usage example with type definitions and request creation

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Complete example demonstrating fetch.isRequest. It defines a schema, creates a fetch instance, creates a request, and then uses the type guard to narrow the request type. The example shows that after the guard, request.headers.get('content-type') returns 'application/json' and request.json() returns the body.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: {
        headers: { 'content-type': 'application/json' };
        body: { username: string };
      };
      response: {
        201: { body: User };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

// highlight-start
const request = new fetch.Request('/users', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ username: 'me' }),
});
// highlight-end

if (fetch.isRequest(request, 'POST', '/users')) {
  // request is a FetchRequest<Schema, 'POST', '/users'>

  const contentType = request.headers.get('content-type'); // 'application/json'
  const body = await request.json(); // { username: string }
}
```

--------------------------------

### Install canary releases with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install the latest canary versions of @zimic/http and @zimic/fetch using npm. Canary releases may include unstable or breaking changes.

```bash
npm install @zimic/http@canary @zimic/fetch@canary --save
```

--------------------------------

### Install canary releases with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/2-getting-started.mdx

Install the latest canary versions of @zimic/http and @zimic/fetch using yarn. Canary releases may include unstable or breaking changes.

```bash
yarn add @zimic/http@canary @zimic/fetch@canary
```

--------------------------------

### Install @zimic/http canary with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the canary release of @zimic/http using npm. Canary releases contain the latest code and may be unstable.

```bash
npm install @zimic/http@canary --save
```

--------------------------------

### Install @zimic/http canary with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the canary release of @zimic/http using yarn. Canary releases contain the latest code and may be unstable.

```bash
yarn add @zimic/http@canary
```

--------------------------------

### Install stable @zimic/interceptor with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the stable versions of @zimic/http and @zimic/interceptor as dev dependencies using npm.

```bash
npm install @zimic/http @zimic/interceptor --save-dev
```

--------------------------------

### Install stable @zimic/interceptor with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the stable versions of @zimic/http and @zimic/interceptor as dev dependencies using pnpm.

```bash
pnpm add @zimic/http @zimic/interceptor --dev
```

--------------------------------

### Creating a FetchResponse instance

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/4-fetch-response.md

Example of creating a FetchResponse from a request, a JSON body, and init options with status and headers.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch, FetchResponse } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users/:userId': {
    GET: {
      response: {
        200: { body: User };
        404: { body: { message: string } };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const request = new fetch.Request(`/users/${userId}`, {
  method: 'GET',
});

//  highlight-start
const response = new FetchResponse(
  request,
  JSON.stringify({
    id: crypto.randomUUID(),
    username: 'me',
  }),
  {
    status: 200,
    headers: { 'content-type': 'application/json' },
  },
);
//  highlight-end
```

--------------------------------

### Install @zimic/http canary with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/2-getting-started.mdx

Installs the canary release of @zimic/http using pnpm. Canary releases contain the latest code and may be unstable.

```bash
pnpm add @zimic/http@canary
```

--------------------------------

### Install stable @zimic/interceptor with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the stable versions of @zimic/http and @zimic/interceptor as dev dependencies using yarn.

```bash
yarn add @zimic/http @zimic/interceptor --dev
```

--------------------------------

### Start interceptor server standalone

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/2-remote-http-interceptors.md

Starts the interceptor server on port 3000 as a standalone process.

```bash
zimic-interceptor server start --port 3000
```

--------------------------------

### Basic createFetch usage with schema

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/1-create-fetch.md

Example of creating a fetch instance with a base URL and a schema type. The schema is defined using HttpSchema from @zimic/http.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

type Schema = HttpSchema<{
  // ...
}>;

// highlight-start
const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});
// highlight-end
```

--------------------------------

### Start interceptor server as prefix to test command

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/2-remote-http-interceptors.md

Starts the interceptor server on port 3000 with --ephemeral, then runs npm run test after the server is ready. The server stops automatically when the command finishes.

```bash
zimic-interceptor server start --port 3000 --ephemeral -- npm run test
```

--------------------------------

### generateTypesFromOpenAPI() usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/5-typegen.md

Example of importing and calling generateTypesFromOpenAPI with a local schema file, output path, service name, filters, and default options for comments and pruning.

```TypeScript
import { generateTypesFromOpenAPI } from '@zimic/http/typegen';

await generateTypesFromOpenAPI({
  input: './schema.yaml',
  output: './schema.ts',
  serviceName: 'MyService',
  filters: ['* /users**'],
  includeComments: true,
  prune: true,
});
```

--------------------------------

### onResponse listener usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/1-create-fetch.md

Example of using onResponse to log a response header when the response matches a specific path and method.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers: { 'content-encoding'?: string };
          body: User[];
        };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:80',

  // highlight-start
  onResponse(response) {
    if (this.isResponse(response, 'GET', '/users')) {
      console.log(response.headers.get('content-encoding'));
    }
    return response;
  },
  // highlight-end
});
```

--------------------------------

### server.start()

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/api/5-interceptor-server.md

Starts the interceptor server. It automatically stops on process exit events such as SIGINT, SIGTERM, or uncaught exceptions.

```APIDOC
## server.start()

### Description
Starts the interceptor server. It will automatically stop if a process exit event is detected, such as SIGINT, SIGTERM, or an uncaught exception.

### Method
start

### Returns
`Promise<void>`

### Example
```ts
await server.start();
```
```

--------------------------------

### Install canary @zimic/interceptor with pnpm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the canary versions of @zimic/http and @zimic/interceptor as dev dependencies using pnpm. Canary releases contain the latest code and may include unstable or breaking changes.

```bash
pnpm add @zimic/http@canary @zimic/interceptor@canary --dev
```

--------------------------------

### Install canary @zimic/interceptor with npm

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the canary versions of @zimic/http and @zimic/interceptor as dev dependencies using npm. Canary releases contain the latest code and may include unstable or breaking changes.

```bash
npm install @zimic/http@canary @zimic/interceptor@canary --save-dev
```

--------------------------------

### Generated schema.ts example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/guides/2-typegen.mdx

Example of the generated schema file, named based on the --service-name option, containing the HTTP schema and generated types for each endpoint.

```ts
import { HttpSchema } from '@zimic/http';

export type Schema = HttpSchema<{
  users: {
    GET: {
      request: {
        searchParams: { search?: string };
      };
      response: {
        200: {
          headers: { 'content-type': 'application/json' };
          body: MyServiceComponents['schemas']['Users'];
        };
      };
    };
    // ...
  };
  // ...
}>;

export interface MyServiceComponents {
  schemas: {
    User: { id: number; name: string };
    Users: MyServiceComponents['schemas']['User'][];
    // ...
  };
  // ...
}

export interface MyServiceOperations {
  // ...
}
```

--------------------------------

### Install canary @zimic/interceptor with yarn

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Installs the canary versions of @zimic/http and @zimic/interceptor as dev dependencies using yarn. Canary releases contain the latest code and may include unstable or breaking changes.

```bash
yarn add @zimic/http@canary @zimic/interceptor@canary --dev
```

--------------------------------

### Mock a GET request with typed handler

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/2-remote-http-interceptors.md

Sets up a mock response for a GET /users request with headers, search params, and a body, limited to one call. All paths, methods, parameters, requests, and responses are typed by default.

```typescript
test('example', async () => {
  const users: User[] = [{ username: 'me' }];

  //  highlight-start
  await interceptor
    .get('/users')
    .with({
      headers: { authorization: 'Bearer my-token' },
      searchParams: { query: 'u' },
    })
    .respond({
      status: 200,
      body: users,
    })
    .times(1);
  //  highlight-end

  // Run the application and make requests...
});
```

--------------------------------

### Filter endpoints with --filter

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/cli/1-typegen.md

Filters which endpoints to include in the generated types. The example includes only GET requests to paths starting with /users.

```bash
zimic-http typegen openapi ./schema.yaml \
  --output ./schema.ts \
  --service-name MyService \
  --filter 'GET /users**'
```

--------------------------------

### Using HttpSchemaPath to extract paths

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Example showing how to use HttpSchemaPath to extract all paths or filter by method.

```TypeScript
import { HttpSchema, HttpSchemaPath } from '@zimic/http';

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: { 200: { body: User[] } };
    };
  };
  '/users/:userId': {
    DELETE: {
      response: { 200: { body: User } };
    };
  };
}>;

type Path = HttpSchemaPath<Schema>;
// "/users" | "/users/:userId" | "/users/${string}"

type GetPath = HttpSchemaPath<Schema, 'GET'>;
// "/users"
```

--------------------------------

### Creating and using HttpFormData with a typed schema

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/4-http-form-data.md

Shows how to import HttpFormData from @zimic/http, create an instance with a schema, append values, and retrieve them using getAll and get.

```TypeScript
import { HttpFormData } from '@zimic/http';

const formData = new HttpFormData<{
  files: File[];
  description?: string;
}>();

formData.append('file', new File(['content'], 'file.txt', { type: 'text/plain' }));
formData.append('description', 'My file');

const files = formData.getAll('file');
console.log(files); // [File { name: 'file.txt', type: 'text/plain' }]

const description = formData.get('description');
console.log(description); // 'My file'
```

--------------------------------

### CLI help output for zimic-interceptor browser init

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/2-browser.md

Shows the usage and positional argument for the `init` command, requiring a `publicDirectory` path.

```bash
zimic-interceptor browser init <publicDirectory>

Positionals:
  publicDirectory  The path to the public directory of your application.
                                                             [string] [required]
```

--------------------------------

### Schema with error responses for GET /users/:userId

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/guides/6-errors.md

Defines an HttpSchema for a GET request to /users/:userId with success (200) and error (401, 403, 404, 500, 503) responses. Used as the basis for the error handling examples.

```TypeScript
import { HttpSchema } from '@zimic/http';

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users/:userId': {
    GET: {
      request: {
        headers?: { authorization?: string };
      };
      response: {
        // highlight-start
        200: { body: User };
        401: { body: { code: 'UNAUTHORIZED'; message: string } };
        403: { body: { code: 'FORBIDDEN'; message: string } };
        404: { body: { code: 'NOT_FOUND'; message: string } };
        500: { body: { code: 'INTERNAL_SERVER_ERROR'; message: string } };
        503: { body: { code: 'SERVICE_UNAVAILABLE'; message: string } };
        // highlight-end
      };
    };
  };
}>;
```

--------------------------------

### Using HttpSchema.PathParams in a schema

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Example schema.ts file showing how to use HttpSchema.PathParams to define path parameters for a GET endpoint.

```TypeScript
import { HttpSchema, InferPathParams } from '@zimic/http';

type Schema = HttpSchema<{
  '/users/:userId': {
    GET: {
      response: {
        200: { body: User };
      };
    };
  };
}>;

type UserByIdPathParams = HttpSchema.PathParams<{
  userId: string;
}>;
```

--------------------------------

### searchParams.assign() method signature and usage example

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/3-http-search-params.md

Assigns another HttpSearchParams instance to the current one, modifying only the instance where the method is called. The example shows that after assignment, getAll('names') returns ['user 2'] and get('page') returns '1'.

```TypeScript
searchParams.assign(otherSearchParams);
```

```TypeScript
const searchParams = new HttpSearchParams({
  names: ['user 1'],
  page: '1',
});

const otherSearchParams = new HttpSearchParams({
  names: ['user 2'],
});

searchParams.assign(otherSearchParams);

console.log(searchParams.getAll('names')); // ['user 2']
console.log(searchParams.get('page')); // '1'
```

--------------------------------

### Create fetch instance with default headers

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Shows how to create a fetch instance with default headers and update them later. The example uses a schema with a POST endpoint and sets default headers for accept-language and cache-control. It also demonstrates updating the authorization header directly on the fetch instance.

```TypeScript
import { HttpSchema } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

interface Post {
  id: string;
  title: string;
}

type Schema = HttpSchema<{
  '/posts': {
    POST: {
      request: {
        headers: {
          'accept-language'?: string;
          'cache-control'?: string;
          authorization?: string;
        };
        body: { title: string };
      };
      response: {
        201: { body: Post };
      };
    };
  };
}>;

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
  // Setting defaults when creating the fetch instance
  // highlight-start
  headers: {
    'accept-language': 'en',
    'cache-control': 'no-cache',
  },
  // highlight-end
});

// Somewhere else in the code, you can update the defaults as needed
// highlight-next-line
fetch.headers.authorization = `Bearer ${accessToken}`;
```

--------------------------------

### CLI help output for zimic-interceptor browser

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/2-browser.md

Shows the available commands under `zimic-interceptor browser`, including the `init` command with its positional argument.

```bash
zimic-interceptor browser

Commands:
  zimic-interceptor browser init <publicDirectory>   Initialize the browser service
                                                     worker configuration.
```

--------------------------------

### Log response error with toObject()

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/guides/6-errors.md

Use FetchResponseError.toObject() to get a plain object representation of the error for logging. This example logs the error object to the console.

```TypeScript
import { FetchResponseError } from '@zimic/fetch';

if (error instanceof FetchResponseError) {
  // highlight-next-line
  console.error(error.toObject());
}
```

--------------------------------

### Using HttpSchema.ResponseByStatusCode in a schema

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/1-http-schema.md

Example of using HttpSchema.ResponseByStatusCode to define a response schema for a GET /users endpoint, with specific schemas for 200 and 400 status codes.

```TypeScript
import { HttpSchema } from '@zimic/http';

type UserListResponseByStatusCode = HttpSchema.ResponseByStatusCode<{
  200: { body: User[] };
  400: { body: { message: string } };
}>;

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: UserListResponseByStatusCode;
    };
  };
}>;
```

--------------------------------

### fetch(input, init)

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Sends a request with the provided input and init options. The init object extends the native RequestInit interface with additional properties: method, baseURL, searchParams, and duplex. Returns a Promise resolving to a FetchResponse.

```APIDOC
## fetch(input, init)

### Description
Sends a request with the provided input and init options. The init object extends the native RequestInit interface with additional properties: method, baseURL, searchParams, and duplex. Returns a Promise resolving to a FetchResponse.

### Method
fetch

### Endpoint
fetch(input, init)

### Parameters
#### Input
- **input** (string | URL | FetchRequest) - Required - The resource to fetch, either a path, a URL, or another FetchRequest request. If a path is provided, it is automatically prefixed with the base URL of the fetch instance when the request is sent. If a URL or a request is provided, it is used as is.

#### Init
- **method** (string) - Required - The HTTP method to use for the request. Differently from the native Fetch API, this is required to ensure that requests are typed correctly.
- **baseURL** (string | undefined) - Optional - The base URL for the request. If provided, it will have preference over the default base URL of the fetch instance.
- **searchParams** (HttpSearchParamsSchema.Loose | undefined) - Optional - The search parameters to be sent with the request. If provided, it will have preference over the default search parameters of the fetch instance.
- **duplex** ('half' | undefined) - Optional - The duplex mode for the request. If set to 'half', the request body will be streamed.

### Returns
- **Promise<FetchResponse>** - A promise that resolves to a FetchResponse, which is typed with the schema of the fetch instance.

### Example
```ts
const response = await fetch('/users', {
  method: 'GET',
  searchParams: { query: 'u' },
});
```
```

--------------------------------

### Set headers using fetch.onRequest listener

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/guides/1-headers.md

Uses the onRequest listener to set headers with custom logic, such as reading from local storage or limiting to specific requests. The example sets 'accept-language' only for GET /users requests.

```TypeScript
import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',

  // highlight-start
  onRequest(request) {
    if (this.isRequest(request, 'GET', '/users')) {
      request.headers.set('accept-language', 'en');
    }
    return request;
  },
  // highlight-end
});
```

--------------------------------

### Create a local HTTP interceptor

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/2-getting-started.mdx

Creates an interceptor with type 'local' (the default). Local interceptors use MSW to intercept requests in the same process as your application, requiring no server setup. This is the simplest way to start mocking requests.

```TypeScript
import { createHttpInterceptor } from '@zimic/interceptor/http';

const interceptor = createHttpInterceptor<Schema>({
  // highlight-next-line
  type: 'local',
  baseURL: 'http://localhost:3000',
});
```

--------------------------------

### Computed restriction with handler.with() - Local interceptor

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/7-declarative-assertions.mdx

Defines a computed restriction by passing a function to handler.with(). The function receives the intercepted request and returns a boolean. This example checks that the 'accept' header starts with 'application'. Use with local interceptors.

```TypeScript
interceptor
  .post('/users')
  .with((request) => {
    // Expect the request to have an 'accept' header that starts with 'application'
    const accept = request.headers.get('accept');
    return accept !== null && accept.startsWith('application');
  })
  .respond({
    status: 201,
    body: user,
  });
```

--------------------------------

### Send search params in a fetch request

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/guides/2-search-params.md

Uses the searchParams option in a fetch request to send query parameters. The params are automatically encoded in the URL. This example sends q, page, size, and orderBy for a GET /users request.

```TypeScript
import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch('/users', {
  method: 'GET',
  // highlight-start
  searchParams: {
    q: 'search term',
    page: 1,
    size: 10,
    orderBy: 'createdAt:desc',
  },
  // highlight-end
});
```

--------------------------------

### Computed restriction with handler.with() - Remote interceptor

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/guides/http/7-declarative-assertions.mdx

Defines a computed restriction by passing a function to handler.with(). The function receives the intercepted request and returns a boolean. This example checks that the 'accept' header starts with 'application'. Use with remote interceptors; note the await keyword.

```TypeScript
await interceptor
  .post('/users')
  .with((request) => {
    // Expect the request to have an 'accept' header that starts with 'application'
    const accept = request.headers.get('accept');
    return accept !== null && accept.startsWith('application');
  })
  .respond({
    status: 201,
    body: user,
  });
```

--------------------------------

### Declaring responses with status code ranges

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/guides/1-schemas.md

Shows how to use HttpStatusCode ranges to declare responses for multiple status codes. The example defines a GET /users endpoint that can return a 200 success, any 4XX client error, or any 5XX server error, each with specific body types.

```TypeScript
import { HttpSchema, HttpStatusCode } from '@zimic/http';

interface User {
  name: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    GET: {
      // highlight-start
      response: {
        200: User[];
      } & {
        // 4XX
        [StatusCode in HttpStatusCode.ClientError]: {
          body: { message?: string; code: 'client_error' };
        };
      } & {
        // 5XX
        [StatusCode in HttpStatusCode.ServerError]: {
          body: { message?: string; code: 'server_error' };
        };
      };
      // highlight-end
    };
  };
}>;
```

--------------------------------

### new fetch.Request(input, init)

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-fetch/api/2-fetch.md

Creates a new FetchRequest instance with the given input and init options. The init argument is required when the first argument is a path or URL, and optional when the first argument is a FetchRequest.

```APIDOC
## `fetch.Request`

### Description
Creates a new `FetchRequest` instance with the given input and init options.

### Constructor
`new fetch.Request(input, init)`

### Parameters
#### input
- **input** (`string | URL | FetchRequest`) - Required - The resource to fetch, either a path, a URL, or another `FetchRequest`. If a path is provided, it is automatically prefixed with the base URL of the fetch instance when the request is sent. If a URL or a request is provided, it is used as is.

#### init
- **init** (`FetchRequestInit | undefined`) - Required if the first argument is a path or URL; optional if the first argument is a `FetchRequest` - The options to use for the request. Inherits from the native `RequestInit` interface, with the following additional properties:
  - **method** (`string`) - Required - The HTTP method to use for the request.
  - **baseURL** (`string | undefined`) - Optional - The base URL for the request. If provided, it will have preference over the default base URL of the fetch instance.
  - **searchParams** (`HttpSearchParamsSchema.Loose | undefined`) - Optional - The search parameters to be sent with the request. If provided, it will have preference over the default search parameters of the fetch instance.
  - **duplex** (`'half' | undefined`) - Optional - The duplex mode for the request. If set to `'half'`, the request body will be streamed.

### Example
```ts
new fetch.Request('/users', {
  method: 'GET',
  baseURL: 'https://api.example.com',
  searchParams: { page: 1 },
});
```

```

--------------------------------

### zimic-interceptor server token create - usage

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/cli/1-server.md

Shows the usage and options for the `create` subcommand. The `--name` option is a string, and `--tokens-dir` defaults to `.zimic/interceptor/server/tokens`.

```bash
zimic-interceptor server token create

Options:
  -n, --name        The name of the token to create.                    [string]
  -t, --tokens-dir  The directory where the created interceptor token will be
                    saved.[string] [default: ".zimic/interceptor/server/tokens"]
```

--------------------------------

### Create a typed HttpHeaders instance

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-http/api/2-http-headers.md

Imports HttpHeaders from '@zimic/http' and creates a new instance with a schema defining 'accept' and 'content-type' headers. The example then retrieves the 'content-type' header and logs it, outputting 'application/json'.

```TypeScript
import { HttpHeaders } from '@zimic/http';

const headers = new HttpHeaders<{
  accept?: string;
  'content-type'?: string;
}>({
  accept: '*',
  'content-type': 'application/json',
});

const contentType = headers.get('content-type');
console.log(contentType); // 'application/json'
```

--------------------------------

### Start the interceptor server

Source: https://github.com/zimicjs/zimic/blob/main/apps/zimic-web/docs/zimic-interceptor/api/5-interceptor-server.md

Starts the server. It will automatically stop if a process exit event is detected, such as SIGINT, SIGTERM, or an uncaught exception.

```typescript
await server.start();
```