TypeScript WSDL Client


> Transform complex WSDL/XSD definitions into type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and production-ready REST gateways.

Use This If You Need...

- ✅ TypeScript-first SOAP clients — Strongly typed, ergonomic client generation from WSDL
- ✅ OpenAPI 3.1 specs — Generate REST API documentation that mirrors your TypeScript types
- ✅ REST gateway over SOAP — Production-ready Fastify handlers with automatic request/response transformation
- ✅ CI-friendly determinism — Stable, diff-friendly output for safe regeneration in version control
- ✅ Predictable modeling — Flattened attributes, consistent $value convention, inheritance resolution

Vendor: TechSpokes · Maintainer: Serge Liatko (@sergeliatko)

---

Table of Contents

- Installation
- Quick Start (60 Seconds)
- What You Get (Outputs)
- Core Concepts
- Common Workflows
- Command Reference
- pipeline (Recommended)
- client
- openapi
- gateway
- app
- compile (Advanced)
- Configuration Files
- Working With Generated Clients
- Production Concerns
- Programmatic API
- Troubleshooting
- Contributing
- License
- Support

---

Installation

``bash
npm install --save-dev @techspokes/typescript-wsdl-client
npm install soap # Runtime dependency for SOAP calls
`

Requirements:
- Node.js 20.0.0 or later
- soap package (runtime dependency for generated clients)

---

Quick Start (60 Seconds)

Generate a complete SOAP-to-REST stack in one command:

`bash


Generate client, OpenAPI spec, gateway, and runnable app


npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir ./tmp/client \
--openapi-file ./tmp/openapi.json \
--gateway-dir ./tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
`

Start the server:

`bash
cd tmp/app
cp .env.example .env


Edit .env to set WSDL_SOURCE if needed


npx tsx server.js
`

Test it:

`bash


Health check

curl http://localhost:3000/health

Get OpenAPI spec

curl http://localhost:3000/openapi.json | jq .

Call a SOAP operation via REST

curl -X POST http://localhost:3000/get-weather-information \
-H "Content-Type: application/json" \
-d '{}'
`

What just happened?
1. Parsed the WSDL and compiled types
2. Generated a TypeScript SOAP client with full type safety
3. Created an OpenAPI 3.1 spec matching the client types
4. Built Fastify gateway handlers that call SOAP and return JSON
5. Created a runnable Express-style app with health/OpenAPI endpoints

---

What You Get (Outputs)

$3

`
client/
├── client.ts # Strongly-typed SOAP client wrapper with methods
├── types.ts # Flattened interfaces, type aliases, and enums
├── utils.ts # Runtime metadata for JSON→SOAP conversion
└── catalog.json # Compiled schema representation (reusable)
`

Example usage:

`typescript
import { Weather } from './client/client.js';

const client = new Weather({
source: 'https://example.com/weather.wsdl',
});

const result = await client.GetCityWeatherByZIP({ ZIP: '10001' });
console.log(result.GetCityWeatherByZIPResult);
`

$3

`
openapi.json # or .yaml — Complete REST API documentation
`

- Mirrors exact TypeScript type structure
- All responses wrapped in standard envelope (status, message, data, error)
- Deterministic ordering for version control
- Validates with swagger-parser by default

$3

`
gateway/
├── schemas/
│ ├── models/ # JSON Schema components with URN IDs
│ └── operations/ # Request/response validation schemas
├── routes/ # Route handlers (fully implemented)
├── schemas.ts # Schema registration module
├── routes.ts # Route aggregator
├── runtime.ts # Envelope builders, error handlers
└── plugin.ts # Fastify plugin wrapper
`

Example integration:

`typescript
import Fastify from 'fastify';
import weatherGateway from './gateway/plugin.js';
import { Weather } from './client/client.js';

const app = Fastify({ logger: true });
const client = new Weather({ source: 'weather.wsdl' });

await app.register(weatherGateway, { client });
await app.listen({ port: 3000 });
`

$3

`
app/
├── server.js # Main entry point
├── config.js # Configuration with env var support
├── .env.example # Environment template
├── README.md # Usage instructions
└── openapi.json # OpenAPI spec (when --openapi-mode=copy)
`

$3

All gateway responses follow this structure:

Success:
`json
{
"status": "SUCCESS",
"message": null,
"data": { / SOAP response / },
"error": null
}
`

Error:
`json
{
"status": "ERROR",
"message": "Request validation failed",
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": { / validation errors / }
}
}
`

---

Core Concepts

$3

Attributes and elements become peer properties — No nested wrapper noise:

`xml








`

`typescript
// Generated TypeScript
interface Price {
currency?: string; // attribute
$value: string; // text content (decimal mapped to string by default)
}
`

$3

Prevents precision loss and parsing errors at the cost of convenience:

| XSD Type | Default | Override Options | When to Override |
|---------------|----------|--------------------|----------------------------------------|
| xs:long | string | number, bigint | Use number if values fit JS range |
| xs:integer | string | number | Use string for arbitrary-size ints |
| xs:decimal | string | number | Use string for precise decimals |
| xs:dateTime | string | Date | Use Date if runtime parsing is okay |

Override with flags:
- --client-int64-as number
- --client-decimal-as string
- --client-date-as Date

$3

All output is stable and diff-friendly for CI/CD:

- ✅ Sorted type declarations
- ✅ Sorted OpenAPI paths, schemas, parameters
- ✅ Sorted JSON schema keys
- ✅ Stable alias resolution
- ✅ Consistent ordering of imports

Regenerate safely without spurious diffs in version control.

$3

catalog.json is the compiled representation of your WSDL:

- Debuggable — Inspect types, operations, and metadata as JSON
- Cacheable — Reuse across client/OpenAPI/gateway generation
- Co-located — Automatically placed alongside generated output

Common locations:
- client command: {client-dir}/catalog.json
- openapi command: {openapi-dir}/catalog.json
- pipeline command: First available output directory

---

Common Workflows

$3

| I Want... | Use Command | Example |
|-----------------------------------------------|--------------|----------------------------------------------------------------------------------------------------------------------|
| Everything (client + OpenAPI + gateway) | pipeline | npx wsdl-tsc pipeline --wsdl-source service.wsdl --client-dir ./client --openapi-file ./api.json --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1 |
| Only a TypeScript SOAP client | client | npx wsdl-tsc client --wsdl-source service.wsdl --client-dir ./client |
| Only OpenAPI spec (for docs or SDKs) | openapi | npx wsdl-tsc openapi --wsdl-source service.wsdl --openapi-file ./api.json |
| Only REST gateway (have OpenAPI already) | gateway | npx wsdl-tsc gateway --openapi-file ./api.json --client-dir ./client --gateway-dir ./gateway --gateway-service-name svc --gateway-version-prefix v1 |
| Runnable server for testing | app | npx wsdl-tsc app --client-dir ./client --gateway-dir ./gateway --openapi-file ./api.json |
| Debug/inspect WSDL compilation | compile | npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file ./catalog.json |

$3

Use pipeline for complete stack generation:

`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir ./src/services/weather \
--openapi-file ./docs/weather-api.json \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1
`

Output:
- Client: ./src/services/weather/client.ts, types.ts, utils.ts, catalog.json
- OpenAPI: ./docs/weather-api.json
- Gateway: ./src/gateway/weather/ (routes, schemas, plugin)

$3

Generate TypeScript client for direct SOAP integration:

`bash
npx wsdl-tsc client \
--wsdl-source ./wsdl/Hotel.wsdl \
--client-dir ./src/services/hotel
`

Usage:

`typescript
import soap from 'soap';
import { Hotel } from './src/services/hotel/client.js';

