cyclos-sdk-py 0.1.0__py3-none-any.whl

angstrom_cyclos/__init__.py

@@ -0,0 +1,40 @@
+"""angstrom-cyclos: Python SDK for Cyclos 4.16 REST API."""
+
+__version__ = "0.1.0"
+
+from angstrom_cyclos.async_client import AsyncCyclosClient
+from angstrom_cyclos.client import CyclosClient
+from angstrom_cyclos.config import CyclosConfig
+from angstrom_cyclos.exceptions import (
+    CyclosAuthenticationError,
+    CyclosAuthorizationError,
+    CyclosConflictError,
+    CyclosConnectionError,
+    CyclosError,
+    CyclosIdempotencyError,
+    CyclosNotFoundError,
+    CyclosRateLimitError,
+    CyclosServerError,
+    CyclosTimeoutError,
+    CyclosTransferError,
+    CyclosValidationError,
+)
+
+__all__ = [
+    "__version__",
+    "CyclosClient",
+    "AsyncCyclosClient",
+    "CyclosConfig",
+    "CyclosError",
+    "CyclosAuthenticationError",
+    "CyclosAuthorizationError",
+    "CyclosValidationError",
+    "CyclosNotFoundError",
+    "CyclosConflictError",
+    "CyclosRateLimitError",
+    "CyclosServerError",
+    "CyclosTimeoutError",
+    "CyclosConnectionError",
+    "CyclosTransferError",
+    "CyclosIdempotencyError",
+]

angstrom_cyclos/__main__.py

