adsefid 0.1.0__tar.gz

adsefid-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

adsefid-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

adsefid-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - run: make deps
+      - run: make lint
+      - run: make build

adsefid-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.coverage
+htmlcov/
+*.log
+.DS_Store
+.idea/
+.vscode/
+*.iml

adsefid-0.1.0/AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md — adsefid Python SDK
+
+## Scope
+
+This repository is the Python client SDK for the adsefid.com SMS Web Service API (package:
+`adsefid`), independently versioned and published with its own `pyproject.toml`. Equivalent SDKs
+exist for the same API in sibling repositories (`sdk-dotnet`, `sdk-js`, `sdk-php`, `sdk-go`); a
+behavior change here should generally be considered for parity there.
+
+## Source of truth
+
+The API surface (endpoints, field names, types, validation rules, enums, example payloads,
+webhook behavior) is defined by the published adsefid.com SMS Web Service API documentation.
+This SDK is verified against doc version v1.11.0. Re-read the relevant documentation before
+changing any endpoint, request/response model, or enum. The SDK follows independent Semantic
+Versioning from `pyproject.toml`; never copy the API-document version into package metadata.
+Record both versions in the README.
+
+A small number of facts below are empirically observed behaviors of the live API that are easy
+to get wrong from a literal reading of the documentation's prose or pseudo-code. Trust these
+notes over an ambiguous doc reading:
+
+- Webhook signatures are plain Base64, not hex-then-Base64. The signature is HMAC-SHA256 over
+  the literal string `"{timestamp}.{raw_body}"`, and the raw digest bytes are Base64-encoded
+  directly — there is no intermediate hex-encoding step, even though a literal reading of some
+  spec pseudo-code can suggest one. See `src/adsefid/webhooks/verifier.py`.
+- `TemplateParameterType` has an undocumented third value in the wild. The documented, supported
+  public set is `{string, number}`. The live API has been observed to also emit a `url` value for
+  some templates; this SDK intentionally models only the two documented values — do not add
+  support for it without first confirming it against current, documented API behavior. See
+  `src/adsefid/enums.py`.
+- `error.details` shape varies per endpoint and is intentionally untyped. It may be a validation
+  map, a bulk/P2P per-item list, a cancel-specific map, or absent entirely — never give it a
+  strong type; decode it defensively per endpoint if you need it.
+
+## Architecture map
+
+```
+src/adsefid/
+├── __init__.py          public API re-exports
+├── py.typed             PEP 561 marker — do not remove
+├── client.py            AdsefidClient (sync, wraps httpx.Client)
+├── async_client.py       AdsefidAsyncClient (async, wraps httpx.AsyncClient)
+├── _base.py              shared request-building / envelope-parsing / error-raising (used by both clients)
+├── config.py             ClientConfig
+├── exceptions.py         full exception hierarchy
+├── enums.py              LineSelector, WebServiceMessageStatus, WebServiceResponseCode, TemplateState, TemplateParameterType
+├── _serialization.py     to_dict/from_dict helpers, ISO-8601 datetime parse/format, local_id regex + validators, CSV join
+├── resources/
+│   ├── sms.py            SmsResource (sync) + AsyncSmsResource (async) — 7 ops each
+│   ├── messenger.py      MessengerResource + AsyncMessengerResource — 7 ops each (incl. upload_file)
+│   └── user.py           UserResource + AsyncUserResource — 4 ops each
+├── models/
+│   ├── common.py         shared envelope/status/cancel dataclasses reused by sms + messenger
+│   ├── sms.py            request/response dataclasses for the 7 SMS ops
+│   ├── messenger.py       request/response dataclasses for the 7 messenger ops
+│   └── user.py            request/response dataclasses for the 4 user ops
+└── webhooks/
+    ├── verifier.py        verify_and_parse_webhook
+    ├── events.py          WebhookEvent union + 3 concrete dataclasses
+    └── headers.py         WebhookHeaders/WebhookEventType constants — use instead of typing header/type strings
+```
+
+## Adding a new endpoint
+
+1. Add the request/response `@dataclass(frozen=True, slots=True)` types to the right `models/<area>.py` (or `models/common.py` if the shape is shared across SMS and messenger, e.g. cancel/status). Hand-write `to_dict`/`from_dict` — no metaprogramming.
+2. Add one sync method to the resource class in `resources/<area>.py`, and the structurally identical `async def` method to the `Async<Area>Resource` class in the same file. The two classes must stay parallel: same method names, same parameter order, same validation calls, same shape of return.
+3. Any client-side pre-flight rule (max length, required field, `local_id` shape, count limits) goes in `_serialization.py` as a small named validator function and is called from the resource method *before* the request is built — never inline `if` checks scattered across resource methods.
+4. Re-export anything new that belongs in the public surface from `adsefid/__init__.py`.
+
+## Hard rules
+
+- **No tests, ever.** Do not add a `tests/` directory, doctest, or pytest dependency to this repo.
+- **No pydantic, no reflection-based validation/serialization.** Every dataclass hand-writes its own `to_dict`/`from_dict`. If two models share shape, factor the shared dataclass into `models/common.py` — don't reach for a validation library.
+- **No magic string/int literals.** Any code value that appears in the doc's enum tables belongs in `enums.py`. Any other repeated constant (max lengths, limits, header names) is a named module-level constant, not a literal repeated at call sites.
+- **Docstrings on the public API, minimal comments elsewhere.** Every public class/function (clients, resources, exceptions, enums, `verify_and_parse_webhook`) needs a PEP 257 docstring with real content — not a restatement of its name. Internal/private (`_`-prefixed) code stays uncommented except where a genuinely non-obvious constraint requires a note (e.g. the webhook digest-vs-hex behavior, the permissive-enum-parsing rationale). Don't narrate what the code obviously does.
+- **Raise on error, always — never introduce a Result/Either type.** Every resource method either returns a typed success dataclass or raises from the `exceptions.py` hierarchy. Partial-success bulk/P2P responses are still normal typed returns (they're HTTP 200 successes with per-item status), not exceptions.
+- **Keep sync and async clients/resources behaviorally identical.** Same validation, same error mapping, same defaults. If you touch one, touch the other in the same change.
+- **No retry logic anywhere in this SDK.** Every request is a single attempt.
+- `WebServiceMessageStatus` and `WebServiceResponseCode` are the two enums most likely to grow ahead of doc updates — they're parsed permissively (unknown int falls back to a raw int field rather than raising). Don't "fix" this into a hard `IntEnum(value)` call that would crash on a new server-side code.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"  # installs ruff + mypy + build into this repo's venv
+make lint                 # ruff check + ruff format --check + mypy
+make fmt                  # ruff format .
+make build                 # python -m build (sdist + wheel)
+```

adsefid-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# AGENTS.md — adsefid Python SDK
+
+## Scope
+
+This repository is the Python client SDK for the adsefid.com SMS Web Service API (package:
+`adsefid`), independently versioned and published with its own `pyproject.toml`. Equivalent SDKs
+exist for the same API in sibling repositories (`sdk-dotnet`, `sdk-js`, `sdk-php`, `sdk-go`); a
+behavior change here should generally be considered for parity there.
+
+## Source of truth
+
+The API surface (endpoints, field names, types, validation rules, enums, example payloads,
+webhook behavior) is defined by the published adsefid.com SMS Web Service API documentation.
+This SDK is verified against doc version v1.11.0. Re-read the relevant documentation before
+changing any endpoint, request/response model, or enum. The SDK follows independent Semantic
+Versioning from `pyproject.toml`; never copy the API-document version into package metadata.
+Record both versions in the README.
+
+A small number of facts below are empirically observed behaviors of the live API that are easy
+to get wrong from a literal reading of the documentation's prose or pseudo-code. Trust these
+notes over an ambiguous doc reading:
+
+- Webhook signatures are plain Base64, not hex-then-Base64. The signature is HMAC-SHA256 over
+  the literal string `"{timestamp}.{raw_body}"`, and the raw digest bytes are Base64-encoded
+  directly — there is no intermediate hex-encoding step, even though a literal reading of some
+  spec pseudo-code can suggest one. See `src/adsefid/webhooks/verifier.py`.
+- `TemplateParameterType` has an undocumented third value in the wild. The documented, supported
+  public set is `{string, number}`. The live API has been observed to also emit a `url` value for
+  some templates; this SDK intentionally models only the two documented values — do not add
+  support for it without first confirming it against current, documented API behavior. See
+  `src/adsefid/enums.py`.
+- `error.details` shape varies per endpoint and is intentionally untyped. It may be a validation
+  map, a bulk/P2P per-item list, a cancel-specific map, or absent entirely — never give it a
+  strong type; decode it defensively per endpoint if you need it.
+
+## Architecture map
+
+```
+src/adsefid/
+├── __init__.py          public API re-exports
+├── py.typed             PEP 561 marker — do not remove
+├── client.py            AdsefidClient (sync, wraps httpx.Client)
+├── async_client.py       AdsefidAsyncClient (async, wraps httpx.AsyncClient)
+├── _base.py              shared request-building / envelope-parsing / error-raising (used by both clients)
+├── config.py             ClientConfig
+├── exceptions.py         full exception hierarchy
+├── enums.py              LineSelector, WebServiceMessageStatus, WebServiceResponseCode, TemplateState, TemplateParameterType
+├── _serialization.py     to_dict/from_dict helpers, ISO-8601 datetime parse/format, local_id regex + validators, CSV join
+├── resources/
+│   ├── sms.py            SmsResource (sync) + AsyncSmsResource (async) — 7 ops each
+│   ├── messenger.py      MessengerResource + AsyncMessengerResource — 7 ops each (incl. upload_file)
+│   └── user.py           UserResource + AsyncUserResource — 4 ops each
+├── models/
+│   ├── common.py         shared envelope/status/cancel dataclasses reused by sms + messenger
+│   ├── sms.py            request/response dataclasses for the 7 SMS ops
+│   ├── messenger.py       request/response dataclasses for the 7 messenger ops
+│   └── user.py            request/response dataclasses for the 4 user ops
+└── webhooks/
+    ├── verifier.py        verify_and_parse_webhook
+    ├── events.py          WebhookEvent union + 3 concrete dataclasses
+    └── headers.py         WebhookHeaders/WebhookEventType constants — use instead of typing header/type strings
+```
+
+## Adding a new endpoint
+
+1. Add the request/response `@dataclass(frozen=True, slots=True)` types to the right `models/<area>.py` (or `models/common.py` if the shape is shared across SMS and messenger, e.g. cancel/status). Hand-write `to_dict`/`from_dict` — no metaprogramming.
+2. Add one sync method to the resource class in `resources/<area>.py`, and the structurally identical `async def` method to the `Async<Area>Resource` class in the same file. The two classes must stay parallel: same method names, same parameter order, same validation calls, same shape of return.
+3. Any client-side pre-flight rule (max length, required field, `local_id` shape, count limits) goes in `_serialization.py` as a small named validator function and is called from the resource method *before* the request is built — never inline `if` checks scattered across resource methods.
+4. Re-export anything new that belongs in the public surface from `adsefid/__init__.py`.
+
+## Hard rules
+
+- **No tests, ever.** Do not add a `tests/` directory, doctest, or pytest dependency to this repo.
+- **No pydantic, no reflection-based validation/serialization.** Every dataclass hand-writes its own `to_dict`/`from_dict`. If two models share shape, factor the shared dataclass into `models/common.py` — don't reach for a validation library.
+- **No magic string/int literals.** Any code value that appears in the doc's enum tables belongs in `enums.py`. Any other repeated constant (max lengths, limits, header names) is a named module-level constant, not a literal repeated at call sites.
+- **Docstrings on the public API, minimal comments elsewhere.** Every public class/function (clients, resources, exceptions, enums, `verify_and_parse_webhook`) needs a PEP 257 docstring with real content — not a restatement of its name. Internal/private (`_`-prefixed) code stays uncommented except where a genuinely non-obvious constraint requires a note (e.g. the webhook digest-vs-hex behavior, the permissive-enum-parsing rationale). Don't narrate what the code obviously does.
+- **Raise on error, always — never introduce a Result/Either type.** Every resource method either returns a typed success dataclass or raises from the `exceptions.py` hierarchy. Partial-success bulk/P2P responses are still normal typed returns (they're HTTP 200 successes with per-item status), not exceptions.
+- **Keep sync and async clients/resources behaviorally identical.** Same validation, same error mapping, same defaults. If you touch one, touch the other in the same change.
+- **No retry logic anywhere in this SDK.** Every request is a single attempt.
+- `WebServiceMessageStatus` and `WebServiceResponseCode` are the two enums most likely to grow ahead of doc updates — they're parsed permissively (unknown int falls back to a raw int field rather than raising). Don't "fix" this into a hard `IntEnum(value)` call that would crash on a new server-side code.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"  # installs ruff + mypy + build into this repo's venv
+make lint                 # ruff check + ruff format --check + mypy
+make fmt                  # ruff format .
+make build                 # python -m build (sdist + wheel)
+```

adsefid-0.1.0/Makefile

@@ -0,0 +1,9 @@
+.PHONY: deps fmt lint build
+deps:
+	pip install -e ".[dev]"
+fmt:
+	ruff format .
+lint:
+	ruff check . && ruff format --check . && mypy src/adsefid
+build:
+	python -m build

adsefid-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: adsefid
+Version: 0.1.0
+Summary: Python client SDK for the adsefid.com SMS Web Service API
+Project-URL: Homepage, https://github.com/adsefid/sdk-python
+Project-URL: Repository, https://github.com/adsefid/sdk-python
+Project-URL: Issues, https://github.com/adsefid/sdk-python/issues
+Author: adsefid.com
+License: Proprietary
+Keywords: adsefid,messenger,sms,webservice
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: flask; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# adsefid
+
+[![CI](https://github.com/adsefid/sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/adsefid/sdk-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/adsefid.svg)](https://pypi.org/project/adsefid/)
+
+Python client SDK for the [adsefid.com](https://adsefid.com) SMS Web Service API — SMS, Messenger (Rubika/Bale/etc.), and account/user endpoints, plus outgoing webhook signature verification.
+
+## Requirements
+
+- Python 3.10+
+- [`httpx`](https://www.python-httpx.org/) (the only runtime dependency)
+
+## Install
+
+```bash
+pip install adsefid
+```
+
+## Quickstart
+
+### Sync
+
+```python
+import os
+
+from adsefid import AdsefidClient
+from adsefid.models.sms import SendSingleSmsRequest
+
+client = AdsefidClient(api_key=os.environ["ADSEFID_API_KEY"])
+
+result = client.sms.send_single(
+    SendSingleSmsRequest(
+        receptor="98912xxxxxxx",
+        line_number="3000xxxx",
+        message="Hello from adsefid",
+    )
+)
+print(result.message_id, result.status)
+
+client.close()
+```
+
+### Async
+
+```python
+import asyncio
+import os
+
+from adsefid import AdsefidAsyncClient
+from adsefid.models.sms import SendSingleSmsRequest
+
+
+async def main() -> None:
+    async with AdsefidAsyncClient(api_key=os.environ["ADSEFID_API_KEY"]) as client:
+        result = await client.sms.send_single(
+            SendSingleSmsRequest(
+                receptor="98912xxxxxxx",
+                line_number="3000xxxx",
+                message="Hello from adsefid",
+            )
+        )
+        print(result.message_id, result.status)
+
+
+asyncio.run(main())
+```
+
+`AdsefidClient` also supports the `with` statement (shown above via explicit `close()`); `AdsefidAsyncClient` supports `async with`.
+
+## Authentication
+
+The SDK never reads environment variables itself — pass the API key explicitly:
+
+```python
+import os
+from adsefid import AdsefidClient
+
+client = AdsefidClient(api_key=os.environ["ADSEFID_API_KEY"])
+```
+
+## Configuration
+
+```python
+from adsefid import AdsefidClient
+import httpx
+
+client = AdsefidClient(
+    api_key="...",
+    base_url="https://api.adsefid.com",  # override for a different environment
+    timeout=30.0,  # seconds, passed to httpx
+    http_client=httpx.Client(...),  # optional: inject your own configured httpx.Client
+)
+```
+
+If you pass your own `http_client`/`AdsefidAsyncClient(http_client=...)`, the SDK will not close it for you when `.close()`/`.aclose()` is called — you own its lifecycle.
+
+## Resource reference
+
+| Resource | SDK method | HTTP endpoint | Notes |
+|---|---|---|---|
+| `client.sms` | `send_single(request)` | `POST /v1/sms/single` | |
+| `client.sms` | `send_bulk(request)` | `POST /v1/sms/bulk` | Partial success is a normal typed return, not an exception |
+| `client.sms` | `send_p2p(request)` | `POST /v1/sms/p2p` | Partial success is a normal typed return, not an exception |
+| `client.sms` | `send_template(request)` | `POST /v1/sms/template` | |
+| `client.sms` | `get_status(message_ids=..., local_ids=...)` | `GET /v1/sms/status` | |
+| `client.sms` | `cancel(request)` | `POST /v1/sms/cancel` | |
+| `client.sms` | `get_received(line_number=..., count=..., since=...)` | `GET /v1/sms/receive` | |
+| `client.messenger` | `send_single(request)` | `POST /v1/messenger/single` | |
+| `client.messenger` | `send_bulk(request)` | `POST /v1/messenger/bulk` | Partial success is a normal typed return, not an exception |
+| `client.messenger` | `send_p2p(request)` | `POST /v1/messenger/p2p` | Partial success is a normal typed return, not an exception |
+| `client.messenger` | `upload_file(file, filename=..., content_type=...)` | `POST /v1/messenger/file` | Accepts a path, bytes, or an open file object |
+| `client.messenger` | `cancel(request)` | `POST /v1/messenger/cancel` | |
+| `client.messenger` | `send_template(request)` | `POST /v1/messenger/template` | |
+| `client.messenger` | `get_status(message_ids=..., local_ids=...)` | `GET /v1/messenger/status` | |
+| `client.user` | `get_info()` | `GET /v1/user/info` | |
+| `client.user` | `get_lines()` | `GET /v1/user/lines` | |
+| `client.user` | `get_profiles()` | `GET /v1/user/profiles` | |
+| `client.user` | `get_templates(state=..., skip=..., take=...)` | `GET /v1/user/templates` | |
+
+`AdsefidAsyncClient` exposes the identical surface with `await`-able methods (`client.sms.send_single(...)`, etc.).
+
+Every method takes/returns hand-written `@dataclass(frozen=True, slots=True)` request/response types from `adsefid.models.*` whose fields mirror the API's snake_case JSON exactly.
+
+## Error handling
+
+Every resource method **raises** on a non-success API response or a non-2xx HTTP status — it never returns a Result/Either type. Bulk and P2P responses with mixed per-item outcomes are still normal successful returns (HTTP 200, `status: "success"`); check each item's own `status`/`raw_status` field.
+
+```python
+from adsefid import AdsefidApiError, AdsefidRateLimitError, AdsefidValidationError
+
+try:
+    result = client.sms.send_single(request)
+except AdsefidValidationError as e:
+    # Failed a client-side pre-flight check (e.g. bad local_id, message too long) — no network call was made.
+    print("invalid request:", e)
+except AdsefidRateLimitError as e:
+    # WebServiceResponseCode 2035 (MESSAGE_LIMIT_REACHED) or 2036 (REQUEST_LIMIT_REACHED),
+    # or a bare HTTP 429 with an unparseable body.
+    print("rate limited:", e.code, e.name)
+except AdsefidApiError as e:
+    print("API error:", e.code, e.name, e.http_status_code, e.details)
+```
+
+### Rate limits
+
+The default sending limit is 500 units/second shared across SMS and Messenger traffic (SMS counts by segment). Codes `2035`, `2036`, and bare HTTP `429` responses surface as `AdsefidRateLimitError`.
+
+## Enums
+
+All enums live in `adsefid.enums` and are exported from the top-level package:
+
+- `LineSelector` (`IntEnum`, 0-5) — see doc §3.1
+- `WebServiceMessageStatus` (`IntEnum`, 1000-1999) — see doc §3.2. Parsed **permissively**: response dataclasses expose both a `status: WebServiceMessageStatus | None` field and a `raw_status: int` field, so an unrecognized future status code never crashes parsing.
+- `WebServiceResponseCode` (`IntEnum`, 2000-2045) — see doc §3.4. `AdsefidApiError.code` is the enum member when recognized, otherwise the raw `int`.
+- `TemplateState` (`str, Enum`: `pendingapproval` / `approved` / `rejected`) — see doc §3.5
+- `TemplateParameterType` (`str, Enum`: `string` / `number`) — see doc §3.6. This is the doc's complete *documented* public set; the live server has been observed to also emit an undocumented `url` value which is intentionally not exposed here.
+
+Free-form server strings with no complete documented enum (`messenger`, e.g. `"rubika"`/`"bale"`; `account_status`, e.g. `"active"`) are plain `str` fields, not enums.
+
+## File upload example
+
+```python
+from adsefid.resources.messenger import MessengerResource  # via client.messenger
+
+file_result = client.messenger.upload_file("./brochure.pdf", content_type="application/pdf")
+print(file_result.file_id)
+
+# Also accepts raw bytes or an already-open binary file object:
+with open("./brochure.pdf", "rb") as f:
+    file_result = client.messenger.upload_file(
+        f, filename="brochure.pdf", content_type="application/pdf"
+    )
+```
+
+## Webhook verification
+
+The platform signs outgoing webhooks as `X-Atlas-Webhook-Signature: v1=<base64_hmac_sha256>` over `f"{timestamp}.{raw_body}"`, keyed with your per-endpoint webhook secret. Always verify on the **raw** request body bytes, before any JSON parsing your framework might have already done.
+
+```python
+from flask import Flask, request
+
+from adsefid import AdsefidWebhookVerificationError, verify_and_parse_webhook
+from adsefid.webhooks import WebhookEventType, WebhookHeaders
+
+app = Flask(__name__)
+WEBHOOK_SECRET = os.environ["ADSEFID_WEBHOOK_SECRET"]
+
+
+@app.post("/webhooks/adsefid")
+def handle_webhook():
+    try:
+        event = verify_and_parse_webhook(
+            raw_body=request.get_data(),  # raw bytes, not request.json
+            signature_header=request.headers[WebhookHeaders.SIGNATURE],
+            timestamp_header=request.headers[WebhookHeaders.TIMESTAMP],
+            secret=WEBHOOK_SECRET,
+        )
+    except AdsefidWebhookVerificationError as e:
+        return {"error": str(e)}, 400
+
+    # Only event types this webhook endpoint is subscribed to (in your adsefid.com panel) ever
+    # arrive here — an endpoint subscribed to just "receive" never sees a "status" event.
+    match event.type:
+        case WebhookEventType.RECEIVE:
+            for item in event.data:
+                print("inbound SMS from", item.sender, ":", item.message)
+        case WebhookEventType.STATUS:
+            for item in event.data:
+                print("SMS", item.id, "->", item.status_delivery)
+        case WebhookEventType.MESSENGER_STATUS:
+            for item in event.data:
+                print("messenger message", item.id, "->", item.status_delivery)
+
+    return {"ok": True}, 200
+```
+
+`WebhookHeaders` exposes every header name as a constant so you never have to type
+`"X-Atlas-Webhook-Signature"` yourself; `WebhookEventType` does the same for the `type` values.
+
+Return a `2xx` quickly and process asynchronously where possible — the platform treats any `2xx` as delivered and otherwise retries with backoff (`5s, 60s, 120s, 360s, 600s, 900s`) until it gives up. Handlers should be idempotent using `WebhookHeaders.ID` plus each event item's own id.
+
+## Versioning
+
+This SDK follows Semantic Versioning independently of the API documentation.
+
+- SDK version: **`0.1.0`** (`version` in `pyproject.toml`; `adsefid.__version__` reads package metadata)
+- Verified API documentation: **`v1.11.0`**
+
+SDK releases use `v<SDK_VERSION>` tags. The two version numbers move independently.
+
+## Development
+
+```bash
+make deps    # pip install -e ".[dev]" (ruff, mypy, build)
+make fmt     # ruff format .
+make lint    # ruff check . && ruff format --check . && mypy src/adsefid
+make build   # python -m build
+```
+
+## License
+
+Proprietary — All rights reserved.