klasik 1.0.12 → 1.0.14

package/README.md

@@ -6,6 +6,9 @@ Download OpenAPI specifications from remote URLs and generate TypeScript clients
 
 - 📥 **Download OpenAPI specs** from remote URLs or local files
 - 📁 **Multiple input formats** - HTTP/HTTPS URLs, file:// URLs, absolute/relative paths
+- 📄 **JSON and YAML support** - Automatically parse and handle both formats
+- 🔐 **Authentication support** - Custom headers including Bearer tokens and API keys
+- 🔗 **External reference resolution** - Automatically download referenced schema files (`$ref`)
 - 🔄 **Automatic transformation** - Converts API responses to class instances using class-transformer
 - 🎯 **Type-safe** - Full TypeScript support with decorators
 - 🛠️ **Configurable** - Custom headers, timeouts, and templates
@@ -25,17 +28,23 @@ npm install klasik
 Generate a TypeScript client from a remote OpenAPI spec:
 
 ```bash
+# JSON spec
 npx klasik generate \
   --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json \
   --output ./k8s-client
+
+# YAML spec
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./client
 ```
 
-Generate from a local OpenAPI spec file:
+Generate from a local OpenAPI spec file (JSON or YAML):
 
 ```bash
 # Absolute path
 npx klasik generate \
-  --url /path/to/openapi.json \
+  --url /path/to/openapi.yaml \
   --output ./client
 
 # Relative path
@@ -45,16 +54,22 @@ npx klasik generate \
 
 # file:// URL
 npx klasik generate \
-  --url file:///path/to/openapi.json \
+  --url file:///path/to/openapi.yaml \
   --output ./client
 ```
 
-Download an OpenAPI spec without generating:
+Download an OpenAPI spec without generating (supports JSON and YAML):
 
 ```bash
+# Download JSON spec
 npx klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json
+
+# Download YAML spec
+npx klasik download \
+  --url https://api.example.com/openapi.yaml \
+  --output ./specs/api-spec.yaml
 ```
 
 ### Programmatic Usage
@@ -81,6 +96,9 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
   - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
 - `-o, --output <dir>` - Output directory for generated client code (required)
 - `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
+  - Can be used multiple times for multiple headers
+  - Perfect for authorization: `--header "Authorization: Bearer token"`
+- `-r, --resolve-refs` - Resolve and download external `$ref` references
 - `-t, --template <dir>` - Custom template directory
 - `-k, --keep-spec` - Keep the downloaded spec file after generation
 - `--timeout <ms>` - Request timeout in milliseconds for HTTP requests (default: 30000)
@@ -88,13 +106,27 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
 **Examples:**
 
 ```bash
-# From remote URL
+# From remote URL with authorization
 klasik generate \
   --url https://api.example.com/openapi.json \
   --output ./client \
   --header "Authorization: Bearer token123" \
   --timeout 60000
 
+# With external reference resolution
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token123" \
+  --resolve-refs
+
+# Multiple headers
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token" \
+  --header "X-API-Version: v1"
+
 # From local file
 klasik generate \
   --url ./my-spec.json \
@@ -114,15 +146,24 @@ Download an OpenAPI spec from a remote URL without generating code.
 - `-u, --url <url>` - Remote URL to download the OpenAPI spec from (required)
 - `-o, --output <file>` - Output file path for the downloaded spec (required)
 - `-H, --header <header...>` - Custom headers for the request
+- `-r, --resolve-refs` - Resolve and download external `$ref` references
 - `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
 
-**Example:**
+**Examples:**
 
 ```bash
+# Download spec only
 klasik download \
   --url https://api.example.com/openapi.json \
   --output ./specs/api-spec.json \
   --header "Authorization: Bearer token123"
