@techspokes/typescript-wsdl-client 0.10.0 → 0.10.2

package/docs/concepts.md

@@ -0,0 +1,212 @@
+# Core Concepts and Advanced Topics
+
+This document covers the design principles and modeling strategies used by
+TypeScript WSDL Client. For installation, quick-start, and CLI usage see the
+[README](../README.md).
+
+## Flattening and $value
+
+Attributes and elements become peer properties with no nested wrapper noise.
+
+Given a WSDL complex type with simple content:
+
+```xml
+<xs:complexType name="Price">
+  <xs:simpleContent>
+    <xs:extension base="xs:decimal">
+      <xs:attribute name="currency" type="xs:string"/>
+    </xs:extension>
+  </xs:simpleContent>
+</xs:complexType>
+```
+
+The generator produces a flat interface:
+
+```typescript
+interface Price {
+  currency?: string;  // attribute
+  $value: string;     // text content (decimal mapped to string by default)
+}
+```
+
+## Primitive Mapping
+
+All XSD numeric and date-time types map to `string` by default. This prevents
+precision loss 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 CLI flags:
+
+- `--client-int64-as`
+- `--client-decimal-as`
+- `--client-date-as`
+
+## Deterministic Generation
+
+All output is stable and diff-friendly for CI/CD pipelines.
+
+- Sorted type declarations
+- Sorted OpenAPI paths, schemas, and parameters
+- Sorted JSON schema keys
+- Stable alias resolution
+- Consistent import ordering
+
+Regenerate safely without spurious diffs in version control.
+
+## Catalog as Intermediate Artifact
+
+`catalog.json` is the compiled representation of your WSDL. It is debuggable,
+cacheable, and reused across client, OpenAPI, and gateway generation.
+
+Inspect types, operations, and metadata as plain JSON. The catalog is
+automatically placed alongside generated output.
+
+### Catalog Locations by Command
+
+| Command | Location |
+|---------|----------|
+| client | `{client-dir}/catalog.json` |
+| openapi | `{openapi-dir}/catalog.json` |
+| pipeline | First available output directory |
+
+## Response Envelope
+
+All gateway responses follow a uniform envelope structure. This has been
+always-on since v0.7.1.
+
+### Success Response
+
+```json
+{
+  "status": "SUCCESS",
+  "message": null,
+  "data": { },
+  "error": null
+}
+```
+
+### Error Response
+
+```json
+{
+  "status": "ERROR",
+  "message": "Request validation failed",
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": { }
+  }
+}
+```
+
+### Envelope Shape
+
+The base envelope is generic over the payload type `T`:
+
+```typescript
+{
+  status: string;
+  message: string | null;
+  data: T | null;
+  error: ErrorObject | null;
+}
+```
+
+The error object carries a machine-readable code, a human message, and optional
+details:
+
+```typescript
+{
+  code: string;
+  message: string;
+  details: object | null;
+}
+```
+
+### Envelope Naming
+
+The base envelope is named `${serviceName}ResponseEnvelope`. Override with
+`--openapi-envelope-namespace`.
+
+The error type is named `${serviceName}ErrorObject`. Override with
+`--openapi-error-namespace`.
+
+Per-operation envelopes use the pattern
+`<PayloadType|OperationName><EnvelopeNamespace>`.
+
+### Collision Avoidance
+
+When the payload type already ends with the namespace prefix, an underscore is
+inserted. For example, `WeatherResponse` combined with `ResponseEnvelope`
+produces `WeatherResponse_ResponseEnvelope`.
+
+## Choice Element Handling
+
+The current strategy is all-optional. All choice branches are emitted as
+optional properties on a single interface.
+
+```typescript
+// WSDL: <xs:choice>
+interface MyType {
+  optionA?: string;
+  optionB?: number;
+}
+```
+
+## Array Wrapper Flattening
+
+A complex type whose only child is a single repeated element with no attributes
+collapses to an array schema in OpenAPI.
+
+```xml
+<xs:complexType name="ArrayOfForecast">
+  <xs:sequence>
+    <xs:element name="Forecast" type="tns:Forecast" maxOccurs="unbounded"/>
+  </xs:sequence>
+</xs:complexType>
+```
+
+The resulting OpenAPI schema:
+
+```json
+{
+  "ArrayOfForecast": {
+    "type": "array",
+    "items": { "$ref": "#/components/schemas/Forecast" }
+  }
+}
+```
+
+## Inheritance Flattening
+
+Three XSD inheritance patterns are supported.
+
+### Extension
+
+Base properties are merged into the derived type. TypeScript uses `extends`
+when possible.
+
+### Restriction
+
+Treated as the base type with additional constraints applied.
+
+### SimpleContent
+
+The base value collapses into a `$value` property. Attributes remain as peer
+properties on the same interface.
+
+## Validation
+
+OpenAPI output is validated with `@apidevtools/swagger-parser`. The validator
+checks schema structure, resolves all `$ref` references, catches missing
+schemas, and detects circular dependencies.
+
+Disable with `--openapi-validate false` or `validate: false` in the
+programmatic API.

