@taxora/sdk 1.1.0 → 1.3.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>;
 }
 
@@ -89,8 +160,24 @@ declare function toComplianceEnrollmentStatus(value: unknown): ComplianceEnrollm
 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).
+ * The compliance service an enrollment books for its country: French DGFiP
+ * e-reporting, or e-invoicing (e.g. Norway EHF / Peppol BIS 3.0). Each country
+ * and service is unlocked and billed separately.
+ */
+declare const ComplianceService: {
+    readonly E_REPORTING: "e_reporting";
+    readonly E_INVOICING: "e_invoicing";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceService = (typeof ComplianceService)[keyof typeof ComplianceService];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceService(value: unknown): ComplianceService;
+declare function describeComplianceService(service: ComplianceService): string;
+
+/**
+ * A compliance enrollment — the merchant's provisioned account for one country
+ * and service (GET/POST /compliance/enrollments), e.g. France e-reporting
+ * (regime "dgfip_flux10") or Norway e-invoicing (regime "peppol_bis3").
  */
 declare class ComplianceEnrollment {
     readonly id: number;
@@ -112,9 +199,13 @@ declare class ComplianceEnrollment {
     readonly autoSend: boolean;
     readonly createdAt: string | null;
     readonly updatedAt: string | null;
+    /** Booked service ("e_reporting" / "e_invoicing"); `unknown` when an older server omits it. */
+    readonly service: ComplianceService;
     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);
+    reportingStartDate: string | null, notificationEmail: string | null, autoSend: boolean, createdAt: string | null, updatedAt: string | null, 
+    /** Booked service ("e_reporting" / "e_invoicing"); `unknown` when an older server omits it. */
+    service?: ComplianceService);
     static fromArray(data: Record<string, unknown>): ComplianceEnrollment;
 }
 
@@ -193,6 +284,17 @@ declare class ComplianceTaxReportPage implements Iterable<ComplianceTaxReport> {
     get length(): number;
 }
 
