@taxora/sdk 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVer](https://semver.org/).
 
+## [1.7.0] — 2026-10-24
+
+### Added
+
+- **Smart Enrichment: `taxNumberType`, `taxNumberLabel`, `taxNumberSource`** next to `taxNumber`. `taxNumber` is now
+  the company's local tax / business number: on `found` it is read off the confirmed VAT ID where that country's
+  VAT ID contains it (`taxNumberSource` = `'vat_id'`: FR SIREN, IT Partita IVA, ES NIF, PL NIP, BE enterprise
+  number, DK CVR, PT, RO, CZ IČO, SK DIČ, SE/NO orgnr, FI Y-tunnus, SI, HR OIB, BG EIK, GR AFM), otherwise a
+  domestic number the company published (`'company_website'`, e.g. a DE/AT Steuernummer — not a VAT ID).
+  `taxNumberType` is the code (`pl_nip`, `fr_siren`, `de_steuernummer` …), `taxNumberLabel` its national name.
+  New type `SmartEnrichmentTaxNumberSource`.
+- **Local tax numbers report** on `client.vat`: `localTaxNumbersCsv()` (raw CSV, UTF-8 with BOM),
+  `localTaxNumbers()` (parsed `LocalTaxNumberRow[]` — BOM dropped, the Excel TAB guard before digit-only tax numbers
+  trimmed, empty cells `null`) and `localTaxNumbersSummary()` (`{ companies, withTaxNumber }`). Filters: `dateFrom`,
+  `dateTo`, `countries`, `onlyWithTaxNumber`. `parseLocalTaxNumbersCsv()` parses a saved file.
+
+### Changed
+
+- Bundled OpenAPI specs (`resources/`) refreshed from the current API.
+
+## [1.6.0] — 2026-10-22
+
+### Added
+
+- **Smart Enrichment: `taxNumber`** — a domestic tax number (e.g. a German Steuernummer) a company's page shows
+  instead of a VAT ID. It is not a VAT ID; the lookup stays `not_found`.
+- **Smart Enrichment: the official VAT check behind a found number** — `vatValid`, `aiScore`, `nameMatch`
+  (`'ok' | 'mismatch'`, plus `nameMismatch()`), `officialName` and `officialAddress`
+  (`SmartEnrichmentOfficialAddress`). Lets you write the register's name and address back into your records.
+
+### Changed
+
+- Bundled OpenAPI specs (`resources/`) refreshed from the current API.
+
 ## [1.5.0] — 2026-10-22
 
 ### Added

package/README.md

@@ -307,6 +307,39 @@ const results = await client.vat.search('Alpha Handels', 25 /* perPage */);
 
 ---
 
+## 🧾 Local tax numbers report
+
+Every company you checked — single and bulk VAT checks and Smart Enrichment lookups — once, with its **local tax
+number** (NIP, SIREN, Partita IVA, Steuernummer …), the number's national name and where it comes from (`vat_id` =
+read off the confirmed VAT ID, `company_website` = published by the company). All filters are optional.
+
+```typescript
+import { parseLocalTaxNumbersCsv } from '@taxora/sdk';
+import { writeFileSync } from 'node:fs';
+
+// Parsed rows (BOM dropped, cells trimmed, empty cells null)
+const rows = await client.vat.localTaxNumbers({
+  dateFrom: '2026-10-01', // optional (YYYY-MM-DD or Date)
+  dateTo: '2026-10-31', // optional
+  countries: ['PL', 'IT'], // optional (ISO-2)
+  onlyWithTaxNumber: true, // optional: skip companies without one
+});
+for (const row of rows) {
+  // e.g. Orlen S.A. PL 5260250995 (NIP, vat_id)
+  console.log(`${row.companyName} ${row.country} ${row.taxNumber} (${row.taxNumberName}, ${row.taxNumberSource})`);
+}
+// row.vatStatus: valid | invalid | unconfirmed | wrong_company | no_vat_id | not_found
+// row.source: vat_check | smart_enrichment; row.checkId: the VAT check uuid or the lookup job id
+
+// The raw CSV (UTF-8 with BOM) for a spreadsheet. Digit-only tax numbers carry a leading TAB so
+// Excel keeps leading zeros; parseLocalTaxNumbersCsv() turns a saved file into rows.
+writeFileSync('local-tax-numbers.csv', await client.vat.localTaxNumbersCsv({ countries: ['PL'] }));
+
+// Counts for the same filters
+const summary = await client.vat.localTaxNumbersSummary({ dateFrom: '2026-10-01' });
+console.log(`${summary.withTaxNumber} of ${summary.companies} companies have a local tax number`);
+```
+
 ## 🔎 Smart Enrichment (reverse VAT lookup)
 
 Resolve a company **name + address + country → VAT number + confidence**. A confident match