@@ -0,0 +1,82 @@
+"""CLI entry point for angstrom-cyclos."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from angstrom_cyclos import CyclosClient, CyclosConfig
+
+
+def _sync_main(args: argparse.Namespace) -> int:
+    config = CyclosConfig.from_env()
+    with CyclosClient(config) as client:
+        if args.command == "auth" and args.subcommand == "login":
+            print("Use application code or environment variables to authenticate.")
+            return 0
+        if args.command == "members" and args.subcommand == "get":
+            member = client.members.get(args.id)
+            print(member.model_dump_json(indent=2))
+            return 0
+        if args.command == "members" and args.subcommand == "search":
+            result = client.members.search(query=args.query)
+            print(result.model_dump_json(indent=2))
+            return 0
+        if args.command == "accounts" and args.subcommand == "balance":
+            balance = client.accounts.get_balance(args.member)
+            print(balance.model_dump_json(indent=2))
+            return 0
+        if args.command == "transfers" and args.subcommand == "get":
+            transfer = client.transfers.get(args.id)
+            print(transfer.model_dump_json(indent=2))
+            return 0
+        if args.command == "transfers" and args.subcommand == "history":
+            history = client.transfers.history(
+                member_id=args.member, account_type=args.account_type
+            )
+            print(history.model_dump_json(indent=2))
+            return 0
+    return 1
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cyclos", description="Angstrom Cyclos SDK CLI")
+    sub = parser.add_subparsers(dest="command")
+
+    auth = sub.add_parser("auth")
+    auth.add_subparsers(dest="subcommand").add_parser("login")
+
+    members = sub.add_parser("members")
+    members_sub = members.add_subparsers(dest="subcommand")
+    get_member = members_sub.add_parser("get")
+    get_member.add_argument("id")
+    search_member = members_sub.add_parser("search")
+    search_member.add_argument("query")
+
+    accounts = sub.add_parser("accounts")
+    accounts_sub = accounts.add_subparsers(dest="subcommand")
+    balance = accounts_sub.add_parser("balance")
+    balance.add_argument("member")
+
+    transfers = sub.add_parser("transfers")
+    transfers_sub = transfers.add_subparsers(dest="subcommand")
+    get_transfer = transfers_sub.add_parser("get")
+    get_transfer.add_argument("id")
+    history = transfers_sub.add_parser("history")
+    history.add_argument("member")
+    history.add_argument("--account-type", default="mobileWallet")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    return _sync_main(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

angstrom_cyclos/accounts/__init__.py

@@ -0,0 +1,6 @@
+"""Account management module."""
+
+from angstrom_cyclos.accounts.client import AccountsClient
+from angstrom_cyclos.accounts.models import Account, AccountHistoryEntry, AccountStatus
+
+__all__ = ["AccountsClient", "Account", "AccountStatus", "AccountHistoryEntry"]

angstrom_cyclos/accounts/client.py

@@ -0,0 +1,109 @@
+"""Account management client."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from angstrom_cyclos.accounts.models import Account, AccountHistoryEntry, AccountStatus
+from angstrom_cyclos.models import AccountBalance, PaginatedResult
+
+if TYPE_CHECKING:
+    from angstrom_cyclos.client import CyclosClient
+
+
+class AccountsClient:
+    """List accounts, retrieve statuses and balances, and fetch history."""
+
+    def __init__(self, client: CyclosClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        member_id: str,
+        *,
+        page: int = 0,
+        page_size: int = 20,
+    ) -> PaginatedResult[Account]:
+        """List accounts for an owner/member."""
+        response = self._client._transport.get(
+            f"/{member_id}/accounts",
+            params={"page": page, "pageSize": page_size},
+        )
+        items = [Account.model_validate(a) for a in response.json()]
+        return PaginatedResult[Account](
+            items=items,
+            page=page,
+            page_size=page_size,
+            has_next=len(items) >= page_size,
+        )
+
+    def get(self, member_id: str, account_type: str) -> Account:
+        """Retrieve the account status for a specific account type."""
+        response = self._client._transport.get(f"/{member_id}/accounts/{account_type}")
+        return Account.model_validate(response.json())
+
+    def get_balance(
+        self,
+        member_id: str,
+        *,
+        account_type: str = "mobileWallet",
+    ) -> AccountBalance:
+        """Return a strongly typed balance for the given member and account type."""
+        account = self.get(member_id, account_type)
+        status = account.status or AccountStatus()
+        return AccountBalance(
+            account_id=account.id or member_id,
+            account_type=account_type,
+            currency=account.currency.name if account.currency else None,
+            balance=status.balance or Decimal("0"),
+            available_balance=status.available_balance,
+            credit_limit=status.credit_limit,
+            reserved_amount=status.reserved_amount,
+        )
+
+    def history(
+        self,
+        member_id: str,
+        account_type: str,
+        *,
+        page: int = 0,
+        page_size: int = 20,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        amount_min: Decimal | None = None,
+        amount_max: Decimal | None = None,
+        status: str | None = None,
+        transfer_type: str | None = None,
+        direction: str | None = None,
+    ) -> PaginatedResult[AccountHistoryEntry]:
+        """Fetch account history (balance transfers)."""
+        params: dict[str, Any] = {
+            "page": page,
+            "pageSize": page_size,
+        }
+        if date_from:
+            params["datePeriod.begin"] = date_from
+        if date_to:
+            params["datePeriod.end"] = date_to
+        if amount_min is not None:
+            params["amountRange.min"] = str(amount_min)
+        if amount_max is not None:
+            params["amountRange.max"] = str(amount_max)
+        if status:
+            params["statuses"] = status
+        if transfer_type:
+            params["transferTypes"] = transfer_type
+        if direction:
+            params["direction"] = direction
+        response = self._client._transport.get(
+            f"/{member_id}/accounts/{account_type}/history",
+            params=params,
+        )
+        items = [AccountHistoryEntry.model_validate(entry) for entry in response.json()]
+        return PaginatedResult[AccountHistoryEntry](
+            items=items,
+            page=page,
+            page_size=page_size,
+            has_next=len(items) >= page_size,
+        )

angstrom_cyclos/accounts/client_async.py

