dime-python-sdk 1.0.0__py3-none-any.whl

dime_payments/exceptions/not_found_exception.py

@@ -0,0 +1,5 @@
+from .dime_exception import DimeException
+
+
+class NotFoundException(DimeException):
+    pass

dime_payments/exceptions/permission_denied_exception.py

@@ -0,0 +1,5 @@
+from .dime_exception import DimeException
+
+
+class PermissionDeniedException(DimeException):
+    pass

dime_payments/exceptions/rate_limit_exception.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+from .dime_exception import DimeException
+
+
+class RateLimitException(DimeException):
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: dict[str, Any] | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code, response_body)
+        self._retry_after = retry_after
+
+    def get_retry_after(self) -> float | None:
+        return self._retry_after

dime_payments/exceptions/server_exception.py

@@ -0,0 +1,5 @@
+from .dime_exception import DimeException
+
+
+class ServerException(DimeException):
+    pass

dime_payments/exceptions/validation_exception.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+from .dime_exception import DimeException
+
+
+class ValidationException(DimeException):
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: dict[str, Any] | None = None,
+        errors: dict[str, list[str]] | None = None,
+    ) -> None:
+        super().__init__(message, status_code, response_body)
+        self.errors: dict[str, list[str]] = errors or {}
+
+    def get_errors(self) -> dict[str, list[str]]:
+        return self.errors
+
+    def first_error(self) -> str | None:
+        for messages in self.errors.values():
+            if messages:
+                return messages[0]
+        return None

dime_payments/http/error_handler.py

@@ -0,0 +1,76 @@
+from typing import Any
+
+from ..exceptions import (
+    ApiException,
+    AuthenticationException,
+    NotFoundException,
+    PermissionDeniedException,
+    RateLimitException,
+    ServerException,
+    ValidationException,
+)
+
+
+class ErrorHandler:
+    @staticmethod
+    def check(response: Any) -> None:
+        status: int = response.status_code
+        if 200 <= status < 300:
+            return
+
+        try:
+            body: dict[str, Any] = response.json()
+            if not isinstance(body, dict):
+                body = {}
+        except Exception:
+            body = {}
+
+        if status in (400, 422):
+            errors = body.get('errors')
+            if isinstance(errors, dict):
+                raise ValidationException('Validation failed', status_code=status, response_body=body, errors=errors)
+            message = body.get('message')
+            if isinstance(message, dict):
+                raise ValidationException('Validation failed', status_code=status, response_body=body, errors=message)
+            msg = message if isinstance(message, str) else f'Validation failed ({status})'
+            raise ValidationException(msg, status_code=status, response_body=body)
+
+        if status == 401:
+            msg = body.get('message', 'Unauthenticated')
+            raise AuthenticationException(str(msg), status_code=status, response_body=body)
+
+        if status == 403:
+            data_section = body.get('data') or {}
+            msg = (
+                body.get('message')
+                or (data_section.get('message') if isinstance(data_section, dict) else None)
+                or 'Forbidden'
+            )
+            raise PermissionDeniedException(str(msg), status_code=status, response_body=body)
+
+        if status == 404:
+            data_section = body.get('data') or {}
+            msg = (
+                body.get('message')
+                or (data_section.get('message') if isinstance(data_section, dict) else None)
+                or 'Not found'
+            )
+            raise NotFoundException(str(msg), status_code=status, response_body=body)
+
+        if status == 429:
+            retry_after_hdr = response.headers.get('Retry-After')
+            retry_after: float | None = None
+            if retry_after_hdr:
+                try:
+                    retry_after = float(retry_after_hdr)
+                except (ValueError, TypeError):
+                    pass
+            msg = body.get('message', 'Too many requests')
+            raise RateLimitException(str(msg), status_code=status, response_body=body, retry_after=retry_after)
+
+        if status >= 500:
+            msg = body.get('message', 'Server error')
+            raise ServerException(str(msg), status_code=status, response_body=body)
+
+        msg = body.get('message', f'HTTP {status}')
+        raise ApiException(str(msg), status_code=status, response_body=body)