@@ -370,6 +403,23 @@ console.log(result?.sourceUrl ?? '—'); // e.g. 'https://example.de/impressum'
 console.log(result?.sourceUrls.join(', ')); // every page it was found on, main one first
 console.log(result?.registeredOwner ?? '—'); // e.g. 'Kevin Seibel'
 
+// The official VAT check behind a found number. nameMatch 'mismatch' means the register has the
+// number under a different name — another company, unless `registeredOwner` is set (an e.K. filed
+// under its owner): then write officialName / officialAddress into your own records.
+if (result?.nameMismatch()) {
+  console.log(result.officialName, result.officialAddress);
+}
+
+// `taxNumber` is the company's LOCAL tax / business number — what domestic e-invoicing asks for.
+// On 'found' it is read off the confirmed VAT ID where that country's VAT ID contains it
+// (taxNumberSource 'vat_id': FR SIREN, IT Partita IVA, ES NIF, PL NIP, BE, DK CVR, CZ IČO, …).
+// Otherwise it is a number the company published itself ('company_website', e.g. a German
+// Steuernummer shown under the VAT ID heading) — that one is not a VAT ID.
+console.log(result?.taxNumber ?? '—'); // e.g. '5260250995'
+console.log(result?.taxNumberType ?? '—'); // e.g. 'pl_nip', 'fr_siren', 'de_steuernummer'
+console.log(result?.taxNumberLabel ?? '—'); // e.g. 'NIP'
+console.log(result?.taxNumberSource ?? '—'); // 'vat_id' | 'company_website'
+
 // 'not_found' doesn't always mean nothing turned up. When the research found a VAT number but
 // the official check threw it out (e.g. the tax authority reports it as invalid), the number
 // and the reason are in `rejectedCandidates` — no need to re-check it yourself.

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   ImportResult: () => ImportResult,
   InMemoryTokenStorage: () => InMemoryTokenStorage,
   Language: () => Language,
+  LocalTaxNumberRow: () => LocalTaxNumberRow,
   LoginIdentifier: () => LoginIdentifier,
   NorwegianOrgNumber: () => NorwegianOrgNumber,
   PeppolLookupResult: () => PeppolLookupResult,
