// querrio SDK & API v1 — TypeScript Definitions
// Quelle: https://<deine-domain>/sdk.d.ts
// Nutzung (ohne Bundler):
//   /// <reference path="./asky.d.ts" />
//   const client = window.Querrio.createClient({ key: "pk_..." });

declare namespace Querrio {
  /** Standard-Kategorien. Eigene Kategorien sind per Regel im Backend möglich. */
  type KnownCategory =
    | "event"
    | "article"
    | "product"
    | "page"
    | "person"
    | "location"
    | "faq"
    | "download";

  /** Kategorie eines Treffers: bekannte Kategorie oder projektspezifischer String. */
  type Category = KnownCategory | (string & {});

  /** Gewichtung im Ergebnis: "top" = Teaser-Darstellung, "list" = Listeneintrag. */
  type Tier = "top" | "list";

  interface SearchHit {
    id: string;
    url: string;
    title: string | null;
    description: string | null;
    image_url: string | null;
    /** Relevanz-Score (höher = relevanter), Skala projektspezifisch. */
    score: number;
    category?: Category | null;
    tags?: string[];
    snippet?: string | null;
    tier?: Tier;
    is_event?: boolean;
    /** ISO-8601 Zeitstempel. */
    event_start?: string | null;
    event_end?: string | null;
    event_location?: string | null;
    /**
     * Zeitbezug des Treffers — gesetzt bei Veranstaltungen, Öffnungszeiten,
     * Angeboten, Saisonzeiträumen und Fristen. \`label\` ist direkt anzeigbar.
     */
    time_context?: {
      kind: 'event' | 'opening_hours' | 'offer' | 'season' | 'deadline';
      label: string;
      /** true, wenn der Inhalt den in der Suchanfrage gemeinten Tag trifft. */
      matches_query_date: boolean;
      expired: boolean;
      valid_from?: string | null;
      valid_until?: string | null;
    } | null;
  }


  interface SearchGroup {
    category: Category;
    label: string;
    count: number;
    hit_ids: string[];
  }

  interface ParsedIntent {
    normalized: string;
    language?: string;
    entities: Record<string, unknown>;
    /** YYYY-MM-DD */
    date_from?: string;
    date_to?: string;
    audience?: string;
  }

  /** Nur vorhanden, wenn Debug-Mode angefordert und für den Key erlaubt ist. */
  interface SearchDebug {
    version: 1;
    query: { raw: string; normalized: string; language: string | null; limit: number; candidate_limit: number };
    intent: ParsedIntent & { prompt_override: boolean };
    resolved: {
      date_from: string | null;
      date_to: string | null;
      date_label: string | null;
      date_source: "deterministic" | "llm" | "none";
      audience: string | null;
      audience_source: "query" | "llm" | "none";
      now: string;
    };
    filters: {
      date_from: string | null;
      date_to: string | null;
      audience: string | null;
      category: string | null;
      tags: string[];
    };
    weights: Record<string, number | null>;
    candidates: Array<{
      rank: number;
      id: string;
      url: string;
      title: string | null;
      score: number;
      is_event: boolean;
      event_start: string | null;
    }>;
    rerank: { applied: boolean; model_used: boolean; before: string[]; after: string[] };
    rescue: { attempted: boolean; from_cache: boolean; candidates: string[]; used: string | null };
    tiering: { top_score: number; max_top_hits: number; tier_threshold: number; top_hit_ids: string[] };
    scores: Array<{
      id: string;
      position: number;
      final_score: number;
      relative_to_top: number;
      tier: Tier;
      category: Category | null;
    }>;
    timings: Record<string, number>;
    notes: string[];
  }

