mista 0.1.0__tar.gz

mista-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.coverage
+.env
+.DS_Store

mista-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+First release, covering the Mista API v3 as documented at https://docs.mista.io,
+with a synchronous `Mista` and an asynchronous `AsyncMista` client:
+
+- SMS: `sms.send`
+- Campaigns: `campaigns.bulk`, `campaigns.send_to_groups`, `campaigns.get`
+- Logs: `logs.list` (filters + auto-pagination), `logs.get`
+- Account: `account.balance`, `account.me`
+- Contact groups and contacts: list, create, get, update, delete
+- Verify: `verify.start`, `verify.check`, `verify.get`
+- Voice: `voice.access_token`, `voice.numbers`, `voice.calls.list`, `voice.calls.get`
+- Typed errors, automatic retries for rate limits, request timeouts, `py.typed`

mista-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mista-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: mista
+Version: 0.1.0
+Summary: Official Python SDK for the Mista Messaging, Verify and Voice APIs
+Project-URL: Homepage, https://mista.io
+Project-URL: Documentation, https://docs.mista.io
+Project-URL: Source, https://github.com/mista-io/mista-python
+Project-URL: Issues, https://github.com/mista-io/mista-python/issues
+Author: Mista
+License-Expression: MIT
+License-File: LICENSE
+Keywords: africa,bulk-sms,mista,otp,rwanda,sms,verify,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Mista Python SDK
+
+Official Python client for the [Mista](https://mista.io) Messaging, Verify and Voice APIs.
+Full API reference: https://docs.mista.io
+
+```bash
+pip install mista
+```
+
+Requires Python 3.9+. The only dependency is [httpx](https://www.python-httpx.org/).
+Both a synchronous (`Mista`) and an asynchronous (`AsyncMista`) client are included.
+
+## Quickstart
+
+```python
+from mista import Mista
+
+mista = Mista(token="...")  # or set MISTA_API_TOKEN
+
+message = mista.sms.send(to="250780000001", sender_id="YourBrand", message="Your order has shipped")
+print(message["uid"], message["status"])
+```
+
+Get your API token in the dashboard under **Settings → API**. Responses are plain dicts with the
+same snake_case keys as the docs (typed as `TypedDict`s in `mista.types`).
+
+Async:
+
+```python
+import asyncio
+from mista import AsyncMista
+
+async def main() -> None:
+    async with AsyncMista() as mista:
+        balance = await mista.account.balance()
+        print(balance["remaining_unit"])
+
+asyncio.run(main())
+```
+
+Every method below works the same way on `AsyncMista`; just `await` it.
+
+## SMS
+
+`sms.send` sends one message to **one** recipient. To reach several numbers, or to schedule a
+send, use a campaign.
+
+```python
+message = mista.sms.send(
+    to="250780000001",
+    sender_id="YourBrand",
+    message="Hello",
+    type="plain",  # plain | unicode | voice | mms | whatsapp | viber | otp
+)
+latest = mista.logs.get(message["uid"])  # delivery status
+```
+
+## Campaigns
+
+```python
+from datetime import datetime
+
+# Broadcast: one message, up to 10,000 numbers
+mista.campaigns.bulk(
+    sender_id="LOYALTY",
+    recipients=["250780000001", "250780000002"],
+    message="Double points this weekend!",
+    schedule_time=datetime(2026, 12, 24, 9, 0),  # or "2026-12-24 09:00"; account timezone
+)
+
+# Personalized: one message per number
+mista.campaigns.bulk(
+    sender_id="LOYALTY",
+    recipients=[
+        {"to": "250780000001", "message": "Hi Alice, you have 120 points."},
+        {"to": "250780000002", "message": "Hi Bob, you have 45 points."},
+    ],
+)
+
+# Everyone in one or more contact groups
+mista.campaigns.send_to_groups(group_uids=["grp_uid"], sender_id="YourBrand", message="Hi!")
+
+campaign = mista.campaigns.get("campaign_uid")
+```
+
+## Message logs
+
+```python
+page = mista.logs.list(start_date="2026-10-01", status="Delivered", per_page=50)
+page.items        # this page
+page.meta.total   # total matches
+
+for message in page:  # walks every remaining page (use `async for` with AsyncMista)
+    print(message["uid"], message["status"])
+```
+
+Filters: `page`, `per_page`, `start_date`, `end_date` (`Y-m-d`), `sender_id`, `status`, `sms_type`.
+When nothing matches, you get an empty page.
+
+## Account
+
+```python
+balance = mista.account.balance()  # {"remaining_unit": ..., "expired_on": ...}
+me = mista.account.me()
+```
+
+## Contact groups and contacts
+
+```python
+group = mista.contact_groups.create("Developers")
+mista.contact_groups.list()
+mista.contact_groups.get(group["uid"])
+mista.contact_groups.update(group["uid"], "Developers KGL")
+
+contact = mista.contacts.create(
+    group["uid"],
+    phone="250780000001",
+    first_name="Alice",
+    last_name="Uwase",
+    fields={"CITY": "Kigali"},  # custom fields, keyed by the group's field tag
+)
+mista.contacts.list(group["uid"])
+mista.contacts.get(group["uid"], contact["uid"])
+mista.contacts.update(group["uid"], contact["uid"], phone="250780000001", first_name="Alicia")
+mista.contacts.delete(group["uid"], contact["uid"])
+
+mista.contact_groups.delete(group["uid"])  # also deletes its contacts
+```
+
+## Verify (OTP)
+
+```python
+verification = mista.verify.start(to="+250780000001", channel="sms")
+
+result = mista.verify.check(sid=verification["sid"], code="123456")
+if result["verified"]:
+    ...  # signed in
+else:
+    print(result["reason"])  # e.g. "invalid_code"; a wrong code does not raise
+
+mista.verify.get(verification["sid"])
+```
+
+## Voice
+
+```python
+token = mista.voice.access_token(platform="ios")["token"]
+numbers = mista.voice.numbers()
+calls = mista.voice.calls.list(filter="missed", per_page=20)
+call = mista.voice.calls.get("call_uid")
+```
+
+## Errors
+
+Every failure raises a subclass of `mista.MistaError`:
+
+| Exception | When |
+| --- | --- |
+| `BadRequestError` | 400, e.g. an invalid phone number |
+| `AuthenticationError` | 401, missing or wrong token |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422; field problems are in `error.errors` |
+| `RateLimitError` | 429 after retries; see `error.retry_after` |
+| `ServerError` | 5xx |
+| `APIError` | any other API error, including a 200 whose body says `"status": "error"` (e.g. a contact already in the group) |
+| `APIConnectionError` / `APITimeoutError` | network failure or timeout |
+
+```python
+from mista import ValidationError
+
+try:
+    mista.sms.send(to="123", sender_id="YourBrand", message="Hi")
+except ValidationError as error:
+    for problem in error.errors:
+        print(problem.field, problem.message)
+```
+
+All API errors carry `status`, `body` (the parsed response) and `headers`.
+
+## Retries, timeouts and HTTP client
+
+```python
+mista = Mista(max_retries=2, timeout=30.0)
+```
+
+- `429 Too Many Requests` is retried for every request, waiting for `Retry-After`.
+- Network errors and 5xx responses are retried for `GET` only, so a send is never duplicated.
+- `max_retries=0` turns retries off.
+- Pass `http_client=httpx.Client(...)` (or `httpx.AsyncClient`) for proxies or custom transports.
+- Use the client as a context manager, or call `close()` / `await aclose()`, to release connections.
+
+## Not covered
+
+Delivery-report webhooks (configure those in the dashboard) and the retired Push API.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest && .venv/bin/mypy
+MISTA_API_TOKEN=... .venv/bin/python scripts/smoke.py   # read-only: balance + account
+```
+
+## License
+
+MIT

mista-0.1.0/README.md

@@ -0,0 +1,207 @@
+# Mista Python SDK
+
+Official Python client for the [Mista](https://mista.io) Messaging, Verify and Voice APIs.
+Full API reference: https://docs.mista.io
+
+```bash
+pip install mista
+```
+
+Requires Python 3.9+. The only dependency is [httpx](https://www.python-httpx.org/).
+Both a synchronous (`Mista`) and an asynchronous (`AsyncMista`) client are included.
+
+## Quickstart
+
+```python
+from mista import Mista
+
+mista = Mista(token="...")  # or set MISTA_API_TOKEN
+
+message = mista.sms.send(to="250780000001", sender_id="YourBrand", message="Your order has shipped")
+print(message["uid"], message["status"])
+```
+
+Get your API token in the dashboard under **Settings → API**. Responses are plain dicts with the
+same snake_case keys as the docs (typed as `TypedDict`s in `mista.types`).
+
+Async:
+
+```python
+import asyncio
+from mista import AsyncMista
+
+async def main() -> None:
+    async with AsyncMista() as mista:
+        balance = await mista.account.balance()
+        print(balance["remaining_unit"])
+
+asyncio.run(main())
+```
+
+Every method below works the same way on `AsyncMista`; just `await` it.
+
+## SMS
+
+`sms.send` sends one message to **one** recipient. To reach several numbers, or to schedule a
+send, use a campaign.
+
+```python
+message = mista.sms.send(
+    to="250780000001",
+    sender_id="YourBrand",
+    message="Hello",
+    type="plain",  # plain | unicode | voice | mms | whatsapp | viber | otp
+)
+latest = mista.logs.get(message["uid"])  # delivery status
+```
+
+## Campaigns
+
+```python
+from datetime import datetime
+
+# Broadcast: one message, up to 10,000 numbers
+mista.campaigns.bulk(
+    sender_id="LOYALTY",
+    recipients=["250780000001", "250780000002"],
+    message="Double points this weekend!",
+    schedule_time=datetime(2026, 12, 24, 9, 0),  # or "2026-12-24 09:00"; account timezone
+)
+
+# Personalized: one message per number
+mista.campaigns.bulk(
+    sender_id="LOYALTY",
+    recipients=[
+        {"to": "250780000001", "message": "Hi Alice, you have 120 points."},
+        {"to": "250780000002", "message": "Hi Bob, you have 45 points."},
+    ],
+)
+
+# Everyone in one or more contact groups
+mista.campaigns.send_to_groups(group_uids=["grp_uid"], sender_id="YourBrand", message="Hi!")
+
+campaign = mista.campaigns.get("campaign_uid")
+```
+
+## Message logs
+
+```python
+page = mista.logs.list(start_date="2026-10-01", status="Delivered", per_page=50)
+page.items        # this page
+page.meta.total   # total matches
+
+for message in page:  # walks every remaining page (use `async for` with AsyncMista)
+    print(message["uid"], message["status"])
+```
+
+Filters: `page`, `per_page`, `start_date`, `end_date` (`Y-m-d`), `sender_id`, `status`, `sms_type`.
+When nothing matches, you get an empty page.
+
+## Account
+
+```python
+balance = mista.account.balance()  # {"remaining_unit": ..., "expired_on": ...}
+me = mista.account.me()
+```
+
+## Contact groups and contacts
+
+```python
+group = mista.contact_groups.create("Developers")
+mista.contact_groups.list()
+mista.contact_groups.get(group["uid"])
+mista.contact_groups.update(group["uid"], "Developers KGL")
+
+contact = mista.contacts.create(
+    group["uid"],
+    phone="250780000001",
+    first_name="Alice",
+    last_name="Uwase",
+    fields={"CITY": "Kigali"},  # custom fields, keyed by the group's field tag
+)
+mista.contacts.list(group["uid"])
+mista.contacts.get(group["uid"], contact["uid"])
+mista.contacts.update(group["uid"], contact["uid"], phone="250780000001", first_name="Alicia")
+mista.contacts.delete(group["uid"], contact["uid"])
+
+mista.contact_groups.delete(group["uid"])  # also deletes its contacts
+```
+
+## Verify (OTP)
+
+```python
+verification = mista.verify.start(to="+250780000001", channel="sms")
+
+result = mista.verify.check(sid=verification["sid"], code="123456")
+if result["verified"]:
+    ...  # signed in
+else:
+    print(result["reason"])  # e.g. "invalid_code"; a wrong code does not raise
+
+mista.verify.get(verification["sid"])
+```
+
+## Voice
+
+```python
+token = mista.voice.access_token(platform="ios")["token"]
+numbers = mista.voice.numbers()
+calls = mista.voice.calls.list(filter="missed", per_page=20)
+call = mista.voice.calls.get("call_uid")
+```
+
+## Errors
+
+Every failure raises a subclass of `mista.MistaError`:
+
+| Exception | When |
+| --- | --- |
+| `BadRequestError` | 400, e.g. an invalid phone number |
+| `AuthenticationError` | 401, missing or wrong token |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422; field problems are in `error.errors` |
+| `RateLimitError` | 429 after retries; see `error.retry_after` |
+| `ServerError` | 5xx |
+| `APIError` | any other API error, including a 200 whose body says `"status": "error"` (e.g. a contact already in the group) |
+| `APIConnectionError` / `APITimeoutError` | network failure or timeout |
+
+```python
+from mista import ValidationError
+
+try:
+    mista.sms.send(to="123", sender_id="YourBrand", message="Hi")
+except ValidationError as error:
+    for problem in error.errors:
+        print(problem.field, problem.message)
+```
+
+All API errors carry `status`, `body` (the parsed response) and `headers`.
+
+## Retries, timeouts and HTTP client
+
+```python
+mista = Mista(max_retries=2, timeout=30.0)
+```
+
+- `429 Too Many Requests` is retried for every request, waiting for `Retry-After`.
+- Network errors and 5xx responses are retried for `GET` only, so a send is never duplicated.
+- `max_retries=0` turns retries off.
+- Pass `http_client=httpx.Client(...)` (or `httpx.AsyncClient`) for proxies or custom transports.
+- Use the client as a context manager, or call `close()` / `await aclose()`, to release connections.
+
+## Not covered
+
+Delivery-report webhooks (configure those in the dashboard) and the retired Push API.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest && .venv/bin/mypy
+MISTA_API_TOKEN=... .venv/bin/python scripts/smoke.py   # read-only: balance + account
+```
+
+## License
+
+MIT

mista-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mista"
+dynamic = ["version"]
+description = "Official Python SDK for the Mista Messaging, Verify and Voice APIs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Mista" }]
+keywords = ["mista", "sms", "bulk-sms", "otp", "verify", "voice", "rwanda", "africa"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Telephony",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10", "build>=1.2", "twine>=5"]
+
+[project.urls]
+Homepage = "https://mista.io"
+Documentation = "https://docs.mista.io"
+Source = "https://github.com/mista-io/mista-python"
+Issues = "https://github.com/mista-io/mista-python/issues"
+
+[tool.hatch.version]
+path = "src/mista/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mista"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mista", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src/mista", "tests", "examples"]
+
+[[tool.mypy.overrides]]
+module = ["tests.*", "examples.*"]
+disallow_untyped_defs = false
+disallow_incomplete_defs = false