@@ -98,6 +99,7 @@ __export(index_exports, {
   generateWebhookSignatureHeader: () => generateWebhookSignatureHeader,
   getBaseUrl: () => getBaseUrl,
   getFailedVatStates: () => getFailedVatStates,
+  parseLocalTaxNumbersCsv: () => parseLocalTaxNumbersCsv,
   parseWebhookSignatureHeader: () => parseWebhookSignatureHeader,
   toComplianceDocumentType: () => toComplianceDocumentType,
   toComplianceEnrollmentStatus: () => toComplianceEnrollmentStatus,
@@ -2430,8 +2432,22 @@ function toRejectedCandidates(value) {
   }
   return candidates;
 }
+function toOfficialAddress(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return void 0;
+  }
+  const record = value;
+  const address = {};
+  for (const key of ["street", "postal_code", "city", "country"]) {
+    const part = typeof record[key] === "string" ? record[key].trim() : "";
+    if (part !== "") {
+      address[key] = part;
+    }
+  }
+  return Object.keys(address).length > 0 ? address : void 0;
+}
 var SmartEnrichmentResource = class _SmartEnrichmentResource {
-  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source, mode = void 0, providerVerdicts = [], addressQuality = void 0, rejectedCandidates = [], sourceUrl = void 0, registeredOwner = void 0, sourceUrls = []) {
+  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source, mode = void 0, providerVerdicts = [], addressQuality = void 0, rejectedCandidates = [], sourceUrl = void 0, registeredOwner = void 0, sourceUrls = [], taxNumber = void 0, vatValid = void 0, aiScore = void 0, nameMatch = void 0, officialName = void 0, officialAddress = void 0, taxNumberType = void 0, taxNumberLabel = void 0, taxNumberSource = void 0) {
     this.status = status;
     this.vatNumber = vatNumber;
     this.vatType = vatType;
@@ -2447,6 +2463,15 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
     this.sourceUrl = sourceUrl;
     this.registeredOwner = registeredOwner;
     this.sourceUrls = sourceUrls;
+    this.taxNumber = taxNumber;
+    this.vatValid = vatValid;
+    this.aiScore = aiScore;
+    this.nameMatch = nameMatch;
+    this.officialName = officialName;
+    this.officialAddress = officialAddress;
+    this.taxNumberType = taxNumberType;
+    this.taxNumberLabel = taxNumberLabel;
+    this.taxNumberSource = taxNumberSource;
   }
   status;
   vatNumber;
@@ -2463,6 +2488,19 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
   sourceUrl;
   registeredOwner;
   sourceUrls;
+  taxNumber;
+  vatValid;
+  aiScore;
+  nameMatch;
+  officialName;
+  officialAddress;
+  taxNumberType;
+  taxNumberLabel;
+  taxNumberSource;
+  /** True when the register knows the number under a different name than the one requested. */
+  nameMismatch() {
+    return this.nameMatch === "mismatch";
+  }
   /** True when a VAT number was found but rejected by the official check. */
   hasRejectedCandidates() {
     return this.rejectedCandidates.length > 0;
@@ -2500,7 +2538,16 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       toRejectedCandidates(data["rejectedCandidates"]),
       url && isWebUrl(url) ? url : void 0,
       text("registeredOwner"),
-      Array.isArray(urls) ? [...new Set(urls.filter(isWebUrl).map((u) => u.trim()))] : []
+      Array.isArray(urls) ? [...new Set(urls.filter(isWebUrl).map((u) => u.trim()))] : [],
+      text("taxNumber"),
+      typeof data["vatValid"] === "boolean" ? data["vatValid"] : void 0,
+      num("aiScore"),
+      data["nameMatch"] === "ok" || data["nameMatch"] === "mismatch" ? data["nameMatch"] : void 0,
+      text("officialName"),
+      toOfficialAddress(data["officialAddress"]),
+      text("taxNumberType"),
+      text("taxNumberLabel"),
+      data["taxNumberSource"] === "vat_id" || data["taxNumberSource"] === "company_website" ? data["taxNumberSource"] : void 0
     );
   }
   toArray() {
@@ -2519,7 +2566,16 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       rejectedCandidates: this.rejectedCandidates.map((c) => ({ vatNumber: c.vatNumber, reason: c.reason })),
       sourceUrl: this.sourceUrl ?? null,
       registeredOwner: this.registeredOwner ?? null,
-      sourceUrls: this.sourceUrls
+      sourceUrls: this.sourceUrls,
+      taxNumber: this.taxNumber ?? null,
+      vatValid: this.vatValid ?? null,
+      aiScore: this.aiScore ?? null,
+      nameMatch: this.nameMatch ?? null,
+      officialName: this.officialName ?? null,
+      officialAddress: this.officialAddress ?? null,
+      taxNumberType: this.taxNumberType ?? null,
+      taxNumberLabel: this.taxNumberLabel ?? null,
+      taxNumberSource: this.taxNumberSource ?? null
     };
   }
 };