package/docs/configuration.md

@@ -0,0 +1,74 @@
+# Configuration Files
+
+Optional JSON configuration files for customizing OpenAPI generation. Pass these via CLI flags to the `openapi` or `pipeline` commands.
+
+See [CLI Reference](cli-reference.md) for flag details and [README](../README.md) for quick start.
+
+## Security Configuration
+
+Pass via `--openapi-security-config-file`.
+
+Defines 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.
+
+## Tags Configuration
+
+Pass via `--openapi-tags-file`.
+
+Explicit operation-to-tag mapping when heuristic tag inference is insufficient.
+
+```json
+{
+  "GetCityWeatherByZIP": ["Weather", "Forecast"],
+  "GetWeatherInformation": ["Weather", "Info"],
+  "CancelBooking": ["Booking", "Cancellation"]
+}
+```
+
+## Operations Configuration
+
+Pass via `--openapi-ops-file`.
+
+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
+  }
+}
+```
+
+## Example Files
+
+Example configuration files are available in the `examples/openapi/` directory:
+
+- `examples/openapi/security.json` for security scheme configuration
+- `examples/openapi/tags.json` for tag mapping
+- `examples/openapi/ops.json` for operation overrides

package/docs/gateway-guide.md

@@ -0,0 +1,124 @@
+# Gateway Guide
+
+Guide to integrating the generated Fastify REST gateway with your application.
+
+See [README](../README.md) for quick start and [CLI Reference](cli-reference.md) for gateway command flags.
+
+## 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 });
+
+const weatherClient = new Weather({
+  source: 'https://example.com/weather.wsdl',
+});
+
+await app.register(weatherGateway, {
+  client: weatherClient,
+});
+
+await app.listen({ port: 3000 });
+```
+
+The plugin automatically decorates Fastify with the SOAP client, registers JSON schemas, installs a centralized error handler, and registers all routes.
+
+Route paths are determined by --openapi-base-path during generation. The prefix option adds an additional runtime prefix on top of generated paths.
+
+## Using Individual Components (Advanced)
+
+```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 });
+
+const weatherClient = new Weather({ source: 'weather.wsdl' });
+app.decorate('weatherClient', weatherClient);
+
+await registerSchemas_v1_weather(app);
+app.setErrorHandler(createGatewayErrorHandler_v1_weather());
+await registerRoutes_v1_weather(app);
+
+await app.listen({ port: 3000 });
+```
+
+## Generated Handler Implementation
+
+Route handlers call the SOAP client automatically:
+
+```typescript
+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);
+    },
+  });
+}
+```
+
+## Error Handling
+
+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 |
+
+All errors are wrapped in the standard envelope format. See [Concepts](concepts.md) for the envelope structure.
+
+## Stub Handler Mode
+
+For 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.
+
+## URN-Based Schema IDs
+
+All generated JSON Schemas use deterministic URN identifiers:
+`urn:services:{serviceSlug}:{versionSlug}:schemas:{models|operations}:{schemaSlug}`
+
+Example: `urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse`
+
+## Contract Assumptions
+
+- 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

