nylonpay-py 0.1.0__py3-none-any.whl

nylonpay/__init__.py

@@ -0,0 +1,116 @@
+"""Nylon Pay SDK for merchant integrations.
+
+Server-side SDK for collecting payments, making payouts, verifying phones,
+creating invoices, checking transaction status, and verifying webhooks.
+
+Example:
+    from nylonpay import create_nylon_pay
+
+    nylonpay = create_nylon_pay(
+        api_key="npk_live_...",
+        api_secret="nps_live_...",
+    )
+
+    payment = nylonpay.collect_payment(
+        amount=10000,
+        currency="UGX",
+        customer={"name": "Jane", "phone_number": "+256700000000"},
+        description="Order #1234",
+    )
+    payment.on("success", lambda data: print("Paid:", data.transaction))
+"""
+
+from .factory import create_nylon_pay
+from .slang import Err, Ok, Result
+from .transport import SdkException, create_sdk_error, parse_error
+from .types import (
+    AfterCollectHook,
+    AfterHookInput,
+    AfterPayoutHook,
+    BankDetails,
+    BeforeCollectHook,
+    BeforePayoutHook,
+    CollectPaymentInput,
+    CreateInvoiceInput,
+    Currency,
+    Customer,
+    Destination,
+    EventData,
+    GetStatusInput,
+    GetTransactionInput,
+    InitiationResult,
+    InvoiceItem,
+    InvoiceResponse,
+    MakePayoutInput,
+    NylonPayConfig,
+    NylonPaySdk,
+    PaymentEvent,
+    PaymentEventHandler,
+    PaymentInstance,
+    PaymentMethod,
+    PhoneVerification,
+    SdkError,
+    SdkErrorCategory,
+    SdkHook,
+    SdkHooks,
+    StatusResponse,
+    Transaction,
+    TransactionMode,
+    TransactionStatus,
+    TransactionType,
+    VerifyPhoneInput,
+    VerifyWebhookInput,
+    WebhookEventType,
+    WebhookPayload,
+)
+from .verify_webhook import verify_webhook_signature
+
+__all__ = [
+    # Types
+    "AfterCollectHook",
+    "AfterHookInput",
+    "AfterPayoutHook",
+    "BankDetails",
+    "BeforeCollectHook",
+    "BeforePayoutHook",
+    "CollectPaymentInput",
+    "CreateInvoiceInput",
+    "Currency",
+    "Customer",
+    "Destination",
+    "Err",
+    "EventData",
+    "GetStatusInput",
+    "GetTransactionInput",
+    "InitiationResult",
+    "InvoiceItem",
+    "InvoiceResponse",
+    "MakePayoutInput",
+    "NylonPayConfig",
+    "NylonPaySdk",
+    "Ok",
+    "PaymentEvent",
+    "PaymentEventHandler",
+    "PaymentInstance",
+    "PaymentMethod",
+    "PhoneVerification",
+    "Result",
+    "SdkError",
+    "SdkErrorCategory",
+    "SdkException",
+    "SdkHook",
+    "SdkHooks",
+    "StatusResponse",
+    "Transaction",
+    "TransactionMode",
+    "TransactionStatus",
+    "TransactionType",
+    "VerifyPhoneInput",
+    "VerifyWebhookInput",
+    "WebhookEventType",
+    "WebhookPayload",
+    "create_nylon_pay",
+    "create_sdk_error",
+    "parse_error",
+    "verify_webhook_signature",
+]

nylonpay/coerce.py

