/**
 * OneBot 11 protocol helpers (no legacy Adapter/Endpoint / segment-mapper).
 * Canonicalization is owned by gateway/core before endpoint.send.
 * Spec: https://github.com/botuniverse/onebot-11
 */
import { type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
export interface OneBot11EndpointConfig {
    readonly connection?: 'ws' | 'wss';
    readonly id: string;
    readonly access_token?: string;
    readonly url?: string;
    readonly path?: string;
    readonly reconnect_interval?: number;
    readonly heartbeat_interval?: number;
}
export interface OneBot11ConfigBase {
    readonly context: 'onebot11';
    readonly id: string;
    readonly access_token?: string;
}
/** 正向 WebSocket：应用连 OneBot 实现的 WS 服务器 */
export interface OneBot11WsConfig extends OneBot11ConfigBase {
    readonly connection: 'ws';
    readonly url: string;
    readonly reconnect_interval: number;
    readonly heartbeat_interval: number;
}
/** 反向 WebSocket（slice 1 deferred — needs httpHostToken） */
export interface OneBot11WssConfig extends OneBot11ConfigBase {
    readonly connection: 'wss';
    readonly path: string;
    readonly heartbeat_interval: number;
}
export type ResolvedOneBot11Config = OneBot11WsConfig | OneBot11WssConfig;
export interface OneBot11Sender {
    readonly role?: string;
    readonly nickname?: string;
    readonly card?: string;
    readonly title?: string;
}
export interface OneBot11Segment {
    type: string;
    data?: Record<string, unknown>;
}
export interface OneBot11Event {
    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?: OneBot11Sender;
    message?: OneBot11Segment[];
    raw_message?: string;
    time?: number;
    notice_type?: string;
    request_type?: string;
    [key: string]: unknown;
}
export interface OneBot11ActionRequest {
    action: string;
    params: Record<string, unknown>;
    echo?: string;
}
export interface OneBot11ActionResponse {
    status: 'ok' | 'failed';
    retcode: number;
    data?: unknown;
    message?: string;
    echo?: string;
}
export interface OneBot11WireSegment {
    readonly type: string;
    readonly data?: Record<string, unknown>;
}
export declare function resolveOneBot11Config(config: OneBot11EndpointConfig): ResolvedOneBot11Config;
/** 判断是否为消息事件（post_type=message） */
export declare function isMessageEvent(ev: OneBot11Event): ev is OneBot11Event & {
    message_id: number | string;
};
/** 从事件得到场景 id：私聊 user_id，群 group_id */
export declare function getChannelId(ev: OneBot11Event): string;
/**
 * 入站归一化 → ConversationRef：OneBot 11 `group` 消息 → kind 'group'，
 * 其余（private 及带 group_id 的非 private 事件按群处理）→ kind 'private'。
 * OneBot 11 无 guild/temp 容器概念，不填 parent。
 */
export declare function onebot11InboundConversation(endpointKey: string, ev: OneBot11Event): ConversationRef;
/** Build inbound text for OutboundMessageService.receive */
export declare function formatInboundContent(ev: OneBot11Event): string;
export declare function senderDisplayName(ev: OneBot11Event): string;
/**
 * Runtime Message.sender 必须是用户 ID（agent bridge 用它与 endpointMaster 比对）。
 * user_id 缺失时兜底为空串，绝不回退到显示名。
 */
export declare function senderUserId(ev: OneBot11Event): string;
/** 显示名（群名片优先）放 metadata.nickname；没有则返回 undefined，不写该字段。 */
export declare function senderNickname(ev: OneBot11Event): string | undefined;
/**
 * 回复引用 id：优先取 message 数组中的 {type:'reply', data:{id}} 段；
 * 兼容部分实现把 reply 放在事件顶层（标量或带 message_id 的对象）。
 */
export declare function extractQuoteId(ev: OneBot11Event): string | undefined;
/** 扫描 message 段中的 at，qq 等于本机 uin（self_id）即视为被 @；`qq:'all'`（@全体）不算。 */
export declare function isOneBot11BotMentioned(input: {
    readonly selfId: string | undefined;
    readonly message?: readonly OneBot11Segment[];
}): boolean;
/** Inbound fields extracted from an event for gateway.receive (ws / wss 两个 endpoint 共用). */
export interface OneBot11InboundFields {
    readonly metadata: Readonly<Record<string, unknown>>;
    readonly endpointId: string;
    readonly mentioned: boolean;
    readonly replyTo: {
        readonly id: string;
    } | undefined;
}
/** 构造 gateway.receive 的 metadata 与提升字段（ws / wss 两个 endpoint 共用）。 */
export declare function formatInboundMetadata(ev: OneBot11Event, endpoint: string): OneBot11InboundFields;
/**
 * 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 11 message segments.
 * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
 * 媒体段只消费 canonical `data.media`（无 MediaRef 的媒体段 warn + 丢弃），
 * 其余 wire 形状段（at / 平台扩展段）原样透传。
 */
export declare function formatOutboundSegments(payload: unknown): OneBot11Segment[];
export declare function buildSendAction(conversation: ConversationRef, message: OneBot11Segment[]): {
    action: string;
    params: Record<string, unknown>;
};
/** Build WS connect URL + headers (access_token via Bearer + query). */
export declare function buildWsConnectOptions(config: OneBot11WsConfig): {
    readonly url: string;
    readonly headers: Record<string, string>;
    readonly safeUrl: string;
};