mulink 1.1.8 → 1.2.0

package/dist/lib/{version-checker-uF6o5ziX.d.cts → version-checker-DU88tpi8.d.cts}

@@ -324,22 +324,66 @@ interface FileMetadata {
     imports: string[];
     dependencies: string[];
 }
+/**
+ * Base error class for all Mulink errors
+ *
+ * Follows best practices similar to Apollo Client's error handling.
+ * Provides structured error information with error codes and details.
+ *
+ * @public
+ */
 declare class BridgeError extends Error {
     readonly code: string;
     readonly details?: unknown;
-    constructor(message: string, code: string, details?: unknown);
+    readonly timestamp: number;
+    readonly cause?: Error;
+    constructor(message: string, code: string, details?: unknown, cause?: Error);
+    /**
+     * Converts the error to a JSON-serializable object
+     *
+     * @returns JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Checks if this error is retryable
+     *
+     * @returns True if the operation that caused this error can be retried
+     */
+    isRetryable(): boolean;
 }
+/**
+ * Error thrown when configuration validation fails
+ *
+ * Contains Zod validation errors for detailed feedback.
+ */
 declare class ValidationError extends BridgeError {
     readonly errors: z.ZodError;
-    constructor(message: string, errors: z.ZodError);
+    constructor(message: string, errors: z.ZodError, cause?: Error);
+    /**
+     * Gets formatted validation error messages
+     *
+     * @returns Array of formatted error messages
+     */
+    getFormattedErrors(): string[];
 }
+/**
+ * Error thrown when OpenAPI schema parsing fails
+ *
+ * Contains the schema URL that failed to parse.
+ */
 declare class SchemaParseError extends BridgeError {
     readonly schemaUrl: string;
-    constructor(message: string, schemaUrl: string);
+    constructor(message: string, schemaUrl: string, cause?: Error);
+    isRetryable(): boolean;
 }
