@powerduck/openapi-request 0.2.2 → 0.2.4

package/README.md

@@ -1,711 +1,272 @@
 # @powerduck/openapi-request
 
-OpenAPI 3.2-first protocol debugger for HTTP, SSE, WebSocket, GraphQL, gRPC and MCP.
-One client surface, one event model, one write-back pipeline.
+[![npm version](https://img.shields.io/npm/v/@powerduck/openapi-request)](https://www.npmjs.com/package/@powerduck/openapi-request)
+[![license](https://img.shields.io/npm/l/@powerduck/openapi-request)](https://github.com/PowerDuckie/openapi-request/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/openapi-request)](https://www.npmjs.com/package/@powerduck/openapi-request)
 
-## Features
+Execute OpenAPI operations with full parameter serialization, security resolution, and response parsing. Supports fetch, axios, and custom HTTP clients. Built for browsers, Node.js, and Edge Functions.
+
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
 
-- **OpenAPI 3.2** as the single source of truth — every protocol is an operation with extensions.
-- **Incremental SSE / ndjson streaming** with `onEvent` callbacks and `onResponseStart` early classification.
-- **Manual sessions** for WebSocket, gRPC (all four RPC modes) and MCP (Streamable HTTP + stdio).
-- **gRPC** via reflection or `.proto` files, with metadata / status / trailers surfaced as events.
-- **MCP** tools, prompts, resources and resource templates over HTTP or stdio.
-- **GraphQL** introspection, query/mutation generation and subscription over WebSocket.
-- **Postman-runtime** under the hood for HTTP, with full script (pre-request / test) support.
-- **Response write-back** — merges live responses into the OpenAPI document as `responses` objects.
+- **Full Parameter Serialization** — Path, query, header, and cookie parameters with RFC 6570 URI templates
+- **Security Resolution** — Bearer tokens, API keys, Basic auth, OAuth2, and custom schemes
+- **3 HTTP Clients** — fetch (default), axios, and custom client adapters
+- **Request Body Handling** — JSON, form-data, x-www-form-urlencoded, and raw payloads
+- **Response Parsing** — Automatic JSON, text, blob, and stream parsing with content-type detection
+- **Prepare & Send** — Two-phase API for request inspection before sending
+- **Type-Safe Operations** — Full TypeScript types for parameters, request bodies, and responses
+- **Error Handling** — Structured error objects with status, headers, and parsed body
+- **Interceptors** — Request and response interceptors for logging, auth refresh, and retries
+- **Browser & Node** — Works in browsers, Node.js, and Edge Functions with zero dependencies
 
-## Installation
+---
+
+## Quick Start
+
+### Install
 
 ```bash
 npm install @powerduck/openapi-request
 ```
 
-Requires Node.js >= 18.17.
-
-## Quick Start
+### Create a client and send a request
 
-```ts
+```typescript
 import { createClient } from "@powerduck/openapi-request";
 
 const client = createClient();
 
-// 1. Decide how to render before sending anything.
-const prepared = client.prepare({
-  spec: openApiDoc,
-  target: { path: "/users/{id}", method: "get" },
-});
-console.log(prepared.display.mode);   // "response" | "event-list" | "duplex-session"
-console.log(prepared.stream.kind);    // "none" | "sse" | "grpc-unary" | ...
-
-// 2. Send a one-shot request (HTTP / GraphQL / MCP one-shot).
 const result = await client.send({
-  spec: openApiDoc,
-  target: { path: "/users/{id}", method: "get" },
-  values: { path: { id: "42" } },
-  serverUrl: "https://api.example.com",
-  onResponseStart: (info) => {
-    console.log("streaming:", info.streaming); // true for SSE, switch UI early
-  },
-  onEvent: (event) => {
-    console.log(event.event, event.data); // incremental SSE events
+  spec: openApiDocument,
+  operationId: "getUserById",
+  parameters: {
+    path: { id: "123" },
+    query: { include: "profile" },
   },
 });
 
-// 3. Open a long-lived session (WebSocket / gRPC / MCP).
-const session = client.connect({ kind: "websocket", url: "wss://api.example.com/ws" });
-await session.open();
-session.onEvent((e) => console.log(e));
-await session.send({ type: "ping" });
-await session.close();
+console.log(result.response.status); // e.g. 200
+console.log(result.response.body); // parsed response body
+console.log(result.response.headers); // response headers
 ```
 
----
-
-## API Reference
-
-### `createClient(options?)`
-
-Returns a client with `prepare`, `send`, `sendMany`, `connect`, `discover`, `writeback`, `dispose`, `probeStreamingResponse`.
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `writeBack` | `WriteBackOptions` | `{}` | Controls how responses are merged into the spec. |
-| `response` | `ToResponseOptions` | `{}` | Controls how a live response becomes an OpenAPI Response object. |
-
-### `client.prepare(options)` → `PreparedRequest`
-
-Pure, synchronous. No I/O. Returns everything the UI needs to choose a renderer.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `protocol` | `string` | `"http"` \| `"sse"` \| `"websocket"` \| `"grpc"` \| `"graphql"` \| `"mcp"` |
-| `transport` | `string` | `"http"` \| `"websocket"` \| `"grpc"` \| `"stdio"` |
-| `display.mode` | `"response"` \| `"event-list"` \| `"duplex-session"` | How to render the result. |
-| `stream.kind` | `StreamKind` | Fine-grained streaming taxonomy. |
-| `stream.expected` | `boolean` | True when the operation declares or implies streaming. |
-| `openapi.extensions` | `Record<string, unknown>` | The seven `x-*` extensions derived from the operation. |
-| `warnings` | `string[]` | Non-fatal issues found during preparation. |
-
-### `client.send(options)` → `Promise<SendResult>`
+### Prepare and send separately
 
-One-shot execution through the full pipeline: build collection → run → parse → write back.
-
-### `client.connect(options)` → `ManualSession`
-
-Opens a long-lived session for WebSocket, gRPC or MCP. See [Manual Sessions](#manual-sessions).
-
-### `client.discover(options)` → `Promise<DiscoveryResult>`
-
-Discovers schema/capabilities for MCP or gRPC.
-
-| Protocol | Options |
-|----------|---------|
-| `mcp` | `{ protocol: "mcp", endpoint, headers?, transport?, command?, args?, cwd? }` |
-| `grpc` | `{ protocol: "grpc", address, reflection?, protoPaths?, includeDirs?, metadata?, channelOptions? }` |
+```typescript
+import { createClient } from "@powerduck/openapi-request";
 
-### `client.writeback(spec, prepared, result, options?)` → `OpenApiDocument`
+const client = createClient();
 
-Merges a result's response into the spec at the operation's path+method.
+// Prepare builds the request without sending
+const prepared = client.prepare({
+  spec: openApiDocument,
+  operationId: "listUsers",
+  parameters: {
+    query: { page: 1, limit: 20 },
+  },
+});
 
----
+console.log(prepared.url); // final URL with serialized params
+console.log(prepared.method); // HTTP method
+console.log(prepared.headers); // resolved headers
 
-## SendOptions (all protocols)
-
-The full option shape passed to `client.send()`. Protocol-specific fields are nested under `runner`, `websocket`, `graphql`, `mcp`, `grpc`.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `spec` | `OpenApiDocument` | **required** | The OpenAPI 3.2 document. |
-| `target` | `OperationTarget` | **required** | `{ path?, method?, operationId? }` — identifies the operation. |
-| `values` | `RequestValues` | `{}` | Path/query/header/cookie/body values to inject. |
-| `serverUrl` | `string` | `spec.servers[0].url` | Overrides the server URL. |
-| `serverVariables` | `Record<string,string>` | `{}` | Variables for `{var}` placeholders in the server URL. |
-| `variables` | `Record<string,string>` | `{}` | Postman environment variables (`{{name}}`). |
-| `globals` | `Record<string,string>` | `{}` | Postman global variables. |
-| `localVariables` | `Record<string,string>` | `{}` | Postman local variables. |
-| `auth` | `AuthConfig` | — | `{ type: "bearer"\|"basic"\|"apikey"\|"none", ... }`. |
-| `scripts` | `ScriptConfig` | `{}` | Pre-request / test scripts and `x-postman-scripts` handling. |
-| `runner` | `RuntimeRunOptions` | `{}` | Full postman-runtime passthrough. Highest precedence. |
-| `websocket` | `WebSocketOptions` | `{}` | WebSocket-specific options. |
-| `graphql` | `GraphQLOptions` | `{}` | GraphQL-specific options. |
-| `mcp` | `McpOptions` | `{}` | MCP-specific options. |
-| `grpc` | `any` | `{}` | gRPC-specific options (used by the gRPC adapter). |
-| `timeout` | `number` | `30000` | Convenience shortcut for `runner.timeout.request`. `0` = unlimited. |
-| `maxEvents` | `number` | `100` | Maximum streaming events to retain. |
-| `maxStreamMs` | `number` | `30000` | Maximum streaming duration before sampling stops. |
-| `maxResponseSize` | `number` | — | Hard byte ceiling for the response body. Rejected if `<= 0`. |
-| `writeBack` | `boolean` | `true` | Set `false` to skip OpenAPI write-back. |
-| `signal` | `AbortSignal` | — | Cancels the run; returns a partial result. |
-| `onEvent` | `(event: StreamEvent) => void` | — | Incremental SSE / ndjson events. Called defensively (errors swallowed). |
-| `onResponseStart` | `(info: ResponseStartInfo) => void` | — | Fires when headers arrive. `info.streaming` is the early SSE flag. |
-| `onConsole` | `(log: ConsoleLog) => void` | — | Script `console.*` output. |
-| `onAssertion` | `(a: AssertionResult) => void` | — | Individual test assertion results. |
-| `onOpen` | `(info: {url, protocol?, headers}) => void` | — | WebSocket connection established. |
-
-### StreamParserOptions (also on SendOptions)
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `maxBufferChars` | `number` | `4194304` (4 Mi) | Max chars buffered while waiting for an event boundary. |
-| `maxEventChars` | `number` | `1048576` (1 Mi) | Max chars in a single event's `data`. |
-| `inheritEventId` | `boolean` | `true` | Attach the last seen `id` to events that omit one. Set `false` for spec-faithful streams. |
+// Send the prepared request
+const result = await client.sendPrepared(prepared);
+```
 
----
+### With authentication
 
-## HTTP / SSE
-
-### Request JSON structure
-
-An HTTP operation is a standard OpenAPI path item. SSE is detected automatically from the response content type or the `x-response-stream` extension.
-
-```json
-{
-  "openapi": "3.2.0",
-  "info": { "title": "example", "version": "1.0.0" },
-  "servers": [{ "url": "https://api.example.com" }],
-  "paths": {
-    "/users/{id}": {
-      "get": {
-        "operationId": "getUser",
-        "parameters": [
-          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
-        ],
-        "responses": {
-          "200": {
-            "description": "ok",
-            "content": { "application/json": {} }
-          }
-        }
-      }
-    },
-    "/events": {
-      "get": {
-        "operationId": "streamEvents",
-        "responses": {
-          "200": {
-            "description": "ok",
-            "content": { "text/event-stream": {} }
-          }
-        }
-      }
-    }
-  }
-}
-```
+```typescript
+import { createClient } from "@powerduck/openapi-request";
 
-### `runner.requester` options (HTTP transport)
-
-These control the underlying HTTP client. Pass via `send({ runner: { requester: { ... } } })`.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `followRedirects` | `boolean` | `true` | Follow HTTP 3xx redirects. |
-| `followOriginalHttpMethod` | `boolean` | `false` | Keep the original method on redirect (e.g. POST stays POST). When `false`, 301/302/303 downgrade to GET. |
-| `maxRedirects` | `number` | `10` | Maximum redirect hops. Must be a non-negative integer. |
-| `protocolVersion` | `"http1" \| "http2" \| "auto"` | `"http1"` | HTTP protocol version. `"http1"` is required for SSE chunked streaming; use `"auto"` for HTTP/2 endpoints. |
-| `strictSSL` | `boolean` | `true` | Reject self-signed / invalid TLS certificates. |
-| `insecureHTTPParser` | `boolean` | `false` | Allow invalid HTTP responses (e.g. malformed headers). |
-| `maxResponseSize` | `number` | — | Hard byte ceiling for the response body. `0` is rejected (would silently yield empty streams). Omit for unbounded. |
-| `maxHeaderSize` | `number` | — | Maximum response header size in bytes. |
-| `useWhatWGUrlParser` | `boolean` | `true` | Use the WHATWG URL parser for request URLs. |
-| `removeRefererHeaderOnRedirect` | `boolean` | `false` | Strip the `Referer` header when following a redirect. |
-| `timings` | `boolean` | `true` | Collect detailed timing data (powers `firstByteMs`, `networkDurationMs`). |
-| `verbose` | `boolean` | `true` | Keep request/response history (powers `replays`). |
-| `implicitCacheControl` | `boolean` | `true` | Add `Cache-Control: no-cache` implicitly. |
-| `implicitTraceHeader` | `boolean` | `true` | Add a trace header implicitly. |
-| `disableCookies` | `boolean` | `false` | Disable the cookie jar. |
-| `cookieJar` | `any` | — | Custom cookie jar instance. |
-| `systemHeaders` | `Record<string,string>` | — | Headers added to every request (e.g. `User-Agent`). |
-| `extendedRootCA` | `string` | — | Path to an additional CA bundle. |
-| `encoding` | `null \| string` | `null` | Response body encoding. **Must be `null` for incremental SSE streaming** — the default `utf8` buffers the body to decode multi-byte boundaries. |
-| `agents` | `{ http?, https? }` | — | Custom HTTP/HTTPS agents. Supplying agents disables the library's socket tracking (stream cancellation falls back to `run.abort()`). |
-| `network.hostLookup` | `{ type, hostIpMap? }` | — | Custom DNS resolution. |
-| `network.restrictedAddresses` | `Record<string,boolean>` | — | Block specific IP addresses (SSRF protection). |
-| `maxInvokableNestedRequests` | `number` | `5` | Max nested requests from scripts (`pm.sendRequest`). |
-| `sslKeyLogFile` | `string` | — | Path to write TLS session keys (for Wireshark debugging). |
-
-### `runner` top-level options
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `timeout.request` | `number` | `30000` | Per-request timeout in ms. `0` = unlimited. |
-| `timeout.script` | `number` | `15000` | Script execution timeout in ms. |
-| `timeout.global` | `number` | computed | Global run timeout. Derived from `request + streamBudget + 15000` slack. |
-| `iterationCount` | `number` | `1` | Number of iterations. Must be >= 1. |
-| `data` | `Array<Record<string,unknown>>` | — | Data-driven iteration values. When provided, `iterationCount` defaults to `data.length`. |
-| `stopOnError` | `boolean` | `false` | Halt the run on a request error. |
-| `abortOnError` | `boolean` | `false` | Abort immediately on error (no cleanup callbacks). |
-| `stopOnFailure` | `boolean` | `false` | Halt on a failed test assertion. |
-| `abortOnFailure` | `boolean` | `false` | Abort immediately on assertion failure. |
-| `environment` | `any` | built from `variables` | Postman environment. Override to supply a custom VariableScope. |
-| `globals` | `any` | built from `globals` | Postman globals. |
-| `localVariables` | `any` | built from `localVariables` | Postman local variables. |
-| `proxies` | `any` | — | Postman proxy configuration list. |
-| `systemProxy` | `(url, cb) => void` | — | Callback to resolve the system proxy for a URL. |
-| `ignoreProxyEnvironmentVariables` | `boolean` | `false` | Ignore `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` env vars. |
-| `certificates` | `any` | — | Client certificate list. |
-| `delay.item` | `number` | `0` | Delay between requests in ms. |
-| `delay.iteration` | `number` | `0` | Delay between iterations in ms. |
-| `entrypoint.execute` | `string` | — | Name of the item to start from. |
-| `entrypoint.lookupStrategy` | `"idOrName" \| "path"` | — | How to resolve the entrypoint. |
-| `secretResolver` | `(ctx, cb) => void` | — | Resolve secrets referenced in the collection. |
-| `fileResolver` | `unknown` | — | Resolve file references in request bodies. |
-
-### SSE streaming example
-
-```ts
-const result = await client.send({
-  spec,
-  target: { path: "/events", method: "get" },
-  maxStreamMs: 60000,
-  maxEvents: 100,
-  onResponseStart: (info) => {
-    if (info.streaming) {
-      // Switch the UI to the event-list view immediately — do not wait
-      // for send() to resolve.
-      renderEventList();
-    }
-  },
-  onEvent: (event) => {
-    appendEvent(event); // called incrementally, ~every chunk
+const client = createClient({
+  securityValues: {
+    bearerAuth: "your-token-here",
+    apiKey: "your-api-key",
   },
 });
 
-// result.response.events contains all retained events.
-// result.response.truncated / stopReason explain why sampling ended.
+const result = await client.send({
+  spec: openApiDocument,
+  operationId: "getProfile",
+});
 ```
 
 ---
 
-## WebSocket
-
-### Request JSON structure
-
-```json
-{
-  "paths": {
-    "/ws": {
-      "get": {
-        "operationId": "wsConnect",
-        "x-protocol": "websocket",
-        "x-ws": {
-          "url": "wss://api.example.com/ws",
-          "subprotocols": ["graphql-transport-ws"]
-        },
-        "responses": { "200": { "description": "duplex" } }
-      }
-    }
-  }
-}
-```
+## Links
 
-### `websocket` options
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `url` | `string` | from `x-ws.url` | Absolute `ws://` or `wss://` URL. Overrides the spec. |
-| `subprotocols` | `string[]` | `[]` | WebSocket subprotocols to negotiate. |
-| `headers` | `Record<string,string>` | `{}` | Extra handshake headers. |
-| `send` | `Array<string \| object \| Uint8Array>` | — | Messages sent immediately after open. |
-| `sendDelayMs` | `number` | — | Delay between consecutive `send` messages. |
-| `maxMessages` | `number` | — | Stop after this many inbound messages. |
-| `maxSessionMs` | `number` | — | Hard cap on total session duration. |
-| `idleTimeoutMs` | `number` | — | Close when no message arrives within this window. |
-| `keepAlive` | `{ intervalMs, payload? }` | — | Application-level ping on an interval. |
-| `closeCode` | `number` | `1000` | Close code sent when terminating. |
-| `closeReason` | `string` | `"Closed"` | Close reason text. |
-| `closeTimeoutMs` | `number` | — | Grace period for the peer's close frame before destroying the socket. |
-| `rejectUnauthorized` | `boolean` | `true` | Reject self-signed TLS certificates. |
-| `maxPayloadBytes` | `number` | — | Cap on retained payload size per frame. |
-| `handshakeTimeoutMs` | `number` | `15000` | Handshake timeout. |
-| `clientOptions` | `Record<string,unknown>` | `{}` | Extra options forwarded to the `ws` constructor. |
-
-### Manual WebSocket session
-
-```ts
-const session = client.connect({
-  kind: "websocket",
-  url: "wss://api.example.com/ws",
-  subprotocols: ["chat"],
-  headers: { Authorization: "Bearer xxx" },
-});
+- [Official Website](https://www.powerduck.com/opensource/openapi-request.html)
+- [Documentation](https://www.powerduck.com/docs/openapi-request/introduction)
+- [GitHub](https://github.com/PowerDuckie/openapi-request)
+- [npm](https://www.npmjs.com/package/@powerduck/openapi-request)
 
-session.onEvent((e) => {
-  // e.kind: "open" | "text" | "binary" | "error" | "close" | "upgrade"
-  // e.direction: "in" | "out" | "meta"
-  // e.data: text payload (or base64 for binary)
-});
+---
 
-await session.open();
-await session.send({ type: "subscribe", channel: "updates" });
-await session.close({ code: 1000, reason: "done" });
-```
+## Features
+
+- **Full parameter serialization** — Path, query, header, and cookie parameters with RFC 6570 URI templates
+- **Security resolution** — Bearer tokens, API keys, Basic auth, OAuth2, and custom schemes
+- **3 HTTP clients** — fetch (default), axios, and custom client adapters
+- **Request body handling** — JSON, form-data, x-www-form-urlencoded, and raw payloads
+- **Response parsing** — Automatic JSON, text, blob, and stream parsing with content-type detection
+- **Prepare & send** — Two-phase API for request inspection before sending
+- **Type-safe operations** — Full TypeScript types for parameters, request bodies, and responses
+- **Error handling** — Structured error objects with status, headers, and parsed body
+- **Interceptors** — Request and response interceptors for logging, auth refresh, and retries
+- **Browser & Node** — Works in browsers, Node.js, and Edge Functions with zero dependencies
+- **Server selection** — Auto-select or manually specify server from OpenAPI servers
+- **Content negotiation** — Automatic Accept header based on response content types
+- **Upload progress** — Progress callbacks for file uploads with axios client
+- **Abort support** — AbortController / AbortSignal for request cancellation
+- **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
 
 ---
 
-## GraphQL
-
-### Request JSON structure
-
-```json
-{
-  "paths": {
-    "/graphql": {
-      "post": {
-        "operationId": "graphqlQuery",
-        "x-protocol": "graphql",
-        "x-graphql": {
-          "endpoint": "https://api.example.com/graphql",
-          "operationType": "query",
-          "operationName": "GetUser",
-          "query": "query GetUser($id: ID!) { user(id: $id) { name } }",
-          "variablesSchema": {
-            "type": "object",
-            "properties": { "id": { "type": "string" } },
-            "required": ["id"]
-          }
-        },
-        "requestBody": {
-          "content": { "application/json": { "schema": { "type": "object" } } }
-        },
-        "responses": { "200": { "description": "ok" } }
-      }
-    }
-  }
-}
-```
+## API Reference
 
-### `graphql` options
+### `createClient(options?)`
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `endpoint` | `string` | from `x-graphql.endpoint` | Absolute HTTP(S) URL of the GraphQL endpoint. |
-| `query` | `string` | from `x-graphql.query` | Query or mutation document. Overrides the spec. |
-| `operationName` | `string` | from `x-graphql.operationName` | Required when `query` declares more than one operation. |
-| `variables` | `Record<string,unknown>` | `{}` | GraphQL variables. Merged over sampled values. |
-| `headers` | `Record<string,string>` | `{}` | Extra headers, merged over `values.header` and auth. |
-| `useGet` | `boolean` | `false` | Use HTTP GET with querystring-encoded `query`/`variables` instead of POST. |
+Create an OpenAPI request client.
 
-### GraphQL discovery (introspection)
+```typescript
+import { createClient } from "@powerduck/openapi-request";
 
-```ts
-const result = await client.discover({
-  protocol: "graphql",
-  endpoint: "https://countries.trevorblades.com/",
-  headers: { Authorization: "Bearer xxx" },
+const client = createClient({
+  client: "fetch", // "fetch" | "axios" | custom adapter
+  baseUrl: "https://api.example.com",
+  securityValues: { bearerAuth: "token" },
+  defaultHeaders: { "X-App": "my-app" },
+  timeout: 30000,
 });
-// result.discovery contains the introspected schema
 ```
 
----
-
-## gRPC
-
-### Request JSON structure
-
-```json
-{
-  "paths": {
-    "/grpc": {
-      "post": {
-        "operationId": "grpcCall",
-        "x-protocol": "grpc",
-        "x-grpc": {
-          "address": "127.0.0.1:50051",
-          "service": "demo.echo.Echo",
-          "method": "Say",
-          "kind": "unary",
-          "reflection": true
-        },
-        "responses": { "200": { "description": "ok" } }
-      }
-    }
-  }
-}
-```
+### `client.send(options)`
 
-### gRPC method kinds
-
-| Kind | Streaming | Interaction | Button label |
-|------|-----------|-------------|-------------|
-| `unary` | none | One request → one response. Session closes automatically. | "Send and await" |
-| `server_streaming` | server → client | One request → N responses. Session closes on stream end. | "Send and await" |
-| `client_streaming` | client → server | N requests → one response. Send messages, then Finish. | "Send message" + "Finish" |
-| `bidi_streaming` | both | N requests ↔ N responses. Full duplex. | "Send message" + "Finish" |
-
-### Manual gRPC session options
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `address` | `string` | **required** | `host:port`, no scheme. |
-| `service` | `string` | **required** | Fully-qualified service name, e.g. `"demo.echo.Echo"`. |
-| `method` | `string` | **required** | Method name as declared in proto. Matched case-insensitively as fallback. |
-| `reflection` | `boolean` | — | Set `true` to use server reflection. Mutually exclusive with `protoPaths`. |
-| `protoPaths` | `string[]` | — | `.proto` files or directories. Directories are walked recursively. |
-| `includeDirs` | `string[]` | derived | Import roots for proto-loader. |
-| `metadata` | `Record<string, string \| string[]>` | `{}` | gRPC metadata sent on every call. |
-| `deadlineMs` | `number` | — | Per-call deadline. Enforced by the server (yields DEADLINE_EXCEEDED). |
-| `channelOptions` | `Record<string,unknown>` | `{}` | grpc-js channel options. |
-| `tls` | `boolean \| GrpcTlsOptions` | — | `false`/undefined = insecure; `true` = TLS with system roots; object = custom TLS. |
-| `loaderOptions` | `Record<string,unknown>` | `{}` | Extra proto-loader options. |
-| `reflectionTimeoutMs` | `number` | `5000` | Budget for the whole reflection session. |
-| `reflectionVersion` | `"v1" \| "v1alpha"` | try v1, fall back | Pin a reflection version. |
-| `reflectionHost` | `string` | — | `host` field on reflection requests (virtual-hosted servers). |
-
-### gRPC TLS options
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `rootCerts` | `Buffer` | CA bundle contents (not a path). Pass `await readFile(p)`. |
-| `privateKey` | `Buffer` | Client key for mTLS. Must be given with `certChain`. |
-| `certChain` | `Buffer` | Client certificate chain for mTLS. Must be given with `privateKey`. |
-| `skipHostnameVerification` | `boolean` | Skip hostname verification only. Chain is still verified. Always produces a warning. |
-
-### gRPC session events
-
-| `kind` | `direction` | Payload |
-|--------|-------------|---------|
-| `open` | `meta` | `{ address, service, method, kind, descriptorSource }` |
-| `metadata` | `meta` | Response headers (initial metadata). |
-| `data` | `out` | Outbound request message. |
-| `data` | `in` | Inbound response message. |
-| `status` | `meta` | Terminal status: `{ code, statusName, details, metadata }` (trailers). |
-| `error` | `meta` | Error: `{ code, statusName, details, error }`. |
-| `end` | `meta` | Stream ended. |
-| `close` | `meta` | Session closed by the client. |
-
-### gRPC example
-
-```ts
-const session = client.connect({
-  kind: "grpc",
-  address: "127.0.0.1:50051",
-  reflection: true,
-  service: "demo.echo.Echo",
-  method: "Say",
-});
+Send an OpenAPI operation.
 
-session.onEvent((e) => {
-  if (e.kind === "status") {
-    console.log("status:", e.meta.code, e.meta.statusName);
-  }
+```typescript
+const result = await client.send({
+  spec: openApiDocument,
+  operationId: "getUser",
+  parameters: {
+    path: { id: "123" },
+    query: { include: ["profile", "orders"] },
+    header: { "X-Request-ID": "abc" },
+  },
+  requestBody: { name: "Ada" },
+  securityValues: { bearerAuth: "token" },
+  serverIndex: 0,
+  signal: abortSignal,
 });
-
-await session.open();
-await session.send({ text: "hello" });
-// session.state === "closed" after a unary call
 ```
 
----
+### `client.prepare(options)`
 
-## MCP (Model Context Protocol)
-
-### Request JSON structure
-
-```json
-{
-  "paths": {
-    "/mcp": {
-      "post": {
-        "operationId": "mcpCall",
-        "x-protocol": "mcp",
-        "x-transport": "http",
-        "x-mcp": {
-          "endpoint": "http://127.0.0.1:4200/mcp",
-          "method": "tools/call",
-          "name": "get_weather",
-          "arguments": { "city": "SF" }
-        },
-        "responses": { "200": { "description": "ok" } }
-      }
-    }
-  }
-}
-```
+Prepare a request without sending.
 
-### `mcp` options
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `transport` | `"streamable-http" \| "stdio"` | `"streamable-http"` | Wire transport. |
-| `endpoint` | `string` | from `x-mcp.endpoint` | Absolute http(s) URL for Streamable HTTP transport. |
-| `headers` | `Record<string,string>` | `{}` | Extra HTTP headers. |
-| `command` | `string` | — | stdio command (e.g. `"npx"`). Required for stdio. |
-| `args` | `string[]` | `[]` | stdio command arguments. |
-| `cwd` | `string` | — | Working directory for the stdio child. |
-| `env` | `Record<string,string \| undefined>` | — | Environment for the stdio child. |
-| `timeoutMs` | `number` | `30000` | Per-request timeout. `0` disables. |
-| `maxBufferBytes` | `number` | — | stdio stdout buffer cap. |
-| `maxStderrBytes` | `number` | — | stdio stderr cap before the child is killed. |
-| `method` | `string` | from `x-mcp.method` | JSON-RPC method, e.g. `"tools/call"`. |
-| `name` | `string` | from `x-mcp.name` | Target tool/prompt/resource name. |
-| `arguments` | `Record<string,unknown>` | `{}` | JSON-RPC params. |
-| `sessionId` | `string` | — | Reuse an existing MCP session ID. |
-| `protocolVersion` | `string` | — | MCP protocol version to negotiate. |
-| `clientInfo` | `{ name, version }` | `{ name: "powerduck", version: "0.1.0" }` | Client info sent in `initialize`. |
-
-### Manual MCP session
-
-```ts
-const session = client.connect({
-  kind: "mcp",
-  transport: "streamable-http",
-  endpoint: "http://127.0.0.1:4200/mcp",
+```typescript
+const prepared = client.prepare({
+  spec: openApiDocument,
+  operationId: "listUsers",
+  parameters: { query: { page: 1 } },
 });
 
-await session.open();
-
-// List capabilities
-const tools = await session.listTools();
-const prompts = await session.listPrompts();
-const resources = await session.listResources();
+// prepared.url, prepared.method, prepared.headers, prepared.body
+```
 
-// Call a tool
-const result = await session.callTool("get_weather", { city: "SF" });
+### `client.sendPrepared(prepared)`
 
-// Raw JSON-RPC
-const raw = await session.request("tools/call", { name: "x", arguments: {} });
+Send a previously prepared request.
 
-await session.close();
+```typescript
+const result = await client.sendPrepared(prepared);
 ```
 
-### MCP stdio session
-
-```ts
-const session = client.connect({
-  kind: "mcp",
-  transport: "stdio",
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-everything"],
-  cwd: "/path/to/project",
-});
-await session.open();
+### Result Type
+
+```typescript
+interface RequestResult<T = unknown> {
+  response: {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: T;
+    raw: Response;
+  };
+  request: {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+  };
+  duration: number; // milliseconds
+}
 ```
 
----
+### Error Type
 
-## Manual Sessions (unified API)
-
-All manual sessions (WebSocket, gRPC, MCP) share this contract:
-
-| Method / Property | Description |
-|-------------------|-------------|
-| `protocol` | `"websocket"` \| `"grpc"` \| `"mcp"` |
-| `state` | `"idle"` \| `"connecting"` \| `"open"` \| `"closing"` \| `"closed"` \| `"error"` |
-| `events` | Read-only array of all events (ring-buffered at 1000 by default). |
-| `onEvent(listener)` | Subscribe to events. Returns `{ unsubscribe() }`. |
-| `open()` | Connect / initialize. Rejects from non-idle states. |
-| `send(message, options?)` | Send a message. Rejects when not open. |
-| `close(options?)` | Close gracefully. Idempotent. |
-| `waitForClose()` | Promise that resolves when the session closes. |
-
-### SessionEventDTO
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `protocol` | `string` | Protocol name. |
-| `transport` | `string` | Transport label. |
-| `sessionId` | `string` | Unique session identifier. |
-| `direction` | `"in" \| "out" \| "meta"` | Message direction. |
-| `kind` | `string` | Event discriminator (protocol-specific). |
-| `at` | `number` | Epoch ms timestamp. |
-| `state` | `SessionState?` | Session state at the time of the event. |
-| `data` | `Cloneable?` | Message payload. |
-| `error` | `Cloneable?` | Error payload. |
-| `meta` | `Cloneable?` | Metadata (headers, status code, etc.). |
+```typescript
+class OpenApiRequestError extends Error {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: unknown;
+  request: { url: string; method: string; headers: Record<string, string> };
+}
+```
 
 ---
 
-## SendResult
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `protocol` | `ProtocolName` | `"http"` \| `"sse"` \| etc. |
-| `request` | `{ method, url, headers, body? }` | The request that was sent. |
-| `response.status` | `number` | HTTP status code. `0` if no response. |
-| `response.statusText` | `string` | Status text. |
-| `response.headers` | `Record<string,string>` | Response headers (case preserved). |
-| `response.contentType` | `string?` | Parsed content type. |
-| `response.body` | `unknown` | Parsed body (non-streaming). |
-| `response.text` | `string?` | Raw body text. |
-| `response.events` | `StreamEvent[]` | Collected streaming events. |
-| `response.timings` | `{ startedAt, endedAt, durationMs, firstByteMs?, networkDurationMs? }` | Timing data. |
-| `response.sizeBytes` | `number` | Body bytes received. |
-| `response.truncated` | `boolean?` | True if sampling stopped before natural completion. |
-| `response.stopReason` | `StopReason?` | Which limit fired: `"maxEvents" \| "maxStreamMs" \| "maxResponseSize" \| "aborted" \| "hardTimeout"`. |
-| `response.droppedEvents` | `number?` | Events discarded by the parser's size caps. |
-| `scripts` | `ScriptReport?` | Pre-request / test script results. |
-| `cookies` | `Array<{name, value, domain?, path?}>` | Cookies set by the response. |
-| `replays` | `ReplayRecord[]` | Auxiliary traffic (OAuth refreshes, redirects). |
-| `error` | `{ message, code?, name?, stack? }?` | Fatal error, if any. |
-| `collection` | `any` | Generated Postman collection (HTTP only). |
-| `environment` | `any` | Generated Postman environment. |
-| `responseFragment` | `any` | OpenAPI Response object derived from the live call. |
-| `responseStatusCode` | `string` | Status code the fragment was filed under. |
-| `patchedSpec` | `OpenApiDocument?` | Spec with the response merged in. |
-| `writeBackSkippedReason` | `string?` | Why write-back was skipped. |
+## Interceptors
 
----
+```typescript
+import { createClient } from "@powerduck/openapi-request";
 
-## Error Handling
-
-All errors are thrown as `ProtoKitError` with a machine-readable `code`:
-
-| Code | Meaning |
-|------|---------|
-| `BAD_OPTIONS` | Missing or invalid send options. |
-| `BAD_RUN_OPTIONS` | Invalid runtime options (e.g. `maxResponseSize: 0`). |
-| `BAD_COLLECTION` | Failed to construct the Postman collection. |
-| `RUNTIME_INIT` | postman-runtime failed to initialize. |
-| `RUNTIME_RUN` | The run failed with a done error. |
-| `EXECUTION_FAILED` | A protocol adapter threw. |
-| `BAD_MCP_ENDPOINT` | Invalid MCP endpoint URL. |
-| `BAD_MCP_STDIO_COMMAND` | Missing stdio command. |
-| `MCP_TIMEOUT` | MCP request or initialize timed out. |
-| `MCP_NOT_OPEN` | Called before `open()`. |
-| `MCP_SESSION_CLOSED` | Called on a closed session. |
-| `MCP_SESSION_EXPIRED` | Server returned 404 for the session. |
-| `MCP_RPC_ERROR` | JSON-RPC error response. |
-| `MCP_EMPTY_RESPONSE` | No JSON-RPC message in the response. |
-
-```ts
-import { ProtoKitError } from "@powerduck/openapi-request";
-
-try {
-  await client.send(options);
-} catch (err) {
-  if (err instanceof ProtoKitError) {
-    console.error(err.code, err.message);
-  }
-}
+const client = createClient({
+  interceptors: {
+    request: async (request) => {
+      console.log("Request:", request.method, request.url);
+      request.headers["X-Request-ID"] = crypto.randomUUID();
+      return request;
+    },
+    response: async (response) => {
+      console.log("Response:", response.status);
+      return response;
+    },
+    error: async (error) => {
+      if (error.status === 401) {
+        // Refresh token and retry
+        return refreshToken().then(() => client.sendPrepared(error.request));
+      }
+      throw error;
+    },
+  },
+});
 ```
 
 ---
 
-## Development
-
-```bash
-npm install
-npm run build       # tsup → dist/
-npm test            # vitest run (107 tests)
-npm run typecheck   # tsc --noEmit
+## TypeScript Types
+
+```typescript
+import type {
+  OpenApiClient,
+  ClientOptions,
+  SendOptions,
+  PrepareOptions,
+  RequestResult,
+  OpenApiRequestError,
+  ParameterMap,
+  SecurityValues,
+  HttpMethod,
+} from "@powerduck/openapi-request";
 ```
 
-### Test layout
-
-| File | Coverage |
-|------|----------|
-| `tests/sse-parser.test.ts` | 29 tests — SSE parser edge cases, size caps, chunk boundaries. |
-| `tests/runner-options.test.ts` | 19 tests — HTTP option validation and defaults. |
-| `tests/session-hub.test.ts` | 9 tests — event hub, listener safety, ring buffer. |
-| `tests/grpc-session.test.ts` | 10 tests — unary success/error state, streaming, lifecycle. |
-| `tests/ws-session.test.ts` | 10 tests — connect, send/receive, error state, lifecycle. |
-| `tests/client.test.ts` | 8 tests — prepare() protocol inference. |
-| `tests/session.test.ts` | 6 tests — unified createManualSession routing. |
-| `tests/integration.test.ts` | 4 tests — end-to-end HTTP + SSE streaming. |
-| `tests/clone.test.ts` | 8 tests — payload cloning. |
-| `tests/detect.test.ts` | 4 tests — SSE content-type detection. |
+---
 
 ## License
 
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/openapi-request",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "OpenAPI 3.2 collection debugger with HTTP, SSE and WebSocket support, plus response write-back",
   "type": "module",
   "main": "./dist/index.cjs",