@taxora/sdk 1.1.0 → 1.2.0

package/README.md

@@ -331,7 +331,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' },
@@ -668,11 +696,73 @@ 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() });
+```
+
 ---
 
 ## 🔌 VatState Helpers