dime_payments/http/transport.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+import requests
+
+from ..exceptions.connection_exception import ConnectionException
+from .error_handler import ErrorHandler
+
+if TYPE_CHECKING:
+    from ..config import Config
+
+SDK_VERSION = '1.0.0'
+
+
+class Transport:
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        if config._session is not None:
+            self._session = config._session
+        else:
+            self._session = requests.Session()
+            self._session.headers.update({
+                'Authorization': f'Bearer {config.token}',
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+                'X-Dime-Sdk': f'dime-python-sdk/{SDK_VERSION}',
+            })
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = self._config.base_uri() + path.lstrip('/')
+        params = {k: v for k, v in (query or {}).items() if v is not None} or None
+
+        attempt = 0
+
+        while True:
+            try:
+                response = self._session.request(
+                    method.upper(),
+                    url,
+                    json=body or None,
+                    params=params,
+                    timeout=self._config.timeout,
+                )
+            except requests.exceptions.RequestException as exc:
+                if attempt < self._config.max_retries:
+                    self._do_sleep(self._config.retry_base_delay * (2 ** attempt))
+                    attempt += 1
+                    continue
+                raise ConnectionException(f'Could not reach the Dime API: {exc}') from exc
+
+            if (response.status_code == 429 or response.status_code >= 500) and attempt < self._config.max_retries:
+                self._do_sleep(self._retry_delay(attempt, response))
+                attempt += 1
+                continue
+
+            ErrorHandler.check(response)
+            return response.json()
+
+    def _retry_delay(self, attempt: int, response: Any) -> float:
+        retry_after = response.headers.get('Retry-After')
+        if retry_after:
+            try:
+                return float(retry_after)
+            except (ValueError, TypeError):
+                pass
+        return min(self._config.retry_base_delay * (2 ** attempt), 30.0)
+
+    def _do_sleep(self, seconds: float) -> None:
+        if self._config._sleep is not None:
+            self._config._sleep(seconds)
+        else:
+            time.sleep(seconds)

dime_payments/pagination/__init__.py

@@ -0,0 +1,3 @@
+from .cursor_page import CursorPage
+
+__all__ = ['CursorPage']

dime_payments/pagination/cursor_page.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Generic, Iterator, TypeVar
+
+T = TypeVar('T')
+PageFetcher = Callable[[str | None], 'CursorPage[T]']
+
+
+class CursorPage(Generic[T]):
+    def __init__(
+        self,
+        data: list[T],
+        next_cursor: str | None = None,
+        prev_cursor: str | None = None,
+        per_page: int | None = None,
+        path: str | None = None,
+        fetcher: PageFetcher | None = None,
+    ) -> None:
+        self.data = data
+        self.next_cursor = next_cursor
+        self.prev_cursor = prev_cursor
+        self.per_page = per_page
+        self.path = path
+        self._fetcher = fetcher
+
+    def has_more(self) -> bool:
+        return self.next_cursor is not None and self._fetcher is not None
+
+    def next(self) -> CursorPage[T] | None:
+        if not self.has_more():
+            return None
+        assert self._fetcher is not None
+        return self._fetcher(self.next_cursor)
+
+    def auto_paging(self) -> Iterator[T]:
+        page: CursorPage[T] | None = self
+        while page is not None:
+            # Yield items individually (not yield from) so indices stay sequential.
+            for item in page.data:
+                yield item
+            page = page.next()
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    @classmethod
+    def from_response(
+        cls,
+        items: list[T],
+        response: dict[str, Any],
+        fetcher: PageFetcher,
+    ) -> CursorPage[T]:
+        meta = response.get('meta') or {}
+        if not isinstance(meta, dict):
+            meta = {}
+
+        next_cursor = meta.get('next_cursor')
+        prev_cursor = meta.get('prev_cursor')
+        per_page = meta.get('per_page')
+        path = meta.get('path')
+
+        return cls(
+            data=items,
+            next_cursor=next_cursor if isinstance(next_cursor, str) and next_cursor else None,
+            prev_cursor=prev_cursor if isinstance(prev_cursor, str) and prev_cursor else None,
+            per_page=int(per_page) if isinstance(per_page, (int, float, str)) and str(per_page).isdigit() else None,
+            path=path if isinstance(path, str) else None,
+            fetcher=fetcher,
+        )

