makky-acb-api 0.1.0__tar.gz

makky_acb_api-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include README.md

makky_acb_api-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: makky-acb-api
+Version: 0.1.0
+Summary: Unofficial Python client for ACB account balances and transaction history
+Author: Makky
+Maintainer: Makky
+Project-URL: Homepage, https://github.com/Makky/ACB-API
+Project-URL: Repository, https://github.com/Makky/ACB-API
+Project-URL: Issues, https://github.com/Makky/ACB-API/issues
+Keywords: acb,banking,api,transactions,payments
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# makky-acb-api
+
+**🇺🇸 English** | [🇻🇳 Tiếng Việt](README_VI.md)
+
+Unofficial Python client for ACB account balances and transaction history, packaged for local installation and future PyPI publication.
+
+## Features
+
+- Authenticate with ACB using username and password
+- Fetch balances for payment accounts
+- Retrieve recent transaction history for a selected account
+- Use as a Python library or from a CLI command
+
+## Installation
+
+### Local development install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### After publication to PyPI
+
+```bash
+pip install makky-acb-api
+```
+
+## Environment variables
+
+Create a `.env` file in the project root:
+
+```env
+ACB_USERNAME=your_username
+ACB_PASSWORD=your_password
+```
+
+> [!WARNING]
+> This project uses an unofficial ACB API. Protect your credentials and use it at your own risk.
+
+## Python usage
+
+```python
+from acb_api import ACBClient
+
+client = ACBClient(username="your_username", password="your_password")
+balances = client.get_balances()
+print(balances)
+
+account = balances["balances"][0]["accountNumber"]
+transactions = client.get_transactions(rows=5, account_number=account)
+print(transactions)
+```
+
+## CLI usage
+
+After `pip install -e .`, run:
+
+```bash
+acb-api --action all --rows 5
+```
+
+Other examples:
+
+```bash
+acb-api --action balances
+acb-api --action transactions --account 19527581 --rows 10
+acb-api --action all --debug
+```
+
+## Local demo script
+
+For backward-compatible local testing:
+
+```bash
+python main.py
+```
+
+## Project structure
+
+```text
+ACB-API/
+├── src/acb_api/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── exceptions.py
+│   └── models.py
+├── main.py
+├── pyproject.toml
+└── README.md
+```
+
+## Packaging notes
+
+- Distribution/package name: `makky-acb-api`
+- Import package name: `acb_api`
+- Author / maintainer: `Makky`
+
+To build distributable artifacts locally:
+
+```bash
+python -m build
+```
+
+## Credits
+
+This packaged version is maintained by **Makky**.
+
+Inspired by earlier community work around ACB unofficial integrations, including:
+- [anhnmt/ACB](https://github.com/anhnmt/ACB)
+
+## Disclaimer
+
+This is an unofficial client and is not affiliated with ACB. APIs, headers, and authentication flows may change without notice. Use at your own risk.

makky_acb_api-0.1.0/README.md

@@ -0,0 +1,116 @@
+# makky-acb-api
+
+**🇺🇸 English** | [🇻🇳 Tiếng Việt](README_VI.md)
+
+Unofficial Python client for ACB account balances and transaction history, packaged for local installation and future PyPI publication.
+
+## Features
+
+- Authenticate with ACB using username and password
+- Fetch balances for payment accounts
+- Retrieve recent transaction history for a selected account
+- Use as a Python library or from a CLI command
+
+## Installation
+
+### Local development install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### After publication to PyPI
+
+```bash
+pip install makky-acb-api
+```
+
+## Environment variables
+
+Create a `.env` file in the project root:
+
+```env
+ACB_USERNAME=your_username
+ACB_PASSWORD=your_password
+```
+
+> [!WARNING]
+> This project uses an unofficial ACB API. Protect your credentials and use it at your own risk.
+
+## Python usage
+
+```python
+from acb_api import ACBClient
+
+client = ACBClient(username="your_username", password="your_password")
+balances = client.get_balances()
+print(balances)
+
+account = balances["balances"][0]["accountNumber"]
+transactions = client.get_transactions(rows=5, account_number=account)
+print(transactions)
+```
+
+## CLI usage
+
+After `pip install -e .`, run:
+
+```bash
+acb-api --action all --rows 5
+```
+
+Other examples:
+
+```bash
+acb-api --action balances
+acb-api --action transactions --account 19527581 --rows 10
+acb-api --action all --debug
+```
+
+## Local demo script
+
+For backward-compatible local testing:
+
+```bash
+python main.py
+```
+
+## Project structure
+
+```text
+ACB-API/
+├── src/acb_api/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── exceptions.py
+│   └── models.py
+├── main.py
+├── pyproject.toml
+└── README.md
+```
+
+## Packaging notes
+
+- Distribution/package name: `makky-acb-api`
+- Import package name: `acb_api`
+- Author / maintainer: `Makky`
+
+To build distributable artifacts locally:
+
+```bash
+python -m build
+```
+
+## Credits
+
+This packaged version is maintained by **Makky**.
+
+Inspired by earlier community work around ACB unofficial integrations, including:
+- [anhnmt/ACB](https://github.com/anhnmt/ACB)
+
+## Disclaimer
+
+This is an unofficial client and is not affiliated with ACB. APIs, headers, and authentication flows may change without notice. Use at your own risk.

makky_acb_api-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "makky-acb-api"
+version = "0.1.0"
+description = "Unofficial Python client for ACB account balances and transaction history"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Makky" }
+]
+maintainers = [
+  { name = "Makky" }
+]
+dependencies = [
+  "requests>=2.31.0",
+  "python-dotenv>=1.0.0"
+]
+keywords = ["acb", "banking", "api", "transactions", "payments"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.urls]
+Homepage = "https://github.com/Makky/ACB-API"
+Repository = "https://github.com/Makky/ACB-API"
+Issues = "https://github.com/Makky/ACB-API/issues"
+
+[project.scripts]
+acb-api = "acb_api.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

makky_acb_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

makky_acb_api-0.1.0/src/acb_api/__init__.py

@@ -0,0 +1,4 @@
+from .client import ACB, ACBClient
+
+__all__ = ["ACB", "ACBClient"]
+__version__ = "0.1.0"

makky_acb_api-0.1.0/src/acb_api/cli.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from .client import ACBClient
+from .exceptions import ACBError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Unofficial ACB API CLI")
+    parser.add_argument("--username", help="ACB username")
+    parser.add_argument("--password", help="ACB password")
+    parser.add_argument("--rows", type=int, default=5, help="Number of transactions to fetch")
+    parser.add_argument("--account", help="Account number to fetch transactions for")
+    parser.add_argument(
+        "--action",
+        choices=["balances", "transactions", "all"],
+        default="all",
+        help="Operation to perform",
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable verbose HTTP debug output")
+    return parser
+
+
+def resolve_credentials(username: Optional[str], password: Optional[str]) -> tuple[str, str]:
+    load_dotenv()
+    final_username = username or os.getenv("ACB_USERNAME")
+    final_password = password or os.getenv("ACB_PASSWORD")
+
+    if not final_username or not final_password:
+        raise ValueError("Missing credentials. Provide --username/--password or set ACB_USERNAME and ACB_PASSWORD.")
+
+    return final_username, final_password
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        username, password = resolve_credentials(args.username, args.password)
+        client = ACBClient(username=username, password=password, debug=args.debug)
+
+        if args.action in {"balances", "all"}:
+            balances = client.get_balances()
+            print(json.dumps({"balances": balances["balances"]}, indent=2, ensure_ascii=False))
+
+        if args.action in {"transactions", "all"}:
+            account = args.account or client.get_first_account_number()
+            if not account:
+                print("No account available for transaction lookup.")
+                return 0
+
+            transactions = client.get_transactions(rows=args.rows, account_number=account)
+            print(json.dumps({"account": account, "transactions": transactions}, indent=2, ensure_ascii=False))
+
+        return 0
+    except (ValueError, ACBError) as exc:
+        print(f"Error: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

makky_acb_api-0.1.0/src/acb_api/client.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CLIENT_ID,
+    DEFAULT_SESSION_HEADERS,
+    DEFAULT_TIMEOUT,
+)
+from .exceptions import ACBAuthenticationError, ACBRequestError
+from .models import AccountBalance, TransactionRecord
+
+
+def _generate_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def _generate_device_id() -> str:
+    return str(uuid.uuid4()).upper()
+
+
+class ACBClient:
+    """Unofficial ACB API client for balances and transaction history."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        client_id: str = DEFAULT_CLIENT_ID,
+        timeout: int = DEFAULT_TIMEOUT,
+        debug: bool = False,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not username or not password:
+            raise ValueError("Username and password cannot be empty.")
+
+        self.username = username.strip()
+        self.password = password.strip()
+        self.base_url = base_url.rstrip("/")
+        self.client_id = client_id
+        self.timeout = timeout
+        self.debug = debug
+        self.device_id = _generate_device_id()
+        self.access_token: Optional[str] = None
+        self.refresh_token: Optional[str] = None
+
+        self.session = session or requests.Session()
+        self.session.headers.update(DEFAULT_SESSION_HEADERS)
+
+    def _debug(self, message: str) -> None:
+        if self.debug:
+            print(message)
+
+    def _get_request_headers(self, include_auth: bool = False) -> Dict[str, str]:
+        headers = {"x-request-id": _generate_uuid()}
+        if include_auth and self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        data: Optional[str] = None,
+        auth_required: bool = False,
+    ) -> requests.Response:
+        request_headers = self._get_request_headers(include_auth=auth_required)
+        if headers:
+            request_headers.update(headers)
+
+        url = f"{self.base_url}{path}"
+        self._debug(f"{method.upper()} {url}")
+
+        try:
+            response = self.session.request(
+                method=method.upper(),
+                url=url,
+                headers=request_headers,
+                data=data,
+                timeout=self.timeout,
+            )
+        except requests.exceptions.RequestException as exc:
+            raise ACBRequestError(f"Request to ACB failed: {exc}") from exc
+
+        self._debug(f"Status: {response.status_code}")
+        if self.debug:
+            self._debug(f"Response body: {response.text}")
+
+        return response
+
+    def login(self) -> None:
+        payload = {
+            "username": self.username,
+            "password": self.password,
+            "deviceId": self.device_id,
+            "clientId": self.client_id,
+        }
+
+        response = self._request(
+            "POST",
+            "/mb/v2/auth/tokens",
+            data=json.dumps(payload),
+        )
+
+        if not response.ok:
+            raise ACBAuthenticationError(
+                f"Authentication failed ({response.status_code}): {response.text}"
+            )
+
+        login_data = response.json()
+        self.access_token = login_data.get("accessToken")
+        self.refresh_token = login_data.get("refreshToken")
+
+        if not self.access_token:
+            raise ACBAuthenticationError("Authentication succeeded but no access token was returned.")
+
+    def refresh(self) -> None:
+        if not self.refresh_token:
+            self.login()
+            return
+
+        response = self._request(
+            "POST",
+            "/mb/v2/auth/refresh",
+            headers={"Authorization": f"Bearer {self.refresh_token}"},
+        )
+
+        if not response.ok:
+            self._debug("Refresh failed, retrying with full login.")
+            self.login()
+            return
+
+        refresh_data = response.json()
+        self.access_token = refresh_data.get("accessToken")
+        if not self.access_token:
+            self.login()
+
+    def authenticate(self) -> None:
+        if self.refresh_token:
+            self.refresh()
+        else:
+            self.login()
+
+    def get_balances(self) -> Dict[str, List[AccountBalance]]:
+        self.authenticate()
+        response = self._request(
+            "GET",
+            "/mb/legacy/ss/cs/bankservice/transfers/list/account-payment",
+            auth_required=True,
+        )
+
+        if not response.ok:
+            raise ACBRequestError(
+                f"Failed to fetch balances ({response.status_code}): {response.text}"
+            )
+
+        payload = response.json()
+        balances: List[AccountBalance] = []
+        for account in payload.get("data", []):
+            balances.append(
+                AccountBalance(
+                    accountNumber=str(account.get("accountNumber", "")),
+                    accountDescription=account.get("accountDescription", ""),
+                    ownerName=account.get("owner", ""),
+                    currency=account.get("currency", ""),
+                    balance=float(account.get("balance", 0) or 0),
+                    totalBalance=float(account.get("totalBalance", 0) or 0),
+                    status=int(account.get("status", 0) or 0),
+                )
+            )
+        return {"balances": balances}
+
+    def get_transactions(self, rows: int, account_number: str) -> List[TransactionRecord]:
+        self.authenticate()
+        path = (
+            f"/mb/legacy/ss/cs/bankservice/saving/tx-history?maxRows={rows}"
+            f"&account={account_number}"
+        )
+        response = self._request("GET", path, auth_required=True)
+
+        if not response.ok:
+            raise ACBRequestError(
+                f"Failed to fetch transactions ({response.status_code}): {response.text}"
+            )
+
+        payload = response.json()
+        data = payload.get("data", [])
+        return [TransactionRecord(**item) for item in data]
+
+    def get_first_account_number(self) -> Optional[str]:
+        balances = self.get_balances().get("balances", [])
+        if not balances:
+            return None
+        return balances[0]["accountNumber"]
+
+
+ACB = ACBClient

makky_acb_api-0.1.0/src/acb_api/config.py

@@ -0,0 +1,16 @@
+DEFAULT_BASE_URL = "https://apiapp.acb.com.vn"
+DEFAULT_CLIENT_ID = "iuSuHYVufIUuNIREV0FB9EoLn9kHsDbm"
+DEFAULT_API_KEY = "CQk6S5usauGmMgMYLGqCuDtgtqIM8FI1"
+DEFAULT_APP_VERSION = "3.26.0"
+DEFAULT_USER_AGENT = "ACB-MBA/8 CFNetwork/1335.0.3 Darwin/21.6.0"
+DEFAULT_CONVERSATION_ID = "f43472f1-6d88-4228-91b9-4618a079342a"
+DEFAULT_TIMEOUT = 30
+
+DEFAULT_SESSION_HEADERS = {
+    "Accept": "application/json, text/plain, */*",
+    "Content-Type": "application/json",
+    "apikey": DEFAULT_API_KEY,
+    "User-Agent": DEFAULT_USER_AGENT,
+    "x-app-version": DEFAULT_APP_VERSION,
+    "x-conversation-id": DEFAULT_CONVERSATION_ID,
+}

makky_acb_api-0.1.0/src/acb_api/exceptions.py

@@ -0,0 +1,10 @@
+class ACBError(Exception):
+    """Base exception for the acb_api package."""
+
+
+class ACBAuthenticationError(ACBError):
+    """Raised when authentication with ACB fails."""
+
+
+class ACBRequestError(ACBError):
+    """Raised when an ACB API request fails."""

makky_acb_api-0.1.0/src/acb_api/models.py

@@ -0,0 +1,29 @@
+from typing import TypedDict
+
+
+class AccountBalance(TypedDict):
+    accountNumber: str
+    accountDescription: str
+    ownerName: str
+    currency: str
+    balance: float
+    totalBalance: float
+    status: int
+
+
+class TransactionRecord(TypedDict, total=False):
+    amount: float
+    accountName: str
+    receiverName: str
+    transactionNumber: int
+    description: str
+    bankName: str
+    isOnline: bool
+    postingDate: int
+    accountOwner: str
+    type: str
+    receiverAccountNumber: str
+    currency: str
+    account: int
+    activeDatetime: int
+    effectiveDate: int

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: makky-acb-api
+Version: 0.1.0
+Summary: Unofficial Python client for ACB account balances and transaction history
+Author: Makky
+Maintainer: Makky
+Project-URL: Homepage, https://github.com/Makky/ACB-API
+Project-URL: Repository, https://github.com/Makky/ACB-API
+Project-URL: Issues, https://github.com/Makky/ACB-API/issues
+Keywords: acb,banking,api,transactions,payments
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# makky-acb-api
+
+**🇺🇸 English** | [🇻🇳 Tiếng Việt](README_VI.md)
+
+Unofficial Python client for ACB account balances and transaction history, packaged for local installation and future PyPI publication.
+
+## Features
+
+- Authenticate with ACB using username and password
+- Fetch balances for payment accounts
+- Retrieve recent transaction history for a selected account
+- Use as a Python library or from a CLI command
+
+## Installation
+
+### Local development install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### After publication to PyPI
+
+```bash
+pip install makky-acb-api
+```
+
+## Environment variables
+
+Create a `.env` file in the project root:
+
+```env
+ACB_USERNAME=your_username
+ACB_PASSWORD=your_password
+```
+
+> [!WARNING]
+> This project uses an unofficial ACB API. Protect your credentials and use it at your own risk.
+
+## Python usage
+
+```python
+from acb_api import ACBClient
+
+client = ACBClient(username="your_username", password="your_password")
+balances = client.get_balances()
+print(balances)
+
+account = balances["balances"][0]["accountNumber"]
+transactions = client.get_transactions(rows=5, account_number=account)
+print(transactions)
+```
+
+## CLI usage
+
+After `pip install -e .`, run:
+
+```bash
+acb-api --action all --rows 5
+```
+
+Other examples:
+
+```bash
+acb-api --action balances
+acb-api --action transactions --account 19527581 --rows 10
+acb-api --action all --debug
+```
+
+## Local demo script
+
+For backward-compatible local testing:
+
+```bash
+python main.py
+```
+
+## Project structure
+
+```text
+ACB-API/
+├── src/acb_api/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── client.py
+│   ├── config.py
+│   ├── exceptions.py
+│   └── models.py
+├── main.py
+├── pyproject.toml
+└── README.md
+```
+
+## Packaging notes
+
+- Distribution/package name: `makky-acb-api`
+- Import package name: `acb_api`
+- Author / maintainer: `Makky`
+
+To build distributable artifacts locally:
+
+```bash
+python -m build
+```
+
+## Credits
+
+This packaged version is maintained by **Makky**.
+
+Inspired by earlier community work around ACB unofficial integrations, including:
+- [anhnmt/ACB](https://github.com/anhnmt/ACB)
+
+## Disclaimer
+
+This is an unofficial client and is not affiliated with ACB. APIs, headers, and authentication flows may change without notice. Use at your own risk.

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/acb_api/__init__.py
+src/acb_api/cli.py
+src/acb_api/client.py
+src/acb_api/config.py
+src/acb_api/exceptions.py
+src/acb_api/models.py
+src/makky_acb_api.egg-info/PKG-INFO
+src/makky_acb_api.egg-info/SOURCES.txt
+src/makky_acb_api.egg-info/dependency_links.txt
+src/makky_acb_api.egg-info/entry_points.txt
+src/makky_acb_api.egg-info/requires.txt
+src/makky_acb_api.egg-info/top_level.txt

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+acb-api = acb_api.cli:main

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.31.0
+python-dotenv>=1.0.0

makky_acb_api-0.1.0/src/makky_acb_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+acb_api