@@ -0,0 +1,104 @@
+"""Coercion helpers for accepting dicts at SDK boundaries.
+
+Lets merchants pass plain dicts instead of importing and constructing
+dataclasses for every nested type (Customer, Destination, BankDetails,
+InvoiceItem). The coercion runs at the operation boundary so the rest
+of the SDK always works with typed dataclass instances.
+
+Example::
+
+    # Instead of this:
+    from nylonpay import Customer, CollectPaymentInput
+    nylonpay.collect_payment(CollectPaymentInput(
+        amount=5000, currency="UGX",
+        customer=Customer(name="John", phone_number="256700000000"),
+        description="Order",
+    ))
+
+    # Merchants can do this:
+    nylonpay.collect_payment(
+        amount=5000, currency="UGX",
+        customer={"name": "John", "phone_number": "256700000000"},
+        description="Order",
+    )
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+from typing import Any, get_args, get_origin, get_type_hints
+
+_MAX_DEPTH = 32
+
+
+class _DepthExceededError(Exception):
+    """Raised when dict nesting exceeds the safety cap during coercion."""
+
+
+def coerce_dataclass(cls: type, data: Any, depth: int = 0) -> Any:
+    """Construct a dataclass from a dict, coercing nested fields recursively.
+
+    If *data* is already a dataclass instance, returns it unchanged.
+    If *data* is a dict, constructs *cls* from it, coercing any nested
+    dict fields to their declared dataclass types.
+    Otherwise, returns *data* unchanged.
+
+    A depth cap prevents stack overflow on pathologically nested input.
+    """
+    if dataclasses.is_dataclass(data) and not isinstance(data, type):
+        return data
+    if not isinstance(data, dict):
+        return data
+
+    if depth > _MAX_DEPTH:
+        raise _DepthExceededError(_MAX_DEPTH)
+
+    hints = get_type_hints(cls)
+    kwargs: dict[str, Any] = {}
+
+    for key, value in data.items():
+        field_type = hints.get(key)
+        kwargs[key] = _coerce_field(field_type, value, depth + 1)
+
+    return cls(**kwargs)
+
+
+def _coerce_field(field_type: Any, value: Any, depth: int = 0) -> Any:
+    """Coerce a value based on its declared field type."""
+    if value is None or field_type is None:
+        return value
+
+    if isinstance(field_type, types.UnionType):
+        for arg in get_args(field_type):
+            if arg is type(None):
+                continue
+            if dataclasses.is_dataclass(arg) and isinstance(value, dict):
+                return coerce_dataclass(arg, value, depth)
+            if get_origin(arg) is list:
+                return _coerce_list(arg, value, depth)
+        return value
+
+    if get_origin(field_type) is list:
+        return _coerce_list(field_type, value, depth)
+
+    if dataclasses.is_dataclass(field_type) and isinstance(value, dict):
+        return coerce_dataclass(field_type, value, depth)
+
+    return value
+
+
+def _coerce_list(list_type: Any, value: Any, depth: int = 0) -> Any:
+    """Coerce a list of dicts to a list of dataclass instances."""
+    if not isinstance(value, list):
+        return value
+
+    args = get_args(list_type)
+    element_type = args[0] if args else None
+    if element_type is None or not dataclasses.is_dataclass(element_type):
+        return value
+
+    return [
+        coerce_dataclass(element_type, item, depth) if isinstance(item, dict) else item
+        for item in value
+    ]

nylonpay/config.py

@@ -0,0 +1,51 @@
+"""Constants and defaults for the Nylon Pay SDK.
+
+These values define the SDK's operational envelope — timeouts, retry limits,
+polling cadence, and validation thresholds. They're derived from the SDK
+spec (v1.3.0) which sets these as cross-language invariants: every SDK
+implementation (TypeScript, Python, future languages) must enforce the same
+minimums and defaults so backend behavior is predictable regardless of
+which language the merchant integrates with.
+
+Defaults are overridable via ``NylonPayConfig`` — merchants with slow
+networks or long-running payment flows can widen timeouts and poll limits
+without touching the spec-mandated validation thresholds (min amounts,
+reference length).
+"""
+
+from __future__ import annotations
+
+# --- Defaults (overridable via NylonPayConfig) ---
+
+DEFAULT_BASE_URL = "https://api.nylonpay.nilesquad.com/api/services"
+DEFAULT_TIMEOUT_MS = 30_000
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_MAX_POLL_INTERVAL_MS = 2_000
+DEFAULT_MAX_POLL_DURATION_MS = 300_000
+DEFAULT_MAX_POLL_ATTEMPTS = 150
+
+POLL_JITTER_MS = 250
+
+# --- Internal constants ---
+
+SDK_SERVICE = "sdk"
+
+SDK_ACTIONS = {
+    "collect_payment": "sdk-collect-payment",
+    "collect_payment_and_resolve": "sdk-collect-payment-and-resolve",
+    "make_payout": "sdk-make-payout",
+    "make_payout_and_resolve": "sdk-make-payout-and-resolve",
+    "get_status": "sdk-get-status",
+    "get_transaction": "sdk-get-transaction",
+    "verify_phone": "sdk-verify-phone",
+    "create_invoice": "sdk-create-invoice",
+}
+
+RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+
+# --- Validation constants ---
+
+MIN_COLLECTION_AMOUNT = 500
+MIN_DISBURSEMENT_AMOUNT = 5000
+MIN_REFERENCE_LENGTH = 13
+MAX_REFERENCE_LENGTH = 15

nylonpay/factory.py

@@ -0,0 +1,78 @@
+"""Factory function to create a Nylon Pay SDK instance.
+
+Main entry point for merchants. Singleton-caches instances by
+``api_key + base_url + sha256(api_secret)`` so the same credentials
+return the same instance — rotating the secret yields a fresh one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from typing import Any
+
+from .config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_POLL_ATTEMPTS,
+    DEFAULT_MAX_POLL_DURATION_MS,
+    DEFAULT_MAX_POLL_INTERVAL_MS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT_MS,
+)
+from .sdk import create_sdk_instance
+from .types import NylonPayConfig, NylonPaySdk
+
+_instances: dict[str, NylonPaySdk] = {}
+_instances_lock = threading.Lock()
+
+
+def create_nylon_pay(**kwargs: Any) -> NylonPaySdk:
+    """Create a Nylon Pay SDK instance.
+
+    Accepts keyword arguments matching :class:`NylonPayConfig` fields.
+    Returns the same instance for the same ``api_key`` + ``api_secret`` +
+    ``base_url`` combination unless ``force=True`` is passed. Rotating the
+    secret yields a fresh instance (secret-aware cache key).
+
+    Raises ``ValueError`` if ``api_key`` is missing or doesn't start with
+    ``npk_``, or ``api_secret`` is missing or doesn't start with ``nps_``.
+    """
+    config = NylonPayConfig(**kwargs)
+    if not config.api_key:
+        raise ValueError("api_key is required")
+    if not config.api_key.startswith("npk_"):
+        raise ValueError('api_key must start with "npk_"')
+    if not config.api_secret:
+        raise ValueError("api_secret is required")
+    if not config.api_secret.startswith("nps_"):
+        raise ValueError('api_secret must start with "nps_"')
+
+    base_url = config.base_url or DEFAULT_BASE_URL
+    # Hash the secret so it never sits raw in a dict key; rotating the
+    # secret produces a different cache key → fresh instance.
+    secret_hash = hashlib.sha256(config.api_secret.encode()).hexdigest()[:16]
+    instance_key = f"{config.api_key}:{base_url}:{secret_hash}"
+
+    if not config.force:
+        with _instances_lock:
+            existing = _instances.get(instance_key)
+            if existing is not None:
+                return existing
+
+    resolved: dict[str, Any] = {
+        "api_key": config.api_key,
+        "api_secret": config.api_secret,
+        "base_url": base_url,
+        "timeout_ms": config.timeout_ms or DEFAULT_TIMEOUT_MS,
+        "max_retries": config.max_retries or DEFAULT_MAX_RETRIES,
+        "max_poll_interval_ms": config.max_poll_interval_ms or DEFAULT_MAX_POLL_INTERVAL_MS,
+        "max_poll_duration_ms": config.max_poll_duration_ms or DEFAULT_MAX_POLL_DURATION_MS,
+        "max_poll_attempts": config.max_poll_attempts or DEFAULT_MAX_POLL_ATTEMPTS,
+        "http_client": config.http_client,
+        "hooks": config.hooks,
+    }
+
+    instance = create_sdk_instance(resolved)
+    with _instances_lock:
+        _instances[instance_key] = instance
+    return instance

