import type { LogicalType } from "./logical-types";
import type { QuackMessage } from "./messages";
import type { ColumnSchema } from "./builders";
import type { QuackJsonOptions, QuackJsonRow } from "./json";
import type { SqlParameters } from "./sql";
import type { QuackDataChunk, QuackRow, QuackValue } from "./vector";
import type { QuackArrowAppendOptions, QuackArrowInput, QuackArrowIPCOptions, QuackArrowTableOptions } from "./arrow";
import type { Table as ArrowTable } from "@uwdata/flechette";
/** Options that apply to an individual Quack HTTP request. */
export interface QuackRequestOptions {
    /** Abort signal passed through to the underlying `fetch` request. */
    signal?: AbortSignal;
    /** Request timeout in milliseconds. */
    timeoutMs?: number;
}
/** Options used when opening a Quack connection. */
export interface QuackClientOptions extends QuackRequestOptions {
    /** Authentication token sent in the Quack connection request. */
    authToken?: string;
    /** Optional client DuckDB version string advertised to the server. */
    clientDuckdbVersion?: string;
    /** Optional client platform string advertised to the server. */
    clientPlatform?: string;
    /** Minimum Quack protocol version supported by the client. */
    minSupportedQuackVersion?: number | bigint;
    /** Maximum Quack protocol version supported by the client. */
    maxSupportedQuackVersion?: number | bigint;
    /** Custom fetch implementation, useful for tests or non-standard runtimes. */
    fetch?: typeof fetch;
    /** Extra HTTP headers merged into every Quack request. */
    headers?: HeadersInit;
    /** Force non-HTTP connection strings to resolve to HTTPS. */
    ssl?: boolean;
}
/** Options accepted by query and streaming methods. */
export interface QuackQueryOptions extends QuackRequestOptions {
    /** Positional or named SQL parameters formatted as client-side literals. */
    params?: SqlParameters;
}
/** Options accepted by low-level append calls. */
export interface AppendOptions extends QuackRequestOptions {
    /** Optional schema name for the target table. */
    schema?: string;
}
/** Options accepted by row-oriented append calls. */
export interface AppendRowsOptions<T extends Record<string, unknown>> extends AppendOptions {
    /** Column definitions used to encode row values as a DuckDB DataChunk. */
    columns?: ColumnSchema<T>;
    /** Number of input rows encoded into each append chunk. Defaults to all rows. */
    batchSize?: number;
}
/** Schema-qualified table reference used by append helpers. */
export interface TableReference {
    /** Table name without schema qualification. */
    table: string;
    /** Optional schema name. */
    schema?: string;
}
/** Parsed connection string with the HTTP base URL used for transport. */
export interface ParsedQuackUri {
    /** HTTP or HTTPS base URL without the `/quack` endpoint suffix. */
    baseUrl: string;
    /** Host parsed from the connection string. */
    host: string;
    /** Port parsed from the connection string, defaulting to 9494. */
    port: number;
    /** Whether the transport uses HTTPS. */
    ssl: boolean;
}
/** Server metadata returned by the Quack connection response. */
export interface QuackConnectionInfo {
    /** DuckDB version reported by the server. */
    serverDuckdbVersion?: string;
    /** Platform string reported by the server. */
    serverPlatform?: string;
    /** Quack protocol version reported by the server. */
    quackVersion?: bigint;
}
/** Result of a collected Quack query. */
export interface QuackQueryResult<T extends QuackRow = QuackRow> {
    /** Result column names in DuckDB result order. */
    names: string[];
    /** Decoded DuckDB logical types for each result column. */
    types: LogicalType[];
    /** Decoded DuckDB DataChunks returned by prepare/fetch. */
    chunks: QuackDataChunk[];
    /** Materialize the decoded chunks as row objects keyed by column name. */
    rows(): T[];
    /** Materialize rows and convert Quack-specific values to JSON-safe values. */
    jsonRows(options?: QuackJsonOptions): QuackJsonRow[];
}
/** Options accepted by Arrow query and streaming methods. */
export interface QuackArrowQueryOptions extends QuackQueryOptions, QuackArrowTableOptions {
}
/** Options accepted by Arrow IPC query methods. */
export interface QuackArrowQueryIPCOptions extends QuackQueryOptions, QuackArrowIPCOptions {
}
/** Options accepted by Arrow append methods. */
export interface AppendArrowOptions extends AppendOptions, QuackArrowAppendOptions {
}
/** Client for DuckDB's Quack HTTP protocol. */
export declare class QuackClient {
    /** HTTP or HTTPS base URL used for Quack requests. */
    readonly baseUrl: string;
    /** Fetch implementation used by this client. */
    readonly fetchImpl: typeof fetch;
    /** Server metadata populated after a successful connection. */
    info: QuackConnectionInfo | undefined;
    private readonly headers;
    private connectionId;
    private closed;
    private nextQueryId;
    private constructor();
    /**
     * Open a Quack connection.
     *
     * Accepts bare host strings such as `localhost:9494`, DuckDB-style
     * `quack:` URIs, and direct HTTP(S) URLs.
     */
    static connect(uri: string, options?: QuackClientOptions): Promise<QuackClient>;
    /**
     * Open a connection, run a callback, and always disconnect afterwards.
     */
    static withConnection<T>(uri: string, fn: (client: QuackClient) => Promise<T> | T): Promise<T>;
    static withConnection<T>(uri: string, options: QuackClientOptions, fn: (client: QuackClient) => Promise<T> | T): Promise<T>;
    /** Whether this client currently has an open Quack connection. */
    get isConnected(): boolean;
    /**
     * Run SQL and collect all result chunks.
     *
     * Use the generic parameter to type the materialized rows returned by
     * {@link QuackQueryResult.rows}.
     */
    query<T extends QuackRow = QuackRow>(sql: string, options?: QuackQueryOptions): Promise<QuackQueryResult<T>>;
    query<T extends QuackRow = QuackRow>(sql: string, params: SqlParameters, options?: QuackRequestOptions): Promise<QuackQueryResult<T>>;
    /** Run SQL and collect the result as a Flechette Arrow Table. */
    queryArrow(sql: string, options?: QuackArrowQueryOptions): Promise<ArrowTable>;
    queryArrow(sql: string, params: SqlParameters, options?: QuackArrowQueryOptions): Promise<ArrowTable>;
    /** Run SQL and collect the result as Arrow IPC bytes. */
    queryArrowIPC(sql: string, options?: QuackArrowQueryIPCOptions): Promise<Uint8Array>;
    queryArrowIPC(sql: string, params: SqlParameters, options?: QuackArrowQueryIPCOptions): Promise<Uint8Array>;
    /** Run SQL and return the first row, or `null` when the result is empty. */
    first<T extends QuackRow = QuackRow>(sql: string, options?: QuackQueryOptions): Promise<T | null>;
    first<T extends QuackRow = QuackRow>(sql: string, params: SqlParameters, options?: QuackRequestOptions): Promise<T | null>;
    /** Run SQL and return exactly one row, throwing when the row count is not one. */
    one<T extends QuackRow = QuackRow>(sql: string, options?: QuackQueryOptions): Promise<T>;
    one<T extends QuackRow = QuackRow>(sql: string, params: SqlParameters, options?: QuackRequestOptions): Promise<T>;
    /** Run SQL and return the first column from every materialized row. */
    values<T extends QuackValue = QuackValue>(sql: string, options?: QuackQueryOptions): Promise<T[]>;
    values<T extends QuackValue = QuackValue>(sql: string, params: SqlParameters, options?: QuackRequestOptions): Promise<T[]>;
    /** Run SQL and stream decoded DuckDB DataChunks without materializing all rows. */
    stream(sql: string, options?: QuackQueryOptions): AsyncGenerator<QuackDataChunk, void, void>;
    stream(sql: string, params: SqlParameters, options?: QuackRequestOptions): AsyncGenerator<QuackDataChunk, void, void>;
    /** Run SQL and stream materialized rows. */
    streamRows<T extends QuackRow = QuackRow>(sql: string, options?: QuackQueryOptions): AsyncGenerator<T, void, void>;
    streamRows<T extends QuackRow = QuackRow>(sql: string, params: SqlParameters, options?: QuackRequestOptions): AsyncGenerator<T, void, void>;
    /** Run SQL and stream result chunks as Flechette Arrow Tables. */
    streamArrow(sql: string, options?: QuackArrowQueryOptions): AsyncGenerator<ArrowTable, void, void>;
    streamArrow(sql: string, params: SqlParameters, options?: QuackArrowQueryOptions): AsyncGenerator<ArrowTable, void, void>;
    /** Append an already encoded DuckDB DataChunk to a table. */
    append(table: string, chunk: QuackDataChunk, schemaName?: string): Promise<void>;
    append(table: string, chunk: QuackDataChunk, options?: AppendOptions): Promise<void>;
    append(table: TableReference, chunk: QuackDataChunk, options?: QuackRequestOptions): Promise<void>;
    append(table: string | TableReference, chunk: QuackDataChunk, schemaOrOptions?: string | AppendOptions | QuackRequestOptions): Promise<void>;
    /**
     * Encode row objects as one or more flat DataChunks and append them to a table.
     *
     * Provide explicit column types for stable production use, especially for
     * empty row sets or columns containing only `null`.
     */
    appendRows<T extends Record<string, unknown>>(table: string | TableReference, rows: readonly T[], options?: AppendRowsOptions<T>): Promise<void>;
    /** Append data from a Flechette Arrow Table or Arrow IPC bytes. */
    appendArrow(table: string | TableReference, input: QuackArrowInput, options?: AppendArrowOptions): Promise<void>;
    /**
     * Run a callback inside a DuckDB transaction.
     *
     * Commits when the callback succeeds and attempts rollback when it throws.
     */
    transaction<T>(fn: (client: this) => Promise<T> | T, options?: QuackRequestOptions): Promise<T>;
    /** Disconnect from the Quack server. Safe to call more than once. */
    disconnect(options?: QuackRequestOptions): Promise<void>;
    /** Alias for {@link disconnect}. */
    close(options?: QuackRequestOptions): Promise<void>;
    /**
     * Send a raw Quack protocol message.
     *
     * This is an escape hatch for protocol tests and advanced clients; most
     * application code should use higher-level methods.
     */
    send(message: QuackMessage, options?: QuackRequestOptions): Promise<QuackMessage>;
    private prepare;
    private fetchResult;
    private ensureOpen;
    private getConnectionId;
    private allocateQueryId;
}
/**
 * Parse a Quack connection string into the HTTP base URL used by the client.
 *
 * Bare hosts default to port 9494, and `quack:` URIs are normalized to HTTP(S).
 */
export declare function parseQuackUri(input: string, sslOverride?: boolean): ParsedQuackUri;