@dodobrands/pos-receipts-plugin-contracts 5.13.2 → 5.13.4

package/README.en.md

@@ -0,0 +1,36 @@
+# @dodobrands/pos-receipts-plugin-contracts
+
+Public contracts for fiscal cash register (Cash Register) plugins. Implemented by fiscal printer plugin authors.
+
+Full documentation: [dodopizza.github.io/cashierapp](https://dodopizza.github.io/cashierapp/)
+
+---
+
+## Main Interface: `ICashRegister`
+
+```ts
+export interface ICashRegister {
+  initialize?: (options: InitializationOptions) => Promise<void>;
+  getSettings: () => Promise<CashRegisterSettings>;
+  handleSale: (request: HandleSaleRequest) => Promise<PrintedReceipt>;
+
+  // Optional
+  handleRefund?: (request: HandleRefundRequest) => Promise<PrintedRefundReceipt>;
+  makeXReport?: () => Promise<void>;
+  makeZReport?: (options: MakeZReportOptions) => Promise<void>;
+  withdrawCash?: (options: WithdrawCashOptions) => Promise<void>;
+  depositCash?: (options: DepositCashOptions) => Promise<void>;
+  printText?: (options: PrintTextOptions) => Promise<void>;
+}
+```
+
+Start by exploring [`src/ICashRegister.ts`](./src/ICashRegister.ts).
+
+The `Receipt` type contains complete information about the order, customer, taxes, organization, and country-specific marking data (Russia, Belarus, Uzbekistan, Kazakhstan).
+
+---
+
+## Related Packages
+
+- [`@dodopizza/pos-receipts-ipc-client`](../../private/pos-receipts-ipc-client/README.en.md) — ready-made IPC client for Electron using these contracts
+- [`@dodobrands/pos-plugins-shared-models`](../../shared/pos-plugins-shared-models/README.en.md) — shared models (`Business`, `Country`, `ILogger`)

package/README.md

@@ -0,0 +1,36 @@
+# @dodobrands/pos-receipts-plugin-contracts
+
+Публичные контракты для плагинов фискальных касс (Cash Register). Реализуется авторами плагинов фискальных принтеров.
+
+Полная документация: [dodopizza.github.io/cashierapp](https://dodopizza.github.io/cashierapp/)
+
+---
+
+## Основной интерфейс: `ICashRegister`
+
+```ts
+export interface ICashRegister {
+  initialize?: (options: InitializationOptions) => Promise<void>;
+  getSettings: () => Promise<CashRegisterSettings>;
+  handleSale: (request: HandleSaleRequest) => Promise<PrintedReceipt>;
+
+  // Опциональные
+  handleRefund?: (request: HandleRefundRequest) => Promise<PrintedRefundReceipt>;
+  makeXReport?: () => Promise<void>;
+  makeZReport?: (options: MakeZReportOptions) => Promise<void>;
+  withdrawCash?: (options: WithdrawCashOptions) => Promise<void>;
+  depositCash?: (options: DepositCashOptions) => Promise<void>;
+  printText?: (options: PrintTextOptions) => Promise<void>;
+}
+```
+
+Начните с изучения [`src/ICashRegister.ts`](./src/ICashRegister.ts).
+
+Тип `Receipt` содержит полную информацию о заказе, покупателе, налогах, организации и страно-специфичных данных маркировки (Россия, Беларусь, Узбекистан, Казахстан).
+
+---
+
+## Смежные пакеты
+
+- [`@dodopizza/pos-receipts-ipc-client`](../../private/pos-receipts-ipc-client/README.md) — готовый IPC-клиент для Electron, использующий эти контракты
+- [`@dodobrands/pos-plugins-shared-models`](../../shared/pos-plugins-shared-models/README.md) — общие модели (`Business`, `Country`, `ILogger`)

package/dist/index.d.cts

@@ -106,6 +106,29 @@ interface ILogger<TScope extends Record<string, unknown> = never> {
     fatal<T>(message: string, error?: unknown, metadata?: ErrorMessageMetadataWith<T>): void;
 }
 
+interface IDigitalReceipt {
+    views: DigitalReceiptView[];
+    fields?: Fields;
+    version: 'v1';
+}
+type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
+type DigitalReceiptView = {
+    type: DigitalReceiptViewType;
+    data: string;
+};
+type Fields = {
+    type: 'FPtr10';
+    fnNumber: string;
+    fiscalDocumentSign: string;
+    fiscalDocumentNumber: string;
+};
+
+type FiscalizationPayload = {
+    ReceiptId: string;
+    Payload: string;
+    DigitalReceipt: IDigitalReceipt;
+};
+
 /**
  * Unique identifier of the transaction
  */
@@ -189,11 +212,17 @@ type TextSlipData = {
  */
 type SlipData = TextSlipData;
 
-type QrPaymentResult = {
+type BasePaymentResult = {
     /**
      * Information about the payment.
      */
     paymentInfo: PaymentInfo;
+    /**
+     * Fiscalization payload returned by 2-in-1 devices.
+     */
+    fiscalizationPayload?: FiscalizationPayload;
+};
+type QrPaymentResult = BasePaymentResult & {
     /**
      * QR code data
      */
@@ -202,11 +231,7 @@ type QrPaymentResult = {
 /**
  * Represents the payment result for CARD payment request
  */
-type CardPaymentResult = {
-    /**
-     * Information about the payment.
-     */
-    paymentInfo: PaymentInfo;
+type CardPaymentResult = BasePaymentResult & {
     /**
      * Data for slip
      */
@@ -538,7 +563,7 @@ interface CashRegisterSettings {
     };
 }
 
-type BaseReceiptRefundInfo = {
+type ReceiptRefundInfo = {
     /** The payment provider used for this transaction (e.g. "Ibox", "KaspiQr"). */
     paymentProvider: PaymentProvider;
     /** The final status of the payment at the time of printing. */
@@ -549,21 +574,6 @@ type BaseReceiptRefundInfo = {
      */
     orderRefundResult?: OrderRefundResult;
 };
-type KioskRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.Kiosk;
-};
-type RestaurantCashierRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.RestaurantCashier;
-};
-type JobRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.RefundJob;
-};
-/**
- * Refund context passed to the receipt plugin when printing a refund receipt.
- * Discriminated union on `refundSource` — add source-specific fields to the
- * corresponding branch as needed.
- */
-type ReceiptRefundInfo = KioskRefundInfo | RestaurantCashierRefundInfo | JobRefundInfo;
 
 /**
  * Obsolete Receipt interface backward compatibility.
@@ -577,7 +587,7 @@ interface HandleRefundRequestClear {
     refundInfo?: ReceiptRefundInfo;
 }
 
-type BaseReceiptPaymentInfo = {
+type ReceiptPaymentInfo = {
     /** The payment provider used for this transaction (e.g. "Ibox", "KaspiQr"). */
     paymentProvider: PaymentProvider;
     /** The final status of the payment at the time of printing. */
@@ -588,18 +598,6 @@ type BaseReceiptPaymentInfo = {
      */
     orderPaymentResult?: OrderPaymentResult;
 };
-type KioskPaymentInfo = BaseReceiptPaymentInfo & {
-    paymentSource: PaymentSource.Kiosk;
-};
-type RestaurantCashierPaymentInfo = BaseReceiptPaymentInfo & {
-    paymentSource: PaymentSource.RestaurantCashier;
-};
-/**
- * Payment context passed to the receipt plugin when printing a receipt.
- * Discriminated union on `paymentSource` — add source-specific fields to the
- * corresponding branch as needed.
- */
-type ReceiptPaymentInfo = KioskPaymentInfo | RestaurantCashierPaymentInfo;
 
 /**
  * Obsolete Receipt interface backward compatibility.
@@ -636,23 +634,6 @@ interface MakeZReportOptions {
     withoutPaper?: boolean;
 }
 
-interface IDigitalReceipt {
-    views: DigitalReceiptView[];
-    fields?: Fields;
-    version: 'v1';
-}
-type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
-type DigitalReceiptView = {
-    type: DigitalReceiptViewType;
-    data: string;
-};
-type Fields = {
-    type: 'FPtr10';
-    fnNumber: string;
-    fiscalDocumentSign: string;
-    fiscalDocumentNumber: string;
-};
-
 /** Other types of receipts may appear here */
 type PrintedReceipt = PrintedFiscalReceipt | PrintedNonFiscalReceipt;
 interface PrintedFiscalReceipt {
@@ -752,4 +733,4 @@ declare enum DigitalReceiptNotificationPreference {
     PhoneSms = "PhoneSms"
 }
 
-export { type AddedIngredient, Business, type CardInfo, type CardPaymentResult, type CardRefundResult, type CashRegister, type CashRegisterSettings, type Cashier, type Country, type CountryIsoCode, type CreateScopeOptions, type Customer, type DepositCashOptions, DigitalReceiptNotificationPreference, type DigitalReceiptView, type DigitalReceiptViewType, type ErrorMessageMetadataWith, type Fields, type HTMLContentData, type HTMLContentType, type HandleRefundRequest, type HandleRefundRequestClear, type HandleSaleRequest, type HandleSaleRequestClear, type ICashRegister, type IDigitalReceipt, type ILogger, type Image, type InitializationOptions, type JobRefundInfo, type KazakhstanProductData, type KioskPaymentInfo, type KioskRefundInfo, KnownCountryCodes, type KyrgyzstanProductData, type Loyalty, type MakeZReportOptions, type MarkingCodes, type Message, type MessageMetadata, type MessageMetadataWith, type MessageWith, type Money, type OperationIdentifiers, type Order, type OrderPaymentResult, type OrderPrice, type OrderRefundResult, OrderSource, OrderType, type Organization, OwnerType, type PaymentInfo, PaymentMode, type PaymentProvider, type PaymentResult, PaymentSource, PaymentStatus, PaymentType, type PreviousReceipt, type PrintParams, type PrintTextOptions, type PrintedFiscalReceipt, type PrintedNonFiscalReceipt, type PrintedReceipt, type PrintedRefundReceipt, type Product, type ProductPrice, type ProductSpecificData, type QRData, type QRIdData, type QRIdType, type QrPaymentResult, type QrRefundResult, type Receipt, type ReceiptPaymentInfo, type ReceiptRefundInfo, type RefundInfo, type RefundResult, RefundSource, type RestaurantCashierPaymentInfo, type RestaurantCashierRefundInfo, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };
+export { type AddedIngredient, Business, type CardInfo, type CardPaymentResult, type CardRefundResult, type CashRegister, type CashRegisterSettings, type Cashier, type Country, type CountryIsoCode, type CreateScopeOptions, type Customer, type DepositCashOptions, DigitalReceiptNotificationPreference, type DigitalReceiptView, type DigitalReceiptViewType, type ErrorMessageMetadataWith, type Fields, type FiscalizationPayload, type HTMLContentData, type HTMLContentType, type HandleRefundRequest, type HandleRefundRequestClear, type HandleSaleRequest, type HandleSaleRequestClear, type ICashRegister, type IDigitalReceipt, type ILogger, type Image, type InitializationOptions, type KazakhstanProductData, KnownCountryCodes, type KyrgyzstanProductData, type Loyalty, type MakeZReportOptions, type MarkingCodes, type Message, type MessageMetadata, type MessageMetadataWith, type MessageWith, type Money, type OperationIdentifiers, type Order, type OrderPaymentResult, type OrderPrice, type OrderRefundResult, OrderSource, OrderType, type Organization, OwnerType, type PaymentInfo, PaymentMode, type PaymentProvider, type PaymentResult, PaymentSource, PaymentStatus, PaymentType, type PreviousReceipt, type PrintParams, type PrintTextOptions, type PrintedFiscalReceipt, type PrintedNonFiscalReceipt, type PrintedReceipt, type PrintedRefundReceipt, type Product, type ProductPrice, type ProductSpecificData, type QRData, type QRIdData, type QRIdType, type QrPaymentResult, type QrRefundResult, type Receipt, type ReceiptPaymentInfo, type ReceiptRefundInfo, type RefundInfo, type RefundResult, RefundSource, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };

package/dist/index.d.ts

@@ -106,6 +106,29 @@ interface ILogger<TScope extends Record<string, unknown> = never> {
     fatal<T>(message: string, error?: unknown, metadata?: ErrorMessageMetadataWith<T>): void;
 }
 
+interface IDigitalReceipt {
+    views: DigitalReceiptView[];
+    fields?: Fields;
+    version: 'v1';
+}
+type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
+type DigitalReceiptView = {
+    type: DigitalReceiptViewType;
+    data: string;
+};
+type Fields = {
+    type: 'FPtr10';
+    fnNumber: string;
+    fiscalDocumentSign: string;
+    fiscalDocumentNumber: string;
+};
+
+type FiscalizationPayload = {
+    ReceiptId: string;
+    Payload: string;
+    DigitalReceipt: IDigitalReceipt;
+};
+
 /**
  * Unique identifier of the transaction
  */
@@ -189,11 +212,17 @@ type TextSlipData = {
  */
 type SlipData = TextSlipData;
 
-type QrPaymentResult = {
+type BasePaymentResult = {
     /**
      * Information about the payment.
      */
     paymentInfo: PaymentInfo;
+    /**
+     * Fiscalization payload returned by 2-in-1 devices.
+     */
+    fiscalizationPayload?: FiscalizationPayload;
+};
+type QrPaymentResult = BasePaymentResult & {
     /**
      * QR code data
      */
@@ -202,11 +231,7 @@ type QrPaymentResult = {
 /**
  * Represents the payment result for CARD payment request
  */
-type CardPaymentResult = {
-    /**
-     * Information about the payment.
-     */
-    paymentInfo: PaymentInfo;
+type CardPaymentResult = BasePaymentResult & {
     /**
      * Data for slip
      */
@@ -538,7 +563,7 @@ interface CashRegisterSettings {
     };
 }
 
-type BaseReceiptRefundInfo = {
+type ReceiptRefundInfo = {
     /** The payment provider used for this transaction (e.g. "Ibox", "KaspiQr"). */
     paymentProvider: PaymentProvider;
     /** The final status of the payment at the time of printing. */
@@ -549,21 +574,6 @@ type BaseReceiptRefundInfo = {
      */
     orderRefundResult?: OrderRefundResult;
 };
-type KioskRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.Kiosk;
-};
-type RestaurantCashierRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.RestaurantCashier;
-};
-type JobRefundInfo = BaseReceiptRefundInfo & {
-    refundSource: RefundSource.RefundJob;
-};
-/**
- * Refund context passed to the receipt plugin when printing a refund receipt.
- * Discriminated union on `refundSource` — add source-specific fields to the
- * corresponding branch as needed.
- */
-type ReceiptRefundInfo = KioskRefundInfo | RestaurantCashierRefundInfo | JobRefundInfo;
 
 /**
  * Obsolete Receipt interface backward compatibility.
@@ -577,7 +587,7 @@ interface HandleRefundRequestClear {
     refundInfo?: ReceiptRefundInfo;
 }
 
-type BaseReceiptPaymentInfo = {
+type ReceiptPaymentInfo = {
     /** The payment provider used for this transaction (e.g. "Ibox", "KaspiQr"). */
     paymentProvider: PaymentProvider;
     /** The final status of the payment at the time of printing. */
@@ -588,18 +598,6 @@ type BaseReceiptPaymentInfo = {
      */
     orderPaymentResult?: OrderPaymentResult;
 };
-type KioskPaymentInfo = BaseReceiptPaymentInfo & {
-    paymentSource: PaymentSource.Kiosk;
-};
-type RestaurantCashierPaymentInfo = BaseReceiptPaymentInfo & {
-    paymentSource: PaymentSource.RestaurantCashier;
-};
-/**
- * Payment context passed to the receipt plugin when printing a receipt.
- * Discriminated union on `paymentSource` — add source-specific fields to the
- * corresponding branch as needed.
- */
-type ReceiptPaymentInfo = KioskPaymentInfo | RestaurantCashierPaymentInfo;
 
 /**
  * Obsolete Receipt interface backward compatibility.
@@ -636,23 +634,6 @@ interface MakeZReportOptions {
     withoutPaper?: boolean;
 }
 
-interface IDigitalReceipt {
-    views: DigitalReceiptView[];
-    fields?: Fields;
-    version: 'v1';
-}
-type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
-type DigitalReceiptView = {
-    type: DigitalReceiptViewType;
-    data: string;
-};
-type Fields = {
-    type: 'FPtr10';
-    fnNumber: string;
-    fiscalDocumentSign: string;
-    fiscalDocumentNumber: string;
-};
-
 /** Other types of receipts may appear here */
 type PrintedReceipt = PrintedFiscalReceipt | PrintedNonFiscalReceipt;
 interface PrintedFiscalReceipt {
@@ -752,4 +733,4 @@ declare enum DigitalReceiptNotificationPreference {
     PhoneSms = "PhoneSms"
 }
 
-export { type AddedIngredient, Business, type CardInfo, type CardPaymentResult, type CardRefundResult, type CashRegister, type CashRegisterSettings, type Cashier, type Country, type CountryIsoCode, type CreateScopeOptions, type Customer, type DepositCashOptions, DigitalReceiptNotificationPreference, type DigitalReceiptView, type DigitalReceiptViewType, type ErrorMessageMetadataWith, type Fields, type HTMLContentData, type HTMLContentType, type HandleRefundRequest, type HandleRefundRequestClear, type HandleSaleRequest, type HandleSaleRequestClear, type ICashRegister, type IDigitalReceipt, type ILogger, type Image, type InitializationOptions, type JobRefundInfo, type KazakhstanProductData, type KioskPaymentInfo, type KioskRefundInfo, KnownCountryCodes, type KyrgyzstanProductData, type Loyalty, type MakeZReportOptions, type MarkingCodes, type Message, type MessageMetadata, type MessageMetadataWith, type MessageWith, type Money, type OperationIdentifiers, type Order, type OrderPaymentResult, type OrderPrice, type OrderRefundResult, OrderSource, OrderType, type Organization, OwnerType, type PaymentInfo, PaymentMode, type PaymentProvider, type PaymentResult, PaymentSource, PaymentStatus, PaymentType, type PreviousReceipt, type PrintParams, type PrintTextOptions, type PrintedFiscalReceipt, type PrintedNonFiscalReceipt, type PrintedReceipt, type PrintedRefundReceipt, type Product, type ProductPrice, type ProductSpecificData, type QRData, type QRIdData, type QRIdType, type QrPaymentResult, type QrRefundResult, type Receipt, type ReceiptPaymentInfo, type ReceiptRefundInfo, type RefundInfo, type RefundResult, RefundSource, type RestaurantCashierPaymentInfo, type RestaurantCashierRefundInfo, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };
+export { type AddedIngredient, Business, type CardInfo, type CardPaymentResult, type CardRefundResult, type CashRegister, type CashRegisterSettings, type Cashier, type Country, type CountryIsoCode, type CreateScopeOptions, type Customer, type DepositCashOptions, DigitalReceiptNotificationPreference, type DigitalReceiptView, type DigitalReceiptViewType, type ErrorMessageMetadataWith, type Fields, type FiscalizationPayload, type HTMLContentData, type HTMLContentType, type HandleRefundRequest, type HandleRefundRequestClear, type HandleSaleRequest, type HandleSaleRequestClear, type ICashRegister, type IDigitalReceipt, type ILogger, type Image, type InitializationOptions, type KazakhstanProductData, KnownCountryCodes, type KyrgyzstanProductData, type Loyalty, type MakeZReportOptions, type MarkingCodes, type Message, type MessageMetadata, type MessageMetadataWith, type MessageWith, type Money, type OperationIdentifiers, type Order, type OrderPaymentResult, type OrderPrice, type OrderRefundResult, OrderSource, OrderType, type Organization, OwnerType, type PaymentInfo, PaymentMode, type PaymentProvider, type PaymentResult, PaymentSource, PaymentStatus, PaymentType, type PreviousReceipt, type PrintParams, type PrintTextOptions, type PrintedFiscalReceipt, type PrintedNonFiscalReceipt, type PrintedReceipt, type PrintedRefundReceipt, type Product, type ProductPrice, type ProductSpecificData, type QRData, type QRIdData, type QRIdType, type QrPaymentResult, type QrRefundResult, type Receipt, type ReceiptPaymentInfo, type ReceiptRefundInfo, type RefundInfo, type RefundResult, RefundSource, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dodobrands/pos-receipts-plugin-contracts",
-	"version": "5.13.2",
+	"version": "5.13.4",
 	"type": "module",
 	"repository": {
 		"type": "git",

package/readme.md

@@ -1,18 +0,0 @@
-# pos-receipts-plugin-contracts
-
-Public contracts for cash register plugins
-
-## Documentation
-
-Please use auto-generated documentation available [here](https://dodopizza.github.io/cashierapp/)
-
-## Creating plugins
-Start from the documentation related to [ICashRegister interface](\src\ICashRegister.ts)
-
-
-## Tech radar
-
-We at Dodo have expertize at the following [Tech Radar](https://radar.thoughtworks.com/?sheetId=https%3A%2F%2Fdocs.google.com%2Fspreadsheets%2Fd%2F15B0mJaxj8gdS4opGCsn42w3PeIAV0YCfVeEFzzcFe5w%2Fpub%2Foutput%3Dcsv%26format%3D%252FDec%2C%202022)
-and try to follow [Dodo NFRs](https://www.notion.so/dodobrands/Frontend-NFR-draft-535df248e84347d1b46147b8026a5250).
-
-We present it here as a recommendation for all new contributors so that we can provide better support in the future.