/**
 * NapCat protocol helpers (OneBot 11 + NapCat extensions).
 * No legacy Adapter/Endpoint / segment-mapper.
 * Canonicalization is owned by gateway/core before endpoint.send.
 */
import { type MediaRef } from '@zhin.js/core';
import type { ConversationRef } from '@zhin.js/im-contract';
/** Transitional legacy endpoint row (`endpoints[]` with `context: napcat`). */
export interface NapCatLegacyEndpointRow {
    readonly context?: string;
    readonly connection?: 'ws' | 'wss' | 'http';
    readonly id?: string;
    readonly access_token?: string;
    readonly url?: string;
    readonly path?: string;
    readonly http_url?: string;
    readonly post_path?: string;
    readonly reconnect_interval?: number;
    readonly heartbeat_interval?: number;
    readonly poll_interval?: number;
}
/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
export interface NapCatAdapterConfig {
    readonly connection?: 'ws' | 'wss' | 'http';
    readonly id?: string;
    readonly access_token?: string;
    readonly url?: string;
    readonly path?: string;
    readonly http_url?: string;
    readonly post_path?: string;
    readonly reconnect_interval?: number;
    readonly heartbeat_interval?: number;
    readonly poll_interval?: number;
    /** Transitional: legacy root `endpoints[]` with `context: napcat`. */
    readonly endpoints?: ReadonlyArray<NapCatLegacyEndpointRow>;
}
export interface NapCatConfigBase {
    readonly context: 'napcat';
    readonly id: string;
    readonly access_token?: string;
}
/** 正向 WebSocket：应用连 NapCat WS */
export interface NapCatWsConfig extends NapCatConfigBase {
    readonly connection: 'ws';
    readonly url: string;
    readonly reconnect_interval: number;
    readonly heartbeat_interval: number;
}
/** 反向 WebSocket：httpHostToken WS upgrade 入站/出站 */
export interface NapCatWssConfig extends NapCatConfigBase {
    readonly connection: 'wss';
    readonly path: string;
    readonly heartbeat_interval: number;
}
/** HTTP API + POST 上报：httpHostToken POST 入站 + http_url/{action} 出站 */
export interface NapCatHttpConfig extends NapCatConfigBase {
    readonly connection: 'http';
    readonly http_url: string;
    readonly post_path: string;
    readonly poll_interval: number;
}
export type ResolvedNapCatConfig = NapCatWsConfig | NapCatWssConfig | NapCatHttpConfig;
export type NapCatEndpointConfig = ResolvedNapCatConfig;
export interface NapCatSender {
    readonly role?: string;
    readonly nickname?: string;
    readonly card?: string;
    readonly title?: string;
    readonly user_id?: number;
}
export interface MessageSegment {
    type: string;
    data?: Record<string, unknown>;
}
export interface NapCatEvent {
    post_type: string;
    self_id?: number | string;
    message_type?: string;
    sub_type?: string;
    message_id?: number | string;
    user_id?: number | string;
    group_id?: number | string;
    sender?: NapCatSender;
    message?: MessageSegment[] | string;
    raw_message?: string;
    time?: number;
    notice_type?: string;
    request_type?: string;
    [key: string]: unknown;
}
export type NapCatMessageEvent = NapCatEvent & {
    post_type: 'message' | 'message_sent';
    message_id: number | string;
    user_id: number | string;
};
export interface NapCatActionRequest {
    action: string;
    params: Record<string, unknown>;
    echo?: string;
}
export interface NapCatActionResponse {
    status: string;
    retcode: number;
    data?: unknown;
    echo?: string;
    message?: string;
    wording?: string;
}
export interface NapCatWireSegment {
    readonly type: string;
    readonly data?: Record<string, unknown>;
}
export interface ParsedSendTarget {
    readonly message_type: 'private' | 'group';
    readonly id: string;
}
export declare function resolveNapCatConfig(config?: NapCatAdapterConfig): ResolvedNapCatConfig;
export declare function isMessageEvent(ev: NapCatEvent): ev is NapCatMessageEvent;
export declare function getChannelId(ev: NapCatEvent): string;
/**
 * 入站归一化 → ConversationRef：群消息 → kind 'group'；私聊临时会话
 * （sub_type 'group'）→ kind 'private' + 群容器进 `parent`；其余私聊 → 'private'。
 */
export declare function napcatInboundConversation(endpointKey: string, ev: NapCatEvent): ConversationRef;
/** 出站：ConversationRef → OneBot 私聊/群聊目标。 */
export declare function napcatOutboundTarget(conversation: ConversationRef): ParsedSendTarget;
export declare function formatInboundContent(ev: NapCatEvent): string;
/**
 * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
 * 显示名走 metadata.nickname，见 senderNickname。
 */
export declare function senderUserId(ev: NapCatEvent): string;
/** 显示名（群名片 card 优先于 nickname），没有则 undefined。 */
export declare function senderNickname(ev: NapCatEvent): string | undefined;
/**
 * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
 * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
 */
export declare function mediaRefToOneBotFile(media: MediaRef): string;
/**
 * Wire-encode an already-rendered outbound payload into OneBot message segments.
 * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
 * 媒体段（image/audio/video）仅认 canonical `data.media`，缺失则 warn + 丢弃；
 * 非媒体的 wire 段（at 等）原样透传。
 */
export declare function formatOutboundSegments(payload: unknown): MessageSegment[];
export declare function buildSendAction(target: ParsedSendTarget, message: MessageSegment[]): {
    action: string;
    params: Record<string, unknown>;
};
/** Build WS connect URL + headers (access_token via Bearer + query). */
export declare function buildWsConnectOptions(config: NapCatWsConfig): {
    readonly url: string;
    readonly headers: Record<string, string>;
    readonly safeUrl: string;
};
export interface NapCatHttpOptions {
    readonly http_url: string;
    readonly access_token?: string;
}
/**
 * 向 NapCat HTTP API 发送动作请求：POST {http_url}/{action}。
 * 供 connection:http 出站与纯协议测试使用。
 */
export declare function callNapCatHttpAction(options: NapCatHttpOptions, action: string, params?: Record<string, unknown>): Promise<NapCatActionResponse>;