@techspokes/typescript-wsdl-client 0.10.4 → 0.11.1

package/README.md

@@ -62,6 +62,31 @@ curl -X POST http://localhost:3000/get-weather-information \
 | Fastify Gateway | plugin.ts, routes/, schemas/ | Production REST handlers |
 | Catalog | catalog.json | Compiled WSDL (debuggable, cacheable) |
 
+## Testing With Generated Code
+
+The generated `operations.ts` provides a typed interface for mocking the SOAP client without importing the concrete class or the `soap` package:
+
+```typescript
+import type { WeatherOperations } from "./generated/client/operations.js";
+
+const mockClient: WeatherOperations = {
+  GetCityWeatherByZIP: async (args) => ({
+    response: { GetCityWeatherByZIPResult: { Success: true, City: "Test" } },
+    headers: {},
+  }),
+  // ... other operations
+};
+
+// Use with the gateway plugin
+import Fastify from "fastify";
+import { weatherGateway } from "./generated/gateway/plugin.js";
+
+const app = Fastify();
+await app.register(weatherGateway, { client: mockClient, prefix: "/v1/weather" });
+```
+
+See [Testing Guide](docs/testing.md) for integration test patterns and mock examples.
+
 ## Commands
 
 | Command | Purpose |
@@ -85,6 +110,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Gateway Guide](docs/gateway-guide.md) | Fastify integration and error handling |
 | [Configuration](docs/configuration.md) | Security, tags, operations config files |
 | [Production Guide](docs/production.md) | CI/CD, validation, logging, limitations |
+| [Testing Guide](docs/testing.md) | Testing patterns and mock client examples |
 | [Troubleshooting](docs/troubleshooting.md) | Common issues and debugging |
 | [Working With Generated Code](docs/generated-code.md) | Using clients and types |
 | [Architecture](docs/architecture.md) | Internal pipeline for contributors |

package/dist/cli.js

@@ -19,6 +19,7 @@ import { generateTypes } from "./client/generateTypes.js";
 import { generateUtils } from "./client/generateUtils.js";
 import { generateCatalog } from "./compiler/generateCatalog.js";
 import { generateClient } from "./client/generateClient.js";
+import { generateOperations } from "./client/generateOperations.js";
 import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
 import { runGenerationPipeline } from "./pipeline.js";
 import { resolveCompilerOptions } from "./config.js";
@@ -183,7 +184,7 @@ if (rawArgs[0] === "client") {
         success(`Compiled catalog written to ${catalogOutPath}`);
     }
     // Emit client artifacts (excluding catalog since we already emitted it above if needed)
-    emitClientArtifacts(clientOutDir, compiled, generateClient, generateTypes, generateUtils);
+    emitClientArtifacts(clientOutDir, compiled, generateClient, generateTypes, generateUtils, generateOperations);
     process.exit(0);
 }
 /**
@@ -237,6 +238,11 @@ if (rawArgs[0] === "openapi") {
         type: "boolean",
         default: false,
         desc: "Emit additionalProperties:false for object schemas"
+    })
+        .option("openapi-flatten-array-wrappers", {
+        type: "boolean",
+        default: true,
+        desc: "Flatten ArrayOf* wrapper types to plain arrays in schemas (default: true)"
     })
         .option("openapi-prune-unused-schemas", {
         type: "boolean",
@@ -357,6 +363,11 @@ if (rawArgs[0] === "gateway") {
         type: "boolean",
         default: false,
         desc: "Skip generating runtime.ts utilities"
+    })
+        .option("openapi-flatten-array-wrappers", {
+        type: "boolean",
+        default: true,
+        desc: "Generate runtime unwrap for ArrayOf* wrapper types (default: true)"
     })
         .strict()
         .help()
@@ -388,6 +399,7 @@ if (rawArgs[0] === "gateway") {
         // 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,
+        flattenArrayWrappers: gatewayArgv["openapi-flatten-array-wrappers"],
     });
     success(`Gateway code generated in ${outDir}`);
     process.exit(0);
@@ -569,6 +581,11 @@ if (rawArgs[0] === "pipeline") {
         .option("openapi-tags-file", { type: "string" })
         .option("openapi-ops-file", { type: "string" })
         .option("openapi-closed-schemas", { type: "boolean", default: false })
+        .option("openapi-flatten-array-wrappers", {
+        type: "boolean",
+        default: true,
+        desc: "Flatten ArrayOf* wrapper types to plain arrays in schemas (default: true)"
+    })
         .option("openapi-prune-unused-schemas", { type: "boolean", default: false })
         .option("openapi-envelope-namespace", { type: "string" })
         .option("openapi-error-namespace", { type: "string" })

package/dist/client/generateOperations.d.ts

@@ -0,0 +1,13 @@
+import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Generates an operations.ts file with a fully-typed interface for all SOAP operations
+ *
+ * The interface mirrors the async method signatures of the generated client class
+ * but uses concrete input/output types from types.ts instead of generic parameters.
+ * This enables type-safe mocking without SOAP runtime dependencies.
+ *
+ * @param outFile - Path to the output TypeScript file
+ * @param compiled - The compiled WSDL catalog
+ */
+export declare function generateOperations(outFile: string, compiled: CompiledCatalog): void;
+//# sourceMappingURL=generateOperations.d.ts.map

