openapi-sync 4.0.2 → 5.0.1

package/dist/index.d.mts

@@ -1,6 +1,24 @@
 import { Method } from 'axios';
 
+/**
+ * OpenAPI Specification document type
+ *
+ * Represents a complete OpenAPI specification object with the required
+ * "openapi" version field and any additional specification properties.
+ *
+ * @public
+ */
 type IOpenApiSpec = Record<"openapi", string> & Record<string, any>;
+/**
+ * OpenAPI Schema Specification
+ *
+ * Represents a schema object as defined in the OpenAPI Specification.
+ * Includes all standard JSON Schema properties plus OpenAPI extensions.
+ * Supports validation constraints, composition keywords (anyOf, oneOf, allOf),
+ * and references.
+ *
+ * @public
+ */
 type IOpenApSchemaSpec = {
     nullable?: boolean;
     type: "string" | "integer" | "number" | "array" | "object" | "boolean" | "null" | any[];
@@ -30,6 +48,14 @@ type IOpenApSchemaSpec = {
     minProperties?: number;
     maxProperties?: number;
 };
+/**
+ * OpenAPI Parameter Specification
+ *
+ * Represents a parameter object in an OpenAPI operation. Can describe
+ * path, query, header, or cookie parameters with validation and examples.
+ *
+ * @public
+ */
 type IOpenApiParameterSpec = {
     $ref?: string;
     name: string;
@@ -46,27 +72,73 @@ type IOpenApiParameterSpec = {
     example?: any;
     examples?: any[];
 };
+/**
+ * OpenAPI Media Type Specification
+ *
+ * Represents a media type object for request/response bodies.
+ * Includes schema definitions and examples for specific content types.
+ *
+ * @public
+ */
 type IOpenApiMediaTypeSpec = {
     schema?: IOpenApSchemaSpec;
     example?: any;
     examples?: any[];
     encoding?: any;
 };
+/**
+ * OpenAPI Request Body Specification
+ *
+ * Represents a request body object with content types and schemas.
+ * Maps content types (e.g., "application/json") to their specifications.
+ *
+ * @public
+ */
 type IOpenApiRequestBodySpec = {
     description?: string;
     required?: boolean;
     content: Record<string, IOpenApiMediaTypeSpec>;
 };
+/**
+ * OpenAPI Response Specification
+ *
+ * Maps HTTP status codes to their response specifications.
+ *
+ * @public
+ */
 type IOpenApiResponseSpec = Record<string, IOpenApiRequestBodySpec>;
+/**
+ * Configuration for word/pattern replacement in generated names
+ *
+ * Allows find-and-replace operations on generated type names and endpoint names.
+ * Supports regular expressions for pattern matching.
+ *
+ * @public
+ */
 type IConfigReplaceWord = {
     /**  string and regular expression as a string*/
     replace: string;
     with: string;
 };
+/**
+ * Configuration for documentation generation
+ *
+ * Controls whether documentation is generated and what features are included.
+ *
+ * @public
+ */
 type IConfigDoc = {
     disable?: boolean;
     showCurl?: boolean;
 };
+/**
+ * Configuration for excluding endpoints from generation
+ *
+ * Allows filtering out specific endpoints by tags or path/method combinations.
+ * Supports regex patterns for flexible matching.
+ *
+ * @public
+ */
 type IConfigExclude = {
     /** Exclude/Include endpoints by tags */
     tags?: string[];
@@ -80,8 +152,24 @@ type IConfigExclude = {
         method?: Method;
     }>;
 };
+/**
+ * Configuration for including endpoints in generation
+ *
+ * Mirror of IConfigExclude but used for explicit inclusion filtering.
+ * When specified, only matching endpoints will be generated.
+ *
+ * @public
+ */
 interface IConfigInclude extends IConfigExclude {
 }
+/**
+ * Configuration for folder splitting
+ *
+ * Controls how generated files are organized into folders.
+ * Can split by OpenAPI tags or use custom logic.
+ *
+ * @public
+ */
 type IConfigFolderSplit = {
     /** Split folders by tags - creates folders named after each tag */
     byTags?: boolean;
@@ -97,6 +185,14 @@ type IConfigFolderSplit = {
         responses?: IOpenApiResponseSpec;
     }) => string | null;
 };
+/**
+ * Configuration for custom code preservation
+ *
+ * Controls how custom code sections are handled during regeneration.
+ * Allows users to add code that won't be overwritten when files are regenerated.
+ *
+ * @public
+ */
 type IConfigCustomCode = {
     /** Enable custom code preservation (default: true) */
     enabled?: boolean;
@@ -107,6 +203,14 @@ type IConfigCustomCode = {
     /** Add helpful instructions in markers (default: true) */
     includeInstructions?: boolean;
 };
+/**
+ * Configuration for validation schema generation
+ *
+ * Controls generation of runtime validation schemas using Zod, Yup, or Joi.
+ * Allows selective generation for query parameters and request bodies.
+ *
+ * @public
+ */
 type IConfigValidations = {
     /** Disable validation schema generation (default: false) */
     disable?: boolean;
@@ -134,6 +238,105 @@ type IConfigValidations = {
         }, defaultName: string) => string | null | undefined;
     };
 };
