irnoti 1.2.0__tar.gz

irnoti-1.2.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+*.egg-info
+dist
+.venv
+.pytest_cache

irnoti-1.2.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this package are documented here. This project follows [Semantic Versioning](https://semver.org/).
+
+## [1.2.0] - 2026-10-14
+
+### Changed
+- `line_id` is now optional everywhere (`sms.send`, `sms.quote`, link tracker, number banks). When omitted it is not sent and the server chooses the sender line. Passing it still works exactly as before.
+
+## [1.1.0] - 2026-10-12
+
+### Added
+- Telegram broker (`broker.*` scopes): register/rename/delete bots, replace token, rotate relay link, call any Bot API method (`request`), pull `updates`, and manage the return webhook.
+
+## [1.0.0] - 2026-10-10
+
+### Added
+- Initial release of the official irnoti Python SDK for the platform API (`https://api.irnoti.com/v1`).
+- SMS: send (single, bulk, group, scheduled, gradual, idempotent), quote, pattern, SOS.
+- Messages, batches, lines, wallet, phonebook (groups, contacts, CSV import).
+- Provider services (regional, targeted, peyamap, smart, messenger, voice, international), link tracker, number banks, verify sessions, bots, VoIP.
+- Typed error with stable `code` and helpers; webhook signature verification.

irnoti-1.2.0/LICENSE.md

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

irnoti-1.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: irnoti
+Version: 1.2.0
+Summary: Official Python SDK for the irnoti platform API (SMS, pattern, SOS, phonebook, services, verify, bots, VoIP, webhooks).
+Project-URL: Homepage, https://irnoti.com
+Project-URL: Documentation, https://irnoti.com/docs
+Project-URL: Repository, https://github.com/irnoti/python-sms-panel-api
+Project-URL: Issues, https://github.com/irnoti/python-sms-panel-api/issues
+Project-URL: Changelog, https://github.com/irnoti/python-sms-panel-api/blob/main/CHANGELOG.md
+Author-email: irnoti <support@irnoti.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: api-client,iran,irnoti,otp,sdk,sms,sms-api
+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.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: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# irnoti (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/irnoti.svg)](https://pypi.org/project/irnoti/) [![tests](https://github.com/irnoti/python-sms-panel-api/actions/workflows/tests.yml/badge.svg)](https://github.com/irnoti/python-sms-panel-api/actions/workflows/tests.yml) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+Python SDK for the irnoti API, built on `httpx`.
+
+```bash
+pip install irnoti
+```
+
+```python
+from irnoti import Irnoti, IrnotiApiError, parse_webhook
+
+irnoti = Irnoti(api_key="irn_live_…")  # base_url, timeout, retries, http_client are optional
+
+try:
+    line = irnoti.lines.list()[0]["id"]
+    irnoti.sms.quote(line, "Hi", to="09121234567")
+    irnoti.sms.send(line, "Hi", to=["09121234567"], group_ids=[12], idempotency_key="k1")
+    irnoti.sms.pattern("k3f9a2", "09121234567", {"code": "4821"})
+    irnoti.services.create("regional", {"province": "tehran", "count": 5000, "text": "Sale"})
+except IrnotiApiError as e:
+    if e.is_insufficient_balance:
+        ...  # top up
+    else:
+        raise
+
+# Flask: verify against the raw body
+event = parse_webhook(request.get_data(), request.headers["X-Irnoti-Signature"], WEBHOOK_SECRET)
+```
+
+Multi-tenant: `irnoti.with_api_key(customer_key)` returns an independent client. Optional request fields use the API's camelCase names where they are passed as `**options` / dicts (e.g. `verify.create(to=…, ttlSec=300)`).
+
+## Quickstart
+
+New here? Follow **[QUICKSTART.md](QUICKSTART.md)**: install, get a key, send your first (free, sandbox) SMS in 5 minutes.
+
+## What can this SDK do? (function reference)
+
+Everything hangs off one client, `irnoti = Irnoti(api_key=...)`. Each group below is a *resource* (`irnoti.<resource>.<function>()`), and each links to its section in the API docs at [irnoti.com/docs](https://irnoti.com/docs) (open the docs panel and look for the section named in the "Docs section" column).
+
+| Resource | Docs section | What it is for | Functions |
+|---|---|---|---|
+| `irnoti.sms` | SMS | Send text messages | `send` (single / bulk / group / scheduled / gradual), `quote` (exact price, no send), `pattern` (approved OTP/transactional template), `sos` (guaranteed delivery with failover) |
+| `irnoti.messages` | SMS → Messages | Look up sent messages | `list`, `get`, `check` (ask operator for final delivery state) |
+| `irnoti.batches` | SMS → Batches | Control scheduled/gradual sends | `scheduled`, `cancel`, `pause`, `resume` |
+| `irnoti.lines` | SMS → Lines | Your sender numbers (you need a `line_id` to send) | `list` |
+| `irnoti.wallet` | Wallet | Balance and history | `balance`, `transactions` |
+| `irnoti.phonebook` | Phonebook | Contact groups and contacts | `groups`, `create_group`, `delete_group`, `contacts`, `add_contacts`, `import_csv`, `update_contact`, `delete_contact` |
+| `irnoti.services` | Services | Provider products: `regional`, `targeted`, `peyamap`, `smart`, `messenger`, `voice`, `international` | `prices`, `international_rates`, `list`, `quote`, `create`, `get`, `refresh`, `cancel` |
+| `irnoti.link_tracker` | Link tracker | SMS with tracked links, A/B variants, holdout | `send`, `holdouts`, `send_now`, `campaigns`, `campaign` |
+| `irnoti.number_banks` | Number banks | Send to purchased/filtered number banks | `list`, `facets`, `quote`, `send` |
+| `irnoti.verify` | Verify | OTP verification sessions (SMS or bot) | `info`, `create`, `list`, `get`, `cancel`, `stats` |
+| `irnoti.bots` | Bot builder | Read bots, send messages/OTP through them (creating bots is panel-only) | `info`, `list`, `get`, `stats`, `subscribers`, `messages`, `send`, `otp`, `shop_orders`, `shop_stats` |
+| `irnoti.broker` | Telegram broker | Run Telegram bots through a private relay | `list`, `get`, `create`, `rename`, `replace_token`, `rotate`, `delete`, `request`, `updates`, `webhook`, `set_webhook`, `delete_webhook` |
+| `irnoti.voip` | VoIP | Click-to-call | `calls`, `price`, `call` |
+
+Top-level helpers (no network call):
+
+| Function | What it does |
+|---|---|
+| `Irnoti(api_key, base_url=, timeout=, retries=, http_client=)` | Create the client |
+| `irnoti.with_api_key(key)` | New independent client for another customer key (multi-tenant) |
+| `verify_webhook(raw_body, signature, secret)` | `True`/`False`: is this webhook really from irnoti? |
+| `parse_webhook(raw_body, signature, secret)` | Verify and return the decoded event, raises `ValueError` if the signature is bad |
+| `IrnotiApiError` | Raised on any non-2xx answer; has `.status`, `.code`, `.details` and helpers like `.is_insufficient_balance` |
+
+Every function is a thin wrapper over one HTTP endpoint and returns the API's JSON as plain `dict`/`list`. Read the docstring in [`src/irnoti/resources.py`](src/irnoti/resources.py) for exact arguments, e.g. `help(irnoti.sms.send)`.
+
+> Typical flow: `lines.list()` (pick a sender) → `sms.quote()` (see the cost) → `sms.send()` (with an `idempotency_key`) → `messages.get()` / webhook (delivery result). Use an `irn_test_…` key and `line_id="sandbox"` while experimenting: nothing is sent or charged.
+
+### Telegram broker
+
+```python
+bot = irnoti.broker.create("Shop bot", botfather_token)    # scope broker.write (account owner); returns the relay `link`
+irnoti.broker.request(bot["id"], "sendMessage", {"chat_id": 123, "text": "Hi"})   # scope broker.request
+irnoti.broker.updates(bot["id"], limit=20)                  # pull mode
+irnoti.broker.set_webhook(bot["id"], "https://example.com/tg", secret_token="s3cret")  # push mode
+```
+
+## Behaviour shared by all irnoti SDKs
+
+- **Auth:** `Authorization: Bearer irn_live_…`. Use an `irn_test_…` key with `lineId: "sandbox"` to try sends for free. Keys carry scopes (`sms.send`, `sms.read`, `wallet.read`, `phonebook.read|write`, `bot.send|read`, `broker.read|write|request`, `verify.send|read`); a missing scope is a `403`.
+- **Money** is integer **Rial** returned as a **string** (`"1960"`) — never parse it into a float.
+- **Idempotency:** every send takes an idempotency key; retrying with the same key never sends twice (`replayed: true`). Automatic retries apply only to `GET`s and sends that carry a key.
+- **Errors:** one error type carrying `status`, the API's machine `code` (`insufficient_balance`, `invalid_recipients`, `no_price`, … — empty for plain 401/403/404) and `details`, with helpers such as `isInsufficientBalance` / `isRateLimited` / `isUnauthenticated`.
+- **Limits:** send 600 req/min, pattern 1200 req/min per IP (`429` when exceeded).
+- **Webhooks:** verify the **raw** body against `X-Irnoti-Signature: t=<unix>,v1=<hex>` (HMAC-SHA256 of `"<t>.<body>"` with your `whsec_…` key); signatures older than 5 minutes are rejected.
+- Bot-builder creation/configuration and verify settings are panel-only; Telegram broker bots can be managed through the API.
+
+Sibling SDKs: [Laravel](https://github.com/irnoti/laravel-sms-panel-api) · [Node.js](https://github.com/irnoti/node-sms-panel-api) · [Python](https://github.com/irnoti/python-sms-panel-api) · [Go](https://github.com/irnoti/go-sms-panel-api) · [PHP](https://github.com/irnoti/php-sms-panel-api). API reference: [irnoti.com/docs](https://irnoti.com/docs).
+
+MIT licensed.

irnoti-1.2.0/README.md

@@ -0,0 +1,93 @@
+# irnoti (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/irnoti.svg)](https://pypi.org/project/irnoti/) [![tests](https://github.com/irnoti/python-sms-panel-api/actions/workflows/tests.yml/badge.svg)](https://github.com/irnoti/python-sms-panel-api/actions/workflows/tests.yml) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+Python SDK for the irnoti API, built on `httpx`.
+
+```bash
+pip install irnoti
+```
+
+```python
+from irnoti import Irnoti, IrnotiApiError, parse_webhook
+
+irnoti = Irnoti(api_key="irn_live_…")  # base_url, timeout, retries, http_client are optional
+
+try:
+    line = irnoti.lines.list()[0]["id"]
+    irnoti.sms.quote(line, "Hi", to="09121234567")
+    irnoti.sms.send(line, "Hi", to=["09121234567"], group_ids=[12], idempotency_key="k1")
+    irnoti.sms.pattern("k3f9a2", "09121234567", {"code": "4821"})
+    irnoti.services.create("regional", {"province": "tehran", "count": 5000, "text": "Sale"})
+except IrnotiApiError as e:
+    if e.is_insufficient_balance:
+        ...  # top up
+    else:
+        raise
+
+# Flask: verify against the raw body
+event = parse_webhook(request.get_data(), request.headers["X-Irnoti-Signature"], WEBHOOK_SECRET)
+```
+
+Multi-tenant: `irnoti.with_api_key(customer_key)` returns an independent client. Optional request fields use the API's camelCase names where they are passed as `**options` / dicts (e.g. `verify.create(to=…, ttlSec=300)`).
+
+## Quickstart
+
+New here? Follow **[QUICKSTART.md](QUICKSTART.md)**: install, get a key, send your first (free, sandbox) SMS in 5 minutes.
+
+## What can this SDK do? (function reference)
+
+Everything hangs off one client, `irnoti = Irnoti(api_key=...)`. Each group below is a *resource* (`irnoti.<resource>.<function>()`), and each links to its section in the API docs at [irnoti.com/docs](https://irnoti.com/docs) (open the docs panel and look for the section named in the "Docs section" column).
+
+| Resource | Docs section | What it is for | Functions |
+|---|---|---|---|
+| `irnoti.sms` | SMS | Send text messages | `send` (single / bulk / group / scheduled / gradual), `quote` (exact price, no send), `pattern` (approved OTP/transactional template), `sos` (guaranteed delivery with failover) |
+| `irnoti.messages` | SMS → Messages | Look up sent messages | `list`, `get`, `check` (ask operator for final delivery state) |
+| `irnoti.batches` | SMS → Batches | Control scheduled/gradual sends | `scheduled`, `cancel`, `pause`, `resume` |
+| `irnoti.lines` | SMS → Lines | Your sender numbers (you need a `line_id` to send) | `list` |
+| `irnoti.wallet` | Wallet | Balance and history | `balance`, `transactions` |
+| `irnoti.phonebook` | Phonebook | Contact groups and contacts | `groups`, `create_group`, `delete_group`, `contacts`, `add_contacts`, `import_csv`, `update_contact`, `delete_contact` |
+| `irnoti.services` | Services | Provider products: `regional`, `targeted`, `peyamap`, `smart`, `messenger`, `voice`, `international` | `prices`, `international_rates`, `list`, `quote`, `create`, `get`, `refresh`, `cancel` |
+| `irnoti.link_tracker` | Link tracker | SMS with tracked links, A/B variants, holdout | `send`, `holdouts`, `send_now`, `campaigns`, `campaign` |
+| `irnoti.number_banks` | Number banks | Send to purchased/filtered number banks | `list`, `facets`, `quote`, `send` |
+| `irnoti.verify` | Verify | OTP verification sessions (SMS or bot) | `info`, `create`, `list`, `get`, `cancel`, `stats` |
+| `irnoti.bots` | Bot builder | Read bots, send messages/OTP through them (creating bots is panel-only) | `info`, `list`, `get`, `stats`, `subscribers`, `messages`, `send`, `otp`, `shop_orders`, `shop_stats` |
+| `irnoti.broker` | Telegram broker | Run Telegram bots through a private relay | `list`, `get`, `create`, `rename`, `replace_token`, `rotate`, `delete`, `request`, `updates`, `webhook`, `set_webhook`, `delete_webhook` |
+| `irnoti.voip` | VoIP | Click-to-call | `calls`, `price`, `call` |
+
+Top-level helpers (no network call):
+
+| Function | What it does |
+|---|---|
+| `Irnoti(api_key, base_url=, timeout=, retries=, http_client=)` | Create the client |
+| `irnoti.with_api_key(key)` | New independent client for another customer key (multi-tenant) |
+| `verify_webhook(raw_body, signature, secret)` | `True`/`False`: is this webhook really from irnoti? |
+| `parse_webhook(raw_body, signature, secret)` | Verify and return the decoded event, raises `ValueError` if the signature is bad |
+| `IrnotiApiError` | Raised on any non-2xx answer; has `.status`, `.code`, `.details` and helpers like `.is_insufficient_balance` |
+
+Every function is a thin wrapper over one HTTP endpoint and returns the API's JSON as plain `dict`/`list`. Read the docstring in [`src/irnoti/resources.py`](src/irnoti/resources.py) for exact arguments, e.g. `help(irnoti.sms.send)`.
+
+> Typical flow: `lines.list()` (pick a sender) → `sms.quote()` (see the cost) → `sms.send()` (with an `idempotency_key`) → `messages.get()` / webhook (delivery result). Use an `irn_test_…` key and `line_id="sandbox"` while experimenting: nothing is sent or charged.
+
+### Telegram broker
+
+```python
+bot = irnoti.broker.create("Shop bot", botfather_token)    # scope broker.write (account owner); returns the relay `link`
+irnoti.broker.request(bot["id"], "sendMessage", {"chat_id": 123, "text": "Hi"})   # scope broker.request
+irnoti.broker.updates(bot["id"], limit=20)                  # pull mode
+irnoti.broker.set_webhook(bot["id"], "https://example.com/tg", secret_token="s3cret")  # push mode
+```
+
+## Behaviour shared by all irnoti SDKs
+
+- **Auth:** `Authorization: Bearer irn_live_…`. Use an `irn_test_…` key with `lineId: "sandbox"` to try sends for free. Keys carry scopes (`sms.send`, `sms.read`, `wallet.read`, `phonebook.read|write`, `bot.send|read`, `broker.read|write|request`, `verify.send|read`); a missing scope is a `403`.
+- **Money** is integer **Rial** returned as a **string** (`"1960"`) — never parse it into a float.
+- **Idempotency:** every send takes an idempotency key; retrying with the same key never sends twice (`replayed: true`). Automatic retries apply only to `GET`s and sends that carry a key.
+- **Errors:** one error type carrying `status`, the API's machine `code` (`insufficient_balance`, `invalid_recipients`, `no_price`, … — empty for plain 401/403/404) and `details`, with helpers such as `isInsufficientBalance` / `isRateLimited` / `isUnauthenticated`.
+- **Limits:** send 600 req/min, pattern 1200 req/min per IP (`429` when exceeded).
+- **Webhooks:** verify the **raw** body against `X-Irnoti-Signature: t=<unix>,v1=<hex>` (HMAC-SHA256 of `"<t>.<body>"` with your `whsec_…` key); signatures older than 5 minutes are rejected.
+- Bot-builder creation/configuration and verify settings are panel-only; Telegram broker bots can be managed through the API.
+
+Sibling SDKs: [Laravel](https://github.com/irnoti/laravel-sms-panel-api) · [Node.js](https://github.com/irnoti/node-sms-panel-api) · [Python](https://github.com/irnoti/python-sms-panel-api) · [Go](https://github.com/irnoti/go-sms-panel-api) · [PHP](https://github.com/irnoti/php-sms-panel-api). API reference: [irnoti.com/docs](https://irnoti.com/docs).
+
+MIT licensed.

irnoti-1.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "irnoti"
+version = "1.2.0"
+description = "Official Python SDK for the irnoti platform API (SMS, pattern, SOS, phonebook, services, verify, bots, VoIP, webhooks)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25"]
+keywords = ["irnoti", "sms", "sms-api", "sdk", "api-client", "otp", "iran"]
+authors = [{ name = "irnoti", email = "support@irnoti.com" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: Communications",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://irnoti.com"
+Documentation = "https://irnoti.com/docs"
+Repository = "https://github.com/irnoti/python-sms-panel-api"
+Issues = "https://github.com/irnoti/python-sms-panel-api/issues"
+Changelog = "https://github.com/irnoti/python-sms-panel-api/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build", "twine"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/irnoti"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE.md", "CHANGELOG.md"]

irnoti-1.2.0/src/irnoti/__init__.py

@@ -0,0 +1,6 @@
+from .client import Irnoti
+from .errors import IrnotiApiError, IrnotiError
+from .webhook import parse_webhook, verify_webhook
+
+__all__ = ["Irnoti", "IrnotiApiError", "IrnotiError", "verify_webhook", "parse_webhook"]
+__version__ = "1.2.0"

irnoti-1.2.0/src/irnoti/client.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Iterable, Mapping, Optional, Union
+
+import httpx
+
+from .errors import IrnotiApiError
+from .resources import (
+    Batches, Bots, Broker, Lines, LinkTracker, Messages, NumberBanks, Phonebook, Services, Sms, Verify, Voip, Wallet,
+)
+
+DEFAULT_BASE_URL = "https://api.irnoti.com"
+
+
+class Transport:
+    def __init__(self, api_key: str, base_url: str, timeout: float, retries: int, client: Optional[httpx.Client]):
+        if not api_key:
+            raise ValueError("irnoti: api_key is required")
+        self._base = base_url.rstrip("/") + "/v1"
+        self._retries = retries
+        self._http = client or httpx.Client(timeout=timeout)
+        self._headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        files: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        params = {k: v for k, v in (query or {}).items() if v is not None}
+        hdrs = {**self._headers, **(headers or {})}
+        # Only calls that are safe to repeat are retried: GETs and sends carrying an Idempotency-Key.
+        attempts = 1 + (self._retries if method == "GET" or "Idempotency-Key" in hdrs else 0)
+        last: Optional[Exception] = None
+        for i in range(attempts):
+            try:
+                res = self._http.request(
+                    method, self._base + path, params=params or None, headers=hdrs,
+                    json=_clean(body) if body is not None and not files else None, files=files,
+                )
+            except httpx.TransportError as exc:
+                last = exc
+                continue
+            if res.status_code >= 500 and i < attempts - 1:
+                continue
+            return self._unwrap(res)
+        assert last is not None
+        raise last
+
+    @staticmethod
+    def _unwrap(res: httpx.Response) -> Any:
+        try:
+            data = res.json() if res.content else None
+        except ValueError:
+            data = None
+        if res.is_success:
+            return data
+        msg = data.get("message") if isinstance(data, dict) else None
+        if isinstance(msg, list):
+            msg = " ".join(map(str, msg))
+        raise IrnotiApiError(
+            msg or f"irnoti API error (HTTP {res.status_code})",
+            res.status_code,
+            str(data.get("code", "")) if isinstance(data, dict) else "",
+            data.get("details") if isinstance(data, dict) else None,
+        )
+
+
+def _clean(value: Any) -> Any:
+    """Drop ``None`` values (optional fields are omitted) and serialise datetimes."""
+    if isinstance(value, dict):
+        return {k: _clean(v) for k, v in value.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        return [_clean(v) for v in value]
+    if isinstance(value, datetime):
+        return value.isoformat()
+    return value
+
+
+class Irnoti:
+    """Entry point. ``Irnoti(api_key="irn_live_…").sms.send(line_id=1, to="0912…", text="hi")``"""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        retries: int = 1,
+        http_client: Optional[httpx.Client] = None,
+    ):
+        self._cfg = dict(base_url=base_url, timeout=timeout, retries=retries, http_client=http_client)
+        t = Transport(api_key, base_url, timeout, retries, http_client)
+        self.sms = Sms(t)
+        self.messages = Messages(t)
+        self.batches = Batches(t)
+        self.lines = Lines(t)
+        self.wallet = Wallet(t)
+        self.phonebook = Phonebook(t)
+        self.services = Services(t)
+        self.link_tracker = LinkTracker(t)
+        self.number_banks = NumberBanks(t)
+        self.verify = Verify(t)
+        self.bots = Bots(t)
+        self.broker = Broker(t)
+        self.voip = Voip(t)
+
+    def with_api_key(self, api_key: str) -> "Irnoti":
+        """A new independent client bound to another key (multi-tenant apps)."""
+        return Irnoti(api_key, **self._cfg)  # type: ignore[arg-type]

irnoti-1.2.0/src/irnoti/errors.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class IrnotiError(Exception):
+    """Base class for all SDK errors."""
+
+
+class IrnotiApiError(IrnotiError):
+    """Non-2xx answer. ``code`` is the API's machine-readable code ('' for plain 401/403/404)."""
+
+    def __init__(self, message: str, status: int, code: str = "", details: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+
+    @property
+    def is_validation_error(self) -> bool:
+        return self.code in ("validation_error", "invalid_recipients", "missing_params")
+
+    @property
+    def is_invalid_recipients(self) -> bool:
+        return self.code == "invalid_recipients"
+
+    @property
+    def is_insufficient_balance(self) -> bool:
+        return self.status == 402 or self.code == "insufficient_balance"
+
+    @property
+    def is_no_price(self) -> bool:
+        return self.code == "no_price"
+
+    @property
+    def is_rate_limited(self) -> bool:
+        return self.status == 429
+
+    @property
+    def is_unauthenticated(self) -> bool:
+        return self.status == 401
+
+    @property
+    def is_forbidden(self) -> bool:
+        return self.status == 403
+
+    @property
+    def is_not_found(self) -> bool:
+        return self.status == 404
+
+    @property
+    def is_conflict(self) -> bool:
+        return self.status == 409
+
+    @property
+    def is_server_error(self) -> bool:
+        return self.status >= 500
+
+    def __repr__(self) -> str:
+        return f"IrnotiApiError(status={self.status}, code={self.code!r}, message={self.message!r})"

irnoti-1.2.0/src/irnoti/resources.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Union
+
+Id = Union[str, int]
+Json = Dict[str, Any]
+
+
+def _e(v: Id) -> str:
+    from urllib.parse import quote
+
+    return quote(str(v), safe="")
+
+
+def _idem(key: Optional[str]) -> Optional[Dict[str, str]]:
+    return {"Idempotency-Key": key} if key else None
+
+
+def _line(line_id: Any) -> Optional[str]:
+    """``lineId`` is optional: ``None``/empty is dropped from the body so the server picks the line."""
+    return None if line_id is None or line_id == "" else str(line_id)
+
+
+def _ids(g: Optional[Iterable[Id]]) -> Optional[List[str]]:
+    return [str(x) for x in g] if g else None
+
+
+class _Resource:
+    def __init__(self, t: Any):
+        self._t = t
+
+
+class Sms(_Resource):
+    def send(
+        self,
+        line_id: Union[Id, str, None] = None,
+        text: str = "",
+        to: Union[str, List[str], None] = None,
+        group_ids: Optional[Iterable[Id]] = None,
+        scheduled_at: Union[datetime, str, None] = None,
+        gradual: Optional[Mapping[str, int]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Json:
+        """Scope ``sms.send``. ``line_id`` is optional (omitted → the server picks the sender line). ``line_id="sandbox"`` + an ``irn_test_`` key sends nothing and costs nothing.
+
+        ``scheduled_at``: 1 minute – 60 days ahead. ``gradual``: ``{"chunkSize": 500, "intervalMinutes": 10}``.
+        Returns ``{batchId, count, totalPrice, replayed}`` (``totalPrice`` is integer Rial as a string).
+        """
+        return self._t.request("POST", "/sms/send", headers=_idem(idempotency_key), body={
+            "lineId": _line(line_id), "to": to, "groupIds": _ids(group_ids), "text": text,
+            "scheduledAt": scheduled_at, "gradual": dict(gradual) if gradual else None,
+        })
+
+    def quote(self, line_id: Union[Id, str, None] = None, text: str = "", to: Union[str, List[str], None] = None,
+              group_ids: Optional[Iterable[Id]] = None) -> Json:
+        """Scope ``sms.read``: exact cost without sending or charging."""
+        return self._t.request("POST", "/sms/quote", body={
+            "lineId": _line(line_id), "to": to, "groupIds": _ids(group_ids), "text": text})
+
+    def pattern(self, code: str, to: str, params: Optional[Mapping[str, Any]] = None,
+                idempotency_key: Optional[str] = None) -> Json:
+        """Approved template (OTP / transactional). Scope ``sms.send``."""
+        return self._t.request("POST", "/sms/pattern", headers=_idem(idempotency_key),
+                               body={"code": code, "to": to, "params": dict(params or {})})
+
+    def sos(self, to: Union[str, List[str]], text: str, idempotency_key: Optional[str] = None) -> Json:
+        """Guaranteed delivery with provider failover (<= 200 recipients, ``sms.sos`` tariff)."""
+        return self._t.request("POST", "/sms/sos", headers=_idem(idempotency_key), body={"to": to, "text": text})
+
+
+class Messages(_Resource):
+    def list(self, take: Optional[int] = None, before: Optional[Id] = None) -> List[Json]:
+        return self._t.request("GET", "/sms/messages", query={"take": take, "before": None if before is None else str(before)})
+
+    def get(self, id: Id) -> Json:
+        return self._t.request("GET", f"/sms/messages/{_e(id)}")
+
+    def check(self, id: Id) -> Json:
+        """Ask the operator for the final delivery state now (30/min)."""
+        return self._t.request("POST", f"/sms/messages/{_e(id)}/check")
+
+
+class Batches(_Resource):
+    def scheduled(self) -> List[Json]:
+        return self._t.request("GET", "/sms/scheduled")
+
+    def cancel(self, batch_id: Id) -> Json:
+        return self._t.request("POST", f"/sms/batches/{_e(batch_id)}/cancel")
+
+    def pause(self, batch_id: Id) -> None:
+        self._t.request("POST", f"/sms/batches/{_e(batch_id)}/pause")
+
+    def resume(self, batch_id: Id) -> None:
+        self._t.request("POST", f"/sms/batches/{_e(batch_id)}/resume")
+
+
+class Lines(_Resource):
+    def list(self) -> List[Json]:
+        return self._t.request("GET", "/sms/lines")
+
+
+class Wallet(_Resource):
+    def balance(self) -> Json:
+        return self._t.request("GET", "/wallet")
+
+    def transactions(self) -> List[Json]:
+        return self._t.request("GET", "/wallet/transactions")
+
+
+class Phonebook(_Resource):
+    def groups(self) -> List[Json]:
+        return self._t.request("GET", "/phonebook/groups")
+
+    def create_group(self, name: str) -> Json:
+        return self._t.request("POST", "/phonebook/groups", body={"name": name})
+
+    def delete_group(self, id: Id) -> None:
+        self._t.request("DELETE", f"/phonebook/groups/{_e(id)}")
+
+    def contacts(self, group_id: Id, take: Optional[int] = None, after: Optional[Id] = None, q: Optional[str] = None) -> Any:
+        return self._t.request("GET", f"/phonebook/groups/{_e(group_id)}/contacts",
+                               query={"take": take, "after": None if after is None else str(after), "q": q})
+
+    def add_contacts(self, group_id: Id, contacts: List[Mapping[str, Any]]) -> Json:
+        """Up to 10,000 per call; invalid/duplicate numbers are counted, not fatal."""
+        return self._t.request("POST", f"/phonebook/groups/{_e(group_id)}/contacts", body={"contacts": contacts})
+
+    def import_csv(self, group_id: Id, csv: Union[str, bytes], filename: str = "contacts.csv") -> Json:
+        data = csv.encode() if isinstance(csv, str) else csv
+        return self._t.request("POST", f"/phonebook/groups/{_e(group_id)}/import",
+                               files={"file": (filename, data, "text/csv")})
+
+    def update_contact(self, id: Id, **attributes: Any) -> Json:
+        """camelCase API fields: mobile, name, lastName, company, email, city, note, birth, fields, optedOut."""
+        return self._t.request("PATCH", f"/phonebook/contacts/{_e(id)}", body=attributes)
+
+    def delete_contact(self, id: Id) -> None:
+        self._t.request("DELETE", f"/phonebook/contacts/{_e(id)}")
+
+
+class Services(_Resource):
+    """regional, targeted, peyamap, smart, messenger, voice, international: quote -> create -> refresh -> cancel."""
+
+    def prices(self) -> List[Json]:
+        return self._t.request("GET", "/services/prices")
+
+    def international_rates(self) -> Any:
+        return self._t.request("GET", "/services/international/rates")
+
+    def list(self, product: str) -> List[Json]:
+        return self._t.request("GET", f"/services/{product}")
+
+    def quote(self, product: str, body: Mapping[str, Any]) -> Json:
+        return self._t.request("POST", f"/services/{product}/quote", body=dict(body))
+
+    def create(self, product: str, body: Mapping[str, Any]) -> Json:
+        return self._t.request("POST", f"/services/{product}", body=dict(body))
+
+    def get(self, product: str, id: Id) -> Json:
+        return self._t.request("GET", f"/services/{product}/{_e(id)}")
+
+    def refresh(self, product: str, id: Id) -> Json:
+        return self._t.request("POST", f"/services/{product}/{_e(id)}/refresh")
+
+    def cancel(self, product: str, id: Id) -> Json:
+        """Only before the provider starts; refunded."""
+        return self._t.request("POST", f"/services/{product}/{_e(id)}/cancel")
+
+
+class LinkTracker(_Resource):
+    def send(self, line_id: Optional[Id] = None, text: str = "", url: str = "", to: Optional[List[str]] = None,
+             group_ids: Optional[Iterable[Id]] = None, variants: Optional[List[str]] = None,
+             holdout_percent: Optional[int] = None, decide_after_minutes: Optional[int] = None) -> Json:
+        return self._t.request("POST", "/link-tracker/send", body={
+            "lineId": _line(line_id), "text": text, "url": url, "to": to, "groupIds": _ids(group_ids),
+            "variants": variants, "holdoutPercent": holdout_percent, "decideAfterMinutes": decide_after_minutes})
+
+    def holdouts(self) -> List[Json]:
+        return self._t.request("GET", "/link-tracker/holdouts")
+
+    def send_now(self, holdout_id: Id) -> Json:
+        return self._t.request("POST", f"/link-tracker/holdouts/{_e(holdout_id)}/send-now")
+
+    def campaigns(self) -> List[Json]:
+        return self._t.request("GET", "/link-tracker/campaigns")
+
+    def campaign(self, batch_id: Id) -> Json:
+        return self._t.request("GET", f"/link-tracker/campaigns/{_e(batch_id)}")
+
+
+class NumberBanks(_Resource):
+    def list(self) -> List[Json]:
+        return self._t.request("GET", "/number-banks")
+
+    def facets(self, bank_id: Id) -> Json:
+        return self._t.request("GET", f"/number-banks/{_e(bank_id)}/facets")
+
+    def _body(self, bank_id: Id, count: int, line_id: Optional[Id], text: str, filters: Optional[Mapping[str, str]]) -> Json:
+        return {"bankId": str(bank_id), "count": count, "lineId": _line(line_id), "text": text, "filters": dict(filters or {})}
+
+    def quote(self, bank_id: Id, count: int, line_id: Optional[Id], text: str, filters: Optional[Mapping[str, str]] = None) -> Json:
+        return self._t.request("POST", "/number-banks/quote", body=self._body(bank_id, count, line_id, text, filters))
+
+    def send(self, bank_id: Id, count: int, line_id: Optional[Id], text: str, filters: Optional[Mapping[str, str]] = None,
+             idempotency_key: Optional[str] = None) -> Json:
+        return self._t.request("POST", "/number-banks/send", headers=_idem(idempotency_key),
+                               body=self._body(bank_id, count, line_id, text, filters))
+
+
+class Verify(_Resource):
+    def info(self) -> Json:
+        return self._t.request("GET", "/verify/info")
+
+    def create(self, to: Optional[str] = None, bot: Optional[Mapping[str, Any]] = None, **options: Any) -> Json:
+        """Exactly one of ``to`` (mobile) or ``bot`` (``{"id", "ref"}``). Options (camelCase): lineId, mode, length,
+        ttlSec, maxAttempts, redirectUrl, callbackUrl, clientRef, brandName, brandColor."""
+        return self._t.request("POST", "/verify/sessions", body={**options, "to": to, "bot": dict(bot) if bot else None})
+
+    def list(self, take: Optional[int] = None, before: Optional[Id] = None) -> List[Json]:
+        return self._t.request("GET", "/verify/sessions", query={"take": take, "before": None if before is None else str(before)})
+
+    def get(self, id: Id) -> Json:
+        return self._t.request("GET", f"/verify/sessions/{_e(id)}")
+
+    def cancel(self, id: Id) -> None:
+        self._t.request("POST", f"/verify/sessions/{_e(id)}/cancel")
+
+    def stats(self) -> Json:
+        return self._t.request("GET", "/verify/stats")
+
+
+class Bots(_Resource):
+    """Bot builder. Creating/configuring bots is panel-only; ``to``/``message`` follow the panel's bot sender shapes."""
+
+    def info(self) -> Json:
+        return self._t.request("GET", "/botbuilder/info")
+
+    def list(self) -> List[Json]:
+        return self._t.request("GET", "/botbuilder/bots")
+
+    def get(self, bot_id: Id) -> Json:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}")
+
+    def stats(self, bot_id: Id) -> Json:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}/stats")
+
+    def subscribers(self, bot_id: Id, take: Optional[int] = None, before: Optional[Id] = None) -> List[Json]:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}/subscribers",
+                               query={"take": take, "before": None if before is None else str(before)})
+
+    def messages(self, bot_id: Id, take: Optional[int] = None, before: Optional[Id] = None) -> List[Json]:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}/messages",
+                               query={"take": take, "before": None if before is None else str(before)})
+
+    def send(self, bot_id: Id, to: Mapping[str, Any], message: Mapping[str, Any], idempotency_key: Optional[str] = None) -> Json:
+        return self._t.request("POST", f"/botbuilder/bots/{_e(bot_id)}/send", headers=_idem(idempotency_key),
+                               body={"to": dict(to), "message": dict(message)})
+
+    def otp(self, bot_id: Id, to: Mapping[str, Any], length: Optional[int] = None, template: Optional[str] = None,
+            idempotency_key: Optional[str] = None) -> Json:
+        return self._t.request("POST", f"/botbuilder/bots/{_e(bot_id)}/otp", headers=_idem(idempotency_key),
+                               body={"to": dict(to), "length": length, "template": template})
+
+    def shop_orders(self, bot_id: Id, status: Optional[str] = None) -> List[Json]:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}/shop/orders", query={"status": status})
+
+    def shop_stats(self, bot_id: Id) -> Json:
+        return self._t.request("GET", f"/botbuilder/bots/{_e(bot_id)}/shop/stats")
+
+
+class Broker(_Resource):
+    """Telegram broker: register a bot token, get a private relay link, call the Bot API and pull updates through it."""
+
+    def list(self) -> List[Json]:
+        return self._t.request("GET", "/broker/bots")
+
+    def get(self, id: Id) -> Json:
+        return self._t.request("GET", f"/broker/bots/{_e(id)}")
+
+    def create(self, label: str, token: str) -> Json:
+        """Scope ``broker.write``, account owner only. The token is never returned afterwards; the response carries the relay ``link``."""
+        return self._t.request("POST", "/broker/bots", body={"label": label, "token": token})
+
+    def rename(self, id: Id, label: str) -> None:
+        self._t.request("PATCH", f"/broker/bots/{_e(id)}", body={"label": label})
+
+    def replace_token(self, id: Id, token: str) -> Json:
+        """Swap in a regenerated BotFather token. Clears the return webhook."""
+        return self._t.request("PUT", f"/broker/bots/{_e(id)}/token", body={"token": token})
+
+    def rotate(self, id: Id) -> Json:
+        """New relay link; the previous one stops working."""
+        return self._t.request("POST", f"/broker/bots/{_e(id)}/rotate")
+
+    def delete(self, id: Id) -> None:
+        self._t.request("DELETE", f"/broker/bots/{_e(id)}")
+
+    def request(self, id: Id, method: str, params: Optional[Mapping[str, Any]] = None) -> Json:
+        """Scope ``broker.request``: call any Telegram Bot API method. Returns ``{status, response}``."""
+        return self._t.request("POST", f"/broker/bots/{_e(id)}/request", body={"method": method, "params": dict(params or {})})
+
+    def updates(self, id: Id, offset: Optional[int] = None, limit: Optional[int] = None, timeout: Optional[int] = None,
+                allowed_updates: Optional[List[str]] = None) -> Json:
+        """Scope ``broker.request``: pull updates (long-poll ``timeout`` <= 25 s)."""
+        return self._t.request("POST", f"/broker/bots/{_e(id)}/updates",
+                               body={"offset": offset, "limit": limit, "timeout": timeout, "allowedUpdates": allowed_updates})
+
+    def webhook(self, id: Id) -> Json:
+        return self._t.request("GET", f"/broker/bots/{_e(id)}/webhook")
+
+    def set_webhook(self, id: Id, url: str, secret_token: Optional[str] = None, allowed_updates: Optional[List[str]] = None,
+                    drop_pending_updates: Optional[bool] = None) -> Json:
+        return self._t.request("PUT", f"/broker/bots/{_e(id)}/webhook",
+                               body={"url": url, "secretToken": secret_token, "allowedUpdates": allowed_updates,
+                                     "dropPendingUpdates": drop_pending_updates})
+
+    def delete_webhook(self, id: Id, drop_pending_updates: Optional[bool] = None) -> Json:
+        return self._t.request("DELETE", f"/broker/bots/{_e(id)}/webhook", body={"dropPendingUpdates": drop_pending_updates})
+
+
+class Voip(_Resource):
+    def calls(self) -> List[Json]:
+        return self._t.request("GET", "/voip/calls")
+
+    def price(self) -> Json:
+        return self._t.request("GET", "/voip/price")
+
+    def call(self, from_: str, to: str) -> Json:
+        return self._t.request("POST", "/voip/calls", body={"from": from_, "to": to})

irnoti-1.2.0/src/irnoti/webhook.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Union
+
+_SIG = re.compile(r"^t=(\d+),v1=([0-9a-f]{64})$")
+
+
+def verify_webhook(raw_body: Union[str, bytes], signature_header: str, secret: str, tolerance: int = 300) -> bool:
+    """Check ``X-Irnoti-Signature`` (``t=<unix>,v1=<hex>``): HMAC-SHA256 of ``"<t>.<raw body>"`` with your ``whsec_`` key.
+
+    Pass the RAW request body, not re-serialised JSON.
+    """
+    m = _SIG.match(signature_header or "")
+    if not m:
+        return False
+    if abs(time.time() - int(m.group(1))) > tolerance:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, m.group(2))
+
+
+def parse_webhook(raw_body: Union[str, bytes], signature_header: str, secret: str, tolerance: int = 300) -> dict[str, Any]:
+    """Verify and decode; raises ``ValueError`` on a bad signature."""
+    if not verify_webhook(raw_body, signature_header, secret, tolerance):
+        raise ValueError("Invalid irnoti webhook signature")
+    return json.loads(raw_body)