@@ -3527,6 +3583,123 @@ var VatValidationAddressInput = class _VatValidationAddressInput {
   }
 };
 
+// src/dto/LocalTaxNumberReport.ts
+var LocalTaxNumberRow = class _LocalTaxNumberRow {
+  constructor(companyName, requestedName, country, vatNumber, vatStatus, taxNumber, taxNumberName, taxNumberSource, source, checkedAt, checkId) {
+    this.companyName = companyName;
+    this.requestedName = requestedName;
+    this.country = country;
+    this.vatNumber = vatNumber;
+    this.vatStatus = vatStatus;
+    this.taxNumber = taxNumber;
+    this.taxNumberName = taxNumberName;
+    this.taxNumberSource = taxNumberSource;
+    this.source = source;
+    this.checkedAt = checkedAt;
+    this.checkId = checkId;
+  }
+  companyName;
+  requestedName;
+  country;
+  vatNumber;
+  vatStatus;
+  taxNumber;
+  taxNumberName;
+  taxNumberSource;
+  source;
+  checkedAt;
+  checkId;
+  /** One CSV row keyed by column name. */
+  static fromArray(data) {
+    const cell = (key) => {
+      const value = data[key];
+      const trimmed = typeof value === "string" ? value.trim() : "";
+      return trimmed === "" ? null : trimmed;
+    };
+    return new _LocalTaxNumberRow(
+      cell("companyName"),
+      cell("requestedName"),
+      cell("country"),
+      cell("vatNumber"),
+      cell("vatStatus"),
+      cell("taxNumber"),
+      cell("taxNumberName"),
+      cell("taxNumberSource"),
+      cell("source"),
+      cell("checkedAt"),
+      cell("checkId")
+    );
+  }
+  toArray() {
+    return {
+      companyName: this.companyName,
+      requestedName: this.requestedName,
+      country: this.country,
+      vatNumber: this.vatNumber,
+      vatStatus: this.vatStatus,
+      taxNumber: this.taxNumber,
+      taxNumberName: this.taxNumberName,
+      taxNumberSource: this.taxNumberSource,
+      source: this.source,
+      checkedAt: this.checkedAt,
+      checkId: this.checkId
+    };
+  }
+};
+function parseCsvRecords(csv) {
+  const records = [];
+  let record = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < csv.length; i++) {
+    const ch = csv[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (csv[i + 1] === '"') {
+          cell += '"';
+          i++;
+        } else {
+          quoted = false;
+        }
+      } else {
+        cell += ch;
+      }
+    } else if (ch === '"') {
+      quoted = true;
+    } else if (ch === ",") {
+      record.push(cell);
+      cell = "";
+    } else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && csv[i + 1] === "\n") i++;
+      record.push(cell);
+      records.push(record);
+      record = [];
+      cell = "";
+    } else {
+      cell += ch;
+    }
+  }
+  if (cell !== "" || record.length > 0) {
+    record.push(cell);
+    records.push(record);
+  }
+  return records.filter((r) => !(r.length === 1 && r[0] === ""));
+}
+function parseLocalTaxNumbersCsv(csv) {
+  const [header, ...records] = parseCsvRecords(csv.replace(/^\uFEFF/, ""));
+  if (!header) {
+    return [];
+  }
+  const names = header.map((name) => name.trim());
+  return records.map((cells) => {
+    const row = {};
+    names.forEach((name, i) => {
+      row[name] = cells[i];
+    });
+    return LocalTaxNumberRow.fromArray(row);
+  });
+}
+
 // src/endpoints/VatEndpoint.ts
 var DATE_REGEX2 = /^\d{4}-\d{2}-\d{2}$/;
 var VatEndpoint = class {
@@ -3637,6 +3810,69 @@ var VatEndpoint = class {
       return new Uint8Array(buffer);
     });
   }
