@techspokes/typescript-wsdl-client 0.10.0 → 0.10.1

package/docs/api-reference.md

@@ -0,0 +1,223 @@
+# Programmatic API
+
+All CLI commands are available as TypeScript functions. This document covers each exported function, its usage, and its type signatures.
+
+See the main [README](../README.md) for installation, CLI usage, and project overview.
+
+## compileWsdlToProject
+
+Generate a TypeScript SOAP client from WSDL.
+
+```typescript
+import { compileWsdlToProject } from "@techspokes/typescript-wsdl-client";
+
+await compileWsdlToProject({
+  wsdl: "./wsdl/Hotel.wsdl",
+  outDir: "./src/services/hotel",
+  options: {
+    imports: "js",
+    catalog: true,
+    primitive: {
+      int64As: "number",
+      bigIntegerAs: "string",
+      decimalAs: "string",
+      dateAs: "string"
+    },
+    choice: "all-optional",
+    clientName: "HotelClient",
+    nillableAsOptional: false
+  }
+});
+```
+
+### Type Signature
+
+```typescript
+function compileWsdlToProject(input: {
+  wsdl: string;
+  outDir: string;
+  options?: Partial<CompilerOptions>;
+}): Promise<void>;
+```
+
+### CompilerOptions
+
+```typescript
+interface CompilerOptions {
+  wsdl: string;
+  out: string;
+  imports: "js" | "ts" | "bare";
+  catalog: boolean;
+  primitive: PrimitiveOptions;
+  choice?: "all-optional" | "union";
+  failOnUnresolved?: boolean;
+  attributesKey?: string;
+  clientName?: string;
+  nillableAsOptional?: boolean;
+}
+
+interface PrimitiveOptions {
+  int64As?: "string" | "number" | "bigint";
+  bigIntegerAs?: "string" | "number";
+  decimalAs?: "string" | "number";
+  dateAs?: "string" | "Date";
+}
+```
+
+## generateOpenAPI
+
+Generate an OpenAPI 3.1 specification from WSDL or catalog.
+
+```typescript
+import { generateOpenAPI } from "@techspokes/typescript-wsdl-client";
+
+const { doc, jsonPath, yamlPath } = await generateOpenAPI({
+  wsdl: "./wsdl/Hotel.wsdl",
+  outFile: "./docs/hotel-api",
+  format: "both",
+  title: "Hotel Booking API",
+  version: "1.0.0",
+  servers: ["https://api.example.com/v1"],
+  basePath: "/booking",
+  pathStyle: "kebab",
+  tagStyle: "service",
+  validate: true
+});
+```
+
+### Type Signature
+
+```typescript
+function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
+  doc: any;
+  jsonPath?: string;
+  yamlPath?: string;
+}>;
+```
+
+### GenerateOpenAPIOptions
+
+```typescript
+interface GenerateOpenAPIOptions {
+  wsdl?: string;
+  catalogFile?: string;
+  compiledCatalog?: CompiledCatalog;
+  outFile?: string;
+  format?: "json" | "yaml" | "both";
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: string[];
+  basePath?: string;
+  pathStyle?: "kebab" | "asis" | "lower";
+  defaultMethod?: string;
+  closedSchemas?: boolean;
+  pruneUnusedSchemas?: boolean;
+  tagStyle?: "default" | "first" | "service";
+  tagsFile?: string;
+  securityConfigFile?: string;
+  opsFile?: string;
+  envelopeNamespace?: string;
+  errorNamespace?: string;
+  validate?: boolean;
+  skipValidate?: boolean;
+  asYaml?: boolean;  // deprecated
+}
+```
+
+## generateGateway
+
+Generate Fastify gateway code from an OpenAPI specification.
+
+```typescript
+import { generateGateway } from "@techspokes/typescript-wsdl-client";
+
+await generateGateway({
+  openapiFile: "./docs/hotel-api.json",
+  outDir: "./src/gateway/hotel",
+  clientDir: "./src/services/hotel",
+  versionSlug: "v1",
+  serviceSlug: "hotel",
+  defaultResponseStatusCodes: [200, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503, 504],
+  imports: "js"
+});
+```
+
+### Type Signature
+
+```typescript
+function generateGateway(opts: GenerateGatewayOptions): Promise<void>;
+```
+
+### GenerateGatewayOptions
+
+```typescript
+interface GenerateGatewayOptions {
+  openapiFile?: string;
+  openapiDocument?: any;
+  outDir: string;
+  clientDir?: string;
+  versionSlug?: string;
+  serviceSlug?: string;
+  defaultResponseStatusCodes?: number[];
+  imports?: "js" | "ts" | "bare";
+}
+```
+
+## runGenerationPipeline
+
+Run the complete pipeline: client, OpenAPI, and gateway in one pass.
+
+```typescript
+import { runGenerationPipeline } from "@techspokes/typescript-wsdl-client";
+
+const { compiled, openapiDoc } = await runGenerationPipeline({
+  wsdl: "./wsdl/Hotel.wsdl",
+  catalogOut: "./build/hotel-catalog.json",
+  clientOutDir: "./src/services/hotel",
+  compiler: {
+    imports: "js",
+    primitive: {
+      int64As: "number",
+      decimalAs: "string"
+    }
+  },
+  openapi: {
+    outFile: "./docs/hotel-api.json",
+    format: "both",
+    servers: ["https://api.example.com/v1"],
+    tagStyle: "service"
+  },
+  gateway: {
+    outDir: "./src/gateway/hotel",
+    versionSlug: "v1",
+    serviceSlug: "hotel"
+  }
+});
+```
+
+### Type Signature
+
+```typescript
+function runGenerationPipeline(opts: PipelineOptions): Promise<{
+  compiled: CompiledCatalog;
+  openapiDoc?: any;
+}>;
+```
+
+### PipelineOptions
+
+```typescript
+interface PipelineOptions {
+  wsdl: string;
+  catalogOut: string;
+  clientOutDir?: string;
+  compiler?: Partial<CompilerOptions>;
+  openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
+    outFile?: string;
+  };
+  gateway?: Omit<GenerateGatewayOptions, "openapiFile" | "openapiDocument"> & {
+    outDir?: string;
+  };
+}
+```

