/**
 * =====================================================================
 *  HEGA GmbH - Portal-API - TypeScript-Typen zum Node.js-Referenzclient
 * =====================================================================
 *
 *  Diese Datei einfach NEBEN `hega-api-client.cjs` legen - TypeScript
 *  findet sie automatisch, es ist keine Konfiguration noetig:
 *
 *      import { HegaApiClient, HegaApiError } from './hega-api-client.cjs';
 *
 *  Reine JavaScript-Projekte brauchen diese Datei nicht; sie aendert am
 *  Laufzeitverhalten nichts.
 *
 *  Hinweis: Die Endung `.d.cts` gehoert zur Endung `.cjs` des Clients.
 *  Geprueft mit TypeScript 5.9 unter allen gaengigen Aufloesungen
 *  (`node16`, `nodenext`, `bundler` und dem alten `node10`) - eine
 *  Umbenennung ist in keinem dieser Faelle noetig.
 *
 *  Stand: August 2026
 */

/** Eine Position der Dropshipping-Bestellung. */
export interface DsOrderZeile {
  /** Artikelnummer bei HEGA. */
  artnr: string;
  /** Menge - ohne `mengeneinheit` in Verkaufseinheiten (VE). */
  menge: number;
  /** `"Stueck"`, wenn `menge` in Stueck angegeben ist; HEGA rechnet auf VE um. */
  mengeneinheit?: string;
  [feld: string]: unknown;
}

/**
 * Dropshipping-Bestellung.
 *
 * Achtung: Das Strassenfeld heisst in der API tatsaechlich `straße`
 * (mit Eszett) - der Feldname ist nicht frei waehlbar.
 */
export interface DsOrder {
  /** Ihre eigene Referenz, max. 20 Zeichen - dient auch der Doublettenpruefung. */
  bestellnummer: string;
  vorname: string;
  nachname: string;
  /** Strasse des Endkunden - Feldname mit Eszett, siehe oben. */
  'straße': string;
  hausnummer: string;
  postleitzahl: string;
  ort: string;
  /** Laenderkennzeichen in Grossbuchstaben, z. B. `"DE"` (case-sensitive). */
  laenderkennzeichen: string;
  /** `"DHL"` oder `"DPD"` (case-sensitive). */
  versender: string;
  /** Bei DPD Pflicht - alternativ `mobilnummer`. */
  emailadresse?: string;
  /** Bei DPD Pflicht - alternativ `emailadresse`. */
  mobilnummer?: string;
  dsorderzeiledto: DsOrderZeile[];
  [feld: string]: unknown;
}

/** Einzelfehler aus dem Dry-Run bzw. aus `HegaApiError.errors`. */
export interface DsOrderFehler {
  errorCode?: string;
  message?: string;
  /** Enthaelt u. a. `Position` (1-basierte Bestellposition). */
  details?: Record<string, string>;
  [feld: string]: unknown;
}

/** Ergebnis des Dry-Runs `orderValidate`. */
export interface OrderValidateErgebnis {
  valid: boolean;
  errorCount: number;
  errors: DsOrderFehler[];
  [feld: string]: unknown;
}

/**
 * Eine Statuszeile zu einer Bestellung. Bei Teillieferungen kommen
 * mehrere Zeilen zurueck.
 */
export interface OrderStatusZeile {
  /** z. B. `Open`, `Dispatched`, `Invoiced`. */
  status?: string;
  /** Lieferscheinnummer. */
  lsnr?: string;
  /** Sendungsverfolgungsnummer des Versenders. */
  trackingid?: string | null;
  [feld: string]: unknown;
}

/** Rohantwort eines Aufrufs ueber `request`. */
export interface ApiAntwort {
  status: number;
  rumpf: unknown;
  /** Header-Namen ausschliesslich in Kleinbuchstaben. */
  header: Record<string, string>;
}

export interface HegaApiClientOptionen {
  /** Zeitueberschreitung in SEKUNDEN (nicht Millisekunden). Vorgabe 60. */
  timeout?: number;
  /** Wird fuer Diagnosemeldungen aufgerufen; ohne Angabe wird nichts protokolliert. */
  logger?: (zeile: string) => void;
}