+/**
+ * Configuration for API client generation
+ *
+ * Controls generation of type-safe API clients including Fetch, Axios,
+ * React Query hooks, SWR hooks, and RTK Query slices. Supports filtering,
+ * custom naming, and framework-specific options.
+ *
+ * @public
+ */
+type IConfigClientGeneration = {
+    /** Enable client generation (default: false) */
+    enabled?: boolean;
+    /** Client type to generate */
+    type?: "fetch" | "axios" | "react-query" | "swr" | "rtk-query";
+    /** Output directory for generated clients */
+    outputDir?: string;
+    /** Base URL for API requests (can be overridden at runtime) */
+    baseURL?: string;
+    /** Filter endpoints by tags */
+    tags?: string[];
+    /** Filter endpoints by endpoint names */
+    endpoints?: string[];
+    /** Naming configuration for client functions */
+    name?: {
+        prefix?: string;
+        suffix?: string;
+        useOperationId?: boolean;
+        format?: (data: {
+            method: Method;
+            path: string;
+            summary?: string;
+            operationId?: string;
+            tags?: string[];
+        }, defaultName: string) => string | null | undefined;
+    };
+    /** Configuration for React Query hooks */
+    reactQuery?: {
+        /** Version of React Query (default: 5) */
+        version?: 4 | 5;
+        /** Enable mutation hooks for POST/PUT/PATCH/DELETE (default: true) */
+        mutations?: boolean;
+        /** Enable infinite query hooks for paginated endpoints (default: false) */
+        infiniteQueries?: {
+            disable?: boolean;
+            /** Include/exclude advanced filters for client generation */
+            include?: IConfigInclude;
+            exclude?: IConfigExclude;
+        };
+    };
+    /** Configuration for SWR hooks */
+    swr?: {
+        /** Enable SWR mutation hooks (default: true) */
+        mutations?: boolean;
+        infiniteQueries?: {
+            disable?: boolean;
+            /** Include/exclude advanced filters for client generation */
+            include?: IConfigInclude;
+            exclude?: IConfigExclude;
+        };
+    };
+    /** Configuration for RTK Query */
+    rtkQuery?: {
+        /** API slice name */
+        apiName?: string;
+        /** Base query type */
+        baseQuery?: "fetchBaseQuery" | "axiosBaseQuery";
+        infiniteQueries?: {
+            disable?: boolean;
+            /** Include/exclude advanced filters for client generation */
+            include?: IConfigInclude;
+            exclude?: IConfigExclude;
+        };
+    };
+    /** Include authentication/authorization setup */
+    auth?: {
+        /** Auth type */
+        type?: "bearer" | "apiKey" | "basic" | "oauth2";
+        /** Where to include auth token */
+        in?: "header" | "query" | "cookie";
+        /** Header/query param name for auth */
+        name?: string;
+    };
+    /** Error handling configuration */
+    errorHandling?: {
+        /** Generate typed error classes */
+        generateErrorClasses?: boolean;
+        /** Custom error handler function name */
+        customHandler?: string;
+    };
+};
+/**
+ * Main OpenAPI Sync configuration
+ *
+ * The root configuration object for openapi-sync. Defines API sources,
+ * output settings, code generation options, and all feature configurations.
+ * Used in openapi.sync.ts, openapi.sync.js, or openapi.sync.json files.
+ *
+ * @public
+ */
 type IConfig = {
     refetchInterval?: number;
     folder?: string;
@@ -145,6 +348,8 @@ type IConfig = {
     customCode?: IConfigCustomCode;
     /** Configuration for validation schema generation */
     validations?: IConfigValidations;
+    /** Configuration for API client generation */
+    clientGeneration?: IConfigClientGeneration;
     /** Configuration for excluding endpoints from code generation */
     types?: {
         name?: {
@@ -183,6 +388,15 @@ type IConfig = {
         include?: IConfigInclude;
     };
 };
+/**
+ * OpenAPI Security Schemes
+ *
+ * Defines security schemes available in an OpenAPI specification.
+ * Supports various authentication methods including HTTP, API keys,
+ * OAuth2, OpenID Connect, and mutual TLS.
+ *
+ * @public
+ */
 type IOpenApiSecuritySchemes = {
     [key: string]: {
         type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
@@ -203,17 +417,110 @@ type IOpenApiSecuritySchemes = {
     };
 };
 
+/**
+ * Check if a value is a JSON object
+ *
+ * @param {any} value - Value to check
+ * @returns {boolean} True if the value is an object and not a Blob
+ *
+ * @public
+ */
 declare const isJson: (value: any) => boolean;
+/**
+ * Check if a string is valid YAML
+ *
+ * Attempts to parse the string as YAML and returns true if successful.
+ *
+ * @param {string} fileContent - String content to check
+ * @returns {boolean} True if the string can be parsed as YAML
+ *
+ * @public
+ */
 declare const isYamlString: (fileContent: string) => boolean;
+/**
+ * Convert YAML string to JSON object
+ *
+ * Parses a YAML string and returns a JSON object representation.
+ * Returns undefined if the string is not valid YAML.
+ *
+ * @param {string} fileContent - YAML string content
+ * @returns {any | undefined} Parsed JSON object, or undefined if invalid YAML
+ *
+ * @public
+ */
 declare const yamlStringToJson: (fileContent: string) => any;
+/**
+ * Capitalize the first letter of a string
+ *
+ * @param {string} text - Text to capitalize
+ * @returns {string} Text with first letter capitalized
+ *
+ * @public
+ */
 declare const capitalize: (text: string) => string;
+/**
+ * Extract endpoint details from path and method
+ *
+ * Parses an API path to generate a function name and extract path variables.
+ * Handles multiple path variable formats: {id}, <id>, and :id.
+ *
+ * @param {string} path - API endpoint path (e.g., "/users/{userId}/posts")
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @returns {{ name: string; variables: string[]; pathParts: string[] }} Object containing generated name, path variables, and path parts
+ *
+ * @example
+ * getEndpointDetails("/users/{userId}", "GET")
+ * // Returns: { name: "GetUsers$userId", variables: ["userId"], pathParts: [...] }
+ *
+ * @public
+ */
 declare const getEndpointDetails: (path: string, method: string) => {
     name: string;
     variables: string[];
     pathParts: string[];
 };
+/**
+ * Convert object to formatted TypeScript string
+ *
+ * Creates a human-readable TypeScript object representation with proper indentation.
+ * Used for generating type definitions in generated code.
+ *
+ * @param {Record<string, any>} obj - Object to stringify
+ * @param {number} [indent=1] - Current indentation level
+ * @returns {string} Formatted TypeScript object string
+ *
+ * @public
+ */
 declare const JSONStringify: (obj: Record<string, any>, indent?: number) => string;
+/**
+ * Render TypeScript type reference as markdown code block
+ *
+ * Formats a TypeScript type definition for inclusion in markdown documentation.
+ *
+ * @param {string} typeRef - TypeScript type definition
+ * @param {number} [indent=1] - Indentation level
+ * @returns {string} Markdown formatted code block
+ *
+ * @public
+ */
 declare const renderTypeRefMD: (typeRef: string, indent?: number) => string;
+/**
+ * Get nested value from object using dot notation path
+ *
+ * Safely retrieves a deeply nested value from an object using a string path.
+ * Returns undefined if the path doesn't exist.
+ *
+ * @template T - Type of the expected return value
+ * @param {object} obj - Object to navigate
+ * @param {string} path - Dot-notation path (e.g., "user.address.city")
+ * @returns {T | undefined} The value at the path, or undefined if not found
+ *
+ * @example
+ * getNestedValue<string>({ user: { name: "John" } }, "user.name")
+ * // Returns: "John"
+ *
+ * @public
+ */
 declare function getNestedValue<T>(obj: object, path: string): T | undefined;
 interface ExtractedCustomCode {
     beforeGenerated: string;
@@ -221,25 +528,48 @@ interface ExtractedCustomCode {
 }
 /**
  * Extract custom code from existing file using comment markers
- * @param fileContent - The content of the existing file
- * @param markerText - The marker text to look for (default: "CUSTOM CODE")
- * @returns Object containing custom code sections before and after generated code
+ *
+ * Scans an existing file for custom code blocks marked with special comments
+ * and extracts them for preservation during regeneration.
+ *
+ * @param {string} fileContent - The content of the existing file
+ * @param {string} [markerText="CUSTOM CODE"] - The marker text to look for
+ * @returns {ExtractedCustomCode} Object containing custom code sections before and after generated code
+ *
+ * @public
  */
 declare const extractCustomCode: (fileContent: string, markerText?: string) => ExtractedCustomCode;
 /**
  * Create an empty custom code marker section
- * @param position - Position of the marker ("top" or "bottom")
- * @param markerText - The marker text (default: "CUSTOM CODE")
- * @param includeInstructions - Whether to include helpful instructions
- * @returns The marker section as a string
+ *
+ * Generates the comment markers that delineate custom code sections in
+ * generated files. These markers tell the regeneration process where
+ * user-added code should be preserved.
+ *
+ * @param {"top" | "bottom"} position - Position of the marker in the file
+ * @param {string} [markerText="CUSTOM CODE"] - The marker text to use
+ * @param {boolean} [includeInstructions=true] - Whether to include helpful instructions
+ * @returns {string} The marker section as a string
+ *
+ * @public
  */
 declare const createCustomCodeMarker: (position: "top" | "bottom", markerText?: string, includeInstructions?: boolean) => string;
 /**
  * Merge generated content with preserved custom code
- * @param generatedContent - The newly generated content
- * @param existingFileContent - The existing file content (null if file doesn't exist)
- * @param config - Configuration options
- * @returns The merged content with custom code preserved
+ *
+ * The core function for custom code preservation. Extracts custom code from
+ * existing files and merges it with newly generated content, ensuring user
+ * modifications survive regeneration.
+ *
+ * @param {string} generatedContent - The newly generated content
+ * @param {string | null} existingFileContent - The existing file content (null if file doesn't exist)
+ * @param {Object} [config] - Configuration options
+ * @param {"top" | "bottom" | "both"} [config.position="bottom"] - Where to place custom code markers
+ * @param {string} [config.markerText="CUSTOM CODE"] - Custom marker text
+ * @param {boolean} [config.includeInstructions=true] - Whether to include helpful instructions
+ * @returns {string} The merged content with custom code preserved
+ *
+ * @public
  */
 declare const mergeCustomCode: (generatedContent: string, existingFileContent: string | null, config?: {
     position?: "top" | "bottom" | "both";
@@ -250,8 +580,92 @@ declare const mergeCustomCode: (generatedContent: string, existingFileContent: s
 declare const variableName: RegExp;
 declare const variableNameChar: RegExp;
 
+/**
+ * Initialize and sync all OpenAPI specifications
+ *
+ * This is the main entry point for the OpenAPI sync process. It loads the configuration,
+ * resets the state, and syncs all configured APIs to generate types, endpoints, and validations.
+ *
+ * @param {Object} [options] - Optional configuration
+ * @param {number} [options.refetchInterval] - Interval in milliseconds to automatically refetch specifications
+ * @returns {Promise<void>}
+ * @throws {Error} When configuration is not found or sync fails
+ *
+ * @example
+ * // Sync once
+ * await Init();
+ *
+ * @example
+ * // Sync with auto-refresh every 10 seconds
+ * await Init({ refetchInterval: 10000 });
+ *
+ * @public
+ */
 declare const Init: (options?: {
     refetchInterval?: number;
 }) => Promise<void>;
+/**
+ * Generate API client from OpenAPI specification
+ *
+ * Generates type-safe API clients based on OpenAPI specifications. Supports multiple
+ * client types including Fetch, Axios, React Query, SWR, and RTK Query. Can filter
+ * endpoints by tags or specific endpoint names.
+ *
+ * @param {Object} options - Client generation options
+ * @param {"fetch" | "axios" | "react-query" | "swr" | "rtk-query"} options.type - Type of client to generate
+ * @param {string} [options.apiName] - Specific API name to generate client for (generates for all if not specified)
+ * @param {string[]} [options.tags] - Filter endpoints by OpenAPI tags
+ * @param {string[]} [options.endpoints] - Filter by specific endpoint operation IDs
+ * @param {string} [options.outputDir] - Custom output directory for generated client
+ * @param {string} [options.baseURL] - Base URL for API requests
+ * @returns {Promise<void>}
+ * @throws {Error} When API name is not found in configuration or sync fails
+ *
+ * @example
+ * // Generate Axios client for all APIs
+ * await GenerateClient({ type: "axios" });
+ *
+ * @example
+ * // Generate React Query hooks for a specific API
+ * await GenerateClient({
+ *   type: "react-query",
+ *   apiName: "petstore",
+ *   baseURL: "https://api.example.com"
+ * });
+ *
+ * @example
+ * // Generate SWR hooks for specific endpoints
+ * await GenerateClient({
+ *   type: "swr",
+ *   endpoints: ["getPetById", "createPet"]
+ * });
+ *
+ * @public
+ */
+declare const GenerateClient: (options: {
+    type: "fetch" | "axios" | "react-query" | "swr" | "rtk-query";
+    apiName?: string;
+    tags?: string[];
+    endpoints?: string[];
+    outputDir?: string;
+    baseURL?: string;
+}) => Promise<void>;
+/**
+ * Interactive CLI wizard to create configuration
+ *
+ * Launches an interactive command-line wizard that guides users through
+ * creating an openapi.sync configuration file. Prompts for API URLs,
+ * output directories, client generation preferences, and more.
+ *
+ * @returns {Promise<void>}
+ * @throws {Error} When wizard is cancelled or configuration creation fails
+ *
+ * @example
+ * // Run the interactive setup wizard
+ * await InteractiveInit();
+ *
+ * @public
+ */
+declare const InteractiveInit: () => Promise<void>;
 
-export { type ExtractedCustomCode, type IConfig, type IConfigCustomCode, type IConfigDoc, type IConfigExclude, type IConfigFolderSplit, type IConfigInclude, type IConfigReplaceWord, type IConfigValidations, type IOpenApSchemaSpec, type IOpenApiMediaTypeSpec, type IOpenApiParameterSpec, type IOpenApiRequestBodySpec, type IOpenApiResponseSpec, type IOpenApiSecuritySchemes, type IOpenApiSpec, Init, JSONStringify, capitalize, createCustomCodeMarker, extractCustomCode, getEndpointDetails, getNestedValue, isJson, isYamlString, mergeCustomCode, renderTypeRefMD, variableName, variableNameChar, yamlStringToJson };
+export { type ExtractedCustomCode, GenerateClient, type IConfig, type IConfigClientGeneration, type IConfigCustomCode, type IConfigDoc, type IConfigExclude, type IConfigFolderSplit, type IConfigInclude, type IConfigReplaceWord, type IConfigValidations, type IOpenApSchemaSpec, type IOpenApiMediaTypeSpec, type IOpenApiParameterSpec, type IOpenApiRequestBodySpec, type IOpenApiResponseSpec, type IOpenApiSecuritySchemes, type IOpenApiSpec, Init, InteractiveInit, JSONStringify, capitalize, createCustomCodeMarker, extractCustomCode, getEndpointDetails, getNestedValue, isJson, isYamlString, mergeCustomCode, renderTypeRefMD, variableName, variableNameChar, yamlStringToJson };