inttegro 1.0.0__py3-none-any.whl

inttegro/__init__.py

@@ -0,0 +1,21 @@
+from .client import InttegroClient
+from .errors import (
+    InttegroError,
+    NetworkError,
+    TimeoutError,
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+)
+from .enums import *  # noqa: F401,F403
+from .enums import __all__ as _enum_exports
+
+__all__ = [
+    "InttegroClient",
+    "InttegroError",
+    "NetworkError",
+    "TimeoutError",
+    "APIError",
+    "AuthenticationError",
+    "RateLimitError",
+] + _enum_exports

inttegro/client.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from .http_client import HttpClient
+from .resources.balance_transactions import BalanceTransactions
+from .resources.chimes import Chimes
+from .resources.customers import Customers
+from .resources.schedules import Schedules
+from .resources.broadcasts import Broadcasts
+from .resources.message_templates import MessageTemplates
+from .resources.financial_accounts import FinancialAccounts
+from .resources.files import Files
+from .resources.file_links import FileLinks
+from .resources.file_references import FileReferences
+from .resources.keys import Keys
+from .resources.otp import Otp
+from .resources.orders import Orders
+from .resources.payment_methods import PaymentMethods
+from .resources.payouts import Payouts
+from .resources.products import Products
+from .resources.prices import Prices
+from .resources.purchase_intents import PurchaseIntents
+from .resources.refunds import Refunds
+from .resources.spec import Spec
+from .resources.balances import Balances
+from .resources.upload_requests import UploadRequests
+from .resources.apps import Apps
+
+
+class InttegroClient:
+    """
+    Main SDK client for the Inttegro API.
+
+    The Inttegro client provides access to all API resources including orders,
+    payment methods, payouts, financial accounts, and more. Initialize with
+    your API key from the Inttegro dashboard.
+
+    Attributes:
+        orders: Orders resource for creating and managing orders, processing payments
+        payment_methods: Payment methods resource for tokenizing and managing payment instruments
+        payouts: Payouts resource for scheduling and managing fund transfers
+        balance_transactions: Balance transactions resource for viewing account activity
+        financial_accounts: Financial accounts resource for connecting bank and mobile money accounts
+        customers: Customers resource for creating and managing customers
+        products: Products resource for managing catalog products
+        prices: Prices resource for managing catalog prices
+        refunds: Refunds resource for creating and managing refunds
+        chimes: Chimes resource for sending transactional notifications
+        schedules: Schedules resource for looking up and canceling scheduled chimes
+        broadcasts: Broadcasts resource for looking up and canceling broadcasts
+        otp: OTP resource for one-time password verification
+        apps: Apps resource for creating, looking up, and updating applications
+        spec: Spec resource for retrieving supported countries and currencies
+
+    Example:
+        ```python
+        import os
+        from inttegro import InttegroClient
+
+        # Initialize client with API key
+        client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
+
+        # Create and process an order
+        result = client.orders.create({
+            "customer_data": {
+                "name": "Akua Asantewaa",
+                "phone_number": "+233541234567",
+                "email_address": "akua@example.com"
+            },
+            "line_items": [{
+                "type": "product",
+                "product": {
+                    "type": "digital",
+                    "name": "Premium Subscription",
+                    "quantity": 1,
+                    "price": {"currency": "ghs", "value": 5000}
+                }
+            }],
+            "billing_details": {
+                "name": "Akua Asantewaa",
+                "phone_number": "+233541234567"
+            },
+            "execute_payment": True
+        })
+        ```
+
+    Thread Safety:
+        The client is thread-safe after initialization and can be safely shared
+        across multiple threads.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.inttegro.com",
+        timeout: float = 30.0,
+        transport=None,
+    ):
+        """
+        Initialize a new Inttegro client.
+
+        Args:
+            api_key: Your Inttegro API key (required). Get this from your dashboard
+                at https://studio.inttegro.com/settings/keys. Use test keys (sk_test_...)
+                for development and live keys (sk_live_...) for production.
+            base_url: API base URL. Defaults to production (https://api.inttegro.com).
+                Override for testing or staging environments.
+            timeout: Request timeout in seconds. Defaults to 30.0. Increase for
+                long-running operations or slow networks.
+            transport: Custom HTTP transport adapter. Pass a requests.Session or
+                custom transport for connection pooling, retries, or proxies.
+
+        Raises:
+            ValueError: If api_key is empty or invalid
+
+        Example:
+            ```python
+            # Production usage
+            client = InttegroClient(api_key="sk_live_...")
+
+            # Development with custom timeout
+            client = InttegroClient(
+                api_key="sk_test_...",
+                timeout=60.0
+            )
+
+            # Testing with mock server
+            client = InttegroClient(
+                api_key="sk_test_...",
+                base_url="http://localhost:8080"
+            )
+            ```
+        """
+        self.http = HttpClient(api_key=api_key, base_url=base_url, timeout=timeout, transport=transport)
+
+        self.orders = Orders(self.http)
+        self.payment_methods = PaymentMethods(self.http)
+        self.payouts = Payouts(self.http)
+        self.balance_transactions = BalanceTransactions(self.http)
+        self.financial_accounts = FinancialAccounts(self.http)
+        self.files = Files(self.http)
+        self.file_links = FileLinks(self.http)
+        self.file_references = FileReferences(self.http)
+        self.customers = Customers(self.http)
+        self.products = Products(self.http)
+        self.prices = Prices(self.http)
+        self.purchase_intents = PurchaseIntents(self.http)
+        self.refunds = Refunds(self.http)
+        self.chimes = Chimes(self.http)
+        self.schedules = Schedules(self.http)
+        self.broadcasts = Broadcasts(self.http)
+        self.message_templates = MessageTemplates(self.http)
+        self.otp = Otp(self.http)
+        self.apps = Apps(self.http)
+        self.keys = Keys(self.http)
+        self.spec = Spec(self.http)
+        self.balances = Balances(self.http)
+        self.upload_requests = UploadRequests(self.http)

inttegro/enums.py

@@ -0,0 +1,401 @@
+"""Typed string constants for enums published by the Inttegro API."""
+
+from enum import Enum
+
+
+class WireEnum(str, Enum):
+    """A JSON-compatible string enum used on the Inttegro API wire."""
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AppManagementRole(WireEnum):
+    PARENT = "parent"
+    CHILD = "child"
+
+
+class AppCredentialOwner(WireEnum):
+    CHILD = "child"
+    PARENT = "parent"
+
+
+class AppRelationshipKind(WireEnum):
+    PLACEMENT = "placement"
+
+
+class AppRelationshipStatus(WireEnum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    SUSPENDED = "suspended"
+    REVOKED = "revoked"
+
+
+class SecretKeyTokenType(WireEnum):
+    BEARER = "bearer"
+
+
+class SecretKeyStatus(WireEnum):
+    ACTIVE = "active"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+
+
+class SecretKeyAuthResult(WireEnum):
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class FileStatus(WireEnum):
+    UPLOADING = "uploading"
+    PROCESSING = "processing"
+    AVAILABLE = "available"
+    FAILED = "failed"
+    DELETED = "deleted"
+
+
+class FileDisposition(WireEnum):
+    ATTACHMENT = "attachment"
+    INLINE = "inline"
+
+
+class FileDelivery(WireEnum):
+    STREAM = "stream"
+    REDIRECT = "redirect"
+
+
+class FileScanStatus(WireEnum):
+    PENDING = "pending"
+    PASSED = "passed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class FileSourceType(WireEnum):
+    DIRECT = "direct"
+    UPLOAD_REQUEST = "upload_request"
+    SERVICE = "service"
+
+
+class FileStorageEncoding(WireEnum):
+    IDENTITY = "identity"
+    BROTLI = "br"
+
+
+class FileLinkStatus(WireEnum):
+    ACTIVE = "active"
+    REVOKED = "revoked"
+    EXPIRED = "expired"
+    DISABLED = "disabled"
+
+
+class FileLinkKind(WireEnum):
+    PUBLIC = "public"
+
+
+class FileLinkDeliveryMode(WireEnum):
+    REDIRECT = "redirect"
+    DOWNLOAD = "download"
+    INLINE = "inline"
+
+
+class UploadRequestStatus(WireEnum):
+    PENDING = "pending"
+    UPLOADING = "uploading"
+    FULFILLED = "fulfilled"
+    EXPIRED = "expired"
+    CANCELED = "canceled"
+    FAILED = "failed"
+
+
+class UploadReviewDecision(WireEnum):
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+class UploadReviewType(WireEnum):
+    AUTOMATIC = "automatic"
+    MANUAL = "manual"
+
+
+class PaymentNextActionType(WireEnum):
+    CONFIRM_PAYMENT = "confirm_payment"
+    EXECUTE = "execute"
+    REDIRECT = "redirect"
+    AUTHORIZE = "authorize"
+    NONE = "none"
+
+
+class PaymentConfirmationChannel(WireEnum):
+    SMS = "sms"
+    EMAIL = "email"
+    PUSH = "push"
+
+
+class PaymentMethodType(WireEnum):
+    MOBILE_MONEY = "mobile_money"
+    BANK_ACCOUNT = "bank_account"
+    CARD = "card"
+    MOTITO = "motito"
+
+
+class MobileMoneyNetwork(WireEnum):
+    AIRTEL = "airtel"
+    MTN = "mtn"
+    TELECEL = "telecel"
+    VODAFONE = "vodafone"
+
+
+class ProductType(WireEnum):
+    PHYSICAL = "physical"
+    DIGITAL = "digital"
+    SERVICE = "service"
+    VOUCHER = "voucher"
+    CUSTOM = "custom"
+    CAUSE = "cause"
+
+
+class ProductShipmentType(WireEnum):
+    DELIVERY = "delivery"
+    DOWNLOAD = "download"
+    RENDER = "render"
+    SERVICE = "service"
+    STREAM = "stream"
+
+
+class ProductShipmentInputType(WireEnum):
+    DELIVERY = "delivery"
+    DOWNLOAD = "download"
+    RENDER = "render"
+    STREAM = "stream"
+
+
+class LineItemType(WireEnum):
+    PRODUCT = "product"
+    FEE = "fee"
+    SHIPPING = "shipping"
+
+
+class PurchaseIntentStatus(WireEnum):
+    ACTIVE = "active"
+    EXPIRED = "expired"
+    INACTIVE = "inactive"
+    USED = "used"
+
+
+class PurchaseIntentActivityType(WireEnum):
+    EXPIRED_VIEWED = "expired_viewed"
+    ORDER_CREATED = "order_created"
+    PAYMENT_FAILED = "payment_failed"
+    PAYMENT_STARTED = "payment_started"
+    VIEWED = "viewed"
+
+
+class FinancialAccountType(WireEnum):
+    WALLET = "wallet"
+    BANK_ACCOUNT = "bank_account"
+    DOSH_ACCOUNT = "dosh_account"
+
+
+class WalletType(WireEnum):
+    MOBILE_MONEY = "mobile_money"
+
+
+class BankAccountType(WireEnum):
+    GHANA_BANK_ACCOUNT = "ghana_bank_account"
+
+
+class MessageTemplateChannel(WireEnum):
+    SMS = "sms"
+    EMAIL = "email"
+
+
+class MessageTemplateStatus(WireEnum):
+    DRAFT = "draft"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"
+
+
+class MessageTemplateVariableType(WireEnum):
+    STRING = "string"
+    NUMBER = "number"
+    INTEGER = "integer"
+    BOOLEAN = "boolean"
+    URL = "url"
+    EMAIL = "email"
+    PHONE = "phone"
+    DATE = "date"
+    DATETIME = "datetime"
+    ARRAY = "array"
+
+
+class MessageTemplateVariableItemType(WireEnum):
+    STRING = "string"
+    NUMBER = "number"
+    INTEGER = "integer"
+    BOOLEAN = "boolean"
+    URL = "url"
+    EMAIL = "email"
+    PHONE = "phone"
+    DATE = "date"
+    DATETIME = "datetime"
+
+
+class ContentSafetyStatus(WireEnum):
+    ALLOWED = "allowed"
+    REJECTED = "rejected"
+    QUARANTINED = "quarantined"
+
+
+class OrderDocumentKind(WireEnum):
+    INVOICE = "invoice"
+    RECEIPT = "receipt"
+
+
+class DeliveryChannel(WireEnum):
+    EMAIL = "email"
+    SMS = "sms"
+
+
+class CheckoutOrderStatus(WireEnum):
+    PREPARING = "preparing"
+    REQUIRES_PAYMENT = "requires_payment"
+    COMPLETED = "completed"
+    CANCELED = "canceled"
+    EXPIRED = "expired"
+
+
+class OrderStatus(WireEnum):
+    PREPARING = "preparing"
+    REQUIRES_PAYMENT = "requires_payment"
+    PAID = "paid"
+    COMPLETED = "completed"
+    CANCELED = "canceled"
+    EXPIRED = "expired"
+    UNKNOWN = "unknown"
+
+
+class OrderPaymentStatus(WireEnum):
+    INITIATED = "initiated"
+    REQUIRES_ACTION = "requires_action"
+    OVERDUE = "overdue"
+    EXECUTED = "executed"
+    PAID = "paid"
+    CANCELED = "canceled"
+    EXPIRED = "expired"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+
+
+class PaymentAttemptStatus(WireEnum):
+    INITIATED = "initiated"
+    EXECUTED = "executed"
+    SUCCEEDED = "succeeded"
+    CANCELED = "canceled"
+    EXPIRED = "expired"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+
+
+class CheckoutPaymentStatus(WireEnum):
+    REQUIRES_ACTION = "requires_action"
+    PROCESSING = "processing"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class PaymentResponseStatus(WireEnum):
+    PENDING = "pending"
+    REQUIRES_CONFIRMATION = "requires_confirmation"
+    PROCESSING = "processing"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class OrderCreatedFromResourceType(WireEnum):
+    PURCHASE_INTENT = "purchase_intent"
+
+
+class RefundReason(WireEnum):
+    REQUESTED_BY_CUSTOMER = "requested_by_customer"
+    DUPLICATE = "duplicate"
+    FRAUDULENT = "fraudulent"
+    ORDER_CANCELED = "order_canceled"
+    ITEM_RETURNED = "item_returned"
+    ITEM_DAMAGED = "item_damaged"
+    ITEM_NOT_RECEIVED = "item_not_received"
+    ITEM_NOT_AS_DESCRIBED = "item_not_as_described"
+    CUSTOM = "custom"
+
+
+class RefundStatus(WireEnum):
+    CANCELED = "canceled"
+    FAILED = "failed"
+    PENDING = "pending"
+    PROCESSING = "processing"
+    SUCCEEDED = "succeeded"
+
+
+class BalanceTransactionType(WireEnum):
+    PAYMENT = "payment"
+    REFUND = "refund"
+
+
+class PayoutStatus(WireEnum):
+    INITIALIZED = "initialized"
+    SCHEDULED = "scheduled"
+    PROCESSING = "processing"
+    EXECUTING = "executing"
+    SUCCEEDED = "succeeded"
+    INVALID = "invalid"
+    CANCELED = "canceled"
+
+
+class ChimeRecipientType(WireEnum):
+    PHONE = "phone"
+    EMAIL = "email"
+
+
+class ChimeTransport(WireEnum):
+    SMS = "sms"
+    EMAIL = "email"
+
+
+class ChimeEmailSchemaKind(WireEnum):
+    GMAIL_VIEW_ACTION = "gmail_view_action"
+    SCHEMA_ORG_ORDER = "schema_org_order"
+    SCHEMA_ORG_INVOICE = "schema_org_invoice"
+
+
+class OTPAlphabetType(WireEnum):
+    NUMERIC = "numeric"
+    ALPHA = "alpha"
+    ALPHANUMERIC = "alphanumeric"
+
+
+class OTPStatus(WireEnum):
+    CANCELED = "canceled"
+    EXPIRED = "expired"
+    PENDING = "pending"
+    PENDING_DELIVERY = "pending_delivery"
+    PENDING_VERIFICATION = "pending_verification"
+    VERIFIED = "verified"
+
+
+class OTPTransmissionStatus(WireEnum):
+    DELIVERED = "delivered"
+    FAILED = "failed"
+    SUBMITTED = "submitted"
+
+
+class OTPVerificationVerdict(WireEnum):
+    FAIL = "fail"
+    PASS = "pass"
+
+
+__all__ = [
+    name
+    for name, value in globals().items()
+    if isinstance(value, type) and issubclass(value, WireEnum)
+]

inttegro/errors.py

@@ -0,0 +1,78 @@
+class InttegroError(Exception):
+    """Base error for the Inttegro SDK."""
+
+
+class NetworkError(InttegroError):
+    """Raised for network connectivity errors."""
+
+    def __init__(self, message: str, original: Exception | None = None):
+        super().__init__(message)
+        self.original = original
+
+
+class TimeoutError(NetworkError):
+    """Raised when a request times out."""
+
+
+class APIError(InttegroError):
+    """Raised for API errors (HTTP >= 400)."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str | None = None,
+        error_type: str | None = None,
+        url: str | None = None,
+        detail: str | None = None,
+        fix_code: str | None = None,
+        cause: str | None = None,
+        body=None,
+        data=None,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.type = error_type
+        self.url = url
+        self.detail = detail
+        self.fix_code = fix_code
+        self.cause = cause
+        self.body = body
+        self.data = data
+
+
+class AuthenticationError(APIError):
+    """Raised on 401 responses."""
+
+
+class RateLimitError(APIError):
+    """Raised on 429 responses."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        code: str | None = None,
+        error_type: str | None = None,
+        url: str | None = None,
+        detail: str | None = None,
+        fix_code: str | None = None,
+        cause: str | None = None,
+        body=None,
+        data=None,
+        retry_after: int | None = None,
+    ):
+        super().__init__(
+            message,
+            status=status,
+            code=code,
+            error_type=error_type,
+            url=url,
+            detail=detail,
+            fix_code=fix_code,
+            cause=cause,
+            body=body,
+            data=data,
+        )
+        self.retry_after = retry_after