mojawave 1.0.0__tar.gz

mojawave-1.0.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -m venv .venv)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(.venv/bin/python -m pytest -q)"
+    ]
+  }
+}

mojawave-1.0.0/.gitignore

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

mojawave-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 MojaWave
+
+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.

mojawave-1.0.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: mojawave
+Version: 1.0.0
+Summary: Official Python SDK for the MojaWave API — SMS and transactional messaging for Tanzania.
+Project-URL: Homepage, https://mojawave.com
+Project-URL: Documentation, https://mojawave.com/docs
+Project-URL: Source, https://github.com/mojawave/mojawave-python
+Author: MojaWave
+License: MIT
+License-File: LICENSE
+Keywords: api,messaging,mojawave,otp,sdk,sms,tanzania
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MojaWave Python SDK
+
+A thin, typed Python client for the [MojaWave](https://mojawave.com) REST API —
+send SMS (single, bulk, OTP), check credit balances, and verify webhooks across
+Tanzania's telco networks (Vodacom, Tigo, Airtel, Halotel).
+
+```bash
+pip install mojawave
+```
+
+Requires Python 3.8+.
+
+## Quickstart
+
+```python
+from mojawave import MojaWave
+
+client = MojaWave(api_key="sk_live_mw_...")  # or set MOJAWAVE_API_KEY
+
+msg = client.sms.send(
+    to="+255753276939",
+    sender="MojaWave",
+    message="Hello from Mojawave! Your verification code is 1234.",
+)
+print(msg.id, msg.status)
+```
+
+The client reads `MOJAWAVE_API_KEY` from the environment when `api_key` is
+omitted. Use an `sk_test_mw_` key for the sandbox — no real messages are sent
+and no charges apply.
+
+> **Never** expose your live API key in client-side code. Use environment
+> variables and server-side requests only.
+
+## Sending SMS
+
+### Single message
+
+```python
+msg = client.sms.send(
+    to="+255712345678",
+    sender="MojaWave",                 # sender ID (≤11 alphanumeric chars); defaults to MojaWave
+    message="Your code is 1234.",
+    webhook_url="https://example.com/webhooks/sms",  # optional delivery receipts
+    schedule_at="2026-07-01T09:00:00Z",              # optional ISO-8601 schedule
+    metadata={"customer_id": "cust98765"},           # optional, echoed back
+    tags=["onboarding", "verification"],             # optional
+)
+```
+
+### Look up a message
+
+```python
+msg = client.sms.get("89b82624-f1a2-4f5e-85b5-102e79a06779")
+if msg.delivered:
+    print("Delivered at", msg.timeline.delivered_at)
+elif msg.failed:
+    print("Failed:", msg.failure_reason)
+```
+
+### Bulk send (up to 10,000 recipients)
+
+Bulk jobs run asynchronously — you get a job back immediately, then poll it.
+
+```python
+job = client.sms.bulk(
+    name="Marketing Campaign Q1",
+    sender="MojaWave",
+    message="Hello {name}, your code is {code}",
+    recipients=[
+        {"to": "+255712345678", "personalization": {"name": "John", "code": "ABC123"}},
+        {"to": "+255712345679", "personalization": {"name": "Jane", "code": "XYZ789"}},
+        "+255712345680",  # a bare string works too (no personalization)
+    ],
+    webhook_url="https://example.com/webhooks",
+)
+print(job.id, job.status, job.total_recipients)
+
+# Poll for progress
+job = client.sms.get_bulk(job.id)
+print(f"{job.progress_percent}% — {job.sent_count} sent")
+```
+
+> Unicode messages have a 70-character per-segment limit (vs. 160 for plain
+> SMS). Plan message length accordingly.
+
+## Credits
+
+```python
+balances = client.credits.balance()
+print(balances.sms.balance, balances.sms.is_low_balance)
+print(balances.email.balance)
+```
+
+## Webhooks
+
+MojaWave signs every webhook with an `X-MojaWave-Signature` header (HMAC-SHA256
+of the raw body). Always verify against the **raw** request bytes — parsing to
+JSON first can change whitespace and break the check.
+
+```python
+from mojawave import construct_event, WebhookVerificationError, SIGNATURE_HEADER
+
+# Flask / Django view
+signature = request.headers.get(SIGNATURE_HEADER)
+try:
+    event = construct_event(request.get_data(), signature, WEBHOOK_SECRET)
+except WebhookVerificationError:
+    return "Forbidden", 403
+
+if event.type == "message.delivered":
+    ...
+```
+
+Event types: `message.sent`, `message.delivered`, `message.failed`,
+`credits.low`. See `examples/flask_webhook.py` for a full handler.
+
+If you only need a boolean, use `verify_signature(payload, signature, secret)`.
+
+## Error handling
+
+Every documented HTTP status maps to a typed exception. All inherit from
+`MojaWaveError`.
+
+| Exception | HTTP | Code |
+|---|---|---|
+| `InvalidRequestError` | 400 | `invalid_request` |
+| `AuthenticationError` | 401 | `unauthorized` |
+| `InsufficientBalanceError` | 402 | `insufficient_balance` |
+| `UnprocessableError` | 422 | `unprocessable` |
+| `RateLimitError` | 429 | `rate_limit_exceeded` |
+| `ServerError` | 5xx | `server_error` |
+| `APIConnectionError` / `APITimeoutError` | — | transport failures |
+
+```python
+from mojawave import InsufficientBalanceError, RateLimitError
+
+try:
+    client.sms.send(to="+255712345678", message="hi")
+except InsufficientBalanceError:
+    ...  # top up
+except RateLimitError as e:
+    time.sleep(e.retry_after or 1)
+```
+
+The client automatically retries `429` and `5xx` responses with exponential
+backoff (honouring `Retry-After`), controlled by `max_retries` (default 2).
+
+## Configuration
+
+```python
+client = MojaWave(
+    api_key="sk_live_mw_...",
+    environment="live",        # or "sandbox"
+    timeout=30.0,              # seconds
+    max_retries=2,
+    base_url="https://api.mojawave.com/v1",
+)
+```
+
+Rate-limit headers from the most recent response are available on
+`client.rate_limit` (`.limit`, `.remaining`, `.reset`). The client is usable as
+a context manager to ensure the HTTP session is closed:
+
+```python
+with MojaWave() as client:
+    client.sms.send(to="+255712345678", message="hi")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy
+```
+
+## License
+
+MIT

mojawave-1.0.0/README.md

@@ -0,0 +1,180 @@
+# MojaWave Python SDK
+
+A thin, typed Python client for the [MojaWave](https://mojawave.com) REST API —
+send SMS (single, bulk, OTP), check credit balances, and verify webhooks across
+Tanzania's telco networks (Vodacom, Tigo, Airtel, Halotel).
+
+```bash
+pip install mojawave
+```
+
+Requires Python 3.8+.
+
+## Quickstart
+
+```python
+from mojawave import MojaWave
+
+client = MojaWave(api_key="sk_live_mw_...")  # or set MOJAWAVE_API_KEY
+
+msg = client.sms.send(
+    to="+255753276939",
+    sender="MojaWave",
+    message="Hello from Mojawave! Your verification code is 1234.",
+)
+print(msg.id, msg.status)
+```
+
+The client reads `MOJAWAVE_API_KEY` from the environment when `api_key` is
+omitted. Use an `sk_test_mw_` key for the sandbox — no real messages are sent
+and no charges apply.
+
+> **Never** expose your live API key in client-side code. Use environment
+> variables and server-side requests only.
+
+## Sending SMS
+
+### Single message
+
+```python
+msg = client.sms.send(
+    to="+255712345678",
+    sender="MojaWave",                 # sender ID (≤11 alphanumeric chars); defaults to MojaWave
+    message="Your code is 1234.",
+    webhook_url="https://example.com/webhooks/sms",  # optional delivery receipts
+    schedule_at="2026-07-01T09:00:00Z",              # optional ISO-8601 schedule
+    metadata={"customer_id": "cust98765"},           # optional, echoed back
+    tags=["onboarding", "verification"],             # optional
+)
+```
+
+### Look up a message
+
+```python
+msg = client.sms.get("89b82624-f1a2-4f5e-85b5-102e79a06779")
+if msg.delivered:
+    print("Delivered at", msg.timeline.delivered_at)
+elif msg.failed:
+    print("Failed:", msg.failure_reason)
+```
+
+### Bulk send (up to 10,000 recipients)
+
+Bulk jobs run asynchronously — you get a job back immediately, then poll it.
+
+```python
+job = client.sms.bulk(
+    name="Marketing Campaign Q1",
+    sender="MojaWave",
+    message="Hello {name}, your code is {code}",
+    recipients=[
+        {"to": "+255712345678", "personalization": {"name": "John", "code": "ABC123"}},
+        {"to": "+255712345679", "personalization": {"name": "Jane", "code": "XYZ789"}},
+        "+255712345680",  # a bare string works too (no personalization)
+    ],
+    webhook_url="https://example.com/webhooks",
+)
+print(job.id, job.status, job.total_recipients)
+
+# Poll for progress
+job = client.sms.get_bulk(job.id)
+print(f"{job.progress_percent}% — {job.sent_count} sent")
+```
+
+> Unicode messages have a 70-character per-segment limit (vs. 160 for plain
+> SMS). Plan message length accordingly.
+
+## Credits
+
+```python
+balances = client.credits.balance()
+print(balances.sms.balance, balances.sms.is_low_balance)
+print(balances.email.balance)
+```
+
+## Webhooks
+
+MojaWave signs every webhook with an `X-MojaWave-Signature` header (HMAC-SHA256
+of the raw body). Always verify against the **raw** request bytes — parsing to
+JSON first can change whitespace and break the check.
+
+```python
+from mojawave import construct_event, WebhookVerificationError, SIGNATURE_HEADER
+
+# Flask / Django view
+signature = request.headers.get(SIGNATURE_HEADER)
+try:
+    event = construct_event(request.get_data(), signature, WEBHOOK_SECRET)
+except WebhookVerificationError:
+    return "Forbidden", 403
+
+if event.type == "message.delivered":
+    ...
+```
+
+Event types: `message.sent`, `message.delivered`, `message.failed`,
+`credits.low`. See `examples/flask_webhook.py` for a full handler.
+
+If you only need a boolean, use `verify_signature(payload, signature, secret)`.
+
+## Error handling
+
+Every documented HTTP status maps to a typed exception. All inherit from
+`MojaWaveError`.
+
+| Exception | HTTP | Code |
+|---|---|---|
+| `InvalidRequestError` | 400 | `invalid_request` |
+| `AuthenticationError` | 401 | `unauthorized` |
+| `InsufficientBalanceError` | 402 | `insufficient_balance` |
+| `UnprocessableError` | 422 | `unprocessable` |
+| `RateLimitError` | 429 | `rate_limit_exceeded` |
+| `ServerError` | 5xx | `server_error` |
+| `APIConnectionError` / `APITimeoutError` | — | transport failures |
+
+```python
+from mojawave import InsufficientBalanceError, RateLimitError
+
+try:
+    client.sms.send(to="+255712345678", message="hi")
+except InsufficientBalanceError:
+    ...  # top up
+except RateLimitError as e:
+    time.sleep(e.retry_after or 1)
+```
+
+The client automatically retries `429` and `5xx` responses with exponential
+backoff (honouring `Retry-After`), controlled by `max_retries` (default 2).
+
+## Configuration
+
+```python
+client = MojaWave(
+    api_key="sk_live_mw_...",
+    environment="live",        # or "sandbox"
+    timeout=30.0,              # seconds
+    max_retries=2,
+    base_url="https://api.mojawave.com/v1",
+)
+```
+
+Rate-limit headers from the most recent response are available on
+`client.rate_limit` (`.limit`, `.remaining`, `.reset`). The client is usable as
+a context manager to ensure the HTTP session is closed:
+
+```python
+with MojaWave() as client:
+    client.sms.send(to="+255712345678", message="hi")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+mypy
+```
+
+## License
+
+MIT

mojawave-1.0.0/examples/flask_webhook.py

@@ -0,0 +1,37 @@
+"""Receive and verify MojaWave webhooks with Flask.
+
+    pip install flask
+    MOJAWAVE_WEBHOOK_SECRET=whsec_... python examples/flask_webhook.py
+"""
+
+import os
+
+from flask import Flask, request
+
+from mojawave import SIGNATURE_HEADER, WebhookVerificationError, construct_event
+
+app = Flask(__name__)
+WEBHOOK_SECRET = os.environ["MOJAWAVE_WEBHOOK_SECRET"]
+
+
+@app.post("/webhooks/mojawave")
+def handle_webhook():
+    signature = request.headers.get(SIGNATURE_HEADER)
+    try:
+        # Verify against the RAW body — never the parsed JSON.
+        event = construct_event(request.get_data(), signature, WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        return "Forbidden", 403
+
+    if event.type == "message.delivered":
+        print(f"Delivered: {event.data['id']} -> {event.data['to']}")
+    elif event.type == "message.failed":
+        print(f"Failed: {event.data['id']} ({event.data.get('failure_reason')})")
+    elif event.type == "credits.low":
+        print("Credit balance is low — top up soon.")
+
+    return "", 204
+
+
+if __name__ == "__main__":
+    app.run(port=4242)

mojawave-1.0.0/examples/quickstart.py

@@ -0,0 +1,33 @@
+"""Minimal end-to-end example. Run with MOJAWAVE_API_KEY set in your env."""
+
+from mojawave import MojaWave, InsufficientBalanceError
+
+client = MojaWave()  # reads MOJAWAVE_API_KEY
+
+# Check balance first.
+balances = client.credits.balance()
+print(f"SMS credits remaining: {balances.sms.balance}")
+
+# Send a single message.
+try:
+    msg = client.sms.send(
+        to="+255753276939",
+        sender="MojaWave",
+        message="Hello from Mojawave! Your code is 1234.",
+        metadata={"customer_id": "cust98765"},
+    )
+    print(f"Sent {msg.id} — status={msg.status}, cost={msg.credits_cost}")
+except InsufficientBalanceError:
+    print("Top up your account to send messages.")
+
+# Bulk send with per-recipient personalization.
+job = client.sms.bulk(
+    name="Marketing Campaign Q1",
+    sender="MojaWave",
+    message="Hello {name}, your code is {code}",
+    recipients=[
+        {"to": "+255712345678", "personalization": {"name": "John", "code": "ABC123"}},
+        {"to": "+255712345679", "personalization": {"name": "Jane", "code": "XYZ789"}},
+    ],
+)
+print(f"Bulk job {job.id}: {job.status} ({job.total_recipients} recipients)")

mojawave-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mojawave"
+version = "1.0.0"
+description = "Official Python SDK for the MojaWave API — SMS and transactional messaging for Tanzania."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "MojaWave" }]
+keywords = ["mojawave", "sms", "tanzania", "otp", "messaging", "api", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["requests>=2.25"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "responses>=0.23", "mypy>=1.0", "types-requests"]
+
+[project.urls]
+Homepage = "https://mojawave.com"
+Documentation = "https://mojawave.com/docs"
+Source = "https://github.com/mojawave/mojawave-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mojawave"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/mojawave"]

mojawave-1.0.0/src/mojawave/__init__.py

@@ -0,0 +1,70 @@
+"""MojaWave Python SDK.
+
+A thin, typed client for the MojaWave REST API — send SMS (single, bulk, OTP),
+check credit balances, and verify webhooks.
+
+    from mojawave import MojaWave
+
+    client = MojaWave(api_key="sk_live_mw_...")
+    client.sms.send(to="+255712345678", message="Hello!")
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from .client import MojaWave
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    MojaWaveError,
+    RateLimitError,
+    ServerError,
+    UnprocessableError,
+)
+from .models import (
+    BulkJob,
+    CreditBalances,
+    Message,
+    ServiceCredits,
+    Timeline,
+)
+from .webhooks import (
+    SIGNATURE_HEADER,
+    WebhookEvent,
+    WebhookVerificationError,
+    compute_signature,
+    construct_event,
+    verify_signature,
+)
+
+__all__ = [
+    "__version__",
+    "MojaWave",
+    # errors
+    "MojaWaveError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "ServerError",
+    "UnprocessableError",
+    # models
+    "BulkJob",
+    "CreditBalances",
+    "Message",
+    "ServiceCredits",
+    "Timeline",
+    # webhooks
+    "SIGNATURE_HEADER",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "compute_signature",
+    "construct_event",
+    "verify_signature",
+]