@techspokes/typescript-wsdl-client 0.10.0 → 0.10.2

package/docs/AGENTS.md

@@ -0,0 +1,47 @@
+# Agent Instructions for docs/
+
+## Summary
+
+This directory contains human-maintained reference documentation for `@techspokes/typescript-wsdl-client`. Documents here are not generated; agents may edit them but must preserve cross-references, formatting conventions, and consistency with the root README.
+
+## Must-follow rules
+
+- Maintain cross-references between documents; when a doc mentions a related topic, link to the relevant file.
+- Use relative links for all internal references (e.g. `[CLI Reference](cli-reference.md)`, `[root README](../README.md)`).
+- Each document must open with an H1 title, a one-line description, and a cross-reference to the root [README.md](../README.md).
+- When adding, renaming, or removing a document, update the Documentation table in the root [README.md](../README.md) — that table is the single source of truth for this directory's contents.
+- Do not duplicate content from root-level files (README.md, CONTRIBUTING.md, CHANGELOG.md); link to them instead.
+
+## Must-read documents
+
+- [Root README.md](../README.md): authoritative Documentation table and project overview
+- [Root AGENTS.md](../AGENTS.md): project-wide agent instructions pointing to `.github/copilot-instructions.md` for full detail
+
+## Agent guidelines
+
+### Style conventions
+
+- Use fenced code blocks for CLI examples and inline code for flag names (`` `--flag-name` ``).
+- Keep language direct and task-oriented.
+- `architecture.md` targets contributors; all other documents target users.
+
+### Adding a new document
+
+1. Create the file in `docs/` with an H1 title and description.
+2. Add a row to the Documentation table in the root README.md.
+3. Add a bullet to the Contents list in `docs/README.md`.
+4. Cross-reference from related existing documents where appropriate.
+
+### Editing existing documents
+
+- Preserve the H1 + description + cross-reference opening pattern.
+- If renaming a file, update the root README.md Documentation table and fix any relative links in other docs.
+
+## Context
+
+The `docs/` directory was introduced in v0.8.x to move detailed reference material out of the root README. `architecture.md` covers the internal pipeline for contributors; the remaining documents serve end users integrating with or deploying generated code.
+
+## References
+
+- [examples/README.md](../examples/README.md): folder README pattern example
+- [Root README.md Documentation table](../README.md#documentation): authoritative listing of all docs

package/docs/README.md

@@ -0,0 +1,35 @@
+# Documentation
+
+Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. The root [README.md](../README.md) Documentation table is the authoritative index with descriptions; the list below is a quick local reference.
+
+## Contents
+
+- [api-reference.md](api-reference.md) – Programmatic TypeScript API
+- [architecture.md](architecture.md) – Internal pipeline for contributors
+- [cli-reference.md](cli-reference.md) – All 6 commands with flags and examples
+- [concepts.md](concepts.md) – Flattening, `$value`, primitives, determinism
+- [configuration.md](configuration.md) – Security, tags, operations config files
+- [gateway-guide.md](gateway-guide.md) – Fastify integration and error handling
+- [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
+- [troubleshooting.md](troubleshooting.md) – Common issues and debugging
+
+## Conventions
+
+- Each document opens with an H1 title and a one-line description.
+- Cross-reference related documents and the root README where relevant.
+- Use fenced code blocks for CLI examples; format flags as inline code (`` `--flag-name` ``).
+- Keep language direct and task-oriented; architecture.md targets contributors, all others target users.
+
+## Related
+
+- [Root README](../README.md) – project overview, quick start, and authoritative Documentation table
+- [CONTRIBUTING.md](../CONTRIBUTING.md) – development setup and workflow
+- [CHANGELOG.md](../CHANGELOG.md) – version history
+- [examples/](../examples/) – sample WSDL files and generated output
+
+## Not Here
+
+- Generated code samples live in `examples/generated-output/`, not in `docs/`.
+- Installation and dev setup belong in the root README and CONTRIBUTING.md respectively.

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