@taxora/sdk 1.8.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -110,6 +110,178 @@ declare class AuthEndpoint {
110
110
  private parseResponse;
111
111
  }
112
112
 
113
+ /** One month of the e-invoicing allowance (documents included, used, still free, what is due beyond it). */
114
+ declare class EInvoicingQuotaPeriod {
115
+ /** Billing period, YYYY-MM. */
116
+ readonly period: string;
117
+ readonly used: number;
118
+ readonly included: number;
119
+ readonly freeUsed: number;
120
+ readonly freeRemaining: number;
121
+ readonly billableUnits: number;
122
+ /** Net EUR due for documents beyond the allowance. */
123
+ readonly amount: string;
124
+ /** Agreed monthly base fee (net EUR) for this month, null when none. */
125
+ readonly monthlyFee: string | null;
126
+ /** Net EUR due for the month: base fee + documents beyond the allowance. */
127
+ readonly total: string;
128
+ /** open | included | pending_billing | billed */
129
+ readonly state: string;
130
+ /** Documents used per country code. */
131
+ readonly byCountry: Record<string, number>;
132
+ readonly billedAt: string | null;
133
+ /** Our invoice number once invoiced. */
134
+ readonly manualReference: string | null;
135
+ readonly monthlyFeeReference: string | null;
136
+ constructor(
137
+ /** Billing period, YYYY-MM. */
138
+ period: string, used: number, included: number, freeUsed: number, freeRemaining: number, billableUnits: number,
139
+ /** Net EUR due for documents beyond the allowance. */
140
+ amount: string,
141
+ /** Agreed monthly base fee (net EUR) for this month, null when none. */
142
+ monthlyFee: string | null,
143
+ /** Net EUR due for the month: base fee + documents beyond the allowance. */
144
+ total: string,
145
+ /** open | included | pending_billing | billed */
146
+ state: string,
147
+ /** Documents used per country code. */
148
+ byCountry: Record<string, number>, billedAt: string | null,
149
+ /** Our invoice number once invoiced. */
150
+ manualReference: string | null, monthlyFeeReference: string | null);
151
+ static fromArray(data: Record<string, unknown>): EInvoicingQuotaPeriod;
152
+ }
153
+ interface EInvoicingQuotaTier {
154
+ /** Cumulative documents per month up to which the price applies; null = no upper bound. */
155
+ upTo: number | null;
156
+ /** Net EUR per document. */
157
+ unitPrice: string;
158
+ }
159
+ /** The company's e-invoicing allowance: one pool over all e-invoicing countries. */
160
+ declare class EInvoicingQuota {
161
+ /** How documents beyond the allowance are paid: "subscription" (on the plan's invoice) or "invoice" (invoiced separately). */
162
+ readonly billing: string;
163
+ readonly plan: string | null;
164
+ readonly currency: string;
165
+ /** Documents included per month. */
166
+ readonly included: number;
167
+ readonly tiers: EInvoicingQuotaTier[];
168
+ readonly countries: string[];
169
+ /** Agreed monthly base fee (net EUR), null when none. */
170
+ readonly monthlyFee: string | null;
171
+ readonly current: EInvoicingQuotaPeriod;
172
+ /** Earlier months, newest first. */
173
+ readonly history: EInvoicingQuotaPeriod[];
174
+ constructor(
175
+ /** How documents beyond the allowance are paid: "subscription" (on the plan's invoice) or "invoice" (invoiced separately). */
176
+ billing: string, plan: string | null, currency: string,
177
+ /** Documents included per month. */
178
+ included: number, tiers: EInvoicingQuotaTier[], countries: string[],
179
+ /** Agreed monthly base fee (net EUR), null when none. */
180
+ monthlyFee: string | null, current: EInvoicingQuotaPeriod,
181
+ /** Earlier months, newest first. */
182
+ history: EInvoicingQuotaPeriod[]);
183
+ static fromArray(data: Record<string, unknown>): EInvoicingQuota;
184
+ }
185
+
186
+ /** One billable usage event of a summary (only included by billing.getUsageSummaries(period)). */
187
+ interface UsageEvent {
188
+ id: number;
189
+ usageSummaryId: number | null;
190
+ feature: string;
191
+ country: string | null;
192
+ regime: string | null;
193
+ billingPeriod: string;
194
+ /** What was billed, e.g. a compliance transaction. */
195
+ resourceType: string | null;
196
+ resourceId: number | null;
197
+ stripeUsageRecordId: string | null;
198
+ stripeReportedAt: string | null;
199
+ createdAt: string | null;
200
+ }
201
+ /**
202
+ * Billed usage of one feature (e.g. `ereporting_transaction`) in one billing
203
+ * period (YYYY-MM) — GET /billing/usage-summaries.
204
+ */
205
+ declare class UsageSummary {
206
+ readonly id: number;
207
+ readonly companyId: number;
208
+ readonly feature: string;
209
+ readonly country: string | null;
210
+ readonly regime: string | null;
211
+ /** Billing period, YYYY-MM. */
212
+ readonly billingPeriod: string;
213
+ readonly eventCount: number;
214
+ /** Precision-safe decimal string as returned by the API (e.g. "49.00"); null until priced. */
215
+ readonly billableAmount: string | null;
216
+ /** e.g. "open"; free-form so new states don't break parsing. */
217
+ readonly state: string | null;
218
+ readonly stateLabel: string | null;
219
+ readonly periodClosedAt: string | null;
220
+ readonly billingTriggeredAt: string | null;
221
+ readonly billedAt: string | null;
222
+ readonly stripeInvoiceId: string | null;
223
+ readonly stripeSubscriptionItemId: string | null;
224
+ readonly billingNotes: string | null;
225
+ /** The period's usage events — only filled by getUsageSummaries(period); empty in the list. */
226
+ readonly events: UsageEvent[];
227
+ readonly createdAt: string | null;
228
+ readonly updatedAt: string | null;
229
+ constructor(id: number, companyId: number, feature: string, country: string | null, regime: string | null,
230
+ /** Billing period, YYYY-MM. */
231
+ billingPeriod: string, eventCount: number,
232
+ /** Precision-safe decimal string as returned by the API (e.g. "49.00"); null until priced. */
233
+ billableAmount: string | null,
234
+ /** e.g. "open"; free-form so new states don't break parsing. */
235
+ state: string | null, stateLabel: string | null, periodClosedAt: string | null, billingTriggeredAt: string | null, billedAt: string | null, stripeInvoiceId: string | null, stripeSubscriptionItemId: string | null, billingNotes: string | null,
236
+ /** The period's usage events — only filled by getUsageSummaries(period); empty in the list. */
237
+ events: UsageEvent[], createdAt: string | null, updatedAt: string | null);
238
+ static fromArray(data: Record<string, unknown>): UsageSummary;
239
+ }
240
+ /** A paginated page of usage summaries (newest billing period first). */
241
+ declare class UsageSummaryPage implements Iterable<UsageSummary> {
242
+ readonly rows: UsageSummary[];
243
+ readonly currentPage: number;
244
+ readonly perPage: number;
245
+ readonly total: number;
246
+ readonly lastPage: number;
247
+ constructor(rows: UsageSummary[], currentPage: number, perPage: number, total: number, lastPage: number);
248
+ static fromResponse(payload: unknown): UsageSummaryPage;
249
+ [Symbol.iterator](): Iterator<UsageSummary>;
250
+ get length(): number;
251
+ }
252
+
253
+ /**
254
+ * Billing transparency: read-only usage summaries of the company's billable
255
+ * modules (E-Reporting / E-Invoicing, Smart Enrichment). Requires one of those
256
+ * modules on the account (403 otherwise). Every call is a GET, so transient
257
+ * gateway failures are retried (see RetryPolicy).
258
+ */
259
+ declare class BillingEndpoint {
260
+ private readonly baseUrl;
261
+ private readonly apiKey;
262
+ private readonly tokenStorage;
263
+ private readonly httpClient;
264
+ private readonly retryPolicy;
265
+ constructor(baseUrl: string, apiKey: string, tokenStorage: TokenStorageInterface, httpClient: HttpClientInterface, retryPolicy?: RetryPolicy);
266
+ /** Paginated usage summaries, newest billing period first. `perPage` is clamped to 1-100 server-side. */
267
+ listUsageSummaries(page?: number, perPage?: number): Promise<UsageSummaryPage>;
268
+ /**
269
+ * The usage summaries of one billing period (YYYY-MM), one per feature,
270
+ * each with its usage events. A period without usage yields a 404 (HttpException).
271
+ */
272
+ getUsageSummaries(period: string): Promise<UsageSummary[]>;
273
+ /**
274
+ * The e-invoicing allowance: documents included per month, used, still free and
275
+ * what is due for the documents beyond it — one pool over all e-invoicing
276
+ * countries, current month first, then up to `months - 1` earlier months (1-24).
277
+ * Resolves to null when the company has no e-invoicing.
278
+ */
279
+ getEInvoicingQuota(months?: number): Promise<EInvoicingQuota | null>;
280
+ private buildHeaders;
281
+ /** GET + envelope unwrap (`{success, data}` → data, which may be an object or an array). */
282
+ private getJson;
283
+ }
284
+
113
285
  interface CompanyResource {
114
286
  id?: number;
115
287
  uuid?: string;
@@ -144,6 +316,77 @@ declare class CompanyEndpoint {
144
316
  get(): Promise<CompanyResource>;
145
317
  }
146
318
 
319
+ /**
320
+ * What to do with an invoice to a buyer, derived from the Peppol directory
321
+ * (EReportingEndpoint.decideDelivery()).
322
+ */
323
+ declare const ComplianceDeliveryAction: {
324
+ /** The buyer can receive e-invoices: create the transaction, Taxora sends it. */
325
+ readonly EINVOICE: "einvoice";
326
+ /** The buyer is not on the network: send your regular invoice yourself (a transaction would end as not_required and is not billed). */
327
+ readonly REGULAR_INVOICE: "regular_invoice";
328
+ /** No definite directory answer yet: create the transaction anyway, Taxora asks again before sending. */
329
+ readonly EINVOICE_PENDING: "einvoice_pending";
330
+ };
331
+ type ComplianceDeliveryAction = (typeof ComplianceDeliveryAction)[keyof typeof ComplianceDeliveryAction];
332
+
333
+ /**
334
+ * Outcome of a Peppol directory lookup (GET /compliance/peppol-lookup). The
335
+ * directory resolves asynchronously — `pending` means ask again in a few seconds.
336
+ */
337
+ declare const PeppolLookupStatus: {
338
+ readonly REACHABLE: "reachable";
339
+ readonly NOT_REACHABLE: "not_reachable";
340
+ readonly PENDING: "pending";
341
+ readonly UNKNOWN: "unknown";
342
+ };
343
+ type PeppolLookupStatus = (typeof PeppolLookupStatus)[keyof typeof PeppolLookupStatus];
344
+ /** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
345
+ declare function toPeppolLookupStatus(value: unknown): PeppolLookupStatus;
346
+ declare function describePeppolLookupStatus(status: PeppolLookupStatus): string;
347
+
348
+ /**
349
+ * Whether a participant can receive e-invoices over Peppol
350
+ * (GET /compliance/peppol-lookup). For Norway, `reachable === true` means the
351
+ * buyer is registered in ELMA and must receive an EHF e-invoice.
352
+ */
353
+ declare class PeppolLookupResult {
354
+ readonly status: PeppolLookupStatus;
355
+ /** null while the lookup is still `pending`. */
356
+ readonly reachable: boolean | null;
357
+ readonly country: string;
358
+ /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
359
+ readonly scheme: string;
360
+ /** Participant identifier, e.g. the organisation number. */
361
+ readonly id: string;
362
+ /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
363
+ readonly documentTypes: string[];
364
+ readonly transportTypeCode: string | null;
365
+ readonly checkedAt: string | null;
366
+ constructor(status: PeppolLookupStatus,
367
+ /** null while the lookup is still `pending`. */
368
+ reachable: boolean | null, country: string,
369
+ /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
370
+ scheme: string,
371
+ /** Participant identifier, e.g. the organisation number. */
372
+ id: string,
373
+ /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
374
+ documentTypes: string[], transportTypeCode: string | null, checkedAt: string | null);
375
+ /** True while the directory is still resolving — ask again in a few seconds. */
376
+ get isPending(): boolean;
377
+ static fromArray(data: Record<string, unknown>): PeppolLookupResult;
378
+ }
379
+
380
+ /** The action for one buyer plus the directory answer it is based on (EReportingEndpoint.decideDelivery()). */
381
+ declare class ComplianceDeliveryDecision {
382
+ readonly action: ComplianceDeliveryAction;
383
+ readonly lookup: PeppolLookupResult;
384
+ constructor(action: ComplianceDeliveryAction, lookup: PeppolLookupResult);
385
+ /** True unless the buyer is not on the network. */
386
+ get sendsEInvoice(): boolean;
387
+ static fromLookup(lookup: PeppolLookupResult): ComplianceDeliveryDecision;
388
+ }
389
+
147
390
  declare const ComplianceEnrollmentStatus: {
148
391
  readonly PENDING_DATA: "pending_data";
149
392
  readonly ACCOUNT_CREATED: "account_created";
@@ -209,6 +452,81 @@ declare class ComplianceEnrollment {
209
452
  static fromArray(data: Record<string, unknown>): ComplianceEnrollment;
210
453
  }
211
454
 
455
+ /** One bookable plan of a country offering. Fees are net EUR amounts. */
456
+ interface ComplianceOfferingPlan {
457
+ key: string;
458
+ monthlyFee: number | null;
459
+ setupFee: number | null;
460
+ /** Usage tiers as configured server-side (raw objects). */
461
+ usageTiers: unknown[];
462
+ volumeLimit: unknown;
463
+ /** Contact-only plans cannot be booked via createCheckout(). */
464
+ contactOnly: boolean;
465
+ /** True when createCheckout() can be started for this plan right now. */
466
+ checkoutAvailable: boolean;
467
+ /** Prerequisite of the plan (e.g. `{ country: 'FR', service: 'e_reporting' }`); null when there is none. */
468
+ requires: {
469
+ country: string;
470
+ service: string;
471
+ } | null;
472
+ /** Whether the company meets `requires`. */
473
+ eligible: boolean;
474
+ }
475
+ /** A country offering with the company's current state for it. */
476
+ interface ComplianceOffering {
477
+ /** Upper-case ISO 3166-1 alpha-2 code. */
478
+ country: string;
479
+ /** "e_reporting" or "e_invoicing". */
480
+ service: string;
481
+ currency: string;
482
+ active: boolean;
483
+ /** The plan was bought via Stripe self-service (vs. granted manually). */
484
+ viaStripe: boolean;
485
+ plan: string | null;
486
+ status: string | null;
487
+ enrolled: boolean;
488
+ plans: ComplianceOfferingPlan[];
489
+ }
490
+ /** A country Taxora reaches — bookable self-service or set up on request. */
491
+ interface ComplianceCoverageCountry {
492
+ country: string;
493
+ /** "bookable" or "on_request". */
494
+ availability: string;
495
+ services: string[];
496
+ network: string | null;
497
+ format: string | null;
498
+ mandate: string | null;
499
+ /**
500
+ * "yes", "cross_border_only" (only invoices across the border are reached) or
501
+ * "coming_soon" (not live yet, can be requested). Older API versions send none: "yes".
502
+ */
503
+ support?: string;
504
+ }
505
+ /**
506
+ * GET /compliance/offerings — bookable compliance plans per country, every
507
+ * reachable country, and which services the company has unlocked.
508
+ */
509
+ declare class ComplianceOfferings {
510
+ readonly offerings: ComplianceOffering[];
511
+ readonly coverage: ComplianceCoverageCountry[];
512
+ /** Company-wide: is the service unlocked anywhere. */
513
+ readonly access: {
514
+ eReporting: boolean;
515
+ eInvoicing: boolean;
516
+ };
517
+ /** Per country (upper-case code) and service (`e_reporting` / `e_invoicing`). */
518
+ readonly accessByCountry: Record<string, Record<string, boolean>>;
519
+ constructor(offerings: ComplianceOffering[], coverage: ComplianceCoverageCountry[],
520
+ /** Company-wide: is the service unlocked anywhere. */
521
+ access: {
522
+ eReporting: boolean;
523
+ eInvoicing: boolean;
524
+ },
525
+ /** Per country (upper-case code) and service (`e_reporting` / `e_invoicing`). */
526
+ accessByCountry: Record<string, Record<string, boolean>>);
527
+ static fromArray(data: Record<string, unknown>): ComplianceOfferings;
528
+ }
529
+
212
530
  /**
213
531
  * A paginated page of compliance enrollments (GET /compliance/enrollments).
214
532
  */
@@ -300,6 +618,8 @@ declare const ComplianceTransactionState: {
300
618
  readonly SENDING: "sending";
301
619
  readonly SUBMITTED: "submitted";
302
620
  readonly ERROR: "error";
621
+ /** E-invoicing only: the buyer cannot receive e-invoices — nothing was sent or billed; send your regular invoice. */
622
+ readonly NOT_REQUIRED: "not_required";
303
623
  readonly UNKNOWN: "unknown";
304
624
  };
305
625
  type ComplianceTransactionState = (typeof ComplianceTransactionState)[keyof typeof ComplianceTransactionState];
@@ -338,6 +658,38 @@ interface ComplianceTransactionInvoiceLine {
338
658
  unit: number | null;
339
659
  taxes: ComplianceTransactionInvoiceLineTax[];
340
660
  }
661
+ /** The seller's own invoice PDF attached to an e-invoice (`invoice_pdf`). */
662
+ interface ComplianceTransactionInvoicePdf {
663
+ filename: string | null;
664
+ /** Size in bytes. */
665
+ size: number | null;
666
+ /** True once the PDF was uploaded to the provider together with the e-invoice. */
667
+ attached: boolean;
668
+ }
669
+ /**
670
+ * Non-EUR invoices: the amounts in EUR at the ECB reference rate of the invoice
671
+ * date (or the last published rate before it) — `eur_equivalent`. A reference
672
+ * value for bookkeeping; the invoice itself stays in its own currency. Amounts
673
+ * are decimal strings with two decimals, as returned by the API.
674
+ */
675
+ interface ComplianceTransactionEurEquivalent {
676
+ subtotal: string;
677
+ taxAmount: string;
678
+ total: string;
679
+ /** Units of the invoice currency per 1 EUR (ECB reference rate), as a decimal string. */
680
+ rate: string;
681
+ /** Date (YYYY-MM-DD) the ECB published the rate used. */
682
+ rateDate: string | null;
683
+ /** Where the rate comes from — currently always "ECB". */
684
+ source: string;
685
+ }
686
+ /**
687
+ * E-invoicing: the Peppol directory answer about the buyer when it held the
688
+ * invoice back (`delivery_check`) — e.g. status `not_reachable` (state
689
+ * `not_required`) or `pending` (retried automatically). Kept as the raw object;
690
+ * its keys may grow.
691
+ */
692
+ type ComplianceTransactionDeliveryCheck = Record<string, unknown>;
341
693
  /**
342
694
  * A recorded compliance transaction (GET/POST /compliance/transactions) — an
343
695
  * e-reported transaction (France) or an e-invoice / credit note (Norway).
@@ -396,6 +748,35 @@ declare class ComplianceTransaction {
396
748
  readonly providerState: string | null;
397
749
  /** The stored invoice lines (empty when the server does not include them). */
398
750
  readonly invoiceLines: ComplianceTransactionInvoiceLine[];
751
+ /**
752
+ * E-invoicing: URL of the legal e-invoice document once it was sent; null
753
+ * until then. Download it with `eReporting.getTransactionDocument(id)`.
754
+ */
755
+ readonly documentUrl: string | null;
756
+ /** E-invoicing: Peppol directory answer when the buyer check held the invoice back; null otherwise. */
757
+ readonly deliveryCheck: ComplianceTransactionDeliveryCheck | null;
758
+ /** E-invoicing: the attached seller PDF, or null when none is attached. */
759
+ readonly invoicePdf: ComplianceTransactionInvoicePdf | null;
760
+ /**
761
+ * The customer's own reference (order number, ERP id) for searching; never
762
+ * sent to the buyer or the tax authority. Null when not set.
763
+ */
764
+ readonly internalReference: string | null;
765
+ /**
766
+ * URL of the invoice as a readable PDF (the attached seller PDF or the
767
+ * provider's rendering of the e-invoice); null when no PDF is available.
768
+ * Download it with `eReporting.getTransactionPdf(id)`.
769
+ */
770
+ readonly pdfUrl: string | null;
771
+ /** E-invoicing: the buyer refused the invoice (provider state `refused`) — correct it with a credit note. */
772
+ readonly buyerRejected: boolean;
773
+ /** E-invoicing: the buyer's reason for the rejection, when given. */
774
+ readonly rejectionReason: string | null;
775
+ /**
776
+ * Non-EUR invoices: the amounts in EUR at the ECB reference rate of the
777
+ * invoice date. Null for EUR invoices or when no rate is known.
778
+ */
779
+ readonly eurEquivalent: ComplianceTransactionEurEquivalent | null;
399
780
  constructor(id: number, companyId: number, complianceEnrollmentId: number, country: string, regime: string, transactionType: ComplianceTransactionType, transactionTypeLabel: string, state: ComplianceTransactionState, stateLabel: string, invoiceNumber: string,
400
781
  /** Invoice date (YYYY-MM-DD). */
401
782
  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,
@@ -416,7 +797,36 @@ declare class ComplianceTransaction {
416
797
  */
417
798
  providerState?: string | null,
418
799
  /** The stored invoice lines (empty when the server does not include them). */
419
- invoiceLines?: ComplianceTransactionInvoiceLine[]);
800
+ invoiceLines?: ComplianceTransactionInvoiceLine[],
801
+ /**
802
+ * E-invoicing: URL of the legal e-invoice document once it was sent; null
803
+ * until then. Download it with `eReporting.getTransactionDocument(id)`.
804
+ */
805
+ documentUrl?: string | null,
806
+ /** E-invoicing: Peppol directory answer when the buyer check held the invoice back; null otherwise. */
807
+ deliveryCheck?: ComplianceTransactionDeliveryCheck | null,
808
+ /** E-invoicing: the attached seller PDF, or null when none is attached. */
809
+ invoicePdf?: ComplianceTransactionInvoicePdf | null,
810
+ /**
811
+ * The customer's own reference (order number, ERP id) for searching; never
812
+ * sent to the buyer or the tax authority. Null when not set.
813
+ */
814
+ internalReference?: string | null,
815
+ /**
816
+ * URL of the invoice as a readable PDF (the attached seller PDF or the
817
+ * provider's rendering of the e-invoice); null when no PDF is available.
818
+ * Download it with `eReporting.getTransactionPdf(id)`.
819
+ */
820
+ pdfUrl?: string | null,
821
+ /** E-invoicing: the buyer refused the invoice (provider state `refused`) — correct it with a credit note. */
822
+ buyerRejected?: boolean,
823
+ /** E-invoicing: the buyer's reason for the rejection, when given. */
824
+ rejectionReason?: string | null,
825
+ /**
826
+ * Non-EUR invoices: the amounts in EUR at the ECB reference rate of the
827
+ * invoice date. Null for EUR invoices or when no rate is known.
828
+ */
829
+ eurEquivalent?: ComplianceTransactionEurEquivalent | null);
420
830
  get isCreditNote(): boolean;
421
831
  static fromArray(data: Record<string, unknown>): ComplianceTransaction;
422
832
  }
@@ -456,53 +866,6 @@ declare class ImportResult {
456
866
  static fromArray(data: Record<string, unknown>): ImportResult;
457
867
  }
458
868
 
459
- /**
460
- * Outcome of a Peppol directory lookup (GET /compliance/peppol-lookup). The
461
- * directory resolves asynchronously — `pending` means ask again in a few seconds.
462
- */
463
- declare const PeppolLookupStatus: {
464
- readonly REACHABLE: "reachable";
465
- readonly NOT_REACHABLE: "not_reachable";
466
- readonly PENDING: "pending";
467
- readonly UNKNOWN: "unknown";
468
- };
469
- type PeppolLookupStatus = (typeof PeppolLookupStatus)[keyof typeof PeppolLookupStatus];
470
- /** Tolerant coercion: unrecognized values become `unknown` instead of throwing. */
471
- declare function toPeppolLookupStatus(value: unknown): PeppolLookupStatus;
472
- declare function describePeppolLookupStatus(status: PeppolLookupStatus): string;
473
-
474
- /**
475
- * Whether a participant can receive e-invoices over Peppol
476
- * (GET /compliance/peppol-lookup). For Norway, `reachable === true` means the
477
- * buyer is registered in ELMA and must receive an EHF e-invoice.
478
- */
479
- declare class PeppolLookupResult {
480
- readonly status: PeppolLookupStatus;
481
- /** null while the lookup is still `pending`. */
482
- readonly reachable: boolean | null;
483
- readonly country: string;
484
- /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
485
- readonly scheme: string;
486
- /** Participant identifier, e.g. the organisation number. */
487
- readonly id: string;
488
- /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
489
- readonly documentTypes: string[];
490
- readonly transportTypeCode: string | null;
491
- readonly checkedAt: string | null;
492
- constructor(status: PeppolLookupStatus,
493
- /** null while the lookup is still `pending`. */
494
- reachable: boolean | null, country: string,
495
- /** Peppol identifier scheme, e.g. "0192" for Norwegian organisation numbers. */
496
- scheme: string,
497
- /** Participant identifier, e.g. the organisation number. */
498
- id: string,
499
- /** Peppol document types the participant accepts, e.g. "xml.ubl.invoice.bis3". */
500
- documentTypes: string[], transportTypeCode: string | null, checkedAt: string | null);
501
- /** True while the directory is still resolving — ask again in a few seconds. */
502
- get isPending(): boolean;
503
- static fromArray(data: Record<string, unknown>): PeppolLookupResult;
504
- }
505
-
506
869
  /**
507
870
  * A company from a national company register (GET /compliance/registry-lookup) —
508
871
  * for Norway the Brønnøysund Enhetsregisteret. Maps onto the Norway enrollment
@@ -653,6 +1016,31 @@ declare class VatRates {
653
1016
  static fromArray(data: Record<string, unknown>): VatRates;
654
1017
  }
655
1018
 
1019
+ declare const Language: {
1020
+ readonly ENGLISH: "en";
1021
+ readonly GERMAN: "de";
1022
+ };
1023
+ type Language = (typeof Language)[keyof typeof Language];
1024
+
1025
+ /**
1026
+ * Tax category of an invoice line (UNCL5305 / DGFiP codes). Which categories and rates a country
1027
+ * accepts is in eReporting.getVatRates(); Norway uses S (25 / 15 / 12 %), Z, E (with a VATEX code)
1028
+ * and AE (reverse charge).
1029
+ */
1030
+ declare const ComplianceTaxCategory: {
1031
+ readonly STANDARD: "S";
1032
+ readonly REDUCED: "AA";
1033
+ readonly SUPER_REDUCED: "AAA";
1034
+ readonly INTRA_COMMUNITY: "K";
1035
+ readonly EXPORT: "G";
1036
+ readonly REVERSE_CHARGE: "AE";
1037
+ readonly EXEMPT: "E";
1038
+ readonly ZERO: "Z";
1039
+ };
1040
+ type ComplianceTaxCategory = (typeof ComplianceTaxCategory)[keyof typeof ComplianceTaxCategory];
1041
+ /** Strict mapping for input: any case is accepted, an unknown code returns null. */
1042
+ declare function parseComplianceTaxCategory(value: unknown): ComplianceTaxCategory | null;
1043
+
656
1044
  /** Time-series bucket size accepted by the revenue statistics endpoint. */
657
1045
  type EReportingInterval = 'day' | 'week' | 'month';
658
1046
  /** Enterprise size categories accepted by the DGFiP enrollment. */
@@ -674,6 +1062,70 @@ interface RevenueStatisticsFilters {
674
1062
  interval?: EReportingInterval;
675
1063
  transactionType?: ComplianceTransactionRequestType;
676
1064
  state?: ComplianceTransactionRequestState;
1065
+ /** Only this enrollment's transactions — one country's figures (e.g. France or Norway). */
1066
+ complianceEnrollmentId?: number;
1067
+ }
1068
+ /** Filters for exportRevenueTaxRatesCsv() — the revenue statistics filters without `interval`. */
1069
+ type RevenueTaxRatesCsvFilters = Omit<RevenueStatisticsFilters, 'interval'>;
1070
+ /** A transaction download: the legal e-invoice document (getTransactionDocument()) or the invoice PDF (getTransactionPdf()). */
1071
+ interface ComplianceTransactionDocument {
1072
+ /** Raw bytes as delivered by the network (e.g. the EHF/UBL XML). */
1073
+ content: Uint8Array;
1074
+ /** Content-Type header of the download, e.g. "application/xml". */
1075
+ contentType: string;
1076
+ /** Filename from Content-Disposition; null when the header is missing. */
1077
+ filename: string | null;
1078
+ }
1079
+ /** createCheckout() result: open `url` in the browser to pay via Stripe Checkout. */
1080
+ interface ComplianceCheckoutSession {
1081
+ id: string;
1082
+ url: string;
1083
+ }
1084
+ /** Digest email schedule: daily at 08:00 for the day before, weekly on Mondays for the last 7 days. */
1085
+ type ComplianceNotificationDigest = 'off' | 'daily' | 'weekly';
1086
+ /** getNotificationSettings() / updateNotificationSettings() result: the company's opt-in compliance emails. */
1087
+ interface ComplianceNotificationSettings {
1088
+ /** Up to 5 email addresses (lower-cased by the server). */
1089
+ recipients: string[];
1090
+ /** Language of the emails. */
1091
+ language: Language;
1092
+ /** Email (at most hourly) listing new invoices held back because the buyer is not on Peppol. */
1093
+ notOnPeppol: boolean;
1094
+ digest: ComplianceNotificationDigest;
1095
+ /** ISO 8601 timestamp of the last digest sent; null when none was sent yet. */
1096
+ digestSentAt: string | null;
1097
+ }
1098
+ /** updateNotificationSettings() input: only the provided fields change (at least one is required). */
1099
+ interface UpdateComplianceNotificationSettingsInput {
1100
+ /** Replaces the whole list (max 5 addresses); `[]` clears it. */
1101
+ recipients?: string[];
1102
+ language?: Language;
1103
+ notOnPeppol?: boolean;
1104
+ digest?: ComplianceNotificationDigest;
1105
+ }
1106
+ /** confirmCheckout() result: the plan state after the checkout. */
1107
+ interface ComplianceCheckoutConfirmation {
1108
+ active: boolean;
1109
+ country: string | null;
1110
+ service: string | null;
1111
+ plan: string | null;
1112
+ status: string | null;
1113
+ }
1114
+ /**
1115
+ * The seller's own invoice PDF: raw bytes (Uint8Array — a Node Buffer works —
1116
+ * or ArrayBuffer), base64-encoded by the SDK; or a string that is already
1117
+ * base64 (a `data:application/pdf;base64,` prefix is accepted).
1118
+ */
1119
+ type ComplianceInvoicePdfInput = Uint8Array | ArrayBuffer | string;
1120
+ /**
1121
+ * E-invoicing only: attach your own invoice PDF as the e-invoice's visual
1122
+ * representation (max 10 MB). The structured e-invoice stays the legal
1123
+ * document. Rejected with 422 when the country is not booked as e-invoicing.
1124
+ */
1125
+ interface ComplianceInvoicePdfFields {
1126
+ invoicePdf?: ComplianceInvoicePdfInput;
1127
+ /** Filename for the PDF (max 120 chars); defaults server-side to the invoice number. */
1128
+ invoicePdfFilename?: string;
677
1129
  }
678
1130
  /**
679
1131
  * France (DGFiP e-reporting) enrollment — the original createEnrollment() input.
@@ -751,8 +1203,8 @@ interface ComplianceInvoiceTaxInput {
751
1203
  name: string;
752
1204
  /** VAT percentage, e.g. 20 or 5.5. */
753
1205
  percent: number;
754
- /** DGFiP tax category code (S/AA/AAA/K/G/AE/E/Z) — see getVatRates(). */
755
- category: string;
1206
+ /** Tax category code (S/AA/AAA/K/G/AE/E/Z, any case) — see getVatRates() for what a country accepts. */
1207
+ category: ComplianceTaxCategory | Lowercase<ComplianceTaxCategory>;
756
1208
  /** VATEX exemption code; required when `category` is "E". */
757
1209
  comment?: string;
758
1210
  }
