openapi-sync 5.0.7 → 6.0.0

package/dist/chunk-VLACEFT4.mjs

@@ -0,0 +1 @@
+var m=Object.defineProperty,n=Object.defineProperties;var o=Object.getOwnPropertyDescriptors;var i=Object.getOwnPropertySymbols;var p=Object.prototype.hasOwnProperty,q=Object.prototype.propertyIsEnumerable;var j=(c,a,b)=>a in c?m(c,a,{enumerable:true,configurable:true,writable:true,value:b}):c[a]=b,r=(c,a)=>{for(var b in a||(a={}))p.call(a,b)&&j(c,b,a[b]);if(i)for(var b of i(a))q.call(a,b)&&j(c,b,a[b]);return c},s=(c,a)=>n(c,o(a));var t=(c=>typeof require!="undefined"?require:typeof Proxy!="undefined"?new Proxy(c,{get:(a,b)=>(typeof require!="undefined"?require:a)[b]}):c)(function(c){if(typeof require!="undefined")return require.apply(this,arguments);throw Error('Dynamic require of "'+c+'" is not supported')});var u=(c,a,b)=>()=>{if(b)throw b[0];try{return c&&(a=c(c=0)),a}catch(e){throw b=[e],e}};var v=(c,a)=>()=>{try{return a||c((a={exports:{}}).exports,a),a.exports}catch(b){throw a=0,b}};var w=(c,a,b)=>new Promise((e,h)=>{var k=d=>{try{f(b.next(d));}catch(g){h(g);}},l=d=>{try{f(b.throw(d));}catch(g){h(g);}},f=d=>d.done?e(d.value):Promise.resolve(d.value).then(k,l);f((b=b.apply(c,a)).next());});export{r as a,s as b,t as c,u as d,v as e,w as f};

package/dist/index.d.mts

@@ -417,6 +417,84 @@ type IOpenApiSecuritySchemes = {
         name?: string;
     };
 };