const client = new Hotel({
source: 'https://example.com/hotel.wsdl',
security: new soap.WSSecurity('username', 'password'),
});

const result = await client.SearchAvailableRooms({
checkIn: '2024-01-15',
checkOut: '2024-01-20',
guests: 2,
});
`

$3

Generate OpenAPI spec for API documentation or SDK generation:

`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Booking.wsdl \
--openapi-file ./docs/booking-api.yaml \
--openapi-format yaml \
--openapi-title "Hotel Booking API" \
--openapi-version "1.0.0" \
--openapi-servers https://api.example.com/v1
`

Use the spec:
- Import into Postman, Insomnia, or Swagger UI
- Generate client SDKs with OpenAPI Generator
- Share as REST API documentation

$3

Build a REST API layer over legacy SOAP services:

`bash


1. Generate client + OpenAPI

npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Legacy.wsdl \
--client-dir ./src/services/legacy \
--openapi-file ./docs/legacy-api.json

2. Generate gateway

npx wsdl-tsc gateway \
--openapi-file ./docs/legacy-api.json \
--client-dir ./src/services/legacy \
--gateway-dir ./src/gateway/legacy \
--gateway-service-name legacy \
--gateway-version-prefix v1
`

Or in one command:

`bash
npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Legacy.wsdl \
--client-dir ./src/services/legacy \
--openapi-file ./docs/legacy-api.json \
--gateway-dir ./src/gateway/legacy \
--gateway-service-name legacy \
--gateway-version-prefix v1
`

$3

Cache compiled catalog for faster multi-stage builds:

`bash


Stage 1: Compile catalog (cacheable)

npx wsdl-tsc compile \
--wsdl-source ./wsdl/Service.wsdl \
--catalog-file ./build/service-catalog.json

Stage 2: Generate client from catalog

npx wsdl-tsc client \
--catalog-file ./build/service-catalog.json \
--client-dir ./src/services/service

Stage 3: Generate OpenAPI from catalog

npx wsdl-tsc openapi \
--catalog-file ./build/service-catalog.json \
--openapi-file ./docs/service-api.json
`

$3

Inspect compiled types and operations:

`bash


Compile to catalog

npx wsdl-tsc compile \
--wsdl-source ./wsdl/Complex.wsdl \
--catalog-file ./debug/catalog.json

Inspect types

cat ./debug/catalog.json | jq '.types'

Inspect operations

