@taxora/sdk 1.0.7 → 1.2.0

package/README.md

@@ -301,6 +301,331 @@ const results = await client.vat.search('Alpha Handels', 25 /* perPage */);
 
 ---
 
+## 🔎 Smart Enrichment (reverse VAT lookup)
+
+Resolve a company **name + address + country → VAT number + confidence**. A confident match
+returns synchronously; harder cases (and all bulk batches) are processed asynchronously and
+delivered via the `enrichment.completed` webhook — poll with `get(jobId)` in the meantime.
+Requires the Smart Enrichment add-on to be active on your account.
+
+```ts
+// Single lookup
+let job = await client.smartEnrichment.lookup({
+  companyName: 'Example Company GmbH',
+  country: 'AT',
+  street: 'Main Street 10',
+  postalCode: '1010',
+  city: 'Vienna',
+});
+
+if (job.isProcessing()) {
+  // Resolved asynchronously — poll until done (or wait for the webhook)
+  job = await client.smartEnrichment.waitForCompletion(job.jobId, {
+    pollIntervalMs: 2000, // optional, default 2000
+    timeoutMs: 120_000, // optional, default 120000 — throws TaxoraException on timeout
+  });
+}
+
+const result = job.result();
+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' },
+]);
+const done = await client.smartEnrichment.waitForCompletion(bulk.jobId);
+for (const r of done.results) {
+  console.log(r.status, r.vatNumber ?? '—', r.matchedAddress ?? '');
+}
+
+// Lookup history (paginated, newest first; perPage is capped at 100 server-side)
+const history = await client.smartEnrichment.history(1, 25, 'Example GmbH' /* optional free-text search */);
+console.log(`${history.total} lookups`);
+console.log(history.stats?.total, history.stats?.found); // account-wide tiles (independent of the search filter)
+for (const row of history) {
+  console.log(row.queryCompanyName, '→', row.result?.vatNumber ?? row.status);
+}
+```
+
+### Quota usage & billing history
+
+```ts
+const usage = await client.smartEnrichment.usage();
+console.log(usage.period, `${usage.used}/${usage.included}`, 'remaining:', usage.remaining);
+console.log(usage.overageCount, '×', usage.overagePrice, '=', usage.overageAmount);
+for (const entry of usage.history) {
+  console.log(entry.period, entry.matches, entry.amount, entry.state); // 'billed' | 'pending'
+}
+```
+
+### CSV export
+
+Download your lookups as CSV in the bulk-input shape plus the resolved VAT columns (bulk jobs
+are flattened to one line per input row). All filters are optional.
+
+```ts
+import { SmartEnrichmentStatus } from '@taxora/sdk';
+import { writeFileSync } from 'fs';
+
+const csv = await client.smartEnrichment.export({
+  dateFrom: '2026-01-01', // job created_at lower bound (YYYY-MM-DD)
+  dateTo: '2026-06-30', // job created_at upper bound (YYYY-MM-DD)
+  minConfidence: 80, // 0–100
+  status: [SmartEnrichmentStatus.FOUND, SmartEnrichmentStatus.NO_VAT_EXISTS],
+  onlyFound: true, // only rows that resolved to a VAT number
+});
+writeFileSync('smart-enrichment.csv', csv);
+```
+
+### Statistics
+
+Aggregated lookup statistics: headline totals, a time series and breakdowns by source, outcome
+and confidence band. Defaults to the last 12 months and a monthly interval (server-side).
+
+```ts
+const stats = await client.smartEnrichment.statistics({
+  dateFrom: '2026-01-01', // optional (YYYY-MM-DD)
+  dateTo: '2026-06-30', // optional (YYYY-MM-DD)
+  interval: 'month', // 'day' | 'week' | 'month'
+});
+
+console.log(stats.totals.items, 'items,', stats.totals.found, `found (${stats.totals.foundRate}%)`);
+console.log('avg confidence:', stats.totals.avgConfidence);
+for (const bucket of stats.timeSeries) {
+  console.log(`${bucket.bucket}: ${bucket.found}/${bucket.items}`);
+}
+for (const band of stats.confidenceBuckets) {
+  console.log(band.bucket, band.count); // high / medium / low
+}
+```
+
+> Note: `no_vat_exists` means the company was identified but legitimately has **no** VAT/UID
+> number (common for purely-domestic German firms). It is a definitive answer — not a failure —
+> and is not billed.
+
+---
+
+## 🇫🇷 E-Reporting / Compliance (DGFiP Flux 10)
+
+Full French e-reporting integration: enroll a company with the compliance provider, record and
+submit transactions (individually or via CSV import), and track the resulting DGFiP tax reports.
+All `compliance` routes require an active E-Reporting subscription / feature grant on your
+account — except `requestEReportingAccess()`, which is how you ask for one.
+
+### Request feature activation
+
+Not enabled yet? This route is deliberately **not** gated — it requests activation of the
+E-Reporting feature for your account (the authenticated user's name/email take precedence over
+the form values):
+
+```ts
+await client.eReporting.requestEReportingAccess({
+  company: 'Example GmbH',
+  phone: '+43 660 1234567',
+  message: 'Please activate e-reporting for our account.',
+  language: 'de', // locale of the confirmation mail
+});
+```
+
+### 1. SIRENE lookup (prefill enrollment data)
+
+Resolve company data by SIRET, SIREN or French VAT number via the French SIRENE registry.
+**Rate-limited to 3 requests/minute per user** (protects the external French government API).
+
+```ts
+const company = await client.eReporting.sireneLookup('FR32123456789'); // or a SIRET/SIREN
+
+console.log(company.companyName, company.siret);
+console.log(company.nafCode, company.enterpriseSize); // e.g. "47", "pme"
+```
+
+### 2. Create an enrollment
+
+Creates the local enrollment, provisions the provider account and (by default) activates the
+DGFiP regime. Either `siret` or `siren` is required. On provider failure the API responds 502
+(an `HttpException`) and the enrollment is persisted in an error state for retries.
+
+```ts
+const enrollment = await client.eReporting.createEnrollment({
+  siret: company.siret!, // or siren: company.siren
+  companyName: company.companyName,
+  address: company.address ?? undefined,
+  city: company.city ?? undefined,
+  postalcode: company.postalcode ?? undefined,
+  email: 'tax@acme.fr',
+  nafCode: company.nafCode!, // 2-digit NAF division, e.g. "47"
+  enterpriseSize: 'pme', // 'micro' | 'pme' | 'eti' | 'ge'
+  typeOperation: 'mixed', // 'services' | 'goods' | 'mixed'
+  reportingStartDate: '2026-09-01', // or a Date
+  autoActivate: true, // optional — false creates the account without regime activation
+});
+
+console.log(enrollment.id, enrollment.status, enrollment.statusLabel);
+
+const page = await client.eReporting.listEnrollments(1, 25); // paginated
+const single = await client.eReporting.getEnrollment(enrollment.id);
+```
+
+### 3. Record & submit transactions
+
+Records the transaction and (by default) submits it right away; pass `submitNow: false` to defer.
+Creation is **idempotent** on the invoice's natural key (enrollment, type, invoice number,
+invoice date, counterparty VAT) — a client retry returns the existing transaction instead of
+creating a duplicate.
+
+> **Note:** Immediate per-invoice submission (and `submitTransaction()`) requires the
+> **e-invoicing** feature on your account. In pure e-reporting mode transactions are only
+> recorded here and reported automatically via the aggregated daily ledgers —
+> `submitTransaction()` then returns a 422 `ValidationException` explaining this.
+
+```ts
+const tx = await client.eReporting.createTransaction({
+  complianceEnrollmentId: enrollment.id,
+  transactionType: 'b2c_outbound', // | 'b2b_domestic_outbound' | 'b2b_domestic_inbound'
+  //                                  | 'crossborder_outbound' | 'crossborder_inbound'
+  invoiceNumber: 'TKT-2026-00001',
+  invoiceDate: '2026-07-01', // or a Date
+  currency: 'EUR', // optional, default EUR
+  subtotal: 100,
+  taxAmount: 20,
+  total: 120,
+  invoiceLines: [
+    {
+      description: 'Ticket',
+      quantity: 1,
+      price: 100,
+      taxes: [{ name: 'TVA', percent: 20, category: 'S' }], // category E needs a VATEX `comment`
+    },
+  ],
+  submitNow: false, // record now, submit later
+});
+
+// Submit (or retry) a pending/error transaction later — replays the stored invoice lines
+const submitted = await client.eReporting.submitTransaction(tx.id);
+console.log(submitted.state, submitted.stateLabel); // e.g. "submitted"
+
+// Manage recorded transactions (only `pending` ones can be edited/deleted)
+const transactions = await client.eReporting.listTransactions({
+  dateFrom: '2026-07-01', // or a Date
+  dateTo: '2026-07-31',
+  state: 'pending', // 'pending' | 'sending' | 'submitted' | 'error'
+  transactionType: 'b2c_outbound',
+  page: 1,
+  perPage: 25,
+});
+const one = await client.eReporting.getTransaction(tx.id);
+await client.eReporting.updateTransaction(tx.id, { total: 130, taxAmount: 21.67 });
+await client.eReporting.deleteTransaction(tx.id); // resolves void on 204
+```
+
+### CSV import
+
+Bulk-import from a semicolon-separated CSV (one row per invoice line; rows sharing an
+`invoice_number` are grouped into one transaction). Idempotent: re-uploading skips rows whose
+invoice already exists.
+
+```ts
+import { readFileSync } from 'fs';
+
+const result = await client.eReporting.importTransactions(
+  enrollment.id,
+  readFileSync('transactions.csv', 'utf8'),
+  'transactions.csv', // optional filename
+);
+
+console.log(result.created, result.skippedDuplicates);
+for (const error of result.errors) console.warn(error); // row-level errors
+```
+
+### 4. Track tax reports
+
+Every submitted transaction is tracked through the aggregated DGFiP ledger lifecycle
+(`new → sent → acknowledged → registered` or `refused`/`error`).
+
+```ts
+const reports = await client.eReporting.listTaxReports(1, 25, 'refused'); // state filter optional
+for (const report of reports) {
+  console.log(report.state, report.stateLabel, report.isTerminal, report.refusalReason);
+}
+
+const report = await client.eReporting.getTaxReport(reports.rows[0]!.id);
+console.log(report.baseAmount, report.taxAmount, report.totalAmount); // precision-safe strings
+```
+
+### VAT rates & DGFiP tax categories
+
+The canonical rates for a reporting country (the seller's reporting-country rates). Use these to
+build the `taxes` entries of your invoice lines.
+
+```ts
+const rates = await client.eReporting.getVatRates('FR'); // defaults to FR when omitted
+
+for (const rate of rates.rates) {
+  console.log(rate.percent, rate.category, rate.taxName, rate.requiresVatex);
+  // 20 'S' 'TVA' false … 0 'E' 'TVA' true (VATEX code required in the line's comment)
+}
+```
+
+### Revenue statistics
+
+Read-only turnover aggregation over your e-reporting transactions — totals, a time series and
+breakdowns by transaction type, counterparty country and state. All headline figures are
+expressed in the most frequent currency in the range (`primaryCurrency`); when more than one
+currency is present, `isMultiCurrency` is `true` and `byCurrency` lists each one. Monetary values
+are returned as 4-decimal strings to preserve precision.
+
+```typescript
+const stats = await client.eReporting.getRevenueStatistics({
+  dateFrom: '2026-01-01', // optional — defaults to 12 months ago (server-side)
+  dateTo: new Date(), // optional — defaults to today
+  interval: 'month', // 'day' | 'week' | 'month' (default 'month')
+  transactionType: 'b2c_outbound', // optional filter
+  state: 'submitted', // optional filter
+});
+
+console.log(stats.primaryCurrency); // e.g. EUR
+console.log(stats.totals.total); // e.g. 120000.0000
+for (const bucket of stats.timeSeries) {
+  console.log(`${bucket.bucket}: ${bucket.total}`); // 2026-01: 10800.0000
+}
+for (const row of stats.byCountry) {
+  console.log(`${row.country} → ${row.total}`); // 'unknown' groups NULL partners
+}
+```
+
+---
+
 ## 📜 Certificates
 
 ### Single Certificate (PDF)
@@ -371,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