nylonpay/fingerprint.py

@@ -0,0 +1,41 @@
+"""Stable server fingerprint based on the runtime environment.
+
+WHY fingerprinting: the backend binds each signed request to the
+originating server so that a leaked signature cannot be replayed from
+a different machine. The fingerprint must be stable within a process
+but differ across hosts, OS versions, and Python runtimes.
+
+The components (OS type, platform, arch, release, hostname, runtime
+versions) are derived from Python's ``platform`` and ``sys`` stdlib
+modules. The same conceptual inputs are used across all SDK
+implementations so a merchant running both TS and Python SDKs on the
+same server produces comparable fingerprints.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import platform
+import socket
+from functools import lru_cache
+
+
+@lru_cache(maxsize=1)
+def generate_fingerprint() -> str:
+    """Derive a SHA-256 hex digest from OS and runtime metadata.
+
+    Cached after first call — the environment cannot change within a
+    running process, so recomputing is wasteful.
+    """
+    components = "|".join(
+        [
+            f"type:{platform.system()}",
+            f"platform:{platform.platform()}",
+            f"arch:{platform.machine()}",
+            f"release:{platform.release()}",
+            f"hostname:{socket.gethostname()}",
+            f"python:{platform.python_version()}",
+            f"implementation:{platform.python_implementation()}",
+        ]
+    )
+    return hashlib.sha256(components.encode()).hexdigest()

nylonpay/nonce.py

@@ -0,0 +1,21 @@
+"""Cryptographic nonce generation for SDK request deduplication.
+
+WHY a separate module: the nonce is a core security primitive used in
+every signed request. Isolating it keeps the generation strategy
+(swappable for testing) and the byte-length → hex-length relationship
+in one place.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+
+def generate_nonce(length: int = 16) -> str:
+    """Produce a cryptographically secure random hex string.
+
+    The default 16-byte (32 hex char) nonce provides sufficient entropy
+    for replay-attack prevention within the backend's freshness window.
+    Uses ``secrets.token_hex`` which delegates to the OS CSPRNG.
+    """
+    return secrets.token_hex(length)