@@ -792,7 +1244,7 @@ interface ComplianceTransactionBuyerInput {
792
1244
  /** Free-text note printed on the invoice (max 1000 chars). */
793
1245
  extraInfo?: string;
794
1246
  }
795
- interface CreateComplianceTransactionInput extends ComplianceTransactionBuyerInput {
1247
+ interface CreateComplianceTransactionInput extends ComplianceTransactionBuyerInput, ComplianceInvoicePdfFields {
796
1248
  complianceEnrollmentId: number;
797
1249
  transactionType: ComplianceTransactionRequestType;
798
1250
  invoiceNumber: string;
@@ -816,10 +1268,15 @@ interface CreateComplianceTransactionInput extends ComplianceTransactionBuyerInp
816
1268
  remittanceInformation?: string;
817
1269
  paymentMethodText?: string;
818
1270
  paymentTerms?: string;
1271
+ /**
1272
+ * Your own reference (order number, ERP id), max 100 chars. Stored for your search
1273
+ * only — never sent to the buyer or the tax authority.
1274
+ */
1275
+ internalReference?: string;
819
1276
  /** When false, the transaction is only recorded — submission is deferred. Defaults to true server-side. */
820
1277
  submitNow?: boolean;
821
1278
  }
822
- interface UpdateComplianceTransactionInput extends ComplianceTransactionBuyerInput {
1279
+ interface UpdateComplianceTransactionInput extends ComplianceTransactionBuyerInput, ComplianceInvoicePdfFields {
823
1280
  transactionType?: ComplianceTransactionRequestType;
824
1281
  invoiceNumber?: string;
825
1282
  invoiceDate?: Date | string;
@@ -840,6 +1297,30 @@ interface UpdateComplianceTransactionInput extends ComplianceTransactionBuyerInp
840
1297
  remittanceInformation?: string;
841
1298
  paymentMethodText?: string;
842
1299
  paymentTerms?: string;
1300
+ /**
1301
+ * Your own reference (order number, ERP id), max 100 chars. Stored for your search
1302
+ * only — never sent to the buyer or the tax authority. An empty string clears it.
1303
+ */
1304
+ internalReference?: string;
1305
+ }
1306
+ /**
1307
+ * createCreditNote() input. Without invoiceLines and amounts the whole invoice is
1308
+ * credited; for a partial credit pass invoiceLines, subtotal, taxAmount and total together.
1309
+ */
1310
+ interface CreateCreditNoteInput extends ComplianceInvoicePdfFields {
1311
+ /** The credit note's own number (max 50 chars). */
1312
+ creditNoteNumber: string;
1313
+ /** Defaults to today. */
1314
+ invoiceDate?: Date | string;
1315
+ /** Partial credit: the credited lines. */
1316
+ invoiceLines?: ComplianceInvoiceLineInput[];
1317
+ subtotal?: number;
1318
+ taxAmount?: number;
1319
+ total?: number;
1320
+ extraInfo?: string;
1321
+ /** Your own reference (order number, RMA id), max 100 chars. */
1322
+ internalReference?: string;
1323
+ submitNow?: boolean;
843
1324
  }
844
1325
  interface ComplianceTransactionFilters {
845
1326
  /** Inclusive lower bound on the invoice date (Date or strict YYYY-MM-DD). */
@@ -852,10 +1333,18 @@ interface ComplianceTransactionFilters {
852
1333
  complianceEnrollmentId?: number;
853
1334
  /** Only transactions of this country (2-char ISO 3166-1 alpha-2). */
854
1335
  country?: string;
1336
+ /** Contains-match over invoice number, internal reference and buyer name (max 100 chars). */
1337
+ search?: string;
1338
+ /** Exact match on the internal reference (max 100 chars). */
1339
+ internalReference?: string;
1340
+ /** Provider delivery state (lowercase letters/underscore, max 30), e.g. `refused` = rejected by the buyer. */
1341
+ providerState?: string;
855
1342
  page?: number;
856
1343
  /** Page size (1-100, default 25 server-side). */
857
1344
  perPage?: number;
858
1345
  }
1346
+ /** Filters for exportTransactionsCsv() — the transaction list filters without pagination. */
1347
+ type ComplianceTransactionExportFilters = Omit<ComplianceTransactionFilters, 'page' | 'perPage'>;
859
1348
  interface EReportingAccessRequestInput {
860
1349
  name?: string;
861
1350
  email?: string;
@@ -883,6 +1372,8 @@ interface EReportingAccessRequestInput {
883
1372
  *
884
1373
  * Each country/service is unlocked (and billed) separately; enrolling for a
885
1374
  * service the company does not have yields a 403 with code `service_not_active`.
1375
+ * Write requests (create/update/delete/submit/import) by a user whose only role
1376
+ * is read-only yield a 403 (HttpException) with body code `read_only_role`.
886
1377
  * All routes except requestEReportingAccess() require compliance access on the
887
1378
  * account.
888
1379
  */
@@ -952,6 +1443,17 @@ declare class EReportingEndpoint {
952
1443
  * (HttpException) on provider failure.
953
1444
  */
954
1445
  peppolLookup(country: string, id: string, scheme?: string): Promise<PeppolLookupResult>;
1446
+ /**
1447
+ * What to do with an invoice to this buyer: peppolLookup() turned into an action,
1448
+ * e.g. in a shop checkout when a business buyer enters its number.
1449
+ *
1450
+ * - `einvoice`: create the transaction, Taxora sends the e-invoice;
1451
+ * - `regular_invoice`: the buyer is not on the network — send your regular invoice
1452
+ * yourself (a transaction would end as not_required and is not billed);
1453
+ * - `einvoice_pending`: no definite answer yet — create the transaction anyway,
1454
+ * Taxora asks the directory again before sending.
1455
+ */
1456
+ decideDelivery(country: string, id: string, scheme?: string): Promise<ComplianceDeliveryDecision>;
955
1457
  /**
956
1458
  * Record and (by default) submit a Flux 10 transaction. Pass `submitNow: false`
957
1459
  * to only record it — submission can be triggered later via submitTransaction().
@@ -967,8 +1469,36 @@ declare class EReportingEndpoint {
967
1469
  * On provider failure the API responds 502 (mapped to an HttpException).
968
1470
  */
969
1471
  createTransaction(input: CreateComplianceTransactionInput): Promise<ComplianceTransaction>;
970
- /** Paginated list of the company's transactions (newest invoice date first), filterable by date / state / type / enrollment / country. */
1472
+ /**
1473
+ * Issue a credit note for an invoice you sent through Taxora. Everything that must
1474
+ * match the corrected invoice is taken from `original`: enrollment, transaction type,
1475
+ * currency, buyer (name, register id, address, e-mail, VAT number, buyer reference) —
1476
+ * and the reference to the corrected invoice (number and date) is set for you.
1477
+ *
1478
+ * Without invoiceLines and amounts it credits the whole invoice: lines and amounts are
1479
+ * taken over as they are (the document type, not the sign, makes it a credit note).
1480
+ * For a partial credit pass invoiceLines, subtotal, taxAmount and total together.
1481
+ *
1482
+ * Not possible for an invoice that was never sent to the buyer (state not_required)
1483
+ * or for a credit note. A buyer rejected the invoice? Correct it with a credit note and
1484
+ * send a new invoice (`original.buyerRejected`).
1485
+ */
1486
+ createCreditNote(original: ComplianceTransaction, input: CreateCreditNoteInput): Promise<ComplianceTransaction>;
1487
+ /** Paginated list of the company's transactions (newest invoice date first), filterable by date / state / type / enrollment / country / search / internal reference / provider state. */
971
1488
  listTransactions(filters?: ComplianceTransactionFilters): Promise<ComplianceTransactionPage>;
1489
+ /**
1490
+ * All transactions matching the filters as raw CSV for bookkeeping
1491
+ * (semicolon-separated) — the same filters as listTransactions() without
1492
+ * pagination. Columns: invoice_number, internal_reference, invoice_date,
1493
+ * due_date, country, transaction_type, document_type, state, delivery_state,
1494
+ * buyer_rejected, rejection_reason, counterparty_name, counterparty_country,
1495
+ * counterparty_vat_number, currency, subtotal, tax_amount, total, eur_rate,
1496
+ * eur_rate_date, eur_subtotal, eur_tax_amount, eur_total, provider_invoice_id,
1497
+ * created_at. The eur_* columns hold the ECB reference conversion for non-EUR
1498
+ * invoices (empty for EUR). Max 50,000 rows server-side. The body is returned
1499
+ * verbatim, a UTF-8 BOM included when the API sends one.
1500
+ */
1501
+ exportTransactionsCsv(filters?: ComplianceTransactionExportFilters): Promise<string>;
972
1502
  /** Get a single transaction by id (includes its tax report when one exists). */
973
1503
  getTransaction(id: number): Promise<ComplianceTransaction>;
974
1504
  /** Update a still-pending transaction. Only the provided fields are sent; already-submitted transactions are rejected with 422. */
@@ -986,6 +1516,25 @@ declare class EReportingEndpoint {
986
1516
  * already-submitted transactions are rejected with 422.
987
1517
  */
988
1518
  submitTransaction(id: number): Promise<ComplianceTransaction>;
1519
+ /**
1520
+ * Download the legal e-invoice document of a sent transaction (e-invoicing,
1521
+ * e.g. the EHF/UBL XML for Norway). Available once `documentUrl` on the
1522
+ * transaction is set.
1523
+ *
1524
+ * Errors: 404 (HttpException) for an unknown transaction; 409 (HttpException)
1525
+ * when no document exists (yet) — e.g. e-reporting, not sent, or the network
1526
+ * has not produced it yet (try again in a few minutes); 502 on provider failure.
1527
+ */
1528
+ getTransactionDocument(id: number): Promise<ComplianceTransactionDocument>;
1529
+ /**
1530
+ * Download the invoice as a readable PDF — the seller's attached PDF, or the
1531
+ * provider's rendering of the e-invoice. Available once `pdfUrl` on the
1532
+ * transaction is set.
1533
+ *
1534
+ * Errors: 404 (HttpException) for an unknown transaction; 409 (HttpException)
1535
+ * when no PDF exists (yet); 502 on provider failure.
1536
+ */
1537
+ getTransactionPdf(id: number): Promise<ComplianceTransactionDocument>;
989
1538
  /**
990
1539
  * Bulk-import transactions from a semicolon-separated CSV (one row per invoice
991
1540
  * line; rows sharing an invoice_number are grouped into one transaction).
@@ -1003,14 +1552,25 @@ declare class EReportingEndpoint {
1003
1552
  * months and a monthly interval.
1004
1553
  */
1005
1554
  getRevenueStatistics(filters?: RevenueStatisticsFilters): Promise<RevenueStatistics>;
1555
+ /**
1556
+ * Net and VAT per month, currency and tax rate as raw CSV (semicolon-separated,
1557
+ * computed from the invoice lines) — for reconciling the reported figures with
1558
+ * your VAT return. Same filters as getRevenueStatistics() (without
1559
+ * `interval`); defaults to the last 12 months. The body is returned verbatim,
1560
+ * a UTF-8 BOM included when the API sends one.
1561
+ */
1562
+ exportRevenueTaxRatesCsv(filters?: RevenueTaxRatesCsvFilters): Promise<string>;
1006
1563
  /**
1007
1564
  * The canonical VAT rates & DGFiP tax categories for a reporting country
1008
1565
  * (the seller's reporting-country rates, not the counterparty's). Falls back
1009
1566
  * to the configured default country (FR) when none/unknown is given.
1010
1567
  */
1011
1568
  getVatRates(country?: string): Promise<VatRates>;
1012
- /** Paginated list of the company's tax reports (newest first), optionally filtered by state. */
1013
- listTaxReports(page?: number, perPage?: number, state?: ComplianceTaxReportRequestState): Promise<ComplianceTaxReportPage>;
1569
+ /**
1570
+ * Paginated list of the company's tax reports (newest first), optionally
1571
+ * filtered by state and by country (2-letter ISO code, case-insensitive).
1572
+ */
1573
+ listTaxReports(page?: number, perPage?: number, state?: ComplianceTaxReportRequestState, country?: string): Promise<ComplianceTaxReportPage>;
1014
1574
  /** Get a single tax report by id. */
1015
1575
  getTaxReport(id: number): Promise<ComplianceTaxReport>;
1016
1576
  /**
@@ -1023,6 +1583,48 @@ declare class EReportingEndpoint {
1023
1583
  * returned as HTTP 400 (surfaced as HttpException), not 422.
1024
1584
  */
1025
1585
  requestEReportingAccess(input?: EReportingAccessRequestInput): Promise<void>;
1586
+ /**
1587
+ * Bookable compliance plans per country (net EUR prices), every country
1588
+ * Taxora reaches, and which services the company has unlocked. Works for
1589
+ * companies without compliance access.
1590
+ */
1591
+ getOfferings(): Promise<ComplianceOfferings>;
1592
+ /**
1593
+ * Start a Stripe Checkout for a plan (see getOfferings() — `checkoutAvailable`).
1594
+ * Open the returned `url` in the browser. After payment Stripe redirects to
1595
+ * the Taxora portal, which activates the plan; call confirmCheckout() with the
1596
+ * session id to activate it from your side (idempotent).
1597
+ *
1598
+ * Errors: 422 (ValidationException) for an unknown or contact-only plan or a
1599
+ * plan that is already active; 502 (HttpException) on a Stripe error.
1600
+ */
1601
+ createCheckout(country: string, plan: string): Promise<ComplianceCheckoutSession>;
1602
+ /** Confirm a finished Stripe Checkout and activate its plan. Idempotent. */
1603
+ confirmCheckout(sessionId: string): Promise<ComplianceCheckoutConfirmation>;
1604
+ /**
1605
+ * URL of the Stripe billing portal for the company's compliance plans
1606
+ * (invoices, payment method, cancellation). The portal returns to the Taxora
1607
+ * portal. 404 (HttpException) when no plan was bought via Stripe.
1608
+ */
1609
+ createBillingPortalSession(): Promise<string>;
1610
+ /**
1611
+ * The company's opt-in e-reporting / e-invoicing emails: recipients, language,
1612
+ * the "buyer not on Peppol" email and the digest. Readable by every member.
1613
+ */
1614
+ getNotificationSettings(): Promise<ComplianceNotificationSettings>;
1615
+ /**
1616
+ * Change the company's e-reporting / e-invoicing emails; only the provided
1617
+ * fields change. `notOnPeppol` only reports invoices held back after it was
1618
+ * switched on.
1619
+ *
1620
+ * Errors: 422 (ValidationException) when an email is switched on without any
1621
+ * recipient; 403 (HttpException, body code `admin_only` or `read_only_role`)
1622
+ * for users who are not company admins.
1623
+ */
1624
+ updateNotificationSettings(input: UpdateComplianceNotificationSettingsInput): Promise<ComplianceNotificationSettings>;
1625
+ private toNotificationSettings;
1626
+ /** Validated transaction-list filters as query params (shared by listTransactions and exportTransactionsCsv). */
1627
+ private buildTransactionFilterParams;
1026
1628
  private validateEnrollmentInput;
1027
1629
  private isNorwayEnrollmentInput;
1028
1630
  /** Validates the Norway input and builds its wire body (org number normalized to 9 digits). */
@@ -1036,6 +1638,16 @@ declare class EReportingEndpoint {
1036
1638
  private validateTransactionType;
1037
1639
  private validateInvoiceNumber;
1038
1640
  private validateInvoiceLines;
1641
+ private validateInvoicePdfFilename;
1642
+ private validateInternalReference;
1643
+ /**
1644
+ * Relations that cannot be right: a due date before the invoice date, a credit note without (or an
1645
+ * invoice with) a corrected invoice, a credit note that reuses the number it corrects, a corrected
1646
+ * invoice dated after the credit note.
1647
+ */
1648
+ private validateDocument;
1649
+ /** A category read back from a stored invoice; one that is not a known code cannot be re-sent. */
1650
+ private storedTaxCategory;
1039
1651
  private validateOptionalCodes;
1040
1652
  /**
1041
1653
  * Format checks for the buyer/document fields. Country rules (e.g. the Norway
@@ -1046,8 +1658,14 @@ declare class EReportingEndpoint {
1046
1658
  private buildInvoiceLines;
1047
1659
  /** Applies the optional scalar fields shared by create and update. */
1048
1660
  private applyOptionalTransactionFields;
1661
+ /** Bytes → base64 (validated as a PDF of at most 10 MB); strings are taken as already base64. */
1662
+ private encodeInvoicePdf;
1049
1663
  private buildHeaders;
1050
1664
  private sendRequest;
1665
+ /** GET for a non-JSON download (CSV / document): no JSON Content-Type, retried like other GETs. */
1666
+ private sendDownloadRequest;
1667
+ /** `attachment; filename="x.xml"` (or RFC 5987 `filename*=UTF-8''x.xml`) → "x.xml". */
1668
+ private filenameFromDisposition;
1051
1669
  /** Multipart upload: Content-Type is left to fetch so the boundary is set correctly. */
1052
1670
  private sendMultipartRequest;
1053
1671
  /** Accepts any 2xx response (e.g. 201 on create, 200 on idempotent replay). */
@@ -1896,12 +2514,6 @@ interface LocalTaxNumberReportOptions {
1896
2514
  */
1897
2515
  declare function parseLocalTaxNumbersCsv(csv: string): LocalTaxNumberRow[];
1898
2516
 
1899
- declare const Language: {
1900
- readonly ENGLISH: "en";
1901
- readonly GERMAN: "de";
1902
- };
1903
- type Language = (typeof Language)[keyof typeof Language];
1904
-
1905
2517
  declare class VatEndpoint {
1906
2518
  private readonly baseUrl;
1907
2519
  private readonly apiKey;
@@ -1961,6 +2573,7 @@ declare class TaxoraClient {
1961
2573
  readonly company: CompanyEndpoint;
1962
2574
  readonly smartEnrichment: SmartEnrichmentEndpoint;
1963
2575
  readonly eReporting: EReportingEndpoint;
2576
+ readonly billing: BillingEndpoint;
1964
2577
  readonly baseUrl: string;
1965
2578
  constructor(options: TaxoraClientOptions);
1966
2579
  }
@@ -1974,6 +2587,51 @@ declare const ApiVersion: {
1974
2587
  };
1975
2588
  type ApiVersion = (typeof ApiVersion)[keyof typeof ApiVersion];
1976
2589
 
2590
+ interface InvoiceTotals {
2591
+ /** Sum of the line net amounts, 2 decimals. */
2592
+ subtotal: number;
2593
+ /** Sum of the line VAT amounts, 2 decimals. */
2594
+ taxAmount: number;
2595
+ /** subtotal + taxAmount, 2 decimals. */
2596
+ total: number;
2597
+ /** Expected total minus computed total (0 when no expected total was given). */
2598
+ roundingDifference: number;
2599
+ }
2600
+ interface InvoiceTotalsOptions {
2601
+ /**
2602
+ * The total your own system shows the buyer. The totals always follow the lines (the e-invoice is built
2603
+ * from them); this only checks that your total is within rounding distance and reports the difference.
2604
+ */
2605
+ expectedTotal?: number;
2606
+ /** Largest accepted difference to the expected total (default 0.05). */
2607
+ tolerance?: number;
2608
+ }
2609
+ /**
2610
+ * Subtotal, VAT and total of invoice lines, computed the way the e-invoice is built: every line is
2611
+ * quantity × price rounded to cents, VAT per line at the rates of its taxes. Use it so the header
2612
+ * amounts of createTransaction() always match the lines (the API refuses an e-invoice whose amounts
2613
+ * disagree with its lines).
2614
+ */
2615
+ declare function calculateInvoiceTotals(lines: ComplianceInvoiceLineInput[], options?: InvoiceTotalsOptions): InvoiceTotals;
2616
+
2617
+ /**
2618
+ * Taxes for invoice lines without remembering category codes. The rate itself is the seller's to know;
2619
+ * the API checks it against the country's catalogue (see eReporting.getVatRates()). The name defaults to "VAT".
2620
+ */
2621
+ declare const ComplianceTax: {
2622
+ /**
2623
+ * A taxed rate above 0 %, category S (Norway: 25 / 15 / 12 % are all S). Where a country files reduced rates
2624
+ * under their own category (France: AA / AAA), pass it as `category`.
2625
+ */
2626
+ readonly rate: (percent: number, name?: string, category?: ComplianceInvoiceTaxInput["category"]) => ComplianceInvoiceTaxInput;
2627
+ /** 0 % but taxable (category Z). */
2628
+ readonly zeroRated: (name?: string) => ComplianceInvoiceTaxInput;
2629
+ /** Exempt from VAT (category E); the VATEX exemption code is mandatory. */
2630
+ readonly exempt: (exemptionCode: string, name?: string) => ComplianceInvoiceTaxInput;
2631
+ /** Reverse charge (category AE); the mandatory legal text is added by Taxora. */
2632
+ readonly reverseCharge: (name?: string) => ComplianceInvoiceTaxInput;
2633
+ };
2634
+
1977
2635
  /**
1978
2636
  * Norwegian organisation number (organisasjonsnummer): 9 digits, the last one a
1979
2637
  * modulus-11 check digit (weights 3,2,7,6,5,4,3,2). It is also the Peppol
@@ -2041,13 +2699,40 @@ interface ComplianceLedgerWebhookObject {
2041
2699
  ledger_type: string | null;
2042
2700
  ledger_date: string | null;
2043
2701
  }
2702
+ /**
2703
+ * `compliance.transaction.state_changed` payload. Sent for every real change of a
2704
+ * transaction — Taxora's own state (submitted, error, not_required) and the
2705
+ * provider's delivery state (accepted, refused, paid, …); never twice for the
2706
+ * same state and never for the transient `sending`.
2707
+ *
2708
+ * The optional fields were added later and are missing on older deliveries.
2709
+ */
2044
2710
  interface ComplianceTransactionWebhookObject {
2045
2711
  id: number;
2712
+ /** A ComplianceTransactionState value, e.g. `submitted`, `error`, `not_required`. */
2046
2713
  state: string;
2714
+ /** Provider-side delivery state, e.g. `sent`, `accepted`, `refused`, `paid`. */
2047
2715
  provider_state: string | null;
2716
+ /** Lowercase ISO 3166-1 alpha-2 code, e.g. `no`. */
2048
2717
  country: string | null;
2049
2718
  invoice_number: string | null;
2050
- }
2719
+ /** Your own reference of the transaction. */
2720
+ internal_reference?: string | null;
2721
+ /** Taxora state before this change. */
2722
+ previous_state?: string | null;
2723
+ /** Provider state before this change. */
2724
+ previous_provider_state?: string | null;
2725
+ /** The buyer refused the e-invoice — issue a credit note. */
2726
+ buyer_rejected?: boolean;
2727
+ /** The buyer's reason for the rejection, when given. */
2728
+ rejection_reason?: string | null;
2729
+ /** Why sending failed (state `error`). */
2730
+ submission_error?: string | null;
2731
+ /** Peppol directory result, e.g. `not_reachable` when the state is `not_required`. */
2732
+ delivery_check?: string | null;
2733
+ }
2734
+ /** True when the buyer refused the e-invoice (false for older deliveries without the field). */
2735
+ declare function isTransactionBuyerRejected(object: ComplianceTransactionWebhookObject): boolean;
2051
2736
  /** Raw Smart Enrichment rows — wrap them with `SmartEnrichmentResource.fromArray()` for a typed DTO. */
2052
2737
  interface EnrichmentCompletedWebhookObject {
2053
2738
  jobId: string;
@@ -2210,4 +2895,4 @@ declare class AuthRetryHttpClient implements HttpClientInterface {
2210
2895
  private injectAuthHeader;
2211
2896
  }
2212
2897
 
2213
- 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, type LocalTaxNumberReportOptions, LocalTaxNumberRow, type LocalTaxNumberSummary, 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 SmartEnrichmentOfficialAddress, type SmartEnrichmentOutcomeBreakdown, type SmartEnrichmentProviderVerdict, SmartEnrichmentRecheck, type SmartEnrichmentRecheckOptions, type SmartEnrichmentRecheckRun, type SmartEnrichmentRecheckRunState, type SmartEnrichmentRecheckSkipReason, SmartEnrichmentRecheckState, type SmartEnrichmentRejectedCandidate, SmartEnrichmentRejectionReason, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTaxNumberSource, 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, describeSmartEnrichmentRejectionReason, describeSmartEnrichmentStatus, describeVatState, generateWebhookSignatureHeader, getBaseUrl, getFailedVatStates, parseLocalTaxNumbersCsv, parseWebhookSignatureHeader, toComplianceDocumentType, toComplianceEnrollmentStatus, toComplianceService, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toPeppolLookupStatus, toSmartEnrichmentMode, toSmartEnrichmentRejectionReason, toSmartEnrichmentStatus, verifyWebhookSignature };
2898
+ export { ApiVersion, AuthEndpoint, AuthRetryHttpClient, AuthenticationException, BillingEndpoint, CompanyAddress, CompanyEndpoint, type CompanyResource, type ComplianceCheckoutConfirmation, type ComplianceCheckoutSession, type ComplianceCoverageCountry, ComplianceDeliveryAction, ComplianceDeliveryDecision, ComplianceDocumentType, ComplianceEnrollment, ComplianceEnrollmentPage, ComplianceEnrollmentStatus, type ComplianceEnterpriseSize, type ComplianceInvoiceLineInput, type ComplianceInvoicePdfFields, type ComplianceInvoicePdfInput, type ComplianceInvoiceTaxInput, type ComplianceLedgerStateChangedEvent, type ComplianceLedgerWebhookObject, type ComplianceNotificationDigest, type ComplianceNotificationSettings, type ComplianceOffering, type ComplianceOfferingPlan, ComplianceOfferings, type ComplianceRequestService, ComplianceService, ComplianceTax, ComplianceTaxCategory, ComplianceTaxReport, ComplianceTaxReportPage, type ComplianceTaxReportRequestState, ComplianceTaxReportState, ComplianceTransaction, type ComplianceTransactionBuyerInput, type ComplianceTransactionDeliveryCheck, type ComplianceTransactionDocument, type ComplianceTransactionEurEquivalent, type ComplianceTransactionExportFilters, type ComplianceTransactionFilters, type ComplianceTransactionInvoiceLine, type ComplianceTransactionInvoiceLineTax, type ComplianceTransactionInvoicePdf, ComplianceTransactionPage, type ComplianceTransactionRequestState, type ComplianceTransactionRequestType, ComplianceTransactionState, type ComplianceTransactionStateChangedEvent, ComplianceTransactionType, type ComplianceTransactionWebhookObject, type ComplianceTypeOperation, type CreateComplianceEnrollmentInput, type CreateComplianceTransactionInput, type CreateCreditNoteInput, type CreateNorwayEnrollmentInput, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, EInvoicingQuota, EInvoicingQuotaPeriod, type EInvoicingQuotaTier, type EReportingAccessRequestInput, EReportingEndpoint, type EReportingInterval, type EnrichmentCompletedEvent, type EnrichmentCompletedWebhookObject, type EnrichmentUpdatedEvent, type EnrichmentUpdatedWebhookObject, Environment, Environment as EnvironmentType, FetchHttpClient, type HttpClientInterface, HttpException, ImportResult, InMemoryTokenStorage, type InvoiceTotals, type InvoiceTotalsOptions, Language, type LocalTaxNumberReportOptions, LocalTaxNumberRow, type LocalTaxNumberSummary, LoginIdentifier, type NorwayEnrollmentInput, NorwegianOrgNumber, type ParsedWebhookSignatureHeader, PeppolLookupResult, PeppolLookupStatus, ProviderDocument, ProviderDocumentLine, RegistryCompany, RetryPolicy, type RetryPolicyOptions, type RevenueCountryBreakdown, type RevenueCurrencyBreakdown, type RevenueStateBreakdown, RevenueStatistics, type RevenueStatisticsFilters, type RevenueTaxRatesCsvFilters, 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 SmartEnrichmentOfficialAddress, type SmartEnrichmentOutcomeBreakdown, type SmartEnrichmentProviderVerdict, SmartEnrichmentRecheck, type SmartEnrichmentRecheckOptions, type SmartEnrichmentRecheckRun, type SmartEnrichmentRecheckRunState, type SmartEnrichmentRecheckSkipReason, SmartEnrichmentRecheckState, type SmartEnrichmentRejectedCandidate, SmartEnrichmentRejectionReason, SmartEnrichmentResource, type SmartEnrichmentSourceBreakdown, SmartEnrichmentStatistics, type SmartEnrichmentStatisticsInterval, type SmartEnrichmentStatisticsOptions, type SmartEnrichmentStatisticsRange, type SmartEnrichmentStatisticsTotals, SmartEnrichmentStatus, type SmartEnrichmentTaxNumberSource, type SmartEnrichmentTimeBucket, type SmartEnrichmentUsage, type SmartEnrichmentUsageHistoryEntry, type SmartEnrichmentWaitOptions, TaxoraClient, TaxoraClientFactory, type TaxoraClientOptions, TaxoraException, type TaxoraWebhookEvent, type TestWebhookObject, Token, type TokenStorageInterface, type UpdateComplianceNotificationSettingsInput, type UpdateComplianceTransactionInput, type UsageEvent, UsageSummary, UsageSummaryPage, 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, calculateInvoiceTotals, computeWebhookSignature, constructWebhookEvent, describeApiError, describeComplianceDocumentType, describeComplianceEnrollmentStatus, describeComplianceService, describeComplianceTaxReportState, describeComplianceTransactionState, describeComplianceTransactionType, describePeppolLookupStatus, describeSmartEnrichmentMode, describeSmartEnrichmentRejectionReason, describeSmartEnrichmentStatus, describeVatState, generateWebhookSignatureHeader, getBaseUrl, getFailedVatStates, isTransactionBuyerRejected, parseComplianceTaxCategory, parseLocalTaxNumbersCsv, parseWebhookSignatureHeader, toComplianceDocumentType, toComplianceEnrollmentStatus, toComplianceService, toComplianceTaxReportState, toComplianceTransactionState, toComplianceTransactionType, toPeppolLookupStatus, toSmartEnrichmentMode, toSmartEnrichmentRejectionReason, toSmartEnrichmentStatus, verifyWebhookSignature };