@getpeppr/cli 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@getpeppr/cli` are documented here.
 
 The CLI bundles `@getpeppr/sdk` into its published artifact (tsup `noExternal`), so `validate`, `convert` and `init` run the SDK's validators, country rules and UBL builder locally — an SDK release only reaches CLI users once the CLI is rebundled. Rebundle-only releases are listed with the SDK version they ship.
 
+## [0.9.0] — 2026-08-23
+
+Before every sandbox send, the CLI now reads the exact sender profile from
+`GET /v1/identity`. Its own generated fixture is adapted to O/0 for a
+routing-only sender or AE/0 for a sender carrying a Tax Identifier. A
+user-authored file is never rewritten silently: an incompatible tax mode is
+refused locally before the invoice API is called.
+
+This replaces the incomplete static O/0 assumption in 0.8.4. It also bundles
+SDK 4.8.0 and fails closed when the provider inventory or scheme role cannot be
+verified (GPR-1149).
+
+## [0.8.4] — 2026-08-22
+
+`getpeppr init` scaffolded the SPF Economie test receiver plus out-of-scope
+`O/0` lines. That fixed routing-only senders but incorrectly assumed every
+sandbox sender lacked a Tax Identifier; 0.9.0 supersedes the static choice with
+the exact sender profile.
+
+Every generated `O` line includes the builder-only exemption reason required by
+the SDK's local validator. The quick `getpeppr send --to …` payload remains on
+the same contract. This release bundles SDK 4.7.0.
+
 ## [0.8.3] — 2026-08-21
 
 Rebundles `@getpeppr/sdk` **4.6.0** (was 4.5.0), so `getpeppr validate` and

package/README.md

@@ -237,11 +237,11 @@ The CLI runs three validation engines from the [@getpeppr/sdk](https://www.npmjs
 2. **Business Rules** — Peppol BIS 3.0 / EN 16931 compliance (BR-xx, BR-CO-xx, PEPPOL-xx rules)
 3. **Country Rules** — Belgium (BE), France (FR), Italy (IT), Netherlands (NL), Germany (DE)
 
-Scaffolding (`init`), validation, and conversion run fully offline — no API key or network connection required. Only `lookup`, `send`, and `whoami` need a network connection.
+Scaffolding (`init`), validation, and conversion run fully offline — no API key or network connection required. Only `lookup`, `send`, and `whoami` need a network connection. Before a sandbox `send`, the CLI reads `GET /v1/identity`: its own generated fixture is adapted to the returned O/0 or AE/0 profile, while a user-edited file is never rewritten silently and is refused locally if its tax mode conflicts with the sender.
 
 ## Invoice format
 
-The input file must be a JSON object matching the getpeppr `InvoiceInput` type. `number`, `to`, and `lines` are required for API sends. The `from` party is included in the scaffold because offline validation and UBL conversion need seller metadata; API sends use the legal entity linked to your key.
+The input file must be a JSON object matching the getpeppr `InvoiceInput` type. `number`, `to`, and `lines` are required for API sends. The `from` party is included in the scaffold because offline validation and UBL conversion need seller metadata; API sends use the legal entity linked to your key. The generated file starts as an O/0 integration fixture. At send time the CLI verifies it against the actual sender profile and never forwards an incompatible tax mode.
 
 ```json
 {
@@ -271,14 +271,17 @@ The input file must be a JSON object matching the getpeppr `InvoiceInput` type.
       "description": "Conseil en transformation numérique",
       "quantity": 10,
       "unitPrice": 950,
-      "vatRate": 21
+      "vatRate": 0,
+      "vatCategory": "O",
+      "taxExemptReason": "Integration test"
     },
     {
       "description": "Software license — annual subscription",
       "quantity": 1,
       "unitPrice": 2400,
       "vatRate": 0,
-      "vatCategory": "AE"
+      "vatCategory": "O",
+      "taxExemptReason": "Integration test"
     }
   ],
   "paymentTerms": "Net 30 days",

package/dist/index.js

@@ -717,6 +717,28 @@ function formatVatRate(vatRate, field) {
   }
   return String(vatRate);
 }
