import { ExecuteTransport, MeshInstance, CollectionResult, MeshFile } from 'meshql-core';
import { Readable } from 'node:stream';

/** Supported MeshQL query transport formats. */
type QueryFormat = "json" | "ql";
/** Decoded query payload from HTTP headers. */
interface DecodedQuery {
    raw: string;
    format: QueryFormat;
    transport: ExecuteTransport;
}
/** Object carrying HTTP headers for query decoding. */
interface HeaderCarrier {
    headers: Record<string, string | string[] | undefined>;
}
/** Resolved persisted query payload. */
interface ResolvedQueryId {
    raw: string;
    format?: QueryFormat;
}
/** Options for {@link decodeQuery}. */
interface DecodeQueryOptions {
    /** Resolve a persisted query ID to its stored wire payload. */
    resolveQueryId?: (id: string) => ResolvedQueryId | undefined;
}
/** Read transport headers without decoding the query body. */
declare function readTransportHeaders(req: HeaderCarrier): ExecuteTransport;
/** Decode a MeshQL query from transport headers. */
declare function decodeQuery(req: HeaderCarrier, options?: DecodeQueryOptions): DecodedQuery;
/** Encode a MeshQL query into transport headers for HTTP requests. */
declare function encodeQuery(query: string, format?: QueryFormat): Record<string, string>;
/** Encode a persisted query ID into transport headers. */
declare function encodePersistedQuery(queryId: string, format?: QueryFormat): Record<string, string>;
/** Options for signing encoded query headers. */
interface SignQueryOptions {
    secret?: string;
    signingToken?: string;
    token?: string;
}
/** Encode and sign a MeshQL query for HTTP transport. */
declare function signQuery(query: string, options?: SignQueryOptions & {
    format?: QueryFormat;
}): Record<string, string>;
/** Encode and sign a persisted query ID for HTTP transport. */
declare function signPersistedQuery(queryId: string, options?: SignQueryOptions & {
    format?: QueryFormat;
}): Record<string, string>;

/** Response envelope returned by MeshQL HTTP handlers. */
type HandlerResult = Record<string, unknown> | CollectionResult<Record<string, unknown>> | null;
interface HttpRequest {
    method: string;
    params: Record<string, string | undefined>;
    headers: Record<string, string | string[] | undefined>;
    body?: unknown;
}
type HttpHandlerContext = DecodeQueryOptions;
declare function handleGet(mesh: MeshInstance, req: HttpRequest, context?: HttpHandlerContext): Promise<HandlerResult>;
declare function handlePost(mesh: MeshInstance, req: HttpRequest): Promise<HandlerResult>;
declare function handlePut(mesh: MeshInstance, req: HttpRequest, context?: HttpHandlerContext): Promise<HandlerResult>;

/** Options for multipart parsing. */
interface ParseMultipartOptions {
    /** Max total file bytes. Default 25 MiB. */
    maxBytes?: number;
    headers: Record<string, string | string[] | undefined>;
}
/** Result of parsing a multipart upload body. */
interface ParsedMultipart {
    file: MeshFile;
    /** Optional JSON metadata from a part named `meta`. */
    meta?: Record<string, unknown>;
}
/**
 * Stream-parse `multipart/form-data` into a single file and optional `meta` JSON.
 *
 * Rejects when `Content-Length` exceeds `maxBytes` (default 25 MiB) or when
 * the accumulated file size exceeds the limit during streaming.
 */
declare function parseMultipart(stream: Readable, options: ParseMultipartOptions): Promise<ParsedMultipart>;
/** SHA-256 content hash in the form `sha256:<hex>`. */
declare function hashFileContent(buffer: Buffer): Promise<string>;

/** HTTP request shape for upload handling. */
interface UploadHttpRequest {
    method: string;
    params: Record<string, string | undefined>;
    headers: Record<string, string | string[] | undefined>;
    /** Raw request stream (multipart body). */
    stream: Readable;
    /** Max upload bytes; defaults to 25 MiB. */
    maxBytes?: number;
}
/** Pull the upload field name from a signed wire payload. */
declare function extractUploadField(raw: string, entity: string): string | undefined;
/** Handle a multipart upload request. */
declare function handleUpload(mesh: MeshInstance, req: UploadHttpRequest): Promise<Record<string, unknown>>;

/**
 * HTTP transport for MeshQL queries and framework-agnostic request handling.
 *
 * @example
 * ```ts
 * import { createMesh } from "meshql-core";
 * import { createHttpHandler } from "meshql-http";
 *
 * const mesh = createMesh({ entities: { user: { table: "users" } } });
 * const handler = createHttpHandler(mesh);
 *
 * const { status, body } = await handler({
 *   method: "GET",
 *   params: { entity: "user", id: "123" },
 *   headers: { "x-mesh-query": "...", "x-mesh-format": "json" },
 * });
 * ```
 */

/** Options for {@link createHttpHandler}. */
interface HttpHandlerOptions {
    basePath?: string;
    resolveQueryId?: DecodeQueryOptions["resolveQueryId"];
}
/** Low-level HTTP handler for MeshQL requests. */
type MeshHttpHandler = (req: HttpRequest) => Promise<{
    status: number;
    body: unknown;
}>;
/** Map any thrown value to an HTTP status and JSON error body. */
declare function toErrorResponse(error: unknown): {
    status: number;
    body: Record<string, unknown>;
};
/** Create a framework-agnostic MeshQL HTTP handler. */
declare function createHttpHandler(mesh: MeshInstance, options?: HttpHandlerOptions): MeshHttpHandler;

export { type DecodeQueryOptions, type DecodedQuery, type HttpHandlerOptions, type HttpRequest, type MeshHttpHandler, type ParseMultipartOptions, type ParsedMultipart, type QueryFormat, type ResolvedQueryId, type SignQueryOptions, type UploadHttpRequest, createHttpHandler, decodeQuery, encodePersistedQuery, encodeQuery, extractUploadField, handleGet, handlePost, handlePut, handleUpload, hashFileContent, parseMultipart, readTransportHeaders, signPersistedQuery, signQuery, toErrorResponse };