export interface RequestOptionen {
  /** Wird als JSON gesendet. */
  body?: unknown;
  /** Zusaetzliche Query-Parameter; `api-version` setzt der Client selbst. */
  query?: Record<string, string | number | boolean>;
  /** Nur bei `true` wird nach Timeout/5xx wiederholt. Beim Anlegen von Bestellungen IMMER `false`. */
  idempotent?: boolean;
  /** `true` = Antwort nicht als JSON auswerten (PDF/CSV) - `rumpf` ist dann ein `Buffer`. */
  binaer?: boolean;
}

/**
 * Fehler der HEGA-API - vereinheitlicht BEIDE Fehlerschemas.
 *
 * Wer nur `errorCode` auswertet, uebersieht die formale Feldpruefung
 * vollstaendig; deren Meldungen stehen in `fieldErrors`.
 */
export declare class HegaApiError extends Error {
  constructor(
    meldung: string,
    status: number,
    zusatz?: {
      errorCode?: string | null;
      errors?: DsOrderFehler[];
      fieldErrors?: Record<string, unknown>;
      raw?: unknown;
    },
  );

  name: 'HegaApiError';
  /** HTTP-Statuscode; `0` = keine Verbindung zustande gekommen. */
  status: number;
  /** Maschinenlesbarer Fehlercode (Schema a), sonst `null`. */
  errorCode: string | null;
  /** Fehlerhafte Bestellpositionen (Schema a). */
  errors: DsOrderFehler[];
  /** Feldfehler der formalen Pruefung (Schema b). */
  fieldErrors: Record<string, unknown>;
  /** Unveraenderte Antwort - fuer die eigene Protokollierung. */
  raw: unknown;

  /** HTTP 403 heisst hier meist "Funktion fuer Ihr Konto nicht freigeschaltet". */
  readonly istNichtFreigeschaltet: boolean;
  /** Dieselbe Bestellnummer ging innerhalb von 24 Stunden schon ein. */
  readonly istDoublette: boolean;
}

/** Client fuer die HEGA Portal-API (Dropshipping & B2B). */
export declare class HegaApiClient {
  constructor(
    baseUrl: string,
    apiMail: string,
    password: string,
    kundennummer: string | number,
    optionen?: HegaApiClientOptionen,
  );

  static readonly TOKEN_PUFFER_SEK: number;
  static readonly MAX_VERSUCHE: number;
  static readonly BASIS_TEST: string;
  static readonly BASIS_LIVE: string;

  readonly baseUrl: string;

  /** Dry-Run: prueft Adresse, Artikel und Mengen, legt aber NICHTS an. */
  orderValidate(bestellung: DsOrder): Promise<OrderValidateErgebnis>;

  /** Legt eine Dropshipping-Bestellung an. */
  orderAdd(bestellung: DsOrder): Promise<string>;

  /**
   * Wie `orderAdd`, behandelt aber Timeouts sicher: nach einem
   * Verbindungsabbruch wird erst der Status geprueft, statt blind zu
   * wiederholen - so entstehen keine Doubletten.
   */
  orderAddSafe(bestellung: DsOrder): Promise<string>;

  /** Status ueber Ihre eigene Bestellnummer; leeres Array = nicht gefunden. */
  orderStatus(bestellnummer: string): Promise<OrderStatusZeile[]>;

  /** Einzelner Artikel; `null`, wenn er fuer Ihr Konto nicht bestellbar ist. */
  artikel(artikelnummer: string, kompakt?: boolean): Promise<Record<string, unknown> | null>;

  /** Warenbestand eines Artikels; `null` bei HTTP 404. */
  bestand(artikelnummer: string): Promise<Record<string, unknown> | null>;

  /** Sortiment seitenweise abrufen - laeuft bis `X-Total-Count` erreicht ist. */
  artikelDatenKompaktAlle(pageSize?: number): Promise<Array<Record<string, unknown>>>;

  /** Beleg-PDF; nur diese Endpunkte laufen MIT `/api/v1/` im Pfad. */
  belegPdf(art: 'DeliveryNote' | 'Invoice', nummer: string): Promise<Buffer>;

  /** Meldet an und legt Access- und Refresh-Token ab. */
  login(): Promise<void>;

  /** Meldet ab und gibt das Refresh-Token zurueck. */
  logout(): Promise<void>;

  /** Beliebiger Aufruf inkl. Token-Verwaltung, Wiederholungen und Fehlerauswertung. */
  request(methode: string, pfad: string, optionen?: RequestOptionen): Promise<ApiAntwort>;
}

export declare const BASIS_TEST: string;
export declare const BASIS_LIVE: string;