import { SuggestOptions } from '@searchstack/public-api';

/**
 * A suggestion record returned by the API. The public API returns suggestions
 * as opaque records of the List's suggest fields; these are the well-known
 * fields the plugin uses when present.
 */
type Data = {
    id?: string;
    name?: string;
    list_name?: string;
    version?: number;
    [key: string]: unknown;
};

declare class Options {
    delay?: number;
    minimum_characters?: number;
    suggestion_options?: SuggestOptions;
    headless: boolean;
    template: (data: Data) => string;
    footer_template?: (elements: HTMLElement[]) => string;
    history_template?: (data: Data) => string;
    list_style?: string;
    list_item_style?: string;
    history_item_style?: string;
    /** Label shown in a header row above history results so the user can see the
     *  suggestions are from their recent selections. Set to an empty string to
     *  hide the header. Defaults to "Recent". */
    history_header?: string;
    enable_history: boolean;
    selected?: (data: Data) => void;
    suggested?: (dataArray: Data[]) => void;
    search?: (query: string) => void;
    selected_failed?: (id: string, status: number, message: string) => void;
    suggested_failed?: (query: string, status: number, message: string) => void;
    allow_multiple: boolean;
    /** API key sent as the X-API-Key header. Supply this or access_token. */
    api_key?: string | undefined;
    /** JWT access token sent as Authorization: Bearer. Supply this or api_key. */
    access_token?: string | undefined;
    base_url?: string | undefined;
    constructor(options?: Partial<Options>);
}

/**
 * Escapes a value for safe interpolation into an HTML template string.
 *
 * Item templates (`template`, `history_template`, `footer_template`) assign
 * their returned string via `innerHTML`, so any field that may contain
 * user-generated content must be passed through this helper to avoid injecting
 * markup or scripts into the host page.
 */
declare function escapeHtml(value: unknown): string;

declare class DesktopOptions extends Options {
    enable_repositioning: boolean;
    full_length: boolean;
    constructor(options?: Partial<DesktopOptions>);
}

declare class AutocompleteOptions extends DesktopOptions {
    full_screen_on_mobile: boolean;
    mobile_max_screen_width: number;
    constructor(options?: Partial<AutocompleteOptions>);
}

/**
 * Options for the Ask overlay.
 *
 * Everything a deployment needs to differ on is here rather than baked into the
 * component, because this widget ships twice: once on searchstack.dev's own
 * documentation, and once as the embeddable "Ask this Site" widget. Nothing in
 * `src/ask` may hard-code a hostname, our product name, or an assumption about
 * the surrounding page.
 */
declare class AskOptions {
    /**
     * Endpoint that answers a question. Receives `{ question }` and replies with
     * server-sent events: `sources`, then `delta`…, then `done` (or `error`).
     *
     * The answer goes through a backend rather than direct to the search API
     * because generation needs a model key, which must never reach the page.
     * Typeahead stays a direct browser call — that split is the whole topology.
     */
    ask_endpoint: string;
    /** Label on the row pinned beneath the suggestions. */
    ask_row_label: string;
    /** Heading above the answer while it streams. */
    ask_thinking_label: string;
    /** Heading above the deduplicated list of cited sources. */
    ask_sources_label: string;
    /** Heading above the full retrieved set. */
    ask_results_label: string;
    /** Placeholder in the overlay's own question box. */
    ask_placeholder: string;
    /** Shown when the endpoint is unreachable or errors. */
    ask_error_label: string;
    /** Open the overlay on Cmd-K / Ctrl-K anywhere on the page. */
    ask_hotkey: boolean;
    /**
     * Treat a trailing question mark as "I am asking", in two places:
     *   - in the search box, it pre-selects the Ask row so Enter answers rather
     *     than jumping to the top match;
     *   - in the overlay, it starts the answer on its own, no Enter needed.
     *
     * Deliberately keyed on the question mark alone rather than on question
     * words. Typing "?" is an explicit act — the reader has said they are asking
     * rather than looking — whereas "how to add a reranker" is just as likely to
     * be keywords, and silently redefining Enter for it would break the muscle
     * memory of people already using the box. Arrowing into the suggestions
     * always overrides it.
     */
    ask_on_question_mark: boolean;
    /**
     * How long to wait after the last keystroke before an auto-started answer
     * fires, in milliseconds.
     *
     * This exists because every answer is a paid model call. Without the pause,
     * "why?" typed mid-sentence would fire before the reader had finished the
     * thought, and each further character would fire again — burning money and
     * tripping the rate limiter on a single sentence. Long enough to mean
     * "stopped typing", short enough to still feel automatic.
     */
    ask_auto_delay: number;
    /** Ask the reader whether the answer helped. */
    ask_feedback: boolean;
    /**
     * Rewrites a citation/source link before navigation. The docs site uses this
     * to stay on the host being browsed, since records store absolute crawled
     * URLs and dev/staging are different origins.
     */
    ask_link?: (url: string) => string;
    /** Fired when the reader rates an answer. Wire it to your own telemetry. */
    ask_rated?: (rating: 'up' | 'down', question: string) => void;
    constructor(options?: Partial<AskOptions>);
}

