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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.ts CHANGED
@@ -45,6 +45,28 @@ declare const createDepartmentResponseSchema: z.ZodObject<{
45
45
  message: z.ZodString;
46
46
  department: z.ZodNumber;
47
47
  }, z.core.$strip>;
48
+ declare const exchangeRateResponseSchema: z.ZodObject<{
49
+ currency: z.ZodString;
50
+ ratePerUnit: z.ZodNumber;
51
+ amount: z.ZodNumber;
52
+ rateDate: z.ZodString;
53
+ saleDate: z.ZodString;
54
+ ruleVersion: z.ZodString;
55
+ source: z.ZodLiteral<"CBA">;
56
+ }, z.core.$strip>;
57
+ declare const whoamiResponseSchema: z.ZodObject<{
58
+ vcrId: z.ZodNumber;
59
+ crn: z.ZodNullable<z.ZodString>;
60
+ mode: z.ZodEnum<{
61
+ production: "production";
62
+ sandbox: "sandbox";
63
+ }>;
64
+ tradingPlatformName: z.ZodString;
65
+ businessEntity: z.ZodObject<{
66
+ tin: z.ZodString;
67
+ name: z.ZodString;
68
+ }, z.core.$strip>;
69
+ }, z.core.$strip>;
48
70
  declare const cashierListItemSchema: z.ZodObject<{
49
71
  deskId: z.ZodString;
50
72
  internalId: z.ZodNumber;
@@ -71,6 +93,46 @@ declare const cashierListResponseSchema: z.ZodArray<z.ZodObject<{
71
93
  content: z.ZodString;
72
94
  }, z.core.$strip>>;
73
95
  }, z.core.$strip>>;
96
+ declare const departmentListItemSchema: z.ZodObject<{
97
+ internalId: z.ZodNumber;
98
+ externalId: z.ZodNullable<z.ZodString>;
99
+ taxRegime: z.ZodEnum<{
100
+ vat: "vat";
101
+ vat_exempt: "vat_exempt";
102
+ turnover_tax: "turnover_tax";
103
+ micro_enterprise: "micro_enterprise";
104
+ }>;
105
+ title: z.ZodRecord<z.ZodString, z.ZodObject<{
106
+ id: z.ZodNumber;
107
+ language: z.ZodEnum<{
108
+ hy: "hy";
109
+ ru: "ru";
110
+ en: "en";
111
+ multi: "multi";
112
+ }>;
113
+ content: z.ZodString;
114
+ }, z.core.$strip>>;
115
+ }, z.core.$strip>;
116
+ declare const departmentListResponseSchema: z.ZodArray<z.ZodObject<{
117
+ internalId: z.ZodNumber;
118
+ externalId: z.ZodNullable<z.ZodString>;
119
+ taxRegime: z.ZodEnum<{
120
+ vat: "vat";
121
+ vat_exempt: "vat_exempt";
122
+ turnover_tax: "turnover_tax";
123
+ micro_enterprise: "micro_enterprise";
124
+ }>;
125
+ title: z.ZodRecord<z.ZodString, z.ZodObject<{
126
+ id: z.ZodNumber;
127
+ language: z.ZodEnum<{
128
+ hy: "hy";
129
+ ru: "ru";
130
+ en: "en";
131
+ multi: "multi";
132
+ }>;
133
+ content: z.ZodString;
134
+ }, z.core.$strip>>;
135
+ }, z.core.$strip>>;
74
136
  declare const classifierSearchItemSchema: z.ZodObject<{
75
137
  code: z.ZodString;
76
138
  title: z.ZodOptional<z.ZodString>;
@@ -79,6 +141,56 @@ declare const classifierSearchResponseSchema: z.ZodArray<z.ZodObject<{
79
141
  code: z.ZodString;
80
142
  title: z.ZodOptional<z.ZodString>;
81
143
  }, z.core.$strip>>;
144
+ declare const offerListItemSchema: z.ZodObject<{
145
+ id: z.ZodNumber;
146
+ externalId: z.ZodNullable<z.ZodString>;
147
+ type: z.ZodEnum<{
148
+ product: "product";
149
+ service: "service";
150
+ }>;
151
+ classifierCode: z.ZodString;
152
+ defaultMeasureUnit: z.ZodString;
153
+ defaultDepartment: z.ZodObject<{
154
+ internalId: z.ZodNumber;
155
+ }, z.core.$strip>;
156
+ title: z.ZodArray<z.ZodObject<{
157
+ id: z.ZodNumber;
158
+ language: z.ZodEnum<{
159
+ hy: "hy";
160
+ ru: "ru";
161
+ en: "en";
162
+ multi: "multi";
163
+ }>;
164
+ content: z.ZodString;
165
+ }, z.core.$strip>>;
166
+ archivedAt: z.ZodNullable<z.ZodString>;
167
+ createdAt: z.ZodString;
168
+ }, z.core.$strip>;
169
+ declare const offerListResponseSchema: z.ZodArray<z.ZodObject<{
170
+ id: z.ZodNumber;
171
+ externalId: z.ZodNullable<z.ZodString>;
172
+ type: z.ZodEnum<{
173
+ product: "product";
174
+ service: "service";
175
+ }>;
176
+ classifierCode: z.ZodString;
177
+ defaultMeasureUnit: z.ZodString;
178
+ defaultDepartment: z.ZodObject<{
179
+ internalId: z.ZodNumber;
180
+ }, z.core.$strip>;
181
+ title: z.ZodArray<z.ZodObject<{
182
+ id: z.ZodNumber;
183
+ language: z.ZodEnum<{
184
+ hy: "hy";
185
+ ru: "ru";
186
+ en: "en";
187
+ multi: "multi";
188
+ }>;
189
+ content: z.ZodString;
190
+ }, z.core.$strip>>;
191
+ archivedAt: z.ZodNullable<z.ZodString>;
192
+ createdAt: z.ZodString;
193
+ }, z.core.$strip>>;
82
194
  declare const saleDetailResponseSchema: z.ZodObject<{
83
195
  id: z.ZodNumber;
84
196
  createdAt: z.ZodString;
@@ -216,6 +328,11 @@ declare const saleDetailResponseSchema: z.ZodObject<{
216
328
  }, z.core.$strip>;
217
329
  }, z.core.$strip>>;
218
330
  }, z.core.$strip>;
