import { z } from 'zod';

/**
 * OpenApiRegistry — collects Zod schemas and path specs, emits a
 * complete `OpenAPIObject` on `build()` (OPENAPI-1).
 *
 * Wraps `@anatine/zod-openapi` as an **optional peer dependency** using
 * the lazy-import pattern from `runtime/subsystems/analytics/cube-backend.ts`
 * — consumer apps that never call `build()` still boot even if
 * `@anatine/zod-openapi` isn't installed.
 *
 * The registry is the single source of truth consumed by OPENAPI-2
 * (generated DTOs register their Zod schemas at module init), OPENAPI-3
 * (controller decorators reference those schemas), and OPENAPI-4
 * (Swagger UI bootstrap calls `build()` once at startup).
 */

type HttpMethod = 'get' | 'post' | 'patch' | 'delete' | 'put';
/**
 * OpenAPI path spec. Structurally compatible with `openapi3-ts`'s
 * `OperationObject` but typed loosely here because the peer type package
 * isn't installed as a direct dep — consumers supply whatever their
 * codegen emits.
 */
interface PathSpec {
    summary?: string;
    description?: string;
    operationId?: string;
    tags?: string[];
    parameters?: unknown[];
    requestBody?: unknown;
    responses?: Record<string, unknown>;
    security?: unknown[];
    [key: string]: unknown;
}
interface OpenAPIInfo {
    title: string;
    version: string;
    description?: string;
}
/**
 * Minimal OpenAPIObject shape. We redeclare rather than pull
 * `openapi3-ts` types through the peer — the peer's `generateSchema`
 * returns a `SchemaObject`, but the final document assembly is ours.
 */
interface OpenAPIObject {
    openapi: string;
    info: OpenAPIInfo;
    paths: Record<string, Record<string, PathSpec>>;
    components: {
        schemas: Record<string, unknown>;
    };
}
interface PeerModule {
    generateSchema: (zodRef: unknown, useOutput?: boolean, version?: '3.0' | '3.1') => unknown;
}
declare class OpenApiRegistry {
    private zodSchemas;
    private pathEntries;
    private peer;
    constructor();
    registerSchema(name: string, schema: z.ZodType): void;
    registerPath(path: string, method: HttpMethod, spec: PathSpec): void;
    /**
     * Emit the full OpenAPI document. Lazy-imports `@anatine/zod-openapi`
     * on first call; failure to resolve raises `OpenApiPeerDepMissingError`
     * (matches the `CubeAnalyticsBackend.onModuleInit` precedent).
     *
     * OpenAPI version is pinned to `3.0.3` — Swagger UI tooling is most
     * stable on 3.0.x (see OPENAPI-PHASE-1-PLAN §Four locked decisions).
     */
    build(info: OpenAPIInfo): Promise<OpenAPIObject>;
    /**
     * Test helper — clears registered schemas and paths, then re-seeds the
     * core `ErrorResponseDto` entry so post-reset state matches the
     * invariant established in the constructor.
     */
    reset(): void;
    protected loadPeer(): Promise<PeerModule>;
}

export { type HttpMethod, type OpenAPIInfo, type OpenAPIObject, OpenApiRegistry, type PathSpec };
