Source code for pain001_mcp._replies
# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Bank-reply tools: camt.053 statements and pain.002 status reports.
Both read a file the caller names, through the core parsers and their
path guards, and return the parsed content or an ``{"error": ...}``
payload.
"""
from typing import Annotated, cast
from pain001 import parse_camt053_statement, parse_pain002_report
from pydantic import Field
from pain001_mcp._shapes import Camt053Result, Pain002Result
[docs]
def parse_camt053(
xml_file_path: Annotated[
str,
Field(
description=(
"Local filesystem path to the camt.053 bank-statement XML "
"file to parse."
)
),
],
xsd_file_path: Annotated[
str | None,
Field(
description=(
"Optional local path to a camt.053 XSD; when given, the "
"document is validated against it before parsing. Omit to "
"skip schema validation."
)
),
] = None,
) -> Camt053Result:
"""Parse a camt.053 bank-statement XML file on disk into structured data.
Use this to read a bank's account statement (the reply that confirms
settlement) into a header + entry list. Reads ``xml_file_path`` from the
local filesystem. For the payment-status reply (accepted/rejected per
transaction) use ``parse_pain002`` instead; to validate a camt.053
string you already hold, this is not it — this tool needs a file path.
Wraps :func:`pain001.parse_camt053_statement`. When ``xsd_file_path``
is provided, the document is first validated against that XSD; on a
schema or parse error the tool returns ``{"error": ...}`` rather than
raising.
Args:
xml_file_path: Filesystem path to the camt.053 XML statement.
xsd_file_path: Optional path to a camt.053 XSD for upfront
validation.
Returns:
The first statement's header and entries, every statement under
``statements``, or an ``{"error": ...}`` payload on failure.
"""
try:
return cast(
Camt053Result,
parse_camt053_statement(xml_file_path, xsd_file_path),
)
except Exception as exc: # noqa: BLE001 - pain001 raises several types
return {"error": str(exc)}
[docs]
def parse_pain002(
xml_file_path: Annotated[
str,
Field(
description=(
"Local filesystem path to the pain.002 payment-status report "
"XML file to parse."
)
),
],
xsd_file_path: Annotated[
str | None,
Field(
description=(
"Optional local path to a pain.002 XSD; when given, the "
"document is validated against it before parsing. Omit to "
"skip schema validation."
)
),
] = None,
) -> Pain002Result:
"""Parse a pain.002 payment-status report file on disk into structured data.
Use this to read the bank's acknowledgement of a submitted pain.001 —
the per-transaction accepted/rejected status and reason codes. Reads
``xml_file_path`` from the local filesystem. For the account statement
that later confirms booked entries, use ``parse_camt053`` instead.
Wraps :func:`pain001.parse_pain002_report`. When ``xsd_file_path`` is
provided, the document is first validated against that XSD; on a
schema or parse error the tool returns ``{"error": ...}`` rather than
raising.
Args:
xml_file_path: Filesystem path to the pain.002 XML report.
xsd_file_path: Optional path to a pain.002 XSD for upfront
validation.
Returns:
A dict with the group header and transaction statuses, or an
``{"error": ...}`` payload on failure.
"""
try:
return cast(
Pain002Result, parse_pain002_report(xml_file_path, xsd_file_path)
)
except Exception as exc: # noqa: BLE001 - pain001 raises several types
return {"error": str(exc)}