@kody/api-research

import { fetchOpenApiSpecText } from './fetch-spec-lib.ts'
import { parseOpenApiSpec } from './parse-spec-lib.ts'
import {
	summarizeOpenApiSpec,
	type OpenApiSpecSummary,
} from './summarize-spec-lib.ts'

export type SummarizeSpecInput = {
	/** HTTPS URL of an OpenAPI 3.x document (JSON or YAML). */
	specUrl: string
	/** Max operations to return after filtering (default 300). */
	maxOperations?: number
	operationFilter?: {
		tags?: Array<string>
		pathPrefixes?: Array<string>
		search?: string
	}
}

export type SummarizeSpecOutput = OpenApiSpecSummary & {
	specUrl: string
}

/**
 * Fetch, parse, and summarize an OpenAPI 3.x document for wiring a Kody package.
 * Use after discover when a surface.spec URL is available, before hand-coding a client.
 *
 * @param input - Spec URL plus optional operation filters
 * @returns Title, servers, auth paths, smoke-test candidates, and operations
 *
 * @example
 * import summarizeSpec from 'kody:@kody/api-research/summarize-spec'
 * const summary = await summarizeSpec({
 *   specUrl: 'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
 *   operationFilter: { search: 'user' },
 *   maxOperations: 20,
 * })
 */
export default async function summarizeSpec(
	input: SummarizeSpecInput,
): Promise<SummarizeSpecOutput> {
	const rawText = await fetchOpenApiSpecText({ specUrl: input.specUrl })
	const parsed = parseOpenApiSpec(rawText)
	const summary = summarizeOpenApiSpec(parsed, {
		maxOperations: input.maxOperations,
		operationFilter: input.operationFilter,
	})
	return { specUrl: input.specUrl, ...summary }
}

export { summarizeOpenApiSpec } from './summarize-spec-lib.ts'