@techspokes/typescript-wsdl-client 0.6.3 → 0.7.1

package/dist/openapi/generateOpenAPI.js

@@ -0,0 +1,315 @@
+/**
+ * OpenAPI 3.1 Generator from WSDL
+ *
+ * This module generates OpenAPI 3.1 specifications from WSDL documents or compiled catalogs.
+ * It bridges the gap between SOAP web services and REST APIs by creating an OpenAPI
+ * representation that mirrors the TypeScript model generated by the WSDL client generator.
+ *
+ * Core capabilities:
+ * - Multiple input sources (WSDL URL/path, pre-compiled catalog, or in-memory catalog)
+ * - Deterministic schema + path emission mirroring generated TypeScript
+ * - Security scheme + header parameter integration (via security.json)
+ * - Operation tagging heuristics + explicit tag + op override files
+ * - Multi-format output (json|yaml|both) with optional validation
+ * - Always-on Standard Response Envelope (since 0.7.1): automatically wraps all
+ *   responses in a base envelope plus per-payload extensions, providing stable
+ *   top-level fields (status, message, data, error). Naming is customizable via
+ *   --envelope-namespace / --error-namespace.
+ *
+ * Naming Rules:
+ *   - If a namespace flag is provided its value is used verbatim as the component name.
+ *   - Otherwise `${serviceName}ResponseEnvelope` / `${serviceName}ErrorObject` are used.
+ *   - Each operation output produces an extension schema named `<PayloadType|OpName><EnvelopeNamespace>`.
+ *   - All schemas, paths, methods, securitySchemes, and parameters are alphabetically sorted for diff friendliness.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { loadWsdl } from "../loader/wsdlLoader.js";
+import { compileCatalog } from "../compiler/schemaCompiler.js";
+import { buildSchemas } from "./buildSchemas.js";
+import { buildPaths } from "./buildPaths.js";
+import { buildSecurity, loadSecurityConfig } from "./security.js";
+export async function generateOpenAPI(opts) {
+    // Normalize format (back-compat: asYaml overrides if provided and format not set)
+    let format = opts.format || (opts.asYaml ? "yaml" : "json");
+    if (format === "yaml" && opts.asYaml && opts.outFile && /\.json$/i.test(opts.outFile)) {
+        // user asked for yaml but provided .json path → we'll still switch extension
+    }
+    if (!opts.compiledCatalog && !opts.wsdl && !opts.catalogFile) {
+        throw new Error("Provide one of: compiledCatalog, wsdl, or catalogFile");
+    }
+    if ((opts.wsdl && opts.catalogFile) || (opts.compiledCatalog && (opts.wsdl || opts.catalogFile))) {
+        // Not strictly an error, but disallow ambiguous multi-source inputs to keep deterministic
+        // Users should supply only ONE source of truth.
+        throw new Error("Provide only one source: compiledCatalog OR wsdl OR catalogFile");
+    }
+    let compiled;
+    if (opts.compiledCatalog) {
+        compiled = opts.compiledCatalog;
+    }
+    else if (opts.catalogFile) {
+        const raw = fs.readFileSync(opts.catalogFile, "utf8");
+        compiled = JSON.parse(raw);
+    }
+    else {
+        const wsdlCatalog = await loadWsdl(String(opts.wsdl));
+        compiled = compileCatalog(wsdlCatalog, {
+            // minimal compiler options (no generation side effects needed here)
+            wsdl: String(opts.wsdl),
+            out: "",
+            imports: "js",
+            catalog: false,
+            primitive: { int64As: "string", bigIntegerAs: "string", decimalAs: "string", dateAs: "string" },
+            choice: "all-optional",
+            failOnUnresolved: false,
+            attributesKey: "$attributes",
+            nillableAsOptional: false,
+            clientName: undefined,
+        });
+    }
+    const title = opts.title || (compiled.serviceName ? `${compiled.serviceName} SOAP API` : "Generated SOAP API");
+    const infoVersion = opts.version || "0.0.0";
+    // Load external config files (optional)
+    const tagsMap = opts.tagsFile ? safeJson(opts.tagsFile) : undefined;
+    const opsOverrides = opts.opsFile ? safeJson(opts.opsFile) : undefined;
+    const securityCfg = loadSecurityConfig(opts.securityConfigFile);
+    const securityBuilt = buildSecurity(securityCfg);
+    // Build components.schemas
+    const schemas = buildSchemas(compiled, {
+        closedSchemas: opts.closedSchemas,
+        pruneUnusedSchemas: opts.pruneUnusedSchemas,
+    });
+    // Build paths
+    const tagStyle = opts.tagStyle || "default";
+    const defaultTag = (() => {
+        if (tagStyle === "service")
+            return compiled.serviceName || "SOAP";
+        if (tagStyle === "first")
+            return "General"; // fallback; per-op derivation below
+        return compiled.serviceName || "SOAP";
+    })();
+    const paths = buildPaths(compiled, {
+        basePath: opts.basePath || "/",
+        pathStyle: opts.pathStyle || "kebab",
+        defaultMethod: opts.defaultMethod || "post",
+        tagsMap,
+        overrides: opsOverrides,
+        defaultTag,
+        opSecurity: securityBuilt.opSecurity,
+        opHeaderParameters: securityBuilt.opHeaderParameters,
+    });
+    // --- Standard Envelope (always enabled since 0.7.1) ---
+    const serviceName = compiled.serviceName || "Service";
+    const envelopeNamespace = opts.envelopeNamespace || "ResponseEnvelope";
+    const errorNamespace = opts.errorNamespace || "ErrorObject";
+    function leadingToken(ns) {
+        return ns.match(/^[A-Z][a-z0-9]*/)?.[0] || ns;
+    }
+    function joinWithNamespace(base, ns) {
+        const token = leadingToken(ns);
+        return base.endsWith(token) ? `${base}_${ns}` : `${base}${ns}`;
+    }
+    const baseEnvelopeName = opts.envelopeNamespace
+        ? envelopeNamespace
+        : joinWithNamespace(serviceName, envelopeNamespace);
+    const errorSchemaName = opts.errorNamespace
+        ? errorNamespace
+        : joinWithNamespace(serviceName, errorNamespace);
+    const errorSchema = {
+        type: "object",
+        properties: {
+            code: { type: "string" },
+            message: { type: "string" },
+            details: { anyOf: [{ type: "object", additionalProperties: true }, { type: "null" }] },
+        },
+        required: ["code", "message"],
+        additionalProperties: false,
+        description: "Standard error object for REST responses (not reused for underlying SOAP faults).",
+    };
+    const baseEnvelopeSchema = {
+        type: "object",
+        properties: {
+            status: { type: "string", description: "Machine-readable high-level status (e.g. SUCCESS, FAILURE, PENDING)." },
+            message: {
+                anyOf: [{ type: "string" }, { type: "null" }],
+                description: "Diagnostic/logging message (not for end-user display)."
+            },
+            data: { anyOf: [{}, { type: "null" }], description: "Primary payload; per-operation extension refines the shape." },
+            error: {
+                anyOf: [{ $ref: `#/components/schemas/${errorSchemaName}` }, { type: "null" }],
+                description: "Error details when status indicates failure; null otherwise."
+            },
+        },
+        required: ["status", "data", "error", "message"],
+        additionalProperties: true,
+        description: "Standard API response envelope base schema.",
+    };
+    const extensionSchemas = {};
+    for (const op of compiled.operations) {
+        const payloadType = op.outputElement?.local;
+        const payloadRef = payloadType && schemas[payloadType] ? { $ref: `#/components/schemas/${payloadType}` } : { type: "object" };
+        const baseForExt = payloadType || op.name;
+        const extName = joinWithNamespace(baseForExt, envelopeNamespace);
+        if (extensionSchemas[extName])
+            continue; // de-dupe
+        extensionSchemas[extName] = {
+            allOf: [
+                { $ref: `#/components/schemas/${baseEnvelopeName}` },
+                { type: "object", properties: { data: { anyOf: [payloadRef, { type: "null" }] } }, additionalProperties: true }
+            ],
+            description: `Envelope for ${payloadType || op.name} operation output wrapping its payload in 'data'.`
+        };
+    }
+    // Merge all schemas: add base + extensions + error then original schemas, then final alphabetical sort of all keys
+    const mergedSchemas = {
+        [baseEnvelopeName]: baseEnvelopeSchema,
+        ...extensionSchemas,
+        [errorSchemaName]: errorSchema,
+        ...schemas,
+    };
+    const sortedSchemaKeys = Object.keys(mergedSchemas).sort((a, b) => a.localeCompare(b));
+    const finalSchemas = {};
+    for (const k of sortedSchemaKeys)
+        finalSchemas[k] = mergedSchemas[k];
+    // Update paths response schemas to reference extension envelopes
+    for (const pathItem of Object.values(paths)) {
+        for (const methodObj of Object.values(pathItem)) {
+            const opId = methodObj.operationId;
+            if (!opId)
+                continue;
+            const op = compiled.operations.find(o => o.name === opId);
+            if (!op)
+                continue;
+            const payloadType = op.outputElement?.local;
+            const baseForExt = payloadType || op.name;
+            const extName = joinWithNamespace(baseForExt, envelopeNamespace);
+            if (methodObj.responses?.["200"]) {
+                methodObj.responses["200"].description = "Successful operation (standard envelope)";
+                methodObj.responses["200"].content = { "application/json": { schema: { $ref: `#/components/schemas/${extName}` } } };
+            }
+            if (methodObj.responses?.default) {
+                methodObj.responses.default.description = "Error response (standard envelope with populated error object)";
+                methodObj.responses.default.content = { "application/json": { schema: { $ref: `#/components/schemas/${baseEnvelopeName}` } } };
+            }
+        }
+    }
+    // --- End Standard Envelope ---
+    // Sort paths and methods alphabetically for diff-friendly output
+    const sortedPathKeys = Object.keys(paths).sort((a, b) => a.localeCompare(b));
+    const sortedPaths = {};
+    for (const p of sortedPathKeys) {
+        const ops = paths[p];
+        const methodKeys = Object.keys(ops).sort((a, b) => a.localeCompare(b));
+        const sortedOps = {};
+        for (const m of methodKeys)
+            sortedOps[m] = ops[m];
+        sortedPaths[p] = sortedOps;
+    }
+    // Sort securitySchemes & parameters if present
+    let sortedSecuritySchemes;
+    if (securityBuilt.securitySchemes) {
+        sortedSecuritySchemes = {};
+        for (const k of Object.keys(securityBuilt.securitySchemes).sort((a, b) => a.localeCompare(b))) {
+            sortedSecuritySchemes[k] = securityBuilt.securitySchemes[k];
+        }
+    }
+    let sortedParameters;
+    if (Object.keys(securityBuilt.headerParameters).length) {
+        sortedParameters = {};
+        for (const k of Object.keys(securityBuilt.headerParameters).sort((a, b) => a.localeCompare(b))) {
+            sortedParameters[k] = securityBuilt.headerParameters[k];
+        }
+    }
+    // Ensure operation tags arrays are deterministic (alphabetical unique) for diff-friendly output
+    for (const p of Object.keys(sortedPaths)) {
+        const pathItem = sortedPaths[p];
+        for (const m of Object.keys(pathItem)) {
+            const op = pathItem[m];
+            if (Array.isArray(op.tags)) {
+                const tags = Array.from(new Set(op.tags)).map(t => String(t));
+                tags.sort((a, b) => a.localeCompare(b));
+                op.tags = tags;
+            }
+        }
+    }
+    // Build components object then sort its top-level keys for stable ordering
+    const componentsRaw = {
+        schemas: finalSchemas,
+        ...(sortedSecuritySchemes ? { securitySchemes: sortedSecuritySchemes } : {}),
+        ...(sortedParameters ? { parameters: sortedParameters } : {}),
+    };
+    const componentKeyOrder = Object.keys(componentsRaw).sort((a, b) => a.localeCompare(b));
+    const components = {};
+    for (const k of componentKeyOrder)
+        components[k] = componentsRaw[k];
+    const doc = {
+        openapi: "3.1.0",
+        // NOTE: jsonSchemaDialect intentionally omitted unless a future flag requires non-default dialect.
+        info: { title, version: infoVersion },
+        paths: sortedPaths,
+        components,
+    };
+    if (opts.description)
+        doc.info.description = opts.description;
+    if (opts.servers && opts.servers.length) {
+        doc.servers = opts.servers.map(u => ({ url: u }));
+    }
+    else {
+        // Provide a deterministic default relative server for spec completeness & gateway friendliness.
+        doc.servers = [{ url: "/" }];
+    }
+    if (opts.skipValidate !== true) {
+        try {
+            const parser = await import("@apidevtools/swagger-parser");
+            await parser.default.validate(JSON.parse(JSON.stringify(doc)));
+            console.log("OpenAPI validation: OK");
+        }
+        catch (e) {
+            console.error("OpenAPI validation failed:", e instanceof Error ? e.message : e);
+            throw e;
+        }
+    }
+    else {
+        console.log("OpenAPI validation skipped by flag");
+    }
+    // Determine base path for writing
+    let base = opts.outFile;
+    if (base) {
+        const extMatch = base.match(/\.(json|ya?ml)$/i);
+        if (extMatch) {
+            base = base.slice(0, -extMatch[0].length); // strip extension
+        }
+    }
+    let jsonPath;
+    let yamlPath;
+    if (opts.outFile) {
+        const dir = path.dirname(opts.outFile);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        if (format === "json") {
+            jsonPath = base ? `${base}.json` : opts.outFile;
+            fs.writeFileSync(jsonPath, JSON.stringify(doc, null, 2), "utf8");
+        }
+        else if (format === "yaml") {
+            yamlPath = base ? `${base}.yaml` : opts.outFile.replace(/\.(json)$/i, ".yaml");
+            fs.writeFileSync(yamlPath, yaml.dump(doc), "utf8");
+        }
+        else { // both
+            jsonPath = `${base}.json`;
+            yamlPath = `${base}.yaml`;
+            fs.writeFileSync(jsonPath, JSON.stringify(doc, null, 2), "utf8");
+            fs.writeFileSync(yamlPath, yaml.dump(doc), "utf8");
+        }
+    }
+    return { doc, jsonPath, yamlPath };
+}
+function safeJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        console.warn(`⚠️ Failed to parse JSON file '${file}': ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+}

package/dist/openapi/security.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Authentication scheme types supported in the OpenAPI specification
+ *
+ * @property {"none"} string No authentication required
+ * @property {"basic"} string HTTP Basic authentication
+ * @property {"bearer"} string HTTP Bearer token authentication
+ * @property {"apiKey"} string API key authentication
+ * @property {"oauth2"} string OAuth 2.0 authentication
+ */
+export type AuthScheme = "none" | "basic" | "bearer" | "apiKey" | "oauth2";
+/**
+ * Security configuration schema for the OpenAPI generation
+ *
+ * @interface SecurityConfig
+ * @property {Object} [global] - Global security settings applied to all operations by default
+ * @property {AuthScheme} [global.scheme] - Default authentication scheme
+ * @property {Object} [global.apiKey] - API key configuration (when scheme is "apiKey")
+ * @property {Object} [global.bearer] - Bearer token configuration (when scheme is "bearer")
+ * @property {Object} [global.basic] - Basic auth configuration (when scheme is "basic")
+ * @property {Object} [global.oauth2] - OAuth2 configuration (when scheme is "oauth2")
+ * @property {Array<Object>} [global.headers] - Global security headers
+ * @property {Record<string, Object>} [overrides] - Operation-specific security overrides
+ */
+export type SecurityConfig = {
+    global?: {
+        scheme?: AuthScheme;
+        apiKey?: {
+            in: "header" | "query" | "cookie";
+            name: string;
+        };
+        bearer?: {
+            bearerFormat?: string;
+        };
+        basic?: Record<string, never>;
+        oauth2?: {
+            flows: Record<string, any>;
+        };
+        headers?: Array<{
+            name: string;
+            required?: boolean;
+            schema?: any;
+        }>;
+    };
+    overrides?: Record<string, {
+        scheme?: AuthScheme;
+        headers?: Array<{
+            name: string;
+            required?: boolean;
+            schema?: any;
+        }>;
+    }>;
+};
+/**
+ * Built security components for OpenAPI generation
+ *
+ * @interface BuiltSecurity
+ * @property {Record<string, any>} [securitySchemes] - Security schemes defined for the API
+ * @property {Record<string, any>} headerParameters - Header parameters for security
+ * @property {Record<string, any[]>} opSecurity - Operation security requirements
+ * @property {Record<string, string[]>} opHeaderParameters - Operation-specific header parameters
+ */
+export type BuiltSecurity = {
+    securitySchemes?: Record<string, any>;
+    headerParameters: Record<string, any>;
+    opSecurity: Record<string, any[] | undefined>;
+    opHeaderParameters: Record<string, string[]>;
+};
+/**
+ * Load security configuration from a JSON file
+ *
+ * @param {string} [filePath] - Path to the security configuration file
+ * @returns {SecurityConfig|undefined} Parsed security configuration object or undefined if loading failed
+ */
+export declare function loadSecurityConfig(filePath?: string): SecurityConfig | undefined;
+/**
+ * Build security schemes and parameters for OpenAPI generation
+ *
+ * @param {SecurityConfig} [cfg] - Security configuration object
+ * @returns {BuiltSecurity} Object containing built security schemes and parameters
+ */
+export declare function buildSecurity(cfg?: SecurityConfig): BuiltSecurity;
+//# sourceMappingURL=security.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/openapi/security.ts"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,UAAU,CAAC;QACpB,MAAM,CAAC,EAAE;YAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7D,MAAM,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAAE,CAAC;QACxC,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC,CAAC;KACrE,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,MAAM,CAAC,EAAE,UAAU,CAAC;QACpB,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC,CAAA;KACpE,CAAC,CAAC;CACJ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAC9C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAShF;AAeD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,aAAa,CA+FjE"}

package/dist/openapi/security.js

@@ -0,0 +1,145 @@
+/**
+ * OpenAPI Security Configuration
+ *
+ * This module handles security scheme generation for the OpenAPI specification.
+ * It provides functionality to define authentication and authorization requirements
+ * for the API, including:
+ *
+ * - Basic authentication
+ * - Bearer token authentication
+ * - API key authentication
+ * - OAuth2 flows
+ * - Custom security headers
+ *
+ * The module supports both global security requirements and operation-specific
+ * security overrides through an external JSON configuration file.
+ */
+import fs from "node:fs";
+/**
+ * Load security configuration from a JSON file
+ *
+ * @param {string} [filePath] - Path to the security configuration file
+ * @returns {SecurityConfig|undefined} Parsed security configuration object or undefined if loading failed
+ */
+export function loadSecurityConfig(filePath) {
+    if (!filePath)
+        return undefined;
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        console.warn(`⚠️ Failed to read security config '${filePath}': ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+}
+/**
+ * Generate a canonical parameter component name from a header name
+ *
+ * @param {string} headerName - Original header name
+ * @returns {string} Canonicalized component name
+ */
+function makeParamComponentName(headerName) {
+    return headerName
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        || "X_Header";
+}
+/**
+ * Build security schemes and parameters for OpenAPI generation
+ *
+ * @param {SecurityConfig} [cfg] - Security configuration object
+ * @returns {BuiltSecurity} Object containing built security schemes and parameters
+ */
+export function buildSecurity(cfg) {
+    const securitySchemes = {};
+    const headerParameters = {};
+    const opSecurity = {};
+    const opHeaderParameters = {};
+    if (!cfg || !cfg.global) {
+        return { securitySchemes: undefined, headerParameters, opSecurity, opHeaderParameters };
+    }
+    const global = cfg.global;
+    const schemeName = "defaultAuth";
+    const scheme = global.scheme || "none";
+    const hasGlobal = scheme !== "none";
+    if (scheme !== "none") {
+        switch (scheme) {
+            case "basic":
+                securitySchemes[schemeName] = { type: "http", scheme: "basic" };
+                break;
+            case "bearer":
+                securitySchemes[schemeName] = { type: "http", scheme: "bearer", ...(global.bearer || {}) };
+                break;
+            case "apiKey":
+                securitySchemes[schemeName] = { type: "apiKey", ...(global.apiKey || { in: "header", name: "X-API-Key" }) };
+                break;
+            case "oauth2":
+                securitySchemes[schemeName] = { type: "oauth2", ...(global.oauth2 || { flows: {} }) };
+                break;
+        }
+    }
+    // Global headers
+    for (const h of global.headers || []) {
+        const compName = makeParamComponentName(h.name);
+        headerParameters[compName] = {
+            name: h.name,
+            in: "header",
+            required: !!h.required,
+            schema: h.schema || { type: "string" },
+        };
+    }
+    // Default op security (inherit global scheme)
+    // (If scheme is none we omit entirely)
+    // Overrides can set scheme to none to remove security
+    for (const [opName, override] of Object.entries(cfg.overrides || {})) {
+        const oScheme = override.scheme ?? scheme;
+        if (oScheme === "none") {
+            opSecurity[opName] = undefined;
+        }
+        else if (oScheme === scheme) {
+            opSecurity[opName] = hasGlobal ? [{ [schemeName]: [] }] : undefined;
+        }
+        else {
+            // Different scheme per operation -> create ad-hoc component name
+            const altName = `${schemeName}_${oScheme}`;
+            if (!securitySchemes[altName]) {
+                switch (oScheme) {
+                    case "basic":
+                        securitySchemes[altName] = { type: "http", scheme: "basic" };
+                        break;
+                    case "bearer":
+                        securitySchemes[altName] = { type: "http", scheme: "bearer" };
+                        break;
+                    case "apiKey":
+                        securitySchemes[altName] = { type: "apiKey", ...(global.apiKey || { in: "header", name: "X-API-Key" }) };
+                        break;
+                    case "oauth2":
+                        securitySchemes[altName] = { type: "oauth2", ...(global.oauth2 || { flows: {} }) };
+                        break;
+                }
+            }
+            opSecurity[opName] = [{ [altName]: [] }];
+        }
+        // Per-op headers merge global + override specific headers
+        const headers = [...(global.headers || []), ...(override.headers || [])];
+        opHeaderParameters[opName] = headers.map(h => makeParamComponentName(h.name));
+        for (const h of override.headers || []) {
+            const compName = makeParamComponentName(h.name);
+            if (!headerParameters[compName]) {
+                headerParameters[compName] = {
+                    name: h.name,
+                    in: "header",
+                    required: !!h.required,
+                    schema: h.schema || { type: "string" },
+                };
+            }
+        }
+    }
+    return {
+        securitySchemes: Object.keys(securitySchemes).length ? securitySchemes : undefined,
+        headerParameters,
+        opSecurity,
+        opHeaderParameters
+    };
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,37 @@
+import { type GenerateOpenAPIOptions } from "./openapi/generateOpenAPI.js";
+import type { CompilerOptions } from "./config.js";
+/**
+ * Configuration options for the generation pipeline
+ *
+ * @interface PipelineOptions
+ * @property {string} wsdl - Path or URL to the WSDL file to process
+ * @property {string} outDir - Output directory for generated TypeScript artifacts
+ * @property {Partial<CompilerOptions>} [compiler] - Compiler options for type generation
+ * @property {object} [openapi] - OpenAPI generation configuration (optional)
+ * @property {string} [openapi.outFile] - Optional output path for OpenAPI specification
+ */
+export interface PipelineOptions {
+    wsdl: string;
+    outDir: string;
+    compiler?: Partial<CompilerOptions>;
+    openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
+        outFile?: string;
+    };
+}
+/**
+ * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI
+ *
+ * This function orchestrates the entire process:
+ * 1. Loads and parses the WSDL from file or URL
+ * 2. Compiles the WSDL into an internal catalog representation
+ * 3. Emits TypeScript client code, types, and utilities
+ * 4. Optionally emits a JSON catalog for introspection
+ * 5. Optionally generates an OpenAPI 3.1 specification
+ *
+ * @param {PipelineOptions} opts - Configuration options for the pipeline
+ * @returns {Promise<{compiled: any}>} - The compiled catalog for potential further processing
+ */
+export declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
+    compiled: import("./compiler/schemaCompiler.js").CompiledCatalog;
+}>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +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,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAGjD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,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;CAC3G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe;;GAgDhE"}