+
+# Download spec with all external references
+klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json \
+  --header "Authorization: Bearer token123" \
+  --resolve-refs
 ```
 
 ## Programmatic API
@@ -141,6 +182,7 @@ await generator.generate({
     'Authorization': 'Bearer token123',
     'X-Custom-Header': 'value'
   },
+  resolveReferences: true, // Download external $ref files
   templateDir: './custom-templates', // Optional
   keepSpec: true, // Keep downloaded spec file
   timeout: 60000 // Request timeout in ms
@@ -160,6 +202,7 @@ const specPath = await downloader.download({
   headers: {
     'Authorization': 'Bearer token123'
   },
+  resolveReferences: true, // Download external $ref files
   timeout: 30000
 });
 
@@ -235,6 +278,90 @@ const user = response.data; // user is instanceof User ✅
 console.log(user.name); // Fully typed!
 ```
 
+## External Reference Resolution
+
+Klasik can automatically resolve and download external `$ref` references in your OpenAPI specs. This is useful when your spec splits schemas across multiple files.
+
+### How It Works
+
+When you enable `--resolve-refs` (CLI) or `resolveReferences: true` (programmatic), klasik will:
+
+1. **Parse the main spec** for external `$ref` references
+2. **Download all referenced files** preserving directory structure
+3. **Recursively resolve nested references** in downloaded files
+4. **Use the same authentication** for all downloads
+
+### Example OpenAPI Spec with External References
+
+```json
+{
+  "openapi": "3.0.0",
+  "paths": {
+    "/users": {
+      "get": {
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "./schemas/users-orgs.yaml#/components/schemas/Org"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+With `--resolve-refs`, klasik will automatically download `./schemas/users-orgs.yaml` and any files it references.
+
+### Output Structure
+
+Referenced files are downloaded preserving the directory structure:
+
+```
+output/
+├── openapi-spec.json       # Main spec
+└── schemas/
+    ├── users-orgs.yaml     # Referenced schema
+    └── common/
+        └── types.yaml      # Nested reference
+```
+
+### Supported Reference Types
+
+- **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
+- **Remote URLs**: `https://api.example.com/schemas/user.yaml`
+- **Mixed**: Main spec from HTTPS, references can be relative or absolute
+
+### CLI Example
+
+```bash
+# Download spec with all external references
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token" \
+  --resolve-refs
+```
+
+### Programmatic Example
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+await new K8sClientGenerator().generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  headers: { 'Authorization': 'Bearer token' },
+  resolveReferences: true,
+  keepSpec: true // Keep all downloaded files
+});
+```
+
 ## Advanced Configuration
 
 ### Custom Error Handling

package/USAGE_EXAMPLES.md

@@ -0,0 +1,221 @@
+# Klasik Usage Examples
+
+## JSON and YAML Support
+
+Klasik automatically detects and parses both JSON and YAML OpenAPI specifications. The original format is preserved when downloading.
+
+### CLI Examples
+
+```bash
+# JSON spec
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client
+
+# YAML spec
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./client
+
+# Local YAML file
+npx klasik generate \
+  --url ./specs/openapi.yaml \
+  --output ./client
+
+# Download and keep YAML format
+npx klasik download \
+  --url https://api.example.com/openapi.yaml \
+  --output ./specs/api-spec.yaml \
+  --resolve-refs
+```
+
+### Programmatic Examples
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+// Works with both JSON and YAML
+await new K8sClientGenerator().generate({
+  specUrl: 'https://api.example.com/openapi.yaml',
+  outputDir: './client'
+});
+```
+
+### Mixed Formats with References
+
+Klasik handles specs where the main file is in one format and referenced files are in another:
+
+```yaml
+# openapi.yaml (main spec in YAML)
+openapi: 3.0.0
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: './schemas/users.json#/components/schemas/User'  # JSON reference
+```
+
+Both formats work seamlessly together!
+
+## Using Custom Headers (Authorization)
+
+### CLI Example - Authorization Token
+
+```bash
+# Using Bearer token
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer your-token-here"
+
+# Using API key
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "X-API-Key: your-api-key"
+
+# Multiple headers
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer your-token" \
+  --header "X-Custom-Header: custom-value"
+```
+
+### Programmatic Example - Authorization Token
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  headers: {
+    'Authorization': 'Bearer your-token-here',
+    'X-API-Key': 'your-api-key'
+  }
+});
+```
+
+## Resolving External References
+
+### CLI Example - With Reference Resolution
+
+```bash
+# Download spec and all external $ref files
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --resolve-refs \
+  --header "Authorization: Bearer your-token"
+
+# Download only (no code generation)
+npx klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json \
+  --resolve-refs \
+  --header "Authorization: Bearer your-token"
+```
+
+### Programmatic Example - With Reference Resolution
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  resolveReferences: true,
+  headers: {
+    'Authorization': 'Bearer your-token-here'
+  }
+});
+```
+
+## How Reference Resolution Works
+
+When you enable `--resolve-refs` (or `resolveReferences: true`), klasik will:
+
+1. **Parse the main OpenAPI spec** for external `$ref` references like:
+   ```yaml
+   schema:
+     $ref: './schemas/users-orgs.yaml#/components/schemas/Org'
+   ```
+
+2. **Download all referenced files** preserving the directory structure:
+   ```
+   output/
+   ├── openapi-spec.json (main spec)
+   └── schemas/
+       └── users-orgs.yaml (referenced schema)
+   ```
+
+3. **Recursively resolve nested references** - if `users-orgs.yaml` has its own `$ref` to other files, those will be downloaded too
+
+4. **Use the same headers** for all downloads (useful when all files require authentication)
+
+### Supported Reference Types
+
+- **Relative paths**: `./schemas/user.yaml`, `../common/types.yaml`
+- **Remote URLs**: `https://api.example.com/schemas/user.yaml`
+- **Mixed**: Main spec from HTTPS, references can be relative or absolute
+
+### Example OpenAPI Spec with External References
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "My API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "./schemas/users.yaml#/components/schemas/UserList"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+When you run with `--resolve-refs`, klasik will automatically download `./schemas/users.yaml`.
+
+## Complete Example
+
+```bash
+# Full workflow with private API
+npx klasik generate \
+  --url https://private-api.example.com/v1/openapi.json \
+  --output ./generated-client \
+  --header "Authorization: Bearer eyJhbGc..." \
+  --header "X-API-Version: v1" \
+  --resolve-refs \
+  --keep-spec \
+  --timeout 60000
+```
+
+This will:
+- Download the OpenAPI spec with authorization headers
+- Resolve and download all external schema references
+- Generate the TypeScript client
+- Keep all downloaded specs in the output directory
+- Use a 60-second timeout for all HTTP requests

