@techspokes/typescript-wsdl-client 0.9.0 → 0.9.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 TechSpokes, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 TechSpokes, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,7 +9,7 @@
 [![TechSpokes Org](https://img.shields.io/badge/org-techspokes-181717?logo=github)](https://github.com/techspokes)
 [![Sponsor](https://img.shields.io/badge/sponsor-GitHub-blue?logo=github-sponsors)](https://github.com/sponsors/TechSpokes)
 
-> **Mission**: Transform complex WSDL/XSD definitions into ergonomic, type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and Fastify REST gateway scaffolding — enabling confident integration with legacy enterprise services.
+> **Mission**: Transform complex WSDL/XSD definitions into ergonomic, type-safe TypeScript SOAP clients with optional OpenAPI 3.1 specs and production-ready Fastify REST gateways — enabling confident integration with legacy enterprise services.
 
 ---
 
@@ -23,15 +23,16 @@
 - [6. Command: `client`](#6-command-client)
 - [7. Command: `openapi`](#7-command-openapi)
 - [8. Command: `gateway`](#8-command-gateway)
-- [9. Command: `pipeline`](#9-command-pipeline)
-- [10. Working With Generated Clients](#10-working-with-generated-clients)
-- [11. OpenAPI Configuration](#11-openapi-configuration)
-- [12. Programmatic API](#12-programmatic-api)
-- [13. Advanced Topics](#13-advanced-topics)
-- [14. Troubleshooting](#14-troubleshooting)
-- [15. Contributing](#15-contributing)
-- [16. License](#16-license)
-- [17. Sponsors](#17-sponsors)
+- [9. Command: `app`](#9-command-app)
+- [10. Command: `pipeline`](#10-command-pipeline)
+- [11. Working With Generated Clients](#11-working-with-generated-clients)
+- [12. OpenAPI Configuration](#12-openapi-configuration)
+- [13. Programmatic API](#13-programmatic-api)
+- [14. Advanced Topics](#14-advanced-topics)
+- [15. Troubleshooting](#15-troubleshooting)
+- [16. Contributing](#16-contributing)
+- [17. License](#17-license)
+- [18. Sponsors](#18-sponsors)
 
 ---
 
@@ -51,7 +52,7 @@ Most WSDL generators produce loosely typed stubs or expose raw XML complexity to
 | **Catalog Introspection**            | One JSON artifact (`catalog.json`) to drive further tooling (including OpenAPI & gateway).           |
 | **OpenAPI 3.1 Bridge**               | Mirrors the exact TypeScript model with no divergence between runtime and spec.                      |
 | **Standard Response Envelope**       | Always-on, debuggable envelope structure (status, message, data, error) for REST gateways.           |
-| **Fastify Gateway Scaffolding**      | Route and schema generation with JSON Schema validation (handler implementation in progress).        |
+| **Fastify Gateway Generation**       | Production-ready route handlers with SOAP client integration and standardized envelope responses.    |
 | **Multi-format Output**              | `--openapi-format json\|yaml\|both` with always-on validation (unless disabled).                     |
 | **One-Shot Pipeline**                | Single pass (parse to TS to OpenAPI to Gateway) for CI & automation.                                 |
 
@@ -104,15 +105,16 @@ npx wsdl-tsc pipeline \
 
 ## 4. Commands Overview
 
-The tool provides **five commands** for different integration scenarios:
+The tool provides **six commands** for different integration scenarios:
 
-| Command      | Purpose                                                        | Typical Use Case                                    |
-|--------------|----------------------------------------------------------------|-----------------------------------------------------|
-| `compile`    | Parse WSDL and emit `catalog.json` only                        | Debugging, inspection, or multi-stage builds        |
-| `client`     | Generate TypeScript SOAP client from WSDL or catalog           | Standard SOAP integration (most common)             |
-| `openapi`    | Generate OpenAPI 3.1 spec from WSDL or catalog                 | Documentation, REST proxies, API gateways           |
-| `gateway`    | Generate Fastify gateway scaffolding from OpenAPI spec         | REST gateway foundation (handler stubs)             |
-| `pipeline`   | Run full pipeline: client + OpenAPI + gateway in one pass      | CI/CD automation, complete stack generation         |
+| Command    | Purpose                                                        | Typical Use Case                              |
+|------------|----------------------------------------------------------------|-----------------------------------------------|
+| `compile`  | Parse WSDL and emit `catalog.json` only                        | Debugging, inspection, or multi-stage builds  |
+| `client`   | Generate TypeScript SOAP client from WSDL or catalog           | Standard SOAP integration (most common)       |
+| `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         |
+| `pipeline` | Run full pipeline: client + OpenAPI + gateway (+ app optional) | CI/CD automation, complete stack generation   |
 
 ---
 
@@ -579,23 +581,21 @@ This ensures diff-friendly output for version control.
 
 ## 8. Command: `gateway`
 
-**Purpose**: Generate Fastify gateway scaffolding (routes and schemas) from an OpenAPI 3.1 specification. This provides the foundation for building a REST API layer over your SOAP client.
-
-> **Current Status (v0.8.0)**: The gateway generator produces basic scaffolding including route registration, JSON Schema validation setup, and handler stubs. Full code generation with complete handler implementations is planned for future releases. You will need to implement the business logic that calls your SOAP client and transforms responses.
+**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 for SOAP operations
+- Establishing Fastify routing structure with full handler implementations
 
 **What it generates**:
-- Fastify route registration files
+- 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
-- Handler stubs (require manual implementation)
-- Full handler implementations (coming in future versions)
+- Runtime utilities (envelope builders, error handlers)
+- Fastify plugin wrapper for simplified integration
 
 ### Usage
 
@@ -647,8 +647,8 @@ npx wsdl-tsc gateway \
 │       ├── <operation1>.json
 │       ├── <operation2>.json
 │       └── ...
-├── routes/                  # Individual route registration files
-│   ├── <route1>.ts          # Full handler implementations
+├── routes/                  # Route registration files with full handlers
+│   ├── <route1>.ts
 │   ├── <route2>.ts
 │   └── ...
 ├── schemas.ts               # Schema registration module
@@ -848,9 +848,9 @@ The centralized error handler (`runtime.ts`) automatically classifies errors:
 | Timeout               | 504         | `GATEWAY_TIMEOUT`     |
 | Other errors          | 500         | `INTERNAL_ERROR`      |
 
-### Stub Handler Mode (Legacy)
+### Stub Handler Mode (Backward Compatible)
 
-For backward compatibility or manual handler implementation, use stub mode:
+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 \
@@ -862,11 +862,193 @@ npx wsdl-tsc gateway \
   --gateway-stub-handlers
 ```
 
-This generates handler stubs that throw "Not implemented" errors, allowing you to implement custom logic.
+This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.
+
+---
+
+## 9. Command: `app`
+
+**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
+
+### Usage
+
+```bash
+npx wsdl-tsc app \
+  --client-dir <path> \
+  --gateway-dir <path> \
+  --openapi-file <path> \
+  [--catalog-file <path>] \
+  [--app-dir <path>] \
+  [options]
+```
+
+### Required Flags
+
+| 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                       |
+
+### Optional Flags
+
+| 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` |
+
+### Examples
+
+#### 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
+```
+
+### Generated App Structure
+
+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)
+```
+
+### Running the Generated App
+
+```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
+```
+
+### Configuration
+
+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                |
+
+### Endpoints
+
+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.
+
+### Example Usage
+
+```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 '{}'
+```
+
+### Integration with Pipeline
+
+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.
 
 ---
 
-## 9. Command: `pipeline`
+## 10. Command: `pipeline`
 
 **Purpose**: Run the complete generation pipeline in a single pass: WSDL parsing → TypeScript client → OpenAPI spec → Fastify gateway.
 
@@ -1044,7 +1226,7 @@ All steps share the same parsed WSDL and compiled catalog, ensuring consistency.
 
 ---
 
-## 10. Working With Generated Clients
+## 11. Working With Generated Clients
 
 ### Client Construction
 
@@ -1111,7 +1293,7 @@ result.GetCityWeatherByZIPResult.Temperature;  // number | string (depends on ma
 
 ---
 
-## 11. OpenAPI Configuration
+## 12. OpenAPI Configuration
 
 ### Security Configuration (`security.json`)
 
@@ -1170,7 +1352,7 @@ Per-operation overrides for method, summary, description, and deprecation:
 
 ---
 
-## 12. Programmatic API
+## 13. Programmatic API
 
 All CLI commands are available as TypeScript functions for programmatic usage.
 
@@ -1437,7 +1619,7 @@ interface PipelineOptions {
 
 ---
 
-## 13. Advanced Topics
+## 14. Advanced Topics
 
 ### Primitive Mapping Philosophy
 
@@ -1512,7 +1694,7 @@ Disable with `--openapi-validate false` or `validate: false` in API.
 
 ---
 
-## 14. Troubleshooting
+## 15. Troubleshooting
 
 ### Common Issues
 
@@ -1593,7 +1775,7 @@ The catalog is automatically placed at `./src/services/hotel/catalog.json`.
 
 ---
 
-## 15. Contributing
+## 16. Contributing
 
 We welcome contributions! Here's how to get started:
 
@@ -1667,7 +1849,7 @@ See also: [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDU
 
 ---
 
-## 16. License
+## 17. License
 
 MIT © TechSpokes
 
@@ -1677,7 +1859,7 @@ See [LICENSE](LICENSE) for full text.
 
 ---
 
-## 17. Sponsors
+## 18. Sponsors
 
 Support ongoing development and maintenance:
 

package/dist/app/generateApp.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Options for app generation
+ *
+ * @interface GenerateAppOptions
+ * @property {string} clientDir - Path to client directory (where client.ts is located)
+ * @property {string} gatewayDir - Path to gateway directory (where plugin.ts is located)
+ * @property {string} openapiFile - Path to OpenAPI spec file
+ * @property {string} catalogFile - Path to catalog.json (required)
+ * @property {string} appDir - Output directory for generated app
+ * @property {"js"|"ts"|"bare"} [imports] - Import-extension mode (default: "js")
+ * @property {string} [host] - Default server host (default: "127.0.0.1")
+ * @property {number} [port] - Default server port (default: 3000)
+ * @property {string} [prefix] - Route prefix (default: "")
+ * @property {boolean} [logger] - Enable Fastify logger (default: true)
+ * @property {"copy"|"reference"} [openapiMode] - How to handle OpenAPI file (default: "copy")
+ */
+export interface GenerateAppOptions {
+    clientDir: string;
+    gatewayDir: string;
+    openapiFile: string;
+    catalogFile: string;
+    appDir: string;
+    imports?: "js" | "ts" | "bare";
+    host?: string;
+    port?: number;
+    prefix?: string;
+    logger?: boolean;
+    openapiMode?: "copy" | "reference";
+}
+/**
+ * Generates a runnable Fastify application
+ *
+ * This function orchestrates the complete app generation process:
+ * 1. Validates all required inputs exist
+ * 2. Reads catalog.json for metadata
+ * 3. Creates app directory
+ * 4. Generates server.ts with Fastify setup
+ * 5. Generates config.ts with environment loading
+ * 6. Generates .env.example with configuration template
+ * 7. Generates README.md with usage instructions
+ * 8. Optionally copies OpenAPI spec into app directory
+ *
+ * @param {GenerateAppOptions} opts - App generation options
+ * @returns {Promise<void>}
+ * @throws {Error} If validation fails or required files are missing
+ */
+export declare function generateApp(opts: GenerateAppOptions): Promise<void>;
+//# sourceMappingURL=generateApp.d.ts.map

package/dist/app/generateApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateApp.d.ts","sourceRoot":"","sources":["../../src/app/generateApp.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;CACpC;AA2gBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCzE"}