cat ./debug/catalog.json | jq '.operations'
`

---

Command Reference

The tool provides six commands for different integration scenarios. Commands are listed in recommended order of use:

| Command | Purpose | Typical Use Case |
|------------|----------------------------------------------------------------|-----------------------------------------------|
| pipeline | Run full pipeline: client + OpenAPI + gateway (+ app optional) | CI/CD automation, complete stack generation (recommended) |
| client | Generate TypeScript SOAP client from WSDL or catalog | Standard SOAP integration |
| openapi | Generate OpenAPI 3.1 spec from WSDL or catalog | Documentation, REST proxies, API gateways |
| gateway | Generate Fastify gateway with full handlers from OpenAPI spec | Production REST gateway with SOAP integration |
| app | Generate runnable Fastify app from client + gateway + OpenAPI | Local testing, quick iteration, demos |
| compile | Parse WSDL and emit catalog.json only | Debugging, inspection, or multi-stage builds (advanced) |

---

$3

Purpose: Run the complete generation pipeline in a single pass: WSDL parsing → TypeScript client → OpenAPI spec → Fastify gateway (+ app optional).

When to use:
- CI/CD automation
- Complete stack generation
- Ensuring all artifacts are generated from the same WSDL parse
- One-command development workflows

#### Usage

`bash
npx wsdl-tsc pipeline \
--wsdl-source \
[--catalog-file ] \
[--client-dir ] \
[--openapi-file ] \
[--gateway-dir ] \
[options]
`

#### Required Flags

| Flag | Description |
|---------------------|----------------------------------------------------------------------|
| --wsdl-source | Path or URL to WSDL file |

#### Output Flags

| Flag | Default | Description |
|---------------------|---------------------------------------------|---------------------------------------------------|
| --catalog-file | Co-located with first output (see below) | Output path for catalog.json (always generated) |

Catalog Default Location: The catalog is automatically placed alongside the first available output:
- With --client-dir: {client-dir}/catalog.json
- With --openapi-file only: {openapi-file-dir}/catalog.json
- With --gateway-dir only: {gateway-dir}/catalog.json

Note: At least one of --client-dir, --openapi-file, or --gateway-dir must be provided.

#### Generation Control Flags

| Flag | Description |
|-------------------------|------------------------------------------------|
| --client-dir | Generate TypeScript client in this directory |
| --openapi-file | Generate OpenAPI spec at this path |
| --gateway-dir | Generate Fastify gateway in this directory |
| --generate-app | Generate runnable app (requires gateway) |

#### Optional Flags

All flags from client, openapi, and gateway commands are supported. Key flags:

Client Flags:
- --import-extensions (default: js)
- --client-attributes-key (default: $attributes)
- --client-class-name
- --client-int64-as (default: string)
- --client-bigint-as (default: string)
- --client-decimal-as (default: string)
- --client-date-as (default: string)
- --client-choice-mode (default: all-optional)
- --client-fail-on-unresolved (default: false)
- --client-nillable-as-optional (default: false)

OpenAPI Flags:
- --openapi-format (default: json)
- --openapi-title
- --openapi-version (default: 0.0.0)
- --openapi-description
- --openapi-servers (default: /)
- --openapi-base-path
- --openapi-path-style (default: kebab)
- --openapi-method (default: post)
- --openapi-tag-style (default: default)
- --openapi-closed-schemas (default: false)
- --openapi-prune-unused-schemas (default: false)
- --openapi-envelope-namespace (default: ResponseEnvelope)
- --openapi-error-namespace (default: ErrorObject)
- --openapi-validate (default: true)
- --openapi-security-config-file
- --openapi-tags-file
- --openapi-ops-file

Gateway Flags:
- --gateway-service-name (required if --gateway-dir provided)
- --gateway-version-prefix (required if --gateway-dir provided)
- --gateway-default-status-codes
- --gateway-stub-handlers (default: false)

#### Examples

Complete Stack Generation:

`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--openapi-file tmp/openapi.json \
--gateway-dir tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1
`

With App Generation:

`bash
npx wsdl-tsc pipeline \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--openapi-file tmp/openapi.json \
--gateway-dir tmp/gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
`

Client + OpenAPI Only:

`bash
npx wsdl-tsc pipeline \
--wsdl-source https://example.com/Hotel.wsdl \
--client-dir ./build/client \
--openapi-file ./docs/hotel-api.json \
--openapi-format both
`

With Full Configuration:

`bash
npx wsdl-tsc pipeline \
--wsdl-source ./wsdl/Booking.wsdl \
--client-dir ./build/client \
--openapi-file ./docs/booking-api \
--gateway-dir ./build/gateway \
--openapi-format both \
--openapi-servers https://api.example.com/v1 \
--openapi-base-path /booking \
--openapi-security-config-file ./config/security.json \
--gateway-service-name booking \
--gateway-version-prefix v1 \
--client-int64-as number \
--client-decimal-as string
`

#### Pipeline Workflow

The pipeline command executes these steps in order:

1. Parse WSDL → Load and validate WSDL document
2. Compile Catalog → Generate intermediate representation
3. Emit Catalog → Write catalog.json (always)
4. Generate Client → Emit TypeScript client files (if --client-dir)
5. Generate OpenAPI → Create OpenAPI spec (if --openapi-file)
6. Generate Gateway → Create Fastify gateway code (if --gateway-dir)
7. Generate App → Create runnable application (if --generate-app)

All steps share the same parsed WSDL and compiled catalog, ensuring consistency.

---

$3

Purpose: Generate strongly-typed TypeScript SOAP client code from WSDL or a pre-compiled catalog.

When to use:
- Standard SOAP integration (most common use case)
- When you need TypeScript types and client methods for SOAP operations
- When building applications that consume SOAP services

$3

`bash
npx wsdl-tsc client --wsdl-source --client-dir [options]


OR


npx wsdl-tsc client --catalog-file --client-dir [options]
`

$3

| Flag | Description |
|------------------|-------------------------------------------------|
| --wsdl-source | Path or URL to WSDL file (see note below) |
| --client-dir | Output directory for generated TypeScript files |

$3

| Flag | Default | Description |
|------------------|-----------------------------|----------------------------------------------------------------------|
| --catalog-file | {client-dir}/catalog.json | Path to pre-compiled catalog.json (when not using --wsdl-source) |

Note: Provide either --wsdl-source (to compile from WSDL) or --catalog-file (to use pre-compiled catalog). When using --wsdl-source, the catalog is automatically generated in the client directory unless you override with --catalog-file.

$3

| File | Purpose |
|----------------|------------------------------------------------------------------------------|
| client.ts | Strongly-typed SOAP client wrapper with one method per operation |
| types.ts | Flattened TypeScript interfaces, type aliases, and enums |
| utils.ts | Runtime metadata for JSON to SOAP conversion (attribute mapping, occurrence) |
| catalog.json | (When using --wsdl-source) Generated in client directory by default |

$3

All flags from compile command, plus:

| Flag | Default | Description |
|---------------------------------|----------------|-------------------------------------|
| --import-extensions | js | Import style: js, ts, or bare |
| --client-attributes-key | $attributes | Attribute bag key |
| --client-class-name | (derived) | Override client class name |
| --client-int64-as | string | Map 64-bit integers |
| --client-bigint-as | string | Map arbitrary-size integers |
| --client-decimal-as | string | Map xs:decimal |
| --client-date-as | string | Map date/time types |
| --client-choice-mode | all-optional | Choice element strategy |
| --client-fail-on-unresolved | false | Fail on unresolved references |
| --client-nillable-as-optional | false | Treat nillable as optional |

$3

#### Basic Generation (Default Catalog Location)

`bash
npx wsdl-tsc client \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client
`

Output: Generates client files and catalog at tmp/client/catalog.json.

#### With Custom Catalog Path

`bash
npx wsdl-tsc client \
--wsdl-source examples/minimal/weather.wsdl \
--client-dir tmp/client \
--catalog-file build/shared-catalog.json
`

#### With Custom Numeric Mappings

`bash
npx wsdl-tsc client \
--wsdl-source https://example.com/Hotel.wsdl \
--client-dir ./src/integrations/soap/hotel \
--client-int64-as number \
--client-decimal-as string \
--client-date-as string
`

Output: Catalog generated at ./src/integrations/soap/hotel/catalog.json.

#### From Pre-compiled Catalog

`bash


First compile the catalog

npx wsdl-tsc compile --wsdl-source https://example.com/Hotel.wsdl --catalog-file build/hotel-catalog.json

Then generate client from catalog

npx wsdl-tsc client \
--catalog-file build/hotel-catalog.json \
--client-dir ./src/services/hotel
`

$3

- Attributes & elements become peer properties (flattened)
- Text content becomes $value property
- Required attributes: use!="optional"; elements minOccurs>=1
- Multiplicity: maxOccurs>1 or unbounded become arrays
- Nillable: nillable="true" preserved (optionally model as optional with --client-nillable-as-optional)
- Inheritance: extensions merged or emitted as extends; simpleContent base collapsed logically

---

$3

Purpose: Generate OpenAPI 3.1 specification from WSDL or a pre-compiled catalog, mirroring the exact TypeScript type structure.

When to use:
- Creating REST API documentation for SOAP services
- Building API gateways or proxies
- Enabling REST-style access to SOAP operations
- Generating client SDKs in other languages

$3

`bash
npx wsdl-tsc openapi --wsdl-source --openapi-file [options]