package/dist/cli.js

@@ -51,6 +51,7 @@ program
     .option('-H, --header <header...>', 'Custom headers for the request (format: "Key: Value")')
     .option('-t, --template <dir>', 'Custom template directory')
     .option('-k, --keep-spec', 'Keep the downloaded spec file after generation', false)
+    .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -80,6 +81,7 @@ program
             headers: Object.keys(headers).length > 0 ? headers : undefined,
             templateDir: options.template,
             keepSpec: options.keepSpec,
+            resolveReferences: options.resolveRefs,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);
@@ -95,6 +97,7 @@ program
     .requiredOption('-u, --url <url>', 'Remote URL to download the OpenAPI spec from')
     .requiredOption('-o, --output <file>', 'Output file path for the downloaded spec')
     .option('-H, --header <header...>', 'Custom headers for the request (format: "Key: Value")')
+    .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -115,6 +118,7 @@ program
             url: options.url,
             outputPath: path.resolve(options.output),
             headers: Object.keys(headers).length > 0 ? headers : undefined,
+            resolveReferences: options.resolveRefs,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);

package/dist/k8s-client-generator.d.ts

@@ -28,6 +28,11 @@ export interface K8sClientGeneratorOptions {
      * @default false
      */
     keepSpec?: boolean;
+    /**
+     * Whether to resolve and download external $ref references
+     * @default false
+     */
+    resolveReferences?: boolean;
     /**
      * Request timeout for downloading spec in milliseconds
      * @default 30000

package/dist/k8s-client-generator.js

@@ -46,7 +46,7 @@ class K8sClientGenerator {
      * Generate TypeScript client from a remote OpenAPI spec URL
      */
     async generate(options) {
-        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, timeout, } = options;
+        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, timeout, } = options;
         let specPath;
         try {
             // Step 1: Download the OpenAPI spec
@@ -55,6 +55,7 @@ class K8sClientGenerator {
                 url: specUrl,
                 headers,
                 timeout,
+                resolveReferences,
                 // If keepSpec is true, save the spec in the output directory
                 outputPath: keepSpec ? path.join(outputDir, 'openapi-spec.json') : undefined,
             };

package/dist/spec-downloader.d.ts

@@ -22,8 +22,19 @@ export interface DownloadOptions {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Whether to resolve and download external $ref references
+     * @default false
+     */
+    resolveReferences?: boolean;
+    /**
+     * Base URL for resolving relative references (used when main spec is from HTTP)
+     * If not provided, will be derived from the main spec URL
+     */
+    baseUrl?: string;
 }
 export declare class SpecDownloader {
+    private downloadedRefs;
     /**
      * Download an OpenAPI specification from a URL or load from a local file
      * @param options Download options
@@ -43,11 +54,31 @@ export declare class SpecDownloader {
      */
     private generateTempPath;
     /**
-     * Validate that the downloaded content is an OpenAPI spec
+     * Validate that the parsed content is an OpenAPI spec
      */
     private validateSpec;
     /**
      * Clean up temporary files
      */
     cleanupTemp(): void;
+    /**
+     * Get base URL from a full URL (removes the filename)
+     */
+    private getBaseUrl;
+    /**
+     * Resolve and download all external $ref references in the spec
+     */
+    private resolveExternalRefs;
+    /**
+     * Find all external $ref values in the spec
+     */
+    private findExternalRefs;
+    /**
+     * Check if a $ref is external (references another file)
+     */
+    private isExternalRef;
+    /**
+     * Download a single reference file
+     */
+    private downloadReference;
 }

package/dist/spec-downloader.js

@@ -40,17 +40,27 @@ exports.SpecDownloader = void 0;
 const axios_1 = __importDefault(require("axios"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
 class SpecDownloader {
+    constructor() {
+        this.downloadedRefs = new Set();
+    }
     /**
      * Download an OpenAPI specification from a URL or load from a local file
      * @param options Download options
      * @returns Path to the spec file
      */
     async download(options) {
-        const { url, outputPath, headers, timeout = 30000 } = options;
+        const { url, outputPath, headers, timeout = 30000, resolveReferences = false, baseUrl } = options;
+        // Reset downloaded refs tracking for each new download
+        this.downloadedRefs.clear();
         // Check if it's a local file path
         if (this.isLocalFile(url)) {
-            return this.loadLocalFile(url, outputPath);
+            const specPath = await this.loadLocalFile(url, outputPath);
+            if (resolveReferences) {
+                await this.resolveExternalRefs(specPath, headers, timeout, baseUrl || path.dirname(specPath));
+            }
+            return specPath;
         }
         // Otherwise, download from HTTP/HTTPS
         console.log(`Downloading OpenAPI spec from ${url}...`);
@@ -69,25 +79,39 @@ class SpecDownloader {
             }
             // Parse and validate the spec
             let specContent;
+            let parsedSpec;
             if (typeof response.data === 'string') {
-                // Try to parse as JSON to validate
+                // Try to parse as JSON first
                 try {
-                    const parsed = JSON.parse(response.data);
-                    specContent = JSON.stringify(parsed, null, 2);
+                    parsedSpec = JSON.parse(response.data);
+                    specContent = JSON.stringify(parsedSpec, null, 2);
                 }
                 catch {
-                    // If not JSON, might be YAML - save as-is
-                    specContent = response.data;
+                    // If not JSON, try YAML
+                    try {
+                        parsedSpec = yaml.load(response.data);
+                        // Keep YAML format if input was YAML
+                        specContent = response.data;
+                    }
+                    catch {
+                        throw new Error('Failed to parse spec: not valid JSON or YAML');
+                    }
                 }
             }
             else {
+                parsedSpec = response.data;
                 specContent = JSON.stringify(response.data, null, 2);
             }
             // Validate it's an OpenAPI spec
-            this.validateSpec(specContent);
+            this.validateSpec(parsedSpec);
             // Write to file
             fs.writeFileSync(specPath, specContent, 'utf-8');
             console.log(`OpenAPI spec downloaded successfully to ${specPath}`);
+            // Resolve references if requested
+            if (resolveReferences) {
+                const resolvedBaseUrl = baseUrl || this.getBaseUrl(url);
+                await this.resolveExternalRefs(specPath, headers, timeout, resolvedBaseUrl);
+            }
             return specPath;
         }
         catch (error) {
@@ -140,24 +164,29 @@ class SpecDownloader {
         }
         // Read the file
         const content = fs.readFileSync(resolvedPath, 'utf-8');
+        // Parse the content (JSON or YAML)
+        let parsedSpec;
+        try {
+            parsedSpec = JSON.parse(content);
+        }
+        catch {
+            try {
+                parsedSpec = yaml.load(content);
+            }
+            catch {
+                throw new Error(`Failed to parse spec at ${resolvedPath}: not valid JSON or YAML`);
+            }
+        }
         // Validate it's an OpenAPI spec
-        this.validateSpec(content);
+        this.validateSpec(parsedSpec);
         // If outputPath is provided, copy to that location
         if (outputPath) {
             const dir = path.dirname(outputPath);
             if (!fs.existsSync(dir)) {
                 fs.mkdirSync(dir, { recursive: true });
             }
-            // Parse and format if it's JSON
-            let formattedContent = content;
-            try {
-                const parsed = JSON.parse(content);
-                formattedContent = JSON.stringify(parsed, null, 2);
-            }
-            catch {
-                // Not JSON, keep original
-            }
-            fs.writeFileSync(outputPath, formattedContent, 'utf-8');
+            // Keep the original format (JSON or YAML)
+            fs.writeFileSync(outputPath, content, 'utf-8');
             console.log(`OpenAPI spec copied to ${outputPath}`);
             return outputPath;
         }
@@ -175,28 +204,22 @@ class SpecDownloader {
         return path.join(process.cwd(), '.tmp', filename);
     }
     /**
-     * Validate that the downloaded content is an OpenAPI spec
+     * Validate that the parsed content is an OpenAPI spec
      */
-    validateSpec(content) {
-        try {
-            const spec = JSON.parse(content);
-            // Check for OpenAPI version
-            if (!spec.openapi && !spec.swagger) {
-                throw new Error('Invalid OpenAPI spec: missing "openapi" or "swagger" field');
-            }
-            // Check for required fields
-            if (!spec.info) {
-                throw new Error('Invalid OpenAPI spec: missing "info" field');
-            }
-            if (!spec.paths && !spec.components) {
-                throw new Error('Invalid OpenAPI spec: must have either "paths" or "components"');
-            }
+    validateSpec(spec) {
+        if (!spec || typeof spec !== 'object') {
+            throw new Error('Invalid OpenAPI spec: not a valid object');
         }
-        catch (error) {
-            if (error instanceof SyntaxError) {
-                throw new Error('Invalid OpenAPI spec: not valid JSON');
-            }
-            throw error;
+        // Check for OpenAPI version
+        if (!spec.openapi && !spec.swagger) {
+            throw new Error('Invalid OpenAPI spec: missing "openapi" or "swagger" field');
+        }
+        // Check for required fields
+        if (!spec.info) {
+            throw new Error('Invalid OpenAPI spec: missing "info" field');
+        }
+        if (!spec.paths && !spec.components) {
+            throw new Error('Invalid OpenAPI spec: must have either "paths" or "components"');
         }
     }
     /**
@@ -209,5 +232,166 @@ class SpecDownloader {
             console.log('Cleaned up temporary files');
         }
     }
+    /**
+     * Get base URL from a full URL (removes the filename)
+     */
+    getBaseUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            const pathParts = urlObj.pathname.split('/');
+            pathParts.pop(); // Remove filename
+            urlObj.pathname = pathParts.join('/');
+            return urlObj.toString();
+        }
+        catch {
+            // If URL parsing fails, return the original URL
+            return url;
+        }
+    }
+    /**
+     * Resolve and download all external $ref references in the spec
+     */
+    async resolveExternalRefs(specPath, headers, timeout, baseUrl) {
+        console.log('Resolving external references...');
+        const content = fs.readFileSync(specPath, 'utf-8');
+        let spec;
+        try {
+            spec = JSON.parse(content);
+        }
+        catch {
+            try {
+                spec = yaml.load(content);
+            }
+            catch {
+                console.log('Spec is not valid JSON or YAML, skipping reference resolution');
+                return;
+            }
+        }
+        const refs = this.findExternalRefs(spec);
+        if (refs.length === 0) {
+            console.log('No external references found');
+            return;
+        }
+        console.log(`Found ${refs.length} external reference(s)`);
+        const specDir = path.dirname(specPath);
+        const isRemoteSpec = !this.isLocalFile(baseUrl || '');
+        for (const ref of refs) {
+            await this.downloadReference(ref, specDir, baseUrl, isRemoteSpec, headers, timeout);
+        }
+        console.log('All external references resolved successfully');
+    }
+    /**
+     * Find all external $ref values in the spec
+     */
+    findExternalRefs(obj, refs = []) {
+        if (typeof obj !== 'object' || obj === null) {
+            return refs;
+        }
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                this.findExternalRefs(item, refs);
+            }
+            return refs;
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === '$ref' && typeof value === 'string') {
+                // Check if it's an external reference (contains a file path)
+                if (this.isExternalRef(value)) {
+                    // Remove the fragment (#/...) part if present
+                    const refPath = value.split('#')[0];
+                    if (refPath && !refs.includes(refPath)) {
+                        refs.push(refPath);
+                    }
+                }
+            }
+            else {
+                this.findExternalRefs(value, refs);
+            }
+        }
+        return refs;
+    }
+    /**
+     * Check if a $ref is external (references another file)
+     */
+    isExternalRef(ref) {
+        // External refs start with ./ or ../ or / or http:// or https://
+        return (ref.startsWith('./') ||
+            ref.startsWith('../') ||
+            ref.startsWith('http://') ||
+            ref.startsWith('https://') ||
+            (ref.startsWith('/') && !ref.startsWith('/#')));
+    }
+    /**
+     * Download a single reference file
+     */
+    async downloadReference(ref, specDir, baseUrl, isRemoteSpec, headers, timeout) {
+        // Skip if already downloaded
+        if (this.downloadedRefs.has(ref)) {
+            return;
+        }
+        this.downloadedRefs.add(ref);
+        let refUrl;
+        let outputPath;
+        if (isRemoteSpec && baseUrl) {
+            // For remote specs, construct the full URL
+            refUrl = new URL(ref, baseUrl).toString();
+            // Preserve the directory structure in the output
+            const refPath = ref.split('#')[0];
+            outputPath = path.join(specDir, refPath);
+        }
+        else {
+            // For local specs, resolve relative to the spec directory
+            refUrl = ref;
+            outputPath = path.resolve(specDir, ref.split('#')[0]);
+        }
+        console.log(`  - Downloading reference: ${ref}`);
+        try {
+            // Ensure output directory exists
+            const outputDir = path.dirname(outputPath);
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            if (this.isLocalFile(refUrl) && !isRemoteSpec) {
+                // Copy local file
+                const sourcePath = path.resolve(specDir, refUrl.split('#')[0]);
+                if (fs.existsSync(sourcePath)) {
+                    const content = fs.readFileSync(sourcePath, 'utf-8');
+                    fs.writeFileSync(outputPath, content, 'utf-8');
+                    console.log(`    ✓ Copied: ${sourcePath} -> ${outputPath}`);
+                    // Recursively resolve references in the downloaded file
+                    await this.resolveExternalRefs(outputPath, headers, timeout, path.dirname(sourcePath));
+                }
+                else {
+                    console.warn(`    ⚠ Reference file not found: ${sourcePath}`);
+                }
+            }
+            else {
+                // Download from HTTP/HTTPS
+                const response = await axios_1.default.get(refUrl, {
+                    headers,
+                    timeout: timeout || 30000,
+                    responseType: 'text',
+                });
+                let content = response.data;
+                if (typeof content !== 'string') {
+                    content = JSON.stringify(content, null, 2);
+                }
+                fs.writeFileSync(outputPath, content, 'utf-8');
+                console.log(`    ✓ Downloaded: ${refUrl}`);
+                // Recursively resolve references in the downloaded file
+                const refBaseUrl = this.getBaseUrl(refUrl);
+                await this.resolveExternalRefs(outputPath, headers, timeout, refBaseUrl);
+            }
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                console.error(`    ✗ Failed to download ${ref}: ${error.message}`);
+            }
+            else {
+                console.error(`    ✗ Failed to process ${ref}:`, error);
+            }
+            // Continue with other references even if one fails
+        }
+    }
 }
 exports.SpecDownloader = SpecDownloader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,11 +28,13 @@
     "axios": "^1.6.0",
     "class-transformer": "^0.5.1",
     "commander": "^11.0.0",
+    "js-yaml": "^4.1.0",
     "openapi-class-transformer": "^1.0.11",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.0.0",
     "jest": "^29.5.0",
     "ts-jest": "^29.1.0",

package/test-runtime.js

@@ -1,72 +0,0 @@
-var _a, _b, _c;
-import 'reflect-metadata';
-import { plainToInstance } from 'class-transformer';
-import { Capability } from './test-discriminated-output/models/capability.js';
-import { HelmComponent } from './test-discriminated-output/models/helm-component.js';
-import { KustomizeComponent } from './test-discriminated-output/models/kustomize-component.js';
-import { ManifestComponent } from './test-discriminated-output/models/manifest-component.js';
-// Test data with discriminated union
-var plainData = {
-    name: 'my-app',
-    description: 'Application deployment',
-    components: [
-        {
-            type: 'helm',
-            chartName: 'nginx',
-            version: '1.0.0',
-            values: { replicas: 3 }
-        },
-        {
-            type: 'kustomize',
-            path: './overlays/production',
-            namespace: 'prod'
-        },
-        {
-            type: 'manifest',
-            manifests: [
-                'apiVersion: v1\nkind: ConfigMap',
-                'apiVersion: v1\nkind: Service'
-            ]
-        }
-    ]
-};
-console.log('🧪 Testing Discriminated Union Runtime Transformation\n');
-// Transform using plainToInstance
-var capability = plainToInstance(Capability, plainData);
-// Verify instance types
-console.log('✅ Verification Results:');
-console.log('  capability instanceof Capability:', capability instanceof Capability);
-console.log('  capability.name:', capability.name);
-console.log('  capability.components.length:', capability.components.length);
-console.log('');
-console.log('✅ Component Type Verification:');
-console.log('  components[0] instanceof HelmComponent:', capability.components[0] instanceof HelmComponent);
-console.log('  components[1] instanceof KustomizeComponent:', capability.components[1] instanceof KustomizeComponent);
-console.log('  components[2] instanceof ManifestComponent:', capability.components[2] instanceof ManifestComponent);
-console.log('');
-console.log('✅ Property Access:');
-console.log('  HelmComponent.chartName:', capability.components[0].chartName);
-console.log('  KustomizeComponent.path:', capability.components[1].path);
-console.log('  ManifestComponent.manifests.length:', (_a = capability.components[2].manifests) === null || _a === void 0 ? void 0 : _a.length);
-console.log('');
-console.log('✅ attributeTypeMap Check:');
-var componentsMetadata = Capability.attributeTypeMap.find(function (m) { return m.name === 'components'; });
-console.log('  type:', componentsMetadata === null || componentsMetadata === void 0 ? void 0 : componentsMetadata.type);
-console.log('  modelClasses:', (_b = componentsMetadata === null || componentsMetadata === void 0 ? void 0 : componentsMetadata.modelClasses) === null || _b === void 0 ? void 0 : _b.map(function (c) { return c.name; }));
-console.log('  discriminatorProperty:', componentsMetadata === null || componentsMetadata === void 0 ? void 0 : componentsMetadata.discriminatorProperty);
-console.log('');
-// Final verification
-var allCorrect = capability instanceof Capability &&
-    capability.components[0] instanceof HelmComponent &&
-    capability.components[1] instanceof KustomizeComponent &&
-    capability.components[2] instanceof ManifestComponent &&
-    capability.components[0].chartName === 'nginx' &&
-    capability.components[1].path === './overlays/production' &&
-    ((_c = capability.components[2].manifests) === null || _c === void 0 ? void 0 : _c.length) === 2;
-if (allCorrect) {
-    console.log('🎉 SUCCESS! All discriminated union transformations working correctly!');
-}
-else {
-    console.log('❌ FAILED! Some transformations did not work as expected.');
-    process.exit(1);
-}

package/test-runtime.ts

@@ -1,80 +0,0 @@
-import 'reflect-metadata';
-import { plainToInstance } from 'class-transformer';
-import { Capability } from './test-discriminated-output/models/capability.js';
-import { HelmComponent } from './test-discriminated-output/models/helm-component.js';
-import { KustomizeComponent } from './test-discriminated-output/models/kustomize-component.js';
-import { ManifestComponent } from './test-discriminated-output/models/manifest-component.js';
-
-// Test data with discriminated union
-const plainData = {
-    name: 'my-app',
-    description: 'Application deployment',
-    components: [
-        {
-            type: 'helm',
-            chartName: 'nginx',
-            version: '1.0.0',
-            values: { replicas: 3 }
-        },
-        {
-            type: 'kustomize',
-            path: './overlays/production',
-            namespace: 'prod'
-        },
-        {
-            type: 'manifest',
-            manifests: [
-              'apiVersion: v1\nkind: ConfigMap',
-              'apiVersion: v1\nkind: Service'
-            ]
-        }
-    ]
-};
-
-console.log('🧪 Testing Discriminated Union Runtime Transformation\n');
-
-// Transform using plainToInstance
-const capability = plainToInstance(Capability, plainData);
-
-// Verify instance types
-console.log('✅ Verification Results:');
-console.log('  capability instanceof Capability:', capability instanceof Capability);
-console.log('  capability.name:', capability.name);
-console.log('  capability.components.length:', capability.components.length);
-console.log('');
-
-console.log('✅ Component Type Verification:');
-console.log('  components[0] instanceof HelmComponent:', capability.components[0] instanceof HelmComponent);
-console.log('  components[1] instanceof KustomizeComponent:', capability.components[1] instanceof KustomizeComponent);
-console.log('  components[2] instanceof ManifestComponent:', capability.components[2] instanceof ManifestComponent);
-console.log('');
-
-console.log('✅ Property Access:');
-console.log('  HelmComponent.chartName:', (capability.components[0] as HelmComponent).chartName);
-console.log('  KustomizeComponent.path:', (capability.components[1] as KustomizeComponent).path);
-console.log('  ManifestComponent.manifests.length:', (capability.components[2] as ManifestComponent).manifests?.length);
-console.log('');
-
-console.log('✅ attributeTypeMap Check:');
-const componentsMetadata = Capability.attributeTypeMap.find(m => m.name === 'components');
-console.log('  type:', componentsMetadata?.type);
-console.log('  modelClasses:', (componentsMetadata as any)?.modelClasses?.map((c: any) => c.name));
-console.log('  discriminatorProperty:', (componentsMetadata as any)?.discriminatorProperty);
-console.log('');
-
-// Final verification
-const allCorrect =
-    capability instanceof Capability &&
-    capability.components[0] instanceof HelmComponent &&
-    capability.components[1] instanceof KustomizeComponent &&
-    capability.components[2] instanceof ManifestComponent &&
-    (capability.components[0] as HelmComponent).chartName === 'nginx' &&
-    (capability.components[1] as KustomizeComponent).path === './overlays/production' &&
-    (capability.components[2] as ManifestComponent).manifests?.length === 2;
-
-if (allCorrect) {
-    console.log('🎉 SUCCESS! All discriminated union transformations working correctly!');
-} else {
-    console.log('❌ FAILED! Some transformations did not work as expected.');
-    process.exit(1);
-}