package/dist/client/generateOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateOperations.d.ts","sourceRoot":"","sources":["../../src/client/generateOperations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAIrE;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CA0DnF"}

package/dist/client/generateOperations.js

@@ -0,0 +1,71 @@
+/**
+ * Operations Interface Generator
+ *
+ * Generates a fully-typed operations interface for the SOAP client.
+ * This standalone interface enables mocking and testing without importing
+ * the concrete SOAP client class or its runtime dependencies.
+ */
+import fs from "node:fs";
+import { deriveClientName, pascal } from "../util/tools.js";
+import { error } from "../util/cli.js";
+/**
+ * Generates an operations.ts file with a fully-typed interface for all SOAP operations
+ *
+ * The interface mirrors the async method signatures of the generated client class
+ * but uses concrete input/output types from types.ts instead of generic parameters.
+ * This enables type-safe mocking without SOAP runtime dependencies.
+ *
+ * @param outFile - Path to the output TypeScript file
+ * @param compiled - The compiled WSDL catalog
+ */
+export function generateOperations(outFile, compiled) {
+    const ext = compiled.options.imports ?? "bare";
+    const suffix = ext === "bare" ? "" : `.${ext}`;
+    const clientName = deriveClientName(compiled);
+    // Collect type names used in method signatures for the import statement
+    const importedTypes = new Set();
+    const methods = [];
+    for (const op of compiled.operations) {
+        const inTypeName = op.inputElement ? pascal(op.inputElement.local) : undefined;
+        const outTypeName = op.outputElement ? pascal(op.outputElement.local) : undefined;
+        if (!inTypeName && !outTypeName) {
+            continue;
+        }
+        const inTs = inTypeName ?? "Record<string, unknown>";
+        const outTs = outTypeName ?? "unknown";
+        if (inTypeName)
+            importedTypes.add(inTypeName);
+        if (outTypeName)
+            importedTypes.add(outTypeName);
+        methods.push(`  ${op.name}(\n` +
+            `    args: ${inTs}\n` +
+            `  ): Promise<{ response: ${outTs}; headers: unknown }>;\n`);
+    }
+    // Build sorted import list for deterministic output
+    const sortedImports = Array.from(importedTypes).sort();
+    const typeImport = sortedImports.length > 0
+        ? `import type {\n${sortedImports.map((t) => `  ${t},`).join("\n")}\n} from "./types${suffix}";\n\n`
+        : "";
+    const content = `/**
+ * Typed operations interface for the ${clientName} service.
+ *
+ * Implement this interface to create mock clients or alternative
+ * transport layers without depending on the SOAP runtime.
+ *
+ * Auto-generated - do not edit manually.
+ */
+${typeImport}/**
+ * All operations exposed by the ${clientName} SOAP service.
+ *
+ * The concrete ${clientName} class satisfies this interface.
+ * Use this type for dependency injection, mocking, or testing.
+ */
+export interface ${clientName}Operations {
+${methods.join("\n")}}\n`;
+    try {
+        fs.writeFileSync(outFile, content, "utf8");
+    }
+    catch (e) {
+        error(`Failed to write operations interface to ${outFile}`);
+    }
+}

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

@@ -1,5 +1,6 @@
 import { getChildrenWithLocalName, getFirstWithLocalName, normalizeArray, pascal, resolveQName, } from "../util/tools.js";
 import { xsdToTsPrimitive } from "../xsd/primitives.js";
