@taxora/sdk 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -22,6 +22,75 @@ interface HttpClientInterface {
     request(method: string, url: string, options?: RequestInit): Promise<Response>;
 }
 
+/**
+ * How the SDK retries transient failures.
+ *
+ * Only gateway-level failures are retried by default (502/503/504): those come
+ * from the infrastructure in front of the API, not from the API itself, and a
+ * second attempt a moment later usually succeeds. Everything else — 4xx, and any
+ * answer the API produced itself — is surfaced immediately.
+ *
+ * On top of that, a 429 is retried when the API answers with a `Retry-After`
+ * telling us how long to wait, and connection-level failures (reset connection,
+ * client-side timeout, DNS hiccup) are retried as well — those never reached the
+ * API's answer either.
+ *
+ * Retries are opt-in per operation and are only applied to read-only calls
+ * (lookups, downloads, polling). Calls that change state or cost quota — booking
+ * a transaction, starting an enrichment job, triggering a certificate export —
+ * are never retried automatically, because a gateway timeout does not tell us
+ * whether the API already processed the request.
+ */
+interface RetryPolicyOptions {
+    /** Total attempts including the first one (1 disables retrying). */
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    backoffMultiplier?: number;
+    maxDelayMs?: number;
+    retryableStatusCodes?: number[];
+    /** Honour a `Retry-After` header instead of the backoff, and retry a 429 that carries one. */
+    respectRetryAfter?: boolean;
+    /** Longest wait accepted from `Retry-After`; a longer one means we give up instead of blocking. */
+    maxRetryAfterMs?: number;
+    /** Retry connection-level failures (reset connection, client-side timeout, DNS hiccup). */
+    retryOnNetworkErrors?: boolean;
+    /** Receives the delay in milliseconds; defaults to setTimeout. */
+    sleeper?: (delayMs: number) => Promise<void> | void;
+}
+declare class RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialDelayMs: number;
+    readonly backoffMultiplier: number;
+    readonly maxDelayMs: number;
+    readonly retryableStatusCodes: number[];
+    readonly respectRetryAfter: boolean;
+    readonly maxRetryAfterMs: number;
+    readonly retryOnNetworkErrors: boolean;
+    private readonly sleeper;
+    constructor(options?: RetryPolicyOptions);
+    /** No retrying at all — every failure is surfaced on the first attempt. */
+    static disabled(): RetryPolicy;
+    /** Retry immediately, without waiting (mainly useful in tests). */
+    static withoutDelay(maxAttempts?: number): RetryPolicy;
+    isRetryable(statusCode: number, retryAfterHeader?: string | null): boolean;
+    /** @param attempt Number of attempts made so far (1 = the first one just failed). */
+    shouldRetry(statusCode: number, attempt: number, retryAfterHeader?: string | null): boolean;
+    /**
+     * A connection-level failure: the request never got an answer, so repeating it
+     * is as safe as repeating a gateway timeout.
+     */
+    isRetryableError(error: unknown): boolean;
+    shouldRetryError(error: unknown, attempt: number): boolean;
+    /**
+     * 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: string | null | undefined, now?: Date): number | null;
+    /** The wait before the next attempt: what the API asked for, else exponential backoff. */
+    delayMsForAttempt(attempt: number, retryAfterHeader?: string | null): number;
+    sleepBeforeRetry(attempt: number, retryAfterHeader?: string | null): Promise<void>;
+}
+
 interface TokenStorageInterface {
     get(): Token | null;
     set(token: Token): void;
@@ -33,7 +102,8 @@ declare class AuthEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     login(identifier: string, password: string, device?: string, loginIdentifier?: LoginIdentifier): Promise<Token>;
     loginWithClientId(clientId: string, password: string, device?: string): Promise<Token>;
     refresh(): Promise<Token>;
@@ -69,7 +139,8 @@ declare class CompanyEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     get(): Promise<CompanyResource>;
 }
 