+function formatBaseQuantity(baseQuantity, field) {
+  if (typeof baseQuantity !== "number" || !Number.isFinite(baseQuantity) || baseQuantity <= 0) {
+    throw new UblBuilderInputError("baseQuantity must be a finite number greater than zero.", field, "PEPPOL-EN16931-R121");
+  }
+  const numeric = String(baseQuantity);
+  const exponentMarker = numeric.search(/[eE]/);
+  if (exponentMarker === -1)
+    return numeric;
+  const coefficient = numeric.slice(0, exponentMarker);
+  const exponent = Number(numeric.slice(exponentMarker + 1));
+  const decimalPoint = coefficient.indexOf(".");
+  const digits = coefficient.replace(".", "");
+  const integerDigits = decimalPoint === -1 ? coefficient.length : decimalPoint;
+  const outputPoint = integerDigits + exponent;
+  if (outputPoint <= 0) {
+    return `0.${"0".repeat(-outputPoint)}${digits}`;
+  }
+  if (outputPoint >= digits.length) {
+    return `${digits}${"0".repeat(outputPoint - digits.length)}`;
+  }
+  return `${digits.slice(0, outputPoint)}.${digits.slice(outputPoint)}`;
+}
 function round2(n) {
   return Math.round(n * 100) / 100;
 }
