nomba-python 0.1.0__py3-none-any.whl

nomba_python/resources/transfers.py

@@ -0,0 +1,298 @@
+# This file is auto-generated from Nomba's OpenAPI spec. Do not edit by hand;
+# regenerate via scripts/generate_resources.py instead.
+from __future__ import annotations
+
+
+from ..http import AsyncNombaClient, NombaClient
+from ..validation import validate_body
+from .. import models as _models
+
+
+class Transfers:
+    """Sync resource methods for the Transfers group."""
+
+    def __init__(self, client: NombaClient) -> None:
+        self._client = client
+
+    def fetch_bank_codes_and_names(self, **extra: object) -> _models.FetchBankCodesAndNamesResponse:
+        """
+        Fetch bank codes and names
+
+        You can use this endpoint to fetch all banks, their names and codes.
+        """
+        path = "/v1/transfers/banks"
+        params = None
+        return self._client.get(path, params=params)  # type: ignore[return-value]
+
+    def perform_bank_account_lookup(self, account_number, bank_code, **extra: object) -> _models.PerformBankAccountLookupResponse:
+        """
+        Perform bank account lookup
+
+        You can use this endpoint to perform bank account lookup.
+
+        Body fields:
+            accountNumber (required): The account number to be looked up.
+            bankCode (required): The bankCode of the bank the account number belongs to. This can be obtained from a call to `/v1/transfers/bank` 
+        """
+        path = "/v1/transfers/bank/lookup"
+        params = None
+        body: dict[str, object] = {}
+        body["accountNumber"] = account_number
+        body["bankCode"] = bank_code
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank/lookup", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def perform_bank_account_transfer_the_parent_account(self, amount, account_number, account_name, bank_code, merchant_tx_ref, sender_name, *, narration: object | None = None, **extra: object) -> _models.PerformBankAccountTransferTheParentAccountResponse:
+        """
+        Perform bank account transfer from the parent account
+
+        You can use this endpoint to perform bank account transfer.
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            accountNumber (required): The destination bank account number.
+            accountName (required): The name on the account.
+            bankCode (required): The code of the recipient bank.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            senderName (required): Sender name
+            narration: The payment narration
+        """
+        path = "/v1/transfers/bank"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["accountNumber"] = account_number
+        body["accountName"] = account_name
+        body["bankCode"] = bank_code
+        body["merchantTxRef"] = merchant_tx_ref
+        body["senderName"] = sender_name
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def perform_bank_account_transfer_from_account(self, sub_account_id: str, amount, account_number, account_name, bank_code, merchant_tx_ref, sender_name, *, narration: object | None = None, **extra: object) -> _models.PerformBankAccountTransferFromAccountResponse:
+        """
+        Perform bank account transfer from a sub account
+
+        You can use this endpoint to perform bank account transfer using a sub account
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            accountNumber (required): The destination bank account number.
+            accountName (required): The name on the account.
+            bankCode (required): The code of the recipient bank.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            senderName (required): Sender name
+            narration: The payment narration
+        """
+        path = f"/v1/transfers/bank/{sub_account_id}"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["accountNumber"] = account_number
+        body["accountName"] = account_name
+        body["bankCode"] = bank_code
+        body["merchantTxRef"] = merchant_tx_ref
+        body["senderName"] = sender_name
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank/{subAccountId}", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def perform_wallet_transfer_from_the_parent_account(self, amount, receiver_account_id, merchant_tx_ref, *, narration: object | None = None, **extra: object) -> _models.PerformWalletTransferFromTheParentAccountResponse:
+        """
+        Perform wallet transfer from the parent account
+
+        You can use this endpoint to perform a wallet transfer.
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            receiverAccountId (required): The receiver's accountId.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            narration: The payment narration
+        """
+        path = "/v1/transfers/wallet"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["receiverAccountId"] = receiver_account_id
+        body["merchantTxRef"] = merchant_tx_ref
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/wallet", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def perform_wallet_transfer_from_a_sub_account(self, sub_account_id: str, amount, receiver_account_id, merchant_tx_ref, *, narration: object | None = None, **extra: object) -> _models.PerformWalletTransferFromASubAccountResponse:
+        """
+        Perform wallet transfer from a sub account
+
+        You can use this endpoint to perform a wallet transfer from a sub account
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            receiverAccountId (required): The receiver's accountId.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            narration: The payment narration
+        """
+        path = f"/v1/transfers/wallet/{sub_account_id}"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["receiverAccountId"] = receiver_account_id
+        body["merchantTxRef"] = merchant_tx_ref
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/wallet/{subAccountId}", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+
+
+class AsyncTransfers:
+    """Async resource methods for the Transfers group."""
+
+    def __init__(self, client: AsyncNombaClient) -> None:
+        self._client = client
+
+    async def fetch_bank_codes_and_names(self, **extra: object) -> _models.FetchBankCodesAndNamesResponse:
+        """
+        Fetch bank codes and names
+
+        You can use this endpoint to fetch all banks, their names and codes.
+        """
+        path = "/v1/transfers/banks"
+        params = None
+        return await self._client.get(path, params=params)  # type: ignore[return-value]
+
+    async def perform_bank_account_lookup(self, account_number, bank_code, **extra: object) -> _models.PerformBankAccountLookupResponse:
+        """
+        Perform bank account lookup
+
+        You can use this endpoint to perform bank account lookup.
+
+        Body fields:
+            accountNumber (required): The account number to be looked up.
+            bankCode (required): The bankCode of the bank the account number belongs to. This can be obtained from a call to `/v1/transfers/bank` 
+        """
+        path = "/v1/transfers/bank/lookup"
+        params = None
+        body: dict[str, object] = {}
+        body["accountNumber"] = account_number
+        body["bankCode"] = bank_code
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank/lookup", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def perform_bank_account_transfer_the_parent_account(self, amount, account_number, account_name, bank_code, merchant_tx_ref, sender_name, *, narration: object | None = None, **extra: object) -> _models.PerformBankAccountTransferTheParentAccountResponse:
+        """
+        Perform bank account transfer from the parent account
+
+        You can use this endpoint to perform bank account transfer.
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            accountNumber (required): The destination bank account number.
+            accountName (required): The name on the account.
+            bankCode (required): The code of the recipient bank.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            senderName (required): Sender name
+            narration: The payment narration
+        """
+        path = "/v1/transfers/bank"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["accountNumber"] = account_number
+        body["accountName"] = account_name
+        body["bankCode"] = bank_code
+        body["merchantTxRef"] = merchant_tx_ref
+        body["senderName"] = sender_name
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def perform_bank_account_transfer_from_account(self, sub_account_id: str, amount, account_number, account_name, bank_code, merchant_tx_ref, sender_name, *, narration: object | None = None, **extra: object) -> _models.PerformBankAccountTransferFromAccountResponse:
+        """
+        Perform bank account transfer from a sub account
+
+        You can use this endpoint to perform bank account transfer using a sub account
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            accountNumber (required): The destination bank account number.
+            accountName (required): The name on the account.
+            bankCode (required): The code of the recipient bank.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            senderName (required): Sender name
+            narration: The payment narration
+        """
+        path = f"/v1/transfers/bank/{sub_account_id}"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["accountNumber"] = account_number
+        body["accountName"] = account_name
+        body["bankCode"] = bank_code
+        body["merchantTxRef"] = merchant_tx_ref
+        body["senderName"] = sender_name
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/bank/{subAccountId}", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def perform_wallet_transfer_from_the_parent_account(self, amount, receiver_account_id, merchant_tx_ref, *, narration: object | None = None, **extra: object) -> _models.PerformWalletTransferFromTheParentAccountResponse:
+        """
+        Perform wallet transfer from the parent account
+
+        You can use this endpoint to perform a wallet transfer.
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            receiverAccountId (required): The receiver's accountId.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            narration: The payment narration
+        """
+        path = "/v1/transfers/wallet"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["receiverAccountId"] = receiver_account_id
+        body["merchantTxRef"] = merchant_tx_ref
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/wallet", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def perform_wallet_transfer_from_a_sub_account(self, sub_account_id: str, amount, receiver_account_id, merchant_tx_ref, *, narration: object | None = None, **extra: object) -> _models.PerformWalletTransferFromASubAccountResponse:
+        """
+        Perform wallet transfer from a sub account
+
+        You can use this endpoint to perform a wallet transfer from a sub account
+
+        Body fields:
+            amount (required): The amount to be transferred.
+            receiverAccountId (required): The receiver's accountId.
+            merchantTxRef (required): Unique reference used to track a transaction from an external process.
+            narration: The payment narration
+        """
+        path = f"/v1/transfers/wallet/{sub_account_id}"
+        params = None
+        body: dict[str, object] = {}
+        body["amount"] = amount
+        body["receiverAccountId"] = receiver_account_id
+        body["merchantTxRef"] = merchant_tx_ref
+        if narration is not None:
+            body["narration"] = narration
+        body.update(extra)
+        validate_body("post", "/v1/transfers/wallet/{subAccountId}", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+

nomba_python/resources/virtual_accounts.py

@@ -0,0 +1,230 @@
+# This file is auto-generated from Nomba's OpenAPI spec. Do not edit by hand;
+# regenerate via scripts/generate_resources.py instead.
+from __future__ import annotations
+
+
+from ..http import AsyncNombaClient, NombaClient
+from ..validation import validate_body
+from .. import models as _models
+
+
+class VirtualAccounts:
+    """Sync resource methods for the VirtualAccounts group."""
+
+    def __init__(self, client: NombaClient) -> None:
+        self._client = client
+
+    def create_virtual_account(self, account_ref, account_name, **extra: object) -> _models.CreateVirtualAccountResponse:
+        """
+        Create virtual account
+
+        You can use this endpoint to create a virtual account to receive payments.
+
+        Body fields:
+            accountRef (required): Account reference
+            accountName (required): Account holder's name
+        """
+        path = "/v1/accounts/virtual"
+        params = None
+        body: dict[str, object] = {}
+        body["accountRef"] = account_ref
+        body["accountName"] = account_name
+        body.update(extra)
+        validate_body("post", "/v1/accounts/virtual", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def filter_virtual_accounts(self, *, limit: str | None = None, cursor: str | None = None, account_name: object | None = None, account_ref: object | None = None, bvn: object | None = None, bank_account_number: object | None = None, date_created_from: object | None = None, date_created_to: object | None = None, expired: object | None = None, resource_acquired: object | None = None, **extra: object) -> _models.FilterVirtualAccountsResponse:
+        """
+        Filter virtual accounts
+
+        You can use this endpoint to filter your virtual accounts.
+
+        Body fields:
+            accountName: Account holder's name
+            accountRef: Account reference
+            bvn: Bank Verification Number (BVN)
+            bankAccountNumber: Bank account number
+            dateCreatedFrom: Date created from
+            dateCreatedTo: Date created to
+            expired: Whether the virtual account is expired or not
+            resourceAcquired: Whether the virtual account is in use or not
+        """
+        path = "/v1/accounts/virtual/list"
+        params: dict[str, object] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        body: dict[str, object] = {}
+        if account_name is not None:
+            body["accountName"] = account_name
+        if account_ref is not None:
+            body["accountRef"] = account_ref
+        if bvn is not None:
+            body["bvn"] = bvn
+        if bank_account_number is not None:
+            body["bankAccountNumber"] = bank_account_number
+        if date_created_from is not None:
+            body["dateCreatedFrom"] = date_created_from
+        if date_created_to is not None:
+            body["dateCreatedTo"] = date_created_to
+        if expired is not None:
+            body["expired"] = expired
+        if resource_acquired is not None:
+            body["resourceAcquired"] = resource_acquired
+        body.update(extra)
+        validate_body("post", "/v1/accounts/virtual/list", body)
+        return self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    def update_a_virtual_account(self, account_ref: str, *, account_name: object | None = None, callback_url: object | None = None, **extra: object) -> _models.UpdateAVirtualAccountResponse:
+        """
+        Update a virtual account
+
+        You can use this endpoint to update a virtual account.
+
+        Body fields:
+            accountName: Account holder's name
+            callbackUrl: Callback url
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        body: dict[str, object] = {}
+        if account_name is not None:
+            body["accountName"] = account_name
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        body.update(extra)
+        validate_body("put", "/v1/accounts/virtual/{accountRef}", body)
+        return self._client.put(path, json=body, params=params)  # type: ignore[return-value]
+
+    def fetch_a_virtual_account(self, account_ref: str, **extra: object) -> _models.FetchAVirtualAccountResponse:
+        """
+        Fetch a virtual account
+
+        You can use this endpoint to fetch a virtual account.
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        return self._client.get(path, params=params)  # type: ignore[return-value]
+
+    def expire_a_virtual_account(self, account_ref: str, **extra: object) -> _models.ExpireAVirtualAccountResponse:
+        """
+        Expire a virtual account
+
+        You can use this endpoint to expire a virtual account.
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        return self._client.delete(path, params=params)  # type: ignore[return-value]
+
+
+
+class AsyncVirtualAccounts:
+    """Async resource methods for the VirtualAccounts group."""
+
+    def __init__(self, client: AsyncNombaClient) -> None:
+        self._client = client
+
+    async def create_virtual_account(self, account_ref, account_name, **extra: object) -> _models.CreateVirtualAccountResponse:
+        """
+        Create virtual account
+
+        You can use this endpoint to create a virtual account to receive payments.
+
+        Body fields:
+            accountRef (required): Account reference
+            accountName (required): Account holder's name
+        """
+        path = "/v1/accounts/virtual"
+        params = None
+        body: dict[str, object] = {}
+        body["accountRef"] = account_ref
+        body["accountName"] = account_name
+        body.update(extra)
+        validate_body("post", "/v1/accounts/virtual", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def filter_virtual_accounts(self, *, limit: str | None = None, cursor: str | None = None, account_name: object | None = None, account_ref: object | None = None, bvn: object | None = None, bank_account_number: object | None = None, date_created_from: object | None = None, date_created_to: object | None = None, expired: object | None = None, resource_acquired: object | None = None, **extra: object) -> _models.FilterVirtualAccountsResponse:
+        """
+        Filter virtual accounts
+
+        You can use this endpoint to filter your virtual accounts.
+
+        Body fields:
+            accountName: Account holder's name
+            accountRef: Account reference
+            bvn: Bank Verification Number (BVN)
+            bankAccountNumber: Bank account number
+            dateCreatedFrom: Date created from
+            dateCreatedTo: Date created to
+            expired: Whether the virtual account is expired or not
+            resourceAcquired: Whether the virtual account is in use or not
+        """
+        path = "/v1/accounts/virtual/list"
+        params: dict[str, object] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        body: dict[str, object] = {}
+        if account_name is not None:
+            body["accountName"] = account_name
+        if account_ref is not None:
+            body["accountRef"] = account_ref
+        if bvn is not None:
+            body["bvn"] = bvn
+        if bank_account_number is not None:
+            body["bankAccountNumber"] = bank_account_number
+        if date_created_from is not None:
+            body["dateCreatedFrom"] = date_created_from
+        if date_created_to is not None:
+            body["dateCreatedTo"] = date_created_to
+        if expired is not None:
+            body["expired"] = expired
+        if resource_acquired is not None:
+            body["resourceAcquired"] = resource_acquired
+        body.update(extra)
+        validate_body("post", "/v1/accounts/virtual/list", body)
+        return await self._client.post(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def update_a_virtual_account(self, account_ref: str, *, account_name: object | None = None, callback_url: object | None = None, **extra: object) -> _models.UpdateAVirtualAccountResponse:
+        """
+        Update a virtual account
+
+        You can use this endpoint to update a virtual account.
+
+        Body fields:
+            accountName: Account holder's name
+            callbackUrl: Callback url
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        body: dict[str, object] = {}
+        if account_name is not None:
+            body["accountName"] = account_name
+        if callback_url is not None:
+            body["callbackUrl"] = callback_url
+        body.update(extra)
+        validate_body("put", "/v1/accounts/virtual/{accountRef}", body)
+        return await self._client.put(path, json=body, params=params)  # type: ignore[return-value]
+
+    async def fetch_a_virtual_account(self, account_ref: str, **extra: object) -> _models.FetchAVirtualAccountResponse:
+        """
+        Fetch a virtual account
+
+        You can use this endpoint to fetch a virtual account.
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        return await self._client.get(path, params=params)  # type: ignore[return-value]
+
+    async def expire_a_virtual_account(self, account_ref: str, **extra: object) -> _models.ExpireAVirtualAccountResponse:
+        """
+        Expire a virtual account
+
+        You can use this endpoint to expire a virtual account.
+        """
+        path = f"/v1/accounts/virtual/{account_ref}"
+        params = None
+        return await self._client.delete(path, params=params)  # type: ignore[return-value]
+

nomba_python/validation.py

@@ -0,0 +1,97 @@
+"""
+Lightweight, dependency-free validation of request bodies against Nomba's
+own OpenAPI spec — specifically nested required fields that a flat method
+signature can't enforce (e.g. `order={...}` in checkout order creation).
+
+This only checks presence of required keys recursively (and a coarse
+type check for "object"/"array"), not full JSON-Schema validation. It's a
+local fast-fail before any network call, not a replacement for Nomba's own
+server-side validation.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+from .exceptions import NombaValidationError
+
+
+@lru_cache(maxsize=1)
+def _load_spec() -> dict[str, Any]:
+    with resources.files("nomba.data").joinpath("nomba_openapi.json").open(
+        "r", encoding="utf-8"
+    ) as f:
+        return json.load(f)
+
+
+def _resolve(spec: dict[str, Any], schema: Any) -> Any:
+    if not isinstance(schema, dict):
+        return schema
+    if "$ref" in schema:
+        name = schema["$ref"].split("/")[-1]
+        return spec["components"]["schemas"].get(name, {})
+    return schema
+
+
+@lru_cache(maxsize=None)
+def _request_schema_key(verb: str, path_template: str) -> Any:
+    spec = _load_spec()
+    op = spec.get("paths", {}).get(path_template, {}).get(verb.lower())
+    if not op:
+        return None
+    rb = op.get("requestBody")
+    if not rb:
+        return None
+    schema = rb.get("content", {}).get("application/json", {}).get("schema")
+    return _resolve(spec, schema)
+
+
+def _check(spec: dict[str, Any], schema: Any, value: Any, path: str, missing: list[str]) -> None:
+    schema = _resolve(spec, schema)
+    if not isinstance(schema, dict):
+        return
+    schema_type = schema.get("type")
+
+    if schema_type == "object" or "properties" in schema:
+        if not isinstance(value, dict):
+            if value is not None:
+                missing.append(f"{path} (expected an object)")
+            return
+        for required_name in schema.get("required", []):
+            if required_name not in value or value[required_name] is None:
+                missing.append(f"{path}.{required_name}" if path else required_name)
+        props = schema.get("properties", {})
+        for key, sub_value in value.items():
+            if key in props:
+                _check(spec, props[key], sub_value, f"{path}.{key}" if path else key, missing)
+
+    elif schema_type == "array":
+        if not isinstance(value, list):
+            return
+        items_schema = schema.get("items")
+        if items_schema:
+            for i, item in enumerate(value):
+                _check(spec, items_schema, item, f"{path}[{i}]", missing)
+
+
+def validate_body(verb: str, path_template: str, body: dict[str, Any]) -> None:
+    """
+    Validate `body` against the requestBody schema for `verb`/`path_template`
+    in Nomba's OpenAPI spec, recursively checking required fields on nested
+    objects/arrays. Raises NombaValidationError listing every missing field
+    if any are absent. No-ops if the spec has no requestBody for this
+    operation, or no nested object/array fields to check.
+    """
+    schema = _request_schema_key(verb, path_template)
+    if schema is None:
+        return
+    spec = _load_spec()
+    missing: list[str] = []
+    _check(spec, schema, body, "", missing)
+    if missing:
+        raise NombaValidationError(
+            f"Missing required field(s) in request body: {', '.join(missing)}",
+            missing=missing,
+        )