@taxora/sdk 1.0.7 → 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,10 +139,988 @@ 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>;
 }
 
+declare const ComplianceEnrollmentStatus: {
+    readonly PENDING_DATA: "pending_data";
+    readonly ACCOUNT_CREATED: "account_created";
+    readonly REGIME_ACTIVATED: "regime_activated";
+    readonly READY: "ready";
+    readonly SUSPENDED: "suspended";
+    readonly ERROR_ACCOUNT: "error_account";
+    readonly ERROR_ACTIVATION: "error_activation";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceEnrollmentStatus = (typeof ComplianceEnrollmentStatus)[keyof typeof ComplianceEnrollmentStatus];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceEnrollmentStatus(value: unknown): ComplianceEnrollmentStatus;
+declare function describeComplianceEnrollmentStatus(status: ComplianceEnrollmentStatus): string;
+
+/**
+ * A compliance enrollment — the merchant's provisioned e-reporting account for
+ * one reporting country/regime (GET/POST /compliance/enrollments).
+ */
+declare class ComplianceEnrollment {
+    readonly id: number;
+    readonly companyId: number;
+    readonly country: string;
+    readonly regime: string;
+    readonly provider: string;
+    readonly status: ComplianceEnrollmentStatus;
+    readonly statusLabel: string;
+    readonly statusError: string | null;
+    readonly providerAccountId: string | null;
+    readonly taxId: string | null;
+    readonly companyRegisterId: string | null;
+    readonly companyRegisterScheme: string | null;
+    readonly regimeConfig: Record<string, unknown> | null;
+    /** First date transactions are reported for (YYYY-MM-DD). */
+    readonly reportingStartDate: string | null;
+    readonly notificationEmail: string | null;
+    readonly autoSend: boolean;
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    constructor(id: number, companyId: number, country: string, regime: string, provider: string, status: ComplianceEnrollmentStatus, statusLabel: string, statusError: string | null, providerAccountId: string | null, taxId: string | null, companyRegisterId: string | null, companyRegisterScheme: string | null, regimeConfig: Record<string, unknown> | null, 
+    /** First date transactions are reported for (YYYY-MM-DD). */
+    reportingStartDate: string | null, notificationEmail: string | null, autoSend: boolean, createdAt: string | null, updatedAt: string | null);
+    static fromArray(data: Record<string, unknown>): ComplianceEnrollment;
+}
+
+/**
+ * A paginated page of compliance enrollments (GET /compliance/enrollments).
+ */
+declare class ComplianceEnrollmentPage implements Iterable<ComplianceEnrollment> {
+    readonly rows: ComplianceEnrollment[];
+    readonly currentPage: number;
+    readonly perPage: number;
+    readonly total: number;
+    readonly lastPage: number;
+    constructor(rows: ComplianceEnrollment[], currentPage: number, perPage: number, total: number, lastPage: number);
+    static fromResponse(payload: unknown): ComplianceEnrollmentPage;
+    [Symbol.iterator](): Iterator<ComplianceEnrollment>;
+    get length(): number;
+}
+
+declare const ComplianceTaxReportState: {
+    readonly NEW: "new";
+    readonly SENT: "sent";
+    readonly ACKNOWLEDGED: "acknowledged";
+    readonly REGISTERED: "registered";
+    readonly REFUSED: "refused";
+    readonly ERROR: "error";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceTaxReportState = (typeof ComplianceTaxReportState)[keyof typeof ComplianceTaxReportState];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceTaxReportState(value: unknown): ComplianceTaxReportState;
+declare function describeComplianceTaxReportState(state: ComplianceTaxReportState): string;
+
+/**
+ * A DGFiP tax report tracking one transaction through the aggregated daily
+ * ledger lifecycle (GET /compliance/tax-reports).
+ */
+declare class ComplianceTaxReport {
+    readonly id: number;
+    readonly companyId: number;
+    readonly complianceTransactionId: number | null;
+    readonly ledgerId: number | null;
+    readonly country: string;
+    readonly regime: string;
+    readonly state: ComplianceTaxReportState;
+    readonly stateLabel: string;
+    /** True once the report reached a final state (registered, refused or error). */
+    readonly isTerminal: boolean;
+    readonly providerTaxReportId: string | null;
+    readonly providerLedgerId: string | null;
+    readonly baseAmount: string;
+    readonly taxAmount: string;
+    readonly totalAmount: string;
+    readonly refusalReason: string | null;
+    readonly registeredAt: string | null;
+    readonly refusedAt: string | null;
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    constructor(id: number, companyId: number, complianceTransactionId: number | null, ledgerId: number | null, country: string, regime: string, state: ComplianceTaxReportState, stateLabel: string, 
+    /** True once the report reached a final state (registered, refused or error). */
+    isTerminal: boolean, providerTaxReportId: string | null, providerLedgerId: string | null, baseAmount: string, taxAmount: string, totalAmount: string, refusalReason: string | null, registeredAt: string | null, refusedAt: string | null, createdAt: string | null, updatedAt: string | null);
+    static fromArray(data: Record<string, unknown>): ComplianceTaxReport;
+}
+
+/**
+ * A paginated page of compliance tax reports (GET /compliance/tax-reports).
+ */
+declare class ComplianceTaxReportPage implements Iterable<ComplianceTaxReport> {
+    readonly rows: ComplianceTaxReport[];
+    readonly currentPage: number;
+    readonly perPage: number;
+    readonly total: number;
+    readonly lastPage: number;
+    constructor(rows: ComplianceTaxReport[], currentPage: number, perPage: number, total: number, lastPage: number);
+    static fromResponse(payload: unknown): ComplianceTaxReportPage;
+    [Symbol.iterator](): Iterator<ComplianceTaxReport>;
+    get length(): number;
+}
+
+declare const ComplianceTransactionState: {
+    readonly PENDING: "pending";
+    readonly SENDING: "sending";
+    readonly SUBMITTED: "submitted";
+    readonly ERROR: "error";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceTransactionState = (typeof ComplianceTransactionState)[keyof typeof ComplianceTransactionState];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceTransactionState(value: unknown): ComplianceTransactionState;
+declare function describeComplianceTransactionState(state: ComplianceTransactionState): string;
+
+declare const ComplianceTransactionType: {
+    readonly B2C_OUTBOUND: "b2c_outbound";
+    readonly B2B_DOMESTIC_OUTBOUND: "b2b_domestic_outbound";
+    readonly B2B_DOMESTIC_INBOUND: "b2b_domestic_inbound";
+    readonly CROSSBORDER_OUTBOUND: "crossborder_outbound";
+    readonly CROSSBORDER_INBOUND: "crossborder_inbound";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceTransactionType = (typeof ComplianceTransactionType)[keyof typeof ComplianceTransactionType];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceTransactionType(value: unknown): ComplianceTransactionType;
+declare function describeComplianceTransactionType(type: ComplianceTransactionType): string;
+
+/**
+ * A recorded e-reporting transaction (GET/POST /compliance/transactions).
+ */
+declare class ComplianceTransaction {
+    readonly id: number;
+    readonly companyId: number;
+    readonly complianceEnrollmentId: number;
+    readonly country: string;
+    readonly regime: string;
+    readonly transactionType: ComplianceTransactionType;
+    readonly transactionTypeLabel: string;
+    readonly state: ComplianceTransactionState;
+    readonly stateLabel: string;
+    readonly invoiceNumber: string;
+    /** Invoice date (YYYY-MM-DD). */
+    readonly invoiceDate: string | null;
+    readonly dueDate: string | null;
+    readonly currency: string;
+    readonly subtotal: string;
+    readonly taxAmount: string;
+    readonly total: string;
+    readonly counterpartyName: string | null;
+    readonly counterpartyCountry: string | null;
+    readonly counterpartyVatNumber: string | null;
+    readonly isPaid: boolean;
+    readonly paidAt: string | null;
+    readonly providerInvoiceId: string | null;
+    readonly submissionError: string | null;
+    readonly reportedAt: string | null;
+    /** Associated DGFiP tax report; undefined when the API did not include it. */
+    readonly taxReport: ComplianceTaxReport | undefined;
+    readonly createdAt: string | null;
+    readonly updatedAt: string | null;
+    constructor(id: number, companyId: number, complianceEnrollmentId: number, country: string, regime: string, transactionType: ComplianceTransactionType, transactionTypeLabel: string, state: ComplianceTransactionState, stateLabel: string, invoiceNumber: string, 
+    /** Invoice date (YYYY-MM-DD). */
+    invoiceDate: string | null, dueDate: string | null, currency: string, subtotal: string, taxAmount: string, total: string, counterpartyName: string | null, counterpartyCountry: string | null, counterpartyVatNumber: string | null, isPaid: boolean, paidAt: string | null, providerInvoiceId: string | null, submissionError: string | null, reportedAt: string | null, 
+    /** Associated DGFiP tax report; undefined when the API did not include it. */
+    taxReport: ComplianceTaxReport | undefined, createdAt: string | null, updatedAt: string | null);
+    static fromArray(data: Record<string, unknown>): ComplianceTransaction;
+}
+
+/**
+ * A paginated page of compliance transactions (GET /compliance/transactions).
+ */
+declare class ComplianceTransactionPage implements Iterable<ComplianceTransaction> {
+    readonly rows: ComplianceTransaction[];
+    readonly currentPage: number;
+    readonly perPage: number;
+    readonly total: number;
+    readonly lastPage: number;
+    constructor(rows: ComplianceTransaction[], currentPage: number, perPage: number, total: number, lastPage: number);
+    static fromResponse(payload: unknown): ComplianceTransactionPage;
+    [Symbol.iterator](): Iterator<ComplianceTransaction>;
+    get length(): number;
+}
+
+/**
+ * Result of a CSV transaction import (POST /compliance/transactions/import).
+ */
+declare class ImportResult {
+    /** Number of transactions created from the file. */
+    readonly created: number;
+    /** Rows skipped because a matching transaction already exists (idempotent re-upload). */
+    readonly skippedDuplicates: number;
+    /** Row-level errors, e.g. "Row 3 (INV-1): invalid transaction_type 'x'". */
+    readonly errors: string[];
+    constructor(
+    /** Number of transactions created from the file. */
+    created: number, 
+    /** Rows skipped because a matching transaction already exists (idempotent re-upload). */
+    skippedDuplicates: number, 
+    /** Row-level errors, e.g. "Row 3 (INV-1): invalid transaction_type 'x'". */
+    errors: string[]);
+    static fromArray(data: Record<string, unknown>): ImportResult;
+}
+
+/**
+ * DTOs for the e-reporting revenue statistics endpoint
+ * (GET /compliance/revenue-statistics).
+ *
+ * Monetary values are kept as the 4-decimal strings returned by the API (no
+ * Number conversion) to preserve precision. All headline figures are expressed
+ * in `primaryCurrency`; when `isMultiCurrency` is true, `byCurrency` lists every
+ * currency present in the range.
+ */
+interface RevenueTotals {
+    count: number;
+    subtotal: string;
+    taxAmount: string;
+    total: string;
+}
+interface RevenueTimeBucket extends RevenueTotals {
+    /** Period key: "2026-01-15" (day), "2026-03" (ISO year-week) or "2026-01" (month). */
+    bucket: string;
+}
+interface RevenueTypeBreakdown {
+    type: string;
+    typeLabel: string;
+    count: number;
+    total: string;
+}
+interface RevenueCountryBreakdown {
+    /** Counterparty country code; "unknown" groups transactions with no partner country. */
+    country: string;
+    count: number;
+    total: string;
+}
+interface RevenueStateBreakdown {
+    state: string;
+    stateLabel: string;
+    count: number;
+    total: string;
+}
+interface RevenueCurrencyBreakdown extends RevenueTotals {
+    currency: string;
+}
+declare class RevenueStatistics {
+    readonly dateFrom: string | undefined;
+    readonly dateTo: string | undefined;
+    readonly interval: string | undefined;
+    readonly primaryCurrency: string;
+    readonly isMultiCurrency: boolean;
+    readonly totals: RevenueTotals;
+    readonly timeSeries: RevenueTimeBucket[];
+    readonly byType: RevenueTypeBreakdown[];
+    readonly byCountry: RevenueCountryBreakdown[];
+    readonly byState: RevenueStateBreakdown[];
+    readonly byCurrency: RevenueCurrencyBreakdown[];
+    constructor(dateFrom: string | undefined, dateTo: string | undefined, interval: string | undefined, primaryCurrency: string, isMultiCurrency: boolean, totals: RevenueTotals, timeSeries: RevenueTimeBucket[], byType: RevenueTypeBreakdown[], byCountry: RevenueCountryBreakdown[], byState: RevenueStateBreakdown[], byCurrency: RevenueCurrencyBreakdown[]);
+    static fromArray(data: Record<string, unknown>): RevenueStatistics;
+}
+
+/**
+ * Company data resolved from the French SIRENE registry
+ * (GET /compliance/sirene-lookup). Maps 1:1 onto the createEnrollment input.
+ */
+declare class SireneLookupResult {
+    readonly companyName: string;
+    readonly siren: string;
+    readonly siret: string | null;
+    /** 2-digit NAF division, e.g. "47". */
+    readonly nafCode: string | null;
+    /** Full NAF/APE code, e.g. "47.11D". */
+    readonly nafFull: string | null;
+    /** Mapped enterprise size ("micro", "pme", "eti" or "ge"); null when unmappable. */
+    readonly enterpriseSize: string | null;
+    readonly address: string | null;
+    readonly city: string | null;
+    readonly postalcode: string | null;
+    constructor(companyName: string, siren: string, siret: string | null, 
+    /** 2-digit NAF division, e.g. "47". */
+    nafCode: string | null, 
+    /** Full NAF/APE code, e.g. "47.11D". */
+    nafFull: string | null, 
+    /** Mapped enterprise size ("micro", "pme", "eti" or "ge"); null when unmappable. */
+    enterpriseSize: string | null, address: string | null, city: string | null, postalcode: string | null);
+    static fromArray(data: Record<string, unknown>): SireneLookupResult;
+}
+
+/**
+ * One VAT rate / DGFiP tax category offered for a reporting country.
+ */
+interface VatRate {
+    /** VAT percentage, e.g. 20 or 5.5. */
+    percent: number;
+    /** DGFiP tax category code (S/AA/AAA/K/G/AE/E/Z). */
+    category: string;
+    /** i18n key for the rate label, e.g. "fr_standard". */
+    labelKey: string;
+    /** Default tax designation prefilled into invoice lines, e.g. "TVA". */
+    taxName: string;
+    /** True when a VATEX exemption code is mandatory in the line's `comment` (category E). */
+    requiresVatex: boolean;
+}
+/**
+ * The canonical VAT rates & DGFiP tax categories for a reporting country
+ * (GET /compliance/vat-rates).
+ */
+declare class VatRates {
+    readonly country: string;
+    readonly currency: string;
+    readonly rates: VatRate[];
+    constructor(country: string, currency: string, rates: VatRate[]);
+    static fromArray(data: Record<string, unknown>): VatRates;
+}
+
+/** Time-series bucket size accepted by the revenue statistics endpoint. */
+type EReportingInterval = 'day' | 'week' | 'month';
+/** Enterprise size categories accepted by the DGFiP enrollment. */
+type ComplianceEnterpriseSize = 'micro' | 'pme' | 'eti' | 'ge';
+/** Type of operations the enrolled company performs. */
+type ComplianceTypeOperation = 'services' | 'goods' | 'mixed';
+/** Transaction types accepted on the request side (the tolerant `unknown` is response-only). */
+type ComplianceTransactionRequestType = Exclude<ComplianceTransactionType, 'unknown'>;
+/** Transaction states accepted as filters (the tolerant `unknown` is response-only). */
+type ComplianceTransactionRequestState = Exclude<ComplianceTransactionState, 'unknown'>;
+/** Tax report states accepted as filters (the tolerant `unknown` is response-only). */
+type ComplianceTaxReportRequestState = Exclude<ComplianceTaxReportState, 'unknown'>;
+interface RevenueStatisticsFilters {
+    dateFrom?: Date | string;
+    dateTo?: Date | string;
+    /** Time-series bucket size. Defaults to "month" server-side. */
+    interval?: EReportingInterval;
+    transactionType?: ComplianceTransactionRequestType;
+    state?: ComplianceTransactionRequestState;
+}
+interface CreateComplianceEnrollmentInput {
+    /** Reporting country (2-char ISO 3166-1 alpha-2). Defaults server-side (FR). */
+    country?: string;
+    /** Compliance regime, e.g. "dgfip_flux10". Defaults server-side. */
+    regime?: string;
+    /** 14-digit SIRET. Required unless `siren` is set. */
+    siret?: string;
+    /** 9-digit SIREN. Required unless `siret` is set. */
+    siren?: string;
+    vatNumber?: string;
+    companyName?: string;
+    address?: string;
+    city?: string;
+    postalcode?: string;
+    province?: string;
+    /** Notification email for the provider account. */
+    email: string;
+    /** 2-digit NAF division, e.g. "47". */
+    nafCode: string;
+    enterpriseSize: ComplianceEnterpriseSize;
+    typeOperation: ComplianceTypeOperation;
+    /** First date transactions are reported for (Date or strict YYYY-MM-DD). */
+    reportingStartDate: Date | string;
+    /** When false, only the provider account is created — the DGFiP regime is NOT activated. Defaults to true server-side. */
+    autoActivate?: boolean;
+}
+interface ComplianceInvoiceTaxInput {
+    /** Tax designation, e.g. "TVA". */
+    name: string;
+    /** VAT percentage, e.g. 20 or 5.5. */
+    percent: number;
+    /** DGFiP tax category code (S/AA/AAA/K/G/AE/E/Z) — see getVatRates(). */
+    category: string;
+    /** VATEX exemption code; required when `category` is "E". */
+    comment?: string;
+}
+interface ComplianceInvoiceLineInput {
+    description: string;
+    quantity: number;
+    price: number;
+    /** UN/ECE unit code, e.g. 9 (each). */
+    unit?: number;
+    /** At least one tax per line. */
+    taxes: ComplianceInvoiceTaxInput[];
+}
+interface CreateComplianceTransactionInput {
+    complianceEnrollmentId: number;
+    transactionType: ComplianceTransactionRequestType;
+    invoiceNumber: string;
+    /** Invoice date (Date or strict YYYY-MM-DD). */
+    invoiceDate: Date | string;
+    subtotal: number;
+    total: number;
+    /** At least one invoice line, each with at least one tax. */
+    invoiceLines: ComplianceInvoiceLineInput[];
+    dueDate?: Date | string;
+    /** 3-char ISO 4217 code. Defaults to EUR server-side. */
+    currency?: string;
+    taxAmount?: number;
+    counterpartyName?: string;
+    /** 2-char ISO 3166-1 alpha-2 code. */
+    counterpartyCountry?: string;
+    counterpartyVatNumber?: string;
+    providerContactId?: string;
+    /** Payment means code; required for cross-border outbound. */
+    paymentMethod?: number;
+    remittanceInformation?: string;
+    paymentMethodText?: string;
+    paymentTerms?: string;
+    /** When false, the transaction is only recorded — submission is deferred. Defaults to true server-side. */
+    submitNow?: boolean;
+}
+interface UpdateComplianceTransactionInput {
+    transactionType?: ComplianceTransactionRequestType;
+    invoiceNumber?: string;
+    invoiceDate?: Date | string;
+    dueDate?: Date | string;
+    /** 3-char ISO 4217 code. */
+    currency?: string;
+    subtotal?: number;
+    taxAmount?: number;
+    total?: number;
+    counterpartyName?: string;
+    /** 2-char ISO 3166-1 alpha-2 code. */
+    counterpartyCountry?: string;
+    counterpartyVatNumber?: string;
+    providerContactId?: string;
+    /** When set: at least one invoice line, each with at least one tax. */
+    invoiceLines?: ComplianceInvoiceLineInput[];
+    paymentMethod?: number;
+    remittanceInformation?: string;
+    paymentMethodText?: string;
+    paymentTerms?: string;
+}
+interface ComplianceTransactionFilters {
+    /** Inclusive lower bound on the invoice date (Date or strict YYYY-MM-DD). */
+    dateFrom?: Date | string;
+    /** Inclusive upper bound on the invoice date (Date or strict YYYY-MM-DD). */
+    dateTo?: Date | string;
+    state?: ComplianceTransactionRequestState;
+    transactionType?: ComplianceTransactionRequestType;
+    page?: number;
+    /** Page size (1-100, default 25 server-side). */
+    perPage?: number;
+}
+interface EReportingAccessRequestInput {
+    name?: string;
+    email?: string;
+    company?: string;
+    phone?: string;
+    message?: string;
+    /** Locale for the confirmation mail, e.g. "de" or "en". */
+    language?: string;
+}
+/**
+ * E-Reporting / Compliance (DGFiP Flux 10) endpoints.
+ *
+ * Typical flow: sireneLookup() to prefill company data, createEnrollment() to
+ * provision the provider account, then createTransaction() / importTransactions()
+ * to record invoices and listTaxReports() to track their DGFiP lifecycle.
+ *
+ * All routes except requestEReportingAccess() require an active E-Reporting
+ * subscription / feature grant on the account.
+ */
+declare class EReportingEndpoint {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tokenStorage;
+    private readonly httpClient;
+    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`
+     * to only create the account.
+     *
+     * On provider failure the API responds 502 (mapped to an HttpException) and
+     * the enrollment is persisted in `error_account`/`error_activation` state so
+     * provisioning can be retried.
+     */
+    createEnrollment(input: CreateComplianceEnrollmentInput): Promise<ComplianceEnrollment>;
+    /** Paginated list of the company's enrollments (newest first). `perPage` is capped at 100 server-side. */
+    listEnrollments(page?: number, perPage?: number): Promise<ComplianceEnrollmentPage>;
+    /** Get a single enrollment by id. */
+    getEnrollment(id: number): Promise<ComplianceEnrollment>;
+    /**
+     * Look up company data by SIRET, SIREN or French VAT number via the French
+     * SIRENE registry — ideal for prefilling createEnrollment().
+     *
+     * Rate-limited to 3 requests/minute per user (protects the external French
+     * government API); exceeding it yields a 429 (mapped to an HttpException).
+     */
+    sireneLookup(q: string): Promise<SireneLookupResult>;
+    /**
+     * Record and (by default) submit a Flux 10 transaction. Pass `submitNow: false`
+     * to only record it — submission can be triggered later via submitTransaction().
+     *
+     * Immediate per-invoice submission requires the e-invoicing feature on the
+     * account; in pure e-reporting mode the transaction is only recorded and
+     * reported via the aggregated daily ledgers.
+     *
+     * Creation is idempotent on the invoice's natural key (enrollment, type,
+     * invoice number, invoice date, counterparty VAT): a re-sent create returns
+     * the existing transaction with HTTP 200 instead of creating a duplicate.
+     *
+     * On provider failure the API responds 502 (mapped to an HttpException).
+     */
+    createTransaction(input: CreateComplianceTransactionInput): Promise<ComplianceTransaction>;
+    /** Paginated list of the company's transactions (newest invoice date first), filterable by date / state / type. */
+    listTransactions(filters?: ComplianceTransactionFilters): Promise<ComplianceTransactionPage>;
+    /** Get a single transaction by id (includes its tax report when one exists). */
+    getTransaction(id: number): Promise<ComplianceTransaction>;
+    /** Update a still-pending transaction. Only the provided fields are sent; already-submitted transactions are rejected with 422. */
+    updateTransaction(id: number, input: UpdateComplianceTransactionInput): Promise<ComplianceTransaction>;
+    /** Delete a still-pending transaction. Already-submitted transactions are rejected with 422. */
+    deleteTransaction(id: number): Promise<void>;
+    /**
+     * Submit (or retry) an existing `pending`/`error` transaction to the provider.
+     * Replays the invoice lines stored at creation, so they don't have to be re-sent.
+     *
+     * Requires the e-invoicing feature on the account — pure e-reporting customers
+     * get a 422 (transactions are reported via the aggregated daily ledgers instead).
+     *
+     * On provider failure the API responds 502 (mapped to an HttpException);
+     * already-submitted transactions are rejected with 422.
+     */
+    submitTransaction(id: number): Promise<ComplianceTransaction>;
+    /**
+     * Bulk-import transactions from a semicolon-separated CSV (one row per invoice
+     * line; rows sharing an invoice_number are grouped into one transaction).
+     * Required columns: invoice_number, invoice_date, transaction_type, subtotal,
+     * total, line_description, line_quantity, line_price, tax_name, tax_percent,
+     * tax_category.
+     *
+     * The import is idempotent: re-uploading the same file skips rows whose
+     * invoice already exists (reported via `skippedDuplicates`).
+     */
+    importTransactions(enrollmentId: number, csvContent: string, filename?: string): Promise<ImportResult>;
+    /**
+     * Aggregated turnover statistics for the authenticated company's e-reporting
+     * transactions. All arguments are optional — the API defaults to the last 12
+     * months and a monthly interval.
+     */
+    getRevenueStatistics(filters?: RevenueStatisticsFilters): Promise<RevenueStatistics>;
+    /**
+     * The canonical VAT rates & DGFiP tax categories for a reporting country
+     * (the seller's reporting-country rates, not the counterparty's). Falls back
+     * to the configured default country (FR) when none/unknown is given.
+     */
+    getVatRates(country?: string): Promise<VatRates>;
+    /** Paginated list of the company's tax reports (newest first), optionally filtered by state. */
+    listTaxReports(page?: number, perPage?: number, state?: ComplianceTaxReportRequestState): Promise<ComplianceTaxReportPage>;
+    /** Get a single tax report by id. */
+    getTaxReport(id: number): Promise<ComplianceTaxReport>;
+    /**
+     * Request activation of the E-Reporting feature for the account. This route
+     * is deliberately NOT gated by compliance access — it exists precisely for
+     * accounts that do not have the feature yet. The authenticated user's
+     * name/email take precedence over the form values server-side.
+     *
+     * Note: unlike the other compliance routes, validation failures here are
+     * returned as HTTP 400 (surfaced as HttpException), not 422.
+     */
+    requestEReportingAccess(input?: EReportingAccessRequestInput): Promise<void>;
+    private validateEnrollmentInput;
+    private validateId;
+    private validateTransactionType;
+    private validateInvoiceNumber;
+    private validateInvoiceLines;
+    private validateOptionalCodes;
+    private buildInvoiceLines;
+    /** Applies the optional scalar fields shared by create and update. */
+    private applyOptionalTransactionFields;
+    private buildHeaders;
+    private sendRequest;
+    /** Multipart upload: Content-Type is left to fetch so the boundary is set correctly. */
+    private sendMultipartRequest;
+    /** Accepts any 2xx response (e.g. 201 on create, 200 on idempotent replay). */
+    private parseJsonResponse;
+    /** For the 204 delete: keeps the shared 422/HTTP error mapping but never parses a body. */
+    private assertNoContentResponse;
+    /**
+     * The backend emits two 422 shapes: Laravel FormRequest failures as
+     * `{message, errors: {field: [...]}}` and state-guard errors via returnError()
+     * as `{error: "reason"}`. Preserve the reason in both cases.
+     */
+    private buildValidationException;
+    /**
+     * Date objects are serialized from their LOCAL date parts — construct them as
+     * `new Date('2026-09-01T00:00:00')` (local midnight); a bare `new Date('2026-09-01')`
+     * is UTC midnight and shifts a day back in UTC-negative timezones.
+     */
+    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";
+    readonly NOT_FOUND: "not_found";
+    readonly PROCESSING: "processing";
+    readonly QUEUED: "queued";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly UNKNOWN: "unknown";
+};
+type SmartEnrichmentStatus = (typeof SmartEnrichmentStatus)[keyof typeof SmartEnrichmentStatus];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+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).
+ */
+declare class SmartEnrichmentResource {
+    readonly status: SmartEnrichmentStatus;
+    readonly vatNumber: string | undefined;
+    readonly vatType: string | undefined;
+    readonly confidence: number | undefined;
+    readonly matchedCompanyName: string | undefined;
+    /** Official/registered address of the matched company, when available. */
+    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, 
+    /** 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>;
+}
+
+/**
+ * A Smart Enrichment job — single lookup or bulk batch. Unifies the API's sync and async
+ * responses: a confident single lookup comes back already resolved (one result, status
+ * `found`); everything else comes back `processing` with a `jobId` to poll.
+ */
+declare class SmartEnrichmentJob {
+    readonly jobId: string;
+    readonly status: SmartEnrichmentStatus;
+    readonly itemCount: number | undefined;
+    readonly completedCount: number | undefined;
+    readonly foundCount: number | undefined;
+    readonly results: SmartEnrichmentResource[];
+    constructor(jobId: string, status: SmartEnrichmentStatus, itemCount: number | undefined, completedCount: number | undefined, foundCount: number | undefined, results: SmartEnrichmentResource[]);
+    static fromArray(data: Record<string, unknown>): SmartEnrichmentJob;
+    isProcessing(): boolean;
+    /** Convenience for single lookups: the first (or only) result, if any. */
+    result(): SmartEnrichmentResource | undefined;
+    private static looksLikeItem;
+}
+
+/**
+ * Full first input of a history row (incl. street + postalCode) — everything that was
+ * queried, so a detail view needs no second fetch. `query` stays the compact summary.
+ */
+interface SmartEnrichmentHistoryInput {
+    companyName: string | undefined;
+    street: string | undefined;
+    postalCode: string | undefined;
+    city: string | undefined;
+    country: string | undefined;
+}
+/**
+ * One row of Smart Enrichment lookup history (compact summary; full detail via getJob).
+ */
+declare class SmartEnrichmentHistoryRow {
+    readonly jobId: string;
+    readonly status: SmartEnrichmentStatus;
+    readonly isBulk: boolean;
+    readonly itemCount: number;
+    readonly foundCount: number;
+    readonly queryCompanyName: string | undefined;
+    readonly queryCountry: string | undefined;
+    readonly queryCity: string | undefined;
+    readonly input: SmartEnrichmentHistoryInput | undefined;
+    readonly result: SmartEnrichmentResource | undefined;
+    readonly createdAt: string | undefined;
+    readonly finishedAt: string | undefined;
+    constructor(jobId: string, status: SmartEnrichmentStatus, isBulk: boolean, itemCount: number, foundCount: number, queryCompanyName: string | undefined, queryCountry: string | undefined, queryCity: string | undefined, input: SmartEnrichmentHistoryInput | undefined, result: SmartEnrichmentResource | undefined, createdAt: string | undefined, finishedAt: string | undefined);
+    static fromArray(data: Record<string, unknown>): SmartEnrichmentHistoryRow;
+}
+
+/**
+ * Account-wide history tiles — stable regardless of the current search/page filter.
+ */
+interface SmartEnrichmentHistoryStats {
+    total: number;
+    found: number;
+}
+/**
+ * A paginated page of Smart Enrichment lookup history.
+ */
+declare class SmartEnrichmentHistoryPage implements Iterable<SmartEnrichmentHistoryRow> {
+    readonly rows: SmartEnrichmentHistoryRow[];
+    readonly currentPage: number;
+    readonly perPage: number;
+    readonly total: number;
+    readonly lastPage: number;
+    readonly stats?: SmartEnrichmentHistoryStats | undefined;
+    constructor(rows: SmartEnrichmentHistoryRow[], currentPage: number, perPage: number, total: number, lastPage: number, stats?: SmartEnrichmentHistoryStats | undefined);
+    static fromResponse(payload: unknown): SmartEnrichmentHistoryPage;
+    [Symbol.iterator](): Iterator<SmartEnrichmentHistoryRow>;
+    get length(): number;
+}
+
+/**
+ * DTOs for the Smart Enrichment statistics endpoint
+ * (GET /smart-enrichment/statistics).
+ *
+ * Read-only aggregation over the company's lookups: headline totals, a time
+ * series and breakdowns by source, outcome and confidence band. The API
+ * defaults to the last 12 months and a monthly interval.
+ */
+/** Time-series bucket size accepted by the statistics endpoint. */
+type SmartEnrichmentStatisticsInterval = 'day' | 'week' | 'month';
+interface SmartEnrichmentStatisticsRange {
+    dateFrom: string;
+    dateTo: string;
+    interval: string;
+}
+interface SmartEnrichmentStatisticsTotals {
+    jobs: number;
+    items: number;
+    found: number;
+    /** Share of items that resolved to a VAT number, 0–100. */
+    foundRate: number;
+    /** Average confidence of found items, 0–100. */
+    avgConfidence: number;
+}
+interface SmartEnrichmentTimeBucket {
+    /** Period key: "2026-01-15" (day), "2026-03" (ISO year-week) or "2026-01" (month). */
+    bucket: string;
+    jobs: number;
+    items: number;
+    found: number;
+}
+interface SmartEnrichmentSourceBreakdown {
+    source: string;
+    jobs: number;
+    found: number;
+}
+interface SmartEnrichmentOutcomeBreakdown {
+    outcome: string;
+    count: number;
+}
+interface SmartEnrichmentConfidenceBucket {
+    /** Confidence band: "high", "medium" or "low". */
+    bucket: string;
+    count: number;
+}
+declare class SmartEnrichmentStatistics {
+    readonly range: SmartEnrichmentStatisticsRange;
+    readonly totals: SmartEnrichmentStatisticsTotals;
+    readonly timeSeries: SmartEnrichmentTimeBucket[];
+    readonly bySource: SmartEnrichmentSourceBreakdown[];
+    readonly byOutcome: SmartEnrichmentOutcomeBreakdown[];
+    readonly confidenceBuckets: SmartEnrichmentConfidenceBucket[];
+    constructor(range: SmartEnrichmentStatisticsRange, totals: SmartEnrichmentStatisticsTotals, timeSeries: SmartEnrichmentTimeBucket[], bySource: SmartEnrichmentSourceBreakdown[], byOutcome: SmartEnrichmentOutcomeBreakdown[], confidenceBuckets: SmartEnrichmentConfidenceBucket[]);
+    static fromArray(data: Record<string, unknown>): SmartEnrichmentStatistics;
+}
+
+interface SmartEnrichmentInput {
+    companyName: string;
+    country: string;
+    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 {
+    /** Billing period, e.g. "2026-05". */
+    period: string;
+    matches: number;
+    /** Amount due for the period as a decimal string, e.g. "9.60". */
+    amount: string;
+    state: 'billed' | 'pending';
+    billingType: string | null;
+    manualReference: string | null;
+}
+interface SmartEnrichmentUsage {
+    period: string;
+    used: number;
+    included: number;
+    remaining: number;
+    overageCount: number;
+    overagePrice: number;
+    overageAmount: number;
+    hardCap: number | null;
+    /** Recent monthly billing entries; empty when the API sends none. */
+    history: SmartEnrichmentUsageHistoryEntry[];
+}
+interface SmartEnrichmentExportOptions {
+    /** Inclusive lower bound on the job's creation date (YYYY-MM-DD). */
+    dateFrom?: string;
+    /** Inclusive upper bound on the job's creation date (YYYY-MM-DD). */
+    dateTo?: string;
+    /** Only include rows with at least this result confidence (0–100). */
+    minConfidence?: number;
+    /** Only include rows with one of these item statuses (found, no_vat_exists, not_found). */
+    status?: SmartEnrichmentStatus[];
+    /** Only include rows that resolved to a VAT number. */
+    onlyFound?: boolean;
+}
+interface SmartEnrichmentStatisticsOptions {
+    /** Inclusive lower bound (YYYY-MM-DD). Defaults to 12 months ago (server-side). */
+    dateFrom?: string;
+    /** Inclusive upper bound (YYYY-MM-DD). Defaults to today (server-side). */
+    dateTo?: string;
+    /** Time-series bucket size. Defaults to "month" server-side. */
+    interval?: SmartEnrichmentStatisticsInterval;
+}
+interface SmartEnrichmentWaitOptions {
+    /** Delay between polls in milliseconds. Defaults to 2000. */
+    pollIntervalMs?: number;
+    /** Maximum total time to wait in milliseconds. Defaults to 120000. */
+    timeoutMs?: number;
+}
+/**
+ * Smart Enrichment — reverse VAT lookup (company name + address + country → VAT + confidence).
+ *
+ *   let job = await client.smartEnrichment.lookup({ companyName: 'Example GmbH', country: 'AT' });
+ *   if (job.isProcessing()) job = await client.smartEnrichment.waitForCompletion(job.jobId);
+ *   console.log(job.result()?.vatNumber);
+ */
+declare class SmartEnrichmentEndpoint {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tokenStorage;
+    private readonly httpClient;
+    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
+     * is needed.
+     */
+    lookup(input: SmartEnrichmentInput): Promise<SmartEnrichmentJob>;
+    /**
+     * 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[], mode?: SmartEnrichmentMode): Promise<SmartEnrichmentJob>;
+    /** Poll a job (single or bulk) by its id. */
+    get(jobId: string): Promise<SmartEnrichmentJob>;
+    /**
+     * Poll get(jobId) until the job is no longer processing (completed, failed or resolved).
+     * Throws a TaxoraException when the job does not finish within `timeoutMs`.
+     */
+    waitForCompletion(jobId: string, options?: SmartEnrichmentWaitOptions): Promise<SmartEnrichmentJob>;
+    /**
+     * Paginated lookup history (newest first). `perPage` is capped at 100 server-side.
+     * `search` filters (free-text) over the queried company name and the resolved
+     * VAT number / matched company name.
+     */
+    history(page?: number, perPage?: number, search?: string): Promise<SmartEnrichmentHistoryPage>;
+    /** Current billing-period quota usage, plus recent monthly billing entries. */
+    usage(): Promise<SmartEnrichmentUsage>;
+    /**
+     * Export the company's lookups as CSV (bulk-input shape plus the resolved VAT columns;
+     * bulk jobs are flattened to one line per input row). Returns the raw CSV text
+     * (UTF-8, BOM included by the API so Excel opens umlauts correctly).
+     */
+    export(options?: SmartEnrichmentExportOptions): Promise<string>;
+    /**
+     * Aggregated lookup statistics: headline totals, a time series and breakdowns by
+     * source, outcome and confidence band. The API defaults to the last 12 months
+     * and a monthly interval.
+     */
+    statistics(options?: SmartEnrichmentStatisticsOptions): Promise<SmartEnrichmentStatistics>;
+    private validateInput;
+    private validateJobId;
+    private buildHeaders;
+    private sendRequest;
+    private parseJsonResponse;
+    /**
+     * Like parseJsonResponse but returns the whole object WITHOUT unwrapping `data` — used for
+     * the paginated history response (where `data` is the row array and `meta`/`stats` must be
+     * preserved) and the statistics response.
+     */
+    private parseRawJson;
+    /**
+     * For the CSV export: keeps the shared 422/HTTP error mapping but returns the body
+     * verbatim (text/csv) instead of parsing JSON.
+     */
+    private parseCsvResponse;
+    private parseValidationErrors;
+    private parseUsageHistory;
+}
+
 declare const VatState: {
     readonly VALID: "valid";
     readonly INVALID: "invalid";
@@ -241,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>;
@@ -273,11 +1321,15 @@ 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;
     readonly vat: VatEndpoint;
     readonly company: CompanyEndpoint;
+    readonly smartEnrichment: SmartEnrichmentEndpoint;
+    readonly eReporting: EReportingEndpoint;
     readonly baseUrl: string;
     constructor(options: TaxoraClientOptions);
 }
@@ -304,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 {
@@ -316,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;
@@ -342,4 +1420,4 @@ declare class AuthRetryHttpClient implements HttpClientInterface {
     private injectAuthHeader;
 }
 
-export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, CompanyAddress, CompanyEndpoint, type CompanyResource, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, InMemoryTokenStorage, Language, LoginIdentifier, ProviderDocument, ProviderDocumentLine, ScoreBreakdown, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, Token, type TokenStorageInterface, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, VatResource, VatState, VatValidationAddressInput, describeVatState, getBaseUrl, getFailedVatStates };
+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 };