import { ProcedureDescriptor } from '@voltro/protocol';
import { RestRouteDescriptor } from '@voltro/protocol/rest';
import { VoltroPlugin } from '@voltro/protocol';

/**
 * A body derived from a wire JSON schema, deterministically — the same schema
 * always derives the same body, so a generated collection's diff stays quiet.
 * Not a substitute for an author's `publicApi.example`: it exists so an
 * operation without one is not an empty body in Swagger UI and in every
 * collection, and it is marked `x-voltro-example: derived` where it is used.
 */
export declare const deriveExample: (schema: JsonObject, defs: Record<string, unknown>, depth?: number) => unknown;

/**
 * Build the full OpenAPI 3.1 document from a list of REST descriptors and,
 * optionally, the rpc procedure descriptors.
 *
 * Overloads keep the original `(routes, info)` shape working while adding the
 * `(routes, info, sources)` form that folds in rpc procedures.
 */
export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info?: OpenApiInfo): OpenApiDocument;

export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info: OpenApiInfo, sources: OpenApiSources, options?: OpenApiGenerateOptions): OpenApiDocument;

declare type JsonObject = Record<string, unknown>;

/** Every version mounted, newest first (`v2` before `v1`). */
export declare const mountedVersions: (routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => ReadonlyArray<string>;

/** A minimal OpenAPI 3.1 document — the shape `generateOpenApiSpec` returns.
 *  Deliberately narrow: it names the top-level keys a deployment reads (so the
 *  public `.d.ts` documents the contract) while leaving the per-operation
 *  `paths` / `components.schemas` values open — those are full OpenAPI objects
 *  the JSON-Schema converter assembles, not worth re-typing here. */
export declare interface OpenApiDocument {
    readonly openapi: '3.1.0';
    readonly info: {
        readonly title: string;
        readonly version: string;
        readonly description?: string;
        readonly contact?: OpenApiInfo['contact'];
        readonly license?: OpenApiInfo['license'];
        readonly termsOfService?: string;
        readonly 'x-logo'?: OpenApiInfo['logo'];
    };
    readonly servers?: ReadonlyArray<{
        readonly url: string;
        readonly description?: string;
        readonly 'x-voltro-environment'?: string;
    }>;
    readonly externalDocs?: OpenApiExternalDocs;
    readonly 'x-voltro-environment'?: string;
    /** The digest of the projected surface — what a generated client was built
     *  from, and what `voltro check --public-api --against` compares. */
    readonly 'x-voltro-surface-digest'?: string;
    readonly paths: Record<string, Record<string, unknown>>;
    /** Every tag group an operation uses, with its description when one was given. */
    readonly tags?: ReadonlyArray<{
        readonly name: string;
        readonly description?: string;
        readonly externalDocs?: OpenApiExternalDocs;
    }>;
    readonly components: {
        readonly schemas: Record<string, unknown>;
        readonly securitySchemes?: Record<string, unknown>;
    };
}

export declare interface OpenApiExternalDocs {
    readonly url: string;
    readonly description?: string;
}

/** What the generator knows beyond the routes: a description per tag group
 *  (`teams` → "Teams and membership"), for the document's `tags[]`. */
export declare interface OpenApiGenerateOptions {
    readonly tagDescriptions?: Readonly<Record<string, string>>;
    /** A link per tag group — the handbook page of a domain — for `tags[].externalDocs`. */
    readonly tagExternalDocs?: Readonly<Record<string, OpenApiExternalDocs>>;
    /** The document's `externalDocs`. */
    readonly externalDocs?: OpenApiExternalDocs;
    /** The document's `servers` — the first entry is what a generated client
     *  and a collection take as the default base URL. */
    readonly servers?: ReadonlyArray<OpenApiServer>;
    /** The environment THIS instance serves (`x-voltro-environment` on the
     *  document): `dev`, `staging`, `production`, … */
    readonly environment?: string;
}

export declare interface OpenApiInfo {
    readonly title?: string;
    readonly version?: string;
    readonly description?: string;
    /** The API team a consumer writes to — `info.contact`. */
    readonly contact?: {
        readonly name?: string;
        readonly url?: string;
        readonly email?: string;
    };
    /** `info.license`. */
    readonly license?: {
        readonly name: string;
        readonly url?: string;
        readonly identifier?: string;
    };
    /** `info.termsOfService` — a URL. */
    readonly termsOfService?: string;
    /** `x-logo` — what ReDoc renders at the top of the page. */
    readonly logo?: {
        readonly url: string;
        readonly altText?: string;
        readonly backgroundColor?: string;
    };
}

export declare const openapiPlugin: (options: OpenApiPluginOptions) => VoltroPlugin;

export declare interface OpenApiPluginOptions {
    /** The REST descriptors to document (the same array you pass to `restRoutes`).
     *  Optional — a spec of ONLY rpc procedures is valid (pass `procedures`). */
    readonly routes?: ReadonlyArray<RestRouteDescriptor<any, any>>;
    /**
     * rpc procedure descriptors to project into the spec — the queries /
     * mutations / actions / streams your app defines. Each becomes a
     * `POST /rpc/<name>` operation. Opt-in: omit to keep the spec REST-only.
     * (Mixing rpc + REST in one spec is fine — the rpc ops are tagged `rpc` and
     * flagged `x-voltro-rpc` so consumers can tell them apart.)
     */
    readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
    /** Spec metadata. */
    readonly info?: OpenApiInfo;
    /** A description per tag group (`teams` → 'Teams and membership'), for the
     *  document's `tags[]`. A group with no entry is listed by name. */
    readonly tagDescriptions?: Readonly<Record<string, string>>;
    /** A link per tag group — the handbook page of a domain — for
     *  `tags[].externalDocs`. */
    readonly tagExternalDocs?: Readonly<Record<string, OpenApiExternalDocs>>;
    /** The document's `externalDocs`. */
    readonly externalDocs?: OpenApiExternalDocs;
    /**
     * Where the API is reachable — the document's `servers`. The first entry is
     * the default base URL of a generated client and of a collection, and every
     * entry becomes one environment file there. Omitted: one entry from
     * `VOLTRO_PUBLIC_API_ORIGIN` when that is set (the public origin of THIS
     * api — `VOLTRO_API_ORIGIN` is the web app's server-side route to it, and
     * `VOLTRO_PUBLIC_URL` the storage plugin's), tagged with `environment`.
     */
    readonly servers?: ReadonlyArray<OpenApiServer>;
    /**
     * The environment this instance serves — `dev`, `staging`, `production` —
     * written as `x-voltro-environment` on the document and on the default
     * server entry. Default `VOLTRO_ENVIRONMENT`, else `production` under
     * `NODE_ENV=production` and `dev` otherwise.
     */
    readonly environment?: string;
    /** Path to serve the JSON spec. Default `/openapi.json`. */
    readonly specPath?: string;
    /** Path to serve the Swagger-UI page. Default `/docs`. `false` disables it. */
    readonly docsPath?: string | false;
    /**
     * Require `Authorization: Bearer <token>` on BOTH the spec and the docs
     * route. Default `OPENAPI_DOCS_TOKEN` env; unset → open (the spec/docs are
     * public — gate at the network layer, or set this for a public deployment).
     */
    readonly token?: string;
    readonly name?: string;
    /**
     * Document the app's OWN REST surface as the framework mounts it — every
     * `restRoutes` descriptor and every `publicApi` projection — without listing
     * them here. Default `true`. The framework hands the plugin the mounted
     * routes (`onRestSurface`) once they exist, on both boot paths; a route also
     * passed in `routes` is documented once. `false` documents `routes` and
     * `procedures` only.
     */
    readonly includeAppRoutes?: boolean;
    /**
     * Document the app's OWN rpc procedures — every query, mutation, action and
     * stream discovery found, minus `internal` ones — without listing them in
     * `procedures`. Default `false`: the spec stays REST-only unless asked. The
     * framework hands the plugin the discovered descriptors
     * (`onProcedureSurface`) once discovery has run, on both boot paths; one
     * also passed in `procedures` is documented once. Importing the descriptor
     * modules into `app.config.ts` to fill `procedures` evaluates every one of
     * them before discovery on every load of the config — this option is the
     * way around that.
     */
    readonly includeAppProcedures?: boolean;
}

/** One `servers[]` entry: where the API is reachable, and for which
 *  environment (`x-voltro-environment`), so a collection can write one
 *  environment file per entry. */
export declare interface OpenApiServer {
    readonly url: string;
    readonly description?: string;
    /** `dev` | `staging` | `production` — free text; the entry's environment. */
    readonly environment?: string;
}

/** Extra sources to fold into the spec beyond the REST `routes`. Today: the
 *  rpc procedure descriptors (queries / mutations / actions / streams). */
export declare interface OpenApiSources {
    /** rpc procedure descriptors to project into the spec. Each becomes a POST
     *  operation under `/rpc/<name>` (see `rpc.ts`). Opt-in — omit to keep the
     *  spec REST-only. */
    readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
}

/** RFC 9457 Problem Details — the error body of every projection under a
 *  `problem-details` profile. Published once; each typed error's response
 *  references it and names its `type`. */
export declare const PROBLEM_DETAILS_SCHEMA_NAME = "ProblemDetails";

/** One entry of Swagger UI's "Select a definition" dropdown. */
declare interface SwaggerUiDefinition {
    readonly url: string;
    readonly name: string;
}

export declare const swaggerUiHtml: (specUrl: string, title?: string, options?: SwaggerUiOptions) => string;

declare interface SwaggerUiOptions {
    /** Several definitions — one per API version — shown as a dropdown in the
     *  topbar (`urls`), instead of the single `url`. */
    readonly urls?: ReadonlyArray<SwaggerUiDefinition>;
    /** The dropdown's preselected entry (`urls.primaryName`). */
    readonly primaryName?: string;
}

/** The dropdown name of a version: the version, with the earliest `sunset`
 *  among its routes when one is declared — `v1 — sunset 2027-03-01`. */
export declare const versionLabel: (version: string, routes: ReadonlyArray<RestRouteDescriptor<any, any>>) => string;

export { }