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

package/lib/index.d.ts

@@ -45,6 +45,15 @@ declare const createDepartmentResponseSchema: z.ZodObject<{
     message: z.ZodString;
     department: z.ZodNumber;
 }, z.core.$strip>;
+declare const exchangeRateResponseSchema: z.ZodObject<{
+    currency: z.ZodString;
+    ratePerUnit: z.ZodNumber;
+    amount: z.ZodNumber;
+    rateDate: z.ZodString;
+    saleDate: z.ZodString;
+    ruleVersion: z.ZodString;
+    source: z.ZodLiteral<"CBA">;
+}, z.core.$strip>;
 declare const whoamiResponseSchema: z.ZodObject<{
     vcrId: z.ZodNumber;
     crn: z.ZodNullable<z.ZodString>;
@@ -186,6 +195,7 @@ declare const saleDetailResponseSchema: z.ZodObject<{
     id: z.ZodNumber;
     createdAt: z.ZodString;
     buyerTin: z.ZodNullable<z.ZodString>;
+    comment: z.ZodNullable<z.ZodString>;
     cashAmount: z.ZodNumber;
     nonCashAmount: z.ZodNumber;
     prepaymentAmount: z.ZodNumber;
@@ -433,6 +443,7 @@ type PrepaymentListItem = z.infer<typeof prepaymentListItemSchema>;
 type PrepaymentState = z.infer<typeof prepaymentStateSchema>;
 type CustomerPrepaymentBalance = z.infer<typeof customerPrepaymentBalanceResponseSchema>;
 type DepartmentListItem = z.infer<typeof departmentListItemSchema>;
+type ExchangeRate = z.infer<typeof exchangeRateResponseSchema>;
 
 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"];
 declare const AVAILABLE_LANGUAGES: readonly ["hy", "ru", "en"];
@@ -527,7 +538,27 @@ type SaleItem = {
     offer: Offer;
     department: DepartmentInput;
     quantity: string;
+    /**
+     * Unit price. AMD by default. When {@link SaleItem.currency} is set to a
+     * non-AMD code, this value is denominated in that foreign currency and VCR
+     * converts it to AMD server-side at the authoritative CBA rate — never send
+     * a pre-converted AMD figure alongside a `currency`.
+     */
     price: string;
+    /**
+     * Optional ISO 4217 input currency for foreign-currency sales (HO-234-N,
+     * server-side conversion). Omit — or set to `"AMD"` — for a native AMD line.
+     *
+     * When set to a non-AMD code (e.g. `"USD"`, `"RUB"`), `price` is read in that
+     * currency and VCR converts every line to AMD at the previous-business-day
+     * CBA mid-market rate; the fiscal receipt is always issued in AMD. All
+     * foreign-priced items in one sale MUST share the same currency — mixing two
+     * currencies, or AMD and foreign lines, in a single sale is rejected. Pair
+     * with `autoSettle` (see {@link RegisterSaleInput}) so you don't have to know
+     * the AMD total up front, and preview the applied rate via
+     * {@link VCRClient.getExchangeRate}. Normalized to uppercase server-side.
+     */
+    currency?: string;
     unit: Unit;
     discounts?: Discounts;
     totalAmountTolerance?: string;
@@ -537,27 +568,6 @@ type SaleItem = {
      */
     emarks?: string[];
 };
-/**
- * Foreign-currency input trail (HO-234-N). Present only when the sale was
- * entered in a non-AMD currency; omit it entirely for native-AMD sales.
- *
- * The AMD `price` values in `items[]` remain the authoritative fiscal figures.
- * This block carries the raw foreign inputs plus the CBA rate the client used;
- * the server re-resolves the previous-business-day rate and rejects the sale
- * if the supplied rate is stale.
- */
-type CurrencyConversionInput = {
-    /** 3-letter ISO 4217 code (normalized to uppercase server-side). Not AMD. */
-    currency: string;
-    /** AMD per one unit of `currency` (CBA rate / amount). */
-    ratePerUnit: string;
-    /** Rate date in `YYYY-MM-DD` (CBA previous business day). */
-    rateDate: string;
-    /** Per-line foreign unit prices, index-aligned to `items[]`. At least one. */
-    lines: Array<{
-        foreignUnitPrice: string;
-    }>;
-};
 type SaleAmount = RequireAtLeastOne<{
     prepayment?: string;
     compensation?: string;
@@ -594,17 +604,44 @@ type LegalEntityBuyer = BuyerContact & {
     receipt?: SendReceiptToBuyer;
 };
 type Buyer = IndividualBuyer | LegalEntityBuyer;
+/**
+ * Derived-total payment: name a single tender and VCR settles the whole
+ * server-computed AMD cart total on it. Only `cash` / `nonCash` — `prepayment`
+ * and `compensation` are ledger draws that must be stated explicitly via
+ * {@link SaleAmount}. Ideal for foreign-currency sales (the AMD total isn't
+ * known client-side) or any sale that would rather not sum the cart itself.
+ */
+type AutoSettle = {
+    tender: "cash" | "nonCash";
+};
+/** Explicit AMD amount per tender. Mutually exclusive with `autoSettle`. */
+type PayByAmount = {
+    amount: SaleAmount;
+    autoSettle?: never;
+};
+/** VCR derives the AMD total onto one tender. Mutually exclusive with `amount`. */
+type PayByAutoSettle = {
+    autoSettle: AutoSettle;
+    amount?: never;
+};
+/**
+ * A sale settles EITHER by explicit `amount` OR by `autoSettle` — exactly one,
+ * never both. The `never` guards make passing both a compile error, mirroring
+ * the server's cross-field validation.
+ */
+type SalePayment = PayByAmount | PayByAutoSettle;
 type RegisterSaleInput = {
     cashier: CashierId;
     items: SaleItem[];
+    buyer: Buyer;
     /**
-     * Optional foreign-currency input. Absent => native-AMD sale, byte-identical
-     * to the pre-existing behaviour. See {@link CurrencyConversionInput}.
+     * Optional merchant-internal note, e.g. an external payment reference. Max
+     * 500 characters; control characters are stripped and surrounding whitespace
+     * trimmed server-side. It is purely internal: never printed on the buyer's
+     * receipt and never sent to the tax authority (SRC).
      */
-    currencyConversion?: CurrencyConversionInput;
-    amount: SaleAmount;
-    buyer: Buyer;
-};
+    comment?: string;
+} & SalePayment;
 /** @deprecated Use {@link RegisterSaleInput} instead. Will be removed in 1.0. */
 type SaleData = RegisterSaleInput;
 type ClassifierType = "product" | "service";
@@ -807,6 +844,20 @@ declare class VCRClient {
      *   future params can be added without breaking the call site.
      */
     searchClassifierCategory(query: string, type: ClassifierType, language: Language, options?: RequestOptions): Promise<ClassifierSearchItem[]>;
+    /**
+     * Preview the AMD conversion rate VCR would apply to a foreign-currency sale
+     * registered now — the CBA mid-market rate published on the previous business
+     * day (Tax Code art. 16, HO-234-N). Use it to show a buyer the AMD equivalent
+     * before charging. The sale itself is converted server-side from each item's
+     * `currency` + `price` (see {@link RegisterSaleInput}); this endpoint is a
+     * read-only preview and does not fiscalize anything.
+     *
+     * `currency` is a 3-letter ISO 4217 code, case-insensitive. `AMD` is rejected
+     * (it is the native receipt currency and needs no conversion).
+     */
+    getExchangeRate(input: {
+        currency: string;
+    }, options?: RequestOptions): Promise<ExchangeRate>;
 }
 
 type ApiErrorIssue = {
@@ -869,4 +920,4 @@ declare class VCRNetworkError extends VCRError {
     });
 }
 
-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, type CreateOfferTitle, type CurrencyConversionInput, type CustomerPrepaymentBalance, DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, type DepartmentInput, type DepartmentListItem, type Discounts, 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 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, offerListItemSchema, offerListResponseSchema, prepaymentDetailResponseSchema, prepaymentListItemSchema, prepaymentListResponseSchema, prepaymentStateSchema, registerPrepaymentRefundResponseSchema, registerPrepaymentResponseSchema, registerSaleRefundResponseSchema, registerSaleResponseSchema, saleDetailResponseSchema, unitsKeys, whoamiResponseSchema };
+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 };