@techspokes/typescript-wsdl-client 0.10.0 → 0.10.2

package/docs/troubleshooting.md

@@ -0,0 +1,70 @@
+# Troubleshooting
+
+Common issues and debugging guidance for wsdl-tsc.
+
+See [README](../README.md) for quick start and [CLI Reference](cli-reference.md) for command details.
+
+## Common Issues
+
+| Symptom | Resolution |
+|---------|------------|
+| WSDL fetch fails | Curl the URL, check TLS/proxy settings, retry with local copy |
+| Unresolved type references | Re-run with --client-fail-on-unresolved=false to inspect partial graph |
+| Missing schema in OpenAPI | Ensure the global element exists (catalog shows compiled symbols) |
+| Wrong array modeling | Check maxOccurs in WSDL; tool only arrays when maxOccurs>1 or unbounded |
+| Authentication errors | Provide proper soap.ISecurity instance (WSSecurity, BasicAuthSecurity) |
+| Date/time confusion | Use --client-date-as Date for runtime Date objects |
+| TypeScript compilation errors | Check --import-extensions matches your tsconfig moduleResolution |
+| Gateway validation failures | Ensure OpenAPI has valid $ref paths and all schemas in components.schemas |
+| Catalog file not found | Catalog defaults to output directory; use --catalog-file to specify |
+
+## SOAP Wire Logging
+
+Enable SOAP request/response debugging:
+
+```bash
+NODE_DEBUG=soap node app.js
+```
+
+## Verify Installation
+
+```bash
+npx wsdl-tsc --help
+npm run smoke:pipeline
+```
+
+## TypeScript Configuration
+
+Ensure your tsconfig.json is compatible:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Catalog Inspection
+
+Examine the compiled catalog to debug type resolution:
+
+```bash
+npx wsdl-tsc compile \
+  --wsdl-source ./wsdl/Hotel.wsdl \
+  --catalog-file build/hotel-catalog.json
+
+cat build/hotel-catalog.json | jq '.types'
+cat build/hotel-catalog.json | jq '.operations'
+```
+
+Or inspect catalog from client generation:
+
+```bash
+cat ./src/services/hotel/catalog.json | jq '.types'
+```

package/llms.txt

@@ -0,0 +1,53 @@
+# @techspokes/typescript-wsdl-client
+
+> Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and
+> production-ready Fastify REST gateways from WSDL/XSD definitions.
+
+## Quick Facts
+
+- CLI binary: wsdl-tsc
+- Node.js >= 20.0.0
+- Runtime dependency: soap
+- Output: TypeScript client + OpenAPI 3.1 + Fastify gateway
+- All output is deterministic and diff-friendly
+
+## Install
+
+npm install --save-dev @techspokes/typescript-wsdl-client
+npm install soap
+
+## Primary Command
+
+npx wsdl-tsc pipeline \
+  --wsdl-source <path-or-url> \
+  --client-dir <output-dir> \
+  --openapi-file <output-path> \
+  --gateway-dir <output-dir> \
+  --gateway-service-name <slug> \
+  --gateway-version-prefix <version>
+
+## Generated Files
+
+- client/client.ts: typed SOAP client class
+- client/types.ts: TypeScript interfaces from XSD
+- client/utils.ts: runtime metadata
+- client/catalog.json: compiled WSDL representation
+- openapi.json: OpenAPI 3.1 specification
+- gateway/plugin.ts: Fastify plugin entry point
+- gateway/routes.ts: route aggregator module
+- gateway/routes/: route handlers with typed request bodies
+- gateway/runtime.ts: envelope builders and error handler
+- gateway/schemas.ts: schema registration module
+- gateway/schemas/: JSON schemas for validation and serialization
+- gateway/_typecheck.ts: build-time type-check fixture
+
+## Documentation
+
+- AGENTS.md: agent instructions (universal, tool-agnostic)
+- README.md: project overview and quick start
+- CONTRIBUTING.md: development setup, project structure, testing strategy
+- docs/migration.md: upgrade paths between versions
+- .github/copilot-instructions.md: authoritative detailed agent instructions (referenced by AGENTS.md)
+- docs/README.md: documentation directory index and conventions
+- npm: https://www.npmjs.com/package/@techspokes/typescript-wsdl-client
+- GitHub: https://github.com/TechSpokes/typescript-wsdl-client

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.10.0",
-  "description": "TypeScript WSDL → SOAP client generator with full xs:attribute support, complex types, sequences, inheritance, and namespace-collision merging.",
+  "version": "0.10.2",
+  "description": "Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.",
   "keywords": [
     "wsdl",
     "soap",
     "typescript",
+    "openapi",
+    "rest",
+    "gateway",
+    "fastify",
     "codegen",
-    "generator",
-    "xml",
-    "xsd"
+    "soap-to-rest",
+    "api-gateway",
+    "code-generator",
+    "wsdl-to-typescript"
   ],
   "homepage": "https://github.com/TechSpokes/typescript-wsdl-client#readme",
   "bugs": {
@@ -41,8 +46,10 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",
@@ -81,6 +88,6 @@
   },
   "funding": {
     "type": "github",
-    "url": "https://github.com/techspokes"
+    "url": "https://github.com/sponsors/TechSpokes"
   }
 }