+/**
+ * Summary of a single endpoint returned by {@link ListEndpoints}.
+ *
+ * AI agents can use this to understand the API surface before deciding which
+ * client type to generate, or to filter endpoints by tag/method.
+ *
+ * @public
+ */
+type EndpointSummary = {
+    /** Camel-case function name used in generated code (e.g. `getPetById`) */
+    name: string;
+    /** HTTP method in uppercase (e.g. `"GET"`) */
+    method: string;
+    /** OpenAPI path (e.g. `"/pet/{petId}"`) */
+    path: string;
+    /** OpenAPI operation ID if present */
+    operationId?: string;
+    /** OpenAPI tags assigned to this endpoint */
+    tags?: string[];
+    /** Short human-readable summary from the OpenAPI spec */
+    summary?: string;
+};
+/**
+ * Structured result returned by {@link Init} and {@link GenerateClient}.
+ *
+ * When the CLI is invoked with `--json`, this object is serialized to stdout.
+ * AI agents should parse this to determine success, discover written files,
+ * and surface errors without screen-scraping emoji log lines.
+ *
+ * @example
+ * ```ts
+ * const result = await Init();
+ * if (!result.success) {
+ *   console.error(result.errors);
+ * } else {
+ *   console.log(`Wrote ${result.filesWritten.length} files`);
+ * }
+ * ```
+ *
+ * @public
+ */
+type SyncResult = {
+    /** Whether the operation completed without fatal errors */
+    success: boolean;
+    /** API name(s) that were processed */
+    apis: string[];
+    /** Absolute paths of all files written to disk */
+    filesWritten: string[];
+    /** Total number of endpoints discovered across all processed APIs */
+    endpointCount: number;
+    /** Non-fatal warnings (e.g. skipped endpoints) */
+    warnings: string[];
+    /** Fatal or per-file error messages; non-empty when `success` is false */
+    errors: string[];
+};
+/**
+ * Structured result returned by {@link ValidateConfig}.
+ *
+ * Lets agents check configuration and spec validity before running a full sync.
+ * No files are written to disk during validation.
+ *
+ * @public
+ */
+type ValidationResult = {
+    /** Whether the config file and all specs are valid */
+    valid: boolean;
+    /** Per-API validation results */
+    apis: Record<string, {
+        /** Whether this specific API's spec is valid and reachable */
+        valid: boolean;
+        /** Number of endpoints found in the spec */
+        endpointCount: number;
+        /** Error message if invalid */
+        error?: string;
+    }>;
+    /** Config-level errors (missing fields, bad types, etc.) */
+    configErrors: string[];
+};
 
 /**
  * Check if a value is a JSON object
@@ -584,19 +662,184 @@ declare const variableName: RegExp;
 declare const variableNameChar: RegExp;
 
 /**
- * Initialize and sync all OpenAPI specifications
+ * @fileoverview Typed error classes for openapi-sync.
  *
- * 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.
+ * Each error class exposes a stable `code` string so that AI agents and
+ * programmatic consumers can reliably branch on error type without parsing
+ * human-readable messages.
  *
- * @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
+ * When the CLI is invoked with `--json`, errors are serialized to:
+ * ```json
+ * { "success": false, "error": { "code": "SPEC_FETCH_FAILED", "message": "...", "url": "..." } }
+ * ```
+ *
+ * @public
+ */
+/**
+ * Base class for all openapi-sync errors.
+ *
+ * @public
+ */
+declare abstract class OpenApiSyncError extends Error {
+    abstract readonly code: string;
+    /**
+     * Serialize this error to a plain object suitable for JSON output.
+     * @returns Plain object with `code`, `message`, and any extra fields.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown when no configuration file (`openapi.sync.ts/js/json`) is found
+ * in the current working directory.
  *
  * @example
- * // Sync once
- * await Init();
+ * // Agent can catch and suggest a fix:
+ * catch (e) {
+ *   if (e instanceof ConfigNotFoundError) {
+ *     // run: npx openapi-sync init --no-interactive --api-name X --api-url Y
+ *   }
+ * }
+ *
+ * @public
+ */
+declare class ConfigNotFoundError extends OpenApiSyncError {
+    readonly code: "CONFIG_NOT_FOUND";
+    constructor(searchedPaths: string[]);
+    toJSON(): {
+        searchedPaths: string;
+    };
+}
+/**
+ * Thrown when the configuration file exists but fails to parse or export a
+ * valid config object.
+ *
+ * @public
+ */
+declare class ConfigParseError extends OpenApiSyncError {
+    readonly code: "CONFIG_PARSE_FAILED";
+    readonly configPath: string;
+    constructor(configPath: string, cause: unknown);
+    toJSON(): {
+        configPath: string;
+    };
+}
+/**
+ * Thrown when the config object is missing required fields or contains
+ * invalid values (e.g., empty `api` map, unsupported client type).
+ *
+ * @public
+ */
+declare class ConfigValidationError extends OpenApiSyncError {
+    readonly code: "CONFIG_INVALID";
+    readonly field: string;
+    constructor(field: string, reason: string);
+    toJSON(): {
+        field: string;
+    };
+}
+/**
+ * Thrown when fetching an OpenAPI spec from a URL fails (network error,
+ * timeout, non-2xx response, etc.).
+ *
+ * @public
+ */
+declare class SpecFetchError extends OpenApiSyncError {
+    readonly code: "SPEC_FETCH_FAILED";
+    readonly url: string;
+    readonly statusCode?: number;
+    constructor(url: string, cause: unknown, statusCode?: number);
+    toJSON(): {
+        statusCode?: number | undefined;
+        url: string;
+    };
+}
+/**
+ * Thrown when reading a local OpenAPI spec file fails (file not found,
+ * permission denied, etc.).
+ *
+ * @public
+ */
+declare class SpecReadError extends OpenApiSyncError {
+    readonly code: "SPEC_READ_FAILED";
+    readonly filePath: string;
+    constructor(filePath: string, cause: unknown);
+    toJSON(): {
+        filePath: string;
+    };
+}
+/**
+ * Thrown when the OpenAPI spec is fetched/read successfully but fails to
+ * parse or validate as a valid OpenAPI document.
+ *
+ * @public
+ */
+declare class SpecParseError extends OpenApiSyncError {
+    readonly code: "SPEC_PARSE_FAILED";
+    readonly api: string;
+    constructor(api: string, cause: unknown);
+    toJSON(): {
+        api: string;
+    };
+}
+/**
+ * Thrown when writing a generated file to disk fails.
+ *
+ * @public
+ */
+declare class GenerationError extends OpenApiSyncError {
+    readonly code: "GENERATION_FAILED";
+    readonly file: string;
+    readonly api: string;
+    constructor(file: string, api: string, cause: unknown);
+    toJSON(): {
+        file: string;
+        api: string;
+    };
+}
+/**
+ * Thrown when an API name specified by the user (e.g. via `--api`) does not
+ * exist in the config file.
+ *
+ * @public
+ */
+declare class UnknownApiError extends OpenApiSyncError {
+    readonly code: "UNKNOWN_API";
+    readonly requestedApi: string;
+    readonly availableApis: string[];
+    constructor(requestedApi: string, availableApis: string[]);
+    toJSON(): {
+        requestedApi: string;
+        availableApis: string[];
+    };
+}
+
+/**
+ * Initialize and sync all OpenAPI specifications.
+ *
+ * Loads the configuration, resets state, and syncs all configured APIs to
+ * generate TypeScript types, endpoint functions, and validation schemas.
+ *
+ * **Agent-safe** — call programmatically without any interactive prompts.
+ * Returns a structured {@link SyncResult} that can be serialized to JSON.
+ *
+ * @param {Object} [options] - Optional configuration overrides
+ * @param {number} [options.refetchInterval] - Auto-refetch interval in milliseconds
+ * @param {boolean} [options.silent=false] - Suppress all console output (useful when the caller handles logging)
+ * @returns {Promise<SyncResult>} Structured result describing files written and any errors
+ * @throws {ConfigNotFoundError} When no config file is found in the working directory
+ * @throws {ConfigParseError} When the config file cannot be parsed
+ *
+ * @example
+ * // Sync once and check results
+ * const result = await Init();
+ * if (result.success) {
+ *   console.log(`Wrote ${result.filesWritten.length} files for ${result.endpointCount} endpoints`);
+ * }
+ *
+ * @example
+ * // Sync silently and get JSON-serializable result
+ * const result = await Init({ silent: true });
+ * process.stdout.write(JSON.stringify(result));
  *
  * @example
  * // Sync with auto-refresh every 10 seconds
@@ -606,41 +849,47 @@ declare const variableNameChar: RegExp;
  */
 declare const Init: (options?: {
     refetchInterval?: number;
-}) => Promise<void>;
+    silent?: boolean;
+}) => Promise<SyncResult>;
 /**
- * Generate API client from OpenAPI specification
+ * Generate a type-safe API client from synced OpenAPI specifications.
  *
- * 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.
+ * Supports Fetch, Axios, React Query, SWR, and RTK Query. Runs a sync
+ * first to collect up-to-date endpoint information, then generates client files.
+ *
+ * **Agent-safe** — fully non-interactive. Returns a structured {@link SyncResult}.
  *
  * @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 {"fetch"|"axios"|"react-query"|"swr"|"rtk-query"} options.type - Client type to generate
+ * @param {string} [options.apiName] - Specific API from config (generates for all if omitted)
  * @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
+ * @param {string} [options.outputDir] - Custom output directory for generated client files
+ * @param {string} [options.baseURL] - Base URL for API requests (baked into the generated client)
+ * @param {boolean} [options.silent=false] - Suppress all console output
+ * @returns {Promise<SyncResult>} Structured result describing files written and any errors
+ * @throws {ConfigNotFoundError} When no config file is found
+ * @throws {UnknownApiError} When the specified apiName is not in config
  *
  * @example
  * // Generate Axios client for all APIs
- * await GenerateClient({ type: "axios" });
+ * const result = await GenerateClient({ type: "axios" });
  *
  * @example
  * // Generate React Query hooks for a specific API
- * await GenerateClient({
+ * const result = await GenerateClient({
  *   type: "react-query",
  *   apiName: "petstore",
- *   baseURL: "https://api.example.com"
+ *   baseURL: "https://api.example.com",
+ *   silent: true,
  * });
+ * console.log(JSON.stringify(result));
  *
  * @example
- * // Generate SWR hooks for specific endpoints
- * await GenerateClient({
+ * // Generate SWR hooks for specific endpoints only
+ * const result = await GenerateClient({
  *   type: "swr",
- *   endpoints: ["getPetById", "createPet"]
+ *   endpoints: ["getPetById", "createPet"],
  * });
  *
  * @public
@@ -652,23 +901,93 @@ declare const GenerateClient: (options: {
     endpoints?: string[];
     outputDir?: string;
     baseURL?: string;
-}) => Promise<void>;
+    silent?: boolean;
+}) => Promise<SyncResult>;
 /**
- * Interactive CLI wizard to create configuration
+ * Validate the config file and all configured API specs without writing any files.
+ *
+ * Use this as a pre-flight check before running {@link Init} or {@link GenerateClient}.
+ * Safe to run repeatedly — it has no side effects.
+ *
+ * **Agent-safe** — fully non-interactive. Returns a structured {@link ValidationResult}.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.silent=false] - Suppress console output
+ * @returns {Promise<ValidationResult>} Structured validation report
+ *
+ * @example
+ * // Validate before syncing
+ * const validation = await ValidateConfig();
+ * if (!validation.valid) {
+ *   console.error("Config errors:", validation.configErrors);
+ *   for (const [api, info] of Object.entries(validation.apis)) {
+ *     if (!info.valid) console.error(`  ${api}: ${info.error}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * await Init();
+ *
+ * @public
+ */
+declare const ValidateConfig: (options?: {
+    silent?: boolean;
+}) => Promise<ValidationResult>;
+/**
+ * List all endpoints discovered in the configured API specs.
+ *
+ * Fetches and parses specs, then returns a flat array of endpoint summaries.
+ * No files are written. Use this to understand the API surface before
+ * deciding which client type or tag filters to apply.
+ *
+ * **Agent-safe** — fully non-interactive.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.apiName] - Limit to a specific API (lists all if omitted)
+ * @param {string[]} [options.tags] - Filter endpoints by OpenAPI tags
+ * @param {boolean} [options.silent=false] - Suppress console output
+ * @returns {Promise<Record<string, EndpointSummary[]>>} Map of API name → endpoint summaries
+ *
+ * @example
+ * // List all endpoints across all APIs
+ * const endpoints = await ListEndpoints();
+ * for (const [api, list] of Object.entries(endpoints)) {
+ *   console.log(`${api}: ${list.length} endpoints`);
+ *   list.forEach(e => console.log(`  ${e.method} ${e.path} — ${e.summary}`));
+ * }
+ *
+ * @example
+ * // List only GET endpoints for the petstore API
+ * const result = await ListEndpoints({ apiName: "petstore", tags: ["pet"] });
+ *
+ * @public
+ */
+declare const ListEndpoints: (options?: {
+    apiName?: string;
+    tags?: string[];
+    silent?: boolean;
+}) => Promise<Record<string, EndpointSummary[]>>;
+/**
+ * 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.
+ * creating an `openapi.sync` configuration file.
+ *
+ * > ⚠️ **Not agent-safe** — this function blocks on stdin prompts.
+ * > AI agents should use the CLI with `--no-interactive` instead:
+ * > ```bash
+ * > npx openapi-sync init --no-interactive --api-name myapi --api-url https://...
+ * > ```
  *
  * @returns {Promise<void>}
  * @throws {Error} When wizard is cancelled or configuration creation fails
  *
  * @example
- * // Run the interactive setup wizard
+ * // Human-interactive setup
  * await InteractiveInit();
  *
  * @public
+ * @interactiveOnly
  */
 declare const InteractiveInit: () => Promise<void>;
 
-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 };
+export { ConfigNotFoundError, ConfigParseError, ConfigValidationError, type EndpointSummary, type ExtractedCustomCode, GenerateClient, GenerationError, 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, ListEndpoints, OpenApiSyncError, SpecFetchError, SpecParseError, SpecReadError, type SyncResult, UnknownApiError, ValidateConfig, type ValidationResult, capitalize, createCustomCodeMarker, extractCustomCode, getEndpointDetails, getNestedValue, isJson, isYamlString, mergeCustomCode, renderTypeRefMD, variableName, variableNameChar, yamlStringToJson };