// wowdb.d.ts : types du client officiel wowdb.mjs (API de WoWDB des Défias v1), version 1.0.0.
// Release 58 du site (01/10/2026). Licence : MIT. Types complets de chaque champ : /api/v1/openapi.json (openapi-typescript).

export declare const VERSION: string;
export declare const BASE_URL: string;

/** Version du jeu : Vanilla (1.12.1), The Burning Crusade (2.4.3), Wrath of the Lich King (3.3.5a). */
export type GameVersion = "classic" | "tbc" | "wotlk";
export type Quality = "poor" | "common" | "uncommon" | "rare" | "epic" | "legendary" | "artifact" | "heirloom";
export type Params = Record<string, string | number | boolean | Array<string | number> | null | undefined>;

/** Référence courte vers une autre fiche. */
export interface Ref {
  object: string;
  id: number;
  version: GameVersion;
  name: string | null;
  url: string;
  api_url: string;
  [champ: string]: unknown;
}

/** Objet de l'API : champ object, id, version, name, url, api_url, plus les champs de sa ressource. */
export interface ApiObject {
  object: string;
  id?: number | string;
  name?: string;
  url?: string;
  api_url?: string;
  [champ: string]: unknown;
}

export interface Item extends ApiObject {
  object: "item";
  id: number;
  key: string;
  version: GameVersion;
  name: string;
  quality: Quality | null;
  quality_name: string | null;
  icon: string | null;
  item_level: number | null;
  required_level: number | null;
  slot: string | null;
  slot_name: string | null;
  type: string | null;
  type_name: string | null;
  weapon: { damage_min: number; damage_max: number; speed: number; dps: number } | null;
  sell_price: number | null;
  rogue: boolean;
  internal: boolean;
  tooltip: string[];
  url: string;
  api_url: string;
}

/** Enveloppe de toutes les listes, paginées par curseur. */
export interface List<T = ApiObject> {
  object: "list";
  data: T[];
  has_more: boolean;
  next_cursor: string | null;
  url: string;
  total_count?: number;
}

export declare class WowDbError extends Error {
  /** Statut HTTP (0 : erreur réseau). */
  status: number;
  /** invalid_request_error, rate_limit_error, api_error. */
  type: string;
  /** Code stable : parameter_invalid, resource_missing, rate_limited… */
  code: string;
  param: string | null;
  docUrl: string | null;
  requestId: string | null;
}

export interface WowDbOptions {
  /** Nom de votre application et moyen de vous joindre (ignoré par les navigateurs). */
  userAgent?: string;
  baseUrl?: string;
  fetch?: typeof fetch;
  /** Nouvelles tentatives après un 429 (Retry-After) ; 2 par défaut. */
  maxRetries?: number;
  /** Délai maximum d'une requête en millisecondes ; 30 000 par défaut. */
  timeout?: number;
}

export interface Resource<T = ApiObject> {
  list(version: GameVersion, params?: Params): Promise<List<T>>;
  retrieve(version: GameVersion, id: number): Promise<T>;
  iterate(version: GameVersion, params?: Params): AsyncGenerator<T, void, unknown>;
}

export declare class WowDb {
  constructor(options?: WowDbOptions);
  baseUrl: string;
  userAgent: string;
  maxRetries: number;
  timeout: number;
  items: Resource<Item>;
  spells: Resource;
  quests: Resource;
  npcs: Resource & {
    loot(version: GameVersion, id: number, params?: Params): Promise<List>;
    sells(version: GameVersion, id: number, params?: Params): Promise<List>;
    quests(version: GameVersion, id: number, params?: Params): Promise<List>;
    locations(version: GameVersion, id: number, params?: Params): Promise<List>;
  };
  gameObjects: Resource & {
    loot(version: GameVersion, id: number, params?: Params): Promise<List>;
    locations(version: GameVersion, id: number, params?: Params): Promise<List>;
  };
  itemSets: Resource;
  factions: Resource;
  instances: Resource & {
    loot(version: GameVersion, id: number, params?: Params): Promise<List>;
  };
  /** Requête GET brute : chemin relatif à /v1. */
  request<T = ApiObject>(path: string, params?: Params): Promise<T>;
  list<T = ApiObject>(path: string, params?: Params): Promise<List<T>>;
  iterate<T = ApiObject>(path: string, params?: Params): AsyncGenerator<T, void, unknown>;
  retrieve<T = ApiObject>(version: GameVersion, resource: string, id: number): Promise<T>;
  search(q: string, params?: Params): Promise<List>;
  stats(): Promise<ApiObject>;
  versions(): Promise<List>;
}

export default WowDb;