@techspokes/typescript-wsdl-client 0.6.3 → 0.7.0

package/README.md

@@ -7,223 +7,299 @@
 [![GitHub Stars](https://img.shields.io/github/stars/techspokes/typescript-wsdl-client?style=social)](https://github.com/techspokes/typescript-wsdl-client/stargazers)
 [![GitHub Forks](https://img.shields.io/github/forks/techspokes/typescript-wsdl-client?style=social)](https://github.com/techspokes/typescript-wsdl-client/network/members)
 [![GitHub Watchers](https://img.shields.io/github/watchers/techspokes/typescript-wsdl-client?style=social)](https://github.com/techspokes/typescript-wsdl-client/watchers)
-
 [![TechSpokes Org](https://img.shields.io/badge/org-techspokes-181717?logo=github)](https://github.com/techspokes)
-[![Sponsor TechSpokes](https://img.shields.io/badge/sponsor-GitHub-blue?logo=github-sponsors)](https://github.com/sponsors/TechSpokes)
-
-## Introduction
-
-- TypeScript WSDL Client transforms WSDL/XSD schemas into a fully-typed, ready-to-use SOAP client for TypeScript.
-- Eliminates common SOAP pain points: inconsistent XML mappings, complex type inheritance, and module interop headaches.
-- Generates maintainable, diff-friendly code that runs in modern Node.js (ESM/CJS) and strict TypeScript.
+[![Sponsor](https://img.shields.io/badge/sponsor-GitHub-blue?logo=github-sponsors)](https://github.com/sponsors/TechSpokes)
 
-With this tool you get:
-- End-to-end type safety: generated interfaces, aliases, and marshalling/unmarshalling logic.
-- Deterministic JSON ⇄ SOAP metadata: clear attribute vs element ordering.
-- Flexible primitive mapping: control decimals, dates, integers, and more via flags.
-- Automatic flattening of `<complexContent>`/`<simpleContent>` inheritance.
-- `<choice>` handling strategies and WS-Policy security hints baked in.
-- Pluggable ESM/CJS imports: target your runtime with `--imports` alone.
-
-Vendor: **[TechSpokes](https://www.techspokes.com)**  
-Maintainer: **Serge Liatko** ([@sergeliatko](https://github.com/sergeliatko))  
+> **Mission**: Turn complex WSDL/XSD definitions into ergonomic, stable, type‑safe TypeScript SOAP clients — with an optional OpenAPI 3.1 bridge — so you can integrate legacy enterprise services confidently.
 
 ---
+## 1. Why This Project (What Sets It Apart)
+Most generators stop at loosely typed stubs or leak XML complexity into your application layer. This tool focuses on **correct flattening and determinism**:
+
+| Core Differentiator | What You Get |
+|---------------------|--------------|
+| Attribute + Element Flattening | Attributes and child elements appear as peer properties (no nested wrapper noise). |
+| `$value` Text Content Convention | Simple & mixed content always represented as a `$value` property (collision-safe & documented). |
+| Inheritance Resolution | `complexContent` and `simpleContent` extensions are merged or extended consistently. |
+| Choice Strategy | Predictable `all-optional` modeling today (future advanced discriminators planned). |
+| WS‑Policy Security Hints | Inline scan of policies surfaces required auth hints (e.g. `usernameToken`, `https`). |
+| Deterministic Output | Sorted declarations and stable alias resolution for diff‑friendly regeneration. |
+| Primitive Mapping Controls | Explicit flags for long / big integer / decimal / temporal families (string‑first safety). |
+| Catalog Introspection | One JSON artifact (`catalog.json`) to drive further tooling (including OpenAPI). |
+| OpenAPI 3.1 Bridge | Mirrors the exact TypeScript model — no divergence between runtime and spec. |
+| Multi‑format Output | `--format json|yaml|both` with always‑on validation (unless disabled). |
+| One‑Shot Pipeline | Single pass (parse → TS → OpenAPI) for CI & automation. |
+
+**Vendor**: [TechSpokes](https://www.techspokes.com) · **Maintainer**: Serge Liatko ([@sergeliatko](https://github.com/sergeliatko))
 
-## Installation
-
-Install the generator as a development dependency:
 
+---
+## 2. Installation
 ```bash
 npm i -D @techspokes/typescript-wsdl-client
-# Your app will use node-soap at runtime:
-npm i soap
+npm i soap   # runtime dependency for actual SOAP calls
 ```
 
 ---
+## 3. Typical Repository Layout
+You usually want generated SOAP clients under a namespaced integration folder. Examples:
+```
+src/
+  services/
+    third-party/
+      weather/
+        client.ts
+        types.ts
+        utils.ts
+        catalog.json
+        openapi.json
+```
+Pick a structure that communicates ownership and stability. Regenerate into the same folder for clean diffs.
 
-## Quick Start
-
-### Generate a SOAP Client
-
-Run the following command to generate a client from your WSDL file:
+---
+## 4. Primary Usage: Generate a TypeScript SOAP Client
+The **SOAP client generation** is the core of this project and the most common use case.
 
+### 4.1 Quick Start
 ```bash
-npx wsdl-tsc --wsdl ./spec/wsdl/MyService.wsdl --out ./src/services/my-service
+npx wsdl-tsc --wsdl ./wsdl/Weather.wsdl --out ./src/services/third-party/weather
 ```
 
-### Use the Generated Client
+**Try with included example:**
+```bash
+npx wsdl-tsc --wsdl examples/minimal/weather.wsdl --out ./tmp/weather
+```
 
+Imports afterward:
 ```ts
-import soap from "soap";
-import { MyService } from "./services/my-service/client.js";
+import { Weather } from "../services/third-party/weather/client.js";
+```
 
-const client = new MyService({
-  source: "https://example.com/MyService?wsdl",
-  security: new soap.WSSecurity("user", "pass")
-});
+### 4.2 What Gets Generated
+| File | Purpose |
+|------|---------|
+| `client.ts` | Strongly typed wrapper with one method per operation. |
+| `types.ts` | Flattened interfaces & literal/enum aliases. |
+| `utils.ts` | Metadata (attribute vs element, occurrence, nillable). |
+| `catalog.json` | (If `--catalog`) compiled representation for debugging / OpenAPI reuse. |
+
+### 4.3 Key Modeling Rules Recap
+- **Attributes & elements** → peer properties.
+- **Text content** → `$value`.
+- **Required attributes**: `use!=optional`; elements `min>=1`.
+- **Multiplicity**: `max>1` or `unbounded` → arrays.
+- **Nillable**: `nillable="true"` preserved (optionally modelled optional with `--nillable-as-optional`).
+- **Inheritance**: extensions merged or emitted as extends; simpleContent base collapsed logically.
+
+### 4.4 CLI Flags (SOAP Client)
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wsdl` | (required) | Local path or URL to WSDL. |
+| `--out` | (required) | Output directory. |
+| `--imports` | `js` | Intra‑generated import style: `js`, `ts`, `bare`. |
+| `--catalog` | `false` | Emit `catalog.json`. |
+| `--client-name` | derived | Override exported class name. |
+| `--attributes-key` | `$attributes` | Attribute bag key. |
+| `--choice` | `all-optional` | Current choice strategy. |
+| `--nillable-as-optional` | `false` | Treat nillable elements as optional props. |
+| `--fail-on-unresolved` | `true` | Fail build on unresolved references. |
+| `--int64-as` | `string` | Map 64‑bit integer types. |
+| `--bigint-as` | `string` | Map arbitrary-size integer family. |
+| `--decimal-as` | `string` | Map `xs:decimal`. |
+| `--date-as` | `string` | Map date/time/duration primitives. |
+
+### 4.5 Example With Safer Numeric Decisions
+```bash
+npx wsdl-tsc \
+  --wsdl https://example.com/Hotel.wsdl \
+  --out ./src/integrations/soap/hotel \
+  --int64-as number \
+  --decimal-as string \
+  --date-as string \
+  --catalog
+```
 
-const response = await client.MyOperation({
-  MyOperationRQ: {
-    MyElement: {
-      MyAttribute: "value",
-      ChildElementA: "valueA",
-    },
-  },
+### 4.6 Programmatic Generation (TypeScript Only)
+```ts
+import { compileWsdlToProject } from "@techspokes/typescript-wsdl-client";
+await compileWsdlToProject({
+  wsdl: "./wsdl/Hotel.wsdl",
+  outDir: "./src/integrations/soap/hotel"
 });
-
-console.log(response);
 ```
 
 ---
+## 5. Generating an OpenAPI 3.1 Definition (as a standalone run)
+If you already have generated your SOAP client and just want an HTTP-friendly spec for proxies / gateways / docs:
+```bash
+npx wsdl-tsc openapi --wsdl ./wsdl/Hotel.wsdl --out ./openapi/hotel --format both
+```
+Or reuse a previously generated catalog:
+```bash
+npx wsdl-tsc openapi --catalog ./src/integrations/soap/hotel/catalog.json --out ./openapi/hotel
+```
 
-## Features
-
-- **Primitive-type mapping**: Fine-grained flags (`--int64-as`, `--bigint-as`, `--decimal-as`, `--date-as`) so you don't have to hand-roll conversions for odd XSD primitives.
-- **Complex/simpleContent inheritance**: Automatically flattens and extends base types for `<complexContent>` and `<simpleContent>` extensions.
-- **Deterministic metadata**: Emits runtime maps for JSON ⇄ SOAP mapping—clear attribute vs element distinctions and order.
-- **Choice element support**: Two modes (`all-optional` or `union`) to handle `<choice>` constructs exactly how you need.
-- **Fail-fast unresolved references**: `--fail-on-unresolved` aborts codegen on missing type refs to catch XSD import issues early.
-- **WS-Policy security hints**: Parses WS-Policy tokens and surfaces required security hints in generated JSDoc.
-- **Full catalog introspection**: `--catalog` emits a JSON dump of the compiled schema for debugging large/malformed WSDLs.
-- **Stable, sorted output**: Interfaces, aliases, attributes, and elements are consistently sorted for diff-friendly regeneration.
-- **ESM/CJS interop & custom imports**: `--imports js|ts|bare` lets you target your module system without manual edits.
-- **Attributes and child elements**: Supports both XML attributes and nested elements (including mixed `$value` content).
-- **Security integration**: Works with any `soap.ISecurity` (e.g., `WSSecurity`, `BasicAuthSecurity`) for seamless auth.
+### 5.1 Formats & Validation
+| Flag | Purpose |
+|------|---------|
+| `--format json|yaml|both` | Output format (default json). |
+| `--yaml` | (Deprecated) alias for `--format yaml` when format absent. |
+| `--validate/--no-validate` | Validation on by default. |
+| `--out` | Base path or explicit file (extension optional). |
+
+### 5.2 Core Schema Parity
+The OpenAPI schemas reproduce the **exact** flattening & naming used in `types.ts` — crucial for avoiding drift between SOAP and REST surfaces.
+
+### 5.3 Additional Flags (Selected)
+| Flag | Description |
+|------|-------------|
+| `--basePath` | Prefix for REST path segments (e.g. `/v1/booking`). |
+| `--pathStyle kebab|asis|lower` | Control operation name → path transformation. |
+| `--method` | Default HTTP method (per‑op override via `--ops`). |
+| `--tag-style` | Tag inference: `default`, `service`, `first`. |
+| `--security` | Path to `security.json` (schemes + headers + overrides). |
+| `--tags` | Path to `tags.json` (explicit operation → tag map). |
+| `--ops` | Path to `ops.json` (method/summary/description/deprecated). |
+| `--closedSchemas` | Apply `additionalProperties:false` globally. |
+| `--pruneUnusedSchemas` | Emit only reachable schemas. |
+
+### 5.4 Programmatic OpenAPI Generation
+```ts
+import { generateOpenAPI } from "@techspokes/typescript-wsdl-client";
+const { jsonPath, yamlPath } = await generateOpenAPI({
+  wsdl: "./wsdl/Hotel.wsdl",
+  outFile: "./openapi/hotel",
+  format: "both"
+});
+```
 
 ---
-
-## CLI Usage
-
+## 6. One‑Shot Pipeline (SOAP Client + OpenAPI Together)
+Ideal for CI: single WSDL parse → TS artifacts + catalog + OpenAPI (validated).
 ```bash
-wsdl-tsc --wsdl <path-or-url> --out <dir> [options]
+npx wsdl-tsc pipeline --wsdl ./wsdl/Hotel.wsdl --out ./src/integrations/soap/hotel --format both
 ```
 
-### Required Flags
-- `--wsdl`: Path or URL to the WSDL file.
-- `--out`: Output directory for the generated files.
+| Pipeline Flag | Default | Notes |
+|---------------|---------|-------|
+| All SOAP flags | — | Same semantics as base generation. |
+| All OpenAPI flags | — | Same semantics as standalone openapi. |
+| `--openapi-out` | derived | Override OpenAPI base file. |
+| `--format` | json | Multi-format control. |
+| `--validate/--no-validate` | validate | Spec validation toggle. |
+| `--tag-style` | default | Tag inference. |
 
-### Options
-
-| Flag                   | Type      | Choices                        | Default        | Description                                                      |
-|------------------------|-----------|--------------------------------|----------------|------------------------------------------------------------------|
-| `--imports`            | string    | js, ts, bare                   | js             | Intra-generated import specifiers: '.js', '.ts', or bare         |
-| `--catalog`            | boolean   | true, false                    | false          | Emit catalog.json for introspection                              |
-| `--client-name`        | string    | —                              | derived        | Override the exported client class name                          |
-| `--attributes-key`     | string    | any                            | $attributes    | Key used by runtime marshaller for XML attributes                |
-| `--int64-as`           | string    | string, number, bigint         | string         | How to map xs:long/xs:unsignedLong                               |
-| `--bigint-as`          | string    | string, number                 | string         | How to map xs:integer family (positive/nonNegative/etc.)         |
-| `--decimal-as`         | string    | string, number                 | string         | How to map xs:decimal (money/precision)                          |
-| `--date-as`            | string    | string, Date                   | string         | How to map date/time/duration types                              |
-| `--choice`             | string    | all-optional, union            | all-optional   | Representation of `<choice>` elements                            |
-| `--fail-on-unresolved` | boolean   | true, false                    | true           | Fail if any type references cannot be resolved                   |
-| `--nillable-as-optional` | boolean | true, false                    | false          | Treat nillable elements as optional properties in types          |
+Programmatic single pass:
+```ts
+import { runGenerationPipeline } from "@techspokes/typescript-wsdl-client";
+await runGenerationPipeline({
+  wsdl: "./wsdl/Hotel.wsdl",
+  outDir: "./src/integrations/soap/hotel",
+  openapi: { format: "both", tagStyle: "service" }
+});
+```
 
 ---
-
-## Generated Files
-
-The generator produces the following files in the output directory:
-
-```
-<out>/
-  types.ts       # TypeScript interfaces and type aliases
-  utils.ts       # Runtime metadata for JSON ⇄ SOAP mapping
-  client.ts      # Strongly-typed SOAP client wrapper
-  catalog.json   # (optional) Compiled catalog JSON if `--catalog` is set
+## 7. Security Configuration (OpenAPI)
+`security.json` example:
+```json
+{
+  "global": {
+    "scheme": "bearer",
+    "bearer": { "bearerFormat": "JWT" },
+    "headers": [ { "name": "X-Correlation-Id", "required": false, "schema": { "type": "string" } } ]
+  },
+  "overrides": {
+    "CancelBooking": { "scheme": "apiKey" }
+  }
+}
 ```
+Supported `scheme`: `none|basic|bearer|apiKey|oauth2`.
 
 ---
+## 8. Tag Inference Strategies
+| Strategy | Behavior |
+|----------|----------|
+| `default` | Single tag = service name (fallback `SOAP`). |
+| `service` | Always service name (even if operation prefix differs). |
+| `first` | First lexical segment of CamelCase operation (e.g. `GetCityWeatherByZIP` → `Get`). |
 
-## Advanced Usage
-
-### Programmatic API
-
-You can use the generator programmatically:
+Provide `tags.json` for explicit mapping when heuristics are insufficient.
 
+---
+## 9. Working With the Generated Client
+### 9.1 SOAP Client Construction
 ```ts
-import { compileWsdlToProject } from "@techspokes/typescript-wsdl-client";
+import soap from "soap";
+import { Hotel } from "./src/integrations/soap/hotel/client.js";
 
-await compileWsdlToProject({
-  wsdl: "./spec/wsdl/MyService.wsdl",
-  outDir: "./generated",
-  options: {
-    imports: "js",
-    catalog: true,
-    primitive: {
-      int64As: "string",
-      bigIntegerAs: "string",
-      decimalAs: "string",
-      dateAs: "string",
-    },
-    choice: "all-optional",
-    failOnUnresolved: true,
-    attributesKey: "$attributes",
-    clientName: "MyServiceClient",
-    nillableAsOptional: false,
-  },
+const hotel = new Hotel({
+  source: "https://example.com/HotelService?wsdl",
+  security: new soap.WSSecurity("user", "pass")
+});
+
+const res = await hotel.GetReservation({
+  GetReservationRQ: { ReservationId: "ABC123" }
 });
 ```
+### 9.2 Attributes & Text Values
+If an element has text content and attributes, you pass both:
+```ts
+const Price = {
+  currencyCode: "USD",
+  $value: "123.45"
+};
+```
 
 ---
-
-## Troubleshooting
-
-- CLI errors  
-  • "Error: Cannot parse WSDL" → verify file path or URL; test with `curl -I <wsdl-url>`.  
-  • "Cannot resolve type XYZ" → ensure all XSD imports are reachable or use `--fail-on-unresolved=false`.  
-- Module resolution  
-  • `ERR_MODULE_NOT_FOUND` → align import extensions: use `--imports js` (adds `.js`), `--imports ts` (adds `.ts`), or `--imports bare` for no extension.  
-- TypeScript type issues  
-  • "Cannot find module './client'" → run `npm run typecheck`, confirm your `outDir` matches import paths, and include generated `.d.ts`.  
-- Runtime SOAP errors  
-  • Enable raw SOAP logging:  
-    ```bash
-    NODE_DEBUG=soap node your-app.js
-    ```  
-  • "wsdl is not valid" → update `soap` to latest (`npm i soap@latest`).  
-- Security warnings  
-  • Missing or invalid headers → pass a valid `soap.ISecurity` instance:  
-    ```ts
-    new soap.WSSecurity("user","pass",{passwordType:"PasswordText"});
-    ```  
-- XML attribute/content issues  
-  • Wrong key in requests → override with `--attributes-key inKey[:outKey]` (e.g., `--attributes-key $attributes:attributes`).
+## 10. Advanced Topics
+| Topic | Notes |
+|-------|-------|
+| Primitive mapping philosophy | Defaults prefer string to avoid precision loss. |
+| Choice flattening | Represented as optional union of fields – simpler consumption. |
+| Array wrappers | Single repeated child w/out attributes collapses to an array schema in OpenAPI. |
+| Validation | Uses `@apidevtools/swagger-parser`; disable with `--no-validate`. |
+| Future | Discriminated unions for choices, richer policy extraction, snapshot OpenAPI tests. |
 
 ---
-
-## Roadmap
-
-Please see the [ROADMAP.md](ROADMAP.md) for planned features and improvements.
+## 11. Troubleshooting
+| Symptom | Resolution |
+|---------|------------|
+| WSDL fetch fails | Curl the URL, check TLS/proxy, retry with local copy. |
+| Unresolved types | Re-run with `--fail-on-unresolved=false` to inspect partial graph. |
+| Missing schema in OpenAPI | Ensure the global element exists (catalog shows compiled symbols). |
+| Wrong array modeling | Check `maxOccurs` in WSDL; tool only arrays when `max>1` or `unbounded`. |
+| Auth errors at runtime | Provide a proper `soap.ISecurity` instance (`WSSecurity`, etc.). |
+| Date/time confusion | Use `--date-as Date` for runtime Date objects. |
+
+Enable SOAP wire logging:
+```bash
+NODE_DEBUG=soap node app.js
+```
 
 ---
-
-## Contributing
-
-We welcome contributions! Please see the following resources:
-- [CONTRIBUTING.md](CONTRIBUTING.md): Development workflow and guidelines.
-- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): Community expectations.
-- [SECURITY.md](SECURITY.md): Reporting vulnerabilities.
+## 12. Programmatic Reference (Summary)
+| Function | Purpose |
+|----------|---------|
+| `compileWsdlToProject` | WSDL → TS artifacts. |
+| `generateOpenAPI` | WSDL or catalog → OpenAPI (json / yaml / both). |
+| `runGenerationPipeline` | One pass: compile + TS emit + OpenAPI. |
 
 ---
+## 13. Contributing
+1. Fork & branch.
+2. `npm i && npm run build`.
+3. Use `npm run smoke:gen`, `npm run smoke:pipeline`, `npm run smoke:openapi:validate`.
+   - Note: These smoke tests use `examples/minimal/weather.wsdl` for quick validation.
+4. Add a bullet under **Unreleased** in `CHANGELOG.md`.
 
-## License
-
-MIT © TechSpokes.
-*The tool is MIT-licensed. Generated artifacts are owned by you; the tool imposes no license on generated files.*
+See also: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`.
 
 ---
+## 14. License
+MIT © TechSpokes — Generated artifacts are fully yours.
 
-## Sponsors
-
-**Silver Sponsors**
-- Your Name Here!
-
-**Gold Sponsors**
-- [Your Name or Company (with a link) Here!](https://your-link-here.com)
-
-**Platinum Sponsors**
-- [Your Name or Company (with a link) Here!](https://your-link-here.com)
-- **AND** 30-min one-to-one video meeting on AI, business automations, vacation rentals industry, development, tools, or a subject of your choice.
-
-Want to see your name or company here? [Become a sponsor!](https://github.com/sponsors/TechSpokes)
+---
+## 15. Sponsors
+Support ongoing maintenance: https://github.com/sponsors/TechSpokes  
+*Your brand could be featured here.*