klasik 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# klasik
+
+Download OpenAPI specifications from remote URLs and generate TypeScript clients with class-transformer support for Kubernetes and other APIs.
+
+## Features
+
+- 📥 **Download OpenAPI specs** from remote URLs or local files
+- 📁 **Multiple input formats** - HTTP/HTTPS URLs, file:// URLs, absolute/relative paths
+- 🔄 **Automatic transformation** - Converts API responses to class instances using class-transformer
+- 🎯 **Type-safe** - Full TypeScript support with decorators
+- 🛠️ **Configurable** - Custom headers, timeouts, and templates
+- 🧪 **Well-tested** - Comprehensive test coverage (11 tests passing)
+- 📦 **Easy to use** - Simple CLI and programmatic API
+
+## Installation
+
+```bash
+npm install klasik
+```
+
+## Quick Start
+
+### CLI Usage
+
+Generate a TypeScript client from a remote OpenAPI spec:
+
+```bash
+npx klasik generate \
+  --url https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json \
+  --output ./k8s-client
+```
+
+Generate from a local OpenAPI spec file:
+
+```bash
+# Absolute path
+npx klasik generate \
+  --url /path/to/openapi.json \
+  --output ./client
+
+# Relative path
+npx klasik generate \
+  --url ./specs/openapi.json \
+  --output ./client
+
+# file:// URL
+npx klasik generate \
+  --url file:///path/to/openapi.json \
+  --output ./client
+```
+
+Download an OpenAPI spec without generating:
+
+```bash
+npx klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json
+```
+
+### Programmatic Usage
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json',
+  outputDir: './k8s-client',
+});
+```
+
+## CLI Commands
+
+### `generate`
+
+Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
+
+**Options:**
+- `-u, --url <url>` - URL or file path to the OpenAPI spec (required)
+  - 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")
+- `-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)
+
+**Examples:**
+
+```bash
+# From remote URL
+klasik generate \
+  --url https://api.example.com/openapi.json \
+  --output ./client \
+  --header "Authorization: Bearer token123" \
+  --timeout 60000
+
+# From local file
+klasik generate \
+  --url ./my-spec.json \
+  --output ./client
+
+# From file:// URL
+klasik generate \
+  --url file:///Users/me/specs/api.json \
+  --output ./client
+```
+
+### `download`
+
+Download an OpenAPI spec from a remote URL without generating code.
+
+**Options:**
+- `-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
+- `--timeout <ms>` - Request timeout in milliseconds (default: 30000)
+
+**Example:**
+
+```bash
+klasik download \
+  --url https://api.example.com/openapi.json \
+  --output ./specs/api-spec.json \
+  --header "Authorization: Bearer token123"
+```
+
+## Programmatic API
+
+### K8sClientGenerator
+
+```typescript
+import { K8sClientGenerator } from 'klasik';
+
+const generator = new K8sClientGenerator();
+
+await generator.generate({
+  specUrl: 'https://api.example.com/openapi.json',
+  outputDir: './client',
+  headers: {
+    'Authorization': 'Bearer token123',
+    'X-Custom-Header': 'value'
+  },
+  templateDir: './custom-templates', // Optional
+  keepSpec: true, // Keep downloaded spec file
+  timeout: 60000 // Request timeout in ms
+});
+```
+
+### SpecDownloader
+
+```typescript
+import { SpecDownloader } from 'klasik';
+
+const downloader = new SpecDownloader();
+
+const specPath = await downloader.download({
+  url: 'https://api.example.com/openapi.json',
+  outputPath: './specs/api-spec.json',
+  headers: {
+    'Authorization': 'Bearer token123'
+  },
+  timeout: 30000
+});
+
+console.log(`Spec downloaded to: ${specPath}`);
+
+// Clean up temporary files
+downloader.cleanupTemp();
+```
+
+## Generated Client Features
+
+The generated TypeScript client includes:
+
+- ✅ **Class-transformer decorators** - `@Expose()` and `@Type()` on all models
+- ✅ **Automatic response transformation** - API responses converted to class instances
+- ✅ **Runtime type metadata** - Static `attributeTypeMap` on all models
+- ✅ **Union type support** - `anyOf` schemas become TypeScript unions
+- ✅ **Vendor extensions** - Preserved in JSDoc comments and metadata
+- ✅ **Error handling** - Configurable transformation error handlers
+- ✅ **Configuration options** - Enable/disable transformation, custom error handlers
+
+### Example Generated Model
+
+```typescript
+import { Expose, Type } from 'class-transformer';
+
+export class User {
+    @Expose()
+    'id': string;
+
+    @Expose()
+    'name': string;
+
+    @Expose()
+    @Type(() => Profile)
+    'profile'?: Profile;
+
+    static readonly attributeTypeMap = [
+        {
+            "name": "id",
+            "baseName": "id",
+            "type": "string",
+            "format": "",
+            "description": "User ID",
+            "vendorExtensions": {}
+        },
+        // ... more properties
+    ];
+}
+```
+
+### Using the Generated Client
+
+```typescript
+import { DefaultApi, Configuration } from './generated-client';
+import { plainToInstance } from 'class-transformer';
+
+// Create API client
+const config = new Configuration({
+    basePath: 'https://api.example.com',
+    enableResponseTransformation: true, // Default
+    onTransformationError: (error, modelClass, data) => {
+        console.error('Transformation failed:', error);
+    }
+});
+
+const api = new DefaultApi(config);
+
+// Get user - response is automatically transformed to User class instance
+const response = await api.getUserById({ id: '123' });
+const user = response.data; // user is instanceof User ✅
+
+console.log(user.name); // Fully typed!
+```
+
+## Advanced Configuration
+
+### Custom Error Handling
+
+```typescript
+const config = new Configuration({
+    basePath: 'https://api.example.com',
+    onTransformationError: (error, modelClass, data) => {
+        // Log to custom logger
+        logger.error('Failed to transform response', {
+            error: error.message,
+            modelClass: modelClass.name,
+            rawData: data
+        });
+
+        // Send to error tracking
+        Sentry.captureException(error);
+    }
+});
+```
+
+### Disable Transformation
+
+```typescript
+const config = new Configuration({
+    basePath: 'https://api.example.com',
+    enableResponseTransformation: false // Get plain objects
+});
+```
+
+## Requirements
+
+- Node.js >= 16
+- TypeScript >= 5.0 (for experimentalDecorators support)
+
+### TypeScript Configuration
+
+Your `tsconfig.json` must include:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT
+
+## Related Projects
+
+- [openapi-class-transformer](https://github.com/example/openapi-class-transformer) - The underlying generator used by this package
+- [class-transformer](https://github.com/typestack/class-transformer) - Transformation library
+- [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) - OpenAPI code generator
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const k8s_client_generator_1 = require("./k8s-client-generator");
+const path = __importStar(require("path"));
+const program = new commander_1.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 = {};
+        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 k8s_client_generator_1.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 Promise.resolve().then(() => __importStar(require('./spec-downloader')));
+        // Parse headers if provided
+        const headers = {};
+        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/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecDownloader = exports.K8sClientGenerator = void 0;
+var k8s_client_generator_1 = require("./k8s-client-generator");
+Object.defineProperty(exports, "K8sClientGenerator", { enumerable: true, get: function () { return k8s_client_generator_1.K8sClientGenerator; } });
+var spec_downloader_1 = require("./spec-downloader");
+Object.defineProperty(exports, "SpecDownloader", { enumerable: true, get: function () { return spec_downloader_1.SpecDownloader; } });

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

@@ -0,0 +1,52 @@
+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 declare class K8sClientGenerator {
+    private downloader;
+    constructor();
+    /**
+     * Generate TypeScript client from a remote OpenAPI spec URL
+     */
+    generate(options: K8sClientGeneratorOptions): Promise<void>;
+    /**
+     * Prepare the output directory
+     */
+    private prepareOutputDirectory;
+    /**
+     * Clean up the downloaded spec file
+     */
+    private cleanupSpecFile;
+}

package/dist/k8s-client-generator.js

@@ -0,0 +1,119 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.K8sClientGenerator = void 0;
+const openapi_class_transformer_1 = require("openapi-class-transformer");
+const spec_downloader_1 = require("./spec-downloader");
+const fs = __importStar(require("fs"));
+class K8sClientGenerator {
+    constructor() {
+        this.downloader = new spec_downloader_1.SpecDownloader();
+    }
+    /**
+     * Generate TypeScript client from a remote OpenAPI spec URL
+     */
+    async generate(options) {
+        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, timeout, } = options;
+        let specPath;
+        try {
+            // Step 1: Download the OpenAPI spec
+            console.log('Step 1: Downloading OpenAPI specification...');
+            const 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 = {
+                inputSpec: specPath,
+                outputDir,
+                modelsOnly: mode === 'models-only',
+            };
+            // Only add templateDir if it's provided
+            if (templateDir) {
+                generatorOptions.templateDir = templateDir;
+            }
+            const generator = new openapi_class_transformer_1.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
+     */
+    prepareOutputDirectory(outputDir) {
+        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
+     */
+    cleanupSpecFile(specPath) {
+        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);
+        }
+    }
+}
+exports.K8sClientGenerator = K8sClientGenerator;

package/dist/spec-downloader.d.ts

@@ -0,0 +1,53 @@
+export interface DownloadOptions {
+    /**
+     * URL or file path to the OpenAPI spec
+     * Supports:
+     * - HTTP/HTTPS URLs: https://example.com/spec.json
+     * - File URLs: file:///path/to/spec.json
+     * - Absolute paths: /path/to/spec.json
+     * - Relative paths: ./spec.json, ../specs/api.json
+     */
+    url: string;
+    /**
+     * Optional output path to save the downloaded spec
+     * If not provided, will save to a temp file (for HTTP) or use the source path (for files)
+     */
+    outputPath?: string;
+    /**
+     * Optional headers to include in the request (only used for HTTP/HTTPS)
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds (only used for HTTP/HTTPS)
+     * @default 30000
+     */
+    timeout?: number;
+}
+export declare 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
+     */
+    download(options: DownloadOptions): Promise<string>;
+    /**
+     * Check if the URL is a local file path
+     */
+    private isLocalFile;
+    /**
+     * Load and validate an OpenAPI spec from a local file
+     */
+    private loadLocalFile;
+    /**
+     * Generate a temporary file path based on the URL
+     */
+    private generateTempPath;
+    /**
+     * Validate that the downloaded content is an OpenAPI spec
+     */
+    private validateSpec;
+    /**
+     * Clean up temporary files
+     */
+    cleanupTemp(): void;
+}