klasik 1.0.0

package/dist/spec-downloader.js

@@ -0,0 +1,213 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecDownloader = void 0;
+const axios_1 = __importDefault(require("axios"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class SpecDownloader {
+    /**
+     * 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;
+        // Check if it's a local file path
+        if (this.isLocalFile(url)) {
+            return this.loadLocalFile(url, outputPath);
+        }
+        // Otherwise, download from HTTP/HTTPS
+        console.log(`Downloading OpenAPI spec from ${url}...`);
+        try {
+            const response = await axios_1.default.get(url, {
+                headers,
+                timeout,
+                responseType: 'text',
+            });
+            // Determine output path
+            const specPath = outputPath || this.generateTempPath(url);
+            // Ensure directory exists
+            const dir = path.dirname(specPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Parse and validate the spec
+            let specContent;
+            if (typeof response.data === 'string') {
+                // Try to parse as JSON to validate
+                try {
+                    const parsed = JSON.parse(response.data);
+                    specContent = JSON.stringify(parsed, null, 2);
+                }
+                catch {
+                    // If not JSON, might be YAML - save as-is
+                    specContent = response.data;
+                }
+            }
+            else {
+                specContent = JSON.stringify(response.data, null, 2);
+            }
+            // Validate it's an OpenAPI spec
+            this.validateSpec(specContent);
+            // Write to file
+            fs.writeFileSync(specPath, specContent, 'utf-8');
+            console.log(`OpenAPI spec downloaded successfully to ${specPath}`);
+            return specPath;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                throw new Error(`Failed to download OpenAPI spec from ${url}: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if the URL is a local file path
+     */
+    isLocalFile(url) {
+        // Check for file:// protocol
+        if (url.startsWith('file://')) {
+            return true;
+        }
+        // Check for HTTP/HTTPS protocols
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            return false;
+        }
+        // Check if it's an absolute or relative path
+        // Absolute paths start with / (Unix) or C:\ (Windows)
+        // Relative paths start with ./ or ../
+        return (url.startsWith('/') ||
+            url.startsWith('./') ||
+            url.startsWith('../') ||
+            /^[a-zA-Z]:[\\\/]/.test(url) // Windows paths like C:\
+        );
+    }
+    /**
+     * Load and validate an OpenAPI spec from a local file
+     */
+    loadLocalFile(filePath, outputPath) {
+        // Handle file:// URLs
+        let resolvedPath = filePath;
+        if (filePath.startsWith('file://')) {
+            resolvedPath = filePath.replace('file://', '');
+            // On Windows, file URLs might be file:///C:/path
+            if (process.platform === 'win32' && resolvedPath.startsWith('/')) {
+                resolvedPath = resolvedPath.substring(1);
+            }
+        }
+        // Resolve to absolute path
+        resolvedPath = path.resolve(resolvedPath);
+        console.log(`Loading OpenAPI spec from local file: ${resolvedPath}...`);
+        // Check if file exists
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`File not found: ${resolvedPath}`);
+        }
+        // Read the file
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        // Validate it's an OpenAPI spec
+        this.validateSpec(content);
+        // 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');
+            console.log(`OpenAPI spec copied to ${outputPath}`);
+            return outputPath;
+        }
+        console.log(`OpenAPI spec loaded successfully from ${resolvedPath}`);
+        return resolvedPath;
+    }
+    /**
+     * Generate a temporary file path based on the URL
+     */
+    generateTempPath(url) {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname.replace(/\./g, '-');
+        const timestamp = Date.now();
+        const filename = `openapi-${hostname}-${timestamp}.json`;
+        return path.join(process.cwd(), '.tmp', filename);
+    }
+    /**
+     * Validate that the downloaded 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"');
+            }
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error('Invalid OpenAPI spec: not valid JSON');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Clean up temporary files
+     */
+    cleanupTemp() {
+        const tempDir = path.join(process.cwd(), '.tmp');
+        if (fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+            console.log('Cleaned up temporary files');
+        }
+    }
+}
+exports.SpecDownloader = SpecDownloader;

package/example.md