331
+ declare const prepaymentStateSchema: z.ZodEnum<{
332
+ open: "open";
333
+ consumed: "consumed";
334
+ refunded: "refunded";
335
+ }>;
219
336
  declare const prepaymentDetailResponseSchema: z.ZodObject<{
220
337
  id: z.ZodNumber;
221
338
  createdAt: z.ZodString;
@@ -262,6 +379,51 @@ declare const prepaymentDetailResponseSchema: z.ZodObject<{
262
379
  content: z.ZodString;
263
380
  }, z.core.$strip>>;
264
381
  }, z.core.$strip>;
382
+ remaining: z.ZodNumber;
383
+ state: z.ZodEnum<{
384
+ open: "open";
385
+ consumed: "consumed";
386
+ refunded: "refunded";
387
+ }>;
388
+ }, z.core.$strip>;
389
+ declare const prepaymentListItemSchema: z.ZodObject<{
390
+ id: z.ZodNumber;
391
+ createdAt: z.ZodString;
392
+ buyerTin: z.ZodNullable<z.ZodString>;
393
+ cashAmount: z.ZodNumber;
394
+ nonCashAmount: z.ZodNumber;
395
+ remaining: z.ZodNumber;
396
+ state: z.ZodEnum<{
397
+ open: "open";
398
+ consumed: "consumed";
399
+ refunded: "refunded";
400
+ }>;
401
+ }, z.core.$strip>;
402
+ declare const prepaymentListResponseSchema: z.ZodArray<z.ZodObject<{
403
+ id: z.ZodNumber;
404
+ createdAt: z.ZodString;
405
+ buyerTin: z.ZodNullable<z.ZodString>;
406
+ cashAmount: z.ZodNumber;
407
+ nonCashAmount: z.ZodNumber;
408
+ remaining: z.ZodNumber;
409
+ state: z.ZodEnum<{
410
+ open: "open";
411
+ consumed: "consumed";
412
+ refunded: "refunded";
413
+ }>;
414
+ }, z.core.$strip>>;
415
+ declare const customerPrepaymentBalanceResponseSchema: z.ZodObject<{
416
+ entityId: z.ZodNumber;
417
+ customerRef: z.ZodString;
418
+ balance: z.ZodNumber;
419
+ openPrepayments: z.ZodArray<z.ZodObject<{
420
+ prepaymentId: z.ZodNumber;
421
+ createdAt: z.ZodString;
422
+ cashAmount: z.ZodNumber;
423
+ nonCashAmount: z.ZodNumber;
424
+ buyerTin: z.ZodNullable<z.ZodString>;
425
+ remaining: z.ZodNumber;
426
+ }, z.core.$strip>>;
265
427
  }, z.core.$strip>;
