rayacash 1.0.0__py3-none-any.whl

rayacash/__init__.py

@@ -0,0 +1,126 @@
+"""El SDK oficial de Python para la API de Raya Cash.
+
+Estilo cliente (el recomendado)::
+
+    import rayacash
+
+    client = rayacash.RayaClient()  # lee la clave secreta de RAYA_SECRET_KEY
+    payment = client.payments.create(amount=15000, description="Pedido #1042")
+
+Estilo global, como stripe-python::
+
+    rayacash.api_key = os.environ["RAYA_SECRET_KEY"]
+    payment = rayacash.Payment.create(amount=15000)
+
+Referencia de la API: https://raya.cash/api
+"""
+
+from __future__ import annotations
+
+import httpx
+from typing_extensions import Literal
+
+from rayacash._requestor import DEFAULT_API_BASE, DEFAULT_MAX_NETWORK_RETRIES, DEFAULT_TIMEOUT
+from rayacash._util import AppInfo, validate_app_info
+from rayacash._version import VERSION
+
+__version__ = VERSION
+
+# --- Configuración del estilo global -------------------------------------------------------
+# Solo la usan rayacash.Balance / Transfer / Payment. Un RayaClient tiene la suya.
+
+#: Tu clave secreta. Si es None, se lee de la variable de entorno RAYA_SECRET_KEY.
+api_key: str | None = None
+api_base: str = DEFAULT_API_BASE
+max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES
+#: Segundos por intento o un httpx.Timeout.
+timeout: float | httpx.Timeout = DEFAULT_TIMEOUT
+#: Clientes httpx propios para el estilo global (proxies, certificados…). No los cerramos.
+http_client: httpx.Client | None = None
+async_http_client: httpx.AsyncClient | None = None
+app_info: AppInfo | None = None
+#: "info" o "debug" para ver las requests en stderr (también con RAYA_LOG).
+log: Literal["debug", "info"] | None = None
+
+
+def set_app_info(name: str, *, version: str | None = None, url: str | None = None) -> None:
+    """Identifica tu plugin en el User-Agent del estilo global (lo ves en Developers › Logs)."""
+    global app_info
+    info: AppInfo = {"name": name}
+    if version is not None:
+        info["version"] = version
+    if url is not None:
+        info["url"] = url
+    app_info = validate_app_info(info)
+
+
+from rayacash._balance import Balance  # noqa: E402
+from rayacash._client import RayaClient  # noqa: E402
+from rayacash._encoding import Amount  # noqa: E402
+from rayacash._error import (  # noqa: E402
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    IdempotencyError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RayaError,
+    SignatureVerificationError,
+    UnprocessableEntityError,
+)
+from rayacash._event import Event, EventType  # noqa: E402
+from rayacash._list_object import AnyIterator, ListObject  # noqa: E402
+from rayacash._payment import Payment, PaymentStatus  # noqa: E402
+from rayacash._raya_object import RayaObject  # noqa: E402
+from rayacash._request_options import RequestOptions  # noqa: E402
+from rayacash._response import RayaResponse  # noqa: E402
+from rayacash._transfer import Transfer, TransferDirection, TransferStatus  # noqa: E402
+from rayacash._webhook import Webhook, WebhookSignature  # noqa: E402
+
+__all__ = [
+    "DEFAULT_API_BASE",
+    "VERSION",
+    "APIConnectionError",
+    "APIError",
+    "Amount",
+    "AnyIterator",
+    "AppInfo",
+    "AuthenticationError",
+    "Balance",
+    "ConflictError",
+    "Event",
+    "EventType",
+    "IdempotencyError",
+    "InvalidRequestError",
+    "ListObject",
+    "NotFoundError",
+    "Payment",
+    "PaymentStatus",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RayaClient",
+    "RayaError",
+    "RayaObject",
+    "RayaResponse",
+    "RequestOptions",
+    "SignatureVerificationError",
+    "Transfer",
+    "TransferDirection",
+    "TransferStatus",
+    "UnprocessableEntityError",
+    "Webhook",
+    "WebhookSignature",
+    "__version__",
+    "api_base",
+    "api_key",
+    "app_info",
+    "async_http_client",
+    "http_client",
+    "log",
+    "max_network_retries",
+    "set_app_info",
+    "timeout",
+]