package/docs/architecture.md

@@ -0,0 +1,115 @@
+# Architecture
+
+Internal architecture of the wsdl-tsc code generator for contributors.
+
+See [CONTRIBUTING](../CONTRIBUTING.md) for development setup and [README](../README.md) for user documentation.
+
+## Pipeline Overview
+
+```text
+WSDL Source
+    |
+    v
+Loader (fetch.ts, wsdlLoader.ts)
+    Fetches WSDL from URL or file
+    Returns parsed XML document
+    |
+    v
+Compiler (schemaCompiler.ts)
+    Walks XSD types, resolves references
+    Produces CompiledCatalog
+    |
+    v
+Catalog Emitter (generateCatalog.ts)
+    Serializes to catalog.json
+    |
+    +-------+--------+--------+
+    |       |        |        |
+    v       v        v        v
+Client  OpenAPI  Gateway   App
+Emitter  Gen      Gen     Gen
+```
+
+## Module Responsibilities
+
+### loader/
+
+fetch.ts handles HTTP/HTTPS/file fetching. wsdlLoader.ts handles XML parsing and import/include resolution.
+
+### compiler/
+
+schemaCompiler.ts is the core compiler. It walks XSD complex/simple types, resolves inheritance, handles choices, and builds the type graph. generateCatalog.ts serializes compiled types to catalog.json.
+
+### client/
+
+generateClient.ts emits the client class with one method per operation. generateTypes.ts emits interfaces, type aliases, and enums. generateUtils.ts emits runtime metadata for attribute maps and occurrence info.
+
+### openapi/
+
+generateOpenAPI.ts orchestrates the complete OpenAPI document. generateSchemas.ts converts compiled types to JSON Schema. generatePaths.ts generates path items from operations. security.ts processes security configuration files. casing.ts handles path style transformation.
+
+### gateway/
+
+generateGateway.ts orchestrates all gateway file generation. generators.ts contains template emitters for each file type (plugin, routes, schemas, runtime, _typecheck). helpers.ts resolves client metadata, computes paths, and builds URNs.
+
+### app/
+
+generateApp.ts generates server.js, config.js, and .env.example.
+
+### Top-level Modules
+
+pipeline.ts orchestrates the full pipeline from compile through app generation. config.ts provides default compiler options and option merging. cli.ts defines the Yargs CLI and routes commands. index.ts exports the four public API functions.
+
+### util/
+
+tools.ts provides string helpers (pascal, kebab, QName resolution). cli.ts provides console output helpers and error handling. builder.ts provides shared Yargs option builders.
+
+### xsd/
+
+primitives.ts maps XSD primitive types to TypeScript types.
+
+## Central Data Structure
+
+The CompiledCatalog is the central data structure:
+
+```text
+CompiledCatalog {
+  wsdlUri: string
+  targetNamespace: string
+  serviceName: string
+  types: CompiledType[]
+  operations: Operation[]
+  options: CompilerOptions
+}
+```
+
+Data flow through the pipeline:
+
+1. schemaCompiler produces CompiledCatalog from WSDL XML
+2. generateCatalog serializes it to JSON
+3. Client generators read types[] for TypeScript emission
+4. OpenAPI generator reads types[] and operations[] for spec generation
+5. Gateway generator reads the OpenAPI spec (not the catalog directly)
+
+## Extension Points
+
+### Adding a New CLI Flag
+
+1. Add option to builder in src/util/builder.ts
+2. Wire it in the command handler in src/cli.ts
+3. Pass it through to the relevant generator
+4. Update smoke tests if the flag affects output
+
+### Adding a New Generator
+
+1. Create src/<name>/generate<Name>.ts
+2. Export the function from src/index.ts
+3. Add CLI command in src/cli.ts
+4. Wire into pipeline in src/pipeline.ts
+5. Add smoke test in package.json
+
+### Adding a New XSD Type Mapping
+
+1. Add mapping in src/xsd/primitives.ts
+2. Handle in src/compiler/schemaCompiler.ts if needed
+3. Update src/openapi/generateSchemas.ts for JSON Schema output