OR


npx wsdl-tsc openapi --catalog-file --openapi-file [options]
`

$3

| Flag | Description |
|---------------------|----------------------------------------------------|
| --openapi-file | Output path for OpenAPI specification |

$3

| Flag | Default | Description |
|---------------------|--------------------------------------|----------------------------------------------------|
| --wsdl-source | (none) | Path or URL to WSDL file |
| --catalog-file | {openapi-file-dir}/catalog.json | Path to pre-compiled catalog.json |

Note: Provide either --wsdl-source or --catalog-file. When neither is provided, defaults to reading from the OpenAPI output directory. When using --wsdl-source, the catalog is automatically written to the OpenAPI output directory unless overridden.

$3

| Flag | Default | Description |
|-------------------------------|-----------|----------------------------------------------------------|
| --openapi-format | json | Output format: json, yaml, or both |
| --openapi-title | (derived) | API title in info section |
| --openapi-version | 0.0.0 | API version in info.version |
| --openapi-description | (empty) | API description in info section |
| --openapi-servers | / | Comma-separated server URLs |
| --openapi-base-path | (empty) | Base path prefix (e.g., /v1/soap) |
| --openapi-validate | true | Validate spec with swagger-parser |

$3

| Flag | Default | Description |
|----------------------------------|-----------|--------------------------------------------------|
| --openapi-path-style | kebab | Path transformation: kebab, asis, or lower |
| --openapi-method | post | Default HTTP method for operations |
| --openapi-tag-style | default | Tag inference: default, service, or first |
| --openapi-closed-schemas | false | Add additionalProperties: false to all schemas |
| --openapi-prune-unused-schemas | false | Emit only schemas referenced by operations |

$3

| Flag | Default | Description |
|--------------------------------|--------------------|---------------------------------------------|
| --openapi-envelope-namespace | ResponseEnvelope | Override envelope component name suffix |
| --openapi-error-namespace | ErrorObject | Override error object component name suffix |

$3

| Flag | Description |
|-----------------------------------|-------------------------------------------------------|
| --openapi-security-config-file | Path to security.json (schemes, headers, overrides) |
| --openapi-tags-file | Path to tags.json (explicit operation → tag map) |
| --openapi-ops-file | Path to ops.json (per-operation overrides) |

$3

#### Basic JSON Output

`bash
npx wsdl-tsc openapi \
--wsdl-source examples/minimal/weather.wsdl \
--openapi-file ./docs/weather-api.json
`

#### Multi-Format with Validation

`bash
npx wsdl-tsc openapi \
--wsdl-source https://example.com/Hotel.wsdl \
--openapi-file ./docs/hotel-api \
--openapi-format both \
--openapi-servers https://api.example.com/v1,https://api-staging.example.com/v1 \
--openapi-base-path /soap
`

#### From Pre-compiled Catalog

`bash
npx wsdl-tsc openapi \
--catalog-file ./artifacts/hotel-catalog.json \
--openapi-file ./docs/hotel-api.json \
--openapi-format json
`

#### With Custom Configuration

`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Booking.wsdl \
--openapi-file ./docs/booking-api.yaml \
--openapi-format yaml \
--openapi-title "Hotel Booking API" \
--openapi-version "1.2.0" \
--openapi-description "REST API for hotel booking SOAP service" \
--openapi-security-config-file ./config/security.json \
--openapi-tags-file ./config/tags.json \
--openapi-path-style kebab \
--openapi-method post \
--openapi-tag-style service
`

$3

All responses are wrapped in a standard envelope for consistency and debuggability (always-on since 0.7.1):

#### Base Envelope Structure

`typescript
{
status: string; // e.g., "SUCCESS", "FAILURE", "PENDING"
message: string | null; // diagnostic message (not for end-user UI)
data: T | null; // operation payload (typed per operation)
error: ErrorObject | null; // populated on failures
}
`

#### Error Object Structure

`typescript
{
code: string; // stable machine error code
message: string; // brief description
details: object | null; // arbitrary extra info
}
`

#### Naming Rules

- Base envelope: ${serviceName}ResponseEnvelope (override with --openapi-envelope-namespace)
- Error object: ${serviceName}ErrorObject (override with --openapi-error-namespace)
- Per-operation extension: (refines data field)

#### Collision Avoidance

If the payload type already ends with the namespace prefix, an underscore is inserted:

- Payload WeatherResponse + default ResponseEnvelope → WeatherResponse_ResponseEnvelope
- Payload Booking + default ResponseEnvelope → BookingResponseEnvelope

#### Example

`bash
npx wsdl-tsc openapi \
--wsdl-source ./wsdl/Hotel.wsdl \
--openapi-file ./docs/hotel-api.json \
--openapi-envelope-namespace ApiEnvelope \
--openapi-error-namespace ApiError
`

Produces components:
1. HotelApiEnvelope (base)
2. ApiEnvelope extension schemas (alphabetically sorted)
3. HotelApiError (error object)
4. Domain schemas

$3

| 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) |

Use --openapi-tags-file for explicit mapping when heuristics are insufficient.

$3

All generated OpenAPI specs have deterministic ordering:
- Path keys (alphabetically sorted)
- HTTP methods within paths (alphabetically sorted)
- Component schema names (alphabetically sorted)
- Security schemes (alphabetically sorted)
- Parameters (alphabetically sorted)
- Operation tag arrays (alphabetically sorted)

This ensures diff-friendly output for version control.

---

$3

Purpose: Generate a production-ready Fastify gateway with fully functional route handlers from an OpenAPI 3.1 specification. This creates a complete REST API layer over your SOAP client with automatic request/response transformation and standardized envelope responses.

When to use:
- Building a REST API gateway for legacy SOAP services
- Creating a modern HTTP/JSON interface for SOAP operations
- Setting up request/response validation with JSON Schema
- Establishing Fastify routing structure with full handler implementations

What it generates:
- Fastify route registration files with complete handler implementations
- JSON Schema models with URN-based IDs
- Operation schemas (request/response validation)
- Schema and route registration modules
- Runtime utilities (envelope builders, error handlers)
- Fastify plugin wrapper for simplified integration

$3

`bash
npx wsdl-tsc gateway \
--openapi-file \
--client-dir \
--gateway-dir \
--gateway-service-name \
--gateway-version-prefix \
[options]
`

$3

| Flag | Description |
|----------------------------|--------------------------------------------------------------------------|
| --openapi-file | Path to OpenAPI 3.1 JSON or YAML file |
| --client-dir | Path to client directory (where client.ts is located) |
| --gateway-dir | Output directory for generated gateway code |
| --gateway-service-name | Service identifier for URN generation (e.g., weather, booking) |
| --gateway-version-prefix | Version prefix for URN generation (e.g., v1, v2, urn:1.0.2:schema) |

$3

| Flag | Default | Description |
|----------------------------------|---------------------------------------------------|-------------------------------------------------------------|
| --import-extensions | js | Import style: js, ts, or bare |
| --gateway-default-status-codes | 200,400,401,403,404,409,422,429,500,502,503,504 | Comma-separated status codes to backfill |
| --catalog-file | (none) | Path to catalog.json for operation metadata |
| --gateway-client-class-name | (auto-detected) | Override SOAP client class name |
| --gateway-decorator-name | {serviceSlug}Client | Fastify decorator name for client instance |
| --gateway-stub-handlers | false | Generate stub handlers instead of full implementations |
| --gateway-skip-plugin | false | Skip generating plugin.ts wrapper |
| --gateway-skip-runtime | false | Skip generating runtime.ts utilities |

> Note: Route URLs are derived from the OpenAPI document paths, which already include any base path configured during OpenAPI generation (via --openapi-base-path). There is no separate route prefix option for the gateway.

$3

`
{gateway-dir}/
├── schemas/
│ ├── models/ # JSON Schema components with URN IDs
│ │ ├── .json
│ │ ├── .json
│ │ └── ...
│ └── operations/ # Fastify operation schemas
│ ├── .json
│ ├── .json
│ └── ...
├── routes/ # Route registration files with full handlers
│ ├── .ts
│ ├── .ts
│ └── ...
├── schemas.ts # Schema registration module
├── routes.ts # Route aggregator module
├── runtime.ts # Envelope builders and error handler
└── plugin.ts # Fastify plugin wrapper (recommended entry point)
`

$3

All generated JSON Schemas use deterministic URN identifiers:

`
urn:services:{serviceSlug}:{versionSlug}:schemas:{models|operations}:{schemaSlug}
`

Example: urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse

$3

The gateway generator enforces strict OpenAPI contract validation:

- All request/response bodies must use $ref to components.schemas (no inline schemas)
- Every operation must have a default response with application/json content
- All schemas referenced by operations must exist in components.schemas

$3

#### Basic Gateway Generation

`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/weather-api.json \
--client-dir ./src/services/weather \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1
`

#### With Custom Status Codes

`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/hotel-api.json \
--client-dir ./src/services/hotel \
--gateway-dir ./src/gateway/hotel \
--gateway-service-name hotel \
--gateway-version-prefix v2 \
--gateway-default-status-codes 200,400,401,404,500
`

#### From YAML OpenAPI

`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/booking-api.yaml \
--client-dir ./src/services/booking \
--gateway-dir ./src/gateway/booking \
--gateway-service-name booking \
--gateway-version-prefix v1
`

$3

The generated gateway provides a Fastify plugin for simplified integration.

#### Prerequisites

Your host application needs these dependencies:

`bash
npm install fastify fastify-plugin
`

#### Using the Generated Plugin (Recommended)

`typescript
import Fastify from 'fastify';
import weatherGateway from './gateway/plugin.js';
import { Weather } from './client/client.js';

