banklink 0.1.0__tar.gz

banklink-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/

banklink-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.1
+Name: banklink
+Version: 0.1.0
+Summary: Official BankLink SDK for Python
+Project-URL: Homepage, https://banklink.co.za
+Project-URL: Repository, https://github.com/aurvex-labs/banklink-python
+Project-URL: Documentation, https://banklink.co.za/docs
+License: MIT
+Keywords: banklink,fintech,open-banking,south-africa
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# BankLink Python SDK
+
+Official Python SDK for the [BankLink](https://banklink.co.za) Open Finance API. Link South African bank accounts, ingest transactions, and deliver them anywhere.
+
+## Install
+
+```bash
+pip install banklink
+```
+
+## Quick Start
+
+```python
+from banklink import BankLink
+
+client = BankLink(api_key="bl_live_...")
+
+# List all linked accounts
+accounts = client.accounts.list()
+for account in accounts.data:
+    print(account.id, account.bank, account.account_number)
+
+# Fetch a single page of transactions
+page = client.transactions.list("acc_123", limit=50)
+for txn in page.data:
+    print(txn.date, txn.description, txn.amount, txn.direction)
+
+# Auto-paginate through all transactions
+for txn in client.transactions.list_auto_paginate("acc_123"):
+    print(txn.date, txn.amount)
+
+# Get account balance
+balance = client.balances.get("acc_123")
+print(balance.balance, balance.currency)
+
+# Trigger an on-demand sync
+result = client.accounts.sync("acc_123")
+print(f"Synced {result.synced} transactions, skipped {result.skipped}")
+```
+
+## Async Support
+
+```python
+import asyncio
+from banklink import AsyncBankLink
+
+async def main():
+    async with AsyncBankLink(api_key="bl_live_...") as client:
+        accounts = await client.accounts.list()
+        for account in accounts.data:
+            print(account.id, account.bank)
+
+        # Async auto-pagination
+        async for txn in client.transactions.list_auto_paginate("acc_123"):
+            print(txn.date, txn.amount)
+
+asyncio.run(main())
+```
+
+## Bank Linking
+
+```python
+from banklink import BankLink
+
+client = BankLink(api_key="bl_live_...")
+
+# Initiate a link flow
+result = client.link.create(
+    bank_id="fnb",
+    credentials={"username": "your_username", "password": "your_password"},
+    nickname="My FNB Account",
+)
+
+if result.type == "otp_required":
+    # Submit OTP if required
+    result = client.link.submit_otp(
+        session_token=result.session_token,
+        otp="123456",
+    )
+
+print("Linked:", result.profile_id, result.account_number)
+```
+
+## Error Handling
+
+```python
+from banklink import BankLink, AuthenticationError, NotFoundError, RateLimitError, BankLinkError
+
+client = BankLink(api_key="bl_live_...")
+
+try:
+    account = client.accounts.get("acc_does_not_exist")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except NotFoundError:
+    print("Account not found")
+except RateLimitError:
+    print("Rate limit exceeded — back off and retry")
+except BankLinkError as e:
+    print(f"API error {e.status}: [{e.code}] {e.message}")
+```
+
+## Configuration
+
+```python
+from banklink import BankLink
+
+client = BankLink(
+    api_key="bl_live_...",
+    base_url="https://api.banklink.co.za/v1",  # default
+    timeout=30.0,                               # seconds, default 30
+)
+```
+
+Use the context manager to ensure connections are closed:
+
+```python
+with BankLink(api_key="bl_live_...") as client:
+    accounts = client.accounts.list()
+```
+
+## Requirements
+
+- Python 3.9+
+- [httpx](https://www.python-httpx.org/) >= 0.24 (installed automatically)
+
+## License
+
+MIT — Copyright (c) 2026 Aurvex Labs

banklink-0.1.0/README.md

@@ -0,0 +1,129 @@
+# BankLink Python SDK
+
+Official Python SDK for the [BankLink](https://banklink.co.za) Open Finance API. Link South African bank accounts, ingest transactions, and deliver them anywhere.
+
+## Install
+
+```bash
+pip install banklink
+```
+
+## Quick Start
+
+```python
+from banklink import BankLink
+
+client = BankLink(api_key="bl_live_...")
+
+# List all linked accounts
+accounts = client.accounts.list()
+for account in accounts.data:
+    print(account.id, account.bank, account.account_number)
+
+# Fetch a single page of transactions
+page = client.transactions.list("acc_123", limit=50)
+for txn in page.data:
+    print(txn.date, txn.description, txn.amount, txn.direction)
+
+# Auto-paginate through all transactions
+for txn in client.transactions.list_auto_paginate("acc_123"):
+    print(txn.date, txn.amount)
+
+# Get account balance
+balance = client.balances.get("acc_123")
+print(balance.balance, balance.currency)
+
+# Trigger an on-demand sync
+result = client.accounts.sync("acc_123")
+print(f"Synced {result.synced} transactions, skipped {result.skipped}")
+```
+
+## Async Support
+
+```python
+import asyncio
+from banklink import AsyncBankLink
+
+async def main():
+    async with AsyncBankLink(api_key="bl_live_...") as client:
+        accounts = await client.accounts.list()
+        for account in accounts.data:
+            print(account.id, account.bank)
+
+        # Async auto-pagination
+        async for txn in client.transactions.list_auto_paginate("acc_123"):
+            print(txn.date, txn.amount)
+
+asyncio.run(main())
+```
+
+## Bank Linking
+
+```python
+from banklink import BankLink
+
+client = BankLink(api_key="bl_live_...")
+
+# Initiate a link flow
+result = client.link.create(
+    bank_id="fnb",
+    credentials={"username": "your_username", "password": "your_password"},
+    nickname="My FNB Account",
+)
+
+if result.type == "otp_required":
+    # Submit OTP if required
+    result = client.link.submit_otp(
+        session_token=result.session_token,
+        otp="123456",
+    )
+
+print("Linked:", result.profile_id, result.account_number)
+```
+
+## Error Handling
+
+```python
+from banklink import BankLink, AuthenticationError, NotFoundError, RateLimitError, BankLinkError
+
+client = BankLink(api_key="bl_live_...")
+
+try:
+    account = client.accounts.get("acc_does_not_exist")
+except AuthenticationError:
+    print("Invalid or missing API key")
+except NotFoundError:
+    print("Account not found")
+except RateLimitError:
+    print("Rate limit exceeded — back off and retry")
+except BankLinkError as e:
+    print(f"API error {e.status}: [{e.code}] {e.message}")
+```
+
+## Configuration
+
+```python
+from banklink import BankLink
+
+client = BankLink(
+    api_key="bl_live_...",
+    base_url="https://api.banklink.co.za/v1",  # default
+    timeout=30.0,                               # seconds, default 30
+)
+```
+
+Use the context manager to ensure connections are closed:
+
+```python
+with BankLink(api_key="bl_live_...") as client:
+    accounts = client.accounts.list()
+```
+
+## Requirements
+
+- Python 3.9+
+- [httpx](https://www.python-httpx.org/) >= 0.24 (installed automatically)
+
+## License
+
+MIT — Copyright (c) 2026 Aurvex Labs

banklink-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling<1.22"]
+build-backend = "hatchling.build"
+
+[project]
+name = "banklink"
+version = "0.1.0"
+description = "Official BankLink SDK for Python"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+keywords = ["banklink", "open-banking", "south-africa", "fintech"]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://banklink.co.za"
+Repository = "https://github.com/aurvex-labs/banklink-python"
+Documentation = "https://banklink.co.za/docs"

banklink-0.1.0/src/banklink/__init__.py

@@ -0,0 +1,117 @@
+"""BankLink Python SDK — Official client for the BankLink Open Finance API."""
+
+from __future__ import annotations
+
+from ._client import AsyncClient, SyncClient
+from .errors import (
+    AuthenticationError,
+    BankLinkError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+)
+from .resources.accounts import AsyncAccounts, Accounts
+from .resources.balances import AsyncBalances, Balances
+from .resources.link import AsyncLinkResource, LinkResource
+from .resources.transactions import AsyncTransactions, Transactions
+from .types import (
+    Account,
+    Balance,
+    LinkResult,
+    ListResponse,
+    SyncResult,
+    Transaction,
+)
+
+_DEFAULT_BASE_URL = "https://api.banklink.co.za/v1"
+
+
+class BankLink:
+    """Synchronous BankLink API client.
+
+    Usage::
+
+        client = BankLink(api_key="bl_live_...")
+        accounts = client.accounts.list()
+
+    Or as a context manager::
+
+        with BankLink(api_key="bl_live_...") as client:
+            accounts = client.accounts.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = SyncClient(api_key, base_url=base_url, timeout=timeout)
+        self.accounts = Accounts(self._http)
+        self.transactions = Transactions(self._http)
+        self.balances = Balances(self._http)
+        self.link = LinkResource(self._http)
+
+    def __enter__(self) -> BankLink:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._http.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+
+class AsyncBankLink:
+    """Asynchronous BankLink API client.
+
+    Usage::
+
+        async with AsyncBankLink(api_key="bl_live_...") as client:
+            accounts = await client.accounts.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = AsyncClient(api_key, base_url=base_url, timeout=timeout)
+        self.accounts = AsyncAccounts(self._http)
+        self.transactions = AsyncTransactions(self._http)
+        self.balances = AsyncBalances(self._http)
+        self.link = AsyncLinkResource(self._http)
+
+    async def __aenter__(self) -> AsyncBankLink:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self._http.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._http.close()
+
+
+__all__ = [
+    # Clients
+    "BankLink",
+    "AsyncBankLink",
+    # Types
+    "Account",
+    "Transaction",
+    "Balance",
+    "SyncResult",
+    "LinkResult",
+    "ListResponse",
+    # Errors
+    "BankLinkError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+]

banklink-0.1.0/src/banklink/_client.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import (
+    AuthenticationError,
+    BankLinkError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+)
+
+_DEFAULT_BASE_URL = "https://api.banklink.co.za/v1"
+_USER_AGENT = "banklink-python/0.1.0"
+
+_ERROR_MAP = {
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    status = response.status_code
+    try:
+        payload = response.json()
+        code = payload.get("code", "unknown_error")
+        message = payload.get("message", response.text)
+    except Exception:
+        code = "unknown_error"
+        message = response.text
+
+    exc_class = _ERROR_MAP.get(status, BankLinkError)
+    raise exc_class(status, code, message)
+
+
+class SyncClient:
+    """Synchronous HTTP client for the BankLink API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": _USER_AGENT,
+            },
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        response = self._http.request(method, url, json=body)
+        _raise_for_status(response)
+        return response.json()
+
+    def get(self, path: str) -> Any:
+        return self.request("GET", path)
+
+    def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("POST", path, body=body)
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncClient:
+    """Asynchronous HTTP client for the BankLink API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": _USER_AGENT,
+            },
+            timeout=timeout,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        response = await self._http.request(method, url, json=body)
+        _raise_for_status(response)
+        return response.json()
+
+    async def get(self, path: str) -> Any:
+        return await self.request("GET", path)
+
+    async def post(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("POST", path, body=body)
+
+    async def close(self) -> None:
+        await self._http.aclose()

banklink-0.1.0/src/banklink/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+class BankLinkError(Exception):
+    """Base exception for all BankLink API errors."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class AuthenticationError(BankLinkError):
+    """Raised when the API key is missing or invalid (HTTP 401)."""
+
+
+class InsufficientCreditsError(BankLinkError):
+    """Raised when the account has insufficient credits (HTTP 402)."""
+
+
+class NotFoundError(BankLinkError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+
+class RateLimitError(BankLinkError):
+    """Raised when the rate limit has been exceeded (HTTP 429)."""

banklink-0.1.0/src/banklink/resources/__init__.py

@@ -0,0 +1 @@
+"""BankLink resource modules (accounts, transactions, balances, link)."""

banklink-0.1.0/src/banklink/resources/accounts.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import Account, ListResponse, SyncResult
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, SyncClient
+
+
+def _parse_account(raw: dict) -> Account:
+    return Account(
+        id=raw["id"],
+        bank=raw["bank"],
+        account_number=raw.get("account_number"),
+        nickname=raw["nickname"],
+        last_synced_at=raw.get("last_synced_at"),
+        created_at=raw["created_at"],
+    )
+
+
+class Accounts:
+    """Synchronous accounts resource."""
+
+    def __init__(self, client: SyncClient) -> None:
+        self._client = client
+
+    def list(self) -> ListResponse[Account]:
+        """List all linked bank accounts."""
+        raw = self._client.get("/accounts")
+        return ListResponse(
+            data=[_parse_account(item) for item in raw.get("data", [])],
+            cursor=raw.get("cursor"),
+        )
+
+    def get(self, account_id: str) -> Account:
+        """Retrieve a single bank account by ID."""
+        raw = self._client.get(f"/accounts/{account_id}")
+        return _parse_account(raw)
+
+    def sync(self, account_id: str) -> SyncResult:
+        """Trigger an on-demand sync for the given account."""
+        raw = self._client.post(f"/accounts/{account_id}/sync")
+        return SyncResult(
+            synced=raw["synced"],
+            skipped=raw["skipped"],
+        )
+
+
+class AsyncAccounts:
+    """Asynchronous accounts resource."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def list(self) -> ListResponse[Account]:
+        """List all linked bank accounts."""
+        raw = await self._client.get("/accounts")
+        return ListResponse(
+            data=[_parse_account(item) for item in raw.get("data", [])],
+            cursor=raw.get("cursor"),
+        )
+
+    async def get(self, account_id: str) -> Account:
+        """Retrieve a single bank account by ID."""
+        raw = await self._client.get(f"/accounts/{account_id}")
+        return _parse_account(raw)
+
+    async def sync(self, account_id: str) -> SyncResult:
+        """Trigger an on-demand sync for the given account."""
+        raw = await self._client.post(f"/accounts/{account_id}/sync")
+        return SyncResult(
+            synced=raw["synced"],
+            skipped=raw["skipped"],
+        )

banklink-0.1.0/src/banklink/resources/balances.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..types import Balance
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, SyncClient
+
+
+class Balances:
+    """Synchronous balances resource."""
+
+    def __init__(self, client: SyncClient) -> None:
+        self._client = client
+
+    def get(self, account_id: str) -> Balance:
+        """Retrieve the current balance for the given account."""
+        raw = self._client.get(f"/accounts/{account_id}/balance")
+        return Balance(
+            account_id=raw["account_id"],
+            balance=float(raw["balance"]) if raw.get("balance") is not None else None,
+            currency=raw["currency"],
+            last_synced_at=raw.get("last_synced_at"),
+        )
+
+
+class AsyncBalances:
+    """Asynchronous balances resource."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def get(self, account_id: str) -> Balance:
+        """Retrieve the current balance for the given account."""
+        raw = await self._client.get(f"/accounts/{account_id}/balance")
+        return Balance(
+            account_id=raw["account_id"],
+            balance=float(raw["balance"]) if raw.get("balance") is not None else None,
+            currency=raw["currency"],
+            last_synced_at=raw.get("last_synced_at"),
+        )

banklink-0.1.0/src/banklink/resources/link.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Optional
+
+from ..types import LinkResult
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, SyncClient
+
+
+def _parse_link_result(raw: dict) -> LinkResult:
+    return LinkResult(
+        type=raw["type"],
+        profile_id=raw.get("profile_id"),
+        account_number=raw.get("account_number"),
+        session_token=raw.get("session_token"),
+        message=raw.get("message"),
+    )
+
+
+class LinkResource:
+    """Synchronous link resource for connecting bank accounts."""
+
+    def __init__(self, client: SyncClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        bank_id: str,
+        credentials: Dict[str, str],
+        nickname: Optional[str] = None,
+    ) -> LinkResult:
+        """Initiate a bank account link flow."""
+        body: Dict[str, object] = {
+            "bankId": bank_id,
+            "credentials": credentials,
+        }
+        if nickname is not None:
+            body["nickname"] = nickname
+        raw = self._client.post("/link", body=body)
+        return _parse_link_result(raw)
+
+    def submit_otp(self, *, session_token: str, otp: str) -> LinkResult:
+        """Submit an OTP to complete a multi-step link flow."""
+        raw = self._client.post(
+            "/link/otp",
+            body={"session_token": session_token, "otp": otp},
+        )
+        return _parse_link_result(raw)
+
+
+class AsyncLinkResource:
+    """Asynchronous link resource for connecting bank accounts."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        bank_id: str,
+        credentials: Dict[str, str],
+        nickname: Optional[str] = None,
+    ) -> LinkResult:
+        """Initiate a bank account link flow."""
+        body: Dict[str, object] = {
+            "bankId": bank_id,
+            "credentials": credentials,
+        }
+        if nickname is not None:
+            body["nickname"] = nickname
+        raw = await self._client.post("/link", body=body)
+        return _parse_link_result(raw)
+
+    async def submit_otp(self, *, session_token: str, otp: str) -> LinkResult:
+        """Submit an OTP to complete a multi-step link flow."""
+        raw = await self._client.post(
+            "/link/otp",
+            body={"session_token": session_token, "otp": otp},
+        )
+        return _parse_link_result(raw)

banklink-0.1.0/src/banklink/resources/transactions.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, AsyncIterator, Iterator, Optional
+
+from ..types import ListResponse, Transaction
+
+if TYPE_CHECKING:
+    from .._client import AsyncClient, SyncClient
+
+
+def _parse_transaction(raw: dict) -> Transaction:
+    return Transaction(
+        id=raw["id"],
+        account_id=raw["account_id"],
+        external_id=raw["external_id"],
+        date=raw["date"],
+        description=raw["description"],
+        amount=float(raw["amount"]),
+        currency=raw["currency"],
+        direction=raw["direction"],
+        balance=float(raw["balance"]) if raw.get("balance") is not None else None,
+        reference=raw.get("reference"),
+        created_at=raw["created_at"],
+    )
+
+
+def _build_path(
+    account_id: str,
+    limit: Optional[int],
+    cursor: Optional[str],
+) -> str:
+    path = f"/accounts/{account_id}/transactions"
+    params: list[str] = []
+    if limit is not None:
+        params.append(f"limit={limit}")
+    if cursor is not None:
+        params.append(f"cursor={cursor}")
+    if params:
+        path = f"{path}?{'&'.join(params)}"
+    return path
+
+
+class Transactions:
+    """Synchronous transactions resource."""
+
+    def __init__(self, client: SyncClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        account_id: str,
+        *,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> ListResponse[Transaction]:
+        """Fetch a single page of transactions for the given account."""
+        path = _build_path(account_id, limit, cursor)
+        raw = self._client.get(path)
+        return ListResponse(
+            data=[_parse_transaction(item) for item in raw.get("data", [])],
+            cursor=raw.get("cursor"),
+        )
+
+    def list_auto_paginate(
+        self,
+        account_id: str,
+        *,
+        limit: Optional[int] = None,
+    ) -> Iterator[Transaction]:
+        """Yield all transactions across all pages automatically."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.list(account_id, limit=limit, cursor=cursor)
+            yield from page.data
+            if page.cursor is None:
+                break
+            cursor = page.cursor
+
+
+class AsyncTransactions:
+    """Asynchronous transactions resource."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        account_id: str,
+        *,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> ListResponse[Transaction]:
+        """Fetch a single page of transactions for the given account."""
+        path = _build_path(account_id, limit, cursor)
+        raw = await self._client.get(path)
+        return ListResponse(
+            data=[_parse_transaction(item) for item in raw.get("data", [])],
+            cursor=raw.get("cursor"),
+        )
+
+    async def list_auto_paginate(
+        self,
+        account_id: str,
+        *,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[Transaction]:
+        """Yield all transactions across all pages automatically."""
+        cursor: Optional[str] = None
+        while True:
+            page = await self.list(account_id, limit=limit, cursor=cursor)
+            for txn in page.data:
+                yield txn
+            if page.cursor is None:
+                break
+            cursor = page.cursor

banklink-0.1.0/src/banklink/types.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Account:
+    id: str
+    bank: str
+    account_number: Optional[str]
+    nickname: str
+    last_synced_at: Optional[str]
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Transaction:
+    id: str
+    account_id: str
+    external_id: str
+    date: str
+    description: str
+    amount: float
+    currency: str
+    direction: str
+    balance: Optional[float]
+    reference: Optional[str]
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Balance:
+    account_id: str
+    balance: Optional[float]
+    currency: str
+    last_synced_at: Optional[str]
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    synced: int
+    skipped: int
+
+
+@dataclass(frozen=True)
+class LinkResult:
+    type: str
+    profile_id: Optional[str] = None
+    account_number: Optional[str] = None
+    session_token: Optional[str] = None
+    message: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ListResponse(Generic[T]):
+    data: List[T]
+    cursor: Optional[str]