266
428
  type RegisterSaleResponse = z.infer<typeof registerSaleResponseSchema>;
267
429
  type RegisterSaleRefundResponse = z.infer<typeof registerSaleRefundResponseSchema>;
@@ -272,8 +434,15 @@ type CreateCashierResponse = z.infer<typeof createCashierResponseSchema>;
272
434
  type CreateDepartmentResponse = z.infer<typeof createDepartmentResponseSchema>;
273
435
  type CashierListItem = z.infer<typeof cashierListItemSchema>;
274
436
  type ClassifierSearchItem = z.infer<typeof classifierSearchItemSchema>;
437
+ type Whoami = z.infer<typeof whoamiResponseSchema>;
438
+ type OfferListItem = z.infer<typeof offerListItemSchema>;
275
439
  type SaleDetail = z.infer<typeof saleDetailResponseSchema>;
276
440
  type PrepaymentDetail = z.infer<typeof prepaymentDetailResponseSchema>;
441
+ type PrepaymentListItem = z.infer<typeof prepaymentListItemSchema>;
442
+ type PrepaymentState = z.infer<typeof prepaymentStateSchema>;
443
+ type CustomerPrepaymentBalance = z.infer<typeof customerPrepaymentBalanceResponseSchema>;
444
+ type DepartmentListItem = z.infer<typeof departmentListItemSchema>;
445
+ type ExchangeRate = z.infer<typeof exchangeRateResponseSchema>;
277
446
 
278
447
  declare const unitsKeys: readonly ["pc", "unit", "set", "box", "pack", "case", "hr", "sess", "proj", "sub", "kg", "l", "m", "g", "ml", "cm", "bottle", "can", "jar", "bag", "m2", "dozen", "pair", "mm", "roll", "tube", "km", "ton", "m3", "pallet", "other"];
279
448
  declare const AVAILABLE_LANGUAGES: readonly ["hy", "ru", "en"];
@@ -318,9 +487,14 @@ type Discounts = {
318
487
  base?: BaseDiscount;
319
488
  additional?: AdditionalDiscount;
320
489
  };
