@taxora/sdk 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVer](https://semver.org/).
 
+## [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
+
+- **Smart Enrichment: `sourceUrl` and `registeredOwner`** on `SmartEnrichmentResource`. `sourceUrl` is the page
+  the VAT number was read from (usually the company's Impressum; only http(s) addresses are accepted).
+  `registeredOwner` names the person the tax authority has the VAT ID under when that is not the trading name —
+  typical for a German sole proprietorship (e.K.). `sourceUrls` lists every page the number was read from,
+  `sourceUrl` first (each research pass that found the same number contributes its page).
+
+### Changed
+
+- Bundled OpenAPI specs (`resources/`) refreshed from the current API.
+
 ## [1.4.0] — 2026-10-21
 
 ### Added

package/README.md

@@ -363,6 +363,24 @@ if (quality && quality.warnings.length > 0) {
   console.log(quality.warnings.join(', '), '→', quality.derivedPlace);
 }
 
+// Where the number came from, and who it is registered to. `sourceUrl` is the page it was read
+// from (usually the Impressum). `registeredOwner` is set when the tax authority has the VAT ID
+// under a person rather than the trading name — a German e.K. — and confirmed it for them.
+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);
+}
+
+// A page that shows a tax number (Steuernummer) under the VAT ID heading is not a VAT ID:
+// the lookup stays 'not_found' and the number comes back as `taxNumber`.
+console.log(result?.taxNumber ?? '—');
+
 // '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

@@ -2430,8 +2430,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 = []) {
+  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) {
     this.status = status;
     this.vatNumber = vatNumber;
     this.vatType = vatType;
@@ -2444,6 +2458,15 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
     this.providerVerdicts = providerVerdicts;
     this.addressQuality = addressQuality;
     this.rejectedCandidates = rejectedCandidates;
+    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;
   }
   status;
   vatNumber;
@@ -2457,6 +2480,19 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
   providerVerdicts;
   addressQuality;
   rejectedCandidates;
+  sourceUrl;
+  registeredOwner;
+  sourceUrls;
+  taxNumber;
+  vatValid;
+  aiScore;
+  nameMatch;
+  officialName;
+  officialAddress;
+  /** 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;
@@ -2466,6 +2502,13 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       const v = data[key];
       return typeof v === "string" ? v : void 0;
     };
+    const text = (key) => {
+      const v = str(key)?.trim();
+      return v ? v : void 0;
+    };
+    const isWebUrl = (value) => typeof value === "string" && /^https?:\/\/\S+$/i.test(value.trim());
+    const url = text("sourceUrl");
+    const urls = data["sourceUrls"];
     const num = (key) => {
       const v = data[key];
       return typeof v === "number" ? v : void 0;
@@ -2484,7 +2527,16 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       toSmartEnrichmentMode(data["mode"]),
       Array.isArray(verdicts) ? verdicts.filter((v) => typeof v === "object" && v !== null) : [],
       typeof quality === "object" && quality !== null ? quality : void 0,
-      toRejectedCandidates(data["rejectedCandidates"])
+      toRejectedCandidates(data["rejectedCandidates"]),
+      url && isWebUrl(url) ? url : void 0,
+      text("registeredOwner"),
+      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"])
     );
   }
   toArray() {
@@ -2500,7 +2552,16 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       mode: this.mode ?? null,
       providerVerdicts: this.providerVerdicts,
       addressQuality: this.addressQuality ?? null,
-      rejectedCandidates: this.rejectedCandidates.map((c) => ({ vatNumber: c.vatNumber, reason: c.reason }))
+      rejectedCandidates: this.rejectedCandidates.map((c) => ({ vatNumber: c.vatNumber, reason: c.reason })),
+      sourceUrl: this.sourceUrl ?? null,
+      registeredOwner: this.registeredOwner ?? null,
+      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
     };
   }
 };
@@ -3778,7 +3839,7 @@ var AuthRetryHttpClient = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.4.0";
+var SDK_VERSION = "1.6.0";
 
 // src/http/SdkVersionHttpClient.ts
 var SDK_VERSION_HEADER = "X-Taxora-SDK-Version";