@taxora/sdk 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [1.9.0] — 2026-10-27
+
+### Added
+
+- **`ComplianceCoverageCountry.support`** — `'yes' | 'cross_border_only' | 'coming_soon'` from
+  `GET /compliance/offerings`: whether a country is fully served, reached only for invoices across the border, or not
+  live yet (can still be requested). Defaults to `'yes'` for older API versions.
+- **`eReporting.getNotificationSettings()` / `eReporting.updateNotificationSettings(input)`** —
+  `GET` / `PUT /compliance/notification-settings`: the company's opt-in compliance emails as
+  `ComplianceNotificationSettings` (`{ recipients, language, notOnPeppol, digest, digestSentAt }`). `notOnPeppol` =
+  hourly email listing invoices held back because the buyer is not on Peppol; `digest` = `'off' | 'daily' | 'weekly'`
+  summary. Updates send only the provided fields (`UpdateComplianceNotificationSettingsInput`, at least one; max 5
+  recipients, validated before the request); 422 when an email is switched on without recipients, 403 `admin_only` /
+  `read_only_role` for non-admins.
+- **`eReporting.exportTransactionsCsv(filters)`** — `GET /compliance/transactions/export.csv`: all transactions
+  matching the `listTransactions()` filters (without pagination, type `ComplianceTransactionExportFilters`) as a
+  semicolon-separated CSV for bookkeeping, incl. internal reference, delivery state, buyer rejection and ECB EUR
+  columns (max 50,000 rows). Returned verbatim as a string.
+- **`ComplianceTransaction.eurEquivalent`** (`{ subtotal, taxAmount, total, rate, rateDate, source: 'ECB' }`): the
+  amounts of a non-EUR invoice in EUR at the ECB reference rate of the invoice date; null for EUR invoices or when no
+  rate is known.
+- **E-invoicing status signals:** `compliance.transaction.state_changed` now fires for every real change (Taxora's
+  own state and the provider's delivery state: accepted, refused, paid, …; never twice, never for `sending`).
+  `ComplianceTransactionWebhookObject` gained the optional `internal_reference`, `previous_state`,
+  `previous_provider_state`, `buyer_rejected`, `rejection_reason`, `submission_error` and `delivery_check`, plus the
+  helper **`isTransactionBuyerRejected(object)`**.
+- **`ComplianceTransaction.buyerRejected` / `.rejectionReason`** and the **`providerState`** filter on
+  `listTransactions()` (e.g. `'refused'` = rejected by the buyer).
+- **`eReporting.getTransactionPdf(id)`** downloads the invoice as a readable PDF (the attached seller PDF or the
+  provider's rendering of the e-invoice) as `{ content, contentType, filename }`; 409 while no PDF is available.
+  **`ComplianceTransaction.pdfUrl`** is set once a PDF is available.
+- **Internal reference:** `internalReference` on `createTransaction()` and `updateTransaction()` (max 100 chars;
+  an empty string clears it on update) and `ComplianceTransaction.internalReference`. Your own reference (order
+  number, ERP id) for searching — never sent to the buyer or the tax authority. Also an optional CSV import column
+  `internal_reference`.
+- **`listTransactions()` filters `search`** (contains-match over invoice number, internal reference and buyer name)
+  **and `internalReference`** (exact match), both max 100 chars.
+- **`eReporting.getTransactionDocument(id)`** downloads the legal e-invoice of a sent transaction
+  (`{ content: Uint8Array, contentType, filename }`); 409 while it is not available yet.
+- **Invoice PDF attachment:** `invoicePdf` / `invoicePdfFilename` on `createTransaction()` and `updateTransaction()`
+  (e-invoicing only). Bytes (`Buffer` / `Uint8Array` / `ArrayBuffer`) are checked (PDF, max 10 MB) and base64-encoded;
+  strings are sent as-is (already base64).
+- **`ComplianceTransaction.documentUrl`, `.deliveryCheck` and `.invoicePdf`** (`{ filename, size, attached }`).
+- **`ComplianceTransactionState.NOT_REQUIRED`** (`not_required`): the buyer cannot receive e-invoices, so nothing was
+  sent or billed.
+- **`eReporting.exportRevenueTaxRatesCsv(filters)`**: net and VAT per month and tax rate as CSV (BOM preserved).
+- **Self-service plans:** `eReporting.getOfferings()` (`ComplianceOfferings`), `createCheckout(country, plan)`,
+  `confirmCheckout(sessionId)` and `createBillingPortalSession()`.
+- **`client.billing`** (`BillingEndpoint`): `listUsageSummaries(page, perPage)` (`UsageSummaryPage`) and
+  `getUsageSummaries(period)` (`UsageSummary[]` with events).
+- **Per-country filters:** `complianceEnrollmentId` on `getRevenueStatistics()` and `exportRevenueTaxRatesCsv()`;
+  `country` as 4th argument of `listTaxReports(page, perPage, state, country)`.
+- README: compliance write requests by a read-only user return 403 with code `read_only_role` (HttpException).
+- README: compliance webhook events (`compliance.transaction.state_changed`, `compliance.ledger.state_changed`) listed
+  with their payloads.
+
+### Fixed
+
+- **`ComplianceOfferingPlan.requires`** is now typed `{ country: string; service: string } | null` and parsed from the
+  object the API sends (e.g. `{ country: 'FR', service: 'e_reporting' }`). It was typed `unknown[] | null` and always
+  came back `null`. Public type change.
+- `createTransaction()` / `updateTransaction()` reject `invoicePdfFilename` without `invoicePdf`
+  (`invoicePdfFilename requires invoicePdf.`), like the PHP SDK.
+- README: `admin_only` (403) listed with the compliance error codes; the webhook example no longer mentions a
+  `not_required` state event (it is never sent).
+
 ## [1.8.0] — 2026-10-25
 
 ### Added

package/README.md

@@ -124,7 +124,10 @@ TaxoraClientFactory.create()
   └── TaxoraClient
         ├── auth    → AuthEndpoint    (login, loginWithClientId, refresh)
         ├── vat     → VatEndpoint     (validate, history, search, certificates)
-        └── company → CompanyEndpoint (company info)
+        ├── company → CompanyEndpoint (company info)
+        ├── smartEnrichment → SmartEnrichmentEndpoint (reverse VAT lookup)
+        ├── eReporting      → EReportingEndpoint      (compliance: enrollments, transactions, plans)
+        └── billing         → BillingEndpoint         (usage summaries)
 ```
 
 Each endpoint handles:
@@ -153,6 +156,8 @@ Each endpoint handles:
 | `ProviderDocument`          | Attached provider document metadata (type, date, MIME, hash, nested line item)                  |
 | `ComplianceEnrollment`      | Per-country compliance enrollment: country, regime, `service`, provisioning status              |
 | `ComplianceTransaction`     | Recorded transaction / e-invoice: amounts, state, buyer fields, `documentType`, `providerState` |
+| `ComplianceOfferings`       | Bookable compliance plans per country, coverage, unlocked services                              |
+| `UsageSummary`              | Billed usage of one feature in one billing period (YYYY-MM), optionally with its events         |
 | `ComplianceTaxReport`       | DGFiP tax report lifecycle of a transaction (France)                                            |
 | `SireneLookupResult`        | Company data from the French SIRENE registry                                                    |
 | `RegistryCompany`           | Company from a national register (Norway: Brønnøysund) — org number, VAT / register flags       |
@@ -626,6 +631,7 @@ const tx = await client.eReporting.createTransaction({
       taxes: [{ name: 'TVA', percent: 20, category: 'S' }], // category E needs a VATEX `comment`
     },
   ],
+  internalReference: 'ORDER-4711', // optional, max 100: your own reference (order no., ERP id) — never sent to the buyer or the tax authority
   submitNow: false, // record now, submit later
 });
 
@@ -637,15 +643,34 @@ console.log(submitted.state, submitted.stateLabel); // e.g. "submitted"
 const transactions = await client.eReporting.listTransactions({
   dateFrom: '2026-07-01', // or a Date
   dateTo: '2026-07-31',
-  state: 'pending', // 'pending' | 'sending' | 'submitted' | 'error'
+  state: 'pending', // 'pending' | 'sending' | 'submitted' | 'error' | 'not_required'
   transactionType: 'b2c_outbound',
   complianceEnrollmentId: enrollment.id, // optional: one enrollment only
   country: 'FR', // optional: one country only
+  search: 'ACME', // optional: contains-match over invoice number, internal reference and buyer name
+  internalReference: 'ORDER-4711', // optional: exact match on your internal reference
+  providerState: 'refused', // optional: provider delivery state, 'refused' = rejected by the buyer
   page: 1,
   perPage: 25,
 });
 const one = await client.eReporting.getTransaction(tx.id);
+// Non-EUR invoices carry the EUR amounts at the ECB reference rate of the invoice date
+// (null for EUR invoices or when no rate is known):
+if (one.eurEquivalent) {
+  const { total, rate, rateDate, source } = one.eurEquivalent; // decimal strings, e.g. '98.92', '11.6250'
+  console.log(`${total} EUR @ ${rate} (${source}, ${rateDate})`);
+}
+
+// The same filters (without page/perPage) as a semicolon-separated CSV for your bookkeeping —
+// incl. internal reference, delivery state, buyer rejection and the eur_rate / eur_rate_date /
+// eur_subtotal / eur_tax_amount / eur_total columns. Max 50,000 rows; returned verbatim.
+const bookkeepingCsv = await client.eReporting.exportTransactionsCsv({
+  dateFrom: '2026-01-01',
+  dateTo: '2026-09-30',
+  country: 'NO',
+});
 await client.eReporting.updateTransaction(tx.id, { total: 130, taxAmount: 21.67 });
+await client.eReporting.updateTransaction(tx.id, { internalReference: '' }); // empty string clears it
 await client.eReporting.deleteTransaction(tx.id); // resolves void on 204
 ```
 
@@ -653,7 +678,8 @@ await client.eReporting.deleteTransaction(tx.id); // resolves void on 204
 
 Bulk-import from a semicolon-separated CSV (one row per invoice line; rows sharing an
 `invoice_number` are grouped into one transaction). Idempotent: re-uploading skips rows whose
-invoice already exists.
+invoice already exists. An optional `internal_reference` column sets your own reference per
+invoice.
 
 ```ts
 import { readFileSync } from 'fs';
@@ -674,7 +700,7 @@ Every submitted transaction is tracked through the aggregated DGFiP ledger lifec
 (`new → sent → acknowledged → registered` or `refused`/`error`).
 
 ```ts
-const reports = await client.eReporting.listTaxReports(1, 25, 'refused'); // state filter optional
+const reports = await client.eReporting.listTaxReports(1, 25, 'refused', 'FR'); // state + country filters optional
 for (const report of reports) {
   console.log(report.state, report.stateLabel, report.isTerminal, report.refusalReason);
 }
@@ -712,6 +738,7 @@ const stats = await client.eReporting.getRevenueStatistics({
   interval: 'month', // 'day' | 'week' | 'month' (default 'month')
   transactionType: 'b2c_outbound', // optional filter
   state: 'submitted', // optional filter
+  complianceEnrollmentId: enrollment.id, // optional: one enrollment = one country's figures
 });
 
 console.log(stats.primaryCurrency); // e.g. EUR
@@ -724,6 +751,23 @@ for (const row of stats.byCountry) {
 }
 ```
 
+### Tax-rate CSV
+
+Net and VAT per month, currency and tax rate (semicolon-separated, computed from the invoice lines) — for reconciling
+the reported figures with your VAT return. Same filters as `getRevenueStatistics()` without `interval`. The body is
+returned byte-for-byte, a UTF-8 BOM included.
+
+```ts
+import { writeFileSync } from 'fs';
+
+const csv = await client.eReporting.exportRevenueTaxRatesCsv({
+  dateFrom: '2026-01-01',
+  dateTo: '2026-12-31',
+  complianceEnrollmentId: enrollment.id, // optional: one country only
+});
+writeFileSync('tax-rates.csv', csv);
+```
+
 ### 🇳🇴 E-Invoicing Norway (EHF / Peppol)
 
 Send EHF e-invoices and credit notes (Peppol BIS Billing 3.0) to Norwegian buyers. The
@@ -837,6 +881,99 @@ console.log(creditNote.isCreditNote); // true
 const noDocs = await client.eReporting.listTransactions({ country: 'NO' });
 ```
 
+**6. Attach your own invoice PDF** (e-invoicing only, max 10 MB) — pass the bytes (`Buffer` / `Uint8Array` /
+`ArrayBuffer`); the SDK base64-encodes them. A string is sent as-is and must already be base64. The structured
+e-invoice stays the legal document; whether the buyer's system shows the PDF depends on that system.
+
+```ts
+import { readFileSync } from 'fs';
+
+const withPdf = await client.eReporting.createTransaction({
+  ...invoiceInput,
+  invoicePdf: readFileSync('NO-2026-0002.pdf'),
+  invoicePdfFilename: 'NO-2026-0002.pdf', // optional, defaults to the invoice number
+});
+console.log(withPdf.invoicePdf); // { filename, size, attached } — attached once uploaded with the e-invoice
+
+await client.eReporting.updateTransaction(withPdf.id, { invoicePdf: readFileSync('fixed.pdf') }); // replaces it
+```
+
+**7. Buyer not on Peppol / download the legal document**
+
+```ts
+const tx = await client.eReporting.getTransaction(invoice.id);
+
+if (tx.state === 'not_required') {
+  // The buyer cannot receive e-invoices: nothing was sent or billed — send your regular invoice.
+  console.log(tx.deliveryCheck); // Peppol directory answer, e.g. { status: 'not_reachable', … }
+}
+
+if (tx.documentUrl !== null) {
+  const doc = await client.eReporting.getTransactionDocument(tx.id); // 409 while not available yet
+  writeFileSync(doc.filename ?? `${tx.invoiceNumber}.xml`, doc.content); // doc.contentType e.g. application/xml
+}
+
+// The invoice as a readable PDF (your attached PDF, or the provider's rendering of the e-invoice)
+if (tx.pdfUrl !== null) {
+  const pdf = await client.eReporting.getTransactionPdf(tx.id); // 409 while no PDF is available
+  writeFileSync(pdf.filename ?? `${tx.invoiceNumber}.pdf`, pdf.content); // pdf.contentType: application/pdf
+}
+```
+
+### Self-service plans (Stripe)
+
+Book compliance plans without contacting sales. These routes work for companies **without** compliance access.
+
+```ts
+const { offerings, coverage, access, accessByCountry } = await client.eReporting.getOfferings();
+const plan = offerings.find((o) => o.country === 'NO')?.plans.find((p) => p.checkoutAvailable);
+
+const session = await client.eReporting.createCheckout('NO', plan!.key); // 422 if contact-only / already active
+// open session.url in the browser; Stripe returns the user to the Taxora portal
+const state = await client.eReporting.confirmCheckout(session.id); // idempotent → { active, country, service, plan, status }
+
+const portalUrl = await client.eReporting.createBillingPortalSession(); // invoices, payment method, cancel; 404 without a Stripe plan
+```
+
+### Notification emails
+
+Opt-in e-reporting / e-invoicing emails for your company — readable by every member, changeable by company **admins**
+only.
+
+```ts
+const settings = await client.eReporting.getNotificationSettings();
+// { recipients: ['accounting@example.com'], language: 'de' | 'en', notOnPeppol: boolean,
+//   digest: 'off' | 'daily' | 'weekly', digestSentAt: string | null }
+
+// Only the provided fields change (at least one is required); recipients replaces the whole list (max 5):
+await client.eReporting.updateNotificationSettings({
+  recipients: ['accounting@example.com', 'cfo@example.com'],
+  language: 'en',
+  notOnPeppol: true, // hourly email listing invoices held back because the buyer is not on Peppol
+  digest: 'weekly', // 'daily' = 08:00 for the day before, 'weekly' = Mondays for the last 7 days
+});
+```
+
+Invalid input (more than 5 or invalid addresses, unknown `language` / `digest`, no field) throws a `TaxoraException`
+before any request. Switching an email on without any recipient answers `422` (`ValidationException`); a non-admin
+gets `403` with body code `admin_only` (or `read_only_role`) as `HttpException`. `notOnPeppol` only reports invoices
+held back after it was switched on.
+
+### Billing usage summaries
+
+Read-only usage of your billable modules (E-Reporting / E-Invoicing, Smart Enrichment), per feature and billing
+period.
+
+```ts
+const page = await client.billing.listUsageSummaries(1, 25); // newest period first
+for (const summary of page) {
+  console.log(summary.billingPeriod, summary.feature, summary.eventCount, summary.billableAmount, summary.state);
+}
+
+const september = await client.billing.getUsageSummaries('2026-09'); // with events; 404 for a period without usage
+console.log(september[0]?.events.length);
+```
+
 ---
 
 ## 📜 Certificates
@@ -922,6 +1059,13 @@ error body when there is one, and falls back to the status line
 (`Taxora API request failed (HTTP 504 Gateway Timeout).`) otherwise. The
 untouched body stays available via `err.getResponseBody()`.
 
+**Compliance 403 codes.** Compliance 403s are `HttpException`s; the reason is the `code` in the JSON body
+(`err.getResponseBody()`): `service_not_active` (the company has not booked the service/country),
+`read_only_role` (a write request — create, update, delete, submit, import — by a user whose only role is
+read-only) or `admin_only` (body `{ message, code: 'admin_only' }`: a developer-role user tried to create an
+enrollment, `createCheckout()`, `confirmCheckout()`, `createBillingPortalSession()` or
+`updateNotificationSettings()` — only admins can add countries, change plans or change the notification emails).
+
 ### Automatic retries
 
 The SDK retries what never produced an answer from the API itself: **3 attempts,
@@ -1038,6 +1182,43 @@ Next.js App Router: `const rawBody = await request.text();` (not `request.json()
   `reason: 'invalid_body'`.
 - **Idempotency:** dedupe on `event.id` (= `Taxora-Webhook-Id`), which stays the same across retries.
 
+### Events
+
+| Event                                  | `data.object`                                                                                                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `vat.validated` / `vat.state_changed`  | `VatWebhookObject` (`id`, `vat_uid`, `state`, `company_name`, …)                                              |
+| `compliance.transaction.state_changed` | `ComplianceTransactionWebhookObject` (`id`, `state`, `previous_state`, `provider_state`, `buyer_rejected`, …) |
+| `compliance.ledger.state_changed`      | `ComplianceLedgerWebhookObject` (`id`, `state`, `ledger_type`, `ledger_date`)                                 |
+| `enrichment.completed`                 | `EnrichmentCompletedWebhookObject` (`jobId`, `status`, `results`, …)                                          |
+| `enrichment.updated`                   | `EnrichmentUpdatedWebhookObject` (`jobId`, `rowIndex`, `result`, …)                                           |
+| `webhook.test`                         | `TestWebhookObject` (`message`)                                                                               |
+
+`compliance.transaction.state_changed` fires for **every real change** of a transaction: Taxora's own state
+(`submitted`, `error`, `not_required`) and the provider's delivery state (`accepted`, `refused`, `paid`, …). It is
+never sent twice for the same state and never for the transient `sending`. Besides `id`, `invoice_number`,
+`country` (lowercase), `state` and `provider_state` the object carries `internal_reference`, `previous_state`,
+`previous_provider_state`, `buyer_rejected`, `rejection_reason`, `submission_error` and `delivery_check` — these are
+optional in the type because older deliveries lack them.
+
+```ts
+import { isTransactionBuyerRejected } from '@taxora/sdk';
+
+if (event.event === 'compliance.transaction.state_changed') {
+  const tx = event.data.object;
+  if (tx.state === 'not_required') {
+    // The buyer cannot receive e-invoices (tx.delivery_check e.g. 'not_reachable'):
+    // nothing was sent or billed — send your PDF to the buyer by e-mail yourself.
+  }
+  if (isTransactionBuyerRejected(tx)) {
+    // The buyer refused the e-invoice (tx.rejection_reason) — issue a credit note.
+  }
+  if (tx.state === 'error') console.warn(tx.submission_error);
+}
+```
+
+Transactions carry the same signal (`tx.buyerRejected`, `tx.rejectionReason`); find rejected invoices with
+`listTransactions({ providerState: 'refused' })`.
+
 ---
 
 ## 🔌 VatState Helpers