# Reference: external interface

This document describes the **supported public surface** of the software published from this repository: **inputs** (what you pass in) and **outputs** (what you get back). For every function, type, and option, see the **[TypeDoc API reference](https://thedude459.github.io/boundfetch/)** generated from source.

The primary product is the **`@boundfetch/core`** runtime library for Node.js. Optional packages (`@boundfetch/plugin-*`, `@boundfetch/presets`) extend that surface; their public entry points are the **`index` exports** of each package (no deep imports).

---

## `@boundfetch/core`

### Entry point

All supported API is re-exported from the package root:

- Module: `@boundfetch/core`
- Source of truth for names: [`packages/core/src/index.ts`](../packages/core/src/index.ts)

### Main function: `createClient`

**Input — `ClientConfig`**

| Field             | Role                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `baseUrl`         | String base URL for all requests (validated against security rules).                                    |
| `endpoints`       | Map of endpoint **names** → `EndpointDef` (see below). Each name becomes a method on the client.        |
| `mode`            | Optional. `'throw'` (default) or `'result'` — controls error signaling (exceptions vs result envelope). |
| `timeout`         | Optional. Milliseconds for request timeout (default 30_000).                                            |
| `headers`         | Optional. Default headers merged into every request.                                                    |
| `fetcher`         | Optional. `FetcherAdapter` replacing the default native `fetch` bridge.                                 |
| `plugins`         | Optional. Ordered `BoundFetchPlugin[]` for middleware and wrappers.                                     |
| `securityProfile` | Optional. One of `'production' \| 'development' \| 'internal' \| 'balanced'`.                           |
| `security`        | Optional. Partial `SecurityConfig` merged onto the profile.                                             |

**Input — each `EndpointDef`**

| Field                | Role                                                                                                |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `method`             | HTTP verb: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, or `HEAD`.                                      |
| `path`               | Path template; may include `:param` segments matching `params` keys.                                |
| `params`             | Optional. Zod schema for path parameters.                                                           |
| `query`              | Optional. Zod schema for query string.                                                              |
| `body`               | Optional. Zod schema for JSON body (serialized with `JSON.stringify`).                              |
| `response`           | **Required.** Zod schema for successful response body (parsed as JSON unless configured otherwise). |
| `expectJsonResponse` | Optional. Affects parsing expectations.                                                             |
| `headers`            | Optional. Per-endpoint default headers.                                                             |

**Output — `BoundFetchClient`**

For each key `K` in `endpoints`, the client exposes a callable `client[K](input?)`:

- **Input to the call:** `EndpointInput` for that endpoint — an object with optional `params`, `query`, and/or `body` sections matching the schemas (only required keys must be present; fully optional shapes may be called with no argument).
- **Output when `mode` is `'throw'`:** A `Promise` of the **output type** of that endpoint’s `response` Zod schema. Failures throw **`BoundFetchError`** (`code`, optional `status`, `cause`, `details`).
- **Output when `mode` is `'result'`:** A `Promise<BoundFetchResult<T>>` where `T` is the response schema output type — either `{ success: true, data, error: null }` or `{ success: false, data: null, error: BoundFetchError }`.

Other exports (`composePlugins`, `securityProfiles`, types, `BoundFetchError`) are part of the same supported surface; see TypeDoc for exact signatures.

---

## Optional packages

| Package                              | Purpose                                      | Typical input / output                                                                                                              |
| ------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `@boundfetch/plugin-retry`           | Retry middleware                             | Plugin factory options → `BoundFetchPlugin` passed in `ClientConfig.plugins`.                                                       |
| `@boundfetch/plugin-circuit-breaker` | Circuit breaker middleware                   | Same pattern.                                                                                                                       |
| `@boundfetch/plugin-openapi`         | OpenAPI → endpoint definitions helper        | Functions that take an OpenAPI document / structure and produce data consumable by `createClient` (see package README and TypeDoc). |
| `@boundfetch/presets`                | Composition helpers for common plugin setups | Preset factories combining plugins; input/output per TypeDoc.                                                                       |

---

## HTTP and transport (implicit contract)

- Requests use the configured **`fetcher`** (default: native fetch) with URL `baseUrl` + interpolated path + query string, JSON body when `body` is present, and merged headers.
- Successful responses are validated against each endpoint’s **`response`** schema; validation failures surface as **`BoundFetchError`** with `VALIDATION_ERROR` (and related semantics documented in code).
- Size limits, HTTPS rules, host allowlists, and other guards are enforced from **`securityProfile`** + **`security`**; blocking events may invoke `onSecurityEvent` when configured.

For behavior-focused examples, see [`docs/recipes.md`](recipes.md) and [`docs/security.md`](security.md).