dime_payments/resources/abstract_resource.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from ..http.transport import Transport
+from ..pagination.cursor_page import CursorPage
+
+T = TypeVar('T')
+
+
+class AbstractResource:
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def _envelope(
+        self,
+        data: dict[str, Any] | None = None,
+        filters: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if data:
+            pruned = {k: v for k, v in data.items() if v is not None}
+            if pruned:
+                body['data'] = pruned
+        if filters:
+            pruned_f = {k: v for k, v in filters.items() if v is not None}
+            if pruned_f:
+                body['filters'] = pruned_f
+        return body
+
+    def _paginate(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any],
+        mapper: Callable[[dict[str, Any]], T],
+        query: dict[str, Any] | None = None,
+    ) -> CursorPage[T]:
+        def fetcher(cursor: str | None) -> CursorPage[T]:
+            return self._paginate(method, path, body, mapper, {'cursor': cursor})
+
+        response = self._transport.request(method, path, body, query)
+
+        raw_data = response.get('data', [])
+        if isinstance(raw_data, dict):
+            raw_data = list(raw_data.values())
+
+        items = [mapper(item) for item in raw_data if isinstance(item, dict)]
+        return CursorPage.from_response(items, response, fetcher)

dime_payments/resources/addresses.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.address import Address
+from ..data_objects.message_result import MessageResult
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class Addresses(AbstractResource):
+    def list(self, sid: str, uuid: str) -> CursorPage[Address]:
+        body = self._envelope({'sid': sid, 'uuid': uuid})
+        return self._paginate('GET', 'address/list', body, Address.from_dict)
+
+    def show(self, sid: str, uuid: str, address_id: int | str) -> Address:
+        raw = self._transport.request(
+            'GET',
+            'address/show',
+            self._envelope({'sid': sid, 'uuid': uuid, 'address_id': address_id}),
+        )
+        return Address.from_dict(raw.get('data') or {})
+
+    def create(self, sid: str, uuid: str, attributes: dict[str, Any]) -> Address:
+        body = self._envelope({'sid': sid, 'uuid': uuid} | attributes)
+        raw = self._transport.request('POST', 'address/create', body)
+        return Address.from_dict(raw.get('data') or {})
+
+    def update(self, sid: str, uuid: str, address_id: int | str, attributes: dict[str, Any]) -> Address:
+        body = self._envelope({'sid': sid, 'uuid': uuid, 'address_id': address_id} | attributes)
+        raw = self._transport.request('PATCH', 'address/update', body)
+        return Address.from_dict(raw.get('data') or {})
+
+    def delete(self, sid: str, uuid: str, address_id: int | str) -> MessageResult:
+        body = self._envelope({'sid': sid, 'uuid': uuid, 'address_id': address_id})
+        raw = self._transport.request('POST', 'address/delete', body)
+        return MessageResult.from_dict(raw.get('data') or raw)

dime_payments/resources/customers.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.customer import Customer
+from ..data_objects.message_result import MessageResult
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class Customers(AbstractResource):
+    def list(self, sid: str, filters: dict[str, Any] | None = None) -> CursorPage[Customer]:
+        body = self._envelope({'sid': sid}, filters or {})
+        return self._paginate('GET', 'customer/list', body, Customer.from_dict)
+
+    def show(self, sid: str, filters: dict[str, Any]) -> Customer:
+        raw = self._transport.request('GET', 'customer/show', self._envelope({'sid': sid}, filters))
+        return Customer.from_dict(raw.get('data') or {})
+
+    def create(self, sid: str, attributes: dict[str, Any]) -> Customer:
+        body = self._envelope({'sid': sid} | attributes)
+        raw = self._transport.request('POST', 'customer/create', body)
+        return Customer.from_dict(raw.get('data') or {})
+
+    def update(self, sid: str, filters: dict[str, Any], attributes: dict[str, Any]) -> Customer:
+        body = self._envelope({'sid': sid} | attributes, filters)
+        raw = self._transport.request('PATCH', 'customer/update', body)
+        return Customer.from_dict(raw.get('data') or {})
+
+    def delete(self, sid: str, filters: dict[str, Any]) -> MessageResult:
+        raw = self._transport.request('POST', 'customer/delete', self._envelope({'sid': sid}, filters))
+        return MessageResult.from_dict(raw.get('data') or raw)

dime_payments/resources/deposits.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.deposit import Deposit
+from ..data_objects.deposit_group import DepositGroup
+from ..data_objects.deposit_with_transactions import DepositWithTransactions
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class Deposits(AbstractResource):
+    def list(self, sid: str, filters: dict[str, Any] | None = None) -> CursorPage[Deposit]:
+        body = self._envelope({'sid': sid}, filters or {})
+        return self._paginate('GET', 'deposit/list', body, Deposit.from_dict)
+
+    def list_with_transactions(self, sid: str, filters: dict[str, Any]) -> DepositGroup:
+        raw = self._transport.request(
+            'GET',
+            'deposit/list-with-trans',
+            self._envelope({'sid': sid}, filters),
+        )
+        return DepositGroup.from_dict(raw.get('data') or {})
+
+    def show(self, sid: str, identifier: dict[str, Any]) -> DepositWithTransactions:
+        raw = self._transport.request(
+            'GET',
+            'deposit/show',
+            self._envelope({'sid': sid} | identifier),
+        )
+        return DepositWithTransactions.from_dict(raw.get('data') or {})

