Skip to main content

@powerduck/openapi-request Introduction

@powerduck/openapi-request is an OpenAPI 3.2 collection debugger and request runtime. It turns an OpenAPI document into something you can actually drive: it plans a request from the document, sends it, classifies streaming responses, can produce an updated document from observed responses, and speaks six wire protocols behind one small surface.

  • Package name: @powerduck/openapi-request
  • Version:
  • License: MIT
  • Module format: dual ESM and CommonJS builds with bundled type declarations.

What it is​

The library answers three different needs with one document as the source of truth:

  • A UI-first client — createClient() returns an object whose prepare(), send(), connect(), discover() and writeback() methods line up exactly with the steps a graphical request builder walks through.
  • A scripted debugger — createDebugger() returns a ProtoKit with send(), sendMany() and toCollection() for automation, scripts and CI.
  • Long-lived manual sessions — createManualSession() returns a duplex session object (open/send/close + an event stream) that is identical in shape for WebSocket, MCP and gRPC, so one renderer can drive all three.

Protocol adapters​

The core is transport-agnostic; behaviour is supplied by protocol adapters registered in an AdapterRegistry.

  • HTTP / SSE — the default. Plain JSON requests and Server-Sent-Events streams are detected automatically from declared content types or by probing live response headers.
  • WebSocket — duplex text/binary sessions over one event shape.
  • gRPC — unary, server-streaming, client-streaming and bidi calls, driven from .proto files or server reflection.
  • MCP — calls to Model Context Protocol tools over Streamable HTTP or stdio.
  • GraphQL — introspection, operation generation and execution.

Key features​

  • OpenAPI 3.2 collection model — operations are located by operationId or method+path, and requests are planned from parameters, request bodies and examples.
  • Streaming detection — isStreamingOperation(), isSseContentType() and isStreamingContentType() classify a response from declared content types, and probeStreamingResponse() inspects live response headers.
  • Response write-back — inferSchema(), mergeSchema(), toResponseObject() and writeBackResponse() derive response schemas and return an updated document. By default, send() returns it as patchedSpec when write-back succeeds; set writeBack: false to disable this. The input document is not mutated and no file is saved automatically. Check writeBackSkippedReason and writeBackWarnings before persisting the result.
  • Schema helpers — sampleFromSchema() produces example payloads from a schema.
  • Lazy heavy dependencies — gRPC (@grpc/grpc-js, @grpc/proto-loader) and MCP (@modelcontextprotocol/sdk) are loaded on first use, so HTTP-only consumers never pay for them.

Installation​

npm install @powerduck/openapi-request

Quick start​

import { createClient } from "@powerduck/openapi-request";

const spec = {
  openapi: "3.2.0",
  info: { title: "Users", version: "1.0.0" },
  paths: {
    "/users/{id}": {
      get: {
        operationId: "getUserById",
        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
        responses: { "200": { description: "User" } },
      },
    },
  },
};

const client = createClient();

const plan = client.prepare({
  spec,
  target: { operationId: "getUserById" },
});

const result = await client.send({
  spec,
  target: { operationId: "getUserById" },
  values: { path: { id: "42" } },
  serverUrl: "https://api.example.com",
});

Next steps​

  • Installation — package layout, subpath exports and peer capability packages.
  • Quickstart — your first request, debugger run and manual session.
  • Configuration — CreateClientOptions, DebuggerOptions and per-protocol configuration.
  • API Reference — every export grouped by surface area.
  • Examples — runnable recipes for HTTP, SSE, WebSocket, GraphQL, MCP and gRPC.

License​

MIT.