@techspokes/typescript-wsdl-client 0.8.19 → 0.9.1

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.
 
 ---
 
@@ -51,7 +51,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.                                 |
 
@@ -106,13 +106,13 @@ npx wsdl-tsc pipeline \
 
 The tool provides **five 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 |
+| `pipeline` | Run full pipeline: client + OpenAPI + gateway in one pass     | CI/CD automation, complete stack generation   |
 
 ---
 
@@ -579,23 +579,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
 
@@ -621,10 +619,18 @@ npx wsdl-tsc gateway \
 
 ### Optional Flags
 
-| 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 |
+| 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.
 
 ### Generated Output Structure
 
@@ -639,12 +645,14 @@ npx wsdl-tsc gateway \
 │       ├── <operation1>.json
 │       ├── <operation2>.json
 │       └── ...
-├── routes/                  # Individual route registration files
+├── routes/                  # Route registration files with full handlers
 │   ├── <route1>.ts
 │   ├── <route2>.ts
 │   └── ...
 ├── schemas.ts               # Schema registration module
-└── routes.ts                # Route aggregator module
+├── routes.ts                # Route aggregator module
+├── runtime.ts               # Envelope builders and error handler
+└── plugin.ts                # Fastify plugin wrapper (recommended entry point)
 ```
 
 ### URN-Based Schema IDs
@@ -703,56 +711,156 @@ npx wsdl-tsc gateway \
 
 ### Integration Pattern
 
-The generated gateway scaffolding provides the foundation for your Fastify application:
+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 { registerSchemas } from './gateway/schemas.js';
-import { registerRoutes } from './gateway/routes.js';
+import weatherGateway from './gateway/plugin.js';
+import { Weather } from './client/client.js';
 
 const app = Fastify({ logger: true });
 
-// Register JSON Schemas (validation setup)
-await registerSchemas(app);
+// Create and configure SOAP client
+const weatherClient = new Weather({
+  source: 'https://example.com/weather.wsdl',
+  // security: new soap.WSSecurity('user', 'pass'), // if needed
+});
 
-// Register routes (with handler stubs)
-await registerRoutes(app, {
-  prefix: '/api/v1',
-  // Pass any route-level options
+// 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 });
 ```
 
-> **Note**: The registered routes contain handler stubs that throw "Not implemented" errors. You must implement the handler logic in each route file before the gateway becomes functional.
+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)
 
-### Handler Implementation
+For more control, you can use the individual modules:
 
-> ** Manual Implementation Required**: Currently, the gateway generator produces handler stubs that you must implement. Future versions will include full code generation for handler logic.
+```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';
 
-Each generated route file contains handler stubs that you need to implement:
+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 });
+```
+
+### Generated Handler Implementation
+
+Route handlers are fully implemented and call the SOAP client automatically:
 
 ```typescript
-// Example: routes/get-weather.ts
-export async function handler(request, reply) {
-  // TODO: Implement handler logic
-  // 1. Extract validated input from request.body
-  // 2. Call SOAP client
-  // 3. Transform response
-  // 4. Return standard envelope
-  
-  throw new Error('Not implemented');
+// 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);
+    },
+  });
+}
+```
+
+### Response Envelope
+
+All responses are wrapped in a standard envelope format:
+
+**Success Response:**
+```
+{
+  "status": "SUCCESS",
+  "message": null,
+  "data": { /* SOAP response data */ },
+  "error": null
 }
 ```
 