+  /**
+   * Local tax numbers report as raw CSV (UTF-8 with BOM, comma-separated): every company checked —
+   * single and bulk VAT checks and Smart Enrichment lookups — once, with its local tax number
+   * (taxNumber, taxNumberName, taxNumberSource). Digit-only taxNumber cells carry a leading TAB so
+   * Excel keeps them as text; `localTaxNumbers()` strips it for you.
+   */
+  async localTaxNumbersCsv(options = {}) {
+    const params = this.localTaxNumbersParams(options);
+    if (options.onlyWithTaxNumber !== void 0) {
+      params.set("only_with_tax_number", options.onlyWithTaxNumber ? "1" : "0");
+    }
+    const url = this.withQuery(`${this.baseUrl}/reports/local-tax-numbers`, params);
+    return withRetries(this.retryPolicy, "Local tax numbers report", async () => {
+      const headers = this.buildHeaders();
+      delete headers["Content-Type"];
+      headers["Accept"] = "text/csv, application/json";
+      const response = await this.httpClient.request("GET", url, { headers });
+      if (response.status === 422) {
+        await this.parseJsonResponse(response);
+      }
+      const text = new TextDecoder("utf-8", { ignoreBOM: true }).decode(await response.arrayBuffer());
+      if (!response.ok) {
+        throw new HttpException(
+          describeApiError(text, response.status),
+          response.status,
+          text,
+          {},
+          response.headers.get("retry-after")
+        );
+      }
+      return text;
+    });
+  }
+  /** The local tax numbers report, parsed: one row per company (same filters as `localTaxNumbersCsv()`). */
+  async localTaxNumbers(options = {}) {
+    return parseLocalTaxNumbersCsv(await this.localTaxNumbersCsv(options));
+  }
+  /** How many companies the report would list for the filters, and how many have a tax number. */
+  async localTaxNumbersSummary(options = {}) {
+    const url = this.withQuery(
+      `${this.baseUrl}/reports/local-tax-numbers/summary`,
+      this.localTaxNumbersParams(options)
+    );
+    return withRetries(this.retryPolicy, "Local tax numbers summary", async () => {
+      const response = await this.sendRequest("GET", url);
+      const data = await this.parseJsonResponse(response);
+      const count = (key) => typeof data[key] === "number" ? data[key] : 0;
+      return { companies: count("companies"), withTaxNumber: count("withTaxNumber") };
+    });
+  }
+  localTaxNumbersParams(options) {
+    const params = new URLSearchParams();
+    if (options.dateFrom !== void 0) params.set("date_from", this.formatDate(options.dateFrom));
+    if (options.dateTo !== void 0) params.set("date_to", this.formatDate(options.dateTo));
+    for (const country of options.countries ?? []) {
+      params.append("countries[]", country.trim().toUpperCase());
+    }
+    return params;
+  }
+  withQuery(url, params) {
+    const queryString = params.toString();
+    return queryString ? `${url}?${queryString}` : url;
+  }
   buildHeaders() {
     const headers = {
       "Content-Type": "application/json",
@@ -3797,7 +4033,7 @@ var AuthRetryHttpClient = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.5.0";
+var SDK_VERSION = "1.7.0";
 
 // src/http/SdkVersionHttpClient.ts
 var SDK_VERSION_HEADER = "X-Taxora-SDK-Version";
@@ -4011,6 +4247,7 @@ function toBytes(rawBody) {
   ImportResult,
   InMemoryTokenStorage,
   Language,
+  LocalTaxNumberRow,
   LoginIdentifier,
   NorwegianOrgNumber,
   PeppolLookupResult,
@@ -4063,6 +4300,7 @@ function toBytes(rawBody) {
   generateWebhookSignatureHeader,
   getBaseUrl,
   getFailedVatStates,
+  parseLocalTaxNumbersCsv,
   parseWebhookSignatureHeader,
   toComplianceDocumentType,
   toComplianceEnrollmentStatus,