package/docs/generated-code.md

@@ -0,0 +1,74 @@
+# Working With Generated Code
+
+Guide to using the TypeScript SOAP clients and types generated by wsdl-tsc.
+
+See [README](../README.md) for quick start and [Concepts](concepts.md) for type modeling details.
+
+## Client Construction
+
+```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")
+});
+```
+
+The `source` parameter accepts a URL or local file path to the WSDL.
+
+## Calling Operations
+
+```typescript
+const forecast = await client.GetCityForecastByZIP({
+  ZIP: "10001"
+});
+
+console.log(forecast.GetCityForecastByZIPResult.Success);
+console.log(forecast.GetCityForecastByZIPResult.ForecastResult);
+```
+
+Operations without input still require an empty object:
+
+```typescript
+const info = await client.GetWeatherInformation({});
+console.log(info.GetWeatherInformationResult.WeatherDescriptions);
+```
+
+## Attributes and Text Content
+
+When an element has both attributes and text content, use the $value convention:
+
+```typescript
+const price = {
+  currencyCode: "USD",
+  $value: "123.45"
+};
+```
+
+See [Concepts](concepts.md) for details on the flattening model and $value convention.
+
+## Working With Arrays
+
+Repeated elements are automatically typed as arrays:
+
+```typescript
+interface ForecastReturn {
+  Forecast: Forecast[];  // maxOccurs > 1
+}
+```
+
+## Type Safety
+
+All operations and types are fully typed:
+
+```typescript
+const result: GetCityWeatherByZIPResponse = await client.GetCityWeatherByZIP({
+  ZIP: "10001"
+});
+
+result.GetCityWeatherByZIPResult.Temperature;
+```
+
+Autocomplete and type checking work across all generated interfaces.

package/docs/migration.md

