hdm_am/
lib.rs

1//! Client for the Armenian fiscal cash register (HDM) protocol.
2//!
3//! Specification: State Revenue Committee of Armenia (ՀՀՊԵԿ),
4//! "ՀՍԿԻՉ - ԴՐԱՄԱՐԿՂԱՅԻՆ ՄԵՔԵՆԱՅԻ ԻՆՏԵԳՐՈՒՄԸ ԱՐՏԱՔԻՆ (ԱՌԵՎՏՐԱՅԻՆ) ԾՐԱԳՐԵՐԻ ՀԵՏ",
5//! version 0.7.3 (April 2025). The original Armenian PDF and an English translation are
6//! checked in under `docs/`.
7//!
8//! # Example
9//!
10//! ```no_run
11//! use hdm_am::{Client, Decimal, InMemorySeq, PrintMode, PrintReceiptRequest};
12//! use std::net::TcpStream;
13//! use std::time::Duration;
14//!
15//! let mut tcp = TcpStream::connect("192.168.1.50:9000")?;
16//! tcp.set_read_timeout(Some(Duration::from_secs(50)))?;
17//! tcp.set_write_timeout(Some(Duration::from_secs(50)))?;
18//!
19//! let mut client = Client::new(tcp, "hdm-password", InMemorySeq::default());
20//! client.login(1, "1234")?;
21//!
22//! let receipt = client.print_receipt(PrintReceiptRequest {
23//!     mode: PrintMode::Simple,
24//!     paid_amount: Decimal::from(1000),
25//!     paid_amount_card: Decimal::ZERO,
26//!     partial_amount: Decimal::ZERO,
27//!     pre_payment_amount: Decimal::ZERO,
28//!     dep: Some(1),
29//!     partner_tin: None,
30//!     use_ext_pos: false,
31//!     payment_system: None,
32//!     rrn: None,
33//!     terminal_id: None,
34//!     e_marks: vec![],
35//!     items: vec![],
36//! })?;
37//!
38//! println!("fiscal number: {}", receipt.fiscal);
39//! # Ok::<(), Box<dyn std::error::Error>>(())
40//! ```
41//!
42//! # Versions and forward compatibility
43//!
44//! Three version axes are easy to confuse, so the crate keeps them separate:
45//!
46//! - **Wire framing version** — the byte in the request header ([`PROTOCOL_VERSION`]). Frozen
47//!   at `05` since spec v0.5 (2017); one framing covers the whole live protocol.
48//! - **Spec (document) version** — which manual revision the operation/field set follows
49//!   ([`SPEC_VERSION`], currently `0.7.3`). This is what grows over time.
50//! - **Crate version** — ordinary semver; not coupled to the spec version (the mapping lives in the
51//!   changelog, not the version number).
52//!
53//! The crate targets the current `0.7.x` line and is built to tolerate *newer* devices without code
54//! changes:
55//!
56//! - **Responses are forward-compatible.** They are `#[non_exhaustive]`, never use
57//!   `#[serde(deny_unknown_fields)]`, and put `#[serde(default)]` on later-added fields — so a newer
58//!   firmware that returns extra fields still deserialises cleanly. Preserve this when adding ops.
59//! - **Requests track a spec revision exactly.** They are ordinary (exhaustive) structs, so a new
60//!   *request* field introduced by a future spec is a breaking change shipped in a major release —
61//!   a deliberate signal that the targeted [`SPEC_VERSION`] moved.
62//!
63//! `docs/history/` holds the full version lineage (v0.3–v0.7.3) and a runbook for adopting a new
64//! spec.
65
66#![warn(missing_docs)]
67#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
68
69pub mod client;
70pub mod error;
71pub mod operations;
72pub mod probe;
73pub mod seq;
74
75// Framing and crypto are implementation details: the genuinely-public items (OperationCode,
76// PROTOCOL_VERSION) are re-exported below; everything else stays internal.
77pub(crate) mod crypto;
78pub(crate) mod wire;
79
80pub use client::Client;
81pub use error::{CryptoError, Error, ServerErrorKind, VendorErrorKind};
82pub use operations::{
83    CashInOutRequest, DateTimeRequest, DateTimeResponse, DepartmentInfo, DiscountKind,
84    EmptyResponse, FiscalReportKind, FiscalReportRequest, GetReturnableReceiptRequest,
85    HdmTimeSyncRequest, ListOpsAndDepsRequest, ListOpsAndDepsResponse, Operation, OperatorInfo,
86    OperatorLoginRequest, OperatorLoginResponse, OperatorLogoutRequest, PaymentSystemEntry,
87    PaymentSystemsListRequest, PaymentSystemsListResponse, PrintLastReceiptRequest, PrintMode,
88    PrintReceiptRequest, PrintReturnReceiptRequest, ReceiptItem, ReceiptResponse,
89    ReceiptSampleRequest, ReportFilter, ReturnItem, ReturnReceiptResponse, ReturnableReceiptItem,
90    ReturnableReceiptResponse, SetupHeaderFooterRequest, SetupHeaderLogoRequest,
91    SingleEmarkRequest, TaxationKind, TextAlign, TextLine,
92};
93pub use probe::{HdmIdentity, identify};
94pub use seq::{FileSeq, InMemorySeq, SequenceProvider};
95pub use wire::{OperationCode, PROTOCOL_VERSION};
96
97/// Re-exported so consumers can name monetary/quantity values without depending on `rust_decimal`
98/// directly. All amount and quantity fields use this type.
99///
100/// The wire encoding is a JSON **number** (the HDM format), so values round-trip through `f64` and
101/// are bounded by `f64` precision — about 15–16 significant digits. This is inherent to the protocol,
102/// not the crate; it is far above any realistic AMD receipt magnitude (totals ≪ 10¹³ with 2 decimal
103/// places), but a pathological quantity × price could lose precision.
104pub use rust_decimal::Decimal;
105
106/// HDM specification (document) version this crate targets — the operation and field set follow
107/// this manual revision.
108///
109/// Distinct from the wire framing version [`PROTOCOL_VERSION`] (`05`, frozen since spec v0.5)
110/// and from the crate's own semver. The full version lineage and an upgrade runbook are in
111/// `docs/history/`.
112pub const SPEC_VERSION: &str = "0.7.3";
hdm_am/lib.rs

hdm_am/
lib.rs
