cadrumo.domain.invoices.normalization module

Invoice payload normalization and validation helpers.

These helpers are the canonical implementation used by models; the public invoice record definitions and derive_invoice_id remain there.

normalise_invoice_dates(payload)

Coerce every present date and datetime field on payload in place, and return it.

Return type:

dict[str, object]

Parameters:

payload (dict[str, object])

normalise_invoice_counterparty(payload)

Validate and normalise the counterparty country, tax id, and identification state in place.

Return type:

dict[str, object]

Parameters:

payload (dict[str, object])

normalise_invoice_currency(payload)

Normalise the ISO 4217 currency field in place, and return the payload.

Return type:

dict[str, object]

Parameters:

payload (dict[str, object])

raise_first_invoice_violation(violations)

Raise on the first (violated, message) pair whose flag is true.

Return type:

None

Parameters:

violations (Iterable[tuple[bool, str]])

require_optional_non_negative(value, message)

Raise message when value is present and negative.

Return type:

None

Parameters:

• value (Decimal | None)

• message (str)

require_equal(actual, expected, message)

Raise message when actual does not equal expected.

Return type:

None

Parameters:

• actual (Decimal)

• expected (Decimal)

• message (str)

normalise_invoice_monetary_fields(payload)

Coerce every present monetary field on payload to Decimal in place, and return it.

Return type:

dict[str, object]

Parameters:

payload (dict[str, object])

derive_invoice_id_when_complete(payload, *, derive_invoice_id)

Derive and set invoice_id once every identity field is present, or refuse a mismatch.

Raises:

InvoiceValidationError – When the payload already carries an invoice_id that disagrees with the derived one.

Return type:

dict[str, object]

Parameters:

• payload (dict[str, object])

• derive_invoice_id (Callable[[...], str])

normalise_invoice_collections(payload, *, normalise_linked_transaction_ids)

Normalise the linked-transaction and line collections in place, and return the payload.

Return type:

dict[str, object]

Parameters:

• payload (dict[str, object])

• normalise_linked_transaction_ids (Callable[[object], tuple[str, ...]])

normalise_invoice_payment_id(payload)

Validate and normalise payment_id to lowercase hex in place, or raise.

Raises:

InvoiceValidationError – When payment_id is a non-empty string that is not a 64-character lowercase hex digest.

Return type:

dict[str, object]

Parameters:

payload (dict[str, object])