@@ -0,0 +1,139 @@
+# Example Usage
+
+## Using klasik with a Real API
+
+### Example 1: Generate client from Kubernetes OpenAPI spec
+
+```bash
+# Download and generate TypeScript client
+npx klasik generate \
+  --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json \
+  --output ./kubernetes-client
+```
+
+### Example 2: Generate client with authentication
+
+```bash
+# Generate client with custom headers
+npx klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./api-client \
+  --header "Authorization: Bearer YOUR_TOKEN" \
+  --header "X-API-Key: YOUR_KEY"
+```
+
+### Example 3: Programmatic usage
+
+Create a file `generate-client.ts`:
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+async function generateClient() {
+  const generator = new K8sClientGenerator();
+
+  await generator.generate({
+    specUrl: 'https://petstore3.swagger.io/api/v3/openapi.json',
+    outputDir: './petstore-client',
+    keepSpec: true, // Keep the downloaded spec for reference
+  });
+
+  console.log('✅ Client generated successfully!');
+}
+
+generateClient().catch(console.error);
+```
+
+Run it:
+
+```bash
+npx ts-node generate-client.ts
+```
+
+### Example 4: Using the generated client
+
+After generating the client, you can use it like this:
+
+```typescript
+import { DefaultApi, Configuration } from './petstore-client';
+
+async function main() {
+  // Create configuration
+  const config = new Configuration({
+    basePath: 'https://petstore3.swagger.io/api/v3',
+    enableResponseTransformation: true,
+    onTransformationError: (error, modelClass, data) => {
+      console.error('Transformation error:', error.message);
+      console.error('Model:', modelClass.name);
+    }
+  });
+
+  // Create API client
+  const api = new DefaultApi(config);
+
+  // Make API calls - responses are automatically transformed to class instances!
+  const response = await api.findPetsByStatus({ status: ['available'] });
+  const pets = response.data; // Array of Pet class instances
+
+  pets.forEach(pet => {
+    console.log(`Pet: ${pet.name}, ID: ${pet.id}`);
+    // pet is instanceof Pet, with all decorators applied!
+  });
+}
+
+main().catch(console.error);
+```
+
+## Testing Locally
+
+To test the package locally with the linked `openapi-class-transformer`:
+
+```bash
+# In openapi-class-transformer directory
+cd /Users/eyald/koalaops/openapi-class-transformer
+npm link
+
+# In klasik directory
+cd /Users/eyald/koalaops/klasik
+npm link openapi-class-transformer
+
+# Build and test
+npm run build
+npm test
+
+# Try generating a client
+node dist/cli.js generate \
+  --url https://petstore3.swagger.io/api/v3/openapi.json \
+  --output ./test-client
+```
+
+## What Gets Generated?
+
+When you run the generator, you'll get:
+
+```
+./output-directory/
+├── api/
+│   └── default-api.ts          # API client with methods
+├── models/
+│   ├── index.ts                # Model exports
+│   ├── pet.ts                  # Pet model with decorators
+│   ├── category.ts             # Category model
+│   └── ...                     # Other models
+├── base.ts                     # Base API classes
+├── common.ts                   # Common utilities
+├── configuration.ts            # Configuration class (with transformation options!)
+└── index.ts                    # Main exports
+```
+
+Each model will have:
+- ✅ `@Expose()` decorators on all properties
+- ✅ `@Type()` decorators for nested objects
+- ✅ Static `attributeTypeMap` for runtime metadata
+- ✅ Vendor extensions in JSDoc comments
+- ✅ Union types for `anyOf` schemas
+
+Each API method will:
+- ✅ Automatically transform responses to class instances
+- ✅ Handle transformation errors gracefully
+- ✅ Support configuration options for enabling/disabling transformation

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/test'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+  ],
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "klasik",
+  "version": "1.0.0",
+  "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "klasik": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "openapi",
+    "kubernetes",
+    "k8s",
+    "typescript",
+    "class-transformer",
+    "api-client",
+    "generator"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0",
+    "commander": "^11.0.0",
+    "openapi-class-transformer": "file:../openapi-class-transformer"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { K8sClientGenerator } from './k8s-client-generator';
+import * as path from 'path';
+
+const program = new Command();
+
+program
+  .name('klasik')
+  .description('Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support')
+  .version('1.0.0');
+
+program
+  .command('generate')
+  .description('Generate TypeScript client from a remote OpenAPI spec')
+  .requiredOption('-u, --url <url>', 'Remote URL to download the OpenAPI spec from')
+  .requiredOption('-o, --output <dir>', 'Output directory for generated client code')
+  .option('-m, --mode <mode>', 'Generation mode: "full" (models + APIs + config) or "models-only"', 'full')
+  .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('--timeout <ms>', 'Request timeout in milliseconds', '30000')
+  .action(async (options) => {
+    try {
+      // Validate mode
+      if (options.mode !== 'full' && options.mode !== 'models-only') {
+        console.error('Error: --mode must be either "full" or "models-only"');
+        process.exit(1);
+      }
+
+      // Parse headers if provided
+      const headers: Record<string, string> = {};
+      if (options.header) {
+        for (const header of options.header) {
+          const [key, ...valueParts] = header.split(':');
+          const value = valueParts.join(':').trim();
+          if (key && value) {
+            headers[key.trim()] = value;
+          }
+        }
+      }
+
+      // Resolve output directory to absolute path
+      const outputDir = path.resolve(options.output);
+
+      const generator = new K8sClientGenerator();
+      await generator.generate({
+        specUrl: options.url,
+        outputDir,
+        mode: options.mode,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        templateDir: options.template,
+        keepSpec: options.keepSpec,
+        timeout: parseInt(options.timeout, 10),
+      });
+
+      process.exit(0);
+    } catch (error) {
+      console.error('Error:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('download')
+  .description('Download an OpenAPI spec from a remote URL (without generating)')
+  .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('--timeout <ms>', 'Request timeout in milliseconds', '30000')
+  .action(async (options) => {
+    try {
+      const { SpecDownloader } = await import('./spec-downloader');
+
+      // Parse headers if provided
+      const headers: Record<string, string> = {};
+      if (options.header) {
+        for (const header of options.header) {
+          const [key, ...valueParts] = header.split(':');
+          const value = valueParts.join(':').trim();
+          if (key && value) {
+            headers[key.trim()] = value;
+          }
+        }
+      }
+
+      const downloader = new SpecDownloader();
+      await downloader.download({
+        url: options.url,
+        outputPath: path.resolve(options.output),
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        timeout: parseInt(options.timeout, 10),
+      });
+
+      process.exit(0);
+    } catch (error) {
+      console.error('Error:', error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/index.ts

@@ -0,0 +1,2 @@
+export { K8sClientGenerator, K8sClientGeneratorOptions, GenerationMode } from './k8s-client-generator';
+export { SpecDownloader, DownloadOptions } from './spec-downloader';

package/src/k8s-client-generator.ts

@@ -0,0 +1,145 @@
+import { Generator, GeneratorOptions } from 'openapi-class-transformer';
+import { SpecDownloader, DownloadOptions } from './spec-downloader';
+import * as fs from 'fs';
+
+export type GenerationMode = 'full' | 'models-only';
+
+export interface K8sClientGeneratorOptions {
+  /**
+   * Remote URL to download the OpenAPI spec from
+   */
+  specUrl: string;
+
+  /**
+   * Output directory for generated client code
+   */
+  outputDir: string;
+
+  /**
+   * Generation mode
+   * - 'full': Generate models, APIs, and configuration (default)
+   * - 'models-only': Generate only model classes
+   * @default 'full'
+   */
+  mode?: GenerationMode;
+
+  /**
+   * Optional headers to include in the spec download request
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Optional custom template directory
+   */
+  templateDir?: string;
+
+  /**
+   * Whether to keep the downloaded spec file after generation
+   * @default false
+   */
+  keepSpec?: boolean;
+
+  /**
+   * Request timeout for downloading spec in milliseconds
+   * @default 30000
+   */
+  timeout?: number;
+}
+
+export class K8sClientGenerator {
+  private downloader: SpecDownloader;
+
+  constructor() {
+    this.downloader = new SpecDownloader();
+  }
+
+  /**
+   * Generate TypeScript client from a remote OpenAPI spec URL
+   */
+  async generate(options: K8sClientGeneratorOptions): Promise<void> {
+    const {
+      specUrl,
+      outputDir,
+      mode = 'full',
+      headers,
+      templateDir,
+      keepSpec = false,
+      timeout,
+    } = options;
+
+    let specPath: string | undefined;
+
+    try {
+      // Step 1: Download the OpenAPI spec
+      console.log('Step 1: Downloading OpenAPI specification...');
+      const downloadOptions: DownloadOptions = {
+        url: specUrl,
+        headers,
+        timeout,
+      };
+
+      specPath = await this.downloader.download(downloadOptions);
+
+      // Step 2: Validate output directory
+      console.log('Step 2: Preparing output directory...');
+      this.prepareOutputDirectory(outputDir);
+
+      // Step 3: Generate client using openapi-class-transformer
+      const modeLabel = mode === 'models-only' ? 'models only' : 'full client';
+      console.log(`Step 3: Generating TypeScript ${modeLabel}...`);
+      const generatorOptions: GeneratorOptions = {
+        inputSpec: specPath,
+        outputDir,
+        modelsOnly: mode === 'models-only',
+      };
+
+      // Only add templateDir if it's provided
+      if (templateDir) {
+        generatorOptions.templateDir = templateDir;
+      }
+
+      const generator = new Generator(generatorOptions);
+      await generator.generate();
+
+      console.log('✅ Client generation completed successfully!');
+      console.log(`📁 Generated files location: ${outputDir}`);
+    } catch (error) {
+      console.error('❌ Client generation failed:', error);
+      throw error;
+    } finally {
+      // Cleanup
+      if (!keepSpec && specPath) {
+        this.cleanupSpecFile(specPath);
+      }
+    }
+  }
+
+  /**
+   * Prepare the output directory
+   */
+  private prepareOutputDirectory(outputDir: string): void {
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+      console.log(`Created output directory: ${outputDir}`);
+    } else {
+      console.log(`Using existing output directory: ${outputDir}`);
+    }
+  }
+
+  /**
+   * Clean up the downloaded spec file
+   */
+  private cleanupSpecFile(specPath: string): void {
+    try {
+      if (fs.existsSync(specPath)) {
+        fs.unlinkSync(specPath);
+        console.log(`Cleaned up downloaded spec file: ${specPath}`);
+      }
+
+      // Also cleanup temp directory if empty
+      this.downloader.cleanupTemp();
+    } catch (error) {
+      console.warn('Warning: Failed to cleanup spec file:', error);
+    }
+  }
+}