-**Current workflow**:
-1. Generate gateway scaffolding with `wsdl-tsc gateway`
-2. Implement handler functions manually in each route file
-3. Import and call your SOAP client
-4. Transform SOAP responses to match OpenAPI schemas
-5. Return responses in the standard envelope format
+**Error Response:**
+```
+{
+  "status": "ERROR",
+  "message": "Request validation failed",
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": { /* validation errors */ }
+  }
+}
+```
+
+### 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`      |
+
+### Stub Handler Mode (Backward Compatible)
+
+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
+```
 
-**Future enhancement**: Automated handler generation will include SOAP client calls, response transformation, error handling, and envelope wrapping.
+This generates minimal handler stubs that throw "Not implemented" errors, allowing you to implement fully custom logic while keeping the routing and validation infrastructure.
 
 ---
 

package/dist/cli.js

@@ -327,6 +327,33 @@ if (rawArgs[0] === "gateway") {
         .option("gateway-default-status-codes", {
         type: "string",
         desc: "Comma-separated status codes to backfill with default response (default: 200,400,401,403,404,409,422,429,500,502,503,504)"
+    })
+        .option("catalog-file", {
+        type: "string",
+        desc: "Path to catalog.json for operation metadata (enables type-safe handlers)"
+    })
+        .option("gateway-client-class-name", {
+        type: "string",
+        desc: "Override auto-detected SOAP client class name"
+    })
+        .option("gateway-decorator-name", {
+        type: "string",
+        desc: "Fastify decorator name for client (default: derived from service slug)"
+    })
+        .option("gateway-stub-handlers", {
+        type: "boolean",
+        default: false,
+        desc: "Generate stub handlers instead of full implementations"
+    })
+        .option("gateway-skip-plugin", {
+        type: "boolean",
+        default: false,
+        desc: "Skip generating plugin.ts wrapper"
+    })
+        .option("gateway-skip-runtime", {
+        type: "boolean",
+        default: false,
+        desc: "Skip generating runtime.ts utilities"
     })
         .strict()
         .help()
@@ -351,6 +378,13 @@ if (rawArgs[0] === "gateway") {
         serviceSlug: gatewayArgv["gateway-service-name"],
         defaultResponseStatusCodes,
         imports: gatewayArgv["import-extensions"],
+        catalogFile: gatewayArgv["catalog-file"],
+        clientClassName: gatewayArgv["gateway-client-class-name"],
+        clientDecoratorName: gatewayArgv["gateway-decorator-name"],
+        stubHandlers: gatewayArgv["gateway-stub-handlers"],
+        // Only override defaults if explicitly skipping (otherwise let generateGateway decide based on stubHandlers)
+        emitPlugin: gatewayArgv["gateway-skip-plugin"] ? false : undefined,
+        emitRuntime: gatewayArgv["gateway-skip-runtime"] ? false : undefined,
     });
     success(`Gateway code generated in ${outDir}`);
     process.exit(0);
@@ -430,6 +464,29 @@ if (rawArgs[0] === "pipeline") {
         .option("gateway-default-status-codes", {
         type: "string",
         desc: "Comma-separated status codes for gateway (default: 200,400,401,403,404,409,422,429,500,502,503,504)"
+    })
+        .option("gateway-client-class-name", {
+        type: "string",
+        desc: "Override auto-detected SOAP client class name for gateway"
+    })
+        .option("gateway-decorator-name", {
+        type: "string",
+        desc: "Fastify decorator name for client (default: derived from service slug)"
+    })
+        .option("gateway-stub-handlers", {
+        type: "boolean",
+        default: false,
+        desc: "Generate stub handlers instead of full implementations"
+    })
+        .option("gateway-skip-plugin", {
+        type: "boolean",
+        default: false,
+        desc: "Skip generating plugin.ts wrapper"
+    })
+        .option("gateway-skip-runtime", {
+        type: "boolean",
+        default: false,
+        desc: "Skip generating runtime.ts utilities"
     })
         .strict()
         .help()
@@ -507,6 +564,11 @@ if (rawArgs[0] === "pipeline") {
             outDir: path.resolve(gatewayOut),
             serviceSlug: pipelineArgv["gateway-service-name"],
             versionSlug: pipelineArgv["gateway-version-prefix"],
+            clientClassName: pipelineArgv["gateway-client-class-name"],
+            clientDecoratorName: pipelineArgv["gateway-decorator-name"],
+            stubHandlers: pipelineArgv["gateway-stub-handlers"],
+            emitPlugin: pipelineArgv["gateway-skip-plugin"] ? false : undefined,
+            emitRuntime: pipelineArgv["gateway-skip-runtime"] ? false : undefined,
         } : undefined,
     });
     process.exit(0);

package/dist/compiler/schemaCompiler.d.ts

@@ -114,6 +114,8 @@ export type CompiledCatalog = {
         inputElement?: QName;
         outputElement?: QName;
         security?: string[];
+        inputTypeName?: string;
+        outputTypeName?: string;
     }>;
     wsdlTargetNS: string;
     wsdlUri: string;

package/dist/compiler/schemaCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemaCompiler.d.ts","sourceRoot":"","sources":["../../src/compiler/schemaCompiler.ts"],"names":[],"mappings":"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"}

package/dist/compiler/schemaCompiler.js

@@ -615,7 +615,10 @@ export function compileCatalog(cat, options) {
         const outMsg = findMessage(getFirstWithLocalName(po, "output")?.["@_message"]);
         const inputElement = elementOfMessage(inMsg);
         const outputElement = elementOfMessage(outMsg);
-        return { name, soapAction: bOps.get(name) || "", inputElement, outputElement };
+        // Derive TypeScript type names from element local names
+        const inputTypeName = inputElement ? pascal(inputElement.local) : undefined;
+        const outputTypeName = outputElement ? pascal(outputElement.local) : undefined;
+        return { name, soapAction: bOps.get(name) || "", inputElement, outputElement, inputTypeName, outputTypeName };
     })
         .filter((x) => x != null));
     // --- WS-Policy: scan for security requirements (inline policies only) ---

package/dist/gateway/generateGateway.d.ts

@@ -10,6 +10,12 @@
  * @property {string} serviceSlug - Service identifier for URN generation (required)
  * @property {number[]} [defaultResponseStatusCodes] - Status codes to backfill with default response
  * @property {"js"|"ts"|"bare"} [imports] - Import-extension mode for generated TypeScript modules (mirrors global --imports)
+ * @property {string} [clientClassName] - Override auto-detected SOAP client class name
+ * @property {string} [clientDecoratorName] - Fastify decorator name for client (default: derived from serviceSlug)
+ * @property {string} [catalogFile] - Path to catalog.json for operation metadata
+ * @property {boolean} [emitPlugin] - Whether to emit plugin.ts (default: true)
+ * @property {boolean} [emitRuntime] - Whether to emit runtime.ts (default: true)
+ * @property {boolean} [stubHandlers] - If true, emit stubs instead of full handlers (default: false)
  */
 export interface GenerateGatewayOptions {
     openapiFile?: string;
@@ -20,6 +26,12 @@ export interface GenerateGatewayOptions {
     serviceSlug: string;
     defaultResponseStatusCodes?: number[];
     imports?: "js" | "ts" | "bare";
+    clientClassName?: string;
+    clientDecoratorName?: string;
+    catalogFile?: string;
+    emitPlugin?: boolean;
+    emitRuntime?: boolean;
+    stubHandlers?: boolean;
 }
 /**
  * Generates Fastify gateway code from an OpenAPI 3.1 specification

package/dist/gateway/generateGateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateGateway.d.ts","sourceRoot":"","sources":["../../src/gateway/generateGateway.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,GAAG,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFjF"}
+{"version":3,"file":"generateGateway.d.ts","sourceRoot":"","sources":["../../src/gateway/generateGateway.ts"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,GAAG,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAE/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqJjF"}

package/dist/gateway/generateGateway.js

@@ -23,8 +23,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import * as yaml from "js-yaml";
-import { buildParamSchemasForOperation, getJsonSchemaRefName, isNumericStatus, } from "./helpers.js";
-import { emitModelSchemas, emitOperationSchemas, emitRouteFiles, emitSchemasModule, } from "./generators.js";
+import { buildParamSchemasForOperation, getJsonSchemaRefName, isNumericStatus, resolveClientMeta, resolveOperationMeta, } from "./helpers.js";
+import { emitModelSchemas, emitOperationSchemas, emitPluginModule, emitRouteFiles, emitRouteFilesWithHandlers, emitRuntimeModule, emitSchemasModule, } from "./generators.js";
 /**
  * Generates Fastify gateway code from an OpenAPI 3.1 specification
  *
@@ -119,6 +119,25 @@ export async function generateGateway(opts) {
     ];
     // Determine import-extension mode (defaults to "js" like the client/compiler)
     const importsMode = opts.imports ?? "js";
+    // Determine if we should generate full handlers or stubs
+    const stubHandlers = opts.stubHandlers ?? false;
+    const emitPlugin = opts.emitPlugin ?? !stubHandlers;
+    const emitRuntime = opts.emitRuntime ?? !stubHandlers;
+    // Load catalog if provided (for operation metadata)
+    let catalog = undefined;
+    if (opts.catalogFile && fs.existsSync(opts.catalogFile)) {
+        const catalogRaw = fs.readFileSync(opts.catalogFile, "utf8");
+        catalog = JSON.parse(catalogRaw);
+    }
+    // Resolve client metadata for full handler generation
+    const clientMeta = resolveClientMeta({
+        clientDir: opts.clientDir,
+        catalogFile: opts.catalogFile,
+        clientClassName: opts.clientClassName,
+        clientDecoratorName: opts.clientDecoratorName,
+        serviceSlug,
+        importsMode,
+    }, catalog);
     // Prepare output directories
     const outDir = opts.outDir;
     const modelsDir = path.join(outDir, "schemas", "models");
@@ -126,10 +145,42 @@ export async function generateGateway(opts) {
     const routesDir = path.join(outDir, "routes");
     // Step 1: Generate model schemas and build URN mapping
     const schemaIdByName = emitModelSchemas(doc.components.schemas, modelsDir, versionSlug, serviceSlug);
-    // Step 2: Generate operation schemas
-    const operations = emitOperationSchemas(doc, opsDir, versionSlug, serviceSlug, schemaIdByName, defaultResponseStatusCodes, buildParamSchemasForOperation, getJsonSchemaRefName, isNumericStatus);
-    // Step 3: Emit schemas.ts module
+    // Step 2: Generate operation schemas and collect basic metadata
+    const basicOperations = emitOperationSchemas(doc, opsDir, versionSlug, serviceSlug, schemaIdByName, defaultResponseStatusCodes, buildParamSchemasForOperation, getJsonSchemaRefName, isNumericStatus);
+    // Step 3: Enrich operations with type information for full handlers
+    const operations = basicOperations.map((op) => {
+        // Extract operationId from OpenAPI document
+        const pathItem = doc.paths[op.path];
+        const opDef = pathItem?.[op.method];
+        const operationId = opDef?.operationId || op.operationSlug;
+        // Resolve full operation metadata from catalog
+        const resolved = resolveOperationMeta(operationId, op.operationSlug, op.method, op.path, catalog?.operations);
+        return {
+            ...op,
+            operationId: resolved.operationId,
+            clientMethodName: resolved.clientMethodName,
+            requestTypeName: resolved.requestTypeName,
+            responseTypeName: resolved.responseTypeName,
+        };
+    });
+    // Step 4: Emit schemas.ts module
     emitSchemasModule(outDir, modelsDir, versionSlug, serviceSlug);
-    // Step 4: Emit route files and routes.ts module
-    emitRouteFiles(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode);
+    // Step 5: Emit route files (with handlers or stubs)
+    // Note: Route URLs come from OpenAPI paths which already include any base path
+    if (stubHandlers) {
+        // Legacy mode: emit stub handlers
+        emitRouteFiles(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode);
+    }
+    else {
+        // Full handler mode: emit working implementations
+        emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta);
+    }
+    // Step 6: Emit runtime.ts (if enabled)
+    if (emitRuntime) {
+        emitRuntimeModule(outDir, versionSlug, serviceSlug);
+    }
+    // Step 7: Emit plugin.ts (if enabled)
+    if (emitPlugin) {
+        emitPluginModule(outDir, versionSlug, serviceSlug, clientMeta, importsMode);
+    }
 }

package/dist/gateway/generators.d.ts

@@ -1,4 +1,4 @@
-import { type OpenAPIDocument } from "./helpers.js";
+import { type ClientMeta, type OpenAPIDocument } from "./helpers.js";
 /**
  * Emits individual JSON Schema files for each OpenAPI component schema
  *
@@ -18,11 +18,24 @@ import { type OpenAPIDocument } from "./helpers.js";
 export declare function emitModelSchemas(schemas: Record<string, any>, modelsDir: string, versionSlug: string, serviceSlug: string): Record<string, string>;
 /**
  * Operation metadata for route generation
+ *
+ * @interface OperationMetadata
+ * @property {string} operationSlug - Slugified operation name for filenames
+ * @property {string} method - HTTP method (lowercase)
+ * @property {string} path - URL path
+ * @property {string} [operationId] - OpenAPI operationId
+ * @property {string} [clientMethodName] - SOAP client method to call
+ * @property {string} [requestTypeName] - TypeScript request type name
+ * @property {string} [responseTypeName] - TypeScript response type name
  */
 export interface OperationMetadata {
     operationSlug: string;
     method: string;
     path: string;
+    operationId?: string;
+    clientMethodName?: string;
+    requestTypeName?: string;
+    responseTypeName?: string;
 }
 /**
  * Emits Fastify-compatible operation schema files
@@ -79,6 +92,9 @@ export declare function emitSchemasModule(outDir: string, modelsDir: string, ver
  * - Imports all route registration functions
  * - Exports registerRoutes_{version}_{service}(fastify) function
  *
+ * Note: Route URLs come from OpenAPI paths which already include any base path
+ * configured during OpenAPI generation (--openapi-base-path).
+ *
  * @param {string} outDir - Root output directory
  * @param {string} routesDir - Directory for individual route files
  * @param {string} versionSlug - Version slug for function naming
@@ -87,4 +103,53 @@ export declare function emitSchemasModule(outDir: string, modelsDir: string, ver
  * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode for generated TypeScript modules
  */
 export declare function emitRouteFiles(outDir: string, routesDir: string, versionSlug: string, serviceSlug: string, operations: OperationMetadata[], importsMode: "js" | "ts" | "bare"): void;
+/**
+ * Emits runtime.ts module with envelope builders and error handling utilities
+ *
+ * Generated code includes:
+ * - Response envelope types (SuccessEnvelope, ErrorEnvelope)
+ * - buildSuccessEnvelope() and buildErrorEnvelope() functions
+ * - classifyError() for mapping errors to HTTP status codes
+ * - createGatewayErrorHandler_{version}_{service}() factory function
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ */
+export declare function emitRuntimeModule(outDir: string, versionSlug: string, serviceSlug: string): void;
+/**
+ * Emits plugin.ts module as the primary Fastify plugin wrapper
+ *
+ * Generated code includes:
+ * - Plugin options interface with client and prefix support
+ * - Fastify decorator type augmentation
+ * - Plugin implementation that registers schemas, routes, and error handler
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ * @param {ClientMeta} clientMeta - Client class metadata
+ * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode
+ */
+export declare function emitPluginModule(outDir: string, versionSlug: string, serviceSlug: string, clientMeta: ClientMeta, importsMode: "js" | "ts" | "bare"): void;
+/**
+ * Emits individual route files with full handler implementations
+ *
+ * For each operation:
+ * - Creates routes/{slug}.ts with registerRoute_{slug} function
+ * - Imports operation schema, types, and runtime utilities
+ * - Implements handler that calls decorated client and returns envelope
+ *
+ * Note: Route URLs come from OpenAPI paths which already include any base path
+ * configured during OpenAPI generation (--openapi-base-path).
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} routesDir - Directory for individual route files
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ * @param {OperationMetadata[]} operations - Array of operation metadata
+ * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode
+ * @param {ClientMeta} clientMeta - Client class metadata
+ */
+export declare function emitRouteFilesWithHandlers(outDir: string, routesDir: string, versionSlug: string, serviceSlug: string, operations: OperationMetadata[], importsMode: "js" | "ts" | "bare", clientMeta: ClientMeta): void;
 //# sourceMappingURL=generators.d.ts.map

package/dist/gateway/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"AAcA,OAAO,EAAC,KAAK,eAAe,EAA+B,MAAM,cAAc,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,0BAA0B,EAAE,MAAM,EAAE,EACpC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,GAAG,EACvH,UAAU,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,EACnC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACnC,iBAAiB,EAAE,CA2HrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CA0CN"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"AAcA,OAAO,EAAC,KAAK,UAAU,EAAE,KAAK,eAAe,EAA+B,MAAM,cAAc,CAAC;AAEjG;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,0BAA0B,EAAE,MAAM,EAAE,EACpC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,GAAG,EACvH,UAAU,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,MAAM,EACnC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACnC,iBAAiB,EAAE,CA2HrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CA2CN;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,IAAI,CAkLN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,IAAI,CAyFN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,GACrB,IAAI,CAwEN"}

package/dist/gateway/generators.js

@@ -226,6 +226,9 @@ export function emitSchemasModule(outDir, modelsDir, versionSlug, serviceSlug) {
  * - Imports all route registration functions
  * - Exports registerRoutes_{version}_{service}(fastify) function
  *
+ * Note: Route URLs come from OpenAPI paths which already include any base path
+ * configured during OpenAPI generation (--openapi-base-path).
+ *
  * @param {string} outDir - Root output directory
  * @param {string} routesDir - Directory for individual route files
  * @param {string} versionSlug - Version slug for function naming
@@ -244,6 +247,7 @@ export function emitRouteFiles(outDir, routesDir, versionSlug, serviceSlug, oper
         const routeFileBase = op.operationSlug;
         routesTs += `import { ${fnName} } from "./routes/${routeFileBase}${suffix}";\n`;
         // Generate individual route file
+        // Note: op.path comes from OpenAPI and already includes any base path
         let routeTs = "";
         routeTs += `import type { FastifyInstance } from "fastify";\n`;
         routeTs += `import schema from "../schemas/operations/${op.operationSlug}.json" with { type: "json" };\n\n`;
@@ -268,3 +272,376 @@ export function emitRouteFiles(outDir, routesDir, versionSlug, serviceSlug, oper
     routesTs += `}\n`;
     fs.writeFileSync(path.join(outDir, "routes.ts"), routesTs, "utf8");
 }
+/**
+ * Emits runtime.ts module with envelope builders and error handling utilities
+ *
+ * Generated code includes:
+ * - Response envelope types (SuccessEnvelope, ErrorEnvelope)
+ * - buildSuccessEnvelope() and buildErrorEnvelope() functions
+ * - classifyError() for mapping errors to HTTP status codes
+ * - createGatewayErrorHandler_{version}_{service}() factory function
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ */
+export function emitRuntimeModule(outDir, versionSlug, serviceSlug) {
+    const vSlug = slugName(versionSlug);
+    const sSlug = slugName(serviceSlug);
+    const runtimeTs = `/**
+ * Gateway Runtime Utilities
+ *
+ * Provides envelope builders and error handling for the generated gateway.
+ * Auto-generated - do not edit manually.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+/**
+ * Success response envelope
+ */
+export interface SuccessEnvelope<T> {
+  status: "SUCCESS";
+  message: string | null;
+  data: T;
+  error: null;
+}
+
+/**
+ * Error response envelope
+ */
+export interface ErrorEnvelope {
+  status: "ERROR";
+  message: string;
+  data: null;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+/**
+ * Union type for response envelopes
+ */
+export type ResponseEnvelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+
+/**
+ * Builds a success response envelope
+ *
+ * @param data - The response data
+ * @param message - Optional success message
+ * @returns Success envelope wrapping the data
+ */
+export function buildSuccessEnvelope<T>(data: T, message?: string): SuccessEnvelope<T> {
+  return {
+    status: "SUCCESS",
+    message: message ?? null,
+    data,
+    error: null,
+  };
+}
+
+/**
+ * Builds an error response envelope
+ *
+ * @param code - Error code (e.g., "VALIDATION_ERROR")
+ * @param message - Human-readable error message
+ * @param details - Optional error details
+ * @returns Error envelope with the error information
+ */
+export function buildErrorEnvelope(
+  code: string,
+  message: string,
+  details?: unknown
+): ErrorEnvelope {
+  return {
+    status: "ERROR",
+    message,
+    data: null,
+    error: { code, message, details },
+  };
+}
+
+/**
+ * Classified error with HTTP status and details
+ */
+export interface ClassifiedError {
+  httpStatus: number;
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+/**
+ * Classifies an error and maps it to an appropriate HTTP status code
+ *
+ * @param err - The error to classify
+ * @returns Classified error with HTTP status, code, and message
+ */
+export function classifyError(err: unknown): ClassifiedError {
+  // Fastify validation errors
+  if (err && typeof err === "object" && "validation" in err) {
+    return {
+      httpStatus: 400,
+      code: "VALIDATION_ERROR",
+      message: "Request validation failed",
+      details: (err as Record<string, unknown>).validation,
+    };
+  }
+
+  // SOAP fault errors (node-soap throws these)
+  if (err && typeof err === "object" && "root" in err) {
+    const root = (err as Record<string, unknown>).root as Record<string, unknown> | undefined;
+    const envelope = root?.Envelope as Record<string, unknown> | undefined;
+    const body = envelope?.Body as Record<string, unknown> | undefined;
+    const fault = body?.Fault as Record<string, unknown> | undefined;
+    if (fault) {
+      return {
+        httpStatus: 502,
+        code: "SOAP_FAULT",
+        message: (fault.faultstring as string) || "SOAP service returned a fault",
+        details: fault,
+      };
+    }
+  }
+
+  // Connection/timeout errors
+  if (err instanceof Error) {
+    if (err.message.includes("ECONNREFUSED") || err.message.includes("ENOTFOUND")) {
+      return {
+        httpStatus: 503,
+        code: "SERVICE_UNAVAILABLE",
+        message: "Unable to connect to SOAP service",
+        details: err.message,
+      };
+    }
+    if (err.message.includes("ETIMEDOUT") || err.message.includes("timeout")) {
+      return {
+        httpStatus: 504,
+        code: "GATEWAY_TIMEOUT",
+        message: "SOAP service request timed out",
+        details: err.message,
+      };
+    }
+  }
+
+  // Generic error fallback
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    httpStatus: 500,
+    code: "INTERNAL_ERROR",
+    message,
+    details: process.env.NODE_ENV === "development" ? err : undefined,
+  };
+}
+
+/**
+ * Creates a gateway error handler for this service
+ *
+ * @returns Fastify error handler function
+ */
+export function createGatewayErrorHandler_${vSlug}_${sSlug}() {
+  return async function gatewayErrorHandler(
+    error: Error,
+    request: FastifyRequest,
+    reply: FastifyReply
+  ): Promise<ErrorEnvelope> {
+    const classified = classifyError(error);
+
+    request.log.error({
+      err: error,
+      classified,
+      url: request.url,
+      method: request.method,
+    }, "Gateway error");
+
+    reply.status(classified.httpStatus);
+    return buildErrorEnvelope(classified.code, classified.message, classified.details);
+  };
+}
+`;
+    fs.writeFileSync(path.join(outDir, "runtime.ts"), runtimeTs, "utf8");
+}
+/**
+ * Emits plugin.ts module as the primary Fastify plugin wrapper
+ *
+ * Generated code includes:
+ * - Plugin options interface with client and prefix support
+ * - Fastify decorator type augmentation
+ * - Plugin implementation that registers schemas, routes, and error handler
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ * @param {ClientMeta} clientMeta - Client class metadata
+ * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode
+ */
+export function emitPluginModule(outDir, versionSlug, serviceSlug, clientMeta, importsMode) {
+    const vSlug = slugName(versionSlug);
+    const sSlug = slugName(serviceSlug);
+    const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
+    const pluginTs = `/**
+ * ${clientMeta.className} Gateway Plugin
+ *
+ * Fastify plugin that registers the SOAP-to-REST gateway for ${serviceSlug}.
+ * Auto-generated - do not edit manually.
+ */
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyPluginOptions } from "fastify";
+import { registerSchemas_${vSlug}_${sSlug} } from "./schemas${suffix}";
+import { registerRoutes_${vSlug}_${sSlug} } from "./routes${suffix}";
+import { createGatewayErrorHandler_${vSlug}_${sSlug} } from "./runtime${suffix}";
+
+/**
+ * Options for the ${clientMeta.className} gateway plugin
+ */
+export interface ${clientMeta.className}GatewayOptions extends FastifyPluginOptions {
+  /**
+   * SOAP client instance (pre-configured).
+   * The client should be instantiated with appropriate source and security settings.
+   */
+  client: {
+    [method: string]: (args: unknown) => Promise<{ response: unknown; headers: unknown }>;
+  };
+  /**
+   * Optional additional route prefix applied at runtime.
+   * Note: If you used --openapi-base-path during generation, routes already have that prefix baked in.
+   * Only use this for additional runtime prefixing (e.g., mounting under a versioned sub-path).
+   */
+  prefix?: string;
+}
+
+/**
+ * Fastify decorator type augmentation
+ */
+declare module "fastify" {
+  interface FastifyInstance {
+    ${clientMeta.decoratorName}: {
+      [method: string]: (args: unknown) => Promise<{ response: unknown; headers: unknown }>;
+    };
+  }
+}
+
+/**
+ * Gateway plugin implementation
+ *
+ * @param fastify - Fastify instance
+ * @param opts - Plugin options including client and optional prefix
+ */
+async function ${sSlug}GatewayPlugin(
+  fastify: FastifyInstance,
+  opts: ${clientMeta.className}GatewayOptions
+): Promise<void> {
+  // Decorate with SOAP client
+  if (!fastify.hasDecorator("${clientMeta.decoratorName}")) {
+    fastify.decorate("${clientMeta.decoratorName}", opts.client);
+  }
+
+  // Register model schemas
+  await registerSchemas_${vSlug}_${sSlug}(fastify);
+
+  // Register error handler (scoped to this plugin)
+  fastify.setErrorHandler(createGatewayErrorHandler_${vSlug}_${sSlug}());
+
+  // Register routes (optionally prefixed)
+  if (opts.prefix) {
+    await fastify.register(async (child) => {
+      await registerRoutes_${vSlug}_${sSlug}(child);
+    }, { prefix: opts.prefix });
+  } else {
+    await registerRoutes_${vSlug}_${sSlug}(fastify);
+  }
+}
+
+// Export as Fastify plugin (encapsulated)
+export default fp(${sSlug}GatewayPlugin, {
+  fastify: "5.x",
+  name: "${sSlug}-gateway",
+});
+
+// Named export for convenience
+export { ${sSlug}GatewayPlugin };
+`;
+    fs.writeFileSync(path.join(outDir, "plugin.ts"), pluginTs, "utf8");
+}
+/**
+ * Emits individual route files with full handler implementations
+ *
+ * For each operation:
+ * - Creates routes/{slug}.ts with registerRoute_{slug} function
+ * - Imports operation schema, types, and runtime utilities
+ * - Implements handler that calls decorated client and returns envelope
+ *
+ * Note: Route URLs come from OpenAPI paths which already include any base path
+ * configured during OpenAPI generation (--openapi-base-path).
+ *
+ * @param {string} outDir - Root output directory
+ * @param {string} routesDir - Directory for individual route files
+ * @param {string} versionSlug - Version slug for function naming
+ * @param {string} serviceSlug - Service slug for function naming
+ * @param {OperationMetadata[]} operations - Array of operation metadata
+ * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode
+ * @param {ClientMeta} clientMeta - Client class metadata
+ */
+export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta) {
+    fs.mkdirSync(routesDir, { recursive: true });
+    // Sort operations for deterministic output
+    operations.sort((a, b) => a.operationSlug.localeCompare(b.operationSlug));
+    const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
+    const vSlug = slugName(versionSlug);
+    const sSlug = slugName(serviceSlug);
+    let routesTs = `import type { FastifyInstance } from "fastify";\n`;
+    operations.forEach((op) => {
+        const fnName = `registerRoute_${vSlug}_${sSlug}_${op.operationSlug.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+        const routeFileBase = op.operationSlug;
+        routesTs += `import { ${fnName} } from "./routes/${routeFileBase}${suffix}";\n`;
+        // Generate individual route file with full handler
+        const clientMethod = op.clientMethodName || op.operationId || op.operationSlug;
+        // Type names for documentation; we use unknown at runtime since schema validation handles it
+        const reqTypeName = op.requestTypeName || "unknown";
+        const resTypeName = op.responseTypeName || "unknown";
+        // Note: op.path comes from OpenAPI and already includes any base path
+        let routeTs = `/**
+ * Route: ${op.method.toUpperCase()} ${op.path}
+ * Operation: ${op.operationId || op.operationSlug}
+ * Request Type: ${reqTypeName}
+ * Response Type: ${resTypeName} (wrapped in envelope)
+ * Auto-generated - do not edit manually.
+ */
+import type { FastifyInstance } from "fastify";
+import schema from "../schemas/operations/${op.operationSlug}.json" with { type: "json" };
+import { buildSuccessEnvelope } from "../runtime${suffix}";
+
+export async function ${fnName}(fastify: FastifyInstance) {
+  fastify.route({
+    method: "${op.method.toUpperCase()}",
+    url: "${op.path}",
+    schema,
+    handler: async (request) => {
+      const client = fastify.${clientMeta.decoratorName};
+      const result = await client.${clientMethod}(request.body);
+      return buildSuccessEnvelope(result.response);
+    },
+  });
+}
+`;
+        fs.writeFileSync(path.join(routesDir, `${routeFileBase}.ts`), routeTs, "utf8");
+    });
+    // Generate routes.ts aggregator module
+    const routeFnName = `registerRoutes_${vSlug}_${sSlug}`;
+    routesTs += `
+/**
+ * Registers all ${serviceSlug} routes with the Fastify instance.
+ * Route paths are determined by the OpenAPI specification (--openapi-base-path).
+ */
+export async function ${routeFnName}(fastify: FastifyInstance): Promise<void> {
+`;
+    // Generate route registration calls
+    const routeCalls = operations.map((op) => {
+        const fnName = `registerRoute_${vSlug}_${sSlug}_${op.operationSlug.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+        return `  await ${fnName}(fastify);`;
+    }).join("\n");
+    routesTs += `  // Register all routes\n${routeCalls}\n`;
+    routesTs += `}\n`;
+    fs.writeFileSync(path.join(outDir, "routes.ts"), routesTs, "utf8");
+}

package/dist/gateway/helpers.d.ts

@@ -112,4 +112,99 @@ export interface ParamSchemaBuildResult {
  * @returns {ParamSchemaBuildResult} - Object with optional params/querystring/headers schemas
  */
 export declare function buildParamSchemasForOperation(pathItem: any, operation: any, doc: OpenAPIDocument, schemaIdByName: Record<string, string>): ParamSchemaBuildResult;
+/**
+ * Client Metadata Resolution
+ *
+ * Types and functions for resolving SOAP client metadata used in handler generation.
+ */
+/**
+ * Metadata about the SOAP client for handler generation
+ *
+ * @interface ClientMeta
+ * @property {string} className - Client class name (e.g., "EVRNService")
+ * @property {string} decoratorName - Fastify decorator name (e.g., "evrnserviceClient")
+ * @property {string} importPath - Import path relative to routes directory
+ * @property {string} typesImportPath - Import path for types
+ */
+export interface ClientMeta {
+    className: string;
+    decoratorName: string;
+    importPath: string;
+    typesImportPath: string;
+}
+/**
+ * Extended operation metadata for full handler generation
+ *
+ * @interface ResolvedOperationMeta
+ * @property {string} operationId - OpenAPI operationId
+ * @property {string} operationSlug - Slugified for filenames
+ * @property {string} method - HTTP method
+ * @property {string} path - URL path
+ * @property {string} clientMethodName - SOAP client method to call
+ * @property {string} [requestTypeName] - TypeScript request type
+ * @property {string} [responseTypeName] - TypeScript response type
+ */
+export interface ResolvedOperationMeta {
+    operationId: string;
+    operationSlug: string;
+    method: string;
+    path: string;
+    clientMethodName: string;
+    requestTypeName?: string;
+    responseTypeName?: string;
+}
+/**
+ * PascalCase conversion utility
+ *
+ * @param {string} str - String to convert to PascalCase
+ * @returns {string} - PascalCase version of the string
+ */
+export declare function pascalCase(str: string): string;
+/**
+ * Options for resolving client metadata
+ *
+ * @interface ResolveClientMetaOptions
+ * @property {string} [clientDir] - Path to client directory
+ * @property {string} [catalogFile] - Path to catalog.json
+ * @property {string} [clientClassName] - Override client class name
+ * @property {string} [clientDecoratorName] - Override decorator name
+ * @property {string} serviceSlug - Service slug for derivation
+ * @property {"js"|"ts"|"bare"} importsMode - Import extension mode
+ */
+export interface ResolveClientMetaOptions {
+    clientDir?: string;
+    catalogFile?: string;
+    clientClassName?: string;
+    clientDecoratorName?: string;
+    serviceSlug: string;
+    importsMode: "js" | "ts" | "bare";
+}
+/**
+ * Resolves client metadata from available sources
+ *
+ * Resolution priority:
+ * 1. Explicit clientClassName/clientDecoratorName options
+ * 2. serviceName from catalog.json if catalogFile provided
+ * 3. Derive from serviceSlug
+ *
+ * @param {ResolveClientMetaOptions} opts - Options for resolving client metadata
+ * @param {any} [catalog] - Optional loaded catalog object
+ * @returns {ClientMeta} - Resolved client metadata
+ */
+export declare function resolveClientMeta(opts: ResolveClientMetaOptions, catalog?: any): ClientMeta;
+/**
+ * Resolves operation metadata by matching OpenAPI operationId to catalog operations
+ *
+ * @param {string} operationId - OpenAPI operation ID
+ * @param {string} operationSlug - Slugified operation name for filenames
+ * @param {string} method - HTTP method
+ * @param {string} path - URL path
+ * @param {Array} [catalogOperations] - Optional catalog operations to match against
+ * @returns {ResolvedOperationMeta} - Resolved operation metadata with type names
+ */
+export declare function resolveOperationMeta(operationId: string, operationSlug: string, method: string, path: string, catalogOperations?: Array<{
+    name: string;
+    inputTypeName?: string;
+    outputTypeName?: string;
+}>): ResolvedOperationMeta;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/gateway/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/gateway/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAClC,CAAC;CACH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAqBxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,CAcxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,GAAG,GAAG,CAiB3E;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB,WAAW,CAAC,EAAE,GAAG,CAAC;IAClB,aAAa,CAAC,EAAE,GAAG,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,GAAG,EACb,SAAS,EAAE,GAAG,EACd,GAAG,EAAE,eAAe,EACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,sBAAsB,CAmFxB"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/gateway/helpers.ts"],"names":[],"mappings":"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"}

