@beliq/sdk 0.3.0 → 0.4.0

package/README.md

@@ -26,13 +26,33 @@ const account = await beliq.me();
 const generated = await beliq.generate({
   standard: 'xrechnung',
   verify: true,
+  // The XRechnung CIUS asks for more than plain EN 16931: a seller contact
+  // (BR-DE-2), payment instructions (BR-DE-1), a VAT breakdown (BR-CO-18) and an
+  // electronic address for each party. examples/invoice.json is this same shape.
   invoice: {
     number: 'INV-2026-001',
     issueDate: '2026-01-15',
     currencyCode: 'EUR',
-    seller: { name: 'Seller GmbH', address: { city: 'Berlin', postalCode: '10115', countryCode: 'DE' } },
-    buyer: { name: 'Buyer GmbH', address: { city: 'Munich', postalCode: '80331', countryCode: 'DE' } },
+    buyerReference: '04011000-12345-06',
+    seller: {
+      name: 'Seller GmbH',
+      vatId: 'DE123456789',
+      contactName: 'Anna Muster',
+      email: 'billing@seller.example',
+      phone: '+49 30 1234567',
+      address: { street: 'Hauptstr. 1', city: 'Berlin', postalCode: '10115', countryCode: 'DE' },
+      peppol: { schemeId: '9930', id: 'DE123456789' },
+    },
+    buyer: {
+      name: 'Buyer GmbH',
+      vatId: 'DE987654321',
+      email: 'ap@buyer.example',
+      address: { street: 'Marktweg 2', city: 'Munich', postalCode: '80331', countryCode: 'DE' },
+      peppol: { schemeId: '9930', id: 'DE987654321' },
+    },
     lines: [{ description: 'Consulting', quantity: 10, unitCode: 'HUR', unitPrice: 100, lineTotal: 1000, vatRate: 19, vatCategoryCode: 'S' }],
+    taxSummary: [{ vatCategoryCode: 'S', vatRate: 19, taxableAmount: 1000, taxAmount: 190 }],
+    paymentMeans: { typeCode: '58', iban: 'DE89370400440532013000' },
     totalNetAmount: 1000,
     totalTaxAmount: 190,
     totalGrossAmount: 1190,
@@ -88,6 +108,11 @@ costs you a second document.
 the work may still be running on beliq's side, so retrying risks producing a
 second document rather than recovering the first.
 
+A `429` carrying `QUOTA_EXCEEDED` is not retried either. `RATE_LIMITED` and
+`ACCOUNT_THROTTLED` clear on their own, but a spent monthly allowance only returns
+when your billing window turns, so the error is raised straight away and names the
+cause instead of sleeping against it.
+
 The default deadline is generous because beliq runs the full Schematron rule set
 over each document, and a generate or validate can legitimately take tens of
 seconds. If you lower it, keep it above the latency you actually see: a deadline
@@ -160,6 +185,7 @@ npm install
 npm run build       # tsup: dual ESM + CJS + d.ts
 npm run typecheck
 npm run lint
+npm run scrub:check   # no em-dash in any tracked file
 npm test            # unit tests (no network)
 BELIQ_API_KEY=blq_xxx npm run test:integration   # hits the live API; draws quota
 ```

package/dist/index.cjs

@@ -255,6 +255,11 @@ var LIVE_CONVERT_TARGET_FORMATS = [
 
 // src/transport.ts
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503]);
+var QUOTA_EXHAUSTED_CODE = "QUOTA_EXCEEDED";
+function isRetryable(status, code) {
+  if (!RETRYABLE_STATUSES.has(status)) return false;
+  return !(status === 429 && code === QUOTA_EXHAUSTED_CODE);
+}
 var MAX_RETRY_AFTER_MS = 3e4;
 var BACKOFF_BASE_MS = 500;
 function authHeaders(config) {
@@ -302,12 +307,13 @@ async function send(config, req) {
       });
       const bytes = new Uint8Array(await res.arrayBuffer());
       if (res.ok) return { status: res.status, headers: res.headers, bytes };
-      lastError = errorFromResponse(res.status, bytes);
-      if (!RETRYABLE_STATUSES.has(res.status) || attempt === config.maxRetries) {
-        throw lastError;
+      const apiError = errorFromResponse(res.status, bytes);
+      lastError = apiError;
+      if (!isRetryable(apiError.status, apiError.code) || attempt === config.maxRetries) {
+        throw apiError;
       }
     } catch (err) {
-      if (err instanceof BeliqApiError && !RETRYABLE_STATUSES.has(err.status)) throw err;
+      if (err instanceof BeliqApiError && !isRetryable(err.status, err.code)) throw err;
       if (controller.signal.aborted) {
         throw new BeliqApiError(
           `beliq: request to ${req.path} exceeded ${config.timeoutMs}ms`,