  interface SearchResponse {
    query: string;
    intent: ParsedIntent;
    /** Alle Treffer in Rangfolge (top_hits + results). */
    hits: SearchHit[];
    /** Beste Treffer für Teaser-Darstellung. */
    top_hits: SearchHit[];
    /** Restliche Treffer als Liste. */
    results: SearchHit[];
    /** Gruppierung nach Kategorie. */
    groups: SearchGroup[];
    /** "Häufig gesucht" — klickbare Suchvorschläge. */
    suggestions: string[];
    did_you_mean?: string | null;
    total: number;
    date_from?: string | null;
    date_to?: string | null;
    date_label?: string | null;
    audience?: string | null;
    took_ms: number;
    reranked?: boolean;
    /** Für Tracking-Events (Klick, Feedback) mitzusenden. */
    query_id?: string;
    rescued_with?: string | null;
    debug?: SearchDebug;
  }

  interface SearchParams {
    limit?: number;
    language?: string;
    filters?: { category?: Category; tags?: string[] };
    /** ID eines im Publisher-Dashboard definierten Suchbereichs (Scope). */
    scope?: string | null;
    /** Nur mit Server-Key oder freigeschaltetem Browser-Key. */
    debug?: boolean;
  }

  interface SuggestItem {
    text: string;
    /** "popular" = häufige frühere Suche, "content" = Titel/Kategorie aus dem Index. */
    type: "popular" | "content";
  }

  interface SuggestResponse {
    query: string;
    /** Auto-Suggest ist pro Projekt aktivierbar. */
    enabled: boolean;
    /** Ab wie vielen Zeichen Vorschläge geliefert werden. */
    min_chars: number;
    /** Vorschläge als reine Textliste (rückwärtskompatibel). */
    suggestions: string[];
    /** Vorschläge inkl. Typ. */
    items: SuggestItem[];
    /** Direkttreffer für das Dropdown. */
    hits: Array<{
      id: string;
      url: string;
      title: string | null;
      category: Category | null;
      image_url: string | null;
    }>;
    /** Erkannter Zeitbezug im Eingabetext, z. B. "morgen". */
    date_label: string | null;
  }

  interface SchemaResponse {
    languages: string[];
    categories: Array<{ id: Category; label: string; count: number }>;
    widget: {
      theme: string | null;
      config: Record<string, unknown>;
      custom_css: string | null;
      max_top_hits: number;
      suggestions_enabled: boolean;
      suggest_min_chars: number;
      suggest_limit: number;
      suggest_show_hits: boolean;
    };
  }

  type TrackKind =
    | "impression"
    | "click"
    | "suggest_click"
    | "dwell"
    | "reformulation"
    | "abandon"
    | "conversion"
    | "helpful"
    | "not_helpful";

  interface ClientOptions {
    /** Browser- oder Server-Key aus dem querrio-Backend. */
    key: string;
    /** API-Basis-URL, Standard: aktuelle Origin. */
    api?: string;
  }

  interface ErrorResponse {
    error: string;
  }

  interface Client {
    search(query: string, params?: SearchParams): Promise<SearchResponse>;
    /** Debounced Variante für Search-as-you-type (Standard 180 ms). */
    searchDebounced(query: string, params?: SearchParams, wait?: number): Promise<SearchResponse>;
    /** Typeahead-Vorschläge; ältere Aufrufe werden automatisch abgebrochen. */
    suggest(query: string): Promise<SuggestResponse>;
    /** Klick auf einen Vorschlag melden (fließt in Analytics und Autopilot). */
    trackSuggestClick(text: string, documentId?: string): Promise<unknown> | void;
    schema(): Promise<SchemaResponse>;
    track(kind: TrackKind, extra?: Record<string, unknown>): Promise<unknown> | void;
    trackClick(hit: Pick<SearchHit, "id">, position?: number): Promise<unknown> | void;
    feedback(helpful: boolean): Promise<unknown> | void;
    /** Query-ID der letzten Suche (für Tracking). */
    readonly queryId: string | null;
  }

  interface SDK {
    createClient(options: ClientOptions): Client;
  }
}

declare global {
  interface Window {
    Querrio: Querrio.SDK;
    Querron: Querrio.SDK;
    /** Alias von window.Querrio. */
    Asky: Querrio.SDK;
  }
}

export = Querrio;
export as namespace Querrio;