package/dist/gateway/helpers.js

@@ -222,3 +222,87 @@ export function buildParamSchemasForOperation(pathItem, operation, doc, schemaId
         headersSchema,
     };
 }
+/**
+ * PascalCase conversion utility
+ *
+ * @param {string} str - String to convert to PascalCase
+ * @returns {string} - PascalCase version of the string
+ */
+export function pascalCase(str) {
+    return str
+        .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+        .replace(/^(.)/, (c) => c.toUpperCase());
+}
+/**
+ * Resolves client metadata from available sources
+ *
+ * Resolution priority:
+ * 1. Explicit clientClassName/clientDecoratorName options
+ * 2. serviceName from catalog.json if catalogFile provided
+ * 3. Derive from serviceSlug
+ *
+ * @param {ResolveClientMetaOptions} opts - Options for resolving client metadata
+ * @param {any} [catalog] - Optional loaded catalog object
+ * @returns {ClientMeta} - Resolved client metadata
+ */
+export function resolveClientMeta(opts, catalog) {
+    const suffix = opts.importsMode === "bare" ? "" : `.${opts.importsMode}`;
+    // Determine client class name
+    let className;
+    if (opts.clientClassName) {
+        className = opts.clientClassName;
+    }
+    else if (catalog?.serviceName) {
+        className = pascalCase(catalog.serviceName);
+    }
+    else {
+        className = pascalCase(opts.serviceSlug);
+    }
+    // Determine decorator name
+    let decoratorName;
+    if (opts.clientDecoratorName) {
+        decoratorName = opts.clientDecoratorName;
+    }
+    else {
+        decoratorName = slugName(className) + "Client";
+    }
+    // Build import paths (relative from routes/ to client/)
+    const importPath = opts.clientDir
+        ? `../../client/client${suffix}`
+        : `../client/client${suffix}`;
+    const typesImportPath = opts.clientDir
+        ? `../../client/types${suffix}`
+        : `../client/types${suffix}`;
+    return {
+        className,
+        decoratorName,
+        importPath,
+        typesImportPath,
+    };
+}
+/**
+ * Resolves operation metadata by matching OpenAPI operationId to catalog operations
+ *
+ * @param {string} operationId - OpenAPI operation ID
+ * @param {string} operationSlug - Slugified operation name for filenames
+ * @param {string} method - HTTP method
+ * @param {string} path - URL path
+ * @param {Array} [catalogOperations] - Optional catalog operations to match against
+ * @returns {ResolvedOperationMeta} - Resolved operation metadata with type names
+ */
+export function resolveOperationMeta(operationId, operationSlug, method, path, catalogOperations) {
+    // Try to find matching operation in catalog
+    const catalogOp = catalogOperations?.find(op => op.name === operationId || slugName(op.name) === operationSlug);
+    // Use catalog type names if available, otherwise derive by convention
+    const requestTypeName = catalogOp?.inputTypeName ?? pascalCase(operationId);
+    const responseTypeName = catalogOp?.outputTypeName ?? pascalCase(operationId);
+    return {
+        operationId,
+        operationSlug,
+        method,
+        path,
+        clientMethodName: operationId, // Client methods use the original operation name
+        requestTypeName,
+        responseTypeName,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.8.19",
+  "version": "0.9.1",
   "description": "TypeScript WSDL → SOAP client generator with full xs:attribute support, complex types, sequences, inheritance, and namespace-collision merging.",
   "keywords": [
     "wsdl",
@@ -65,6 +65,7 @@
     "@types/node": "^25.0.2",
     "@types/yargs": "^17.0.33",
     "fastify": "^5.2.0",
+    "fastify-plugin": "^5.1.0",
     "rimraf": "^6.0.0",
     "tsx": "^4.20.0",
     "typescript": "^5.6.3"