irnoti-1.2.0/tests/test_sdk.py

@@ -0,0 +1,116 @@
+import hashlib
+import hmac
+import json
+import time
+from datetime import datetime, timezone
+
+import httpx
+import pytest
+
+from irnoti import Irnoti, IrnotiApiError, parse_webhook, verify_webhook
+
+
+def make(status=200, payload=None):
+    calls = []
+
+    def handler(req: httpx.Request) -> httpx.Response:
+        calls.append(req)
+        return httpx.Response(status, json=payload) if payload is not None else httpx.Response(status)
+
+    api = Irnoti("irn_test_x", base_url="https://irnoti.test/", retries=0,
+                 http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    return api, calls
+
+
+def test_send_builds_request():
+    api, calls = make(201, {"batchId": "1", "count": 2, "totalPrice": "1960", "replayed": False})
+    r = api.sms.send(1, "hi", to=["0912"], group_ids=[12], idempotency_key="k1",
+                     scheduled_at=datetime(2026, 10, 20, 9, tzinfo=timezone.utc))
+    assert r["totalPrice"] == "1960"
+    req = calls[0]
+    assert str(req.url) == "https://irnoti.test/v1/sms/send"
+    assert req.headers["authorization"] == "Bearer irn_test_x"
+    assert req.headers["idempotency-key"] == "k1"
+    assert json.loads(req.content) == {"lineId": "1", "to": ["0912"], "groupIds": ["12"], "text": "hi",
+                                       "scheduledAt": "2026-10-20T09:00:00+00:00"}
+
+
+def test_send_omits_line_id_when_not_given():
+    api, calls = make(201, {"batchId": "1", "count": 1, "totalPrice": "980", "replayed": False})
+    api.sms.send(text="hi", to="0912")
+    assert json.loads(calls[0].content) == {"to": "0912", "text": "hi"}
+
+
+def test_query_skips_none_and_pattern_params_object():
+    api, calls = make(200, [])
+    api.messages.list(take=2, before=90)
+    assert str(calls[0].url) == "https://irnoti.test/v1/sms/messages?take=2&before=90"
+    api.bots.shop_orders(5)
+    assert str(calls[1].url) == "https://irnoti.test/v1/botbuilder/bots/5/shop/orders"
+    api.sms.pattern("k3f9a2", "0912")
+    assert json.loads(calls[2].content)["params"] == {}
+
+
+def test_errors():
+    api, _ = make(400, {"statusCode": 400, "code": "invalid_recipients", "details": ["0912"]})
+    with pytest.raises(IrnotiApiError) as ei:
+        api.sms.send(1, "x", to="0912")
+    e = ei.value
+    assert (e.status, e.code, e.details) == (400, "invalid_recipients", ["0912"])
+    assert e.is_invalid_recipients and e.is_validation_error
+
+    api, _ = make(402, {"statusCode": 402, "code": "insufficient_balance", "message": ["Not", "enough"]})
+    with pytest.raises(IrnotiApiError) as ei:
+        api.wallet.balance()
+    assert ei.value.is_insufficient_balance and str(ei.value) == "Not enough"
+
+    api, _ = make(401, {"statusCode": 401, "message": "Invalid API key"})
+    with pytest.raises(IrnotiApiError) as ei:
+        api.lines.list()
+    assert ei.value.is_unauthenticated and ei.value.code == ""
+
+
+def test_204_and_csv_multipart():
+    api, calls = make(204)
+    assert api.batches.pause(7) is None
+    assert str(calls[0].url) == "https://irnoti.test/v1/sms/batches/7/pause"
+    api, calls = make(200, {"added": 1, "duplicates": 0, "invalid": 0})
+    assert api.phonebook.import_csv(12, "0912,Ali\n")["added"] == 1
+    assert calls[0].headers["content-type"].startswith("multipart/form-data")
+
+
+def test_with_api_key():
+    api, _ = make()
+    assert api.with_api_key("irn_live_y") is not api
+
+
+def test_webhook():
+    body = '{"id":"1","event":"message.delivered","createdAt":"x","data":{}}'
+
+    def sign(t, b=body):
+        return f"t={t},v1=" + hmac.new(b"whsec", f"{t}.{b}".encode(), hashlib.sha256).hexdigest()
+
+    now = int(time.time())
+    assert verify_webhook(body, sign(now), "whsec")
+    assert parse_webhook(body.encode(), sign(now), "whsec")["event"] == "message.delivered"
+    assert not verify_webhook(body + " ", sign(now), "whsec")
+    assert not verify_webhook(body, sign(now - 3600), "whsec")
+    assert not verify_webhook(body, "junk", "whsec")
+    with pytest.raises(ValueError):
+        parse_webhook(body, "junk", "whsec")
+
+
+def test_broker_routes_and_bodies():
+    api, calls = make(200, {})
+    api.broker.request(7, "sendMessage", {"chat_id": 1, "text": "hi"})
+    api.broker.updates(7, limit=10, allowed_updates=["message"])
+    api.broker.set_webhook(7, "https://example.com/hook", secret_token="s")
+    api.broker.delete_webhook(7, True)
+    api.broker.replace_token(7, "123456:ABCDEF-token")
+    assert [(c.method, c.url.path) for c in calls] == [
+        ("POST", "/v1/broker/bots/7/request"), ("POST", "/v1/broker/bots/7/updates"), ("PUT", "/v1/broker/bots/7/webhook"),
+        ("DELETE", "/v1/broker/bots/7/webhook"), ("PUT", "/v1/broker/bots/7/token"),
+    ]
+    assert json.loads(calls[0].content) == {"method": "sendMessage", "params": {"chat_id": 1, "text": "hi"}}
+    assert json.loads(calls[1].content) == {"limit": 10, "allowedUpdates": ["message"]}
+    assert json.loads(calls[3].content) == {"dropPendingUpdates": True}