rayacash/_balance.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing_extensions import Literal
+
+from rayacash._raya_object import RayaObject
+from rayacash._request_options import RequestOptions
+
+
+class Balance(RayaObject):
+    """Tu saldo disponible, en pesos.
+
+    Ya tiene descontadas las transferencias que enviaste, aunque sigan ``pending``.
+    """
+
+    OBJECT_NAME = "balance"
+
+    object: Literal["balance"]
+    #: Saldo disponible en pesos (puede ser negativo).
+    available: float
+    #: Siempre ``"ARS"``.
+    currency: str
+
+    @classmethod
+    def retrieve(cls, *, options: RequestOptions | None = None) -> Balance:
+        """Estilo global: ``rayacash.Balance.retrieve()``. Ver ``client.balance.retrieve()``."""
+        from rayacash._balance_service import BalanceService
+        from rayacash._global import default_requestor
+
+        return BalanceService(default_requestor()).retrieve(options=options)
+
+    @classmethod
+    async def retrieve_async(cls, *, options: RequestOptions | None = None) -> Balance:
+        from rayacash._balance_service import BalanceService
+        from rayacash._global import default_requestor
+
+        return await BalanceService(default_requestor()).retrieve_async(options=options)

rayacash/_balance_service.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from rayacash._balance import Balance
+from rayacash._request_options import RequestOptions
+
+if TYPE_CHECKING:
+    from rayacash._requestor import APIRequestor
+
+
+class BalanceService:
+    """``client.balance``: tu saldo disponible."""
+
+    def __init__(self, requestor: APIRequestor) -> None:
+        self._requestor = requestor
+
+    def retrieve(self, *, options: RequestOptions | None = None) -> Balance:
+        """Tu saldo disponible en pesos (``GET /v1/balance``)."""
+        return cast(
+            Balance,
+            self._requestor.request("GET", "/v1/balance", options=options, expected=Balance),
+        )
+
+    async def retrieve_async(self, *, options: RequestOptions | None = None) -> Balance:
+        """Como ``retrieve()``, para asyncio."""
+        return cast(
+            Balance,
+            await self._requestor.request_async(
+                "GET", "/v1/balance", options=options, expected=Balance
+            ),
+        )