+import { WsdlCompilationError } from "../util/errors.js";
 // XML Schema namespace constant
 const XS = "http://www.w3.org/2001/XMLSchema";
 /**
@@ -194,7 +195,14 @@ export function compileCatalog(cat, options) {
             const t = getOrCompileComplex(q.local, crec.node, crec.tns, crec.prefixes);
             return { tsType: t.name, declared: `{${t.ns}}${q.local}` };
         }
-        // fallback
+        // Unresolved type reference
+        if (options.failOnUnresolved) {
+            throw new WsdlCompilationError(`Unresolved type reference: "${q.local}" in namespace "${q.ns}".`, {
+                element: q.local,
+                namespace: q.ns,
+                suggestion: "Check that the XSD import for this namespace is included in the WSDL, or use --no-fail-on-unresolved to emit 'any'.",
+            });
+        }
         return { tsType: "any", declared: `{${q.ns}}${q.local}` };
     }
     function findComplexRec(q) {
@@ -565,6 +573,12 @@ export function compileCatalog(cat, options) {
     const tns = defs?.["@_targetNamespace"] || "";
     const bindingDefs = normalizeArray(defs?.["wsdl:binding"] || defs?.["binding"]);
     const soapBinding = bindingDefs.find(b => Object.keys(b).some(k => k === "soap:binding" || k === "soap12:binding")) || bindingDefs[0];
+    if (!soapBinding) {
+        throw new WsdlCompilationError("No SOAP binding found in the WSDL document.", {
+            file: cat.wsdlUri,
+            suggestion: "Ensure the WSDL defines a <wsdl:binding> element with a <soap:binding> or <soap12:binding> child.",
+        });
+    }
     // binding @type typically looks like "tns:MyPortType", so resolve via prefixes map
     const portTypeAttr = soapBinding?.["@_type"];
     const portTypeQName = portTypeAttr ? resolveQName(portTypeAttr, tns, cat.prefixMap) : undefined;

package/dist/gateway/generateGateway.d.ts

@@ -32,6 +32,7 @@ export interface GenerateGatewayOptions {
     emitPlugin?: boolean;
     emitRuntime?: boolean;
     stubHandlers?: boolean;
+    flattenArrayWrappers?: 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":"AA6CA;;;;;;;;;;;;;;;;;;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,CAsJjF"}
+{"version":3,"file":"generateGateway.d.ts","sourceRoot":"","sources":["../../src/gateway/generateGateway.ts"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;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;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJjF"}

package/dist/gateway/generateGateway.js

@@ -165,6 +165,8 @@ export async function generateGateway(opts) {
     });
     // Step 4: Emit schemas.ts module
     emitSchemasModule(outDir, modelsDir, versionSlug, serviceSlug);
+    // Determine whether to generate unwrap code for ArrayOf* wrappers
+    const shouldUnwrap = opts.flattenArrayWrappers !== false && catalog;
     // Step 5: Emit route files (with handlers or stubs)
     // Note: Route URLs come from OpenAPI paths which already include any base path
     if (stubHandlers) {
@@ -173,11 +175,11 @@ export async function generateGateway(opts) {
     }
     else {
         // Full handler mode: emit working implementations
-        emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta);
+        emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta, shouldUnwrap ? catalog : undefined);
     }
     // Step 6: Emit runtime.ts (if enabled)
     if (emitRuntime) {
-        emitRuntimeModule(outDir, versionSlug, serviceSlug);
+        emitRuntimeModule(outDir, versionSlug, serviceSlug, shouldUnwrap ? catalog : undefined);
     }
     // Step 7: Emit plugin.ts and type-check fixture (if enabled)
     if (emitPlugin) {

package/dist/gateway/generators.d.ts

@@ -103,20 +103,7 @@ 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;
+export declare function emitRuntimeModule(outDir: string, versionSlug: string, serviceSlug: string, catalog?: any): void;
 /**
  * Emits plugin.ts module as the primary Fastify plugin wrapper
  *
@@ -165,5 +152,5 @@ export declare function emitTypeCheckFixture(outDir: string, clientMeta: ClientM
  * @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;
+export declare function emitRouteFilesWithHandlers(outDir: string, routesDir: string, versionSlug: string, serviceSlug: string, operations: OperationMetadata[], importsMode: "js" | "ts" | "bare", clientMeta: ClientMeta, catalog?: any): 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":"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"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}

package/dist/gateway/generators.js

@@ -288,9 +288,88 @@ export function emitRouteFiles(outDir, routesDir, versionSlug, serviceSlug, oper
  * @param {string} versionSlug - Version slug for function naming
  * @param {string} serviceSlug - Service slug for function naming
  */