+/**
+ * Error thrown when code generation fails
+ *
+ * Contains the file path where generation failed, if applicable.
+ */
 declare class GenerationError extends BridgeError {
     readonly file?: string;
-    constructor(message: string, file?: string);
+    constructor(message: string, file?: string, cause?: Error);
 }
 interface BridgePlugin {
     name: string;
@@ -403,23 +447,119 @@ interface StreamingResponse<T = any> {
     controller: AbortController;
 }
 
+/**
+ * Core class for the Mulink library
+ *
+ * This class orchestrates the entire code generation process from OpenAPI schemas
+ * to production-ready Next.js 16.0.7 code. It follows best practices similar to
+ * Apollo Client and other enterprise-grade libraries.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new BridgeCore();
+ * await bridge.generate(configuration);
+ * ```
+ *
+ * @public
+ */
 declare class BridgeCore {
     private readonly logger;
     private readonly schemaParser;
     private readonly fileManager;
+    /**
+     * Creates a new instance of BridgeCore
+     *
+     * Initializes all required dependencies including logger, schema parser, and file manager.
+     * All dependencies are readonly to ensure immutability and thread safety.
+     */
     constructor();
+    /**
+     * Generates type-safe API client code from OpenAPI schema
+     *
+     * This is the main entry point for code generation. It validates the configuration,
+     * parses the OpenAPI schema, generates all necessary files, and writes them to disk.
+     *
+     * The generated code follows Next.js 16.0.7 best practices including:
+     * - Server Actions with type safety
+     * - React Query hooks with proper caching
+     * - Middleware support
+     * - Error handling
+     * - Cache tag management
+     *
+     * @param configuration - The bridge configuration containing schema URL, output directory, and framework settings
+     * @returns Promise that resolves when generation is complete
+     * @throws {ValidationError} When configuration is invalid
+     * @throws {SchemaParseError} When OpenAPI schema cannot be parsed
+     * @throws {GenerationError} When code generation fails
+     *
+     * @example
+     * ```typescript
+     * const config: BridgeConfiguration = {
+     *   schema: 'https://api.example.com/openapi.json',
+     *   outputDir: 'src/generated',
+     *   framework: { type: 'nextjs', router: 'app', features: {...} },
+     *   api: { baseUrl: 'https://api.example.com', timeout: 30000, retries: 3 }
+     * };
+     * await bridge.generate(config);
+     * ```
+     */
     generate(configuration: BridgeConfiguration): Promise<void>;
     private validateConfiguration;
     private generateFiles;
     private writeFiles;
     private logGenerationSummary;
+    /**
+     * Validates an OpenAPI schema without generating code
+     *
+     * Useful for checking schema validity before running full generation.
+     *
+     * @param schemaUrl - URL or file path to the OpenAPI schema
+     * @returns Promise resolving to true if schema is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isValid = await bridge.validateSchema('https://api.example.com/openapi.json');
+     * if (isValid) {
+     *   await bridge.generate(config);
+     * }
+     * ```
+     */
     validateSchema(schemaUrl: string): Promise<boolean>;
+    /**
+     * Retrieves metadata from an OpenAPI schema
+     *
+     * Extracts schema metadata including title, version, description, and other
+     * OpenAPI document information without parsing the entire schema.
+     *
+     * @param schemaUrl - URL or file path to the OpenAPI schema
+     * @returns Promise resolving to schema metadata
+     * @throws {BridgeError} When schema URL is invalid
+     * @throws {SchemaParseError} When schema cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const metadata = await bridge.getSchemaInfo('https://api.example.com/openapi.json');
+     * console.log(`Schema: ${metadata.title} v${metadata.version}`);
+     * ```
+     */
     getSchemaInfo(schemaUrl: string): Promise<ParsedApiSchema['metadata']>;
+    /**
+     * Clears the internal schema cache
+     *
+     * Useful when you need to force re-fetching of schemas or during development.
+     * The cache is automatically managed, but this method allows manual invalidation.
+     *
+     * @example
+     * ```typescript
+     * bridge.clearCache();
+     * await bridge.generate(config); // Will fetch fresh schema
+     * ```
+     */
     clearCache(): void;
 }
 
 declare class OpenApiSchemaParser {
-    private schemaCache;
+    private readonly schemaCache;
     parse(schemaUrl: string): Promise<ParsedApiSchema>;
     private fetchSchema;
     private parseDocument;
@@ -443,7 +583,7 @@ declare class OpenApiSchemaParser {
 
 declare class ConfigurationLoader {
     load(configPath?: string): Promise<BridgeConfiguration>;
-    createDefault(framework?: 'nextjs'): Promise<BridgeConfiguration>;
+    createDefault(framework?: 'nextjs'): BridgeConfiguration;
     save(config: BridgeConfiguration, configPath?: string): Promise<void>;
 }
 
@@ -498,10 +638,10 @@ interface VersionInfo {
 }
 type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'unknown';
 declare class VersionChecker {
-    private logger;
-    private packageName;
-    private currentVersion;
-    private cache;
+    private readonly logger;
+    private readonly packageName;
+    private readonly currentVersion;
+    private readonly cache;
     private readonly CACHE_DURATION;
     constructor(packageName: string, currentVersion: string, logger?: BridgeLogger);
     /**
@@ -515,7 +655,7 @@ declare class VersionChecker {
     /**
      * Get the appropriate upgrade command for the detected package manager
      */
-    getUpgradeCommand(versionInfo: VersionInfo): string;
+    getUpgradeCommand(_versionInfo: VersionInfo): string;
     /**
      * Get a user-friendly update message
      */
@@ -575,4 +715,4 @@ declare function checkAndNotifyUpdates(options?: {
     logger?: BridgeLogger;
 }): Promise<VersionInfo | null>;
 
-export { type ApiConfiguration as A, type BridgeConfiguration as B, ConfigurationLoader as C, type DevelopmentConfiguration as D, type EndpointMetadata as E, FileSystemManager as F, type GenerationContext as G, type HttpMethod as H, GenerationError as I, type ClientConfiguration as J, type RequestConfiguration as K, LogLevel as L, type ClientResponse as M, type StreamingResponse as N, OpenApiSchemaParser as O, type PluginConfiguration as P, type RequestBodyDefinition as R, type SchemaDefinition as S, VersionChecker as V, type GeneratedFile as a, BridgeCore as b, BridgeLogger as c, createBridgeVersionChecker as d, checkAndNotifyUpdates as e, type FrameworkConfiguration as f, type AuthConfiguration as g, type CacheConfiguration as h, type GenerationConfiguration as i, type OpenApiDocument as j, type ParsedApiSchema as k, type ApiEndpointDefinition as l, type ParameterDefinition as m, type ApiResponseDefinition as n, type SecuritySchemeDefinition as o, type ServerDefinition as p, type SchemaMetadata as q, type SecurityRequirement as r, type CacheStrategy as s, type RateLimit as t, type FileMetadata as u, type BridgePlugin as v, type VersionInfo as w, BridgeError as x, ValidationError as y, SchemaParseError as z };
+export { type ApiConfiguration as A, type BridgeConfiguration as B, ConfigurationLoader as C, type DevelopmentConfiguration as D, type EndpointMetadata as E, FileSystemManager as F, type GenerationConfiguration as G, type HttpMethod as H, BridgeError as I, ValidationError as J, SchemaParseError as K, LogLevel as L, GenerationError as M, type VersionInfo as N, OpenApiSchemaParser as O, type PluginConfiguration as P, type RequestBodyDefinition as R, type SchemaDefinition as S, VersionChecker as V, BridgeCore as a, BridgeLogger as b, createBridgeVersionChecker as c, checkAndNotifyUpdates as d, type FrameworkConfiguration as e, type AuthConfiguration as f, type CacheConfiguration as g, type OpenApiDocument as h, type ParsedApiSchema as i, type ApiEndpointDefinition as j, type ParameterDefinition as k, type ApiResponseDefinition as l, type SecuritySchemeDefinition as m, type ServerDefinition as n, type SchemaMetadata as o, type SecurityRequirement as p, type CacheStrategy as q, type RateLimit as r, type GenerationContext as s, type GeneratedFile as t, type FileMetadata as u, type BridgePlugin as v, type ClientConfiguration as w, type RequestConfiguration as x, type ClientResponse as y, type StreamingResponse as z };

package/dist/lib/{version-checker-uF6o5ziX.d.ts → version-checker-DU88tpi8.d.ts}

@@ -324,22 +324,66 @@ interface FileMetadata {
     imports: string[];
     dependencies: string[];
 }
+/**
+ * Base error class for all Mulink errors
+ *
+ * Follows best practices similar to Apollo Client's error handling.
+ * Provides structured error information with error codes and details.
+ *
+ * @public
+ */
 declare class BridgeError extends Error {
     readonly code: string;
     readonly details?: unknown;
-    constructor(message: string, code: string, details?: unknown);
+    readonly timestamp: number;
+    readonly cause?: Error;
+    constructor(message: string, code: string, details?: unknown, cause?: Error);
+    /**
+     * Converts the error to a JSON-serializable object
+     *
+     * @returns JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Checks if this error is retryable
+     *
+     * @returns True if the operation that caused this error can be retried
+     */
+    isRetryable(): boolean;
 }
+/**
+ * Error thrown when configuration validation fails
+ *
+ * Contains Zod validation errors for detailed feedback.
+ */
 declare class ValidationError extends BridgeError {
     readonly errors: z.ZodError;
-    constructor(message: string, errors: z.ZodError);
+    constructor(message: string, errors: z.ZodError, cause?: Error);
+    /**
+     * Gets formatted validation error messages
+     *
+     * @returns Array of formatted error messages
+     */
+    getFormattedErrors(): string[];
 }
+/**
+ * Error thrown when OpenAPI schema parsing fails
+ *
+ * Contains the schema URL that failed to parse.
+ */
 declare class SchemaParseError extends BridgeError {
     readonly schemaUrl: string;
-    constructor(message: string, schemaUrl: string);
+    constructor(message: string, schemaUrl: string, cause?: Error);
+    isRetryable(): boolean;
 }
+/**
+ * Error thrown when code generation fails
+ *
+ * Contains the file path where generation failed, if applicable.
+ */
 declare class GenerationError extends BridgeError {
     readonly file?: string;
-    constructor(message: string, file?: string);
+    constructor(message: string, file?: string, cause?: Error);
 }
 interface BridgePlugin {
     name: string;
@@ -403,23 +447,119 @@ interface StreamingResponse<T = any> {
     controller: AbortController;
 }
 
+/**
+ * Core class for the Mulink library
+ *
+ * This class orchestrates the entire code generation process from OpenAPI schemas
+ * to production-ready Next.js 16.0.7 code. It follows best practices similar to
+ * Apollo Client and other enterprise-grade libraries.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new BridgeCore();
+ * await bridge.generate(configuration);
+ * ```
+ *
+ * @public
+ */
 declare class BridgeCore {
     private readonly logger;
     private readonly schemaParser;
     private readonly fileManager;
+    /**
+     * Creates a new instance of BridgeCore
+     *
+     * Initializes all required dependencies including logger, schema parser, and file manager.
+     * All dependencies are readonly to ensure immutability and thread safety.
+     */
     constructor();
+    /**
+     * Generates type-safe API client code from OpenAPI schema
+     *
+     * This is the main entry point for code generation. It validates the configuration,
+     * parses the OpenAPI schema, generates all necessary files, and writes them to disk.
+     *
+     * The generated code follows Next.js 16.0.7 best practices including:
+     * - Server Actions with type safety
+     * - React Query hooks with proper caching
+     * - Middleware support
+     * - Error handling
+     * - Cache tag management
+     *
+     * @param configuration - The bridge configuration containing schema URL, output directory, and framework settings
+     * @returns Promise that resolves when generation is complete
+     * @throws {ValidationError} When configuration is invalid
+     * @throws {SchemaParseError} When OpenAPI schema cannot be parsed
+     * @throws {GenerationError} When code generation fails
+     *
+     * @example
+     * ```typescript
+     * const config: BridgeConfiguration = {
+     *   schema: 'https://api.example.com/openapi.json',
+     *   outputDir: 'src/generated',
+     *   framework: { type: 'nextjs', router: 'app', features: {...} },
+     *   api: { baseUrl: 'https://api.example.com', timeout: 30000, retries: 3 }
+     * };
+     * await bridge.generate(config);
+     * ```
+     */
     generate(configuration: BridgeConfiguration): Promise<void>;
     private validateConfiguration;
     private generateFiles;
     private writeFiles;
     private logGenerationSummary;
+    /**
+     * Validates an OpenAPI schema without generating code
+     *
+     * Useful for checking schema validity before running full generation.
+     *
+     * @param schemaUrl - URL or file path to the OpenAPI schema
+     * @returns Promise resolving to true if schema is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isValid = await bridge.validateSchema('https://api.example.com/openapi.json');
+     * if (isValid) {
+     *   await bridge.generate(config);
+     * }
+     * ```
+     */
     validateSchema(schemaUrl: string): Promise<boolean>;
+    /**
+     * Retrieves metadata from an OpenAPI schema
+     *
+     * Extracts schema metadata including title, version, description, and other
+     * OpenAPI document information without parsing the entire schema.
+     *
+     * @param schemaUrl - URL or file path to the OpenAPI schema
+     * @returns Promise resolving to schema metadata
+     * @throws {BridgeError} When schema URL is invalid
+     * @throws {SchemaParseError} When schema cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const metadata = await bridge.getSchemaInfo('https://api.example.com/openapi.json');
+     * console.log(`Schema: ${metadata.title} v${metadata.version}`);
+     * ```
+     */
     getSchemaInfo(schemaUrl: string): Promise<ParsedApiSchema['metadata']>;
+    /**
+     * Clears the internal schema cache
+     *
+     * Useful when you need to force re-fetching of schemas or during development.
+     * The cache is automatically managed, but this method allows manual invalidation.
+     *
+     * @example
+     * ```typescript
+     * bridge.clearCache();
+     * await bridge.generate(config); // Will fetch fresh schema
+     * ```
+     */
     clearCache(): void;
 }
 
 declare class OpenApiSchemaParser {
-    private schemaCache;
+    private readonly schemaCache;
     parse(schemaUrl: string): Promise<ParsedApiSchema>;
     private fetchSchema;
     private parseDocument;
@@ -443,7 +583,7 @@ declare class OpenApiSchemaParser {
 
 declare class ConfigurationLoader {
     load(configPath?: string): Promise<BridgeConfiguration>;
-    createDefault(framework?: 'nextjs'): Promise<BridgeConfiguration>;
+    createDefault(framework?: 'nextjs'): BridgeConfiguration;
     save(config: BridgeConfiguration, configPath?: string): Promise<void>;
 }
 
@@ -498,10 +638,10 @@ interface VersionInfo {
 }
 type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'unknown';
 declare class VersionChecker {
-    private logger;
-    private packageName;
-    private currentVersion;
-    private cache;
+    private readonly logger;
+    private readonly packageName;
+    private readonly currentVersion;
+    private readonly cache;
     private readonly CACHE_DURATION;
     constructor(packageName: string, currentVersion: string, logger?: BridgeLogger);
     /**
@@ -515,7 +655,7 @@ declare class VersionChecker {
     /**
      * Get the appropriate upgrade command for the detected package manager
      */
-    getUpgradeCommand(versionInfo: VersionInfo): string;
+    getUpgradeCommand(_versionInfo: VersionInfo): string;
     /**
      * Get a user-friendly update message
      */
@@ -575,4 +715,4 @@ declare function checkAndNotifyUpdates(options?: {
     logger?: BridgeLogger;
 }): Promise<VersionInfo | null>;
 
-export { type ApiConfiguration as A, type BridgeConfiguration as B, ConfigurationLoader as C, type DevelopmentConfiguration as D, type EndpointMetadata as E, FileSystemManager as F, type GenerationContext as G, type HttpMethod as H, GenerationError as I, type ClientConfiguration as J, type RequestConfiguration as K, LogLevel as L, type ClientResponse as M, type StreamingResponse as N, OpenApiSchemaParser as O, type PluginConfiguration as P, type RequestBodyDefinition as R, type SchemaDefinition as S, VersionChecker as V, type GeneratedFile as a, BridgeCore as b, BridgeLogger as c, createBridgeVersionChecker as d, checkAndNotifyUpdates as e, type FrameworkConfiguration as f, type AuthConfiguration as g, type CacheConfiguration as h, type GenerationConfiguration as i, type OpenApiDocument as j, type ParsedApiSchema as k, type ApiEndpointDefinition as l, type ParameterDefinition as m, type ApiResponseDefinition as n, type SecuritySchemeDefinition as o, type ServerDefinition as p, type SchemaMetadata as q, type SecurityRequirement as r, type CacheStrategy as s, type RateLimit as t, type FileMetadata as u, type BridgePlugin as v, type VersionInfo as w, BridgeError as x, ValidationError as y, SchemaParseError as z };
+export { type ApiConfiguration as A, type BridgeConfiguration as B, ConfigurationLoader as C, type DevelopmentConfiguration as D, type EndpointMetadata as E, FileSystemManager as F, type GenerationConfiguration as G, type HttpMethod as H, BridgeError as I, ValidationError as J, SchemaParseError as K, LogLevel as L, GenerationError as M, type VersionInfo as N, OpenApiSchemaParser as O, type PluginConfiguration as P, type RequestBodyDefinition as R, type SchemaDefinition as S, VersionChecker as V, BridgeCore as a, BridgeLogger as b, createBridgeVersionChecker as c, checkAndNotifyUpdates as d, type FrameworkConfiguration as e, type AuthConfiguration as f, type CacheConfiguration as g, type OpenApiDocument as h, type ParsedApiSchema as i, type ApiEndpointDefinition as j, type ParameterDefinition as k, type ApiResponseDefinition as l, type SecuritySchemeDefinition as m, type ServerDefinition as n, type SchemaMetadata as o, type SecurityRequirement as p, type CacheStrategy as q, type RateLimit as r, type GenerationContext as s, type GeneratedFile as t, type FileMetadata as u, type BridgePlugin as v, type ClientConfiguration as w, type RequestConfiguration as x, type ClientResponse as y, type StreamingResponse as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulink",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Universal type-safe API integration library for modern web applications",
   "type": "module",
   "exports": {
@@ -30,7 +30,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "vitest",
+    "test": "vitest run",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
     "test:watch": "vitest --watch",