@@ -0,0 +1,107 @@
+# Migration Guide
+
+This guide covers upgrade steps between major versions of `@techspokes/typescript-wsdl-client`.
+
+Versions are listed newest first. Find your current version and follow the steps for each version you need to cross.
+
+## General Upgrade Steps
+
+These steps apply to every version upgrade:
+
+1. Update the package: `npm install --save-dev @techspokes/typescript-wsdl-client@latest`
+2. Read the migration section for your version jump below
+3. Regenerate all output by running your generation script or pipeline command
+4. Run `tsc --noEmit` to verify the generated code compiles
+5. Test your application
+
+## Version Compatibility
+
+| wsdl-tsc | Node.js | TypeScript | soap | Fastify |
+|----------|---------|------------|------|---------|
+| 0.10.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
+| 0.9.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
+| 0.8.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
+| 0.7.x | >= 20.0 | >= 5.6 | >= 1.3 | N/A |
+
+## Upgrading to 0.10.x from 0.9.x
+
+This upgrade changes generated gateway code only. No CLI flags changed.
+
+### What Changed in 0.10.x
+
+The gateway plugin now uses the concrete client class type instead of a generic index signature. Route handlers are fully typed with `Body: T` generics. A new `_typecheck.ts` fixture is generated to catch plugin-client type divergence at build time.
+
+### Steps to Upgrade to 0.10.x
+
+1. Regenerate all gateway code: `npx wsdl-tsc pipeline ...`
+2. Remove any `@ts-expect-error` comments you added for client type mismatches
+3. Add `_typecheck.ts` to your TypeScript includes if you use a custom tsconfig
+
+### Is 0.10.x Breaking?
+
+No. These are generated code improvements only. Regenerating your output is sufficient.
+
+## Upgrading to 0.9.x from 0.8.x
+
+This upgrade changes how the gateway command generates route handlers.
+
+### What Changed in 0.9.x
+
+The gateway command now generates full handler implementations that call the SOAP client and return envelope responses. Previous versions generated stub handlers. New files `runtime.ts` and `plugin.ts` are generated. A new `app` command creates runnable Fastify applications.
+
+### Steps to Upgrade to 0.9.x
+
+1. Regenerate gateway code: `npx wsdl-tsc pipeline ...`
+2. If you wrote custom handlers over the old stubs, use `--gateway-stub-handlers` to keep stub behavior
+3. Alternatively, migrate custom logic into the gateway plugin lifecycle hooks
+4. The new `plugin.ts` is the recommended entry point and replaces manual Fastify wiring
+
+### New CLI Flags in 0.9.x
+
+| Flag | Purpose |
+|------|---------|
+| `--gateway-stub-handlers` | Generate stub handlers instead of full implementations |
+| `--gateway-client-class-name` | Override the client class name used in handlers |
+| `--gateway-decorator-name` | Override the Fastify decorator name |
+| `--gateway-skip-plugin` | Skip `plugin.ts` generation |
+| `--gateway-skip-runtime` | Skip `runtime.ts` generation |
+| `--catalog-file` | Specify catalog location for gateway command |
+
+### Is 0.9.x Breaking?
+
+Soft breaking. Regeneration changes the output, but the `--gateway-stub-handlers` flag preserves the old behavior.
+
+## Upgrading to 0.8.x from 0.7.x
+
+This upgrade changes CLI flag names, URN format, and adds required arguments. It is a breaking change.
+
+### What Changed in 0.8.x
+
+All CLI flags changed from camelCase to kebab-case. The URN format changed to a service-first structure. The `--gateway-version-prefix` and `--gateway-service-name` flags became required for gateway and pipeline commands. Catalog files now co-locate with their output directory by default.
+
+### CLI Flag Renames in 0.8.x
+
+| Old Flag (0.7.x) | New Flag (0.8.x) |
+|-------------------|-------------------|
+| `--versionTag` | `--openapi-version` |
+| `--basePath` | `--openapi-base-path` |
+| `--pathStyle` | `--openapi-path-style` |
+| `--closedSchemas` | `--openapi-closed-schemas` |
+| `--pruneUnusedSchemas` | `--openapi-prune-unused-schemas` |
+
+### Steps to Upgrade to 0.8.x
+
+1. Update all CLI commands in scripts and CI to use the new kebab-case flag names
+2. Add `--gateway-service-name` and `--gateway-version-prefix` to all gateway and pipeline commands
+3. Regenerate all output because the URN format in JSON schemas changed
+4. Update any code that parses URN identifiers to use the new service-first format
+
+### URN Format Change in 0.8.x
+
+The old format was `urn:schema:{version}:services:{service}:{models|operations}:{slug}`.
+
+The new format is `urn:services:{service}:{version}:schemas:{models|operations}:{slug}`.
+
+### Is 0.8.x Breaking?
+
+Yes. CLI flags, URN format, and required arguments all changed.

package/docs/production.md

@@ -0,0 +1,80 @@
+# Production Guide
+
+Guidance for using wsdl-tsc generated code in production environments.
+
+See [README](../README.md) for quick start and [Gateway Guide](gateway-guide.md) for integration patterns.
+
+## Deterministic Output
+
+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
+
+Regenerate safely in CI/CD without spurious diffs.
+
+## Validation
+
+### OpenAPI Validation
+
+Enabled by default using @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.
+
+## SOAP Wire Logging
+
+Enable SOAP request/response debugging:
+
+```bash
+NODE_DEBUG=soap node app.js
+```
+
+This logs full XML request/response payloads to console.
+
+## CI/CD Tips
+
+### Caching Strategy
+
+```bash
+npx wsdl-tsc compile \
+  --wsdl-source ./wsdl/Service.wsdl \
+  --catalog-file ./build/catalog.json
+
+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
+
+```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"
+  }
+}
+```
+
+## Known Limitations
+
+### Choice Elements
+
+Current strategy: all-optional (all branches optional). Discriminated union support is 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.