-export function emitRuntimeModule(outDir, versionSlug, serviceSlug) {
+/**
+ * Detects ArrayOf* wrapper types from catalog type metadata.
+ *
+ * An ArrayOf* wrapper has exactly one element with max "unbounded" (or > 1)
+ * and no attributes — mirroring the logic in generateSchemas.ts isArrayWrapper().
+ *
+ * @param catalog - Compiled catalog object
+ * @returns Record mapping wrapper type name to inner element property name
+ */
+function detectArrayWrappers(catalog) {
+    const wrappers = {};
+    for (const t of catalog.types || []) {
+        if (t.attrs && t.attrs.length !== 0)
+            continue;
+        if (!t.elems || t.elems.length !== 1)
+            continue;
+        const e = t.elems[0];
+        if (e.max !== "unbounded" && !(e.max > 1))
+            continue;
+        wrappers[t.name] = e.name;
+    }
+    return wrappers;
+}
+export function emitRuntimeModule(outDir, versionSlug, serviceSlug, catalog) {
     const vSlug = slugName(versionSlug);
     const sSlug = slugName(serviceSlug);
+    // Build unwrap maps from catalog if provided
+    let unwrapSection = "";
+    if (catalog) {
+        const arrayWrappers = detectArrayWrappers(catalog);
+        const childTypes = catalog.meta?.childType || {};
+        // Only emit if there are actual wrapper types to unwrap
+        if (Object.keys(arrayWrappers).length > 0) {
+            unwrapSection = `
+/**
+ * ArrayOf* wrapper type → inner element property name.
+ * These types are flattened to plain arrays in the OpenAPI schema,
+ * so the runtime must unwrap { InnerElement: [...] } → [...].
+ */
+const ARRAY_WRAPPERS: Record<string, string> = ${JSON.stringify(arrayWrappers, null, 2)};
+
+/**
+ * Type name → { propertyName: propertyTypeName } for recursive unwrapping.
+ */
+const CHILDREN_TYPES: Record<string, Record<string, string>> = ${JSON.stringify(childTypes, null, 2)};
+
+/**
+ * Recursively unwraps ArrayOf* wrapper objects in a SOAP response so the
+ * data matches the flattened OpenAPI array schemas.
+ *
+ * Safe to call on any response — returns data unchanged when the type
+ * has no wrapper fields.
+ *
+ * @param data - SOAP response data (potentially with wrapper objects)
+ * @param typeName - The type name for the current data level
+ * @returns Unwrapped data matching the OpenAPI schema shape
+ */
+export function unwrapArrayWrappers(data: unknown, typeName: string): unknown {
+  if (data == null || typeof data !== "object") return data;
+
+  // If this type is itself a wrapper, unwrap it
+  if (typeName in ARRAY_WRAPPERS) {
+    const innerKey = ARRAY_WRAPPERS[typeName];
+    return (data as Record<string, unknown>)[innerKey] ?? [];
+  }
+
+  // Recurse into children whose types may contain wrappers
+  if (typeName in CHILDREN_TYPES) {
+    const children = CHILDREN_TYPES[typeName];
+    for (const [propName, propType] of Object.entries(children)) {
+      const val = (data as Record<string, unknown>)[propName];
+      if (val !== undefined) {
+        (data as Record<string, unknown>)[propName] = unwrapArrayWrappers(val, propType);
+      }
+    }
+  }
+
+  return data;
+}
+`;
+        }
+    }
     const runtimeTs = `/**
  * Gateway Runtime Utilities
  *
@@ -388,7 +467,7 @@ export function classifyError(err: unknown): ClassifiedError {
       httpStatus: 400,
       code: "VALIDATION_ERROR",
       message: "Request validation failed",
-      details: (err as Record<string, unknown>).validation,
+      details: { validationErrors: (err as Record<string, unknown>).validation },
     };
   }
 
@@ -415,7 +494,7 @@ export function classifyError(err: unknown): ClassifiedError {
         httpStatus: 503,
         code: "SERVICE_UNAVAILABLE",
         message: "Unable to connect to SOAP service",
-        details: err.message,
+        details: { message: err.message },
       };
     }
     if (err.message.includes("ETIMEDOUT") || err.message.includes("timeout")) {
@@ -423,7 +502,7 @@ export function classifyError(err: unknown): ClassifiedError {
         httpStatus: 504,
         code: "GATEWAY_TIMEOUT",
         message: "SOAP service request timed out",
-        details: err.message,
+        details: { message: err.message },
       };
     }
   }
@@ -463,7 +542,7 @@ export function createGatewayErrorHandler_${vSlug}_${sSlug}() {
   };
 }
 `;
-    fs.writeFileSync(path.join(outDir, "runtime.ts"), runtimeTs, "utf8");
+    fs.writeFileSync(path.join(outDir, "runtime.ts"), runtimeTs + unwrapSection, "utf8");
 }
 /**
  * Emits plugin.ts module as the primary Fastify plugin wrapper
@@ -485,11 +564,6 @@ export function emitPluginModule(outDir, versionSlug, serviceSlug, clientMeta, i
     const vSlug = slugName(versionSlug);
     const sSlug = slugName(serviceSlug);
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
-    // Build named operations interface methods from operation metadata
-    const operationMethods = operations
-        .filter(op => op.clientMethodName)
-        .map(op => `  ${op.clientMethodName}(args: unknown): Promise<{ response: unknown; headers: unknown }>;`)
-        .join("\n");
     const pluginTs = `/**
  * ${clientMeta.className} Gateway Plugin
  *
@@ -499,10 +573,14 @@ export function emitPluginModule(outDir, versionSlug, serviceSlug, clientMeta, i
 import fp from "fastify-plugin";
 import type { FastifyInstance, FastifyPluginOptions } from "fastify";
 import type { ${clientMeta.className} } from "${clientMeta.pluginImportPath}";
+import type { ${clientMeta.className}Operations } from "${clientMeta.operationsImportPath}";
 import { registerSchemas_${vSlug}_${sSlug} } from "./schemas${suffix}";
 import { registerRoutes_${vSlug}_${sSlug} } from "./routes${suffix}";
 import { createGatewayErrorHandler_${vSlug}_${sSlug} } from "./runtime${suffix}";
 
+// Re-export the operations interface for convenience
+export type { ${clientMeta.className}Operations };
+
 /**
  * Options for the ${clientMeta.className} gateway plugin
  */
@@ -510,8 +588,9 @@ export interface ${clientMeta.className}GatewayOptions extends FastifyPluginOpti
   /**
    * SOAP client instance (pre-configured).
    * The client should be instantiated with appropriate source and security settings.
+   * Accepts the concrete client class or any implementation of ${clientMeta.className}Operations.
    */
-  client: ${clientMeta.className};
+  client: ${clientMeta.className}Operations;
   /**
    * Optional additional route prefix applied at runtime.
    * Note: If you used --openapi-base-path during generation, routes already have that prefix baked in.
@@ -520,21 +599,9 @@ export interface ${clientMeta.className}GatewayOptions extends FastifyPluginOpti
   prefix?: string;
 }
 
-/**
- * Convenience type listing all SOAP operations with \`args: unknown\` signatures.
- *
- * This interface is NOT used for the decorator type (which uses the concrete
- * client class for full type safety). It is exported as a lightweight alternative
- * for mocking or testing scenarios where importing the full client class is
- * undesirable.
- */
-export interface ${clientMeta.className}Operations {
-${operationMethods}
-}
-
 declare module "fastify" {
   interface FastifyInstance {
-    ${clientMeta.decoratorName}: ${clientMeta.className};
+    ${clientMeta.decoratorName}: ${clientMeta.className}Operations;
   }
 }
 
@@ -598,11 +665,19 @@ export function emitTypeCheckFixture(outDir, clientMeta, importsMode) {
  * Auto-generated. Not intended for runtime use.
  */
 import type { ${clientMeta.className} } from "${clientMeta.pluginImportPath}";
+import type { ${clientMeta.className}Operations } from "${clientMeta.operationsImportPath}";
 import type { ${clientMeta.className}GatewayOptions } from "./plugin${suffix}";
 
-// This function verifies structural compatibility at the type level.
-// If the plugin options interface diverges from the client class, this
-// will produce a compile error with a clear message.
+// Verify the concrete client class satisfies the operations interface.
+// If the client class diverges from the operations interface, this
+// will produce a compile error.
+function _assertClientSatisfiesOps(client: ${clientMeta.className}): ${clientMeta.className}Operations {
+  return client;
+}
+void _assertClientSatisfiesOps;
+
+// Verify the concrete client class is accepted by plugin options.
+// This ensures the gateway plugin can be used with the generated client.
 function _assertClientCompatible(client: ${clientMeta.className}): void {
   const _opts: ${clientMeta.className}GatewayOptions = { client };
   void _opts;
@@ -630,13 +705,15 @@ void _assertClientCompatible;
  * @param {"js"|"ts"|"bare"} importsMode - Import-extension mode
  * @param {ClientMeta} clientMeta - Client class metadata
  */
-export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta) {
+export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, serviceSlug, operations, importsMode, clientMeta, catalog) {
     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);
+    // Detect if unwrap code should be emitted
+    const hasUnwrap = catalog ? Object.keys(detectArrayWrappers(catalog)).length > 0 : false;
     let routesTs = `import type { FastifyInstance } from "fastify";\n`;
     operations.forEach((op) => {
         const fnName = `registerRoute_${vSlug}_${sSlug}_${op.operationSlug.replace(/[^a-zA-Z0-9_]/g, "_")}`;
@@ -661,6 +738,13 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
         const bodyArg = hasRequestType
             ? `request.body as ${reqTypeName}`
             : "request.body";
+        // Build the runtime import and return expression based on unwrap availability
+        const runtimeImport = hasUnwrap
+            ? `import { buildSuccessEnvelope, unwrapArrayWrappers } from "../runtime${suffix}";`
+            : `import { buildSuccessEnvelope } from "../runtime${suffix}";`;
+        const returnExpr = hasUnwrap
+            ? `return buildSuccessEnvelope(unwrapArrayWrappers(result.response, "${resTypeName}"));`
+            : `return buildSuccessEnvelope(result.response);`;
         // Note: op.path comes from OpenAPI and already includes any base path
         let routeTs = `/**
  * Route: ${op.method.toUpperCase()} ${op.path}
@@ -671,7 +755,7 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
  */
 import type { FastifyInstance } from "fastify";
 ${typeImport}import schema from "../schemas/operations/${op.operationSlug}.json" with { type: "json" };
-import { buildSuccessEnvelope } from "../runtime${suffix}";
+${runtimeImport}
 
 export async function ${fnName}(fastify: FastifyInstance) {
   fastify.route${routeGeneric}({
@@ -681,7 +765,7 @@ export async function ${fnName}(fastify: FastifyInstance) {
     handler: async (request) => {
       const client = fastify.${clientMeta.decoratorName};
       const result = await client.${clientMethod}(${bodyArg});
-      return buildSuccessEnvelope(result.response);
+      ${returnExpr}
     },
   });
 }

package/dist/gateway/helpers.d.ts

@@ -141,9 +141,10 @@ export declare function buildParamSchemasForOperation(pathItem: any, operation:
  * @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 — for future typed route handlers
- * @property {string} typesImportPath - Types import path relative to routes/ directory — for future typed route handlers
+ * @property {string} importPath - Import path relative to routes/ directory — for typed route handlers
+ * @property {string} typesImportPath - Types import path relative to routes/ directory — for typed route handlers
  * @property {string} pluginImportPath - Import path relative to gateway output directory — used by emitPluginModule()
+ * @property {string} operationsImportPath - Operations interface import path relative to gateway output directory
  */
 export interface ClientMeta {
     className: string;
@@ -151,6 +152,7 @@ export interface ClientMeta {
     importPath: string;
     typesImportPath: string;
     pluginImportPath: string;
+    operationsImportPath: string;
 }
 /**
  * Extended operation metadata for full handler generation

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

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

package/dist/gateway/helpers.js

@@ -390,12 +390,16 @@ export function resolveClientMeta(opts, catalog) {
     const pluginImportPath = opts.clientDir
         ? `../client/client${suffix}`
         : `./client/client${suffix}`;
+    const operationsImportPath = opts.clientDir
+        ? `../client/operations${suffix}`
+        : `./client/operations${suffix}`;
     return {
         className,
         decoratorName,
         importPath,
         typesImportPath,
         pluginImportPath,
+        operationsImportPath,
     };
 }
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAUjD,OAAO,EAAC,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAC,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAC,qBAAqB,EAAC,MAAM,eAAe,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,eAAe,CAAA;CAAE,GACjE,OAAO,CAAC,IAAI,CAAC,CAsDf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAWjD,OAAO,EAAC,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAC,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAC,qBAAqB,EAAC,MAAM,eAAe,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,eAAe,CAAA;CAAE,GACjE,OAAO,CAAC,IAAI,CAAC,CAwDf"}