RemitSandbox

"""
RemitSandbox adapter — starter template.

Your task: implement every method marked TODO so that test_adapter.py passes.

    python test_adapter.py --skip-wait   # fast feedback loop
    python test_adapter.py               # full run including settlement (~65 s)

Read the API documentation at https://remit.palashonanton.in before you start.
Pay close attention to the request field names and response shapes.

Dependencies:
    pip install requests
"""

import time
from typing import Optional

import requests  # https://requests.readthedocs.io


BASE_URL = "https://remit.palashonanton.in"


class RemitSandboxError(Exception):
    """
    Raised whenever the RemitSandbox API returns a non-2xx response.

    Attributes:
        status_code  HTTP status code (e.g. 404, 422)
        code         Machine-readable error identifier from the response body
        message      Human-readable explanation from the response body
        field        The request field that caused the error, if any (may be None)

    Example error response body:
        {
          "error": {
            "code":    "not_found",
            "message": "Customer 'cus_abc123' not found.",
            "field":   "customer_id"
          }
        }
    """

    def __init__(
        self,
        status_code: int,
        code: str,
        message: str,
        field: Optional[str] = None,
    ):
        self.status_code = status_code
        self.code = code
        self.message = message
        self.field = field
        detail = f" (field: {field})" if field else ""
        super().__init__(f"HTTP {status_code} [{code}] {message}{detail}")


class RemitSandboxAdapter:
    """
    Adapter for the RemitSandbox API.

    All methods raise RemitSandboxError on API errors; let the caller decide
    whether to retry or surface the error.

    Usage:
        adapter = RemitSandboxAdapter()
        customer    = adapter.create_customer("Alice", "Sharma", "alice@example.com", "+12025550182")
        beneficiary = adapter.create_beneficiary(customer["id"], "Ramesh", "9876543210", "HDFC0001234", "HDFC Bank")
        transfer    = adapter.create_transfer(customer["id"], beneficiary["id"], 250.0)
        result      = adapter.poll_transfer(transfer["id"])
        print(result["status"])   # "SUCCESS" or "FAILED"
    """

    def __init__(self, base_url: str = BASE_URL):
        self.base_url = base_url.rstrip("/")
        # TODO: create a requests.Session and configure default headers.
        #       All requests and responses use JSON; set Content-Type accordingly.
        raise NotImplementedError("TODO: initialise the HTTP session")

    # ── Internal helper ───────────────────────────────────────────────────────

    def _request(self, method: str, path: str, **kwargs) -> dict:
        """
        Send an HTTP request to `self.base_url + path`.
        Return the parsed JSON body on success (2xx).
        Raise RemitSandboxError on any non-2xx response.

        The error envelope is always:
            {"error": {"code": "...", "message": "...", "field": "..."}}
        where "field" may be absent.
        """
        # TODO: make the request, parse the response, raise on errors
        raise NotImplementedError("TODO: implement _request")

    # ── Customers ─────────────────────────────────────────────────────────────

    def create_customer(
        self,
        first_name: str,
        last_name: str,
        email: str,
        phone: str,
        country: str = "US",
    ) -> dict:
        """
        Create a new customer. Returns the created customer dict.

        The response includes at minimum: id, first_name, last_name, email,
        phone, country, created_at.

        Raises RemitSandboxError on validation failure (e.g. unsupported country,
        invalid email or phone format).
        """
        # TODO: POST /customers
        raise NotImplementedError("TODO: implement create_customer")

    def get_customer(self, customer_id: str) -> dict:
        """
        Retrieve a customer by ID.

        Raises RemitSandboxError(code="not_found") if the ID does not exist.
        """
        # TODO: GET /customers/{customer_id}
        raise NotImplementedError("TODO: implement get_customer")

    # ── Beneficiaries ─────────────────────────────────────────────────────────

    def create_beneficiary(
        self,
        customer_id: str,
        name: str,
        account_number: str,
        ifsc: str,
        bank_name: str,
    ) -> dict:
        """
        Add a beneficiary linked to the given customer.
        Returns the created beneficiary dict.

        Raises RemitSandboxError on validation failure (e.g. IFSC wrong length,
        customer not found).

        Hint: read the API docs carefully — one of the request field names
        may not match the parameter name in this method signature.
        """
        # TODO: POST /beneficiaries
        raise NotImplementedError("TODO: implement create_beneficiary")

    def get_beneficiary(self, beneficiary_id: str) -> dict:
        """
        Retrieve a beneficiary by ID.

        Raises RemitSandboxError(code="not_found") if the ID does not exist.
        """
        # TODO: GET /beneficiaries/{beneficiary_id}
        raise NotImplementedError("TODO: implement get_beneficiary")

    # ── Transfers ─────────────────────────────────────────────────────────────

    def create_transfer(
        self,
        customer_id: str,
        beneficiary_id: str,
        amount: float,
        currency: str = "USD",
        reference: Optional[str] = None,
    ) -> dict:
        """
        Initiate a transfer. Returns the transfer dict with status "PROCESSING".

        The response includes: id, status, customer_id, beneficiary_id, amount,
        currency, reference, fx_rate, payout_amount_inr, created_at.

        Raises RemitSandboxError on validation failure (e.g. amount out of range,
        currency not supported, beneficiary ownership mismatch).

        Hint: check the API docs for the exact field names in the request body —
        one of them may differ from the parameter name in this signature.
        If reference is None, generate a unique string of your choice.
        """
        # TODO: POST /transfers
        raise NotImplementedError("TODO: implement create_transfer")

    def get_transfer(self, transfer_id: str) -> dict:
        """
        Retrieve the current state of a transfer.

        The "status" field will be one of:
          "PROCESSING"  — not yet settled, keep polling
          "SUCCESS"     — funds delivered successfully
          "FAILED"      — failed; check the "failure_reason" field

        Note: the docs may show a different value for the success status —
        trust what the API actually returns.

        Raises RemitSandboxError(code="not_found") if the ID does not exist.
        """
        # TODO: GET /transfers/{transfer_id}
        raise NotImplementedError("TODO: implement get_transfer")

    def poll_transfer(
        self,
        transfer_id: str,
        max_wait: int = 120,
        interval: int = 5,
    ) -> dict:
        """
        Poll GET /transfers/{id} every `interval` seconds until the status
        is no longer "PROCESSING", then return the final transfer dict.

        Raises TimeoutError if the transfer has not settled within `max_wait` seconds.

        Hint:
            deadline = time.time() + max_wait
            while time.time() < deadline:
                ...
                time.sleep(interval)
            raise TimeoutError(...)
        """
        # TODO: implement the polling loop using get_transfer()
        raise NotImplementedError("TODO: implement poll_transfer")