@@ -553,7 +624,8 @@ declare class EReportingEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     /**
      * Create a compliance enrollment and provision the provider account. By
      * default the DGFiP regime is activated right away; pass `autoActivate: false`
@@ -678,6 +750,30 @@ declare class EReportingEndpoint {
     private formatDate;
 }
 
+/**
+ * How hard a Smart Enrichment lookup is allowed to search.
+ *
+ * `default` searches with one AI provider and consults a second one only when the first finds
+ * nothing — one paid search per lookup in the common case.
+ *
+ * `complex` has two independent AI providers search from the start, and every VAT number either of
+ * them proposes is put through the tax authority's checks until one confirms. Noticeably better on
+ * hard lookups — companies whose VAT only appears in a website Impressum — and it costs more per
+ * lookup, so it is opt-in per request rather than the default.
+ */
+declare const SmartEnrichmentMode: {
+    readonly DEFAULT: "default";
+    readonly COMPLEX: "complex";
+};
+type SmartEnrichmentMode = (typeof SmartEnrichmentMode)[keyof typeof SmartEnrichmentMode];
+/**
+ * Coercion for values coming back from the API. Returns undefined for anything unrecognized —
+ * unlike the status enum there is no `unknown` member to fall back to, and inventing a mode would
+ * misreport how a lookup actually ran.
+ */
+declare function toSmartEnrichmentMode(value: unknown): SmartEnrichmentMode | undefined;
+declare function describeSmartEnrichmentMode(mode: SmartEnrichmentMode): string;
+
 declare const SmartEnrichmentStatus: {
     readonly FOUND: "found";
     readonly NO_VAT_EXISTS: "no_vat_exists";
@@ -693,6 +789,34 @@ type SmartEnrichmentStatus = (typeof SmartEnrichmentStatus)[keyof typeof SmartEn
 declare function toSmartEnrichmentStatus(value: unknown): SmartEnrichmentStatus;
 declare function describeSmartEnrichmentStatus(status: SmartEnrichmentStatus): string;
 
+/** What one AI provider independently concluded, when more than one searched. */
+interface SmartEnrichmentProviderVerdict {
+    provider: string;
+    model: string | null;
+    status: string;
+    vatNumber: string | null;
+    confidence: number | null;
+    /** False when the model answered from memory instead of an actual web search. */
+    grounded: boolean;
+    sourceUrl: string | null;
+}
+/**
+ * What the API made of the address you submitted. The actionable part is `warnings`:
+ * `postal_code_city_mismatch` / `postal_code_unassigned` / `postal_code_format_invalid` mean the
+ * postal code in your source record is wrong, and `derivedPlace` is where it actually points —
+ * worth writing back into your own data.
+ */
+interface SmartEnrichmentAddressQuality {
+    providedPostalCode: string | null;
+    providedCity: string | null;
+    postalCodeFormatValid: boolean | null;
+    postalCodeAssigned: boolean | null;
+    /** False when the postal code was excluded from the search because it could not be trusted. */
+    postalCodeTrusted: boolean;
+    derivedPlace: string | null;
+    cityMatchesPostalCode: boolean | null;
+    warnings: string[];
+}
 /**
  * Result of resolving one reverse-VAT lookup (company name + address → VAT + confidence).
  * Mirrors the API response item shape (camelCase keys).
@@ -707,9 +831,26 @@ declare class SmartEnrichmentResource {
     readonly matchedAddress: string | undefined;
     readonly country: string | undefined;
     readonly source: string | undefined;
+    /** The search mode this lookup actually ran in. */
+    readonly mode: SmartEnrichmentMode | undefined;
+    /**
+     * What each AI provider independently concluded. Populated when more than one searched
+     * (complex mode, or a fallback). Two entries reporting the same vatNumber is the strongest
+     * confirmation this layer produces.
+     */
+    readonly providerVerdicts: SmartEnrichmentProviderVerdict[];
+    readonly addressQuality: SmartEnrichmentAddressQuality | undefined;
     constructor(status: SmartEnrichmentStatus, vatNumber: string | undefined, vatType: string | undefined, confidence: number | undefined, matchedCompanyName: string | undefined, 
     /** Official/registered address of the matched company, when available. */
-    matchedAddress: string | undefined, country: string | undefined, source: string | undefined);
+    matchedAddress: string | undefined, country: string | undefined, source: string | undefined, 
+    /** The search mode this lookup actually ran in. */
+    mode?: SmartEnrichmentMode | undefined, 
+    /**
+     * What each AI provider independently concluded. Populated when more than one searched
+     * (complex mode, or a fallback). Two entries reporting the same vatNumber is the strongest
+     * confirmation this layer produces.
+     */
+    providerVerdicts?: SmartEnrichmentProviderVerdict[], addressQuality?: SmartEnrichmentAddressQuality | undefined);
     static fromArray(data: Record<string, unknown>): SmartEnrichmentResource;
     toArray(): Record<string, unknown>;
 }
