bankstatementparser-loader-bai2 0.0.10__py3-none-any.whl

bankstatementparser_loader_bai2/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2023-2026 Sebastien Rousseau. All rights reserved.
+
+"""BAI2 -> bankstatementparser ``Transaction`` loader.
+
+BAI2 (Bank Administration Institute, version 2) is the US cash-management
+file format banks ship for balance and transaction reporting. The
+`bankstatementparser <https://pypi.org/project/bankstatementparser/>`_
+library does not parse BAI2; this companion loader turns a BAI2 payload
+into a flat list of
+:class:`bankstatementparser.transaction_models.Transaction` objects.
+
+See :mod:`bankstatementparser_loader_bai2.loader` for the documented
+record subset, amount handling, and debit / credit sign convention.
+"""
+
+from bankstatementparser_loader_bai2.loader import (
+    Bai2Summary,
+    load_bai2,
+    load_bai2_file,
+    summarize_bai2,
+)
+
+__version__ = "0.0.10"
+
+__all__ = [
+    "load_bai2",
+    "load_bai2_file",
+    "summarize_bai2",
+    "Bai2Summary",
+    "__version__",
+]

bankstatementparser_loader_bai2/loader.py

@@ -0,0 +1,440 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2023-2026 Sebastien Rousseau. All rights reserved.
+
+"""BAI2 -> bankstatementparser ``Transaction`` loader.
+
+`BAI2 <https://www.bai.org/>`_ (Bank Administration Institute, version 2)
+is the de-facto US cash-management file format that banks ship for
+intraday and prior-day balance reporting. The published
+`bankstatementparser <https://pypi.org/project/bankstatementparser/>`_
+library does **not** parse BAI2; this companion loader fills that gap by
+turning a BAI2 payload into a flat list of
+:class:`bankstatementparser.transaction_models.Transaction` objects that
+downstream deterministic logic can consume.
+
+Supported (pragmatic) subset
+----------------------------
+
+BAI2 files are line-oriented. Each physical record is a sequence of
+comma-delimited fields and ends with a ``/`` record delimiter. Every
+record begins with a numeric *type code* identifying the record kind.
+This loader implements the following records:
+
+``01`` File Header
+    ``01,senderId,receiverId,fileDate,fileTime,fileId,...`` -- the file
+    must start with this record. ``fileId`` is captured for the summary.
+
+``02`` Group Header
+    ``02,ultimateReceiver,originator,groupStatus,asOfDate,asOfTime,currency,...``
+    -- the group ``currency`` and ``asOfDate`` are captured. The as-of
+    date becomes each transaction's ``booking_date``; the group
+    currency is the fallback currency for accounts that omit one.
+
+``03`` Account Identifier
+    ``03,accountNumber,currencyCode,typeCode,amount,itemCount,fundsType,...``
+    -- ``accountNumber`` and the optional account ``currencyCode`` are
+    captured. The account currency, when present, overrides the group
+    currency for every transaction under this account.
+
+``16`` Transaction Detail
+    ``16,typeCode,amount,fundsType,bankRefNum,customerRefNum,text`` --
+    one transaction. ``amount`` is an integer in the account currency's
+    minor units (see "Amounts" below). ``text`` becomes the
+    description.
+
+``88`` Continuation
+    Continues the text of the immediately preceding ``03`` or ``16``
+    record; its content is appended to that record's description.
+
+``49`` Account Trailer, ``98`` Group Trailer, ``99`` File Trailer
+    Control-total records. This loader **ignores** them -- it does not
+    validate the control sums. Ignoring is a deliberate, documented
+    choice: the goal is faithful transaction extraction, not file-level
+    reconciliation.
+
+Any other (or unknown) leading type code is ignored so that vendor
+extensions do not abort the parse.
+
+Amounts
+-------
+
+BAI2 amounts are unsigned integers expressed in the account currency's
+**minor units** (e.g. cents), with no decimal point. They are converted
+to :class:`decimal.Decimal` by dividing by 100 -- ``Decimal`` is used
+throughout (never ``float``) to avoid binary rounding error. An empty
+amount field is treated as ``0``.
+
+Sign convention (debit / credit)
+---------------------------------
+
+BAI2 transaction *type codes* encode the direction of funds. This loader
+applies the following documented convention based on the numeric range
+of the ``16`` record's type code:
+
+* ``100``-``399`` -> **credit** (amount kept **positive**)
+* ``400``-``699`` -> **debit** (amount made **negative**)
+* anything else -> kept **positive**; the raw type code is preserved.
+
+The raw BAI2 type code is always preserved on the resulting
+``Transaction`` in both the ``category`` field (as ``bai2:<code>``) and
+the ``reference`` field, so no information is lost even for codes outside
+the two ranges above.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+
+from bankstatementparser.transaction_models import Transaction
+
+__all__ = [
+    "load_bai2",
+    "load_bai2_file",
+    "summarize_bai2",
+    "Bai2Summary",
+]
+
+# ─── Sign-convention boundaries ──────────────────────────────────────────────
+
+# Inclusive lower/upper bounds for the credit and debit type-code ranges.
+# Documented in the module docstring; kept here as the single source of
+# truth so the loader and the tests agree.
+_CREDIT_RANGE = range(100, 400)  # 100-399 -> credit (positive)
+_DEBIT_RANGE = range(400, 700)  # 400-699 -> debit (negative)
+
+
+# ─── Record tokeniser ────────────────────────────────────────────────────────
+
+
+def _iter_records(text: str) -> Iterator[list[str]]:
+    """Yield each BAI2 record as a list of its comma-delimited fields.
+
+    Tolerates CRLF / LF line endings, blank lines, and an optional
+    trailing ``/`` record delimiter. The trailing ``/`` (and anything a
+    bank may append after it) is stripped before the fields are split.
+
+    Args:
+        text: The raw BAI2 payload.
+
+    Yields:
+        One ``list[str]`` of fields per non-empty record, in file order.
+    """
+    for raw_line in text.replace("\r\n", "\n").replace("\r", "\n").split("\n"):
+        line = raw_line.strip()
+        if not line:
+            continue
+        # A record ends with the '/' delimiter; drop it (and any
+        # trailing remainder) so the final field is clean.
+        if "/" in line:
+            line = line[: line.index("/")]
+        line = line.rstrip()
+        if not line:
+            continue
+        yield [field.strip() for field in line.split(",")]
+
+
+# ─── Field helpers ───────────────────────────────────────────────────────────
+
+
+def _field(fields: list[str], index: int) -> str:
+    """Return the field at ``index`` or an empty string if absent.
+
+    Args:
+        fields: The split fields of one record.
+        index: Zero-based field position.
+
+    Returns:
+        The trimmed field value, or ``""`` when the position is missing.
+    """
+    if 0 <= index < len(fields):
+        return fields[index]
+    return ""
+
+
+def _amount_to_decimal(raw: str) -> Decimal:
+    """Convert a BAI2 minor-unit integer amount to a major-unit Decimal.
+
+    BAI2 amounts are unsigned integers in the currency's minor units
+    (cents) with no decimal point. An empty field is treated as ``0``.
+
+    Args:
+        raw: The raw amount field (e.g. ``"150000"`` for 1500.00).
+
+    Returns:
+        The amount as a :class:`decimal.Decimal` in major units.
+    """
+    text = raw.strip()
+    if not text:
+        return Decimal("0")
+    return Decimal(text) / Decimal(100)
+
+
+def _signed_amount(type_code: str, magnitude: Decimal) -> Decimal:
+    """Apply the documented sign convention to a transaction magnitude.
+
+    Args:
+        type_code: The raw BAI2 ``16`` record type code.
+        magnitude: The non-negative amount in major units.
+
+    Returns:
+        The magnitude negated for debit type codes (``400``-``699``),
+        otherwise returned unchanged (credits and unknown codes stay
+        positive).
+    """
+    try:
+        code = int(type_code)
+    except ValueError:
+        return magnitude
+    if code in _DEBIT_RANGE:
+        return -magnitude
+    return magnitude
+
+
+def _parse_bai2_date(raw: str) -> date | None:
+    """Parse a BAI2 ``YYMMDD`` date into a :class:`datetime.date`.
+
+    Years are interpreted with a sliding window matching industry
+    practice: ``00``-``79`` -> ``20YY``, ``80``-``99`` -> ``19YY``. An
+    empty or malformed value yields ``None`` rather than raising, so a
+    missing as-of date never aborts a parse.
+
+    Args:
+        raw: The raw 6-digit date field.
+
+    Returns:
+        The parsed date, or ``None`` when absent or unparseable.
+    """
+    text = raw.strip()
+    if len(text) != 6 or not text.isdigit():
+        return None
+    year = int(text[0:2])
+    century = 2000 if year < 80 else 1900
+    try:
+        return datetime.strptime(
+            f"{century + year:04d}{text[2:4]}{text[4:6]}", "%Y%m%d"
+        ).date()
+    except ValueError:  # pragma: no cover - guarded by the isdigit check
+        return None
+
+
+# ─── Working state ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class _PendingTransaction:
+    """Mutable accumulator for one ``16`` record and its continuations."""
+
+    type_code: str
+    amount: Decimal
+    bank_ref: str
+    customer_ref: str
+    text_parts: list[str]
+    account_number: str | None
+    currency: str | None
+    booking_date: date | None
+    index: int
+
+    def to_transaction(self) -> Transaction:
+        """Materialise the accumulated state into a ``Transaction``.
+
+        Returns:
+            A frozen :class:`~bankstatementparser.transaction_models.Transaction`
+            with the BAI2 sign convention applied and the raw type code
+            preserved in both ``category`` and ``reference``.
+        """
+        description = " ".join(
+            part for part in self.text_parts if part
+        ).strip()
+        transaction_id = self.bank_ref or self.customer_ref or None
+        return Transaction(
+            account_id=self.account_number,
+            currency=self.currency,
+            amount=_signed_amount(self.type_code, self.amount),
+            booking_date=self.booking_date,
+            description=description or None,
+            reference=self.type_code or None,
+            transaction_id=transaction_id,
+            category=f"bai2:{self.type_code}" if self.type_code else None,
+            source="bai2",
+            source_index=self.index,
+        )
+
+
+# ─── Summary model ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class Bai2Summary:
+    """High-level counts and identifiers for a parsed BAI2 file.
+
+    Attributes:
+        file_id: The ``fileId`` field from the ``01`` File Header.
+        group_count: Number of ``02`` Group Header records.
+        account_count: Number of ``03`` Account Identifier records.
+        transaction_count: Number of ``16`` Transaction Detail records.
+        currency: The first currency seen (account currency preferred,
+            otherwise the group currency), or ``None`` if none was given.
+    """
+
+    file_id: str | None
+    group_count: int
+    account_count: int
+    transaction_count: int
+    currency: str | None
+
+
+# ─── Public API ──────────────────────────────────────────────────────────────
+
+
+def load_bai2(text: str) -> list[Transaction]:
+    """Parse a BAI2 payload into a flat list of ``Transaction`` objects.
+
+    Every ``16`` Transaction Detail record across all groups and
+    accounts becomes one transaction, carrying its account number and
+    currency. ``88`` continuation records extend the description of the
+    preceding ``03`` or ``16`` record.
+
+    Args:
+        text: The raw BAI2 payload. CRLF / LF endings, blank lines, and
+            an optional trailing ``/`` per record are all tolerated.
+
+    Returns:
+        The parsed transactions in file order. May be empty if the file
+        contains headers but no ``16`` records.
+
+    Raises:
+        ValueError: If the file does not start with an ``01`` File
+            Header record.
+    """
+    records = list(_iter_records(text))
+    if not records or _field(records[0], 0) != "01":
+        raise ValueError("BAI2 payload must start with an '01' File Header")
+
+    transactions: list[Transaction] = []
+    pending: _PendingTransaction | None = None
+    # Continuation target: 0 = none, 3 = last account note, 16 = pending tx.
+    continuation_target = 0
+    group_currency: str | None = None
+    group_as_of: date | None = None
+    account_number: str | None = None
+    account_currency: str | None = None
+
+    def _flush() -> None:
+        """Append any in-progress transaction to the output list."""
+        nonlocal pending
+        if pending is not None:
+            transactions.append(pending.to_transaction())
+            pending = None
+
+    for fields in records:
+        code = _field(fields, 0)
+        if code == "02":
+            _flush()
+            continuation_target = 0
+            group_as_of = _parse_bai2_date(_field(fields, 4))
+            group_currency = _field(fields, 6) or None
+            account_number = None
+            account_currency = None
+        elif code == "03":
+            _flush()
+            continuation_target = 3
+            account_number = _field(fields, 1) or None
+            account_currency = _field(fields, 2) or None
+        elif code == "16":
+            _flush()
+            continuation_target = 16
+            pending = _PendingTransaction(
+                type_code=_field(fields, 1),
+                amount=_amount_to_decimal(_field(fields, 2)),
+                bank_ref=_field(fields, 4),
+                customer_ref=_field(fields, 5),
+                text_parts=[_field(fields, 6)],
+                account_number=account_number,
+                currency=account_currency or group_currency,
+                booking_date=group_as_of,
+                index=len(transactions),
+            )
+        elif code == "88":
+            # Continuation text is every field after the leading '88'.
+            note = ",".join(fields[1:]).strip()
+            if continuation_target == 16 and pending is not None:
+                pending.text_parts.append(note)
+            # A continuation of an '03' account note has no transaction
+            # to attach to yet; it is informational and dropped here.
+        elif code in {"49", "98", "99"}:
+            # Trailer / control-total records are intentionally ignored.
+            _flush()
+            continuation_target = 0
+        # 01 and any unknown code: nothing to accumulate.
+
+    _flush()
+    return transactions
+
+
+def load_bai2_file(path: str | Path) -> list[Transaction]:
+    """Parse a BAI2 file from disk into ``Transaction`` objects.
+
+    Args:
+        path: Filesystem path to the BAI2 file. UTF-8 is assumed.
+
+    Returns:
+        The parsed transactions, identical to calling :func:`load_bai2`
+        on the file's text content.
+
+    Raises:
+        ValueError: If the file does not start with an ``01`` record.
+        OSError: If the file cannot be read.
+    """
+    return load_bai2(Path(path).read_text(encoding="utf-8"))
+
+
+def summarize_bai2(text: str) -> Bai2Summary:
+    """Summarise a BAI2 payload without materialising every transaction.
+
+    Args:
+        text: The raw BAI2 payload.
+
+    Returns:
+        A :class:`Bai2Summary` with the file id, group / account /
+        transaction counts, and the first currency observed.
+
+    Raises:
+        ValueError: If the file does not start with an ``01`` record.
+    """
+    records = list(_iter_records(text))
+    if not records or _field(records[0], 0) != "01":
+        raise ValueError("BAI2 payload must start with an '01' File Header")
+
+    file_id = _field(records[0], 5) or None
+    group_count = 0
+    account_count = 0
+    transaction_count = 0
+    currency: str | None = None
+    group_currency: str | None = None
+
+    for fields in records:
+        code = _field(fields, 0)
+        if code == "02":
+            group_count += 1
+            group_currency = _field(fields, 6) or None
+            if currency is None and group_currency is not None:
+                currency = group_currency
+        elif code == "03":
+            account_count += 1
+            account_currency = _field(fields, 2) or None
+            if account_currency is not None:
+                currency = account_currency
+        elif code == "16":
+            transaction_count += 1
+
+    return Bai2Summary(
+        file_id=file_id,
+        group_count=group_count,
+        account_count=account_count,
+        transaction_count=transaction_count,
+        currency=currency,
+    )

bankstatementparser_loader_bai2-0.0.10.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: bankstatementparser-loader-bai2
+Version: 0.0.10
+Summary: BAI2 (Bank Administration Institute v2) cash-management loader that parses BAI2 files into bankstatementparser Transaction objects.
+License: Apache-2.0
+License-File: LICENSE
+Keywords: bai2,bank,statement,cash-management,transactions
+Author: Sebastien Rousseau
+Author-email: sebastian.rousseau@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: bankstatementparser (>=0.0.9)
+Project-URL: Homepage, https://bankstatementparser.com
+Project-URL: Repository, https://github.com/sebastienrousseau/bankstatementparser-loader-bai2
+Description-Content-Type: text/markdown
+
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+<p align="center">
+  <img
+    src="https://cloudcdn.pro/bankstatementparser/v1/logos/bankstatementparser.svg"
+    alt="bankstatementparser-loader-bai2 logo"
+    width="120"
+    height="120"
+  />
+</p>
+
+<h1 align="center">bankstatementparser-loader-bai2</h1>
+
+<p align="center">
+  <b>A BAI2 (Bank Administration Institute, version 2) cash-management loader that parses BAI2 files into <code>bankstatementparser</code> <code>Transaction</code> objects.</b>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bankstatementparser-loader-bai2/"><img src="https://img.shields.io/pypi/v/bankstatementparser-loader-bai2?style=for-the-badge" alt="PyPI version" /></a>
+  <a href="https://pypi.org/project/bankstatementparser-loader-bai2/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser-loader-bai2.svg?style=for-the-badge" alt="Python versions" /></a>
+  <a href="https://pypi.org/project/bankstatementparser-loader-bai2/"><img src="https://img.shields.io/pypi/dm/bankstatementparser-loader-bai2.svg?style=for-the-badge" alt="PyPI downloads" /></a>
+  <a href="https://github.com/sebastienrousseau/bankstatementparser-loader-bai2/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser-loader-bai2/ci.yml?branch=main&label=Tests&style=for-the-badge" alt="Tests" /></a>
+  <a href="#license"><img src="https://img.shields.io/pypi/l/bankstatementparser-loader-bai2?style=for-the-badge" alt="License" /></a>
+</p>
+
+---
+
+## Contents
+
+- [What is bankstatementparser-loader-bai2?](#what-is-bankstatementparser-loader-bai2) — the problem it solves
+- [Install](#install) — PyPI, virtualenv
+- [Quick start](#quick-start) — parse a file in three lines
+- [Public API](#public-api) — `load_bai2`, `load_bai2_file`, `summarize_bai2`
+- [Supported BAI2 subset](#supported-bai2-subset) — exactly which records are handled
+- [Amount and sign convention](#amount-and-sign-convention) — how cents and debit/credit map
+- [When not to use this loader](#when-not-to-use-this-loader) — honest boundaries
+- [Development](#development) — gates, make targets
+- [Security](#security) — input-handling posture
+- [Contributing](#contributing) — how to get changes in
+- [License](#license) — Apache-2.0
+
+---
+
+## What is bankstatementparser-loader-bai2?
+
+**BAI2** (Bank Administration Institute, version 2) is the de-facto US
+cash-management file format that banks ship for intraday and prior-day
+balance and transaction reporting. The published
+[`bankstatementparser`](https://pypi.org/project/bankstatementparser/)
+library parses PDF and other statement formats but **does not support
+BAI2**.
+
+**bankstatementparser-loader-bai2** is a small, dependency-light companion
+that fills that gap: give it a BAI2 payload and it returns a flat list of
+[`bankstatementparser.transaction_models.Transaction`](https://pypi.org/project/bankstatementparser/)
+objects (`source="bai2"`) that the rest of your deterministic pipeline
+can consume unchanged.
+
+| Concern | How this loader handles it |
+| :--- | :--- |
+| Record model | A documented, pragmatic subset of BAI2 (`01`/`02`/`03`/`16`/`88` plus ignored trailers) |
+| Amounts | BAI2 minor-unit integers (cents) converted to `Decimal` (never `float`) |
+| Debit / credit | Derived from the `16` type-code range, with the raw code preserved |
+| Multiple accounts | All `16` records across every group / account are flattened into one list |
+| Robustness | Tolerates CRLF, blank lines, and an optional trailing `/` per record |
+| Errors | A clear `ValueError` if the file does not start with an `01` File Header |
+
+---
+
+## Install
+
+| Channel | Command | Notes |
+| :--- | :--- | :--- |
+| PyPI | `pip install bankstatementparser-loader-bai2` | Pulls in `bankstatementparser >= 0.0.9` |
+| Source | `git clone https://github.com/sebastienrousseau/bankstatementparser-loader-bai2 && cd bankstatementparser-loader-bai2 && poetry install` | For development |
+
+Requires Python 3.10 or later. Works on macOS, Linux, and Windows.
+
+<details>
+<summary>Using an isolated virtual environment (recommended)</summary>
+
+```sh
+python -m venv venv
+source venv/bin/activate        # macOS/Linux
+venv\Scripts\activate           # Windows
+python -m pip install -U bankstatementparser-loader-bai2
+```
+
+</details>
+
+---
+
+## Quick start
+
+```python
+from bankstatementparser_loader_bai2 import load_bai2_file
+
+transactions = load_bai2_file("statement.bai")
+for txn in transactions:
+    print(txn.account_id, txn.currency, txn.amount, txn.description)
+```
+
+Or parse an in-memory payload:
+
+```python
+from bankstatementparser_loader_bai2 import load_bai2
+
+payload = (
+    "01,SENDER,RECEIVER,260601,1200,FILE001,,,/\n"
+    "02,RCVR,ORIG,1,260601,1200,USD,/\n"
+    "03,0123456789,USD,010,150000,1,,/\n"
+    "16,165,150000,Z,BANKREF1,CUSTREF1,Incoming wire payment/\n"
+    "88,from ACME Corp invoice 42/\n"
+    "16,475,2500,Z,BANKREF2,,ATM withdrawal/\n"
+    "49,152500,2/\n"
+    "98,152500,1,4/\n"
+    "99,152500,1,6/\n"
+)
+
+for txn in load_bai2(payload):
+    print(txn.amount, txn.category, txn.description)
+# 1500 bai2:165 Incoming wire payment from ACME Corp invoice 42
+# -25 bai2:475 ATM withdrawal
+```
+
+Runnable versions live in [`examples/`](examples/).
+
+---
+
+## Public API
+
+```python
+from bankstatementparser_loader_bai2 import (
+    load_bai2,
+    load_bai2_file,
+    summarize_bai2,
+    Bai2Summary,
+)
+```
+
+| Function | Signature | Returns |
+| :--- | :--- | :--- |
+| `load_bai2` | `load_bai2(text: str)` | `list[Transaction]` |
+| `load_bai2_file` | `load_bai2_file(path)` | `list[Transaction]` |
+| `summarize_bai2` | `summarize_bai2(text: str)` | `Bai2Summary` |
+
+`Bai2Summary` is a dataclass with the fields `file_id`, `group_count`,
+`account_count`, `transaction_count`, and `currency`.
+
+Each produced `Transaction` is populated as follows:
+
+| `Transaction` field | Source |
+| :--- | :--- |
+| `account_id` | `03` Account Identifier — `accountNumber` |
+| `currency` | `03` `currencyCode`, falling back to the `02` group currency |
+| `amount` | `16` `amount` (cents / 100), signed per the convention below |
+| `booking_date` | `02` Group Header as-of date, when present |
+| `description` | `16` text plus any `88` continuations |
+| `transaction_id` | `16` `bankRefNum`, falling back to `customerRefNum` |
+| `reference` / `category` | The raw `16` type code (`category` as `bai2:<code>`) |
+| `source` | Always `"bai2"` |
+
+---
+
+## Supported BAI2 subset
+
+BAI2 records are comma-delimited fields ending with a `/` delimiter,
+each beginning with a numeric type code. This loader implements a
+**documented, pragmatic subset**:
+
+| Record | Meaning | Handling |
+| :--- | :--- | :--- |
+| `01` | File Header | **Required first record.** `fileId` captured for the summary. |
+| `02` | Group Header | Group `currency` and as-of date captured. |
+| `03` | Account Identifier | `accountNumber` + optional `currencyCode` captured; account currency overrides group currency. |
+| `16` | Transaction Detail | One transaction. |
+| `88` | Continuation | Appended to the preceding `03`/`16` record's text. |
+| `49` / `98` / `99` | Account / Group / File trailers | **Ignored** — control totals are not validated. |
+
+Any other (or unknown) leading type code is ignored so that vendor
+extensions do not abort the parse. Ignoring control-total trailers is a
+deliberate, documented choice: the goal is faithful transaction
+extraction, not file-level reconciliation.
+
+---
+
+## Amount and sign convention
+
+BAI2 amounts are unsigned integers in the account currency's **minor
+units** (cents), with no decimal point. They are converted to
+`decimal.Decimal` by dividing by 100. An empty amount field is treated
+as `0`.
+
+Debit / credit direction is derived from the numeric range of the `16`
+record's type code (this is the loader's chosen, documented convention):
+
+| Type-code range | Direction | Sign |
+| :--- | :--- | :--- |
+| `100`–`399` | Credit | amount kept **positive** |
+| `400`–`699` | Debit | amount made **negative** |
+| anything else | unknown | amount kept **positive** |
+
+The raw BAI2 type code is always preserved on the `Transaction` in both
+`category` (as `bai2:<code>`) and `reference`, so no information is lost
+— even for codes outside the two ranges above.
+
+---
+
+## When not to use this loader
+
+- **You have ISO 20022 camt.053 or SWIFT MT940, not BAI2.** Those are
+  different formats with their own dedicated loaders.
+- **You need control-total reconciliation.** This loader extracts
+  transactions and deliberately ignores the `49`/`98`/`99` trailers; if
+  you must validate file sums, do so before or after loading.
+- **You need the full BAI2 specification.** This is a documented subset
+  focused on transaction extraction, not an exhaustive BAI2 parser.
+
+---
+
+## Development
+
+This project uses [Poetry](https://python-poetry.org/) and
+[mise](https://mise.jdx.dev/).
+
+```bash
+git clone https://github.com/sebastienrousseau/bankstatementparser-loader-bai2.git
+cd bankstatementparser-loader-bai2
+poetry env use python3.12
+poetry install
+```
+
+A `Makefile` orchestrates the quality gates (kept in lockstep with CI):
+
+| Target | What it runs |
+| :--- | :--- |
+| `make check` | All gates (REQUIRED before commit) |
+| `make test` | `pytest --cov=bankstatementparser_loader_bai2 --cov-branch --cov-fail-under=100` |
+| `make lint` | `ruff check` + `black --check` |
+| `make type-check` | `mypy --strict` |
+| `make doc-coverage` | `interrogate --fail-under=100` (docstring coverage) |
+
+Current state (v0.0.10): **all tests passing, 100% line + branch
+coverage** against a 100% enforced floor, `mypy --strict` clean,
+interrogate 100%.
+
+---
+
+## Security
+
+- **Read-only.** The loader only reads text / files you pass it; it
+  writes nothing.
+- **No XML, no network, no code execution.** Parsing is a pure
+  string-to-dataclass transformation.
+- **Decimal arithmetic** is used throughout, avoiding `float` rounding
+  surprises in financial amounts.
+- **Dependencies** are pinned via `poetry.lock` and audited in CI.
+
+To report a vulnerability, please use
+[GitHub private vulnerability reporting](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2/security)
+rather than a public issue.
+
+---
+
+## Contributing
+
+Contributions are welcome — see the
+[contributing instructions](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2/blob/main/CONTRIBUTING.md).
+Thanks to all the
+[contributors](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2/graphs/contributors)
+who have helped build `bankstatementparser-loader-bai2`.
+
+---
+
+## License
+
+Licensed under the [Apache License, Version 2.0](https://opensource.org/license/apache-2-0/).
+Any contribution submitted for inclusion shall be licensed as above,
+without additional terms.
+
+---
+
+<p align="center">
+  <a href="https://bankstatementparser.com">bankstatementparser.com</a> ·
+  <a href="https://pypi.org/project/bankstatementparser-loader-bai2/">PyPI</a> ·
+  <a href="https://github.com/sebastienrousseau/bankstatementparser-loader-bai2">GitHub</a>
+</p>
+

bankstatementparser_loader_bai2-0.0.10.dist-info/RECORD

@@ -0,0 +1,6 @@
+bankstatementparser_loader_bai2/__init__.py,sha256=brUSm0ran5O3AhzsAwjuLBlF5BCCCRdQ1cNZYI3M88Y,942
+bankstatementparser_loader_bai2/loader.py,sha256=Tj9dVM49L54K9ZJVFlMCU5xp4DFoSVI0gM0dTXhEhCk,16133
+bankstatementparser_loader_bai2-0.0.10.dist-info/METADATA,sha256=vdGXVrB_yaT97fu5VunfFBQPr1ZbS5mBlDYVis8soy4,12100
+bankstatementparser_loader_bai2-0.0.10.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+bankstatementparser_loader_bai2-0.0.10.dist-info/licenses/LICENSE,sha256=BhsQ65IVGLlScIgEHcMm2leCnoRbQqwPcLd7N2c8Gt0,10244
+bankstatementparser_loader_bai2-0.0.10.dist-info/RECORD,,

bankstatementparser_loader_bai2-0.0.10.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bankstatementparser_loader_bai2-0.0.10.dist-info/licenses/LICENSE

@@ -0,0 +1,189 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to the Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by the Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding any notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2023-2026 Sebastien Rousseau
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.