@taxora/sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVer](https://semver.org/).
+
+## [1.3.0] — 2026-10-13
+
+### Added
+
+- **Webhook signature verification** for Taxora's opt-in HMAC-signed webhooks (`Taxora-Signature: t=…,v1=…`):
+  - `verifyWebhookSignature(rawBody, header, secret, { tolerance })` — constant-time comparison, timestamp
+    tolerance against replays (default 300 s), accepts several `v1` entries (rotation) and several secrets.
+  - `constructWebhookEvent(rawBody, header, secret, options)` — verifies, then returns a typed
+    `TaxoraWebhookEvent` (discriminated union on `event`).
+  - `generateWebhookSignatureHeader()` for testing your own handlers, plus `parseWebhookSignatureHeader()` and
+    `computeWebhookSignature()`.
+  - `WebhookSignatureVerificationError` with a machine-readable `reason`.
+  - Event types: `vat.validated`, `vat.state_changed`, `compliance.ledger.state_changed`,
+    `compliance.transaction.state_changed`, `enrichment.completed`, `enrichment.updated`, `webhook.test`.
+
+## [1.2.0]
+
+- Per-country compliance services incl. Norway e-invoicing (EHF / Peppol). See the GitHub release notes.

package/README.md

@@ -151,6 +151,12 @@ Each endpoint handles:
 | `Token`                     | Access token with type and expiry; 15-second buffer for proactive refresh                       |
 | `VatCertificateExport`      | Bulk export job reference (`exportId` + optional message)                                       |
 | `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` |
+| `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       |
+| `PeppolLookupResult`        | Peppol directory lookup: `status` (reachable / not_reachable / pending), document types         |
 
 All DTOs expose `toArray()` for serialization and a static `fromArray()` factory.
 
@@ -331,7 +337,35 @@ console.log(result?.status); // 'found' | 'no_vat_exists' | 'not_found'
 console.log(result?.vatNumber); // e.g. 'ATU12345678'
 console.log(result?.confidence); // 0–100
 
+// Search mode: 'default' searches with one AI provider and only consults a second one when
+// the first finds nothing. 'complex' has two independent providers search from the start and
+// puts every number either of them proposes through the tax authority's checks. Complex finds
+// companies a single search misses — typically ones whose VAT only appears in a website
+// Impressum — and costs more per lookup, so it is opt-in.
+const deep = await client.smartEnrichment.lookup({
+  companyName: 'Vodafone D2 GmbH',
+  country: 'DE',
+  postalCode: '40547',
+  mode: SmartEnrichmentMode.COMPLEX,
+});
+
+// When more than one provider searched, you can see what each one concluded on its own.
+// Two of them reporting the same number is the strongest confirmation this layer produces.
+for (const verdict of deep.result()?.providerVerdicts ?? []) {
+  console.log(`${verdict.provider}: ${verdict.vatNumber ?? 'nothing'}`);
+}
+
+// The API also grades the address you sent. Worth writing back into your own records: a
+// 'postal_code_city_mismatch' / 'postal_code_unassigned' warning means the postal code in
+// your source data is wrong, and `derivedPlace` is the area it actually points at.
+const quality = deep.result()?.addressQuality;
+if (quality && quality.warnings.length > 0) {
+  console.log(quality.warnings.join(', '), '→', quality.derivedPlace);
+}
+
 // Bulk lookup (always async → webhook + polling)
+// The batch-level mode applies to every row; a row carrying its own `mode` overrides it,
+// so you can pay for 'complex' on just the rows that need it.
 const bulk = await client.smartEnrichment.bulkLookup([
   { companyName: 'A GmbH', country: 'DE', city: 'Berlin' },
   { companyName: 'B SARL', country: 'FR' },
@@ -415,6 +449,12 @@ submit transactions (individually or via CSV import), and track the resulting DG
 All `compliance` routes require an active E-Reporting subscription / feature grant on your
 account — except `requestEReportingAccess()`, which is how you ask for one.
 
+**Per-country services:** each enrollment books one service for one country — `e_reporting`
+(France, regime `dgfip_flux10`) or `e_invoicing` (Norway EHF / Peppol BIS 3.0, regime
+`peppol_bis3`, see [below](#-e-invoicing-norway-ehf--peppol)). Every country is unlocked and
+billed separately (one-off setup fee + per document). Enrolling for a service your company does not
+have yields a 403 `HttpException` whose body carries `code: "service_not_active"`.
+
 ### Request feature activation
 
 Not enabled yet? This route is deliberately **not** gated — it requests activation of the
@@ -427,6 +467,8 @@ await client.eReporting.requestEReportingAccess({
   phone: '+43 660 1234567',
   message: 'Please activate e-reporting for our account.',
   language: 'de', // locale of the confirmation mail
+  service: 'e_invoicing', // optional: 'e_reporting' (default) | 'e_invoicing'
+  countries: ['NO'], // optional: the countries you want the service for
 });
 ```
 
@@ -513,6 +555,8 @@ const transactions = await client.eReporting.listTransactions({
   dateTo: '2026-07-31',
   state: 'pending', // 'pending' | 'sending' | 'submitted' | 'error'
   transactionType: 'b2c_outbound',
+  complianceEnrollmentId: enrollment.id, // optional: one enrollment only
+  country: 'FR', // optional: one country only
   page: 1,
   perPage: 25,
 });
@@ -596,6 +640,119 @@ for (const row of stats.byCountry) {
 }
 ```
 
+### 🇳🇴 E-Invoicing Norway (EHF / Peppol)
+
+Send EHF e-invoices and credit notes (Peppol BIS Billing 3.0) to Norwegian buyers. The
+`e_invoicing` service for Norway is billed separately from French e-reporting (one-off setup
+fee + per document) — ask for it via `requestEReportingAccess({ service: 'e_invoicing', countries: ['NO'] })`.
+
+**1. Registry lookup** — resolve an organisation number, `NO…MVA` VAT number or company name in
+the Brønnøysund register (rate-limited to 30 requests/minute; 404 when nothing is found):
+
+```ts
+import { NorwegianOrgNumber } from '@taxora/sdk';
+
+const [company] = await client.eReporting.registryLookup('NO', '923609016');
+console.log(company.companyName, company.vatNumber, company.vatRegistered, company.enterpriseRegister);
+
+// Client-side helper (mod-11 check digit, accepts spaces / NO prefix / MVA suffix)
+NorwegianOrgNumber.isValid('NO 923 609 016 MVA'); // true
+NorwegianOrgNumber.normalize('923609016MVA'); // '923609016'
+NorwegianOrgNumber.toVatNumber('923609016'); // 'NO923609016MVA'
+```
+
+**2. Enrollment** — registers your company as a Peppol participant. The organisation number is
+validated and normalized before sending:
+
+```ts
+const noEnrollment = await client.eReporting.createNorwayEnrollment({
+  orgNumber: company.orgNumber,
+  companyName: company.companyName,
+  address: company.address!,
+  city: company.city!,
+  postalcode: company.postalcode!,
+  email: 'faktura@acme.no',
+  vatRegistered: company.vatRegistered, // optional, default true → "MVA" on invoices
+  enterpriseRegister: company.enterpriseRegister, // optional, default false → "Foretaksregisteret"
+  reception: false, // optional: also receive e-invoices over Peppol
+});
+// Equivalent: client.eReporting.createEnrollment({ country: 'NO', ... })
+
+console.log(noEnrollment.service, noEnrollment.regime); // 'e_invoicing' 'peppol_bis3'
+```
+
+**3. Peppol lookup** — check that the buyer can receive EHF invoices (free of charge). The
+directory resolves asynchronously: `pending` means ask again in a few seconds.
+
+```ts
+let reach = await client.eReporting.peppolLookup('NO', '974760673'); // scheme defaults to 0192
+if (reach.isPending) {
+  await new Promise((r) => setTimeout(r, 3000));
+  reach = await client.eReporting.peppolLookup('NO', '974760673');
+}
+console.log(reach.status, reach.reachable, reach.documentTypes); // 'reachable' true [...]
+```
+
+**4. Send an invoice** — Norway requires `transactionType: 'b2b_domestic_outbound'`, the buyer's
+organisation number (`counterpartyRegisterId`) and `counterpartyName` (enforced server-side, 422):
+
+```ts
+const invoice = await client.eReporting.createTransaction({
+  complianceEnrollmentId: noEnrollment.id,
+  transactionType: 'b2b_domestic_outbound',
+  invoiceNumber: 'NO-2026-0001',
+  invoiceDate: '2026-09-25',
+  dueDate: '2026-10-09',
+  currency: 'NOK',
+  subtotal: 2000,
+  taxAmount: 500,
+  total: 2500,
+  counterpartyName: 'EXAMPLE BUYER AS',
+  counterpartyCountry: 'NO',
+  counterpartyRegisterId: '974760673',
+  counterpartyAddress: 'Storgata 1',
+  counterpartyCity: 'Oslo',
+  counterpartyPostalcode: '0155',
+  counterpartyEmail: 'ap@buyer.example', // optional
+  buyerReference: 'PO-4711', // optional, defaults to the buyer's org number
+  invoiceLines: [
+    { description: 'Consulting', quantity: 2, price: 1000, taxes: [{ name: 'MVA', percent: 25, category: 'S' }] },
+  ],
+});
+
+// `state` tracks submission; `providerState` the Peppol delivery (e.g. sent, accepted, refused, paid)
+const current = await client.eReporting.getTransaction(invoice.id);
+console.log(current.state, current.providerState, current.documentType); // … 'invoice'
+```
+
+**5. Send a credit note** — set `isCreditNote` and reference the corrected invoice:
+
+```ts
+const creditNote = await client.eReporting.createTransaction({
+  complianceEnrollmentId: noEnrollment.id,
+  transactionType: 'b2b_domestic_outbound',
+  invoiceNumber: 'NO-2026-0001-CN',
+  invoiceDate: '2026-09-30',
+  currency: 'NOK',
+  subtotal: 1000,
+  taxAmount: 250,
+  total: 1250,
+  counterpartyName: 'EXAMPLE BUYER AS',
+  counterpartyRegisterId: '974760673',
+  isCreditNote: true,
+  amendedNumber: 'NO-2026-0001', // required for credit notes in Norway
+  amendedDate: '2026-09-25',
+  extraInfo: 'Credit for one returned consulting day',
+  invoiceLines: [
+    { description: 'Consulting', quantity: 1, price: 1000, taxes: [{ name: 'MVA', percent: 25, category: 'S' }] },
+  ],
+});
+console.log(creditNote.isCreditNote); // true
+
+// All Norwegian documents
+const noDocs = await client.eReporting.listTransactions({ country: 'NO' });
+```
+
 ---
 
 ## 📜 Certificates
@@ -668,11 +825,135 @@ try {
     console.error('Validation errors:', err.getErrors()); // Record<string, string[]>
   } else if (err instanceof HttpException) {
     // Any other HTTP error
-    console.error(`HTTP ${err.getStatusCode()}:`, err.getResponseBody());
+    console.error(`HTTP ${err.getStatusCode()}:`, err.message);
   }
 }
 ```
 
+**Exception messages are always short and safe to log.** A response body is
+never used as the message: gateways in front of the API answer `502`/`503`/`504`
+with a full HTML error page, and that page would otherwise land in every log
+line of your application. The SDK uses the `message` / `error` field of a JSON
+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()`.
+
+### Automatic retries
+
+The SDK retries what never produced an answer from the API itself: **3 attempts,
+with 500 ms and 1000 ms of backoff in between**. That covers
+
+- **gateway failures (`502`, `503`, `504`)** — the infrastructure in front of the
+  API, where a second attempt a moment later usually succeeds;
+- **connection-level failures** — reset connections, client-side timeouts, DNS
+  hiccups (`fetch failed`, `ECONNRESET`, `UND_ERR_CONNECT_TIMEOUT`, …). Once the
+  attempts are used up, the original error is rethrown unchanged;
+- **`429 Too Many Requests`, but only with a `Retry-After`** — then the SDK waits
+  exactly as long as the API asked instead of using its own backoff. Without that
+  header a retry would only hammer a rate limit that is already tripped, so the
+  error is surfaced immediately. A `Retry-After` longer than `maxRetryAfterMs`
+  (10 s by default) also fails immediately rather than blocking your worker — the
+  raw header stays readable via `err.getRetryAfter()`.
+
+Everything else fails on the first attempt, including any `5xx` the API produced
+itself (a `500` is a bug, not a hiccup — repeating it just costs time).
+
+Retries apply to read-only calls only — VAT validation, lookups, state, history,
+search, certificate downloads, company and e-reporting reads, login and token
+refresh. Calls that change state or cost quota (`certificatesBulkExport()`,
+`smartEnrichment.lookup()`, e-reporting enrollment/transaction writes) are
+**never** retried automatically, because a gateway timeout does not tell us
+whether the API already processed the request.
+
+Once the attempts are used up you get one clean error:
+
+```
+Taxora VAT validation failed after 3 attempts (HTTP 504 Gateway Timeout).
+```
+
+Tune or disable it via `RetryPolicy`:
+
+```ts
+import { RetryPolicy, TaxoraClientFactory } from '@taxora/sdk';
+
+const client = TaxoraClientFactory.create({
+  apiKey: 'YOUR_X_API_KEY',
+  retryPolicy: new RetryPolicy({
+    maxAttempts: 5,
+    initialDelayMs: 250,
+    retryableStatusCodes: [502, 503, 504], // add or drop status codes
+    respectRetryAfter: true, // false = ignore the header entirely
+    maxRetryAfterMs: 10_000, // longest wait accepted from Retry-After
+    retryOnNetworkErrors: true, // false = surface transport errors at once
+  }),
+});
+
+// or, for callers that do their own retrying (queue workers, cron jobs):
+const noRetries = TaxoraClientFactory.create({ apiKey: '…', retryPolicy: RetryPolicy.disabled() });
+```
+
+---
+
+## 🔐 Webhook Signatures
+
+Taxora can sign every webhook request with HMAC-SHA256 (opt-in per endpoint: dashboard → **Developer → Webhooks**,
+or `POST /v1/webhooks/{id}/signing/enable`). Signed requests carry:
+
+```
+Taxora-Signature: t=1716115200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
+Taxora-Webhook-Id: 550e8400-e29b-41d4-a716-446655440000
+```
+
+`constructWebhookEvent` verifies the signature (constant-time, 5-minute replay window) and returns a typed event:
+
+```ts
+import express from 'express';
+import { constructWebhookEvent, WebhookSignatureVerificationError } from '@taxora/sdk';
+
+const app = express();
+
+// express.raw — NOT express.json: the signature covers the exact bytes Taxora sent.
+app.post('/taxora-webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  let event;
+  try {
+    event = constructWebhookEvent(req.body, req.header('Taxora-Signature'), process.env.TAXORA_WEBHOOK_SECRET!, {
+      tolerance: 300, // seconds, default
+    });
+  } catch (err) {
+    if (err instanceof WebhookSignatureVerificationError) {
+      return res.status(400).send(err.message); // err.reason: 'no_matching_signature' | 'timestamp_outside_tolerance' | …
+    }
+    throw err;
+  }
+
+  switch (event.event) {
+    case 'vat.validated':
+      console.log(event.data.object.vat_uid, event.data.object.state); // typed
+      break;
+    case 'enrichment.completed':
+      console.log(event.data.object.foundCount);
+      break;
+  }
+
+  res.sendStatus(200);
+});
+```
+
+Next.js App Router: `const rawBody = await request.text();` (not `request.json()`).
+
+| Helper                                                                 | Purpose                                                      |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `verifyWebhookSignature(rawBody, header, secret, { tolerance })`       | Returns `true` or throws `WebhookSignatureVerificationError` |
+| `constructWebhookEvent(rawBody, header, secret, { tolerance })`        | Verifies, then parses into `TaxoraWebhookEvent`              |
+| `generateWebhookSignatureHeader(rawBody, secret, timestamp?)`          | Builds a valid header — for testing your own handler         |
+| `parseWebhookSignatureHeader(header)` / `computeWebhookSignature(...)` | Low-level building blocks                                    |
+
+- **Rotation:** while Taxora rotates your secret, requests carry one `v1=` per live secret — any match is accepted.
+  `secret` may also be an array, so you can accept old and new secret on your side during a deploy.
+- **Raw body:** pass a `string`, `Buffer` or `Uint8Array`. Passing an already parsed object throws
+  `reason: 'invalid_body'`.
+- **Idempotency:** dedupe on `event.id` (= `Taxora-Webhook-Id`), which stays the same across retries.
+
 ---
 
 ## 🔌 VatState Helpers