const app = Fastify({ logger: true });

// Create and configure SOAP client
const weatherClient = new Weather({
source: 'https://example.com/weather.wsdl',
// security: new soap.WSSecurity('user', 'pass'), // if needed
});

// Register gateway plugin with client
await app.register(weatherGateway, {
client: weatherClient,
// Note: Route paths are determined by --openapi-base-path during generation.
// The prefix option here adds an ADDITIONAL runtime prefix on top of generated paths.
// Only use if you need to mount routes under a different sub-path at runtime.
});

await app.listen({ port: 3000 });
`

The plugin automatically:
- Decorates Fastify with the SOAP client (fastify.weatherClient)
- Registers all JSON schemas for validation
- Installs a centralized error handler
- Registers all routes with full handler implementations

#### Using Individual Components (Advanced)

For more control, you can use the individual modules:

`typescript
import Fastify from 'fastify';
import { registerSchemas_v1_weather } from './gateway/schemas.js';
import { registerRoutes_v1_weather } from './gateway/routes.js';
import { createGatewayErrorHandler_v1_weather } from './gateway/runtime.js';
import { Weather } from './client/client.js';

const app = Fastify({ logger: true });

// Manual setup
const weatherClient = new Weather({ source: 'weather.wsdl' });
app.decorate('weatherClient', weatherClient);

// Register schemas
await registerSchemas_v1_weather(app);

// Install error handler
app.setErrorHandler(createGatewayErrorHandler_v1_weather());

// Register routes (paths already include --openapi-base-path if configured)
await registerRoutes_v1_weather(app);

await app.listen({ port: 3000 });
`

$3

Route handlers are fully implemented and call the SOAP client automatically:

`typescript
// Generated: routes/get-city-forecast-by-zip.ts
import type { FastifyInstance } from "fastify";
import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
import { buildSuccessEnvelope } from "../runtime.js";

