@techspokes/typescript-wsdl-client 0.10.4 → 0.11.0

package/dist/loader/wsdlLoader.js

@@ -14,6 +14,7 @@ import { XMLParser } from "fast-xml-parser";
 import { fetchText } from "./fetch.js";
 import path from "node:path";
 import { getChildrenWithLocalName } from "../util/tools.js";
+import { WsdlCompilationError } from "../util/errors.js";
 // Configure XML parser to preserve attributes with @_ prefix
 const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
 /**
@@ -32,12 +33,37 @@ const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_
  */
 export async function loadWsdl(wsdlUrlOrPath) {
     // Fetch and parse the WSDL document
-    const { uri: wsdlUri, text } = await fetchText(wsdlUrlOrPath);
-    const wsdlXml = parser.parse(text);
+    let wsdlUri;
+    let text;
+    try {
+        const fetched = await fetchText(wsdlUrlOrPath);
+        wsdlUri = fetched.uri;
+        text = fetched.text;
+    }
+    catch (err) {
+        throw new WsdlCompilationError(`Failed to load WSDL document: ${err instanceof Error ? err.message : String(err)}`, {
+            file: wsdlUrlOrPath,
+            suggestion: "Verify the file path or URL is correct and accessible.",
+        });
+    }
+    let wsdlXml;
+    try {
+        wsdlXml = parser.parse(text);
+    }
+    catch (err) {
+        throw new WsdlCompilationError(`Failed to parse WSDL/XSD document as XML: ${err instanceof Error ? err.message : String(err)}`, {
+            file: wsdlUrlOrPath,
+            suggestion: "Validate the XML with an external tool (e.g., xmllint) and fix any syntax errors.",
+        });
+    }
     // Extract the WSDL definitions node (with or without namespace prefix)
     const defs = wsdlXml["wsdl:definitions"] || wsdlXml["definitions"];
-    if (!defs)
-        throw new Error("Not a WSDL 1.1 file: missing wsdl:definitions");
+    if (!defs) {
+        throw new WsdlCompilationError("Not a WSDL 1.1 file: missing <wsdl:definitions> root element.", {
+            file: wsdlUrlOrPath,
+            suggestion: "Ensure the file is a valid WSDL 1.1 document with a <definitions> root element.",
+        });
+    }
     // Extract namespace prefixes declared at the WSDL level
     const prefixMap = {};
     for (const [k, v] of Object.entries(defs)) {

package/dist/openapi/generateOpenAPI.d.ts

@@ -76,6 +76,7 @@ export interface GenerateOpenAPIOptions {
     skipValidate?: boolean;
     envelopeNamespace?: string;
     errorNamespace?: string;
+    flattenArrayWrappers?: boolean;
 }
 export declare function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
     doc: any;

package/dist/openapi/generateOpenAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAyRD"}
+{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CA0RD"}

package/dist/openapi/generateOpenAPI.js

@@ -80,6 +80,7 @@ export async function generateOpenAPI(opts) {
     const schemas = generateSchemas(compiled, {
         closedSchemas: opts.closedSchemas,
         pruneUnusedSchemas: opts.pruneUnusedSchemas,
+        flattenArrayWrappers: opts.flattenArrayWrappers,
     });
     // Build paths
     const tagStyle = opts.tagStyle || "default";

package/dist/openapi/generateSchemas.d.ts

@@ -24,6 +24,7 @@ import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
 export interface GenerateSchemasOptions {
     closedSchemas?: boolean;
     pruneUnusedSchemas?: boolean;
+    flattenArrayWrappers?: boolean;
 }
 export type ComponentsSchemas = Record<string, any>;
 /**

package/dist/openapi/generateSchemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/generateSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAwIpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CA8C1G"}
+{"version":3,"file":"generateSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/generateSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAwIpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CA+C1G"}

package/dist/openapi/generateSchemas.js

@@ -47,7 +47,7 @@ function isArrayWrapper(t) {
         return null;
     return { itemType: e.tsType };
 }
-function buildComplexSchema(t, closed, knownTypeNames, aliasNames) {
+function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappers) {
     // Use knownTypeNames/aliasNames to validate $ref targets so we surface
     // compiler issues early instead of emitting dangling references in OpenAPI output.
     function refOrPrimitive(ts) {
@@ -77,7 +77,7 @@ function buildComplexSchema(t, closed, knownTypeNames, aliasNames) {
                 return { $ref: `#/components/schemas/${ts}` };
         }
     }
-    const arrayWrap = isArrayWrapper(t);
+    const arrayWrap = flattenWrappers ? isArrayWrapper(t) : null;
     if (arrayWrap) {
         const item = refOrPrimitive(String(arrayWrap.itemType));
         return { type: "array", items: item };
@@ -148,6 +148,7 @@ function buildComplexSchema(t, closed, knownTypeNames, aliasNames) {
  */
 export function generateSchemas(compiled, opts) {
     const closed = !!opts.closedSchemas;
+    const flattenWrappers = opts.flattenArrayWrappers !== false; // default true
     const schemas = {};
     const typeNames = new Set(compiled.types.map(t => t.name));
     const aliasNames = new Set(compiled.aliases.map(a => a.name));
@@ -156,7 +157,7 @@ export function generateSchemas(compiled, opts) {
         schemas[a.name] = buildAliasSchema(a);
     }
     for (const t of compiled.types) {
-        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames);
+        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames, flattenWrappers);
     }
     if (opts.pruneUnusedSchemas) {
         // Root references: each operation's inputElement.local, outputElement.local

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAC,KAAK,eAAe,EAAyB,MAAM,aAAa,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1G,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;QACnC,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,GAAG,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC;CAAE,CAAC,CAuHhH"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,EAAC,KAAK,eAAe,EAAyB,MAAM,aAAa,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1G,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;QACnC,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,GAAG,CAAC;IAAC,UAAU,CAAC,EAAE,GAAG,CAAC;CAAE,CAAC,CA4HhH"}

package/dist/pipeline.js

@@ -13,6 +13,7 @@ import { compileCatalog } from "./compiler/schemaCompiler.js";
 import { generateClient } from "./client/generateClient.js";
 import { generateTypes } from "./client/generateTypes.js";
 import { generateUtils } from "./client/generateUtils.js";
+import { generateOperations } from "./client/generateOperations.js";
 import { generateCatalog } from "./compiler/generateCatalog.js";
 import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
 import { generateGateway } from "./gateway/generateGateway.js";
@@ -63,7 +64,7 @@ export async function runGenerationPipeline(opts) {
     success(`Compiled catalog written to ${opts.catalogOut}`);
     // Step 4: Optionally generate TypeScript client artifacts
     if (opts.clientOutDir) {
-        emitClientArtifacts(opts.clientOutDir, compiled, generateClient, generateTypes, generateUtils);
+        emitClientArtifacts(opts.clientOutDir, compiled, generateClient, generateTypes, generateUtils, generateOperations);
     }
     // Step 4: Optionally generate OpenAPI specification
     let openapiDoc;
@@ -99,6 +100,10 @@ export async function runGenerationPipeline(opts) {
             clientDir: opts.clientOutDir ? path.resolve(opts.clientOutDir) : undefined,
             // Reuse the same imports mode as the TypeScript client/types/utils emitters
             imports: finalCompiler.imports,
+            // Pass catalog for runtime unwrap generation
+            catalogFile: path.resolve(opts.catalogOut),
+            // Thread flatten flag from OpenAPI options
+            flattenArrayWrappers: opts.openapi?.flattenArrayWrappers,
         });
         success(`Gateway code generated in ${gatewayOutDir}`);
     }

package/dist/util/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/util/builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,+BAA+B,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBhF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,EAAE,GAChB,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC,CAoBtF"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/util/builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,+BAA+B,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBhF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,EAAE,GAChB,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC,CAqBtF"}

package/dist/util/builder.js

@@ -47,6 +47,7 @@ export function buildOpenApiOptionsFromArgv(argv, format, servers) {
         tagsFile: argv["openapi-tags-file"],
         title: argv["openapi-title"],
         version: argv["openapi-version-tag"],
+        flattenArrayWrappers: argv["openapi-flatten-array-wrappers"],
         asYaml: format === "yaml",
     };
 }

