@taxora/sdk 1.1.0 → 1.2.0

package/dist/index.js

@@ -60,37 +60,299 @@ var AuthenticationException = class extends TaxoraException {
   }
 };
 
+// src/exceptions/apiErrorMessage.ts
+var MAX_LENGTH = 500;
+var MAX_PLAIN_LENGTH = 200;
+var REASON_PHRASES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  422: "Unprocessable Entity",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function describeApiError(body, statusCode) {
+  return jsonErrorMessage(body) ?? plainErrorMessage(body) ?? statusErrorMessage(statusCode);
+}
+function detailApiError(body, statusCode) {
+  return jsonErrorMessage(body) ?? plainErrorMessage(body) ?? statusPhrase(statusCode);
+}
+function jsonErrorMessage(body) {
+  if (body === null || body === void 0 || body.trim() === "") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const payload = parsed;
+  for (const key of ["message", "error"]) {
+    const value = payload[key];
+    if (typeof value === "string") {
+      const message = sanitize(value);
+      if (message !== null) return message;
+    }
+  }
+  const errors = payload["errors"];
+  if (typeof errors === "object" && errors !== null) {
+    return fromErrorBag(errors);
+  }
+  return null;
+}
+function statusErrorMessage(statusCode) {
+  return `Taxora API request failed (${statusPhrase(statusCode)}).`;
+}
+function statusPhrase(statusCode) {
+  const phrase = REASON_PHRASES[statusCode];
+  return `HTTP ${statusCode}${phrase ? ` ${phrase}` : ""}`;
+}
+function plainErrorMessage(body) {
+  if (body === null || body === void 0) return null;
+  const value = body.replace(/\s+/g, " ").trim();
+  if (value === "" || value.length > MAX_PLAIN_LENGTH) return null;
+  if (value.includes("<") || value.includes("{")) return null;
+  return value;
+}
+function fromErrorBag(errors) {
+  for (const [field, messages] of Object.entries(errors)) {
+    for (const message of Array.isArray(messages) ? messages : [messages]) {
+      if (typeof message !== "string") continue;
+      const sanitized = sanitize(message);
+      if (sanitized === null) continue;
+      return field !== "" ? `${field}: ${sanitized}` : sanitized;
+    }
+  }
+  return null;
+}
+function sanitize(value) {
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  if (collapsed === "") return null;
+  if (/<!doctype\s+html|<html[\s>]/i.test(collapsed)) return null;
+  return collapsed.length > MAX_LENGTH ? `${collapsed.slice(0, MAX_LENGTH - 1)}\u2026` : collapsed;
+}
+
 // src/exceptions/HttpException.ts