mista-0.1.0/src/mista/__init__.py

@@ -0,0 +1,44 @@
+"""Official Python SDK for the Mista Messaging, Verify and Voice APIs. Docs: https://docs.mista.io"""
+
+from ._base import DEFAULT_BASE_URL
+from ._client import AsyncMista, Mista
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    FieldError,
+    MistaError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from ._operations import MAX_BULK_RECIPIENTS
+from ._version import __version__
+from .pagination import AsyncPage, Page, PageMeta
+
+__all__ = [
+    "Mista",
+    "AsyncMista",
+    "DEFAULT_BASE_URL",
+    "MAX_BULK_RECIPIENTS",
+    "Page",
+    "AsyncPage",
+    "PageMeta",
+    "MistaError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "FieldError",
+    "__version__",
+]

mista-0.1.0/src/mista/_base.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import os
+import random
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+from ._errors import MistaError, error_from_response
+from ._operations import Request
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.mista.io"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+class BaseClient:
+    def __init__(
+        self,
+        token: Optional[str],
+        base_url: Optional[str],
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        token = token or os.environ.get("MISTA_API_TOKEN")
+        if not token:
+            raise MistaError("Missing API token. Pass token=... or set the MISTA_API_TOKEN environment variable.")
+        self._token = token
+        self.base_url = (base_url or os.environ.get("MISTA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def _headers(self, request: Request) -> Dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "User-Agent": f"mista-python/{__version__}",
+        }
+        if request.body is not None:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _build(self, request: Request) -> Dict[str, Any]:
+        return {
+            "method": request.method,
+            "url": f"{self.base_url}{request.path}",
+            "params": {k: v for k, v in request.query.items() if v is not None and v != ""},
+            "json": request.body,
+            "headers": self._headers(request),
+            "timeout": self.timeout,
+        }
+
+    def _should_retry_status(self, request: Request, status: int, attempt: int) -> bool:
+        if attempt >= self.max_retries:
+            return False
+        return status == 429 or (status >= 500 and request.method == "GET")
+
+    def _should_retry_connection(self, request: Request, attempt: int) -> bool:
+        return request.method == "GET" and attempt < self.max_retries
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        base = min(8.0, 0.5 * 2.0**attempt)
+        return base / 2 + random.random() * (base / 2)
+
+    def _retry_delay(self, attempt: int, headers: Mapping[str, str]) -> float:
+        try:
+            retry_after = float(headers.get("retry-after", ""))
+        except ValueError:
+            retry_after = 0
+        if retry_after > 0:
+            return min(retry_after, 60.0)
+        return self._backoff(attempt)
+
+    @staticmethod
+    def _parse_body(response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    def _result(self, response: httpx.Response) -> Any:
+        """Return the envelope's ``data``, or raise the matching APIError."""
+        body = self._parse_body(response)
+        is_error = isinstance(body, dict) and body.get("status") == "error"
+        if response.is_success and not is_error:
+            if isinstance(body, dict) and body.get("status") == "success" and "data" in body:
+                return body["data"]
+            return body
+        raise error_from_response(response.status_code, body, response.headers)