@techspokes/typescript-wsdl-client 0.8.19 → 0.9.0

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

@@ -621,10 +621,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
 
@@ -640,11 +648,13 @@ npx wsdl-tsc gateway \
 │       ├── <operation2>.json
 │       └── ...
 ├── routes/                  # Individual route registration files
-│   ├── <route1>.ts
+│   ├── <route1>.ts          # Full handler implementations
 │   ├── <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 +713,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)
+
+For more control, you can use the individual modules:
+
+```typescript
+import Fastify from 'fastify';
+import { registerSchemas_v1_weather } from './gateway/schemas.js';
+import { registerRoutes_v1_weather } from './gateway/routes.js';
+import { createGatewayErrorHandler_v1_weather } from './gateway/runtime.js';
+import { Weather } from './client/client.js';
+
+const app = Fastify({ logger: true });
+
+// Manual setup
+const weatherClient = new Weather({ source: 'weather.wsdl' });
+app.decorate('weatherClient', weatherClient);
+
+// Register schemas
+await registerSchemas_v1_weather(app);
+
+// Install error handler
+app.setErrorHandler(createGatewayErrorHandler_v1_weather());
+
+// Register routes (paths already include --openapi-base-path if configured)
+await registerRoutes_v1_weather(app);
 
-### Handler Implementation
+await app.listen({ port: 3000 });
+```
 
-> ** Manual Implementation Required**: Currently, the gateway generator produces handler stubs that you must implement. Future versions will include full code generation for handler logic.
+### Generated Handler Implementation
 
-Each generated route file contains handler stubs that you need to implement:
+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
+}
+```
+
+**Error Response:**
+```
+{
+  "status": "ERROR",
+  "message": "Request validation failed",
+  "data": null,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": { /* validation errors */ }
+  }
 }
 ```
 
-**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 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 (Legacy)
+
+For backward compatibility or manual handler implementation, 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 handler stubs that throw "Not implemented" errors, allowing you to implement custom logic.
 
 ---
 

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.0",
   "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"