/**
 * Attaches the autocomplete to the textbox with the given id, suggesting over a
 * single List. Waits for the element to appear in the DOM if necessary, and
 * uses the full-screen mobile experience on small touch screens and the
 * anchored desktop list elsewhere.
 *
 * @param apiKey - The Search Stack API key used to authenticate requests. Sent
 * as the `X-API-Key` header. Required.
 * @param version - The List version to suggest against.
 */
declare const attachList: (textboxId: string, apiKey: string, accountName: string, listName: string, version: number, options?: Partial<AutocompleteOptions>) => Promise<HTMLElement>;
/**
 * Attaches the autocomplete to the textbox with the given id, suggesting across
 * every List in a Group. Otherwise identical to {@link attachList}.
 *
 * @param apiKey - The Search Stack API key used to authenticate requests. Sent
 * as the `X-API-Key` header. Required.
 * @param version - The Group's membership version to suggest against. Pass
 * `"latest"` to always track the Group's current version, or a concrete integer
 * to pin a frozen version.
 */
declare const attachGroup: (textboxId: string, apiKey: string, accountName: string, groupName: string, version: number | "latest", options?: Partial<AutocompleteOptions>) => Promise<HTMLElement>;
/**
 * Attaches typeahead AND a grounded, cited answer panel to the same input.
 *
 * Identical to {@link attachList} in every respect — same suggestions, same
 * direct search call, same Enter behaviour — plus an "Ask this" row pinned under
 * the suggestions and a Cmd-K shortcut, either of which opens an overlay that
 * streams an answer with a link back to every section it used.
 *
 * The typeahead call goes browser → search API on the key you pass here. The
 * answer goes through `ask_endpoint` on your own backend instead, because
 * generation needs a model key and a model key must never ship in a page.
 *
 * @param apiKey - Search Stack API key for the typeahead half. Use a read-only,
 * list-scoped key: it ships in your page.
 */
declare const attachAsk: (textboxId: string, apiKey: string, accountName: string, listName: string, version: number, options?: Partial<AutocompleteOptions & AskOptions>) => Promise<HTMLElement>;
/**
 * Wires an element — a button, or a bar styled to look like one — to open the Ask
 * overlay. For pages with no search box of their own: a home page, a footer, a
 * help menu.
 *
 * Unlike {@link attachAsk} this fetches no suggestions and needs no search key,
 * because there is nothing to suggest into. All it needs is `ask_endpoint`.
 */
declare const attachAskLauncher: (elementId: string, options?: Partial<AskOptions>) => Promise<HTMLElement>;
/** Destroys every attached desktop list, mobile modal and ask overlay. */
declare const destroy: () => void;
/** Forgets attached instances without touching the DOM. */
declare const reset: () => void;
/** Clears the stored suggestion history. */
declare const clearHistory: () => void;
/** Removes a single entry from the stored suggestion history by its id. */
declare const removeHistory: (key: string) => void;

export { AskOptions, AutocompleteOptions, DesktopOptions, Options, attachAsk, attachAskLauncher, attachGroup, attachList, clearHistory, destroy, escapeHtml, removeHistory, reset };
export type { Data };