@@ -0,0 +1,102 @@
+"""Asynchronous account client."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from angstrom_cyclos.accounts.models import Account, AccountHistoryEntry, AccountStatus
+from angstrom_cyclos.models import AccountBalance, PaginatedResult
+
+if TYPE_CHECKING:
+    from angstrom_cyclos.async_client import AsyncCyclosClient
+
+
+class AsyncAccountsClient:
+    """Async account client."""
+
+    def __init__(self, client: AsyncCyclosClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        member_id: str,
+        *,
+        page: int = 0,
+        page_size: int = 20,
+    ) -> PaginatedResult[Account]:
+        response = await self._client._transport.get(
+            f"/{member_id}/accounts",
+            params={"page": page, "pageSize": page_size},
+        )
+        items = [Account.model_validate(a) for a in response.json()]
+        return PaginatedResult[Account](
+            items=items,
+            page=page,
+            page_size=page_size,
+            has_next=len(items) >= page_size,
+        )
+
+    async def get(self, member_id: str, account_type: str) -> Account:
+        response = await self._client._transport.get(f"/{member_id}/accounts/{account_type}")
+        return Account.model_validate(response.json())
+
+    async def get_balance(
+        self,
+        member_id: str,
+        *,
+        account_type: str = "mobileWallet",
+    ) -> AccountBalance:
+        account = await self.get(member_id, account_type)
+        status = account.status or AccountStatus()
+        return AccountBalance(
+            account_id=account.id or member_id,
+            account_type=account_type,
+            currency=account.currency.name if account.currency else None,
+            balance=status.balance or Decimal("0"),
+            available_balance=status.available_balance,
+            credit_limit=status.credit_limit,
+            reserved_amount=status.reserved_amount,
+        )
+
+    async def history(
+        self,
+        member_id: str,
+        account_type: str,
+        *,
+        page: int = 0,
+        page_size: int = 20,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        amount_min: Decimal | None = None,
+        amount_max: Decimal | None = None,
+        status: str | None = None,
+        transfer_type: str | None = None,
+        direction: str | None = None,
+    ) -> PaginatedResult[AccountHistoryEntry]:
+        params: dict[str, Any] = {"page": page, "pageSize": page_size}
+        if date_from:
+            params["datePeriod.begin"] = date_from
+        if date_to:
+            params["datePeriod.end"] = date_to
+        if amount_min is not None:
+            params["amountRange.min"] = str(amount_min)
+        if amount_max is not None:
+            params["amountRange.max"] = str(amount_max)
+        if status:
+            params["statuses"] = status
+        if transfer_type:
+            params["transferTypes"] = transfer_type
+        if direction:
+            params["direction"] = direction
+        response = await self._client._transport.get(
+            f"/{member_id}/accounts/{account_type}/history",
+            params=params,
+        )
+        items = [AccountHistoryEntry.model_validate(entry) for entry in response.json()]
+        return PaginatedResult[AccountHistoryEntry](
+            items=items,
+            page=page,
+            page_size=page_size,
+            has_next=len(items) >= page_size,
+        )

angstrom_cyclos/accounts/models.py

@@ -0,0 +1,57 @@
+"""Account models."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from pydantic import Field
+
+from angstrom_cyclos.models import (
+    AccountReference,
+    Currency,
+    CyclosBaseModel,
+    EntityReference,
+    UserReference,
+)
+
+
+class AccountStatus(CyclosBaseModel):
+    """Account status including balances."""
+
+    balance: Decimal | None = None
+    credit_limit: Decimal | None = Field(default=None, alias="creditLimit")
+    upper_credit_limit: Decimal | None = Field(default=None, alias="upperCreditLimit")
+    reserved_amount: Decimal | None = Field(default=None, alias="reservedAmount")
+    available_balance: Decimal | None = Field(default=None, alias="availableBalance")
+    negative_since: str | None = Field(default=None, alias="negativeSince")
+    begin_date: str | None = Field(default=None, alias="beginDate")
+    end_date: str | None = Field(default=None, alias="endDate")
+    balance_at_begin: Decimal | None = Field(default=None, alias="balanceAtBegin")
+    balance_at_end: Decimal | None = Field(default=None, alias="balanceAtEnd")
+
+
+class Account(CyclosBaseModel):
+    """Cyclos account with owner and currency."""
+
+    id: str | None = None
+    type: EntityReference | None = None
+    user: UserReference | None = None
+    kind: str | None = None
+    currency: Currency | None = None
+    status: AccountStatus | None = None
+
+
+class AccountHistoryEntry(CyclosBaseModel):
+    """Single entry from an account history."""
+
+    id: str | None = None
+    date: str | None = None
+    amount: Decimal | None = None
+    description: str | None = None
+    transaction_number: str | None = Field(default=None, alias="transactionNumber")
+    related_account: AccountReference | None = Field(default=None, alias="relatedAccount")
+    related_name: str | None = Field(default=None, alias="relatedName")
+    statuses: dict[str, str] | None = None
+
+
+__all__ = ["Account", "AccountStatus", "AccountHistoryEntry", "AccountReference", "Currency"]

