@blob-solutions/vcr-am-sdk 0.11.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 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.14.0] — 2026-07-08
+
+Closes the drift that had accumulated against `/api/v1` since 0.13.0. Everything here is additive — no call-site changes required.
+
+### Added
+
+- `whoami()` — wraps `GET /whoami`. Returns `{ vcrId, crn, mode, tradingPlatformName, businessEntity }`, where `mode` is `"production"` / `"sandbox"` and `crn` is `null` for imported-but-not-yet-activated VCRs. Useful as a cheap SDK health-check and for telling production keys apart from sandbox ones. New type `Whoami`, new schema `whoamiResponseSchema`.
+- `listOffers({ externalId?, type?, includeArchived? })` — wraps `GET /offers`. Returns up to 500 `OfferListItem[]`. Check whether an offer already exists (by `externalId`) before creating it.
+- `getOffer(id)` — wraps `GET /offers/{id}`. Returns a single `OfferListItem`.
+- `updateOffer(id, { title })` — wraps `PATCH /offers/{id}`. Renames an offer's title going forward; already-issued receipts and the SRC fiscal record are unchanged. Accepts the canonical `OfferTitle` (`localized` / `universal`).
+- New types `OfferListItem`, `ListOffersFilter`, `UpdateOfferInput`, `CurrencyConversionInput`; new schemas `offerListItemSchema`, `offerListResponseSchema`.
+- `RegisterSaleInput.currencyConversion?` — foreign-currency sales (HO-234-N). Enter the sale in USD/EUR/RUB etc.; VCR converts to AMD at the previous-business-day CBA rate and rejects a stale rate. The AMD `price` values in `items[]` stay authoritative.
+- `SaleItem.emarks?: string[]` — per-line eMark codes for marked goods (Govt Decision 1976-N). Previously only refund items could carry eMarks.
+- `Offer` (sale-item offer) gained the by-internal-id reference shape `{ id: number }`, alongside the existing new-offer and `{ externalId }` shapes.
+- `VCRApiError.body.requestId` — the server's 5xx correlation ID is now preserved instead of being stripped. Include it when contacting support.
+
+### Changed
+
+- `CreateOfferInput.title` now also accepts the canonical `OfferTitle` shape (`{ type: "localized" | "universal", ... }`), unifying it with inline sale offers and `updateOffer`, and unlocking `universal` (brand-name) titles. The legacy `{ value, localizationStrategy }` shape (now typed as `LegacyOfferTitle`) still works but is **deprecated** — the server plans to drop it.
+- Dependency refresh: `zod` `^4.4.1` → `^4.4.3`. Dev tooling bumped (`vite` `^8.0.10` → `^8.1.3`, clearing two Windows-only dev-server advisories; `@biomejs/biome`, `vitest`, `@vitest/coverage-v8`, `publint`, `@arethetypeswrong/cli`). An `esbuild` `>=0.28.1` override clears a low-severity build-time advisory. None of these ship in the published package.
+
+## [0.13.0] — 2026-05-27
+
+### Added
+
+- `listDepartments()` — wraps `GET /departments`. Returns `DepartmentListItem[]` with `internalId`, `externalId`, `taxRegime`, and the localized `title`. Only departments confirmed by the tax service are included, so each `internalId` is safe to reference from a sale item's `department.id`. Closes the gap where the SDK could create departments but not list them.
+- New exported types: `DepartmentListItem`. New exported schemas: `departmentListItemSchema`, `departmentListResponseSchema`.
+
+## [0.12.0] — 2026-05-26
+
+### Added
+
+- `listPrepayments({ customerRef?, state? })` — wraps `GET /prepayments`. Returns up to 500 rows; each item carries the ledger-derived `remaining` and `state` (`open` / `consumed` / `refunded`). `state: "all"` is accepted as an explicit no-op filter.
+- `getCustomerPrepaymentBalance({ customerRef })` — wraps `GET /prepayments/balance`. Returns the open balance for that customer, scoped to the BusinessEntity that owns the calling VCR's API key, plus the FIFO-ordered list of contributing open prepayments.
+- New exported types: `PrepaymentListItem`, `PrepaymentState`, `CustomerPrepaymentBalance`, `ListPrepaymentsFilter`. New exported schemas: `prepaymentListItemSchema`, `prepaymentListResponseSchema`, `prepaymentStateSchema`, `customerPrepaymentBalanceResponseSchema`.
+
+### Changed
+
+- `PrepaymentDetail` (the `getPrepayment` response) now includes `remaining: number` and `state: PrepaymentState`. The server has been sending these since the ledger landed; the SDK schema is catching up. Strictly additive — existing consumers keep working.
+
 ## [0.11.0] — 2026-05-13
 
 ### Breaking

