import type { EndpointManifestDefinition, EndpointManifestEndpointDefinition } from '@wp-typia/block-runtime/metadata-core';
import { type EndpointAuthIntent, type EndpointWordPressAuthDefinition, type JsonSchemaDocument } from './schema-core.js';
import { type AbilitySpecCatalog } from '../add/ability-spec.js';
export type { AbilityAnnotationSpec, AbilityCategorySpec, AbilityMcpProjectionSpec, AbilityMetaSpec, AbilitySpec, AbilitySpecCatalog, } from '../add/ability-spec.js';
/**
 * Represents one projected WordPress-native ability derived from an endpoint
 * manifest plus an AbilitySpec definition.
 */
export interface ProjectedWordPressAbilityDefinition {
    /** Normalized auth intent derived from the endpoint manifest. */
    authIntent: EndpointAuthIntent;
    /** Optional auth mode propagated from the manifest when present. */
    authMode?: EndpointManifestEndpointDefinition['authMode'];
    /** Shared category identifier resolved from the AbilitySpec catalog. */
    category: string;
    /** Human-readable summary shown to ability discovery consumers. */
    description: string;
    /** PHP callback that executes the ability. */
    executeCallback: string;
    /** Stable generated ability identifier. */
    id: string;
    /** Optional projected input schema, or null when no input exists. */
    inputSchema: Record<string, unknown> | null;
    /** Display label propagated from the AbilitySpec layer. */
    label: string;
    /** WordPress-owned metadata preserved in the projected document. */
    meta: Record<string, unknown>;
    /** HTTP method from the source endpoint manifest. */
    method: EndpointManifestEndpointDefinition['method'];
    /** Source operation identifier from the endpoint manifest. */
    operationId: string;
    /** Projected AI response schema shared by the document. */
    outputSchema: Record<string, unknown>;
    /** HTTP path from the source endpoint manifest. */
    path: string;
    /** PHP permission callback that gates the ability. */
    permissionCallback: string;
    /** Optional WordPress auth metadata preserved for downstream adapters. */
    wordpressAuth?: EndpointWordPressAuthDefinition;
}
/**
 * Bundles a single-category WordPress AI abilities document together with the
 * metadata that describes how it was generated.
 */
export interface ProjectedWordPressAbilitiesDocument {
    /** Ability definitions generated from the current manifest and AbilitySpec map. */
    abilities: ProjectedWordPressAbilityDefinition[];
    /** Shared category metadata for the generated document. */
    category: {
        id: string;
        label: string;
    };
    /** Source metadata that points downstream consumers at the generated schema. */
    generatedFrom: {
        blockSlug: string;
        responseSchemaPath: string;
        schemaProfile: 'ai-structured-output';
    };
}
/**
 * Carries the projected input schema plus endpoint metadata into an optional
 * transform hook.
 */
export interface WordPressAiInputSchemaTransformContext {
    /** Name of the input contract being transformed. */
    contractName: string;
    /** Source endpoint that requested the input schema. */
    endpoint: EndpointManifestEndpointDefinition;
    /** Already-projected AI-friendly input schema. */
    schema: JsonSchemaDocument & Record<string, unknown>;
}
interface BuildWordPressAbilitiesDocumentOptions {
    abilityCatalog: AbilitySpecCatalog;
    buildAbilityId?: (operationId: string) => string;
    generatedFrom: ProjectedWordPressAbilitiesDocument['generatedFrom'];
    loadInputSchema?: (endpoint: EndpointManifestEndpointDefinition, contractName: string) => Promise<JsonSchemaDocument & Record<string, unknown>>;
    manifest: EndpointManifestDefinition;
    outputSchema: Record<string, unknown>;
    transformInputSchema?: (context: WordPressAiInputSchemaTransformContext) => JsonSchemaDocument & Record<string, unknown>;
}
interface BuildWordPressAiArtifactsOptions extends Omit<BuildWordPressAbilitiesDocumentOptions, 'outputSchema'> {
    responseSchema: JsonSchemaDocument & Record<string, unknown>;
}
/**
 * Projects a canonical schema into the AI structured-output profile used by
 * WordPress AI artifact generation.
 *
 * @param schema Canonical JSON Schema document from the manifest-owned source.
 * @returns The projected AI-friendly schema document.
 */
export declare function projectWordPressAiSchema(schema: JsonSchemaDocument & Record<string, unknown>): JsonSchemaDocument & Record<string, unknown>;
/**
 * Builds a WordPress abilities document from a manifest-first REST surface and
 * a matching AbilitySpec catalog.
 *
 * Input schemas are loaded lazily per endpoint only when an input contract
 * exists, and `transformInputSchema` runs after the schema has already been
 * projected into the AI structured-output profile.
 *
 * @param options Manifest, ability catalog, and projected output schema inputs.
 * @returns The generated WordPress abilities document.
 * @throws When an endpoint is missing an AbilitySpec.
 * @throws When categories are missing, inconsistent, or span multiple documents.
 * @throws When an endpoint references a missing input contract or no loader was supplied.
 */
export declare function buildWordPressAbilitiesDocument({ abilityCatalog, buildAbilityId, generatedFrom, loadInputSchema, manifest, outputSchema, transformInputSchema }: BuildWordPressAbilitiesDocumentOptions): Promise<ProjectedWordPressAbilitiesDocument>;
/**
 * Builds the projected AI response schema together with its companion
 * WordPress abilities document.
 *
 * All endpoints must share the same response contract and category so the
 * generated artifacts stay aligned with one manifest-owned response surface.
 *
 * @param options Manifest, ability catalog, and response schema inputs.
 * @returns The projected AI response schema and generated abilities document.
 * @throws When the manifest has no endpoints.
 * @throws When the shared response contract is missing or inconsistent.
 */
export declare function buildWordPressAiArtifacts({ abilityCatalog, buildAbilityId, generatedFrom, loadInputSchema, manifest, responseSchema, transformInputSchema }: BuildWordPressAiArtifactsOptions): Promise<{
    abilitiesDocument: ProjectedWordPressAbilitiesDocument;
    aiResponseSchema: Record<string, unknown>;
}>;