+/** Kind of document a compliance transaction represents. */
+declare const ComplianceDocumentType: {
+    readonly INVOICE: "invoice";
+    readonly CREDIT_NOTE: "credit_note";
+    readonly UNKNOWN: "unknown";
+};
+type ComplianceDocumentType = (typeof ComplianceDocumentType)[keyof typeof ComplianceDocumentType];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toComplianceDocumentType(value: unknown): ComplianceDocumentType;
+declare function describeComplianceDocumentType(type: ComplianceDocumentType): string;
+
 declare const ComplianceTransactionState: {
     readonly PENDING: "pending";
     readonly SENDING: "sending";
@@ -218,8 +320,30 @@ type ComplianceTransactionType = (typeof ComplianceTransactionType)[keyof typeof
 declare function toComplianceTransactionType(value: unknown): ComplianceTransactionType;
 declare function describeComplianceTransactionType(type: ComplianceTransactionType): string;
 
+/** One tax of a stored invoice line (provider shape, as recorded at creation/update). */
+interface ComplianceTransactionInvoiceLineTax {
+    name: string;
+    percent: number | null;
+    category: string | null;
+    /** VATEX exemption code for category "E". */
+    comment: string | null;
+}
+/** One stored invoice line (`provider_payload.invoice.invoice_lines_attributes`). */
+interface ComplianceTransactionInvoiceLine {
+    description: string;
+    quantity: number | null;
+    /** Unit price as a precision-safe decimal string. */
+    price: string;
+    /** UN/ECE unit code, e.g. 9 (each). */
+    unit: number | null;
+    taxes: ComplianceTransactionInvoiceLineTax[];
+}
 /**
- * A recorded e-reporting transaction (GET/POST /compliance/transactions).
+ * A recorded compliance transaction (GET/POST /compliance/transactions) — an
+ * e-reported transaction (France) or an e-invoice / credit note (Norway).
+ *
+ * The e-invoicing fields at the end of the constructor are optional so DTOs
+ * built from older servers (or by hand) stay valid.
  */
 declare class ComplianceTransaction {
     readonly id: number;
@@ -251,11 +375,49 @@ declare class ComplianceTransaction {
     readonly taxReport: ComplianceTaxReport | undefined;
     readonly createdAt: string | null;
     readonly updatedAt: string | null;
+    /** Buyer's company register id (Norway: 9-digit organisation number). */
+    readonly counterpartyRegisterId: string | null;
+    readonly counterpartyAddress: string | null;
+    readonly counterpartyCity: string | null;
+    readonly counterpartyPostalcode: string | null;
+    readonly counterpartyEmail: string | null;
+    readonly buyerReference: string | null;
+    /** "invoice" or "credit_note" (older servers without the field → "invoice"). */
+    readonly documentType: ComplianceDocumentType;
+    /** Number of the invoice a credit note corrects. */
+    readonly amendedNumber: string | null;
+    /** Date of the invoice a credit note corrects (YYYY-MM-DD). */
+    readonly amendedDate: string | null;
+    /**
+     * Latest provider-side delivery state (e.g. "sent", "accepted", "refused",
+     * "paid") — richer than `state` for e-invoicing, where delivery continues
+     * after submission. Free-form string; null until the provider reports one.
+     */
+    readonly providerState: string | null;
+    /** The stored invoice lines (empty when the server does not include them). */
+    readonly invoiceLines: ComplianceTransactionInvoiceLine[];
     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);
+    taxReport: ComplianceTaxReport | undefined, createdAt: string | null, updatedAt: string | null, 
+    /** Buyer's company register id (Norway: 9-digit organisation number). */
+    counterpartyRegisterId?: string | null, counterpartyAddress?: string | null, counterpartyCity?: string | null, counterpartyPostalcode?: string | null, counterpartyEmail?: string | null, buyerReference?: string | null, 
+    /** "invoice" or "credit_note" (older servers without the field → "invoice"). */
+    documentType?: ComplianceDocumentType, 
+    /** Number of the invoice a credit note corrects. */
+    amendedNumber?: string | null, 
+    /** Date of the invoice a credit note corrects (YYYY-MM-DD). */
+    amendedDate?: string | null, 
+    /**
+     * Latest provider-side delivery state (e.g. "sent", "accepted", "refused",
+     * "paid") — richer than `state` for e-invoicing, where delivery continues
+     * after submission. Free-form string; null until the provider reports one.
+     */
+    providerState?: string | null, 
+    /** The stored invoice lines (empty when the server does not include them). */
+    invoiceLines?: ComplianceTransactionInvoiceLine[]);
+    get isCreditNote(): boolean;
     static fromArray(data: Record<string, unknown>): ComplianceTransaction;
 }
 
@@ -294,6 +456,93 @@ declare class ImportResult {
     static fromArray(data: Record<string, unknown>): ImportResult;
 }
 
+/**
+ * Outcome of a Peppol directory lookup (GET /compliance/peppol-lookup). The
+ * directory resolves asynchronously — `pending` means ask again in a few seconds.
+ */
+declare const PeppolLookupStatus: {
+    readonly REACHABLE: "reachable";
+    readonly NOT_REACHABLE: "not_reachable";
+    readonly PENDING: "pending";
+    readonly UNKNOWN: "unknown";
+};
+type PeppolLookupStatus = (typeof PeppolLookupStatus)[keyof typeof PeppolLookupStatus];
+/** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
+declare function toPeppolLookupStatus(value: unknown): PeppolLookupStatus;
+declare function describePeppolLookupStatus(status: PeppolLookupStatus): string;
+
+/**
+ * Whether a participant can receive e-invoices over Peppol
+ * (GET /compliance/peppol-lookup). For Norway, `reachable === true` means the
+ * buyer is registered in ELMA and must receive an EHF e-invoice.
+ */
+declare class PeppolLookupResult {
+    readonly status: PeppolLookupStatus;
+    /** null while the lookup is still `pending`. */
+    readonly reachable: boolean | null;
+    readonly country: string;
+    /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
+    readonly scheme: string;
+    /** Participant identifier, e.g. the organisation number. */
+    readonly id: string;
+    /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
+    readonly documentTypes: string[];
+    readonly transportTypeCode: string | null;
+    readonly checkedAt: string | null;
+    constructor(status: PeppolLookupStatus, 
+    /** null while the lookup is still `pending`. */
+    reachable: boolean | null, country: string, 
+    /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
+    scheme: string, 
+    /** Participant identifier, e.g. the organisation number. */
+    id: string, 
+    /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
+    documentTypes: string[], transportTypeCode: string | null, checkedAt: string | null);
+    /** True while the directory is still resolving — ask again in a few seconds. */
+    get isPending(): boolean;
+    static fromArray(data: Record<string, unknown>): PeppolLookupResult;
+}
+
+/**
+ * A company from a national company register (GET /compliance/registry-lookup) —
+ * for Norway the Brønnøysund Enhetsregisteret. Maps onto the Norway enrollment
+ * input and the buyer fields of a Norwegian e-invoice.
+ */
+declare class RegistryCompany {
+    /** 9-digit Norwegian organisation number. */
+    readonly orgNumber: string;
+    readonly companyName: string;
+    /** Legal form, e.g. "AS" or "ASA". */
+    readonly organisationForm: string | null;
+    /** Registered for VAT (Merverdiavgiftsregisteret). */
+    readonly vatRegistered: boolean;
+    /** "NO…MVA" VAT number; null when not VAT-registered. */
+    readonly vatNumber: string | null;
+    /** Registered in Foretaksregisteret (adds "Foretaksregisteret" to invoices). */
+    readonly enterpriseRegister: boolean;
+    readonly bankrupt: boolean;
+    readonly underLiquidation: boolean;
+    readonly address: string | null;
+    readonly postalcode: string | null;
+    readonly city: string | null;
+    /** 2-char ISO 3166-1 alpha-2 code, e.g. "NO". */
+    readonly country: string;
+    constructor(
+    /** 9-digit Norwegian organisation number. */
+    orgNumber: string, companyName: string, 
+    /** Legal form, e.g. "AS" or "ASA". */
+    organisationForm: string | null, 
+    /** Registered for VAT (Merverdiavgiftsregisteret). */
+    vatRegistered: boolean, 
+    /** "NO…MVA" VAT number; null when not VAT-registered. */
+    vatNumber: string | null, 
+    /** Registered in Foretaksregisteret (adds "Foretaksregisteret" to invoices). */
+    enterpriseRegister: boolean, bankrupt: boolean, underLiquidation: boolean, address: string | null, postalcode: string | null, city: string | null, 
+    /** 2-char ISO 3166-1 alpha-2 code, e.g. "NO". */
+    country: string);
+    static fromArray(data: Record<string, unknown>): RegistryCompany;
+}
+
 /**
  * DTOs for the e-reporting revenue statistics endpoint
  * (GET /compliance/revenue-statistics).
@@ -410,6 +659,8 @@ type EReportingInterval = 'day' | 'week' | 'month';
 type ComplianceEnterpriseSize = 'micro' | 'pme' | 'eti' | 'ge';
 /** Type of operations the enrolled company performs. */
 type ComplianceTypeOperation = 'services' | 'goods' | 'mixed';
+/** Services accepted on the request side (the tolerant `unknown` is response-only). */
+type ComplianceRequestService = Exclude<ComplianceService, 'unknown'>;
 /** 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). */
@@ -424,9 +675,15 @@ interface RevenueStatisticsFilters {
     transactionType?: ComplianceTransactionRequestType;
     state?: ComplianceTransactionRequestState;
 }
+/**
+ * France (DGFiP e-reporting) enrollment — the original createEnrollment() input.
+ * For Norway use {@link CreateNorwayEnrollmentInput} (or createNorwayEnrollment()).
+ */
 interface CreateComplianceEnrollmentInput {
-    /** Reporting country (2-char ISO 3166-1 alpha-2). Defaults server-side (FR). */
+    /** Reporting country (2-char ISO 3166-1 alpha-2). Defaults server-side (FR). "NO" selects the Norway input. */
     country?: string;
+    /** Service to book. Defaults server-side to the country's default service (FR: "e_reporting"). */
+    service?: ComplianceRequestService;
     /** Compliance regime, e.g. "dgfip_flux10". Defaults server-side. */
     regime?: string;
     /** 14-digit SIRET. Required unless `siren` is set. */
@@ -450,6 +707,45 @@ interface CreateComplianceEnrollmentInput {
     /** When false, only the provider account is created — the DGFiP regime is NOT activated. Defaults to true server-side. */
     autoActivate?: boolean;
 }
+/**
+ * Norway e-invoicing (EHF / Peppol BIS 3.0) enrollment: registers the company
+ * as a Peppol participant so it can send (and optionally receive) e-invoices.
+ * Prefill it from registryLookup('NO', …).
+ */
+interface CreateNorwayEnrollmentInput {
+    country: 'NO';
+    /** Service to book. Defaults server-side to "e_invoicing" (the only service for NO). */
+    service?: ComplianceRequestService;
+    /** Compliance regime. Defaults server-side ("peppol_bis3"). */
+    regime?: string;
+    /**
+     * 9-digit Norwegian organisation number (mod-11 check digit). Spaces, a "NO"
+     * prefix and an "MVA" suffix are accepted and stripped before sending.
+     */
+    orgNumber: string;
+    companyName: string;
+    address: string;
+    city: string;
+    postalcode: string;
+    /** Notification email for the provider account. */
+    email: string;
+    vatNumber?: string;
+    province?: string;
+    /** Registered in Merverdiavgiftsregisteret (adds "MVA" to invoices). Defaults to true server-side. */
+    vatRegistered?: boolean;
+    /** Registered in Foretaksregisteret (adds "Foretaksregisteret" to invoices). Defaults to false server-side. */
+    enterpriseRegister?: boolean;
+    /** Also register to RECEIVE e-invoices over Peppol. Defaults to false server-side. */
+    reception?: boolean;
+    /** Country of the legal entity when it differs from NO (2-char ISO 3166-1 alpha-2). */
+    legalCountry?: string;
+    /** Optional first date transactions are recorded for (Date or strict YYYY-MM-DD). */
+    reportingStartDate?: Date | string;
+    /** When false, only the provider account is created — the Peppol registration is NOT activated. Defaults to true server-side. */
+    autoActivate?: boolean;
+}
+/** createNorwayEnrollment() input — the Norway input without the fixed `country`. */
+type NorwayEnrollmentInput = Omit<CreateNorwayEnrollmentInput, 'country'>;
 interface ComplianceInvoiceTaxInput {
     /** Tax designation, e.g. "TVA". */
     name: string;
@@ -469,7 +765,34 @@ interface ComplianceInvoiceLineInput {
     /** At least one tax per line. */
     taxes: ComplianceInvoiceTaxInput[];
 }
-interface CreateComplianceTransactionInput {
+/**
+ * Buyer and document fields interpreted per country. For Norway (EHF / Peppol)
+ * `counterpartyRegisterId` (the buyer's organisation number) and
+ * `counterpartyName` are required unless `providerContactId` is set, the
+ * transaction type must be "b2b_domestic_outbound", and a credit note needs
+ * `amendedNumber`. The SDK does not know the enrollment's country — those rules
+ * are enforced server-side (422).
+ */
+interface ComplianceTransactionBuyerInput {
+    /** Buyer's company register id (Norway: 9-digit organisation number; "NO…MVA" is accepted). Max 30 chars. */
+    counterpartyRegisterId?: string;
+    counterpartyAddress?: string;
+    counterpartyCity?: string;
+    counterpartyPostalcode?: string;
+    /** Buyer's email address. */
+    counterpartyEmail?: string;
+    /** Buyer reference (Peppol BuyerReference); max 100 chars. Norway defaults it to the buyer's org number. */
+    buyerReference?: string;
+    /** Issue the document as a credit note. */
+    isCreditNote?: boolean;
+    /** Number of the invoice a credit note corrects (max 50 chars). */
+    amendedNumber?: string;
+    /** Date of the invoice a credit note corrects (Date or strict YYYY-MM-DD). */
+    amendedDate?: Date | string;
+    /** Free-text note printed on the invoice (max 1000 chars). */
+    extraInfo?: string;
+}
+interface CreateComplianceTransactionInput extends ComplianceTransactionBuyerInput {
     complianceEnrollmentId: number;
     transactionType: ComplianceTransactionRequestType;
     invoiceNumber: string;
@@ -496,7 +819,7 @@ interface CreateComplianceTransactionInput {
     /** When false, the transaction is only recorded — submission is deferred. Defaults to true server-side. */
     submitNow?: boolean;
 }
-interface UpdateComplianceTransactionInput {
+interface UpdateComplianceTransactionInput extends ComplianceTransactionBuyerInput {
     transactionType?: ComplianceTransactionRequestType;
     invoiceNumber?: string;
     invoiceDate?: Date | string;
@@ -525,6 +848,10 @@ interface ComplianceTransactionFilters {
     dateTo?: Date | string;
     state?: ComplianceTransactionRequestState;
     transactionType?: ComplianceTransactionRequestType;
+    /** Only transactions of this enrollment. */
+    complianceEnrollmentId?: number;
+    /** Only transactions of this country (2-char ISO 3166-1 alpha-2). */
+    country?: string;
     page?: number;
     /** Page size (1-100, default 25 server-side). */
     perPage?: number;
@@ -537,33 +864,57 @@ interface EReportingAccessRequestInput {
     message?: string;
     /** Locale for the confirmation mail, e.g. "de" or "en". */
     language?: string;
+    /** The service being requested. Defaults server-side to "e_reporting". */
+    service?: ComplianceRequestService;
+    /** The countries the service is requested for (2-char ISO codes), e.g. ["NO"]. */
+    countries?: string[];
 }
 /**
- * E-Reporting / Compliance (DGFiP Flux 10) endpoints.
+ * E-Reporting / Compliance endpoints (per-country services).
  *
- * 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.
+ * - France — e-reporting (DGFiP Flux 10): sireneLookup() to prefill company
+ *   data, createEnrollment() to provision the provider account, then
+ *   createTransaction() / importTransactions() to record invoices and
+ *   listTaxReports() to track their DGFiP lifecycle.
+ * - Norway — e-invoicing (EHF / Peppol BIS 3.0): registryLookup('NO', …) to
+ *   prefill company/buyer data, createNorwayEnrollment() to register as a Peppol
+ *   participant, peppolLookup('NO', …) to check a buyer is reachable, then
+ *   createTransaction() to send invoices and credit notes.
  *
- * All routes except requestEReportingAccess() require an active E-Reporting
- * subscription / feature grant on the account.
+ * Each country/service is unlocked (and billed) separately; enrolling for a
+ * service the company does not have yields a 403 with code `service_not_active`.
+ * All routes except requestEReportingAccess() require compliance access on the
+ * account.
  */
 declare class EReportingEndpoint {
     private readonly baseUrl;
     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`
+     * default the country regime is activated right away (France: DGFiP tax
+     * report setting; Norway: Peppol registration); 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
+     * The input shape depends on `country`: omitted/"FR" takes the France input
+     * (unchanged, backwards compatible), "NO" the Norway input — see also the
+     * createNorwayEnrollment() shortcut.
+     *
+     * Errors: 403 (HttpException, body code `service_not_active`) when the company
+     * lacks the requested service; on provider failure 502 (HttpException) — the
+     * enrollment is then persisted in `error_account`/`error_activation` state so
      * provisioning can be retried.
      */
-    createEnrollment(input: CreateComplianceEnrollmentInput): Promise<ComplianceEnrollment>;
+    createEnrollment(input: CreateComplianceEnrollmentInput | CreateNorwayEnrollmentInput): Promise<ComplianceEnrollment>;
+    /**
+     * Enroll the company for Norway e-invoicing (EHF / Peppol BIS 3.0) — shortcut
+     * for createEnrollment({ country: 'NO', ... }). The organisation number is
+     * checked (mod-11) and normalized to 9 digits before sending.
+     */
+    createNorwayEnrollment(input: NorwayEnrollmentInput): 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. */
@@ -576,6 +927,31 @@ declare class EReportingEndpoint {
      * government API); exceeding it yields a 429 (mapped to an HttpException).
      */
     sireneLookup(q: string): Promise<SireneLookupResult>;
+    /**
+     * Look up companies in a national company register — currently Norway
+     * (Brønnøysund Enhetsregisteret). `q` is an organisation number, a "NO…MVA"
+     * VAT number or a company name; an exact number match yields one result.
+     * Ideal for prefilling createNorwayEnrollment() and the buyer fields of an
+     * e-invoice. For France use sireneLookup().
+     *
+     * Errors: 404 (HttpException) when nothing is found, 422 (ValidationException)
+     * on invalid input / unsupported country, 429 (HttpException) when the
+     * per-user rate limit (30/min) is exceeded.
+     */
+    registryLookup(country: string, q: string): Promise<RegistryCompany[]>;
+    /**
+     * Check whether a participant (typically the buyer) can receive e-invoices
+     * over Peppol. For Norway pass the organisation number (scheme defaults to
+     * "0192"): `reachable === true` means the buyer is registered in ELMA and must
+     * receive an EHF e-invoice. The directory resolves asynchronously —
+     * `status === 'pending'` (`reachable === null`) means ask again in a few
+     * seconds. Free of charge; definite answers are cached for 24h server-side.
+     *
+     * A Norwegian organisation number is checked (mod-11) and normalized before
+     * sending. Errors: 422 (ValidationException) on invalid input, 502
+     * (HttpException) on provider failure.
+     */
+    peppolLookup(country: string, id: string, scheme?: string): Promise<PeppolLookupResult>;
     /**
      * Record and (by default) submit a Flux 10 transaction. Pass `submitNow: false`
      * to only record it — submission can be triggered later via submitTransaction().
@@ -591,7 +967,7 @@ declare class EReportingEndpoint {
      * 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. */
+    /** Paginated list of the company's transactions (newest invoice date first), filterable by date / state / type / enrollment / country. */
     listTransactions(filters?: ComplianceTransactionFilters): Promise<ComplianceTransactionPage>;
     /** Get a single transaction by id (includes its tax report when one exists). */
     getTransaction(id: number): Promise<ComplianceTransaction>;
@@ -648,11 +1024,25 @@ declare class EReportingEndpoint {
      */
     requestEReportingAccess(input?: EReportingAccessRequestInput): Promise<void>;
     private validateEnrollmentInput;
+    private isNorwayEnrollmentInput;
+    /** Validates the Norway input and builds its wire body (org number normalized to 9 digits). */
+    private buildNorwayEnrollmentBody;
+    private createEnrollmentFromBody;
+    private validateService;
+    private validateEmail;
+    /** Lookup routes take a 2-letter country; the API expects it upper-case. */
+    private normalizeLookupCountry;
     private validateId;
     private validateTransactionType;
     private validateInvoiceNumber;
     private validateInvoiceLines;
     private validateOptionalCodes;
+    /**
+     * Format checks for the buyer/document fields. Country rules (e.g. the Norway
+     * org number being required) depend on the enrollment and stay server-side;
+     * a register id is only check-digit validated when the buyer is Norwegian.
+     */
+    private validateBuyerFields;
     private buildInvoiceLines;
     /** Applies the optional scalar fields shared by create and update. */
     private applyOptionalTransactionFields;
@@ -678,6 +1068,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 +1107,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 +1149,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 +1309,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 +1376,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 +1387,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 +1607,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 +1639,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;
@@ -1191,11 +1661,170 @@ declare const ApiVersion: {
 };
 type ApiVersion = (typeof ApiVersion)[keyof typeof ApiVersion];
 
+/**
+ * Norwegian organisation number (organisasjonsnummer): 9 digits, the last one a
+ * modulus-11 check digit (weights 3,2,7,6,5,4,3,2). It is also the Peppol
+ * participant identifier under scheme 0192 and — with the "NO" prefix and "MVA"
+ * suffix — the Norwegian VAT number.
+ *
+ * Mirrors the backend's validation, so invalid numbers are rejected before a
+ * request is sent.
+ */
+declare const NorwegianOrgNumber: {
+    /** Peppol identifier scheme for Norwegian organisation numbers. */
+    readonly PEPPOL_SCHEME: "0192";
+    /**
+     * Strips whitespace, dots, dashes, a "0192:" Peppol scheme prefix, the "NO"
+     * prefix and the "MVA" suffix: "NO 923 609 016 MVA", "923609016MVA" and
+     * "923 609 016" all become "923609016". Does not validate.
+     */
+    readonly normalize: (value: string | null | undefined) => string;
+    /** True when the (normalized) value is 9 digits with a valid mod-11 check digit. */
+    readonly isValid: (value: string | null | undefined) => boolean;
+    /** "NO923609016MVA" — the Norwegian VAT number of an MVA-registered entity. Does not validate. */
+    readonly toVatNumber: (value: string) => string;
+};
+
 declare class TaxoraException extends Error {
     readonly context: Record<string, unknown>;
     constructor(message: string, context?: Record<string, unknown>);
 }
 
+/**
+ * Typed shapes of the JSON bodies Taxora POSTs to your webhook endpoint.
+ *
+ * Every event shares the same envelope ({@link WebhookEventEnvelope}); `event` narrows `data.object`:
+ *
+ * ```ts
+ * const event = constructWebhookEvent(rawBody, header, secret);
+ * if (event.event === 'vat.validated') {
+ *   event.data.object.vat_uid; // string
+ * }
+ * ```
+ */
+type WebhookEventType = 'vat.validated' | 'vat.state_changed' | 'compliance.ledger.state_changed' | 'compliance.transaction.state_changed' | 'enrichment.completed' | 'enrichment.updated' | 'webhook.test';
+interface WebhookEventEnvelope<TEvent extends string, TObject> {
+    /** Delivery UUID — identical to the `Taxora-Webhook-Id` header and stable across retries. Use it to dedupe. */
+    id: string;
+    event: TEvent;
+    /** Unix seconds when the event was created (not the delivery attempt — that is `t` in the signature). */
+    timestamp: number;
+    data: {
+        object: TObject;
+    };
+}
+interface VatWebhookObject {
+    id: number;
+    vat_uid: string;
+    /** A VatState value, e.g. `valid`, `invalid`. */
+    state: string;
+    company_name: string | null;
+    country_code: string | null;
+    checked_at: string | null;
+}
+interface ComplianceLedgerWebhookObject {
+    id: number;
+    state: string;
+    ledger_type: string | null;
+    ledger_date: string | null;
+}
+interface ComplianceTransactionWebhookObject {
+    id: number;
+    state: string;
+    provider_state: string | null;
+    country: string | null;
+    invoice_number: string | null;
+}
+/** Raw Smart Enrichment rows — wrap them with `SmartEnrichmentResource.fromArray()` for a typed DTO. */
+interface EnrichmentCompletedWebhookObject {
+    jobId: string;
+    status: string;
+    itemCount: number;
+    foundCount: number;
+    results: Record<string, unknown>[];
+}
+interface EnrichmentUpdatedWebhookObject {
+    jobId: string;
+    status: string;
+    itemCount: number;
+    foundCount: number;
+    /** Zero-based index of the row that changed, matching `results[rowIndex]` of enrichment.completed. */
+    rowIndex: number;
+    result: Record<string, unknown> | null;
+}
+interface TestWebhookObject {
+    message: string;
+}
+type VatValidatedEvent = WebhookEventEnvelope<'vat.validated', VatWebhookObject>;
+type VatStateChangedEvent = WebhookEventEnvelope<'vat.state_changed', VatWebhookObject>;
+type ComplianceLedgerStateChangedEvent = WebhookEventEnvelope<'compliance.ledger.state_changed', ComplianceLedgerWebhookObject>;
+type ComplianceTransactionStateChangedEvent = WebhookEventEnvelope<'compliance.transaction.state_changed', ComplianceTransactionWebhookObject>;
+type EnrichmentCompletedEvent = WebhookEventEnvelope<'enrichment.completed', EnrichmentCompletedWebhookObject>;
+type EnrichmentUpdatedEvent = WebhookEventEnvelope<'enrichment.updated', EnrichmentUpdatedWebhookObject>;
+type WebhookTestEvent = WebhookEventEnvelope<'webhook.test', TestWebhookObject>;
+/** Discriminated union of every event Taxora sends. Switch on `event` to narrow `data.object`. */
+type TaxoraWebhookEvent = VatValidatedEvent | VatStateChangedEvent | ComplianceLedgerStateChangedEvent | ComplianceTransactionStateChangedEvent | EnrichmentCompletedEvent | EnrichmentUpdatedEvent | WebhookTestEvent;
+
+/** Name of the HTTP header that carries the signature. Node lower-cases it: `req.headers['taxora-signature']`. */
+declare const WEBHOOK_SIGNATURE_HEADER = "Taxora-Signature";
+/** Name of the HTTP header that carries the delivery UUID (stable across retries). */
+declare const WEBHOOK_ID_HEADER = "Taxora-Webhook-Id";
+/** Default maximum age (seconds) of a signed request before it is rejected as a possible replay. */
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/** The exact bytes Taxora sent. Never pass a parsed-and-re-serialised object. */
+type WebhookRawBody = string | Uint8Array | ArrayBuffer;
+/** Header value as frameworks hand it over (Express/Node may give an array for repeated headers). */
+type WebhookSignatureHeaderInput = string | readonly string[] | null | undefined;
+interface WebhookVerifyOptions {
+    /**
+     * Maximum allowed difference between now and the signature timestamp, in seconds. Default 300.
+     * `0` disables the check — not recommended, it re-opens replay attacks.
+     */
+    tolerance?: number;
+    /** Current time in Unix seconds. Only meant for tests. */
+    now?: number;
+}
+type WebhookSignatureErrorReason = 'missing_secret' | 'missing_header' | 'malformed_header' | 'invalid_body' | 'timestamp_outside_tolerance' | 'no_matching_signature' | 'invalid_payload';
+declare class WebhookSignatureVerificationError extends TaxoraException {
+    readonly reason: WebhookSignatureErrorReason;
+    constructor(message: string, reason: WebhookSignatureErrorReason, context?: Record<string, unknown>);
+}
+interface ParsedWebhookSignatureHeader {
+    timestamp: number;
+    /** All `v1` signatures — two during a secret rotation on Taxora's side. */
+    signatures: string[];
+}
+/** Parses `t=<unix>,v1=<hex>[,v1=<hex>…]`. Unknown schemes are ignored for forward compatibility. */
+declare function parseWebhookSignatureHeader(header: WebhookSignatureHeaderInput): ParsedWebhookSignatureHeader;
+/** hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`)) — the value Taxora puts into `v1=`. */
+declare function computeWebhookSignature(rawBody: WebhookRawBody, timestamp: number, secret: string): string;
+/**
+ * Builds a valid `Taxora-Signature` header value for a payload — handy for unit-testing your webhook handler
+ * without calling Taxora.
+ */
+declare function generateWebhookSignatureHeader(rawBody: WebhookRawBody, secret: string | readonly string[], timestamp?: number): string;
+/**
+ * Verifies a Taxora webhook request. Returns `true` or throws {@link WebhookSignatureVerificationError}.
+ *
+ * - `rawBody` must be the unmodified request body (e.g. `express.raw()`, `await request.text()`).
+ * - `secret` may be a list — useful while you rotate the secret on your side.
+ * - The comparison is constant-time; the timestamp must be within `tolerance` seconds (default 300).
+ */
+declare function verifyWebhookSignature(rawBody: WebhookRawBody, header: WebhookSignatureHeaderInput, secret: string | readonly string[], options?: WebhookVerifyOptions): true;
+/**
+ * Verifies the signature and returns the parsed, typed event. Throws {@link WebhookSignatureVerificationError}
+ * on any problem — respond with HTTP 400 in that case.
+ *
+ * ```ts
+ * app.post('/taxora-webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const event = constructWebhookEvent(req.body, req.header('Taxora-Signature'), process.env.TAXORA_WEBHOOK_SECRET!);
+ *   if (event.event === 'vat.validated') { ... }
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+declare function constructWebhookEvent<T extends TaxoraWebhookEvent = TaxoraWebhookEvent>(rawBody: WebhookRawBody, header: WebhookSignatureHeaderInput, secret: string | readonly string[], options?: WebhookVerifyOptions): T;
+
 declare class AuthenticationException extends TaxoraException {
     readonly statusCode = 401;
     constructor(message: string, context?: Record<string, unknown>);
@@ -1204,9 +1833,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 +1853,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 +1897,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, ComplianceDocumentType, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoiceTaxInput, type ComplianceLedgerStateChangedEvent, type ComplianceLedgerWebhookObject, type ComplianceRequestService, ComplianceService, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionBuyerInput, type ComplianceTransactionFilters, type ComplianceTransactionInvoiceLine, type ComplianceTransactionInvoiceLineTax, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, type ComplianceTransactionStateChangedEvent, ComplianceTransactionType, type ComplianceTransactionWebhookObject, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type CreateNorwayEnrollmentInput, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, type EnrichmentCompletedEvent, type EnrichmentCompletedWebhookObject, type EnrichmentUpdatedEvent, type EnrichmentUpdatedWebhookObject, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, Language, LoginIdentifier, type NorwayEnrollmentInput, NorwegianOrgNumber, type ParsedWebhookSignatureHeader, PeppolLookupResult, PeppolLookupStatus, ProviderDocument, ProviderDocumentLine, RegistryCompany, 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, type TaxoraWebhookEvent, type TestWebhookObject, Token, type TokenStorageInterface, type UpdateComplianceTransactionInput, ValidationException, VatCertificateExport, VatCollection, VatEndpoint, type VatRate, VatRates, VatResource, VatState, type VatStateChangedEvent, type VatValidatedEvent, VatValidationAddressInput, type VatWebhookObject, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, type WebhookEventEnvelope, type WebhookEventType, type WebhookRawBody, type WebhookSignatureErrorReason, type WebhookSignatureHeaderInput, WebhookSignatureVerificationError, type WebhookTestEvent, type WebhookVerifyOptions, computeWebhookSignature, constructWebhookEvent, describeApiError, describeComplianceDocumentType, describeComplianceEnrollmentStatus, describeComplianceService, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describePeppolLookupStatus, describeSmartEnrichmentMode, describeSmartEnrichmentStatus, describeVatState, generateWebhookSignatureHeader, getBaseUrl, getFailedVatStates, parseWebhookSignatureHeader, toComplianceDocumentType, toComplianceEnrollmentStatus, toComplianceService, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toPeppolLookupStatus, toSmartEnrichmentMode, toSmartEnrichmentStatus, verifyWebhookSignature };