import type Koa from "koa";
import type { VextResponse } from "../../types/response.js";
/**
 * Koa Context → VextResponse 转换
 *
 * 核心设计（与 Hono / Fastify / Express Adapter 的 response.ts 逻辑对齐）：
 *
 *   1. 延迟绑定 requestId（getRequestId getter）
 *      requestId 在 createVextResponse 调用时尚未生成（requestId 中间件还没执行），
 *      传入 getter 函数确保 json() 实际调用时才取值（此时 requestId 必然已由中间件生成）。
 *
 *   2. 内建出口包装（_wrapEnabled 标志）
 *      response-wrapper 中间件通过 _enableWrap() 开启包装标志。
 *      json() 根据标志决定是否将响应体包装为 { code: 0, data, requestId }。
 *      rawJson() 始终绕过包装——仅供框架内部错误处理使用。
 *
 *   3. 重复发送保护（_sent 标志）
 *      防止 handler 中误调用多次 res.json()，dev 模式打印警告，生产模式静默忽略。
 *
 *   4. 链式调用（status / setHeader 返回 this）
 *      res.status(201).json(data) 正确设置 HTTP 201。
 *
 *   5. 204 No Content 合规（RFC 9110 §15.3.5）
 *      无论包装是否开启，204 均发送无消息体的响应。
 *
 *   6. 手动 JSON 序列化
 *      使用 ctx.res.end(JSON.stringify(...)) 而非 ctx.body = object，
 *      避免 Koa 内置的响应体处理（自动 Content-Type 推断、自动 JSON 序列化），
 *      保证与 Hono / Fastify / Express Adapter 行为一致（跨 Adapter 行为一致性 > 单 Adapter 便利性）。
 *
 * 与其他 Adapter 的差异：
 *   - Hono: 通过 ResponseBox 容器捕获 c.json() 返回的 Web Response 对象
 *   - Fastify: 直接调用 reply.status().header().send() 发送响应
 *   - Express: 直接调用 expressRes.statusCode + setHeader() + end() 发送响应
 *   - Koa: 通过 ctx.res（Node.js 原生 ServerResponse）直接操作，
 *     绕过 Koa 的 ctx.body / ctx.status 赋值模式，避免 Koa 后续的响应体自动处理
 *     与 vext 的手动控制产生冲突。
 *
 * 时序保证：
 *   createVextResponse(ctx, () => req.requestId)
 *     ↓ executeChain 开始
 *   [requestIdMiddleware]        → req.requestId = 'a1b2c3d4...'
 *   [responseWrapperMiddleware]  → res._enableWrap()
 *     ↓
 *   [handler] res.status(201).json(data)
 *     → _wrapEnabled = true
 *     → getRequestId() → 'a1b2c3d4...'（已设置）
 *     → ctx.res.end(JSON.stringify({ code: 0, data, requestId }))
 *     → HTTP 201 ✅
 *
 * @param ctx            Koa Context 对象
 * @param getRequestId   延迟获取 requestId 的 getter 函数
 * @returns VextResponse 实例（含内部方法 _enableWrap）
 *
 * @see adapters/hono/response.ts（Hono Adapter 对应实现）
 * @see adapters/fastify/response.ts（Fastify Adapter 对应实现）
 * @see adapters/express/response.ts（Express Adapter 对应实现）
 */
export declare function createVextResponse(ctx: Koa.Context, getRequestId: () => string): VextResponse;