package/dist/pipeline.js

@@ -0,0 +1,72 @@
+/**
+ * TypeScript WSDL Client Generation Pipeline
+ *
+ * This file implements the high-level generation pipeline that orchestrates the entire
+ * process of converting a WSDL file into TypeScript client code and optionally an OpenAPI
+ * specification. It serves as an integration layer between the various stages of the generation
+ * process.
+ */
+import path from "node:path";
+import fs from "node:fs";
+import { loadWsdl } from "./loader/wsdlLoader.js";
+import { compileCatalog } from "./compiler/schemaCompiler.js";
+import { emitClient } from "./emit/clientEmitter.js";
+import { emitTypes } from "./emit/typesEmitter.js";
+import { emitUtils } from "./emit/utilsEmitter.js";
+import { emitCatalog } from "./emit/catalogEmitter.js";
+import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
+import { TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS } from "./config.js";
+/**
+ * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI
+ *
+ * This function orchestrates the entire process:
+ * 1. Loads and parses the WSDL from file or URL
+ * 2. Compiles the WSDL into an internal catalog representation
+ * 3. Emits TypeScript client code, types, and utilities
+ * 4. Optionally emits a JSON catalog for introspection
+ * 5. Optionally generates an OpenAPI 3.1 specification
+ *
+ * @param {PipelineOptions} opts - Configuration options for the pipeline
+ * @returns {Promise<{compiled: any}>} - The compiled catalog for potential further processing
+ */
+export async function runGenerationPipeline(opts) {
+    // Merge provided compiler options with defaults, ensuring required fields are set
+    const finalCompiler = {
+        ...TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS,
+        catalog: opts.compiler?.catalog ?? true, // default to emitting catalog in pipeline mode
+        ...(opts.compiler || {}),
+        wsdl: opts.wsdl,
+        out: opts.outDir,
+    };
+    // Step 1: Load and parse the WSDL document
+    const wsdlCatalog = await loadWsdl(opts.wsdl);
+    // Step 2: Compile the WSDL into a structured catalog
+    const compiled = compileCatalog(wsdlCatalog, finalCompiler);
+    // Step 3: Ensure the output directory exists
+    fs.mkdirSync(opts.outDir, { recursive: true });
+    // Step 4: Emit TypeScript artifacts
+    emitClient(path.join(opts.outDir, "client.ts"), compiled);
+    emitTypes(path.join(opts.outDir, "types.ts"), compiled);
+    emitUtils(path.join(opts.outDir, "utils.ts"), compiled);
+    // Step 5: Optionally emit the JSON catalog for introspection
+    if (finalCompiler.catalog) {
+        emitCatalog(path.join(opts.outDir, "catalog.json"), compiled);
+    }
+    // Step 6: Optionally generate OpenAPI specification
+    if (opts.openapi) {
+        // Determine output path for OpenAPI specification
+        let resolvedOut = opts.openapi.outFile;
+        if (!resolvedOut) {
+            const yamlPreferred = !!opts.openapi.asYaml;
+            resolvedOut = path.join(opts.outDir, yamlPreferred ? "openapi.yaml" : "openapi.json");
+        }
+        // Generate the OpenAPI specification using the compiled catalog
+        await generateOpenAPI({
+            ...opts.openapi,
+            compiledCatalog: compiled,
+            outFile: resolvedOut,
+        });
+    }
+    // Return the compiled catalog for potential further processing
+    return { compiled };
+}