dime_payments/resources/merchants.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.form_link import FormLink
+from ..data_objects.merchant import Merchant
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class Merchants(AbstractResource):
+    def list(self, filters: dict[str, Any] | None = None) -> CursorPage[Merchant]:
+        body = self._envelope({}, filters or {})
+        return self._paginate('GET', 'merchant/list', body, Merchant.from_dict)
+
+    def show(self, sid: str) -> Merchant:
+        raw = self._transport.request('GET', 'merchant/show', self._envelope({'sid': sid}))
+        return Merchant.from_dict(raw.get('data') or {})
+
+    def create(self, attributes: dict[str, Any]) -> Merchant:
+        raw = self._transport.request('POST', 'merchant/create', self._envelope(attributes))
+        return Merchant.from_dict(raw.get('data') or {})
+
+    def update(self, sid: str, attributes: dict[str, Any]) -> Merchant:
+        body = self._envelope({'sid': sid} | attributes)
+        raw = self._transport.request('PATCH', 'merchant/update', body)
+        return Merchant.from_dict(raw.get('data') or {})
+
+    def get_form_link(self, sid: str) -> FormLink:
+        raw = self._transport.request('GET', 'merchant/get-form-link', self._envelope({'sid': sid}))
+        return FormLink.from_dict(raw.get('data') or {})

dime_payments/resources/payment_methods.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.message_result import MessageResult
+from ..data_objects.payment_method import PaymentMethod
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class PaymentMethods(AbstractResource):
+    def list(self, sid: str, filters: dict[str, Any]) -> CursorPage[PaymentMethod]:
+        body = self._envelope({'sid': sid}, filters)
+        return self._paginate('GET', 'payment-method/list', body, PaymentMethod.from_dict)
+
+    def show(self, sid: str, payment_method_id: int | str, filters: dict[str, Any]) -> PaymentMethod:
+        raw = self._transport.request(
+            'GET',
+            'payment-method/show',
+            self._envelope({'sid': sid, 'payment_method_id': payment_method_id}, filters),
+        )
+        return PaymentMethod.from_dict(raw.get('data') or {})
+
+    def create(self, sid: str, attributes: dict[str, Any]) -> PaymentMethod:
+        body = self._envelope({'sid': sid} | attributes)
+        raw = self._transport.request('POST', 'payment-method/create', body)
+        return PaymentMethod.from_dict(raw.get('data') or {})
+
+    def update(self, sid: str, attributes: dict[str, Any]) -> PaymentMethod:
+        body = self._envelope({'sid': sid} | attributes)
+        raw = self._transport.request('PATCH', 'payment-method/update', body)
+        return PaymentMethod.from_dict(raw.get('data') or {})
+
+    def delete(self, sid: str, payment_method_id: int | str, uuid: str) -> MessageResult:
+        body = self._envelope({'sid': sid, 'payment_method_id': payment_method_id, 'uuid': uuid})
+        raw = self._transport.request('POST', 'payment-method/delete', body)
+        return MessageResult.from_dict(raw.get('data') or raw)