export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
fastify.route({
method: "POST",
url: "/get-city-forecast-by-zip",
schema,
handler: async (request) => {
const client = fastify.weatherClient;
const result = await client.GetCityForecastByZIP(request.body);
return buildSuccessEnvelope(result.response);
},
});
}
`

$3

All responses are wrapped in a standard envelope format:

Success Response:
`
{
"status": "SUCCESS",
"message": null,
"data": { / SOAP response data / },
"error": null
}
`

Error Response:
`
{
"status": "ERROR",
"message": "Request validation failed",
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": { / validation errors / }
}
}
`

$3

The centralized error handler (runtime.ts) automatically classifies errors:

| Error Type | HTTP Status | Error Code |
|-----------------------|-------------|-----------------------|
| Validation errors | 400 | VALIDATION_ERROR |
| SOAP faults | 502 | SOAP_FAULT |
| Connection refused | 503 | SERVICE_UNAVAILABLE |
| Timeout | 504 | GATEWAY_TIMEOUT |
| Other errors | 500 | INTERNAL_ERROR |

$3

If you prefer to implement handler logic manually or need custom transformation logic beyond the standard SOAP-to-REST mapping, use stub mode:

`bash
npx wsdl-tsc gateway \
--openapi-file ./docs/weather-api.json \
--client-dir ./src/services/weather \
--gateway-dir ./src/gateway/weather \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--gateway-stub-handlers
`

This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.

---

$3

Purpose: Generate a runnable Fastify application that integrates the generated client, gateway, and OpenAPI spec. This provides an immediately executable server for testing, development, and demonstrations.

When to use:
- Local testing and development
- Quick iteration on gateway configurations
- Demonstrating the generated API
- CI smoke testing

$3

`bash
npx wsdl-tsc app \
--client-dir \
--gateway-dir \
--openapi-file \
[--catalog-file ] \
[--app-dir ] \
[options]
`

$3

| Flag | Description |
|------------------|----------------------------------------------------------|
| --client-dir | Path to client directory (where client.ts is located) |
| --gateway-dir | Path to gateway directory (where plugin.ts is located) |
| --openapi-file | Path to OpenAPI specification file |

$3

| Flag | Default | Description |
|-----------------------|-------------------------------|---------------------------------------------------|
| --catalog-file | {client-dir}/catalog.json | Path to catalog.json (for metadata extraction) |
| --app-dir | {gateway-dir}/../app | Output directory for generated app |
| --import-extensions | Inferred from catalog or js | Import-extension mode: js, ts, or bare |
| --host | 127.0.0.1 | Default server host |
| --port | 3000 | Default server port |
| --prefix | "" (empty) | Route prefix |
| --logger | true | Enable Fastify logger |
| --openapi-mode | copy | How to handle OpenAPI file: copy or reference |

$3

#### Generate App After Pipeline

`bash


First generate client, OpenAPI, and gateway

npx wsdl-tsc pipeline \
--wsdl-source weather.wsdl \
--client-dir ./client \
--openapi-file ./openapi.json \
--gateway-dir ./gateway \
--gateway-service-name weather \
--gateway-version-prefix v1

Then generate runnable app

npx wsdl-tsc app \
--client-dir ./client \
--gateway-dir ./gateway \
--openapi-file ./openapi.json \
--app-dir ./app
`

#### Generate App with Custom Configuration

`bash
npx wsdl-tsc app \
--client-dir ./client \
--gateway-dir ./gateway \
--openapi-file ./openapi.json \
--app-dir ./my-app \
--host 0.0.0.0 \
--port 8080 \
--prefix /api/v1
`

$3

The app command generates the following files:

`
app/
├── server.js (or .ts) # Main application entry point
├── config.js (or .ts) # Configuration loader with env support
├── .env.example # Environment variable template
├── README.md # Usage instructions
└── openapi.json # OpenAPI spec (when --openapi-mode=copy)
`

$3

`bash


Copy environment template

cd app
cp .env.example .env

Edit .env to configure WSDL source and other settings

vim .env

Run the server

npx tsx server.js # For TypeScript files

or

node server.js # For JavaScript files
`

$3

The generated app loads configuration from environment variables with the following precedence:

1. Environment variables (runtime overrides)
2. Catalog defaults (from generation-time)
3. Hard defaults (in config file)

#### Environment Variables

| Variable | Default (from catalog or flags) | Description |
|-----------------|---------------------------------|--------------------------------------|
| WSDL_SOURCE | From catalog or required | WSDL URL or local file path |
| HOST | 127.0.0.1 | Server bind address |
| PORT | 3000 | Server listen port |
| PREFIX | "" (empty) | Route prefix |
| LOGGER | true | Enable Fastify logger |

$3

The generated app serves the following endpoints:

#### Health Check
`bash
GET /health
`
Returns: { "ok": true }

#### OpenAPI Specification
`bash
GET /openapi.json
`
Returns: Complete OpenAPI 3.1 specification

#### Gateway Routes
All SOAP operations are exposed as REST endpoints. See the OpenAPI spec for complete API documentation.

$3

`bash


Start the server

cd app
npx tsx server.js

Test health endpoint

curl http://localhost:3000/health

Get OpenAPI spec

curl http://localhost:3000/openapi.json | jq .

Call a gateway operation (example)

curl -X POST http://localhost:3000/get-weather-information \
-H "Content-Type: application/json" \
-d '{}'
`

$3

The app command can also be used via the pipeline with the --generate-app flag:

`bash
npx wsdl-tsc pipeline \
--wsdl-source weather.wsdl \
--client-dir ./client \
--openapi-file ./openapi.json \
--gateway-dir ./gateway \
--gateway-service-name weather \
--gateway-version-prefix v1 \
--generate-app
`

This generates all artifacts including the runnable app in a single command.

---

$3

Purpose: Parse WSDL and generate only the intermediate catalog.json representation without TypeScript client code.

When to use:
- Multi-stage builds where you want to cache the parsed WSDL
- Debugging or inspecting the compiled schema structure
- Sharing a compiled catalog across multiple generation targets

#### Usage

`bash
npx wsdl-tsc compile --wsdl-source --catalog-file [options]
`

#### Required Flags

| Flag | Description |
|---------------------|------------------------------------------|
| --wsdl-source | Path or URL to the WSDL file |
| --catalog-file | Output path for catalog.json |

#### Optional Flags

| Flag | Default | Description |
|------------------------------------|----------------|--------------------------------------------------------------|
| --import-extensions | js | Import specifier style: js, ts, or bare |
| --client-attributes-key | $attributes | Attribute bag key for runtime mapper |
| --client-class-name | (derived) | Override generated client class name |
| --client-int64-as | string | Map 64-bit integers: string, number, or bigint |
| --client-bigint-as | string | Map arbitrary-size integers: string or number |
| --client-decimal-as | string | Map xs:decimal: string or number |
| --client-date-as | string | Map date/time types: string or Date |
| --client-choice-mode | all-optional | Choice element strategy: all-optional or union |
| --client-fail-on-unresolved | false | Fail build on unresolved type references |
| --client-nillable-as-optional | false | Treat nillable elements as optional properties |

#### Examples

Basic Compilation:

`bash
npx wsdl-tsc compile \
--wsdl-source examples/minimal/weather.wsdl \
--catalog-file tmp/catalog.json
`

With Custom Mapping Options:

`bash
npx wsdl-tsc compile \
--wsdl-source https://example.com/Hotel.wsdl \
--catalog-file ./build/hotel-catalog.json \
--client-int64-as number \
--client-decimal-as string
`

For Debugging:

`bash