321
- type ExistingOffer = {
490
+ /** Reference an already-created offer by its merchant-provided external id. */
491
+ type ExistingOfferByExternalId = {
322
492
  externalId: string;
323
493
  };
494
+ /** Reference an already-created offer by its VCR-internal numeric id. */
495
+ type ExistingOfferById = {
496
+ id: number;
497
+ };
324
498
  type LocalizedOfferTitle = {
325
499
  type: "localized";
326
500
  content: Partial<Record<Language, string>> & {
@@ -332,6 +506,15 @@ type UniversalOfferTitle = {
332
506
  type: "universal";
333
507
  content: string;
334
508
  };
509
+ /**
510
+ * Canonical offer-title shape shared by inline new offers (`registerSale`),
511
+ * `createOffer`, and `updateOffer`.
512
+ *
513
+ * - `universal` — one string treated as multi-language (brand names like
514
+ * "Coca-Cola").
515
+ * - `localized` — per-language map (`hy` required; `en`/`ru` optional and
516
+ * filled server-side per `localizationStrategy` when missing).
517
+ */
335
518
  type OfferTitle = LocalizedOfferTitle | UniversalOfferTitle;
336
519
  type DepartmentInput = {
337
520
  id: number;
@@ -344,15 +527,45 @@ type NewOffer = {
344
527
  defaultDepartment: DepartmentInput;
345
528
  externalId: string;
346
529
  };
347
- type Offer = NewOffer | ExistingOffer;
530
+ /**
531
+ * A sale-item offer: a brand-new inline offer, or a reference to an existing
532
+ * one by `externalId` or by internal `id`. Mirrors the three wire shapes the
533
+ * server's `POST /sales` accepts.
534
+ */
535
+ type Offer = NewOffer | ExistingOfferByExternalId | ExistingOfferById;
348
536
  type SaleItem = {
349
537
  offer: Offer;
350
538
  department: DepartmentInput;
351
539
  quantity: string;
540
+ /**
541
+ * Unit price. AMD by default. When {@link SaleItem.currency} is set to a
542
+ * non-AMD code, this value is denominated in that foreign currency and VCR
543
+ * converts it to AMD server-side at the authoritative CBA rate — never send
544
+ * a pre-converted AMD figure alongside a `currency`.
545
+ */
352
546
  price: string;
547
+ /**
548
+ * Optional ISO 4217 input currency for foreign-currency sales (HO-234-N,
549
+ * server-side conversion). Omit — or set to `"AMD"` — for a native AMD line.
550
+ *
551
+ * When set to a non-AMD code (e.g. `"USD"`, `"RUB"`), `price` is read in that
552
+ * currency and VCR converts every line to AMD at the previous-business-day
553
+ * CBA mid-market rate; the fiscal receipt is always issued in AMD. All
554
+ * foreign-priced items in one sale MUST share the same currency — mixing two
555
+ * currencies, or AMD and foreign lines, in a single sale is rejected. Pair
556
+ * with `autoSettle` (see {@link RegisterSaleInput}) so you don't have to know
557
+ * the AMD total up front, and preview the applied rate via
558
+ * {@link VCRClient.getExchangeRate}. Normalized to uppercase server-side.
559
+ */
560
+ currency?: string;
353
561
  unit: Unit;
354
562
  discounts?: Discounts;
355
563
  totalAmountTolerance?: string;
564
+ /**
565
+ * eMark codes for this line (Govt Decision 1976-N, effective 2026-05-01).
566
+ * Omit or leave empty for unmarked goods. One entry per physical unit sold.
567
+ */
568
+ emarks?: string[];
356
569
  };
357
570
  type SaleAmount = RequireAtLeastOne<{
358
571
  prepayment?: string;
@@ -364,22 +577,63 @@ type SendReceiptToBuyer = {
364
577
  email: string;
365
578
  language: Language;
366
579
  };
367
- type IndividualBuyer = {
580
+ /**
581
+ * Buyer contact captures used by the desk-side prepayment lookup banner.
582
+ * Independent of {@link SendReceiptToBuyer}: a buyer can be reachable for
583
+ * later lookup without receiving an emailed receipt now. When both
584
+ * `email` and `receipt.email` are present, the server stores `email` for
585
+ * lookup and uses `receipt.email` only for delivery (they may
586
+ * legitimately differ — personal vs billing).
587
+ *
588
+ * `phone` must be E.164 ("+37491234567"). Plain Armenian local format
589
+ * is not accepted at the API boundary — clients should parse with
590
+ * libphonenumber before sending.
591
+ */
592
+ type BuyerContact = {
593
+ email?: string;
594
+ phone?: string;
595
+ };
596
+ type IndividualBuyer = BuyerContact & {
368
597
  type: "individual";
369
598
  receipt?: SendReceiptToBuyer;
370
599
  };
371
- type LegalEntityBuyer = {
600
+ type LegalEntityBuyer = BuyerContact & {
372
601
  type: "business_entity";
373
602
  tin: string;
374
603
  receipt?: SendReceiptToBuyer;
375
604
  };
376
605
  type Buyer = IndividualBuyer | LegalEntityBuyer;
606
+ /**
607
+ * Derived-total payment: name a single tender and VCR settles the whole
608
+ * server-computed AMD cart total on it. Only `cash` / `nonCash` — `prepayment`
609
+ * and `compensation` are ledger draws that must be stated explicitly via
610
+ * {@link SaleAmount}. Ideal for foreign-currency sales (the AMD total isn't
611
+ * known client-side) or any sale that would rather not sum the cart itself.
612
+ */
613
+ type AutoSettle = {
614
+ tender: "cash" | "nonCash";
615
+ };
616
+ /** Explicit AMD amount per tender. Mutually exclusive with `autoSettle`. */
617
+ type PayByAmount = {
618
+ amount: SaleAmount;
619
+ autoSettle?: never;
620
+ };
621
+ /** VCR derives the AMD total onto one tender. Mutually exclusive with `amount`. */
622
+ type PayByAutoSettle = {
623
+ autoSettle: AutoSettle;
624
+ amount?: never;
625
+ };
626
+ /**
627
+ * A sale settles EITHER by explicit `amount` OR by `autoSettle` — exactly one,
628
+ * never both. The `never` guards make passing both a compile error, mirroring
629
+ * the server's cross-field validation.
630
+ */
631
+ type SalePayment = PayByAmount | PayByAutoSettle;
377
632
  type RegisterSaleInput = {
378
633
  cashier: CashierId;
379
634
  items: SaleItem[];
380
- amount: SaleAmount;
381
635
  buyer: Buyer;
382
- };
636
+ } & SalePayment;
383
637
  /** @deprecated Use {@link RegisterSaleInput} instead. Will be removed in 1.0. */
384
638
  type SaleData = RegisterSaleInput;
385
639
  type ClassifierType = "product" | "service";
@@ -425,6 +679,22 @@ type RegisterPrepaymentRefundInput = {
425
679
  type LocalizedName = Partial<Record<Language, string>> & {
426
680
  hy: string;
427
681
  };
682
+ /**
683
+ * Legacy offer-title shape (`{ value, localizationStrategy }`) once required by
684
+ * `createOffer`.
685
+ *
686
+ * @deprecated since 0.14.0 — the server still accepts it but plans removal.
687
+ * Prefer the canonical {@link OfferTitle} (`{ type: "localized", content,
688
+ * localizationStrategy }` or `{ type: "universal", content }`), which is the
689
+ * same shape used by inline offers and `updateOffer`, and additionally
690
+ * supports `universal` (brand-name) titles.
691
+ */
692
+ type LegacyOfferTitle = {
693
+ value: LocalizedName;
694
+ localizationStrategy: "translation" | "transliteration";
695
+ };
696
+ /** Title accepted by {@link CreateOfferInput}: canonical or legacy shape. */
697
+ type CreateOfferTitle = OfferTitle | LegacyOfferTitle;
428
698
  type CreateCashierInput = {
429
699
  name: {
430
700
  value: LocalizedName;
@@ -450,10 +720,7 @@ type CreateDepartmentInput = {
450
720
  type CreateOfferInputProduct = {
451
721
  type: "product";
452
722
  classifierCode: string;
453
- title: {
454
- value: LocalizedName;
455
- localizationStrategy: "translation" | "transliteration";
456
- };
723
+ title: CreateOfferTitle;
457
724
  defaultMeasureUnit: Unit;
458
725
  defaultDepartment: DepartmentInput;
459
726
  externalId?: string;
@@ -462,7 +729,29 @@ type CreateOfferInputService = Omit<CreateOfferInputProduct, "type"> & {
462
729
  type: "service";
463
730
  };
464
731
  type CreateOfferInput = CreateOfferInputProduct | CreateOfferInputService;
732
+ /** Body of {@link VCRClient.updateOffer} — a new title for an existing offer. */
733
+ type UpdateOfferInput = {
734
+ title: OfferTitle;
735
+ };
736
+ /** Filter for {@link VCRClient.listOffers}. */
737
+ type ListOffersFilter = {
738
+ /** Exact-match filter by merchant-provided `externalId`. */
739
+ externalId?: string;
740
+ /** Filter by offer type. */
741
+ type?: "product" | "service";
742
+ /** When true, also include archived offers. Defaults to false. */
743
+ includeArchived?: boolean;
744
+ };
465
745
 
746
+ type ListPrepaymentsFilter = {
747
+ /** Exact-match filter against ledger.customerRef (TIN / phone / email). */
748
+ customerRef?: string;
749
+ /**
750
+ * Filter by derived lifecycle state. `all` (the default) returns every
751
+ * prepayment; the other values filter to a single lifecycle stage.
752
+ */
753
+ state?: PrepaymentState | "all";
754
+ };
466
755
  type VCRClientOptions = {
467
756
  /** Base URL for the VCR API. Defaults to https://vcr.am/api/v1. */
468
757
  baseUrl?: string;
@@ -474,16 +763,72 @@ type VCRClientOptions = {
474
763
  declare class VCRClient {
475
764
  #private;
476
765
  constructor(apiKey: string, options?: VCRClientOptions);
766
+ /**
767
+ * Resolve which VCR the calling API key belongs to. Returns the register's
768
+ * identity, its `mode` (`production` / `sandbox`), and the owning business
769
+ * entity. Works on freshly-imported VCRs that have not been activated yet
770
+ * (in which case `crn` is `null`) — handy as a cheap SDK health-check and to
771
+ * tell production keys apart from sandbox ones.
772
+ */
773
+ whoami(options?: RequestOptions): Promise<Whoami>;
477
774
  registerSale(data: RegisterSaleInput, options?: RequestOptions): Promise<RegisterSaleResponse>;
478
775
  getSale(saleId: number, options?: RequestOptions): Promise<SaleDetail>;
479
776
  registerSaleRefund(data: RegisterSaleRefundInput, options?: RequestOptions): Promise<RegisterSaleRefundResponse>;
480
777
  registerPrepayment(data: RegisterPrepaymentInput, options?: RequestOptions): Promise<RegisterPrepaymentResponse>;
481
778
  getPrepayment(prepaymentId: number, options?: RequestOptions): Promise<PrepaymentDetail>;
482
779
  registerPrepaymentRefund(data: RegisterPrepaymentRefundInput, options?: RequestOptions): Promise<RegisterPrepaymentRefundResponse>;
780
+ /**
781
+ * List prepayments registered through the calling VCR. Server caps the
782
+ * response at 500 rows; for larger sets, narrow with `customerRef` or
783
+ * paginate by `id` outside the SDK.
784
+ *
785
+ * `remaining` and `state` are derived from the ledger — call this whenever
786
+ * you want a current snapshot rather than caching the result.
787
+ */
788
+ listPrepayments(filter?: ListPrepaymentsFilter, options?: RequestOptions): Promise<PrepaymentListItem[]>;
789
+ /**
790
+ * Get a customer's open prepayment balance scoped to the BusinessEntity
791
+ * that owns the calling VCR's API key. Because the ledger is entity-scoped,
792
+ * the result reflects deposits made through any VCR belonging to the same
793
+ * entity — merchants who run more than one VCR see a single wallet.
794
+ *
795
+ * `customerRef` is matched exactly against the ledger — typically a TIN,
796
+ * normalized E.164 phone, or lowercased email. Use whichever identifier the
797
+ * customer gave at deposit time; identities are not auto-merged across
798
+ * different ref types.
799
+ */
800
+ getCustomerPrepaymentBalance(input: {
801
+ customerRef: string;
802
+ }, options?: RequestOptions): Promise<CustomerPrepaymentBalance>;
483
803
  listCashiers(options?: RequestOptions): Promise<CashierListItem[]>;
484
804
  createCashier(data: CreateCashierInput, options?: RequestOptions): Promise<CreateCashierResponse>;
485
805
  createOffer(data: CreateOfferInput, options?: RequestOptions): Promise<CreateOfferResponse>;
806
+ /**
807
+ * List offers belonging to the calling VCR. Server caps the response at 500
808
+ * rows; narrow with `externalId` / `type` for larger catalogs. Archived
809
+ * offers are excluded unless `includeArchived` is set.
810
+ *
811
+ * A common use is checking whether an offer already exists (by `externalId`)
812
+ * before creating it.
813
+ */
814
+ listOffers(filter?: ListOffersFilter, options?: RequestOptions): Promise<OfferListItem[]>;
815
+ getOffer(offerId: number, options?: RequestOptions): Promise<OfferListItem>;
816
+ /**
817
+ * Rename an offer's title. Affects only future receipts — already-issued
818
+ * receipts keep the title they were created with, and the SRC fiscal record
819
+ * is unchanged. Missing `en`/`ru` are filled per `localizationStrategy`,
820
+ * exactly as on offer creation. Returns the updated offer.
821
+ */
822
+ updateOffer(offerId: number, data: UpdateOfferInput, options?: RequestOptions): Promise<OfferListItem>;
486
823
  createDepartment(data: CreateDepartmentInput, options?: RequestOptions): Promise<CreateDepartmentResponse>;
824
+ /**
825
+ * List departments configured on the calling VCR — `internalId`,
826
+ * `externalId`, `taxRegime`, and the localized `title`. Mirrors the
827
+ * dashboard catalog: only departments confirmed by the tax service are
828
+ * returned, so the `internalId` field is safe to reference from a sale
829
+ * item's `department.id`.
830
+ */
831
+ listDepartments(options?: RequestOptions): Promise<DepartmentListItem[]>;
487
832
  searchClassifier(input: SearchClassifierInput, options?: RequestOptions): Promise<ClassifierSearchItem[]>;
488
833
  /**
489
834
  * @deprecated Use {@link searchClassifier} with an options object. Will be
@@ -491,6 +836,20 @@ declare class VCRClient {
491
836
  * future params can be added without breaking the call site.
492
837
  */
493
838
  searchClassifierCategory(query: string, type: ClassifierType, language: Language, options?: RequestOptions): Promise<ClassifierSearchItem[]>;
839
+ /**
840
+ * Preview the AMD conversion rate VCR would apply to a foreign-currency sale
841
+ * registered now — the CBA mid-market rate published on the previous business
842
+ * day (Tax Code art. 16, HO-234-N). Use it to show a buyer the AMD equivalent
843
+ * before charging. The sale itself is converted server-side from each item's
844
+ * `currency` + `price` (see {@link RegisterSaleInput}); this endpoint is a
845
+ * read-only preview and does not fiscalize anything.
846
+ *
847
+ * `currency` is a 3-letter ISO 4217 code, case-insensitive. `AMD` is rejected
848
+ * (it is the native receipt currency and needs no conversion).
849
+ */
850
+ getExchangeRate(input: {
851
+ currency: string;
852
+ }, options?: RequestOptions): Promise<ExchangeRate>;
494
853
  }
495
854
 
496
855
  type ApiErrorIssue = {
@@ -501,6 +860,12 @@ type ApiErrorIssue = {
501
860
  type ApiErrorBody = {
502
861
  error: string;
503
862
  issues?: Array<ApiErrorIssue>;
863
+ /**
864
+ * Server-generated correlation ID, present on unexpected 5xx responses.
865
+ * Include it when reporting the issue to support so the matching log entry
866
+ * and Sentry event can be located.
867
+ */
868
+ requestId?: string;
504
869
  };
505
870
  /**
506
871
  * Base class for every error thrown by the SDK.
@@ -547,4 +912,4 @@ declare class VCRNetworkError extends VCRError {
547
912
  });
548
913
  }
549
914
 
550
- export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type Discounts, type Language, type LocalizedName, type NewOffer, type Offer, type OfferTitle, type PrepaymentAmount, type PrepaymentDetail, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SearchClassifierInput, type SendReceiptToBuyer, TAX_REGIMES, type TaxRegime, type Unit, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, prepaymentDetailResponseSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys };
915
+ export { AVAILABLE_LANGUAGES, type ApiErrorBody, type ApiErrorIssue, type AutoSettle, type Buyer, type CashierId, type CashierListItem, type ClassifierSearchItem, type ClassifierType, type CreateCashierInput, type CreateCashierResponse, type CreateDepartmentInput, type CreateDepartmentResponse, type CreateOfferInput, type CreateOfferInputProduct, type CreateOfferInputService, type CreateOfferResponse, type CreateOfferTitle, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, type ExchangeRate, type Language, type LegacyOfferTitle, type ListOffersFilter, type ListPrepaymentsFilter, type LocalizedName, type NewOffer, type Offer, type OfferListItem, type OfferTitle, type PrepaymentAmount, type PrepaymentDetail, type PrepaymentListItem, type PrepaymentState, REFUND_REASONS, type RefundAmount, type RefundItemInput, type RefundReason, type RegisterPrepaymentInput, type RegisterPrepaymentRefundInput, type RegisterPrepaymentRefundResponse, type RegisterPrepaymentResponse, type RegisterSaleInput, type RegisterSaleRefundInput, type RegisterSaleRefundResponse, type RegisterSaleResponse, type RequestOptions, type SaleAmount, type SaleData, type SaleDetail, type SaleItem, type SalePayment, type SearchClassifierInput, type SendReceiptToBuyer, TAX_REGIMES, type TaxRegime, type Unit, type UpdateOfferInput, VCRApiError, VCRClient, type VCRClientOptions, VCRError, VCRNetworkError, VCRValidationError, type Whoami, cashierListItemSchema, cashierListResponseSchema, classifierSearchItemSchema, classifierSearchResponseSchema, createCashierResponseSchema, createDepartmentResponseSchema, createOfferResponseSchema, customerPrepaymentBalanceResponseSchema, departmentListItemSchema, departmentListResponseSchema, exchangeRateResponseSchema, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys, whoamiResponseSchema };