nylonpay/payment.py

@@ -0,0 +1,281 @@
+"""Payment instance with event emission for transaction lifecycle.
+
+Creates an event-driven payment instance that polls for status updates,
+emits lifecycle events, and supports blocking until terminal state.
+
+Fully synchronous — no asyncio. Events fire as callbacks during ``wait()``,
+which runs a polling loop with ``time.sleep`` between polls.
+
+Factory pattern — :func:`create_payment_instance` returns a plain object
+(``SimpleNamespace``) with closure-based methods. No classes.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from typing import Any, cast
+
+from .config import (
+    DEFAULT_MAX_POLL_ATTEMPTS,
+    DEFAULT_MAX_POLL_DURATION_MS,
+    DEFAULT_MAX_POLL_INTERVAL_MS,
+    POLL_JITTER_MS,
+)
+from .pubsub import create_emitter
+from .transport import parse_error
+from .types import (
+    EventData,
+    GetStatusInput,
+    GetTransactionInput,
+    PaymentEvent,
+    PaymentEventHandler,
+    PaymentInstance,
+    SdkError,
+    SdkErrorCategory,
+    StatusResponse,
+    Transaction,
+    TransactionStatus,
+)
+
+# --- Status → Event mapping ---
+
+STATUS_TO_EVENT: dict[str, PaymentEvent] = {
+    "pending": "processing",
+    "processing": "processing",
+    "successful": "success",
+    "failed": "failed",
+    "cancelled": "cancelled",
+}
+
+TERMINAL_STATES: frozenset[str] = frozenset({"successful", "failed", "cancelled"})
+
+
+def _status_to_event(status: str) -> PaymentEvent | None:
+    """Map a transaction status to its corresponding payment event."""
+    return STATUS_TO_EVENT.get(status)
+
+
+def _normalize_status(raw: str) -> TransactionStatus:
+    """Normalise raw backend status strings. ``'completed'`` → ``'successful'``."""
+    if raw == "completed":
+        return "successful"
+    return raw  # ty: ignore[invalid-return-type]
+
+
+def create_payment_instance(
+    initial_response: dict[str, Any],
+    deps: dict[str, Any],
+) -> PaymentInstance:
+    """Create a payment instance with polling and event emission.
+
+    ``initial_response`` carries ``reference`` and ``status`` from the
+    initiation call. ``deps`` injects ``fetch_status``, ``fetch_transaction``,
+    optional poll config, and an optional ``initial_error`` for backend
+    rejections that surface as events rather than exceptions.
+
+    Events fire during ``wait()`` — the polling loop runs inside it and
+    calls registered callbacks as the status changes. If ``wait()`` is
+    never called, no polling occurs.
+
+    Returns a ``SimpleNamespace`` with ``reference``, ``status``,
+    ``on``, ``once``, ``off``, ``wait`` — satisfies ``PaymentInstance``
+    protocol without a class.
+    """
+    emitter = create_emitter()
+
+    state: dict[str, Any] = {
+        "reference": initial_response["reference"],
+        "status": _normalize_status(initial_response["status"]),
+        "transaction": None,
+        "last_status_event": None,
+        "resolved": False,
+        "poll_attempts": 0,
+        "poll_start_time": time.time() * 1000,
+        "emitter": emitter,
+        "fetch_status": deps["fetch_status"],
+        "fetch_transaction": deps["fetch_transaction"],
+        "poll_interval_ms": deps.get("poll_interval_ms", DEFAULT_MAX_POLL_INTERVAL_MS),
+        "max_poll_duration": deps.get("max_poll_duration", DEFAULT_MAX_POLL_DURATION_MS),
+        "max_poll_attempts": deps.get("max_poll_attempts", DEFAULT_MAX_POLL_ATTEMPTS),
+        "pending_error": None,
+    }
+
+    def set_status(new_status: TransactionStatus) -> None:
+        """Update status in both state dict and on the public object."""
+        state["status"] = new_status
+        payment_instance.status = new_status
+
+    def emit_event(
+        event: PaymentEvent,
+        error: str | None = None,
+        category: SdkErrorCategory | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        """Emit a lifecycle event with current transaction data."""
+        data = EventData(
+            event=event,
+            reference=state["reference"],
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            transaction=state["transaction"],
+            error=error,
+            category=category,
+            retryable=retryable,
+        )
+        emitter["emit"](event, data)
+
+    def handle_terminal_state(status: TransactionStatus) -> None:
+        """Fetch full transaction record and emit terminal event."""
+        tx_result = state["fetch_transaction"](GetTransactionInput(reference=state["reference"]))
+        if tx_result.is_ok:
+            state["transaction"] = tx_result.value
+            event = _status_to_event(status)
+            if event is not None:
+                error_msg = None
+                if status == "failed" and state["transaction"] is not None:
+                    error_msg = state["transaction"].failure_reason
+                emit_event(event, error=error_msg)
+        else:
+            emit_event("error", error="Could not retrieve the transaction details")
+        state["resolved"] = True
+
+    def handle_status_update(response: StatusResponse) -> None:
+        """Process a status response from polling."""
+        if state["resolved"]:
+            return
+
+        if response.reference != state["reference"]:
+            emit_event(
+                "error",
+                error="Received a status update for a different transaction",
+                category="internal",
+            )
+            state["resolved"] = True
+            return
+
+        new_status = _normalize_status(response.status)
+        set_status(new_status)
+
+        # Dedupe by event, not raw status
+        event = _status_to_event(new_status)
+        if event is None or event == state["last_status_event"]:
+            return
+        state["last_status_event"] = event
+
+        if new_status in TERMINAL_STATES:
+            handle_terminal_state(new_status)
+            return
+
+        emit_event(event)
+
+    def poll_once() -> None:
+        """Execute one polling cycle."""
+        if state["resolved"]:
+            return
+
+        if state["poll_attempts"] >= state["max_poll_attempts"]:
+            emit_event(
+                "error",
+                error="Timed out waiting for the transaction status to update",
+                category="timeout",
+            )
+            state["resolved"] = True
+            return
+
+        current_ms = time.time() * 1000
+        if current_ms - state["poll_start_time"] >= state["max_poll_duration"]:
+            emit_event(
+                "error",
+                error="Timed out waiting for the transaction status to update",
+                category="timeout",
+            )
+            state["resolved"] = True
+            return
+
+        state["poll_attempts"] += 1
+
+        result = state["fetch_status"](GetStatusInput(reference=state["reference"]))
+
+        if result.is_ok:
+            handle_status_update(result.value)
+        else:
+            parsed = parse_error(result.error)
+            if parsed.category == "not_found":
+                return
+            emit_event("error", parsed.message, parsed.category, parsed.retryable)
+            state["resolved"] = True
+
+    def wait_fn() -> Transaction | None:
+        """Block until terminal state.
+
+        Emits any pending initial error, then polls at jittered intervals
+        until the transaction reaches a terminal state. Event callbacks
+        fire as the status changes during this loop.
+        """
+        # Handle pending initial error (backend rejection at initiation)
+        if state["pending_error"] is not None:
+            err: SdkError = state["pending_error"]
+            state["pending_error"] = None
+            emit_event("error", err.message, err.category, err.retryable)
+            return None
+
+        if state["resolved"]:
+            return state["transaction"] if state["status"] == "successful" else None
+
+        # Emit initial event if status maps to one
+        initial_event = _status_to_event(state["status"])
+        if initial_event is not None and initial_event != state["last_status_event"]:
+            state["last_status_event"] = initial_event
+            emit_event(initial_event)
+
+        # If already in terminal state at creation, handle it
+        if state["status"] in TERMINAL_STATES:
+            handle_terminal_state(state["status"])
+        else:
+            # Poll until resolved
+            while not state["resolved"]:
+                poll_once()
+                if state["resolved"]:
+                    break
+                delay = (state["poll_interval_ms"] + random.random() * POLL_JITTER_MS) / 1000
+                time.sleep(delay)
+
+        return state["transaction"] if state["status"] == "successful" else None
+
+    # --- Public API closures ---
+
+    def on_fn(event: PaymentEvent, handler: PaymentEventHandler) -> PaymentInstance:
+        emitter["on"](event, handler)
+        return payment_instance
+
+    def once_fn(event: PaymentEvent, handler: PaymentEventHandler) -> PaymentInstance:
+        emitter["once"](event, handler)
+        return payment_instance
+
+    def off_fn(event: PaymentEvent, handler: PaymentEventHandler) -> PaymentInstance:
+        emitter["off"](event, handler)
+        return payment_instance
+
+    # --- Build the public object (no class, just closures on SimpleNamespace) ---
+
+    payment_instance = cast(
+        "PaymentInstance",
+        SimpleNamespace(
+            reference=state["reference"],
+            status=state["status"],
+            on=on_fn,
+            once=once_fn,
+            off=off_fn,
+            wait=wait_fn,
+        ),
+    )
+
+    # Store initial error for wait() to emit (handlers aren't registered yet)
+    initial_error: SdkError | None = deps.get("initial_error")
+    if initial_error is not None:
+        state["resolved"] = True
+        state["pending_error"] = initial_error
+
+    return payment_instance