@blob-solutions/vcr-am-sdk 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `@blob-solutions/vcr-am-sdk`. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows [Semantic Versioning](https://semver.org/).
 
+## [0.18.0] — 2026-08-28
+
+Stops making integrators guess a department id.
+
+### Changed
+
+- **`SaleItem.department` is now optional.** Omit it and the line inherits the department of the offer it references — for an inline new offer, the `defaultDepartment` you declared on it. Passing one explicitly still works and still wins, which is what you want when you deliberately sell the same SKU out of a second department.
+
+  The field was required, so every integration had to name a department per line, and the natural thing to write is the first id. That is not a harmless default: departments carry the tax regime, every register is created with one department per regime in a fixed order, and `{ id: 1 }` is the VAT one on every register whether or not the merchant owes VAT. Nothing rejects the mismatch — the receipt simply prints a VAT line the merchant does not owe, and a fiscal receipt can only be refunded and reissued, never corrected. We found this in the field.
+
+  ```diff
+   items: [
+     {
+       offer: { externalId: "sku-coffee" },
+  -    department: { id: 1 },
+       quantity: "1",
+       price: "1500",
+       unit: "pc",
+     },
+   ],
+  ```
+
+  Requires the server-side change shipped alongside it; against an older deployment an omitted `department` is a `422`.
+
 ## [0.17.0] — 2026-08-28
 
 Makes a `502` from an unreachable tax service recoverable. Until now the SDK told you the call failed but gave you no way to learn whether the document survived, and the only obvious response — retry — was the one that creates a duplicate fiscal receipt.

package/README.md

@@ -57,7 +57,6 @@ const { crn, srcReceiptId, fiscal } = await vcr.registerSale({
   items: [
     {
       offer: { externalId: "sku-coffee" },
-      department: { id: 1 },
       quantity: "1",
       price: "1500",
       unit: "pc",
@@ -142,7 +141,7 @@ await vcr.registerSale({
   cashier: { id: 1 },
   items: [
     // price is in USD; VCR converts to AMD.
-    { offer: { id: 5 }, department: { id: 1 }, quantity: "1", price: "10", currency: "USD", unit: "pc" },
+    { offer: { id: 5 }, quantity: "1", price: "10", currency: "USD", unit: "pc" },
   ],
   autoSettle: { tender: "cash" }, // AMD total is server-derived
   buyer: { type: "individual" },
@@ -191,6 +190,10 @@ const cashier = await vcr.createCashier({
 
 `listOffers({ externalId?, type?, includeArchived? })` is handy for checking whether an offer already exists (by `externalId`) before creating it. `updateOffer` renames an offer's title going forward — already-issued receipts are unchanged. Offer titles use the canonical `OfferTitle` shape (`{ type: "localized" | "universal", ... }`); `createOffer` also still accepts the deprecated legacy `{ value, localizationStrategy }` shape.
 
+**Departments decide the tax regime**, so `defaultDepartment` is the one field on `createOffer` worth stopping over. Every register is created with one department per regime — VAT, VAT-exempt, turnover tax, micro-enterprise — and they are numbered in that order, which makes `{ id: 1 }` the VAT one on every register whether or not the merchant owes VAT. Call `listDepartments()` once, read `taxRegime`, and use the id that matches how the business is actually registered. Booking a sale under the wrong regime is not rejected by anything, and a fiscal receipt can only be refunded and reissued, never corrected.
+
+Sale items then leave `department` out and inherit the offer's, so the decision is made once per offer instead of once per line.
+
 ```typescript
 const [existing] = await vcr.listOffers({ externalId: "sku-coffee" });
 if (existing === undefined) {

package/lib/index.d.cts

@@ -584,7 +584,24 @@ type NewOffer = {
 type Offer = NewOffer | ExistingOfferByExternalId | ExistingOfferById;
 type SaleItem = {
     offer: Offer;
-    department: DepartmentInput;
+    /**
+     * Department to book this line under. **Omit it** unless you have a reason
+     * not to: the line then inherits the department of the offer it references
+     * (`defaultDepartment`), which for an inline new offer is the one you just
+     * declared on it.
+     *
+     * The department — not the offer — decides the tax regime printed on the
+     * receipt, and every register is created with one department per regime.
+     * So a hard-coded `{ id: 1 }` copied from an example is not a harmless
+     * default: on a register that owes no VAT it books the sale under the VAT
+     * department anyway, and the receipt shows a VAT line the merchant does not
+     * owe. Nothing rejects it, and a fiscal receipt can only be refunded and
+     * reissued, never corrected.
+     *
+     * Set it explicitly only to override the offer — selling the same SKU out
+     * of a second department (a VAT payer booking an exempt transaction, say).
+     */
+    department?: DepartmentInput;
     quantity: string;
     /**
      * Unit price. AMD by default. When {@link SaleItem.currency} is set to a

package/lib/index.d.ts

@@ -584,7 +584,24 @@ type NewOffer = {
 type Offer = NewOffer | ExistingOfferByExternalId | ExistingOfferById;
 type SaleItem = {
     offer: Offer;
-    department: DepartmentInput;
+    /**
+     * Department to book this line under. **Omit it** unless you have a reason
+     * not to: the line then inherits the department of the offer it references
+     * (`defaultDepartment`), which for an inline new offer is the one you just
+     * declared on it.
+     *
+     * The department — not the offer — decides the tax regime printed on the
+     * receipt, and every register is created with one department per regime.
+     * So a hard-coded `{ id: 1 }` copied from an example is not a harmless
+     * default: on a register that owes no VAT it books the sale under the VAT
+     * department anyway, and the receipt shows a VAT line the merchant does not
+     * owe. Nothing rejects it, and a fiscal receipt can only be refunded and
+     * reissued, never corrected.
+     *
+     * Set it explicitly only to override the offer — selling the same SKU out
+     * of a second department (a VAT payer booking an exempt transaction, say).
+     */
+    department?: DepartmentInput;
     quantity: string;
     /**
      * Unit price. AMD by default. When {@link SaleItem.currency} is set to a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blob-solutions/vcr-am-sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Official TypeScript/JavaScript SDK for the VCR.AM Virtual Cash Register API — fiscalize sales, refunds, and prepayments through Armenia's State Revenue Committee.",
   "keywords": [
     "vcr",