package/README.md

@@ -19,6 +19,7 @@ Official TypeScript / JavaScript SDK for the [VCR.AM](https://vcr.am) Virtual Ca
 - [Quick start](#quick-start)
 - [Configuration](#configuration)
 - [API reference](#api-reference)
+  - [Account](#account)
   - [Sales](#sales)
   - [Prepayments](#prepayments)
   - [Cashiers](#cashiers)
@@ -93,6 +94,19 @@ await vcr.registerSale(sale, {
 
 Every method returns a typed, schema-validated response and accepts an optional `RequestOptions` (`{ signal?, timeoutMs? }`) as its last argument.
 
+### Account
+
+| Method       | Endpoint      | Returns  |
+| ------------ | ------------- | -------- |
+| `whoami()`   | `GET /whoami` | `Whoami` |
+
+`whoami()` resolves which VCR the API key belongs to and whether it is a `production` or `sandbox` key — a cheap health-check. It works on freshly-imported registers that have not been activated yet (`crn` is `null` in that case).
+
+```typescript
+const me = await vcr.whoami();
+console.log(me.vcrId, me.mode, me.businessEntity.tin);
+```
+
 ### Sales
 
 | Method                      | Endpoint            | Returns                       |
@@ -111,13 +125,38 @@ const refund = await vcr.registerSaleRefund({
 });
 ```
 
+**eMark codes** (marked goods, Govt Decision 1976-N) go on each sale item as `emarks: string[]`; the same codes are echoed on refund items.
+
+**Foreign-currency sales** (HO-234-N): pass a `currencyConversion` block alongside the AMD `items`. VCR re-resolves the previous-business-day CBA rate and rejects the sale if the rate you sent is stale. The AMD `price` values in `items[]` remain the authoritative fiscal figures.
+
+```typescript
+await vcr.registerSale({
+  cashier: { id: 1 },
+  items: [
+    { offer: { id: 5 }, department: { id: 1 }, quantity: "1", price: "4000", unit: "pc" },
+  ],
+  currencyConversion: {
+    currency: "USD",          // ISO 4217; not AMD
+    ratePerUnit: "400",       // AMD per 1 USD (CBA, previous business day)
+    rateDate: "2026-07-07",   // YYYY-MM-DD
+    lines: [{ foreignUnitPrice: "10" }], // index-aligned to items[]
+  },
+  amount: { cash: "4000" },
+  buyer: { type: "individual" },
+});
+```
+
 ### Prepayments
 
-| Method                            | Endpoint                  | Returns                              |
-| --------------------------------- | ------------------------- | ------------------------------------ |
-| `registerPrepayment(input)`       | `POST /prepayments`       | `RegisterPrepaymentResponse`         |
-| `getPrepayment(id)`               | `GET /prepayments/{id}`   | `PrepaymentDetail`                   |
-| `registerPrepaymentRefund(input)` | `POST /prepayments/refund`| `RegisterPrepaymentRefundResponse`   |
+| Method                                     | Endpoint                     | Returns                            |
+| ------------------------------------------ | ---------------------------- | ---------------------------------- |
+| `registerPrepayment(input)`                | `POST /prepayments`          | `RegisterPrepaymentResponse`       |
+| `getPrepayment(id)`                        | `GET /prepayments/{id}`      | `PrepaymentDetail`                 |
+| `registerPrepaymentRefund(input)`          | `POST /prepayments/refund`   | `RegisterPrepaymentRefundResponse` |
+| `listPrepayments(filter?)`                 | `GET /prepayments`           | `PrepaymentListItem[]`             |
+| `getCustomerPrepaymentBalance({ ... })`    | `GET /prepayments/balance`   | `CustomerPrepaymentBalance`        |
+
+`listPrepayments({ customerRef?, state? })` returns up to 500 rows, each carrying the ledger-derived `remaining` and `state` (`open` / `consumed` / `refunded`). `getCustomerPrepaymentBalance({ customerRef })` returns the customer's open balance, scoped to the business entity that owns the calling VCR's key.
 
 ### Cashiers
 
@@ -138,10 +177,30 @@ const cashier = await vcr.createCashier({
 
 ### Offers and departments
 
-| Method                    | Endpoint             | Returns                     |
-| ------------------------- | -------------------- | --------------------------- |
-| `createOffer(input)`      | `POST /offers`       | `CreateOfferResponse`       |
-| `createDepartment(input)` | `POST /departments`  | `CreateDepartmentResponse`  |
+| Method                       | Endpoint             | Returns                    |
+| ---------------------------- | -------------------- | -------------------------- |
+| `createOffer(input)`         | `POST /offers`       | `CreateOfferResponse`      |
+| `listOffers(filter?)`        | `GET /offers`        | `OfferListItem[]`          |
+| `getOffer(id)`               | `GET /offers/{id}`   | `OfferListItem`            |
+| `updateOffer(id, { title })` | `PATCH /offers/{id}` | `OfferListItem`            |
+| `createDepartment(input)`    | `POST /departments`  | `CreateDepartmentResponse` |
+| `listDepartments()`          | `GET /departments`   | `DepartmentListItem[]`     |
+
+`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.
+
+```typescript
+const [existing] = await vcr.listOffers({ externalId: "sku-coffee" });
+if (existing === undefined) {
+  await vcr.createOffer({
+    type: "product",
+    classifierCode: "0901",
+    title: { type: "localized", content: { hy: "Սուրճ" }, localizationStrategy: "translation" },
+    defaultMeasureUnit: "pc",
+    defaultDepartment: { id: 1 },
+    externalId: "sku-coffee",
+  });
+}
+```
 
 ### Classifier search
 
@@ -203,7 +262,7 @@ The whole request flow — connection, body read, schema parse — is bounded by
 
 ## Idempotency and retries
 
-**The SDK does not retry.** This is intentional. The fiscal API does not currently support idempotency keys, so retrying a `registerSale` after a network blip can double-fiscalize a receipt. Implement application-level retry only on operations you have confirmed are safe to repeat (typically reads: `getSale`, `getPrepayment`, `listCashiers`, `searchClassifier`).
+**The SDK does not retry.** This is intentional. The fiscal API does not currently support idempotency keys, so retrying a `registerSale` after a network blip can double-fiscalize a receipt. Implement application-level retry only on operations you have confirmed are safe to repeat (typically reads: `whoami`, `getSale`, `getPrepayment`, `listPrepayments`, `listCashiers`, `listOffers`, `getOffer`, `listDepartments`, `searchClassifier`).
 
 ## Browser usage
 

package/lib/index.cjs

@@ -98,7 +98,11 @@ var apiErrorBodySchema = zod.z.object({
       message: zod.z.string(),
       code: zod.z.string()
     })
-  ).optional()
+  ).optional(),
+  // Server-generated correlation ID present on unexpected 5xx responses.
+  // Kept lenient (plain string, not `.uuid()`) so a malformed value can never
+  // make the error envelope fail to parse and mask the real API error.
+  requestId: zod.z.string().optional()
 });
 var isoDateTimeSchema = zod.z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/, "Invalid ISO datetime");
 var detailLanguageSchema = zod.z.enum([...AVAILABLE_LANGUAGES, "multi"]);
@@ -151,6 +155,17 @@ var createDepartmentResponseSchema = zod.z.object({
   message: zod.z.string(),
   department: zod.z.number().int().nonnegative()
 });
+var whoamiResponseSchema = zod.z.object({
+  vcrId: zod.z.number().int().nonnegative(),
+  // `null` until the VCR is activated (freshly-imported registers have no CRN).
+  crn: zod.z.string().nullable(),
+  mode: zod.z.enum(["production", "sandbox"]),
+  tradingPlatformName: zod.z.string(),
+  businessEntity: zod.z.object({
+    tin: zod.z.string(),
+    name: zod.z.string()
+  })
+});
 var cashierNameLocalizationSchema = zod.z.object({
   language: zod.z.enum([...AVAILABLE_LANGUAGES, "multi"]),
   content: zod.z.string()
@@ -161,6 +176,16 @@ var cashierListItemSchema = zod.z.object({
   name: zod.z.record(zod.z.string(), cashierNameLocalizationSchema)
 });
 var cashierListResponseSchema = zod.z.array(cashierListItemSchema);
+var departmentListItemSchema = zod.z.object({
+  internalId: zod.z.number().int().nonnegative(),
+  externalId: zod.z.string().nullable(),
+  taxRegime: taxRegimeSchema,
+  // Map from language code -> { language, content }, matching the wire
+  // format produced by makeLocalizationObject on the server. May be empty
+  // for legacy departments created before titles were mandatory.
+  title: zod.z.record(zod.z.string(), localizationEntrySchema)
+});
+var departmentListResponseSchema = zod.z.array(departmentListItemSchema);
 var classifierSearchItemSchema = zod.z.object({
   code: zod.z.string(),
   // Optional: server may emit `{ code }` without `title` when the classifier
@@ -168,6 +193,20 @@ var classifierSearchItemSchema = zod.z.object({
   title: zod.z.string().optional()
 });
 var classifierSearchResponseSchema = zod.z.array(classifierSearchItemSchema);
+var offerListItemSchema = zod.z.object({
+  id: zod.z.number().int().nonnegative(),
+  externalId: zod.z.string().nullable(),
+  type: offerTypeSchema,
+  classifierCode: zod.z.string(),
+  // Server types this as a plain string (not the unit enum) to stay faithful
+  // to whatever is stored; mirror it so a legacy unit can never fail parsing.
+  defaultMeasureUnit: zod.z.string(),
+  defaultDepartment: zod.z.object({ internalId: zod.z.number().int().nonnegative() }),
+  title: zod.z.array(localizationEntrySchema),
+  archivedAt: isoDateTimeSchema.nullable(),
+  createdAt: isoDateTimeSchema
+});
+var offerListResponseSchema = zod.z.array(offerListItemSchema);
 var receiptPickSchema = zod.z.object({
   srcId: zod.z.number().int(),
   time: zod.z.string().regex(/^\d+$/, "Invalid bigint string"),
@@ -230,6 +269,7 @@ var prepaymentRefundPickSchema = zod.z.object({
   cashAmount: zod.z.number(),
   receipt: receiptPickSchema.nullable()
 });
+var prepaymentStateSchema = zod.z.enum(["open", "consumed", "refunded"]);
 var prepaymentDetailResponseSchema = zod.z.object({
   id: zod.z.number().int().nonnegative(),
   createdAt: isoDateTimeSchema,
@@ -238,7 +278,36 @@ var prepaymentDetailResponseSchema = zod.z.object({
   nonCashAmount: zod.z.number(),
   receipt: receiptPickSchema.nullable(),
   refund: prepaymentRefundPickSchema.nullable(),
-  cashier: cashierPickSchema
+  cashier: cashierPickSchema,
+  /** SUM(amount) across all ledger rows for this prepayment. */
+  remaining: zod.z.number(),
+  state: prepaymentStateSchema
+});
+var prepaymentListItemSchema = zod.z.object({
+  id: zod.z.number().int().nonnegative(),
+  createdAt: isoDateTimeSchema,
+  buyerTin: zod.z.string().nullable(),
+  cashAmount: zod.z.number(),
+  nonCashAmount: zod.z.number(),
+  remaining: zod.z.number(),
+  state: prepaymentStateSchema
+});
+var prepaymentListResponseSchema = zod.z.array(prepaymentListItemSchema);
+var customerOpenPrepaymentSchema = zod.z.object({
+  prepaymentId: zod.z.number().int().nonnegative(),
+  createdAt: isoDateTimeSchema,
+  cashAmount: zod.z.number(),
+  nonCashAmount: zod.z.number(),
+  buyerTin: zod.z.string().nullable(),
+  remaining: zod.z.number()
+});
+var customerPrepaymentBalanceResponseSchema = zod.z.object({
+  entityId: zod.z.number().int().nonnegative(),
+  customerRef: zod.z.string(),
+  /** Total remaining across all open prepayments matching customerRef. */
+  balance: zod.z.number(),
+  /** FIFO-ordered open prepayments contributing to the balance. */
+  openPrepayments: zod.z.array(customerOpenPrepaymentSchema)
 });
 
 // src/fetch.ts
@@ -299,7 +368,8 @@ function buildApiError(status, rawJson, url) {
   if (parsed.success) {
     const body = {
       error: parsed.data.error,
-      ...parsed.data.issues !== void 0 && { issues: parsed.data.issues }
+      ...parsed.data.issues !== void 0 && { issues: parsed.data.issues },
+      ...parsed.data.requestId !== void 0 && { requestId: parsed.data.requestId }
     };
     return new VCRApiError(status, body, url);
   }
@@ -347,6 +417,17 @@ var VCRClient = class {
     this.#fetch = options.fetch === void 0 ? candidate.bind(globalThis) : candidate;
     this.#defaultTimeoutMs = options.timeoutMs === void 0 ? DEFAULT_TIMEOUT_MS : options.timeoutMs;
   }
+  // ─── Account ──────────────────────────────────────────────────────────────
+  /**
+   * Resolve which VCR the calling API key belongs to. Returns the register's
+   * identity, its `mode` (`production` / `sandbox`), and the owning business
+   * entity. Works on freshly-imported VCRs that have not been activated yet
+   * (in which case `crn` is `null`) — handy as a cheap SDK health-check and to
+   * tell production keys apart from sandbox ones.
+   */
+  whoami(options = {}) {
+    return this.#json("GET", "/whoami", whoamiResponseSchema, void 0, options);
+  }
   // ─── Sales ─────────────────────────────────────────────────────────────────
   registerSale(data, options = {}) {
     return this.#json("POST", "/sales", registerSaleResponseSchema, data, options);
@@ -381,6 +462,48 @@ var VCRClient = class {
       options
     );
   }
+  /**
+   * List prepayments registered through the calling VCR. Server caps the
+   * response at 500 rows; for larger sets, narrow with `customerRef` or
+   * paginate by `id` outside the SDK.
+   *
+   * `remaining` and `state` are derived from the ledger — call this whenever
+   * you want a current snapshot rather than caching the result.
+   */
+  listPrepayments(filter = {}, options = {}) {
+    const query = {};
+    if (filter.customerRef !== void 0) query["customerRef"] = filter.customerRef;
+    if (filter.state !== void 0) query["state"] = filter.state;
+    return this.#json(
+      "GET",
+      "/prepayments",
+      prepaymentListResponseSchema,
+      void 0,
+      options,
+      Object.keys(query).length > 0 ? query : void 0
+    );
+  }
+  /**
+   * Get a customer's open prepayment balance scoped to the BusinessEntity
+   * that owns the calling VCR's API key. Because the ledger is entity-scoped,
+   * the result reflects deposits made through any VCR belonging to the same
+   * entity — merchants who run more than one VCR see a single wallet.
+   *
+   * `customerRef` is matched exactly against the ledger — typically a TIN,
+   * normalized E.164 phone, or lowercased email. Use whichever identifier the
+   * customer gave at deposit time; identities are not auto-merged across
+   * different ref types.
+   */
+  getCustomerPrepaymentBalance(input, options = {}) {
+    return this.#json(
+      "GET",
+      "/prepayments/balance",
+      customerPrepaymentBalanceResponseSchema,
+      void 0,
+      options,
+      { customerRef: input.customerRef }
+    );
+  }
   // ─── Cashiers ─────────────────────────────────────────────────────────────
   listCashiers(options = {}) {
     return this.#json("GET", "/cashiers", cashierListResponseSchema, void 0, options);
@@ -392,9 +515,57 @@ var VCRClient = class {
   createOffer(data, options = {}) {
     return this.#json("POST", "/offers", createOfferResponseSchema, data, options);
   }
+  /**
+   * List offers belonging to the calling VCR. Server caps the response at 500
+   * rows; narrow with `externalId` / `type` for larger catalogs. Archived
+   * offers are excluded unless `includeArchived` is set.
+   *
+   * A common use is checking whether an offer already exists (by `externalId`)
+   * before creating it.
+   */
+  listOffers(filter = {}, options = {}) {
+    const query = {};
+    if (filter.externalId !== void 0) query["externalId"] = filter.externalId;
+    if (filter.type !== void 0) query["type"] = filter.type;
+    if (filter.includeArchived !== void 0) {
+      query["includeArchived"] = filter.includeArchived ? "true" : "false";
+    }
+    return this.#json(
+      "GET",
+      "/offers",
+      offerListResponseSchema,
+      void 0,
+      options,
+      Object.keys(query).length > 0 ? query : void 0
+    );
+  }
+  getOffer(offerId, options = {}) {
+    assertNonNegativeInt(offerId, "offerId");
+    return this.#json("GET", `/offers/${offerId}`, offerListItemSchema, void 0, options);
+  }
+  /**
+   * Rename an offer's title. Affects only future receipts — already-issued
+   * receipts keep the title they were created with, and the SRC fiscal record
+   * is unchanged. Missing `en`/`ru` are filled per `localizationStrategy`,
+   * exactly as on offer creation. Returns the updated offer.
+   */
+  updateOffer(offerId, data, options = {}) {
+    assertNonNegativeInt(offerId, "offerId");
+    return this.#json("PATCH", `/offers/${offerId}`, offerListItemSchema, data, options);
+  }
   createDepartment(data, options = {}) {
     return this.#json("POST", "/departments", createDepartmentResponseSchema, data, options);
   }
+  /**
+   * List departments configured on the calling VCR — `internalId`,
+   * `externalId`, `taxRegime`, and the localized `title`. Mirrors the
+   * dashboard catalog: only departments confirmed by the tax service are
+   * returned, so the `internalId` field is safe to reference from a sale
+   * item's `department.id`.
+   */
+  listDepartments(options = {}) {
+    return this.#json("GET", "/departments", departmentListResponseSchema, void 0, options);
+  }
   // ─── Classifier search ────────────────────────────────────────────────────
   searchClassifier(input, options = {}) {
     return this.#json(
@@ -461,12 +632,21 @@ exports.classifierSearchResponseSchema = classifierSearchResponseSchema;
 exports.createCashierResponseSchema = createCashierResponseSchema;
 exports.createDepartmentResponseSchema = createDepartmentResponseSchema;
 exports.createOfferResponseSchema = createOfferResponseSchema;
+exports.customerPrepaymentBalanceResponseSchema = customerPrepaymentBalanceResponseSchema;
+exports.departmentListItemSchema = departmentListItemSchema;
+exports.departmentListResponseSchema = departmentListResponseSchema;
+exports.offerListItemSchema = offerListItemSchema;
+exports.offerListResponseSchema = offerListResponseSchema;
 exports.prepaymentDetailResponseSchema = prepaymentDetailResponseSchema;
+exports.prepaymentListItemSchema = prepaymentListItemSchema;
+exports.prepaymentListResponseSchema = prepaymentListResponseSchema;
+exports.prepaymentStateSchema = prepaymentStateSchema;
 exports.registerPrepaymentRefundResponseSchema = registerPrepaymentRefundResponseSchema;
 exports.registerPrepaymentResponseSchema = registerPrepaymentResponseSchema;
 exports.registerSaleRefundResponseSchema = registerSaleRefundResponseSchema;
 exports.registerSaleResponseSchema = registerSaleResponseSchema;
 exports.saleDetailResponseSchema = saleDetailResponseSchema;
 exports.unitsKeys = unitsKeys;
+exports.whoamiResponseSchema = whoamiResponseSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map