import type { CommonTypes } from "./types.js";
/**
 * 适配器能力清单版本。
 *
 * 清单是协议、管理端、文档和契约测试共同消费的稳定 Seam。版本号只在清单
 * 结构本身发生变化时递增，与具体适配器包版本无关。
 */
export declare const ADAPTER_CAPABILITY_MANIFEST_VERSION: 1;
export type CapabilitySupport = "native" | "emulated" | "unsupported";
export type CapabilityAvailability = "always" | "permission" | "context";
export type CapabilityDirection = "send" | "receive" | "both";
export interface CapabilityDescriptor {
    /** native 为平台原生能力；emulated 表示 OneBots 做了有损或组合实现。 */
    support: CapabilitySupport;
    /** 能力是否依赖额外权限或当前会话上下文。 */
    availability?: CapabilityAvailability;
    scenes?: readonly CommonTypes.Scene[];
    /**
     * 已知且稳定的权限名提示。省略表示平台会按 token、资源角色或动作参数动态判权，
     * 不代表该能力无需权限。
     */
    permissions?: readonly string[];
    note?: string;
}
export interface SegmentCapabilityDescriptor extends CapabilityDescriptor {
    direction: CapabilityDirection;
}
export interface TransportCapabilityDescriptor extends CapabilityDescriptor {
    mode: "webhook" | "websocket" | "reverse_websocket" | "polling" | "sse" | "native";
}
export interface AdapterCapabilityManifest {
    version: typeof ADAPTER_CAPABILITY_MANIFEST_VERSION;
    actions: Readonly<Record<string, CapabilityDescriptor>>;
    events: Readonly<Record<string, CapabilityDescriptor>>;
    segments: Readonly<Record<string, SegmentCapabilityDescriptor>>;
    transports: Readonly<Record<string, TransportCapabilityDescriptor>>;
}
export type AdapterCapabilityDefinition = Omit<AdapterCapabilityManifest, "version">;
export declare const EMPTY_ADAPTER_CAPABILITIES: AdapterCapabilityManifest;
/**
 * 定义并校验适配器能力清单。
 *
 * 适配器应导出一个清单常量，并同时传给 Adapter 构造器和 AdapterRegistry。
 * 这样运行时查询、Web 展示与包元数据不会产生两套容易漂移的声明。
 */
export declare function defineAdapterCapabilities(definition: AdapterCapabilityDefinition): AdapterCapabilityManifest;
/** 在不信任的插件边界校验并复制能力清单，阻止调用方后续修改已发布契约。 */
export declare function normalizeAdapterCapabilities(manifest: AdapterCapabilityManifest): AdapterCapabilityManifest;
export type UnavailableEventNote = string | ((event: string, descriptor: CapabilityDescriptor) => string);
/**
 * 按账号实际可达的 canonical 事件收窄能力清单。
 *
 * 平台适配器应先把 intents、allowed_updates 等原生订阅配置投影为 canonical
 * 事件名，再交给此函数。这样协议/UI 不需要理解各平台订阅术语，也不会把
 * “适配器支持”与“当前账号已订阅”混为一谈。
 *
 * 当全部事件均可达时返回原始对象，便于管理 API 省略没有差异的账号清单。
 */
export declare function restrictAdapterEventCapabilities(manifest: AdapterCapabilityManifest, availableEvents: ReadonlySet<string>, unavailableNote: UnavailableEventNote): AdapterCapabilityManifest;
export type PlatformActionCapabilityResolver<TAction extends string> = CapabilityDescriptor | ((action: TAction) => CapabilityDescriptor);
/**
 * 从平台动作注册表生成能力描述。
 *
 * 平台动作名由可执行注册表产生，能力清单应从同一个集合派生，避免新增动作时遗漏
 * Web 展示与 `get_supported_actions`。需要按动作区分权限或上下文时传入 resolver。
 */
export declare function definePlatformActionCapabilities<TAction extends string>(actions: Iterable<TAction>, descriptor?: PlatformActionCapabilityResolver<TAction>): Readonly<Record<TAction, CapabilityDescriptor>>;
/** 返回原生或模拟实现的动作；明确标为 unsupported 的动作不会暴露给调用方。 */
export declare function listSupportedActions(manifest: AdapterCapabilityManifest): string[];
/**
 * 契约测试与注册阶段共用的清单断言。
 * 保持为无测试框架依赖的函数，使所有适配器都能直接复用。
 */
export declare function assertAdapterCapabilities(manifest: unknown): asserts manifest is AdapterCapabilityManifest;
export interface AdapterCapabilityProvider {
    describeCapabilities(accountId?: string): AdapterCapabilityManifest;
    getSupportedActions(accountId: string): Promise<string[]>;
    /** 通过统一参数对象调用标准或平台扩展动作。 */
    callAction?(accountId: string, action: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
    /** 判断动作是否由具体适配器实现，而不是落到 Adapter 基类的未支持实现。 */
    isActionImplemented?(action: string): boolean;
}
/**
 * Adapter 契约测试的最小入口：校验清单结构以及查询结果是否来自同一份声明。
 * 平台测试只需再验证清单中声明为 supported 的动作和事件确实可执行/可投影。
 */
export declare function assertAdapterCapabilityContract(adapter: AdapterCapabilityProvider, accountId?: string): Promise<void>;
/** 校验每个已声明支持的动作都有实际实现，防止能力清单与运行时漂移。 */
export declare function assertSupportedActionsImplemented(adapter: AdapterCapabilityProvider, manifest?: AdapterCapabilityManifest): void;
/** 将协议层使用的 snake_case 动作名转换为 Adapter 的 camelCase 方法名。 */
export declare function adapterActionMethodName(action: string): string;
/**
 * 判断动作是否属于 Adapter 的正式 canonical 接口面。
 *
 * 只检查 AdapterActionDefaults，避免把 getAccount 等内部实例方法误当作远程动作。
 */
export declare function isCanonicalAdapterAction(action: string): boolean;