package/dist/util/cli.d.ts

@@ -81,7 +81,7 @@ export declare function reportCompilationStats(wsdlCatalog: {
     operations: any[];
 }): void;
 /**
- * Emit TypeScript client artifacts (client.ts, types.ts, utils.ts)
+ * Emit TypeScript client artifacts (client.ts, types.ts, utils.ts, operations.ts)
  *
  * Note: catalog.json is NOT emitted by this function - it should be handled
  * separately by the caller using generateCatalog() with explicit --catalog-file path.
@@ -91,8 +91,9 @@ export declare function reportCompilationStats(wsdlCatalog: {
  * @param generateClient - Client generator function
  * @param generateTypes - Types generator function
  * @param generateUtils - Utils generator function
+ * @param generateOperations - Operations interface generator function
  */
-export declare function emitClientArtifacts(outDir: string, compiled: any, generateClient: (path: string, compiled: any) => void, generateTypes: (path: string, compiled: any) => void, generateUtils: (path: string, compiled: any) => void): void;
+export declare function emitClientArtifacts(outDir: string, compiled: any, generateClient: (path: string, compiled: any) => void, generateTypes: (path: string, compiled: any) => void, generateUtils: (path: string, compiled: any) => void, generateOperations?: (path: string, compiled: any) => void): void;
 /**
  * Validate gateway generation requirements
  *

package/dist/util/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/util/cli.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMhE;AAED;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,KAAK,CAI7E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CASP;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE;IAAE,OAAO,EAAE,GAAG,EAAE,CAAA;CAAE,EAC/B,QAAQ,EAAE;IAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAAC,UAAU,EAAE,GAAG,EAAE,CAAA;CAAE,GAC5C,IAAI,CAIN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,EACb,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EACrD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EACpD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,GACnD,IAAI,CASN;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,IAAI,CAUN"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/util/cli.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMhE;AAED;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,KAAK,CAQ7E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CASP;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE;IAAE,OAAO,EAAE,GAAG,EAAE,CAAA;CAAE,EAC/B,QAAQ,EAAE;IAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAAC,UAAU,EAAE,GAAG,EAAE,CAAA;CAAE,GAC5C,IAAI,CAIN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,EACb,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EACrD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EACpD,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,EACpD,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,IAAI,GACzD,IAAI,CAWN;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACvC,IAAI,CAUN"}

package/dist/util/cli.js

@@ -7,6 +7,7 @@
  */
 import path from "node:path";
 import fs from "node:fs";