dime_payments/resources/recurring_payments.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.message_result import MessageResult
+from ..data_objects.recurring_payment import RecurringPayment
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class RecurringPayments(AbstractResource):
+    def list(self, sid: str, filters: dict[str, Any] | None = None) -> CursorPage[RecurringPayment]:
+        body = self._envelope({'sid': sid}, filters or {})
+        return self._paginate('GET', 'recurring-payment/list', body, RecurringPayment.from_dict)
+
+    def show(self, sid: str, recurring_payment_id: int | str) -> RecurringPayment:
+        body = self._envelope({'sid': sid, 'recurring_payment_id': recurring_payment_id})
+        raw = self._transport.request('GET', 'recurring-payment/show', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def create(self, sid: str, attributes: dict[str, Any]) -> RecurringPayment:
+        body = self._envelope({'sid': sid} | attributes)
+        raw = self._transport.request('POST', 'recurring-payment/create', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def edit(self, sid: str, recurring_payment_id: int | str, attributes: dict[str, Any]) -> RecurringPayment:
+        body = self._envelope({'sid': sid, 'recurring_payment_id': recurring_payment_id} | attributes)
+        raw = self._transport.request('PATCH', 'recurring-payment/edit', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def pause(self, sid: str, recurring_payment_id: int | str, pause_until_date: str | None = None) -> RecurringPayment:
+        body = self._envelope({
+            'sid': sid,
+            'recurring_payment_id': recurring_payment_id,
+            'pause_until_date': pause_until_date,
+        })
+        raw = self._transport.request('PATCH', 'recurring-payment/pause', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def cancel(self, sid: str, recurring_payment_id: int | str) -> RecurringPayment:
+        body = self._envelope({'sid': sid, 'recurring_payment_id': recurring_payment_id})
+        raw = self._transport.request('PATCH', 'recurring-payment/cancel', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def activate(self, sid: str, recurring_payment_id: int | str) -> RecurringPayment:
+        body = self._envelope({'sid': sid, 'recurring_payment_id': recurring_payment_id})
+        raw = self._transport.request('PATCH', 'recurring-payment/activate', body)
+        return RecurringPayment.from_dict(raw.get('data') or {})
+
+    def delete(self, sid: str, recurring_payment_id: int | str) -> MessageResult:
+        body = self._envelope({'sid': sid, 'recurring_payment_id': recurring_payment_id})
+        raw = self._transport.request('POST', 'recurring-payment/delete', body)
+        return MessageResult.from_dict(raw.get('data') or raw)

dime_payments/resources/transactions.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..data_objects.message_result import MessageResult
+from ..data_objects.tokenize_result import TokenizeResult
+from ..data_objects.transaction import Transaction
+from ..pagination.cursor_page import CursorPage
+from .abstract_resource import AbstractResource
+
+
+class Transactions(AbstractResource):
+    def list(self, sid: str, filters: dict[str, Any] | None = None) -> CursorPage[Transaction]:
+        body = self._envelope({'sid': sid}, filters or {})
+        return self._paginate('GET', 'transactions', body, Transaction.from_dict)
+
+    def show(self, sid: str, identifier: dict[str, Any]) -> Transaction:
+        raw = self._transport.request('GET', 'transaction', self._envelope({'sid': sid} | identifier))
+        return Transaction.from_dict(raw.get('data') or {})
+
+    def charge_card(self, sid: str, attributes: dict[str, Any] | None = None) -> Transaction:
+        body = self._envelope({'sid': sid} | (attributes or {}))
+        raw = self._transport.request('POST', 'transaction/charge-card', body)
+        return Transaction.from_dict(raw.get('data') or {})
+
+    def charge_card_token(self, sid: str, attributes: dict[str, Any] | None = None) -> Transaction:
+        body = self._envelope({'sid': sid} | (attributes or {}))
+        raw = self._transport.request('POST', 'transaction/charge-card-token', body)
+        return Transaction.from_dict(raw.get('data') or {})
+
+    def charge_ach(self, sid: str, attributes: dict[str, Any] | None = None) -> Transaction:
+        body = self._envelope({'sid': sid} | (attributes or {}))
+        raw = self._transport.request('POST', 'transaction/charge-ach', body)
+        return Transaction.from_dict(raw.get('data') or {})
+
+    def tokenize_card(self, sid: str, attributes: dict[str, Any] | None = None) -> TokenizeResult:
+        body = self._envelope({'sid': sid} | (attributes or {}))
+        raw = self._transport.request('POST', 'transaction/tokenize-card', body)
+        return TokenizeResult.from_dict(raw.get('data') or {})
+
+    def refund(self, sid: str, attributes: dict[str, Any] | None = None) -> MessageResult:
+        body = self._envelope({'sid': sid} | (attributes or {}))
+        raw = self._transport.request('POST', 'transaction/refund', body)
+        return MessageResult.from_dict(raw.get('data') or raw)
+
+    def void(self, sid: str, transaction_type: str, transaction_id: int | str) -> MessageResult:
+        body = self._envelope({
+            'sid': sid,
+            'transaction_type': transaction_type,
+            'transaction_id': transaction_id,
+        })
+        raw = self._transport.request('PATCH', 'transaction/void', body)
+        return MessageResult.from_dict(raw.get('data') or raw)