@@ -850,6 +991,11 @@ interface SmartEnrichmentInput {
     street?: string;
     postalCode?: string;
     city?: string;
+    /**
+     * Search depth. Omit to use the server default (`default`). `complex` searches with two
+     * independent providers and cross-checks them — better hit rate, higher cost per lookup.
+     */
+    mode?: SmartEnrichmentMode;
 }
 /** One recent monthly billing entry, exposed on the usage response for transparency. */
 interface SmartEnrichmentUsageHistoryEntry {
@@ -912,7 +1058,8 @@ declare class SmartEnrichmentEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: 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
@@ -922,8 +1069,11 @@ declare class SmartEnrichmentEndpoint {
     /**
      * 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.
      */
-    bulkLookup(items: SmartEnrichmentInput[]): Promise<SmartEnrichmentJob>;
+    bulkLookup(items: SmartEnrichmentInput[], mode?: SmartEnrichmentMode): Promise<SmartEnrichmentJob>;
     /** Poll a job (single or bulk) by its id. */
     get(jobId: string): Promise<SmartEnrichmentJob>;
     /**
@@ -1139,9 +1289,9 @@ declare class VatEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     validate(vatUid: string, companyName?: string, provider?: string, addressInput?: VatValidationAddressInput | Record<string, string>): Promise<VatResource>;
-    private validateWithGatewayRetry;
     validateMultiple(vatUids: string[], companyNames?: string[], provider?: string): Promise<VatCollection>;
     validateSchema(vatUid: string): Promise<Record<string, unknown>>;
     state(vatUid: string): Promise<VatResource>;
@@ -1171,6 +1321,8 @@ interface TaxoraClientOptions {
     environment?: Environment;
     tokenStorage?: TokenStorageInterface;
     httpClient?: HttpClientInterface;
+    /** Retry behaviour for transient gateway failures; defaults to 3 attempts with backoff. */
+    retryPolicy?: RetryPolicy;
 }
 declare class TaxoraClient {
     readonly auth: AuthEndpoint;
@@ -1204,9 +1356,17 @@ declare class AuthenticationException extends TaxoraException {
 declare class HttpException extends TaxoraException {
     readonly statusCode: number;
     readonly responseBody: string;
-    constructor(message: string, statusCode: number, responseBody: string, context?: Record<string, unknown>);
+    /** Raw `Retry-After` header of the failed response, when it carried one. */
+    readonly retryAfter: string | null;
+    constructor(message: string, statusCode: number, responseBody: string, context?: Record<string, unknown>, retryAfter?: string | null);
+    /**
+     * 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: string, attempts: number, last: HttpException): HttpException;
     getStatusCode(): number;
     getResponseBody(): string;
+    getRetryAfter(): string | null;
 }
 
 declare class ValidationException extends TaxoraException {
@@ -1216,6 +1376,24 @@ declare class ValidationException extends TaxoraException {
     getErrors(): Record<string, string[]>;
 }
 
+/**
+ * Derives a short, human readable exception message from an API response body.
+ *
+ * A response body is never used verbatim as an exception message: the gateways
+ * in front of the API (DigitalOcean App Platform, load balancers, proxies)
+ * answer 5xx with a full HTML error page, and that page would otherwise end up
+ * in every log line and stack trace of the integrating application.
+ *
+ * Only the human readable message of a JSON error body is used; everything else
+ * (HTML, empty bodies, binary payloads) falls back to the HTTP status line. The
+ * untouched body always stays available via `HttpException.getResponseBody()`.
+ */
+/**
+ * The message for a failed request: the API message when the body carries one,
+ * otherwise a description of the HTTP status.
+ */
+declare function describeApiError(body: string | null | undefined, statusCode: number): string;
+
 declare class InMemoryTokenStorage implements TokenStorageInterface {
     private token;
     get(): Token | null;
@@ -1242,4 +1420,4 @@ declare class AuthRetryHttpClient implements HttpClientInterface {
     private injectAuthHeader;
 }
 
-export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, type CompanyResource, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoiceTaxInput, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionFilters, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, ComplianceTransactionType, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, type RevenueCountryBreakdown, type RevenueCurrencyBreakdown, type RevenueStateBreakdown, RevenueStatistics, type RevenueStatisticsFilters, type RevenueTimeBucket, type RevenueTotals, type RevenueTypeBreakdown, ScoreBreakdown, SireneLookupResult, type SmartEnrichmentConfidenceBucket, SmartEnrichmentEndpoint, type SmartEnrichmentExportOptions, type SmartEnrichmentHistoryInput, SmartEnrichmentHistoryPage, SmartEnrichmentHistoryRow, type SmartEnrichmentHistoryStats, type SmartEnrichmentInput, SmartEnrichmentJob, type SmartEnrichmentOutcomeBreakdown, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTimeBucket, type SmartEnrichmentUsage, type SmartEnrichmentUsageHistoryEntry, type SmartEnrichmentWaitOptions, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, type UpdateComplianceTransactionInput, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, type VatRate, VatRates, VatResource, VatState, VatValidationAddressInput, describeComplianceEnrollmentStatus, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describeSmartEnrichmentStatus, describeVatState, getBaseUrl, getFailedVatStates, toComplianceEnrollmentStatus, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toSmartEnrichmentStatus };
+export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, type CompanyResource, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoiceTaxInput, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionFilters, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, ComplianceTransactionType, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, RetryPolicy, type RetryPolicyOptions, type RevenueCountryBreakdown, type RevenueCurrencyBreakdown, type RevenueStateBreakdown, RevenueStatistics, type RevenueStatisticsFilters, type RevenueTimeBucket, type RevenueTotals, type RevenueTypeBreakdown, ScoreBreakdown, SireneLookupResult, type SmartEnrichmentAddressQuality, type SmartEnrichmentConfidenceBucket, SmartEnrichmentEndpoint, type SmartEnrichmentExportOptions, type SmartEnrichmentHistoryInput, SmartEnrichmentHistoryPage, SmartEnrichmentHistoryRow, type SmartEnrichmentHistoryStats, type SmartEnrichmentInput, SmartEnrichmentJob, SmartEnrichmentMode, type SmartEnrichmentOutcomeBreakdown, type SmartEnrichmentProviderVerdict, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTimeBucket, type SmartEnrichmentUsage, type SmartEnrichmentUsageHistoryEntry, type SmartEnrichmentWaitOptions, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, type UpdateComplianceTransactionInput, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, type VatRate, VatRates, VatResource, VatState, VatValidationAddressInput, describeApiError, describeComplianceEnrollmentStatus, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describeSmartEnrichmentMode, describeSmartEnrichmentStatus, describeVatState, getBaseUrl, getFailedVatStates, toComplianceEnrollmentStatus, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toSmartEnrichmentMode, toSmartEnrichmentStatus };

package/dist/index.d.ts

@@ -22,6 +22,75 @@ interface HttpClientInterface {
     request(method: string, url: string, options?: RequestInit): Promise<Response>;
 }
 
+/**
+ * How the SDK retries transient failures.
+ *
+ * Only gateway-level failures are retried by default (502/503/504): those come
+ * from the infrastructure in front of the API, not from the API itself, and a
+ * second attempt a moment later usually succeeds. Everything else — 4xx, and any
+ * answer the API produced itself — is surfaced immediately.
+ *
+ * On top of that, a 429 is retried when the API answers with a `Retry-After`
+ * telling us how long to wait, and connection-level failures (reset connection,
+ * client-side timeout, DNS hiccup) are retried as well — those never reached the
+ * API's answer either.
+ *
+ * Retries are opt-in per operation and are only applied to read-only calls
+ * (lookups, downloads, polling). Calls that change state or cost quota — booking
+ * a transaction, starting an enrichment job, triggering a certificate export —
+ * are never retried automatically, because a gateway timeout does not tell us
+ * whether the API already processed the request.
+ */
+interface RetryPolicyOptions {
+    /** Total attempts including the first one (1 disables retrying). */
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    backoffMultiplier?: number;
+    maxDelayMs?: number;
+    retryableStatusCodes?: number[];
+    /** Honour a `Retry-After` header instead of the backoff, and retry a 429 that carries one. */
+    respectRetryAfter?: boolean;
+    /** Longest wait accepted from `Retry-After`; a longer one means we give up instead of blocking. */
+    maxRetryAfterMs?: number;
+    /** Retry connection-level failures (reset connection, client-side timeout, DNS hiccup). */
+    retryOnNetworkErrors?: boolean;
+    /** Receives the delay in milliseconds; defaults to setTimeout. */
+    sleeper?: (delayMs: number) => Promise<void> | void;
+}
+declare class RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialDelayMs: number;
+    readonly backoffMultiplier: number;
+    readonly maxDelayMs: number;
+    readonly retryableStatusCodes: number[];
+    readonly respectRetryAfter: boolean;
+    readonly maxRetryAfterMs: number;
+    readonly retryOnNetworkErrors: boolean;
+    private readonly sleeper;
+    constructor(options?: RetryPolicyOptions);
+    /** No retrying at all — every failure is surfaced on the first attempt. */
+    static disabled(): RetryPolicy;
+    /** Retry immediately, without waiting (mainly useful in tests). */
+    static withoutDelay(maxAttempts?: number): RetryPolicy;
+    isRetryable(statusCode: number, retryAfterHeader?: string | null): boolean;
+    /** @param attempt Number of attempts made so far (1 = the first one just failed). */
+    shouldRetry(statusCode: number, attempt: number, retryAfterHeader?: string | null): boolean;
+    /**
+     * A connection-level failure: the request never got an answer, so repeating it
+     * is as safe as repeating a gateway timeout.
+     */
+    isRetryableError(error: unknown): boolean;
+    shouldRetryError(error: unknown, attempt: number): boolean;
+    /**
+     * 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: string | null | undefined, now?: Date): number | null;
+    /** The wait before the next attempt: what the API asked for, else exponential backoff. */
+    delayMsForAttempt(attempt: number, retryAfterHeader?: string | null): number;
+    sleepBeforeRetry(attempt: number, retryAfterHeader?: string | null): Promise<void>;
+}
+
 interface TokenStorageInterface {
     get(): Token | null;
     set(token: Token): void;
@@ -33,7 +102,8 @@ declare class AuthEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     login(identifier: string, password: string, device?: string, loginIdentifier?: LoginIdentifier): Promise<Token>;
     loginWithClientId(clientId: string, password: string, device?: string): Promise<Token>;
     refresh(): Promise<Token>;
@@ -69,7 +139,8 @@ declare class CompanyEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     get(): Promise<CompanyResource>;
 }
 
@@ -553,7 +624,8 @@ declare class EReportingEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     /**
      * Create a compliance enrollment and provision the provider account. By
      * default the DGFiP regime is activated right away; pass `autoActivate: false`
@@ -678,6 +750,30 @@ declare class EReportingEndpoint {
     private formatDate;
 }
 
+/**
+ * How hard a Smart Enrichment lookup is allowed to search.
+ *
+ * `default` searches with one AI provider and consults a second one only when the first finds
+ * nothing — one paid search per lookup in the common case.
+ *
+ * `complex` has two independent AI providers search from the start, and every VAT number either of
+ * them proposes is put through the tax authority's checks until one confirms. Noticeably better on
+ * hard lookups — companies whose VAT only appears in a website Impressum — and it costs more per
+ * lookup, so it is opt-in per request rather than the default.
+ */
+declare const SmartEnrichmentMode: {
+    readonly DEFAULT: "default";
+    readonly COMPLEX: "complex";
+};
+type SmartEnrichmentMode = (typeof SmartEnrichmentMode)[keyof typeof SmartEnrichmentMode];
+/**
+ * Coercion for values coming back from the API. Returns undefined for anything unrecognized —
+ * unlike the status enum there is no `unknown` member to fall back to, and inventing a mode would
+ * misreport how a lookup actually ran.
+ */
+declare function toSmartEnrichmentMode(value: unknown): SmartEnrichmentMode | undefined;
+declare function describeSmartEnrichmentMode(mode: SmartEnrichmentMode): string;
+
 declare const SmartEnrichmentStatus: {
     readonly FOUND: "found";
     readonly NO_VAT_EXISTS: "no_vat_exists";
@@ -693,6 +789,34 @@ type SmartEnrichmentStatus = (typeof SmartEnrichmentStatus)[keyof typeof SmartEn
 declare function toSmartEnrichmentStatus(value: unknown): SmartEnrichmentStatus;
 declare function describeSmartEnrichmentStatus(status: SmartEnrichmentStatus): string;
 
+/** What one AI provider independently concluded, when more than one searched. */
+interface SmartEnrichmentProviderVerdict {
+    provider: string;
+    model: string | null;
+    status: string;
+    vatNumber: string | null;
+    confidence: number | null;
+    /** False when the model answered from memory instead of an actual web search. */
+    grounded: boolean;
+    sourceUrl: string | null;
+}
+/**
+ * What the API made of the address you submitted. The actionable part is `warnings`:
+ * `postal_code_city_mismatch` / `postal_code_unassigned` / `postal_code_format_invalid` mean the
+ * postal code in your source record is wrong, and `derivedPlace` is where it actually points —
+ * worth writing back into your own data.
+ */
+interface SmartEnrichmentAddressQuality {
+    providedPostalCode: string | null;
+    providedCity: string | null;
+    postalCodeFormatValid: boolean | null;
+    postalCodeAssigned: boolean | null;
+    /** False when the postal code was excluded from the search because it could not be trusted. */
+    postalCodeTrusted: boolean;
+    derivedPlace: string | null;
+    cityMatchesPostalCode: boolean | null;
+    warnings: string[];
+}
 /**
  * Result of resolving one reverse-VAT lookup (company name + address → VAT + confidence).
  * Mirrors the API response item shape (camelCase keys).
@@ -707,9 +831,26 @@ declare class SmartEnrichmentResource {
     readonly matchedAddress: string | undefined;
     readonly country: string | undefined;
     readonly source: string | undefined;
+    /** The search mode this lookup actually ran in. */
+    readonly mode: SmartEnrichmentMode | undefined;
+    /**
+     * What each AI provider independently concluded. Populated when more than one searched
+     * (complex mode, or a fallback). Two entries reporting the same vatNumber is the strongest
+     * confirmation this layer produces.
+     */
+    readonly providerVerdicts: SmartEnrichmentProviderVerdict[];
+    readonly addressQuality: SmartEnrichmentAddressQuality | undefined;
     constructor(status: SmartEnrichmentStatus, vatNumber: string | undefined, vatType: string | undefined, confidence: number | undefined, matchedCompanyName: string | undefined, 
     /** Official/registered address of the matched company, when available. */
-    matchedAddress: string | undefined, country: string | undefined, source: string | undefined);
+    matchedAddress: string | undefined, country: string | undefined, source: string | undefined, 
+    /** The search mode this lookup actually ran in. */
+    mode?: SmartEnrichmentMode | undefined, 
+    /**
+     * What each AI provider independently concluded. Populated when more than one searched
+     * (complex mode, or a fallback). Two entries reporting the same vatNumber is the strongest
+     * confirmation this layer produces.
+     */
+    providerVerdicts?: SmartEnrichmentProviderVerdict[], addressQuality?: SmartEnrichmentAddressQuality | undefined);
     static fromArray(data: Record<string, unknown>): SmartEnrichmentResource;
     toArray(): Record<string, unknown>;
 }
@@ -850,6 +991,11 @@ interface SmartEnrichmentInput {
     street?: string;
     postalCode?: string;
     city?: string;
+    /**
+     * Search depth. Omit to use the server default (`default`). `complex` searches with two
+     * independent providers and cross-checks them — better hit rate, higher cost per lookup.
+     */
+    mode?: SmartEnrichmentMode;
 }
 /** One recent monthly billing entry, exposed on the usage response for transparency. */
 interface SmartEnrichmentUsageHistoryEntry {
@@ -912,7 +1058,8 @@ declare class SmartEnrichmentEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: 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
@@ -922,8 +1069,11 @@ declare class SmartEnrichmentEndpoint {
     /**
      * 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.
      */
-    bulkLookup(items: SmartEnrichmentInput[]): Promise<SmartEnrichmentJob>;
+    bulkLookup(items: SmartEnrichmentInput[], mode?: SmartEnrichmentMode): Promise<SmartEnrichmentJob>;
     /** Poll a job (single or bulk) by its id. */
     get(jobId: string): Promise<SmartEnrichmentJob>;
     /**
@@ -1139,9 +1289,9 @@ declare class VatEndpoint {
     private readonly apiKey;
     private readonly tokenStorage;
     private readonly httpClient;
-    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface);
+    private readonly retryPolicy;
+    constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
     validate(vatUid: string, companyName?: string, provider?: string, addressInput?: VatValidationAddressInput | Record<string, string>): Promise<VatResource>;
-    private validateWithGatewayRetry;
     validateMultiple(vatUids: string[], companyNames?: string[], provider?: string): Promise<VatCollection>;
     validateSchema(vatUid: string): Promise<Record<string, unknown>>;
     state(vatUid: string): Promise<VatResource>;
@@ -1171,6 +1321,8 @@ interface TaxoraClientOptions {
     environment?: Environment;
     tokenStorage?: TokenStorageInterface;
     httpClient?: HttpClientInterface;
+    /** Retry behaviour for transient gateway failures; defaults to 3 attempts with backoff. */
+    retryPolicy?: RetryPolicy;
 }
 declare class TaxoraClient {
     readonly auth: AuthEndpoint;
@@ -1204,9 +1356,17 @@ declare class AuthenticationException extends TaxoraException {
 declare class HttpException extends TaxoraException {
     readonly statusCode: number;
     readonly responseBody: string;
-    constructor(message: string, statusCode: number, responseBody: string, context?: Record<string, unknown>);
+    /** Raw `Retry-After` header of the failed response, when it carried one. */
+    readonly retryAfter: string | null;
+    constructor(message: string, statusCode: number, responseBody: string, context?: Record<string, unknown>, retryAfter?: string | null);
+    /**
+     * 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: string, attempts: number, last: HttpException): HttpException;
     getStatusCode(): number;
     getResponseBody(): string;
+    getRetryAfter(): string | null;
 }
 
 declare class ValidationException extends TaxoraException {
@@ -1216,6 +1376,24 @@ declare class ValidationException extends TaxoraException {
     getErrors(): Record<string, string[]>;
 }
 
+/**
+ * Derives a short, human readable exception message from an API response body.
+ *
+ * A response body is never used verbatim as an exception message: the gateways
+ * in front of the API (DigitalOcean App Platform, load balancers, proxies)
+ * answer 5xx with a full HTML error page, and that page would otherwise end up
+ * in every log line and stack trace of the integrating application.
+ *
+ * Only the human readable message of a JSON error body is used; everything else
+ * (HTML, empty bodies, binary payloads) falls back to the HTTP status line. The
+ * untouched body always stays available via `HttpException.getResponseBody()`.
+ */
+/**
+ * The message for a failed request: the API message when the body carries one,
+ * otherwise a description of the HTTP status.
+ */
+declare function describeApiError(body: string | null | undefined, statusCode: number): string;
+
 declare class InMemoryTokenStorage implements TokenStorageInterface {
     private token;
     get(): Token | null;
@@ -1242,4 +1420,4 @@ declare class AuthRetryHttpClient implements HttpClientInterface {
     private injectAuthHeader;
 }
 
-export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, type CompanyResource, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoiceTaxInput, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionFilters, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, ComplianceTransactionType, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, type RevenueCountryBreakdown, type RevenueCurrencyBreakdown, type RevenueStateBreakdown, RevenueStatistics, type RevenueStatisticsFilters, type RevenueTimeBucket, type RevenueTotals, type RevenueTypeBreakdown, ScoreBreakdown, SireneLookupResult, type SmartEnrichmentConfidenceBucket, SmartEnrichmentEndpoint, type SmartEnrichmentExportOptions, type SmartEnrichmentHistoryInput, SmartEnrichmentHistoryPage, SmartEnrichmentHistoryRow, type SmartEnrichmentHistoryStats, type SmartEnrichmentInput, SmartEnrichmentJob, type SmartEnrichmentOutcomeBreakdown, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTimeBucket, type SmartEnrichmentUsage, type SmartEnrichmentUsageHistoryEntry, type SmartEnrichmentWaitOptions, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, type UpdateComplianceTransactionInput, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, type VatRate, VatRates, VatResource, VatState, VatValidationAddressInput, describeComplianceEnrollmentStatus, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describeSmartEnrichmentStatus, describeVatState, getBaseUrl, getFailedVatStates, toComplianceEnrollmentStatus, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toSmartEnrichmentStatus };
+export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, type CompanyResource, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoiceTaxInput, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionFilters, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, ComplianceTransactionType, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, RetryPolicy, type RetryPolicyOptions, type RevenueCountryBreakdown, type RevenueCurrencyBreakdown, type RevenueStateBreakdown, RevenueStatistics, type RevenueStatisticsFilters, type RevenueTimeBucket, type RevenueTotals, type RevenueTypeBreakdown, ScoreBreakdown, SireneLookupResult, type SmartEnrichmentAddressQuality, type SmartEnrichmentConfidenceBucket, SmartEnrichmentEndpoint, type SmartEnrichmentExportOptions, type SmartEnrichmentHistoryInput, SmartEnrichmentHistoryPage, SmartEnrichmentHistoryRow, type SmartEnrichmentHistoryStats, type SmartEnrichmentInput, SmartEnrichmentJob, SmartEnrichmentMode, type SmartEnrichmentOutcomeBreakdown, type SmartEnrichmentProviderVerdict, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTimeBucket, type SmartEnrichmentUsage, type SmartEnrichmentUsageHistoryEntry, type SmartEnrichmentWaitOptions, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, type UpdateComplianceTransactionInput, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, type VatRate, VatRates, VatResource, VatState, VatValidationAddressInput, describeApiError, describeComplianceEnrollmentStatus, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describeSmartEnrichmentMode, describeSmartEnrichmentStatus, describeVatState, getBaseUrl, getFailedVatStates, toComplianceEnrollmentStatus, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toSmartEnrichmentMode, toSmartEnrichmentStatus };