Compile to inspect types and operations

npx wsdl-tsc compile \
--wsdl-source ./wsdl/ComplexService.wsdl \
--catalog-file ./debug/catalog.json \
--client-fail-on-unresolved false

Inspect types

cat ./debug/catalog.json | jq '.types'

Inspect operations

cat ./debug/catalog.json | jq '.operations'
`

#### Output

- catalog.json - Compiled schema representation including types, operations, and metadata

#### Catalog Structure

The catalog.json file contains the compiled WSDL representation:

`json
{
"wsdlUri": "path/to/service.wsdl",
"targetNamespace": "http://example.com/service",
"serviceName": "WeatherService",
"types": [
{
"name": "GetWeatherRequest",
"properties": []
}
],
"operations": [
{
"name": "GetWeather",
"input": "GetWeatherRequest",
"output": "GetWeatherResponse"
}
],
"options": {
"imports": "js",
"catalog": true
}
}
`

Key sections:
- types - All compiled type definitions with properties and inheritance
- operations - SOAP operations with input/output type references
- options - Compiler options used during generation

This catalog can be reused with the client and openapi commands via --catalog-file.

#### Catalog Co-location

Default behavior: Catalog files are co-located with their primary output files for better organization and discoverability.

Catalog Location by Command:
- compile: Always requires explicit --catalog-file (no default)
- client: Defaults to {client-dir}/catalog.json
- openapi: Defaults to {openapi-file-dir}/catalog.json
- pipeline: Intelligent cascade - first available: {client-dir} > {openapi-dir} > {gateway-dir} > tmp/

Common patterns:

1. Co-located with client (recommended for most projects):
`bash
npx wsdl-tsc client --wsdl-source service.wsdl --client-dir src/services/weather
`

Creates src/services/weather/catalog.json automatically.

2. Shared catalog for multiple commands (custom location):
`bash
npx wsdl-tsc compile --wsdl-source service.wsdl --catalog-file build/shared-catalog.json
npx wsdl-tsc client --catalog-file build/shared-catalog.json --client-dir src/client
npx wsdl-tsc openapi --catalog-file build/shared-catalog.json --openapi-file docs/api.json
`

---

Working With Generated Clients

$3

`typescript
import soap from "soap";
import { Weather } from "./src/services/weather/client.js";

const client = new Weather({
source: "https://example.com/WeatherService?wsdl",
security: new soap.WSSecurity("username", "password")
});
`

$3

`typescript
// Operation with input
const forecast = await client.GetCityForecastByZIP({
ZIP: "10001"
});

console.log(forecast.GetCityForecastByZIPResult.Success);
console.log(forecast.GetCityForecastByZIPResult.ForecastResult);

// Operation without input
const info = await client.GetWeatherInformation({});
console.log(info.GetWeatherInformationResult.WeatherDescriptions);
`

$3

When an element has both attributes and text content, use the $value convention:

`typescript
const price = {
currencyCode: "USD", // attribute
$value: "123.45" // text content
};
`

$3

Repeated elements are automatically typed as arrays:

`typescript
interface ForecastReturn {
Forecast: Forecast[]; // maxOccurs > 1
}
`

$3

All operations and types are fully typed:

`typescript
// TypeScript knows the exact shape
const result: GetCityWeatherByZIPResponse = await client.GetCityWeatherByZIP({
ZIP: "10001"
});

// Autocomplete and type checking work
result.GetCityWeatherByZIPResult.Temperature; // number | string (depends on mapping)
`

---

Configuration Files

$3

Define security schemes, headers, and per-operation overrides:

`json
{
"global": {
"scheme": "bearer",
"bearer": { "bearerFormat": "JWT" },
"headers": [
{
"name": "X-Correlation-Id",
"required": false,
"schema": { "type": "string" }
}
]
},
"overrides": {
"CancelBooking": { "scheme": "apiKey" }
}
}
`

Supported schemes: none, basic, bearer, apiKey, oauth2

$3

Explicit operation → tag mapping:

`json
{
"GetCityWeatherByZIP": ["Weather", "Forecast"],
"GetWeatherInformation": ["Weather", "Info"],
"CancelBooking": ["Booking", "Cancellation"]
}
`

$3

Per-operation overrides for method, summary, description, and deprecation:

`json
{
"GetCityWeatherByZIP": {
"method": "get",
"summary": "Get weather forecast by ZIP code",
"description": "Returns a detailed weather forecast for the specified US ZIP code",
"deprecated": false
},
"LegacyOperation": {
"deprecated": true
}
}
`

---

Production Concerns

$3

All generated code and specifications have stable, deterministic ordering for version control:

- ✅ TypeScript files: Sorted type declarations, imports, and exports
- ✅ OpenAPI specs: Sorted paths, HTTP methods, schemas, parameters, security schemes, tags
- ✅ JSON Schemas: Sorted property keys and component names
- ✅ Gateway routes: Alphabetically organized route files
- ✅ Catalog JSON: Consistent ordering of types and operations

Benefit: Safe regeneration in CI/CD without spurious diffs.

$3

OpenAPI Validation (enabled by default):
- Uses @apidevtools/swagger-parser
- Validates schema structure
- Resolves all $ref references
- Catches missing schemas and circular dependencies
- Disable with --openapi-validate false

Gateway Contract Validation:
- All request/response bodies must use $ref to components.schemas
- Every operation must have a default response with application/json content
- All referenced schemas must exist in components.schemas

$3

Gateway Error Classification:

| Error Type | HTTP Status | Error Code | When It Occurs |
|-----------------------|-------------|-----------------------|---------------------------------------|
| Validation errors | 400 | VALIDATION_ERROR | Request doesn't match JSON Schema |
| SOAP faults | 502 | SOAP_FAULT | SOAP service returned a fault |
| Connection refused | 503 | SERVICE_UNAVAILABLE | Cannot reach SOAP endpoint |
| Timeout | 504 | GATEWAY_TIMEOUT | SOAP request exceeded timeout |
| Other errors | 500 | INTERNAL_ERROR | Unexpected errors |

All errors are wrapped in the standard envelope format with error object populated.

$3

Enable SOAP request/response debugging:

`bash
NODE_DEBUG=soap node app.js
`

This logs full XML request/response payloads to console.

$3

Caching Strategy:

`bash


Step 1: Compile catalog (cacheable artifact)

npx wsdl-tsc compile \
--wsdl-source ./wsdl/Service.wsdl \
--catalog-file ./build/catalog.json

