import { ApiDeps } from '@nanoesis/editor-api';

/**
 * Identity reported to MCP clients on `initialize`. Defaults: `{ name: 'nanoesis', version:
 * '0.0.0' }`. Adopters embedding the HTTP route in their own host typically override `name`
 * with their site identifier and `version` with their app version so client UIs identify
 * the deployment, not the framework.
 */
interface McpServerIdentity {
    readonly name?: string;
    readonly version?: string;
}

/**
 * Options for {@link handleMcpRequest}. Both fields are passed straight through to the
 * MCP `Server`'s `initialize` response so client UIs (Claude Desktop, Cursor, …) identify
 * the deployment rather than the framework.
 */
type HandleMcpRequestOptions = McpServerIdentity;
/**
 * Handle a single MCP HTTP request over the SDK's web-standard Streamable HTTP transport
 * (DESIGN §11c/§14). Stateless: each call builds a fresh `Server` + `Transport` pair, so
 * the caller's per-request `Authorization: Bearer …` header — propagated by the SDK into
 * the request handlers as `extra.requestInfo.headers` — drives the editor's per-user role
 * gate exactly as `/api/*` does.
 *
 * The signature is Fetch-API neutral: any runtime that hands a handler a standard
 * `Request` (Azure Functions v4, Cloudflare Workers, plain Node 18+, Bun, Deno, Hono)
 * wires it the same way:
 *
 * ```ts
 * import { handleMcpRequest } from '@xtrable-ltd/nanoesis/mcp';
 * // ... build `deps` once at startup
 * app.http('mcp', {
 *   methods: ['POST', 'GET', 'DELETE'],
 *   handler: (req) => handleMcpRequest(deps, req, { name: 'my-site', version: pkg.version }),
 * });
 * ```
 *
 * Runtimes whose request shape is not a standard `Request` (e.g. Azure Functions' enhanced
 * HttpRequest, Express' IncomingMessage) translate to/from `Request`/`Response` at the
 * boundary — that translation is adopter-side because it depends on the host runtime; the
 * MCP server construction and transport handling, which used to be ~120 lines of inlined
 * boilerplate per adopter, is now this one call.
 */
declare function handleMcpRequest(deps: ApiDeps, request: Request, opts?: HandleMcpRequestOptions): Promise<Response>;

export { type HandleMcpRequestOptions, handleMcpRequest };