@@ -974,7 +996,7 @@ function buildDocumentLineXml(line, index, currency, lineTag, qtyTag) {
       </cac:Item>
       <cac:Price>
         <cbc:PriceAmount currencyID="${escapeXml(currency)}">${formatAmount(line.unitPrice)}</cbc:PriceAmount>
-        ${line.baseQuantity != null ? `<cbc:BaseQuantity unitCode="${escapeXml(resolveUnitCode(line.baseQuantityUnit ?? line.unit ?? DEFAULT_UNIT))}">${line.baseQuantity}</cbc:BaseQuantity>` : ""}
+        ${line.baseQuantity !== void 0 ? `<cbc:BaseQuantity unitCode="${escapeXml(resolveUnitCode(line.baseQuantityUnit ?? line.unit ?? DEFAULT_UNIT))}">${formatBaseQuantity(line.baseQuantity, `lines[${index}].baseQuantity`)}</cbc:BaseQuantity>` : ""}
       </cac:Price>
     </cac:${lineTag}>`;
 }
@@ -1605,6 +1627,11 @@ function validateLine(line, index, isCreditNote = false) {
   } else if (line.unitPrice < 0) {
     errors.push(error(`${path}.unitPrice`, `Unit price cannot be negative, got ${line.unitPrice}`, void 0, "For discounts, use a negative quantity or a separate discount line"));
   }
+  if (line.baseQuantity !== void 0) {
+    if (typeof line.baseQuantity !== "number" || !Number.isFinite(line.baseQuantity) || line.baseQuantity <= 0) {
+      errors.push(error(`${path}.baseQuantity`, "Base quantity must be a finite number greater than zero", "PEPPOL-EN16931-R121", "Use a positive number for the item price base quantity"));
+    }
+  }
   if (line.vatRate === void 0 || line.vatRate === null) {
     errors.push(error(`${path}.vatRate`, "VAT rate is required", "BR-CO-17"));
   } else if (line.vatRate < 0 || line.vatRate > 100) {
@@ -2304,7 +2331,7 @@ function statusFamily(status) {
 var TERMINAL_FAILURE_STATUSES = STATUS_PRECEDENCE.filter((e) => e.family === "terminal-failure").map((e) => e.status);
 
 // ../sdk/dist/version.js
-var SDK_VERSION = "4.6.0";
+var SDK_VERSION = "4.8.0";
 
 // ../sdk/dist/core/client.js
 function findHeaderCaseInsensitive(headers, name) {
@@ -2537,9 +2564,8 @@ var GetpepprAdapter = class {
       clearTimeout(timeoutId);
     }
   }
-  // NOTE: sendInvoice and createInvoice hit the same SDK endpoint (POST /invoices).
-  // The gateway (Tasks 9-10) differentiates them: sendInvoice wraps with
-  // { invoice: {...}, send_after_import: true }, createInvoice omits the flag.
+  // sendInvoice and createInvoice hit the same endpoint. The latter adds the
+  // legacy `_draft` marker, which the current gateway rejects explicitly.
   async sendInvoice(input, options) {
     const headers = {};
     if (options?.idempotencyKey) {
@@ -2578,6 +2604,8 @@ var GetpepprAdapter = class {
       params.set("limit", String(options.limit));
     if (options?.offset != null)
       params.set("offset", String(options.offset));
+    if (options?.number != null)
+      params.set("number", options.number);
     if (options?.includeLines)
       params.set("include", "lines");
     const query = params.toString() ? `?${params.toString()}` : "";
@@ -2711,7 +2739,9 @@ var GetpepprAdapter = class {
       params.set("limit", String(options.limit));
     if (options?.offset != null)
       params.set("offset", String(options.offset));
-    if (options?.invoiceId)
+    if (options?.documentId != null)
+      params.set("documentId", options.documentId);
+    if (options?.invoiceId != null)
       params.set("invoiceId", options.invoiceId);
     if (options?.dateFrom)
       params.set("dateFrom", options.dateFrom);
@@ -3218,9 +3248,49 @@ function parseAccountIdentity(raw) {
   return {
     environment,
     legalEntity: parseAccountIdentityLegalEntity(readOwn(result, "legalEntity"), result),
-    identifiers
+    identifiers,
+    sandboxFirstSend: parseSandboxFirstSendProfile(readOwn(result, "sandboxFirstSend"), result)
   };
 }
+function parseSandboxFirstSendProfile(raw, body) {
+  if (raw === null)
+    return null;
+  if (!isRecord(raw)) {
+    throw new PeppolProtocolError("The getpeppr API answered the identity request without a valid sandboxFirstSend field. Please report this response to support@getpeppr.dev.", "sandboxFirstSend", boundedBody(body));
+  }
+  const status = readOwn(raw, "status");
+  if (status === "blocked") {
+    const code = readOwn(raw, "code");
+    const message = readOwn(raw, "message");
+    if (typeof code === "string" && code.trim() !== "" && typeof message === "string" && message.trim() !== "") {
+      return { status, code, message };
+    }
+  }
+  if (status === "ready") {
+    const taxMode = readOwn(raw, "taxMode");
+    const line = readOwn(raw, "line");
+    if ((taxMode === "outside_scope" || taxMode === "reverse_charge") && isRecord(line)) {
+      const vatRate = readOwn(line, "vatRate");
+      const vatCategory = readOwn(line, "vatCategory");
+      const taxExemptReason = readOwn(line, "taxExemptReason");
+      if (vatRate === 0 && typeof taxExemptReason === "string" && taxExemptReason.trim() !== "" && taxMode === "outside_scope" && vatCategory === "O") {
+        return {
+          status,
+          taxMode,
+          line: { vatRate, vatCategory, taxExemptReason }
+        };
+      }
+      if (vatRate === 0 && typeof taxExemptReason === "string" && taxExemptReason.trim() !== "" && taxMode === "reverse_charge" && vatCategory === "AE") {
+        return {
+          status,
+          taxMode,
+          line: { vatRate, vatCategory, taxExemptReason }
+        };
+      }
+    }
+  }
+  throw new PeppolProtocolError("The getpeppr API answered the identity request with a malformed sandboxFirstSend profile. Please report this response to support@getpeppr.dev.", "sandboxFirstSend", boundedBody(body));
+}
 function parseAccountIdentityLegalEntity(raw, body) {
   if (raw === null)
     return null;
@@ -3521,16 +3591,12 @@ var InvoiceOperations = class {
     this.adapter = adapter;
   }
   /**
-   * Create a draft invoice without sending it.
-   * Validates input client-side, then creates the invoice via the gateway.
-   * Use `sendById()` to send the draft when ready.
+   * Request draft creation from the gateway.
    *
-   * @example
-   * ```ts
-   * const draft = await peppol.invoices.create({ number: "INV-001", to, lines });
-   * // Later, when ready:
-   * await peppol.invoices.sendById(draft.id);
-   * ```
+   * @deprecated The current Storecove-backed gateway does not support drafts
+   * and returns 422 `drafts_not_supported`. Submit the final document with
+   * `invoices.send()` instead.
+   * @throws {PeppolApiError} 422 with code `drafts_not_supported`
    */
   async create(input, options) {
     const validation = validateInvoice(input);
@@ -3545,14 +3611,11 @@ ${validation.errors.map((e) => `  - ${e.field}: ${e.message}${e.suggestion ? ` (
     return result;
   }
   /**
-   * Send an existing draft invoice by ID.
-   * The invoice must have been previously created with `create()`.
+   * Request sending of an existing draft invoice by ID.
    *
-   * @example
-   * ```ts
-   * await peppol.invoices.sendById("inv-1");
-   * ```
-   * @throws {PeppolApiError} 501 if the gateway provider does not support draft sending
+   * @deprecated The current Storecove-backed gateway has no draft lifecycle and
+   * always returns 501. Submit the final document with `invoices.send()`.
+   * @throws {PeppolApiError} 501 with the current gateway provider
    */
   async sendById(id) {
     return this.adapter.sendInvoiceById(id);
@@ -3723,52 +3786,39 @@ ${validation.errors.map((e) => `  - ${e.field}: ${e.message}${e.suggestion ? ` (
     return this.adapter.importInvoice(options);
   }
   /**
-   * Acknowledge a received invoice.
+   * Request acknowledgement of a received invoice.
    *
-   * @example
-   * ```ts
-   * const result = await peppol.invoices.acknowledge("inv-123");
-   * console.log(result.status); // "accepted"
-   * ```
-   * @throws {PeppolApiError} 501 if the gateway provider does not support acknowledgement
+   * @deprecated The current Storecove-backed gateway does not support
+   * acknowledgement and always returns 501.
+   * @throws {PeppolApiError} 501 with the current gateway provider
    */
   async acknowledge(id) {
     return this.adapter.acknowledgeInvoice(id);
   }
   /**
-   * Update an existing invoice (draft only).
-   * Only include the fields you want to change — partial updates are supported.
+   * Request an update to an existing invoice.
    *
-   * @example
-   * ```ts
-   * const updated = await peppol.invoices.update("inv-123", {
-   *   dueDate: "2026-04-01",
-   *   lines: [
-   *     { id: "line-1", quantity: 5 },
-   *     { id: "line-2", _destroy: true },
-   *   ],
-   * });
-   * ```
-   * @throws {PeppolApiError} 501 if the gateway provider does not support invoice updates
+   * @deprecated Storecove documents are immutable after submission. The
+   * current gateway always returns 501; issue a credit note instead.
+   * @throws {PeppolApiError} 501 with the current gateway provider
    */
   async update(id, input) {
     return this.adapter.updateInvoice(id, input);
   }
   /**
-   * Delete an invoice.
+   * Request deletion of an invoice.
    *
-   * @example
-   * ```ts
-   * const deleted = await peppol.invoices.delete("inv-123");
-   * ```
-   * @throws {PeppolApiError} 501 if the gateway provider does not support invoice deletion
+   * @deprecated The current Storecove-backed gateway does not support invoice
+   * deletion and always returns 501.
+   * @throws {PeppolApiError} 501 with the current gateway provider
    */
   async delete(id) {
     return this.adapter.deleteInvoice(id);
   }
   /**
-   * Transition an invoice to a new state.
-   * The gateway validates the state machine — invalid transitions return an error.
+   * Report a French CTC invoice as paid.
+   * Other state transitions are retained for API compatibility but the current
+   * Storecove-backed gateway returns 501 for them.
    *
    * `"paid"` on a French CTC invoice reports the payment collection
    * (« signalement d'encaissement ») to the tax authority via the gateway —
@@ -3970,8 +4020,8 @@ var EventOperations = class {
    * const result = await peppol.events.list({ limit: 10 });
    * console.log(result.data, result.meta);
    *
-   * // Filter by invoice
-   * const invoiceEvents = await peppol.events.list({ invoiceId: "inv-123" });
+   * // Filter by provider document ID or getpeppr submission ID
+   * const invoiceEvents = await peppol.events.list({ documentId: "inv-123" });
    * ```
    */
   async list(options) {
@@ -3982,7 +4032,7 @@ var EventOperations = class {
    *
    * @example
    * ```ts
-   * for await (const event of peppol.events.listAll({ invoiceId: "inv-123" })) {
+   * for await (const event of peppol.events.listAll({ documentId: "inv-123" })) {
    *   console.log(event.name, event.createdAt);
    * }
    * ```
@@ -4448,14 +4498,17 @@ var INVOICE_TEMPLATE = {
       description: "Conseil en transformation num\xE9rique",
       quantity: 10,
       unitPrice: 950,
-      vatRate: 21
+      vatRate: 0,
+      vatCategory: "O",
+      taxExemptReason: "Integration test"
     },
     {
       description: "Software license \u2014 annual subscription",
       quantity: 1,
       unitPrice: 2400,
       vatRate: 0,
-      vatCategory: "AE"
+      vatCategory: "O",
+      taxExemptReason: "Integration test"
     }
   ],
   paymentTerms: "Net 30 days",
@@ -4491,7 +4544,9 @@ var CREDIT_NOTE_TEMPLATE = {
       description: "Avoir partiel \u2014 Conseil en transformation num\xE9rique",
       quantity: 2,
       unitPrice: 950,
-      vatRate: 21
+      vatRate: 0,
+      vatCategory: "O",
+      taxExemptReason: "Integration test"
     }
   ],
   note: "Avoir pour prestations non r\xE9alis\xE9es \u2014 r\xE9f. INV-2026-001"
@@ -4525,9 +4580,9 @@ function registerInitCommand(program2) {
   3. Convert to XML: getpeppr convert ${filename}
   4. Send: getpeppr send ${filename}
 
-  ${pc2.dim("Sandbox note:")} this template includes VAT. To send it on a sandbox
-  account, first register your VAT on the Peppol identity page, or set each
-  line's "vatCategory" to "O" (outside the scope of VAT) for a no-VAT test send.
+  ${pc2.dim("Sandbox note:")} this offline template starts with O/0 tax lines.
+  On send, the CLI checks GET /v1/identity and refuses a conflicting sender
+  profile before anything reaches the provider.
 `);
       process.exit(0);
     }
@@ -5090,11 +5145,11 @@ function buildDefaultSendPayload(overrides = {}) {
         quantity: 1,
         unitPrice: amount,
         vatRate: 0,
-        // vatCategory "O" = "Services outside scope of tax" (UBL 2.1 / EN 16931).
-        // Public entities (SPF Economie) are VAT-exempt. The SDK pre-validator
-        // requires the builder-only reason; the send transport strips it so
-        // Storecove can still derive its own provider-specific text.
-        // If sandbox returns 422 on this combination, fallback is vatRate: 21 + vatCategory: "S".
+        // vatCategory "O" = outside the scope of VAT (UBL 2.1 / EN 16931).
+        // This offline fixture starts at O/0. Before sending, the CLI reads
+        // GET /identity and replaces these tax fields with the sender-specific
+        // O/0 or AE/0 first-send profile. The SDK transport strips the
+        // builder-only reason so Storecove can derive its own provider text.
         vatCategory: "O",
         taxExemptReason: "Not subject to VAT"
       }
@@ -5270,6 +5325,42 @@ function registerSendCommand(program2) {
       }
       throw e;
     }
+    const baseUrl = flags.local ? LOCAL_BASE : API_BASE;
+    const client = new Peppol({ apiKey: auth.apiKey, baseUrl });
+    if (auth.environment === "sandbox") {
+      let profile;
+      try {
+        profile = (await client.identity.get()).sandboxFirstSend;
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`${pc6.red("\u2722")} Could not verify the sandbox sender profile: ${msg}
+`);
+        process.exit(1);
+        return;
+      }
+      if (!profile || profile.status !== "ready") {
+        const message = profile?.status === "blocked" ? profile.message : "The sandbox first-send profile is unavailable.";
+        process.stderr.write(`${pc6.red("\u2722")} ${message}
+`);
+        process.exit(1);
+        return;
+      }
+      const taxEntries = [payload.lines, payload.allowances, payload.charges].filter(Array.isArray).flat();
+      const payloadOutsideScope = taxEntries.length > 0 && taxEntries.every((entry) => entry.vatCategory === "O");
+      const profileOutsideScope = profile.taxMode === "outside_scope";
+      if (file) {
+        if (payloadOutsideScope !== profileOutsideScope) {
+          process.stderr.write(
+            `${pc6.red("\u2722")} This file's tax mode does not match the sandbox sender. GET /v1/identity recommends ${profile.line.vatCategory}/0. Nothing was sent.
+`
+          );
+          process.exit(1);
+          return;
+        }
+      } else {
+        payload.lines = payload.lines.map((line) => ({ ...line, ...profile.line }));
+      }
+    }
     if (flags.validate !== false) {
       const result2 = runValidation(payload);
       if (!result2.valid) {
@@ -5290,8 +5381,6 @@ function registerSendCommand(program2) {
         process.exit(0);
       }
     }
-    const baseUrl = flags.local ? LOCAL_BASE : API_BASE;
-    const client = new Peppol({ apiKey: auth.apiKey, baseUrl });
     let result;
     try {
       result = await client.invoices.send(payload);