ng-openapi 0.2.22 → 0.3.0

package/index.d.ts

@@ -2,52 +2,24 @@ import { Project, ScriptTarget, ModuleKind, MethodDeclaration, FunctionDeclarati
 import { HttpInterceptor } from '@angular/common/http';
 import { Info, ExternalDocs, Path, ParameterType, XML, BodyParameter, QueryParameter, Security, Tag } from 'swagger-schema-official';
 
-interface MethodGenerationContext {
-    pathParams: Array<{
-        name: string;
-        in: string;
-    }>;
-    queryParams: Array<{
-        name: string;
-        in: string;
-    }>;
-    hasBody: boolean;
-    isMultipart: boolean;
-    isUrlEncoded: boolean;
-    formDataFields: string[];
-    urlEncodedFields: string[];
-    responseType: "json" | "blob" | "arraybuffer" | "text";
-}
-interface TypeSchema {
-    type?: string;
-    format?: string;
-    $ref?: string;
-    items?: any;
-    nullable?: boolean;
-    enum?: Array<string | number>;
-    [key: string]: any;
-}
-interface GetMethodGenerationContext {
-    pathParams: Array<{
-        name: string;
-        in: string;
-    }>;
-    queryParams: Array<{
-        name: string;
-        in: string;
-    }>;
-    responseType: "json" | "blob" | "arraybuffer" | "text";
-}
-
+/**
+ * An operation parameter. OpenAPI 3.x carries the type in `schema`;
+ * Swagger 2.0 puts `type`/`format` directly on the parameter — consumers
+ * must handle both (or use the normalized model, which precomputes them).
+ */
 interface Parameter {
     name: string;
     in: "query" | "path" | "header" | "cookie";
     required?: boolean;
-    schema?: any;
+    schema?: SwaggerDefinition;
     type?: string;
     format?: string;
     description?: string;
 }
+/**
+ * One operation of the spec, flattened to (path, method). Raw-ish view —
+ * generators consume its precomputed extension NormalizedOperation instead.
+ */
 interface PathInfo {
     path: string;
     method: string;
@@ -59,18 +31,29 @@ interface PathInfo {
     requestBody?: RequestBody;
     responses?: Record<string, SwaggerResponse>;
 }
+/**
+ * Operation request body, keyed by content type — the OpenAPI 3.x shape.
+ * Swagger 2.0 `in: "body"` parameters are NOT yet lifted into this shape;
+ * 2.0 operations currently generate without a body parameter.
+ */
 interface RequestBody {
     required?: boolean;
     content?: Record<string, {
         schema?: SwaggerDefinition;
     }>;
 }
+/**
+ * A single response entry, keyed by content type — the OpenAPI 3.x shape.
+ * A Swagger 2.0 response's direct `schema` is NOT yet mapped into `content`;
+ * 2.0 responses currently type as `any`.
+ */
 interface SwaggerResponse {
     description?: string;
     content?: Record<string, {
-        schema?: any;
+        schema?: SwaggerDefinition;
     }>;
 }
+/** OpenAPI 3.x security scheme (subset of the spec's fields). */
 interface OpenApiSecurityScheme {
     type?: "apiKey" | "http" | "oauth2" | "openIdConnect";
     description?: string;
@@ -78,15 +61,20 @@ interface OpenApiSecurityScheme {
     in?: "query" | "header" | "cookie";
     scheme?: string;
     bearerFormat?: string;
-    flows?: Record<string, any>;
+    flows?: Record<string, unknown>;
     openIdConnectUrl?: string;
 }
+/**
+ * A JSON-Schema-ish definition as it appears in the spec, shared by
+ * Swagger 2.0 and OpenAPI 3.x (3.0's `nullable` and 3.1's type arrays
+ * both flow through `type`/`nullable`). May contain unresolved `$ref`s.
+ */
 interface SwaggerDefinition {
     type?: ParameterType | undefined;
     format?: string | undefined;
     title?: string | undefined;
     description?: string | undefined;
-    default?: any;
+    default?: unknown;
     multipleOf?: number | undefined;
     maximum?: number | undefined;
     exclusiveMaximum?: boolean | undefined;
@@ -100,7 +88,9 @@ interface SwaggerDefinition {
     uniqueItems?: boolean | undefined;
     maxProperties?: number | undefined;
     minProperties?: number | undefined;
-    enum?: any[] | undefined;
+    enum?: Array<string | number> | undefined;
+    /** OpenAPI 3.1 (JSON Schema); normalizeSchema folds it into a single-value `enum`. */
+    const?: unknown;
     items?: SwaggerDefinition | SwaggerDefinition[] | undefined;
     $ref?: string | undefined;
     allOf?: SwaggerDefinition[] | undefined;
@@ -113,11 +103,16 @@ interface SwaggerDefinition {
     nullable?: boolean | undefined;
     xml?: XML | undefined;
     externalDocs?: ExternalDocs | undefined;
-    example?: any;
+    example?: unknown;
     required?: string[] | undefined;
     oneOf?: SwaggerDefinition[];
     anyOf?: SwaggerDefinition[];
 }
+/**
+ * The raw parsed spec document. Exactly one of `swagger` ("2.x") or
+ * `openapi` ("3.x") identifies the version; everything version-specific
+ * is resolved once by normalizeSpec.
+ */
 interface SwaggerSpec {
     openapi: string;
     swagger: string;
@@ -152,134 +147,539 @@ interface SwaggerSpec {
         securitySchemes?: Record<string, OpenApiSecurityScheme | Security>;
     };
 }
+/**
+ * Shape of a JSON-encoded enum description consumed when
+ * `generateEnumBasedOnDescription` is enabled: the description holds
+ * `[{"Name":"First","Value":1}, …]` and supplies the member names.
+ */
 type EnumValueObject = {
     Name: string;
     Value: number;
 };
 
-declare class SwaggerParser {
-    private readonly spec;
-    private constructor();
-    static create(swaggerPathOrUrl: string, config: GeneratorConfig): Promise<SwaggerParser>;
-    private static loadContent;
-    private static fetchUrlContent;
-    private static parseSpecContent;
-    private static detectFormat;
-    getDefinitions(): Record<string, SwaggerDefinition>;
-    getDefinition(name: string): SwaggerDefinition | undefined;
+type ResponseKind = "json" | "blob" | "arraybuffer" | "text";
+/**
+ * A spec operation with everything the generators need precomputed once at
+ * normalization time. Generators must not re-derive any of these fields or
+ * resolve $refs during emission — that is exactly the duplication this model
+ * exists to remove.
+ */
+interface NormalizedOperation extends PathInfo {
+    /** parameters with in === "path" */
+    pathParams: Parameter[];
+    /** parameters with in === "query" */
+    queryParams: Parameter[];
+    hasBody: boolean;
+    isMultipart: boolean;
+    /** urlencoded body without a JSON alternative */
+    isUrlEncoded: boolean;
+    /** ref-resolved multipart body schema (set only when isMultipart) */
+    formDataSchema?: SwaggerDefinition;
+    /** field names of formDataSchema's properties */
+    formDataFields: string[];
+    /** ref-resolved urlencoded body schema (set only when isUrlEncoded) */
+    urlEncodedSchema?: SwaggerDefinition;
+    /** field names of urlEncodedSchema's properties */
+    urlEncodedFields: string[];
+    /** derived from the first success response (200/201/202/204/206) */
+    responseType: ResponseKind;
+}
+
+/** Detected spec flavor and its literal version string (e.g. openapi "3.0.3"). */
+interface SpecVersion {
+    type: "swagger" | "openapi";
+    version: string;
+}
+/**
+ * Version-free view of a parsed spec: Swagger 2.0 vs OpenAPI 3.x differences
+ * are resolved once at normalization time. Generators consume this instead of
+ * touching the raw SwaggerSpec.
+ */
+interface NormalizedSpec {
+    version: SpecVersion | null;
+    /** 2.0 `definitions` or 3.x `components.schemas`, whichever the spec has */
+    definitions: Record<string, SwaggerDefinition>;
+    operations: NormalizedOperation[];
+    /** Lookup for "#/definitions/X" and "#/components/schemas/X" style refs */
     resolveReference(ref: string): SwaggerDefinition | undefined;
-    getAllDefinitionNames(): string[];
-    getSpec(): SwaggerSpec;
-    getPaths(): Record<string, any>;
-    isValidSpec(): boolean;
-    getSpecVersion(): {
-        type: "swagger" | "openapi";
-        version: string;
-    } | null;
 }
 
 /**
- * Interface for generator class (both constructor and instance)
+ * Everything a plugin generator receives from the orchestrator.
+ *
+ * Plugins consume the version-free NormalizedSpec — never the raw spec or the
+ * SwaggerParser — and emit through the shared ts-morph Project so the
+ * orchestrator can track written files.
+ */
+interface PluginGeneratorContext {
+    /** Version-free spec model; $refs resolved, per-operation fields precomputed. */
+    spec: NormalizedSpec;
+    /** Shared ts-morph project all generators emit through. */
+    project: Project;
+    /** Full user-facing config; plugins should read only the slice they need. */
+    config: GeneratorConfig;
+    /** Sink for non-fatal diagnostics — plugins must never log directly. */
+    onWarning?: (message: string) => void;
+}
+/**
+ * Constructor contract for plugin generator classes (what GeneratorConfig.plugins accepts).
  */
 interface IPluginGeneratorClass {
-    /**
-     * Constructor signature
-     */
-    new (parser: SwaggerParser, project: Project, config: GeneratorConfig): IPluginGenerator;
+    new (context: PluginGeneratorContext): IPluginGenerator;
 }
 /**
  * Interface for generator instances
  */
 interface IPluginGenerator {
     /**
-     * Generate code files
+     * Generate code files under the given output root.
      */
     generate(outputRoot: string): Promise<void>;
 }
 
+/**
+ * The user-facing configuration (config file or programmatic call).
+ * Validated at the boundary by validateGeneratorConfig, which throws
+ * ConfigValidationError listing every problem at once — see
+ * https://ng-openapi.dev for full option documentation.
+ */
 interface GeneratorConfig {
+    /** Path or http(s) URL of the OpenAPI 3.x / Swagger 2.x spec (.json/.yaml/.yml). */
     input: string;
+    /** Output directory; created if missing. */
     output: string;
+    /** Distinguishes tokens/providers when several clients coexist in one app. */
     clientName?: string;
+    /** Custom acceptance check run on the parsed spec; returning false aborts generation. */
     validateInput?: (spec: SwaggerSpec) => boolean;
     options: {
+        /** How date/date-time formats are typed in generated models. */
         dateType: "string" | "Date";
+        /** Emit TS enums or literal-union types for spec enums. */
         enumStyle: "enum" | "union";
         validation?: {
+            /** Adds a `parse` hook to RequestOptions for response validation. */
             response?: boolean;
         };
+        /** Set false to generate models only. Default: true. */
         generateServices?: boolean;
+        /** Read enum member names from JSON-encoded descriptions (see EnumValueObject). */
         generateEnumBasedOnDescription?: boolean;
+        /** Default headers added to every request when not already present. */
         customHeaders?: Record<string, string>;
+        /** Pin the Angular responseType per response content type. */
         responseTypeMapping?: {
             [contentType: string]: "json" | "blob" | "arraybuffer" | "text";
         };
+        /** Derive method names from operationIds; throws when an operation has none. */
         customizeMethodName?: (operationId: string) => string;
+        /** Collapse each method's parameters into a single request object. */
         useSingleRequestParameter?: boolean;
     };
+    /** Overrides for the ts-morph compiler settings used during generation. */
     compilerOptions?: {
         declaration?: boolean;
         target?: ScriptTarget;
         module?: ModuleKind;
         strict?: boolean;
     };
-    plugins?: (new (...args: any) => IPluginGenerator)[];
+    /** Plugin generator classes, run after core generation (see PluginGeneratorContext). */
+    plugins?: IPluginGeneratorClass[];
+}
+/**
+ * Segregated views of GeneratorConfig.
+ * Generators declare the slice they actually consume; callers keep passing the
+ * full GeneratorConfig, which satisfies every view structurally. Only the
+ * user-facing boundary (CLI/orchestrator) and the plugin contract see the
+ * whole config.
+ */
+/** What swagger→TypeScript type mapping needs (getTypeScriptType and friends). */
+interface TypeMappingConfig {
+    options: {
+        dateType: "string" | "Date";
+    };
 }
+/** Options consumed by model/interface generation (TypeGenerator). */
+interface TypeGenOptions {
+    options: {
+        dateType: "string" | "Date";
+        enumStyle: "enum" | "union";
+        generateEnumBasedOnDescription?: boolean;
+        validation?: {
+            response?: boolean;
+        };
+    };
+}
+/** Options consumed by the service/resource method-generation chain. */
+interface MethodGenOptions {
+    options: {
+        dateType: "string" | "Date";
+        validation?: {
+            response?: boolean;
+        };
+        customHeaders?: Record<string, string>;
+        customizeMethodName?: (operationId: string) => string;
+        useSingleRequestParameter?: boolean;
+    };
+}
+/** Per-client runtime configuration consumed by the generated provider functions. */
 interface NgOpenapiClientConfig {
+    /** Unique identifier for this client (matches GeneratorConfig.clientName). */
     clientName: string;
     basePath: string;
     enableDateTransform?: boolean;
     interceptors?: (new (...args: HttpInterceptor[]) => HttpInterceptor)[];
 }
 
+/**
+ * Per-operation facts a method generator needs while emitting a body.
+ * The normalizer precomputes all of these onto NormalizedOperation —
+ * this shape survives for consumers that carry them separately.
+ */
+interface MethodGenerationContext {
+    pathParams: Array<{
+        name: string;
+        in: string;
+    }>;
+    queryParams: Array<{
+        name: string;
+        in: string;
+    }>;
+    hasBody: boolean;
+    isMultipart: boolean;
+    isUrlEncoded: boolean;
+    formDataFields: string[];
+    urlEncodedFields: string[];
+    responseType: "json" | "blob" | "arraybuffer" | "text";
+}
+/**
+ * Loose schema shape accepted by getTypeScriptType at boundaries where a
+ * fully-typed SwaggerDefinition isn't available (e.g. Swagger 2.0 parameters
+ * carrying type/format directly). The index signature admits raw spec JSON.
+ */
+interface TypeSchema {
+    type?: string;
+    format?: string;
+    $ref?: string;
+    items?: TypeSchema | TypeSchema[];
+    nullable?: boolean;
+    enum?: Array<string | number>;
+    [key: string]: unknown;
+}
+/** MethodGenerationContext subset that GET-only generation (http-resource) needs. */
+interface GetMethodGenerationContext {
+    pathParams: Array<{
+        name: string;
+        in: string;
+    }>;
+    queryParams: Array<{
+        name: string;
+        in: string;
+    }>;
+    responseType: "json" | "blob" | "arraybuffer" | "text";
+}
+
+/**
+ * Typed access to a parsed OpenAPI/Swagger spec.
+ * Loading (fs/http) lives in spec-loader.ts; format detection and parsing in
+ * spec-format.ts — this class is a façade over both plus spec accessors.
+ */
+declare class SwaggerParser {
+    private readonly spec;
+    private normalized?;
+    private constructor();
+    /**
+     * Loads, parses and wraps a spec.
+     *
+     * @throws SpecLoadError when the file/URL cannot be read.
+     * @throws SpecParseError when the content cannot be parsed or the
+     *   config's `validateInput` hook rejects the spec.
+     */
+    static create(swaggerPathOrUrl: string, config: GeneratorConfig): Promise<SwaggerParser>;
+    /**
+     * The version-free model generators consume. Computed once and cached —
+     * all generators share the same NormalizedOperation instances, so they
+     * can be used as Map keys across generators.
+     */
+    getNormalizedSpec(): NormalizedSpec;
+    /** Definition map regardless of version: 2.0 `definitions` or 3.x `components.schemas`. */
+    getDefinitions(): Record<string, SwaggerDefinition>;
+    /** One definition by bare name, or undefined when the spec has none by that name. */
+    getDefinition(name: string): SwaggerDefinition | undefined;
+    /** Resolves "#/definitions/X" / "#/components/schemas/X" style refs by their last segment. */
+    resolveReference(ref: string): SwaggerDefinition | undefined;
+    getAllDefinitionNames(): string[];
+    /** The raw parsed spec — prefer getNormalizedSpec() unless raw access is the point. */
+    getSpec(): SwaggerSpec;
+    getPaths(): SwaggerSpec["paths"];
+    /** Whether the spec declares a supported version (Swagger 2.x or OpenAPI 3.x). */
+    isValidSpec(): boolean;
+    /** Detected flavor + literal version string, or null when neither field is present. */
+    getSpecVersion(): {
+        type: "swagger" | "openapi";
+        version: string;
+    } | null;
+}
+
+/**
+ * Normalizes a parsed spec into the version-free model the generators consume.
+ * Everything here used to be re-derived per generator (service-method body,
+ * http-resource body, overloads) — computing it once keeps the derivations
+ * identical by construction.
+ */
+declare function normalizeSpec(spec: SwaggerSpec): NormalizedSpec;
+/**
+ * Normalizes the JSON-Schema constructs OpenAPI 3.1 introduced so generators
+ * never see them:
+ *
+ * - type arrays: `"null"` members fold into `nullable: true`, and a single
+ *   remaining type collapses to a plain string type — so `format`, `enum` and
+ *   friends keep working on nullable 3.1 schemas.
+ * - `const` becomes a single-value `enum`.
+ *
+ * Returns a deep copy; the raw spec is never mutated. Schemas without 3.1
+ * constructs come back semantically identical.
+ */
+declare function normalizeSchema(schema: SwaggerDefinition): SwaggerDefinition;
+
+/**
+ * Typed, user-facing errors of the spec pipeline.
+ *
+ * Hosts (CLI, programmatic callers, tests) branch on the error class — never
+ * on message text, which is presentation and not part of the API contract.
+ */
+/** Base class of every error ng-openapi raises deliberately. */
+declare class NgOpenApiError extends Error {
+    /** The underlying error that caused this one, when there is one. */
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * The spec input could not be read at all: missing/unreadable file,
+ * unsupported file extension, HTTP failure, timeout, or empty response.
+ * `source` is the offending path or URL — the CLI uses it to decide
+ * which hints to print.
+ */
+declare class SpecLoadError extends NgOpenApiError {
+    /** The file path or URL that failed to load. */
+    readonly source: string;
+    constructor(message: string, source: string, cause?: unknown);
+}
+/**
+ * The spec content was read but could not be used: malformed JSON/YAML,
+ * undeterminable format, an unsupported spec version, or a spec rejected
+ * by the user's `validateInput` hook.
+ */
+declare class SpecParseError extends NgOpenApiError {
+    /** The file path or URL the content came from, when known. */
+    readonly source?: string;
+    constructor(message: string, source?: string, cause?: unknown);
+}
+
+interface HeadersEmitOptions {
+    /** Identifier of the per-request options parameter in the generated method ("options", "requestOptions", …). */
+    optionsExpression: string;
+    /** Default headers from GeneratorConfig, added when not already present on the request. */
+    customHeaders?: Record<string, string>;
+    /** Content-Type rules derived from the operation's body; omit to skip (http-resource is GET-only). */
+    contentType?: {
+        isMultipart: boolean;
+        isUrlEncoded: boolean;
+        hasBody: boolean;
+    };
+}
+/**
+ * Emits the `headers` initialization block: normalize the caller-supplied
+ * headers into HttpHeaders, apply configured default headers, then apply
+ * Content-Type rules.
+ */
+declare function emitHeaders(options: HeadersEmitOptions): string;
+/**
+ * Merges configured default headers into caller headers that may be an
+ * HttpHeaders instance or a plain record (http-resource's request options).
+ * Cast-free: the plain record is never funneled through the HttpHeaders
+ * constructor, whose accepted value types are narrower than
+ * HttpResourceRequest's.
+ */
+declare function emitDefaultHeadersMerge(optionsExpression: string, customHeaders: Record<string, string>): string;
+
+/**
+ * Emits the `HttpParams` accumulation block for the core service method body.
+ * Returns "" when the operation has no query parameters.
+ */
+declare function emitQueryParams(queryParams: Parameter[]): string;
+/**
+ * Signal-aware variant for the http-resource plugin: each parameter may be a
+ * signal, so its value is read once before the null check.
+ */
+declare function emitSignalAwareQueryParams(queryParams: Parameter[]): string;
+
+/**
+ * Returns the request-options entry pinning a non-JSON response type, or ""
+ * for JSON (Angular's default). The entry is cast-free: it must be emitted
+ * into a contextually typed position (an options literal inlined into the
+ * `request()` call) so the literal keeps its narrow type.
+ */
+declare function emitResponseTypeOption(responseType: ResponseKind): string;
+/**
+ * Joins requestOptions entries, dropping empties and entries referencing
+ * undefined values, with the indentation both method bodies use.
+ */
+declare function joinRequestOptionEntries(entries: string[]): string;
+
+/** Identity read: the parameter identifier is a plain value. */
+declare function plainParamValue(identifier: string): string;
+/** Signal-aware read used by the http-resource plugin: the value may be a signal → call it. */
+declare function signalAwareParamValue(identifier: string): string;
+/**
+ * Builds the request-URL template literal, substituting `{param}` placeholders
+ * with the (camelCased) method parameter identifiers.
+ */
+declare function emitUrlExpression(path: string, pathParams: Parameter[], paramValue?: (identifier: string) => string): string;
+/** `const url = …;` statement used by the core service method body. */
+declare function emitUrlConstruction(path: string, pathParams: Parameter[]): string;
+
+/**
+ * Converts a string to camelCase. Dots, dashes, underscores and whitespace are
+ * treated as word separators and removed (`"pet_id"` → `"petId"`,
+ * `"filter.name"` → `"filterName"`).
+ */
 declare function camelCase(str: string): string;
+/** Converts a string to kebab-case (`"PetStore"` → `"pet-store"`). */
 declare function kebabCase(str: string): string;
+/**
+ * Converts a string to PascalCase. Dots, dashes, underscores and whitespace
+ * are treated as word separators and removed (`"pet_store"` → `"PetStore"`).
+ */
 declare function pascalCase(str: string): string;
+/** Converts a string to SCREAMING_SNAKE_CASE (`"PetStore"` → `"PET_STORE"`) — used for token names. */
 declare function screamingSnakeCase(str: string): string;
+/**
+ * PascalCase variant safe for generated type/enum identifiers: every
+ * non-alphanumeric character is a separator, and a leading digit is
+ * prefixed with `_` so the result is always a valid TS identifier.
+ */
 declare function pascalCaseForEnums(str: string): string;
 
 /**
  * Convert OpenAPI/Swagger types to TypeScript types
- * @param schemaOrType - Either a schema object or a type string
+ * @param schemaOrType - Either a schema object (loose TypeSchema or a parsed SwaggerDefinition) or a type string
  * @param config - generator configuration
  * @param formatOrNullable - Either format string (if first param is string) or nullable boolean
  * @param isNullable - Nullable boolean (only used if first param is string)
  * @param context - Whether this is for type generation or service generation
  */
-declare function getTypeScriptType(schemaOrType: TypeSchema | string | undefined, config: GeneratorConfig, formatOrNullable?: string | boolean, isNullable?: boolean, context?: "type" | "service"): string;
+declare function getTypeScriptType(schemaOrType: TypeSchema | SwaggerDefinition | string | undefined, config: TypeMappingConfig, formatOrNullable?: string | boolean, isNullable?: boolean, context?: "type" | "service"): string;
+/** Appends `| null` to a type expression when the schema is nullable. */
 declare function nullableType(type: string, isNullable?: boolean): string;
+/** Escapes backslashes and single quotes for embedding in a single-quoted generated literal. */
 declare function escapeString(str: string): string;
 
-type placeHolder = {};
+/** The content types the generators special-case when emitting method bodies. */
+declare const CONTENT_TYPES: {
+    MULTIPART: string;
+    FORM_URLENCODED: string;
+    JSON: string;
+};
 
+/**
+ * Names of the injection tokens emitted into each client's tokens/index.ts.
+ * The client name is normalized to SCREAMING_SNAKE (non-alphanumerics → `_`)
+ * and suffixed, so multiple clients can coexist in one application
+ * (`"PetsApi"` → `BASE_PATH_PETSAPI`); the default client uses `_DEFAULT`.
+ */
+/** Token identifying which client a request belongs to (read by interceptors). */
 declare function getClientContextTokenName(clientName?: string): string;
+/** Token providing the API base path for the client. */
 declare function getBasePathTokenName(clientName?: string): string;
+/** Token carrying the client's interceptor chain. */
 declare function getInterceptorsTokenName(clientName?: string): string;
 
+/** Whether two or more declarations share a name — generation aborts on colliding method names. */
 declare function hasDuplicateFunctionNames<T extends MethodDeclaration | FunctionDeclaration>(arr: T[]): boolean;
 
+/**
+ * Flattens the spec's `paths` object into one PathInfo per (path, method)
+ * pair, merging path-level parameters into each operation. Supports both
+ * Swagger 2.0 and OpenAPI 3.x path items; methods outside the given list
+ * (and vendor extensions) are ignored.
+ */
 declare function extractPaths(swaggerPaths?: {
     [p: string]: Path;
 }, methods?: string[]): PathInfo[];
 
+/**
+ * Angular `responseType` for a response: inspects every content type the
+ * response declares and picks the highest-priority match (JSON-like content
+ * beats text beats binary). `responseTypeMapping` lets the user config pin a
+ * responseType per content type; empty content defaults to "json".
+ */
 declare function getResponseTypeFromResponse(response: SwaggerResponse, responseTypeMapping?: {
     [p: string]: "json" | "blob" | "arraybuffer" | "text";
 }): "json" | "blob" | "arraybuffer" | "text";
-declare function isPrimitiveType(schema: any): boolean;
+/**
+ * Whether a schema resolves to a bare primitive (string/number/integer/
+ * boolean). Arrays, objects, $refs and compositions all count as complex.
+ */
+declare function isPrimitiveType(schema: SwaggerDefinition | undefined): boolean;
+/**
+ * Maps a MIME type (parameters like charset stripped) to the Angular
+ * `responseType` used when fetching it; unknown types are assumed binary.
+ */
 declare function inferResponseTypeFromContentType(contentType: string): "json" | "blob" | "arraybuffer" | "text";
-declare function getResponseType(response: SwaggerResponse, config: GeneratorConfig): string;
+/**
+ * TS type of a response body for generated signatures: schema-derived when
+ * the response declares one, otherwise Blob/ArrayBuffer/string per the
+ * detected responseType ("any" for schema-less JSON).
+ */
+declare function getResponseType(response: SwaggerResponse, config: TypeMappingConfig): string;
 
-declare function getRequestBodyType(requestBody: RequestBody, config: GeneratorConfig): string;
+/**
+ * TS type of an operation's JSON request body; `"any"` when the body has no
+ * JSON content or no schema. Multipart/urlencoded bodies are handled
+ * separately by the method-body emission.
+ */
+declare function getRequestBodyType(requestBody: RequestBody, config: TypeMappingConfig): string;
 
+/**
+ * Whether a rendered TS type expression refers to a generated model interface
+ * (as opposed to a primitive, `File`, an array or an inline shape) — used to
+ * decide parameter naming in generated methods.
+ */
 declare function isDataTypeInterface(type: string): boolean;
 
+/**
+ * Type-parameter expression for request-validation overloads: the request
+ * body's interface type (with `| undefined` when optional), or "" when the
+ * method has no interface-typed body parameter.
+ */
 declare function generateParseRequestTypeParams(params: OptionalKind<ParameterDeclarationStructure>[]): string;
 
-declare const CONTENT_TYPES: {
-    MULTIPART: string;
-    FORM_URLENCODED: string;
-    JSON: string;
-};
+/**
+ * Determines if input is a URL
+ */
+declare function isUrl(input: string): boolean;
+
+/**
+ * Identity helper for config files: full type inference and IDE autocomplete
+ * without a manual type annotation.
+ *
+ * @example
+ * ```typescript
+ * // openapi.config.ts
+ * import { defineConfig } from "ng-openapi";
+ *
+ * export default defineConfig({
+ *     input: "./swagger.json",
+ *     output: "./src/api",
+ *     options: { dateType: "Date", enumStyle: "enum" },
+ * });
+ * ```
+ *
+ * Purely compile-time sugar — runtime validation still happens in
+ * validateGeneratorConfig at the generation boundary.
+ */
+declare function defineConfig(config: GeneratorConfig): GeneratorConfig;
 
 declare const TYPE_GENERATOR_HEADER_COMMENT: string;
 declare const SERVICE_INDEX_GENERATOR_HEADER_COMMENT: string;
@@ -293,12 +693,58 @@ declare const ZOD_PLUGIN_GENERATOR_HEADER_COMMENT: (validatorName: string) => st
 declare const ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT: string;
 
 /**
- * Validates input (file or URL)
+ * Progress/diagnostics contract between the pure orchestrator and whatever
+ * hosts it (CLI, tests, programmatic callers). The orchestrator never logs;
+ * presentation lives entirely in the host's Reporter implementation.
+ */
+type GenerationPhase = "processing-spec" | "types-generated" | "services-generated" | "plugins-generated";
+interface Reporter {
+    /** Called when a generation phase completes (or, for "processing-spec", starts). */
+    onPhase?(phase: GenerationPhase): void;
+    /** Called for non-fatal problems; the same messages end up on GenerationResult.warnings. */
+    onWarning?(message: string): void;
+}
+/** Structured outcome of generateFromConfig — inspectable, no side channel. */
+interface GenerationResult {
+    /** clientName from the config, when set. */
+    client?: string;
+    /** Absolute paths of every file the generation wrote. */
+    filesWritten: string[];
+    /** Non-fatal problems encountered during generation. */
+    warnings: string[];
+    durationMs: number;
+}
+
+/**
+ * Validates input (file or URL).
+ *
+ * @throws SpecLoadError when a local input file is missing or has an
+ *   unsupported extension. URLs are validated by the loader when fetched.
  */
 declare function validateInput(inputPath: string): void;
 /**
- * Generates Angular services and types from a configuration object
+ * Generates Angular services and types from a configuration object.
+ *
+ * Pure orchestration: no logging, no process concerns. Progress and warnings
+ * are surfaced through the optional Reporter and the returned
+ * GenerationResult; presentation (emojis, hints, exit codes) is the CLI's job.
+ *
+ * @throws ConfigValidationError when the config is structurally invalid.
+ * @throws SpecLoadError when the input file/URL cannot be read.
+ * @throws SpecParseError when the spec cannot be parsed, has an unsupported
+ *   version, or is rejected by the config's `validateInput` hook.
  */
-declare function generateFromConfig(config: GeneratorConfig): Promise<void>;
+declare function generateFromConfig(config: GeneratorConfig, reporter?: Reporter): Promise<GenerationResult>;
+
+/**
+ * Thrown when the user-supplied config is structurally invalid. Collects every
+ * issue instead of failing on the first one, so a config file can be fixed in
+ * one pass.
+ */
+declare class ConfigValidationError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+declare function validateGeneratorConfig(config: unknown): asserts config is GeneratorConfig;
 
-export { BASE_INTERCEPTOR_HEADER_COMMENT, CONTENT_TYPES, type EnumValueObject, type GeneratorConfig, type GetMethodGenerationContext, HTTP_RESOURCE_GENERATOR_HEADER_COMMENT, type IPluginGenerator, type IPluginGeneratorClass, MAIN_INDEX_GENERATOR_HEADER_COMMENT, type MethodGenerationContext, type NgOpenapiClientConfig, type OpenApiSecurityScheme, PROVIDER_GENERATOR_HEADER_COMMENT, type Parameter, type PathInfo, REQUEST_PARAMS_GENERATOR_HEADER_COMMENT, type RequestBody, SERVICE_GENERATOR_HEADER_COMMENT, SERVICE_INDEX_GENERATOR_HEADER_COMMENT, type SwaggerDefinition, SwaggerParser, type SwaggerResponse, type SwaggerSpec, TYPE_GENERATOR_HEADER_COMMENT, type TypeSchema, ZOD_PLUGIN_GENERATOR_HEADER_COMMENT, ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT, camelCase, escapeString, extractPaths, generateFromConfig, generateParseRequestTypeParams, getBasePathTokenName, getClientContextTokenName, getInterceptorsTokenName, getRequestBodyType, getResponseType, getResponseTypeFromResponse, getTypeScriptType, hasDuplicateFunctionNames, inferResponseTypeFromContentType, isDataTypeInterface, isPrimitiveType, kebabCase, nullableType, pascalCase, pascalCaseForEnums, type placeHolder, screamingSnakeCase, validateInput };
+export { BASE_INTERCEPTOR_HEADER_COMMENT, CONTENT_TYPES, ConfigValidationError, type EnumValueObject, type GenerationPhase, type GenerationResult, type GeneratorConfig, type GetMethodGenerationContext, HTTP_RESOURCE_GENERATOR_HEADER_COMMENT, type HeadersEmitOptions, type IPluginGenerator, type IPluginGeneratorClass, MAIN_INDEX_GENERATOR_HEADER_COMMENT, type MethodGenOptions, type MethodGenerationContext, NgOpenApiError, type NgOpenapiClientConfig, type NormalizedOperation, type NormalizedSpec, type OpenApiSecurityScheme, PROVIDER_GENERATOR_HEADER_COMMENT, type Parameter, type PathInfo, type PluginGeneratorContext, REQUEST_PARAMS_GENERATOR_HEADER_COMMENT, type Reporter, type RequestBody, type ResponseKind, SERVICE_GENERATOR_HEADER_COMMENT, SERVICE_INDEX_GENERATOR_HEADER_COMMENT, SpecLoadError, SpecParseError, type SpecVersion, type SwaggerDefinition, SwaggerParser, type SwaggerResponse, type SwaggerSpec, TYPE_GENERATOR_HEADER_COMMENT, type TypeGenOptions, type TypeMappingConfig, type TypeSchema, ZOD_PLUGIN_GENERATOR_HEADER_COMMENT, ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT, camelCase, defineConfig, emitDefaultHeadersMerge, emitHeaders, emitQueryParams, emitResponseTypeOption, emitSignalAwareQueryParams, emitUrlConstruction, emitUrlExpression, escapeString, extractPaths, generateFromConfig, generateParseRequestTypeParams, getBasePathTokenName, getClientContextTokenName, getInterceptorsTokenName, getRequestBodyType, getResponseType, getResponseTypeFromResponse, getTypeScriptType, hasDuplicateFunctionNames, inferResponseTypeFromContentType, isDataTypeInterface, isPrimitiveType, isUrl, joinRequestOptionEntries, kebabCase, normalizeSchema, normalizeSpec, nullableType, pascalCase, pascalCaseForEnums, plainParamValue, screamingSnakeCase, signalAwareParamValue, validateGeneratorConfig, validateInput };