@powerduck/openapi-codegen 0.5.2 → 0.5.3

package/README.md

@@ -1,17 +1,23 @@
 # @powerduck/openapi-codegen
 
-Generate runnable HTTP request examples from OpenAPI documents. Supports 21 languages and 41 language/client combinations. Browser-compatible, zero runtime dependencies.
-
 [![npm version](https://img.shields.io/npm/v/@powerduck/openapi-codegen)](https://www.npmjs.com/package/@powerduck/openapi-codegen)
 [![license](https://img.shields.io/npm/l/@powerduck/openapi-codegen)](https://github.com/PowerDuckie/openapi-codegen/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/@powerduck/openapi-codegen)](https://www.npmjs.com/package/@powerduck/openapi-codegen)
 
-## Links
+Generate runnable HTTP request examples from OpenAPI documents. Supports 21 languages and 41 language/client combinations. Browser-compatible, zero runtime dependencies.
 
-- [Official Website](https://www.powerduck.com/opensource/openapi-codegen.html)
-- [Documentation](https://www.powerduck.com/docs/openapi-codegen/introduction)
-- [Live Demo](https://www.powerduck.com/demo/openapi-codegen.html)
-- [GitHub](https://github.com/PowerDuckie/openapi-codegen)
-- [npm](https://www.npmjs.com/package/@powerduck/openapi-codegen)
+---
+
+Powerduck is an open-source developer tooling platform for teams building modern API workflows.
+
+- **21 Languages** — JavaScript, TypeScript, Python, Go, Rust, Java, PHP, Ruby, C#, Kotlin, Swift, Dart, and more
+- **41 Client Combinations** — fetch, axios, requests, httpx, http.client, Faraday, Guzzle, RestSharp, and more
+- **OpenAPI 3.0/3.1/3.2** — Full support for modern OpenAPI specifications
+- **Security Schemes** — Bearer tokens, API keys, Basic auth, OAuth2, and custom headers
+- **Parameter Handling** — Path, query, header, and cookie parameters with proper encoding
+- **Request Bodies** — JSON, form-data, x-www-form-urlencoded, and raw payloads
+- **Browser Compatible** — Pure TypeScript, no Node.js dependencies, works in any modern browser
+- **Dual ESM/CJS** — Works with `import` and `require`, with bundled TypeScript declarations
 
 ---
 
@@ -39,25 +45,6 @@ const code = generate({
 console.log(code);
 ```
 
-### CommonJS equivalent
-
-```javascript
-const { generate } = require("@powerduck/openapi-codegen");
-const fs = require("node:fs");
-
-const document = JSON.parse(fs.readFileSync("./openapi.json", "utf8"));
-
-const code = generate({
-  document,
-  path: "/pets",
-  method: "post",
-  language: "python",
-  client: "requests",
-});
-
-console.log(code);
-```
-
 ### List available generators
 
 ```typescript
@@ -78,326 +65,144 @@ const code = generate({
   language: "javascript",
   client: "fetch",
   securityValues: {
-    bearerAuth: "YOUR_ACCESS_TOKEN",
-    apiKey: "YOUR_API_KEY",
+    bearerAuth: "your-token-here",
+    apiKey: "your-api-key",
   },
 });
 ```
 
-### Override the server URL
-
-```typescript
-const code = generate({
-  document,
-  path: "/pets",
-  method: "get",
-  language: "shell",
-  client: "curl",
-  serverUrl: "https://staging.example.com/v1",
-});
-```
-
 ---
 
-## Features
-
-- **21 languages, 41 clients** — JavaScript, Python, Go, Java, Ruby, PHP, C#, Rust, Swift, Kotlin, Dart, and more
-- **Full OpenAPI parameter serialization** — path, query, header, cookie parameters with style/explode rules (form, spaceDelimited, pipeDelimited, label, matrix, simple, deepObject)
-- **All body types** — JSON, form-urlencoded, multipart/form-data (text + file fields), XML, text, binary
-- **Security resolution** — Bearer, Basic, API key (header/query/cookie), with `securityValues` for credentials
-- **`$ref` resolution** — in-document JSON Pointer resolution with soft mode for broken/circular refs
-- **Example generation** — generates realistic example values from JSON Schema (respects `example`, `enum`, `const`, `default`, `oneOf`/`anyOf`/`allOf`, types, formats, constraints)
-- **Plugin system** — register custom generators through a simple plugin API
-- **Direct RequestIR** — skip normalization entirely by building a `RequestIR` yourself
-- **Browser-compatible** — zero Node.js dependencies, works in browsers, Edge Functions, and Node.js
-- **Dual ESM/CJS builds** — works with `import` and `require`, with bundled TypeScript declarations
-
----
-
-## GenerateOptions
-
-```typescript
-interface GenerateOptions {
-  language: string;       // Target language identifier (case-sensitive)
-  client: string;         // Target HTTP client identifier
-  request?: RequestIR;    // Pre-normalized request; skips normalize
-  document?: unknown;     // A parsed OpenAPI document object
-  path?: string;          // Exact OpenAPI path template, e.g. "/pets/{id}"
-  method?: string;        // HTTP method, e.g. "get" / "post"
-  serverUrl?: string;     // Override the server URL from the document
-  securityValues?: Record<string, string>; // Credentials keyed by security scheme name
-  softRefMode?: boolean;  // Do not throw on broken/circular $refs
-}
-```
-
-> Either `request` alone, or `document` + `path` + `method`, must be provided. When `request` is supplied, `document`, `path`, `method`, `serverUrl`, `securityValues`, and `softRefMode` are ignored.
-
-### Input validation errors
-
-`generate()` throws when required input is missing:
+## Links
 
-- `TypeError: generate() requires an options object`
-- `Error: Unsupported generator: <language>/<client>`
-- `TypeError: generate() requires either a 'request' or a 'document' option`
-- `TypeError: generate() requires a 'path' option when using 'document'`
-- `TypeError: generate() requires a 'method' option when using 'document'`
+- [Official Website](https://www.powerduck.com/opensource/openapi-codegen.html)
+- [Documentation](https://www.powerduck.com/docs/openapi-codegen/introduction)
+- [Live Demo](https://www.powerduck.com/demo/openapi-codegen)
+- [GitHub](https://github.com/PowerDuckie/openapi-codegen)
+- [npm](https://www.npmjs.com/package/@powerduck/openapi-codegen)
 
 ---
 
-## Top-level API
-
-| Export | Signature | Description |
-|---|---|---|
-| `generate` | `(options: GenerateOptions) => string` | Generate runnable source code for one operation |
-| `register` | `(generator: Generator) => void` | Register a custom generator |
-| `get` | `(language: string, client: string) => Generator \| undefined` | Look up a generator |
-| `list` | `() => Array<{ language: string; client: string }>` | List all registered generators |
-| `use` | `(plugin: Plugin) => void` | Apply a plugin that registers generators |
-| `registerBuiltins` | `() => void` | Register all built-in generators (auto-called on import) |
-| `normalize` | `(options) => NormalizedRequest` | Turn a document + path + method into a normalized request |
-| `builtinGenerators` | `Generator[]` | The raw array of all built-in generator definitions |
-
-Built-ins are registered automatically when the module loads, so calling `registerBuiltins()` manually is optional.
+## Supported Languages & Clients
+
+| Language   | Clients                                            |
+| ---------- | -------------------------------------------------- |
+| JavaScript | fetch, axios, XMLHttpRequest, jQuery, Node.js http |
+| TypeScript | fetch, axios                                       |
+| Python     | requests, httpx, http.client, aiohttp              |
+| Go         | net/http, resty, fasthttp                          |
+| Rust       | reqwest, hyper                                     |
+| Java       | OkHttp, HttpClient, Unirest, Retrofit              |
+| PHP        | cURL, Guzzle, HTTP_Request2                        |
+| Ruby       | Net::HTTP, Faraday, RestClient                     |
+| C#         | HttpClient, RestSharp, WebRequest                  |
+| Kotlin     | OkHttp, Fuel                                       |
+| Swift      | URLSession, Alamofire                              |
+| Dart       | http, Dio                                          |
+| Shell      | cURL, wget, HTTPie                                 |
+| PowerShell | Invoke-RestMethod, Invoke-WebRequest               |
+| R          | httr, RCurl                                        |
+| MATLAB     | webread, urlwrite                                  |
+| Elixir     | HTTPoison, Tesla                                   |
+| Haskell    | http-conduit, wreq                                 |
+| Clojure    | clj-http, http-kit                                 |
+| Scala      | sttp, akka-http                                    |
 
 ---
 
-## Built-in Generators (21 languages, 41 clients)
-
-| Language | `language` | `client` values |
-|---|---|---|
-| C | `c` | `libcurl` |
-| C# | `csharp` | `httpclient`, `restsharp` |
-| Clojure | `clojure` | `clj-http` |
-| Dart | `dart` | `http` |
-| F# | `fsharp` | `httpclient` |
-| Go | `go` | `new-request` |
-| HTTP request file | `http` | `http1` |
-| Java | `java` | `asynchttp`, `java-net-http`, `okhttp`, `unirest` |
-| JavaScript | `javascript` | `axios`, `fetch`, `jquery`, `ofetch`, `xhr` |
-| Kotlin | `kotlin` | `okhttp` |
-| Node.js | `node` | `axios`, `fetch`, `ofetch`, `undici` |
-| Objective-C | `objc` | `nsurlsession` |
-| OCaml | `ocaml` | `cohttp` |
-| PHP | `php` | `curl`, `guzzle`, `laravel-http` |
-| PowerShell | `powershell` | `invoke-restmethod`, `invoke-webrequest` |
-| Python | `python` | `aiohttp`, `http-client`, `httpx-async`, `httpx-sync`, `requests` |
-| R | `r` | `httr2` |
-| Ruby | `ruby` | `net-http` |
-| Rust | `rust` | `reqwest` |
-| Shell | `shell` | `curl`, `httpie`, `wget` |
-| Swift | `swift` | `nsurlsession` |
-
-> Generator availability does not mean every client can represent every operation. For example, `shell/wget` cannot safely build arbitrary `multipart/form-data` requests; use `shell/curl` or `shell/httpie` instead.
-
----
+## API Reference
 
-## Custom Generator
+### `generate(options)`
 
-Implement the `Generator` interface and call `register`:
+Generate HTTP request code from an OpenAPI document.
 
 ```typescript
-import { register, generate } from "@powerduck/openapi-codegen";
-import type { RequestIR } from "@powerduck/openapi-codegen";
-
-register({
-  language: "mylang",
-  client: "my-client",
-  generate(request: RequestIR): string {
-    return [
-      `// ${request.method} ${request.baseUrl}${request.path}`,
-      `mylang.request(${JSON.stringify({
-        method: request.method,
-        url: request.baseUrl + request.path,
-      })})`,
-    ].join("\n");
-  },
-});
+import { generate } from "@powerduck/openapi-codegen";
 
 const code = generate({
-  document,
+  document: openApiDocument,
   path: "/pets",
-  method: "get",
-  language: "mylang",
-  client: "my-client",
+  method: "post",
+  language: "python",
+  client: "requests",
+  securityValues: { bearerAuth: "token" },
+  parameterValues: { limit: 10, offset: 0 },
 });
 ```
 
----
+#### Options
+
+| Option            | Type                      | Required | Description                                                |
+| ----------------- | ------------------------- | -------- | ---------------------------------------------------------- |
+| `document`        | `OpenAPIDocument`         | Yes      | Parsed OpenAPI document object                             |
+| `path`            | `string`                  | Yes      | API path (e.g., `/pets/{id}`)                              |
+| `method`          | `string`                  | Yes      | HTTP method (get, post, put, delete, patch, head, options) |
+| `language`        | `string`                  | Yes      | Target language                                            |
+| `client`          | `string`                  | Yes      | HTTP client library                                        |
+| `securityValues`  | `Record<string, string>`  | No       | Security scheme values                                     |
+| `parameterValues` | `Record<string, unknown>` | No       | Parameter values                                           |
+| `requestBody`     | `unknown`                 | No       | Request body value                                         |
+| `headers`         | `Record<string, string>`  | No       | Additional headers                                         |
+| `timeout`         | `number`                  | No       | Request timeout in ms                                      |
+| `indent`          | `string`                  | No       | Indentation string (default: 2 spaces)                     |
+| `quote`           | `"single" \| "double"`    | No       | Quote style (default: language-specific)                   |
 
-## Plugin
+### `list()`
 
-A plugin bundles one or more generator registrations through `use()`:
+List all available language/client combinations.
 
 ```typescript
-import { use, generate } from "@powerduck/openapi-codegen";
-
-use({
-  name: "internal-generators",
-  register(api) {
-    api.register({
-      language: "go",
-      client: "our-wrapper",
-      generate(request) {
-        return `// go wrapper for ${request.method} ${request.path}`;
-      },
-    });
-    api.register({
-      language: "ruby",
-      client: "our-wrapper",
-      generate(request) {
-        return `# ruby wrapper for ${request.method} ${request.path}`;
-      },
-    });
-  },
-});
+import { list } from "@powerduck/openapi-codegen";
 
-const code = generate({
-  document,
-  path: "/pets",
-  method: "get",
-  language: "go",
-  client: "our-wrapper",
-});
+const generators = list();
+// [{ language: "javascript", client: "fetch" }, ...]
 ```
 
----
-
-## Generate from a Direct RequestIR
+### `normalize(document)`
 
-Skip `normalize` entirely by building a `RequestIR` yourself:
+Normalize and validate an OpenAPI document.
 
 ```typescript
-import { generate } from "@powerduck/openapi-codegen";
-import type { RequestIR } from "@powerduck/openapi-codegen";
-
-const request: RequestIR = {
-  method: "GET",
-  baseUrl: "https://api.example.com",
-  path: "/users/{id}",
-  parameters: [
-    { name: "id", in: "path", value: 123 },
-    { name: "limit", in: "query", value: 10, style: "form", explode: true },
-  ],
-  headers: [
-    { name: "Accept", in: "header", value: "application/json" },
-  ],
-  body: undefined,
-  security: [],
-};
+import { normalize } from "@powerduck/openapi-codegen";
 
-const code = generate({
-  request,
-  language: "python",
-  client: "requests",
-});
+const normalized = normalize(rawDocument);
 ```
 
 ---
 
-## Core Types
+## TypeScript Types
 
 ```typescript
-type ParameterLocation = "path" | "query" | "querystring" | "header" | "cookie";
-
-interface Parameter {
-  name: string;
-  in: ParameterLocation;
-  value: unknown;
-  style?: string;
-  explode?: boolean;
-  allowReserved?: boolean;
-}
-
-interface Body {
-  mediaType: string;
-  value: unknown;
-  encoding?: Record<string, unknown>;
-}
-
-interface Security {
-  name: string;
-  type: string;
-  scheme?: string;
-  in?: string;
-  paramName?: string;
-  value: string;
-}
-
-interface RequestIR {
-  method: string;
-  baseUrl: string;
-  path: string;
-  parameters: Parameter[];
-  headers: Parameter[];
-  body?: Body;
-  security: Security[];
-}
-
-interface Generator {
-  language: string;
-  client: string;
-  generate(request: RequestIR): string;
-}
-
-interface Plugin {
-  name: string;
-  register(api: { register(generator: Generator): void }): void;
-}
+import type {
+  GenerateOptions,
+  GeneratorInfo,
+  OpenAPIDocument,
+  SecurityScheme,
+  Parameter,
+  RequestBody,
+} from "@powerduck/openapi-codegen";
 ```
 
 ---
 
-## Error Handling
+## Browser Usage
 
-`generate()` throws for missing input or unsupported generators. Wrap calls when processing untrusted documents:
+```html
+<script type="module">
+  import { generate, list } from "https://esm.sh/@powerduck/openapi-codegen";
 
-```typescript
-try {
   const code = generate({
-    document,
-    path: "/pets/{id}",
+    document: openApiDoc,
+    path: "/users",
     method: "get",
     language: "javascript",
     client: "fetch",
   });
-  console.log(code);
-} catch (error) {
-  console.error("Generation failed:", error instanceof Error ? error.message : 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
+</script>
 ```
 
 ---
 
-## Related Packages
-
-- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
-- [`@powerduck/openapi-request`](https://www.npmjs.com/package/@powerduck/openapi-request) — Execute OpenAPI operations with full parameter serialization
-- [`@powerduck/openapi-cli`](https://www.npmjs.com/package/@powerduck/openapi-cli) — CI-ready batch testing for OpenAPI documents
-- [`@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-codegen",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Generate runnable HTTP request examples from OpenAPI documents. 21 languages, 41 clients, browser-compatible, zero runtime dependencies.",
   "type": "module",
   "main": "./dist/index.cjs",