rayacash/_client.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+from typing_extensions import Self
+
+from rayacash._balance_service import BalanceService
+from rayacash._encoding import encode_query
+from rayacash._event import Event
+from rayacash._list_object import ListObject
+from rayacash._payment_service import PaymentService
+from rayacash._raya_object import RayaObject
+from rayacash._request_options import RequestOptions, validate_options
+from rayacash._requestor import (
+    DEFAULT_API_BASE,
+    DEFAULT_MAX_NETWORK_RETRIES,
+    DEFAULT_TIMEOUT,
+    APIRequestor,
+    HTTPClientManager,
+    RequestorConfig,
+    check_api_key,
+    normalize_api_base,
+    to_timeout,
+    validate_max_network_retries,
+)
+from rayacash._transfer_service import TransferService
+from rayacash._util import AppInfo, mask_key, user_agent, validate_app_info
+from rayacash._webhook import DEFAULT_TOLERANCE, Payload, construct_event
+
+
+class _ClientConfig(RequestorConfig):
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        api_base: str,
+        timeout: httpx.Timeout,
+        max_network_retries: int,
+        user_agent: str,
+        http: HTTPClientManager,
+    ) -> None:
+        self._api_key = api_key
+        self._api_base = api_base
+        self._timeout = timeout
+        self._max_network_retries = max_network_retries
+        self._user_agent = user_agent
+        self._http = http
+
+    def api_key(self) -> str | None:
+        return self._api_key
+
+    def api_base(self) -> str:
+        return self._api_base
+
+    def timeout(self) -> httpx.Timeout:
+        return self._timeout
+
+    def max_network_retries(self) -> int:
+        return self._max_network_retries
+
+    def user_agent(self) -> str:
+        return self._user_agent
+
+    def http(self) -> HTTPClientManager:
+        return self._http
+
+
+class RayaClient:
+    """Cliente de la API de Raya Cash.
+
+    >>> client = rayacash.RayaClient()  # lee la clave de RAYA_SECRET_KEY
+    >>> client.balance.retrieve().available
+
+    La clave secreta va solo en tu servidor, leída de una variable de entorno: nunca en el
+    navegador, en una app mobile ni en el repositorio.
+
+    :param api_key: Tu clave secreta (``raya_sk_live_…``). Si no la pasás, se lee de la variable
+        de entorno ``RAYA_SECRET_KEY``.
+    :param api_base: Por defecto ``https://api.raya.cash``.
+    :param timeout: Segundos por intento (por defecto 65, con 10 para conectar) o un
+        ``httpx.Timeout``. El servidor corta a los 60 s y crear un pago puede tardar ~40 s.
+    :param max_network_retries: Reintentos ante cortes, 5xx, 429 e
+        ``IDEMPOTENCY_KEY_IN_USE`` (por defecto 2). Los POST reintentan con la misma
+        Idempotency-Key, así que nunca se ejecutan dos veces.
+    :param http_client: Un ``httpx.Client`` propio (proxies, certificados…). No lo cerramos.
+    :param async_http_client: Lo mismo, para los métodos ``*_async``.
+    :param app_info: ``{"name", "version", "url"}`` de tu plugin, para el User-Agent.
+    """
+
+    balance: BalanceService
+    transfers: TransferService
+    payments: PaymentService
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        api_base: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        max_network_retries: int | None = None,
+        http_client: httpx.Client | None = None,
+        async_http_client: httpx.AsyncClient | None = None,
+        app_info: AppInfo | None = None,
+    ) -> None:
+        if api_key is None:
+            api_key = os.environ.get("RAYA_SECRET_KEY") or None
+        if api_key is not None:
+            api_key = check_api_key(api_key)
+        if http_client is not None and not isinstance(http_client, httpx.Client):
+            raise TypeError("http_client tiene que ser un httpx.Client.")
+        if async_http_client is not None and not isinstance(async_http_client, httpx.AsyncClient):
+            raise TypeError("async_http_client tiene que ser un httpx.AsyncClient.")
+
+        self._config = _ClientConfig(
+            api_key=api_key,
+            api_base=normalize_api_base(api_base if api_base is not None else DEFAULT_API_BASE),
+            timeout=to_timeout(timeout) if timeout is not None else DEFAULT_TIMEOUT,
+            max_network_retries=(
+                validate_max_network_retries(max_network_retries)
+                if max_network_retries is not None
+                else DEFAULT_MAX_NETWORK_RETRIES
+            ),
+            user_agent=user_agent(validate_app_info(app_info) if app_info is not None else None),
+            http=HTTPClientManager(http_client, async_http_client),
+        )
+        self._requestor = APIRequestor(self._config)
+        self.balance = BalanceService(self._requestor)
+        self.transfers = TransferService(self._requestor)
+        self.payments = PaymentService(self._requestor)
+
+    def raw_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        options: RequestOptions | None = None,
+    ) -> RayaObject:
+        """Una request a cualquier ruta, con la misma autenticación, reintentos y errores.
+
+        Para endpoints que el SDK todavía no tiene: ``client.raw_request("get", "/v1/…")``.
+        ``params`` va en la query y ``body`` en el JSON del POST.
+        """
+        query = encode_query(params) if params else None
+        result = self._requestor.request(
+            method, path, query=query, body=body, idempotency_key=idempotency_key, options=options
+        )
+        return self._with_paging(result, method, path, query, options)
+
+    async def raw_request_async(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        options: RequestOptions | None = None,
+    ) -> RayaObject:
+        """Como ``raw_request()``, para asyncio."""
+        query = encode_query(params) if params else None
+        result = await self._requestor.request_async(
+            method, path, query=query, body=body, idempotency_key=idempotency_key, options=options
+        )
+        return self._with_paging(result, method, path, query, options)
+
+    @staticmethod
+    def _with_paging(
+        result: RayaObject,
+        method: str,
+        path: str,
+        query: Mapping[str, str] | None,
+        options: RequestOptions | None,
+    ) -> RayaObject:
+        if isinstance(result, ListObject) and method.upper() == "GET":
+            result._set_retrieve_context(path, dict(query or {}), validate_options(options))
+        return result
+
+    def construct_event(
+        self,
+        payload: Payload,
+        sig_header: str | None,
+        secret: str,
+        tolerance: float | None = DEFAULT_TOLERANCE,
+    ) -> Event:
+        """Como ``rayacash.Webhook.construct_event``, con el evento ligado a este cliente.
+
+        Así, ``event.data.object.refund()`` usa la clave de este cliente.
+        """
+        return construct_event(payload, sig_header, secret, tolerance, requestor=self._requestor)
+
+    def close(self) -> None:
+        """Cierra el cliente httpx propio (el que pasaste en ``http_client`` no se toca)."""
+        self._config.http().close()
+
+    async def aclose(self) -> None:
+        """Cierra los clientes httpx propios, también el async."""
+        await self._config.http().aclose()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return (
+            f"<RayaClient api_base={self._config.api_base()!r} "
+            f"api_key={mask_key(self._config.api_key())!r}>"
+        )

rayacash/_encoding.py