angstrom_cyclos/async_client.py

@@ -0,0 +1,74 @@
+"""Asynchronous Cyclos SDK client."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Self
+
+from angstrom_cyclos.accounts.client_async import AsyncAccountsClient
+from angstrom_cyclos.auth.client_async import AsyncAuthClient
+from angstrom_cyclos.config import CyclosConfig
+from angstrom_cyclos.members.client_async import AsyncMembersClient
+from angstrom_cyclos.operators.client_async import AsyncOperatorsClient
+from angstrom_cyclos.organizations.client_async import AsyncOrganizationsClient
+from angstrom_cyclos.permissions.client_async import AsyncPermissionsClient
+from angstrom_cyclos.transactions.client_async import AsyncTransactionsClient
+from angstrom_cyclos.transfers.client_async import AsyncTransfersClient
+from angstrom_cyclos.transport import AsyncHTTPTransport
+from angstrom_cyclos.users.client_async import AsyncUsersClient
+from angstrom_cyclos.webservices.client_async import AsyncWebServicesClient
+
+
+class AsyncCyclosClient:
+    """Asynchronous client for the Cyclos 4.16 REST API.
+
+    Example:
+        >>> import asyncio
+        >>> from angstrom_cyclos import AsyncCyclosClient, CyclosConfig
+        >>> config = CyclosConfig.from_env()
+        >>> async def main() -> None:
+        ...     async with AsyncCyclosClient(config) as client:
+        ...         await client.auth.login("username", "password")
+        ...         await client.members.get("alice")
+        >>> asyncio.run(main())
+    """
+
+    def __init__(self, config: CyclosConfig | None = None) -> None:
+        self._config = config or CyclosConfig.from_env()
+        self._transport = AsyncHTTPTransport(self._config)
+        self.auth = AsyncAuthClient(self)
+        self.members = AsyncMembersClient(self)
+        self.users = AsyncUsersClient(self)
+        self.organizations = AsyncOrganizationsClient(self)
+        self.operators = AsyncOperatorsClient(self)
+        self.permissions = AsyncPermissionsClient(self)
+        self.webservices = AsyncWebServicesClient(self)
+        self.accounts = AsyncAccountsClient(self)
+        self.transfers = AsyncTransfersClient(self)
+        self.transactions = AsyncTransactionsClient(self)
+
+    @property
+    def config(self) -> CyclosConfig:
+        return self._config
+
+    @property
+    def _transport(self) -> AsyncHTTPTransport:
+        return self.__transport
+
+    @_transport.setter
+    def _transport(self, value: AsyncHTTPTransport) -> None:
+        self.__transport = value
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._transport.close()

angstrom_cyclos/auth/__init__.py

@@ -0,0 +1,6 @@
+"""Authentication module."""
+
+from angstrom_cyclos.auth.client import AuthClient
+from angstrom_cyclos.auth.models import Auth, LoginAuth
+
+__all__ = ["AuthClient", "Auth", "LoginAuth"]

angstrom_cyclos/auth/client.py

@@ -0,0 +1,68 @@
+"""Authentication client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from angstrom_cyclos.auth.models import Auth, LoginAuth
+
+if TYPE_CHECKING:
+    from angstrom_cyclos.client import CyclosClient
+
+
+class AuthClient:
+    """Handles Cyclos login, logout, session refresh, and current user lookup."""
+
+    def __init__(self, client: CyclosClient) -> None:
+        self._client = client
+
+    def login(self, username: str, password: str) -> LoginAuth:
+        """Authenticate and store the returned session token.
+
+        Args:
+            username: Cyclos login name.
+            password: Cyclos password. Never logged.
+
+        Returns:
+            Parsed login response including ``session_token``.
+        """
+        response = self._client._transport.post(
+            "/auth/session",
+            auth=(username, password),
+        )
+        data = LoginAuth.model_validate(response.json())
+        if data.session_token:
+            self._client._transport.session_token = data.session_token
+        return data
+
+    def logout(self) -> None:
+        """Log out the current session and clear local authentication state."""
+        self._client._transport.delete("/auth/session")
+        self._client._transport.session_token = None
+        self._client._transport.access_client_token = None
+
+    def current_user(self) -> Auth:
+        """Return information about the currently authenticated user."""
+        response = self._client._transport.get("/auth")
+        return Auth.model_validate(response.json())
+
+    def is_authenticated(self) -> bool:
+        """Return ``True`` if a session token is currently stored."""
+        return self._client._transport.session_token is not None
+
+    def refresh(self) -> LoginAuth:
+        """Refresh the current session if supported.
+
+        Cyclos 4.16 does not expose a dedicated refresh endpoint. This method
+        re-authenticates using the credentials stored in the configuration
+        (if available). Prefer explicit ``login`` calls if credentials are not
+        configured.
+        """
+        config = self._client._config
+        if not config.username or not config.password:
+            raise RuntimeError("Cannot refresh session: no credentials configured")
+        return self.login(config.username, config.password.get_secret_value())
+
+    def set_session_token(self, token: str) -> None:
+        """Manually set the session token for subsequent requests."""
+        self._client._transport.session_token = token