+import { WsdlCompilationError } from "./errors.js";
 /**
  * Parse comma-separated status codes from CLI argument
  *
@@ -94,8 +95,13 @@ export function info(message) {
  * @param exitCode - Process exit code (default: 1)
  */
 export function handleCLIError(errorObj, exitCode = 1) {
-    const message = errorObj instanceof Error ? errorObj.message : String(errorObj);
-    error(message);
+    if (errorObj instanceof WsdlCompilationError) {
+        error(errorObj.toUserMessage());
+    }
+    else {
+        const message = errorObj instanceof Error ? errorObj.message : String(errorObj);
+        error(message);
+    }
     process.exit(exitCode);
 }
 /**
@@ -125,7 +131,7 @@ export function reportCompilationStats(wsdlCatalog, compiled) {
     info(`Operations: ${compiled.operations.length}`);
 }
 /**
- * Emit TypeScript client artifacts (client.ts, types.ts, utils.ts)
+ * Emit TypeScript client artifacts (client.ts, types.ts, utils.ts, operations.ts)
  *
  * Note: catalog.json is NOT emitted by this function - it should be handled
  * separately by the caller using generateCatalog() with explicit --catalog-file path.
@@ -135,12 +141,16 @@ export function reportCompilationStats(wsdlCatalog, compiled) {
  * @param generateClient - Client generator function
  * @param generateTypes - Types generator function
  * @param generateUtils - Utils generator function
+ * @param generateOperations - Operations interface generator function
  */
