@taxora/sdk 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVer](https://semver.org/).
 
+## [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
+
+- **Smart Enrichment: rejected VAT candidates.** `SmartEnrichmentResource.rejectedCandidates` lists VAT numbers
+  a `not_found` lookup DID find but the official check threw out, each with a `reason`
+  (`SmartEnrichmentRejectionReason`: `vat_invalid`, `name_mismatch`, `unbound`, `unverified`, `rejected`;
+  unknown values map to `unknown`). Lets you tell "found one, it is invalid" apart from "found nothing".
+  Plus `hasRejectedCandidates()`, `toSmartEnrichmentRejectionReason()` and
+  `describeSmartEnrichmentRejectionReason()`.
+
+### Changed
+
+- Bundled OpenAPI specs (`resources/`) refreshed from the current API.
+
 ## [1.3.0] — 2026-10-13
 
 ### Added

package/README.md

@@ -363,6 +363,20 @@ 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'
+
+// '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.
+for (const candidate of result?.rejectedCandidates ?? []) {
+  console.log(candidate.vatNumber, candidate.reason); // e.g. 'vat_invalid'
+}
+
 // 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.

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   SmartEnrichmentHistoryRow: () => SmartEnrichmentHistoryRow,
   SmartEnrichmentJob: () => SmartEnrichmentJob,
   SmartEnrichmentMode: () => SmartEnrichmentMode,
+  SmartEnrichmentRejectionReason: () => SmartEnrichmentRejectionReason,
   SmartEnrichmentResource: () => SmartEnrichmentResource,
   SmartEnrichmentStatistics: () => SmartEnrichmentStatistics,
   SmartEnrichmentStatus: () => SmartEnrichmentStatus,
@@ -91,6 +92,7 @@ __export(index_exports, {
   describeComplianceTransactionType: () => describeComplianceTransactionType,
   describePeppolLookupStatus: () => describePeppolLookupStatus,
   describeSmartEnrichmentMode: () => describeSmartEnrichmentMode,
+  describeSmartEnrichmentRejectionReason: () => describeSmartEnrichmentRejectionReason,
   describeSmartEnrichmentStatus: () => describeSmartEnrichmentStatus,
   describeVatState: () => describeVatState,
   generateWebhookSignatureHeader: () => generateWebhookSignatureHeader,
@@ -105,6 +107,7 @@ __export(index_exports, {
   toComplianceTransactionType: () => toComplianceTransactionType,
   toPeppolLookupStatus: () => toPeppolLookupStatus,
   toSmartEnrichmentMode: () => toSmartEnrichmentMode,
+  toSmartEnrichmentRejectionReason: () => toSmartEnrichmentRejectionReason,
   toSmartEnrichmentStatus: () => toSmartEnrichmentStatus,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
@@ -2336,6 +2339,43 @@ function describeSmartEnrichmentMode(mode) {
   return DESCRIPTIONS8[mode];
 }
 
+// src/enums/SmartEnrichmentRejectionReason.ts
+var SmartEnrichmentRejectionReason = {
+  /** The tax authority reports the number as not (or no longer) valid. */
+  VAT_INVALID: "vat_invalid",
+  /** The number is valid, but registered to a different company. */
+  NAME_MISMATCH: "name_mismatch",
+  /** The number could not be tied to the requested company. */
+  UNBOUND: "unbound",
+  /** The number could not be checked against the tax authority. */
+  UNVERIFIED: "unverified",
+  /** Rejected for another reason. */
+  REJECTED: "rejected",
+  /** A reason this SDK version does not know yet. */
+  UNKNOWN: "unknown"
+};
+var VALUES9 = Object.values(SmartEnrichmentRejectionReason);
+function toSmartEnrichmentRejectionReason(value) {
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (VALUES9.includes(normalized)) {
+      return normalized;
+    }
+  }
+  return SmartEnrichmentRejectionReason.UNKNOWN;
+}
+var DESCRIPTIONS9 = {
+  [SmartEnrichmentRejectionReason.VAT_INVALID]: "The tax authority reports the VAT number as invalid.",
+  [SmartEnrichmentRejectionReason.NAME_MISMATCH]: "The VAT number is registered to a different company.",
+  [SmartEnrichmentRejectionReason.UNBOUND]: "The VAT number could not be tied to the requested company.",
+  [SmartEnrichmentRejectionReason.UNVERIFIED]: "The VAT number could not be verified with the tax authority.",
+  [SmartEnrichmentRejectionReason.REJECTED]: "The VAT number was not confirmed.",
+  [SmartEnrichmentRejectionReason.UNKNOWN]: "Unknown rejection reason."
+};
+function describeSmartEnrichmentRejectionReason(reason) {
+  return DESCRIPTIONS9[reason];
+}
+
 // src/enums/SmartEnrichmentStatus.ts
 var SmartEnrichmentStatus = {
   FOUND: "found",
@@ -2347,17 +2387,17 @@ var SmartEnrichmentStatus = {
   FAILED: "failed",
   UNKNOWN: "unknown"
 };
-var VALUES9 = Object.values(SmartEnrichmentStatus);
+var VALUES10 = Object.values(SmartEnrichmentStatus);
 function toSmartEnrichmentStatus(value) {
   if (typeof value === "string") {
     const normalized = value.trim().toLowerCase();
-    if (VALUES9.includes(normalized)) {
+    if (VALUES10.includes(normalized)) {
       return normalized;
     }
   }
   return SmartEnrichmentStatus.UNKNOWN;
 }
-var DESCRIPTIONS9 = {
+var DESCRIPTIONS10 = {
   [SmartEnrichmentStatus.FOUND]: "A VAT number was resolved and confirmed.",
   [SmartEnrichmentStatus.NO_VAT_EXISTS]: "The company was identified but has no VAT number.",
   [SmartEnrichmentStatus.NOT_FOUND]: "No sufficiently-confident match could be resolved.",
@@ -2368,12 +2408,30 @@ var DESCRIPTIONS9 = {
   [SmartEnrichmentStatus.UNKNOWN]: "Unknown status."
 };
 function describeSmartEnrichmentStatus(status) {
-  return DESCRIPTIONS9[status];
+  return DESCRIPTIONS10[status];
 }
 
 // src/dto/SmartEnrichmentResource.ts
+function toRejectedCandidates(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
+    }
+    const record = entry;
+    const vatNumber = typeof record["vatNumber"] === "string" ? record["vatNumber"].trim() : "";
+    if (vatNumber === "") {
+      continue;
+    }
+    candidates.push({ vatNumber, reason: toSmartEnrichmentRejectionReason(record["reason"]) });
+  }
+  return candidates;
+}
 var SmartEnrichmentResource = class _SmartEnrichmentResource {
-  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source, mode = void 0, providerVerdicts = [], addressQuality = void 0) {
+  constructor(status, vatNumber, vatType, confidence, matchedCompanyName, matchedAddress, country, source, mode = void 0, providerVerdicts = [], addressQuality = void 0, rejectedCandidates = [], sourceUrl = void 0, registeredOwner = void 0, sourceUrls = []) {
     this.status = status;
     this.vatNumber = vatNumber;
     this.vatType = vatType;
@@ -2385,6 +2443,10 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
     this.mode = mode;
     this.providerVerdicts = providerVerdicts;
     this.addressQuality = addressQuality;
+    this.rejectedCandidates = rejectedCandidates;
+    this.sourceUrl = sourceUrl;
+    this.registeredOwner = registeredOwner;
+    this.sourceUrls = sourceUrls;
   }
   status;
   vatNumber;
@@ -2397,11 +2459,26 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
   mode;
   providerVerdicts;
   addressQuality;
+  rejectedCandidates;
+  sourceUrl;
+  registeredOwner;
+  sourceUrls;
+  /** True when a VAT number was found but rejected by the official check. */
+  hasRejectedCandidates() {
+    return this.rejectedCandidates.length > 0;
+  }
   static fromArray(data) {
     const str = (key) => {
       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;
@@ -2419,7 +2496,11 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       str("source"),
       toSmartEnrichmentMode(data["mode"]),
       Array.isArray(verdicts) ? verdicts.filter((v) => typeof v === "object" && v !== null) : [],
-      typeof quality === "object" && quality !== null ? quality : void 0
+      typeof quality === "object" && quality !== null ? quality : void 0,
+      toRejectedCandidates(data["rejectedCandidates"]),
+      url && isWebUrl(url) ? url : void 0,
+      text("registeredOwner"),
+      Array.isArray(urls) ? [...new Set(urls.filter(isWebUrl).map((u) => u.trim()))] : []
     );
   }
   toArray() {
@@ -2434,7 +2515,11 @@ var SmartEnrichmentResource = class _SmartEnrichmentResource {
       source: this.source ?? null,
       mode: this.mode ?? null,
       providerVerdicts: this.providerVerdicts,
-      addressQuality: this.addressQuality ?? null
+      addressQuality: this.addressQuality ?? null,
+      rejectedCandidates: this.rejectedCandidates.map((c) => ({ vatNumber: c.vatNumber, reason: c.reason })),
+      sourceUrl: this.sourceUrl ?? null,
+      registeredOwner: this.registeredOwner ?? null,
+      sourceUrls: this.sourceUrls
     };
   }
 };
@@ -2973,14 +3058,14 @@ var VatState = {
 function getFailedVatStates() {
   return [VatState.INVALID, VatState.FRAUD];
 }
-var DESCRIPTIONS10 = {
+var DESCRIPTIONS11 = {
   [VatState.VALID]: "The VAT number is valid and active.",
   [VatState.INVALID]: "The VAT number is invalid or not registered.",
   [VatState.FRAUD]: "The VAT number has been flagged as potentially fraudulent.",
   [VatState.UNKNOWN]: "The VAT number state could not be determined."
 };
 function describeVatState(state) {
-  return DESCRIPTIONS10[state];
+  return DESCRIPTIONS11[state];
 }
 
 // src/dto/CompanyAddress.ts
@@ -3712,7 +3797,7 @@ var AuthRetryHttpClient = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.3.0";
+var SDK_VERSION = "1.5.0";
 
 // src/http/SdkVersionHttpClient.ts
 var SDK_VERSION_HEADER = "X-Taxora-SDK-Version";
@@ -3942,6 +4027,7 @@ function toBytes(rawBody) {
   SmartEnrichmentHistoryRow,
   SmartEnrichmentJob,
   SmartEnrichmentMode,
+  SmartEnrichmentRejectionReason,
   SmartEnrichmentResource,
   SmartEnrichmentStatistics,
   SmartEnrichmentStatus,
@@ -3971,6 +4057,7 @@ function toBytes(rawBody) {
   describeComplianceTransactionType,
   describePeppolLookupStatus,
   describeSmartEnrichmentMode,
+  describeSmartEnrichmentRejectionReason,
   describeSmartEnrichmentStatus,
   describeVatState,
   generateWebhookSignatureHeader,
@@ -3985,6 +4072,7 @@ function toBytes(rawBody) {
   toComplianceTransactionType,
   toPeppolLookupStatus,
   toSmartEnrichmentMode,
+  toSmartEnrichmentRejectionReason,
   toSmartEnrichmentStatus,
   verifyWebhookSignature
 });