angstrom_cyclos/auth/client_async.py

@@ -0,0 +1,48 @@
+"""Asynchronous authentication client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from angstrom_cyclos.auth.models import Auth, LoginAuth
+
+if TYPE_CHECKING:
+    from angstrom_cyclos.async_client import AsyncCyclosClient
+
+
+class AsyncAuthClient:
+    """Async authentication client."""
+
+    def __init__(self, client: AsyncCyclosClient) -> None:
+        self._client = client
+
+    async def login(self, username: str, password: str) -> LoginAuth:
+        response = await self._client._transport.post(
+            "/auth/session",
+            auth=(username, password),
+        )
+        data = LoginAuth.model_validate(response.json())
+        if data.session_token:
+            self._client._transport.session_token = data.session_token
+        return data
+
+    async def logout(self) -> None:
+        await self._client._transport.delete("/auth/session")
+        self._client._transport.session_token = None
+        self._client._transport.access_client_token = None
+
+    async def current_user(self) -> Auth:
+        response = await self._client._transport.get("/auth")
+        return Auth.model_validate(response.json())
+
+    async def is_authenticated(self) -> bool:
+        return self._client._transport.session_token is not None
+
+    async def refresh(self) -> LoginAuth:
+        config = self._client._config
+        if not config.username or not config.password:
+            raise RuntimeError("Cannot refresh session: no credentials configured")
+        return await self.login(config.username, config.password.get_secret_value())
+
+    async def set_session_token(self, token: str) -> None:
+        self._client._transport.session_token = token

angstrom_cyclos/auth/models.py

@@ -0,0 +1,27 @@
+"""Authentication-related Pydantic models."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from angstrom_cyclos.models import CyclosBaseModel, EntityReference, UserReference
+
+
+class LoginAuth(CyclosBaseModel):
+    """Response from ``POST /auth/session``."""
+
+    user: UserReference | None = None
+    session_token: str | None = Field(default=None, alias="sessionToken")
+    principal: str | None = None
+    expired_password: bool | None = Field(default=None, alias="expiredPassword")
+    pending_agreements: bool | None = Field(default=None, alias="pendingAgreements")
+
+
+class Auth(CyclosBaseModel):
+    """Response from ``GET /auth``."""
+
+    user: UserReference | None = None
+    principal: str | None = None
+    access_client: EntityReference | None = Field(default=None, alias="accessClient")
+    expired_password: bool | None = Field(default=None, alias="expiredPassword")
+    pending_agreements: bool | None = Field(default=None, alias="pendingAgreements")