-export function emitClientArtifacts(outDir, compiled, generateClient, generateTypes, generateUtils) {
+export function emitClientArtifacts(outDir, compiled, generateClient, generateTypes, generateUtils, generateOperations) {
     fs.mkdirSync(outDir, { recursive: true });
     generateClient(path.join(outDir, "client.ts"), compiled);
     generateTypes(path.join(outDir, "types.ts"), compiled);
     generateUtils(path.join(outDir, "utils.ts"), compiled);
+    if (generateOperations) {
+        generateOperations(path.join(outDir, "operations.ts"), compiled);
+    }
     success(`Generated TypeScript client in ${outDir}`);
 }
 /**

package/dist/util/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Structured error types for WSDL compilation
+ *
+ * Provides context-rich error messages with element names, namespaces,
+ * and actionable suggestions for common issues.
+ */
+/**
+ * Context information attached to WSDL compilation errors
+ */
+export interface WsdlErrorContext {
+    /** Element or type name that triggered the error */
+    element?: string;
+    /** XML namespace where the error occurred */
+    namespace?: string;
+    /** File or URI of the source document */
+    file?: string;
+    /** Referenced-by context (e.g., "element 'bar' in type 'Baz'") */
+    referencedBy?: string;
+    /** Actionable suggestion for resolving the error */
+    suggestion?: string;
+}
+/**
+ * Structured error for WSDL/XSD compilation failures.
+ *
+ * Extends Error with context fields for element, namespace, file, and suggestion.
+ * The CLI error handler formats these into multi-line user-friendly messages.
+ */
+export declare class WsdlCompilationError extends Error {
+    readonly context: WsdlErrorContext;
+    readonly name = "WsdlCompilationError";
+    constructor(message: string, context?: WsdlErrorContext);
+    /**
+     * Formats the error into a user-friendly multi-line message.
+     */
+    toUserMessage(): string;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/util/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAK3B,OAAO,EAAE,gBAAgB;IAJ3C,SAAkB,IAAI,0BAA0B;gBAG9C,OAAO,EAAE,MAAM,EACC,OAAO,GAAE,gBAAqB;IAKhD;;OAEG;IACH,aAAa,IAAI,MAAM;CASxB"}

package/dist/util/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Structured error types for WSDL compilation
+ *
+ * Provides context-rich error messages with element names, namespaces,
+ * and actionable suggestions for common issues.
+ */
+/**
+ * Structured error for WSDL/XSD compilation failures.
+ *
+ * Extends Error with context fields for element, namespace, file, and suggestion.
+ * The CLI error handler formats these into multi-line user-friendly messages.
+ */
+export class WsdlCompilationError extends Error {
+    context;
+    name = "WsdlCompilationError";
+    constructor(message, context = {}) {
+        super(message);
+        this.context = context;
+    }
+    /**
+     * Formats the error into a user-friendly multi-line message.
+     */
+    toUserMessage() {
+        const parts = [this.message];
+        if (this.context.element)
+            parts.push(`  Element: ${this.context.element}`);
+        if (this.context.namespace)
+            parts.push(`  Namespace: ${this.context.namespace}`);
+        if (this.context.referencedBy)
+            parts.push(`  Referenced by: ${this.context.referencedBy}`);
+        if (this.context.file)
+            parts.push(`  File: ${this.context.file}`);
+        if (this.context.suggestion)
+            parts.push(`  Suggestion: ${this.context.suggestion}`);
+        return parts.join("\n");
+    }
+}

package/docs/README.md

@@ -13,6 +13,7 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [generated-code.md](generated-code.md) – Using clients and types
 - [migration.md](migration.md) – Upgrade paths between versions
 - [production.md](production.md) – CI/CD, validation, logging, limitations
+- [testing.md](testing.md) – Testing patterns and mock client examples
 - [troubleshooting.md](troubleshooting.md) – Common issues and debugging
 
 ## Conventions

package/docs/cli-reference.md

@@ -87,6 +87,7 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--openapi-method` | `post` | Default HTTP method |
 | `--openapi-tag-style` | `default` | Tag inference: default, service, or first |
 | `--openapi-closed-schemas` | `false` | Add additionalProperties: false |
+| `--openapi-flatten-array-wrappers` | `true` | Flatten ArrayOf* wrappers to plain arrays; emit runtime unwrap in gateway |
 | `--openapi-prune-unused-schemas` | `false` | Emit only referenced schemas |
 | `--openapi-envelope-namespace` | `ResponseEnvelope` | Envelope component name suffix |
 | `--openapi-error-namespace` | `ErrorObject` | Error object name suffix |
@@ -107,6 +108,7 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--gateway-decorator-name` | {serviceSlug}Client | Fastify decorator name |
 | `--gateway-skip-plugin` | `false` | Skip plugin.ts generation |
 | `--gateway-skip-runtime` | `false` | Skip runtime.ts generation |
+| `--openapi-flatten-array-wrappers` | `true` | Generate runtime unwrap for ArrayOf* wrapper types |
 
 ### App Scaffold Flags
 

package/docs/concepts.md

@@ -163,7 +163,8 @@ interface MyType {
 ## Array Wrapper Flattening
 
 A complex type whose only child is a single repeated element with no attributes
-collapses to an array schema in OpenAPI.
+collapses to an array schema in OpenAPI. Controlled by
+`--openapi-flatten-array-wrappers` (default `true`).
 
 ```xml
 <xs:complexType name="ArrayOfForecast">
@@ -173,7 +174,7 @@ collapses to an array schema in OpenAPI.
 </xs:complexType>
 ```
 
-The resulting OpenAPI schema:
+With flattening enabled (default), the OpenAPI schema becomes a plain array:
 
 ```json
 {
@@ -184,6 +185,32 @@ The resulting OpenAPI schema:
 }
 ```
 
+The TypeScript types preserve the wrapper structure:
+
+```typescript
+export interface ArrayOfForecast {
+  Forecast?: Forecast[];
+}
+```
+
+### Runtime Unwrap
+
+Because the SOAP client returns wrapper-shaped objects (`{ Forecast: [...] }`)
+while the OpenAPI schema expects flat arrays, the generated gateway includes an
+`unwrapArrayWrappers()` function in `runtime.ts`. Route handlers call it
+automatically before serialization. This bridges the TS-type/schema gap without
+requiring consumers to transform responses manually.
+
+### Disabling Flattening
+
+Pass `--openapi-flatten-array-wrappers false` to preserve the wrapper object
+structure in OpenAPI schemas. When disabled:
+
+- ArrayOf* types emit as `type: "object"` with their inner element as a property
+- No `unwrapArrayWrappers()` function is generated in `runtime.ts`
+- Route handlers pass SOAP responses through unmodified
+- The OpenAPI schema matches the TypeScript types exactly
+
 ## Inheritance Flattening
 
 Three XSD inheritance patterns are supported.

package/docs/generated-code.md

@@ -104,3 +104,27 @@ Key features of the generated handlers:
 - **Envelope wrapping** — `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
 
 See [Gateway Guide](gateway-guide.md) for the full architecture and [CLI Reference](cli-reference.md) for generation flags.
+
+## Operations Interface
+
+The generated `operations.ts` exports a typed interface (`{ServiceName}Operations`) that mirrors the concrete client class methods. Use it for dependency injection and testing:
+
+```typescript
+import type { WeatherOperations } from "./client/operations.js";
+
+const mock: WeatherOperations = {
+  GetCityWeatherByZIP: async (args) => ({
+    response: { GetCityWeatherByZIPResult: { Success: true } },
+    headers: {},
+  }),
+  // ...other operations
+};
+```
+
+The gateway plugin accepts any `WeatherOperations` implementation, so you can pass the mock directly:
+
+```typescript
+app.register(weatherGateway, { client: mock });
+```
+
+See [Testing Guide](testing.md) for full integration test patterns.

package/docs/testing.md

@@ -0,0 +1,193 @@
+# Testing Guide
+
+Guide to running and writing tests for wsdl-tsc development and for testing generated code in consumer projects.
+
+See [README](../README.md) for quick start and [CONTRIBUTING](../CONTRIBUTING.md) for development setup.
+
+## Test Architecture
+
+The project uses three layers of testing:
+
+1. **Unit tests** — Pure function tests for utilities, parsers, and type mapping
+2. **Snapshot tests** — Baseline comparisons for all generated pipeline output
+3. **Integration tests** — End-to-end gateway tests using Fastify's `inject()` with mock clients
+
+All tests use [Vitest](https://vitest.dev/) and run in under 3 seconds.
+
+## Running Tests
+
+```bash
+npm test              # All Vitest tests
+npm run test:unit     # Unit tests only
+npm run test:snap     # Snapshot tests only
+npm run test:integration  # Integration tests only
+npm run test:watch    # Watch mode for development
+```
+
+For the full CI pipeline including smoke tests:
+
+```bash
+npm run ci
+```
+
+## Unit Tests
+
+Unit tests cover pure functions with no I/O or side effects:
+
+- **`tools.test.ts`** — `pascal()`, `resolveQName()`, `explodePascal()`, `pascalToSnakeCase()`, `normalizeArray()`, `getChildrenWithLocalName()`, `getFirstWithLocalName()`
+- **`casing.test.ts`** — `toPathSegment()` with kebab, asis, and lower styles
+- **`primitives.test.ts`** — `xsdToTsPrimitive()` covering all XSD types (string-like, boolean, integers, decimals, floats, dates, any)
+- **`errors.test.ts`** — `WsdlCompilationError` construction and `toUserMessage()` formatting
+- **`schema-alignment.test.ts`** — Cross-validates TypeScript types, JSON schemas, and catalog.json for consistency
+
+### Writing Unit Tests
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { pascal } from "../../src/util/tools.js";
+
+describe("pascal", () => {
+  it("converts kebab-case", () => {
+    expect(pascal("get-weather")).toBe("GetWeather");
+  });
+});
+```
+
+## Snapshot Tests
+
+Snapshot tests capture the complete output of the pipeline as baselines. When a generator change intentionally alters output, the snapshot diff shows exactly what changed.
+
+### How It Works
+
+1. The pipeline runs against `examples/minimal/weather.wsdl` into a temp directory
+2. Each generated file is read and compared against the stored snapshot
+3. A file inventory snapshot detects added or removed files
+
+### Updating Snapshots
+
+```bash
+npx vitest run test/snapshot -u
+```
+
+Always review the diff before committing updated snapshots.
+
+### What's Covered
+
+- Client output: `client.ts`, `types.ts`, `utils.ts`, `operations.ts`, `catalog.json`
+- OpenAPI: `openapi.json`
+- Gateway core: `plugin.ts`, `routes.ts`, `schemas.ts`, `runtime.ts`, `_typecheck.ts`
+- Gateway routes: one handler per WSDL operation
+- Gateway schemas: all model and operation JSON schema files
+- File inventory: complete listing of generated files
+
+## Integration Tests
+
+Integration tests verify the generated gateway works end-to-end by:
+
+1. Running the pipeline in `beforeAll` to generate gateway code
+2. Dynamically importing the generated plugin
+3. Creating a Fastify instance with the plugin and a mock client
+4. Using `fastify.inject()` to send HTTP requests and verify responses
+
+### Mock Client Pattern
+
+The generated `operations.ts` provides a typed interface for creating test doubles:
+
+```typescript
+import type { WeatherOperations } from "../client/operations.js";
+
+function createMockClient(): WeatherOperations {
+  return {
+    GetCityWeatherByZIP: async (args) => ({
+      response: {
+        GetCityWeatherByZIPResult: {
+          Success: true,
+          ResponseText: "City Found",
+          State: "NY",
+          City: "New York",
+          Temperature: "72",
+        },
+      },
+      headers: {},
+    }),
+    GetCityForecastByZIP: async (args) => ({
+      response: {
+        GetCityForecastByZIPResult: {
+          Success: true,
+          ResponseText: "Forecast Found",
+          // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+          ForecastResult: { Forecast: [] },
+        },
+      },
+      headers: {},
+    }),
+    GetWeatherInformation: async (args) => ({
+      response: {
+        // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+        GetWeatherInformationResult: { WeatherDescription: [] },
+      },
+      headers: {},
+    }),
+  };
+}
+```
+
+Each method returns the same `{ response, headers }` shape as the real SOAP client. Use the wrapper object structure matching TypeScript types — the generated `unwrapArrayWrappers()` function handles conversion to the flat array shape expected by JSON schemas.
+
+### Using the Mock with Fastify
+
+```typescript
+import Fastify from "fastify";
+
+const app = Fastify();
+await app.register(weatherGateway, {
+  client: createMockClient(),
+  prefix: "/v1/weather",
+});
+await app.ready();
+
+const res = await app.inject({
+  method: "POST",
+  url: "/v1/weather/get-city-weather-by-zip",
+  payload: { ZIP: "10001" },
+});
+
+expect(res.statusCode).toBe(200);
+expect(res.json().status).toBe("SUCCESS");
+```
+
+### Dynamic Import of Generated Code
+
+Integration tests dynamically import generated `.ts` files from temp directories. This works because Vitest's Vite module resolution handles TypeScript imports, JSON import attributes, and bare specifiers from the project's `node_modules`:
+
+```typescript
+import { pathToFileURL } from "node:url";
+
+const pluginModule = await import(pathToFileURL(join(outDir, "gateway", "plugin.ts")).href);
+```
+
+## Known Issues
+
+### ArrayOf* Schema-Type Mismatch (Resolved)
+
+JSON schemas flatten SOAP `ArrayOf*` wrapper types to plain `type: "array"` (when `--openapi-flatten-array-wrappers` is `true`, the default), while TypeScript types preserve the wrapper structure (e.g., `ArrayOfForecast = { Forecast?: Forecast[] }`).
+
+This mismatch is resolved by the generated `unwrapArrayWrappers()` function in `runtime.ts`. Route handlers call it automatically to strip wrapper objects before Fastify serialization. Mock clients should return the real SOAP wrapper structure — the unwrap function handles the conversion.
+
+When `--openapi-flatten-array-wrappers false` is used, ArrayOf* types are emitted as `type: "object"` and no unwrap function is generated. In this mode, mock data should use the wrapper object shape matching both the TypeScript types and the JSON schemas.
+
+### Error Details Serialization
+
+The `classifyError()` function puts `err.message` (a string) in the `details` field for connection and timeout errors, but the error JSON schema defines `details` as `object | null`. This causes Fastify serialization failures for 503/504 error responses. Test error classification directly via `classifyError()` rather than through Fastify's `inject()` for these error types.
+
+## For Consumer Projects
+
+If you're using wsdl-tsc as a dependency and want to test your integration:
+
+1. Generate code with `npx wsdl-tsc pipeline`
+2. Import the operations interface from `operations.ts`
+3. Create a mock client implementing the interface
+4. Register the generated gateway plugin with your mock client
+5. Use Fastify's `inject()` to test routes without a running server
+
+The operations interface is the recommended seam for dependency injection and testing. It's a pure TypeScript interface with no runtime dependencies on the `soap` package.