@@ -0,0 +1,162 @@
+"""Cómo viajan los parámetros: JSON con montos exactos, query de las listas e ids en la ruta.
+
+La API parsea los montos como números exactos y rechaza los que tienen más de 2 decimales
+(``PARAMETER_INVALID``). Por eso un ``Decimal`` viaja como número JSON, nunca como string, y
+el SDK no redondea nunca: si un float trae ruido (``0.1 + 0.2``), lo responde el servidor.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from typing import Any, Union
+from urllib.parse import quote
+
+#: Un monto en pesos: ``1500``, ``1500.5``, ``Decimal("1500.50")`` o ``"1500.50"``.
+Amount = Union[int, float, Decimal, str]
+
+_IDEMPOTENCY_KEY = re.compile(r"[\x21-\x7e]{1,255}")
+
+
+def canonical_amount(value: object, name: str = "amount") -> Decimal:
+    """El monto como ``Decimal`` exacto, sin redondear. El rango lo valida la API."""
+    if isinstance(value, bool):
+        raise TypeError(
+            f"{name} no puede ser un bool: mandá un número en pesos, como 1500 o 1500.5."
+        )
+    if isinstance(value, int):
+        return Decimal(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"{name} tiene que ser un número finito, no {value!r}.")
+        # repr da el decimal más corto que representa el float: 1500.1 -> "1500.1".
+        return Decimal(repr(value))
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError(f"{name} tiene que ser un número finito, no {value!r}.")
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = Decimal(value.strip())
+        except InvalidOperation:
+            raise ValueError(
+                f'{name} {value!r} no es un número: usá punto decimal y nada más, como "1500.50".'
+            ) from None
+        if not parsed.is_finite():
+            raise ValueError(f"{name} tiene que ser un número finito, no {value!r}.")
+        return parsed
+    raise TypeError(
+        f"{name} tiene que ser un número en pesos (int, float, Decimal o str decimal), "
+        f"no {type(value).__name__}."
+    )
+
+
+def format_decimal(value: Decimal) -> str:
+    """El número JSON canónico: Decimal("1500.50") -> 1500.5, Decimal("1E+3") -> 1000."""
+    if not value.is_finite():
+        raise ValueError(f"No se puede mandar {value!r} en JSON.")
+    return format(value.normalize(), "f")
+
+
+def dumps(value: Any) -> str:
+    """JSON compacto en ASCII, con los ``Decimal`` como números (json.dumps no los acepta)."""
+    out: list[str] = []
+    _encode(value, out)
+    return "".join(out)
+
+
+def _encode(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, str):
+        out.append(json.dumps(value))
+    elif isinstance(value, int):
+        out.append(int.__repr__(value))
+    elif isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"No se puede mandar {value!r} en JSON.")
+        out.append(float.__repr__(value))
+    elif isinstance(value, Decimal):
+        out.append(format_decimal(value))
+    elif isinstance(value, Mapping):
+        out.append("{")
+        for index, (key, item) in enumerate(value.items()):
+            if not isinstance(key, str):
+                raise TypeError(f"Las claves de un objeto JSON tienen que ser str, no {key!r}.")
+            if index:
+                out.append(",")
+            out.append(json.dumps(key))
+            out.append(":")
+            _encode(item, out)
+        out.append("}")
+    elif isinstance(value, (list, tuple)):
+        out.append("[")
+        for index, item in enumerate(value):
+            if index:
+                out.append(",")
+            _encode(item, out)
+        out.append("]")
+    else:
+        raise TypeError(f"No se puede mandar un {type(value).__name__} en JSON.")
+
+
+def encode_body(params: Mapping[str, Any]) -> bytes:
+    """El body de un POST: solo los parámetros que vinieron (la API rechaza los desconocidos)."""
+    return dumps({key: value for key, value in params.items() if value is not None}).encode("ascii")
+
+
+def format_datetime(name: str, value: datetime) -> str:
+    if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+        raise ValueError(
+            f"{name} necesita zona horaria: usá un datetime con tzinfo (por ejemplo, "
+            'timezone.utc) o un string ISO 8601 con zona, como "2026-10-01T00:00:00-03:00".'
+        )
+    return value.isoformat()
+
+
+def encode_query(params: Mapping[str, Any]) -> dict[str, str]:
+    """La query de una lista: solo los filtros que vinieron."""
+    query: dict[str, str] = {}
+    for name, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            raise TypeError(f"{name} no puede ser un bool.")
+        if isinstance(value, datetime):
+            query[name] = format_datetime(name, value)
+        elif isinstance(value, (int, str)):
+            query[name] = str(value)
+        else:
+            raise TypeError(f"{name} no acepta un {type(value).__name__}.")
+    return query
+
+
+def path_id(name: str, value: object) -> str:
+    """Un id para la ruta, codificado: nunca deja una barra final ni un segmento vacío."""
+    if not isinstance(value, str):
+        raise TypeError(f"{name} tiene que ser un str, no {type(value).__name__}.")
+    if not value.strip():
+        raise ValueError(f"{name} no puede estar vacío.")
+    return quote(value, safe="")
+
+
+def validate_idempotency_key(value: object) -> str:
+    if not isinstance(value, str):
+        raise TypeError(
+            "idempotency_key tiene que ser un str: generá un UUID v4 con str(uuid.uuid4()) "
+            "y guardalo junto a la operación antes de llamar."
+        )
+    if not _IDEMPOTENCY_KEY.fullmatch(value):
+        raise ValueError(
+            "idempotency_key tiene que tener de 1 a 255 caracteres ASCII visibles, sin espacios "
+            "(por ejemplo, un UUID v4)."
+        )
+    return value