-var HttpException = class extends TaxoraException {
+var HttpException = class _HttpException extends TaxoraException {
   statusCode;
   responseBody;
-  constructor(message, statusCode, responseBody, context = {}) {
+  /** Raw `Retry-After` header of the failed response, when it carried one. */
+  retryAfter;
+  constructor(message, statusCode, responseBody, context = {}, retryAfter = null) {
     super(message, context);
     this.name = "HttpException";
     this.statusCode = statusCode;
     this.responseBody = responseBody;
+    this.retryAfter = retryAfter;
     Object.setPrototypeOf(this, new.target.prototype);
   }
+  /**
+   * The final failure after the SDK retried a transient gateway error, e.g.
+   * "Taxora VAT validation failed after 3 attempts (HTTP 504 Gateway Timeout)."
+   */
+  static afterAttempts(operation, attempts, last) {
+    const detail = detailApiError(last.getResponseBody(), last.getStatusCode());
+    return new _HttpException(
+      `Taxora ${operation} failed after ${attempts} attempts (${detail}).`,
+      last.getStatusCode(),
+      last.getResponseBody(),
+      { ...last.context, attempts, cause: last },
+      last.getRetryAfter()
+    );
+  }
   getStatusCode() {
     return this.statusCode;
   }
   getResponseBody() {
     return this.responseBody;
   }
+  getRetryAfter() {
+    return this.retryAfter;
+  }
 };
 
+// src/http/RetryPolicy.ts
+var DEFAULT_RETRYABLE_STATUS_CODES = [502, 503, 504];
+var RETRY_AFTER_ONLY_STATUS_CODES = [429];
+var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ECONNABORTED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+var RetryPolicy = class _RetryPolicy {
+  maxAttempts;
+  initialDelayMs;
+  backoffMultiplier;
+  maxDelayMs;
+  retryableStatusCodes;
+  respectRetryAfter;
+  maxRetryAfterMs;
+  retryOnNetworkErrors;
+  sleeper;
+  constructor(options = {}) {
+    this.maxAttempts = options.maxAttempts ?? 3;
+    this.initialDelayMs = options.initialDelayMs ?? 500;
+    this.backoffMultiplier = options.backoffMultiplier ?? 2;
+    this.maxDelayMs = options.maxDelayMs ?? 5e3;
+    this.retryableStatusCodes = options.retryableStatusCodes ?? DEFAULT_RETRYABLE_STATUS_CODES;
+    this.respectRetryAfter = options.respectRetryAfter ?? true;
+    this.maxRetryAfterMs = options.maxRetryAfterMs ?? 1e4;
+    this.retryOnNetworkErrors = options.retryOnNetworkErrors ?? true;
+    this.sleeper = options.sleeper;
+    if (this.maxAttempts < 1) throw new Error("maxAttempts must be at least 1.");
+    if (this.initialDelayMs < 0 || this.maxDelayMs < 0) throw new Error("Delays must not be negative.");
+    if (this.backoffMultiplier < 1) throw new Error("backoffMultiplier must be at least 1.");
+  }
+  /** No retrying at all — every failure is surfaced on the first attempt. */
+  static disabled() {
+    return new _RetryPolicy({ maxAttempts: 1 });
+  }
+  /** Retry immediately, without waiting (mainly useful in tests). */
+  static withoutDelay(maxAttempts = 3) {
+    return new _RetryPolicy({ maxAttempts, initialDelayMs: 0, maxDelayMs: 0 });
+  }
+  isRetryable(statusCode, retryAfterHeader) {
+    const retryAfterMs = this.retryAfterMs(retryAfterHeader);
+    if (retryAfterMs !== null && retryAfterMs > this.maxRetryAfterMs) return false;
+    if (this.retryableStatusCodes.includes(statusCode)) return true;
+    return retryAfterMs !== null && RETRY_AFTER_ONLY_STATUS_CODES.includes(statusCode);
+  }
+  /** @param attempt Number of attempts made so far (1 = the first one just failed). */
+  shouldRetry(statusCode, attempt, retryAfterHeader) {
+    return attempt < this.maxAttempts && this.isRetryable(statusCode, retryAfterHeader);
+  }
+  /**
+   * A connection-level failure: the request never got an answer, so repeating it
+   * is as safe as repeating a gateway timeout.
+   */
+  isRetryableError(error) {
+    if (!this.retryOnNetworkErrors || !(error instanceof Error)) return false;
+    if (error.name === "AbortError" || error.name === "TimeoutError") return true;
+    const code = error.code ?? error.cause?.code;
+    if (typeof code === "string" && NETWORK_ERROR_CODES.has(code)) return true;
+    return error instanceof TypeError && /fetch failed|network|failed to fetch/i.test(error.message);
+  }
+  shouldRetryError(error, attempt) {
+    return attempt < this.maxAttempts && this.isRetryableError(error);
+  }
+  /**
+   * The wait the API asked for, in milliseconds — seconds or HTTP-date form — or
+   * null when there is none, it cannot be parsed, or the header is ignored.
+   */
+  retryAfterMs(header, now = /* @__PURE__ */ new Date()) {
+    if (!this.respectRetryAfter || header === null || header === void 0) return null;
+    const value = header.trim();
+    if (value === "") return null;
+    if (/^\d+$/.test(value)) return Number(value) * 1e3;
+    const date = Date.parse(value);
+    if (Number.isNaN(date)) return null;
+    return Math.max(0, date - now.getTime());
+  }
+  /** The wait before the next attempt: what the API asked for, else exponential backoff. */
+  delayMsForAttempt(attempt, retryAfterHeader) {
+    const retryAfterMs = this.retryAfterMs(retryAfterHeader);
+    if (retryAfterMs !== null) return Math.min(retryAfterMs, this.maxRetryAfterMs);
+    if (this.initialDelayMs === 0) return 0;
+    const delay = Math.round(this.initialDelayMs * this.backoffMultiplier ** Math.max(0, attempt - 1));
+    return Math.max(0, Math.min(delay, this.maxDelayMs));
+  }
+  async sleepBeforeRetry(attempt, retryAfterHeader) {
+    const delayMs = this.delayMsForAttempt(attempt, retryAfterHeader);
+    if (delayMs <= 0) return;
+    if (this.sleeper) {
+      await this.sleeper(delayMs);
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+};
+
+// src/http/withRetries.ts
+async function withRetries(policy, operation, request) {
+  let attempt = 1;
+  for (; ; ) {
+    try {
+      return await request();
+    } catch (error) {
+      if (!(error instanceof HttpException)) {
+        if (!policy.shouldRetryError(error, attempt)) throw error;
+        await policy.sleepBeforeRetry(attempt);
+        attempt++;
+        continue;
+      }
+      const retryAfter = error.getRetryAfter();
+      if (!policy.shouldRetry(error.getStatusCode(), attempt, retryAfter)) {
+        throw attempt > 1 && policy.isRetryable(error.getStatusCode(), retryAfter) ? HttpException.afterAttempts(operation, attempt, error) : error;
+      }
+      await policy.sleepBeforeRetry(attempt, retryAfter);
+      attempt++;
+    }
+  }
+}
+async function withResponseRetries(policy, operation, send) {
+  let attempt = 1;
+  for (; ; ) {
+    let response;
+    try {
+      response = await send();
+    } catch (error) {
+      if (!policy.shouldRetryError(error, attempt)) throw error;
+      await policy.sleepBeforeRetry(attempt);
+      attempt++;
+      continue;
+    }
+    const retryAfter = response.headers.get("retry-after");
+    if (!policy.shouldRetry(response.status, attempt, retryAfter)) {
+      if (attempt > 1 && policy.isRetryable(response.status, retryAfter)) {
+        const body = await response.text();
+        const last = new HttpException(
+          describeApiError(body, response.status),
+          response.status,
+          body,
+          {},
+          retryAfter
+        );
+        throw HttpException.afterAttempts(operation, attempt, last);
+      }
+      return response;
+    }
+    await policy.sleepBeforeRetry(attempt, retryAfter);
+    attempt++;
+  }
+}
+
 // src/endpoints/AuthEndpoint.ts
 var AuthEndpoint = class {
-  constructor(baseUrl, apiKey, tokenStorage, httpClient) {
+  constructor(baseUrl, apiKey, tokenStorage, httpClient, retryPolicy = new RetryPolicy()) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.tokenStorage = tokenStorage;
     this.httpClient = httpClient;
+    this.retryPolicy = retryPolicy;
   }
   baseUrl;
   apiKey;
   tokenStorage;
   httpClient;
+  retryPolicy;
   async login(identifier, password, device, loginIdentifier = LoginIdentifier.EMAIL) {
     const deviceName = device ?? hostname();
     const body = {
@@ -103,24 +365,32 @@ var AuthEndpoint = class {
     } else {
       body["email"] = identifier;
     }
-    const response = await this.httpClient.request("POST", `${this.baseUrl}/auth/login`, {
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": this.apiKey
-      },
-      body: JSON.stringify(body)
-    });
-    const responseText = await response.text();
-    if (response.status === 401) {
-      throw new AuthenticationException("Authentication failed: invalid credentials", {
-        status: 401,
-        body: responseText
+    const data = await withRetries(this.retryPolicy, "login", async () => {
+      const response = await this.httpClient.request("POST", `${this.baseUrl}/auth/login`, {
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey
+        },
+        body: JSON.stringify(body)
       });
-    }
-    if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
-    }
-    const data = this.parseResponse(responseText);
+      const responseText = await response.text();
+      if (response.status === 401) {
+        throw new AuthenticationException("Authentication failed: invalid credentials", {
+          status: 401,
+          body: responseText
+        });
+      }
+      if (!response.ok) {
+        throw new HttpException(
+          describeApiError(responseText, response.status),
+          response.status,
+          responseText,
+          {},
+          response.headers.get("retry-after")
+        );
+      }
+      return this.parseResponse(responseText, response.status);
+    });
     const token = Token.fromArray(data);
     this.tokenStorage.set(token);
     return token;
@@ -137,28 +407,36 @@ var AuthEndpoint = class {
     if (storedToken) {
       headers["Authorization"] = `Bearer ${storedToken.accessToken}`;
     }
-    const response = await this.httpClient.request("POST", `${this.baseUrl}/auth/refresh`, { headers });
-    const responseText = await response.text();
-    if (response.status === 401) {
-      throw new AuthenticationException("Token refresh failed: unauthorized", { status: 401, body: responseText });
-    }
-    if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
-    }
-    const data = this.parseResponse(responseText);
+    const data = await withRetries(this.retryPolicy, "token refresh", async () => {
+      const response = await this.httpClient.request("POST", `${this.baseUrl}/auth/refresh`, { headers });
+      const responseText = await response.text();
+      if (response.status === 401) {
+        throw new AuthenticationException("Token refresh failed: unauthorized", { status: 401, body: responseText });
+      }
+      if (!response.ok) {
+        throw new HttpException(
+          describeApiError(responseText, response.status),
+          response.status,
+          responseText,
+          {},
+          response.headers.get("retry-after")
+        );
+      }
+      return this.parseResponse(responseText, response.status);
+    });
     const token = Token.fromArray(data);
     this.tokenStorage.set(token);
     return token;
   }
-  parseResponse(responseText) {
+  parseResponse(responseText, statusCode) {
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
+      throw new HttpException("Invalid JSON response", statusCode, responseText);
     }
     if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
+      throw new HttpException("Unexpected response format", statusCode, responseText);
     }
     const obj = parsed;
     if (obj["data"] !== void 0 && typeof obj["data"] === "object" && obj["data"] !== null) {
@@ -182,16 +460,18 @@ function normalizeCompanyResource(data) {
 
 // src/endpoints/CompanyEndpoint.ts
 var CompanyEndpoint = class {
-  constructor(baseUrl, apiKey, tokenStorage, httpClient) {
+  constructor(baseUrl, apiKey, tokenStorage, httpClient, retryPolicy = new RetryPolicy()) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.tokenStorage = tokenStorage;
     this.httpClient = httpClient;
+    this.retryPolicy = retryPolicy;
   }
   baseUrl;
   apiKey;
   tokenStorage;
   httpClient;
+  retryPolicy;
   async get() {
     const headers = {
       "Content-Type": "application/json",
@@ -201,25 +481,33 @@ var CompanyEndpoint = class {
     if (token) {
       headers["Authorization"] = `Bearer ${token.accessToken}`;
     }
-    const response = await this.httpClient.request("GET", `${this.baseUrl}/company`, { headers });
-    const responseText = await response.text();
-    if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(responseText);
-    } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
-    }
-    if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
-    }
-    const obj = parsed;
-    if (obj["data"] !== void 0 && typeof obj["data"] === "object" && obj["data"] !== null) {
-      return normalizeCompanyResource(obj["data"]);
-    }
-    return normalizeCompanyResource(obj);
+    return withRetries(this.retryPolicy, "company request", async () => {
+      const response = await this.httpClient.request("GET", `${this.baseUrl}/company`, { headers });
+      const responseText = await response.text();
+      if (!response.ok) {
+        throw new HttpException(
+          describeApiError(responseText, response.status),
+          response.status,
+          responseText,
+          {},
+          response.headers.get("retry-after")
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(responseText);
+      } catch {
+        throw new HttpException("Invalid JSON response", response.status, responseText);
+      }
+      if (typeof parsed !== "object" || parsed === null) {
+        throw new HttpException("Unexpected response format", response.status, responseText);
+      }
+      const obj = parsed;
+      if (obj["data"] !== void 0 && typeof obj["data"] === "object" && obj["data"] !== null) {
+        return normalizeCompanyResource(obj["data"]);
+      }
+      return normalizeCompanyResource(obj);
+    });
   }
 };
 
@@ -932,16 +1220,18 @@ var TRANSACTION_TYPES = [
   "crossborder_inbound"
 ];
 var EReportingEndpoint = class {
-  constructor(baseUrl, apiKey, tokenStorage, httpClient) {
+  constructor(baseUrl, apiKey, tokenStorage, httpClient, retryPolicy = new RetryPolicy()) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.tokenStorage = tokenStorage;
     this.httpClient = httpClient;
+    this.retryPolicy = retryPolicy;
   }
   baseUrl;
   apiKey;
   tokenStorage;
   httpClient;
+  retryPolicy;
   // ---------------------------------------------------------------------
   // Enrollments
   // ---------------------------------------------------------------------
@@ -1335,7 +1625,8 @@ var EReportingEndpoint = class {
   async sendRequest(method, url, body) {
     const options = { headers: this.buildHeaders() };
     if (body) options.body = JSON.stringify(body);
-    return this.httpClient.request(method, url, options);
+    const send = () => this.httpClient.request(method, url, options);
+    return method === "GET" ? withResponseRetries(this.retryPolicy, "e-reporting request", send) : send();
   }
   /** Multipart upload: Content-Type is left to fetch so the boundary is set correctly. */
   async sendMultipartRequest(method, url, form) {
@@ -1348,16 +1639,22 @@ var EReportingEndpoint = class {
       throw this.buildValidationException(responseText);
     }
     if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
+      throw new HttpException("Invalid JSON response", response.status, responseText);
     }
     if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
+      throw new HttpException("Unexpected response format", response.status, responseText);
     }
     const obj = parsed;
     if (obj["data"] !== void 0 && typeof obj["data"] === "object" && obj["data"] !== null) {
@@ -1375,7 +1672,13 @@ var EReportingEndpoint = class {
       throw this.buildValidationException(responseText);
     }
     if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
   }
   /**
@@ -1419,6 +1722,29 @@ var EReportingEndpoint = class {
   }
 };
 
+// src/enums/SmartEnrichmentMode.ts
+var SmartEnrichmentMode = {
+  DEFAULT: "default",
+  COMPLEX: "complex"
+};
+var VALUES5 = Object.values(SmartEnrichmentMode);
+function toSmartEnrichmentMode(value) {
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (VALUES5.includes(normalized)) {
+      return normalized;
+    }
+  }
+  return void 0;
+}
+var DESCRIPTIONS5 = {
+  [SmartEnrichmentMode.DEFAULT]: "One provider searches; a second is consulted only if it finds nothing.",
+  [SmartEnrichmentMode.COMPLEX]: "Two providers search independently and are cross-checked against the tax authority. Costs more."
+};
+function describeSmartEnrichmentMode(mode) {
+  return DESCRIPTIONS5[mode];
+}
+
 // src/enums/SmartEnrichmentStatus.ts
 var SmartEnrichmentStatus = {
   FOUND: "found",
@@ -1430,17 +1756,17 @@ var SmartEnrichmentStatus = {
   FAILED: "failed",
   UNKNOWN: "unknown"
 };
-var VALUES5 = Object.values(SmartEnrichmentStatus);
+var VALUES6 = Object.values(SmartEnrichmentStatus);
 function toSmartEnrichmentStatus(value) {
   if (typeof value === "string") {
     const normalized = value.trim().toLowerCase();
-    if (VALUES5.includes(normalized)) {
+    if (VALUES6.includes(normalized)) {
       return normalized;
     }
   }
   return SmartEnrichmentStatus.UNKNOWN;
 }
-var DESCRIPTIONS5 = {
+var DESCRIPTIONS6 = {
   [SmartEnrichmentStatus.FOUND]: "A VAT number was resolved and confirmed.",
   [SmartEnrichmentStatus.NO_VAT_EXISTS]: "The company was identified but has no VAT number.",
   [SmartEnrichmentStatus.NOT_FOUND]: "No sufficiently-confident match could be resolved.",
@@ -1451,12 +1777,12 @@ var DESCRIPTIONS5 = {
   [SmartEnrichmentStatus.UNKNOWN]: "Unknown status."
 };
 function describeSmartEnrichmentStatus(status) {
-  return DESCRIPTIONS5[status];
+  return DESCRIPTIONS6[status];
 }
 
 // src/dto/SmartEnrichmentResource.ts
 var SmartEnrichmentResource = class _SmartEnrichmentResource {
-  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source) {
+  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source, mode = void 0, providerVerdicts = [], addressQuality = void 0) {
     this.status = status;
     this.vatNumber = vatNumber;
     this.vatType = vatType;
@@ -1465,6 +1791,9 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
     this.matchedAddress = matchedAddress;
     this.country = country;
     this.source = source;
+    this.mode = mode;
+    this.providerVerdicts = providerVerdicts;
+    this.addressQuality = addressQuality;
   }
   status;
   vatNumber;
@@ -1474,6 +1803,9 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
   matchedAddress;
   country;
   source;
+  mode;
+  providerVerdicts;
+  addressQuality;
   static fromArray(data) {
     const str = (key) => {
       const v = data[key];
@@ -1483,6 +1815,8 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       const v = data[key];
       return typeof v === "number" ? v : void 0;
     };
+    const verdicts = data["providerVerdicts"];
+    const quality = data["addressQuality"];
     return new _SmartEnrichmentResource(
       toSmartEnrichmentStatus(data["status"]),
       str("vatNumber"),
@@ -1491,7 +1825,10 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       str("matchedCompanyName"),
       str("matchedAddress"),
       str("country"),
-      str("source")
+      str("source"),
+      toSmartEnrichmentMode(data["mode"]),
+      Array.isArray(verdicts) ? verdicts.filter((v) => typeof v === "object" && v !== null) : [],
+      typeof quality === "object" && quality !== null ? quality : void 0
     );
   }
   toArray() {
@@ -1503,7 +1840,10 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       matchedCompanyName: this.matchedCompanyName ?? null,
       matchedAddress: this.matchedAddress ?? null,
       country: this.country ?? null,
-      source: this.source ?? null
+      source: this.source ?? null,
+      mode: this.mode ?? null,
+      providerVerdicts: this.providerVerdicts,
+      addressQuality: this.addressQuality ?? null
     };
   }
 };
@@ -1731,16 +2071,18 @@ var STATISTICS_INTERVALS = ["day", "week", "month"];
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 var DEFAULT_POLL_TIMEOUT_MS = 12e4;
 var SmartEnrichmentEndpoint = class {
-  constructor(baseUrl, apiKey, tokenStorage, httpClient) {
+  constructor(baseUrl, apiKey, tokenStorage, httpClient, retryPolicy = new RetryPolicy()) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.tokenStorage = tokenStorage;
     this.httpClient = httpClient;
+    this.retryPolicy = retryPolicy;
   }
   baseUrl;
   apiKey;
   tokenStorage;
   httpClient;
+  retryPolicy;
   /**
    * Single reverse lookup. Returns a confident result synchronously, or a `processing`
    * job (poll with get(job.jobId) or waitForCompletion(job.jobId)) when deeper resolution
@@ -1755,6 +2097,7 @@ var SmartEnrichmentEndpoint = class {
     if (input.street !== void 0) body["street"] = input.street;
     if (input.postalCode !== void 0) body["postalCode"] = input.postalCode;
     if (input.city !== void 0) body["city"] = input.city;
+    if (input.mode !== void 0) body["mode"] = input.mode;
     const response = await this.sendRequest("POST", `${this.baseUrl}/smart-enrichment`, body);
     const data = await this.parseJsonResponse(response, [200, 202]);
     return SmartEnrichmentJob.fromArray(data);
@@ -1762,13 +2105,18 @@ var SmartEnrichmentEndpoint = class {
   /**
    * Bulk batch — always async. Returns a `processing` job; results arrive via the
    * `enrichment.completed` webhook and are retrievable via get(job.jobId).
+   *
+   * @param mode Search depth for every row in the batch. A row carrying its own `mode` overrides
+   *             it, so a caller can pay for `complex` on just the rows that need it.
    */
-  async bulkLookup(items) {
+  async bulkLookup(items, mode) {
     if (items.length === 0) {
       throw new TaxoraException("bulkLookup requires at least one item.");
     }
     items.forEach((item, index) => this.validateInput(item, `items[${index}]`));
-    const response = await this.sendRequest("POST", `${this.baseUrl}/smart-enrichment/bulk`, { items });
+    const body = { items };
+    if (mode !== void 0) body["mode"] = mode;
+    const response = await this.sendRequest("POST", `${this.baseUrl}/smart-enrichment/bulk`, body);
     const data = await this.parseJsonResponse(response, [200, 202]);
     return SmartEnrichmentJob.fromArray(data);
   }
@@ -1910,24 +2258,31 @@ var SmartEnrichmentEndpoint = class {
   async sendRequest(method, url, body) {
     const options = { headers: this.buildHeaders() };
     if (body) options.body = JSON.stringify(body);
-    return this.httpClient.request(method, url, options);
+    const send = () => this.httpClient.request(method, url, options);
+    return method === "GET" ? withResponseRetries(this.retryPolicy, "Smart Enrichment request", send) : send();
   }
   async parseJsonResponse(response, acceptedStatuses = [200]) {
     const responseText = await response.text();
     if (response.status === 422) {
-      throw new ValidationException("Validation failed", this.parseValidationErrors(responseText));
+      throw new ValidationException(jsonErrorMessage(responseText) ?? "Validation failed", this.parseValidationErrors(responseText));
     }
     if (!response.ok && !acceptedStatuses.includes(response.status)) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
+      throw new HttpException("Invalid JSON response", response.status, responseText);
     }
     if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
+      throw new HttpException("Unexpected response format", response.status, responseText);
     }
     const obj = parsed;
     if (obj["data"] !== void 0 && (typeof obj["data"] === "object" || Array.isArray(obj["data"]))) {
@@ -1943,19 +2298,25 @@ var SmartEnrichmentEndpoint = class {
   async parseRawJson(response) {
     const responseText = await response.text();
     if (response.status === 422) {
-      throw new ValidationException("Validation failed", this.parseValidationErrors(responseText));
+      throw new ValidationException(jsonErrorMessage(responseText) ?? "Validation failed", this.parseValidationErrors(responseText));
     }
     if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
+      throw new HttpException("Invalid JSON response", response.status, responseText);
     }
     if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
+      throw new HttpException("Unexpected response format", response.status, responseText);
     }
     return parsed;
   }
@@ -1966,10 +2327,16 @@ var SmartEnrichmentEndpoint = class {
   async parseCsvResponse(response) {
     const responseText = await response.text();
     if (response.status === 422) {
-      throw new ValidationException("Validation failed", this.parseValidationErrors(responseText));
+      throw new ValidationException(jsonErrorMessage(responseText) ?? "Validation failed", this.parseValidationErrors(responseText));
     }
     if (!response.ok) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     return responseText;
   }
@@ -2006,14 +2373,14 @@ var VatState = {
 function getFailedVatStates() {
   return [VatState.INVALID, VatState.FRAUD];
 }
-var DESCRIPTIONS6 = {
+var DESCRIPTIONS7 = {
   [VatState.VALID]: "The VAT number is valid and active.",
   [VatState.INVALID]: "The VAT number is invalid or not registered.",
   [VatState.FRAUD]: "The VAT number has been flagged as potentially fraudulent.",
   [VatState.UNKNOWN]: "The VAT number state could not be determined."
 };
 function describeVatState(state) {
-  return DESCRIPTIONS6[state];
+  return DESCRIPTIONS7[state];
 }
 
 // src/dto/CompanyAddress.ts
@@ -2478,16 +2845,18 @@ var VatValidationAddressInput = class _VatValidationAddressInput {
 // src/endpoints/VatEndpoint.ts
 var DATE_REGEX2 = /^\d{4}-\d{2}-\d{2}$/;
 var VatEndpoint = class {
-  constructor(baseUrl, apiKey, tokenStorage, httpClient) {
+  constructor(baseUrl, apiKey, tokenStorage, httpClient, retryPolicy = new RetryPolicy()) {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.tokenStorage = tokenStorage;
     this.httpClient = httpClient;
+    this.retryPolicy = retryPolicy;
   }
   baseUrl;
   apiKey;
   tokenStorage;
   httpClient;
+  retryPolicy;
   async validate(vatUid, companyName, provider, addressInput) {
     const body = { vat_uid: vatUid };
     if (companyName) body["company_name"] = companyName;
@@ -2495,44 +2864,44 @@ var VatEndpoint = class {
     if (addressInput) {
       body["address_input"] = addressInput instanceof VatValidationAddressInput ? addressInput.toArray() : addressInput;
     }
-    return this.validateWithGatewayRetry(body, 2);
-  }
-  async validateWithGatewayRetry(body, attemptsLeft) {
-    const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate`, body);
-    if (response.status === 504) {
-      if (attemptsLeft <= 1) {
-        const text = await response.text();
-        throw new HttpException("VAT validation timed out after multiple attempts", 504, text);
-      }
-      return this.validateWithGatewayRetry(body, attemptsLeft - 1);
-    }
-    const data = await this.parseJsonResponse(response);
-    return VatResource.fromArray(data);
+    return withRetries(this.retryPolicy, "VAT validation", async () => {
+      const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate`, body);
+      const data = await this.parseJsonResponse(response);
+      return VatResource.fromArray(data);
+    });
   }
   async validateMultiple(vatUids, companyNames, provider) {
     const body = { vat_uids: vatUids };
     if (companyNames) body["company_names"] = companyNames;
     if (provider) body["source"] = provider;
-    const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate/multiple`, body);
-    const data = await this.parseJsonResponse(response);
-    return VatCollection.fromResponse(data);
+    return withRetries(this.retryPolicy, "VAT validation", async () => {
+      const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate/multiple`, body);
+      const data = await this.parseJsonResponse(response);
+      return VatCollection.fromResponse(data);
+    });
   }
   async validateSchema(vatUid) {
     const body = { vat_uid: vatUid };
-    const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate/schema`, body);
-    return this.parseJsonResponse(response);
+    return withRetries(this.retryPolicy, "VAT schema check", async () => {
+      const response = await this.sendRequest("POST", `${this.baseUrl}/vat/validate/schema`, body);
+      return this.parseJsonResponse(response);
+    });
   }
   async state(vatUid) {
-    const response = await this.sendRequest("GET", `${this.baseUrl}/vat/state/${encodeURIComponent(vatUid)}`);
-    const data = await this.parseJsonResponse(response);
-    return VatResource.fromArray(data);
+    return withRetries(this.retryPolicy, "VAT state lookup", async () => {
+      const response = await this.sendRequest("GET", `${this.baseUrl}/vat/state/${encodeURIComponent(vatUid)}`);
+      const data = await this.parseJsonResponse(response);
+      return VatResource.fromArray(data);
+    });
   }
   async history(vatUid) {
     let url = `${this.baseUrl}/vat/history`;
     if (vatUid) url += `?vat_uid=${encodeURIComponent(vatUid)}`;
-    const response = await this.sendRequest("GET", url);
-    const data = await this.parseJsonResponse(response);
-    return VatCollection.fromResponse(data);
+    return withRetries(this.retryPolicy, "VAT history request", async () => {
+      const response = await this.sendRequest("GET", url);
+      const data = await this.parseJsonResponse(response);
+      return VatCollection.fromResponse(data);
+    });
   }
   async search(term, perPage) {
     const params = new URLSearchParams();
@@ -2540,16 +2909,20 @@ var VatEndpoint = class {
     if (perPage !== void 0) params.set("per_page", String(perPage));
     const queryString = params.toString();
     const url = `${this.baseUrl}/vat/search${queryString ? `?${queryString}` : ""}`;
-    const response = await this.sendRequest("GET", url);
-    const data = await this.parseJsonResponse(response);
-    return VatCollection.fromResponse(data);
+    return withRetries(this.retryPolicy, "VAT search", async () => {
+      const response = await this.sendRequest("GET", url);
+      const data = await this.parseJsonResponse(response);
+      return VatCollection.fromResponse(data);
+    });
   }
   async certificate(uuid, lang) {
     let url = `${this.baseUrl}/vat/certificate/${encodeURIComponent(uuid)}`;
     if (lang) url += `?lang=${lang}`;
-    const response = await this.sendBinaryRequest("GET", url);
-    const buffer = await response.arrayBuffer();
-    return new Uint8Array(buffer);
+    return withRetries(this.retryPolicy, "VAT certificate download", async () => {
+      const response = await this.sendBinaryRequest("GET", url);
+      const buffer = await response.arrayBuffer();
+      return new Uint8Array(buffer);
+    });
   }
   async certificatesBulkExport(fromDate, toDate, countries, lang) {
     return this.exportRequest(`${this.baseUrl}/vat/certificates/bulk-export`, fromDate, toDate, countries, lang);
@@ -2573,9 +2946,11 @@ var VatEndpoint = class {
   }
   async downloadBulkExport(exportId) {
     const url = `${this.baseUrl}/vat/certificates/bulk-export/${encodeURIComponent(exportId)}/download`;
-    const response = await this.sendBinaryRequest("GET", url);
-    const buffer = await response.arrayBuffer();
-    return new Uint8Array(buffer);
+    return withRetries(this.retryPolicy, "VAT export download", async () => {
+      const response = await this.sendBinaryRequest("GET", url);
+      const buffer = await response.arrayBuffer();
+      return new Uint8Array(buffer);
+    });
   }
   buildHeaders() {
     const headers = {
@@ -2599,7 +2974,13 @@ var VatEndpoint = class {
     const response = await this.httpClient.request(method, url, { headers });
     if (!response.ok) {
       const text = await response.text();
-      throw new HttpException(`HTTP error ${response.status}`, response.status, text);
+      throw new HttpException(
+        describeApiError(text, response.status),
+        response.status,
+        text,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     return response;
   }
@@ -2614,19 +2995,25 @@ var VatEndpoint = class {
         }
       } catch {
       }
-      throw new ValidationException("Validation failed", errors);
+      throw new ValidationException(jsonErrorMessage(responseText) ?? "Validation failed", errors);
     }
     if (!response.ok && !acceptedStatuses.includes(response.status)) {
-      throw new HttpException(`HTTP error ${response.status}`, response.status, responseText);
+      throw new HttpException(
+        describeApiError(responseText, response.status),
+        response.status,
+        responseText,
+        {},
+        response.headers.get("retry-after")
+      );
     }
     let parsed;
     try {
       parsed = JSON.parse(responseText);
     } catch {
-      throw new HttpException("Invalid JSON response", 0, responseText);
+      throw new HttpException("Invalid JSON response", response.status, responseText);
     }
     if (typeof parsed !== "object" || parsed === null) {
-      throw new HttpException("Unexpected response format", 0, responseText);
+      throw new HttpException("Unexpected response format", response.status, responseText);
     }
     const obj = parsed;
     if (obj["data"] !== void 0 && (typeof obj["data"] === "object" || Array.isArray(obj["data"]))) {
@@ -2725,7 +3112,7 @@ var AuthRetryHttpClient = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.0";
 
 // src/http/SdkVersionHttpClient.ts
 var SDK_VERSION_HEADER = "X-Taxora-SDK-Version";
@@ -2757,14 +3144,15 @@ var TaxoraClient = class {
     const environment = options.environment ?? Environment.SANDBOX;
     const tokenStorage = options.tokenStorage ?? new InMemoryTokenStorage();
     const httpClient = options.httpClient ?? new FetchHttpClient();
+    const retryPolicy = options.retryPolicy ?? new RetryPolicy();
     const versionedClient = new SdkVersionHttpClient(httpClient);
     this.baseUrl = getBaseUrl(environment);
-    this.auth = new AuthEndpoint(this.baseUrl, options.apiKey, tokenStorage, versionedClient);
+    this.auth = new AuthEndpoint(this.baseUrl, options.apiKey, tokenStorage, versionedClient, retryPolicy);
     const retryClient = new AuthRetryHttpClient(versionedClient, tokenStorage, () => this.auth.refresh());
-    this.vat = new VatEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient);
-    this.company = new CompanyEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient);
-    this.smartEnrichment = new SmartEnrichmentEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient);
-    this.eReporting = new EReportingEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient);
+    this.vat = new VatEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient, retryPolicy);
+    this.company = new CompanyEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient, retryPolicy);
+    this.smartEnrichment = new SmartEnrichmentEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient, retryPolicy);
+    this.eReporting = new EReportingEndpoint(this.baseUrl, options.apiKey, tokenStorage, retryClient, retryPolicy);
   }
 };
 
@@ -2812,6 +3200,7 @@ export {
   LoginIdentifier,
   ProviderDocument,
   ProviderDocumentLine,
+  RetryPolicy,
   RevenueStatistics,
   ScoreBreakdown,
   SireneLookupResult,
@@ -2819,6 +3208,7 @@ export {
   SmartEnrichmentHistoryPage,
   SmartEnrichmentHistoryRow,
   SmartEnrichmentJob,
+  SmartEnrichmentMode,
   SmartEnrichmentResource,
   SmartEnrichmentStatistics,
   SmartEnrichmentStatus,
@@ -2834,10 +3224,12 @@ export {
   VatResource,
   VatState,
   VatValidationAddressInput,
+  describeApiError,
   describeComplianceEnrollmentStatus,
   describeComplianceTaxReportState,
   describeComplianceTransactionState,
   describeComplianceTransactionType,
+  describeSmartEnrichmentMode,
   describeSmartEnrichmentStatus,
   describeVatState,
   getBaseUrl,
@@ -2846,6 +3238,7 @@ export {
   toComplianceTaxReportState,
   toComplianceTransactionState,
   toComplianceTransactionType,
+  toSmartEnrichmentMode,
   toSmartEnrichmentStatus
 };
 //# sourceMappingURL=index.js.map