Step 2: Generate code from cached catalog

npx wsdl-tsc client --catalog-file ./build/catalog.json --client-dir ./src/client
npx wsdl-tsc openapi --catalog-file ./build/catalog.json --openapi-file ./docs/api.json
`

Recommended Build Script (package.json):

`json
{
"scripts": {
"generate": "npx wsdl-tsc pipeline --wsdl-source ./wsdl/service.wsdl --client-dir ./src/client --openapi-file ./docs/api.json --gateway-dir ./src/gateway --gateway-service-name svc --gateway-version-prefix v1",
"build": "npm run generate && tsc",
"typecheck": "tsc --noEmit"
}
}
`

$3

Choice Elements:
- Current strategy: all-optional (all branches optional)
- Future: Discriminated union support (planned)

Union Types:
- Experimental --client-choice-mode union available
- May require manual refinement for complex patterns

WS-Policy:
- Security hints extracted from policies
- Custom policies may require manual security configuration

Array Wrapper Flattening:
- Single-child sequences with maxOccurs>1 become array schemas
- Sequences with multiple children preserve wrapper

---

Programmatic API

All CLI commands are available as TypeScript functions for programmatic usage.

$3

Generate TypeScript SOAP client from WSDL.

`typescript
import { compileWsdlToProject } from "@techspokes/typescript-wsdl-client";

await compileWsdlToProject({
wsdl: "./wsdl/Hotel.wsdl",
outDir: "./src/services/hotel",
options: {
imports: "js",
catalog: true,
primitive: {
int64As: "number",
bigIntegerAs: "string",
decimalAs: "string",
dateAs: "string"
},
choice: "all-optional",
clientName: "HotelClient",
nillableAsOptional: false
}
});
`

Type Signature:

`typescript
// noinspection JSAnnotator
function compileWsdlToProject(input: {
wsdl: string;
outDir: string;
options?: Partial;
}): Promise;
`

Options (CompilerOptions):

`typescript
interface CompilerOptions {
wsdl: string;
out: string;
imports: "js" | "ts" | "bare";
catalog: boolean;
primitive: PrimitiveOptions;
choice?: "all-optional" | "union";
failOnUnresolved?: boolean;
attributesKey?: string;
clientName?: string;
nillableAsOptional?: boolean;
}

interface PrimitiveOptions {
int64As?: "string" | "number" | "bigint";
bigIntegerAs?: "string" | "number";
decimalAs?: "string" | "number";
dateAs?: "string" | "Date";
}
`

$3

Generate OpenAPI 3.1 specification from WSDL or catalog.

`typescript
import { generateOpenAPI } from "@techspokes/typescript-wsdl-client";

const { doc, jsonPath, yamlPath } = await generateOpenAPI({
wsdl: "./wsdl/Hotel.wsdl",
outFile: "./docs/hotel-api",
format: "both",
title: "Hotel Booking API",
version: "1.0.0",
servers: ["https://api.example.com/v1"],
basePath: "/booking",
pathStyle: "kebab",
tagStyle: "service",
validate: true
});
`

Type Signature:

`typescript
// noinspection JSAnnotator
function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
doc: any;
jsonPath?: string;
yamlPath?: string;
}>;
`

Options (GenerateOpenAPIOptions):

`typescript
interface GenerateOpenAPIOptions {
// Input sources (mutually exclusive)
wsdl?: string;
catalogFile?: string;
compiledCatalog?: CompiledCatalog;

// Output
outFile?: string;
format?: "json" | "yaml" | "both";

// Metadata
title?: string;
version?: string;
description?: string;
servers?: string[];

// Path configuration
basePath?: string;
pathStyle?: "kebab" | "asis" | "lower";
defaultMethod?: string;

// Schema configuration
closedSchemas?: boolean;
pruneUnusedSchemas?: boolean;

// Tag configuration
tagStyle?: "default" | "first" | "service";
tagsFile?: string;

// Security & operations
securityConfigFile?: string;
opsFile?: string;

// Envelope customization
envelopeNamespace?: string;
errorNamespace?: string;

// Validation
validate?: boolean;
skipValidate?: boolean;

// Deprecated
asYaml?: boolean;
}
`

$3

Generate Fastify gateway code from OpenAPI specification.

`typescript
import { generateGateway } from "@techspokes/typescript-wsdl-client";

await generateGateway({
openapiFile: "./docs/hotel-api.json",
outDir: "./src/gateway/hotel",
clientDir: "./src/services/hotel",
versionSlug: "v1",
serviceSlug: "hotel",
defaultResponseStatusCodes: [200, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504],
imports: "js"
});
`

Type Signature:

`typescript
// noinspection JSAnnotator
function generateGateway(opts: GenerateGatewayOptions): Promise;
`

Options (GenerateGatewayOptions):

`typescript
interface GenerateGatewayOptions {
// Input sources (mutually exclusive)
openapiFile?: string;
openapiDocument?: any;

// Output
outDir: string;

// Client integration
clientDir?: string;

// URN configuration
versionSlug?: string;
serviceSlug?: string;

// Schema configuration
defaultResponseStatusCodes?: number[];

// Import style
imports?: "js" | "ts" | "bare";
}
`

$3

Run complete pipeline: client + OpenAPI + gateway in one pass.

`typescript
import { runGenerationPipeline } from "@techspokes/typescript-wsdl-client";

const { compiled, openapiDoc } = await runGenerationPipeline({
wsdl: "./wsdl/Hotel.wsdl",
catalogOut: "./build/hotel-catalog.json",
clientOutDir: "./src/services/hotel",
compiler: {
imports: "js",
primitive: {
int64As: "number",
decimalAs: "string"
}
},
openapi: {
outFile: "./docs/hotel-api.json",
format: "both",
servers: ["https://api.example.com/v1"],
tagStyle: "service"
},
gateway: {
outDir: "./src/gateway/hotel",
versionSlug: "v1",
serviceSlug: "hotel"
}
});
`

Type Signature:

`typescript
// noinspection JSAnnotator
function runGenerationPipeline(opts: PipelineOptions): Promise<{
compiled: CompiledCatalog;
openapiDoc?: any;
}>;
`

Options (PipelineOptions):

``typescript
interface PipelineOptions {
// Input
wsdl: string;

// Catalog (always generated)
catalogOut: string;

// Client generation (optional)
clientOutDir?: string;
compiler?: Partial;

// OpenAPI generation (optional)
openapi?: Omit &