@powerduck/openapi-request 0.2.3 → 0.2.4

package/README.md

@@ -1,17 +1,25 @@
 # @powerduck/openapi-request
 
-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.
-
 [![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)
 
-## Links
+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.
 
-- [Official Website](https://www.powerduck.com/opensource/openapi-request.html)
-- [Documentation](https://www.powerduck.com/docs/openapi-request/introduction)
-- [Live Demo](https://www.powerduck.com/demo/openapi-request.html)
-- [GitHub](https://github.com/PowerDuckie/openapi-request)
-- [npm](https://www.npmjs.com/package/@powerduck/openapi-request)
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
+
+- **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
 
 ---
 
@@ -39,9 +47,9 @@ const result = await client.send({
   },
 });
 
-console.log(result.response.status);   // e.g. 200
-console.log(result.response.body);     // parsed response body
-console.log(result.response.headers);  // response headers
+console.log(result.response.status); // e.g. 200
+console.log(result.response.body); // parsed response body
+console.log(result.response.headers); // response headers
 ```
 
 ### Prepare and send separately
@@ -60,368 +68,205 @@ const prepared = client.prepare({
   },
 });
 
-console.log(prepared.url);      // final URL with query string
-console.log(prepared.method);   // HTTP method
-console.log(prepared.headers);  // resolved headers
+console.log(prepared.url); // final URL with serialized params
+console.log(prepared.method); // HTTP method
+console.log(prepared.headers); // resolved headers
 
 // Send the prepared request
-const result = await client.send(prepared);
+const result = await client.sendPrepared(prepared);
 ```
 
-### With security values
+### With authentication
 
 ```typescript
 import { createClient } from "@powerduck/openapi-request";
 
 const client = createClient({
   securityValues: {
-    bearerAuth: "YOUR_ACCESS_TOKEN",
-    apiKey: "YOUR_API_KEY",
+    bearerAuth: "your-token-here",
+    apiKey: "your-api-key",
   },
 });
 
 const result = await client.send({
   spec: openApiDocument,
-  operationId: "createUser",
-  parameters: {
-    body: { name: "Ada", email: "ada@example.com" },
-  },
+  operationId: "getProfile",
 });
 ```
 
-### Custom fetch function
+---
 
-```typescript
-import { createClient } from "@powerduck/openapi-request";
+## Links
 
-const client = createClient({
-  fetchFn: async (url, init) => {
-    console.log("Request:", init.method, url);
-    const response = await fetch(url, init);
-    console.log("Response:", response.status);
-    return response;
-  },
-});
-```
+- [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)
 
 ---
 
 ## Features
 
-- **Full OpenAPI parameter serialization** — path, query, header, cookie parameters with all `style` and `explode` combinations (form, spaceDelimited, pipeDelimited, label, matrix, simple, deepObject)
-- **Security resolution** — Bearer, Basic, API key (header/query/cookie), with per-request or client-level `securityValues`
-- **Request body handling** — JSON, form-urlencoded, multipart/form-data (text + file fields), XML, text, binary
-- **Response parsing** — automatic JSON parsing, text fallback, content-type detection
-- **Two-phase execution** — `prepare()` builds the request without sending, `send()` executes it
-- **Custom HTTP client** — plug in fetch, axios, node-fetch, or any compatible function
-- **Server URL selection** — override or select from spec `servers` array
-- **Timeout and abort** — per-request timeout with `AbortController` integration
-- **Postman script support** — run `pm.test()` / `pm.expect()` scripts from `x-postman-scripts`
-- **Batch requests** — send multiple operations with configurable concurrency
-- **Browser and Node.js compatible** — works in browsers, Edge Functions, and Node.js
-- **Dual ESM/CJS builds** — works with `import` and `require`, with bundled TypeScript declarations
+- **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
 
 ---
 
-## API
-
-### `createClient(options?: CreateClientOptions): OpenApiClient`
-
-Creates a new client instance.
-
-```typescript
-interface CreateClientOptions {
-  fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
-  securityValues?: Record<string, string>;
-  serverUrl?: string;
-  timeoutMs?: number;
-  validateResponse?: boolean;
-}
-```
-
-### `client.send(options: SendOptions): Promise<SendResult>`
-
-Prepares and sends a request in one call.
-
-### `client.prepare(options: SendOptions): PreparedRequest`
-
-Builds the request without sending. Returns a `PreparedRequest` that can be inspected or passed to `send()`.
+## API Reference
 
-### `SendOptions`
+### `createClient(options?)`
 
-```typescript
-interface SendOptions {
-  spec: OpenApiDocument;       // Parsed OpenAPI 3.2 document
-  operationId?: string;         // Operation ID (alternative to path + method)
-  path?: string;                // Path template, e.g. "/users/{id}"
-  method?: string;              // HTTP method, e.g. "get"
-  parameters?: {
-    path?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    header?: Record<string, string>;
-    cookie?: Record<string, string>;
-    body?: unknown;
-  };
-  securityValues?: Record<string, string>;
-  serverUrl?: string;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-}
-```
-
-> Either `operationId` or `path` + `method` must be provided to identify the operation.
-
-### `SendResult`
+Create an OpenAPI request client.
 
 ```typescript
-interface SendResult extends ExecResult {
-  response: {
-    status: number;           // HTTP status code
-    statusText: string;       // HTTP status text
-    headers: Record<string, string>; // Response headers
-    body?: unknown;           // Parsed JSON body (if content-type is JSON)
-    text?: string;            // Raw response text
-  };
-  timings: {
-    durationMs: number;       // Total request duration in milliseconds
-  };
-  sizeBytes: number;          // Response body size in bytes
-}
-```
-
-> **Important:** Response data is under `result.response`, not directly on `result`. Use `result.response.status`, `result.response.body`, and `result.response.headers`.
-
-### `PreparedRequest`
+import { createClient } from "@powerduck/openapi-request";
 
-```typescript
-interface PreparedRequest {
-  url: string;                 // Final URL with query string
-  method: string;              // HTTP method
-  headers: Record<string, string>; // Resolved headers
-  body?: BodyInit;             // Request body (if any)
-  operationId?: string;        // Resolved operation ID
-  path: string;                // Path template
-  parameters: ResolvedParameters;
-}
+const client = createClient({
+  client: "fetch", // "fetch" | "axios" | custom adapter
+  baseUrl: "https://api.example.com",
+  securityValues: { bearerAuth: "token" },
+  defaultHeaders: { "X-App": "my-app" },
+  timeout: 30000,
+});
 ```
 
----
-
-## Parameter Serialization
+### `client.send(options)`
 
-All OpenAPI 3.2 parameter styles are supported:
-
-| Location | Style | `explode: true` | `explode: false` |
-|---|---|---|---|
-| `path` | `simple` (default) | `id=5,role=admin` | `id,role=5,admin` |
-| `path` | `label` | `.id=5.role=admin` | `.id,role=5,admin` |
-| `path` | `matrix` | `;id=5;role=admin` | `;id,role=5,admin` |
-| `query` | `form` (default) | `id=5&role=admin` | `id=5,role=admin` |
-| `query` | `spaceDelimited` | `id=5%20role=admin` | `id=5%20role=admin` |
-| `query` | `pipeDelimited` | `id=5\|role=admin` | `id=5\|role=admin` |
-| `query` | `deepObject` | `user[id]=5&user[role]=admin` | — |
-| `header` | `simple` (default) | `id=5,role=admin` | `id,role=5,admin` |
-| `cookie` | `form` (default) | `id=5; role=admin` | `id=5,role=admin` |
-
----
-
-## Security Schemes
-
-### Bearer token
+Send an OpenAPI operation.
 
 ```typescript
 const result = await client.send({
-  spec,
+  spec: openApiDocument,
   operationId: "getUser",
-  securityValues: { bearerAuth: "YOUR_TOKEN" },
+  parameters: {
+    path: { id: "123" },
+    query: { include: ["profile", "orders"] },
+    header: { "X-Request-ID": "abc" },
+  },
+  requestBody: { name: "Ada" },
+  securityValues: { bearerAuth: "token" },
+  serverIndex: 0,
+  signal: abortSignal,
 });
-// Sends: Authorization: Bearer YOUR_TOKEN
 ```
 
-### Basic auth
-
-```typescript
-const result = await client.send({
-  spec,
-  operationId: "getUser",
-  securityValues: { basicAuth: "username:password" },
-});
-// Sends: Authorization: Basic <base64(username:password)>
-```
+### `client.prepare(options)`
 
-### API key (header)
+Prepare a request without sending.
 
 ```typescript
-const result = await client.send({
-  spec,
-  operationId: "getUser",
-  securityValues: { apiKeyHeader: "YOUR_KEY" },
+const prepared = client.prepare({
+  spec: openApiDocument,
+  operationId: "listUsers",
+  parameters: { query: { page: 1 } },
 });
-// Sends: X-API-Key: YOUR_KEY (header name from spec)
-```
 
-### API key (query)
-
-```typescript
-const result = await client.send({
-  spec,
-  operationId: "getUser",
-  securityValues: { apiKeyQuery: "YOUR_KEY" },
-});
-// Appends: ?api_key=YOUR_KEY (param name from spec)
+// prepared.url, prepared.method, prepared.headers, prepared.body
 ```
 
----
-
-## Request Body Examples
+### `client.sendPrepared(prepared)`
 
-### JSON
+Send a previously prepared request.
 
 ```typescript
-const result = await client.send({
-  spec,
-  operationId: "createUser",
-  parameters: {
-    body: { name: "Ada", email: "ada@example.com" },
-  },
-});
+const result = await client.sendPrepared(prepared);
 ```
 
-### Form URL-encoded
+### Result Type
 
 ```typescript
-const result = await client.send({
-  spec,
-  operationId: "login",
-  parameters: {
-    body: { username: "ada", password: "secret" },
-  },
-});
+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
+}
 ```
 
-### Multipart Form Data
+### Error Type
 
 ```typescript
-const result = await client.send({
-  spec,
-  operationId: "uploadFile",
-  parameters: {
-    body: {
-      title: "My Document",
-      file: new File(["content"], "doc.pdf", { type: "application/pdf" }),
-    },
-  },
-});
+class OpenApiRequestError extends Error {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: unknown;
+  request: { url: string; method: string; headers: Record<string, string> };
+}
 ```
 
 ---
 
-## Batch Requests
+## Interceptors
 
 ```typescript
 import { createClient } from "@powerduck/openapi-request";
 
-const client = createClient();
-
-const results = await client.sendBatch([
-  { spec, operationId: "getUser", parameters: { path: { id: "1" } } },
-  { spec, operationId: "getUser", parameters: { path: { id: "2" } } },
-  { spec, operationId: "getUser", parameters: { path: { id: "3" } } },
-], { concurrency: 2 });
-
-results.forEach((r, i) => {
-  if ("error" in r) {
-    console.log(`Request ${i} failed:`, r.error);
-  } else {
-    console.log(`Request ${i} status:`, r.response.status);
-  }
+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;
+    },
+  },
 });
 ```
 
 ---
 
-## Postman Scripts
-
-Run Postman test scripts embedded in `x-postman-scripts`:
+## TypeScript Types
 
 ```typescript
-import { createClient, runPostmanScripts } from "@powerduck/openapi-request";
-
-const client = createClient();
-const result = await client.send({
-  spec,
-  operationId: "listUsers",
-});
-
-// Run pm.test() scripts from the operation's x-postman-scripts
-const testResults = runPostmanScripts(spec, "listUsers", result.response);
-
-console.log("Passed:", testResults.passed);
-console.log("Failed:", testResults.failed);
-for (const test of testResults.tests) {
-  console.log(`${test.passed ? "✓" : "✗"} ${test.name}`);
-}
+import type {
+  OpenApiClient,
+  ClientOptions,
+  SendOptions,
+  PrepareOptions,
+  RequestResult,
+  OpenApiRequestError,
+  ParameterMap,
+  SecurityValues,
+  HttpMethod,
+} from "@powerduck/openapi-request";
 ```
 
 ---
 
-## Error Handling
-
-```typescript
-try {
-  const result = await client.send({
-    spec,
-    operationId: "getUser",
-    parameters: { path: { id: "123" } },
-  });
-
-  if (result.response.status >= 400) {
-    console.error("API error:", result.response.status, result.response.body);
-  }
-} catch (error) {
-  if (error.name === "AbortError") {
-    console.error("Request timed out or was aborted");
-  } else if (error.name === "OpenApiRequestError") {
-    console.error("Request preparation failed:", error.message);
-  } else {
-    console.error("Network error:", error);
-  }
-}
-```
-
----
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Type check
-npm run typecheck
-
-# Build (ESM + CJS + type declarations)
-npm run build
-
-# Run tests
-npm test
-
-# Watch mode
-npx vitest watch
-```
-
----
-
-## Related Packages
-
-- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
-- [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
-- [`@powerduck/openapi-cli`](https://www.npmjs.com/package/@powerduck/openapi-cli) — CI-ready batch testing for OpenAPI documents
-- [`@powerduck/openapi-mcp-server`](https://www.npmjs.com/package/@powerduck/openapi-mcp-server) — Turn OpenAPI docs into MCP servers
-- [`@powerduck/x-to-openapi`](https://www.npmjs.com/package/@powerduck/x-to-openapi) — Convert curl commands and Postman Collections to OpenAPI 3.2
-
----
-
 ## License
 
-MIT
+MIT © [POWERDUCK LIMITED](https://www.powerduck.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerduck/openapi-request",
-  "version": "0.2.3",
+  "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",