Jukto Python SDK

Jukto is an open-source sync and native asyncio SDK for Bangladesh SMS and logistics APIs, created by Mehedi H Faysal. Version 0.1.0a1 is prepared for early-access evaluation; publication is pending. APIs may change before a stable release. Offline tests do not certify live providers. It provides shared interfaces, typed domain results and classifications for known provider failures. Raw responses remain available, and unverified behavior stays explicit in the contract matrix.

Adapters currently cover Steadfast, Pathao, RedX, GreenWeb, AlphaSMS and BulkSMSBD. The alpha includes experimental SSLCOMMERZ hosted BDT payments; authorized merchant lifecycle verification remains open. Standalone bKash and Nagad remain planned. Native asyncio clients are included; see the async guide. Provider switching requires account/configuration and capability changes; typed models do not erase provider-specific requirements or certify delivery semantics.

Install

python -m pip install jukto==0.1.0a1

This command works after publication. For source-only framework examples, clone the repository, activate a virtual environment and install -e '.[dev,examples]'. See contributing for the exact commands.

Offline quickstart

Run python -m examples.offline_quickstart from the checkout. This source is included directly and tested by pytest; it uses synthetic credentials and an HTTPX MockTransport, so no provider connection occurs.

"""An executable quickstart that cannot contact a real SMS gateway."""
import httpx
from jukto import AlphaSMSClient, SMSSubmissionResult


def run() -> SMSSubmissionResult:
    def reply(request: httpx.Request) -> httpx.Response:
        # Synthetic response matching the documented AlphaSMS success envelope.
        return httpx.Response(200, json={"error": 0, "data": {"request_id": 123}})

    with httpx.Client(transport=httpx.MockTransport(reply)) as http_client:
        with AlphaSMSClient(api_key="synthetic-example-key", http_client=http_client) as provider:
            result = provider.submit_sms("01700000000", "Synthetic offline message")
        assert not http_client.is_closed  # Borrowed client remains caller-owned.
    return result


if __name__ == "__main__":
    print(run().status.value)  # accepted means submitted, not delivered.

Output is accepted, meaning submission acceptance, not delivery. For real operations, obtain your own account configuration, read the provider's current specification and preserve unknown/partial results before deciding to retry.

Continue with logistics, SMS, framework examples and error handling.