@dodobrands/pos-receipts-plugin-contracts 5.13.3 → 5.14.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.
Files changed (6) hide show
  1. package/README.en.md +36 -0
  2. package/README.md +36 -0
  3. package/dist/index.d.cts +40 -25
  4. package/dist/index.d.ts +40 -25
  5. package/package.json +1 -1
  6. package/readme.md +0 -18
package/README.en.md ADDED
@@ -0,0 +1,36 @@
1
+ # @dodobrands/pos-receipts-plugin-contracts
2
+
3
+ Public contracts for fiscal cash register (Cash Register) plugins. Implemented by fiscal printer plugin authors.
4
+
5
+ Full documentation: [dodopizza.github.io/cashierapp](https://dodopizza.github.io/cashierapp/)
6
+
7
+ ---
8
+
9
+ ## Main Interface: `ICashRegister`
10
+
11
+ ```ts
12
+ export interface ICashRegister {
13
+ initialize?: (options: InitializationOptions) => Promise<void>;
14
+ getSettings: () => Promise<CashRegisterSettings>;
15
+ handleSale: (request: HandleSaleRequest) => Promise<PrintedReceipt>;
16
+
17
+ // Optional
18
+ handleRefund?: (request: HandleRefundRequest) => Promise<PrintedRefundReceipt>;
19
+ makeXReport?: () => Promise<void>;
20
+ makeZReport?: (options: MakeZReportOptions) => Promise<void>;
21
+ withdrawCash?: (options: WithdrawCashOptions) => Promise<void>;
22
+ depositCash?: (options: DepositCashOptions) => Promise<void>;
23
+ printText?: (options: PrintTextOptions) => Promise<void>;
24
+ }
25
+ ```
26
+
27
+ Start by exploring [`src/ICashRegister.ts`](./src/ICashRegister.ts).
28
+
29
+ The `Receipt` type contains complete information about the order, customer, taxes, organization, and country-specific marking data (Russia, Belarus, Uzbekistan, Kazakhstan).
30
+
31
+ ---
32
+
33
+ ## Related Packages
34
+
35
+ - [`@dodopizza/pos-receipts-ipc-client`](../../private/pos-receipts-ipc-client/README.en.md) — ready-made IPC client for Electron using these contracts
36
+ - [`@dodobrands/pos-plugins-shared-models`](../../shared/pos-plugins-shared-models/README.en.md) — shared models (`Business`, `Country`, `ILogger`)
package/README.md ADDED
@@ -0,0 +1,36 @@
1
+ # @dodobrands/pos-receipts-plugin-contracts
2
+
3
+ Публичные контракты для плагинов фискальных касс (Cash Register). Реализуется авторами плагинов фискальных принтеров.
4
+
5
+ Полная документация: [dodopizza.github.io/cashierapp](https://dodopizza.github.io/cashierapp/)
6
+
7
+ ---
8
+
9
+ ## Основной интерфейс: `ICashRegister`
10
+
11
+ ```ts
12
+ export interface ICashRegister {
13
+ initialize?: (options: InitializationOptions) => Promise<void>;
14
+ getSettings: () => Promise<CashRegisterSettings>;
15
+ handleSale: (request: HandleSaleRequest) => Promise<PrintedReceipt>;
16
+
17
+ // Опциональные
18
+ handleRefund?: (request: HandleRefundRequest) => Promise<PrintedRefundReceipt>;
19
+ makeXReport?: () => Promise<void>;
20
+ makeZReport?: (options: MakeZReportOptions) => Promise<void>;
21
+ withdrawCash?: (options: WithdrawCashOptions) => Promise<void>;
22
+ depositCash?: (options: DepositCashOptions) => Promise<void>;
23
+ printText?: (options: PrintTextOptions) => Promise<void>;
24
+ }
25
+ ```
26
+
27
+ Начните с изучения [`src/ICashRegister.ts`](./src/ICashRegister.ts).
28
+
29
+ Тип `Receipt` содержит полную информацию о заказе, покупателе, налогах, организации и страно-специфичных данных маркировки (Россия, Беларусь, Узбекистан, Казахстан).
30
+
31
+ ---
32
+
33
+ ## Смежные пакеты
34
+
35
+ - [`@dodopizza/pos-receipts-ipc-client`](../../private/pos-receipts-ipc-client/README.md) — готовый IPC-клиент для Electron, использующий эти контракты
36
+ - [`@dodobrands/pos-plugins-shared-models`](../../shared/pos-plugins-shared-models/README.md) — общие модели (`Business`, `Country`, `ILogger`)
package/dist/index.d.cts CHANGED
@@ -48,7 +48,7 @@ declare enum KnownCountryCodes {
48
48
  Kyrgyzstan = 417
49
49
  }
50
50
 
51
- type ProductSpecificData = UzbekistanProductData | KazakhstanProductData | KyrgyzstanProductData | null;
51
+ type ProductSpecificData = UzbekistanProductData | KazakhstanProductData | KyrgyzstanProductData | RussiaProductData | null;
52
52
  interface UzbekistanProductData {
53
53
  /** Identification code of products and services for Uzbekistan */
54
54
  ikpu: string;
@@ -73,6 +73,12 @@ interface KyrgyzstanProductData {
73
73
  /** `product` — if entry is resold, `service` — if entry is prepared in-house. */
74
74
  entryType?: 'product' | 'service';
75
75
  }
76
+ interface RussiaProductData {
77
+ /** if `true` - product should not be printed on the receipt if it has a zero price
78
+ * if `false` or `undefined` - product should be printed on the receipt regardless of its price
79
+ */
80
+ excludeFromReceiptWithZeroPrice?: boolean;
81
+ }
76
82
 
77
83
  type Message = {
78
84
  content: string;
@@ -106,6 +112,29 @@ interface ILogger<TScope extends Record<string, unknown> = never> {
106
112
  fatal<T>(message: string, error?: unknown, metadata?: ErrorMessageMetadataWith<T>): void;
107
113
  }
108
114
 
115
+ interface IDigitalReceipt {
116
+ views: DigitalReceiptView[];
117
+ fields?: Fields;
118
+ version: 'v1';
119
+ }
120
+ type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
121
+ type DigitalReceiptView = {
122
+ type: DigitalReceiptViewType;
123
+ data: string;
124
+ };
125
+ type Fields = {
126
+ type: 'FPtr10';
127
+ fnNumber: string;
128
+ fiscalDocumentSign: string;
129
+ fiscalDocumentNumber: string;
130
+ };
131
+
132
+ type FiscalizationPayload = {
133
+ ReceiptId: string;
134
+ Payload: string;
135
+ DigitalReceipt: IDigitalReceipt;
136
+ };
137
+
109
138
  /**
110
139
  * Unique identifier of the transaction
111
140
  */
@@ -189,11 +218,17 @@ type TextSlipData = {
189
218
  */
190
219
  type SlipData = TextSlipData;
191
220
 
192
- type QrPaymentResult = {
221
+ type BasePaymentResult = {
193
222
  /**
194
223
  * Information about the payment.
195
224
  */
196
225
  paymentInfo: PaymentInfo;
226
+ /**
227
+ * Fiscalization payload returned by 2-in-1 devices.
228
+ */
229
+ fiscalizationPayload?: FiscalizationPayload;
230
+ };
231
+ type QrPaymentResult = BasePaymentResult & {
197
232
  /**
198
233
  * QR code data
199
234
  */
@@ -202,11 +237,7 @@ type QrPaymentResult = {
202
237
  /**
203
238
  * Represents the payment result for CARD payment request
204
239
  */
205
- type CardPaymentResult = {
206
- /**
207
- * Information about the payment.
208
- */
209
- paymentInfo: PaymentInfo;
240
+ type CardPaymentResult = BasePaymentResult & {
210
241
  /**
211
242
  * Data for slip
212
243
  */
@@ -401,6 +432,7 @@ interface Product {
401
432
  Uzbekistan?: UzbekistanProductData;
402
433
  Kazakhstan?: KazakhstanProductData;
403
434
  Kyrgyzstan?: KyrgyzstanProductData;
435
+ Russia?: RussiaProductData;
404
436
  };
405
437
  }
406
438
  interface ProductPrice {
@@ -609,23 +641,6 @@ interface MakeZReportOptions {
609
641
  withoutPaper?: boolean;
610
642
  }
611
643
 
612
- interface IDigitalReceipt {
613
- views: DigitalReceiptView[];
614
- fields?: Fields;
615
- version: 'v1';
616
- }
617
- type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
618
- type DigitalReceiptView = {
619
- type: DigitalReceiptViewType;
620
- data: string;
621
- };
622
- type Fields = {
623
- type: 'FPtr10';
624
- fnNumber: string;
625
- fiscalDocumentSign: string;
626
- fiscalDocumentNumber: string;
627
- };
628
-
629
644
  /** Other types of receipts may appear here */
630
645
  type PrintedReceipt = PrintedFiscalReceipt | PrintedNonFiscalReceipt;
631
646
  interface PrintedFiscalReceipt {
@@ -725,4 +740,4 @@ declare enum DigitalReceiptNotificationPreference {
725
740
  PhoneSms = "PhoneSms"
726
741
  }
727
742
 
728
- 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 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 };
743
+ 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 RussiaProductData, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };
package/dist/index.d.ts CHANGED
@@ -48,7 +48,7 @@ declare enum KnownCountryCodes {
48
48
  Kyrgyzstan = 417
49
49
  }
50
50
 
51
- type ProductSpecificData = UzbekistanProductData | KazakhstanProductData | KyrgyzstanProductData | null;
51
+ type ProductSpecificData = UzbekistanProductData | KazakhstanProductData | KyrgyzstanProductData | RussiaProductData | null;
52
52
  interface UzbekistanProductData {
53
53
  /** Identification code of products and services for Uzbekistan */
54
54
  ikpu: string;
@@ -73,6 +73,12 @@ interface KyrgyzstanProductData {
73
73
  /** `product` — if entry is resold, `service` — if entry is prepared in-house. */
74
74
  entryType?: 'product' | 'service';
75
75
  }
76
+ interface RussiaProductData {
77
+ /** if `true` - product should not be printed on the receipt if it has a zero price
78
+ * if `false` or `undefined` - product should be printed on the receipt regardless of its price
79
+ */
80
+ excludeFromReceiptWithZeroPrice?: boolean;
81
+ }
76
82
 
77
83
  type Message = {
78
84
  content: string;
@@ -106,6 +112,29 @@ interface ILogger<TScope extends Record<string, unknown> = never> {
106
112
  fatal<T>(message: string, error?: unknown, metadata?: ErrorMessageMetadataWith<T>): void;
107
113
  }
108
114
 
115
+ interface IDigitalReceipt {
116
+ views: DigitalReceiptView[];
117
+ fields?: Fields;
118
+ version: 'v1';
119
+ }
120
+ type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
121
+ type DigitalReceiptView = {
122
+ type: DigitalReceiptViewType;
123
+ data: string;
124
+ };
125
+ type Fields = {
126
+ type: 'FPtr10';
127
+ fnNumber: string;
128
+ fiscalDocumentSign: string;
129
+ fiscalDocumentNumber: string;
130
+ };
131
+
132
+ type FiscalizationPayload = {
133
+ ReceiptId: string;
134
+ Payload: string;
135
+ DigitalReceipt: IDigitalReceipt;
136
+ };
137
+
109
138
  /**
110
139
  * Unique identifier of the transaction
111
140
  */
@@ -189,11 +218,17 @@ type TextSlipData = {
189
218
  */
190
219
  type SlipData = TextSlipData;
191
220
 
192
- type QrPaymentResult = {
221
+ type BasePaymentResult = {
193
222
  /**
194
223
  * Information about the payment.
195
224
  */
196
225
  paymentInfo: PaymentInfo;
226
+ /**
227
+ * Fiscalization payload returned by 2-in-1 devices.
228
+ */
229
+ fiscalizationPayload?: FiscalizationPayload;
230
+ };
231
+ type QrPaymentResult = BasePaymentResult & {
197
232
  /**
198
233
  * QR code data
199
234
  */
@@ -202,11 +237,7 @@ type QrPaymentResult = {
202
237
  /**
203
238
  * Represents the payment result for CARD payment request
204
239
  */
205
- type CardPaymentResult = {
206
- /**
207
- * Information about the payment.
208
- */
209
- paymentInfo: PaymentInfo;
240
+ type CardPaymentResult = BasePaymentResult & {
210
241
  /**
211
242
  * Data for slip
212
243
  */
@@ -401,6 +432,7 @@ interface Product {
401
432
  Uzbekistan?: UzbekistanProductData;
402
433
  Kazakhstan?: KazakhstanProductData;
403
434
  Kyrgyzstan?: KyrgyzstanProductData;
435
+ Russia?: RussiaProductData;
404
436
  };
405
437
  }
406
438
  interface ProductPrice {
@@ -609,23 +641,6 @@ interface MakeZReportOptions {
609
641
  withoutPaper?: boolean;
610
642
  }
611
643
 
612
- interface IDigitalReceipt {
613
- views: DigitalReceiptView[];
614
- fields?: Fields;
615
- version: 'v1';
616
- }
617
- type DigitalReceiptViewType = 'mobile' | 'email' | 'link' | 'pos';
618
- type DigitalReceiptView = {
619
- type: DigitalReceiptViewType;
620
- data: string;
621
- };
622
- type Fields = {
623
- type: 'FPtr10';
624
- fnNumber: string;
625
- fiscalDocumentSign: string;
626
- fiscalDocumentNumber: string;
627
- };
628
-
629
644
  /** Other types of receipts may appear here */
630
645
  type PrintedReceipt = PrintedFiscalReceipt | PrintedNonFiscalReceipt;
631
646
  interface PrintedFiscalReceipt {
@@ -725,4 +740,4 @@ declare enum DigitalReceiptNotificationPreference {
725
740
  PhoneSms = "PhoneSms"
726
741
  }
727
742
 
728
- 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 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 };
743
+ 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 RussiaProductData, type SlipData, type SlipType, type Store, type Tax, type Taxpayer, type TextSlipData, type TextSlipType, type UzbekistanProductData, type WithdrawCashOptions };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dodobrands/pos-receipts-plugin-contracts",
3
- "version": "5.13.3",
3
+ "version": "5.14.0",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/readme.md DELETED
@@ -1,18 +0,0 @@
1
- # pos-receipts-plugin-contracts
2
-
3
- Public contracts for cash register plugins
4
-
5
- ## Documentation
6
-
7
- Please use auto-generated documentation available [here](https://dodopizza.github.io/cashierapp/)
8
-
9
- ## Creating plugins
10
- Start from the documentation related to [ICashRegister interface](\src\ICashRegister.ts)
11
-
12
-
13
- ## Tech radar
14
-
15
- 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)
16
- and try to follow [Dodo NFRs](https://www.notion.so/dodobrands/Frontend-NFR-draft-535df248e84347d1b46147b8026a5250).
17
-
18
- We present it here as a recommendation for all new contributors so that we can provide better support in the future.